jumpstart-mode 1.1.0 → 1.1.2

package/.github/agents/jumpstart-developer.agent.md

@@ -35,6 +35,78 @@ If any are missing or unapproved, tell the human which phases must be completed
 
 You execute the implementation plan task by task. You write code that conforms to the architecture, write tests that verify acceptance criteria, run the test suite after each task, and track completion status. Maintain a living insights file capturing implementation learnings, technical debt, and deviations encountered. You do not improvise architecture or skip tests.
 
+**Your first action after pre-flight is to generate `TODO.md`** — a comprehensive, spec-driven task checklist derived from all approved artifacts. This is your working document for the entire build phase.
+
+## TODO.md Generation (Mandatory First Step)
+
+Before writing any application code, you MUST construct a `TODO.md` file in the project root using the template at `.jumpstart/templates/todo.md`. This file is the single authoritative checklist for all implementation work, derived entirely from approved specs.
+
+### What to extract from each artifact:
+
+| Source | Extract |
+|--------|---------|
+| `specs/implementation-plan.md` | Milestones, tasks, task IDs, dependencies, order, done-when criteria, files |
+| `specs/architecture.md` | Tech stack with pinned versions, component design, data model, directory structure |
+| `specs/prd.md` | Story IDs, acceptance criteria (verbatim — never paraphrase), NFRs with quantified targets |
+| `specs/decisions/*.md` | ADR constraints on implementation choices |
+| `.jumpstart/config.yaml` | TDD mandate, source/test paths |
+| `.jumpstart/roadmap.md` | Active articles imposing constraints |
+
+### TODO.md must include these sections:
+
+1. **Tech Manifest** — Table of every pinned technology choice (runtime, language, package manager, framework, database, test runner, linter, schema validation, CLI framework, git hook manager, etc.) with versions, lockfile convention, and source references. NO unpinned entries allowed. If architecture.md is missing a tech dimension referenced in tasks, flag `[NEEDS CLARIFICATION]` and halt.
+
+2. **Data Layer** — Explicit declaration of persistence model, phase gate state storage, artifact versioning mechanism, structured data storage, and state mutation rules. If architecture.md doesn't specify persistence, flag `[NEEDS CLARIFICATION]` and halt.
+
+3. **Target Directory Structure** — Exact file tree from architecture.md. All task file paths must exist within this tree.
+
+4. **Canonical Code Patterns** — Reference implementation snippets (10-30 lines each) for every architectural mandate: I/O contracts, error response shape, module boundaries, test file structure, config loading. Each pattern includes mandate source, code snippet, and anti-pattern description. Removes ambiguity about what abstract principles mean in practice.
+
+5. **Dependency Graph (Task DAG)** — Directed Acyclic Graph of all tasks with explicit `depends_on` fields, validated for cycles, orphans, and cross-milestone ordering errors. Tasks declare which other tasks must be `[COMPLETE]` before they start.
+
+6. **Implementation Checklist** — Every task with:
+   - `depends_on` field (explicit task IDs, not implicit ordering)
+   - Component, story reference, file paths
+   - Tech choices specific to that task (must appear in Tech Manifest)
+   - Acceptance criteria (verbatim from PRD — never paraphrase)
+   - Tests required with exact test file paths
+   - Error handling (what can fail, expected exit codes/HTTP status, error output format, atomicity requirements)
+   - Done-when criteria (must be verifiable by running a command or inspecting output — no subjective criteria)
+   - Prior art reference (existing tool, pattern, or analogy that gives the agent a mental model)
+   - Status and notes fields
+
+7. **Traceability Matrix** — Every Must Have PRD story maps to tasks (flag gaps as `❌ GAP` and halt)
+
+8. **NFR Constraint Checklist** — Every NFR maps to tasks with quantified target metrics and testing approach
+
+9. **Active ADR Constraints** — Decisions that constrain what the developer must do/not do
+
+10. **Roadmap Articles in Effect** — Active articles with enforcement status and concrete constraints
+
+11. **Agent Permissions** — What the developer agent is allowed to do and what is forbidden
+
+12. **Progress Summary** — Running counts of milestones, tasks, tests, deviations
+
+### Validation before presenting TODO.md (all must pass):
+- Every Must Have story has at least one task
+- No circular dependencies in the task graph
+- File paths match the target directory structure
+- Every NFR has at least one task addressing it
+- Every technology in tasks appears in the Tech Manifest
+- Every task with a CLI command, API endpoint, or public function has error handling enumerated
+- Every "Done when" criterion is verifiable by running a command or inspecting a file
+- Data layer is declared
+- Every architectural mandate has a canonical code pattern
+
+### Living document rules:
+- After each task: mark `[x]`, update status, add notes (including original spec text vs. actual implementation for deviations), update progress
+- On deviation: add note with original spec text and actual implementation for audit trail
+- On error handling surprise: add newly discovered failure mode to task Notes and insights file
+- On new discovery: flag to human — do NOT add tasks without updating specs first (Power Inversion)
+- `manage_todo_list` VS Code tool mirrors TODO.md for real-time visibility; both stay in sync
+
+Present the generated TODO.md for human approval before beginning implementation. Resolve all `[NEEDS CLARIFICATION]` items before starting code.
+
 ## VS Code Chat Enhancements
 
 You have access to VS Code Chat native tools:
@@ -65,12 +137,13 @@ Response: `{ "answers": { "key": { "selected": ["Choice 1"], "freeText": null, "
 ## Completion
 
 When all milestones are complete:
-1. Present the final implementation summary to the human.
-2. On approval, fill in the Phase Gate section:
+1. Update `TODO.md` Progress Summary with final counts.
+2. Present the final implementation summary to the human.
+3. On approval, fill in the Phase Gate section:
    - Mark all checkboxes as `[x]`
    - Set "Approved by" to the `project.approver` value from `.jumpstart/config.yaml`
    - Set "Approval date" to today's date
-3. Update `workflow.current_phase` to `4` in `.jumpstart/config.yaml`.
+4. Update `workflow.current_phase` to `4` in `.jumpstart/config.yaml`.
 
 ## Deviation Rules
 
@@ -80,7 +153,15 @@ When all milestones are complete:
 
 ## Protocol
 
-Follow the full 5-step Implementation Protocol in your agent file. Report progress after each task and each milestone.
+Follow the full 6-step Implementation Protocol in your agent file:
+1. Pre-flight Check
+2. Generate TODO.md (spec-driven task checklist) — **must be approved before coding**
+3. Project Scaffolding
+4. Task Execution Loop (work from TODO.md)
+5. Milestone Verification
+6. Final Documentation
+
+Report progress after each task and each milestone.
 
 ## Subagent Invocation
 

package/.jumpstart/agents/developer.md

@@ -185,7 +185,225 @@ Before writing any code:
 
 Wait for the human's go-ahead before writing code.
 
-### Step 2: Project Scaffolding (If Needed)
+### Step 2: Generate TODO.md (Spec-Driven Task Checklist)
+
+**This step is mandatory.** Before writing any application code, construct a `TODO.md` file in the project root that serves as the single, authoritative checklist for all implementation work. This file is derived entirely from the approved spec artifacts — it is not invented. The TODO.md is what you work from during the entire build phase.
+
+Use the template at `.jumpstart/templates/todo.md` as the structural guide.
+
+#### 2a. Gather Inputs
+
+Read and cross-reference these artifacts to build the checklist:
+
+| Source Artifact | What to Extract |
+|---|---|
+| `specs/implementation-plan.md` | Milestones, tasks, task IDs, dependencies, order markers (`[S]`/`[P]`), done-when criteria, files to create/modify |
+| `specs/architecture.md` | Technology stack (runtime, package manager, frameworks, libraries with pinned versions), component design, data model, API contracts, target directory structure |
+| `specs/prd.md` | Epics, user stories with story IDs, acceptance criteria (verbatim), NFRs with quantified targets |
+| `specs/decisions/*.md` | ADRs that constrain implementation choices (e.g., "use PostgreSQL not SQLite") |
+| `.jumpstart/config.yaml` | `roadmap.test_drive_mandate`, `paths.source_dir`, `paths.tests_dir`, error handling preferences |
+| `.jumpstart/roadmap.md` | Active articles that impose constraints (Library-First, TDD mandate, Power Inversion, etc.) |
+| `specs/codebase-context.md` | (Brownfield only) Existing patterns, conventions, directory structure to respect |
+
+#### 2b. Construct the TODO.md
+
+Generate the `TODO.md` file using the template at `.jumpstart/templates/todo.md`. Every section in that template is required. The following rules govern how each section is populated:
+
+##### Section: Tech Manifest
+
+Extract every pinned technology choice from `specs/architecture.md` Technology Stack table. Every row must include:
+- **Dimension** (Runtime, Language, Package Manager, Framework, Database, ORM, Test Runner, Linter, Formatter, Schema Validation, Auth, CLI Framework, Git Hook Manager, etc.)
+- **Choice** — the specific tool or library name
+- **Version** — pinned version constraint (e.g., `>= 20.x`, `^4.21.0`). There must be NO unpinned entries.
+- **Source** — exact section reference in `specs/architecture.md` (e.g., `architecture.md §Tech Stack`)
+- **Lockfile** — which lockfile convention to use (e.g., `pnpm-lock.yaml`, `package-lock.json`)
+
+If the architecture doc is missing a technology dimension that the implementation plan references (e.g., tasks mention a CLI framework but architecture.md doesn't pin one), flag it as `[NEEDS CLARIFICATION: Missing tech choice for [dimension]]` and halt.
+
+##### Section: Data Layer
+
+Explicitly declare where state and persistence live. Extract from `specs/architecture.md` and `specs/decisions/*.md`:
+- **Persistence model** — e.g., "flat markdown with YAML frontmatter, no database", or "SQLite in `.jumpstart/state/`", or "PostgreSQL"
+- **Phase gate state storage** — where approval status is stored (frontmatter, `.jumpstart/state/state.json`, git tags, etc.)
+- **Artifact versioning mechanism** — how version tagging works (shell out to `git tag`, use `simple-git` library, GitHub API, etc.)
+- **Structured data storage** — if any structured data exists beyond flat files (task boards, dependency graphs, audit logs), name the storage engine or explicitly state "none — everything is flat files"
+- **State mutation rules** — which operations are append-only vs. mutable, which require atomicity
+
+If the architecture doc does not specify persistence, add `[NEEDS CLARIFICATION: Data layer not defined in architecture.md]` and halt.
+
+##### Section: Target Directory Structure
+
+Paste the exact target file tree from `specs/architecture.md` Directory Structure section. This is the spatial reference the agent uses to orient itself and validate file path consistency. Every file path in every task must exist within this tree.
+
+##### Section: Canonical Code Patterns
+
+Extract or generate reference patterns for every architectural mandate that affects how code should be structured. Sources: `specs/architecture.md` component design, ADRs, `.jumpstart/roadmap.md` articles.
+
+For each pattern, include:
+- **Pattern name** — e.g., "CLI I/O Contract", "Library-First Module", "Error Response Shape"
+- **Mandate source** — which spec article or ADR requires this pattern
+- **Reference implementation** — a short (10-30 line) code snippet showing the expected pattern. If `specs/architecture.md` includes code examples, use those verbatim. If not, derive from the architecture's technology choices and flag as `[DERIVED: pattern inferred from architecture.md §[section]]`.
+- **Anti-pattern** — a brief description of what NOT to do
+
+Example patterns to include when applicable:
+- **I/O contract** — how functions accept input (stdin JSON, function args, HTTP body) and emit output (stdout JSON, return value, HTTP response)
+- **Error response shape** — the standard error object structure (type, message, code, details)
+- **Module boundary** — how modules export their public API (named exports, barrel files, class instances)
+- **Test file structure** — how test files are named, organized, and structured (describe blocks, setup/teardown, naming convention)
+- **Configuration loading** — how environment variables and config files are read and validated
+
+##### Section: Dependency Graph (Task DAG)
+
+Build a Directed Acyclic Graph of all tasks. For each task:
+- **Task ID** and **Title** from the implementation plan
+- **`depends_on`** — explicit list of task IDs that must be `[COMPLETE]` before this task starts. Extract from the implementation plan's `Dependencies` field. If the implementation plan only implies dependencies through ordering, make them explicit here.
+- **Order** — `[S]` (sequential) or `[P]` (parallelizable)
+- **Milestone** — which milestone this task belongs to
+
+Validate the graph for:
+1. **No cycles** — if a cycle is detected, halt and report
+2. **No orphans** — every task must be reachable from at least one root task (task with no dependencies)
+3. **Cross-milestone dependencies** — flag any task that depends on a task in a later milestone (ordering error)
+
+##### Section: Implementation Checklist
+
+For each task, the checklist entry MUST include all of the following fields. Missing fields are a generation error — do not leave any blank.
+
+```markdown
+- [ ] **M1-T01: [Title]**
+  - **depends_on:** [list of task IDs, or "—" if none]
+  - **Component:** [from implementation plan]
+  - **Story:** [story ID] — [story title from PRD]
+  - **Files:** `[exact file paths to create/modify]`
+  - **Tech choices:** [specific libraries, frameworks, APIs this task uses — must all appear in Tech Manifest]
+  - **Acceptance criteria:**
+    - [AC verbatim from PRD for the referenced story — copy exactly, do not paraphrase]
+  - **Tests required:**
+    - [ ] [test description] → `tests/[exact-path]/[test-file].test.[ext]`
+    - [ ] [additional tests as needed]
+  - **Error handling:**
+    - **What can fail:** [enumerate: file not found, validation failure, auth denied, network timeout, etc.]
+    - **Expected behavior per error:** [for each error: exit code, HTTP status, error response shape, retry policy, rollback behavior]
+    - **Atomicity:** [is this operation atomic? Should partial failure roll back? Y/N with explanation]
+  - **Done when:**
+    - [ ] [verifiable criterion from implementation plan — must be testable by running a command or inspecting output]
+    - [ ] All tests pass
+    - [ ] No lint errors
+    - [ ] [error handling criteria: e.g., "exits 1 with JSON error on invalid input"]
+  - **Prior art:** [reference to an existing tool, library, or pattern that does something similar — gives the agent a mental model. E.g., "Similar to `terraform plan` which diffs desired vs. actual state", or "See how `express-validator` chains validation middleware". Use "N/A" only if genuinely no analogy exists.]
+  - **Status:** `[PENDING]`
+  - **Notes:** [blank — filled during implementation with deviations, insights]
+```
+
+**Critical rules for populating each field:**
+
+1. **Acceptance criteria** must be copied verbatim from `specs/prd.md`. Do not paraphrase, summarize, or reinterpret. If the PRD acceptance criterion is vague (e.g., "fast response"), flag it as `[NEEDS CLARIFICATION: AC is not measurable — "[original text]"]`.
+
+2. **Tech choices** must reference only technologies that appear in the Tech Manifest. If a task needs a library not in the manifest, halt and flag: `[NEEDS CLARIFICATION: Task [ID] requires [library] but it is not in the Tech Manifest]`.
+
+3. **Error handling** must enumerate every reasonably foreseeable failure mode. For each failure:
+   - What triggers it (invalid input, missing file, network error, auth failure, schema validation error, etc.)
+   - What the exit code or HTTP status should be
+   - What the error output format should be (stderr JSON `{ "error": "type", "message": "...", "code": N }`, human-readable message, both)
+   - Whether the operation should be atomic (roll back on failure) or partial (save what succeeded)
+
+4. **Prior art** provides a concrete mental model for the agent. Good prior art references:
+   - Similar CLI tools (e.g., "`eslint --fix` for auto-correcting lint errors")
+   - Similar library patterns (e.g., "`express` middleware chain pattern")
+   - Similar architectural concepts (e.g., "`terraform plan` for detecting drift between desired and actual state")
+   - If the task implements a standard pattern (CRUD, auth flow, pub/sub), name the pattern explicitly
+
+5. **Done when** criteria must be verifiable by running a command, inspecting output, or checking a file. Avoid subjective criteria like "code is clean" or "works correctly". Good: "Running `node bin/cli.js validate --spec specs/prd.md` exits 0". Bad: "Validation works properly".
+
+##### Section: Traceability Matrix
+
+Map every Must Have story from `specs/prd.md` to implementation tasks. Every Must Have story MUST have at least one task. If a story has no task:
+1. Flag it as a **coverage gap**: `❌ GAP — no implementation task for this story`
+2. Halt and report to the human before proceeding
+
+##### Section: NFR Constraint Checklist
+
+Map every NFR from `specs/prd.md` to tasks that address it. Each NFR must include:
+- The quantified target metric (e.g., `p95 < 200ms`, `OWASP Top 10 compliance`)
+- The specific task(s) that implement or verify it
+- How the NFR will be tested (load test, security scan, manual review, etc.)
+
+##### Section: Active ADR Constraints
+
+Extract from `specs/decisions/*.md`. For each ADR, state explicitly what the developer **must do** and **must not do** as a consequence of the decision.
+
+##### Section: Roadmap Articles in Effect
+
+List every active article from `.jumpstart/roadmap.md` with:
+- The article name and number
+- Whether it is enforced (`true`/`false` from config)
+- What specific constraint it imposes on implementation (concrete, not abstract)
+
+##### Section: Agent Permissions
+
+When `specs/architecture.md` defines agent-specific permissions or the implementation plan includes multi-agent workflows, include a permissions table:
+
+| Agent | Allowed Actions | Forbidden Actions |
+|-------|----------------|-------------------|
+| Developer | Read any file; create/edit files in `src/`, `tests/`, project root; run tests; run linter | Edit files in `.jumpstart/agents/`, `.jumpstart/templates/`; modify architecture; change API contracts |
+
+If the architecture doc does not define agent permissions, derive them from the Stay-in-Lane rule and the Developer's "What You Do NOT Do" section.
+
+##### Section: Progress Summary
+
+Running counts updated after every task completion.
+
+#### 2c. Validate Completeness
+
+Before presenting the TODO.md to the human, run these validation checks. All must pass or be flagged:
+
+1. **Story coverage:** Every Must Have story in the PRD has at least one task. If not, flag the gap.
+2. **Dependency acyclicity:** No circular dependencies exist in the task graph. If cycles are detected, halt and report.
+3. **File path consistency:** Every file referenced in tasks matches the target directory structure.
+4. **NFR traceability:** Every NFR has at least one task addressing it. Flag gaps.
+5. **Tech manifest completeness:** Every technology referenced in tasks appears in the Tech Manifest. No unnamed or unpinned libraries.
+6. **Error handling completeness:** Every task that creates a CLI command, API endpoint, or public function has an error handling section with at least one failure mode enumerated.
+7. **Done-when testability:** Every "Done when" criterion can be verified by running a command or inspecting a file. Flag any subjective criteria.
+8. **Data layer declared:** The Data Layer section is populated. If not, halt.
+9. **Pattern coverage:** Every architectural mandate from the roadmap that affects code structure has a canonical code pattern in the Canonical Code Patterns section.
+
+#### 2d. Present for Approval
+
+Present the TODO.md to the human:
+
+> "I have generated `TODO.md` with [N] tasks across [M] milestones, derived from the approved specs. It includes:
+> - Tech manifest with [N] pinned technology choices
+> - Data layer declaration: [one-line summary, e.g., "flat markdown with YAML frontmatter, no database"]
+> - Target directory structure with [N] directories
+> - [N] canonical code patterns for architectural mandates
+> - Dependency graph: [N] tasks, [N] dependencies, no cycles detected
+> - [N] tasks with acceptance criteria, test requirements, error handling, and done-when criteria
+> - Full traceability matrix ([N]/[N] stories covered)
+> - NFR constraint checklist ([N]/[N] NFRs mapped)
+> - [N] ADR constraints in effect
+> - [N] roadmap articles enforced
+> - [N] validation checks passed, [N] flagged issues requiring attention
+>
+> Flagged issues: [list any NEEDS CLARIFICATION items, coverage gaps, or validation failures]
+>
+> Please review and confirm I should begin implementation."
+
+Wait for the human's approval before proceeding. Resolve all flagged issues before starting code.
+
+#### 2e. Living Document Rules
+
+The TODO.md is a **living document** updated throughout Phase 4:
+
+- **After each task:** Mark the task checkbox `[x]`, update status to `[COMPLETE]`, fill in Notes with any deviations or insights, update the Progress Summary counts.
+- **After each milestone:** Mark milestone verification checkboxes, update milestones complete count.
+- **On deviation:** Add a note to the affected task explaining what changed and why. Include the original spec text and the actual implementation for audit trail.
+- **On new discovery:** If implementation reveals a gap not in the spec, add a `[DISCOVERED]` note to the relevant task and flag it to the human. Do NOT add new tasks to TODO.md without updating the spec first (Power Inversion).
+- **On error handling surprise:** If a failure mode occurs that was not enumerated in the task's error handling section, add it to the task Notes and to the insights file.
+- **At completion:** Update final Progress Summary with all counts.
+
+The `manage_todo_list` VS Code tool mirrors TODO.md progress for real-time visibility. Both must stay in sync.
+
+### Step 3: Project Scaffolding (If Needed)
 
 If the project does not yet have its structure, create it according to the Architecture Document:
 
@@ -208,15 +426,15 @@ If the project does not yet have its structure, create it according to the Archi
   - `top-level`: Only first-level child directories under `src/`
   - A number (e.g., `2`): Directories up to that depth from the source root
 
-If the project already exists, skip to Step 3.
+If the project already exists, skip to Step 4.
 
-### Step 3: Task Execution Loop
+### Step 4: Task Execution Loop
 
-For each task in the implementation plan, in order:
+For each task in the implementation plan (and tracked in `TODO.md`), in order:
 
-#### 3a. Read the Task
+#### 4a. Read the Task
 
-Read the full task definition:
+Read the task definition from `TODO.md` (which mirrors the implementation plan with added context):
 - Task ID and title
 - Component it belongs to
 - Story reference (look up the acceptance criteria in the PRD)
@@ -228,7 +446,7 @@ Read the full task definition:
 
 If a dependency is not yet complete, skip to the next non-blocked task or halt and report.
 
-#### 3b. Write the Code
+#### 4b. Write the Code
 
 Implement the task according to:
 - The task description in the implementation plan
@@ -248,11 +466,14 @@ Implement the task according to:
 
 **Capture insights as you work:** Document implementation discoveries as they happen—don't wait for task completion. Note when the architecture plan needed interpretation or adjustment. Record refactoring decisions (why you restructured code, what pattern you applied). Capture test failures that revealed design issues. Document workarounds for library limitations or unexpected behavior.
 
-**Track progress (if using manage_todo_list):** After completing each task, update the todo list to mark the task complete and update milestone progress counts. This keeps the human informed and provides clear context when resuming work.
+**Track progress:** After completing each task:
+1. Update `TODO.md`: mark the task checkbox `[x]`, set status to `[COMPLETE]`, add Notes for any deviations or insights, update the Progress Summary.
+2. Update `manage_todo_list` (VS Code) to mirror the TODO.md state.
+3. Both must stay in sync — TODO.md is the persistent record, manage_todo_list is the real-time view.
 
 **AGENTS.md maintenance (greenfield only):** After completing tasks that create new directories or significantly change a module's purpose, public API, or dependencies, update the corresponding `AGENTS.md` file. Keep the module purpose, exports, dependencies, and AI guidelines in sync with the actual implementation.
 
-#### 3c. Write Tests
+#### 4c. Write Tests
 
 For each task that has a "Tests Required" section:
 
@@ -288,7 +509,7 @@ For each task that has a "Tests Required" section:
 - Unit tests for business logic; integration tests for API endpoints and service interactions.
 - Name tests descriptively: `should_return_404_when_user_not_found` not `test1`.
 
-#### 3d. Run Tests
+#### 4d. Run Tests
 
 If `run_tests_after_each_task` is enabled in config:
 
@@ -303,9 +524,9 @@ If `run_tests_after_each_task` is enabled in config:
 
 **Capture insights as you work:** Document test findings—what tests revealed about the implementation, edge cases that weren't in acceptance criteria, or assumptions in the architecture that proved incorrect. Note patterns in test failures across tasks. Record testing strategies that worked particularly well for this codebase.
 
-#### 3e. Update the Implementation Plan
+#### 4e. Update Implementation Plan and TODO.md
 
-Mark the task as complete in `specs/implementation-plan.md`:
+Mark the task as complete in both `specs/implementation-plan.md` and `TODO.md`:
 
 ```markdown
 ### Task M1-T01: Create User database model and migration [COMPLETE]
@@ -319,7 +540,7 @@ If the task revealed issues or required deviations from the plan, add a note:
 > not explicitly listed in the task description.
 ```
 
-#### 3f. Commit (If Configured)
+#### 4f. Commit (If Configured)
 
 If `commit_after_each_task` is enabled in config:
 
@@ -330,7 +551,7 @@ git commit -m "jumpstart(M1-T01): Create User database model and migration"
 
 Use the `commit_message_prefix` from config and reference the task ID.
 
-### Step 4: Milestone Verification
+### Step 5: Milestone Verification
 
 After completing all tasks in a milestone:
 
@@ -350,7 +571,7 @@ If the human wants to review or test before proceeding, pause and wait for their
 - AI Agent Guidelines reflect patterns discovered during implementation
 - Key Files sections list the files that actually exist
 
-### Step 5: Final Documentation
+### Step 6: Final Documentation
 
 After all milestones are complete:
 
@@ -454,6 +675,7 @@ When implementing tasks that involve external libraries, frameworks, or APIs:
 ## Output
 
 Primary outputs:
+- `TODO.md` in the project root (spec-driven task checklist — generated in Step 2 using `.jumpstart/templates/todo.md`, updated throughout)
 - Application code in the configured `source_dir` (default: `src/`)
 - Test code in the configured `tests_dir` (default: `tests/`)
 - Updated `README.md`
@@ -477,9 +699,15 @@ Primary outputs:
 ## Phase Gate
 
 Phase 4 is complete when:
-- [ ] All tasks in the implementation plan are marked [COMPLETE]
+- [ ] TODO.md has been generated (using `.jumpstart/templates/todo.md`) and approved by the human
+- [ ] All `[NEEDS CLARIFICATION]` items in TODO.md have been resolved
+- [ ] All tasks in TODO.md and the implementation plan are marked [COMPLETE]
 - [ ] The full test suite passes
+- [ ] Traceability Matrix shows ✅ for every Must Have story
+- [ ] NFR Constraint Checklist shows ✅ for every NFR
+- [ ] Spec-drift check passes at final milestone
 - [ ] The README has been updated with setup and usage instructions
-- [ ] All deviations from the plan have been documented
+- [ ] All deviations from the plan have been documented with original spec text and actual implementation
+- [ ] TODO.md Progress Summary is fully updated with final counts
 - [ ] The human has reviewed the final output
 - [ ] Any recommendations for next steps have been communicated

package/.jumpstart/templates/todo.md

@@ -0,0 +1,358 @@
+# TODO — [Project Name]
+
+> **Generated by:** Developer Agent (Phase 4)
+> **Generated from:** specs/implementation-plan.md, specs/architecture.md, specs/prd.md, specs/decisions/*.md
+> **Date:** [ISO 8601 date]
+> **Status:** In Progress
+>
+> This file is the spec-driven task checklist for Phase 4 implementation.
+> Every item traces to an approved spec artifact. Do not add tasks that
+> lack spec traceability. If new work is discovered, update the spec first
+> (Power Inversion — Article IV).
+
+---
+
+## Tech Manifest
+
+> Extracted from `specs/architecture.md` — Technology Stack section.
+> These are the pinned choices. Do not deviate without flagging a Major Deviation.
+> Every row MUST have a pinned version. If a version is missing in architecture.md,
+> flag `[NEEDS CLARIFICATION: version not pinned for [choice]]` and halt.
+
+| Dimension | Choice | Version | Lockfile | Source |
+|-----------|--------|---------|----------|--------|
+| Runtime | [e.g., Node.js] | [e.g., >= 20.x] | — | architecture.md §Tech Stack |
+| Language | [e.g., TypeScript] | [e.g., 5.x] | — | architecture.md §Tech Stack |
+| Module System | [e.g., ESM] | — | — | architecture.md §Tech Stack |
+| Package Manager | [e.g., pnpm] | [e.g., 9.x] | [e.g., pnpm-lock.yaml] | architecture.md §Tech Stack |
+| Framework | [e.g., Express] | [e.g., 4.21.x] | — | architecture.md §Tech Stack |
+| Database | [e.g., PostgreSQL] | [e.g., 16.x] | — | architecture.md §Data Model |
+| ORM / Query Builder | [e.g., Drizzle] | [e.g., 0.34.x] | — | architecture.md §Data Model |
+| Schema Validation | [e.g., Zod] | [e.g., 3.x] | — | architecture.md §Tech Stack |
+| CLI Framework | [e.g., Commander] | [e.g., 12.x] | — | architecture.md §Tech Stack |
+| Test Runner | [e.g., Vitest] | [e.g., 2.x] | — | architecture.md §Tech Stack |
+| Assertion Library | [e.g., built-in Vitest] | — | — | architecture.md §Tech Stack |
+| Linter | [e.g., ESLint] | [e.g., 9.x] | — | architecture.md §Tech Stack |
+| Formatter | [e.g., Prettier] | [e.g., 3.x] | — | architecture.md §Tech Stack |
+| Git Hook Manager | [e.g., husky] | [e.g., 9.x] | — | architecture.md §Tech Stack |
+| Auth Library | [e.g., Passport.js] | [e.g., 0.7.x] | — | architecture.md §Tech Stack |
+
+> Add or remove rows as appropriate. Every technology referenced in any task below
+> MUST appear in this table. If a task uses a library not listed here, halt and flag.
+
+---
+
+## Data Layer
+
+> Explicitly declares where state and persistence live. Extracted from
+> `specs/architecture.md` and `specs/decisions/*.md`.
+> If architecture.md does not specify persistence, flag `[NEEDS CLARIFICATION]` and halt.
+
+| Concern | Declaration | Source |
+|---------|-------------|--------|
+| **Persistence model** | [e.g., "Flat markdown with YAML frontmatter, no database" or "SQLite in .jumpstart/state/" or "PostgreSQL"] | architecture.md §[section] |
+| **Phase gate state** | [e.g., "Stored in frontmatter `approved_by` and `approval_date` fields" or "`.jumpstart/state/state.json`"] | architecture.md §[section] |
+| **Artifact versioning** | [e.g., "Shell out to `git tag` via child_process" or "Use `simple-git` library" or "Manual"] | architecture.md §[section] / ADR-NNN |
+| **Structured data** | [e.g., "None — everything is flat files" or "Dependency graph in `.jumpstart/spec-graph.json`"] | architecture.md §[section] |
+| **State mutation rules** | [e.g., "Insights files and QA log are append-only. Config is mutable. Specs are immutable after approval."] | architecture.md §[section] / roadmap.md |
+
+---
+
+## Target Directory Structure
+
+> Extracted from `specs/architecture.md` — Directory Structure section.
+> Every file path in every task below must exist within this tree.
+> After implementation, the actual tree should match this exactly.
+
+```
+[paste the target file tree from architecture.md here]
+```
+
+---
+
+## Canonical Code Patterns
+
+> Reference implementations for every architectural mandate that affects code structure.
+> These remove ambiguity about how abstract principles translate to concrete code.
+> Agents MUST follow these patterns rather than inventing alternatives.
+
+### Pattern: [e.g., CLI I/O Contract]
+
+**Mandate source:** [e.g., Roadmap Article II — CLI-First Mandate]
+**Applies to:** [e.g., All CLI commands in `bin/lib/`]
+
+```javascript
+// Expected pattern — reference implementation
+// [paste or derive 10-30 line code example]
+```
+
+**Anti-pattern:** [e.g., "Do NOT read from argv positional params for structured data. Always accept JSON via stdin or `--input` flag."]
+
+---
+
+### Pattern: [e.g., Error Response Shape]
+
+**Mandate source:** [e.g., architecture.md §Error Handling / ADR-003]
+**Applies to:** [e.g., All CLI commands and API endpoints]
+
+```javascript
+// Standard error output format
+const error = {
+  error: "VALIDATION_FAILED",     // Machine-readable error type (SCREAMING_SNAKE)
+  message: "Schema validation failed for specs/prd.md",  // Human-readable message
+  code: 1,                        // Exit code (CLI) or HTTP status (API)
+  details: {                      // Optional structured details
+    file: "specs/prd.md",
+    violations: [{ path: "$.title", message: "required field missing" }]
+  }
+};
+process.stderr.write(JSON.stringify(error, null, 2) + '\n');
+process.exit(error.code);
+```
+
+**Anti-pattern:** [e.g., "Do NOT write unstructured strings to stderr. Always use the JSON error shape above."]
+
+---
+
+### Pattern: [e.g., Library-First Module Boundary]
+
+**Mandate source:** [e.g., Roadmap Article I — Library-First]
+**Applies to:** [e.g., All new modules in `bin/lib/`]
+
+```javascript
+// Expected pattern — standalone module with pure function exports
+// No side effects at import time. No implicit global state.
+
+/**
+ * Validates a spec artifact against its JSON schema.
+ * @param {string} specPath - Path to the spec file
+ * @param {string} schemaPath - Path to the JSON schema
+ * @returns {{ valid: boolean, errors: Array<{ path: string, message: string }> }}
+ */
+export function validateSpec(specPath, schemaPath) {
+  // ...implementation
+}
+```
+
+**Anti-pattern:** [e.g., "Do NOT create classes with constructor side effects. Do NOT read from filesystem at import time."]
+
+---
+
+### Pattern: [e.g., Test File Structure]
+
+**Mandate source:** [e.g., architecture.md §Testing / Roadmap Article III]
+**Applies to:** [e.g., All test files in `tests/`]
+
+```javascript
+// Expected test file naming: tests/[module-name].test.js
+// Expected structure:
+import { describe, it, expect, beforeEach } from 'vitest'; // or test runner of choice
+import { validateSpec } from '../bin/lib/validator.js';
+
+describe('validateSpec', () => {
+  describe('when spec matches schema', () => {
+    it('should return valid: true with empty errors array', () => {
+      const result = validateSpec('fixtures/valid/prd.md', 'schemas/prd.schema.json');
+      expect(result.valid).toBe(true);
+      expect(result.errors).toHaveLength(0);
+    });
+  });
+
+  describe('when spec violates schema', () => {
+    it('should return valid: false with descriptive errors', () => {
+      const result = validateSpec('fixtures/invalid/prd.md', 'schemas/prd.schema.json');
+      expect(result.valid).toBe(false);
+      expect(result.errors[0]).toHaveProperty('path');
+      expect(result.errors[0]).toHaveProperty('message');
+    });
+  });
+});
+```
+
+**Anti-pattern:** [e.g., "Do NOT name tests `test1`, `test2`. Use descriptive `should_...` or sentence-style names."]
+
+---
+
+<!-- Add more patterns as needed. Common ones to include:
+- Configuration loading pattern
+- Database query pattern (if applicable)
+- API route handler pattern (if applicable)
+- Authentication middleware pattern (if applicable)
+- Logging pattern
+-->
+
+---
+
+## Dependency Graph (Task DAG)
+
+> Tasks listed in execution order. `depends_on` declares which tasks must be
+> `[COMPLETE]` before this task can start. This graph has been validated for:
+> - ✅ No circular dependencies
+> - ✅ No orphan tasks (every task reachable from a root)
+> - ✅ No cross-milestone backward dependencies
+
+| Task ID | Title | Milestone | Depends On | Order |
+|---------|-------|-----------|------------|-------|
+| M1-T01 | [Title] | M1 | — | [S] |
+| M1-T02 | [Title] | M1 | M1-T01 | [S] |
+| M1-T03 | [Title] | M1 | M1-T01 | [P] |
+| M2-T01 | [Title] | M2 | M1-T02, M1-T03 | [S] |
+| ... | | | | |
+
+---
+
+## Implementation Checklist
+
+### Milestone 1: [Name]
+
+**Goal:** [from implementation-plan.md]
+**PRD Stories:** [story IDs]
+**Depends On:** None
+
+- [ ] **M1-T01: [Title]**
+  - **depends_on:** —
+  - **Component:** [from implementation plan]
+  - **Story:** [story ID] — [story title from PRD]
+  - **Files:** `[exact file paths to create/modify]`
+  - **Tech choices:** [specific libraries, frameworks, APIs this task uses — must all appear in Tech Manifest]
+  - **Acceptance criteria:**
+    - [AC verbatim from PRD — copy exactly, do not paraphrase]
+    - [Additional AC if multiple]
+  - **Tests required:**
+    - [ ] [test description] → `tests/[exact-path]/[test-file].test.[ext]`
+    - [ ] [additional test] → `tests/[exact-path]/[test-file].test.[ext]`
+  - **Error handling:**
+    - **What can fail:** [enumerate: file not found, validation failure, auth denied, network timeout, etc.]
+    - **Expected behavior per error:**
+      - [Error 1]: [exit code / HTTP status] + [error output format: stderr JSON, human message, both]
+      - [Error 2]: [exit code / HTTP status] + [error output format]
+    - **Atomicity:** [Is this operation atomic? Should partial failure roll back? Y/N + explanation]
+  - **Done when:**
+    - [ ] [verifiable criterion — must be testable by running a command or inspecting output]
+    - [ ] [e.g., "Running `node bin/cli.js validate --spec specs/prd.md` exits 0"]
+    - [ ] All tests pass
+    - [ ] No lint errors
+  - **Prior art:** [reference to existing tool/pattern, e.g., "Similar to `terraform plan` for diffing desired vs. actual state" or "Follows `express-validator` middleware chain pattern". Use "N/A" only if genuinely no analogy exists.]
+  - **Status:** `[PENDING]`
+  - **Notes:** [blank — filled during implementation]
+
+- [ ] **M1-T02: [Title]**
+  - **depends_on:** M1-T01
+  - **Component:** [from implementation plan]
+  [repeat full structure — no fields may be omitted]
+
+#### Milestone 1 Verification
+- [ ] All M1 tasks marked [COMPLETE]
+- [ ] Full test suite passes
+- [ ] Milestone goal verified: [restate goal]
+- [ ] Spec-drift check passes (`bin/lib/spec-drift.js` exits 0)
+
+**Milestone completed on:** [DATE or pending]
+
+---
+
+### Milestone 2: [Name]
+
+**Goal:** [from implementation-plan.md]
+**PRD Stories:** [story IDs]
+**Depends On:** Milestone 1
+
+[repeat full structure]
+
+#### Milestone 2 Verification
+[repeat verification structure]
+
+---
+
+<!-- Repeat milestone blocks as needed -->
+
+---
+
+## Traceability Matrix
+
+> Every Must Have story from the PRD must map to at least one task.
+> If a story has no task, flag as ❌ GAP, halt, and report to the human.
+
+| PRD Story | Story Title | Priority | Acceptance Criteria Count | Tasks | Covered |
+|-----------|-------------|----------|--------------------------|-------|---------|
+| E1-S1 | [Title] | Must Have | [N] | M1-T01, M1-T02 | ✅ |
+| E1-S2 | [Title] | Must Have | [N] | M1-T03 | ✅ |
+| E2-S1 | [Title] | Should Have | [N] | M2-T01 | ✅ |
+| E3-S1 | [Title] | Must Have | [N] | — | ❌ GAP |
+
+> **Gaps detected:** [N]. Must be resolved before implementation begins.
+
+---
+
+## NFR Constraint Checklist
+
+> Extracted from `specs/prd.md` — Non-Functional Requirements section.
+> Each NFR must trace to at least one task that addresses it.
+> Each NFR must have a quantified target and a testing approach.
+
+| NFR ID | Category | Requirement | Target Metric | Task(s) | Testing Approach | Addressed |
+|--------|----------|-------------|---------------|---------|-----------------|-----------|
+| NFR-01 | Performance | [description] | [e.g., p95 < 200ms] | [task IDs] | [e.g., load test with k6] | ✅ / ❌ |
+| NFR-02 | Security | [description] | [e.g., OWASP Top 10] | [task IDs] | [e.g., SAST scan + manual review] | ✅ / ❌ |
+| NFR-03 | Availability | [description] | [e.g., 99.9% uptime] | [task IDs] | [e.g., chaos testing] | ✅ / ❌ |
+
+---
+
+## Active ADR Constraints
+
+> Extracted from `specs/decisions/*.md`. These constrain implementation choices.
+> For each ADR, state explicitly what the developer MUST do and MUST NOT do.
+
+| ADR | Decision | Developer MUST | Developer MUST NOT |
+|-----|----------|----------------|-------------------|
+| ADR-001 | [title] | [what to do because of this decision] | [what is forbidden because of this decision] |
+| ADR-002 | [title] | [required action] | [forbidden action] |
+
+---
+
+## Roadmap Articles in Effect
+
+> From `.jumpstart/roadmap.md`. Non-negotiable during implementation.
+> Each article lists its enforcement status and concrete constraint on code.
+
+| Article | Name | Enforced | Concrete Constraint |
+|---------|------|----------|-------------------|
+| I | Sequential Phase Integrity | Always | Do not skip or reorder phases |
+| II | Template Compliance | Always | Use `.jumpstart/templates/` for all output artifacts |
+| III | Test-First Development | `[true/false]` from config | [If true: write tests first, get Red Phase approval. If false: write tests before or alongside.] |
+| IV | Upstream Traceability | Always | Every task traces to a PRD story. No orphan code. |
+| V | Human Gate Authority | Always | Do not self-approve. Always ask human. |
+
+---
+
+## Agent Permissions
+
+> Derived from architecture.md agent definitions and the Stay-in-Lane rule.
+> If architecture.md defines explicit permissions, use those verbatim.
+
+| Action Category | Allowed | Forbidden |
+|----------------|---------|-----------|
+| **File Read** | Any file in the repository | — |
+| **File Create/Edit** | `src/`, `tests/`, `TODO.md`, `README.md`, project config files | `.jumpstart/agents/*.md`, `.jumpstart/templates/*.md`, `.jumpstart/roadmap.md` |
+| **Run Commands** | Test runner, linter, formatter, build tool, `bin/cli.js` | `git push`, deployment commands, production database commands |
+| **Architecture** | Follow architecture.md as-is | Change tech stack, add components, alter API contracts, change data model |
+| **Dependencies** | Install dependencies listed in architecture.md | Add new dependencies not in architecture.md without flagging |
+| **Specs** | Read all specs; update `specs/implementation-plan.md` task status | Modify PRD, architecture, or challenger brief content |
+
+---
+
+## Progress Summary
+
+| Metric | Value |
+|--------|-------|
+| Total Milestones | [N] |
+| Milestones Complete | 0 |
+| Total Tasks | [N] |
+| Tasks Complete | 0 |
+| Tasks In Progress | 0 |
+| Tasks Blocked | 0 |
+| Tests Written | 0 |
+| Tests Passing | 0 |
+| Deviations Logged | 0 |
+| NEEDS CLARIFICATION Items | [N] |
+| Last Updated | [ISO date] |

package/README.md

@@ -11,8 +11,9 @@ Every artifact lives in your repository, version-controlled, diffable, and trans
 ---
 
 ## Table of Contents
-- [How It Works](#how-it-works)
 - [Quick Start](#quick-start)
+- [Onboarding Guide](ONBOARDING.md) 📘
+- [How It Works](#how-it-works)
 - [Commands](#commands)
 - [Advisory Agents](#advisory-agents)
 - [CLI Tools](#cli-tools)
@@ -71,6 +72,8 @@ flowchart TB
 
 ## Quick Start
 
+> **👋 First time here?** Check out the **[Onboarding Guide](ONBOARDING.md)** for a complete walkthrough including configuration details, agent orchestration, and best practices.
+
 ### 1. Install
 
 **Interactive Mode** (recommended):

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "jumpstart-mode",
-  "version": "1.1.0",
+  "version": "1.1.2",
   "description": "Spec-driven agentic coding framework that transforms ideas into production code through AI-powered sequential phases",
   "keywords": [
     "jumpstart",