@opengsd/gsd-core 1.2.0-rc.1

package/get-shit-done/workflows/add-todo.md

@@ -0,0 +1,161 @@
+<purpose>
+Capture an idea, task, or issue that surfaces during a GSD session as a structured todo for later work. Enables "thought → capture → continue" flow without losing context.
+</purpose>
+
+<required_reading>
+Read all files referenced by the invoking prompt's execution_context before starting.
+</required_reading>
+
+<process>
+
+<step name="init_context">
+Load todo context:
+
+```bash
+_GSD_SHIM_NAME="gsd-tools.cjs"; _GSD_RUNTIME_ROOT="${RUNTIME_DIR:-$(git rev-parse --show-toplevel 2>/dev/null || pwd)}"; GSD_TOOLS="${_GSD_RUNTIME_ROOT}/get-shit-done/bin/${_GSD_SHIM_NAME}"; if [ -f "$GSD_TOOLS" ]; then gsd_run() { node "$GSD_TOOLS" "$@"; }; elif [ -f "${_GSD_RUNTIME_ROOT}/.claude/get-shit-done/bin/${_GSD_SHIM_NAME}" ]; then GSD_TOOLS="${_GSD_RUNTIME_ROOT}/.claude/get-shit-done/bin/${_GSD_SHIM_NAME}"; gsd_run() { node "$GSD_TOOLS" "$@"; }; elif command -v gsd-tools >/dev/null 2>&1; then GSD_TOOLS="$(command -v gsd-tools)"; gsd_run() { "$GSD_TOOLS" "$@"; }; elif [ -f "$HOME/.claude/get-shit-done/bin/${_GSD_SHIM_NAME}" ]; then GSD_TOOLS="$HOME/.claude/get-shit-done/bin/${_GSD_SHIM_NAME}"; gsd_run() { node "$GSD_TOOLS" "$@"; }; else echo "ERROR: gsd-tools.cjs not found at $GSD_TOOLS and gsd-tools is not on PATH. Run: npx -y @opengsd/gsd-core@latest --claude --local" >&2; exit 1; fi
+INIT=$(gsd_run query init.todos)
+if [[ "$INIT" == @file:* ]]; then INIT=$(cat "${INIT#@file:}"); fi
+```
+
+Extract from init JSON: `commit_docs`, `date`, `timestamp`, `todo_count`, `todos`, `pending_dir`, `todos_dir_exists`.
+
+Ensure directories exist:
+```bash
+mkdir -p .planning/todos/pending .planning/todos/completed
+```
+
+Note existing areas from the todos array for consistency in infer_area step.
+</step>
+
+<step name="extract_content">
+**With arguments:** Use as the title/focus.
+- `/gsd-add-todo Add auth token refresh` → title = "Add auth token refresh"
+
+**Without arguments:** Analyze recent conversation to extract:
+- The specific problem, idea, or task discussed
+- Relevant file paths mentioned
+- Technical details (error messages, line numbers, constraints)
+
+Formulate:
+- `title`: 3-10 word descriptive title (action verb preferred)
+- `problem`: What's wrong or why this is needed
+- `solution`: Approach hints or "TBD" if just an idea
+- `files`: Relevant paths with line numbers from conversation
+</step>
+
+<step name="infer_area">
+Infer area from file paths:
+
+| Path pattern | Area |
+|--------------|------|
+| `src/api/*`, `api/*` | `api` |
+| `src/components/*`, `src/ui/*` | `ui` |
+| `src/auth/*`, `auth/*` | `auth` |
+| `src/db/*`, `database/*` | `database` |
+| `tests/*`, `__tests__/*` | `testing` |
+| `docs/*` | `docs` |
+| `.planning/*` | `planning` |
+| `scripts/*`, `bin/*` | `tooling` |
+| No files or unclear | `general` |
+
+Use existing area from step 2 if similar match exists.
+</step>
+
+<step name="check_duplicates">
+```bash
+# Search for key words from title in existing todos
+grep -l -i "[key words from title]" .planning/todos/pending/*.md 2>/dev/null || true
+```
+
+If potential duplicate found:
+1. Read the existing todo
+2. Compare scope
+
+
+**Text mode (`workflow.text_mode: true` in config or `--text` flag):** Set `TEXT_MODE=true` if `--text` is present in `$ARGUMENTS` OR `text_mode` from init JSON is `true`. When TEXT_MODE is active, replace every `AskUserQuestion` call with a plain-text numbered list and ask the user to type their choice number. This is required for non-Claude runtimes (OpenAI Codex, Gemini CLI, etc.) where `AskUserQuestion` is not available.
+If overlapping, use AskUserQuestion:
+- header: "Duplicate?"
+- question: "Similar todo exists: [title]. What would you like to do?"
+- options:
+  - "Skip" — keep existing todo
+  - "Replace" — update existing with new context
+  - "Add anyway" — create as separate todo
+</step>
+
+<step name="create_file">
+Use values from init context: `timestamp` and `date` are already available.
+
+Generate slug for the title:
+```bash
+slug=$(gsd_run query generate-slug "$title" --raw)
+```
+
+Write to `.planning/todos/pending/${date}-${slug}.md`:
+
+```markdown
+---
+created: [timestamp]
+title: [title]
+area: [area]
+files:
+  - [file:lines]
+---
+
+## Problem
+
+[problem description - enough context for future Claude to understand weeks later]
+
+## Solution
+
+[approach hints or "TBD"]
+```
+</step>
+
+<step name="update_state">
+If `.planning/STATE.md` exists:
+
+1. Use `todo_count` from init context (or re-run `init todos` if count changed)
+2. Update "### Pending Todos" under "## Accumulated Context"
+</step>
+
+<step name="git_commit">
+Commit the todo and any updated state:
+
+```bash
+gsd_run query commit "docs: capture todo - [title]" --files .planning/todos/pending/[filename] .planning/STATE.md
+```
+
+Tool respects `commit_docs` config and gitignore automatically.
+
+Confirm: "Committed: docs: capture todo - [title]"
+</step>
+
+<step name="confirm">
+```
+Todo saved: .planning/todos/pending/[filename]
+
+  [title]
+  Area: [area]
+  Files: [count] referenced
+
+---
+
+Would you like to:
+
+1. Continue with current work
+2. Add another todo
+3. View all todos (/gsd:capture --list)
+```
+</step>
+
+</process>
+
+<success_criteria>
+- [ ] Directory structure exists
+- [ ] Todo file created with valid frontmatter
+- [ ] Problem section has enough context for future Claude
+- [ ] No duplicates (checked and resolved)
+- [ ] Area consistent with existing todos
+- [ ] STATE.md updated if exists
+- [ ] Todo and state committed to git
+</success_criteria>

package/get-shit-done/workflows/ai-integration-phase.md

@@ -0,0 +1,295 @@
+<purpose>
+Generate an AI design contract (AI-SPEC.md) for phases that involve building AI systems. Orchestrates gsd-framework-selector → gsd-ai-researcher → gsd-domain-researcher → gsd-eval-planner with a validation gate. Inserts between discuss-phase and plan-phase in the GSD lifecycle.
+
+AI-SPEC.md locks four things before the planner creates tasks:
+1. Framework selection (with rationale and alternatives)
+2. Implementation guidance (correct syntax, patterns, pitfalls from official docs)
+3. Domain context (practitioner rubric ingredients, failure modes, regulatory constraints)
+4. Evaluation strategy (dimensions, rubrics, tooling, reference dataset, guardrails)
+
+This prevents the two most common AI development failures: choosing the wrong framework for the use case, and treating evaluation as an afterthought.
+</purpose>
+
+<required_reading>
+@~/.claude/get-shit-done/references/ai-frameworks.md
+@~/.claude/get-shit-done/references/ai-evals.md
+</required_reading>
+
+<process>
+
+## 1. Initialize
+
+```bash
+_GSD_SHIM_NAME="gsd-tools.cjs"; _GSD_RUNTIME_ROOT="${RUNTIME_DIR:-$(git rev-parse --show-toplevel 2>/dev/null || pwd)}"; GSD_TOOLS="${_GSD_RUNTIME_ROOT}/get-shit-done/bin/${_GSD_SHIM_NAME}"; if [ -f "$GSD_TOOLS" ]; then gsd_run() { node "$GSD_TOOLS" "$@"; }; elif [ -f "${_GSD_RUNTIME_ROOT}/.claude/get-shit-done/bin/${_GSD_SHIM_NAME}" ]; then GSD_TOOLS="${_GSD_RUNTIME_ROOT}/.claude/get-shit-done/bin/${_GSD_SHIM_NAME}"; gsd_run() { node "$GSD_TOOLS" "$@"; }; elif command -v gsd-tools >/dev/null 2>&1; then GSD_TOOLS="$(command -v gsd-tools)"; gsd_run() { "$GSD_TOOLS" "$@"; }; elif [ -f "$HOME/.claude/get-shit-done/bin/${_GSD_SHIM_NAME}" ]; then GSD_TOOLS="$HOME/.claude/get-shit-done/bin/${_GSD_SHIM_NAME}"; gsd_run() { node "$GSD_TOOLS" "$@"; }; else echo "ERROR: gsd-tools.cjs not found at $GSD_TOOLS and gsd-tools is not on PATH. Run: npx -y @opengsd/gsd-core@latest --claude --local" >&2; exit 1; fi
+INIT=$(gsd_run query init.plan-phase "$PHASE")
+if [[ "$INIT" == @file:* ]]; then INIT=$(cat "${INIT#@file:}"); fi
+```
+
+Parse JSON for: `phase_dir`, `phase_number`, `phase_name`, `phase_slug`, `padded_phase`, `has_context`, `has_research`, `commit_docs`.
+
+**File paths:** `state_path`, `roadmap_path`, `requirements_path`, `context_path`.
+
+Resolve agent models:
+```bash
+SELECTOR_MODEL=$(gsd_run query resolve-model gsd-framework-selector 2>/dev/null | jq -r '.model' 2>/dev/null || true)
+RESEARCHER_MODEL=$(gsd_run query resolve-model gsd-ai-researcher 2>/dev/null | jq -r '.model' 2>/dev/null || true)
+DOMAIN_MODEL=$(gsd_run query resolve-model gsd-domain-researcher 2>/dev/null | jq -r '.model' 2>/dev/null || true)
+PLANNER_MODEL=$(gsd_run query resolve-model gsd-eval-planner 2>/dev/null | jq -r '.model' 2>/dev/null || true)
+```
+
+Check config:
+```bash
+AI_PHASE_ENABLED=$(gsd_run query config-get workflow.ai_integration_phase 2>/dev/null || echo "true")
+```
+
+**If `AI_PHASE_ENABLED` is `false`:**
+```
+AI phase is disabled in config. Enable via /gsd:settings.
+```
+Exit workflow.
+
+**If `planning_exists` is false:** Error — run `/gsd:new-project` first.
+
+## 2. Parse and Validate Phase
+
+Extract phase number from $ARGUMENTS. If not provided, detect next unplanned phase.
+
+```bash
+PHASE_INFO=$(gsd_run query roadmap.get-phase "${PHASE}")
+```
+
+**If `found` is false:** Error with available phases.
+
+## 3. Check Prerequisites
+
+**If `has_context` is false:**
+```
+No CONTEXT.md found for Phase {N}.
+Recommended: run /gsd:discuss-phase {N} first to capture framework preferences.
+Continuing without user decisions — framework selector will ask all questions.
+```
+Continue (non-blocking).
+
+## 4. Check Existing AI-SPEC
+
+```bash
+AI_SPEC_FILE=$(ls "${PHASE_DIR}"/*-AI-SPEC.md 2>/dev/null | head -1)
+```
+
+
+**Text mode (`workflow.text_mode: true` in config or `--text` flag):** Set `TEXT_MODE=true` if `--text` is present in `$ARGUMENTS` OR `text_mode` from init JSON is `true`. When TEXT_MODE is active, replace every `AskUserQuestion` call with a plain-text numbered list and ask the user to type their choice number. This is required for non-Claude runtimes (OpenAI Codex, Gemini CLI, etc.) where `AskUserQuestion` is not available.
+**If exists:** Use AskUserQuestion:
+- header: "Existing AI-SPEC"
+- question: "AI-SPEC.md already exists for Phase {N}. What would you like to do?"
+- options:
+  - "Update — re-run with existing as baseline"
+  - "View — display current AI-SPEC and exit"
+  - "Skip — keep current AI-SPEC and exit"
+
+If "View": display file contents, exit.
+If "Skip": exit.
+If "Update": continue to step 5.
+
+## 5. Spawn gsd-framework-selector
+
+Display:
+```
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+ GSD ► AI DESIGN CONTRACT — PHASE {N}: {name}
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+
+◆ Step 1/4 — Framework Selection...
+```
+
+Spawn `gsd-framework-selector` with:
+```markdown
+Read ~/.claude/agents/gsd-framework-selector.md for instructions.
+
+<objective>
+Select the right AI framework for Phase {phase_number}: {phase_name}
+Goal: {phase_goal}
+</objective>
+
+<files_to_read>
+{context_path if exists}
+{requirements_path if exists}
+</files_to_read>
+
+<phase_context>
+Phase: {phase_number} — {phase_name}
+Goal: {phase_goal}
+</phase_context>
+```
+
+Parse selector output for: `primary_framework`, `system_type`, `model_provider`, `eval_concerns`, `alternative_framework`.
+
+**If selector fails or returns empty:** Exit with error — "Framework selection failed. Re-run /gsd:ai-integration-phase {N} or answer the framework question in /gsd:discuss-phase {N} first."
+
+## 6. Initialize AI-SPEC.md
+
+Copy template:
+```bash
+cp "$HOME/.claude/get-shit-done/templates/AI-SPEC.md" "${PHASE_DIR}/${PADDED_PHASE}-AI-SPEC.md"
+```
+
+Fill in header fields:
+- Phase number and name
+- System classification (from selector)
+- Selected framework (from selector)
+- Alternative considered (from selector)
+
+## 7. Spawn gsd-ai-researcher
+
+> **Ordering note (prevents tool-level last-writer-wins race):** Steps 7 and 8 write disjoint sections of AI-SPEC.md but MUST run sequentially — wait for Step 7 to complete before spawning Step 8. Both agents use the `Edit` tool exclusively (never `Write`) when modifying AI-SPEC.md. A `Write` on a shared file replaces the entire file, silently overwriting the other agent's work; `Edit` targets only the relevant lines. See #3096 for a confirmed 40%-incidence race on parallel dispatch.
+
+Display:
+```
+◆ Step 2/4 — Researching {primary_framework} docs + AI systems best practices...
+```
+
+Spawn `gsd-ai-researcher` with:
+```markdown
+Read ~/.claude/agents/gsd-ai-researcher.md for instructions.
+
+**Tool discipline (mandatory):**
+Use the Edit tool exclusively when modifying AI-SPEC.md — NEVER use Write on this file.
+Write replaces the entire file and will overwrite work from parallel or sequential sibling agents.
+Before editing, verify the section you are about to write is still a template placeholder.
+
+<objective>
+</objective>
+
+<files_to_read>
+{ai_spec_path}
+{context_path if exists}
+</files_to_read>
+
+<input>
+framework: {primary_framework}
+system_type: {system_type}
+model_provider: {model_provider}
+ai_spec_path: {ai_spec_path}
+phase_context: Phase {phase_number}: {phase_name} — {phase_goal}
+</input>
+```
+
+## 8. Spawn gsd-domain-researcher
+
+> **Wait for Step 7 to complete before spawning this step** (see ordering note in Step 7).
+
+Display:
+```
+◆ Step 3/4 — Researching domain context and expert evaluation criteria...
+```
+
+Spawn `gsd-domain-researcher` with:
+```markdown
+Read ~/.claude/agents/gsd-domain-researcher.md for instructions.
+
+**Tool discipline (mandatory):**
+Use the Edit tool exclusively when modifying AI-SPEC.md — NEVER use Write on this file.
+Write replaces the entire file and will overwrite work from parallel or sequential sibling agents.
+Before editing, verify the section you are about to write is still a template placeholder.
+
+<objective>
+</objective>
+
+<files_to_read>
+{ai_spec_path}
+{context_path if exists}
+{requirements_path if exists}
+</files_to_read>
+
+<input>
+system_type: {system_type}
+phase_name: {phase_name}
+phase_goal: {phase_goal}
+ai_spec_path: {ai_spec_path}
+</input>
+```
+
+## 9. Spawn gsd-eval-planner
+
+Display:
+```
+◆ Step 4/4 — Designing evaluation strategy from domain + technical context...
+```
+
+Spawn `gsd-eval-planner` with:
+```markdown
+Read ~/.claude/agents/gsd-eval-planner.md for instructions.
+
+<objective>
+Design evaluation strategy for Phase {phase_number}: {phase_name}
+Write Sections 5, 6, and 7 of AI-SPEC.md
+AI-SPEC.md now contains domain context (Section 1b) — use it as your rubric starting point.
+</objective>
+
+<files_to_read>
+{ai_spec_path}
+{context_path if exists}
+{requirements_path if exists}
+</files_to_read>
+
+<input>
+system_type: {system_type}
+framework: {primary_framework}
+model_provider: {model_provider}
+phase_name: {phase_name}
+phase_goal: {phase_goal}
+ai_spec_path: {ai_spec_path}
+</input>
+```
+
+## 10. Validate AI-SPEC Completeness
+
+Read the completed AI-SPEC.md. Check that:
+- Section 2 has a framework name (not placeholder)
+- Section 1b has at least one domain rubric ingredient (Good/Bad/Stakes)
+- Section 3 has a non-empty code block (entry point pattern)
+- Section 4b has a Pydantic example
+- Section 5 has at least one row in the dimensions table
+- Section 6 has at least one guardrail or explicit "N/A for internal tool" note
+- Checklist section at end has 3+ items checked
+
+**If validation fails:** Display specific missing sections. Ask user if they want to re-run the specific step or continue anyway.
+
+## 11. Commit
+
+**If `commit_docs` is true:**
+```bash
+git add "${AI_SPEC_FILE}"
+git commit -m "docs({phase_slug}): generate AI-SPEC.md — {primary_framework} + domain context + eval strategy"
+```
+
+## 12. Display Completion
+
+```
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+ GSD ► AI-SPEC COMPLETE — PHASE {N}: {name}
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+
+◆ Framework: {primary_framework}
+◆ System Type: {system_type}
+◆ Domain: {domain_vertical from Section 1b}
+◆ Eval Dimensions: {eval_concerns}
+◆ Tracing Default: Arize Phoenix (or detected existing tool)
+◆ Output: {ai_spec_path}
+
+Next step:
+  /gsd:plan-phase {N}   — planner will consume AI-SPEC.md
+```
+
+</process>
+
+<success_criteria>
+- [ ] Framework selected with rationale (Section 2)
+- [ ] AI-SPEC.md created from template
+- [ ] Framework docs + AI best practices researched (Sections 3, 4, 4b populated)
+- [ ] Domain context + expert rubric ingredients researched (Section 1b populated)
+- [ ] Eval strategy grounded in domain context (Sections 5-7 populated)
+- [ ] Arize Phoenix (or detected tool) set as tracing default in Section 7
+- [ ] AI-SPEC.md validated (Sections 1b, 2, 3, 4b, 5, 6 all non-empty)
+- [ ] Committed if commit_docs enabled
+- [ ] Next step surfaced to user
+</success_criteria>

package/get-shit-done/workflows/analyze-dependencies.md

@@ -0,0 +1,96 @@
+<purpose>
+Analyze ROADMAP.md phases for dependency relationships before execution. Detect file overlap between phases, semantic API/data-flow dependencies, and suggest `Depends on` entries to prevent merge conflicts during parallel execution by `/gsd:manager`.
+</purpose>
+
+<process>
+
+## 1. Load ROADMAP.md
+
+Read `.planning/ROADMAP.md`. If it does not exist, error: "No ROADMAP.md found — run `/gsd:new-project` first."
+
+Extract all phases. For each phase capture:
+- Phase number and name
+- Scope/Goal description
+- Files listed in `Files` or `files_modified` fields (if present)
+- Existing `Depends on` field value
+
+## 2. Infer Likely File Modifications
+
+For each phase without explicit `files_modified`, analyze the scope/goal description to infer which files will likely be modified. Use these heuristics:
+
+- **Database/schema phases** → migration files, schema definitions, model files
+- **API/backend phases** → route files, controller files, service files, handler files
+- **Frontend/UI phases** → component files, page files, style files
+- **Auth phases** → middleware files, auth route files, session/token files
+- **Config/infra phases** → config files, environment files, CI/CD files
+- **Test phases** → test files, spec files, fixture files
+- **Shared utility phases** → lib/utils files, shared type definitions
+
+Group phases by their inferred file domain (database, API, frontend, auth, config, shared).
+
+## 3. Detect Dependency Relationships
+
+For each pair of phases (A, B), check for dependency signals:
+
+### File Overlap Detection
+If phases A and B will both modify files in the same domain or the same specific files, one must run before the other. The phase that *provides* the foundation runs first.
+
+### Semantic Dependency Detection
+Read each phase's scope/goal for these patterns:
+- Phase B mentions consuming, using, or calling something that Phase A creates/implements
+- Phase B references an "API", "schema", "model", "endpoint", or "interface" that Phase A builds
+- Phase B says "after X is complete", "once X is built", "using the X from Phase N"
+- Phase B extends or modifies code that Phase A establishes
+
+### Data Flow Detection
+- Phase A creates data structures, schemas, or types → Phase B consumes or transforms them
+- Phase A seeds/migrates the database → Phase B reads from that database
+- Phase A exposes an API contract → Phase B implements the client for that contract
+
+## 4. Build Dependency Table
+
+Output a dependency suggestion table:
+
+```
+Phase Dependency Analysis
+=========================
+
+Phase N: <name>
+  Scope: <brief scope>
+  Likely touches: <inferred file domains>
+
+  Suggested dependencies:
+  → Depends on: <Phase M> — reason: <overlap/semantic/data-flow explanation>
+
+  Current "Depends on": <existing value or "(none)">
+```
+
+For phase pairs with no detected dependency, state: "No dependency detected between Phase X and Phase Y."
+
+## 5. Summarize Suggested Changes
+
+Show a consolidated diff of proposed ROADMAP.md `Depends on` changes:
+
+```
+Suggested ROADMAP.md updates:
+  Phase 3: add "Depends on: 1, 2"   (file overlap: database schema)
+  Phase 5: add "Depends on: 3"      (semantic: uses auth API from Phase 3)
+  Phase 4: no change needed         (independent scope)
+```
+
+## 6. Confirm and Apply
+
+Ask the user: "Apply these `Depends on` suggestions to ROADMAP.md? (yes / no / edit)"
+
+- **yes** — Write all suggested `Depends on` entries to ROADMAP.md. Confirm each write.
+- **no** — Print the suggestions as text only. User updates manually.
+- **edit** — Present each suggestion individually with yes/no/skip per suggestion.
+
+When writing to ROADMAP.md:
+- Locate the phase entry and add or update the `Depends on:` field
+- Preserve all other phase content unchanged
+- Do not reorder phases
+
+After applying: "ROADMAP.md updated. Run `/gsd:manager` to execute phases in the correct order."
+
+</process>