Plan: IP-104 Harness Intelligence Lifecycle

Initial Situation

IP-104 is unblocked by completed IP-100. Lifecycle behavior exists across skills, wiki, and docs, but the durable contract has gaps and drift. IP-128/IP-129/IP-130 require a coherent lifecycle from requirements to closeout while keeping backlog product-facing.

Solution Shape

Update the lifecycle source of truth and distributed guidance in three gates: requirements/backlog, spec/plan, implementation/closeout. Reconcile scoped guidance drift, then project changes into docs/wiki and validate generated navigation and scaffold guidance.

Inner Skill Phases

• $grill-me: no live question needed; Linear children and grill artifacts define the scope.
• $parallel-research: used for lifecycle/skill/wiki discovery.
• $swarm-planner: tasks split by lifecycle band and shared projection.
• $tdd: route/build/catalog checks are the acceptance tests for docs/scaffold changes.

Tasks

T104-1: Codify requirements-to-backlog lifecycle

• depends_on: []
• location: apps/wiki/content/docs/harness, .agents/skills/requirements-phase, .agents/skills/create-spec, docs
• description: Make grill artifacts, parked branches, and product-facing backlog boundaries explicit in source/routed lifecycle docs and local skill guidance.
• validation: Search proves lifecycle docs mention grill log/status inputs, parked branches, and product-facing backlog boundary.
• status: Planned
• log:
• files edited/created:
• backlog_item_id: IP-128
• backlog_item_url: https://linear.app/devpunks/issue/IP-128/requirements-to-backlog-workflow-is-explicit-in-the-harness
• relation_mode: native
• assigned_skills: [parallel-research, simplify, docs-ingest-phase]
• tdd_target: A reader can determine that write-backlog consumes locked grill artifacts and does not absorb parked branches.
• review_mode: cli

T104-2: Codify spec, plan, and parallel planning contract

• depends_on: [T104-1]
• location: .agents/skills/create-spec, .agents/skills/create-plan, .agents/skills/swarm-planner, apps/wiki/content/docs/harness
• description: Reconcile planning guidance so specs map to one parent epic with all children, plans include dependency-aware tasks and TDD/review metadata, and source inspection uses official docs plus opensrc.
• validation: Skill/docs search shows one-epic spec coverage, child requirements, dependency-aware plan schema, and current source inspection order.
• status: Planned
• log:
• files edited/created:
• backlog_item_id: IP-129
• backlog_item_url: https://linear.app/devpunks/issue/IP-129/planning-workflow-produces-specs-plans-and-parallel-ready-task
• relation_mode: native
• assigned_skills: [parallel-research, simplify, tdd]
• tdd_target: A generated plan can be checked for depends_on, assigned_skills, tdd_target, review_mode, and child issue links.
• review_mode: cli

T104-3: Codify implementation, review, debug, and docs closeout

• depends_on: [T104-2]
• location: .agents/skills/implement-spec, .agents/skills/delivery-phase, .agents/skills/review-phase, .agents/skills/debugging-phase, .agents/skills/docs-ingest-phase, docs/wiki
• description: Ensure implementation mode, task/wave updates, acceptance audit, review, runtime-evidence debugging, docs ingest, debt, and tracker readiness are explicit.
• validation: Implementation lifecycle docs and skill guidance contain one execution mode, notes updates, review/debug/docs ingest gates, and closeout evidence.
• status: Planned
• log:
• files edited/created:
• backlog_item_id: IP-130
• backlog_item_url: https://linear.app/devpunks/issue/IP-130/implementation-workflow-records-execution-mode-and-closeout-evidence
• relation_mode: native
• assigned_skills: [review-phase, debugging-phase, docs-ingest-phase, simplify, tdd]
• tdd_target: IMPLEMENTATION-NOTES.md for M4 can record execution mode, wave evidence, validation, review, docs ingest, and tracker readiness without hidden chat state.
• review_mode: mixed

T104-4: Validate and document IP-104 closeout

• depends_on: [T104-3]
• location: apps/wiki/specs/cli/IP-104-harness-lifecycle, docs/README.md, wiki routed pages
• description: Update implementation notes, docs indexes, route metadata, run review, and record validation evidence.
• validation: git diff --check; bun run check; bun run check-types; JSON validation; browser smoke if routed pages changed.
• status: Planned
• log:
• files edited/created:
• backlog_item_id: IP-104
• backlog_item_url: https://linear.app/devpunks/issue/IP-104/codify-the-harness-intelligence-lifecycle
• relation_mode: native
• assigned_skills: [review-phase, agent-browser, turborepo, simplify]
• tdd_target: Lifecycle acceptance table maps every IP-128/IP-129/IP-130 criterion to repo evidence.
• review_mode: mixed

Dependency Graph

T104-1 -> T104-2 -> T104-3 -> T104-4

Validation Gates

• Gate 1: IP-128 lifecycle requirements are explicit.
• Gate 2: IP-129 planning metadata is explicit and current.
• Gate 3: IP-130 closeout evidence contract is explicit.
• Gate 4: docs/wiki/scaffold guidance validates.

Risks

• Over-documenting internal mechanics in routed human pages. Mitigation: source pages can be detailed; routed pages summarize and link.
• Rewriting unrelated scaffold state. Mitigation: capture stale scaffold manifest as debt if it is outside IP-104.

Unresolved Questions

• Stale apps/cli/scaffold-manifest.json handling remains non-blocking until implementation confirms whether M4 touches generated scaffold outputs.