Spec: Harness Intelligence Lifecycle

User Input

IP-104 outcome: lifecycle captured from requirements discovery through backlog, specs, plans, implementation, validation, review, debug, and docs maintenance. Scope includes requirements-grill -> write-backlog, create-spec -> create-plan -> swarm-planner, sequential/parallel implement-spec, tdd, agent-browser, review, debug-agent, and docs closeout. Backlog stays product-facing; execution detail belongs in specs/plans/implementation notes.

Child requirements:

IP-128: requirements-to-backlog workflow is explicit in the harness.
IP-129: planning workflow produces specs, plans, and parallel-ready task pipelines.
IP-130: implementation workflow records execution mode and closeout evidence.

Initial Situation

Harness Intelligence already ships phase-wrapper skills and private wiki pages that describe the operating model. The current knowledge is distributed across grill artifacts, reference docs, skill contracts, and compact lifecycle pages. Internal colleagues and future agents need one coherent lifecycle contract that explains how a vague request becomes backlog, spec, plan, implementation, review, debugging, docs maintenance, and tracker closeout.

Issue

The lifecycle exists as practice, but it is not codified deeply enough as an enforceable product contract. Without this, agents can flatten backlog into execution tasks, skip child-story coverage, treat validation as optional, mix sequential and parallel modes, or bury closeout evidence in chat instead of durable artifacts.

Solution

Codify the lifecycle across source wiki, routed project/wiki pages, distributed skill guidance, and repo docs. The lifecycle must preserve the separation between product-facing backlog and execution artifacts:

requirements artifacts feed backlog structure
backlog epics and stories feed one-spec-per-capability SDD
plans translate specs into dependency-aware execution
implementation records mode, task/wave evidence, validation, review, debugging, debt, docs ingest, and tracker readiness

Child Coverage

Child	Required outcome	Covered by
IP-128	Requirements grill artifacts are structured inputs to `write-backlog`; parked branches stay deferred; backlog stays product-facing.	Lifecycle docs, requirements/backlog skill guidance, spec acceptance criteria.
IP-129	`create-spec` anchors one epic and all children; `create-plan` closes planning questions; `swarm-planner` creates dependency-aware parallel work; source inspection uses official docs and `opensrc`.	Planning docs, skill guidance reconciliation, plan schema/task metadata.
IP-130	`implement-spec` records execution mode, updates plan/implementation notes/debt after tasks or waves, and finalizes with acceptance audit plus docs/backlog follow-through.	Implementation lifecycle docs, implementation notes contract, review/validation gates.

Non-Goals

Creating one backlog issue per execution task.
Replacing Linear product/backlog state with implementation notes.
Public landing copy.
Customer-specific methodology examples.
Changing the punks/dp command identity.

Acceptance Criteria

A durable lifecycle page explains the path from requirements discovery through docs maintenance and tracker closeout.
Requirements-to-backlog guidance treats *-grill-log.md and *-grill-status.md as structured inputs and keeps parked branches deferred.
Spec guidance states one SPEC.md maps to one parent epic/capability and must preserve every child/subissue requirement.
Plan guidance requires dependency graph, validation gates, skill routing, tdd_target, review mode, and child/story links.
Implementation guidance requires one explicit execution mode, task/wave evidence updates, acceptance audit, review, optional runtime-evidence debugging, docs ingest, and tracker readiness.
Distributed scaffold/skill guidance does not put global phase skills into scoped AGENTS.md primary skill lists.
Stale lifecycle wording is reconciled where it conflicts with current repo policy, especially source inspection and browser validation guidance.
Specs index, wiki log, routed Fumadocs metadata, root docs, and implementation notes are updated.

Constraints

apps/wiki owns private source content.
Backlog issue bodies stay product-facing.
Phase skills are global orchestration entrypoints, not scoped package/app primary skills.
Validation is a core acceptance gate, not a best-effort afterthought.
Use portless/stable local subdomains in docs examples when local dev URLs are needed.

Technical Notes

Existing lifecycle material: docs/reference/harness-intelligence.md, apps/wiki/content/docs/harness/concepts/phase-goal-workflow.md, apps/wiki/content/docs/harness/flows/delivery-lifecycle.md.
Current drift found during discovery: apps/wiki/AGENTS.md lists docs-ingest-phase as a scoped primary skill even though current policy forbids phase skills in scoped primary lists.
swarm-planner source-inspection wording should align with repo guidance: official docs/web first when current behavior matters, then opensrc for source.
agent-browser guidance contains generic examples that should become Harness validation gate language if it is distributed as part of trust evidence.

Validation Plan

git diff --check
bun run check
bun run check-types
targeted tests for any changed scaffold skill/catalog generation
JSON validation for changed meta.json
browser smoke for affected wiki routes if routed docs change

Decision Log

Decision	Rationale
Treat IP-104 as docs plus distributed workflow contract	The issue is about codifying lifecycle behavior, not inventing a new runtime feature.
Keep backlog product-facing	This is explicit in IP-104 and prevents Linear from becoming worker-task storage.
Fix scoped phase-skill drift as part of lifecycle codification	The drift directly contradicts the lifecycle contract and would be copied into future prompts.

Open Questions

#	Question	Affects	Owner	Status
1	Should the stale `apps/cli/scaffold-manifest.json` be repaired in M4 or captured as separate scaffold-state debt?	Generated scaffold evidence	Delivery	Non-blocking; decide during implementation after diff scope review.

Spec: Harness Intelligence Lifecycle

On this page