Agent skill

manage-plan-artifacts

Plan-scoped artifact storage for assessments and findings with JSONL persistence

View SKILL.md on GitHub Repository
Stars 163
Forks 31

Install this agent skill to your Project

npx add-skill https://github.com/majiayu000/claude-skill-registry/tree/main/skills/data/manage-plan-artifacts

SKILL.md

Manage Plan Artifacts

Plan-level artifact storage providing structured JSONL persistence for assessments and findings.

Scope Distinction

Scope Storage Lifecycle
Project-level .plan/lessons-learned/ Persists across plans
Plan-level .plan/plans/{plan_id}/artifacts/ Temporary, promoted or discarded

Plan artifacts are working data during plan execution. Notable findings are promoted to project-level at 7-finalize.

Storage Structure

.plan/plans/{plan_id}/artifacts/
├── assessments.jsonl  # Component assessments (certainty, confidence)
└── findings.jsonl     # Unified: lessons + bugs (optionally promotable)

Artifact Types

Assessments

Component evaluations from analysis agents with certainty gates and confidence scores.

Certainty values: CERTAIN_INCLUDE, CERTAIN_EXCLUDE, UNCERTAIN

Findings

Unified storage for lessons and bugs. All types optionally promotable.

Finding types:

Type Origin Default Promotion Target
bug Implementation errors manage-lessons
improvement Discovered patterns manage-lessons
anti-pattern Bad practices found manage-lessons
triage Triage decisions manage-lessons
tip Helpful hints architecture (tips)
insight Deeper understanding architecture (insights)
best-practice Recommended patterns architecture (best_practices)
build-error Compilation failures (any, if pattern emerges)
test-failure Test failures (any, if pattern emerges)
lint-issue Linter warnings (any, if pattern emerges)
sonar-issue Sonar findings (any, if pattern emerges)
pr-comment PR review comments (any, if pattern emerges)

Resolution values: pending, fixed, suppressed, accepted

CLI Commands

Assessment Commands

bash
# Add assessment
python3 .plan/execute-script.py pm-workflow:manage-plan-artifacts:manage-artifacts \
  assessment add {plan_id} {file_path} {certainty} {confidence} \
  [--agent AGENT] [--detail DETAIL] [--evidence EVIDENCE]

# Query assessments
python3 .plan/execute-script.py pm-workflow:manage-plan-artifacts:manage-artifacts \
  assessment query {plan_id} [--certainty C] [--min-confidence N] \
  [--max-confidence N] [--file-pattern PATTERN]

# Get single assessment
python3 .plan/execute-script.py pm-workflow:manage-plan-artifacts:manage-artifacts \
  assessment get {plan_id} {hash_id}

Finding Commands

bash
# Add finding
python3 .plan/execute-script.py pm-workflow:manage-plan-artifacts:manage-artifacts \
  finding add {plan_id} {type} {title} --detail DETAIL \
  [--file-path PATH] [--line N] [--component C] \
  [--module M] [--rule R] [--severity S]

# Query findings
python3 .plan/execute-script.py pm-workflow:manage-plan-artifacts:manage-artifacts \
  finding query {plan_id} [--type T] [--resolution R] \
  [--promoted BOOL] [--file-pattern PATTERN]

# Get single finding
python3 .plan/execute-script.py pm-workflow:manage-plan-artifacts:manage-artifacts \
  finding get {plan_id} {hash_id}

# Resolve finding
python3 .plan/execute-script.py pm-workflow:manage-plan-artifacts:manage-artifacts \
  finding resolve {plan_id} {hash_id} {resolution} [--detail DETAIL]

# Promote finding
python3 .plan/execute-script.py pm-workflow:manage-plan-artifacts:manage-artifacts \
  finding promote {plan_id} {hash_id} {promoted_to}

Output Format

All commands return TOON format.

Add response:

toon
status: success
hash_id: a3f2c1
type: bug

Query response:

toon
status: success
plan_id: my-plan
total_count: 30
filtered_count: 15

findings[15]{hash_id,type,title,resolution}:
a3f2c1,bug,Null check missing,pending
b4e3d2,sonar-issue,TODO comment,fixed

Integration

Producers

Client Artifact Operation
Analysis agents assessment add
Sonar integration finding (sonar-issue) add, resolve
CI integration finding (pr-comment) add, resolve
phase-7-finalize finding add, promote

Consumers

Client Artifact Operation
Q-Gate agent assessment query
phase-7-finalize finding query, resolve, promote
Workflow orchestration assessment query

Promotion Workflow

At 7-finalize:

  1. Query unpromoted findings: finding query {plan_id} --promoted false
  2. For each finding to promote:
    • To manage-lessons (bug, improvement, anti-pattern, triage):
      bash
      manage-lessons add --component {component} --category {type} ...
finding promote {plan_id} {hash_id} {promoted_id}
    • To architecture (tip, insight, best-practice):
      bash
      architecture enrich {type} --module {module} --{type} "{content}" --reasoning "From plan {plan_id}"
finding promote {plan_id} {hash_id} architecture

Didn't find tool you were looking for?

Be as detailed as possible for better results