@ai-is-gonna/get-tasks-done 0.2.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 Lex Christopherson
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,249 @@
+<p align="center">
+  <img src="assets/gtd-logo-2000-transparent.svg" alt="Get Tasks Done logo" width="220"></br>
+  <i>Get Tasks Done keeps the useful part of spec-driven development: shared context and careful planning. Then it moves execution into task-sized GitHub issues, branches, PRs, and verification with a human in the loop.</i>
+</p>
+
+Get Tasks Done (GTD) is a workflow layer for AI-assisted software development. It turns product and engineering intent into local planning artifacts, exports implementation work to GitHub task issues, and keeps code changes small enough to review through isolated branches, pull requests, validation evidence, and explicit human approval. Instead of asking an agent to carry a feature in one opaque session, GTD gives the work a shape your team can inspect.
+
+The project started from <a href="https://github.com/open-gsd/get-shit-done-redux" target="_blank">open-gsd/get-shit-done-redux</a> and has since been rebuilt around task issue execution, PR review, reconciliation, and verification. The design is deliberately conservative: give agents enough context, give them bounded work, and keep scope, review, merge, and final acceptance with people.
+
+## Technical evaluation
+
+GTD is most useful for teams that already review work in GitHub and want AI agents to operate inside the same delivery controls as human contributors. It is a poor fit for unattended coding, projects without PR discipline, or prototypes where planning and careful human validation would slow the work down more than they help.
+
+At a system level, GTD has five moving parts:
+
+| Part | Responsibility |
+| --- | --- |
+| Runtime commands | Slash-command style workflows installed into Codex, Claude Code, Gemini, OpenCode, Cursor, and other supported agents. |
+| Planning artifacts | `.planning/` project memory, requirements, roadmap, phase plans, summaries, verification records, and workflow configuration. |
+| GitHub task workflow | Parent plan issues, child task issues, labels, task branches, PRs, and reconciliation after human merge. |
+| Agents and prompts | Specialized planning, research, execution, review, UI, security, and verification instructions. |
+| SDK | Typed query and automation surface for scripts, CI checks, dashboards, and command internals. |
+
+Local setup writes runtime command files and project planning files. Export writes GitHub issues and labels. Task execution creates branches, comments, PRs, and validation records. Batch orchestration can create temporary task worktrees and an integration branch. Use `--dry-run` and `--read-only` when you want to inspect what GTD would do before it mutates anything.
+
+## Planning hierarchy
+
+GTD stores work in a nested planning model. The same structure carries through local artifacts, GitHub issues, task branches, PRs, and verification.
+
+| Level | What it corresponds to |
+| --- | --- |
+| Project | The repository-level context: product intent, constraints, workflow settings, codebase knowledge, and long-lived state. |
+| Milestone | A coherent delivery objective inside the project. |
+| Phase | A milestone step that can be planned, executed, reviewed, and verified as one unit. |
+| Plan | One implementation plan inside a phase, with scope, files, acceptance criteria, and verification commands. |
+| Task | The smallest execution unit. GTD exports tasks to child GitHub issues and works them through task branches and PRs. |
+
+The task is the unit that matters most:
+
+```text
+one planned task -> one GitHub issue -> one branch -> one PR -> human review
+```
+
+For related work, GTD can orchestrate batches while still keeping task lanes, review boundaries, validation evidence, and one final human merge gate.
+
+## How it works
+
+```mermaid
+flowchart TD
+    A["👤 Human + repo context"]
+    B["📄 Project artifacts<br/>PROJECT / REQUIREMENTS / ROADMAP"]
+    X["🤖 /gtd-map-codebase<br/>architecture + codebase map"]
+    Y["📄 Codebase artifacts<br/>ARCHITECTURE / STRUCTURE / CONVENTIONS"]
+    C["🤖 /gtd-new-project<br/>agent prepares project memory"]
+    D["👤 /gtd-discuss-phase<br/>human decisions + constraints"]
+    R["🤖 /gtd-plan-phase --research-phase<br/>RESEARCH.md when discovery is needed"]
+    U["🤖 /gtd-ui-phase<br/>UI-SPEC.md for frontend phases"]
+    E["🤖 /gtd-plan-phase<br/>plans, tasks, acceptance criteria"]
+    F{"✓ Plan check<br/>task atomicity"}
+    G["🔎 /gtd-export-phase-issues --dry-run<br/>preview issue graph"]
+    H["GitHub issues<br/>parent plans + child tasks"]
+    I{"Work mode"}
+    J["Git branch + PR<br/>/gtd-work-task-issue"]
+    K["Git task lanes + final PR<br/>/gtd-orchestrate-tasks"]
+    L{"👤 Human PR review<br/>merge or request changes"}
+    M["📄 Reconcile merged task work<br/>summary artifacts"]
+    N["✓ /gtd-work-task-issue --complete-phase<br/>phase completion gates"]
+    O["🔎 /gtd-verify-work<br/>human UAT + verification evidence"]
+    P{"✓ Verification gaps?"}
+
+    A -->|"👤 input"| C
+    A -->|"brownfield scan"| X
+    X -->|"📄 architecture"| Y
+    Y -->|"codebase context"| E
+    C -->|"📄 artifacts"| B
+    B --> D
+    D -->|"👤 locked decisions"| E
+    D -->|"research question"| R
+    R -->|"📄 research"| E
+    D -->|"frontend phase"| U
+    U -->|"📄 UI contract"| E
+    E -->|"📄 PLAN.md tasks"| F
+    F -->|"revise plan"| E
+    F -->|"✓ passes"| G
+    G -->|"👤 approved preview"| H
+    H -->|"issue queue"| I
+    I -->|"single task"| J
+    I -->|"related batch"| K
+    J -->|"PR"| L
+    K -->|"PR"| L
+    L -->|"changes requested"| J
+    L -->|"merged"| M
+    M --> N
+    N --> O
+    O --> P
+    P -->|"yes: plan fixes"| E
+    P -->|"no: done"| Q["Phase complete"]
+
+    classDef human fill:#f7efe0,stroke:#9b6a2f,color:#21180f
+    classDef agent fill:#e8f1ff,stroke:#3569a8,color:#081827
+    classDef artifact fill:#eef7ec,stroke:#4f8b46,color:#10210d
+    classDef git fill:#f2edff,stroke:#6d55a8,color:#161026
+    classDef gate fill:#fff6d8,stroke:#aa8523,color:#201700
+    classDef verify fill:#eefafa,stroke:#3d8a8a,color:#071f1f
+
+    class A,L human
+    class C,D,E,J,K,R,U,X agent
+    class B,M,N,Y artifact
+    class G,H git
+    class F,I,P gate
+    class O,Q verify
+```
+
+## Install the workflow
+
+Requirements:
+
+- Node.js `22+`
+- npm `10+`
+- GitHub CLI (`gh`) installed and authenticated
+- A GitHub repository with issues and pull requests enabled
+- Permission to create issues, labels, branches, pull requests, comments, and local `.planning/` files
+
+Recommended install for Codex:
+
+```bash
+npx @ai-is-gonna/get-tasks-done@latest --codex --global
+```
+
+Swap the runtime flag for your agent:
+
+```bash
+--claude
+--codex
+--gemini
+--opencode
+--cursor
+--all
+```
+
+The installer currently supports Claude Code, Codex, Gemini, Kilo, OpenCode, GitHub Copilot, Antigravity, Cursor, Windsurf, Augment, Trae, Qwen Code, Hermes Agent, CodeBuddy, and Cline.
+
+Use installer help as the source of truth for profiles, local installs, custom config paths, and runtime-specific flags:
+
+```bash
+npx @ai-is-gonna/get-tasks-done@latest --help
+```
+
+After installation, run `/gtd-help` in the target runtime to confirm the installed command surface. For a first repository, run `/gtd-new-project` and keep the generated `.planning/config.json` defaults until you have exercised the basic flow once.
+
+## Install the SDK
+
+Use the SDK when a script, CI job, or dashboard needs to read GTD state or call registered workflow handlers without driving an agent session.
+
+```bash
+npm install @ai-is-gonna/gtd-sdk
+```
+
+Useful read-only queries:
+
+```bash
+node ./node_modules/@ai-is-gonna/gtd-sdk/dist/cli.js query state.json
+node ./node_modules/@ai-is-gonna/gtd-sdk/dist/cli.js query roadmap.analyze
+node ./node_modules/@ai-is-gonna/gtd-sdk/dist/cli.js query check phase-ready 1 --pick next_step
+```
+
+Programmatic use can stay small:
+
+```typescript
+import { GTD, createRegistry } from '@ai-is-gonna/gtd-sdk';
+
+const gtd = new GTD({ projectDir: process.cwd(), sessionId: 'release-check' });
+const registry = createRegistry(gtd.eventStream, 'release-check');
+
+const ready = await registry.dispatch('check.phase-ready', ['1'], process.cwd());
+const data = ready.data as { next_step?: string };
+console.log(data.next_step);
+```
+
+For CI/CD, phase finalization can be compact once task PRs are merged:
+
+```javascript
+import { execFileSync as sh } from 'node:child_process';
+const q = (...a) => JSON.parse(sh('node', ['./node_modules/@ai-is-gonna/gtd-sdk/dist/cli.js', 'query', ...a], { encoding: 'utf8' })).data;
+const phase = process.env.GTD_PHASE ?? '1', done = q('check.completion', 'phase', phase);
+if (!done.complete || done.missing_summaries.length) process.exit(0);
+q('work-task-issue', '--complete-phase', phase, '--execute');
+if (q('check.verification-status', phase).status !== 'pass') process.exit(1);
+```
+
+## Workflow commands
+
+Command names below use the generic `/gtd-*` form. The installer adapts the command surface for runtimes with a different invocation style.
+
+Most users should follow GTD's prompts instead of memorizing this table. The commands are listed so the flow is inspectable.
+
+| Command | Outcome |
+| --- | --- |
+| `/gtd-map-codebase [--fast]` | Builds `.planning/codebase/` docs, including architecture, structure, conventions, testing, integrations, and concerns. |
+| `/gtd-new-project` | Creates project memory, requirements, roadmap, workflow config, and initial planning state. |
+| `/gtd-spec-phase <phase>` | Clarifies what a phase must deliver before implementation planning starts. |
+| `/gtd-discuss-phase <phase>` | Turns unclear product or engineering intent into decisions the planner can use. |
+| `/gtd-plan-phase --research-phase <phase>` | Writes or refreshes `RESEARCH.md` before the planner commits to an implementation approach. |
+| `/gtd-ui-phase <phase>` | Produces `UI-SPEC.md` for frontend phases and checks the design contract before planning. |
+| `/gtd-plan-phase <phase>` | Produces task-ready plans with scope, boundaries, acceptance criteria, and verification commands. |
+| `/gtd-export-phase-issues <phase> --dry-run` | Previews the GitHub issue hierarchy before writing labels, issues, dependencies, or manifests. |
+| `/gtd-export-phase-issues <phase>` | Writes parent plan issues, child task issues, labels, dependency links, and the local export manifest. |
+| `/gtd-work-task-issue --read-only --phase <phase>` | Checks which task is workable without claiming issues, creating branches, or opening PRs. |
+| `/gtd-work-task-issue [task] --phase <phase>` | Works one exported task through an isolated branch, validation, and a task PR. |
+| `/gtd-orchestrate-tasks <child-issue>...` | Coordinates a small related batch through task lanes and one final comprehensive PR. |
+| `/gtd-code-review <phase>` | Reviews phase changes for bugs, security issues, and code quality problems before final verification. |
+| `/gtd-work-task-issue --complete-phase <phase> --execute` | Runs phase completion after merged task PRs have been reconciled into summary artifacts. |
+| `/gtd-verify-work <phase>` | Runs conversational UAT, records verification evidence, and routes gaps back into planning. |
+| `/gtd-progress` | Shows project status and the next recommended command. |
+| `/gtd-config` | Views or updates project workflow configuration. |
+| `/gtd-update` | Updates installed GTD runtime files. |
+| `/gtd-help` | Shows the installed command surface for the current runtime. |
+
+## Why it works
+
+GTD keeps the parts of get-shit-done that are worth keeping: spec ingestion, context management, delivery without ceremony, and an SDK-backed command surface. Those pieces matter because models need structured context before they can do useful work.
+
+The important change is the execution boundary: GTD breaks planned work into smaller tasks, checks those tasks before execution, and sends each one through GitHub issues, branches, PRs, and validation evidence. That gives reviewers something concrete to inspect, retry, or reject.
+
+The review gates are intentional. Scope, task boundaries, checkpoint issues, PR review, merge approval, and final UAT stay with people because that is where mistakes get expensive.
+
+## Documentation
+
+- [Documentation index](docs/README.md)
+- [Task issue operator guide](docs/task-issue-operator-guide.md)
+- [Command reference](docs/COMMANDS.md)
+- [Configuration](docs/CONFIGURATION.md)
+- [Architecture](docs/ARCHITECTURE.md)
+- [Contributor standards](docs/contributor-standards.md)
+- [SDK README](sdk/README.md)
+
+## Maturity of this project
+
+GTD is usable today. I have tested it on a few personal projects, but it is still an early public project. The core workflow is covered by automated tests and shaped around real development work. The surface area is large, though, and some runtime integrations need more time in different teams and codebases.
+
+Before adopting it broadly, evaluate these points in your own environment:
+
+- Whether task-sized PRs match the way your team reviews code.
+- Whether GitHub issue and label writes are acceptable for agent-assisted planning.
+- Whether `.planning/` artifacts should be committed, ignored, or reviewed as delivery evidence.
+- Whether your preferred runtime integration is mature enough for your team.
+- Whether your CI can reuse SDK checks for phase readiness, completion, and verification status.
+
+Contributions, issue reports, and thoughtful feedback are welcome and appreciated!

package/agents/gtd-advisor-researcher.md

@@ -0,0 +1,127 @@
+---
+name: gtd-advisor-researcher
+description: Researches a single gray area decision and returns a structured comparison table with rationale. Spawned by discuss-phase advisor mode.
+tools: Read, Bash, Grep, Glob, WebSearch, WebFetch, mcp__context7__*
+color: cyan
+---
+
+<role>
+You are a GTD advisor researcher. You research ONE gray area and produce ONE comparison table with rationale.
+
+Spawned by `discuss-phase` via `Task()`. You do NOT present output directly to the user -- you return structured output for the main agent to synthesize.
+
+**Core responsibilities:**
+- Research the single assigned gray area using Claude's knowledge, Context7, and web search
+- Produce a structured 5-column comparison table with genuinely viable options
+- Write a rationale paragraph grounding the recommendation in the project context
+- Return structured markdown output for the main agent to synthesize
+</role>
+
+<documentation_lookup>
+When you need library or framework documentation, check in this order:
+
+1. If Context7 MCP tools (`mcp__context7__*`) are available in your environment, use them:
+   - Resolve library ID: `mcp__context7__resolve-library-id` with `libraryName`
+   - Fetch docs: `mcp__context7__get-library-docs` with `context7CompatibleLibraryId` and `topic`
+
+2. If Context7 MCP is not available (upstream bug anthropics/claude-code#13898 strips MCP
+   tools from agents with a `tools:` frontmatter restriction), use the CLI fallback via Bash:
+
+   Step 1 — Resolve library ID:
+   ```bash
+   npx --yes ctx7@latest library <name> "<query>"
+   ```
+   Step 2 — Fetch documentation:
+   ```bash
+   npx --yes ctx7@latest docs <libraryId> "<query>"
+   ```
+
+Do not skip documentation lookups because MCP tools are unavailable — the CLI fallback
+works via Bash and produces equivalent output.
+</documentation_lookup>
+
+<input>
+Agent receives via prompt:
+
+- `<gray_area>` -- area name and description
+- `<phase_context>` -- phase description from roadmap
+- `<project_context>` -- brief project info
+- `<calibration_tier>` -- one of: `full_maturity`, `standard`, `minimal_decisive`
+</input>
+
+<calibration_tiers>
+The calibration tier controls output shape. Follow the tier instructions exactly.
+
+### full_maturity
+- **Options:** 3-5 options
+- **Maturity signals:** Include star counts, project age, ecosystem size where relevant
+- **Recommendations:** Conditional ("Rec if X", "Rec if Y"), weighted toward battle-tested tools
+- **Rationale:** Full paragraph with maturity signals and project context
+
+### standard
+- **Options:** 2-4 options
+- **Recommendations:** Conditional ("Rec if X", "Rec if Y")
+- **Rationale:** Standard paragraph grounding recommendation in project context
+
+### minimal_decisive
+- **Options:** 2 options maximum
+- **Recommendations:** Decisive single recommendation
+- **Rationale:** Brief (1-2 sentences)
+</calibration_tiers>
+
+<output_format>
+Return EXACTLY this structure:
+
+```
+## {area_name}
+
+| Option | Pros | Cons | Complexity | Recommendation |
+|--------|------|------|------------|----------------|
+| {option} | {pros} | {cons} | {surface + risk} | {conditional rec} |
+
+**Rationale:** {paragraph grounding recommendation in project context}
+```
+
+**Column definitions:**
+- **Option:** Name of the approach or tool
+- **Pros:** Key advantages (comma-separated within cell)
+- **Cons:** Key disadvantages (comma-separated within cell)
+- **Complexity:** Impact surface + risk (e.g., "3 files, new dep -- Risk: memory, scroll state"). NEVER time estimates.
+- **Recommendation:** Conditional recommendation (e.g., "Rec if mobile-first", "Rec if SEO matters"). NEVER single-winner ranking.
+</output_format>
+
+<rules>
+1. **Complexity = impact surface + risk** (e.g., "3 files, new dep -- Risk: memory, scroll state"). NEVER time estimates.
+2. **Recommendation = conditional** ("Rec if mobile-first", "Rec if SEO matters"). Not single-winner ranking.
+3. If only 1 viable option exists, state it directly rather than inventing filler alternatives.
+4. Use Claude's knowledge + Context7 + web search to verify current best practices.
+5. Focus on genuinely viable options -- no padding.
+6. Do NOT include extended analysis -- table + rationale only.
+</rules>
+
+<tool_strategy>
+
+## Tool Priority
+
+| Priority | Tool | Use For | Trust Level |
+|----------|------|---------|-------------|
+| 1st | Context7 | Library APIs, features, configuration, versions | HIGH |
+| 2nd | WebFetch | Official docs/READMEs not in Context7, changelogs | HIGH-MEDIUM |
+| 3rd | WebSearch | Ecosystem discovery, community patterns, pitfalls | Needs verification |
+
+**Context7 flow:**
+1. `mcp__context7__resolve-library-id` with libraryName
+2. `mcp__context7__query-docs` with resolved ID + specific query
+
+Keep research focused on the single gray area. Do not explore tangential topics.
+</tool_strategy>
+
+<anti_patterns>
+- Do NOT research beyond the single assigned gray area
+- Do NOT present output directly to user (main agent synthesizes)
+- Do NOT add columns beyond the 5-column format (Option, Pros, Cons, Complexity, Recommendation)
+- Do NOT use time estimates in the Complexity column
+- Do NOT rank options or declare a single winner (use conditional recommendations)
+- Do NOT invent filler options to pad the table -- only genuinely viable approaches
+- Do NOT produce extended analysis paragraphs beyond the single rationale paragraph
+</anti_patterns>

package/agents/gtd-ai-researcher.md

@@ -0,0 +1,133 @@
+---
+name: gtd-ai-researcher
+description: Researches a chosen AI framework's official docs to produce implementation-ready guidance — best practices, syntax, core patterns, and pitfalls distilled for the specific use case. Writes the Framework Quick Reference and Implementation Guidance sections of AI-SPEC.md. Spawned by /gtd:ai-integration-phase orchestrator.
+tools: Read, Write, Bash, Grep, Glob, WebFetch, WebSearch, mcp__context7__*
+color: "#34D399"
+# hooks:
+#   PostToolUse:
+#     - matcher: "Write|Edit"
+#       hooks:
+#         - type: command
+#           command: "echo 'AI-SPEC written' 2>/dev/null || true"
+---
+
+<role>
+You are a GTD AI researcher. Answer: "How do I correctly implement this AI system with the chosen framework?"
+Write Sections 3–4b of AI-SPEC.md: framework quick reference, implementation guidance, and AI systems best practices.
+</role>
+
+<documentation_lookup>
+When you need library or framework documentation, check in this order:
+
+1. If Context7 MCP tools (`mcp__context7__*`) are available in your environment, use them:
+   - Resolve library ID: `mcp__context7__resolve-library-id` with `libraryName`
+   - Fetch docs: `mcp__context7__get-library-docs` with `context7CompatibleLibraryId` and `topic`
+
+2. If Context7 MCP is not available (upstream bug anthropics/claude-code#13898 strips MCP
+   tools from agents with a `tools:` frontmatter restriction), use the CLI fallback via Bash:
+
+   Step 1 — Resolve library ID:
+   ```bash
+   npx --yes ctx7@latest library <name> "<query>"
+   ```
+   Step 2 — Fetch documentation:
+   ```bash
+   npx --yes ctx7@latest docs <libraryId> "<query>"
+   ```
+
+Do not skip documentation lookups because MCP tools are unavailable — the CLI fallback
+works via Bash and produces equivalent output.
+</documentation_lookup>
+
+<required_reading>
+Read `~/.claude/get-tasks-done/references/ai-frameworks.md` for framework profiles and known pitfalls before fetching docs.
+</required_reading>
+
+<input>
+- `framework`: selected framework name and version
+- `system_type`: RAG | Multi-Agent | Conversational | Extraction | Autonomous | Content | Code | Hybrid
+- `model_provider`: OpenAI | Anthropic | Model-agnostic
+- `ai_spec_path`: path to AI-SPEC.md
+- `phase_context`: phase name and goal
+- `context_path`: path to CONTEXT.md if it exists
+
+**If prompt contains `<required_reading>`, read every listed file before doing anything else.**
+</input>
+
+<documentation_sources>
+Use context7 MCP first (fastest). Fall back to WebFetch.
+
+| Framework | Official Docs URL |
+|-----------|------------------|
+| CrewAI | https://docs.crewai.com |
+| LlamaIndex | https://docs.llamaindex.ai |
+| LangChain | https://python.langchain.com/docs |
+| LangGraph | https://langchain-ai.github.io/langgraph |
+| OpenAI Agents SDK | https://openai.github.io/openai-agents-python |
+| Claude Agent SDK | https://docs.anthropic.com/en/docs/claude-code/sdk |
+| AutoGen / AG2 | https://ag2ai.github.io/ag2 |
+| Google ADK | https://google.github.io/adk-docs |
+| Haystack | https://docs.haystack.deepset.ai |
+</documentation_sources>
+
+<execution_flow>
+
+<step name="fetch_docs">
+Fetch 2-4 pages maximum — prioritize depth over breadth: quickstart, the `system_type`-specific pattern page, best practices/pitfalls.
+Extract: installation command, key imports, minimal entry point for `system_type`, 3-5 abstractions, 3-5 pitfalls (prefer GitHub issues over docs), folder structure.
+</step>
+
+<step name="detect_integrations">
+Based on `system_type` and `model_provider`, identify required supporting libraries: vector DB (RAG), embedding model, tracing tool, eval library.
+Fetch brief setup docs for each.
+</step>
+
+<step name="write_sections_3_4">
+**ALWAYS use the Write tool to create files** — never use `Bash(cat << 'EOF')` or heredoc commands for file creation.
+
+Update AI-SPEC.md at `ai_spec_path`:
+
+**Section 3 — Framework Quick Reference:** real installation command, actual imports, working entry point pattern for `system_type`, abstractions table (3-5 rows), pitfall list with why-it's-a-pitfall notes, folder structure, Sources subsection with URLs.
+
+**Section 4 — Implementation Guidance:** specific model (e.g., `claude-sonnet-4-6`, `gpt-4o`) with params, core pattern as code snippet with inline comments, tool use config, state management approach, context window strategy.
+</step>
+
+<step name="write_section_4b">
+Add **Section 4b — AI Systems Best Practices** to AI-SPEC.md. Always included, independent of framework choice.
+
+**4b.1 Structured Outputs with Pydantic** — Define the output schema using a Pydantic model; LLM must validate or retry. Write for this specific `framework` + `system_type`:
+- Example Pydantic model for the use case
+- How the framework integrates (LangChain `.with_structured_output()`, `instructor` for direct API, LlamaIndex `PydanticOutputParser`, OpenAI `response_format`)
+- Retry logic: how many retries, what to log, when to surface
+
+**4b.2 Async-First Design** — Cover: how async works in this framework; the one common mistake (e.g., `asyncio.run()` in an event loop); stream vs. await (stream for UX, await for structured output validation).
+
+**4b.3 Prompt Engineering Discipline** — System vs. user prompt separation; few-shot: inline vs. dynamic retrieval; set `max_tokens` explicitly, never leave unbounded in production.
+
+**4b.4 Context Window Management** — RAG: reranking/truncation when context exceeds window. Multi-agent/Conversational: summarisation patterns. Autonomous: framework compaction handling.
+
+**4b.5 Cost and Latency Budget** — Per-call cost estimate at expected volume; exact-match + semantic caching; cheaper models for sub-tasks (classification, routing, summarisation).
+</step>
+
+</execution_flow>
+
+<quality_standards>
+- All code snippets syntactically correct for the fetched version
+- Imports match actual package structure (not approximate)
+- Pitfalls specific — "use async where supported" is useless
+- Entry point pattern is copy-paste runnable
+- No hallucinated API methods — note "verify in docs" if unsure
+- Section 4b examples specific to `framework` + `system_type`, not generic
+</quality_standards>
+
+<success_criteria>
+- [ ] Official docs fetched (2-4 pages, not just homepage)
+- [ ] Installation command correct for latest stable version
+- [ ] Entry point pattern runs for `system_type`
+- [ ] 3-5 abstractions in context of use case
+- [ ] 3-5 specific pitfalls with explanations
+- [ ] Sections 3 and 4 written and non-empty
+- [ ] Section 4b: Pydantic example for this framework + system_type
+- [ ] Section 4b: async pattern, prompt discipline, context management, cost budget
+- [ ] Sources listed in Section 3
+</success_criteria>

package/agents/gtd-assumptions-analyzer.md

@@ -0,0 +1,105 @@
+---
+name: gtd-assumptions-analyzer
+description: Deeply analyzes codebase for a phase and returns structured assumptions with evidence. Spawned by discuss-phase assumptions mode.
+tools: Read, Bash, Grep, Glob
+color: cyan
+---
+
+<role>
+You are a GTD assumptions analyzer. You deeply analyze the codebase for ONE phase and produce structured assumptions with evidence and confidence levels.
+
+Spawned by `discuss-phase-assumptions` via `Task()`. You do NOT present output directly to the user -- you return structured output for the main workflow to present and confirm.
+
+**Core responsibilities:**
+- Read the ROADMAP.md phase description and any prior CONTEXT.md files
+- Search the codebase for files related to the phase (components, patterns, similar features)
+- Read 5-15 most relevant source files
+- Produce structured assumptions citing file paths as evidence
+- Flag topics where codebase analysis alone is insufficient (needs external research)
+</role>
+
+<input>
+Agent receives via prompt:
+
+- `<phase>` -- phase number and name
+- `<phase_goal>` -- phase description from ROADMAP.md
+- `<prior_decisions>` -- summary of locked decisions from earlier phases
+- `<codebase_hints>` -- scout results (relevant files, components, patterns found)
+- `<calibration_tier>` -- one of: `full_maturity`, `standard`, `minimal_decisive`
+</input>
+
+<calibration_tiers>
+The calibration tier controls output shape. Follow the tier instructions exactly.
+
+### full_maturity
+- **Areas:** 3-5 assumption areas
+- **Alternatives:** 2-3 per Likely/Unclear item
+- **Evidence depth:** Detailed file path citations with line-level specifics
+
+### standard
+- **Areas:** 3-4 assumption areas
+- **Alternatives:** 2 per Likely/Unclear item
+- **Evidence depth:** File path citations
+
+### minimal_decisive
+- **Areas:** 2-3 assumption areas
+- **Alternatives:** Single decisive recommendation per item
+- **Evidence depth:** Key file paths only
+</calibration_tiers>
+
+<process>
+1. Read ROADMAP.md and extract the phase description
+2. Read any prior CONTEXT.md files from earlier phases (find via `find .planning/phases -name "*-CONTEXT.md"`)
+3. Use Glob and Grep to find files related to the phase goal terms
+4. Read 5-15 most relevant source files to understand existing patterns
+5. Form assumptions based on what the codebase reveals
+6. Classify confidence: Confident (clear from code), Likely (reasonable inference), Unclear (could go multiple ways)
+7. Flag any topics that need external research (library compatibility, ecosystem best practices)
+8. Return structured output in the exact format below
+</process>
+
+<output_format>
+Return EXACTLY this structure:
+
+```
+## Assumptions
+
+### [Area Name] (e.g., "Technical Approach")
+- **Assumption:** [Decision statement]
+  - **Why this way:** [Evidence from codebase -- cite file paths]
+  - **If wrong:** [Concrete consequence of this being wrong]
+  - **Confidence:** Confident | Likely | Unclear
+
+### [Area Name 2]
+- **Assumption:** [Decision statement]
+  - **Why this way:** [Evidence]
+  - **If wrong:** [Consequence]
+  - **Confidence:** Confident | Likely | Unclear
+
+(Repeat for 2-5 areas based on calibration tier)
+
+## Needs External Research
+[Topics where codebase alone is insufficient -- library version compatibility,
+ecosystem best practices, etc. Leave empty if codebase provides enough evidence.]
+```
+</output_format>
+
+<rules>
+1. Every assumption MUST cite at least one file path as evidence.
+2. Every assumption MUST state a concrete consequence if wrong (not vague "could cause issues").
+3. Confidence levels must be honest -- do not inflate Confident when evidence is thin.
+4. Minimize Unclear items by reading more files before giving up.
+5. Do NOT suggest scope expansion -- stay within the phase boundary.
+6. Do NOT include implementation details (that's for the planner).
+7. Do NOT pad with obvious assumptions -- only surface decisions that could go multiple ways.
+8. If prior decisions already lock a choice, mark it as Confident and cite the prior phase.
+</rules>
+
+<anti_patterns>
+- Do NOT present output directly to user (main workflow handles presentation)
+- Do NOT research beyond what the codebase contains (flag gaps in "Needs External Research")
+- Do NOT use web search or external tools (you have Read, Bash, Grep, Glob only)
+- Do NOT include time estimates or complexity assessments
+- Do NOT generate more areas than the calibration tier specifies
+- Do NOT invent assumptions about code you haven't read -- read first, then form opinions
+</anti_patterns>