Plan: Pre-existing Skills Scaffold Policy

Initial Situation

The grill closed on agent-owned pre-existing skill reconciliation, but CLI and runbook wording still reflected older command-owned collision handling. Delivery needed to update generated post-command guidance, $dp-cli, and operator docs without adding command-runtime overlap detection.

Decision Ledger

• Commands do not detect, classify, report, archive, or decide skill overlaps.
• Commands may take blind evidence snapshots of pre-existing skill homes.
• Agents inspect .agents/skills, .claude/skills, .codex/skills, .cursor/skills, and .opencode/skills.
• Exact canonical directory id/name overlap keeps HI baseline active.
• Non-overlapping local skills remain exposed through harness mirrors or symlinks.
• Semantic overlap belongs to model-guided dp report.
• No backlog writes.

Task Graph

T1 || T2 || T3 -> T4 -> T5

Tasks

T1: Update CLI Handoff Guidance

• depends_on: []
• location: apps/cli/src/content/stage-scaffold.ts, apps/cli/src/content/scaffold-copy.ts, apps/cli/src/update/run.ts, apps/cli/src/scaffold/skill-snapshot.ts, focused tests
• description: Update dp scaffold init, dp scaffold setup, and dp update output/handoff wording so the next agent owns pre-existing skill reconciliation; preserve blind skill-home evidence before setup/init/update writes can replace active files.
• validation: Focused CLI tests assert shared skill homes, no command-owned overlap detection, blind snapshot evidence, HI baseline precedence, archive path, non-overlap preservation, and dp report guidance.
• status: Completed
• log:
  • 2026-06-30: Added agent-owned pre-existing skill reconciliation guidance to init prompt, setup handoff, and update summary.
  • 2026-06-30: Replaced command-owned legacy skill migration with blind .devpunks/pre-existing-skills snapshots.
  • 2026-06-30: Added update-apply coverage proving target repo skill evidence is snapshotted before managed skill overwrite.
• assigned_skills: tdd, simplify, quality-types
• tdd_status: completed
• green_command: bun run --cwd apps/cli test -- src/scaffold/run.test.ts src/scaffold/stage.test.ts src/update/run.test.ts src/content/content.test.ts
• review_mode: cli

T2: Update Shared $dp-cli Guidance

• depends_on: []
• location: /Users/stefan/Desktop/repos/wearedevpunks-skills/skills/agnostic/cli/dp-cli, generated Harness skill copies, active global $dp-cli
• description: Verify upstream shared skill first, then sync into Harness and refresh the active global install so distributed $dp-cli matches generated handoffs.
• validation: bun run sync:skills; diff -u proves shared source, Harness apps/cli/skills/agnostic/cli/dp-cli, and global /Users/stefan/.agents/skills/dp-cli match.
• status: Completed
• log:
  • 2026-06-30: Verified upstream /Users/stefan/Desktop/repos/wearedevpunks-skills $dp-cli source at a889421.
  • 2026-06-30: Ran bun run sync:skills to refresh Harness vendored apps/cli/skills/agnostic/cli/dp-cli.
  • 2026-06-30: Refreshed the active global $dp-cli install.
• assigned_skills: dp-cli
• tdd_status: not_applicable
• reason_not_testable: Skill prose sync validated by source-to-vendor/global diffs and downstream text assertions.
• review_mode: cli

T3: Update Operator Docs

• depends_on: []
• location: docs/README.md, docs/runbooks/dp-cli-scaffolding.md, docs/reference/dp-requirements.md, routed wiki mirrors and CLI docs
• description: Replace legacy command-owned migration/collision docs with agent-owned reconciliation policy and blind snapshot evidence.
• validation: rg catches no stale -local collision guidance in active operator docs; routed metadata updated.
• status: Completed
• log:
  • 2026-06-30: Updated root docs, runbooks, reference docs, routed CLI pages, and wiki bookkeeping.
• assigned_skills: docs-ingest-phase
• tdd_status: not_applicable
• reason_not_testable: Documentation validation by diff review and stale-wording search.
• review_mode: docs

T4: Review And Validate

• depends_on: [T1, T2, T3]
• location: CLI focused tests, typecheck, lint/format, shared skill diffs, final diff review
• description: Run focused validation and address review findings without broadening runtime into command-owned overlap classification.
• validation: Focused tests, CLI typecheck, CLI check, git diff --check, source/vendor/global diffs.
• status: Completed
• log:
  • 2026-06-30: Addressed review finding that dp update --write/--yes could overwrite target repo skill evidence before the agent saw it.
  • 2026-06-30: Kept exact-overlap and non-overlap classification in agent guidance, not command runtime.
• assigned_skills: review-phase, autoreview, simplify
• tdd_status: completed
• green_command: bun run --cwd apps/cli test -- src/scaffold/run.test.ts src/scaffold/stage.test.ts src/update/run.test.ts src/content/content.test.ts
• review_mode: cli

T5: Record Implementation Notes

• depends_on: [T4]
• location: apps/wiki/content/docs/project/specs/cli/pre-existing-skills-scaffold-policy/IMPLEMENTATION-NOTES.md
• description: Record changed files, validation evidence, and residual risk.
• validation: Implementation notes exist; plan/spec index statuses updated to implemented.
• status: Completed
• log:
  • 2026-06-30: Wrote implementation notes with source sync, global skill refresh, validation, and scoped residual notes.
• assigned_skills: delivery-phase
• tdd_status: not_applicable
• reason_not_testable: Closeout artifact.
• review_mode: cli

Validation Evidence

• PASS: bun run sync:skills
• PASS: skills add https://github.com/wearedevpunks/skills/tree/main/skills/agnostic/cli/dp-cli --skill dp-cli --global --yes
• PASS: bun run --cwd apps/cli test -- src/scaffold/run.test.ts src/scaffold/stage.test.ts src/update/run.test.ts src/content/content.test.ts
• PASS: bun run --cwd apps/cli check-types
• PASS: bun run --cwd apps/cli check
• PASS: git diff --check
• PASS: diff -u shared source, Harness apps/cli/skills, and global $dp-cli files.

Residual Notes

• Runtime commands still do not classify exact-name or semantic overlaps. That is intentional and locked by the grill.
• Historical grill/spec artifacts keep superseded command-owned behavior as decision context; active status, plan, implementation notes, docs, and command guidance reflect the accepted agent-owned policy.