Plan: Harness Phase Upgrades

Status: Complete Mode: sequential

Initial Situation

Harness has a strong phase lifecycle: requirements/grill, spec, plan, implement, review, docs ingest, and routed wiki/project docs. The shared skills already ship from /Users/stefan/Desktop/repos/wearedevpunks-skills into this repo through bun run sync:skills. The current contracts mention TDD and docs ingest, but they do not make RED/GREEN evidence an auditable task requirement, and the docs-ingest phase does not yet own an explicit learning refresh loop.

Issue

Superpowers is sharper than Harness on hard TDD behavior because it states a simple rule and routes implementation through test-first plans and verification. Compound is stronger on compounding because it deliberately closes learning loops. Harness can adopt both advantages without adopting strategy, ideation, product pulse, or a parallel docs/solutions/ tree.

Solution Shape

Patch the shared skills source first. Make $tdd, $create-plan, $implement-spec, and $review-phase agree on a hard TDD artifact contract. Then extend $docs-ingest-phase with a scoped learning-artifact loop that dedupes and refreshes routed canonical knowledge. Sync skills into Harness, add a compact scaffolded root prompt invariant, and document the operator workflow.

Resolved Decision Ledger

Assumptions And Constraints

• No backlog provider/story was supplied; task backlog fields stay none.
• Shared skill source must be edited in /Users/stefan/Desktop/repos/wearedevpunks-skills.
• Harness distributed skill copies under apps/cli/skills/* are generated outputs of bun run sync:skills.
• This checkout's active .agents/skills/* mirror is not updated by apps/cli/scripts/sync-skills-repo.mjs; affected local skill dirs were manually aligned from the synced CLI bundle for this task.
• reason_not_testable cannot be used for "forgot RED."
• Learning scans are scoped to relevant domain/module/component/referenced files, not broad repository sweeps.

Codebase Findings

• Shared tdd lives at /Users/stefan/Desktop/repos/wearedevpunks-skills/skills/agnostic/quality/tdd/SKILL.md.
• Shared planning refs live under /Users/stefan/Desktop/repos/wearedevpunks-skills/skills/agnostic/planning/create-plan/references/.
• Shared implement-spec lifecycle lives under /Users/stefan/Desktop/repos/wearedevpunks-skills/skills/agnostic/planning/implement-spec/references/.
• Shared docs-ingest-phase lives under /Users/stefan/Desktop/repos/wearedevpunks-skills/skills/phases/docs-ingest-phase/.
• Scaffolded root prompt content lives in apps/cli/src/content/prompts.ts.
• Prompt content tests live in apps/cli/src/content/content.test.ts.
• Operator docs live in docs/README.md and docs/runbooks/dp-cli-scaffolding.md.

External Research

This plan uses the already completed Superpowers/Compound/Harness comparison and the closed requirements grill. No new external package behavior is required.

Dependency Graph

T1 -> T2 -> T3 -> T4 -> T5 -> T6

T1: Harden the shared TDD skill

• depends_on: []
• location: /Users/stefan/Desktop/repos/wearedevpunks-skills/skills/agnostic/quality/tdd/SKILL.md
• description: Add Superpowers-style hard law, applicability, explicit escape hatches, and code-before-RED recovery.
• validation: Skill text contains the hard law, applies to behavior-changing work, and forbids reason_not_testable for forgotten RED.
• status: Complete
• log: Added hard-law language, applicability, allowed escapes, code-before-RED recovery, and RED/GREEN evidence capture requirements to the shared TDD skill. Committed and pushed in wearedevpunks/skills@ea114f8.
• files edited/created: /Users/stefan/Desktop/repos/wearedevpunks-skills/skills/agnostic/quality/tdd/SKILL.md, apps/cli/skills/agnostic/quality/tdd/SKILL.md
• backlog_item_id: none
• backlog_item_url: none
• relation_mode: none
• assigned_skills: [tdd, simplify]
• tdd_status: not_applicable
• tdd_target: Documentation-only skill contract change; validate by text assertions and downstream sync.
• red_command: n/a
• expected_red_failure: n/a
• green_command: rg "No production code before RED|reason_not_testable.*forgotten RED" /Users/stefan/Desktop/repos/wearedevpunks-skills/skills/agnostic/quality/tdd/SKILL.md
• reason_not_testable: No production runtime behavior changes in this task.
• red_evidence:
• green_evidence: rg "No production code before RED|reason_not_testable.*forgotten RED" /Users/stefan/Desktop/repos/wearedevpunks-skills/skills/agnostic/quality/tdd/SKILL.md found both hard-law and forgotten-RED language.
• review_mode: cli

T2: Add TDD evidence fields to plan creation

• depends_on: [T1]
• location: /Users/stefan/Desktop/repos/wearedevpunks-skills/skills/agnostic/planning/create-plan/references/tdd-phase.md, /Users/stefan/Desktop/repos/wearedevpunks-skills/skills/agnostic/planning/create-plan/references/plan-schema.md
• description: Require tdd_status, commands, expected RED failure, evidence fields, and explicit non-testable reasons in every task.
• validation: Plan schema and TDD phase reference list all evidence fields and state behavior-changing tasks need RED/GREEN proof.
• status: Complete
• log: Added tdd_status, RED/GREEN commands, evidence fields, and forgotten-RED recovery rules to the create-plan TDD/schema references. Committed and pushed in wearedevpunks/skills@ea114f8.
• files edited/created: /Users/stefan/Desktop/repos/wearedevpunks-skills/skills/agnostic/planning/create-plan/SKILL.md, /Users/stefan/Desktop/repos/wearedevpunks-skills/skills/agnostic/planning/create-plan/references/tdd-phase.md, /Users/stefan/Desktop/repos/wearedevpunks-skills/skills/agnostic/planning/create-plan/references/plan-schema.md, apps/cli/skills/agnostic/planning/create-plan/SKILL.md, apps/cli/skills/agnostic/planning/create-plan/references/tdd-phase.md, apps/cli/skills/agnostic/planning/create-plan/references/plan-schema.md
• backlog_item_id: none
• backlog_item_url: none
• relation_mode: none
• assigned_skills: [create-plan, tdd, simplify]
• tdd_status: not_applicable
• tdd_target: Documentation-only planning contract change; validate by text assertions and this plan shape.
• red_command: n/a
• expected_red_failure: n/a
• green_command: rg "tdd_status|red_evidence|green_evidence|reason_not_testable" /Users/stefan/Desktop/repos/wearedevpunks-skills/skills/agnostic/planning/create-plan/references
• reason_not_testable: No production runtime behavior changes in this task.
• red_evidence:
• green_evidence: rg "tdd_status|red_evidence|green_evidence|reason_not_testable" /Users/stefan/Desktop/repos/wearedevpunks-skills/skills/agnostic/planning/create-plan/references found the required fields in tdd-phase.md and plan-schema.md.
• review_mode: cli

T3: Enforce RED/GREEN proof in implementation and review contracts

• depends_on: [T2]
• location: /Users/stefan/Desktop/repos/wearedevpunks-skills/skills/agnostic/planning/implement-spec/references/lifecycle.md, /Users/stefan/Desktop/repos/wearedevpunks-skills/skills/agnostic/planning/implement-spec/references/sequential.md, /Users/stefan/Desktop/repos/wearedevpunks-skills/skills/agnostic/planning/implement-spec/references/parallel-worker-brief.md, /Users/stefan/Desktop/repos/wearedevpunks-skills/skills/phases/review-phase/SKILL.md
• description: Block task completion without RED/GREEN evidence or explicit non-testable reason; make missing proof a blocking review finding.
• validation: Implementation and review skills explicitly block missing TDD proof for behavior-changing tasks.
• status: Complete
• log: Updated implement-spec lifecycle/sequential/worker contracts to block completion without proof, and review-phase to treat missing RED/GREEN evidence as a blocking finding. Committed and pushed in wearedevpunks/skills@ea114f8.
• files edited/created: /Users/stefan/Desktop/repos/wearedevpunks-skills/skills/agnostic/planning/implement-spec/references/lifecycle.md, /Users/stefan/Desktop/repos/wearedevpunks-skills/skills/agnostic/planning/implement-spec/references/sequential.md, /Users/stefan/Desktop/repos/wearedevpunks-skills/skills/agnostic/planning/implement-spec/references/parallel-worker-brief.md, /Users/stefan/Desktop/repos/wearedevpunks-skills/skills/phases/review-phase/SKILL.md, apps/cli/skills/agnostic/planning/implement-spec/references/lifecycle.md, apps/cli/skills/agnostic/planning/implement-spec/references/sequential.md, apps/cli/skills/agnostic/planning/implement-spec/references/parallel-worker-brief.md, apps/cli/skills/phases/review-phase/SKILL.md
• backlog_item_id: none
• backlog_item_url: none
• relation_mode: none
• assigned_skills: [implement-spec, review-phase, tdd, simplify]
• tdd_status: not_applicable
• tdd_target: Documentation-only phase contract change; validate by text assertions and downstream sync.
• red_command: n/a
• expected_red_failure: n/a
• green_command: rg "RED/GREEN|red_evidence|green_evidence|reason_not_testable|blocking" /Users/stefan/Desktop/repos/wearedevpunks-skills/skills/agnostic/planning/implement-spec /Users/stefan/Desktop/repos/wearedevpunks-skills/skills/phases/review-phase/SKILL.md
• reason_not_testable: No production runtime behavior changes in this task.
• red_evidence:
• green_evidence: rg "RED/GREEN|red_evidence|green_evidence|reason_not_testable|blocking" ... found completion-blocking language in implement-spec references and review-phase.
• review_mode: cli

T4: Integrate the learning loop into docs-ingest-phase and phase discovery

• depends_on: [T3]
• location: /Users/stefan/Desktop/repos/wearedevpunks-skills/skills/phases/docs-ingest-phase/SKILL.md, /Users/stefan/Desktop/repos/wearedevpunks-skills/skills/phases/docs-ingest-phase/references/learning-artifacts.md, selected phase skills that should scan prior learnings
• description: Add scoped learning-artifact capture/refresh to docs ingest, define bug/knowledge schemas, require future-use hooks, and instruct requirements/spec/plan/debug/review phases to scan relevant learnings.
• validation: Docs ingest references outcomes keep, update, consolidate, replace, delete, mark_stale; phase skills mention relevant learning scans.
• status: Complete
• log: Added learning-artifacts.md, wired docs-ingest quick start/output/never-do rules to it, and instructed requirements, grill, spec, plan, debug, and review phases to scan routed learnings when relevant. Committed and pushed in wearedevpunks/skills@ea114f8.
• files edited/created: /Users/stefan/Desktop/repos/wearedevpunks-skills/skills/phases/docs-ingest-phase/SKILL.md, /Users/stefan/Desktop/repos/wearedevpunks-skills/skills/phases/docs-ingest-phase/references/learning-artifacts.md, /Users/stefan/Desktop/repos/wearedevpunks-skills/skills/phases/requirements-phase/SKILL.md, /Users/stefan/Desktop/repos/wearedevpunks-skills/skills/agnostic/requirements/requirements-grill/SKILL.md, /Users/stefan/Desktop/repos/wearedevpunks-skills/skills/agnostic/planning/create-spec/SKILL.md, /Users/stefan/Desktop/repos/wearedevpunks-skills/skills/agnostic/planning/create-plan/SKILL.md, /Users/stefan/Desktop/repos/wearedevpunks-skills/skills/phases/debugging-phase/SKILL.md, /Users/stefan/Desktop/repos/wearedevpunks-skills/skills/phases/review-phase/SKILL.md, corresponding apps/cli/skills/* synced copies
• backlog_item_id: none
• backlog_item_url: none
• relation_mode: none
• assigned_skills: [docs-ingest-phase, requirements-phase, create-spec, create-plan, debugging-phase, review-phase, simplify]
• tdd_status: not_applicable
• tdd_target: Documentation-only phase contract change; validate by text assertions and downstream sync.
• red_command: n/a
• expected_red_failure: n/a
• green_command: rg "learning artifact|future-use hook|mark_stale|learning_type" /Users/stefan/Desktop/repos/wearedevpunks-skills/skills
• reason_not_testable: No production runtime behavior changes in this task.
• red_evidence:
• green_evidence: rg "learning artifact|future-use hook|mark_stale|learning_type" /Users/stefan/Desktop/repos/wearedevpunks-skills/skills found docs-ingest learning schema, refresh outcomes, and consumer phase scan instructions.
• review_mode: cli

T5: Sync skills and prove scaffolded root prompt carries the compact invariant

• depends_on: [T4]
• location: apps/cli/src/content/prompts.ts, apps/cli/src/content/content.test.ts, AGENTS.md, apps/cli/skills/*, .agents/skills/*
• description: Add a focused RED test for the scaffolded root prompt learning invariant, patch the prompt, then run bun run sync:skills.
• validation: Focused content test fails before prompt change, passes after prompt change, and synced skill copies contain shared-source updates.
• status: Complete
• log: Added focused content test, observed RED against missing rootPromptTemplate invariant, patched the scaffolded root prompt and current repo AGENTS.md, pushed shared skill source, reran bun run sync:skills to pull wearedevpunks/skills@ea114f8 into apps/cli/skills, then aligned affected .agents/skills dirs from the CLI bundle.
• files edited/created: apps/cli/src/content/content.test.ts, apps/cli/src/content/prompts.ts, AGENTS.md, apps/cli/skills/**, .agents/skills/{create-plan,create-spec,implement-spec,tdd,requirements-grill,debugging-phase,docs-ingest-phase,requirements-phase,review-phase}/**
• backlog_item_id: none
• backlog_item_url: none
• relation_mode: none
• assigned_skills: [tdd, dp-cli, simplify]
• tdd_status: required
• tdd_target: Scaffolded root prompt includes a compact instruction to consult relevant routed learning artifacts during discovery, planning, debugging, and review.
• red_command: bun run --cwd apps/cli test src/content/content.test.ts
• expected_red_failure: Content test fails because rootPromptTemplate does not include the routed-learning scan invariant yet.
• green_command: bun run --cwd apps/cli test src/content/content.test.ts
• reason_not_testable:
• red_evidence: After adding the assertion, bun run --cwd apps/cli test src/content/content.test.ts failed with expected '## Root Guidance...' to contain 'When routed learning artifacts exist, consult relevant learnings during discovery, planning, debugging, and review.'
• green_evidence: After patching rootPromptTemplate, bun run --cwd apps/cli test src/content/content.test.ts passed: 1 file, 18 tests.
• review_mode: cli

T6: Update operator docs and implementation notes

• depends_on: [T5]
• location: docs/README.md, docs/runbooks/dp-cli-scaffolding.md, apps/wiki/content/docs/project/specs/cli/harness-phase-upgrades/IMPLEMENTATION-NOTES.md, apps/wiki/log.md
• description: Document the new TDD evidence contract, docs-ingest learning loop, and shared-skill sync implication.
• validation: Docs mention RED/GREEN evidence, docs-ingest learning refresh outcomes, and compact scaffolded root invariant.
• status: Complete
• log: Updated root docs, scaffold runbook, wiki log, spec status, and implementation notes with the new TDD evidence contract, docs-ingest learning refresh loop, root invariant, and shared skill commit.
• files edited/created: docs/README.md, docs/runbooks/dp-cli-scaffolding.md, apps/wiki/content/docs/project/specs/cli/harness-phase-upgrades/IMPLEMENTATION-NOTES.md, apps/wiki/content/docs/project/specs/cli/harness-phase-upgrades/SPEC.md, apps/wiki/content/docs/project/specs/cli/harness-phase-upgrades/PLAN.md, apps/wiki/log.md
• backlog_item_id: none
• backlog_item_url: none
• relation_mode: none
• assigned_skills: [docs-ingest-phase, simplify]
• tdd_status: not_applicable
• tdd_target: Documentation-only repo docs update; validate by text assertions and diff review.
• red_command: n/a
• expected_red_failure: n/a
• green_command: rg "RED/GREEN evidence|learning refresh|routed learning" docs apps/wiki/content/docs/project/specs/cli/harness-phase-upgrades
• reason_not_testable: No production runtime behavior changes in this task.
• red_evidence:
• green_evidence: rg "RED/GREEN evidence|learning refresh|routed learning" docs apps/wiki/content/docs/project/specs/cli/harness-phase-upgrades found the documented operator workflow and spec-folder evidence.
• review_mode: cli

Testing Strategy

• rg assertions over shared skill source before sync.
• RED: bun run --cwd apps/cli test src/content/content.test.ts fails after adding the prompt invariant assertion and before patching rootPromptTemplate.
• GREEN: bun run --cwd apps/cli test src/content/content.test.ts passes after prompt patch.
• bun run sync:skills
• bun run --cwd apps/cli test src/content/content.test.ts
• bun run --cwd apps/cli check
• git diff --check

Risks And Mitigations

• Risk: TDD language becomes too broad and blocks docs/config work. Mitigation: keep explicit not_applicable and reason_not_testable categories.
• Risk: Agents use reason_not_testable as an escape hatch for forgotten RED. Mitigation: explicitly forbid that recovery path.
• Risk: Learning artifacts become a second memory tree. Mitigation: canonical learning stays routed; memory notes only compact hard-to-discover routing aids.
• Risk: Root prompt gets bloated. Mitigation: keep the invariant compact and put mechanics in phase skills.
• Risk: Skill sync overwrites local generated skill edits. Mitigation: edit shared source first and treat synced copies as generated.

Validation Gates

Unresolved Questions

None.