Harness Planning

Harness Planning

Implementation planning with atomic tasks, goal-backward must-haves, and complete executable instructions. Every task fits in one context window.

When to Use

• After a design spec is approved (output of harness-brainstorming) and implementation needs planning
• When starting a new feature or project needing structured task decomposition
• When on_new_feature or on_project_init triggers fire and the work is non-trivial
• When resuming a stalled project that needs a fresh plan
• NOT for small tasks (under 15 minutes, single file — just do it)
• NOT for problem exploration (use harness-brainstorming)
• NOT when a plan exists and needs execution (use harness-execution)

Process

Iron Law

Every task in the plan must be completable in one context window (2-5 minutes). If a task is larger, split it.

A plan with vague tasks like "add validation" or "implement the service" is not a plan — it is a wish list. Every task must contain exact file paths, exact commands, and complete code snippets.

---

Rigor Levels

The rigorLevel is passed by autopilot (or set via --fast/--thorough flags). Default is standard.

Phase	fast	standard (default)	thorough
SCOPE	No change.	No change.	No change.
KNOWLEDGE	Skip entirely.	Run detect; fix if gaps found.	Run detect; fix if gaps found.
DECOMPOSE	Skip skeleton. Full tasks directly after file map.	Skeleton if tasks >= 8; full tasks if < 8.	Always skeleton. Require approval before expanding.
SEQUENCE	No change.	No change.	No change.
VALIDATE	No change.	No change.	No change.

The skeleton pass is the primary rigor lever. Fast mode goes straight to full detail. Thorough mode validates direction before investing tokens in expansion.

---

Argument Resolution

When invoked by autopilot (or with explicit arguments), resolve paths before starting:

1. Session slug: If session-slug argument provided, set {sessionDir} = .harness/sessions/<session-slug>/. Pass to gather_context({ session: "<session-slug>", include: ["state", "learnings", "handoff", "graph", "businessKnowledge", "sessions", "validation"] }). All handoff writes go to {sessionDir}/handoff.json.
2. Spec path: If spec-path argument provided, read spec from that path. Otherwise, discover from {sessionDir}/handoff.json (read upstream brainstorming output) or prompt the user.
3. Rigor level: If fast/thorough argument provided, use it. Otherwise default to standard.

When no arguments are provided (standalone invocation), discover spec from context or prompt. Global .harness/ paths used as fallback.

---

Phase 1: SCOPE — Derive Must-Haves from Goals

Work backward from the goal. Start with "what must be true when we are done?"

1. State the goal. One sentence. What does the system do when this plan is complete?

1b. Load skill recommendations. After loading the spec, check for skill recommendations:

• If docs/changes/<feature>/SKILLS.md exists alongside the spec: parse the Apply and Reference tiers. These inform task annotation in Phase 2.

• If SKILLS.md is missing but a spec exists: run the advisor inline using advise_skills MCP tool to generate SKILLS.md.

• If neither SKILLS.md nor a spec exists: emit a one-line note:

  Note: No skill recommendations found. Run the advisor to discover
  relevant design, framework, and knowledge skills:
    harness advise-skills --spec-path <path>
  

Store the parsed skill list for use in Phase 2 task annotation.

2. Review prior decisions. Check decisions from the prior brainstorming session (loaded via sessions in gather_context). Do not re-decide what was already decided — build on those choices.

3. Derive observable truths. What can be observed (running a command, opening a browser, reading a file) that proves the goal is met? Be specific:

   • BAD: "The API handles errors"
   • GOOD: "GET /api/users/nonexistent returns 404 with { error: 'User not found' } body"

4. Derive required artifacts. For each truth, what files must exist? What functions? What tests pass? List exact file paths.

5. Identify key links. How do artifacts connect? What imports what? What calls what?

6. Apply YAGNI. For every artifact: "Is this required for an observable truth?" If not, cut it.

7. Surface uncertainties. Before proceeding to Phase 2, explicitly list what you do NOT know. For each uncertainty, classify it:

   • Blocking: Cannot decompose tasks without resolving this. Escalate to user.
   • Assumption: Can proceed with a stated assumption. Document it. If wrong, specific tasks will need revision.
   • Deferrable: Does not affect task decomposition. Note for execution phase.

   Format:

   ## Uncertainties
   - [BLOCKING] How should the API handle partial failures? (Spec does not define.)
   - [ASSUMPTION] Database supports transactions. (If not, Task 3 needs redesign.)
   - [DEFERRABLE] Exact error message wording. (Can be finalized during implementation.)
   

   Read-only constraint: Steps 1-6 above are research and analysis. Do not propose task structure, file organization, or implementation approaches during SCOPE. Record what must be true (observable truths) and what you do not know (uncertainties). Solutions belong in DECOMPOSE.

   When scope is ambiguous, use emit_interaction:

   emit_interaction({
     path: "<project-root>",
     type: "question",
     question: {
       text: "The spec mentions X but does not define behavior for Y. Should we:",
       options: [
         {
           label: "A) Include Y in this plan",
           pros: ["Complete feature in one pass", "No follow-up coordination"],
           cons: ["Increases scope and time", "May delay delivery"],
           risk: "medium",
           effort: "high"
         },
         {
           label: "B) Defer Y to a follow-up plan",
           pros: ["Keeps current plan focused", "Ship sooner"],
           cons: ["Y remains unhandled", "May need rework when Y is added"],
           risk: "low",
           effort: "low"
         },
         {
           label: "C) Update the spec first",
           pros: ["Design is complete before planning", "No surprises during execution"],
           cons: ["Blocks planning until spec is updated", "Extra round-trip"],
           risk: "low",
           effort: "medium"
         }
       ],
       recommendation: {
         optionIndex: 1,
         reason: "Keeping the current plan focused reduces risk. Y can be addressed in a follow-up.",
         confidence: "medium"
       }
     }
   })
   

EARS Requirement Patterns

Use EARS (Easy Approach to Requirements Syntax) when writing observable truths. These patterns eliminate ambiguity via consistent grammatical structure.

Pattern	Template	Use When
Ubiquitous	The system shall [behavior].	Always applies, unconditionally
Event-driven	When [trigger], the system shall [response].	Triggered by a specific event
State-driven	While [state], the system shall [behavior].	Only during a certain state
Optional	Where [feature is enabled], the system shall [behavior].	Gated by config or feature flag
Unwanted	If [condition], then the system shall not [behavior].	Preventing undesirable behavior

Worked Examples:

1. Ubiquitous: "The system shall return JSON responses with Content-Type: application/json header."
2. Event-driven: "When a user submits an invalid form, the system shall display field-level error messages within 200ms."
3. State-driven: "While the database connection is unavailable, the system shall serve cached responses and log reconnection attempts."
4. Optional: "Where rate limiting is enabled, the system shall reject requests exceeding 100/minute per API key with HTTP 429."
5. Unwanted: "If the request body exceeds 10MB, then the system shall not attempt to parse it — return HTTP 413 immediately."

Apply EARS for behavioral requirements, not structural checks (e.g., file existence does not need EARS framing).

Graph-Enhanced Context (when available)

When a knowledge graph exists at .harness/graph/, use graph queries for faster context:

• query_graph — discover module dependencies for realistic task decomposition
• get_impact — estimate which modules a feature touches
• compute_blast_radius — simulate failure propagation from target files to understand scope
• predict_failures — forecast which architectural constraints are at risk from planned changes, informing where extra test coverage or smaller tasks are needed
• detect_anomalies — identify structural irregularities in the affected area before planning tasks around them

Fall back to file-based commands if no graph is available.

Intelligence Signals (when orchestrator is available)

If the orchestrator is running, request intelligence analysis via POST /api/analyze with the feature title/description before decomposing. The pipeline returns:

• SEL (Spec Enrichment) — affected systems and blast radius derived from the graph
• CML (Complexity Modeling) — structural, semantic, and historical complexity scores. Use structuralComplexity > 0.7 to flag areas needing smaller, more cautious tasks.
• PESL (Pre-Execution Simulation) — simulated risk score. Use riskScore > 0.6 to add extra checkpoints or split risky tasks further.

If no orchestrator, predict_failures and compute_blast_radius MCP tools provide equivalent directional signals.

---

Phase 1.5: KNOWLEDGE BASELINE — Materialize Domain Knowledge

Before decomposing into tasks, ensure domain knowledge from PRDs and specs is documented. Skip this phase when no PRDs, specs, or business domain documents exist in the project, or when rigor level is fast.

1. Run knowledge pipeline in detect mode. Execute harness knowledge-pipeline --domain <feature-domain> to produce a differential gap report comparing extracted business rules against documented knowledge in docs/knowledge/.

2. If gaps exist and --fix is appropriate, run harness knowledge-pipeline --fix --domain <feature-domain> to materialize docs/knowledge/{domain}/*.md files from extracted findings. This creates the knowledge baseline from PRDs before any tasks are written.

3. Cross-check uncertainties against materialized knowledge (from businessKnowledge loaded in gather_context and freshly materialized docs):

   • Remove "assumptions" from the uncertainty list that are now documented facts in docs/knowledge/
   • Escalate if contradictions exist between PRDs and existing knowledge docs
   • Use business_fact nodes from the graph context to validate domain assumptions

4. Reference materialized knowledge in Phase 2 task decomposition. Tasks should reference specific knowledge docs they implement. Observable truths should map back to documented business rules. Use the businessKnowledge context (domains, tags, documented facts) loaded in Phase 1 to ground task instructions in verified domain knowledge rather than assumptions.

---

Phase 2: DECOMPOSE — Map File Structure and Create Tasks

Report progress: **[Phase 2/4]** DECOMPOSE — mapping file structure and creating tasks

1. Map the file structure first. List every file to create or modify before writing tasks:

   CREATE src/services/notification-service.ts
   CREATE src/services/notification-service.test.ts
   MODIFY src/services/index.ts (add export)
   CREATE src/types/notification.ts
   MODIFY src/api/routes/users.ts (add notification trigger)
   

2. Skeleton pass (rigor-gated). Lightweight skeleton (~200 tokens) validates direction before full expansion. Gating per Rigor Levels table.

   Format: Numbered logical groups with task count and time. No file paths, code, or details.

   1. Foundation types and interfaces (~3 tasks, ~10 min)
   2. Core scoring module with TDD (~2 tasks, ~8 min)
   3. CLI integration and flag parsing (~4 tasks, ~15 min)
   **Estimated total:** 8 tasks, ~33 minutes
   

   Approval gate: Present via emit_interaction (type: confirmation, text: "Approve skeleton direction?"). If approved, proceed to step 3. If rejected, revise and re-present.

3. Decompose into atomic tasks. Each task must:

   • Be completable in 2-5 minutes, fit in a single context window
   • Have a clear, testable outcome
   • Follow TDD: write test, fail, implement, pass, commit
   • Produce one atomic commit

4. Write complete instructions for each task. Not summaries — complete executable instructions:

   • Exact file paths to create or modify
   • Exact code to write (not "add validation logic" — write the actual code)
   • Exact test commands (e.g., npx vitest run src/services/notification-service.test.ts)
   • Exact commit message
   • harness validate as the final step

5. Skill annotations. If skill recommendations were loaded in Phase 1, annotate each task with relevant skills from the Apply and Reference tiers:

   ### Task 3: Implement dark mode toggle
   **Skills:** `design-dark-mode` (apply), `a11y-color-contrast` (reference)
   

   Match skills to tasks based on keyword and domain overlap between the task description and the skill's purpose/keywords. Only annotate when the match is relevant to the specific task.

6. Include checkpoints. Mark tasks requiring human input:

   • [checkpoint:human-verify] — Pause, show result, wait for confirmation
   • [checkpoint:decision] — Pause, present options, wait for choice
   • [checkpoint:human-action] — Pause, instruct human on required action

7. Derive integration tasks from the spec's Integration Points section. If the spec contains an Integration Points section, create tasks for each non-empty integration point. Skip subsections marked "None" — do not derive tasks from them. Integration tasks are normal plan tasks but tagged with category: "integration" in their description. They appear at the end of the task list, after all implementation tasks.

   For each subsection of Integration Points, derive tasks:

   Integration Point	Example Derived Task
   Entry Points: "New CLI command"	"Regenerate barrel exports. Verify new command appears in _registry.ts."
   Registrations Required: "Skill at tier 2"	"Add skill to tier list in AGENTS.md. Generate slash commands."
   Documentation Updates: "AGENTS.md capabilities"	"Update AGENTS.md to describe the feature."
   Architectural Decisions: "ADR for approach X"	"Write ADR docs/knowledge/decisions/NNNN-<slug>.md."
   Knowledge Impact: "Domain concept Y"	"Enrich knowledge graph with concept node."

   Integration tasks follow the same atomic task rules (2-5 minutes, exact file paths, exact code). Use the **Category:** integration tag in the task header, e.g.:

   ### Task N: Update AGENTS.md with new feature description
   
   **Depends on:** Task N-1 | **Files:** `AGENTS.md` | **Category:** integration
   

   If the spec has no Integration Points section, skip this step.

---

Phase 3: SEQUENCE — Order Tasks and Identify Dependencies

1. Order by dependency. Types before implementations. Implementations before integrations. Integration tasks (tagged category: "integration") after all implementation tasks. Tests alongside implementations (same task, TDD style).
2. Identify parallel opportunities. Tasks touching different subsystems with no shared state can be marked parallelizable.
3. Number tasks sequentially. Use Task 1, Task 2, etc. Dependencies reference task numbers.
4. Estimate total time. Sum 2-5 minutes per task. If total exceeds available time, identify a milestone boundary for pausing.

---

Phase 4: VALIDATE — Review and Finalize the Plan

1. Verify completeness. Every observable truth from Phase 1 must trace to specific task(s) that deliver it.

2. Verify task sizing. Could an agent complete each task in one context window without exploring or deciding? If not, split it.

3. Verify TDD compliance. Every code-producing task must include a test step. No "write tests later."

4. Run harness validate to verify project health before writing the plan.

5. Check failures log. Read .harness/failures.md. If planned approaches match known failures, flag them.

6. Run soundness review. Invoke harness-soundness-review --mode plan against the draft. Do not proceed until the review converges with no remaining issues.

7. Write the plan to docs/changes/<topic>/plans/. Naming: YYYY-MM-DD-<feature-name>-plan.md. Resolve <topic> from the spec path — if the spec lives at docs/changes/<topic>/proposal.md, the plan goes in the sibling plans/ directory. If the spec is not under docs/changes/, fall back to docs/plans/ and flag the spec location for human review. Create directories as needed.

8. Commit plan artifact. Immediately after writing the plan, commit it so the paper trail enters git history at planning time, not after execution:

   git add docs/changes/<topic>/plans/YYYY-MM-DD-<feature-name>-plan.md
   git commit -m "docs(<topic>): add plan"
   

   Use docs/plans/ if the spec is not under docs/changes/<topic>/. Do not skip — harness-execution commits only implementation files, so a plan uncommitted here stays untracked until someone notices. If a pre-commit hook reformats the file, re-add and re-commit.

9. Write handoff. Write to the session-scoped path when session slug is known, otherwise fall back to global path:

   • Session-scoped (preferred): .harness/sessions/<session-slug>/handoff.json
   • Global (fallback, deprecated): .harness/handoff.json

   [DEPRECATED] Writing to .harness/handoff.json is deprecated. In autopilot sessions, always use .harness/sessions/<slug>/handoff.json to prevent cross-session contamination.

   Fields: fromSkill, phase, summary, completed, pending, concerns, decisions, contextKeywords.

10. Write session summary (if session is known). Call writeSessionSummary with skill, status, plan path, keyContext, nextStep. Skip if no session slug.

11. Request plan sign-off: Use emit_interaction (type: confirmation) with plan path, task count, and time estimate.

12. Suggest transition to execution. After approval, call emit_interaction with type: transition, completedPhase: "planning", suggestedNext: "execution", requiresConfirmation: true. Include qualityGate with checks: plan-written, harness-validate, observable-truths-traced, human-approved. If confirmed: invoke harness-execution. If declined: stop (handoff already written).

---

Plan Document Structure

# Plan: <Feature Name>

**Date:** YYYY-MM-DD | **Spec:** (if applicable) | **Tasks:** N | **Time:** N min | **Integration Tier:** small | medium | large

## Goal

One sentence.

## Observable Truths (Acceptance Criteria)

1. [observable truth]

## File Map

- CREATE path/to/file.ts
- MODIFY path/to/other-file.ts

## Skeleton (if produced)

1. <group name> (~N tasks, ~N min)
   _Skeleton approved: yes/no._

## Tasks

### Task 1: <descriptive name>

**Depends on:** none | **Files:** path/to/file.ts, path/to/file.test.ts

1. Create test file with exact test code
2. Run test — observe failure
3. Create implementation with exact code
4. Run test — observe pass
5. Run: `harness validate`
6. Commit: `feat(scope): descriptive message`

### Task 2: <descriptive name>

[checkpoint:human-verify] ...

Integration Tier Heuristics

When a spec contains an Integration Points section, set the plan's integrationTier field based on scope:

Tier	Signal	Integration Requirements
small	Bug fix, config change, < 3 files, no new exports	Wiring checks only (defaults always run)
medium	New feature within existing package, new exports, 3-15 files	Wiring + project updates (roadmap, changelog, graph enrichment)
large	New package, new skill, new public API surface, architectural change	Wiring + project updates + knowledge materialization (ADRs, doc updates)

If the spec has no Integration Points section, omit the integrationTier field from the plan header.

Session State

Section	Read	Write	Purpose
terminology	yes	no	Consistent language in plan
decisions	yes	yes	Brainstorming decisions; planning-phase decisions
constraints	yes	yes	Existing constraints; constraints discovered during decomposition
risks	yes	yes	Existing risks; implementation risks from task design
openQuestions	yes	yes	Unresolved questions; new questions; resolve answered ones
evidence	yes	yes	Prior evidence; file:line citations for task specs

When to write: Phase 1 — constraints and risks. Phase 2 — decisions about task structure. Phase 4 — resolve questions.

When to read: Start of Phase 1 via gather_context with include: ["state", "learnings", "handoff", "graph", "businessKnowledge", "sessions", "validation"] to inherit brainstorming context and load documented business knowledge.

Evidence Requirements

When referencing existing code in task specs, cite evidence using file:line format, code pattern references, or test output. Write to evidence session section via manage_state.

When to cite: Phase 1 (existing files), Phase 2 (file paths and patterns), file map (existing files for modification).

Uncited claims: Prefix with [UNVERIFIED].

Harness Integration

• harness validate — Run in Phase 4 (before writing plan) and included in every task.
• harness check-deps — Referenced in tasks adding imports or creating modules.
• Plan commit — After writing the plan (Phase 4 Step 8), commit docs/changes/<topic>/plans/YYYY-MM-DD-<feature-name>-plan.md so the paper trail enters git history at planning time. harness-execution does not backfill — see issue #487.
• Plan location — docs/changes/<topic>/plans/YYYY-MM-DD-<feature-name>-plan.md when the spec lives under docs/changes/<topic>/proposal.md; otherwise docs/plans/ as a fallback.
• Handoff — Once approved, invoke harness-execution for task-by-task implementation.
• Session directory — Session-scoped writes go to .harness/sessions/<slug>/. Structure: handoff.json, state.json, artifacts.json (registry of spec/plan paths and produced file lists). Global .harness/handoff.json is deprecated for session-aware invocations.
• emit_interaction — Call at end of Phase 4 to suggest transitioning to execution (confirmed transition).
• Rigor levels — --fast/--thorough control skeleton pass. See Rigor Levels table.
• Two-pass planning — Skeleton (~200 tokens) before full expansion. Catches directional errors early.

Change Specifications

When planning changes to existing functionality (not greenfield), express requirements as deltas:

• [ADDED] — New behavior that does not exist today
• [MODIFIED] — Existing behavior that changes
• [REMOVED] — Existing behavior that goes away

Example:

## Changes to User Authentication

- [ADDED] OAuth2 refresh tokens with 7-day expiry
- [MODIFIED] Login endpoint returns `refreshToken` alongside `accessToken`
- [MODIFIED] Token validation accepts both JWT and OAuth2 tokens
- [REMOVED] Legacy API key authentication (deprecated in v2.1)

Only apply when modifying existing documented behavior. When docs/changes/ exists, produce docs/changes/<feature>/delta.md alongside the task plan.

Success Criteria

• Plan document exists at the resolved location (docs/changes/<topic>/plans/ or docs/plans/ fallback) with all required sections
• Every task completable in 2-5 minutes (one context window)
• Every task includes exact file paths, exact code, and exact commands
• Every code-producing task follows TDD: test first, fail, implement, pass
• Observable truths trace to specific tasks
• File map lists every file to create or modify
• Checkpoints marked where human input is required
• harness validate passes before plan is written and is in every task
• Human has reviewed and approved the plan
• Rigor level rules followed: fast skips skeleton; thorough always skeletons with approval; standard skeletons at >= 8 tasks

Red Flags

Flag	Corrective Action
"I know the implementation well enough to skip reading the spec"	STOP. Phase 1 SCOPE starts by reading the spec. Assumptions about spec content lead to plans that implement the wrong thing.
"This task is self-explanatory, no need for exact file paths and commands"	STOP. Iron Law: every task must contain exact file paths, exact commands, and complete code snippets. "Implement the service" is a wish, not a task.
"I'll plan the happy path now and add error handling tasks later"	STOP. Error handling is not optional. The spec's success criteria include error scenarios. Plan them alongside the happy path.
// detailed steps TBD or // expand during execution in task descriptions	STOP. A task that defers detail to execution is a vague task. If you cannot write the exact steps now, you do not understand the task well enough to plan it.

Rationalizations to Reject

Rationalization	Reality
"The task is conceptually clear so I do not need to include exact code in the plan"	Every task must have exact file paths, exact code, and exact commands. If you cannot write the code in the plan, you do not understand the task well enough to plan it.
"This task touches 5 files but it is logically one unit of work, so splitting it would add overhead"	Tasks touching more than 3 files must be split. The overhead of splitting is far less than the cost of a failed oversized task.
"Tests for this task can be added in a follow-up task since the implementation is straightforward"	No skipping TDD in tasks. Every code-producing task must start with writing a test. "Add tests later" is explicitly forbidden.
"The spec does not cover this edge case, but I can fill in the gap during planning"	When the spec is missing information, do not fill in the gaps yourself. Escalate. Filling gaps silently creates undocumented design decisions that no one reviewed.
"I discovered we need an additional file during decomposition, but updating the file map is just bookkeeping"	The file map must be complete. Every file that will be created or modified must appear in the file map before task decomposition.
"There are no real uncertainties — the spec is clear enough"	Every plan has unknowns. If you listed zero uncertainties, you skipped the step. Re-read the spec and list what is assumed but not stated.
"I already know how to structure this, no need to finish scoping"	Premature decomposition anchors on the first approach found. Complete SCOPE (observable truths + uncertainties) before proposing any task structure.
"The skeleton pass adds overhead for a plan this size — I will go straight to full tasks"	Rigor level rules are not optional. In thorough mode, the skeleton is always required. In standard mode, 8+ tasks require a skeleton. Skipping it risks task-level misalignment with the goal.
"I will write implementation code in the plan to make the tasks more concrete"	Planning produces a plan document, not code. Writing code during planning violates the phase boundary — code belongs in execution. Exact snippets in task descriptions are plan content, not executed code.

Examples

Example: Planning a User Notification Feature

Goal: Users receive email and in-app notifications when their account is modified.

Observable Truths:

1. POST /api/users/:id with changed fields triggers a notification record in the database
2. GET /api/notifications?userId=:id returns notification with type, message, timestamp
3. Notification email sent via existing email utility (verified by mock in test)
4. npx vitest run src/services/notification-service.test.ts passes with 8+ tests
5. harness validate passes

File Map:

CREATE src/types/notification.ts
CREATE src/services/notification-service.ts
CREATE src/services/notification-service.test.ts
MODIFY src/services/index.ts
MODIFY src/api/routes/users.ts
MODIFY src/api/routes/users.test.ts

Skeleton: Not produced — task count (6) below threshold (8).

Task 1: Define notification types

Files: src/types/notification.ts
1. Create src/types/notification.ts:
   export interface Notification {
     id: string;
     userId: string;
     type: 'account_modified';
     message: string;
     read: boolean;
     createdAt: Date;
     expiresAt: Date;
   }
2. Run: harness validate
3. Commit: "feat(notifications): define Notification type"

Task 2 (TDD): Write test for NotificationService.create(). Observe failure. Implement. Observe pass. Validate. Commit.

Task 3 (TDD): [checkpoint:human-verify] — Write tests for list() and isExpired(). Observe failures. Implement. Observe pass. Validate + check-deps. Commit.

Example: Skeleton (thorough mode)

Goal: Add rate limiting to all API endpoints.

Skeleton: 1) Rate limit types (~2 tasks, ~7 min) 2) Middleware with Redis (~3 tasks, ~12 min) 3) Route integration (~4 tasks, ~15 min) 4) Integration tests (~3 tasks, ~10 min). Total: 12 tasks, ~44 min. Presented for approval. Approved. Expanded to full tasks.

Gates

• No vague tasks. Every task must have exact file paths, exact code, and exact commands. If you cannot write the code, you do not understand the task well enough.
• No tasks larger than one context window. If a task requires exploring, deciding, or touching more than 3 files, split it.
• No skipping TDD. Every code-producing task starts with a test. "Add tests later" is not allowed.
• No plan without observable truths. Must start with goal-backward acceptance criteria.
• No implementation during planning. Write the plan, get approval, then use harness-execution.
• File map must be complete. Every file to create or modify must appear before task decomposition.
• Uncertainties must be surfaced. Phase 1 must produce an uncertainties list. Zero uncertainties means the step was skipped. Blocking uncertainties must be resolved before Phase 2.

Escalation

• Cannot write exact code for a task: Design is underspecified. Return to spec or brainstorm. Do not write vague placeholders.
• Task count exceeds 20: Consider splitting into multiple plans with milestone boundaries.
• Dependencies form a cycle: Re-examine file map. Break the cycle by extracting a shared type or interface.
• Spec is missing information: Do not fill gaps yourself. Escalate: "The spec does not define behavior for [scenario]. This blocks Task N."
• Estimated time exceeds available time: Identify a milestone boundary for pausing. Propose delivering in phases, each producing a usable increment.