gsd-antigravity-kit 2.0.1 → 2.1.0

package/.agent/skills/gsd/references/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
+.agent/skills/gsd/bin/gsd-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 /gsd-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 /gsd-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 Antigravity'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 @assets/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: /gsd-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 /gsd-discuss-phase as next step
+</success_criteria>

package/.agent/skills/gsd/references/workflows/spike-wrap-up.md

@@ -0,0 +1,273 @@
+<purpose>
+Curate spike experiment findings and package them into a persistent project skill for future
+build conversations. Reads from `.planning/spikes/`, writes skill to `./.antigravity/skills/spike-findings-[project]/`
+(project-local) and summary to `.planning/spikes/WRAP-UP-SUMMARY.md`.
+Companion to `/gsd-spike`.
+</purpose>
+
+<required_reading>
+Read all files referenced by the invoking prompt's execution_context before starting.
+</required_reading>
+
+<process>
+
+<step name="banner">
+```
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+ GSD ► SPIKE WRAP-UP
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+```
+</step>
+
+<step name="gather">
+## Gather Spike Inventory
+
+1. Read `.planning/spikes/MANIFEST.md` for the overall idea context
+2. Glob `.planning/spikes/*/README.md` and parse YAML frontmatter from each
+3. Check if `./.antigravity/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 `/gsd-spike` first to create experiments.
+```
+Exit.
+
+Check `commit_docs` config:
+```bash
+COMMIT_DOCS=$(gsd-sdk query config-get commit_docs 2>/dev/null || echo "true")
+```
+</step>
+
+<step name="curate">
+## Curate Spikes One-at-a-Time
+
+Present each unprocessed spike in ascending order. For each spike, show:
+
+- **Spike number and name**
+- **Validates:** the Given/When/Then from frontmatter
+- **Verdict:** VALIDATED / INVALIDATED / PARTIAL
+- **Tags:** from frontmatter
+- **Key findings:** summarize the Results section from the README
+- **Grey areas:** anything uncertain or partially proven
+
+Then ask the user:
+
+╔══════════════════════════════════════════════════════════════╗
+║  CHECKPOINT: Decision Required                               ║
+╚══════════════════════════════════════════════════════════════╝
+
+Spike {NNN}: {name} — {verdict}
+
+{key findings summary}
+
+──────────────────────────────────────────────────────────────
+→ Include / Exclude / Partial / Help me UAT this
+──────────────────────────────────────────────────────────────
+
+**If "Help me UAT this":**
+1. Read the spike's README "How to Run" and "What to Expect" sections
+2. Present step-by-step instructions
+3. Ask: "Does this match what you expected?"
+4. After UAT, return to the include/exclude/partial decision
+
+**If "Partial":**
+Ask what specifically to include or exclude. Record their notes alongside the spike.
+</step>
+
+<step name="group">
+## Auto-Group by Feature Area
+
+After all spikes are curated:
+
+1. Read all included spikes' tags, names, `related` fields, and content
+2. Propose feature-area groupings, e.g.:
+   - "**WebSocket Streaming** — spikes 001, 004, 007"
+   - "**Foo API Integration** — spikes 002, 003"
+   - "**PDF Parsing** — spike 005"
+3. Present the grouping for approval — user may merge, split, rename, or rearrange
+
+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 `./.antigravity/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`:
+
+```markdown
+# [Feature Area Name]
+
+## Validated Patterns
+[For each validated finding: describe the approach that works, include key code snippets extracted from the spike source, explain why it works]
+
+## Landmines
+[Things that look right but aren't. Gotchas. Anti-patterns discovered during spiking.]
+
+## 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: Validated patterns, constraints, and implementation knowledge from spike experiments. Auto-loaded during implementation work on [project-dir-name].
+---
+
+<context>
+## Project: [project-dir-name]
+
+[One paragraph from MANIFEST.md describing the overall idea]
+
+Spike sessions wrapped: [date(s)]
+</context>
+
+<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:** `./.antigravity/skills/spike-findings-[project]/`
+
+## Included Spikes
+| # | Name | Verdict | Feature Area |
+|---|------|---------|--------------|
+
+## Excluded Spikes
+| # | Name | Reason |
+|---|------|--------|
+
+## Key Findings
+[consolidated findings summary]
+```
+</step>
+
+<step name="update_antigravity_md">
+## Update Project ANTIGRAVITY.md
+
+Add an auto-load routing line to the project's ANTIGRAVITY.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="commit">
+Commit all artifacts (if `COMMIT_DOCS` is true):
+
+```bash
+gsd-sdk query commit "docs(spike-wrap-up): package [N] spike findings into project skill" .planning/spikes/WRAP-UP-SUMMARY.md
+```
+</step>
+
+<step name="report">
+```
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+ GSD ► SPIKE WRAP-UP COMPLETE ✓
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+
+**Curated:** {N} spikes ({included} included, {excluded} excluded)
+**Feature areas:** {list}
+**Skill:** `./.antigravity/skills/spike-findings-[project]/`
+**Summary:** `.planning/spikes/WRAP-UP-SUMMARY.md`
+**ANTIGRAVITY.md:** routing line added
+
+The spike-findings skill will auto-load in future build conversations.
+```
+
+───────────────────────────────────────────────────────────────
+
+## ▶ Next Up
+
+**Start building** — plan the real implementation
+
+`/gsd-plan-phase`
+
+───────────────────────────────────────────────────────────────
+
+**Also available:**
+- `/gsd-add-phase` — add a phase based on spike findings
+- `/gsd-spike` — spike additional ideas
+- `/gsd-explore` — continue exploring
+
+───────────────────────────────────────────────────────────────
+</step>
+
+</process>
+
+<success_criteria>
+- [ ] Every unprocessed spike presented for individual curation
+- [ ] Feature-area grouping proposed and approved
+- [ ] Spike-findings skill exists at `./.antigravity/skills/` with SKILL.md, references/, sources/
+- [ ] Core source files from included spikes copied into sources/
+- [ ] Reference files contain validated patterns, code snippets, landmines, constraints
+- [ ] `.planning/spikes/WRAP-UP-SUMMARY.md` written for project history
+- [ ] Project ANTIGRAVITY.md has auto-load routing line
+- [ ] Summary presented with next-step routing
+</success_criteria>