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

package/get-tasks-done/workflows/spec-phase.md

@@ -0,0 +1,262 @@
+<purpose>
+Clarify WHAT a phase delivers through a Socratic interview loop with quantitative ambiguity scoring.
+Produces a SPEC.md with falsifiable requirements that discuss-phase treats as locked decisions.
+
+This workflow handles "what" and "why" — discuss-phase handles "how".
+</purpose>
+
+<ambiguity_model>
+Score each dimension 0.0 (completely unclear) to 1.0 (crystal clear):
+
+| Dimension         | Weight | Minimum | What it measures                                  |
+|-------------------|--------|---------|---------------------------------------------------|
+| Goal Clarity      | 35%    | 0.75    | Is the outcome specific and measurable?           |
+| Boundary Clarity  | 25%    | 0.70    | What's in scope vs out of scope?                  |
+| Constraint Clarity| 20%    | 0.65    | Performance, compatibility, data requirements?    |
+| Acceptance Criteria| 20%   | 0.70    | How do we know it's done?                         |
+
+**Ambiguity score** = 1.0 − (0.35×goal + 0.25×boundary + 0.20×constraint + 0.20×acceptance)
+
+**Gate:** ambiguity ≤ 0.20 AND all dimensions ≥ their minimums → ready to write SPEC.md.
+
+A score of 0.20 means 80% weighted clarity — enough precision that the planner won't silently make wrong assumptions.
+</ambiguity_model>
+
+<interview_perspectives>
+Rotate through these perspectives — each naturally surfaces different blindspots:
+
+**Researcher (rounds 1–2):** Ground the discussion in current reality.
+- "What exists in the codebase today related to this phase?"
+- "What's the delta between today and the target state?"
+- "What triggers this work — what's broken or missing?"
+
+**Simplifier (round 2):** Surface minimum viable scope.
+- "What's the simplest version that solves the core problem?"
+- "If you had to cut 50%, what's the irreducible core?"
+- "What would make this phase a success even without the nice-to-haves?"
+
+**Boundary Keeper (round 3):** Lock the perimeter.
+- "What explicitly will NOT be done in this phase?"
+- "What adjacent problems is it tempting to solve but shouldn't?"
+- "What does 'done' look like — what's the final deliverable?"
+
+**Failure Analyst (round 4):** Find the edge cases that invalidate requirements.
+- "What's the worst thing that could go wrong if we get the requirements wrong?"
+- "What does a broken version of this look like?"
+- "What would cause a verifier to reject the output?"
+
+**Seed Closer (rounds 5–6):** Lock remaining undecided territory.
+- "We have [dimension] at [score] — what would make it completely clear?"
+- "The remaining ambiguity is in [area] — can we make a decision now?"
+- "Is there anything you'd regret not specifying before planning starts?"
+</interview_perspectives>
+
+<process>
+
+## Step 1: Initialize
+
+```bash
+INIT=$(node "$HOME/.claude/get-tasks-done/bin/gtd-tools.cjs" init phase-op "${PHASE}")
+if [[ "$INIT" == @file:* ]]; then INIT=$(cat "${INIT#@file:}"); fi
+```
+
+Parse JSON for: `phase_found`, `phase_dir`, `phase_number`, `phase_name`, `phase_slug`, `padded_phase`, `state_path`, `requirements_path`, `roadmap_path`, `planning_path`, `response_language`, `commit_docs`.
+
+**If `response_language` is set:** All user-facing text in this workflow MUST be in `{response_language}`. Technical terms, code, and file paths stay in English.
+
+**If `phase_found` is false:**
+```
+Phase [X] not found in roadmap.
+Use /gtd:progress to see available phases.
+```
+Exit.
+
+**Check for existing SPEC.md:**
+```bash
+ls ${phase_dir}/*-SPEC.md 2>/dev/null | grep -v AI-SPEC | head -1 || true
+```
+
+If SPEC.md already exists:
+
+**If `--auto`:** Auto-select "Update it". Log: `[auto] SPEC.md exists — updating.`
+
+**Otherwise:** Use AskUserQuestion:
+- header: "Spec"
+- question: "Phase [X] already has a SPEC.md. What do you want to do?"
+- options:
+  - "Update it" — Revise and re-score
+  - "View it" — Show current spec
+  - "Skip" — Exit (use existing spec as-is)
+
+If "View": Display SPEC.md, then offer Update/Skip.
+If "Skip": Exit with message: "Existing SPEC.md unchanged. Run /gtd:discuss-phase [X] to continue."
+If "Update": Load existing SPEC.md, continue to Step 3.
+
+## Step 2: Scout Codebase
+
+**Read these files before any questions:**
+- `{requirements_path}` — Project requirements
+- `{state_path}` — Decisions already made, current phase, blockers
+- ROADMAP.md phase entry — Phase description, goals, canonical refs
+
+**Grep the codebase** for code/files relevant to this phase goal. Look for:
+- Existing implementations of similar functionality
+- Integration points where new code will connect
+- Test coverage gaps relevant to the phase
+- Prior phase artifacts (SUMMARY.md, VERIFICATION.md) that inform current state
+
+**Synthesize current state** — the grounded baseline for the interview:
+- What exists today related to this phase
+- The gap between current state and the phase goal
+- The primary deliverable: what file/behavior/capability does NOT exist yet?
+
+Confirm your current state synthesis internally. Do not present it to the user yet — you'll use it to ask precise, grounded questions.
+
+## Step 3: First Ambiguity Assessment
+
+Before questioning begins, score the phase's current ambiguity based only on what ROADMAP.md and REQUIREMENTS.md say:
+
+```
+Goal Clarity:       [score 0.0–1.0]
+Boundary Clarity:   [score 0.0–1.0]
+Constraint Clarity: [score 0.0–1.0]
+Acceptance Criteria:[score 0.0–1.0]
+
+Ambiguity: [score] ([calculate])
+```
+
+**If `--auto` and initial ambiguity already ≤ 0.20 with all minimums met:** Skip interview — derive SPEC.md directly from roadmap + requirements. Log: `[auto] Phase requirements are already sufficiently clear — generating SPEC.md from existing context.` Jump to Step 6.
+
+**Otherwise:** Continue to Step 4.
+
+## Step 4: Socratic Interview Loop
+
+**Max 6 rounds.** Each round: 2–3 questions max. End round after user responds.
+
+**Round selection by perspective:**
+- Round 1: Researcher
+- Round 2: Researcher + Simplifier
+- Round 3: Boundary Keeper
+- Round 4: Failure Analyst
+- Rounds 5–6: Seed Closer (focus on lowest-scoring dimensions)
+
+**After each round:**
+1. Update all 4 dimension scores from the user's answers
+2. Calculate new ambiguity score
+3. Display the updated scoring:
+
+```
+After round [N]:
+  Goal Clarity:       [score] (min 0.75) [✓ or ↑ needed]
+  Boundary Clarity:   [score] (min 0.70) [✓ or ↑ needed]
+  Constraint Clarity: [score] (min 0.65) [✓ or ↑ needed]
+  Acceptance Criteria:[score] (min 0.70) [✓ or ↑ needed]
+  Ambiguity: [score] (gate: ≤ 0.20)
+```
+
+**Gate check after each round:**
+
+If gate passes (ambiguity ≤ 0.20 AND all minimums met):
+
+**If `--auto`:** Jump to Step 6.
+
+**Otherwise:** AskUserQuestion:
+- header: "Spec Gate Passed"
+- question: "Ambiguity is [score] — requirements are clear enough to write SPEC.md. Proceed?"
+- options:
+  - "Yes — write SPEC.md" → Jump to Step 6
+  - "One more round" → Continue interview
+  - "Done talking — write it" → Jump to Step 6
+
+**If max rounds reached (6) and gate not passed:**
+
+**If `--auto`:** Write SPEC.md anyway — flag unresolved dimensions. Log: `[auto] Max rounds reached. Writing SPEC.md with [N] dimensions below minimum. Planner will need to treat these as assumptions.`
+
+**Otherwise:** AskUserQuestion:
+- header: "Max Rounds"
+- question: "After 6 rounds, ambiguity is [score]. [List dimensions still below minimum.] What would you like to do?"
+- options:
+  - "Write SPEC.md anyway — flag gaps" → Write SPEC.md, mark unresolved dimensions in Ambiguity Report
+  - "Keep talking" → Continue (no round limit from here)
+  - "Abandon" → Exit without writing
+
+**If `--auto` mode throughout:** Replace all AskUserQuestion calls above with Claude's recommended choice. Log decisions inline. Apply the same logic as `--auto` in discuss-phase.
+
+**Text mode (`workflow.text_mode: true` or `--text` flag):** Use plain-text numbered lists instead of AskUserQuestion TUI menus.
+
+## Step 5: (covered inline — ambiguity scoring is per-round)
+
+## Step 6: Generate SPEC.md
+
+Use the SPEC.md template from @~/.claude/get-tasks-done/templates/spec.md.
+
+**Requirements for every requirement entry:**
+- One specific, testable statement
+- Current state (what exists now)
+- Target state (what it should become)
+- Acceptance criterion (how to verify it was met)
+
+**Vague requirements are rejected:**
+- ✗ "The system should be fast"
+- ✗ "Improve user experience"
+- ✓ "API endpoint responds in < 200ms at p95 under 100 concurrent requests"
+- ✓ "CLI command exits with code 1 and prints to stderr on invalid input"
+
+**Count requirements.** The display in discuss-phase reads: "Found SPEC.md — {N} requirements locked."
+
+**Boundaries must be explicit lists:**
+- "In scope" — what this phase produces
+- "Out of scope" — what it explicitly does NOT do (with brief reasoning)
+
+**Acceptance criteria must be pass/fail checkboxes** — no "should feel good" or "looks reasonable."
+
+**If any dimensions are below minimum**, mark them in the Ambiguity Report with: `⚠ Below minimum — planner must treat as assumption`.
+
+Write to: `{phase_dir}/{padded_phase}-SPEC.md`
+
+## Step 7: Commit
+
+```bash
+git add "${phase_dir}/${padded_phase}-SPEC.md"
+git commit -m "spec(phase-${phase_number}): add SPEC.md for ${phase_name} — ${requirement_count} requirements (#2213)"
+```
+
+If `commit_docs` is false: Skip commit. Note that SPEC.md was written but not committed.
+
+## Step 8: Wrap Up
+
+Display:
+
+```
+SPEC.md written — {N} requirements locked.
+
+  Phase {X}: {name}
+  Ambiguity: {final_score} (gate: ≤ 0.20)
+
+Next: /gtd:discuss-phase {X}
+  discuss-phase will detect SPEC.md and focus on implementation decisions only.
+```
+
+</process>
+
+<critical_rules>
+- Every requirement MUST have current state, target state, and acceptance criterion
+- Boundaries section is MANDATORY — cannot be empty
+- "In scope" and "Out of scope" must be explicit lists, not narrative prose
+- Acceptance criteria must be pass/fail — no subjective criteria
+- SPEC.md is NEVER written if the user selects "Abandon"
+- Do NOT ask about HOW to implement — that is discuss-phase territory
+- Scout the codebase BEFORE the first question — grounded questions only
+- Max 2–3 questions per round — do not frontload all questions at once
+</critical_rules>
+
+<success_criteria>
+- Codebase scouted and current state understood before questioning
+- All 4 dimensions scored after every round
+- Gate passed OR user explicitly chose to write despite gaps
+- SPEC.md contains only falsifiable requirements
+- Boundaries are explicit (in scope / out of scope with reasoning)
+- Acceptance criteria are pass/fail checkboxes
+- SPEC.md committed atomically (when commit_docs is true)
+- User directed to /gtd:discuss-phase as next step
+</success_criteria>

package/get-tasks-done/workflows/spike-wrap-up.md

@@ -0,0 +1,306 @@
+<purpose>
+Package spike experiment findings into a persistent project skill — an implementation blueprint
+for future build conversations. Reads from `.planning/spikes/`, writes skill to
+`./.claude/skills/spike-findings-[project]/` (project-local) and summary to
+`.planning/spikes/WRAP-UP-SUMMARY.md`. Companion to `/gtd:spike`.
+</purpose>
+
+<required_reading>
+Read all files referenced by the invoking prompt's execution_context before starting.
+</required_reading>
+
+<process>
+
+<step name="banner">
+```
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+ GTD ► SPIKE WRAP-UP
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+```
+</step>
+
+<step name="gather">
+## Gather Spike Inventory
+
+1. Read `.planning/spikes/MANIFEST.md` for the overall idea context and requirements
+2. Glob `.planning/spikes/*/README.md` and parse YAML frontmatter from each
+3. Check if `./.claude/skills/spike-findings-*/SKILL.md` exists for this project
+   - If yes: read its `processed_spikes` list from the metadata section and filter those out
+   - If no: all spikes are candidates
+
+If no unprocessed spikes exist:
+```
+No unprocessed spikes found in `.planning/spikes/`.
+Run `/gtd:spike` first to create experiments.
+```
+Exit.
+
+Check `commit_docs` config:
+```bash
+COMMIT_DOCS=$(gtd-sdk query config-get commit_docs 2>/dev/null || echo "true")
+```
+</step>
+
+<step name="auto_include">
+## Auto-Include All Spikes
+
+Include all unprocessed spikes automatically. Present a brief inventory showing what's being processed:
+
+```
+Processing N spikes:
+  001 — name (VALIDATED)
+  002 — name (PARTIAL)
+  003 — name (INVALIDATED)
+```
+
+Every spike carries forward:
+- **VALIDATED** spikes provide proven patterns
+- **PARTIAL** spikes provide constrained patterns
+- **INVALIDATED** spikes provide landmines and dead ends
+</step>
+
+<step name="group">
+## Auto-Group by Feature Area
+
+Group spikes by feature area based on tags, names, `related` fields, and content. Proceed directly into synthesis.
+
+Each group becomes one reference file in the generated skill.
+</step>
+
+<step name="skill_name">
+## Determine Output Skill Name
+
+Derive the skill name from the project directory:
+
+1. Get the project root directory name (e.g., `solana-tracker`)
+2. The skill will be created at `./.claude/skills/spike-findings-[project-dir-name]/`
+
+If a skill already exists at that path (append mode), update in place.
+</step>
+
+<step name="copy_sources">
+## Copy Source Files
+
+For each included spike:
+
+1. Identify the core source files — the actual scripts, main files, and config that make the spike work. Exclude:
+   - `node_modules/`, `__pycache__/`, `.venv/`, build artifacts
+   - Lock files (`package-lock.json`, `yarn.lock`, etc.)
+   - `.git/`, `.DS_Store`
+2. Copy the README.md and core source files into `sources/NNN-spike-name/` inside the generated skill directory
+</step>
+
+<step name="synthesize">
+## Synthesize Reference Files
+
+For each feature-area group, write a reference file at `references/[feature-area-name].md` as an **implementation blueprint** — it should read like a recipe, not a research paper. A future build session should be able to follow this and build the feature correctly without re-spiking anything.
+
+```markdown
+# [Feature Area Name]
+
+## Requirements
+
+[Non-negotiable design decisions from MANIFEST.md Requirements section that apply to this feature area. These MUST be honored in the real build. E.g., "Must use streaming JSON output", "Must support reconnection".]
+
+## How to Build It
+
+[Step-by-step: what to install, how to configure, what code pattern to use. Include key code snippets extracted from the spike source. This is the proven approach — not theory, but tested and working code.]
+
+## What to Avoid
+
+[Things that look right but aren't. Gotchas. Anti-patterns discovered during spiking. Dead ends that were tried and failed.]
+
+## Constraints
+
+[Hard facts: rate limits, library limitations, version requirements, incompatibilities]
+
+## Origin
+
+Synthesized from spikes: NNN, NNN, NNN
+Source files available in: sources/NNN-spike-name/, sources/NNN-spike-name/
+```
+</step>
+
+<step name="write_skill">
+## Write SKILL.md
+
+Create (or update) the generated skill's SKILL.md:
+
+```markdown
+---
+name: spike-findings-[project-dir-name]
+description: Implementation blueprint from spike experiments. Requirements, proven patterns, and verified knowledge for building [project-dir-name]. Auto-loaded during implementation work.
+---
+
+<context>
+## Project: [project-dir-name]
+
+[One paragraph from MANIFEST.md describing the overall idea]
+
+Spike sessions wrapped: [date(s)]
+</context>
+
+<requirements>
+## Requirements
+
+[Copied directly from MANIFEST.md Requirements section. These are non-negotiable design decisions that emerged from the user's choices during spiking. Every feature area reference must honor these.]
+
+- [requirement 1]
+- [requirement 2]
+</requirements>
+
+<findings_index>
+## Feature Areas
+
+| Area | Reference | Key Finding |
+|------|-----------|-------------|
+| [Name] | references/[name].md | [One-line summary] |
+
+## Source Files
+
+Original spike source files are preserved in `sources/` for complete reference.
+</findings_index>
+
+<metadata>
+## Processed Spikes
+
+[List of spike numbers wrapped up]
+
+- 001-spike-name
+- 002-spike-name
+</metadata>
+```
+</step>
+
+<step name="write_summary">
+## Write Planning Summary
+
+Write `.planning/spikes/WRAP-UP-SUMMARY.md` for project history:
+
+```markdown
+# Spike Wrap-Up Summary
+
+**Date:** [date]
+**Spikes processed:** [count]
+**Feature areas:** [list]
+**Skill output:** `./.claude/skills/spike-findings-[project]/`
+
+## Processed Spikes
+| # | Name | Type | Verdict | Feature Area |
+|---|------|------|---------|--------------|
+
+## Key Findings
+[consolidated findings summary]
+```
+</step>
+
+<step name="update_claude_md">
+## Update Project CLAUDE.md
+
+Add an auto-load routing line to the project's CLAUDE.md (create the file if it doesn't exist):
+
+```
+- **Spike findings for [project]** (implementation patterns, constraints, gotchas) → `Skill("spike-findings-[project-dir-name]")`
+```
+
+If this routing line already exists (append mode), leave it as-is.
+</step>
+
+<step name="generate_conventions">
+## Generate or Update CONVENTIONS.md
+
+Analyze all processed spikes for recurring patterns and write `.planning/spikes/CONVENTIONS.md`. This file tells future spike sessions *how we spike* — the stack, structure, and patterns that have been established.
+
+1. Read all spike source code and READMEs looking for:
+   - **Stack choices** — What language/framework/runtime appears across multiple spikes?
+   - **Structure patterns** — Common file layouts, port numbers, naming schemes
+   - **Recurring approaches** — How auth is handled, how styling is done, how data is served
+   - **Tools & libraries** — Packages that showed up repeatedly with versions that worked
+
+2. Write or update `.planning/spikes/CONVENTIONS.md`:
+
+```markdown
+# Spike Conventions
+
+Patterns and stack choices established across spike sessions. New spikes follow these unless the question requires otherwise.
+
+## Stack
+[What we use for frontend, backend, scripts, and why — derived from what repeated across spikes]
+
+## Structure
+[Common file layouts, port assignments, naming patterns]
+
+## Patterns
+[Recurring approaches: how we handle auth, how we style, how we serve, etc.]
+
+## Tools & Libraries
+[Preferred packages with versions that worked, and any to avoid]
+```
+
+3. Only include patterns that appeared in 2+ spikes or were explicitly chosen by the user.
+
+4. If `CONVENTIONS.md` already exists (append mode), update sections with new patterns. Remove entries contradicted by newer spikes.
+</step>
+
+<step name="commit">
+Commit all artifacts (if `COMMIT_DOCS` is true):
+
+```bash
+gtd-sdk query commit "docs(spike-wrap-up): package [N] spike findings into project skill" --files .planning/spikes/WRAP-UP-SUMMARY.md .planning/spikes/CONVENTIONS.md
+```
+</step>
+
+<step name="report">
+```
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+ GTD ► SPIKE WRAP-UP COMPLETE ✓
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+
+**Processed:** {N} spikes
+**Feature areas:** {list}
+**Skill:** `./.claude/skills/spike-findings-[project]/`
+**Conventions:** `.planning/spikes/CONVENTIONS.md`
+**Summary:** `.planning/spikes/WRAP-UP-SUMMARY.md`
+**CLAUDE.md:** routing line added
+
+The spike-findings skill will auto-load in future build conversations.
+```
+</step>
+
+<step name="whats_next">
+## What's Next
+
+After the summary, present next-step options:
+
+───────────────────────────────────────────────────────────────
+
+## ▶ Next Up
+
+**Explore frontier spikes** — see what else is worth spiking based on what we've learned
+
+`/gtd:spike` (run with no argument — its frontier mode analyzes the spike landscape and proposes integration and frontier spikes)
+
+───────────────────────────────────────────────────────────────
+
+**Also available:**
+- `/gtd:plan-phase` — start planning the real implementation
+- `/gtd:spike [idea]` — spike a specific new idea
+- `/gtd:explore` — continue exploring
+- Other
+
+───────────────────────────────────────────────────────────────
+</step>
+
+</process>
+
+<success_criteria>
+- [ ] All unprocessed spikes auto-included and processed
+- [ ] Spikes grouped by feature area
+- [ ] Spike-findings skill exists at `./.claude/skills/` with SKILL.md (including requirements), references/, sources/
+- [ ] Reference files are implementation blueprints with Requirements, How to Build It, What to Avoid, Constraints
+- [ ] `.planning/spikes/CONVENTIONS.md` created or updated with recurring stack/structure/pattern choices
+- [ ] `.planning/spikes/WRAP-UP-SUMMARY.md` written for project history
+- [ ] Project CLAUDE.md has auto-load routing line
+- [ ] Summary presented
+- [ ] Next-step options presented (including frontier spike exploration via `/gtd:spike`)
+</success_criteria>