Spec: Pre-existing Skills Scaffold Policy

Source Of Truth

• Grill status: apps/wiki/content/docs/project/grilling/pre-existing-skills-scaffold-grill-status.md
• Grill log: apps/wiki/content/docs/project/grilling/pre-existing-skills-scaffold-grill-log.md
• Handoff: /var/folders/y8/fw7tz9gn7yx645tf162zwlnr0000gp/T/harness-pre-existing-skills-handoff-2026-06-30.md

Requirements are closed. Do not reopen command-owned overlap detection unless the user explicitly reopens the grill.

User Input

we have to redefine the dp scaffold init and setup about how it manages the already pre-existing skills of a repo when we scaffold HI.

both should check the same skills. also dp update should behave the same

actually i thought it was the agents role to check overlapping skills. the command shouldnt and instead should provide very clear post command and dp-cli skill guidance about this

Context

Harness scaffold and update commands can run in repositories that already contain agent skills in neutral or tool-specific homes. Operators need one policy across dp scaffold init, dp scaffold setup, and dp update: commands finish filesystem scaffolding, then the agent follows the handoff and $dp-cli guidance to reconcile pre-existing skills.

The affected readers are agents and operators continuing after scaffold/update output. The affected maintainers are CLI and shared-skill maintainers keeping command output, .devpunks/AGENT-HANDOFF.md, and $dp-cli behavior aligned.

Non-Goals

• Command-runtime exact-name, semantic, or dynamic overlap detection.
• Command-runtime replacement reports or dp update --check intersection reporting.
• Treating pre-existing local skills as active overrides of HI baseline skills.
• Solving semantic overlap outside model-guided dp report work.
• Writing or reshaping backlog items for this delivery.

Acceptance Criteria

• dp scaffold init, dp scaffold setup, and dp update post-command guidance all tell the next agent that it owns pre-existing skill reconciliation.
• The guidance names the same skill homes for agent inspection: .agents/skills, .claude/skills, .codex/skills, .cursor/skills, .opencode/skills.
• The guidance states exact canonical directory id/name overlap keeps the HI baseline skill active.
• The guidance states overlapping local skill evidence should be archived under .devpunks/replaced-skills/<skill-id>/..., then active local copies or mirrors should be removed.
• The guidance states non-overlapping local skills should be preserved and exposed through harness mirrors or symlinks.
• The guidance states dp report is the path for proposing archived local knowledge for HI baseline integration.
• The guidance states semantic or dynamic overlap is deferred to model-guided dp report, not command runtime.
• $dp-cli shared skill guidance matches the command handoff policy.
• Commands do not classify, report, or decide skill overlaps as part of this change.

Constraints

• Reusable $dp-cli skill edits start in /Users/stefan/Desktop/repos/wearedevpunks-skills, then sync into Harness.
• Preserve unrelated dirty workspace changes.
• If command code snapshots pre-existing skill homes, snapshotting must be blind evidence capture only and must not classify overlap.
• Operator workflow and scaffold guidance changes require docs/runbook updates in the same delivery.

Technical Notes

• Current dp scaffold setup behavior migrates legacy harness skill directories into .agents/skills before writing selected baseline skills and running .agents/scripts/sync-subagents.mjs.
• Current dp scaffold setup collision behavior renames local collisions to *-local; this is superseded by agent-owned reconciliation guidance, not by command-owned overlap classification.
• Current dp scaffold init copies staged skills into .agents/skills/<skillId>.

Decision Log