chore: initial backup of Claude Code configuration
Includes: CLAUDE.md, settings.json, agents, commands, rules, skills, hooks, contexts, evals, get-shit-done, plugin configs (installed list and marketplace sources). Excludes credentials, runtime caches, telemetry, session data, and plugin binary cache.
This commit is contained in:
Yaojia Wang
112
get-shit-done/workflows/add-phase.md
Normal file
112
get-shit-done/workflows/add-phase.md
Normal file
@@ -0,0 +1,112 @@
|
||||
<purpose>
|
||||
Add a new integer phase to the end of the current milestone in the roadmap. Automatically calculates next phase number, creates phase directory, and updates roadmap structure.
|
||||
</purpose>
|
||||
|
||||
<required_reading>
|
||||
Read all files referenced by the invoking prompt's execution_context before starting.
|
||||
</required_reading>
|
||||
|
||||
<process>
|
||||
|
||||
<step name="parse_arguments">
|
||||
Parse the command arguments:
|
||||
- All arguments become the phase description
|
||||
- Example: `/gsd:add-phase Add authentication` → description = "Add authentication"
|
||||
- Example: `/gsd:add-phase Fix critical performance issues` → description = "Fix critical performance issues"
|
||||
|
||||
If no arguments provided:
|
||||
|
||||
```
|
||||
ERROR: Phase description required
|
||||
Usage: /gsd:add-phase <description>
|
||||
Example: /gsd:add-phase Add authentication system
|
||||
```
|
||||
|
||||
Exit.
|
||||
</step>
|
||||
|
||||
<step name="init_context">
|
||||
Load phase operation context:
|
||||
|
||||
```bash
|
||||
INIT=$(node "C:/Users/yaoji/.claude/get-shit-done/bin/gsd-tools.cjs" init phase-op "0")
|
||||
if [[ "$INIT" == @file:* ]]; then INIT=$(cat "${INIT#@file:}"); fi
|
||||
```
|
||||
|
||||
Check `roadmap_exists` from init JSON. If false:
|
||||
```
|
||||
ERROR: No roadmap found (.planning/ROADMAP.md)
|
||||
Run /gsd:new-project to initialize.
|
||||
```
|
||||
Exit.
|
||||
</step>
|
||||
|
||||
<step name="add_phase">
|
||||
**Delegate the phase addition to gsd-tools:**
|
||||
|
||||
```bash
|
||||
RESULT=$(node "C:/Users/yaoji/.claude/get-shit-done/bin/gsd-tools.cjs" phase add "${description}")
|
||||
```
|
||||
|
||||
The CLI handles:
|
||||
- Finding the highest existing integer phase number
|
||||
- Calculating next phase number (max + 1)
|
||||
- Generating slug from description
|
||||
- Creating the phase directory (`.planning/phases/{NN}-{slug}/`)
|
||||
- Inserting the phase entry into ROADMAP.md with Goal, Depends on, and Plans sections
|
||||
|
||||
Extract from result: `phase_number`, `padded`, `name`, `slug`, `directory`.
|
||||
</step>
|
||||
|
||||
<step name="update_project_state">
|
||||
Update STATE.md to reflect the new phase:
|
||||
|
||||
1. Read `.planning/STATE.md`
|
||||
2. Under "## Accumulated Context" → "### Roadmap Evolution" add entry:
|
||||
```
|
||||
- Phase {N} added: {description}
|
||||
```
|
||||
|
||||
If "Roadmap Evolution" section doesn't exist, create it.
|
||||
</step>
|
||||
|
||||
<step name="completion">
|
||||
Present completion summary:
|
||||
|
||||
```
|
||||
Phase {N} added to current milestone:
|
||||
- Description: {description}
|
||||
- Directory: .planning/phases/{phase-num}-{slug}/
|
||||
- Status: Not planned yet
|
||||
|
||||
Roadmap updated: .planning/ROADMAP.md
|
||||
|
||||
---
|
||||
|
||||
## ▶ Next Up
|
||||
|
||||
**Phase {N}: {description}**
|
||||
|
||||
`/gsd:plan-phase {N}`
|
||||
|
||||
<sub>`/clear` first → fresh context window</sub>
|
||||
|
||||
---
|
||||
|
||||
**Also available:**
|
||||
- `/gsd:add-phase <description>` — add another phase
|
||||
- Review roadmap
|
||||
|
||||
---
|
||||
```
|
||||
</step>
|
||||
|
||||
</process>
|
||||
|
||||
<success_criteria>
|
||||
- [ ] `gsd-tools phase add` executed successfully
|
||||
- [ ] Phase directory created
|
||||
- [ ] Roadmap updated with new phase entry
|
||||
- [ ] STATE.md updated with roadmap evolution note
|
||||
- [ ] User informed of next steps
|
||||
</success_criteria>
|
||||
351
get-shit-done/workflows/add-tests.md
Normal file
351
get-shit-done/workflows/add-tests.md
Normal file
@@ -0,0 +1,351 @@
|
||||
<purpose>
|
||||
Generate unit and E2E tests for a completed phase based on its SUMMARY.md, CONTEXT.md, and implementation. Classifies each changed file into TDD (unit), E2E (browser), or Skip categories, presents a test plan for user approval, then generates tests following RED-GREEN conventions.
|
||||
|
||||
Users currently hand-craft `/gsd:quick` prompts for test generation after each phase. This workflow standardizes the process with proper classification, quality gates, and gap reporting.
|
||||
</purpose>
|
||||
|
||||
<required_reading>
|
||||
Read all files referenced by the invoking prompt's execution_context before starting.
|
||||
</required_reading>
|
||||
|
||||
<process>
|
||||
|
||||
<step name="parse_arguments">
|
||||
Parse `$ARGUMENTS` for:
|
||||
- Phase number (integer, decimal, or letter-suffix) → store as `$PHASE_ARG`
|
||||
- Remaining text after phase number → store as `$EXTRA_INSTRUCTIONS` (optional)
|
||||
|
||||
Example: `/gsd:add-tests 12 focus on edge cases` → `$PHASE_ARG=12`, `$EXTRA_INSTRUCTIONS="focus on edge cases"`
|
||||
|
||||
If no phase argument provided:
|
||||
|
||||
```
|
||||
ERROR: Phase number required
|
||||
Usage: /gsd:add-tests <phase> [additional instructions]
|
||||
Example: /gsd:add-tests 12
|
||||
Example: /gsd:add-tests 12 focus on edge cases in the pricing module
|
||||
```
|
||||
|
||||
Exit.
|
||||
</step>
|
||||
|
||||
<step name="init_context">
|
||||
Load phase operation context:
|
||||
|
||||
```bash
|
||||
INIT=$(node "C:/Users/yaoji/.claude/get-shit-done/bin/gsd-tools.cjs" init phase-op "${PHASE_ARG}")
|
||||
if [[ "$INIT" == @file:* ]]; then INIT=$(cat "${INIT#@file:}"); fi
|
||||
```
|
||||
|
||||
Extract from init JSON: `phase_dir`, `phase_number`, `phase_name`.
|
||||
|
||||
Verify the phase directory exists. If not:
|
||||
```
|
||||
ERROR: Phase directory not found for phase ${PHASE_ARG}
|
||||
Ensure the phase exists in .planning/phases/
|
||||
```
|
||||
Exit.
|
||||
|
||||
Read the phase artifacts (in order of priority):
|
||||
1. `${phase_dir}/*-SUMMARY.md` — what was implemented, files changed
|
||||
2. `${phase_dir}/CONTEXT.md` — acceptance criteria, decisions
|
||||
3. `${phase_dir}/*-VERIFICATION.md` — user-verified scenarios (if UAT was done)
|
||||
|
||||
If no SUMMARY.md exists:
|
||||
```
|
||||
ERROR: No SUMMARY.md found for phase ${PHASE_ARG}
|
||||
This command works on completed phases. Run /gsd:execute-phase first.
|
||||
```
|
||||
Exit.
|
||||
|
||||
Present banner:
|
||||
```
|
||||
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
|
||||
GSD ► ADD TESTS — Phase ${phase_number}: ${phase_name}
|
||||
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
|
||||
```
|
||||
</step>
|
||||
|
||||
<step name="analyze_implementation">
|
||||
Extract the list of files modified by the phase from SUMMARY.md ("Files Changed" or equivalent section).
|
||||
|
||||
For each file, classify into one of three categories:
|
||||
|
||||
| Category | Criteria | Test Type |
|
||||
|----------|----------|-----------|
|
||||
| **TDD** | Pure functions where `expect(fn(input)).toBe(output)` is writable | Unit tests |
|
||||
| **E2E** | UI behavior verifiable by browser automation | Playwright/E2E tests |
|
||||
| **Skip** | Not meaningfully testable or already covered | None |
|
||||
|
||||
**TDD classification — apply when:**
|
||||
- Business logic: calculations, pricing, tax rules, validation
|
||||
- Data transformations: mapping, filtering, aggregation, formatting
|
||||
- Parsers: CSV, JSON, XML, custom format parsing
|
||||
- Validators: input validation, schema validation, business rules
|
||||
- State machines: status transitions, workflow steps
|
||||
- Utilities: string manipulation, date handling, number formatting
|
||||
|
||||
**E2E classification — apply when:**
|
||||
- Keyboard shortcuts: key bindings, modifier keys, chord sequences
|
||||
- Navigation: page transitions, routing, breadcrumbs, back/forward
|
||||
- Form interactions: submit, validation errors, field focus, autocomplete
|
||||
- Selection: row selection, multi-select, shift-click ranges
|
||||
- Drag and drop: reordering, moving between containers
|
||||
- Modal dialogs: open, close, confirm, cancel
|
||||
- Data grids: sorting, filtering, inline editing, column resize
|
||||
|
||||
**Skip classification — apply when:**
|
||||
- UI layout/styling: CSS classes, visual appearance, responsive breakpoints
|
||||
- Configuration: config files, environment variables, feature flags
|
||||
- Glue code: dependency injection setup, middleware registration, routing tables
|
||||
- Migrations: database migrations, schema changes
|
||||
- Simple CRUD: basic create/read/update/delete with no business logic
|
||||
- Type definitions: records, DTOs, interfaces with no logic
|
||||
|
||||
Read each file to verify classification. Don't classify based on filename alone.
|
||||
</step>
|
||||
|
||||
<step name="present_classification">
|
||||
Present the classification to the user for confirmation before proceeding:
|
||||
|
||||
```
|
||||
AskUserQuestion(
|
||||
header: "Test Classification",
|
||||
question: |
|
||||
## Files classified for testing
|
||||
|
||||
### TDD (Unit Tests) — {N} files
|
||||
{list of files with brief reason}
|
||||
|
||||
### E2E (Browser Tests) — {M} files
|
||||
{list of files with brief reason}
|
||||
|
||||
### Skip — {K} files
|
||||
{list of files with brief reason}
|
||||
|
||||
{if $EXTRA_INSTRUCTIONS: "Additional instructions: ${EXTRA_INSTRUCTIONS}"}
|
||||
|
||||
How would you like to proceed?
|
||||
options:
|
||||
- "Approve and generate test plan"
|
||||
- "Adjust classification (I'll specify changes)"
|
||||
- "Cancel"
|
||||
)
|
||||
```
|
||||
|
||||
If user selects "Adjust classification": apply their changes and re-present.
|
||||
If user selects "Cancel": exit gracefully.
|
||||
</step>
|
||||
|
||||
<step name="discover_test_structure">
|
||||
Before generating the test plan, discover the project's existing test structure:
|
||||
|
||||
```bash
|
||||
# Find existing test directories
|
||||
find . -type d -name "*test*" -o -name "*spec*" -o -name "*__tests__*" 2>/dev/null | head -20
|
||||
# Find existing test files for convention matching
|
||||
find . -type f \( -name "*.test.*" -o -name "*.spec.*" -o -name "*Tests.fs" -o -name "*Test.fs" \) 2>/dev/null | head -20
|
||||
# Check for test runners
|
||||
ls package.json *.sln 2>/dev/null
|
||||
```
|
||||
|
||||
Identify:
|
||||
- Test directory structure (where unit tests live, where E2E tests live)
|
||||
- Naming conventions (`.test.ts`, `.spec.ts`, `*Tests.fs`, etc.)
|
||||
- Test runner commands (how to execute unit tests, how to execute E2E tests)
|
||||
- Test framework (xUnit, NUnit, Jest, Playwright, etc.)
|
||||
|
||||
If test structure is ambiguous, ask the user:
|
||||
```
|
||||
AskUserQuestion(
|
||||
header: "Test Structure",
|
||||
question: "I found multiple test locations. Where should I create tests?",
|
||||
options: [list discovered locations]
|
||||
)
|
||||
```
|
||||
</step>
|
||||
|
||||
<step name="generate_test_plan">
|
||||
For each approved file, create a detailed test plan.
|
||||
|
||||
**For TDD files**, plan tests following RED-GREEN-REFACTOR:
|
||||
1. Identify testable functions/methods in the file
|
||||
2. For each function: list input scenarios, expected outputs, edge cases
|
||||
3. Note: since code already exists, tests may pass immediately — that's OK, but verify they test the RIGHT behavior
|
||||
|
||||
**For E2E files**, plan tests following RED-GREEN gates:
|
||||
1. Identify user scenarios from CONTEXT.md/VERIFICATION.md
|
||||
2. For each scenario: describe the user action, expected outcome, assertions
|
||||
3. Note: RED gate means confirming the test would fail if the feature were broken
|
||||
|
||||
Present the complete test plan:
|
||||
|
||||
```
|
||||
AskUserQuestion(
|
||||
header: "Test Plan",
|
||||
question: |
|
||||
## Test Generation Plan
|
||||
|
||||
### Unit Tests ({N} tests across {M} files)
|
||||
{for each file: test file path, list of test cases}
|
||||
|
||||
### E2E Tests ({P} tests across {Q} files)
|
||||
{for each file: test file path, list of test scenarios}
|
||||
|
||||
### Test Commands
|
||||
- Unit: {discovered test command}
|
||||
- E2E: {discovered e2e command}
|
||||
|
||||
Ready to generate?
|
||||
options:
|
||||
- "Generate all"
|
||||
- "Cherry-pick (I'll specify which)"
|
||||
- "Adjust plan"
|
||||
)
|
||||
```
|
||||
|
||||
If "Cherry-pick": ask user which tests to include.
|
||||
If "Adjust plan": apply changes and re-present.
|
||||
</step>
|
||||
|
||||
<step name="execute_tdd_generation">
|
||||
For each approved TDD test:
|
||||
|
||||
1. **Create test file** following discovered project conventions (directory, naming, imports)
|
||||
|
||||
2. **Write test** with clear arrange/act/assert structure:
|
||||
```
|
||||
// Arrange — set up inputs and expected outputs
|
||||
// Act — call the function under test
|
||||
// Assert — verify the output matches expectations
|
||||
```
|
||||
|
||||
3. **Run the test**:
|
||||
```bash
|
||||
{discovered test command}
|
||||
```
|
||||
|
||||
4. **Evaluate result:**
|
||||
- **Test passes**: Good — the implementation satisfies the test. Verify the test checks meaningful behavior (not just that it compiles).
|
||||
- **Test fails with assertion error**: This may be a genuine bug discovered by the test. Flag it:
|
||||
```
|
||||
⚠️ Potential bug found: {test name}
|
||||
Expected: {expected}
|
||||
Actual: {actual}
|
||||
File: {implementation file}
|
||||
```
|
||||
Do NOT fix the implementation — this is a test-generation command, not a fix command. Record the finding.
|
||||
- **Test fails with error (import, syntax, etc.)**: This is a test error. Fix the test and re-run.
|
||||
</step>
|
||||
|
||||
<step name="execute_e2e_generation">
|
||||
For each approved E2E test:
|
||||
|
||||
1. **Check for existing tests** covering the same scenario:
|
||||
```bash
|
||||
grep -r "{scenario keyword}" {e2e test directory} 2>/dev/null
|
||||
```
|
||||
If found, extend rather than duplicate.
|
||||
|
||||
2. **Create test file** targeting the user scenario from CONTEXT.md/VERIFICATION.md
|
||||
|
||||
3. **Run the E2E test**:
|
||||
```bash
|
||||
{discovered e2e command}
|
||||
```
|
||||
|
||||
4. **Evaluate result:**
|
||||
- **GREEN (passes)**: Record success
|
||||
- **RED (fails)**: Determine if it's a test issue or a genuine application bug. Flag bugs:
|
||||
```
|
||||
⚠️ E2E failure: {test name}
|
||||
Scenario: {description}
|
||||
Error: {error message}
|
||||
```
|
||||
- **Cannot run**: Report blocker. Do NOT mark as complete.
|
||||
```
|
||||
🛑 E2E blocker: {reason tests cannot run}
|
||||
```
|
||||
|
||||
**No-skip rule:** If E2E tests cannot execute (missing dependencies, environment issues), report the blocker and mark the test as incomplete. Never mark success without actually running the test.
|
||||
</step>
|
||||
|
||||
<step name="summary_and_commit">
|
||||
Create a test coverage report and present to user:
|
||||
|
||||
```
|
||||
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
|
||||
GSD ► TEST GENERATION COMPLETE
|
||||
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
|
||||
|
||||
## Results
|
||||
|
||||
| Category | Generated | Passing | Failing | Blocked |
|
||||
|----------|-----------|---------|---------|---------|
|
||||
| Unit | {N} | {n1} | {n2} | {n3} |
|
||||
| E2E | {M} | {m1} | {m2} | {m3} |
|
||||
|
||||
## Files Created/Modified
|
||||
{list of test files with paths}
|
||||
|
||||
## Coverage Gaps
|
||||
{areas that couldn't be tested and why}
|
||||
|
||||
## Bugs Discovered
|
||||
{any assertion failures that indicate implementation bugs}
|
||||
```
|
||||
|
||||
Record test generation in project state:
|
||||
```bash
|
||||
node "C:/Users/yaoji/.claude/get-shit-done/bin/gsd-tools.cjs" state-snapshot
|
||||
```
|
||||
|
||||
If there are passing tests to commit:
|
||||
|
||||
```bash
|
||||
git add {test files}
|
||||
git commit -m "test(phase-${phase_number}): add unit and E2E tests from add-tests command"
|
||||
```
|
||||
|
||||
Present next steps:
|
||||
|
||||
```
|
||||
---
|
||||
|
||||
## ▶ Next Up
|
||||
|
||||
{if bugs discovered:}
|
||||
**Fix discovered bugs:** `/gsd:quick fix the {N} test failures discovered in phase ${phase_number}`
|
||||
|
||||
{if blocked tests:}
|
||||
**Resolve test blockers:** {description of what's needed}
|
||||
|
||||
{otherwise:}
|
||||
**All tests passing!** Phase ${phase_number} is fully tested.
|
||||
|
||||
---
|
||||
|
||||
**Also available:**
|
||||
- `/gsd:add-tests {next_phase}` — test another phase
|
||||
- `/gsd:verify-work {phase_number}` — run UAT verification
|
||||
|
||||
---
|
||||
```
|
||||
</step>
|
||||
|
||||
</process>
|
||||
|
||||
<success_criteria>
|
||||
- [ ] Phase artifacts loaded (SUMMARY.md, CONTEXT.md, optionally VERIFICATION.md)
|
||||
- [ ] All changed files classified into TDD/E2E/Skip categories
|
||||
- [ ] Classification presented to user and approved
|
||||
- [ ] Project test structure discovered (directories, conventions, runners)
|
||||
- [ ] Test plan presented to user and approved
|
||||
- [ ] TDD tests generated with arrange/act/assert structure
|
||||
- [ ] E2E tests generated targeting user scenarios
|
||||
- [ ] All tests executed — no untested tests marked as passing
|
||||
- [ ] Bugs discovered by tests flagged (not fixed)
|
||||
- [ ] Test files committed with proper message
|
||||
- [ ] Coverage gaps documented
|
||||
- [ ] Next steps presented to user
|
||||
</success_criteria>
|
||||
158
get-shit-done/workflows/add-todo.md
Normal file
158
get-shit-done/workflows/add-todo.md
Normal file
@@ -0,0 +1,158 @@
|
||||
<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
|
||||
INIT=$(node "C:/Users/yaoji/.claude/get-shit-done/bin/gsd-tools.cjs" 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/done
|
||||
```
|
||||
|
||||
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
|
||||
```
|
||||
|
||||
If potential duplicate found:
|
||||
1. Read the existing todo
|
||||
2. Compare scope
|
||||
|
||||
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=$(node "C:/Users/yaoji/.claude/get-shit-done/bin/gsd-tools.cjs" 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
|
||||
node "C:/Users/yaoji/.claude/get-shit-done/bin/gsd-tools.cjs" 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:check-todos)
|
||||
```
|
||||
</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>
|
||||
332
get-shit-done/workflows/audit-milestone.md
Normal file
332
get-shit-done/workflows/audit-milestone.md
Normal file
@@ -0,0 +1,332 @@
|
||||
<purpose>
|
||||
Verify milestone achieved its definition of done by aggregating phase verifications, checking cross-phase integration, and assessing requirements coverage. Reads existing VERIFICATION.md files (phases already verified during execute-phase), aggregates tech debt and deferred gaps, then spawns integration checker for cross-phase wiring.
|
||||
</purpose>
|
||||
|
||||
<required_reading>
|
||||
Read all files referenced by the invoking prompt's execution_context before starting.
|
||||
</required_reading>
|
||||
|
||||
<process>
|
||||
|
||||
## 0. Initialize Milestone Context
|
||||
|
||||
```bash
|
||||
INIT=$(node "C:/Users/yaoji/.claude/get-shit-done/bin/gsd-tools.cjs" init milestone-op)
|
||||
if [[ "$INIT" == @file:* ]]; then INIT=$(cat "${INIT#@file:}"); fi
|
||||
```
|
||||
|
||||
Extract from init JSON: `milestone_version`, `milestone_name`, `phase_count`, `completed_phases`, `commit_docs`.
|
||||
|
||||
Resolve integration checker model:
|
||||
```bash
|
||||
integration_checker_model=$(node "C:/Users/yaoji/.claude/get-shit-done/bin/gsd-tools.cjs" resolve-model gsd-integration-checker --raw)
|
||||
```
|
||||
|
||||
## 1. Determine Milestone Scope
|
||||
|
||||
```bash
|
||||
# Get phases in milestone (sorted numerically, handles decimals)
|
||||
node "C:/Users/yaoji/.claude/get-shit-done/bin/gsd-tools.cjs" phases list
|
||||
```
|
||||
|
||||
- Parse version from arguments or detect current from ROADMAP.md
|
||||
- Identify all phase directories in scope
|
||||
- Extract milestone definition of done from ROADMAP.md
|
||||
- Extract requirements mapped to this milestone from REQUIREMENTS.md
|
||||
|
||||
## 2. Read All Phase Verifications
|
||||
|
||||
For each phase directory, read the VERIFICATION.md:
|
||||
|
||||
```bash
|
||||
# For each phase, use find-phase to resolve the directory (handles archived phases)
|
||||
PHASE_INFO=$(node "C:/Users/yaoji/.claude/get-shit-done/bin/gsd-tools.cjs" find-phase 01 --raw)
|
||||
# Extract directory from JSON, then read VERIFICATION.md from that directory
|
||||
# Repeat for each phase number from ROADMAP.md
|
||||
```
|
||||
|
||||
From each VERIFICATION.md, extract:
|
||||
- **Status:** passed | gaps_found
|
||||
- **Critical gaps:** (if any — these are blockers)
|
||||
- **Non-critical gaps:** tech debt, deferred items, warnings
|
||||
- **Anti-patterns found:** TODOs, stubs, placeholders
|
||||
- **Requirements coverage:** which requirements satisfied/blocked
|
||||
|
||||
If a phase is missing VERIFICATION.md, flag it as "unverified phase" — this is a blocker.
|
||||
|
||||
## 3. Spawn Integration Checker
|
||||
|
||||
With phase context collected:
|
||||
|
||||
Extract `MILESTONE_REQ_IDS` from REQUIREMENTS.md traceability table — all REQ-IDs assigned to phases in this milestone.
|
||||
|
||||
```
|
||||
Task(
|
||||
prompt="Check cross-phase integration and E2E flows.
|
||||
|
||||
Phases: {phase_dirs}
|
||||
Phase exports: {from SUMMARYs}
|
||||
API routes: {routes created}
|
||||
|
||||
Milestone Requirements:
|
||||
{MILESTONE_REQ_IDS — list each REQ-ID with description and assigned phase}
|
||||
|
||||
MUST map each integration finding to affected requirement IDs where applicable.
|
||||
|
||||
Verify cross-phase wiring and E2E user flows.",
|
||||
subagent_type="gsd-integration-checker",
|
||||
model="{integration_checker_model}"
|
||||
)
|
||||
```
|
||||
|
||||
## 4. Collect Results
|
||||
|
||||
Combine:
|
||||
- Phase-level gaps and tech debt (from step 2)
|
||||
- Integration checker's report (wiring gaps, broken flows)
|
||||
|
||||
## 5. Check Requirements Coverage (3-Source Cross-Reference)
|
||||
|
||||
MUST cross-reference three independent sources for each requirement:
|
||||
|
||||
### 5a. Parse REQUIREMENTS.md Traceability Table
|
||||
|
||||
Extract all REQ-IDs mapped to milestone phases from the traceability table:
|
||||
- Requirement ID, description, assigned phase, current status, checked-off state (`[x]` vs `[ ]`)
|
||||
|
||||
### 5b. Parse Phase VERIFICATION.md Requirements Tables
|
||||
|
||||
For each phase's VERIFICATION.md, extract the expanded requirements table:
|
||||
- Requirement | Source Plan | Description | Status | Evidence
|
||||
- Map each entry back to its REQ-ID
|
||||
|
||||
### 5c. Extract SUMMARY.md Frontmatter Cross-Check
|
||||
|
||||
For each phase's SUMMARY.md, extract `requirements-completed` from YAML frontmatter:
|
||||
```bash
|
||||
for summary in .planning/phases/*-*/*-SUMMARY.md; do
|
||||
node "C:/Users/yaoji/.claude/get-shit-done/bin/gsd-tools.cjs" summary-extract "$summary" --fields requirements_completed | jq -r '.requirements_completed'
|
||||
done
|
||||
```
|
||||
|
||||
### 5d. Status Determination Matrix
|
||||
|
||||
For each REQ-ID, determine status using all three sources:
|
||||
|
||||
| VERIFICATION.md Status | SUMMARY Frontmatter | REQUIREMENTS.md | → Final Status |
|
||||
|------------------------|---------------------|-----------------|----------------|
|
||||
| passed | listed | `[x]` | **satisfied** |
|
||||
| passed | listed | `[ ]` | **satisfied** (update checkbox) |
|
||||
| passed | missing | any | **partial** (verify manually) |
|
||||
| gaps_found | any | any | **unsatisfied** |
|
||||
| missing | listed | any | **partial** (verification gap) |
|
||||
| missing | missing | any | **unsatisfied** |
|
||||
|
||||
### 5e. FAIL Gate and Orphan Detection
|
||||
|
||||
**REQUIRED:** Any `unsatisfied` requirement MUST force `gaps_found` status on the milestone audit.
|
||||
|
||||
**Orphan detection:** Requirements present in REQUIREMENTS.md traceability table but absent from ALL phase VERIFICATION.md files MUST be flagged as orphaned. Orphaned requirements are treated as `unsatisfied` — they were assigned but never verified by any phase.
|
||||
|
||||
## 5.5. Nyquist Compliance Discovery
|
||||
|
||||
Skip if `workflow.nyquist_validation` is explicitly `false` (absent = enabled).
|
||||
|
||||
```bash
|
||||
NYQUIST_CONFIG=$(node "C:/Users/yaoji/.claude/get-shit-done/bin/gsd-tools.cjs" config get workflow.nyquist_validation --raw 2>/dev/null)
|
||||
```
|
||||
|
||||
If `false`: skip entirely.
|
||||
|
||||
For each phase directory, check `*-VALIDATION.md`. If exists, parse frontmatter (`nyquist_compliant`, `wave_0_complete`).
|
||||
|
||||
Classify per phase:
|
||||
|
||||
| Status | Condition |
|
||||
|--------|-----------|
|
||||
| COMPLIANT | `nyquist_compliant: true` and all tasks green |
|
||||
| PARTIAL | VALIDATION.md exists, `nyquist_compliant: false` or red/pending |
|
||||
| MISSING | No VALIDATION.md |
|
||||
|
||||
Add to audit YAML: `nyquist: { compliant_phases, partial_phases, missing_phases, overall }`
|
||||
|
||||
Discovery only — never auto-calls `/gsd:validate-phase`.
|
||||
|
||||
## 6. Aggregate into v{version}-MILESTONE-AUDIT.md
|
||||
|
||||
Create `.planning/v{version}-v{version}-MILESTONE-AUDIT.md` with:
|
||||
|
||||
```yaml
|
||||
---
|
||||
milestone: {version}
|
||||
audited: {timestamp}
|
||||
status: passed | gaps_found | tech_debt
|
||||
scores:
|
||||
requirements: N/M
|
||||
phases: N/M
|
||||
integration: N/M
|
||||
flows: N/M
|
||||
gaps: # Critical blockers
|
||||
requirements:
|
||||
- id: "{REQ-ID}"
|
||||
status: "unsatisfied | partial | orphaned"
|
||||
phase: "{assigned phase}"
|
||||
claimed_by_plans: ["{plan files that reference this requirement}"]
|
||||
completed_by_plans: ["{plan files whose SUMMARY marks it complete}"]
|
||||
verification_status: "passed | gaps_found | missing | orphaned"
|
||||
evidence: "{specific evidence or lack thereof}"
|
||||
integration: [...]
|
||||
flows: [...]
|
||||
tech_debt: # Non-critical, deferred
|
||||
- phase: 01-auth
|
||||
items:
|
||||
- "TODO: add rate limiting"
|
||||
- "Warning: no password strength validation"
|
||||
- phase: 03-dashboard
|
||||
items:
|
||||
- "Deferred: mobile responsive layout"
|
||||
---
|
||||
```
|
||||
|
||||
Plus full markdown report with tables for requirements, phases, integration, tech debt.
|
||||
|
||||
**Status values:**
|
||||
- `passed` — all requirements met, no critical gaps, minimal tech debt
|
||||
- `gaps_found` — critical blockers exist
|
||||
- `tech_debt` — no blockers but accumulated deferred items need review
|
||||
|
||||
## 7. Present Results
|
||||
|
||||
Route by status (see `<offer_next>`).
|
||||
|
||||
</process>
|
||||
|
||||
<offer_next>
|
||||
Output this markdown directly (not as a code block). Route based on status:
|
||||
|
||||
---
|
||||
|
||||
**If passed:**
|
||||
|
||||
## ✓ Milestone {version} — Audit Passed
|
||||
|
||||
**Score:** {N}/{M} requirements satisfied
|
||||
**Report:** .planning/v{version}-MILESTONE-AUDIT.md
|
||||
|
||||
All requirements covered. Cross-phase integration verified. E2E flows complete.
|
||||
|
||||
───────────────────────────────────────────────────────────────
|
||||
|
||||
## ▶ Next Up
|
||||
|
||||
**Complete milestone** — archive and tag
|
||||
|
||||
/gsd:complete-milestone {version}
|
||||
|
||||
<sub>/clear first → fresh context window</sub>
|
||||
|
||||
───────────────────────────────────────────────────────────────
|
||||
|
||||
---
|
||||
|
||||
**If gaps_found:**
|
||||
|
||||
## ⚠ Milestone {version} — Gaps Found
|
||||
|
||||
**Score:** {N}/{M} requirements satisfied
|
||||
**Report:** .planning/v{version}-MILESTONE-AUDIT.md
|
||||
|
||||
### Unsatisfied Requirements
|
||||
|
||||
{For each unsatisfied requirement:}
|
||||
- **{REQ-ID}: {description}** (Phase {X})
|
||||
- {reason}
|
||||
|
||||
### Cross-Phase Issues
|
||||
|
||||
{For each integration gap:}
|
||||
- **{from} → {to}:** {issue}
|
||||
|
||||
### Broken Flows
|
||||
|
||||
{For each flow gap:}
|
||||
- **{flow name}:** breaks at {step}
|
||||
|
||||
### Nyquist Coverage
|
||||
|
||||
| Phase | VALIDATION.md | Compliant | Action |
|
||||
|-------|---------------|-----------|--------|
|
||||
| {phase} | exists/missing | true/false/partial | `/gsd:validate-phase {N}` |
|
||||
|
||||
Phases needing validation: run `/gsd:validate-phase {N}` for each flagged phase.
|
||||
|
||||
───────────────────────────────────────────────────────────────
|
||||
|
||||
## ▶ Next Up
|
||||
|
||||
**Plan gap closure** — create phases to complete milestone
|
||||
|
||||
/gsd:plan-milestone-gaps
|
||||
|
||||
<sub>/clear first → fresh context window</sub>
|
||||
|
||||
───────────────────────────────────────────────────────────────
|
||||
|
||||
**Also available:**
|
||||
- cat .planning/v{version}-MILESTONE-AUDIT.md — see full report
|
||||
- /gsd:complete-milestone {version} — proceed anyway (accept tech debt)
|
||||
|
||||
───────────────────────────────────────────────────────────────
|
||||
|
||||
---
|
||||
|
||||
**If tech_debt (no blockers but accumulated debt):**
|
||||
|
||||
## ⚡ Milestone {version} — Tech Debt Review
|
||||
|
||||
**Score:** {N}/{M} requirements satisfied
|
||||
**Report:** .planning/v{version}-MILESTONE-AUDIT.md
|
||||
|
||||
All requirements met. No critical blockers. Accumulated tech debt needs review.
|
||||
|
||||
### Tech Debt by Phase
|
||||
|
||||
{For each phase with debt:}
|
||||
**Phase {X}: {name}**
|
||||
- {item 1}
|
||||
- {item 2}
|
||||
|
||||
### Total: {N} items across {M} phases
|
||||
|
||||
───────────────────────────────────────────────────────────────
|
||||
|
||||
## ▶ Options
|
||||
|
||||
**A. Complete milestone** — accept debt, track in backlog
|
||||
|
||||
/gsd:complete-milestone {version}
|
||||
|
||||
**B. Plan cleanup phase** — address debt before completing
|
||||
|
||||
/gsd:plan-milestone-gaps
|
||||
|
||||
<sub>/clear first → fresh context window</sub>
|
||||
|
||||
───────────────────────────────────────────────────────────────
|
||||
</offer_next>
|
||||
|
||||
<success_criteria>
|
||||
- [ ] Milestone scope identified
|
||||
- [ ] All phase VERIFICATION.md files read
|
||||
- [ ] SUMMARY.md `requirements-completed` frontmatter extracted for each phase
|
||||
- [ ] REQUIREMENTS.md traceability table parsed for all milestone REQ-IDs
|
||||
- [ ] 3-source cross-reference completed (VERIFICATION + SUMMARY + traceability)
|
||||
- [ ] Orphaned requirements detected (in traceability but absent from all VERIFICATIONs)
|
||||
- [ ] Tech debt and deferred gaps aggregated
|
||||
- [ ] Integration checker spawned with milestone requirement IDs
|
||||
- [ ] v{version}-MILESTONE-AUDIT.md created with structured requirement gap objects
|
||||
- [ ] FAIL gate enforced — any unsatisfied requirement forces gaps_found status
|
||||
- [ ] Nyquist compliance scanned for all milestone phases (if enabled)
|
||||
- [ ] Missing VALIDATION.md phases flagged with validate-phase suggestion
|
||||
- [ ] Results presented with actionable next steps
|
||||
</success_criteria>
|
||||
743
get-shit-done/workflows/autonomous.md
Normal file
743
get-shit-done/workflows/autonomous.md
Normal file
@@ -0,0 +1,743 @@
|
||||
<purpose>
|
||||
|
||||
Drive all remaining milestone phases autonomously. For each incomplete phase: discuss → plan → execute using Skill() flat invocations. Pauses only for explicit user decisions (grey area acceptance, blockers, validation requests). Re-reads ROADMAP.md after each phase to catch dynamically inserted phases.
|
||||
|
||||
</purpose>
|
||||
|
||||
<required_reading>
|
||||
|
||||
Read all files referenced by the invoking prompt's execution_context before starting.
|
||||
|
||||
</required_reading>
|
||||
|
||||
<process>
|
||||
|
||||
<step name="initialize" priority="first">
|
||||
|
||||
## 1. Initialize
|
||||
|
||||
Parse `$ARGUMENTS` for `--from N` flag:
|
||||
|
||||
```bash
|
||||
FROM_PHASE=""
|
||||
if echo "$ARGUMENTS" | grep -qE '\-\-from\s+[0-9]'; then
|
||||
FROM_PHASE=$(echo "$ARGUMENTS" | grep -oE '\-\-from\s+[0-9]+\.?[0-9]*' | awk '{print $2}')
|
||||
fi
|
||||
```
|
||||
|
||||
Bootstrap via milestone-level init:
|
||||
|
||||
```bash
|
||||
INIT=$(node "C:/Users/yaoji/.claude/get-shit-done/bin/gsd-tools.cjs" init milestone-op)
|
||||
```
|
||||
|
||||
Parse JSON for: `milestone_version`, `milestone_name`, `phase_count`, `completed_phases`, `roadmap_exists`, `state_exists`, `commit_docs`.
|
||||
|
||||
**If `roadmap_exists` is false:** Error — "No ROADMAP.md found. Run `/gsd:new-milestone` first."
|
||||
**If `state_exists` is false:** Error — "No STATE.md found. Run `/gsd:new-milestone` first."
|
||||
|
||||
Display startup banner:
|
||||
|
||||
```
|
||||
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
|
||||
GSD ► AUTONOMOUS
|
||||
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
|
||||
|
||||
Milestone: {milestone_version} — {milestone_name}
|
||||
Phases: {phase_count} total, {completed_phases} complete
|
||||
```
|
||||
|
||||
If `FROM_PHASE` is set, display: `Starting from phase ${FROM_PHASE}`
|
||||
|
||||
</step>
|
||||
|
||||
<step name="discover_phases">
|
||||
|
||||
## 2. Discover Phases
|
||||
|
||||
Run phase discovery:
|
||||
|
||||
```bash
|
||||
ROADMAP=$(node "C:/Users/yaoji/.claude/get-shit-done/bin/gsd-tools.cjs" roadmap analyze)
|
||||
```
|
||||
|
||||
Parse the JSON `phases` array.
|
||||
|
||||
**Filter to incomplete phases:** Keep only phases where `disk_status !== "complete"` OR `roadmap_complete === false`.
|
||||
|
||||
**Apply `--from N` filter:** If `FROM_PHASE` was provided, additionally filter out phases where `number < FROM_PHASE` (use numeric comparison — handles decimal phases like "5.1").
|
||||
|
||||
**Sort by `number`** in numeric ascending order.
|
||||
|
||||
**If no incomplete phases remain:**
|
||||
|
||||
```
|
||||
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
|
||||
GSD ► AUTONOMOUS ▸ COMPLETE 🎉
|
||||
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
|
||||
|
||||
All phases complete! Nothing left to do.
|
||||
```
|
||||
|
||||
Exit cleanly.
|
||||
|
||||
**Display phase plan:**
|
||||
|
||||
```
|
||||
## Phase Plan
|
||||
|
||||
| # | Phase | Status |
|
||||
|---|-------|--------|
|
||||
| 5 | Skill Scaffolding & Phase Discovery | In Progress |
|
||||
| 6 | Smart Discuss | Not Started |
|
||||
| 7 | Auto-Chain Refinements | Not Started |
|
||||
| 8 | Lifecycle Orchestration | Not Started |
|
||||
```
|
||||
|
||||
**Fetch details for each phase:**
|
||||
|
||||
```bash
|
||||
DETAIL=$(node "C:/Users/yaoji/.claude/get-shit-done/bin/gsd-tools.cjs" roadmap get-phase ${PHASE_NUM})
|
||||
```
|
||||
|
||||
Extract `phase_name`, `goal`, `success_criteria` from each. Store for use in execute_phase and transition messages.
|
||||
|
||||
</step>
|
||||
|
||||
<step name="execute_phase">
|
||||
|
||||
## 3. Execute Phase
|
||||
|
||||
For the current phase, display the progress banner:
|
||||
|
||||
```
|
||||
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
|
||||
GSD ► AUTONOMOUS ▸ Phase {N}/{T}: {Name} [████░░░░] {P}%
|
||||
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
|
||||
```
|
||||
|
||||
Where N = current phase number (from the ROADMAP, e.g., 6), T = total milestone phases (from `phase_count` parsed in initialize step, e.g., 8), P = percentage of all milestone phases completed so far. Calculate P as: (number of phases with `disk_status` "complete" from the latest `roadmap analyze` / T × 100). Use █ for filled and ░ for empty segments in the progress bar (8 characters wide).
|
||||
|
||||
**3a. Smart Discuss**
|
||||
|
||||
Check if CONTEXT.md already exists for this phase:
|
||||
|
||||
```bash
|
||||
PHASE_STATE=$(node "C:/Users/yaoji/.claude/get-shit-done/bin/gsd-tools.cjs" init phase-op ${PHASE_NUM})
|
||||
```
|
||||
|
||||
Parse `has_context` from JSON.
|
||||
|
||||
**If has_context is true:** Skip discuss — context already gathered. Display:
|
||||
|
||||
```
|
||||
Phase ${PHASE_NUM}: Context exists — skipping discuss.
|
||||
```
|
||||
|
||||
Proceed to 3b.
|
||||
|
||||
**If has_context is false:** Execute the smart_discuss step for this phase.
|
||||
|
||||
After smart_discuss completes, verify context was written:
|
||||
|
||||
```bash
|
||||
PHASE_STATE=$(node "C:/Users/yaoji/.claude/get-shit-done/bin/gsd-tools.cjs" init phase-op ${PHASE_NUM})
|
||||
```
|
||||
|
||||
Check `has_context`. If false → go to handle_blocker: "Smart discuss for phase ${PHASE_NUM} did not produce CONTEXT.md."
|
||||
|
||||
**3b. Plan**
|
||||
|
||||
```
|
||||
Skill(skill="gsd:plan-phase", args="${PHASE_NUM}")
|
||||
```
|
||||
|
||||
Verify plan produced output — re-run `init phase-op` and check `has_plans`. If false → go to handle_blocker: "Plan phase ${PHASE_NUM} did not produce any plans."
|
||||
|
||||
**3c. Execute**
|
||||
|
||||
```
|
||||
Skill(skill="gsd:execute-phase", args="${PHASE_NUM} --no-transition")
|
||||
```
|
||||
|
||||
**3d. Post-Execution Routing**
|
||||
|
||||
After execute-phase returns, read the verification result:
|
||||
|
||||
```bash
|
||||
VERIFY_STATUS=$(grep "^status:" "${PHASE_DIR}"/*-VERIFICATION.md 2>/dev/null | head -1 | cut -d: -f2 | tr -d ' ')
|
||||
```
|
||||
|
||||
Where `PHASE_DIR` comes from the `init phase-op` call already made in step 3a. If the variable is not in scope, re-fetch:
|
||||
|
||||
```bash
|
||||
PHASE_STATE=$(node "C:/Users/yaoji/.claude/get-shit-done/bin/gsd-tools.cjs" init phase-op ${PHASE_NUM})
|
||||
```
|
||||
|
||||
Parse `phase_dir` from the JSON.
|
||||
|
||||
**If VERIFY_STATUS is empty** (no VERIFICATION.md or no status field):
|
||||
|
||||
Go to handle_blocker: "Execute phase ${PHASE_NUM} did not produce verification results."
|
||||
|
||||
**If `passed`:**
|
||||
|
||||
Display:
|
||||
```
|
||||
Phase ${PHASE_NUM} ✅ ${PHASE_NAME} — Verification passed
|
||||
```
|
||||
|
||||
Proceed to iterate step.
|
||||
|
||||
**If `human_needed`:**
|
||||
|
||||
Read the human_verification section from VERIFICATION.md to get the count and items requiring manual testing.
|
||||
|
||||
Display the items, then ask user via AskUserQuestion:
|
||||
- **question:** "Phase ${PHASE_NUM} has items needing manual verification. Validate now or continue to next phase?"
|
||||
- **options:** "Validate now" / "Continue without validation"
|
||||
|
||||
On **"Validate now"**: Present the specific items from VERIFICATION.md's human_verification section. After user reviews, ask:
|
||||
- **question:** "Validation result?"
|
||||
- **options:** "All good — continue" / "Found issues"
|
||||
|
||||
On "All good — continue": Display `Phase ${PHASE_NUM} ✅ Human validation passed` and proceed to iterate step.
|
||||
|
||||
On "Found issues": Go to handle_blocker with the user's reported issues as the description.
|
||||
|
||||
On **"Continue without validation"**: Display `Phase ${PHASE_NUM} ⏭ Human validation deferred` and proceed to iterate step.
|
||||
|
||||
**If `gaps_found`:**
|
||||
|
||||
Read gap summary from VERIFICATION.md (score and missing items). Display:
|
||||
```
|
||||
⚠ Phase ${PHASE_NUM}: ${PHASE_NAME} — Gaps Found
|
||||
Score: {N}/{M} must-haves verified
|
||||
```
|
||||
|
||||
Ask user via AskUserQuestion:
|
||||
- **question:** "Gaps found in phase ${PHASE_NUM}. How to proceed?"
|
||||
- **options:** "Run gap closure" / "Continue without fixing" / "Stop autonomous mode"
|
||||
|
||||
On **"Run gap closure"**: Execute gap closure cycle (limit: 1 attempt):
|
||||
|
||||
```
|
||||
Skill(skill="gsd:plan-phase", args="${PHASE_NUM} --gaps")
|
||||
```
|
||||
|
||||
Verify gap plans were created — re-run `init phase-op ${PHASE_NUM}` and check `has_plans`. If no new gap plans → go to handle_blocker: "Gap closure planning for phase ${PHASE_NUM} did not produce plans."
|
||||
|
||||
Re-execute:
|
||||
```
|
||||
Skill(skill="gsd:execute-phase", args="${PHASE_NUM} --no-transition")
|
||||
```
|
||||
|
||||
Re-read verification status:
|
||||
```bash
|
||||
VERIFY_STATUS=$(grep "^status:" "${PHASE_DIR}"/*-VERIFICATION.md 2>/dev/null | head -1 | cut -d: -f2 | tr -d ' ')
|
||||
```
|
||||
|
||||
If `passed` or `human_needed`: Route normally (continue or ask user as above).
|
||||
|
||||
If still `gaps_found` after this retry: Display "Gaps persist after closure attempt." and ask via AskUserQuestion:
|
||||
- **question:** "Gap closure did not fully resolve issues. How to proceed?"
|
||||
- **options:** "Continue anyway" / "Stop autonomous mode"
|
||||
|
||||
On "Continue anyway": Proceed to iterate step.
|
||||
On "Stop autonomous mode": Go to handle_blocker.
|
||||
|
||||
This limits gap closure to 1 automatic retry to prevent infinite loops.
|
||||
|
||||
On **"Continue without fixing"**: Display `Phase ${PHASE_NUM} ⏭ Gaps deferred` and proceed to iterate step.
|
||||
|
||||
On **"Stop autonomous mode"**: Go to handle_blocker with "User stopped — gaps remain in phase ${PHASE_NUM}".
|
||||
|
||||
</step>
|
||||
|
||||
<step name="smart_discuss">
|
||||
|
||||
## Smart Discuss
|
||||
|
||||
Run smart discuss for the current phase. Proposes grey area answers in batch tables — the user accepts or overrides per area. Produces identical CONTEXT.md output to regular discuss-phase.
|
||||
|
||||
> **Note:** Smart discuss is an autonomous-optimized variant of the `gsd:discuss-phase` skill. It produces identical CONTEXT.md output but uses batch table proposals instead of sequential questioning. The original `discuss-phase` skill remains unchanged (per CTRL-03). Future milestones may extract this to a separate skill file.
|
||||
|
||||
**Inputs:** `PHASE_NUM` from execute_phase. Run init to get phase paths:
|
||||
|
||||
```bash
|
||||
PHASE_STATE=$(node "C:/Users/yaoji/.claude/get-shit-done/bin/gsd-tools.cjs" init phase-op ${PHASE_NUM})
|
||||
```
|
||||
|
||||
Parse from JSON: `phase_dir`, `phase_slug`, `padded_phase`, `phase_name`.
|
||||
|
||||
---
|
||||
|
||||
### Sub-step 1: Load prior context
|
||||
|
||||
Read project-level and prior phase context to avoid re-asking decided questions.
|
||||
|
||||
**Read project files:**
|
||||
|
||||
```bash
|
||||
cat .planning/PROJECT.md 2>/dev/null
|
||||
cat .planning/REQUIREMENTS.md 2>/dev/null
|
||||
cat .planning/STATE.md 2>/dev/null
|
||||
```
|
||||
|
||||
Extract from these:
|
||||
- **PROJECT.md** — Vision, principles, non-negotiables, user preferences
|
||||
- **REQUIREMENTS.md** — Acceptance criteria, constraints, must-haves vs nice-to-haves
|
||||
- **STATE.md** — Current progress, decisions logged so far
|
||||
|
||||
**Read all prior CONTEXT.md files:**
|
||||
|
||||
```bash
|
||||
find .planning/phases -name "*-CONTEXT.md" 2>/dev/null | sort
|
||||
```
|
||||
|
||||
For each CONTEXT.md where phase number < current phase:
|
||||
- Read the `<decisions>` section — these are locked preferences
|
||||
- Read `<specifics>` — particular references or "I want it like X" moments
|
||||
- Note patterns (e.g., "user consistently prefers minimal UI", "user rejected verbose output")
|
||||
|
||||
**Build internal prior_decisions context** (do not write to file):
|
||||
|
||||
```
|
||||
<prior_decisions>
|
||||
## Project-Level
|
||||
- [Key principle or constraint from PROJECT.md]
|
||||
- [Requirement affecting this phase from REQUIREMENTS.md]
|
||||
|
||||
## From Prior Phases
|
||||
### Phase N: [Name]
|
||||
- [Decision relevant to current phase]
|
||||
- [Preference that establishes a pattern]
|
||||
</prior_decisions>
|
||||
```
|
||||
|
||||
If no prior context exists, continue without — expected for early phases.
|
||||
|
||||
---
|
||||
|
||||
### Sub-step 2: Scout Codebase
|
||||
|
||||
Lightweight codebase scan to inform grey area identification and proposals. Keep under ~5% context.
|
||||
|
||||
**Check for existing codebase maps:**
|
||||
|
||||
```bash
|
||||
ls .planning/codebase/*.md 2>/dev/null
|
||||
```
|
||||
|
||||
**If codebase maps exist:** Read the most relevant ones (CONVENTIONS.md, STRUCTURE.md, STACK.md based on phase type). Extract reusable components, established patterns, integration points. Skip to building context below.
|
||||
|
||||
**If no codebase maps, do targeted grep:**
|
||||
|
||||
Extract key terms from the phase goal. Search for related files:
|
||||
|
||||
```bash
|
||||
grep -rl "{term1}\|{term2}" src/ app/ --include="*.ts" --include="*.tsx" --include="*.js" --include="*.jsx" 2>/dev/null | head -10
|
||||
ls src/components/ src/hooks/ src/lib/ src/utils/ 2>/dev/null
|
||||
```
|
||||
|
||||
Read the 3-5 most relevant files to understand existing patterns.
|
||||
|
||||
**Build internal codebase_context** (do not write to file):
|
||||
- **Reusable assets** — existing components, hooks, utilities usable in this phase
|
||||
- **Established patterns** — how the codebase does state management, styling, data fetching
|
||||
- **Integration points** — where new code connects (routes, nav, providers)
|
||||
|
||||
---
|
||||
|
||||
### Sub-step 3: Analyze Phase and Generate Proposals
|
||||
|
||||
**Get phase details:**
|
||||
|
||||
```bash
|
||||
DETAIL=$(node "C:/Users/yaoji/.claude/get-shit-done/bin/gsd-tools.cjs" roadmap get-phase ${PHASE_NUM})
|
||||
```
|
||||
|
||||
Extract `goal`, `requirements`, `success_criteria` from the JSON response.
|
||||
|
||||
**Infrastructure detection — check FIRST before generating grey areas:**
|
||||
|
||||
A phase is pure infrastructure when ALL of these are true:
|
||||
1. Goal keywords match: "scaffolding", "plumbing", "setup", "configuration", "migration", "refactor", "rename", "restructure", "upgrade", "infrastructure"
|
||||
2. AND success criteria are all technical: "file exists", "test passes", "config valid", "command runs"
|
||||
3. AND no user-facing behavior is described (no "users can", "displays", "shows", "presents")
|
||||
|
||||
**If infrastructure-only:** Skip Sub-step 4. Jump directly to Sub-step 5 with minimal CONTEXT.md. Display:
|
||||
|
||||
```
|
||||
Phase ${PHASE_NUM}: Infrastructure phase — skipping discuss, writing minimal context.
|
||||
```
|
||||
|
||||
Use these defaults for the CONTEXT.md:
|
||||
- `<domain>`: Phase boundary from ROADMAP goal
|
||||
- `<decisions>`: Single "### Claude's Discretion" subsection — "All implementation choices are at Claude's discretion — pure infrastructure phase"
|
||||
- `<code_context>`: Whatever the codebase scout found
|
||||
- `<specifics>`: "No specific requirements — infrastructure phase"
|
||||
- `<deferred>`: "None"
|
||||
|
||||
**If NOT infrastructure — generate grey area proposals:**
|
||||
|
||||
Determine domain type from the phase goal:
|
||||
- Something users **SEE** → visual: layout, interactions, states, density
|
||||
- Something users **CALL** → interface: contracts, responses, errors, auth
|
||||
- Something users **RUN** → execution: invocation, output, behavior modes, flags
|
||||
- Something users **READ** → content: structure, tone, depth, flow
|
||||
- Something being **ORGANIZED** → organization: criteria, grouping, exceptions, naming
|
||||
|
||||
Check prior_decisions — skip grey areas already decided in prior phases.
|
||||
|
||||
Generate **3-4 grey areas** with **~4 questions each**. For each question:
|
||||
- **Pre-select a recommended answer** based on: prior decisions (consistency), codebase patterns (reuse), domain conventions (standard approaches), ROADMAP success criteria
|
||||
- Generate **1-2 alternatives** per question
|
||||
- **Annotate** with prior decision context ("You decided X in Phase N") and code context ("Component Y exists with Z variants") where relevant
|
||||
|
||||
---
|
||||
|
||||
### Sub-step 4: Present Proposals Per Area
|
||||
|
||||
Present grey areas **one at a time**. For each area (M of N):
|
||||
|
||||
Display a table:
|
||||
|
||||
```
|
||||
### Grey Area {M}/{N}: {Area Name}
|
||||
|
||||
| # | Question | ✅ Recommended | Alternative(s) |
|
||||
|---|----------|---------------|-----------------|
|
||||
| 1 | {question} | {answer} — {rationale} | {alt1}; {alt2} |
|
||||
| 2 | {question} | {answer} — {rationale} | {alt1} |
|
||||
| 3 | {question} | {answer} — {rationale} | {alt1}; {alt2} |
|
||||
| 4 | {question} | {answer} — {rationale} | {alt1} |
|
||||
```
|
||||
|
||||
Then prompt the user via **AskUserQuestion**:
|
||||
- **header:** "Area {M}/{N}"
|
||||
- **question:** "Accept these answers for {Area Name}?"
|
||||
- **options:** Build dynamically — always "Accept all" first, then "Change Q1" through "Change QN" for each question (up to 4), then "Discuss deeper" last. Cap at 6 explicit options max (AskUserQuestion adds "Other" automatically).
|
||||
|
||||
**On "Accept all":** Record all recommended answers for this area. Move to next area.
|
||||
|
||||
**On "Change QN":** Use AskUserQuestion with the alternatives for that specific question:
|
||||
- **header:** "{Area Name}"
|
||||
- **question:** "Q{N}: {question text}"
|
||||
- **options:** List the 1-2 alternatives plus "You decide" (maps to Claude's Discretion)
|
||||
|
||||
Record the user's choice. Re-display the updated table with the change reflected. Re-present the full acceptance prompt so the user can make additional changes or accept.
|
||||
|
||||
**On "Discuss deeper":** Switch to interactive mode for this area only — ask questions one at a time using AskUserQuestion with 2-3 concrete options per question plus "You decide". After 4 questions, prompt:
|
||||
- **header:** "{Area Name}"
|
||||
- **question:** "More questions about {area name}, or move to next?"
|
||||
- **options:** "More questions" / "Next area"
|
||||
|
||||
If "More questions", ask 4 more. If "Next area", display final summary table of captured answers for this area and move on.
|
||||
|
||||
**On "Other" (free text):** Interpret as either a specific change request or general feedback. Incorporate into the area's decisions, re-display updated table, re-present acceptance prompt.
|
||||
|
||||
**Scope creep handling:** If user mentions something outside the phase domain:
|
||||
|
||||
```
|
||||
"{Feature} sounds like a new capability — that belongs in its own phase.
|
||||
I'll note it as a deferred idea.
|
||||
|
||||
Back to {current area}: {return to current question}"
|
||||
```
|
||||
|
||||
Track deferred ideas internally for inclusion in CONTEXT.md.
|
||||
|
||||
---
|
||||
|
||||
### Sub-step 5: Write CONTEXT.md
|
||||
|
||||
After all areas are resolved (or infrastructure skip), write the CONTEXT.md file.
|
||||
|
||||
**File path:** `${phase_dir}/${padded_phase}-CONTEXT.md`
|
||||
|
||||
Use **exactly** this structure (identical to discuss-phase output):
|
||||
|
||||
```markdown
|
||||
# Phase {PHASE_NUM}: {Phase Name} - Context
|
||||
|
||||
**Gathered:** {date}
|
||||
**Status:** Ready for planning
|
||||
|
||||
<domain>
|
||||
## Phase Boundary
|
||||
|
||||
{Domain boundary statement from analysis — what this phase delivers}
|
||||
|
||||
</domain>
|
||||
|
||||
<decisions>
|
||||
## Implementation Decisions
|
||||
|
||||
### {Area 1 Name}
|
||||
- {Accepted/chosen answer for Q1}
|
||||
- {Accepted/chosen answer for Q2}
|
||||
- {Accepted/chosen answer for Q3}
|
||||
- {Accepted/chosen answer for Q4}
|
||||
|
||||
### {Area 2 Name}
|
||||
- {Accepted/chosen answer for Q1}
|
||||
- {Accepted/chosen answer for Q2}
|
||||
...
|
||||
|
||||
### Claude's Discretion
|
||||
{Any "You decide" answers collected — note Claude has flexibility here}
|
||||
|
||||
</decisions>
|
||||
|
||||
<code_context>
|
||||
## Existing Code Insights
|
||||
|
||||
### Reusable Assets
|
||||
- {From codebase scout — components, hooks, utilities}
|
||||
|
||||
### Established Patterns
|
||||
- {From codebase scout — state management, styling, data fetching}
|
||||
|
||||
### Integration Points
|
||||
- {From codebase scout — where new code connects}
|
||||
|
||||
</code_context>
|
||||
|
||||
<specifics>
|
||||
## Specific Ideas
|
||||
|
||||
{Any specific references or "I want it like X" from discussion}
|
||||
{If none: "No specific requirements — open to standard approaches"}
|
||||
|
||||
</specifics>
|
||||
|
||||
<deferred>
|
||||
## Deferred Ideas
|
||||
|
||||
{Ideas captured but out of scope for this phase}
|
||||
{If none: "None — discussion stayed within phase scope"}
|
||||
|
||||
</deferred>
|
||||
```
|
||||
|
||||
Write the file.
|
||||
|
||||
**Commit:**
|
||||
|
||||
```bash
|
||||
node "C:/Users/yaoji/.claude/get-shit-done/bin/gsd-tools.cjs" commit "docs(${PADDED_PHASE}): smart discuss context" --files "${phase_dir}/${padded_phase}-CONTEXT.md"
|
||||
```
|
||||
|
||||
Display confirmation:
|
||||
|
||||
```
|
||||
Created: {path}
|
||||
Decisions captured: {count} across {area_count} areas
|
||||
```
|
||||
|
||||
</step>
|
||||
|
||||
<step name="iterate">
|
||||
|
||||
## 4. Iterate
|
||||
|
||||
After each phase completes, re-read ROADMAP.md to catch phases inserted mid-execution (decimal phases like 5.1):
|
||||
|
||||
```bash
|
||||
ROADMAP=$(node "C:/Users/yaoji/.claude/get-shit-done/bin/gsd-tools.cjs" roadmap analyze)
|
||||
```
|
||||
|
||||
Re-filter incomplete phases using the same logic as discover_phases:
|
||||
- Keep phases where `disk_status !== "complete"` OR `roadmap_complete === false`
|
||||
- Apply `--from N` filter if originally provided
|
||||
- Sort by number ascending
|
||||
|
||||
Read STATE.md fresh:
|
||||
|
||||
```bash
|
||||
cat .planning/STATE.md
|
||||
```
|
||||
|
||||
Check for blockers in the Blockers/Concerns section. If blockers are found, go to handle_blocker with the blocker description.
|
||||
|
||||
If incomplete phases remain: proceed to next phase, loop back to execute_phase.
|
||||
|
||||
If all phases complete, proceed to lifecycle step.
|
||||
|
||||
</step>
|
||||
|
||||
<step name="lifecycle">
|
||||
|
||||
## 5. Lifecycle
|
||||
|
||||
After all phases complete, run the milestone lifecycle sequence: audit → complete → cleanup.
|
||||
|
||||
Display lifecycle transition banner:
|
||||
|
||||
```
|
||||
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
|
||||
GSD ► AUTONOMOUS ▸ LIFECYCLE
|
||||
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
|
||||
|
||||
All phases complete → Starting lifecycle: audit → complete → cleanup
|
||||
Milestone: {milestone_version} — {milestone_name}
|
||||
```
|
||||
|
||||
**5a. Audit**
|
||||
|
||||
```
|
||||
Skill(skill="gsd:audit-milestone")
|
||||
```
|
||||
|
||||
After audit completes, detect the result:
|
||||
|
||||
```bash
|
||||
AUDIT_FILE=".planning/v${milestone_version}-MILESTONE-AUDIT.md"
|
||||
AUDIT_STATUS=$(grep "^status:" "${AUDIT_FILE}" 2>/dev/null | head -1 | cut -d: -f2 | tr -d ' ')
|
||||
```
|
||||
|
||||
**If AUDIT_STATUS is empty** (no audit file or no status field):
|
||||
|
||||
Go to handle_blocker: "Audit did not produce results — audit file missing or malformed."
|
||||
|
||||
**If `passed`:**
|
||||
|
||||
Display:
|
||||
```
|
||||
Audit ✅ passed — proceeding to complete milestone
|
||||
```
|
||||
|
||||
Proceed to 5b (no user pause — per CTRL-01).
|
||||
|
||||
**If `gaps_found`:**
|
||||
|
||||
Read the gaps summary from the audit file. Display:
|
||||
```
|
||||
⚠ Audit: Gaps Found
|
||||
```
|
||||
|
||||
Ask user via AskUserQuestion:
|
||||
- **question:** "Milestone audit found gaps. How to proceed?"
|
||||
- **options:** "Continue anyway — accept gaps" / "Stop — fix gaps manually"
|
||||
|
||||
On **"Continue anyway"**: Display `Audit ⏭ Gaps accepted — proceeding to complete milestone` and proceed to 5b.
|
||||
|
||||
On **"Stop"**: Go to handle_blocker with "User stopped — audit gaps remain. Run /gsd:audit-milestone to review, then /gsd:complete-milestone when ready."
|
||||
|
||||
**If `tech_debt`:**
|
||||
|
||||
Read the tech debt summary from the audit file. Display:
|
||||
```
|
||||
⚠ Audit: Tech Debt Identified
|
||||
```
|
||||
|
||||
Show the summary, then ask user via AskUserQuestion:
|
||||
- **question:** "Milestone audit found tech debt. How to proceed?"
|
||||
- **options:** "Continue with tech debt" / "Stop — address debt first"
|
||||
|
||||
On **"Continue with tech debt"**: Display `Audit ⏭ Tech debt acknowledged — proceeding to complete milestone` and proceed to 5b.
|
||||
|
||||
On **"Stop"**: Go to handle_blocker with "User stopped — tech debt to address. Run /gsd:audit-milestone to review details."
|
||||
|
||||
**5b. Complete Milestone**
|
||||
|
||||
```
|
||||
Skill(skill="gsd:complete-milestone", args="${milestone_version}")
|
||||
```
|
||||
|
||||
After complete-milestone returns, verify it produced output:
|
||||
|
||||
```bash
|
||||
ls .planning/milestones/v${milestone_version}-ROADMAP.md 2>/dev/null
|
||||
```
|
||||
|
||||
If the archive file does not exist, go to handle_blocker: "Complete milestone did not produce expected archive files."
|
||||
|
||||
**5c. Cleanup**
|
||||
|
||||
```
|
||||
Skill(skill="gsd:cleanup")
|
||||
```
|
||||
|
||||
Cleanup shows its own dry-run and asks user for approval internally — this is an acceptable pause per CTRL-01 since it's an explicit decision about file deletion.
|
||||
|
||||
**5d. Final Completion**
|
||||
|
||||
Display final completion banner:
|
||||
|
||||
```
|
||||
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
|
||||
GSD ► AUTONOMOUS ▸ COMPLETE 🎉
|
||||
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
|
||||
|
||||
Milestone: {milestone_version} — {milestone_name}
|
||||
Status: Complete ✅
|
||||
Lifecycle: audit ✅ → complete ✅ → cleanup ✅
|
||||
|
||||
Ship it! 🚀
|
||||
```
|
||||
|
||||
</step>
|
||||
|
||||
<step name="handle_blocker">
|
||||
|
||||
## 6. Handle Blocker
|
||||
|
||||
When any phase operation fails or a blocker is detected, present 3 options via AskUserQuestion:
|
||||
|
||||
**Prompt:** "Phase {N} ({Name}) encountered an issue: {description}"
|
||||
|
||||
**Options:**
|
||||
1. **"Fix and retry"** — Re-run the failed step (discuss, plan, or execute) for this phase
|
||||
2. **"Skip this phase"** — Mark phase as skipped, continue to the next incomplete phase
|
||||
3. **"Stop autonomous mode"** — Display summary of progress so far and exit cleanly
|
||||
|
||||
**On "Fix and retry":** Loop back to the failed step within execute_phase. If the same step fails again after retry, re-present these options.
|
||||
|
||||
**On "Skip this phase":** Log `Phase {N} ⏭ {Name} — Skipped by user` and proceed to iterate.
|
||||
|
||||
**On "Stop autonomous mode":** Display progress summary:
|
||||
|
||||
```
|
||||
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
|
||||
GSD ► AUTONOMOUS ▸ STOPPED
|
||||
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
|
||||
|
||||
Completed: {list of completed phases}
|
||||
Skipped: {list of skipped phases}
|
||||
Remaining: {list of remaining phases}
|
||||
|
||||
Resume with: /gsd:autonomous --from {next_phase}
|
||||
```
|
||||
|
||||
</step>
|
||||
|
||||
</process>
|
||||
|
||||
<success_criteria>
|
||||
- [ ] All incomplete phases executed in order (smart discuss → plan → execute each)
|
||||
- [ ] Smart discuss proposes grey area answers in tables, user accepts or overrides per area
|
||||
- [ ] Progress banners displayed between phases
|
||||
- [ ] Execute-phase invoked with --no-transition (autonomous manages transitions)
|
||||
- [ ] Post-execution verification reads VERIFICATION.md and routes on status
|
||||
- [ ] Passed verification → automatic continue to next phase
|
||||
- [ ] Human-needed verification → user prompted to validate or skip
|
||||
- [ ] Gaps-found → user offered gap closure, continue, or stop
|
||||
- [ ] Gap closure limited to 1 retry (prevents infinite loops)
|
||||
- [ ] Plan-phase and execute-phase failures route to handle_blocker
|
||||
- [ ] ROADMAP.md re-read after each phase (catches inserted phases)
|
||||
- [ ] STATE.md checked for blockers before each phase
|
||||
- [ ] Blockers handled via user choice (retry / skip / stop)
|
||||
- [ ] Final completion or stop summary displayed
|
||||
- [ ] After all phases complete, lifecycle step is invoked (not manual suggestion)
|
||||
- [ ] Lifecycle transition banner displayed before audit
|
||||
- [ ] Audit invoked via Skill(skill="gsd:audit-milestone")
|
||||
- [ ] Audit result routing: passed → auto-continue, gaps_found → user decides, tech_debt → user decides
|
||||
- [ ] Audit technical failure (no file/no status) routes to handle_blocker
|
||||
- [ ] Complete-milestone invoked via Skill() with ${milestone_version} arg
|
||||
- [ ] Cleanup invoked via Skill() — internal confirmation is acceptable (CTRL-01)
|
||||
- [ ] Final completion banner displayed after lifecycle
|
||||
- [ ] Progress bar uses phase number / total milestone phases (not position among incomplete)
|
||||
- [ ] Smart discuss documents relationship to discuss-phase with CTRL-03 note
|
||||
</success_criteria>
|
||||
177
get-shit-done/workflows/check-todos.md
Normal file
177
get-shit-done/workflows/check-todos.md
Normal file
@@ -0,0 +1,177 @@
|
||||
<purpose>
|
||||
List all pending todos, allow selection, load full context for the selected todo, and route to appropriate action.
|
||||
</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
|
||||
INIT=$(node "C:/Users/yaoji/.claude/get-shit-done/bin/gsd-tools.cjs" init todos)
|
||||
if [[ "$INIT" == @file:* ]]; then INIT=$(cat "${INIT#@file:}"); fi
|
||||
```
|
||||
|
||||
Extract from init JSON: `todo_count`, `todos`, `pending_dir`.
|
||||
|
||||
If `todo_count` is 0:
|
||||
```
|
||||
No pending todos.
|
||||
|
||||
Todos are captured during work sessions with /gsd:add-todo.
|
||||
|
||||
---
|
||||
|
||||
Would you like to:
|
||||
|
||||
1. Continue with current phase (/gsd:progress)
|
||||
2. Add a todo now (/gsd:add-todo)
|
||||
```
|
||||
|
||||
Exit.
|
||||
</step>
|
||||
|
||||
<step name="parse_filter">
|
||||
Check for area filter in arguments:
|
||||
- `/gsd:check-todos` → show all
|
||||
- `/gsd:check-todos api` → filter to area:api only
|
||||
</step>
|
||||
|
||||
<step name="list_todos">
|
||||
Use the `todos` array from init context (already filtered by area if specified).
|
||||
|
||||
Parse and display as numbered list:
|
||||
|
||||
```
|
||||
Pending Todos:
|
||||
|
||||
1. Add auth token refresh (api, 2d ago)
|
||||
2. Fix modal z-index issue (ui, 1d ago)
|
||||
3. Refactor database connection pool (database, 5h ago)
|
||||
|
||||
---
|
||||
|
||||
Reply with a number to view details, or:
|
||||
- `/gsd:check-todos [area]` to filter by area
|
||||
- `q` to exit
|
||||
```
|
||||
|
||||
Format age as relative time from created timestamp.
|
||||
</step>
|
||||
|
||||
<step name="handle_selection">
|
||||
Wait for user to reply with a number.
|
||||
|
||||
If valid: load selected todo, proceed.
|
||||
If invalid: "Invalid selection. Reply with a number (1-[N]) or `q` to exit."
|
||||
</step>
|
||||
|
||||
<step name="load_context">
|
||||
Read the todo file completely. Display:
|
||||
|
||||
```
|
||||
## [title]
|
||||
|
||||
**Area:** [area]
|
||||
**Created:** [date] ([relative time] ago)
|
||||
**Files:** [list or "None"]
|
||||
|
||||
### Problem
|
||||
[problem section content]
|
||||
|
||||
### Solution
|
||||
[solution section content]
|
||||
```
|
||||
|
||||
If `files` field has entries, read and briefly summarize each.
|
||||
</step>
|
||||
|
||||
<step name="check_roadmap">
|
||||
Check for roadmap (can use init progress or directly check file existence):
|
||||
|
||||
If `.planning/ROADMAP.md` exists:
|
||||
1. Check if todo's area matches an upcoming phase
|
||||
2. Check if todo's files overlap with a phase's scope
|
||||
3. Note any match for action options
|
||||
</step>
|
||||
|
||||
<step name="offer_actions">
|
||||
**If todo maps to a roadmap phase:**
|
||||
|
||||
Use AskUserQuestion:
|
||||
- header: "Action"
|
||||
- question: "This todo relates to Phase [N]: [name]. What would you like to do?"
|
||||
- options:
|
||||
- "Work on it now" — move to done, start working
|
||||
- "Add to phase plan" — include when planning Phase [N]
|
||||
- "Brainstorm approach" — think through before deciding
|
||||
- "Put it back" — return to list
|
||||
|
||||
**If no roadmap match:**
|
||||
|
||||
Use AskUserQuestion:
|
||||
- header: "Action"
|
||||
- question: "What would you like to do with this todo?"
|
||||
- options:
|
||||
- "Work on it now" — move to done, start working
|
||||
- "Create a phase" — /gsd:add-phase with this scope
|
||||
- "Brainstorm approach" — think through before deciding
|
||||
- "Put it back" — return to list
|
||||
</step>
|
||||
|
||||
<step name="execute_action">
|
||||
**Work on it now:**
|
||||
```bash
|
||||
mv ".planning/todos/pending/[filename]" ".planning/todos/done/"
|
||||
```
|
||||
Update STATE.md todo count. Present problem/solution context. Begin work or ask how to proceed.
|
||||
|
||||
**Add to phase plan:**
|
||||
Note todo reference in phase planning notes. Keep in pending. Return to list or exit.
|
||||
|
||||
**Create a phase:**
|
||||
Display: `/gsd:add-phase [description from todo]`
|
||||
Keep in pending. User runs command in fresh context.
|
||||
|
||||
**Brainstorm approach:**
|
||||
Keep in pending. Start discussion about problem and approaches.
|
||||
|
||||
**Put it back:**
|
||||
Return to list_todos step.
|
||||
</step>
|
||||
|
||||
<step name="update_state">
|
||||
After any action that changes todo count:
|
||||
|
||||
Re-run `init todos` to get updated count, then update STATE.md "### Pending Todos" section if exists.
|
||||
</step>
|
||||
|
||||
<step name="git_commit">
|
||||
If todo was moved to done/, commit the change:
|
||||
|
||||
```bash
|
||||
git rm --cached .planning/todos/pending/[filename] 2>/dev/null || true
|
||||
node "C:/Users/yaoji/.claude/get-shit-done/bin/gsd-tools.cjs" commit "docs: start work on todo - [title]" --files .planning/todos/done/[filename] .planning/STATE.md
|
||||
```
|
||||
|
||||
Tool respects `commit_docs` config and gitignore automatically.
|
||||
|
||||
Confirm: "Committed: docs: start work on todo - [title]"
|
||||
</step>
|
||||
|
||||
</process>
|
||||
|
||||
<success_criteria>
|
||||
- [ ] All pending todos listed with title, area, age
|
||||
- [ ] Area filter applied if specified
|
||||
- [ ] Selected todo's full context loaded
|
||||
- [ ] Roadmap context checked for phase match
|
||||
- [ ] Appropriate actions offered
|
||||
- [ ] Selected action executed
|
||||
- [ ] STATE.md updated if todo count changed
|
||||
- [ ] Changes committed to git (if todo moved to done/)
|
||||
</success_criteria>
|
||||
152
get-shit-done/workflows/cleanup.md
Normal file
152
get-shit-done/workflows/cleanup.md
Normal file
@@ -0,0 +1,152 @@
|
||||
<purpose>
|
||||
|
||||
Archive accumulated phase directories from completed milestones into `.planning/milestones/v{X.Y}-phases/`. Identifies which phases belong to each completed milestone, shows a dry-run summary, and moves directories on confirmation.
|
||||
|
||||
</purpose>
|
||||
|
||||
<required_reading>
|
||||
|
||||
1. `.planning/MILESTONES.md`
|
||||
2. `.planning/milestones/` directory listing
|
||||
3. `.planning/phases/` directory listing
|
||||
|
||||
</required_reading>
|
||||
|
||||
<process>
|
||||
|
||||
<step name="identify_completed_milestones">
|
||||
|
||||
Read `.planning/MILESTONES.md` to identify completed milestones and their versions.
|
||||
|
||||
```bash
|
||||
cat .planning/MILESTONES.md
|
||||
```
|
||||
|
||||
Extract each milestone version (e.g., v1.0, v1.1, v2.0).
|
||||
|
||||
Check which milestone archive dirs already exist:
|
||||
|
||||
```bash
|
||||
ls -d .planning/milestones/v*-phases 2>/dev/null
|
||||
```
|
||||
|
||||
Filter to milestones that do NOT already have a `-phases` archive directory.
|
||||
|
||||
If all milestones already have phase archives:
|
||||
|
||||
```
|
||||
All completed milestones already have phase directories archived. Nothing to clean up.
|
||||
```
|
||||
|
||||
Stop here.
|
||||
|
||||
</step>
|
||||
|
||||
<step name="determine_phase_membership">
|
||||
|
||||
For each completed milestone without a `-phases` archive, read the archived ROADMAP snapshot to determine which phases belong to it:
|
||||
|
||||
```bash
|
||||
cat .planning/milestones/v{X.Y}-ROADMAP.md
|
||||
```
|
||||
|
||||
Extract phase numbers and names from the archived roadmap (e.g., Phase 1: Foundation, Phase 2: Auth).
|
||||
|
||||
Check which of those phase directories still exist in `.planning/phases/`:
|
||||
|
||||
```bash
|
||||
ls -d .planning/phases/*/ 2>/dev/null
|
||||
```
|
||||
|
||||
Match phase directories to milestone membership. Only include directories that still exist in `.planning/phases/`.
|
||||
|
||||
</step>
|
||||
|
||||
<step name="show_dry_run">
|
||||
|
||||
Present a dry-run summary for each milestone:
|
||||
|
||||
```
|
||||
## Cleanup Summary
|
||||
|
||||
### v{X.Y} — {Milestone Name}
|
||||
These phase directories will be archived:
|
||||
- 01-foundation/
|
||||
- 02-auth/
|
||||
- 03-core-features/
|
||||
|
||||
Destination: .planning/milestones/v{X.Y}-phases/
|
||||
|
||||
### v{X.Z} — {Milestone Name}
|
||||
These phase directories will be archived:
|
||||
- 04-security/
|
||||
- 05-hardening/
|
||||
|
||||
Destination: .planning/milestones/v{X.Z}-phases/
|
||||
```
|
||||
|
||||
If no phase directories remain to archive (all already moved or deleted):
|
||||
|
||||
```
|
||||
No phase directories found to archive. Phases may have been removed or archived previously.
|
||||
```
|
||||
|
||||
Stop here.
|
||||
|
||||
AskUserQuestion: "Proceed with archiving?" with options: "Yes — archive listed phases" | "Cancel"
|
||||
|
||||
If "Cancel": Stop.
|
||||
|
||||
</step>
|
||||
|
||||
<step name="archive_phases">
|
||||
|
||||
For each milestone, move phase directories:
|
||||
|
||||
```bash
|
||||
mkdir -p .planning/milestones/v{X.Y}-phases
|
||||
```
|
||||
|
||||
For each phase directory belonging to this milestone:
|
||||
|
||||
```bash
|
||||
mv .planning/phases/{dir} .planning/milestones/v{X.Y}-phases/
|
||||
```
|
||||
|
||||
Repeat for all milestones in the cleanup set.
|
||||
|
||||
</step>
|
||||
|
||||
<step name="commit">
|
||||
|
||||
Commit the changes:
|
||||
|
||||
```bash
|
||||
node "C:/Users/yaoji/.claude/get-shit-done/bin/gsd-tools.cjs" commit "chore: archive phase directories from completed milestones" --files .planning/milestones/ .planning/phases/
|
||||
```
|
||||
|
||||
</step>
|
||||
|
||||
<step name="report">
|
||||
|
||||
```
|
||||
Archived:
|
||||
{For each milestone}
|
||||
- v{X.Y}: {N} phase directories → .planning/milestones/v{X.Y}-phases/
|
||||
|
||||
.planning/phases/ cleaned up.
|
||||
```
|
||||
|
||||
</step>
|
||||
|
||||
</process>
|
||||
|
||||
<success_criteria>
|
||||
|
||||
- [ ] All completed milestones without existing phase archives identified
|
||||
- [ ] Phase membership determined from archived ROADMAP snapshots
|
||||
- [ ] Dry-run summary shown and user confirmed
|
||||
- [ ] Phase directories moved to `.planning/milestones/v{X.Y}-phases/`
|
||||
- [ ] Changes committed
|
||||
|
||||
</success_criteria>
|
||||
766
get-shit-done/workflows/complete-milestone.md
Normal file
766
get-shit-done/workflows/complete-milestone.md
Normal file
@@ -0,0 +1,766 @@
|
||||
<purpose>
|
||||
|
||||
Mark a shipped version (v1.0, v1.1, v2.0) as complete. Creates historical record in MILESTONES.md, performs full PROJECT.md evolution review, reorganizes ROADMAP.md with milestone groupings, and tags the release in git.
|
||||
|
||||
</purpose>
|
||||
|
||||
<required_reading>
|
||||
|
||||
1. templates/milestone.md
|
||||
2. templates/milestone-archive.md
|
||||
3. `.planning/ROADMAP.md`
|
||||
4. `.planning/REQUIREMENTS.md`
|
||||
5. `.planning/PROJECT.md`
|
||||
|
||||
</required_reading>
|
||||
|
||||
<archival_behavior>
|
||||
|
||||
When a milestone completes:
|
||||
|
||||
1. Extract full milestone details to `.planning/milestones/v[X.Y]-ROADMAP.md`
|
||||
2. Archive requirements to `.planning/milestones/v[X.Y]-REQUIREMENTS.md`
|
||||
3. Update ROADMAP.md — replace milestone details with one-line summary
|
||||
4. Delete REQUIREMENTS.md (fresh one for next milestone)
|
||||
5. Perform full PROJECT.md evolution review
|
||||
6. Offer to create next milestone inline
|
||||
7. Archive UI artifacts (`*-UI-SPEC.md`, `*-UI-REVIEW.md`) alongside other phase documents
|
||||
8. Clean up `.planning/ui-reviews/` screenshot files (binary assets, never archived)
|
||||
|
||||
**Context Efficiency:** Archives keep ROADMAP.md constant-size and REQUIREMENTS.md milestone-scoped.
|
||||
|
||||
**ROADMAP archive** uses `templates/milestone-archive.md` — includes milestone header (status, phases, date), full phase details, milestone summary (decisions, issues, tech debt).
|
||||
|
||||
**REQUIREMENTS archive** contains all requirements marked complete with outcomes, traceability table with final status, notes on changed requirements.
|
||||
|
||||
</archival_behavior>
|
||||
|
||||
<process>
|
||||
|
||||
<step name="verify_readiness">
|
||||
|
||||
**Use `roadmap analyze` for comprehensive readiness check:**
|
||||
|
||||
```bash
|
||||
ROADMAP=$(node "C:/Users/yaoji/.claude/get-shit-done/bin/gsd-tools.cjs" roadmap analyze)
|
||||
```
|
||||
|
||||
This returns all phases with plan/summary counts and disk status. Use this to verify:
|
||||
- Which phases belong to this milestone?
|
||||
- All phases complete (all plans have summaries)? Check `disk_status === 'complete'` for each.
|
||||
- `progress_percent` should be 100%.
|
||||
|
||||
**Requirements completion check (REQUIRED before presenting):**
|
||||
|
||||
Parse REQUIREMENTS.md traceability table:
|
||||
- Count total v1 requirements vs checked-off (`[x]`) requirements
|
||||
- Identify any non-Complete rows in the traceability table
|
||||
|
||||
Present:
|
||||
|
||||
```
|
||||
Milestone: [Name, e.g., "v1.0 MVP"]
|
||||
|
||||
Includes:
|
||||
- Phase 1: Foundation (2/2 plans complete)
|
||||
- Phase 2: Authentication (2/2 plans complete)
|
||||
- Phase 3: Core Features (3/3 plans complete)
|
||||
- Phase 4: Polish (1/1 plan complete)
|
||||
|
||||
Total: {phase_count} phases, {total_plans} plans, all complete
|
||||
Requirements: {N}/{M} v1 requirements checked off
|
||||
```
|
||||
|
||||
**If requirements incomplete** (N < M):
|
||||
|
||||
```
|
||||
⚠ Unchecked Requirements:
|
||||
|
||||
- [ ] {REQ-ID}: {description} (Phase {X})
|
||||
- [ ] {REQ-ID}: {description} (Phase {Y})
|
||||
```
|
||||
|
||||
MUST present 3 options:
|
||||
1. **Proceed anyway** — mark milestone complete with known gaps
|
||||
2. **Run audit first** — `/gsd:audit-milestone` to assess gap severity
|
||||
3. **Abort** — return to development
|
||||
|
||||
If user selects "Proceed anyway": note incomplete requirements in MILESTONES.md under `### Known Gaps` with REQ-IDs and descriptions.
|
||||
|
||||
<config-check>
|
||||
|
||||
```bash
|
||||
cat .planning/config.json 2>/dev/null
|
||||
```
|
||||
|
||||
</config-check>
|
||||
|
||||
<if mode="yolo">
|
||||
|
||||
```
|
||||
⚡ Auto-approved: Milestone scope verification
|
||||
[Show breakdown summary without prompting]
|
||||
Proceeding to stats gathering...
|
||||
```
|
||||
|
||||
Proceed to gather_stats.
|
||||
|
||||
</if>
|
||||
|
||||
<if mode="interactive" OR="custom with gates.confirm_milestone_scope true">
|
||||
|
||||
```
|
||||
Ready to mark this milestone as shipped?
|
||||
(yes / wait / adjust scope)
|
||||
```
|
||||
|
||||
Wait for confirmation.
|
||||
- "adjust scope": Ask which phases to include.
|
||||
- "wait": Stop, user returns when ready.
|
||||
|
||||
</if>
|
||||
|
||||
</step>
|
||||
|
||||
<step name="gather_stats">
|
||||
|
||||
Calculate milestone statistics:
|
||||
|
||||
```bash
|
||||
git log --oneline --grep="feat(" | head -20
|
||||
git diff --stat FIRST_COMMIT..LAST_COMMIT | tail -1
|
||||
find . -name "*.swift" -o -name "*.ts" -o -name "*.py" | xargs wc -l 2>/dev/null
|
||||
git log --format="%ai" FIRST_COMMIT | tail -1
|
||||
git log --format="%ai" LAST_COMMIT | head -1
|
||||
```
|
||||
|
||||
Present:
|
||||
|
||||
```
|
||||
Milestone Stats:
|
||||
- Phases: [X-Y]
|
||||
- Plans: [Z] total
|
||||
- Tasks: [N] total (from phase summaries)
|
||||
- Files modified: [M]
|
||||
- Lines of code: [LOC] [language]
|
||||
- Timeline: [Days] days ([Start] → [End])
|
||||
- Git range: feat(XX-XX) → feat(YY-YY)
|
||||
```
|
||||
|
||||
</step>
|
||||
|
||||
<step name="extract_accomplishments">
|
||||
|
||||
Extract one-liners from SUMMARY.md files using summary-extract:
|
||||
|
||||
```bash
|
||||
# For each phase in milestone, extract one-liner
|
||||
for summary in .planning/phases/*-*/*-SUMMARY.md; do
|
||||
node "C:/Users/yaoji/.claude/get-shit-done/bin/gsd-tools.cjs" summary-extract "$summary" --fields one_liner | jq -r '.one_liner'
|
||||
done
|
||||
```
|
||||
|
||||
Extract 4-6 key accomplishments. Present:
|
||||
|
||||
```
|
||||
Key accomplishments for this milestone:
|
||||
1. [Achievement from phase 1]
|
||||
2. [Achievement from phase 2]
|
||||
3. [Achievement from phase 3]
|
||||
4. [Achievement from phase 4]
|
||||
5. [Achievement from phase 5]
|
||||
```
|
||||
|
||||
</step>
|
||||
|
||||
<step name="create_milestone_entry">
|
||||
|
||||
**Note:** MILESTONES.md entry is now created automatically by `gsd-tools milestone complete` in the archive_milestone step. The entry includes version, date, phase/plan/task counts, and accomplishments extracted from SUMMARY.md files.
|
||||
|
||||
If additional details are needed (e.g., user-provided "Delivered" summary, git range, LOC stats), add them manually after the CLI creates the base entry.
|
||||
|
||||
</step>
|
||||
|
||||
<step name="evolve_project_full_review">
|
||||
|
||||
Full PROJECT.md evolution review at milestone completion.
|
||||
|
||||
Read all phase summaries:
|
||||
|
||||
```bash
|
||||
cat .planning/phases/*-*/*-SUMMARY.md
|
||||
```
|
||||
|
||||
**Full review checklist:**
|
||||
|
||||
1. **"What This Is" accuracy:**
|
||||
- Compare current description to what was built
|
||||
- Update if product has meaningfully changed
|
||||
|
||||
2. **Core Value check:**
|
||||
- Still the right priority? Did shipping reveal a different core value?
|
||||
- Update if the ONE thing has shifted
|
||||
|
||||
3. **Requirements audit:**
|
||||
|
||||
**Validated section:**
|
||||
- All Active requirements shipped this milestone → Move to Validated
|
||||
- Format: `- ✓ [Requirement] — v[X.Y]`
|
||||
|
||||
**Active section:**
|
||||
- Remove requirements moved to Validated
|
||||
- Add new requirements for next milestone
|
||||
- Keep unaddressed requirements
|
||||
|
||||
**Out of Scope audit:**
|
||||
- Review each item — reasoning still valid?
|
||||
- Remove irrelevant items
|
||||
- Add requirements invalidated during milestone
|
||||
|
||||
4. **Context update:**
|
||||
- Current codebase state (LOC, tech stack)
|
||||
- User feedback themes (if any)
|
||||
- Known issues or technical debt
|
||||
|
||||
5. **Key Decisions audit:**
|
||||
- Extract all decisions from milestone phase summaries
|
||||
- Add to Key Decisions table with outcomes
|
||||
- Mark ✓ Good, ⚠️ Revisit, or — Pending
|
||||
|
||||
6. **Constraints check:**
|
||||
- Any constraints changed during development? Update as needed
|
||||
|
||||
Update PROJECT.md inline. Update "Last updated" footer:
|
||||
|
||||
```markdown
|
||||
---
|
||||
*Last updated: [date] after v[X.Y] milestone*
|
||||
```
|
||||
|
||||
**Example full evolution (v1.0 → v1.1 prep):**
|
||||
|
||||
Before:
|
||||
|
||||
```markdown
|
||||
## What This Is
|
||||
|
||||
A real-time collaborative whiteboard for remote teams.
|
||||
|
||||
## Core Value
|
||||
|
||||
Real-time sync that feels instant.
|
||||
|
||||
## Requirements
|
||||
|
||||
### Validated
|
||||
|
||||
(None yet — ship to validate)
|
||||
|
||||
### Active
|
||||
|
||||
- [ ] Canvas drawing tools
|
||||
- [ ] Real-time sync < 500ms
|
||||
- [ ] User authentication
|
||||
- [ ] Export to PNG
|
||||
|
||||
### Out of Scope
|
||||
|
||||
- Mobile app — web-first approach
|
||||
- Video chat — use external tools
|
||||
```
|
||||
|
||||
After v1.0:
|
||||
|
||||
```markdown
|
||||
## What This Is
|
||||
|
||||
A real-time collaborative whiteboard for remote teams with instant sync and drawing tools.
|
||||
|
||||
## Core Value
|
||||
|
||||
Real-time sync that feels instant.
|
||||
|
||||
## Requirements
|
||||
|
||||
### Validated
|
||||
|
||||
- ✓ Canvas drawing tools — v1.0
|
||||
- ✓ Real-time sync < 500ms — v1.0 (achieved 200ms avg)
|
||||
- ✓ User authentication — v1.0
|
||||
|
||||
### Active
|
||||
|
||||
- [ ] Export to PNG
|
||||
- [ ] Undo/redo history
|
||||
- [ ] Shape tools (rectangles, circles)
|
||||
|
||||
### Out of Scope
|
||||
|
||||
- Mobile app — web-first approach, PWA works well
|
||||
- Video chat — use external tools
|
||||
- Offline mode — real-time is core value
|
||||
|
||||
## Context
|
||||
|
||||
Shipped v1.0 with 2,400 LOC TypeScript.
|
||||
Tech stack: Next.js, Supabase, Canvas API.
|
||||
Initial user testing showed demand for shape tools.
|
||||
```
|
||||
|
||||
**Step complete when:**
|
||||
|
||||
- [ ] "What This Is" reviewed and updated if needed
|
||||
- [ ] Core Value verified as still correct
|
||||
- [ ] All shipped requirements moved to Validated
|
||||
- [ ] New requirements added to Active for next milestone
|
||||
- [ ] Out of Scope reasoning audited
|
||||
- [ ] Context updated with current state
|
||||
- [ ] All milestone decisions added to Key Decisions
|
||||
- [ ] "Last updated" footer reflects milestone completion
|
||||
|
||||
</step>
|
||||
|
||||
<step name="reorganize_roadmap">
|
||||
|
||||
Update `.planning/ROADMAP.md` — group completed milestone phases:
|
||||
|
||||
```markdown
|
||||
# Roadmap: [Project Name]
|
||||
|
||||
## Milestones
|
||||
|
||||
- ✅ **v1.0 MVP** — Phases 1-4 (shipped YYYY-MM-DD)
|
||||
- 🚧 **v1.1 Security** — Phases 5-6 (in progress)
|
||||
- 📋 **v2.0 Redesign** — Phases 7-10 (planned)
|
||||
|
||||
## Phases
|
||||
|
||||
<details>
|
||||
<summary>✅ v1.0 MVP (Phases 1-4) — SHIPPED YYYY-MM-DD</summary>
|
||||
|
||||
- [x] Phase 1: Foundation (2/2 plans) — completed YYYY-MM-DD
|
||||
- [x] Phase 2: Authentication (2/2 plans) — completed YYYY-MM-DD
|
||||
- [x] Phase 3: Core Features (3/3 plans) — completed YYYY-MM-DD
|
||||
- [x] Phase 4: Polish (1/1 plan) — completed YYYY-MM-DD
|
||||
|
||||
</details>
|
||||
|
||||
### 🚧 v[Next] [Name] (In Progress / Planned)
|
||||
|
||||
- [ ] Phase 5: [Name] ([N] plans)
|
||||
- [ ] Phase 6: [Name] ([N] plans)
|
||||
|
||||
## Progress
|
||||
|
||||
| Phase | Milestone | Plans Complete | Status | Completed |
|
||||
| ----------------- | --------- | -------------- | ----------- | ---------- |
|
||||
| 1. Foundation | v1.0 | 2/2 | Complete | YYYY-MM-DD |
|
||||
| 2. Authentication | v1.0 | 2/2 | Complete | YYYY-MM-DD |
|
||||
| 3. Core Features | v1.0 | 3/3 | Complete | YYYY-MM-DD |
|
||||
| 4. Polish | v1.0 | 1/1 | Complete | YYYY-MM-DD |
|
||||
| 5. Security Audit | v1.1 | 0/1 | Not started | - |
|
||||
| 6. Hardening | v1.1 | 0/2 | Not started | - |
|
||||
```
|
||||
|
||||
</step>
|
||||
|
||||
<step name="archive_milestone">
|
||||
|
||||
**Delegate archival to gsd-tools:**
|
||||
|
||||
```bash
|
||||
ARCHIVE=$(node "C:/Users/yaoji/.claude/get-shit-done/bin/gsd-tools.cjs" milestone complete "v[X.Y]" --name "[Milestone Name]")
|
||||
```
|
||||
|
||||
The CLI handles:
|
||||
- Creating `.planning/milestones/` directory
|
||||
- Archiving ROADMAP.md to `milestones/v[X.Y]-ROADMAP.md`
|
||||
- Archiving REQUIREMENTS.md to `milestones/v[X.Y]-REQUIREMENTS.md` with archive header
|
||||
- Moving audit file to milestones if it exists
|
||||
- Creating/appending MILESTONES.md entry with accomplishments from SUMMARY.md files
|
||||
- Updating STATE.md (status, last activity)
|
||||
|
||||
Extract from result: `version`, `date`, `phases`, `plans`, `tasks`, `accomplishments`, `archived`.
|
||||
|
||||
Verify: `✅ Milestone archived to .planning/milestones/`
|
||||
|
||||
**Phase archival (optional):** After archival completes, ask the user:
|
||||
|
||||
AskUserQuestion(header="Archive Phases", question="Archive phase directories to milestones/?", options: "Yes — move to milestones/v[X.Y]-phases/" | "Skip — keep phases in place")
|
||||
|
||||
If "Yes": move phase directories to the milestone archive:
|
||||
```bash
|
||||
mkdir -p .planning/milestones/v[X.Y]-phases
|
||||
# For each phase directory in .planning/phases/:
|
||||
mv .planning/phases/{phase-dir} .planning/milestones/v[X.Y]-phases/
|
||||
```
|
||||
Verify: `✅ Phase directories archived to .planning/milestones/v[X.Y]-phases/`
|
||||
|
||||
If "Skip": Phase directories remain in `.planning/phases/` as raw execution history. Use `/gsd:cleanup` later to archive retroactively.
|
||||
|
||||
After archival, the AI still handles:
|
||||
- Reorganizing ROADMAP.md with milestone grouping (requires judgment)
|
||||
- Full PROJECT.md evolution review (requires understanding)
|
||||
- Deleting original ROADMAP.md and REQUIREMENTS.md
|
||||
- These are NOT fully delegated because they require AI interpretation of content
|
||||
|
||||
</step>
|
||||
|
||||
<step name="reorganize_roadmap_and_delete_originals">
|
||||
|
||||
After `milestone complete` has archived, reorganize ROADMAP.md with milestone groupings, then delete originals:
|
||||
|
||||
**Reorganize ROADMAP.md** — group completed milestone phases:
|
||||
|
||||
```markdown
|
||||
# Roadmap: [Project Name]
|
||||
|
||||
## Milestones
|
||||
|
||||
- ✅ **v1.0 MVP** — Phases 1-4 (shipped YYYY-MM-DD)
|
||||
- 🚧 **v1.1 Security** — Phases 5-6 (in progress)
|
||||
|
||||
## Phases
|
||||
|
||||
<details>
|
||||
<summary>✅ v1.0 MVP (Phases 1-4) — SHIPPED YYYY-MM-DD</summary>
|
||||
|
||||
- [x] Phase 1: Foundation (2/2 plans) — completed YYYY-MM-DD
|
||||
- [x] Phase 2: Authentication (2/2 plans) — completed YYYY-MM-DD
|
||||
|
||||
</details>
|
||||
```
|
||||
|
||||
**Then delete originals:**
|
||||
|
||||
```bash
|
||||
rm .planning/ROADMAP.md
|
||||
rm .planning/REQUIREMENTS.md
|
||||
```
|
||||
|
||||
</step>
|
||||
|
||||
<step name="write_retrospective">
|
||||
|
||||
**Append to living retrospective:**
|
||||
|
||||
Check for existing retrospective:
|
||||
```bash
|
||||
ls .planning/RETROSPECTIVE.md 2>/dev/null
|
||||
```
|
||||
|
||||
**If exists:** Read the file, append new milestone section before the "## Cross-Milestone Trends" section.
|
||||
|
||||
**If doesn't exist:** Create from template at `C:/Users/yaoji/.claude/get-shit-done/templates/retrospective.md`.
|
||||
|
||||
**Gather retrospective data:**
|
||||
|
||||
1. From SUMMARY.md files: Extract key deliverables, one-liners, tech decisions
|
||||
2. From VERIFICATION.md files: Extract verification scores, gaps found
|
||||
3. From UAT.md files: Extract test results, issues found
|
||||
4. From git log: Count commits, calculate timeline
|
||||
5. From the milestone work: Reflect on what worked and what didn't
|
||||
|
||||
**Write the milestone section:**
|
||||
|
||||
```markdown
|
||||
## Milestone: v{version} — {name}
|
||||
|
||||
**Shipped:** {date}
|
||||
**Phases:** {phase_count} | **Plans:** {plan_count}
|
||||
|
||||
### What Was Built
|
||||
{Extract from SUMMARY.md one-liners}
|
||||
|
||||
### What Worked
|
||||
{Patterns that led to smooth execution}
|
||||
|
||||
### What Was Inefficient
|
||||
{Missed opportunities, rework, bottlenecks}
|
||||
|
||||
### Patterns Established
|
||||
{New conventions discovered during this milestone}
|
||||
|
||||
### Key Lessons
|
||||
{Specific, actionable takeaways}
|
||||
|
||||
### Cost Observations
|
||||
- Model mix: {X}% opus, {Y}% sonnet, {Z}% haiku
|
||||
- Sessions: {count}
|
||||
- Notable: {efficiency observation}
|
||||
```
|
||||
|
||||
**Update cross-milestone trends:**
|
||||
|
||||
If the "## Cross-Milestone Trends" section exists, update the tables with new data from this milestone.
|
||||
|
||||
**Commit:**
|
||||
```bash
|
||||
node "C:/Users/yaoji/.claude/get-shit-done/bin/gsd-tools.cjs" commit "docs: update retrospective for v${VERSION}" --files .planning/RETROSPECTIVE.md
|
||||
```
|
||||
|
||||
</step>
|
||||
|
||||
<step name="update_state">
|
||||
|
||||
Most STATE.md updates were handled by `milestone complete`, but verify and update remaining fields:
|
||||
|
||||
**Project Reference:**
|
||||
|
||||
```markdown
|
||||
## Project Reference
|
||||
|
||||
See: .planning/PROJECT.md (updated [today])
|
||||
|
||||
**Core value:** [Current core value from PROJECT.md]
|
||||
**Current focus:** [Next milestone or "Planning next milestone"]
|
||||
```
|
||||
|
||||
**Accumulated Context:**
|
||||
- Clear decisions summary (full log in PROJECT.md)
|
||||
- Clear resolved blockers
|
||||
- Keep open blockers for next milestone
|
||||
|
||||
</step>
|
||||
|
||||
<step name="handle_branches">
|
||||
|
||||
Check branching strategy and offer merge options.
|
||||
|
||||
Use `init milestone-op` for context, or load config directly:
|
||||
|
||||
```bash
|
||||
INIT=$(node "C:/Users/yaoji/.claude/get-shit-done/bin/gsd-tools.cjs" init execute-phase "1")
|
||||
if [[ "$INIT" == @file:* ]]; then INIT=$(cat "${INIT#@file:}"); fi
|
||||
```
|
||||
|
||||
Extract `branching_strategy`, `phase_branch_template`, `milestone_branch_template`, and `commit_docs` from init JSON.
|
||||
|
||||
**If "none":** Skip to git_tag.
|
||||
|
||||
**For "phase" strategy:**
|
||||
|
||||
```bash
|
||||
BRANCH_PREFIX=$(echo "$PHASE_BRANCH_TEMPLATE" | sed 's/{.*//')
|
||||
PHASE_BRANCHES=$(git branch --list "${BRANCH_PREFIX}*" 2>/dev/null | sed 's/^\*//' | tr -d ' ')
|
||||
```
|
||||
|
||||
**For "milestone" strategy:**
|
||||
|
||||
```bash
|
||||
BRANCH_PREFIX=$(echo "$MILESTONE_BRANCH_TEMPLATE" | sed 's/{.*//')
|
||||
MILESTONE_BRANCH=$(git branch --list "${BRANCH_PREFIX}*" 2>/dev/null | sed 's/^\*//' | tr -d ' ' | head -1)
|
||||
```
|
||||
|
||||
**If no branches found:** Skip to git_tag.
|
||||
|
||||
**If branches exist:**
|
||||
|
||||
```
|
||||
## Git Branches Detected
|
||||
|
||||
Branching strategy: {phase/milestone}
|
||||
Branches: {list}
|
||||
|
||||
Options:
|
||||
1. **Merge to main** — Merge branch(es) to main
|
||||
2. **Delete without merging** — Already merged or not needed
|
||||
3. **Keep branches** — Leave for manual handling
|
||||
```
|
||||
|
||||
AskUserQuestion with options: Squash merge (Recommended), Merge with history, Delete without merging, Keep branches.
|
||||
|
||||
**Squash merge:**
|
||||
|
||||
```bash
|
||||
CURRENT_BRANCH=$(git branch --show-current)
|
||||
git checkout main
|
||||
|
||||
if [ "$BRANCHING_STRATEGY" = "phase" ]; then
|
||||
for branch in $PHASE_BRANCHES; do
|
||||
git merge --squash "$branch"
|
||||
# Strip .planning/ from staging if commit_docs is false
|
||||
if [ "$COMMIT_DOCS" = "false" ]; then
|
||||
git reset HEAD .planning/ 2>/dev/null || true
|
||||
fi
|
||||
git commit -m "feat: $branch for v[X.Y]"
|
||||
done
|
||||
fi
|
||||
|
||||
if [ "$BRANCHING_STRATEGY" = "milestone" ]; then
|
||||
git merge --squash "$MILESTONE_BRANCH"
|
||||
# Strip .planning/ from staging if commit_docs is false
|
||||
if [ "$COMMIT_DOCS" = "false" ]; then
|
||||
git reset HEAD .planning/ 2>/dev/null || true
|
||||
fi
|
||||
git commit -m "feat: $MILESTONE_BRANCH for v[X.Y]"
|
||||
fi
|
||||
|
||||
git checkout "$CURRENT_BRANCH"
|
||||
```
|
||||
|
||||
**Merge with history:**
|
||||
|
||||
```bash
|
||||
CURRENT_BRANCH=$(git branch --show-current)
|
||||
git checkout main
|
||||
|
||||
if [ "$BRANCHING_STRATEGY" = "phase" ]; then
|
||||
for branch in $PHASE_BRANCHES; do
|
||||
git merge --no-ff --no-commit "$branch"
|
||||
# Strip .planning/ from staging if commit_docs is false
|
||||
if [ "$COMMIT_DOCS" = "false" ]; then
|
||||
git reset HEAD .planning/ 2>/dev/null || true
|
||||
fi
|
||||
git commit -m "Merge branch '$branch' for v[X.Y]"
|
||||
done
|
||||
fi
|
||||
|
||||
if [ "$BRANCHING_STRATEGY" = "milestone" ]; then
|
||||
git merge --no-ff --no-commit "$MILESTONE_BRANCH"
|
||||
# Strip .planning/ from staging if commit_docs is false
|
||||
if [ "$COMMIT_DOCS" = "false" ]; then
|
||||
git reset HEAD .planning/ 2>/dev/null || true
|
||||
fi
|
||||
git commit -m "Merge branch '$MILESTONE_BRANCH' for v[X.Y]"
|
||||
fi
|
||||
|
||||
git checkout "$CURRENT_BRANCH"
|
||||
```
|
||||
|
||||
**Delete without merging:**
|
||||
|
||||
```bash
|
||||
if [ "$BRANCHING_STRATEGY" = "phase" ]; then
|
||||
for branch in $PHASE_BRANCHES; do
|
||||
git branch -d "$branch" 2>/dev/null || git branch -D "$branch"
|
||||
done
|
||||
fi
|
||||
|
||||
if [ "$BRANCHING_STRATEGY" = "milestone" ]; then
|
||||
git branch -d "$MILESTONE_BRANCH" 2>/dev/null || git branch -D "$MILESTONE_BRANCH"
|
||||
fi
|
||||
```
|
||||
|
||||
**Keep branches:** Report "Branches preserved for manual handling"
|
||||
|
||||
</step>
|
||||
|
||||
<step name="git_tag">
|
||||
|
||||
Create git tag:
|
||||
|
||||
```bash
|
||||
git tag -a v[X.Y] -m "v[X.Y] [Name]
|
||||
|
||||
Delivered: [One sentence]
|
||||
|
||||
Key accomplishments:
|
||||
- [Item 1]
|
||||
- [Item 2]
|
||||
- [Item 3]
|
||||
|
||||
See .planning/MILESTONES.md for full details."
|
||||
```
|
||||
|
||||
Confirm: "Tagged: v[X.Y]"
|
||||
|
||||
Ask: "Push tag to remote? (y/n)"
|
||||
|
||||
If yes:
|
||||
```bash
|
||||
git push origin v[X.Y]
|
||||
```
|
||||
|
||||
</step>
|
||||
|
||||
<step name="git_commit_milestone">
|
||||
|
||||
Commit milestone completion.
|
||||
|
||||
```bash
|
||||
node "C:/Users/yaoji/.claude/get-shit-done/bin/gsd-tools.cjs" commit "chore: complete v[X.Y] milestone" --files .planning/milestones/v[X.Y]-ROADMAP.md .planning/milestones/v[X.Y]-REQUIREMENTS.md .planning/milestones/v[X.Y]-MILESTONE-AUDIT.md .planning/MILESTONES.md .planning/PROJECT.md .planning/STATE.md
|
||||
```
|
||||
```
|
||||
|
||||
Confirm: "Committed: chore: complete v[X.Y] milestone"
|
||||
|
||||
</step>
|
||||
|
||||
<step name="offer_next">
|
||||
|
||||
```
|
||||
✅ Milestone v[X.Y] [Name] complete
|
||||
|
||||
Shipped:
|
||||
- [N] phases ([M] plans, [P] tasks)
|
||||
- [One sentence of what shipped]
|
||||
|
||||
Archived:
|
||||
- milestones/v[X.Y]-ROADMAP.md
|
||||
- milestones/v[X.Y]-REQUIREMENTS.md
|
||||
|
||||
Summary: .planning/MILESTONES.md
|
||||
Tag: v[X.Y]
|
||||
|
||||
---
|
||||
|
||||
## ▶ Next Up
|
||||
|
||||
**Start Next Milestone** — questioning → research → requirements → roadmap
|
||||
|
||||
`/gsd:new-milestone`
|
||||
|
||||
<sub>`/clear` first → fresh context window</sub>
|
||||
|
||||
---
|
||||
```
|
||||
|
||||
</step>
|
||||
|
||||
</process>
|
||||
|
||||
<milestone_naming>
|
||||
|
||||
**Version conventions:**
|
||||
- **v1.0** — Initial MVP
|
||||
- **v1.1, v1.2** — Minor updates, new features, fixes
|
||||
- **v2.0, v3.0** — Major rewrites, breaking changes, new direction
|
||||
|
||||
**Names:** Short 1-2 words (v1.0 MVP, v1.1 Security, v1.2 Performance, v2.0 Redesign).
|
||||
|
||||
</milestone_naming>
|
||||
|
||||
<what_qualifies>
|
||||
|
||||
**Create milestones for:** Initial release, public releases, major feature sets shipped, before archiving planning.
|
||||
|
||||
**Don't create milestones for:** Every phase completion (too granular), work in progress, internal dev iterations (unless truly shipped).
|
||||
|
||||
Heuristic: "Is this deployed/usable/shipped?" If yes → milestone. If no → keep working.
|
||||
|
||||
</what_qualifies>
|
||||
|
||||
<success_criteria>
|
||||
|
||||
Milestone completion is successful when:
|
||||
|
||||
- [ ] MILESTONES.md entry created with stats and accomplishments
|
||||
- [ ] PROJECT.md full evolution review completed
|
||||
- [ ] All shipped requirements moved to Validated in PROJECT.md
|
||||
- [ ] Key Decisions updated with outcomes
|
||||
- [ ] ROADMAP.md reorganized with milestone grouping
|
||||
- [ ] Roadmap archive created (milestones/v[X.Y]-ROADMAP.md)
|
||||
- [ ] Requirements archive created (milestones/v[X.Y]-REQUIREMENTS.md)
|
||||
- [ ] REQUIREMENTS.md deleted (fresh for next milestone)
|
||||
- [ ] STATE.md updated with fresh project reference
|
||||
- [ ] Git tag created (v[X.Y])
|
||||
- [ ] Milestone commit made (includes archive files and deletion)
|
||||
- [ ] Requirements completion checked against REQUIREMENTS.md traceability table
|
||||
- [ ] Incomplete requirements surfaced with proceed/audit/abort options
|
||||
- [ ] Known gaps recorded in MILESTONES.md if user proceeded with incomplete requirements
|
||||
- [ ] RETROSPECTIVE.md updated with milestone section
|
||||
- [ ] Cross-milestone trends updated
|
||||
- [ ] User knows next step (/gsd:new-milestone)
|
||||
|
||||
</success_criteria>
|
||||
219
get-shit-done/workflows/diagnose-issues.md
Normal file
219
get-shit-done/workflows/diagnose-issues.md
Normal file
@@ -0,0 +1,219 @@
|
||||
<purpose>
|
||||
Orchestrate parallel debug agents to investigate UAT gaps and find root causes.
|
||||
|
||||
After UAT finds gaps, spawn one debug agent per gap. Each agent investigates autonomously with symptoms pre-filled from UAT. Collect root causes, update UAT.md gaps with diagnosis, then hand off to plan-phase --gaps with actual diagnoses.
|
||||
|
||||
Orchestrator stays lean: parse gaps, spawn agents, collect results, update UAT.
|
||||
</purpose>
|
||||
|
||||
<paths>
|
||||
DEBUG_DIR=.planning/debug
|
||||
|
||||
Debug files use the `.planning/debug/` path (hidden directory with leading dot).
|
||||
</paths>
|
||||
|
||||
<core_principle>
|
||||
**Diagnose before planning fixes.**
|
||||
|
||||
UAT tells us WHAT is broken (symptoms). Debug agents find WHY (root cause). plan-phase --gaps then creates targeted fixes based on actual causes, not guesses.
|
||||
|
||||
Without diagnosis: "Comment doesn't refresh" → guess at fix → maybe wrong
|
||||
With diagnosis: "Comment doesn't refresh" → "useEffect missing dependency" → precise fix
|
||||
</core_principle>
|
||||
|
||||
<process>
|
||||
|
||||
<step name="parse_gaps">
|
||||
**Extract gaps from UAT.md:**
|
||||
|
||||
Read the "Gaps" section (YAML format):
|
||||
```yaml
|
||||
- truth: "Comment appears immediately after submission"
|
||||
status: failed
|
||||
reason: "User reported: works but doesn't show until I refresh the page"
|
||||
severity: major
|
||||
test: 2
|
||||
artifacts: []
|
||||
missing: []
|
||||
```
|
||||
|
||||
For each gap, also read the corresponding test from "Tests" section to get full context.
|
||||
|
||||
Build gap list:
|
||||
```
|
||||
gaps = [
|
||||
{truth: "Comment appears immediately...", severity: "major", test_num: 2, reason: "..."},
|
||||
{truth: "Reply button positioned correctly...", severity: "minor", test_num: 5, reason: "..."},
|
||||
...
|
||||
]
|
||||
```
|
||||
</step>
|
||||
|
||||
<step name="report_plan">
|
||||
**Report diagnosis plan to user:**
|
||||
|
||||
```
|
||||
## Diagnosing {N} Gaps
|
||||
|
||||
Spawning parallel debug agents to investigate root causes:
|
||||
|
||||
| Gap (Truth) | Severity |
|
||||
|-------------|----------|
|
||||
| Comment appears immediately after submission | major |
|
||||
| Reply button positioned correctly | minor |
|
||||
| Delete removes comment | blocker |
|
||||
|
||||
Each agent will:
|
||||
1. Create DEBUG-{slug}.md with symptoms pre-filled
|
||||
2. Investigate autonomously (read code, form hypotheses, test)
|
||||
3. Return root cause
|
||||
|
||||
This runs in parallel - all gaps investigated simultaneously.
|
||||
```
|
||||
</step>
|
||||
|
||||
<step name="spawn_agents">
|
||||
**Spawn debug agents in parallel:**
|
||||
|
||||
For each gap, fill the debug-subagent-prompt template and spawn:
|
||||
|
||||
```
|
||||
Task(
|
||||
prompt=filled_debug_subagent_prompt + "\n\n<files_to_read>\n- {phase_dir}/{phase_num}-UAT.md\n- .planning/STATE.md\n</files_to_read>",
|
||||
subagent_type="gsd-debugger",
|
||||
description="Debug: {truth_short}"
|
||||
)
|
||||
```
|
||||
|
||||
**All agents spawn in single message** (parallel execution).
|
||||
|
||||
Template placeholders:
|
||||
- `{truth}`: The expected behavior that failed
|
||||
- `{expected}`: From UAT test
|
||||
- `{actual}`: Verbatim user description from reason field
|
||||
- `{errors}`: Any error messages from UAT (or "None reported")
|
||||
- `{reproduction}`: "Test {test_num} in UAT"
|
||||
- `{timeline}`: "Discovered during UAT"
|
||||
- `{goal}`: `find_root_cause_only` (UAT flow - plan-phase --gaps handles fixes)
|
||||
- `{slug}`: Generated from truth
|
||||
</step>
|
||||
|
||||
<step name="collect_results">
|
||||
**Collect root causes from agents:**
|
||||
|
||||
Each agent returns with:
|
||||
```
|
||||
## ROOT CAUSE FOUND
|
||||
|
||||
**Debug Session:** ${DEBUG_DIR}/{slug}.md
|
||||
|
||||
**Root Cause:** {specific cause with evidence}
|
||||
|
||||
**Evidence Summary:**
|
||||
- {key finding 1}
|
||||
- {key finding 2}
|
||||
- {key finding 3}
|
||||
|
||||
**Files Involved:**
|
||||
- {file1}: {what's wrong}
|
||||
- {file2}: {related issue}
|
||||
|
||||
**Suggested Fix Direction:** {brief hint for plan-phase --gaps}
|
||||
```
|
||||
|
||||
Parse each return to extract:
|
||||
- root_cause: The diagnosed cause
|
||||
- files: Files involved
|
||||
- debug_path: Path to debug session file
|
||||
- suggested_fix: Hint for gap closure plan
|
||||
|
||||
If agent returns `## INVESTIGATION INCONCLUSIVE`:
|
||||
- root_cause: "Investigation inconclusive - manual review needed"
|
||||
- Note which issue needs manual attention
|
||||
- Include remaining possibilities from agent return
|
||||
</step>
|
||||
|
||||
<step name="update_uat">
|
||||
**Update UAT.md gaps with diagnosis:**
|
||||
|
||||
For each gap in the Gaps section, add artifacts and missing fields:
|
||||
|
||||
```yaml
|
||||
- truth: "Comment appears immediately after submission"
|
||||
status: failed
|
||||
reason: "User reported: works but doesn't show until I refresh the page"
|
||||
severity: major
|
||||
test: 2
|
||||
root_cause: "useEffect in CommentList.tsx missing commentCount dependency"
|
||||
artifacts:
|
||||
- path: "src/components/CommentList.tsx"
|
||||
issue: "useEffect missing dependency"
|
||||
missing:
|
||||
- "Add commentCount to useEffect dependency array"
|
||||
- "Trigger re-render when new comment added"
|
||||
debug_session: .planning/debug/comment-not-refreshing.md
|
||||
```
|
||||
|
||||
Update status in frontmatter to "diagnosed".
|
||||
|
||||
Commit the updated UAT.md:
|
||||
```bash
|
||||
node "C:/Users/yaoji/.claude/get-shit-done/bin/gsd-tools.cjs" commit "docs({phase_num}): add root causes from diagnosis" --files ".planning/phases/XX-name/{phase_num}-UAT.md"
|
||||
```
|
||||
</step>
|
||||
|
||||
<step name="report_results">
|
||||
**Report diagnosis results and hand off:**
|
||||
|
||||
Display:
|
||||
```
|
||||
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
|
||||
GSD ► DIAGNOSIS COMPLETE
|
||||
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
|
||||
|
||||
| Gap (Truth) | Root Cause | Files |
|
||||
|-------------|------------|-------|
|
||||
| Comment appears immediately | useEffect missing dependency | CommentList.tsx |
|
||||
| Reply button positioned correctly | CSS flex order incorrect | ReplyButton.tsx |
|
||||
| Delete removes comment | API missing auth header | api/comments.ts |
|
||||
|
||||
Debug sessions: ${DEBUG_DIR}/
|
||||
|
||||
Proceeding to plan fixes...
|
||||
```
|
||||
|
||||
Return to verify-work orchestrator for automatic planning.
|
||||
Do NOT offer manual next steps - verify-work handles the rest.
|
||||
</step>
|
||||
|
||||
</process>
|
||||
|
||||
<context_efficiency>
|
||||
Agents start with symptoms pre-filled from UAT (no symptom gathering).
|
||||
Agents only diagnose—plan-phase --gaps handles fixes (no fix application).
|
||||
</context_efficiency>
|
||||
|
||||
<failure_handling>
|
||||
**Agent fails to find root cause:**
|
||||
- Mark gap as "needs manual review"
|
||||
- Continue with other gaps
|
||||
- Report incomplete diagnosis
|
||||
|
||||
**Agent times out:**
|
||||
- Check DEBUG-{slug}.md for partial progress
|
||||
- Can resume with /gsd:debug
|
||||
|
||||
**All agents fail:**
|
||||
- Something systemic (permissions, git, etc.)
|
||||
- Report for manual investigation
|
||||
- Fall back to plan-phase --gaps without root causes (less precise)
|
||||
</failure_handling>
|
||||
|
||||
<success_criteria>
|
||||
- [ ] Gaps parsed from UAT.md
|
||||
- [ ] Debug agents spawned in parallel
|
||||
- [ ] Root causes collected from all agents
|
||||
- [ ] UAT.md gaps updated with artifacts and missing
|
||||
- [ ] Debug sessions saved to ${DEBUG_DIR}/
|
||||
- [ ] Hand off to verify-work for automatic planning
|
||||
</success_criteria>
|
||||
289
get-shit-done/workflows/discovery-phase.md
Normal file
289
get-shit-done/workflows/discovery-phase.md
Normal file
@@ -0,0 +1,289 @@
|
||||
<purpose>
|
||||
Execute discovery at the appropriate depth level.
|
||||
Produces DISCOVERY.md (for Level 2-3) that informs PLAN.md creation.
|
||||
|
||||
Called from plan-phase.md's mandatory_discovery step with a depth parameter.
|
||||
|
||||
NOTE: For comprehensive ecosystem research ("how do experts build this"), use /gsd:research-phase instead, which produces RESEARCH.md.
|
||||
</purpose>
|
||||
|
||||
<depth_levels>
|
||||
**This workflow supports three depth levels:**
|
||||
|
||||
| Level | Name | Time | Output | When |
|
||||
| ----- | ------------ | --------- | -------------------------------------------- | ----------------------------------------- |
|
||||
| 1 | Quick Verify | 2-5 min | No file, proceed with verified knowledge | Single library, confirming current syntax |
|
||||
| 2 | Standard | 15-30 min | DISCOVERY.md | Choosing between options, new integration |
|
||||
| 3 | Deep Dive | 1+ hour | Detailed DISCOVERY.md with validation gates | Architectural decisions, novel problems |
|
||||
|
||||
**Depth is determined by plan-phase.md before routing here.**
|
||||
</depth_levels>
|
||||
|
||||
<source_hierarchy>
|
||||
**MANDATORY: Context7 BEFORE WebSearch**
|
||||
|
||||
Claude's training data is 6-18 months stale. Always verify.
|
||||
|
||||
1. **Context7 MCP FIRST** - Current docs, no hallucination
|
||||
2. **Official docs** - When Context7 lacks coverage
|
||||
3. **WebSearch LAST** - For comparisons and trends only
|
||||
|
||||
See C:/Users/yaoji/.claude/get-shit-done/templates/discovery.md `<discovery_protocol>` for full protocol.
|
||||
</source_hierarchy>
|
||||
|
||||
<process>
|
||||
|
||||
<step name="determine_depth">
|
||||
Check the depth parameter passed from plan-phase.md:
|
||||
- `depth=verify` → Level 1 (Quick Verification)
|
||||
- `depth=standard` → Level 2 (Standard Discovery)
|
||||
- `depth=deep` → Level 3 (Deep Dive)
|
||||
|
||||
Route to appropriate level workflow below.
|
||||
</step>
|
||||
|
||||
<step name="level_1_quick_verify">
|
||||
**Level 1: Quick Verification (2-5 minutes)**
|
||||
|
||||
For: Single known library, confirming syntax/version still correct.
|
||||
|
||||
**Process:**
|
||||
|
||||
1. Resolve library in Context7:
|
||||
|
||||
```
|
||||
mcp__context7__resolve-library-id with libraryName: "[library]"
|
||||
```
|
||||
|
||||
2. Fetch relevant docs:
|
||||
|
||||
```
|
||||
mcp__context7__get-library-docs with:
|
||||
- context7CompatibleLibraryID: [from step 1]
|
||||
- topic: [specific concern]
|
||||
```
|
||||
|
||||
3. Verify:
|
||||
|
||||
- Current version matches expectations
|
||||
- API syntax unchanged
|
||||
- No breaking changes in recent versions
|
||||
|
||||
4. **If verified:** Return to plan-phase.md with confirmation. No DISCOVERY.md needed.
|
||||
|
||||
5. **If concerns found:** Escalate to Level 2.
|
||||
|
||||
**Output:** Verbal confirmation to proceed, or escalation to Level 2.
|
||||
</step>
|
||||
|
||||
<step name="level_2_standard">
|
||||
**Level 2: Standard Discovery (15-30 minutes)**
|
||||
|
||||
For: Choosing between options, new external integration.
|
||||
|
||||
**Process:**
|
||||
|
||||
1. **Identify what to discover:**
|
||||
|
||||
- What options exist?
|
||||
- What are the key comparison criteria?
|
||||
- What's our specific use case?
|
||||
|
||||
2. **Context7 for each option:**
|
||||
|
||||
```
|
||||
For each library/framework:
|
||||
- mcp__context7__resolve-library-id
|
||||
- mcp__context7__get-library-docs (mode: "code" for API, "info" for concepts)
|
||||
```
|
||||
|
||||
3. **Official docs** for anything Context7 lacks.
|
||||
|
||||
4. **WebSearch** for comparisons:
|
||||
|
||||
- "[option A] vs [option B] {current_year}"
|
||||
- "[option] known issues"
|
||||
- "[option] with [our stack]"
|
||||
|
||||
5. **Cross-verify:** Any WebSearch finding → confirm with Context7/official docs.
|
||||
|
||||
6. **Create DISCOVERY.md** using C:/Users/yaoji/.claude/get-shit-done/templates/discovery.md structure:
|
||||
|
||||
- Summary with recommendation
|
||||
- Key findings per option
|
||||
- Code examples from Context7
|
||||
- Confidence level (should be MEDIUM-HIGH for Level 2)
|
||||
|
||||
7. Return to plan-phase.md.
|
||||
|
||||
**Output:** `.planning/phases/XX-name/DISCOVERY.md`
|
||||
</step>
|
||||
|
||||
<step name="level_3_deep_dive">
|
||||
**Level 3: Deep Dive (1+ hour)**
|
||||
|
||||
For: Architectural decisions, novel problems, high-risk choices.
|
||||
|
||||
**Process:**
|
||||
|
||||
1. **Scope the discovery** using C:/Users/yaoji/.claude/get-shit-done/templates/discovery.md:
|
||||
|
||||
- Define clear scope
|
||||
- Define include/exclude boundaries
|
||||
- List specific questions to answer
|
||||
|
||||
2. **Exhaustive Context7 research:**
|
||||
|
||||
- All relevant libraries
|
||||
- Related patterns and concepts
|
||||
- Multiple topics per library if needed
|
||||
|
||||
3. **Official documentation deep read:**
|
||||
|
||||
- Architecture guides
|
||||
- Best practices sections
|
||||
- Migration/upgrade guides
|
||||
- Known limitations
|
||||
|
||||
4. **WebSearch for ecosystem context:**
|
||||
|
||||
- How others solved similar problems
|
||||
- Production experiences
|
||||
- Gotchas and anti-patterns
|
||||
- Recent changes/announcements
|
||||
|
||||
5. **Cross-verify ALL findings:**
|
||||
|
||||
- Every WebSearch claim → verify with authoritative source
|
||||
- Mark what's verified vs assumed
|
||||
- Flag contradictions
|
||||
|
||||
6. **Create comprehensive DISCOVERY.md:**
|
||||
|
||||
- Full structure from C:/Users/yaoji/.claude/get-shit-done/templates/discovery.md
|
||||
- Quality report with source attribution
|
||||
- Confidence by finding
|
||||
- If LOW confidence on any critical finding → add validation checkpoints
|
||||
|
||||
7. **Confidence gate:** If overall confidence is LOW, present options before proceeding.
|
||||
|
||||
8. Return to plan-phase.md.
|
||||
|
||||
**Output:** `.planning/phases/XX-name/DISCOVERY.md` (comprehensive)
|
||||
</step>
|
||||
|
||||
<step name="identify_unknowns">
|
||||
**For Level 2-3:** Define what we need to learn.
|
||||
|
||||
Ask: What do we need to learn before we can plan this phase?
|
||||
|
||||
- Technology choices?
|
||||
- Best practices?
|
||||
- API patterns?
|
||||
- Architecture approach?
|
||||
</step>
|
||||
|
||||
<step name="create_discovery_scope">
|
||||
Use C:/Users/yaoji/.claude/get-shit-done/templates/discovery.md.
|
||||
|
||||
Include:
|
||||
|
||||
- Clear discovery objective
|
||||
- Scoped include/exclude lists
|
||||
- Source preferences (official docs, Context7, current year)
|
||||
- Output structure for DISCOVERY.md
|
||||
</step>
|
||||
|
||||
<step name="execute_discovery">
|
||||
Run the discovery:
|
||||
- Use web search for current info
|
||||
- Use Context7 MCP for library docs
|
||||
- Prefer current year sources
|
||||
- Structure findings per template
|
||||
</step>
|
||||
|
||||
<step name="create_discovery_output">
|
||||
Write `.planning/phases/XX-name/DISCOVERY.md`:
|
||||
- Summary with recommendation
|
||||
- Key findings with sources
|
||||
- Code examples if applicable
|
||||
- Metadata (confidence, dependencies, open questions, assumptions)
|
||||
</step>
|
||||
|
||||
<step name="confidence_gate">
|
||||
After creating DISCOVERY.md, check confidence level.
|
||||
|
||||
If confidence is LOW:
|
||||
Use AskUserQuestion:
|
||||
|
||||
- header: "Low Conf."
|
||||
- question: "Discovery confidence is LOW: [reason]. How would you like to proceed?"
|
||||
- options:
|
||||
- "Dig deeper" - Do more research before planning
|
||||
- "Proceed anyway" - Accept uncertainty, plan with caveats
|
||||
- "Pause" - I need to think about this
|
||||
|
||||
If confidence is MEDIUM:
|
||||
Inline: "Discovery complete (medium confidence). [brief reason]. Proceed to planning?"
|
||||
|
||||
If confidence is HIGH:
|
||||
Proceed directly, just note: "Discovery complete (high confidence)."
|
||||
</step>
|
||||
|
||||
<step name="open_questions_gate">
|
||||
If DISCOVERY.md has open_questions:
|
||||
|
||||
Present them inline:
|
||||
"Open questions from discovery:
|
||||
|
||||
- [Question 1]
|
||||
- [Question 2]
|
||||
|
||||
These may affect implementation. Acknowledge and proceed? (yes / address first)"
|
||||
|
||||
If "address first": Gather user input on questions, update discovery.
|
||||
</step>
|
||||
|
||||
<step name="offer_next">
|
||||
```
|
||||
Discovery complete: .planning/phases/XX-name/DISCOVERY.md
|
||||
Recommendation: [one-liner]
|
||||
Confidence: [level]
|
||||
|
||||
What's next?
|
||||
|
||||
1. Discuss phase context (/gsd:discuss-phase [current-phase])
|
||||
2. Create phase plan (/gsd:plan-phase [current-phase])
|
||||
3. Refine discovery (dig deeper)
|
||||
4. Review discovery
|
||||
|
||||
```
|
||||
|
||||
NOTE: DISCOVERY.md is NOT committed separately. It will be committed with phase completion.
|
||||
</step>
|
||||
|
||||
</process>
|
||||
|
||||
<success_criteria>
|
||||
**Level 1 (Quick Verify):**
|
||||
- Context7 consulted for library/topic
|
||||
- Current state verified or concerns escalated
|
||||
- Verbal confirmation to proceed (no files)
|
||||
|
||||
**Level 2 (Standard):**
|
||||
- Context7 consulted for all options
|
||||
- WebSearch findings cross-verified
|
||||
- DISCOVERY.md created with recommendation
|
||||
- Confidence level MEDIUM or higher
|
||||
- Ready to inform PLAN.md creation
|
||||
|
||||
**Level 3 (Deep Dive):**
|
||||
- Discovery scope defined
|
||||
- Context7 exhaustively consulted
|
||||
- All WebSearch findings verified against authoritative sources
|
||||
- DISCOVERY.md created with comprehensive analysis
|
||||
- Quality report with source attribution
|
||||
- If LOW confidence findings → validation checkpoints defined
|
||||
- Confidence gate passed
|
||||
- Ready to inform PLAN.md creation
|
||||
</success_criteria>
|
||||
764
get-shit-done/workflows/discuss-phase.md
Normal file
764
get-shit-done/workflows/discuss-phase.md
Normal file
@@ -0,0 +1,764 @@
|
||||
<purpose>
|
||||
Extract implementation decisions that downstream agents need. Analyze the phase to identify gray areas, let the user choose what to discuss, then deep-dive each selected area until satisfied.
|
||||
|
||||
You are a thinking partner, not an interviewer. The user is the visionary — you are the builder. Your job is to capture decisions that will guide research and planning, not to figure out implementation yourself.
|
||||
</purpose>
|
||||
|
||||
<downstream_awareness>
|
||||
**CONTEXT.md feeds into:**
|
||||
|
||||
1. **gsd-phase-researcher** — Reads CONTEXT.md to know WHAT to research
|
||||
- "User wants card-based layout" → researcher investigates card component patterns
|
||||
- "Infinite scroll decided" → researcher looks into virtualization libraries
|
||||
|
||||
2. **gsd-planner** — Reads CONTEXT.md to know WHAT decisions are locked
|
||||
- "Pull-to-refresh on mobile" → planner includes that in task specs
|
||||
- "Claude's Discretion: loading skeleton" → planner can decide approach
|
||||
|
||||
**Your job:** Capture decisions clearly enough that downstream agents can act on them without asking the user again.
|
||||
|
||||
**Not your job:** Figure out HOW to implement. That's what research and planning do with the decisions you capture.
|
||||
</downstream_awareness>
|
||||
|
||||
<philosophy>
|
||||
**User = founder/visionary. Claude = builder.**
|
||||
|
||||
The user knows:
|
||||
- How they imagine it working
|
||||
- What it should look/feel like
|
||||
- What's essential vs nice-to-have
|
||||
- Specific behaviors or references they have in mind
|
||||
|
||||
The user doesn't know (and shouldn't be asked):
|
||||
- Codebase patterns (researcher reads the code)
|
||||
- Technical risks (researcher identifies these)
|
||||
- Implementation approach (planner figures this out)
|
||||
- Success metrics (inferred from the work)
|
||||
|
||||
Ask about vision and implementation choices. Capture decisions for downstream agents.
|
||||
</philosophy>
|
||||
|
||||
<scope_guardrail>
|
||||
**CRITICAL: No scope creep.**
|
||||
|
||||
The phase boundary comes from ROADMAP.md and is FIXED. Discussion clarifies HOW to implement what's scoped, never WHETHER to add new capabilities.
|
||||
|
||||
**Allowed (clarifying ambiguity):**
|
||||
- "How should posts be displayed?" (layout, density, info shown)
|
||||
- "What happens on empty state?" (within the feature)
|
||||
- "Pull to refresh or manual?" (behavior choice)
|
||||
|
||||
**Not allowed (scope creep):**
|
||||
- "Should we also add comments?" (new capability)
|
||||
- "What about search/filtering?" (new capability)
|
||||
- "Maybe include bookmarking?" (new capability)
|
||||
|
||||
**The heuristic:** Does this clarify how we implement what's already in the phase, or does it add a new capability that could be its own phase?
|
||||
|
||||
**When user suggests scope creep:**
|
||||
```
|
||||
"[Feature X] would be a new capability — that's its own phase.
|
||||
Want me to note it for the roadmap backlog?
|
||||
|
||||
For now, let's focus on [phase domain]."
|
||||
```
|
||||
|
||||
Capture the idea in a "Deferred Ideas" section. Don't lose it, don't act on it.
|
||||
</scope_guardrail>
|
||||
|
||||
<gray_area_identification>
|
||||
Gray areas are **implementation decisions the user cares about** — things that could go multiple ways and would change the result.
|
||||
|
||||
**How to identify gray areas:**
|
||||
|
||||
1. **Read the phase goal** from ROADMAP.md
|
||||
2. **Understand the domain** — What kind of thing is being built?
|
||||
- Something users SEE → visual presentation, interactions, states matter
|
||||
- Something users CALL → interface contracts, responses, errors matter
|
||||
- Something users RUN → invocation, output, behavior modes matter
|
||||
- Something users READ → structure, tone, depth, flow matter
|
||||
- Something being ORGANIZED → criteria, grouping, handling exceptions matter
|
||||
3. **Generate phase-specific gray areas** — Not generic categories, but concrete decisions for THIS phase
|
||||
|
||||
**Don't use generic category labels** (UI, UX, Behavior). Generate specific gray areas:
|
||||
|
||||
```
|
||||
Phase: "User authentication"
|
||||
→ Session handling, Error responses, Multi-device policy, Recovery flow
|
||||
|
||||
Phase: "Organize photo library"
|
||||
→ Grouping criteria, Duplicate handling, Naming convention, Folder structure
|
||||
|
||||
Phase: "CLI for database backups"
|
||||
→ Output format, Flag design, Progress reporting, Error recovery
|
||||
|
||||
Phase: "API documentation"
|
||||
→ Structure/navigation, Code examples depth, Versioning approach, Interactive elements
|
||||
```
|
||||
|
||||
**The key question:** What decisions would change the outcome that the user should weigh in on?
|
||||
|
||||
**Claude handles these (don't ask):**
|
||||
- Technical implementation details
|
||||
- Architecture patterns
|
||||
- Performance optimization
|
||||
- Scope (roadmap defines this)
|
||||
</gray_area_identification>
|
||||
|
||||
<answer_validation>
|
||||
**IMPORTANT: Answer validation** — After every AskUserQuestion call, check if the response is empty or whitespace-only. If so:
|
||||
1. Retry the question once with the same parameters
|
||||
2. If still empty, present the options as a plain-text numbered list and ask the user to type their choice number
|
||||
Never proceed with an empty answer.
|
||||
</answer_validation>
|
||||
|
||||
<process>
|
||||
|
||||
**Express path available:** If you already have a PRD or acceptance criteria document, use `/gsd:plan-phase {phase} --prd path/to/prd.md` to skip this discussion and go straight to planning.
|
||||
|
||||
<step name="initialize" priority="first">
|
||||
Phase number from argument (required).
|
||||
|
||||
```bash
|
||||
INIT=$(node "C:/Users/yaoji/.claude/get-shit-done/bin/gsd-tools.cjs" init phase-op "${PHASE}")
|
||||
if [[ "$INIT" == @file:* ]]; then INIT=$(cat "${INIT#@file:}"); fi
|
||||
```
|
||||
|
||||
Parse JSON for: `commit_docs`, `phase_found`, `phase_dir`, `phase_number`, `phase_name`, `phase_slug`, `padded_phase`, `has_research`, `has_context`, `has_plans`, `has_verification`, `plan_count`, `roadmap_exists`, `planning_exists`.
|
||||
|
||||
**If `phase_found` is false:**
|
||||
```
|
||||
Phase [X] not found in roadmap.
|
||||
|
||||
Use /gsd:progress to see available phases.
|
||||
```
|
||||
Exit workflow.
|
||||
|
||||
**If `phase_found` is true:** Continue to check_existing.
|
||||
|
||||
**Auto mode** — If `--auto` is present in ARGUMENTS:
|
||||
- In `check_existing`: auto-select "Skip" (if context exists) or continue without prompting (if no context/plans)
|
||||
- In `present_gray_areas`: auto-select ALL gray areas without asking the user
|
||||
- In `discuss_areas`: for each discussion question, choose the recommended option (first option, or the one marked "recommended") without using AskUserQuestion
|
||||
- Log each auto-selected choice inline so the user can review decisions in the context file
|
||||
- After discussion completes, auto-advance to plan-phase (existing behavior)
|
||||
</step>
|
||||
|
||||
<step name="check_existing">
|
||||
Check if CONTEXT.md already exists using `has_context` from init.
|
||||
|
||||
```bash
|
||||
ls ${phase_dir}/*-CONTEXT.md 2>/dev/null
|
||||
```
|
||||
|
||||
**If exists:**
|
||||
|
||||
**If `--auto`:** Auto-select "Update it" — load existing context and continue to analyze_phase. Log: `[auto] Context exists — updating with auto-selected decisions.`
|
||||
|
||||
**Otherwise:** Use AskUserQuestion:
|
||||
- header: "Context"
|
||||
- question: "Phase [X] already has context. What do you want to do?"
|
||||
- options:
|
||||
- "Update it" — Review and revise existing context
|
||||
- "View it" — Show me what's there
|
||||
- "Skip" — Use existing context as-is
|
||||
|
||||
If "Update": Load existing, continue to analyze_phase
|
||||
If "View": Display CONTEXT.md, then offer update/skip
|
||||
If "Skip": Exit workflow
|
||||
|
||||
**If doesn't exist:**
|
||||
|
||||
Check `has_plans` and `plan_count` from init. **If `has_plans` is true:**
|
||||
|
||||
**If `--auto`:** Auto-select "Continue and replan after". Log: `[auto] Plans exist — continuing with context capture, will replan after.`
|
||||
|
||||
**Otherwise:** Use AskUserQuestion:
|
||||
- header: "Plans exist"
|
||||
- question: "Phase [X] already has {plan_count} plan(s) created without user context. Your decisions here won't affect existing plans unless you replan."
|
||||
- options:
|
||||
- "Continue and replan after" — Capture context, then run /gsd:plan-phase {X} to replan
|
||||
- "View existing plans" — Show plans before deciding
|
||||
- "Cancel" — Skip discuss-phase
|
||||
|
||||
If "Continue and replan after": Continue to analyze_phase.
|
||||
If "View existing plans": Display plan files, then offer "Continue" / "Cancel".
|
||||
If "Cancel": Exit workflow.
|
||||
|
||||
**If `has_plans` is false:** Continue to load_prior_context.
|
||||
</step>
|
||||
|
||||
<step name="load_prior_context">
|
||||
Read project-level and prior phase context to avoid re-asking decided questions and maintain consistency.
|
||||
|
||||
**Step 1: Read project-level files**
|
||||
```bash
|
||||
# Core project files
|
||||
cat .planning/PROJECT.md 2>/dev/null
|
||||
cat .planning/REQUIREMENTS.md 2>/dev/null
|
||||
cat .planning/STATE.md 2>/dev/null
|
||||
```
|
||||
|
||||
Extract from these:
|
||||
- **PROJECT.md** — Vision, principles, non-negotiables, user preferences
|
||||
- **REQUIREMENTS.md** — Acceptance criteria, constraints, must-haves vs nice-to-haves
|
||||
- **STATE.md** — Current progress, any flags or session notes
|
||||
|
||||
**Step 2: Read all prior CONTEXT.md files**
|
||||
```bash
|
||||
# Find all CONTEXT.md files from phases before current
|
||||
find .planning/phases -name "*-CONTEXT.md" 2>/dev/null | sort
|
||||
```
|
||||
|
||||
For each CONTEXT.md where phase number < current phase:
|
||||
- Read the `<decisions>` section — these are locked preferences
|
||||
- Read `<specifics>` — particular references or "I want it like X" moments
|
||||
- Note any patterns (e.g., "user consistently prefers minimal UI", "user rejected single-key shortcuts")
|
||||
|
||||
**Step 3: Build internal `<prior_decisions>` context**
|
||||
|
||||
Structure the extracted information:
|
||||
```
|
||||
<prior_decisions>
|
||||
## Project-Level
|
||||
- [Key principle or constraint from PROJECT.md]
|
||||
- [Requirement that affects this phase from REQUIREMENTS.md]
|
||||
|
||||
## From Prior Phases
|
||||
### Phase N: [Name]
|
||||
- [Decision that may be relevant to current phase]
|
||||
- [Preference that establishes a pattern]
|
||||
|
||||
### Phase M: [Name]
|
||||
- [Another relevant decision]
|
||||
</prior_decisions>
|
||||
```
|
||||
|
||||
**Usage in subsequent steps:**
|
||||
- `analyze_phase`: Skip gray areas already decided in prior phases
|
||||
- `present_gray_areas`: Annotate options with prior decisions ("You chose X in Phase 5")
|
||||
- `discuss_areas`: Pre-fill answers or flag conflicts ("This contradicts Phase 3 — same here or different?")
|
||||
|
||||
**If no prior context exists:** Continue without — this is expected for early phases.
|
||||
</step>
|
||||
|
||||
<step name="scout_codebase">
|
||||
Lightweight scan of existing code to inform gray area identification and discussion. Uses ~10% context — acceptable for an interactive session.
|
||||
|
||||
**Step 1: Check for existing codebase maps**
|
||||
```bash
|
||||
ls .planning/codebase/*.md 2>/dev/null
|
||||
```
|
||||
|
||||
**If codebase maps exist:** Read the most relevant ones (CONVENTIONS.md, STRUCTURE.md, STACK.md based on phase type). Extract:
|
||||
- Reusable components/hooks/utilities
|
||||
- Established patterns (state management, styling, data fetching)
|
||||
- Integration points (where new code would connect)
|
||||
|
||||
Skip to Step 3 below.
|
||||
|
||||
**Step 2: If no codebase maps, do targeted grep**
|
||||
|
||||
Extract key terms from the phase goal (e.g., "feed" → "post", "card", "list"; "auth" → "login", "session", "token").
|
||||
|
||||
```bash
|
||||
# Find files related to phase goal terms
|
||||
grep -rl "{term1}\|{term2}" src/ app/ --include="*.ts" --include="*.tsx" --include="*.js" --include="*.jsx" 2>/dev/null | head -10
|
||||
|
||||
# Find existing components/hooks
|
||||
ls src/components/ 2>/dev/null
|
||||
ls src/hooks/ 2>/dev/null
|
||||
ls src/lib/ src/utils/ 2>/dev/null
|
||||
```
|
||||
|
||||
Read the 3-5 most relevant files to understand existing patterns.
|
||||
|
||||
**Step 3: Build internal codebase_context**
|
||||
|
||||
From the scan, identify:
|
||||
- **Reusable assets** — existing components, hooks, utilities that could be used in this phase
|
||||
- **Established patterns** — how the codebase does state management, styling, data fetching
|
||||
- **Integration points** — where new code would connect (routes, nav, providers)
|
||||
- **Creative options** — approaches the existing architecture enables or constrains
|
||||
|
||||
Store as internal `<codebase_context>` for use in analyze_phase and present_gray_areas. This is NOT written to a file — it's used within this session only.
|
||||
</step>
|
||||
|
||||
<step name="analyze_phase">
|
||||
Analyze the phase to identify gray areas worth discussing. **Use both `prior_decisions` and `codebase_context` to ground the analysis.**
|
||||
|
||||
**Read the phase description from ROADMAP.md and determine:**
|
||||
|
||||
1. **Domain boundary** — What capability is this phase delivering? State it clearly.
|
||||
|
||||
1b. **Initialize canonical refs accumulator** — Start building the `<canonical_refs>` list for CONTEXT.md. This accumulates throughout the entire discussion, not just this step.
|
||||
|
||||
**Source 1 (now):** Copy `Canonical refs:` from ROADMAP.md for this phase. Expand each to a full relative path.
|
||||
**Source 2 (now):** Check REQUIREMENTS.md and PROJECT.md for any specs/ADRs referenced for this phase.
|
||||
**Source 3 (scout_codebase):** If existing code references docs (e.g., comments citing ADRs), add those.
|
||||
**Source 4 (discuss_areas):** When the user says "read X", "check Y", or references any doc/spec/ADR during discussion — add it immediately. These are often the MOST important refs because they represent docs the user specifically wants followed.
|
||||
|
||||
This list is MANDATORY in CONTEXT.md. Every ref must have a full relative path so downstream agents can read it directly. If no external docs exist, note that explicitly.
|
||||
|
||||
2. **Check prior decisions** — Before generating gray areas, check if any were already decided:
|
||||
- Scan `<prior_decisions>` for relevant choices (e.g., "Ctrl+C only, no single-key shortcuts")
|
||||
- These are **pre-answered** — don't re-ask unless this phase has conflicting needs
|
||||
- Note applicable prior decisions for use in presentation
|
||||
|
||||
3. **Gray areas by category** — For each relevant category (UI, UX, Behavior, Empty States, Content), identify 1-2 specific ambiguities that would change implementation. **Annotate with code context where relevant** (e.g., "You already have a Card component" or "No existing pattern for this").
|
||||
|
||||
4. **Skip assessment** — If no meaningful gray areas exist (pure infrastructure, clear-cut implementation, or all already decided in prior phases), the phase may not need discussion.
|
||||
|
||||
**Output your analysis internally, then present to user.**
|
||||
|
||||
Example analysis for "Post Feed" phase (with code and prior context):
|
||||
```
|
||||
Domain: Displaying posts from followed users
|
||||
Existing: Card component (src/components/ui/Card.tsx), useInfiniteQuery hook, Tailwind CSS
|
||||
Prior decisions: "Minimal UI preferred" (Phase 2), "No pagination — always infinite scroll" (Phase 4)
|
||||
Gray areas:
|
||||
- UI: Layout style (cards vs timeline vs grid) — Card component exists with shadow/rounded variants
|
||||
- UI: Information density (full posts vs previews) — no existing density patterns
|
||||
- Behavior: Loading pattern — ALREADY DECIDED: infinite scroll (Phase 4)
|
||||
- Empty State: What shows when no posts exist — EmptyState component exists in ui/
|
||||
- Content: What metadata displays (time, author, reactions count)
|
||||
```
|
||||
</step>
|
||||
|
||||
<step name="present_gray_areas">
|
||||
Present the domain boundary, prior decisions, and gray areas to user.
|
||||
|
||||
**First, state the boundary and any prior decisions that apply:**
|
||||
```
|
||||
Phase [X]: [Name]
|
||||
Domain: [What this phase delivers — from your analysis]
|
||||
|
||||
We'll clarify HOW to implement this.
|
||||
(New capabilities belong in other phases.)
|
||||
|
||||
[If prior decisions apply:]
|
||||
**Carrying forward from earlier phases:**
|
||||
- [Decision from Phase N that applies here]
|
||||
- [Decision from Phase M that applies here]
|
||||
```
|
||||
|
||||
**If `--auto`:** Auto-select ALL gray areas. Log: `[auto] Selected all gray areas: [list area names].` Skip the AskUserQuestion below and continue directly to discuss_areas with all areas selected.
|
||||
|
||||
**Otherwise, use AskUserQuestion (multiSelect: true):**
|
||||
- header: "Discuss"
|
||||
- question: "Which areas do you want to discuss for [phase name]?"
|
||||
- options: Generate 3-4 phase-specific gray areas, each with:
|
||||
- "[Specific area]" (label) — concrete, not generic
|
||||
- [1-2 questions this covers + code context annotation] (description)
|
||||
- **Highlight the recommended choice with brief explanation why**
|
||||
|
||||
**Prior decision annotations:** When a gray area was already decided in a prior phase, annotate it:
|
||||
```
|
||||
☐ Exit shortcuts — How should users quit?
|
||||
(You decided "Ctrl+C only, no single-key shortcuts" in Phase 5 — revisit or keep?)
|
||||
```
|
||||
|
||||
**Code context annotations:** When the scout found relevant existing code, annotate the gray area description:
|
||||
```
|
||||
☐ Layout style — Cards vs list vs timeline?
|
||||
(You already have a Card component with shadow/rounded variants. Reusing it keeps the app consistent.)
|
||||
```
|
||||
|
||||
**Combining both:** When both prior decisions and code context apply:
|
||||
```
|
||||
☐ Loading behavior — Infinite scroll or pagination?
|
||||
(You chose infinite scroll in Phase 4. useInfiniteQuery hook already set up.)
|
||||
```
|
||||
|
||||
**Do NOT include a "skip" or "you decide" option.** User ran this command to discuss — give them real choices.
|
||||
|
||||
**Examples by domain (with code context):**
|
||||
|
||||
For "Post Feed" (visual feature):
|
||||
```
|
||||
☐ Layout style — Cards vs list vs timeline? (Card component exists with variants)
|
||||
☐ Loading behavior — Infinite scroll or pagination? (useInfiniteQuery hook available)
|
||||
☐ Content ordering — Chronological, algorithmic, or user choice?
|
||||
☐ Post metadata — What info per post? Timestamps, reactions, author?
|
||||
```
|
||||
|
||||
For "Database backup CLI" (command-line tool):
|
||||
```
|
||||
☐ Output format — JSON, table, or plain text? Verbosity levels?
|
||||
☐ Flag design — Short flags, long flags, or both? Required vs optional?
|
||||
☐ Progress reporting — Silent, progress bar, or verbose logging?
|
||||
☐ Error recovery — Fail fast, retry, or prompt for action?
|
||||
```
|
||||
|
||||
For "Organize photo library" (organization task):
|
||||
```
|
||||
☐ Grouping criteria — By date, location, faces, or events?
|
||||
☐ Duplicate handling — Keep best, keep all, or prompt each time?
|
||||
☐ Naming convention — Original names, dates, or descriptive?
|
||||
☐ Folder structure — Flat, nested by year, or by category?
|
||||
```
|
||||
|
||||
Continue to discuss_areas with selected areas.
|
||||
</step>
|
||||
|
||||
<step name="discuss_areas">
|
||||
For each selected area, conduct a focused discussion loop.
|
||||
|
||||
**Batch mode support:** Parse optional `--batch` from `$ARGUMENTS`.
|
||||
- Accept `--batch`, `--batch=N`, or `--batch N`
|
||||
- Default to 4 questions per batch when no number is provided
|
||||
- Clamp explicit sizes to 2-5 so a batch stays answerable
|
||||
- If `--batch` is absent, keep the existing one-question-at-a-time flow
|
||||
|
||||
**Philosophy:** stay adaptive, but let the user choose the pacing.
|
||||
- Default mode: 4 single-question turns, then check whether to continue
|
||||
- `--batch` mode: 1 grouped turn with 2-5 numbered questions, then check whether to continue
|
||||
|
||||
Each answer (or answer set, in batch mode) should reveal the next question or next batch.
|
||||
|
||||
**Auto mode (`--auto`):** For each area, Claude selects the recommended option (first option, or the one explicitly marked "recommended") for every question without using AskUserQuestion. Log each auto-selected choice:
|
||||
```
|
||||
[auto] [Area] — Q: "[question text]" → Selected: "[chosen option]" (recommended default)
|
||||
```
|
||||
After all areas are auto-resolved, skip the "Explore more gray areas" prompt and proceed directly to write_context.
|
||||
|
||||
**Interactive mode (no `--auto`):**
|
||||
|
||||
**For each area:**
|
||||
|
||||
1. **Announce the area:**
|
||||
```
|
||||
Let's talk about [Area].
|
||||
```
|
||||
|
||||
2. **Ask questions using the selected pacing:**
|
||||
|
||||
**Default (no `--batch`): Ask 4 questions using AskUserQuestion**
|
||||
- header: "[Area]" (max 12 chars — abbreviate if needed)
|
||||
- question: Specific decision for this area
|
||||
- options: 2-3 concrete choices (AskUserQuestion adds "Other" automatically), with the recommended choice highlighted and brief explanation why
|
||||
- **Annotate options with code context** when relevant:
|
||||
```
|
||||
"How should posts be displayed?"
|
||||
- Cards (reuses existing Card component — consistent with Messages)
|
||||
- List (simpler, would be a new pattern)
|
||||
- Timeline (needs new Timeline component — none exists yet)
|
||||
```
|
||||
- Include "You decide" as an option when reasonable — captures Claude discretion
|
||||
- **Context7 for library choices:** When a gray area involves library selection (e.g., "magic links" → query next-auth docs) or API approach decisions, use `mcp__context7__*` tools to fetch current documentation and inform the options. Don't use Context7 for every question — only when library-specific knowledge improves the options.
|
||||
|
||||
**Batch mode (`--batch`): Ask 2-5 numbered questions in one plain-text turn**
|
||||
- Group closely related questions for the current area into a single message
|
||||
- Keep each question concrete and answerable in one reply
|
||||
- When options are helpful, include short inline choices per question rather than a separate AskUserQuestion for every item
|
||||
- After the user replies, reflect back the captured decisions, note any unanswered items, and ask only the minimum follow-up needed before moving on
|
||||
- Preserve adaptiveness between batches: use the full set of answers to decide the next batch or whether the area is sufficiently clear
|
||||
|
||||
3. **After the current set of questions, check:**
|
||||
- header: "[Area]" (max 12 chars)
|
||||
- question: "More questions about [area], or move to next? (Remaining: [list other unvisited areas])"
|
||||
- options: "More questions" / "Next area"
|
||||
|
||||
When building the question text, list the remaining unvisited areas so the user knows what's ahead. For example: "More questions about Layout, or move to next? (Remaining: Loading behavior, Content ordering)"
|
||||
|
||||
If "More questions" → ask another 4 single questions, or another 2-5 question batch when `--batch` is active, then check again
|
||||
If "Next area" → proceed to next selected area
|
||||
If "Other" (free text) → interpret intent: continuation phrases ("chat more", "keep going", "yes", "more") map to "More questions"; advancement phrases ("done", "move on", "next", "skip") map to "Next area". If ambiguous, ask: "Continue with more questions about [area], or move to the next area?"
|
||||
|
||||
4. **After all initially-selected areas complete:**
|
||||
- Summarize what was captured from the discussion so far
|
||||
- AskUserQuestion:
|
||||
- header: "Done"
|
||||
- question: "We've discussed [list areas]. Which gray areas remain unclear?"
|
||||
- options: "Explore more gray areas" / "I'm ready for context"
|
||||
- If "Explore more gray areas":
|
||||
- Identify 2-4 additional gray areas based on what was learned
|
||||
- Return to present_gray_areas logic with these new areas
|
||||
- Loop: discuss new areas, then prompt again
|
||||
- If "I'm ready for context": Proceed to write_context
|
||||
|
||||
**Canonical ref accumulation during discussion:**
|
||||
When the user references a doc, spec, or ADR during any answer — e.g., "read adr-014", "check the MCP spec", "per browse-spec.md" — immediately:
|
||||
1. Read the referenced doc (or confirm it exists)
|
||||
2. Add it to the canonical refs accumulator with full relative path
|
||||
3. Use what you learned from the doc to inform subsequent questions
|
||||
|
||||
These user-referenced docs are often MORE important than ROADMAP.md refs because they represent docs the user specifically wants downstream agents to follow. Never drop them.
|
||||
|
||||
**Question design:**
|
||||
- Options should be concrete, not abstract ("Cards" not "Option A")
|
||||
- Each answer should inform the next question or next batch
|
||||
- If user picks "Other" to provide freeform input (e.g., "let me describe it", "something else", or an open-ended reply), ask your follow-up as plain text — NOT another AskUserQuestion. Wait for them to type at the normal prompt, then reflect their input back and confirm before resuming AskUserQuestion or the next numbered batch.
|
||||
|
||||
**Scope creep handling:**
|
||||
If user mentions something outside the phase domain:
|
||||
```
|
||||
"[Feature] sounds like a new capability — that belongs in its own phase.
|
||||
I'll note it as a deferred idea.
|
||||
|
||||
Back to [current area]: [return to current question]"
|
||||
```
|
||||
|
||||
Track deferred ideas internally.
|
||||
</step>
|
||||
|
||||
<step name="write_context">
|
||||
Create CONTEXT.md capturing decisions made.
|
||||
|
||||
**Find or create phase directory:**
|
||||
|
||||
Use values from init: `phase_dir`, `phase_slug`, `padded_phase`.
|
||||
|
||||
If `phase_dir` is null (phase exists in roadmap but no directory):
|
||||
```bash
|
||||
mkdir -p ".planning/phases/${padded_phase}-${phase_slug}"
|
||||
```
|
||||
|
||||
**File location:** `${phase_dir}/${padded_phase}-CONTEXT.md`
|
||||
|
||||
**Structure the content by what was discussed:**
|
||||
|
||||
```markdown
|
||||
# Phase [X]: [Name] - Context
|
||||
|
||||
**Gathered:** [date]
|
||||
**Status:** Ready for planning
|
||||
|
||||
<domain>
|
||||
## Phase Boundary
|
||||
|
||||
[Clear statement of what this phase delivers — the scope anchor]
|
||||
|
||||
</domain>
|
||||
|
||||
<decisions>
|
||||
## Implementation Decisions
|
||||
|
||||
### [Category 1 that was discussed]
|
||||
- [Decision or preference captured]
|
||||
- [Another decision if applicable]
|
||||
|
||||
### [Category 2 that was discussed]
|
||||
- [Decision or preference captured]
|
||||
|
||||
### Claude's Discretion
|
||||
[Areas where user said "you decide" — note that Claude has flexibility here]
|
||||
|
||||
</decisions>
|
||||
|
||||
<canonical_refs>
|
||||
## Canonical References
|
||||
|
||||
**Downstream agents MUST read these before planning or implementing.**
|
||||
|
||||
[MANDATORY section. Write the FULL accumulated canonical refs list here.
|
||||
Sources: ROADMAP.md refs + REQUIREMENTS.md refs + user-referenced docs during
|
||||
discussion + any docs discovered during codebase scout. Group by topic area.
|
||||
Every entry needs a full relative path — not just a name.]
|
||||
|
||||
### [Topic area 1]
|
||||
- `path/to/adr-or-spec.md` — [What it decides/defines that's relevant]
|
||||
- `path/to/doc.md` §N — [Specific section reference]
|
||||
|
||||
### [Topic area 2]
|
||||
- `path/to/feature-doc.md` — [What this doc defines]
|
||||
|
||||
[If no external specs: "No external specs — requirements fully captured in decisions above"]
|
||||
|
||||
</canonical_refs>
|
||||
|
||||
<code_context>
|
||||
## Existing Code Insights
|
||||
|
||||
### Reusable Assets
|
||||
- [Component/hook/utility]: [How it could be used in this phase]
|
||||
|
||||
### Established Patterns
|
||||
- [Pattern]: [How it constrains/enables this phase]
|
||||
|
||||
### Integration Points
|
||||
- [Where new code connects to existing system]
|
||||
|
||||
</code_context>
|
||||
|
||||
<specifics>
|
||||
## Specific Ideas
|
||||
|
||||
[Any particular references, examples, or "I want it like X" moments from discussion]
|
||||
|
||||
[If none: "No specific requirements — open to standard approaches"]
|
||||
|
||||
</specifics>
|
||||
|
||||
<deferred>
|
||||
## Deferred Ideas
|
||||
|
||||
[Ideas that came up but belong in other phases. Don't lose them.]
|
||||
|
||||
[If none: "None — discussion stayed within phase scope"]
|
||||
|
||||
</deferred>
|
||||
|
||||
---
|
||||
|
||||
*Phase: XX-name*
|
||||
*Context gathered: [date]*
|
||||
```
|
||||
|
||||
Write file.
|
||||
</step>
|
||||
|
||||
<step name="confirm_creation">
|
||||
Present summary and next steps:
|
||||
|
||||
```
|
||||
Created: .planning/phases/${PADDED_PHASE}-${SLUG}/${PADDED_PHASE}-CONTEXT.md
|
||||
|
||||
## Decisions Captured
|
||||
|
||||
### [Category]
|
||||
- [Key decision]
|
||||
|
||||
### [Category]
|
||||
- [Key decision]
|
||||
|
||||
[If deferred ideas exist:]
|
||||
## Noted for Later
|
||||
- [Deferred idea] — future phase
|
||||
|
||||
---
|
||||
|
||||
## ▶ Next Up
|
||||
|
||||
**Phase ${PHASE}: [Name]** — [Goal from ROADMAP.md]
|
||||
|
||||
`/gsd:plan-phase ${PHASE}`
|
||||
|
||||
<sub>`/clear` first → fresh context window</sub>
|
||||
|
||||
---
|
||||
|
||||
**Also available:**
|
||||
- `/gsd:plan-phase ${PHASE} --skip-research` — plan without research
|
||||
- `/gsd:ui-phase ${PHASE}` — generate UI design contract before planning (if phase has frontend work)
|
||||
- Review/edit CONTEXT.md before continuing
|
||||
|
||||
---
|
||||
```
|
||||
</step>
|
||||
|
||||
<step name="git_commit">
|
||||
Commit phase context (uses `commit_docs` from init internally):
|
||||
|
||||
```bash
|
||||
node "C:/Users/yaoji/.claude/get-shit-done/bin/gsd-tools.cjs" commit "docs(${padded_phase}): capture phase context" --files "${phase_dir}/${padded_phase}-CONTEXT.md"
|
||||
```
|
||||
|
||||
Confirm: "Committed: docs(${padded_phase}): capture phase context"
|
||||
</step>
|
||||
|
||||
<step name="update_state">
|
||||
Update STATE.md with session info:
|
||||
|
||||
```bash
|
||||
node "C:/Users/yaoji/.claude/get-shit-done/bin/gsd-tools.cjs" state record-session \
|
||||
--stopped-at "Phase ${PHASE} context gathered" \
|
||||
--resume-file "${phase_dir}/${padded_phase}-CONTEXT.md"
|
||||
```
|
||||
|
||||
Commit STATE.md:
|
||||
|
||||
```bash
|
||||
node "C:/Users/yaoji/.claude/get-shit-done/bin/gsd-tools.cjs" commit "docs(state): record phase ${PHASE} context session" --files .planning/STATE.md
|
||||
```
|
||||
</step>
|
||||
|
||||
<step name="auto_advance">
|
||||
Check for auto-advance trigger:
|
||||
|
||||
1. Parse `--auto` flag from $ARGUMENTS
|
||||
2. **Sync chain flag with intent** — if user invoked manually (no `--auto`), clear the ephemeral chain flag from any previous interrupted `--auto` chain. This does NOT touch `workflow.auto_advance` (the user's persistent settings preference):
|
||||
```bash
|
||||
if [[ ! "$ARGUMENTS" =~ --auto ]]; then
|
||||
node "C:/Users/yaoji/.claude/get-shit-done/bin/gsd-tools.cjs" config-set workflow._auto_chain_active false 2>/dev/null
|
||||
fi
|
||||
```
|
||||
3. Read both the chain flag and user preference:
|
||||
```bash
|
||||
AUTO_CHAIN=$(node "C:/Users/yaoji/.claude/get-shit-done/bin/gsd-tools.cjs" config-get workflow._auto_chain_active 2>/dev/null || echo "false")
|
||||
AUTO_CFG=$(node "C:/Users/yaoji/.claude/get-shit-done/bin/gsd-tools.cjs" config-get workflow.auto_advance 2>/dev/null || echo "false")
|
||||
```
|
||||
|
||||
**If `--auto` flag present AND `AUTO_CHAIN` is not true:** Persist chain flag to config (handles direct `--auto` usage without new-project):
|
||||
```bash
|
||||
node "C:/Users/yaoji/.claude/get-shit-done/bin/gsd-tools.cjs" config-set workflow._auto_chain_active true
|
||||
```
|
||||
|
||||
**If `--auto` flag present OR `AUTO_CHAIN` is true OR `AUTO_CFG` is true:**
|
||||
|
||||
Display banner:
|
||||
```
|
||||
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
|
||||
GSD ► AUTO-ADVANCING TO PLAN
|
||||
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
|
||||
|
||||
Context captured. Launching plan-phase...
|
||||
```
|
||||
|
||||
Launch plan-phase using the Skill tool to avoid nested Task sessions (which cause runtime freezes due to deep agent nesting — see #686):
|
||||
```
|
||||
Skill(skill="gsd:plan-phase", args="${PHASE} --auto")
|
||||
```
|
||||
|
||||
This keeps the auto-advance chain flat — discuss, plan, and execute all run at the same nesting level rather than spawning increasingly deep Task agents.
|
||||
|
||||
**Handle plan-phase return:**
|
||||
- **PHASE COMPLETE** → Full chain succeeded. Display:
|
||||
```
|
||||
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
|
||||
GSD ► PHASE ${PHASE} COMPLETE
|
||||
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
|
||||
|
||||
Auto-advance pipeline finished: discuss → plan → execute
|
||||
|
||||
Next: /gsd:discuss-phase ${NEXT_PHASE} --auto
|
||||
<sub>/clear first → fresh context window</sub>
|
||||
```
|
||||
- **PLANNING COMPLETE** → Planning done, execution didn't complete:
|
||||
```
|
||||
Auto-advance partial: Planning complete, execution did not finish.
|
||||
Continue: /gsd:execute-phase ${PHASE}
|
||||
```
|
||||
- **PLANNING INCONCLUSIVE / CHECKPOINT** → Stop chain:
|
||||
```
|
||||
Auto-advance stopped: Planning needs input.
|
||||
Continue: /gsd:plan-phase ${PHASE}
|
||||
```
|
||||
- **GAPS FOUND** → Stop chain:
|
||||
```
|
||||
Auto-advance stopped: Gaps found during execution.
|
||||
Continue: /gsd:plan-phase ${PHASE} --gaps
|
||||
```
|
||||
|
||||
**If neither `--auto` nor config enabled:**
|
||||
Route to `confirm_creation` step (existing behavior — show manual next steps).
|
||||
</step>
|
||||
|
||||
</process>
|
||||
|
||||
<success_criteria>
|
||||
- Phase validated against roadmap
|
||||
- Prior context loaded (PROJECT.md, REQUIREMENTS.md, STATE.md, prior CONTEXT.md files)
|
||||
- Already-decided questions not re-asked (carried forward from prior phases)
|
||||
- Codebase scouted for reusable assets, patterns, and integration points
|
||||
- Gray areas identified through intelligent analysis with code and prior decision annotations
|
||||
- User selected which areas to discuss
|
||||
- Each selected area explored until user satisfied (with code-informed and prior-decision-informed options)
|
||||
- Scope creep redirected to deferred ideas
|
||||
- CONTEXT.md captures actual decisions, not vague vision
|
||||
- CONTEXT.md includes canonical_refs section with full file paths to every spec/ADR/doc downstream agents need (MANDATORY — never omit)
|
||||
- CONTEXT.md includes code_context section with reusable assets and patterns
|
||||
- Deferred ideas preserved for future phases
|
||||
- STATE.md updated with session info
|
||||
- User knows next steps
|
||||
</success_criteria>
|
||||
104
get-shit-done/workflows/do.md
Normal file
104
get-shit-done/workflows/do.md
Normal file
@@ -0,0 +1,104 @@
|
||||
<purpose>
|
||||
Analyze freeform text from the user and route to the most appropriate GSD command. This is a dispatcher — it never does the work itself. Match user intent to the best command, confirm the routing, and hand off.
|
||||
</purpose>
|
||||
|
||||
<required_reading>
|
||||
Read all files referenced by the invoking prompt's execution_context before starting.
|
||||
</required_reading>
|
||||
|
||||
<process>
|
||||
|
||||
<step name="validate">
|
||||
**Check for input.**
|
||||
|
||||
If `$ARGUMENTS` is empty, ask via AskUserQuestion:
|
||||
|
||||
```
|
||||
What would you like to do? Describe the task, bug, or idea and I'll route it to the right GSD command.
|
||||
```
|
||||
|
||||
Wait for response before continuing.
|
||||
</step>
|
||||
|
||||
<step name="check_project">
|
||||
**Check if project exists.**
|
||||
|
||||
```bash
|
||||
INIT=$(node "C:/Users/yaoji/.claude/get-shit-done/bin/gsd-tools.cjs" state load 2>/dev/null)
|
||||
```
|
||||
|
||||
Track whether `.planning/` exists — some routes require it, others don't.
|
||||
</step>
|
||||
|
||||
<step name="route">
|
||||
**Match intent to command.**
|
||||
|
||||
Evaluate `$ARGUMENTS` against these routing rules. Apply the **first matching** rule:
|
||||
|
||||
| If the text describes... | Route to | Why |
|
||||
|--------------------------|----------|-----|
|
||||
| Starting a new project, "set up", "initialize" | `/gsd:new-project` | Needs full project initialization |
|
||||
| Mapping or analyzing an existing codebase | `/gsd:map-codebase` | Codebase discovery |
|
||||
| A bug, error, crash, failure, or something broken | `/gsd:debug` | Needs systematic investigation |
|
||||
| Exploring, researching, comparing, or "how does X work" | `/gsd:research-phase` | Domain research before planning |
|
||||
| Discussing vision, "how should X look", brainstorming | `/gsd:discuss-phase` | Needs context gathering |
|
||||
| A complex task: refactoring, migration, multi-file architecture, system redesign | `/gsd:add-phase` | Needs a full phase with plan/build cycle |
|
||||
| Planning a specific phase or "plan phase N" | `/gsd:plan-phase` | Direct planning request |
|
||||
| Executing a phase or "build phase N", "run phase N" | `/gsd:execute-phase` | Direct execution request |
|
||||
| Running all remaining phases automatically | `/gsd:autonomous` | Full autonomous execution |
|
||||
| A review or quality concern about existing work | `/gsd:verify-work` | Needs verification |
|
||||
| Checking progress, status, "where am I" | `/gsd:progress` | Status check |
|
||||
| Resuming work, "pick up where I left off" | `/gsd:resume-work` | Session restoration |
|
||||
| A note, idea, or "remember to..." | `/gsd:add-todo` | Capture for later |
|
||||
| Adding tests, "write tests", "test coverage" | `/gsd:add-tests` | Test generation |
|
||||
| Completing a milestone, shipping, releasing | `/gsd:complete-milestone` | Milestone lifecycle |
|
||||
| A specific, actionable, small task (add feature, fix typo, update config) | `/gsd:quick` | Self-contained, single executor |
|
||||
|
||||
**Requires `.planning/` directory:** All routes except `/gsd:new-project`, `/gsd:map-codebase`, `/gsd:help`, and `/gsd:join-discord`. If the project doesn't exist and the route requires it, suggest `/gsd:new-project` first.
|
||||
|
||||
**Ambiguity handling:** If the text could reasonably match multiple routes, ask the user via AskUserQuestion with the top 2-3 options. For example:
|
||||
|
||||
```
|
||||
"Refactor the authentication system" could be:
|
||||
1. /gsd:add-phase — Full planning cycle (recommended for multi-file refactors)
|
||||
2. /gsd:quick — Quick execution (if scope is small and clear)
|
||||
|
||||
Which approach fits better?
|
||||
```
|
||||
</step>
|
||||
|
||||
<step name="display">
|
||||
**Show the routing decision.**
|
||||
|
||||
```
|
||||
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
|
||||
GSD ► ROUTING
|
||||
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
|
||||
|
||||
**Input:** {first 80 chars of $ARGUMENTS}
|
||||
**Routing to:** {chosen command}
|
||||
**Reason:** {one-line explanation}
|
||||
```
|
||||
</step>
|
||||
|
||||
<step name="dispatch">
|
||||
**Invoke the chosen command.**
|
||||
|
||||
Run the selected `/gsd:*` command, passing `$ARGUMENTS` as args.
|
||||
|
||||
If the chosen command expects a phase number and one wasn't provided in the text, extract it from context or ask via AskUserQuestion.
|
||||
|
||||
After invoking the command, stop. The dispatched command handles everything from here.
|
||||
</step>
|
||||
|
||||
</process>
|
||||
|
||||
<success_criteria>
|
||||
- [ ] Input validated (not empty)
|
||||
- [ ] Intent matched to exactly one GSD command
|
||||
- [ ] Ambiguity resolved via user question (if needed)
|
||||
- [ ] Project existence checked for routes that require it
|
||||
- [ ] Routing decision displayed before dispatch
|
||||
- [ ] Command invoked with appropriate arguments
|
||||
- [ ] No work done directly — dispatcher only
|
||||
</success_criteria>
|
||||
670
get-shit-done/workflows/execute-phase.md
Normal file
670
get-shit-done/workflows/execute-phase.md
Normal file
@@ -0,0 +1,670 @@
|
||||
<purpose>
|
||||
Execute all plans in a phase using wave-based parallel execution. Orchestrator stays lean — delegates plan execution to subagents.
|
||||
</purpose>
|
||||
|
||||
<core_principle>
|
||||
Orchestrator coordinates, not executes. Each subagent loads the full execute-plan context. Orchestrator: discover plans → analyze deps → group waves → spawn agents → handle checkpoints → collect results.
|
||||
</core_principle>
|
||||
|
||||
<runtime_compatibility>
|
||||
**Subagent spawning is runtime-specific:**
|
||||
- **Claude Code:** Uses `Task(subagent_type="gsd-executor", ...)` — blocks until complete, returns result
|
||||
- **Copilot:** Uses `@gsd-executor` agent reference — if subagent spawning hangs or fails to return,
|
||||
fall back to **sequential inline execution**: read and follow execute-plan.md directly for each plan
|
||||
instead of spawning parallel agents. This is slower but reliable.
|
||||
- **Other runtimes (Gemini, Codex, OpenCode):** If Task/subagent API is unavailable, use sequential
|
||||
inline execution as the fallback.
|
||||
|
||||
**Fallback rule:** If a spawned agent completes its work (commits visible, SUMMARY.md exists) but
|
||||
the orchestrator never receives the completion signal, treat it as successful based on spot-checks
|
||||
and continue to the next wave/plan.
|
||||
</runtime_compatibility>
|
||||
|
||||
<required_reading>
|
||||
Read STATE.md before any operation to load project context.
|
||||
</required_reading>
|
||||
|
||||
<available_agent_types>
|
||||
These are the valid GSD subagent types registered in .claude/agents/ (or equivalent for your runtime).
|
||||
Always use the exact name from this list — do not fall back to 'general-purpose' or other built-in types:
|
||||
|
||||
- gsd-executor — Executes plan tasks, commits, creates SUMMARY.md
|
||||
- gsd-verifier — Verifies phase completion, checks quality gates
|
||||
- gsd-planner — Creates detailed plans from phase scope
|
||||
- gsd-phase-researcher — Researches technical approaches for a phase
|
||||
- gsd-plan-checker — Reviews plan quality before execution
|
||||
- gsd-debugger — Diagnoses and fixes issues
|
||||
- gsd-codebase-mapper — Maps project structure and dependencies
|
||||
- gsd-integration-checker — Checks cross-phase integration
|
||||
- gsd-nyquist-auditor — Validates verification coverage
|
||||
- gsd-ui-researcher — Researches UI/UX approaches
|
||||
- gsd-ui-checker — Reviews UI implementation quality
|
||||
- gsd-ui-auditor — Audits UI against design requirements
|
||||
</available_agent_types>
|
||||
|
||||
<process>
|
||||
|
||||
<step name="initialize" priority="first">
|
||||
Load all context in one call:
|
||||
|
||||
```bash
|
||||
INIT=$(node "C:/Users/yaoji/.claude/get-shit-done/bin/gsd-tools.cjs" init execute-phase "${PHASE_ARG}")
|
||||
if [[ "$INIT" == @file:* ]]; then INIT=$(cat "${INIT#@file:}"); fi
|
||||
```
|
||||
|
||||
Parse JSON for: `executor_model`, `verifier_model`, `commit_docs`, `parallelization`, `branching_strategy`, `branch_name`, `phase_found`, `phase_dir`, `phase_number`, `phase_name`, `phase_slug`, `plans`, `incomplete_plans`, `plan_count`, `incomplete_count`, `state_exists`, `roadmap_exists`, `phase_req_ids`.
|
||||
|
||||
**If `phase_found` is false:** Error — phase directory not found.
|
||||
**If `plan_count` is 0:** Error — no plans found in phase.
|
||||
**If `state_exists` is false but `.planning/` exists:** Offer reconstruct or continue.
|
||||
|
||||
When `parallelization` is false, plans within a wave execute sequentially.
|
||||
|
||||
**REQUIRED — Sync chain flag with intent.** If user invoked manually (no `--auto`), clear the ephemeral chain flag from any previous interrupted `--auto` chain. This prevents stale `_auto_chain_active: true` from causing unwanted auto-advance. This does NOT touch `workflow.auto_advance` (the user's persistent settings preference). You MUST execute this bash block before any config reads:
|
||||
```bash
|
||||
# REQUIRED: prevents stale auto-chain from previous --auto runs
|
||||
if [[ ! "$ARGUMENTS" =~ --auto ]]; then
|
||||
node "C:/Users/yaoji/.claude/get-shit-done/bin/gsd-tools.cjs" config-set workflow._auto_chain_active false 2>/dev/null
|
||||
fi
|
||||
```
|
||||
</step>
|
||||
|
||||
<step name="check_interactive_mode">
|
||||
**Parse `--interactive` flag from $ARGUMENTS.**
|
||||
|
||||
**If `--interactive` flag present:** Switch to interactive execution mode.
|
||||
|
||||
Interactive mode executes plans sequentially **inline** (no subagent spawning) with user
|
||||
checkpoints between tasks. The user can review, modify, or redirect work at any point.
|
||||
|
||||
**Interactive execution flow:**
|
||||
|
||||
1. Load plan inventory as normal (discover_and_group_plans)
|
||||
2. For each plan (sequentially, ignoring wave grouping):
|
||||
|
||||
a. **Present the plan to the user:**
|
||||
```
|
||||
## Plan {plan_id}: {plan_name}
|
||||
|
||||
Objective: {from plan file}
|
||||
Tasks: {task_count}
|
||||
|
||||
Options:
|
||||
- Execute (proceed with all tasks)
|
||||
- Review first (show task breakdown before starting)
|
||||
- Skip (move to next plan)
|
||||
- Stop (end execution, save progress)
|
||||
```
|
||||
|
||||
b. **If "Review first":** Read and display the full plan file. Ask again: Execute, Modify, Skip.
|
||||
|
||||
c. **If "Execute":** Read and follow `C:/Users/yaoji/.claude/get-shit-done/workflows/execute-plan.md` **inline**
|
||||
(do NOT spawn a subagent). Execute tasks one at a time.
|
||||
|
||||
d. **After each task:** Pause briefly. If the user intervenes (types anything), stop and address
|
||||
their feedback before continuing. Otherwise proceed to next task.
|
||||
|
||||
e. **After plan complete:** Show results, commit, create SUMMARY.md, then present next plan.
|
||||
|
||||
3. After all plans: proceed to verification (same as normal mode).
|
||||
|
||||
**Benefits of interactive mode:**
|
||||
- No subagent overhead — dramatically lower token usage
|
||||
- User catches mistakes early — saves costly verification cycles
|
||||
- Maintains GSD's planning/tracking structure
|
||||
- Best for: small phases, bug fixes, verification gaps, learning GSD
|
||||
|
||||
**Skip to handle_branching step** (interactive plans execute inline after grouping).
|
||||
</step>
|
||||
|
||||
<step name="handle_branching">
|
||||
Check `branching_strategy` from init:
|
||||
|
||||
**"none":** Skip, continue on current branch.
|
||||
|
||||
**"phase" or "milestone":** Use pre-computed `branch_name` from init:
|
||||
```bash
|
||||
git checkout -b "$BRANCH_NAME" 2>/dev/null || git checkout "$BRANCH_NAME"
|
||||
```
|
||||
|
||||
All subsequent commits go to this branch. User handles merging.
|
||||
</step>
|
||||
|
||||
<step name="validate_phase">
|
||||
From init JSON: `phase_dir`, `plan_count`, `incomplete_count`.
|
||||
|
||||
Report: "Found {plan_count} plans in {phase_dir} ({incomplete_count} incomplete)"
|
||||
|
||||
**Update STATE.md for phase start:**
|
||||
```bash
|
||||
node "C:/Users/yaoji/.claude/get-shit-done/bin/gsd-tools.cjs" state begin-phase --phase "${PHASE_NUMBER}" --name "${PHASE_NAME}" --plans "${PLAN_COUNT}"
|
||||
```
|
||||
This updates Status, Last Activity, Current focus, Current Position, and plan counts in STATE.md so frontmatter and body text reflect the active phase immediately.
|
||||
</step>
|
||||
|
||||
<step name="discover_and_group_plans">
|
||||
Load plan inventory with wave grouping in one call:
|
||||
|
||||
```bash
|
||||
PLAN_INDEX=$(node "C:/Users/yaoji/.claude/get-shit-done/bin/gsd-tools.cjs" phase-plan-index "${PHASE_NUMBER}")
|
||||
```
|
||||
|
||||
Parse JSON for: `phase`, `plans[]` (each with `id`, `wave`, `autonomous`, `objective`, `files_modified`, `task_count`, `has_summary`), `waves` (map of wave number → plan IDs), `incomplete`, `has_checkpoints`.
|
||||
|
||||
**Filtering:** Skip plans where `has_summary: true`. If `--gaps-only`: also skip non-gap_closure plans. If all filtered: "No matching incomplete plans" → exit.
|
||||
|
||||
Report:
|
||||
```
|
||||
## Execution Plan
|
||||
|
||||
**Phase {X}: {Name}** — {total_plans} plans across {wave_count} waves
|
||||
|
||||
| Wave | Plans | What it builds |
|
||||
|------|-------|----------------|
|
||||
| 1 | 01-01, 01-02 | {from plan objectives, 3-8 words} |
|
||||
| 2 | 01-03 | ... |
|
||||
```
|
||||
</step>
|
||||
|
||||
<step name="execute_waves">
|
||||
Execute each wave in sequence. Within a wave: parallel if `PARALLELIZATION=true`, sequential if `false`.
|
||||
|
||||
**For each wave:**
|
||||
|
||||
1. **Describe what's being built (BEFORE spawning):**
|
||||
|
||||
Read each plan's `<objective>`. Extract what's being built and why.
|
||||
|
||||
```
|
||||
---
|
||||
## Wave {N}
|
||||
|
||||
**{Plan ID}: {Plan Name}**
|
||||
{2-3 sentences: what this builds, technical approach, why it matters}
|
||||
|
||||
Spawning {count} agent(s)...
|
||||
---
|
||||
```
|
||||
|
||||
- Bad: "Executing terrain generation plan"
|
||||
- Good: "Procedural terrain generator using Perlin noise — creates height maps, biome zones, and collision meshes. Required before vehicle physics can interact with ground."
|
||||
|
||||
2. **Spawn executor agents:**
|
||||
|
||||
Pass paths only — executors read files themselves with their fresh 200k context.
|
||||
This keeps orchestrator context lean (~10-15%).
|
||||
|
||||
```
|
||||
Task(
|
||||
subagent_type="gsd-executor",
|
||||
model="{executor_model}",
|
||||
prompt="
|
||||
<objective>
|
||||
Execute plan {plan_number} of phase {phase_number}-{phase_name}.
|
||||
Commit each task atomically. Create SUMMARY.md. Update STATE.md and ROADMAP.md.
|
||||
</objective>
|
||||
|
||||
<execution_context>
|
||||
@C:/Users/yaoji/.claude/get-shit-done/workflows/execute-plan.md
|
||||
@C:/Users/yaoji/.claude/get-shit-done/templates/summary.md
|
||||
@C:/Users/yaoji/.claude/get-shit-done/references/checkpoints.md
|
||||
@C:/Users/yaoji/.claude/get-shit-done/references/tdd.md
|
||||
</execution_context>
|
||||
|
||||
<files_to_read>
|
||||
Read these files at execution start using the Read tool:
|
||||
- {phase_dir}/{plan_file} (Plan)
|
||||
- .planning/STATE.md (State)
|
||||
- .planning/config.json (Config, if exists)
|
||||
- ./CLAUDE.md (Project instructions, if exists — follow project-specific guidelines and coding conventions)
|
||||
- .claude/skills/ or .agents/skills/ (Project skills, if either exists — list skills, read SKILL.md for each, follow relevant rules during implementation)
|
||||
</files_to_read>
|
||||
|
||||
<mcp_tools>
|
||||
If CLAUDE.md or project instructions reference MCP tools (e.g. jCodeMunch, context7,
|
||||
or other MCP servers), prefer those tools over Grep/Glob for code navigation when available.
|
||||
MCP tools often save significant tokens by providing structured code indexes.
|
||||
Check tool availability first — if MCP tools are not accessible, fall back to Grep/Glob.
|
||||
</mcp_tools>
|
||||
|
||||
<success_criteria>
|
||||
- [ ] All tasks executed
|
||||
- [ ] Each task committed individually
|
||||
- [ ] SUMMARY.md created in plan directory
|
||||
- [ ] STATE.md updated with position and decisions
|
||||
- [ ] ROADMAP.md updated with plan progress (via `roadmap update-plan-progress`)
|
||||
</success_criteria>
|
||||
"
|
||||
)
|
||||
```
|
||||
|
||||
3. **Wait for all agents in wave to complete.**
|
||||
|
||||
4. **Report completion — spot-check claims first:**
|
||||
|
||||
For each SUMMARY.md:
|
||||
- Verify first 2 files from `key-files.created` exist on disk
|
||||
- Check `git log --oneline --all --grep="{phase}-{plan}"` returns ≥1 commit
|
||||
- Check for `## Self-Check: FAILED` marker
|
||||
|
||||
If ANY spot-check fails: report which plan failed, route to failure handler — ask "Retry plan?" or "Continue with remaining waves?"
|
||||
|
||||
If pass:
|
||||
```
|
||||
---
|
||||
## Wave {N} Complete
|
||||
|
||||
**{Plan ID}: {Plan Name}**
|
||||
{What was built — from SUMMARY.md}
|
||||
{Notable deviations, if any}
|
||||
|
||||
{If more waves: what this enables for next wave}
|
||||
---
|
||||
```
|
||||
|
||||
- Bad: "Wave 2 complete. Proceeding to Wave 3."
|
||||
- Good: "Terrain system complete — 3 biome types, height-based texturing, physics collision meshes. Vehicle physics (Wave 3) can now reference ground surfaces."
|
||||
|
||||
5. **Handle failures:**
|
||||
|
||||
**Known Claude Code bug (classifyHandoffIfNeeded):** If an agent reports "failed" with error containing `classifyHandoffIfNeeded is not defined`, this is a Claude Code runtime bug — not a GSD or agent issue. The error fires in the completion handler AFTER all tool calls finish. In this case: run the same spot-checks as step 4 (SUMMARY.md exists, git commits present, no Self-Check: FAILED). If spot-checks PASS → treat as **successful**. If spot-checks FAIL → treat as real failure below.
|
||||
|
||||
For real failures: report which plan failed → ask "Continue?" or "Stop?" → if continue, dependent plans may also fail. If stop, partial completion report.
|
||||
|
||||
5b. **Pre-wave dependency check (waves 2+ only):**
|
||||
|
||||
Before spawning wave N+1, for each plan in the upcoming wave:
|
||||
```bash
|
||||
node "C:/Users/yaoji/.claude/get-shit-done/bin/gsd-tools.cjs" verify key-links {phase_dir}/{plan}-PLAN.md
|
||||
```
|
||||
|
||||
If any key-link from a PRIOR wave's artifact fails verification:
|
||||
|
||||
## Cross-Plan Wiring Gap
|
||||
|
||||
| Plan | Link | From | Expected Pattern | Status |
|
||||
|------|------|------|-----------------|--------|
|
||||
| {plan} | {via} | {from} | {pattern} | NOT FOUND |
|
||||
|
||||
Wave {N} artifacts may not be properly wired. Options:
|
||||
1. Investigate and fix before continuing
|
||||
2. Continue (may cause cascading failures in wave {N+1})
|
||||
|
||||
Key-links referencing files in the CURRENT (upcoming) wave are skipped.
|
||||
|
||||
6. **Execute checkpoint plans between waves** — see `<checkpoint_handling>`.
|
||||
|
||||
7. **Proceed to next wave.**
|
||||
</step>
|
||||
|
||||
<step name="checkpoint_handling">
|
||||
Plans with `autonomous: false` require user interaction.
|
||||
|
||||
**Auto-mode checkpoint handling:**
|
||||
|
||||
Read auto-advance config (chain flag + user preference):
|
||||
```bash
|
||||
AUTO_CHAIN=$(node "C:/Users/yaoji/.claude/get-shit-done/bin/gsd-tools.cjs" config-get workflow._auto_chain_active 2>/dev/null || echo "false")
|
||||
AUTO_CFG=$(node "C:/Users/yaoji/.claude/get-shit-done/bin/gsd-tools.cjs" config-get workflow.auto_advance 2>/dev/null || echo "false")
|
||||
```
|
||||
|
||||
When executor returns a checkpoint AND (`AUTO_CHAIN` is `"true"` OR `AUTO_CFG` is `"true"`):
|
||||
- **human-verify** → Auto-spawn continuation agent with `{user_response}` = `"approved"`. Log `⚡ Auto-approved checkpoint`.
|
||||
- **decision** → Auto-spawn continuation agent with `{user_response}` = first option from checkpoint details. Log `⚡ Auto-selected: [option]`.
|
||||
- **human-action** → Present to user (existing behavior below). Auth gates cannot be automated.
|
||||
|
||||
**Standard flow (not auto-mode, or human-action type):**
|
||||
|
||||
1. Spawn agent for checkpoint plan
|
||||
2. Agent runs until checkpoint task or auth gate → returns structured state
|
||||
3. Agent return includes: completed tasks table, current task + blocker, checkpoint type/details, what's awaited
|
||||
4. **Present to user:**
|
||||
```
|
||||
## Checkpoint: [Type]
|
||||
|
||||
**Plan:** 03-03 Dashboard Layout
|
||||
**Progress:** 2/3 tasks complete
|
||||
|
||||
[Checkpoint Details from agent return]
|
||||
[Awaiting section from agent return]
|
||||
```
|
||||
5. User responds: "approved"/"done" | issue description | decision selection
|
||||
6. **Spawn continuation agent (NOT resume)** using continuation-prompt.md template:
|
||||
- `{completed_tasks_table}`: From checkpoint return
|
||||
- `{resume_task_number}` + `{resume_task_name}`: Current task
|
||||
- `{user_response}`: What user provided
|
||||
- `{resume_instructions}`: Based on checkpoint type
|
||||
7. Continuation agent verifies previous commits, continues from resume point
|
||||
8. Repeat until plan completes or user stops
|
||||
|
||||
**Why fresh agent, not resume:** Resume relies on internal serialization that breaks with parallel tool calls. Fresh agents with explicit state are more reliable.
|
||||
|
||||
**Checkpoints in parallel waves:** Agent pauses and returns while other parallel agents may complete. Present checkpoint, spawn continuation, wait for all before next wave.
|
||||
</step>
|
||||
|
||||
<step name="aggregate_results">
|
||||
After all waves:
|
||||
|
||||
```markdown
|
||||
## Phase {X}: {Name} Execution Complete
|
||||
|
||||
**Waves:** {N} | **Plans:** {M}/{total} complete
|
||||
|
||||
| Wave | Plans | Status |
|
||||
|------|-------|--------|
|
||||
| 1 | plan-01, plan-02 | ✓ Complete |
|
||||
| CP | plan-03 | ✓ Verified |
|
||||
| 2 | plan-04 | ✓ Complete |
|
||||
|
||||
### Plan Details
|
||||
1. **03-01**: [one-liner from SUMMARY.md]
|
||||
2. **03-02**: [one-liner from SUMMARY.md]
|
||||
|
||||
### Issues Encountered
|
||||
[Aggregate from SUMMARYs, or "None"]
|
||||
```
|
||||
</step>
|
||||
|
||||
<step name="close_parent_artifacts">
|
||||
**For decimal/polish phases only (X.Y pattern):** Close the feedback loop by resolving parent UAT and debug artifacts.
|
||||
|
||||
**Skip if** phase number has no decimal (e.g., `3`, `04`) — only applies to gap-closure phases like `4.1`, `03.1`.
|
||||
|
||||
**1. Detect decimal phase and derive parent:**
|
||||
```bash
|
||||
# Check if phase_number contains a decimal
|
||||
if [[ "$PHASE_NUMBER" == *.* ]]; then
|
||||
PARENT_PHASE="${PHASE_NUMBER%%.*}"
|
||||
fi
|
||||
```
|
||||
|
||||
**2. Find parent UAT file:**
|
||||
```bash
|
||||
PARENT_INFO=$(node "C:/Users/yaoji/.claude/get-shit-done/bin/gsd-tools.cjs" find-phase "${PARENT_PHASE}" --raw)
|
||||
# Extract directory from PARENT_INFO JSON, then find UAT file in that directory
|
||||
```
|
||||
|
||||
**If no parent UAT found:** Skip this step (gap-closure may have been triggered by VERIFICATION.md instead).
|
||||
|
||||
**3. Update UAT gap statuses:**
|
||||
|
||||
Read the parent UAT file's `## Gaps` section. For each gap entry with `status: failed`:
|
||||
- Update to `status: resolved`
|
||||
|
||||
**4. Update UAT frontmatter:**
|
||||
|
||||
If all gaps now have `status: resolved`:
|
||||
- Update frontmatter `status: diagnosed` → `status: resolved`
|
||||
- Update frontmatter `updated:` timestamp
|
||||
|
||||
**5. Resolve referenced debug sessions:**
|
||||
|
||||
For each gap that has a `debug_session:` field:
|
||||
- Read the debug session file
|
||||
- Update frontmatter `status:` → `resolved`
|
||||
- Update frontmatter `updated:` timestamp
|
||||
- Move to resolved directory:
|
||||
```bash
|
||||
mkdir -p .planning/debug/resolved
|
||||
mv .planning/debug/{slug}.md .planning/debug/resolved/
|
||||
```
|
||||
|
||||
**6. Commit updated artifacts:**
|
||||
```bash
|
||||
node "C:/Users/yaoji/.claude/get-shit-done/bin/gsd-tools.cjs" commit "docs(phase-${PARENT_PHASE}): resolve UAT gaps and debug sessions after ${PHASE_NUMBER} gap closure" --files .planning/phases/*${PARENT_PHASE}*/*-UAT.md .planning/debug/resolved/*.md
|
||||
```
|
||||
</step>
|
||||
|
||||
<step name="regression_gate">
|
||||
Run prior phases' test suites to catch cross-phase regressions BEFORE verification.
|
||||
|
||||
**Skip if:** This is the first phase (no prior phases), or no prior VERIFICATION.md files exist.
|
||||
|
||||
**Step 1: Discover prior phases' test files**
|
||||
```bash
|
||||
# Find all VERIFICATION.md files from prior phases in current milestone
|
||||
PRIOR_VERIFICATIONS=$(find .planning/phases/ -name "*-VERIFICATION.md" ! -path "*${PHASE_NUMBER}*" 2>/dev/null)
|
||||
```
|
||||
|
||||
**Step 2: Extract test file lists from prior verifications**
|
||||
|
||||
For each VERIFICATION.md found, look for test file references:
|
||||
- Lines containing `test`, `spec`, or `__tests__` paths
|
||||
- The "Test Suite" or "Automated Checks" section
|
||||
- File patterns from `key-files.created` in corresponding SUMMARY.md files that match `*.test.*` or `*.spec.*`
|
||||
|
||||
Collect all unique test file paths into `REGRESSION_FILES`.
|
||||
|
||||
**Step 3: Run regression tests (if any found)**
|
||||
|
||||
```bash
|
||||
# Detect test runner and run prior phase tests
|
||||
if [ -f "package.json" ]; then
|
||||
# Node.js — use project's test runner
|
||||
npx jest ${REGRESSION_FILES} --passWithNoTests --no-coverage -q 2>&1 || npx vitest run ${REGRESSION_FILES} 2>&1
|
||||
elif [ -f "Cargo.toml" ]; then
|
||||
cargo test 2>&1
|
||||
elif [ -f "requirements.txt" ] || [ -f "pyproject.toml" ]; then
|
||||
python -m pytest ${REGRESSION_FILES} -q --tb=short 2>&1
|
||||
fi
|
||||
```
|
||||
|
||||
**Step 4: Report results**
|
||||
|
||||
If all tests pass:
|
||||
```
|
||||
✓ Regression gate: {N} prior-phase test files passed — no regressions detected
|
||||
```
|
||||
→ Proceed to verify_phase_goal
|
||||
|
||||
If any tests fail:
|
||||
```
|
||||
## ⚠ Cross-Phase Regression Detected
|
||||
|
||||
Phase {X} execution may have broken functionality from prior phases.
|
||||
|
||||
| Test File | Phase | Status | Detail |
|
||||
|-----------|-------|--------|--------|
|
||||
| {file} | {origin_phase} | FAILED | {first_failure_line} |
|
||||
|
||||
Options:
|
||||
1. Fix regressions before verification (recommended)
|
||||
2. Continue to verification anyway (regressions will compound)
|
||||
3. Abort phase — roll back and re-plan
|
||||
```
|
||||
|
||||
Use AskUserQuestion to present the options.
|
||||
</step>
|
||||
|
||||
<step name="verify_phase_goal">
|
||||
Verify phase achieved its GOAL, not just completed tasks.
|
||||
|
||||
```
|
||||
Task(
|
||||
prompt="Verify phase {phase_number} goal achievement.
|
||||
Phase directory: {phase_dir}
|
||||
Phase goal: {goal from ROADMAP.md}
|
||||
Phase requirement IDs: {phase_req_ids}
|
||||
Check must_haves against actual codebase.
|
||||
Cross-reference requirement IDs from PLAN frontmatter against REQUIREMENTS.md — every ID MUST be accounted for.
|
||||
Create VERIFICATION.md.",
|
||||
subagent_type="gsd-verifier",
|
||||
model="{verifier_model}"
|
||||
)
|
||||
```
|
||||
|
||||
Read status:
|
||||
```bash
|
||||
grep "^status:" "$PHASE_DIR"/*-VERIFICATION.md | cut -d: -f2 | tr -d ' '
|
||||
```
|
||||
|
||||
| Status | Action |
|
||||
|--------|--------|
|
||||
| `passed` | → update_roadmap |
|
||||
| `human_needed` | Present items for human testing, get approval or feedback |
|
||||
| `gaps_found` | Present gap summary, offer `/gsd:plan-phase {phase} --gaps` |
|
||||
|
||||
**If human_needed:**
|
||||
```
|
||||
## ✓ Phase {X}: {Name} — Human Verification Required
|
||||
|
||||
All automated checks passed. {N} items need human testing:
|
||||
|
||||
{From VERIFICATION.md human_verification section}
|
||||
|
||||
"approved" → continue | Report issues → gap closure
|
||||
```
|
||||
|
||||
**If gaps_found:**
|
||||
```
|
||||
## ⚠ Phase {X}: {Name} — Gaps Found
|
||||
|
||||
**Score:** {N}/{M} must-haves verified
|
||||
**Report:** {phase_dir}/{phase_num}-VERIFICATION.md
|
||||
|
||||
### What's Missing
|
||||
{Gap summaries from VERIFICATION.md}
|
||||
|
||||
---
|
||||
## ▶ Next Up
|
||||
|
||||
`/gsd:plan-phase {X} --gaps`
|
||||
|
||||
<sub>`/clear` first → fresh context window</sub>
|
||||
|
||||
Also: `cat {phase_dir}/{phase_num}-VERIFICATION.md` — full report
|
||||
Also: `/gsd:verify-work {X}` — manual testing first
|
||||
```
|
||||
|
||||
Gap closure cycle: `/gsd:plan-phase {X} --gaps` reads VERIFICATION.md → creates gap plans with `gap_closure: true` → user runs `/gsd:execute-phase {X} --gaps-only` → verifier re-runs.
|
||||
</step>
|
||||
|
||||
<step name="update_roadmap">
|
||||
**Mark phase complete and update all tracking files:**
|
||||
|
||||
```bash
|
||||
COMPLETION=$(node "C:/Users/yaoji/.claude/get-shit-done/bin/gsd-tools.cjs" phase complete "${PHASE_NUMBER}")
|
||||
```
|
||||
|
||||
The CLI handles:
|
||||
- Marking phase checkbox `[x]` with completion date
|
||||
- Updating Progress table (Status → Complete, date)
|
||||
- Updating plan count to final
|
||||
- Advancing STATE.md to next phase
|
||||
- Updating REQUIREMENTS.md traceability
|
||||
|
||||
Extract from result: `next_phase`, `next_phase_name`, `is_last_phase`.
|
||||
|
||||
```bash
|
||||
node "C:/Users/yaoji/.claude/get-shit-done/bin/gsd-tools.cjs" commit "docs(phase-{X}): complete phase execution" --files .planning/ROADMAP.md .planning/STATE.md .planning/REQUIREMENTS.md {phase_dir}/*-VERIFICATION.md
|
||||
```
|
||||
</step>
|
||||
|
||||
<step name="update_project_md">
|
||||
**Evolve PROJECT.md to reflect phase completion (prevents planning document drift — #956):**
|
||||
|
||||
PROJECT.md tracks validated requirements, decisions, and current state. Without this step,
|
||||
PROJECT.md falls behind silently over multiple phases.
|
||||
|
||||
1. Read `.planning/PROJECT.md`
|
||||
2. If the file exists and has a `## Validated Requirements` or `## Requirements` section:
|
||||
- Move any requirements validated by this phase from Active → Validated
|
||||
- Add a brief note: `Validated in Phase {X}: {Name}`
|
||||
3. If the file has a `## Current State` or similar section:
|
||||
- Update it to reflect this phase's completion (e.g., "Phase {X} complete — {one-liner}")
|
||||
4. Update the `Last updated:` footer to today's date
|
||||
5. Commit the change:
|
||||
|
||||
```bash
|
||||
node "C:/Users/yaoji/.claude/get-shit-done/bin/gsd-tools.cjs" commit "docs(phase-{X}): evolve PROJECT.md after phase completion" --files .planning/PROJECT.md
|
||||
```
|
||||
|
||||
**Skip this step if** `.planning/PROJECT.md` does not exist.
|
||||
</step>
|
||||
|
||||
<step name="offer_next">
|
||||
|
||||
**Exception:** If `gaps_found`, the `verify_phase_goal` step already presents the gap-closure path (`/gsd:plan-phase {X} --gaps`). No additional routing needed — skip auto-advance.
|
||||
|
||||
**No-transition check (spawned by auto-advance chain):**
|
||||
|
||||
Parse `--no-transition` flag from $ARGUMENTS.
|
||||
|
||||
**If `--no-transition` flag present:**
|
||||
|
||||
Execute-phase was spawned by plan-phase's auto-advance. Do NOT run transition.md.
|
||||
After verification passes and roadmap is updated, return completion status to parent:
|
||||
|
||||
```
|
||||
## PHASE COMPLETE
|
||||
|
||||
Phase: ${PHASE_NUMBER} - ${PHASE_NAME}
|
||||
Plans: ${completed_count}/${total_count}
|
||||
Verification: {Passed | Gaps Found}
|
||||
|
||||
[Include aggregate_results output]
|
||||
```
|
||||
|
||||
STOP. Do not proceed to auto-advance or transition.
|
||||
|
||||
**If `--no-transition` flag is NOT present:**
|
||||
|
||||
**Auto-advance detection:**
|
||||
|
||||
1. Parse `--auto` flag from $ARGUMENTS
|
||||
2. Read both the chain flag and user preference (chain flag already synced in init step):
|
||||
```bash
|
||||
AUTO_CHAIN=$(node "C:/Users/yaoji/.claude/get-shit-done/bin/gsd-tools.cjs" config-get workflow._auto_chain_active 2>/dev/null || echo "false")
|
||||
AUTO_CFG=$(node "C:/Users/yaoji/.claude/get-shit-done/bin/gsd-tools.cjs" config-get workflow.auto_advance 2>/dev/null || echo "false")
|
||||
```
|
||||
|
||||
**If `--auto` flag present OR `AUTO_CHAIN` is true OR `AUTO_CFG` is true (AND verification passed with no gaps):**
|
||||
|
||||
```
|
||||
╔══════════════════════════════════════════╗
|
||||
║ AUTO-ADVANCING → TRANSITION ║
|
||||
║ Phase {X} verified, continuing chain ║
|
||||
╚══════════════════════════════════════════╝
|
||||
```
|
||||
|
||||
Execute the transition workflow inline (do NOT use Task — orchestrator context is ~10-15%, transition needs phase completion data already in context):
|
||||
|
||||
Read and follow `C:/Users/yaoji/.claude/get-shit-done/workflows/transition.md`, passing through the `--auto` flag so it propagates to the next phase invocation.
|
||||
|
||||
**If none of `--auto`, `AUTO_CHAIN`, or `AUTO_CFG` is true:**
|
||||
|
||||
**STOP. Do not auto-advance. Do not execute transition. Do not plan next phase. Present options to the user and wait.**
|
||||
|
||||
**IMPORTANT: There is NO `/gsd:transition` command. Never suggest it. The transition workflow is internal only.**
|
||||
|
||||
```
|
||||
## ✓ Phase {X}: {Name} Complete
|
||||
|
||||
/gsd:progress — see updated roadmap
|
||||
/gsd:discuss-phase {next} — discuss next phase before planning
|
||||
/gsd:plan-phase {next} — plan next phase
|
||||
/gsd:execute-phase {next} — execute next phase
|
||||
```
|
||||
|
||||
Only suggest the commands listed above. Do not invent or hallucinate command names.
|
||||
</step>
|
||||
|
||||
</process>
|
||||
|
||||
<context_efficiency>
|
||||
Orchestrator: ~10-15% context. Subagents: fresh 200k each. No polling (Task blocks). No context bleed.
|
||||
</context_efficiency>
|
||||
|
||||
<failure_handling>
|
||||
- **classifyHandoffIfNeeded false failure:** Agent reports "failed" but error is `classifyHandoffIfNeeded is not defined` → Claude Code bug, not GSD. Spot-check (SUMMARY exists, commits present) → if pass, treat as success
|
||||
- **Agent fails mid-plan:** Missing SUMMARY.md → report, ask user how to proceed
|
||||
- **Dependency chain breaks:** Wave 1 fails → Wave 2 dependents likely fail → user chooses attempt or skip
|
||||
- **All agents in wave fail:** Systemic issue → stop, report for investigation
|
||||
- **Checkpoint unresolvable:** "Skip this plan?" or "Abort phase execution?" → record partial progress in STATE.md
|
||||
</failure_handling>
|
||||
|
||||
<resumption>
|
||||
Re-run `/gsd:execute-phase {phase}` → discover_plans finds completed SUMMARYs → skips them → resumes from first incomplete plan → continues wave execution.
|
||||
|
||||
STATE.md tracks: last completed plan, current wave, pending checkpoints.
|
||||
</resumption>
|
||||
493
get-shit-done/workflows/execute-plan.md
Normal file
493
get-shit-done/workflows/execute-plan.md
Normal file
@@ -0,0 +1,493 @@
|
||||
<purpose>
|
||||
Execute a phase prompt (PLAN.md) and create the outcome summary (SUMMARY.md).
|
||||
</purpose>
|
||||
|
||||
<required_reading>
|
||||
Read STATE.md before any operation to load project context.
|
||||
Read config.json for planning behavior settings.
|
||||
|
||||
@C:/Users/yaoji/.claude/get-shit-done/references/git-integration.md
|
||||
</required_reading>
|
||||
|
||||
<process>
|
||||
|
||||
<step name="init_context" priority="first">
|
||||
Load execution context (paths only to minimize orchestrator context):
|
||||
|
||||
```bash
|
||||
INIT=$(node "C:/Users/yaoji/.claude/get-shit-done/bin/gsd-tools.cjs" init execute-phase "${PHASE}")
|
||||
if [[ "$INIT" == @file:* ]]; then INIT=$(cat "${INIT#@file:}"); fi
|
||||
```
|
||||
|
||||
Extract from init JSON: `executor_model`, `commit_docs`, `phase_dir`, `phase_number`, `plans`, `summaries`, `incomplete_plans`, `state_path`, `config_path`.
|
||||
|
||||
If `.planning/` missing: error.
|
||||
</step>
|
||||
|
||||
<step name="identify_plan">
|
||||
```bash
|
||||
# Use plans/summaries from INIT JSON, or list files
|
||||
ls .planning/phases/XX-name/*-PLAN.md 2>/dev/null | sort
|
||||
ls .planning/phases/XX-name/*-SUMMARY.md 2>/dev/null | sort
|
||||
```
|
||||
|
||||
Find first PLAN without matching SUMMARY. Decimal phases supported (`01.1-hotfix/`):
|
||||
|
||||
```bash
|
||||
PHASE=$(echo "$PLAN_PATH" | grep -oE '[0-9]+(\.[0-9]+)?-[0-9]+')
|
||||
# config settings can be fetched via gsd-tools config-get if needed
|
||||
```
|
||||
|
||||
<if mode="yolo">
|
||||
Auto-approve: `⚡ Execute {phase}-{plan}-PLAN.md [Plan X of Y for Phase Z]` → parse_segments.
|
||||
</if>
|
||||
|
||||
<if mode="interactive" OR="custom with gates.execute_next_plan true">
|
||||
Present plan identification, wait for confirmation.
|
||||
</if>
|
||||
</step>
|
||||
|
||||
<step name="record_start_time">
|
||||
```bash
|
||||
PLAN_START_TIME=$(date -u +"%Y-%m-%dT%H:%M:%SZ")
|
||||
PLAN_START_EPOCH=$(date +%s)
|
||||
```
|
||||
</step>
|
||||
|
||||
<step name="parse_segments">
|
||||
```bash
|
||||
grep -n "type=\"checkpoint" .planning/phases/XX-name/{phase}-{plan}-PLAN.md
|
||||
```
|
||||
|
||||
**Routing by checkpoint type:**
|
||||
|
||||
| Checkpoints | Pattern | Execution |
|
||||
|-------------|---------|-----------|
|
||||
| None | A (autonomous) | Single subagent: full plan + SUMMARY + commit |
|
||||
| Verify-only | B (segmented) | Segments between checkpoints. After none/human-verify → SUBAGENT. After decision/human-action → MAIN |
|
||||
| Decision | C (main) | Execute entirely in main context |
|
||||
|
||||
**Pattern A:** init_agent_tracking → spawn Task(subagent_type="gsd-executor", model=executor_model) with prompt: execute plan at [path], autonomous, all tasks + SUMMARY + commit, follow deviation/auth rules, report: plan name, tasks, SUMMARY path, commit hash → track agent_id → wait → update tracking → report.
|
||||
|
||||
**Pattern B:** Execute segment-by-segment. Autonomous segments: spawn subagent for assigned tasks only (no SUMMARY/commit). Checkpoints: main context. After all segments: aggregate, create SUMMARY, commit. See segment_execution.
|
||||
|
||||
**Pattern C:** Execute in main using standard flow (step name="execute").
|
||||
|
||||
Fresh context per subagent preserves peak quality. Main context stays lean.
|
||||
</step>
|
||||
|
||||
<step name="init_agent_tracking">
|
||||
```bash
|
||||
if [ ! -f .planning/agent-history.json ]; then
|
||||
echo '{"version":"1.0","max_entries":50,"entries":[]}' > .planning/agent-history.json
|
||||
fi
|
||||
rm -f .planning/current-agent-id.txt
|
||||
if [ -f .planning/current-agent-id.txt ]; then
|
||||
INTERRUPTED_ID=$(cat .planning/current-agent-id.txt)
|
||||
echo "Found interrupted agent: $INTERRUPTED_ID"
|
||||
fi
|
||||
```
|
||||
|
||||
If interrupted: ask user to resume (Task `resume` parameter) or start fresh.
|
||||
|
||||
**Tracking protocol:** On spawn: write agent_id to `current-agent-id.txt`, append to agent-history.json: `{"agent_id":"[id]","task_description":"[desc]","phase":"[phase]","plan":"[plan]","segment":[num|null],"timestamp":"[ISO]","status":"spawned","completion_timestamp":null}`. On completion: status → "completed", set completion_timestamp, delete current-agent-id.txt. Prune: if entries > max_entries, remove oldest "completed" (never "spawned").
|
||||
|
||||
Run for Pattern A/B before spawning. Pattern C: skip.
|
||||
</step>
|
||||
|
||||
<step name="segment_execution">
|
||||
Pattern B only (verify-only checkpoints). Skip for A/C.
|
||||
|
||||
1. Parse segment map: checkpoint locations and types
|
||||
2. Per segment:
|
||||
- Subagent route: spawn gsd-executor for assigned tasks only. Prompt: task range, plan path, read full plan for context, execute assigned tasks, track deviations, NO SUMMARY/commit. Track via agent protocol.
|
||||
- Main route: execute tasks using standard flow (step name="execute")
|
||||
3. After ALL segments: aggregate files/deviations/decisions → create SUMMARY.md → commit → self-check:
|
||||
- Verify key-files.created exist on disk with `[ -f ]`
|
||||
- Check `git log --oneline --all --grep="{phase}-{plan}"` returns ≥1 commit
|
||||
- Append `## Self-Check: PASSED` or `## Self-Check: FAILED` to SUMMARY
|
||||
|
||||
**Known Claude Code bug (classifyHandoffIfNeeded):** If any segment agent reports "failed" with `classifyHandoffIfNeeded is not defined`, this is a Claude Code runtime bug — not a real failure. Run spot-checks; if they pass, treat as successful.
|
||||
|
||||
|
||||
|
||||
|
||||
</step>
|
||||
|
||||
<step name="load_prompt">
|
||||
```bash
|
||||
cat .planning/phases/XX-name/{phase}-{plan}-PLAN.md
|
||||
```
|
||||
This IS the execution instructions. Follow exactly. If plan references CONTEXT.md: honor user's vision throughout.
|
||||
|
||||
**If plan contains `<interfaces>` block:** These are pre-extracted type definitions and contracts. Use them directly — do NOT re-read the source files to discover types. The planner already extracted what you need.
|
||||
</step>
|
||||
|
||||
<step name="previous_phase_check">
|
||||
```bash
|
||||
node "C:/Users/yaoji/.claude/get-shit-done/bin/gsd-tools.cjs" phases list --type summaries --raw
|
||||
# Extract the second-to-last summary from the JSON result
|
||||
```
|
||||
If previous SUMMARY has unresolved "Issues Encountered" or "Next Phase Readiness" blockers: AskUserQuestion(header="Previous Issues", options: "Proceed anyway" | "Address first" | "Review previous").
|
||||
</step>
|
||||
|
||||
<step name="execute">
|
||||
Deviations are normal — handle via rules below.
|
||||
|
||||
1. Read @context files from prompt
|
||||
2. **MCP tools:** If CLAUDE.md or project instructions reference MCP tools (e.g. jCodeMunch for code navigation), prefer them over Grep/Glob when available. Fall back to Grep/Glob if MCP tools are not accessible.
|
||||
3. Per task:
|
||||
- **MANDATORY read_first gate:** If the task has a `<read_first>` field, you MUST read every listed file BEFORE making any edits. This is not optional. Do not skip files because you "already know" what's in them — read them. The read_first files establish ground truth for the task.
|
||||
- `type="auto"`: if `tdd="true"` → TDD execution. Implement with deviation rules + auth gates. Verify done criteria. Commit (see task_commit). Track hash for Summary.
|
||||
- `type="checkpoint:*"`: STOP → checkpoint_protocol → wait for user → continue only after confirmation.
|
||||
- **MANDATORY acceptance_criteria check:** After completing each task, if it has `<acceptance_criteria>`, verify EVERY criterion before moving to the next task. Use grep, file reads, or CLI commands to confirm each criterion. If any criterion fails, fix the implementation before proceeding. Do not skip criteria or mark them as "will verify later".
|
||||
3. Run `<verification>` checks
|
||||
4. Confirm `<success_criteria>` met
|
||||
5. Document deviations in Summary
|
||||
</step>
|
||||
|
||||
<authentication_gates>
|
||||
|
||||
## Authentication Gates
|
||||
|
||||
Auth errors during execution are NOT failures — they're expected interaction points.
|
||||
|
||||
**Indicators:** "Not authenticated", "Unauthorized", 401/403, "Please run {tool} login", "Set {ENV_VAR}"
|
||||
|
||||
**Protocol:**
|
||||
1. Recognize auth gate (not a bug)
|
||||
2. STOP task execution
|
||||
3. Create dynamic checkpoint:human-action with exact auth steps
|
||||
4. Wait for user to authenticate
|
||||
5. Verify credentials work
|
||||
6. Retry original task
|
||||
7. Continue normally
|
||||
|
||||
**Example:** `vercel --yes` → "Not authenticated" → checkpoint asking user to `vercel login` → verify with `vercel whoami` → retry deploy → continue
|
||||
|
||||
**In Summary:** Document as normal flow under "## Authentication Gates", not as deviations.
|
||||
|
||||
</authentication_gates>
|
||||
|
||||
<deviation_rules>
|
||||
|
||||
## Deviation Rules
|
||||
|
||||
You WILL discover unplanned work. Apply automatically, track all for Summary.
|
||||
|
||||
| Rule | Trigger | Action | Permission |
|
||||
|------|---------|--------|------------|
|
||||
| **1: Bug** | Broken behavior, errors, wrong queries, type errors, security vulns, race conditions, leaks | Fix → test → verify → track `[Rule 1 - Bug]` | Auto |
|
||||
| **2: Missing Critical** | Missing essentials: error handling, validation, auth, CSRF/CORS, rate limiting, indexes, logging | Add → test → verify → track `[Rule 2 - Missing Critical]` | Auto |
|
||||
| **3: Blocking** | Prevents completion: missing deps, wrong types, broken imports, missing env/config/files, circular deps | Fix blocker → verify proceeds → track `[Rule 3 - Blocking]` | Auto |
|
||||
| **4: Architectural** | Structural change: new DB table, schema change, new service, switching libs, breaking API, new infra | STOP → present decision (below) → track `[Rule 4 - Architectural]` | Ask user |
|
||||
|
||||
**Rule 4 format:**
|
||||
```
|
||||
⚠️ Architectural Decision Needed
|
||||
|
||||
Current task: [task name]
|
||||
Discovery: [what prompted this]
|
||||
Proposed change: [modification]
|
||||
Why needed: [rationale]
|
||||
Impact: [what this affects]
|
||||
Alternatives: [other approaches]
|
||||
|
||||
Proceed with proposed change? (yes / different approach / defer)
|
||||
```
|
||||
|
||||
**Priority:** Rule 4 (STOP) > Rules 1-3 (auto) > unsure → Rule 4
|
||||
**Edge cases:** missing validation → R2 | null crash → R1 | new table → R4 | new column → R1/2
|
||||
**Heuristic:** Affects correctness/security/completion? → R1-3. Maybe? → R4.
|
||||
|
||||
</deviation_rules>
|
||||
|
||||
<deviation_documentation>
|
||||
|
||||
## Documenting Deviations
|
||||
|
||||
Summary MUST include deviations section. None? → `## Deviations from Plan\n\nNone - plan executed exactly as written.`
|
||||
|
||||
Per deviation: **[Rule N - Category] Title** — Found during: Task X | Issue | Fix | Files modified | Verification | Commit hash
|
||||
|
||||
End with: **Total deviations:** N auto-fixed (breakdown). **Impact:** assessment.
|
||||
|
||||
</deviation_documentation>
|
||||
|
||||
<tdd_plan_execution>
|
||||
## TDD Execution
|
||||
|
||||
For `type: tdd` plans — RED-GREEN-REFACTOR:
|
||||
|
||||
1. **Infrastructure** (first TDD plan only): detect project, install framework, config, verify empty suite
|
||||
2. **RED:** Read `<behavior>` → failing test(s) → run (MUST fail) → commit: `test({phase}-{plan}): add failing test for [feature]`
|
||||
3. **GREEN:** Read `<implementation>` → minimal code → run (MUST pass) → commit: `feat({phase}-{plan}): implement [feature]`
|
||||
4. **REFACTOR:** Clean up → tests MUST pass → commit: `refactor({phase}-{plan}): clean up [feature]`
|
||||
|
||||
Errors: RED doesn't fail → investigate test/existing feature. GREEN doesn't pass → debug, iterate. REFACTOR breaks → undo.
|
||||
|
||||
See `C:/Users/yaoji/.claude/get-shit-done/references/tdd.md` for structure.
|
||||
</tdd_plan_execution>
|
||||
|
||||
<precommit_failure_handling>
|
||||
## Pre-commit Hook Failure Handling
|
||||
|
||||
Your commits may trigger pre-commit hooks. Auto-fix hooks handle themselves transparently — files get fixed and re-staged automatically.
|
||||
|
||||
If a commit is BLOCKED by a hook:
|
||||
|
||||
1. The `git commit` command fails with hook error output
|
||||
2. Read the error — it tells you exactly which hook and what failed
|
||||
3. Fix the issue (type error, lint violation, secret leak, etc.)
|
||||
4. `git add` the fixed files
|
||||
5. Retry the commit
|
||||
6. Do NOT use `--no-verify`
|
||||
|
||||
This is normal and expected. Budget 1-2 retry cycles per commit.
|
||||
</precommit_failure_handling>
|
||||
|
||||
<task_commit>
|
||||
## Task Commit Protocol
|
||||
|
||||
After each task (verification passed, done criteria met), commit immediately.
|
||||
|
||||
**1. Check:** `git status --short`
|
||||
|
||||
**2. Stage individually** (NEVER `git add .` or `git add -A`):
|
||||
```bash
|
||||
git add src/api/auth.ts
|
||||
git add src/types/user.ts
|
||||
```
|
||||
|
||||
**3. Commit type:**
|
||||
|
||||
| Type | When | Example |
|
||||
|------|------|---------|
|
||||
| `feat` | New functionality | feat(08-02): create user registration endpoint |
|
||||
| `fix` | Bug fix | fix(08-02): correct email validation regex |
|
||||
| `test` | Test-only (TDD RED) | test(08-02): add failing test for password hashing |
|
||||
| `refactor` | No behavior change (TDD REFACTOR) | refactor(08-02): extract validation to helper |
|
||||
| `perf` | Performance | perf(08-02): add database index |
|
||||
| `docs` | Documentation | docs(08-02): add API docs |
|
||||
| `style` | Formatting | style(08-02): format auth module |
|
||||
| `chore` | Config/deps | chore(08-02): add bcrypt dependency |
|
||||
|
||||
**4. Format:** `{type}({phase}-{plan}): {description}` with bullet points for key changes.
|
||||
|
||||
**5. Record hash:**
|
||||
```bash
|
||||
TASK_COMMIT=$(git rev-parse --short HEAD)
|
||||
TASK_COMMITS+=("Task ${TASK_NUM}: ${TASK_COMMIT}")
|
||||
```
|
||||
|
||||
**6. Check for untracked generated files:**
|
||||
```bash
|
||||
git status --short | grep '^??'
|
||||
```
|
||||
If new untracked files appeared after running scripts or tools, decide for each:
|
||||
- **Commit it** — if it's a source file, config, or intentional artifact
|
||||
- **Add to .gitignore** — if it's a generated/runtime output (build artifacts, `.env` files, cache files, compiled output)
|
||||
- Do NOT leave generated files untracked
|
||||
|
||||
</task_commit>
|
||||
|
||||
<step name="checkpoint_protocol">
|
||||
On `type="checkpoint:*"`: automate everything possible first. Checkpoints are for verification/decisions only.
|
||||
|
||||
Display: `CHECKPOINT: [Type]` box → Progress {X}/{Y} → Task name → type-specific content → `YOUR ACTION: [signal]`
|
||||
|
||||
| Type | Content | Resume signal |
|
||||
|------|---------|---------------|
|
||||
| human-verify (90%) | What was built + verification steps (commands/URLs) | "approved" or describe issues |
|
||||
| decision (9%) | Decision needed + context + options with pros/cons | "Select: option-id" |
|
||||
| human-action (1%) | What was automated + ONE manual step + verification plan | "done" |
|
||||
|
||||
After response: verify if specified. Pass → continue. Fail → inform, wait. WAIT for user — do NOT hallucinate completion.
|
||||
|
||||
See C:/Users/yaoji/.claude/get-shit-done/references/checkpoints.md for details.
|
||||
</step>
|
||||
|
||||
<step name="checkpoint_return_for_orchestrator">
|
||||
When spawned via Task and hitting checkpoint: return structured state (cannot interact with user directly).
|
||||
|
||||
**Required return:** 1) Completed Tasks table (hashes + files) 2) Current Task (what's blocking) 3) Checkpoint Details (user-facing content) 4) Awaiting (what's needed from user)
|
||||
|
||||
Orchestrator parses → presents to user → spawns fresh continuation with your completed tasks state. You will NOT be resumed. In main context: use checkpoint_protocol above.
|
||||
</step>
|
||||
|
||||
<step name="verification_failure_gate">
|
||||
If verification fails:
|
||||
|
||||
**Check if node repair is enabled** (default: on):
|
||||
```bash
|
||||
NODE_REPAIR=$(node "./.claude/get-shit-done/bin/gsd-tools.cjs" config-get workflow.node_repair 2>/dev/null || echo "true")
|
||||
```
|
||||
|
||||
If `NODE_REPAIR` is `true`: invoke `@./.claude/get-shit-done/workflows/node-repair.md` with:
|
||||
- FAILED_TASK: task number, name, done-criteria
|
||||
- ERROR: expected vs actual result
|
||||
- PLAN_CONTEXT: adjacent task names + phase goal
|
||||
- REPAIR_BUDGET: `workflow.node_repair_budget` from config (default: 2)
|
||||
|
||||
Node repair will attempt RETRY, DECOMPOSE, or PRUNE autonomously. Only reaches this gate again if repair budget is exhausted (ESCALATE).
|
||||
|
||||
If `NODE_REPAIR` is `false` OR repair returns ESCALATE: STOP. Present: "Verification failed for Task [X]: [name]. Expected: [criteria]. Actual: [result]. Repair attempted: [summary of what was tried]." Options: Retry | Skip (mark incomplete) | Stop (investigate). If skipped → SUMMARY "Issues Encountered".
|
||||
</step>
|
||||
|
||||
<step name="record_completion_time">
|
||||
```bash
|
||||
PLAN_END_TIME=$(date -u +"%Y-%m-%dT%H:%M:%SZ")
|
||||
PLAN_END_EPOCH=$(date +%s)
|
||||
|
||||
DURATION_SEC=$(( PLAN_END_EPOCH - PLAN_START_EPOCH ))
|
||||
DURATION_MIN=$(( DURATION_SEC / 60 ))
|
||||
|
||||
if [[ $DURATION_MIN -ge 60 ]]; then
|
||||
HRS=$(( DURATION_MIN / 60 ))
|
||||
MIN=$(( DURATION_MIN % 60 ))
|
||||
DURATION="${HRS}h ${MIN}m"
|
||||
else
|
||||
DURATION="${DURATION_MIN} min"
|
||||
fi
|
||||
```
|
||||
</step>
|
||||
|
||||
<step name="generate_user_setup">
|
||||
```bash
|
||||
grep -A 50 "^user_setup:" .planning/phases/XX-name/{phase}-{plan}-PLAN.md | head -50
|
||||
```
|
||||
|
||||
If user_setup exists: create `{phase}-USER-SETUP.md` using template `C:/Users/yaoji/.claude/get-shit-done/templates/user-setup.md`. Per service: env vars table, account setup checklist, dashboard config, local dev notes, verification commands. Status "Incomplete". Set `USER_SETUP_CREATED=true`. If empty/missing: skip.
|
||||
</step>
|
||||
|
||||
<step name="create_summary">
|
||||
Create `{phase}-{plan}-SUMMARY.md` at `.planning/phases/XX-name/`. Use `C:/Users/yaoji/.claude/get-shit-done/templates/summary.md`.
|
||||
|
||||
**Frontmatter:** phase, plan, subsystem, tags | requires/provides/affects | tech-stack.added/patterns | key-files.created/modified | key-decisions | requirements-completed (**MUST** copy `requirements` array from PLAN.md frontmatter verbatim) | duration ($DURATION), completed ($PLAN_END_TIME date).
|
||||
|
||||
Title: `# Phase [X] Plan [Y]: [Name] Summary`
|
||||
|
||||
One-liner SUBSTANTIVE: "JWT auth with refresh rotation using jose library" not "Authentication implemented"
|
||||
|
||||
Include: duration, start/end times, task count, file count.
|
||||
|
||||
Next: more plans → "Ready for {next-plan}" | last → "Phase complete, ready for next step".
|
||||
</step>
|
||||
|
||||
<step name="update_current_position">
|
||||
Update STATE.md using gsd-tools:
|
||||
|
||||
```bash
|
||||
# Advance plan counter (handles last-plan edge case)
|
||||
node "C:/Users/yaoji/.claude/get-shit-done/bin/gsd-tools.cjs" state advance-plan
|
||||
|
||||
# Recalculate progress bar from disk state
|
||||
node "C:/Users/yaoji/.claude/get-shit-done/bin/gsd-tools.cjs" state update-progress
|
||||
|
||||
# Record execution metrics
|
||||
node "C:/Users/yaoji/.claude/get-shit-done/bin/gsd-tools.cjs" state record-metric \
|
||||
--phase "${PHASE}" --plan "${PLAN}" --duration "${DURATION}" \
|
||||
--tasks "${TASK_COUNT}" --files "${FILE_COUNT}"
|
||||
```
|
||||
</step>
|
||||
|
||||
<step name="extract_decisions_and_issues">
|
||||
From SUMMARY: Extract decisions and add to STATE.md:
|
||||
|
||||
```bash
|
||||
# Add each decision from SUMMARY key-decisions
|
||||
# Prefer file inputs for shell-safe text (preserves `$`, `*`, etc. exactly)
|
||||
node "C:/Users/yaoji/.claude/get-shit-done/bin/gsd-tools.cjs" state add-decision \
|
||||
--phase "${PHASE}" --summary-file "${DECISION_TEXT_FILE}" --rationale-file "${RATIONALE_FILE}"
|
||||
|
||||
# Add blockers if any found
|
||||
node "C:/Users/yaoji/.claude/get-shit-done/bin/gsd-tools.cjs" state add-blocker --text-file "${BLOCKER_TEXT_FILE}"
|
||||
```
|
||||
</step>
|
||||
|
||||
<step name="update_session_continuity">
|
||||
Update session info using gsd-tools:
|
||||
|
||||
```bash
|
||||
node "C:/Users/yaoji/.claude/get-shit-done/bin/gsd-tools.cjs" state record-session \
|
||||
--stopped-at "Completed ${PHASE}-${PLAN}-PLAN.md" \
|
||||
--resume-file "None"
|
||||
```
|
||||
|
||||
Keep STATE.md under 150 lines.
|
||||
</step>
|
||||
|
||||
<step name="issues_review_gate">
|
||||
If SUMMARY "Issues Encountered" ≠ "None": yolo → log and continue. Interactive → present issues, wait for acknowledgment.
|
||||
</step>
|
||||
|
||||
<step name="update_roadmap">
|
||||
```bash
|
||||
node "C:/Users/yaoji/.claude/get-shit-done/bin/gsd-tools.cjs" roadmap update-plan-progress "${PHASE}"
|
||||
```
|
||||
Counts PLAN vs SUMMARY files on disk. Updates progress table row with correct count and status (`In Progress` or `Complete` with date).
|
||||
</step>
|
||||
|
||||
<step name="update_requirements">
|
||||
Mark completed requirements from the PLAN.md frontmatter `requirements:` field:
|
||||
|
||||
```bash
|
||||
node "C:/Users/yaoji/.claude/get-shit-done/bin/gsd-tools.cjs" requirements mark-complete ${REQ_IDS}
|
||||
```
|
||||
|
||||
Extract requirement IDs from the plan's frontmatter (e.g., `requirements: [AUTH-01, AUTH-02]`). If no requirements field, skip.
|
||||
</step>
|
||||
|
||||
<step name="git_commit_metadata">
|
||||
Task code already committed per-task. Commit plan metadata:
|
||||
|
||||
```bash
|
||||
node "C:/Users/yaoji/.claude/get-shit-done/bin/gsd-tools.cjs" commit "docs({phase}-{plan}): complete [plan-name] plan" --files .planning/phases/XX-name/{phase}-{plan}-SUMMARY.md .planning/STATE.md .planning/ROADMAP.md .planning/REQUIREMENTS.md
|
||||
```
|
||||
</step>
|
||||
|
||||
<step name="update_codebase_map">
|
||||
If .planning/codebase/ doesn't exist: skip.
|
||||
|
||||
```bash
|
||||
FIRST_TASK=$(git log --oneline --grep="feat({phase}-{plan}):" --grep="fix({phase}-{plan}):" --grep="test({phase}-{plan}):" --reverse | head -1 | cut -d' ' -f1)
|
||||
git diff --name-only ${FIRST_TASK}^..HEAD 2>/dev/null
|
||||
```
|
||||
|
||||
Update only structural changes: new src/ dir → STRUCTURE.md | deps → STACK.md | file pattern → CONVENTIONS.md | API client → INTEGRATIONS.md | config → STACK.md | renamed → update paths. Skip code-only/bugfix/content changes.
|
||||
|
||||
```bash
|
||||
node "C:/Users/yaoji/.claude/get-shit-done/bin/gsd-tools.cjs" commit "" --files .planning/codebase/*.md --amend
|
||||
```
|
||||
</step>
|
||||
|
||||
<step name="offer_next">
|
||||
If `USER_SETUP_CREATED=true`: display `⚠️ USER SETUP REQUIRED` with path + env/config tasks at TOP.
|
||||
|
||||
```bash
|
||||
ls -1 .planning/phases/[current-phase-dir]/*-PLAN.md 2>/dev/null | wc -l
|
||||
ls -1 .planning/phases/[current-phase-dir]/*-SUMMARY.md 2>/dev/null | wc -l
|
||||
```
|
||||
|
||||
| Condition | Route | Action |
|
||||
|-----------|-------|--------|
|
||||
| summaries < plans | **A: More plans** | Find next PLAN without SUMMARY. Yolo: auto-continue. Interactive: show next plan, suggest `/gsd:execute-phase {phase}` + `/gsd:verify-work`. STOP here. |
|
||||
| summaries = plans, current < highest phase | **B: Phase done** | Show completion, suggest `/gsd:plan-phase {Z+1}` + `/gsd:verify-work {Z}` + `/gsd:discuss-phase {Z+1}` |
|
||||
| summaries = plans, current = highest phase | **C: Milestone done** | Show banner, suggest `/gsd:complete-milestone` + `/gsd:verify-work` + `/gsd:add-phase` |
|
||||
|
||||
All routes: `/clear` first for fresh context.
|
||||
</step>
|
||||
|
||||
</process>
|
||||
|
||||
<success_criteria>
|
||||
|
||||
- All tasks from PLAN.md completed
|
||||
- All verifications pass
|
||||
- USER-SETUP.md generated if user_setup in frontmatter
|
||||
- SUMMARY.md created with substantive content
|
||||
- STATE.md updated (position, decisions, issues, session)
|
||||
- ROADMAP.md updated
|
||||
- If codebase map exists: map updated with execution changes (or skipped if no significant changes)
|
||||
- If USER-SETUP.md created: prominently surfaced in completion output
|
||||
</success_criteria>
|
||||
159
get-shit-done/workflows/health.md
Normal file
159
get-shit-done/workflows/health.md
Normal file
@@ -0,0 +1,159 @@
|
||||
<purpose>
|
||||
Validate `.planning/` directory integrity and report actionable issues. Checks for missing files, invalid configurations, inconsistent state, and orphaned plans. Optionally repairs auto-fixable issues.
|
||||
</purpose>
|
||||
|
||||
<required_reading>
|
||||
Read all files referenced by the invoking prompt's execution_context before starting.
|
||||
</required_reading>
|
||||
|
||||
<process>
|
||||
|
||||
<step name="parse_args">
|
||||
**Parse arguments:**
|
||||
|
||||
Check if `--repair` flag is present in the command arguments.
|
||||
|
||||
```
|
||||
REPAIR_FLAG=""
|
||||
if arguments contain "--repair"; then
|
||||
REPAIR_FLAG="--repair"
|
||||
fi
|
||||
```
|
||||
</step>
|
||||
|
||||
<step name="run_health_check">
|
||||
**Run health validation:**
|
||||
|
||||
```bash
|
||||
node "C:/Users/yaoji/.claude/get-shit-done/bin/gsd-tools.cjs" validate health $REPAIR_FLAG
|
||||
```
|
||||
|
||||
Parse JSON output:
|
||||
- `status`: "healthy" | "degraded" | "broken"
|
||||
- `errors[]`: Critical issues (code, message, fix, repairable)
|
||||
- `warnings[]`: Non-critical issues
|
||||
- `info[]`: Informational notes
|
||||
- `repairable_count`: Number of auto-fixable issues
|
||||
- `repairs_performed[]`: Actions taken if --repair was used
|
||||
</step>
|
||||
|
||||
<step name="format_output">
|
||||
**Format and display results:**
|
||||
|
||||
```
|
||||
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
|
||||
GSD Health Check
|
||||
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
|
||||
|
||||
Status: HEALTHY | DEGRADED | BROKEN
|
||||
Errors: N | Warnings: N | Info: N
|
||||
```
|
||||
|
||||
**If repairs were performed:**
|
||||
```
|
||||
## Repairs Performed
|
||||
|
||||
- ✓ config.json: Created with defaults
|
||||
- ✓ STATE.md: Regenerated from roadmap
|
||||
```
|
||||
|
||||
**If errors exist:**
|
||||
```
|
||||
## Errors
|
||||
|
||||
- [E001] config.json: JSON parse error at line 5
|
||||
Fix: Run /gsd:health --repair to reset to defaults
|
||||
|
||||
- [E002] PROJECT.md not found
|
||||
Fix: Run /gsd:new-project to create
|
||||
```
|
||||
|
||||
**If warnings exist:**
|
||||
```
|
||||
## Warnings
|
||||
|
||||
- [W001] STATE.md references phase 5, but only phases 1-3 exist
|
||||
Fix: Run /gsd:health --repair to regenerate
|
||||
|
||||
- [W005] Phase directory "1-setup" doesn't follow NN-name format
|
||||
Fix: Rename to match pattern (e.g., 01-setup)
|
||||
```
|
||||
|
||||
**If info exists:**
|
||||
```
|
||||
## Info
|
||||
|
||||
- [I001] 02-implementation/02-01-PLAN.md has no SUMMARY.md
|
||||
Note: May be in progress
|
||||
```
|
||||
|
||||
**Footer (if repairable issues exist and --repair was NOT used):**
|
||||
```
|
||||
---
|
||||
N issues can be auto-repaired. Run: /gsd:health --repair
|
||||
```
|
||||
</step>
|
||||
|
||||
<step name="offer_repair">
|
||||
**If repairable issues exist and --repair was NOT used:**
|
||||
|
||||
Ask user if they want to run repairs:
|
||||
|
||||
```
|
||||
Would you like to run /gsd:health --repair to fix N issues automatically?
|
||||
```
|
||||
|
||||
If yes, re-run with --repair flag and display results.
|
||||
</step>
|
||||
|
||||
<step name="verify_repairs">
|
||||
**If repairs were performed:**
|
||||
|
||||
Re-run health check without --repair to confirm issues are resolved:
|
||||
|
||||
```bash
|
||||
node "C:/Users/yaoji/.claude/get-shit-done/bin/gsd-tools.cjs" validate health
|
||||
```
|
||||
|
||||
Report final status.
|
||||
</step>
|
||||
|
||||
</process>
|
||||
|
||||
<error_codes>
|
||||
|
||||
| Code | Severity | Description | Repairable |
|
||||
|------|----------|-------------|------------|
|
||||
| E001 | error | .planning/ directory not found | No |
|
||||
| E002 | error | PROJECT.md not found | No |
|
||||
| E003 | error | ROADMAP.md not found | No |
|
||||
| E004 | error | STATE.md not found | Yes |
|
||||
| E005 | error | config.json parse error | Yes |
|
||||
| W001 | warning | PROJECT.md missing required section | No |
|
||||
| W002 | warning | STATE.md references invalid phase | Yes |
|
||||
| W003 | warning | config.json not found | Yes |
|
||||
| W004 | warning | config.json invalid field value | No |
|
||||
| W005 | warning | Phase directory naming mismatch | No |
|
||||
| W006 | warning | Phase in ROADMAP but no directory | No |
|
||||
| W007 | warning | Phase on disk but not in ROADMAP | No |
|
||||
| W008 | warning | config.json: workflow.nyquist_validation absent (defaults to enabled but agents may skip) | Yes |
|
||||
| W009 | warning | Phase has Validation Architecture in RESEARCH.md but no VALIDATION.md | No |
|
||||
| I001 | info | Plan without SUMMARY (may be in progress) | No |
|
||||
|
||||
</error_codes>
|
||||
|
||||
<repair_actions>
|
||||
|
||||
| Action | Effect | Risk |
|
||||
|--------|--------|------|
|
||||
| createConfig | Create config.json with defaults | None |
|
||||
| resetConfig | Delete + recreate config.json | Loses custom settings |
|
||||
| regenerateState | Create STATE.md from ROADMAP structure | Loses session history |
|
||||
| addNyquistKey | Add workflow.nyquist_validation: true to config.json | None — matches existing default |
|
||||
|
||||
**Not repairable (too risky):**
|
||||
- PROJECT.md, ROADMAP.md content
|
||||
- Phase directory renaming
|
||||
- Orphaned plan cleanup
|
||||
|
||||
</repair_actions>
|
||||
542
get-shit-done/workflows/help.md
Normal file
542
get-shit-done/workflows/help.md
Normal file
@@ -0,0 +1,542 @@
|
||||
<purpose>
|
||||
Display the complete GSD command reference. Output ONLY the reference content. Do NOT add project-specific analysis, git status, next-step suggestions, or any commentary beyond the reference.
|
||||
</purpose>
|
||||
|
||||
<reference>
|
||||
# GSD Command Reference
|
||||
|
||||
**GSD** (Get Shit Done) creates hierarchical project plans optimized for solo agentic development with Claude Code.
|
||||
|
||||
## Quick Start
|
||||
|
||||
1. `/gsd:new-project` - Initialize project (includes research, requirements, roadmap)
|
||||
2. `/gsd:plan-phase 1` - Create detailed plan for first phase
|
||||
3. `/gsd:execute-phase 1` - Execute the phase
|
||||
|
||||
## Staying Updated
|
||||
|
||||
GSD evolves fast. Update periodically:
|
||||
|
||||
```bash
|
||||
npx get-shit-done-cc@latest
|
||||
```
|
||||
|
||||
## Core Workflow
|
||||
|
||||
```
|
||||
/gsd:new-project → /gsd:plan-phase → /gsd:execute-phase → repeat
|
||||
```
|
||||
|
||||
### Project Initialization
|
||||
|
||||
**`/gsd:new-project`**
|
||||
Initialize new project through unified flow.
|
||||
|
||||
One command takes you from idea to ready-for-planning:
|
||||
- Deep questioning to understand what you're building
|
||||
- Optional domain research (spawns 4 parallel researcher agents)
|
||||
- Requirements definition with v1/v2/out-of-scope scoping
|
||||
- Roadmap creation with phase breakdown and success criteria
|
||||
|
||||
Creates all `.planning/` artifacts:
|
||||
- `PROJECT.md` — vision and requirements
|
||||
- `config.json` — workflow mode (interactive/yolo)
|
||||
- `research/` — domain research (if selected)
|
||||
- `REQUIREMENTS.md` — scoped requirements with REQ-IDs
|
||||
- `ROADMAP.md` — phases mapped to requirements
|
||||
- `STATE.md` — project memory
|
||||
|
||||
Usage: `/gsd:new-project`
|
||||
|
||||
**`/gsd:map-codebase`**
|
||||
Map an existing codebase for brownfield projects.
|
||||
|
||||
- Analyzes codebase with parallel Explore agents
|
||||
- Creates `.planning/codebase/` with 7 focused documents
|
||||
- Covers stack, architecture, structure, conventions, testing, integrations, concerns
|
||||
- Use before `/gsd:new-project` on existing codebases
|
||||
|
||||
Usage: `/gsd:map-codebase`
|
||||
|
||||
### Phase Planning
|
||||
|
||||
**`/gsd:discuss-phase <number>`**
|
||||
Help articulate your vision for a phase before planning.
|
||||
|
||||
- Captures how you imagine this phase working
|
||||
- Creates CONTEXT.md with your vision, essentials, and boundaries
|
||||
- Use when you have ideas about how something should look/feel
|
||||
- Optional `--batch` asks 2-5 related questions at a time instead of one-by-one
|
||||
|
||||
Usage: `/gsd:discuss-phase 2`
|
||||
Usage: `/gsd:discuss-phase 2 --batch`
|
||||
Usage: `/gsd:discuss-phase 2 --batch=3`
|
||||
|
||||
**`/gsd:research-phase <number>`**
|
||||
Comprehensive ecosystem research for niche/complex domains.
|
||||
|
||||
- Discovers standard stack, architecture patterns, pitfalls
|
||||
- Creates RESEARCH.md with "how experts build this" knowledge
|
||||
- Use for 3D, games, audio, shaders, ML, and other specialized domains
|
||||
- Goes beyond "which library" to ecosystem knowledge
|
||||
|
||||
Usage: `/gsd:research-phase 3`
|
||||
|
||||
**`/gsd:list-phase-assumptions <number>`**
|
||||
See what Claude is planning to do before it starts.
|
||||
|
||||
- Shows Claude's intended approach for a phase
|
||||
- Lets you course-correct if Claude misunderstood your vision
|
||||
- No files created - conversational output only
|
||||
|
||||
Usage: `/gsd:list-phase-assumptions 3`
|
||||
|
||||
**`/gsd:plan-phase <number>`**
|
||||
Create detailed execution plan for a specific phase.
|
||||
|
||||
- Generates `.planning/phases/XX-phase-name/XX-YY-PLAN.md`
|
||||
- Breaks phase into concrete, actionable tasks
|
||||
- Includes verification criteria and success measures
|
||||
- Multiple plans per phase supported (XX-01, XX-02, etc.)
|
||||
|
||||
Usage: `/gsd:plan-phase 1`
|
||||
Result: Creates `.planning/phases/01-foundation/01-01-PLAN.md`
|
||||
|
||||
**PRD Express Path:** Pass `--prd path/to/requirements.md` to skip discuss-phase entirely. Your PRD becomes locked decisions in CONTEXT.md. Useful when you already have clear acceptance criteria.
|
||||
|
||||
### Execution
|
||||
|
||||
**`/gsd:execute-phase <phase-number>`**
|
||||
Execute all plans in a phase.
|
||||
|
||||
- Groups plans by wave (from frontmatter), executes waves sequentially
|
||||
- Plans within each wave run in parallel via Task tool
|
||||
- Verifies phase goal after all plans complete
|
||||
- Updates REQUIREMENTS.md, ROADMAP.md, STATE.md
|
||||
|
||||
Usage: `/gsd:execute-phase 5`
|
||||
|
||||
### Smart Router
|
||||
|
||||
**`/gsd:do <description>`**
|
||||
Route freeform text to the right GSD command automatically.
|
||||
|
||||
- Analyzes natural language input to find the best matching GSD command
|
||||
- Acts as a dispatcher — never does the work itself
|
||||
- Resolves ambiguity by asking you to pick between top matches
|
||||
- Use when you know what you want but don't know which `/gsd:*` command to run
|
||||
|
||||
Usage: `/gsd:do fix the login button`
|
||||
Usage: `/gsd:do refactor the auth system`
|
||||
Usage: `/gsd:do I want to start a new milestone`
|
||||
|
||||
### Quick Mode
|
||||
|
||||
**`/gsd:quick [--full] [--discuss] [--research]`**
|
||||
Execute small, ad-hoc tasks with GSD guarantees but skip optional agents.
|
||||
|
||||
Quick mode uses the same system with a shorter path:
|
||||
- Spawns planner + executor (skips researcher, checker, verifier by default)
|
||||
- Quick tasks live in `.planning/quick/` separate from planned phases
|
||||
- Updates STATE.md tracking (not ROADMAP.md)
|
||||
|
||||
Flags enable additional quality steps:
|
||||
- `--discuss` — Lightweight discussion to surface gray areas before planning
|
||||
- `--research` — Focused research agent investigates approaches before planning
|
||||
- `--full` — Adds plan-checking (max 2 iterations) and post-execution verification
|
||||
|
||||
Flags are composable: `--discuss --research --full` gives the complete quality pipeline for a single task.
|
||||
|
||||
Usage: `/gsd:quick`
|
||||
Usage: `/gsd:quick --research --full`
|
||||
Result: Creates `.planning/quick/NNN-slug/PLAN.md`, `.planning/quick/NNN-slug/SUMMARY.md`
|
||||
|
||||
### Roadmap Management
|
||||
|
||||
**`/gsd:add-phase <description>`**
|
||||
Add new phase to end of current milestone.
|
||||
|
||||
- Appends to ROADMAP.md
|
||||
- Uses next sequential number
|
||||
- Updates phase directory structure
|
||||
|
||||
Usage: `/gsd:add-phase "Add admin dashboard"`
|
||||
|
||||
**`/gsd:insert-phase <after> <description>`**
|
||||
Insert urgent work as decimal phase between existing phases.
|
||||
|
||||
- Creates intermediate phase (e.g., 7.1 between 7 and 8)
|
||||
- Useful for discovered work that must happen mid-milestone
|
||||
- Maintains phase ordering
|
||||
|
||||
Usage: `/gsd:insert-phase 7 "Fix critical auth bug"`
|
||||
Result: Creates Phase 7.1
|
||||
|
||||
**`/gsd:remove-phase <number>`**
|
||||
Remove a future phase and renumber subsequent phases.
|
||||
|
||||
- Deletes phase directory and all references
|
||||
- Renumbers all subsequent phases to close the gap
|
||||
- Only works on future (unstarted) phases
|
||||
- Git commit preserves historical record
|
||||
|
||||
Usage: `/gsd:remove-phase 17`
|
||||
Result: Phase 17 deleted, phases 18-20 become 17-19
|
||||
|
||||
### Milestone Management
|
||||
|
||||
**`/gsd:new-milestone <name>`**
|
||||
Start a new milestone through unified flow.
|
||||
|
||||
- Deep questioning to understand what you're building next
|
||||
- Optional domain research (spawns 4 parallel researcher agents)
|
||||
- Requirements definition with scoping
|
||||
- Roadmap creation with phase breakdown
|
||||
|
||||
Mirrors `/gsd:new-project` flow for brownfield projects (existing PROJECT.md).
|
||||
|
||||
Usage: `/gsd:new-milestone "v2.0 Features"`
|
||||
|
||||
**`/gsd:complete-milestone <version>`**
|
||||
Archive completed milestone and prepare for next version.
|
||||
|
||||
- Creates MILESTONES.md entry with stats
|
||||
- Archives full details to milestones/ directory
|
||||
- Creates git tag for the release
|
||||
- Prepares workspace for next version
|
||||
|
||||
Usage: `/gsd:complete-milestone 1.0.0`
|
||||
|
||||
### Progress Tracking
|
||||
|
||||
**`/gsd:progress`**
|
||||
Check project status and intelligently route to next action.
|
||||
|
||||
- Shows visual progress bar and completion percentage
|
||||
- Summarizes recent work from SUMMARY files
|
||||
- Displays current position and what's next
|
||||
- Lists key decisions and open issues
|
||||
- Offers to execute next plan or create it if missing
|
||||
- Detects 100% milestone completion
|
||||
|
||||
Usage: `/gsd:progress`
|
||||
|
||||
### Session Management
|
||||
|
||||
**`/gsd:resume-work`**
|
||||
Resume work from previous session with full context restoration.
|
||||
|
||||
- Reads STATE.md for project context
|
||||
- Shows current position and recent progress
|
||||
- Offers next actions based on project state
|
||||
|
||||
Usage: `/gsd:resume-work`
|
||||
|
||||
**`/gsd:pause-work`**
|
||||
Create context handoff when pausing work mid-phase.
|
||||
|
||||
- Creates .continue-here file with current state
|
||||
- Updates STATE.md session continuity section
|
||||
- Captures in-progress work context
|
||||
|
||||
Usage: `/gsd:pause-work`
|
||||
|
||||
### Debugging
|
||||
|
||||
**`/gsd:debug [issue description]`**
|
||||
Systematic debugging with persistent state across context resets.
|
||||
|
||||
- Gathers symptoms through adaptive questioning
|
||||
- Creates `.planning/debug/[slug].md` to track investigation
|
||||
- Investigates using scientific method (evidence → hypothesis → test)
|
||||
- Survives `/clear` — run `/gsd:debug` with no args to resume
|
||||
- Archives resolved issues to `.planning/debug/resolved/`
|
||||
|
||||
Usage: `/gsd:debug "login button doesn't work"`
|
||||
Usage: `/gsd:debug` (resume active session)
|
||||
|
||||
### Quick Notes
|
||||
|
||||
**`/gsd:note <text>`**
|
||||
Zero-friction idea capture — one command, instant save, no questions.
|
||||
|
||||
- Saves timestamped note to `.planning/notes/` (or `C:/Users/yaoji/.claude/notes/` globally)
|
||||
- Three subcommands: append (default), list, promote
|
||||
- Promote converts a note into a structured todo
|
||||
- Works without a project (falls back to global scope)
|
||||
|
||||
Usage: `/gsd:note refactor the hook system`
|
||||
Usage: `/gsd:note list`
|
||||
Usage: `/gsd:note promote 3`
|
||||
Usage: `/gsd:note --global cross-project idea`
|
||||
|
||||
### Todo Management
|
||||
|
||||
**`/gsd:add-todo [description]`**
|
||||
Capture idea or task as todo from current conversation.
|
||||
|
||||
- Extracts context from conversation (or uses provided description)
|
||||
- Creates structured todo file in `.planning/todos/pending/`
|
||||
- Infers area from file paths for grouping
|
||||
- Checks for duplicates before creating
|
||||
- Updates STATE.md todo count
|
||||
|
||||
Usage: `/gsd:add-todo` (infers from conversation)
|
||||
Usage: `/gsd:add-todo Add auth token refresh`
|
||||
|
||||
**`/gsd:check-todos [area]`**
|
||||
List pending todos and select one to work on.
|
||||
|
||||
- Lists all pending todos with title, area, age
|
||||
- Optional area filter (e.g., `/gsd:check-todos api`)
|
||||
- Loads full context for selected todo
|
||||
- Routes to appropriate action (work now, add to phase, brainstorm)
|
||||
- Moves todo to done/ when work begins
|
||||
|
||||
Usage: `/gsd:check-todos`
|
||||
Usage: `/gsd:check-todos api`
|
||||
|
||||
### User Acceptance Testing
|
||||
|
||||
**`/gsd:verify-work [phase]`**
|
||||
Validate built features through conversational UAT.
|
||||
|
||||
- Extracts testable deliverables from SUMMARY.md files
|
||||
- Presents tests one at a time (yes/no responses)
|
||||
- Automatically diagnoses failures and creates fix plans
|
||||
- Ready for re-execution if issues found
|
||||
|
||||
Usage: `/gsd:verify-work 3`
|
||||
|
||||
### Ship Work
|
||||
|
||||
**`/gsd:ship [phase]`**
|
||||
Create a PR from completed phase work with an auto-generated body.
|
||||
|
||||
- Pushes branch to remote
|
||||
- Creates PR with summary from SUMMARY.md, VERIFICATION.md, REQUIREMENTS.md
|
||||
- Optionally requests code review
|
||||
- Updates STATE.md with shipping status
|
||||
|
||||
Prerequisites: Phase verified, `gh` CLI installed and authenticated.
|
||||
|
||||
Usage: `/gsd:ship 4` or `/gsd:ship 4 --draft`
|
||||
|
||||
### Milestone Auditing
|
||||
|
||||
**`/gsd:audit-milestone [version]`**
|
||||
Audit milestone completion against original intent.
|
||||
|
||||
- Reads all phase VERIFICATION.md files
|
||||
- Checks requirements coverage
|
||||
- Spawns integration checker for cross-phase wiring
|
||||
- Creates MILESTONE-AUDIT.md with gaps and tech debt
|
||||
|
||||
Usage: `/gsd:audit-milestone`
|
||||
|
||||
**`/gsd:plan-milestone-gaps`**
|
||||
Create phases to close gaps identified by audit.
|
||||
|
||||
- Reads MILESTONE-AUDIT.md and groups gaps into phases
|
||||
- Prioritizes by requirement priority (must/should/nice)
|
||||
- Adds gap closure phases to ROADMAP.md
|
||||
- Ready for `/gsd:plan-phase` on new phases
|
||||
|
||||
Usage: `/gsd:plan-milestone-gaps`
|
||||
|
||||
### Configuration
|
||||
|
||||
**`/gsd:settings`**
|
||||
Configure workflow toggles and model profile interactively.
|
||||
|
||||
- Toggle researcher, plan checker, verifier agents
|
||||
- Select model profile (quality/balanced/budget/inherit)
|
||||
- Updates `.planning/config.json`
|
||||
|
||||
Usage: `/gsd:settings`
|
||||
|
||||
**`/gsd:set-profile <profile>`**
|
||||
Quick switch model profile for GSD agents.
|
||||
|
||||
- `quality` — Opus everywhere except verification
|
||||
- `balanced` — Opus for planning, Sonnet for execution (default)
|
||||
- `budget` — Sonnet for writing, Haiku for research/verification
|
||||
- `inherit` — Use current session model for all agents (OpenCode `/model`)
|
||||
|
||||
Usage: `/gsd:set-profile budget`
|
||||
|
||||
### Utility Commands
|
||||
|
||||
**`/gsd:cleanup`**
|
||||
Archive accumulated phase directories from completed milestones.
|
||||
|
||||
- Identifies phases from completed milestones still in `.planning/phases/`
|
||||
- Shows dry-run summary before moving anything
|
||||
- Moves phase dirs to `.planning/milestones/v{X.Y}-phases/`
|
||||
- Use after multiple milestones to reduce `.planning/phases/` clutter
|
||||
|
||||
Usage: `/gsd:cleanup`
|
||||
|
||||
**`/gsd:help`**
|
||||
Show this command reference.
|
||||
|
||||
**`/gsd:update`**
|
||||
Update GSD to latest version with changelog preview.
|
||||
|
||||
- Shows installed vs latest version comparison
|
||||
- Displays changelog entries for versions you've missed
|
||||
- Highlights breaking changes
|
||||
- Confirms before running install
|
||||
- Better than raw `npx get-shit-done-cc`
|
||||
|
||||
Usage: `/gsd:update`
|
||||
|
||||
**`/gsd:join-discord`**
|
||||
Join the GSD Discord community.
|
||||
|
||||
- Get help, share what you're building, stay updated
|
||||
- Connect with other GSD users
|
||||
|
||||
Usage: `/gsd:join-discord`
|
||||
|
||||
## Files & Structure
|
||||
|
||||
```
|
||||
.planning/
|
||||
├── PROJECT.md # Project vision
|
||||
├── ROADMAP.md # Current phase breakdown
|
||||
├── STATE.md # Project memory & context
|
||||
├── RETROSPECTIVE.md # Living retrospective (updated per milestone)
|
||||
├── config.json # Workflow mode & gates
|
||||
├── todos/ # Captured ideas and tasks
|
||||
│ ├── pending/ # Todos waiting to be worked on
|
||||
│ └── done/ # Completed todos
|
||||
├── debug/ # Active debug sessions
|
||||
│ └── resolved/ # Archived resolved issues
|
||||
├── milestones/
|
||||
│ ├── v1.0-ROADMAP.md # Archived roadmap snapshot
|
||||
│ ├── v1.0-REQUIREMENTS.md # Archived requirements
|
||||
│ └── v1.0-phases/ # Archived phase dirs (via /gsd:cleanup or --archive-phases)
|
||||
│ ├── 01-foundation/
|
||||
│ └── 02-core-features/
|
||||
├── codebase/ # Codebase map (brownfield projects)
|
||||
│ ├── STACK.md # Languages, frameworks, dependencies
|
||||
│ ├── ARCHITECTURE.md # Patterns, layers, data flow
|
||||
│ ├── STRUCTURE.md # Directory layout, key files
|
||||
│ ├── CONVENTIONS.md # Coding standards, naming
|
||||
│ ├── TESTING.md # Test setup, patterns
|
||||
│ ├── INTEGRATIONS.md # External services, APIs
|
||||
│ └── CONCERNS.md # Tech debt, known issues
|
||||
└── phases/
|
||||
├── 01-foundation/
|
||||
│ ├── 01-01-PLAN.md
|
||||
│ └── 01-01-SUMMARY.md
|
||||
└── 02-core-features/
|
||||
├── 02-01-PLAN.md
|
||||
└── 02-01-SUMMARY.md
|
||||
```
|
||||
|
||||
## Workflow Modes
|
||||
|
||||
Set during `/gsd:new-project`:
|
||||
|
||||
**Interactive Mode**
|
||||
|
||||
- Confirms each major decision
|
||||
- Pauses at checkpoints for approval
|
||||
- More guidance throughout
|
||||
|
||||
**YOLO Mode**
|
||||
|
||||
- Auto-approves most decisions
|
||||
- Executes plans without confirmation
|
||||
- Only stops for critical checkpoints
|
||||
|
||||
Change anytime by editing `.planning/config.json`
|
||||
|
||||
## Planning Configuration
|
||||
|
||||
Configure how planning artifacts are managed in `.planning/config.json`:
|
||||
|
||||
**`planning.commit_docs`** (default: `true`)
|
||||
- `true`: Planning artifacts committed to git (standard workflow)
|
||||
- `false`: Planning artifacts kept local-only, not committed
|
||||
|
||||
When `commit_docs: false`:
|
||||
- Add `.planning/` to your `.gitignore`
|
||||
- Useful for OSS contributions, client projects, or keeping planning private
|
||||
- All planning files still work normally, just not tracked in git
|
||||
|
||||
**`planning.search_gitignored`** (default: `false`)
|
||||
- `true`: Add `--no-ignore` to broad ripgrep searches
|
||||
- Only needed when `.planning/` is gitignored and you want project-wide searches to include it
|
||||
|
||||
Example config:
|
||||
```json
|
||||
{
|
||||
"planning": {
|
||||
"commit_docs": false,
|
||||
"search_gitignored": true
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
## Common Workflows
|
||||
|
||||
**Starting a new project:**
|
||||
|
||||
```
|
||||
/gsd:new-project # Unified flow: questioning → research → requirements → roadmap
|
||||
/clear
|
||||
/gsd:plan-phase 1 # Create plans for first phase
|
||||
/clear
|
||||
/gsd:execute-phase 1 # Execute all plans in phase
|
||||
```
|
||||
|
||||
**Resuming work after a break:**
|
||||
|
||||
```
|
||||
/gsd:progress # See where you left off and continue
|
||||
```
|
||||
|
||||
**Adding urgent mid-milestone work:**
|
||||
|
||||
```
|
||||
/gsd:insert-phase 5 "Critical security fix"
|
||||
/gsd:plan-phase 5.1
|
||||
/gsd:execute-phase 5.1
|
||||
```
|
||||
|
||||
**Completing a milestone:**
|
||||
|
||||
```
|
||||
/gsd:complete-milestone 1.0.0
|
||||
/clear
|
||||
/gsd:new-milestone # Start next milestone (questioning → research → requirements → roadmap)
|
||||
```
|
||||
|
||||
**Capturing ideas during work:**
|
||||
|
||||
```
|
||||
/gsd:add-todo # Capture from conversation context
|
||||
/gsd:add-todo Fix modal z-index # Capture with explicit description
|
||||
/gsd:check-todos # Review and work on todos
|
||||
/gsd:check-todos api # Filter by area
|
||||
```
|
||||
|
||||
**Debugging an issue:**
|
||||
|
||||
```
|
||||
/gsd:debug "form submission fails silently" # Start debug session
|
||||
# ... investigation happens, context fills up ...
|
||||
/clear
|
||||
/gsd:debug # Resume from where you left off
|
||||
```
|
||||
|
||||
## Getting Help
|
||||
|
||||
- Read `.planning/PROJECT.md` for project vision
|
||||
- Read `.planning/STATE.md` for current context
|
||||
- Check `.planning/ROADMAP.md` for phase status
|
||||
- Run `/gsd:progress` to check where you're up to
|
||||
</reference>
|
||||
130
get-shit-done/workflows/insert-phase.md
Normal file
130
get-shit-done/workflows/insert-phase.md
Normal file
@@ -0,0 +1,130 @@
|
||||
<purpose>
|
||||
Insert a decimal phase for urgent work discovered mid-milestone between existing integer phases. Uses decimal numbering (72.1, 72.2, etc.) to preserve the logical sequence of planned phases while accommodating urgent insertions without renumbering the entire roadmap.
|
||||
</purpose>
|
||||
|
||||
<required_reading>
|
||||
Read all files referenced by the invoking prompt's execution_context before starting.
|
||||
</required_reading>
|
||||
|
||||
<process>
|
||||
|
||||
<step name="parse_arguments">
|
||||
Parse the command arguments:
|
||||
- First argument: integer phase number to insert after
|
||||
- Remaining arguments: phase description
|
||||
|
||||
Example: `/gsd:insert-phase 72 Fix critical auth bug`
|
||||
-> after = 72
|
||||
-> description = "Fix critical auth bug"
|
||||
|
||||
If arguments missing:
|
||||
|
||||
```
|
||||
ERROR: Both phase number and description required
|
||||
Usage: /gsd:insert-phase <after> <description>
|
||||
Example: /gsd:insert-phase 72 Fix critical auth bug
|
||||
```
|
||||
|
||||
Exit.
|
||||
|
||||
Validate first argument is an integer.
|
||||
</step>
|
||||
|
||||
<step name="init_context">
|
||||
Load phase operation context:
|
||||
|
||||
```bash
|
||||
INIT=$(node "C:/Users/yaoji/.claude/get-shit-done/bin/gsd-tools.cjs" init phase-op "${after_phase}")
|
||||
if [[ "$INIT" == @file:* ]]; then INIT=$(cat "${INIT#@file:}"); fi
|
||||
```
|
||||
|
||||
Check `roadmap_exists` from init JSON. If false:
|
||||
```
|
||||
ERROR: No roadmap found (.planning/ROADMAP.md)
|
||||
```
|
||||
Exit.
|
||||
</step>
|
||||
|
||||
<step name="insert_phase">
|
||||
**Delegate the phase insertion to gsd-tools:**
|
||||
|
||||
```bash
|
||||
RESULT=$(node "C:/Users/yaoji/.claude/get-shit-done/bin/gsd-tools.cjs" phase insert "${after_phase}" "${description}")
|
||||
```
|
||||
|
||||
The CLI handles:
|
||||
- Verifying target phase exists in ROADMAP.md
|
||||
- Calculating next decimal phase number (checking existing decimals on disk)
|
||||
- Generating slug from description
|
||||
- Creating the phase directory (`.planning/phases/{N.M}-{slug}/`)
|
||||
- Inserting the phase entry into ROADMAP.md after the target phase with (INSERTED) marker
|
||||
|
||||
Extract from result: `phase_number`, `after_phase`, `name`, `slug`, `directory`.
|
||||
</step>
|
||||
|
||||
<step name="update_project_state">
|
||||
Update STATE.md to reflect the inserted phase:
|
||||
|
||||
1. Read `.planning/STATE.md`
|
||||
2. Under "## Accumulated Context" → "### Roadmap Evolution" add entry:
|
||||
```
|
||||
- Phase {decimal_phase} inserted after Phase {after_phase}: {description} (URGENT)
|
||||
```
|
||||
|
||||
If "Roadmap Evolution" section doesn't exist, create it.
|
||||
</step>
|
||||
|
||||
<step name="completion">
|
||||
Present completion summary:
|
||||
|
||||
```
|
||||
Phase {decimal_phase} inserted after Phase {after_phase}:
|
||||
- Description: {description}
|
||||
- Directory: .planning/phases/{decimal-phase}-{slug}/
|
||||
- Status: Not planned yet
|
||||
- Marker: (INSERTED) - indicates urgent work
|
||||
|
||||
Roadmap updated: .planning/ROADMAP.md
|
||||
Project state updated: .planning/STATE.md
|
||||
|
||||
---
|
||||
|
||||
## Next Up
|
||||
|
||||
**Phase {decimal_phase}: {description}** -- urgent insertion
|
||||
|
||||
`/gsd:plan-phase {decimal_phase}`
|
||||
|
||||
<sub>`/clear` first -> fresh context window</sub>
|
||||
|
||||
---
|
||||
|
||||
**Also available:**
|
||||
- Review insertion impact: Check if Phase {next_integer} dependencies still make sense
|
||||
- Review roadmap
|
||||
|
||||
---
|
||||
```
|
||||
</step>
|
||||
|
||||
</process>
|
||||
|
||||
<anti_patterns>
|
||||
|
||||
- Don't use this for planned work at end of milestone (use /gsd:add-phase)
|
||||
- Don't insert before Phase 1 (decimal 0.1 makes no sense)
|
||||
- Don't renumber existing phases
|
||||
- Don't modify the target phase content
|
||||
- Don't create plans yet (that's /gsd:plan-phase)
|
||||
- Don't commit changes (user decides when to commit)
|
||||
</anti_patterns>
|
||||
|
||||
<success_criteria>
|
||||
Phase insertion is complete when:
|
||||
|
||||
- [ ] `gsd-tools phase insert` executed successfully
|
||||
- [ ] Phase directory created
|
||||
- [ ] Roadmap updated with new phase entry (includes "(INSERTED)" marker)
|
||||
- [ ] STATE.md updated with roadmap evolution note
|
||||
- [ ] User informed of next steps and dependency implications
|
||||
</success_criteria>
|
||||
178
get-shit-done/workflows/list-phase-assumptions.md
Normal file
178
get-shit-done/workflows/list-phase-assumptions.md
Normal file
@@ -0,0 +1,178 @@
|
||||
<purpose>
|
||||
Surface Claude's assumptions about a phase before planning, enabling users to correct misconceptions early.
|
||||
|
||||
Key difference from discuss-phase: This is ANALYSIS of what Claude thinks, not INTAKE of what user knows. No file output - purely conversational to prompt discussion.
|
||||
</purpose>
|
||||
|
||||
<process>
|
||||
|
||||
<step name="validate_phase" priority="first">
|
||||
Phase number: $ARGUMENTS (required)
|
||||
|
||||
**If argument missing:**
|
||||
|
||||
```
|
||||
Error: Phase number required.
|
||||
|
||||
Usage: /gsd:list-phase-assumptions [phase-number]
|
||||
Example: /gsd:list-phase-assumptions 3
|
||||
```
|
||||
|
||||
Exit workflow.
|
||||
|
||||
**If argument provided:**
|
||||
Validate phase exists in roadmap:
|
||||
|
||||
```bash
|
||||
cat .planning/ROADMAP.md | grep -i "Phase ${PHASE}"
|
||||
```
|
||||
|
||||
**If phase not found:**
|
||||
|
||||
```
|
||||
Error: Phase ${PHASE} not found in roadmap.
|
||||
|
||||
Available phases:
|
||||
[list phases from roadmap]
|
||||
```
|
||||
|
||||
Exit workflow.
|
||||
|
||||
**If phase found:**
|
||||
Parse phase details from roadmap:
|
||||
|
||||
- Phase number
|
||||
- Phase name
|
||||
- Phase description/goal
|
||||
- Any scope details mentioned
|
||||
|
||||
Continue to analyze_phase.
|
||||
</step>
|
||||
|
||||
<step name="analyze_phase">
|
||||
Based on roadmap description and project context, identify assumptions across five areas:
|
||||
|
||||
**1. Technical Approach:**
|
||||
What libraries, frameworks, patterns, or tools would Claude use?
|
||||
- "I'd use X library because..."
|
||||
- "I'd follow Y pattern because..."
|
||||
- "I'd structure this as Z because..."
|
||||
|
||||
**2. Implementation Order:**
|
||||
What would Claude build first, second, third?
|
||||
- "I'd start with X because it's foundational"
|
||||
- "Then Y because it depends on X"
|
||||
- "Finally Z because..."
|
||||
|
||||
**3. Scope Boundaries:**
|
||||
What's included vs excluded in Claude's interpretation?
|
||||
- "This phase includes: A, B, C"
|
||||
- "This phase does NOT include: D, E, F"
|
||||
- "Boundary ambiguities: G could go either way"
|
||||
|
||||
**4. Risk Areas:**
|
||||
Where does Claude expect complexity or challenges?
|
||||
- "The tricky part is X because..."
|
||||
- "Potential issues: Y, Z"
|
||||
- "I'd watch out for..."
|
||||
|
||||
**5. Dependencies:**
|
||||
What does Claude assume exists or needs to be in place?
|
||||
- "This assumes X from previous phases"
|
||||
- "External dependencies: Y, Z"
|
||||
- "This will be consumed by..."
|
||||
|
||||
Be honest about uncertainty. Mark assumptions with confidence levels:
|
||||
- "Fairly confident: ..." (clear from roadmap)
|
||||
- "Assuming: ..." (reasonable inference)
|
||||
- "Unclear: ..." (could go multiple ways)
|
||||
</step>
|
||||
|
||||
<step name="present_assumptions">
|
||||
Present assumptions in a clear, scannable format:
|
||||
|
||||
```
|
||||
## My Assumptions for Phase ${PHASE}: ${PHASE_NAME}
|
||||
|
||||
### Technical Approach
|
||||
[List assumptions about how to implement]
|
||||
|
||||
### Implementation Order
|
||||
[List assumptions about sequencing]
|
||||
|
||||
### Scope Boundaries
|
||||
**In scope:** [what's included]
|
||||
**Out of scope:** [what's excluded]
|
||||
**Ambiguous:** [what could go either way]
|
||||
|
||||
### Risk Areas
|
||||
[List anticipated challenges]
|
||||
|
||||
### Dependencies
|
||||
**From prior phases:** [what's needed]
|
||||
**External:** [third-party needs]
|
||||
**Feeds into:** [what future phases need from this]
|
||||
|
||||
---
|
||||
|
||||
**What do you think?**
|
||||
|
||||
Are these assumptions accurate? Let me know:
|
||||
- What I got right
|
||||
- What I got wrong
|
||||
- What I'm missing
|
||||
```
|
||||
|
||||
Wait for user response.
|
||||
</step>
|
||||
|
||||
<step name="gather_feedback">
|
||||
**If user provides corrections:**
|
||||
|
||||
Acknowledge the corrections:
|
||||
|
||||
```
|
||||
Key corrections:
|
||||
- [correction 1]
|
||||
- [correction 2]
|
||||
|
||||
This changes my understanding significantly. [Summarize new understanding]
|
||||
```
|
||||
|
||||
**If user confirms assumptions:**
|
||||
|
||||
```
|
||||
Assumptions validated.
|
||||
```
|
||||
|
||||
Continue to offer_next.
|
||||
</step>
|
||||
|
||||
<step name="offer_next">
|
||||
Present next steps:
|
||||
|
||||
```
|
||||
What's next?
|
||||
1. Discuss context (/gsd:discuss-phase ${PHASE}) - Let me ask you questions to build comprehensive context
|
||||
2. Plan this phase (/gsd:plan-phase ${PHASE}) - Create detailed execution plans
|
||||
3. Re-examine assumptions - I'll analyze again with your corrections
|
||||
4. Done for now
|
||||
```
|
||||
|
||||
Wait for user selection.
|
||||
|
||||
If "Discuss context": Note that CONTEXT.md will incorporate any corrections discussed here
|
||||
If "Plan this phase": Proceed knowing assumptions are understood
|
||||
If "Re-examine": Return to analyze_phase with updated understanding
|
||||
</step>
|
||||
|
||||
</process>
|
||||
|
||||
<success_criteria>
|
||||
- Phase number validated against roadmap
|
||||
- Assumptions surfaced across five areas: technical approach, implementation order, scope, risks, dependencies
|
||||
- Confidence levels marked where appropriate
|
||||
- "What do you think?" prompt presented
|
||||
- User feedback acknowledged
|
||||
- Clear next steps offered
|
||||
</success_criteria>
|
||||
360
get-shit-done/workflows/map-codebase.md
Normal file
360
get-shit-done/workflows/map-codebase.md
Normal file
@@ -0,0 +1,360 @@
|
||||
<purpose>
|
||||
Orchestrate parallel codebase mapper agents to analyze codebase and produce structured documents in .planning/codebase/
|
||||
|
||||
Each agent has fresh context, explores a specific focus area, and **writes documents directly**. The orchestrator only receives confirmation + line counts, then writes a summary.
|
||||
|
||||
Output: .planning/codebase/ folder with 7 structured documents about the codebase state.
|
||||
</purpose>
|
||||
|
||||
<philosophy>
|
||||
**Why dedicated mapper agents:**
|
||||
- Fresh context per domain (no token contamination)
|
||||
- Agents write documents directly (no context transfer back to orchestrator)
|
||||
- Orchestrator only summarizes what was created (minimal context usage)
|
||||
- Faster execution (agents run simultaneously)
|
||||
|
||||
**Document quality over length:**
|
||||
Include enough detail to be useful as reference. Prioritize practical examples (especially code patterns) over arbitrary brevity.
|
||||
|
||||
**Always include file paths:**
|
||||
Documents are reference material for Claude when planning/executing. Always include actual file paths formatted with backticks: `src/services/user.ts`.
|
||||
</philosophy>
|
||||
|
||||
<process>
|
||||
|
||||
<step name="init_context" priority="first">
|
||||
Load codebase mapping context:
|
||||
|
||||
```bash
|
||||
INIT=$(node "C:/Users/yaoji/.claude/get-shit-done/bin/gsd-tools.cjs" init map-codebase)
|
||||
if [[ "$INIT" == @file:* ]]; then INIT=$(cat "${INIT#@file:}"); fi
|
||||
```
|
||||
|
||||
Extract from init JSON: `mapper_model`, `commit_docs`, `codebase_dir`, `existing_maps`, `has_maps`, `codebase_dir_exists`.
|
||||
</step>
|
||||
|
||||
<step name="check_existing">
|
||||
Check if .planning/codebase/ already exists using `has_maps` from init context.
|
||||
|
||||
If `codebase_dir_exists` is true:
|
||||
```bash
|
||||
ls -la .planning/codebase/
|
||||
```
|
||||
|
||||
**If exists:**
|
||||
|
||||
```
|
||||
.planning/codebase/ already exists with these documents:
|
||||
[List files found]
|
||||
|
||||
What's next?
|
||||
1. Refresh - Delete existing and remap codebase
|
||||
2. Update - Keep existing, only update specific documents
|
||||
3. Skip - Use existing codebase map as-is
|
||||
```
|
||||
|
||||
Wait for user response.
|
||||
|
||||
If "Refresh": Delete .planning/codebase/, continue to create_structure
|
||||
If "Update": Ask which documents to update, continue to spawn_agents (filtered)
|
||||
If "Skip": Exit workflow
|
||||
|
||||
**If doesn't exist:**
|
||||
Continue to create_structure.
|
||||
</step>
|
||||
|
||||
<step name="create_structure">
|
||||
Create .planning/codebase/ directory:
|
||||
|
||||
```bash
|
||||
mkdir -p .planning/codebase
|
||||
```
|
||||
|
||||
**Expected output files:**
|
||||
- STACK.md (from tech mapper)
|
||||
- INTEGRATIONS.md (from tech mapper)
|
||||
- ARCHITECTURE.md (from arch mapper)
|
||||
- STRUCTURE.md (from arch mapper)
|
||||
- CONVENTIONS.md (from quality mapper)
|
||||
- TESTING.md (from quality mapper)
|
||||
- CONCERNS.md (from concerns mapper)
|
||||
|
||||
Continue to spawn_agents.
|
||||
</step>
|
||||
|
||||
<step name="detect_runtime_capabilities">
|
||||
Before spawning agents, detect whether the current runtime supports the `Task` tool for subagent delegation.
|
||||
|
||||
**Runtimes with Task tool:** Claude Code, Cursor (native subagent support)
|
||||
**Runtimes WITHOUT Task tool:** Antigravity, Gemini CLI, OpenCode, Codex, and others
|
||||
|
||||
**How to detect:** Check if you have access to a `Task` tool. If you do NOT have a `Task` tool (or only have tools like `browser_subagent` which is for web browsing, NOT code analysis):
|
||||
|
||||
→ **Skip `spawn_agents` and `collect_confirmations`** — go directly to `sequential_mapping` instead.
|
||||
|
||||
**CRITICAL:** Never use `browser_subagent` or `Explore` as a substitute for `Task`. The `browser_subagent` tool is exclusively for web page interaction and will fail for codebase analysis. If `Task` is unavailable, perform the mapping sequentially in-context.
|
||||
</step>
|
||||
|
||||
<step name="spawn_agents" condition="Task tool is available">
|
||||
Spawn 4 parallel gsd-codebase-mapper agents.
|
||||
|
||||
Use Task tool with `subagent_type="gsd-codebase-mapper"`, `model="{mapper_model}"`, and `run_in_background=true` for parallel execution.
|
||||
|
||||
**CRITICAL:** Use the dedicated `gsd-codebase-mapper` agent, NOT `Explore` or `browser_subagent`. The mapper agent writes documents directly.
|
||||
|
||||
**Agent 1: Tech Focus**
|
||||
|
||||
```
|
||||
Task(
|
||||
subagent_type="gsd-codebase-mapper",
|
||||
model="{mapper_model}",
|
||||
run_in_background=true,
|
||||
description="Map codebase tech stack",
|
||||
prompt="Focus: tech
|
||||
|
||||
Analyze this codebase for technology stack and external integrations.
|
||||
|
||||
Write these documents to .planning/codebase/:
|
||||
- STACK.md - Languages, runtime, frameworks, dependencies, configuration
|
||||
- INTEGRATIONS.md - External APIs, databases, auth providers, webhooks
|
||||
|
||||
Explore thoroughly. Write documents directly using templates. Return confirmation only."
|
||||
)
|
||||
```
|
||||
|
||||
**Agent 2: Architecture Focus**
|
||||
|
||||
```
|
||||
Task(
|
||||
subagent_type="gsd-codebase-mapper",
|
||||
model="{mapper_model}",
|
||||
run_in_background=true,
|
||||
description="Map codebase architecture",
|
||||
prompt="Focus: arch
|
||||
|
||||
Analyze this codebase architecture and directory structure.
|
||||
|
||||
Write these documents to .planning/codebase/:
|
||||
- ARCHITECTURE.md - Pattern, layers, data flow, abstractions, entry points
|
||||
- STRUCTURE.md - Directory layout, key locations, naming conventions
|
||||
|
||||
Explore thoroughly. Write documents directly using templates. Return confirmation only."
|
||||
)
|
||||
```
|
||||
|
||||
**Agent 3: Quality Focus**
|
||||
|
||||
```
|
||||
Task(
|
||||
subagent_type="gsd-codebase-mapper",
|
||||
model="{mapper_model}",
|
||||
run_in_background=true,
|
||||
description="Map codebase conventions",
|
||||
prompt="Focus: quality
|
||||
|
||||
Analyze this codebase for coding conventions and testing patterns.
|
||||
|
||||
Write these documents to .planning/codebase/:
|
||||
- CONVENTIONS.md - Code style, naming, patterns, error handling
|
||||
- TESTING.md - Framework, structure, mocking, coverage
|
||||
|
||||
Explore thoroughly. Write documents directly using templates. Return confirmation only."
|
||||
)
|
||||
```
|
||||
|
||||
**Agent 4: Concerns Focus**
|
||||
|
||||
```
|
||||
Task(
|
||||
subagent_type="gsd-codebase-mapper",
|
||||
model="{mapper_model}",
|
||||
run_in_background=true,
|
||||
description="Map codebase concerns",
|
||||
prompt="Focus: concerns
|
||||
|
||||
Analyze this codebase for technical debt, known issues, and areas of concern.
|
||||
|
||||
Write this document to .planning/codebase/:
|
||||
- CONCERNS.md - Tech debt, bugs, security, performance, fragile areas
|
||||
|
||||
Explore thoroughly. Write document directly using template. Return confirmation only."
|
||||
)
|
||||
```
|
||||
|
||||
Continue to collect_confirmations.
|
||||
</step>
|
||||
|
||||
<step name="collect_confirmations">
|
||||
Wait for all 4 agents to complete.
|
||||
|
||||
Read each agent's output file to collect confirmations.
|
||||
|
||||
**Expected confirmation format from each agent:**
|
||||
```
|
||||
## Mapping Complete
|
||||
|
||||
**Focus:** {focus}
|
||||
**Documents written:**
|
||||
- `.planning/codebase/{DOC1}.md` ({N} lines)
|
||||
- `.planning/codebase/{DOC2}.md` ({N} lines)
|
||||
|
||||
Ready for orchestrator summary.
|
||||
```
|
||||
|
||||
**What you receive:** Just file paths and line counts. NOT document contents.
|
||||
|
||||
If any agent failed, note the failure and continue with successful documents.
|
||||
|
||||
Continue to verify_output.
|
||||
</step>
|
||||
|
||||
<step name="sequential_mapping" condition="Task tool is NOT available (e.g. Antigravity, Gemini CLI, Codex)">
|
||||
When the `Task` tool is unavailable, perform codebase mapping sequentially in the current context. This replaces `spawn_agents` and `collect_confirmations`.
|
||||
|
||||
**IMPORTANT:** Do NOT use `browser_subagent`, `Explore`, or any browser-based tool. Use only file system tools (Read, Bash, Write, Grep, Glob, list_dir, view_file, grep_search, or equivalent tools available in your runtime).
|
||||
|
||||
Perform all 4 mapping passes sequentially:
|
||||
|
||||
**Pass 1: Tech Focus**
|
||||
- Explore package.json/Cargo.toml/go.mod/requirements.txt, config files, dependency trees
|
||||
- Write `.planning/codebase/STACK.md` — Languages, runtime, frameworks, dependencies, configuration
|
||||
- Write `.planning/codebase/INTEGRATIONS.md` — External APIs, databases, auth providers, webhooks
|
||||
|
||||
**Pass 2: Architecture Focus**
|
||||
- Explore directory structure, entry points, module boundaries, data flow
|
||||
- Write `.planning/codebase/ARCHITECTURE.md` — Pattern, layers, data flow, abstractions, entry points
|
||||
- Write `.planning/codebase/STRUCTURE.md` — Directory layout, key locations, naming conventions
|
||||
|
||||
**Pass 3: Quality Focus**
|
||||
- Explore code style, error handling patterns, test files, CI config
|
||||
- Write `.planning/codebase/CONVENTIONS.md` — Code style, naming, patterns, error handling
|
||||
- Write `.planning/codebase/TESTING.md` — Framework, structure, mocking, coverage
|
||||
|
||||
**Pass 4: Concerns Focus**
|
||||
- Explore TODOs, known issues, fragile areas, security patterns
|
||||
- Write `.planning/codebase/CONCERNS.md` — Tech debt, bugs, security, performance, fragile areas
|
||||
|
||||
Use the same document templates as the `gsd-codebase-mapper` agent. Include actual file paths formatted with backticks.
|
||||
|
||||
Continue to verify_output.
|
||||
</step>
|
||||
|
||||
<step name="verify_output">
|
||||
Verify all documents created successfully:
|
||||
|
||||
```bash
|
||||
ls -la .planning/codebase/
|
||||
wc -l .planning/codebase/*.md
|
||||
```
|
||||
|
||||
**Verification checklist:**
|
||||
- All 7 documents exist
|
||||
- No empty documents (each should have >20 lines)
|
||||
|
||||
If any documents missing or empty, note which agents may have failed.
|
||||
|
||||
Continue to scan_for_secrets.
|
||||
</step>
|
||||
|
||||
<step name="scan_for_secrets">
|
||||
**CRITICAL SECURITY CHECK:** Scan output files for accidentally leaked secrets before committing.
|
||||
|
||||
Run secret pattern detection:
|
||||
|
||||
```bash
|
||||
# Check for common API key patterns in generated docs
|
||||
grep -E '(sk-[a-zA-Z0-9]{20,}|sk_live_[a-zA-Z0-9]+|sk_test_[a-zA-Z0-9]+|ghp_[a-zA-Z0-9]{36}|gho_[a-zA-Z0-9]{36}|glpat-[a-zA-Z0-9_-]+|AKIA[A-Z0-9]{16}|xox[baprs]-[a-zA-Z0-9-]+|-----BEGIN.*PRIVATE KEY|eyJ[a-zA-Z0-9_-]+\.eyJ[a-zA-Z0-9_-]+\.)' .planning/codebase/*.md 2>/dev/null && SECRETS_FOUND=true || SECRETS_FOUND=false
|
||||
```
|
||||
|
||||
**If SECRETS_FOUND=true:**
|
||||
|
||||
```
|
||||
⚠️ SECURITY ALERT: Potential secrets detected in codebase documents!
|
||||
|
||||
Found patterns that look like API keys or tokens in:
|
||||
[show grep output]
|
||||
|
||||
This would expose credentials if committed.
|
||||
|
||||
**Action required:**
|
||||
1. Review the flagged content above
|
||||
2. If these are real secrets, they must be removed before committing
|
||||
3. Consider adding sensitive files to Claude Code "Deny" permissions
|
||||
|
||||
Pausing before commit. Reply "safe to proceed" if the flagged content is not actually sensitive, or edit the files first.
|
||||
```
|
||||
|
||||
Wait for user confirmation before continuing to commit_codebase_map.
|
||||
|
||||
**If SECRETS_FOUND=false:**
|
||||
|
||||
Continue to commit_codebase_map.
|
||||
</step>
|
||||
|
||||
<step name="commit_codebase_map">
|
||||
Commit the codebase map:
|
||||
|
||||
```bash
|
||||
node "C:/Users/yaoji/.claude/get-shit-done/bin/gsd-tools.cjs" commit "docs: map existing codebase" --files .planning/codebase/*.md
|
||||
```
|
||||
|
||||
Continue to offer_next.
|
||||
</step>
|
||||
|
||||
<step name="offer_next">
|
||||
Present completion summary and next steps.
|
||||
|
||||
**Get line counts:**
|
||||
```bash
|
||||
wc -l .planning/codebase/*.md
|
||||
```
|
||||
|
||||
**Output format:**
|
||||
|
||||
```
|
||||
Codebase mapping complete.
|
||||
|
||||
Created .planning/codebase/:
|
||||
- STACK.md ([N] lines) - Technologies and dependencies
|
||||
- ARCHITECTURE.md ([N] lines) - System design and patterns
|
||||
- STRUCTURE.md ([N] lines) - Directory layout and organization
|
||||
- CONVENTIONS.md ([N] lines) - Code style and patterns
|
||||
- TESTING.md ([N] lines) - Test structure and practices
|
||||
- INTEGRATIONS.md ([N] lines) - External services and APIs
|
||||
- CONCERNS.md ([N] lines) - Technical debt and issues
|
||||
|
||||
|
||||
---
|
||||
|
||||
## ▶ Next Up
|
||||
|
||||
**Initialize project** — use codebase context for planning
|
||||
|
||||
`/gsd:new-project`
|
||||
|
||||
<sub>`/clear` first → fresh context window</sub>
|
||||
|
||||
---
|
||||
|
||||
**Also available:**
|
||||
- Re-run mapping: `/gsd:map-codebase`
|
||||
- Review specific file: `cat .planning/codebase/STACK.md`
|
||||
- Edit any document before proceeding
|
||||
|
||||
---
|
||||
```
|
||||
|
||||
End workflow.
|
||||
</step>
|
||||
|
||||
</process>
|
||||
|
||||
<success_criteria>
|
||||
- .planning/codebase/ directory created
|
||||
- If Task tool available: 4 parallel gsd-codebase-mapper agents spawned with run_in_background=true
|
||||
- If Task tool NOT available: 4 sequential mapping passes performed inline (never using browser_subagent)
|
||||
- All 7 codebase documents exist
|
||||
- No empty documents (each should have >20 lines)
|
||||
- Clear completion summary with line counts
|
||||
- User offered clear next steps in GSD style
|
||||
</success_criteria>
|
||||
386
get-shit-done/workflows/new-milestone.md
Normal file
386
get-shit-done/workflows/new-milestone.md
Normal file
@@ -0,0 +1,386 @@
|
||||
<purpose>
|
||||
|
||||
Start a new milestone cycle for an existing project. Loads project context, gathers milestone goals (from MILESTONE-CONTEXT.md or conversation), updates PROJECT.md and STATE.md, optionally runs parallel research, defines scoped requirements with REQ-IDs, spawns the roadmapper to create phased execution plan, and commits all artifacts. Brownfield equivalent of new-project.
|
||||
|
||||
</purpose>
|
||||
|
||||
<required_reading>
|
||||
|
||||
Read all files referenced by the invoking prompt's execution_context before starting.
|
||||
|
||||
</required_reading>
|
||||
|
||||
<process>
|
||||
|
||||
## 1. Load Context
|
||||
|
||||
- Read PROJECT.md (existing project, validated requirements, decisions)
|
||||
- Read MILESTONES.md (what shipped previously)
|
||||
- Read STATE.md (pending todos, blockers)
|
||||
- Check for MILESTONE-CONTEXT.md (from /gsd:discuss-milestone)
|
||||
|
||||
## 2. Gather Milestone Goals
|
||||
|
||||
**If MILESTONE-CONTEXT.md exists:**
|
||||
- Use features and scope from discuss-milestone
|
||||
- Present summary for confirmation
|
||||
|
||||
**If no context file:**
|
||||
- Present what shipped in last milestone
|
||||
- Ask inline (freeform, NOT AskUserQuestion): "What do you want to build next?"
|
||||
- Wait for their response, then use AskUserQuestion to probe specifics
|
||||
- If user selects "Other" at any point to provide freeform input, ask follow-up as plain text — not another AskUserQuestion
|
||||
|
||||
## 3. Determine Milestone Version
|
||||
|
||||
- Parse last version from MILESTONES.md
|
||||
- Suggest next version (v1.0 → v1.1, or v2.0 for major)
|
||||
- Confirm with user
|
||||
|
||||
## 4. Update PROJECT.md
|
||||
|
||||
Add/update:
|
||||
|
||||
```markdown
|
||||
## Current Milestone: v[X.Y] [Name]
|
||||
|
||||
**Goal:** [One sentence describing milestone focus]
|
||||
|
||||
**Target features:**
|
||||
- [Feature 1]
|
||||
- [Feature 2]
|
||||
- [Feature 3]
|
||||
```
|
||||
|
||||
Update Active requirements section and "Last updated" footer.
|
||||
|
||||
## 5. Update STATE.md
|
||||
|
||||
```markdown
|
||||
## Current Position
|
||||
|
||||
Phase: Not started (defining requirements)
|
||||
Plan: —
|
||||
Status: Defining requirements
|
||||
Last activity: [today] — Milestone v[X.Y] started
|
||||
```
|
||||
|
||||
Keep Accumulated Context section from previous milestone.
|
||||
|
||||
## 6. Cleanup and Commit
|
||||
|
||||
Delete MILESTONE-CONTEXT.md if exists (consumed).
|
||||
|
||||
```bash
|
||||
node "C:/Users/yaoji/.claude/get-shit-done/bin/gsd-tools.cjs" commit "docs: start milestone v[X.Y] [Name]" --files .planning/PROJECT.md .planning/STATE.md
|
||||
```
|
||||
|
||||
## 7. Load Context and Resolve Models
|
||||
|
||||
```bash
|
||||
INIT=$(node "C:/Users/yaoji/.claude/get-shit-done/bin/gsd-tools.cjs" init new-milestone)
|
||||
if [[ "$INIT" == @file:* ]]; then INIT=$(cat "${INIT#@file:}"); fi
|
||||
```
|
||||
|
||||
Extract from init JSON: `researcher_model`, `synthesizer_model`, `roadmapper_model`, `commit_docs`, `research_enabled`, `current_milestone`, `project_exists`, `roadmap_exists`.
|
||||
|
||||
## 8. Research Decision
|
||||
|
||||
Check `research_enabled` from init JSON (loaded from config).
|
||||
|
||||
**If `research_enabled` is `true`:**
|
||||
|
||||
AskUserQuestion: "Research the domain ecosystem for new features before defining requirements?"
|
||||
- "Research first (Recommended)" — Discover patterns, features, architecture for NEW capabilities
|
||||
- "Skip research for this milestone" — Go straight to requirements (does not change your default)
|
||||
|
||||
**If `research_enabled` is `false`:**
|
||||
|
||||
AskUserQuestion: "Research the domain ecosystem for new features before defining requirements?"
|
||||
- "Skip research (current default)" — Go straight to requirements
|
||||
- "Research first" — Discover patterns, features, architecture for NEW capabilities
|
||||
|
||||
**IMPORTANT:** Do NOT persist this choice to config.json. The `workflow.research` setting is a persistent user preference that controls plan-phase behavior across the project. Changing it here would silently alter future `/gsd:plan-phase` behavior. To change the default, use `/gsd:settings`.
|
||||
|
||||
**If user chose "Research first":**
|
||||
|
||||
```
|
||||
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
|
||||
GSD ► RESEARCHING
|
||||
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
|
||||
|
||||
◆ Spawning 4 researchers in parallel...
|
||||
→ Stack, Features, Architecture, Pitfalls
|
||||
```
|
||||
|
||||
```bash
|
||||
mkdir -p .planning/research
|
||||
```
|
||||
|
||||
Spawn 4 parallel gsd-project-researcher agents. Each uses this template with dimension-specific fields:
|
||||
|
||||
**Common structure for all 4 researchers:**
|
||||
```
|
||||
Task(prompt="
|
||||
<research_type>Project Research — {DIMENSION} for [new features].</research_type>
|
||||
|
||||
<milestone_context>
|
||||
SUBSEQUENT MILESTONE — Adding [target features] to existing app.
|
||||
{EXISTING_CONTEXT}
|
||||
Focus ONLY on what's needed for the NEW features.
|
||||
</milestone_context>
|
||||
|
||||
<question>{QUESTION}</question>
|
||||
|
||||
<files_to_read>
|
||||
- .planning/PROJECT.md (Project context)
|
||||
</files_to_read>
|
||||
|
||||
<downstream_consumer>{CONSUMER}</downstream_consumer>
|
||||
|
||||
<quality_gate>{GATES}</quality_gate>
|
||||
|
||||
<output>
|
||||
Write to: .planning/research/{FILE}
|
||||
Use template: C:/Users/yaoji/.claude/get-shit-done/templates/research-project/{FILE}
|
||||
</output>
|
||||
", subagent_type="gsd-project-researcher", model="{researcher_model}", description="{DIMENSION} research")
|
||||
```
|
||||
|
||||
**Dimension-specific fields:**
|
||||
|
||||
| Field | Stack | Features | Architecture | Pitfalls |
|
||||
|-------|-------|----------|-------------|----------|
|
||||
| EXISTING_CONTEXT | Existing validated capabilities (DO NOT re-research): [from PROJECT.md] | Existing features (already built): [from PROJECT.md] | Existing architecture: [from PROJECT.md or codebase map] | Focus on common mistakes when ADDING these features to existing system |
|
||||
| QUESTION | What stack additions/changes are needed for [new features]? | How do [target features] typically work? Expected behavior? | How do [target features] integrate with existing architecture? | Common mistakes when adding [target features] to [domain]? |
|
||||
| CONSUMER | Specific libraries with versions for NEW capabilities, integration points, what NOT to add | Table stakes vs differentiators vs anti-features, complexity noted, dependencies on existing | Integration points, new components, data flow changes, suggested build order | Warning signs, prevention strategy, which phase should address it |
|
||||
| GATES | Versions current (verify with Context7), rationale explains WHY, integration considered | Categories clear, complexity noted, dependencies identified | Integration points identified, new vs modified explicit, build order considers deps | Pitfalls specific to adding these features, integration pitfalls covered, prevention actionable |
|
||||
| FILE | STACK.md | FEATURES.md | ARCHITECTURE.md | PITFALLS.md |
|
||||
|
||||
After all 4 complete, spawn synthesizer:
|
||||
|
||||
```
|
||||
Task(prompt="
|
||||
Synthesize research outputs into SUMMARY.md.
|
||||
|
||||
<files_to_read>
|
||||
- .planning/research/STACK.md
|
||||
- .planning/research/FEATURES.md
|
||||
- .planning/research/ARCHITECTURE.md
|
||||
- .planning/research/PITFALLS.md
|
||||
</files_to_read>
|
||||
|
||||
Write to: .planning/research/SUMMARY.md
|
||||
Use template: C:/Users/yaoji/.claude/get-shit-done/templates/research-project/SUMMARY.md
|
||||
Commit after writing.
|
||||
", subagent_type="gsd-research-synthesizer", model="{synthesizer_model}", description="Synthesize research")
|
||||
```
|
||||
|
||||
Display key findings from SUMMARY.md:
|
||||
```
|
||||
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
|
||||
GSD ► RESEARCH COMPLETE ✓
|
||||
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
|
||||
|
||||
**Stack additions:** [from SUMMARY.md]
|
||||
**Feature table stakes:** [from SUMMARY.md]
|
||||
**Watch Out For:** [from SUMMARY.md]
|
||||
```
|
||||
|
||||
**If "Skip research":** Continue to Step 9.
|
||||
|
||||
## 9. Define Requirements
|
||||
|
||||
```
|
||||
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
|
||||
GSD ► DEFINING REQUIREMENTS
|
||||
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
|
||||
```
|
||||
|
||||
Read PROJECT.md: core value, current milestone goals, validated requirements (what exists).
|
||||
|
||||
**If research exists:** Read FEATURES.md, extract feature categories.
|
||||
|
||||
Present features by category:
|
||||
```
|
||||
## [Category 1]
|
||||
**Table stakes:** Feature A, Feature B
|
||||
**Differentiators:** Feature C, Feature D
|
||||
**Research notes:** [any relevant notes]
|
||||
```
|
||||
|
||||
**If no research:** Gather requirements through conversation. Ask: "What are the main things users need to do with [new features]?" Clarify, probe for related capabilities, group into categories.
|
||||
|
||||
**Scope each category** via AskUserQuestion (multiSelect: true, header max 12 chars):
|
||||
- "[Feature 1]" — [brief description]
|
||||
- "[Feature 2]" — [brief description]
|
||||
- "None for this milestone" — Defer entire category
|
||||
|
||||
Track: Selected → this milestone. Unselected table stakes → future. Unselected differentiators → out of scope.
|
||||
|
||||
**Identify gaps** via AskUserQuestion:
|
||||
- "No, research covered it" — Proceed
|
||||
- "Yes, let me add some" — Capture additions
|
||||
|
||||
**Generate REQUIREMENTS.md:**
|
||||
- v1 Requirements grouped by category (checkboxes, REQ-IDs)
|
||||
- Future Requirements (deferred)
|
||||
- Out of Scope (explicit exclusions with reasoning)
|
||||
- Traceability section (empty, filled by roadmap)
|
||||
|
||||
**REQ-ID format:** `[CATEGORY]-[NUMBER]` (AUTH-01, NOTIF-02). Continue numbering from existing.
|
||||
|
||||
**Requirement quality criteria:**
|
||||
|
||||
Good requirements are:
|
||||
- **Specific and testable:** "User can reset password via email link" (not "Handle password reset")
|
||||
- **User-centric:** "User can X" (not "System does Y")
|
||||
- **Atomic:** One capability per requirement (not "User can login and manage profile")
|
||||
- **Independent:** Minimal dependencies on other requirements
|
||||
|
||||
Present FULL requirements list for confirmation:
|
||||
|
||||
```
|
||||
## Milestone v[X.Y] Requirements
|
||||
|
||||
### [Category 1]
|
||||
- [ ] **CAT1-01**: User can do X
|
||||
- [ ] **CAT1-02**: User can do Y
|
||||
|
||||
### [Category 2]
|
||||
- [ ] **CAT2-01**: User can do Z
|
||||
|
||||
Does this capture what you're building? (yes / adjust)
|
||||
```
|
||||
|
||||
If "adjust": Return to scoping.
|
||||
|
||||
**Commit requirements:**
|
||||
```bash
|
||||
node "C:/Users/yaoji/.claude/get-shit-done/bin/gsd-tools.cjs" commit "docs: define milestone v[X.Y] requirements" --files .planning/REQUIREMENTS.md
|
||||
```
|
||||
|
||||
## 10. Create Roadmap
|
||||
|
||||
```
|
||||
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
|
||||
GSD ► CREATING ROADMAP
|
||||
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
|
||||
|
||||
◆ Spawning roadmapper...
|
||||
```
|
||||
|
||||
**Starting phase number:** Read MILESTONES.md for last phase number. Continue from there (v1.0 ended at phase 5 → v1.1 starts at phase 6).
|
||||
|
||||
```
|
||||
Task(prompt="
|
||||
<planning_context>
|
||||
<files_to_read>
|
||||
- .planning/PROJECT.md
|
||||
- .planning/REQUIREMENTS.md
|
||||
- .planning/research/SUMMARY.md (if exists)
|
||||
- .planning/config.json
|
||||
- .planning/MILESTONES.md
|
||||
</files_to_read>
|
||||
</planning_context>
|
||||
|
||||
<instructions>
|
||||
Create roadmap for milestone v[X.Y]:
|
||||
1. Start phase numbering from [N]
|
||||
2. Derive phases from THIS MILESTONE's requirements only
|
||||
3. Map every requirement to exactly one phase
|
||||
4. Derive 2-5 success criteria per phase (observable user behaviors)
|
||||
5. Validate 100% coverage
|
||||
6. Write files immediately (ROADMAP.md, STATE.md, update REQUIREMENTS.md traceability)
|
||||
7. Return ROADMAP CREATED with summary
|
||||
|
||||
Write files first, then return.
|
||||
</instructions>
|
||||
", subagent_type="gsd-roadmapper", model="{roadmapper_model}", description="Create roadmap")
|
||||
```
|
||||
|
||||
**Handle return:**
|
||||
|
||||
**If `## ROADMAP BLOCKED`:** Present blocker, work with user, re-spawn.
|
||||
|
||||
**If `## ROADMAP CREATED`:** Read ROADMAP.md, present inline:
|
||||
|
||||
```
|
||||
## Proposed Roadmap
|
||||
|
||||
**[N] phases** | **[X] requirements mapped** | All covered ✓
|
||||
|
||||
| # | Phase | Goal | Requirements | Success Criteria |
|
||||
|---|-------|------|--------------|------------------|
|
||||
| [N] | [Name] | [Goal] | [REQ-IDs] | [count] |
|
||||
|
||||
### Phase Details
|
||||
|
||||
**Phase [N]: [Name]**
|
||||
Goal: [goal]
|
||||
Requirements: [REQ-IDs]
|
||||
Success criteria:
|
||||
1. [criterion]
|
||||
2. [criterion]
|
||||
```
|
||||
|
||||
**Ask for approval** via AskUserQuestion:
|
||||
- "Approve" — Commit and continue
|
||||
- "Adjust phases" — Tell me what to change
|
||||
- "Review full file" — Show raw ROADMAP.md
|
||||
|
||||
**If "Adjust":** Get notes, re-spawn roadmapper with revision context, loop until approved.
|
||||
**If "Review":** Display raw ROADMAP.md, re-ask.
|
||||
|
||||
**Commit roadmap** (after approval):
|
||||
```bash
|
||||
node "C:/Users/yaoji/.claude/get-shit-done/bin/gsd-tools.cjs" commit "docs: create milestone v[X.Y] roadmap ([N] phases)" --files .planning/ROADMAP.md .planning/STATE.md .planning/REQUIREMENTS.md
|
||||
```
|
||||
|
||||
## 11. Done
|
||||
|
||||
```
|
||||
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
|
||||
GSD ► MILESTONE INITIALIZED ✓
|
||||
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
|
||||
|
||||
**Milestone v[X.Y]: [Name]**
|
||||
|
||||
| Artifact | Location |
|
||||
|----------------|-----------------------------|
|
||||
| Project | `.planning/PROJECT.md` |
|
||||
| Research | `.planning/research/` |
|
||||
| Requirements | `.planning/REQUIREMENTS.md` |
|
||||
| Roadmap | `.planning/ROADMAP.md` |
|
||||
|
||||
**[N] phases** | **[X] requirements** | Ready to build ✓
|
||||
|
||||
## ▶ Next Up
|
||||
|
||||
**Phase [N]: [Phase Name]** — [Goal]
|
||||
|
||||
`/gsd:discuss-phase [N]` — gather context and clarify approach
|
||||
|
||||
<sub>`/clear` first → fresh context window</sub>
|
||||
|
||||
Also: `/gsd:plan-phase [N]` — skip discussion, plan directly
|
||||
```
|
||||
|
||||
</process>
|
||||
|
||||
<success_criteria>
|
||||
- [ ] PROJECT.md updated with Current Milestone section
|
||||
- [ ] STATE.md reset for new milestone
|
||||
- [ ] MILESTONE-CONTEXT.md consumed and deleted (if existed)
|
||||
- [ ] Research completed (if selected) — 4 parallel agents, milestone-aware
|
||||
- [ ] Requirements gathered and scoped per category
|
||||
- [ ] REQUIREMENTS.md created with REQ-IDs
|
||||
- [ ] gsd-roadmapper spawned with phase numbering context
|
||||
- [ ] Roadmap files written immediately (not draft)
|
||||
- [ ] User feedback incorporated (if any)
|
||||
- [ ] ROADMAP.md phases continue from previous milestone
|
||||
- [ ] All commits made (if planning docs committed)
|
||||
- [ ] User knows next step: `/gsd:discuss-phase [N]`
|
||||
|
||||
**Atomic commits:** Each phase commits its artifacts immediately.
|
||||
</success_criteria>
|
||||
1113
get-shit-done/workflows/new-project.md
Normal file
1113
get-shit-done/workflows/new-project.md
Normal file
File diff suppressed because it is too large
Load Diff
97
get-shit-done/workflows/next.md
Normal file
97
get-shit-done/workflows/next.md
Normal file
@@ -0,0 +1,97 @@
|
||||
<purpose>
|
||||
Detect current project state and automatically advance to the next logical GSD workflow step.
|
||||
Reads project state to determine: discuss → plan → execute → verify → complete progression.
|
||||
</purpose>
|
||||
|
||||
<required_reading>
|
||||
Read all files referenced by the invoking prompt's execution_context before starting.
|
||||
</required_reading>
|
||||
|
||||
<process>
|
||||
|
||||
<step name="detect_state">
|
||||
Read project state to determine current position:
|
||||
|
||||
```bash
|
||||
# Get state snapshot
|
||||
node "C:/Users/yaoji/.claude/get-shit-done/bin/gsd-tools.cjs" state json 2>/dev/null || echo "{}"
|
||||
```
|
||||
|
||||
Also read:
|
||||
- `.planning/STATE.md` — current phase, progress, plan counts
|
||||
- `.planning/ROADMAP.md` — milestone structure and phase list
|
||||
|
||||
Extract:
|
||||
- `current_phase` — which phase is active
|
||||
- `plan_of` / `plans_total` — plan execution progress
|
||||
- `progress` — overall percentage
|
||||
- `status` — active, paused, etc.
|
||||
|
||||
If no `.planning/` directory exists:
|
||||
```
|
||||
No GSD project detected. Run `/gsd:new-project` to get started.
|
||||
```
|
||||
Exit.
|
||||
</step>
|
||||
|
||||
<step name="determine_next_action">
|
||||
Apply routing rules based on state:
|
||||
|
||||
**Route 1: No phases exist yet → discuss**
|
||||
If ROADMAP has phases but no phase directories exist on disk:
|
||||
→ Next action: `/gsd:discuss-phase <first-phase>`
|
||||
|
||||
**Route 2: Phase exists but has no CONTEXT.md or RESEARCH.md → discuss**
|
||||
If the current phase directory exists but has neither CONTEXT.md nor RESEARCH.md:
|
||||
→ Next action: `/gsd:discuss-phase <current-phase>`
|
||||
|
||||
**Route 3: Phase has context but no plans → plan**
|
||||
If the current phase has CONTEXT.md (or RESEARCH.md) but no PLAN.md files:
|
||||
→ Next action: `/gsd:plan-phase <current-phase>`
|
||||
|
||||
**Route 4: Phase has plans but incomplete summaries → execute**
|
||||
If plans exist but not all have matching summaries:
|
||||
→ Next action: `/gsd:execute-phase <current-phase>`
|
||||
|
||||
**Route 5: All plans have summaries → verify and complete**
|
||||
If all plans in the current phase have summaries:
|
||||
→ Next action: `/gsd:verify-work` then `/gsd:complete-phase`
|
||||
|
||||
**Route 6: Phase complete, next phase exists → advance**
|
||||
If the current phase is complete and the next phase exists in ROADMAP:
|
||||
→ Next action: `/gsd:discuss-phase <next-phase>`
|
||||
|
||||
**Route 7: All phases complete → complete milestone**
|
||||
If all phases are complete:
|
||||
→ Next action: `/gsd:complete-milestone`
|
||||
|
||||
**Route 8: Paused → resume**
|
||||
If STATE.md shows paused_at:
|
||||
→ Next action: `/gsd:resume-work`
|
||||
</step>
|
||||
|
||||
<step name="show_and_execute">
|
||||
Display the determination:
|
||||
|
||||
```
|
||||
## GSD Next
|
||||
|
||||
**Current:** Phase [N] — [name] | [progress]%
|
||||
**Status:** [status description]
|
||||
|
||||
▶ **Next step:** `/gsd:[command] [args]`
|
||||
[One-line explanation of why this is the next step]
|
||||
```
|
||||
|
||||
Then immediately invoke the determined command via SlashCommand.
|
||||
Do not ask for confirmation — the whole point of `/gsd:next` is zero-friction advancement.
|
||||
</step>
|
||||
|
||||
</process>
|
||||
|
||||
<success_criteria>
|
||||
- [ ] Project state correctly detected
|
||||
- [ ] Next action correctly determined from routing rules
|
||||
- [ ] Command invoked immediately without user confirmation
|
||||
- [ ] Clear status shown before invoking
|
||||
</success_criteria>
|
||||
92
get-shit-done/workflows/node-repair.md
Normal file
92
get-shit-done/workflows/node-repair.md
Normal file
@@ -0,0 +1,92 @@
|
||||
<purpose>
|
||||
Autonomous repair operator for failed task verification. Invoked by execute-plan when a task fails its done-criteria. Proposes and attempts structured fixes before escalating to the user.
|
||||
</purpose>
|
||||
|
||||
<inputs>
|
||||
- FAILED_TASK: Task number, name, and done-criteria from the plan
|
||||
- ERROR: What verification produced — actual result vs expected
|
||||
- PLAN_CONTEXT: Adjacent tasks and phase goal (for constraint awareness)
|
||||
- REPAIR_BUDGET: Max repair attempts remaining (default: 2)
|
||||
</inputs>
|
||||
|
||||
<repair_directive>
|
||||
Analyze the failure and choose exactly one repair strategy:
|
||||
|
||||
**RETRY** — The approach was right but execution failed. Try again with a concrete adjustment.
|
||||
- Use when: command error, missing dependency, wrong path, env issue, transient failure
|
||||
- Output: `RETRY: [specific adjustment to make before retrying]`
|
||||
|
||||
**DECOMPOSE** — The task is too coarse. Break it into smaller verifiable sub-steps.
|
||||
- Use when: done-criteria covers multiple concerns, implementation gaps are structural
|
||||
- Output: `DECOMPOSE: [sub-task 1] | [sub-task 2] | ...` (max 3 sub-tasks)
|
||||
- Sub-tasks must each have a single verifiable outcome
|
||||
|
||||
**PRUNE** — The task is infeasible given current constraints. Skip with justification.
|
||||
- Use when: prerequisite missing and not fixable here, out of scope, contradicts an earlier decision
|
||||
- Output: `PRUNE: [one-sentence justification]`
|
||||
|
||||
**ESCALATE** — Repair budget exhausted, or this is an architectural decision (Rule 4).
|
||||
- Use when: RETRY failed more than once with different approaches, or fix requires structural change
|
||||
- Output: `ESCALATE: [what was tried] | [what decision is needed]`
|
||||
</repair_directive>
|
||||
|
||||
<process>
|
||||
|
||||
<step name="diagnose">
|
||||
Read the error and done-criteria carefully. Ask:
|
||||
1. Is this a transient/environmental issue? → RETRY
|
||||
2. Is the task verifiably too broad? → DECOMPOSE
|
||||
3. Is a prerequisite genuinely missing and unfixable in scope? → PRUNE
|
||||
4. Has RETRY already been attempted with this task? Check REPAIR_BUDGET. If 0 → ESCALATE
|
||||
</step>
|
||||
|
||||
<step name="execute_retry">
|
||||
If RETRY:
|
||||
1. Apply the specific adjustment stated in the directive
|
||||
2. Re-run the task implementation
|
||||
3. Re-run verification
|
||||
4. If passes → continue normally, log `[Node Repair - RETRY] Task [X]: [adjustment made]`
|
||||
5. If fails again → decrement REPAIR_BUDGET, re-invoke node-repair with updated context
|
||||
</step>
|
||||
|
||||
<step name="execute_decompose">
|
||||
If DECOMPOSE:
|
||||
1. Replace the failed task inline with the sub-tasks (do not modify PLAN.md on disk)
|
||||
2. Execute sub-tasks sequentially, each with its own verification
|
||||
3. If all sub-tasks pass → treat original task as succeeded, log `[Node Repair - DECOMPOSE] Task [X] → [N] sub-tasks`
|
||||
4. If a sub-task fails → re-invoke node-repair for that sub-task (REPAIR_BUDGET applies per sub-task)
|
||||
</step>
|
||||
|
||||
<step name="execute_prune">
|
||||
If PRUNE:
|
||||
1. Mark task as skipped with justification
|
||||
2. Log to SUMMARY "Issues Encountered": `[Node Repair - PRUNE] Task [X]: [justification]`
|
||||
3. Continue to next task
|
||||
</step>
|
||||
|
||||
<step name="execute_escalate">
|
||||
If ESCALATE:
|
||||
1. Surface to user via verification_failure_gate with full repair history
|
||||
2. Present: what was tried (each RETRY/DECOMPOSE attempt), what the blocker is, options available
|
||||
3. Wait for user direction before continuing
|
||||
</step>
|
||||
|
||||
</process>
|
||||
|
||||
<logging>
|
||||
All repair actions must appear in SUMMARY.md under "## Deviations from Plan":
|
||||
|
||||
| Type | Format |
|
||||
|------|--------|
|
||||
| RETRY success | `[Node Repair - RETRY] Task X: [adjustment] — resolved` |
|
||||
| RETRY fail → ESCALATE | `[Node Repair - RETRY] Task X: [N] attempts exhausted — escalated to user` |
|
||||
| DECOMPOSE | `[Node Repair - DECOMPOSE] Task X split into [N] sub-tasks — all passed` |
|
||||
| PRUNE | `[Node Repair - PRUNE] Task X skipped: [justification]` |
|
||||
</logging>
|
||||
|
||||
<constraints>
|
||||
- REPAIR_BUDGET defaults to 2 per task. Configurable via config.json `workflow.node_repair_budget`.
|
||||
- Never modify PLAN.md on disk — decomposed sub-tasks are in-memory only.
|
||||
- DECOMPOSE sub-tasks must be more specific than the original, not synonymous rewrites.
|
||||
- If config.json `workflow.node_repair` is `false`, skip directly to verification_failure_gate (user retains original behavior).
|
||||
</constraints>
|
||||
156
get-shit-done/workflows/note.md
Normal file
156
get-shit-done/workflows/note.md
Normal file
@@ -0,0 +1,156 @@
|
||||
<purpose>
|
||||
Zero-friction idea capture. One Write call, one confirmation line. No questions, no prompts.
|
||||
Runs inline — no Task, no AskUserQuestion, no Bash.
|
||||
</purpose>
|
||||
|
||||
<required_reading>
|
||||
Read all files referenced by the invoking prompt's execution_context before starting.
|
||||
</required_reading>
|
||||
|
||||
<process>
|
||||
|
||||
<step name="storage_format">
|
||||
**Note storage format.**
|
||||
|
||||
Notes are stored as individual markdown files:
|
||||
|
||||
- **Project scope**: `.planning/notes/{YYYY-MM-DD}-{slug}.md` — used when `.planning/` exists in cwd
|
||||
- **Global scope**: `C:/Users/yaoji/.claude/notes/{YYYY-MM-DD}-{slug}.md` — fallback when no `.planning/`, or when `--global` flag is present
|
||||
|
||||
Each note file:
|
||||
|
||||
```markdown
|
||||
---
|
||||
date: "YYYY-MM-DD HH:mm"
|
||||
promoted: false
|
||||
---
|
||||
|
||||
{note text verbatim}
|
||||
```
|
||||
|
||||
**`--global` flag**: Strip `--global` from anywhere in `$ARGUMENTS` before parsing. When present, force global scope regardless of whether `.planning/` exists.
|
||||
|
||||
**Important**: Do NOT create `.planning/` if it doesn't exist. Fall back to global scope silently.
|
||||
</step>
|
||||
|
||||
<step name="parse_subcommand">
|
||||
**Parse subcommand from $ARGUMENTS (after stripping --global).**
|
||||
|
||||
| Condition | Subcommand |
|
||||
|-----------|------------|
|
||||
| Arguments are exactly `list` (case-insensitive) | **list** |
|
||||
| Arguments are exactly `promote <N>` where N is a number | **promote** |
|
||||
| Arguments are empty (no text at all) | **list** |
|
||||
| Anything else | **append** (the text IS the note) |
|
||||
|
||||
**Critical**: `list` is only a subcommand when it's the ENTIRE argument. `/gsd:note list of groceries` saves a note with text "list of groceries". Same for `promote` — only a subcommand when followed by exactly one number.
|
||||
</step>
|
||||
|
||||
<step name="append">
|
||||
**Subcommand: append — create a timestamped note file.**
|
||||
|
||||
1. Determine scope (project or global) per storage format above
|
||||
2. Ensure the notes directory exists (`.planning/notes/` or `C:/Users/yaoji/.claude/notes/`)
|
||||
3. Generate slug: first ~4 meaningful words of the note text, lowercase, hyphen-separated (strip articles/prepositions from the start)
|
||||
4. Generate filename: `{YYYY-MM-DD}-{slug}.md`
|
||||
- If a file with that name already exists, append `-2`, `-3`, etc.
|
||||
5. Write the file with frontmatter and note text (see storage format)
|
||||
6. Confirm with exactly one line: `Noted ({scope}): {note text}`
|
||||
- Where `{scope}` is "project" or "global"
|
||||
|
||||
**Constraints:**
|
||||
- **Never modify the note text** — capture verbatim, including typos
|
||||
- **Never ask questions** — just write and confirm
|
||||
- **Timestamp format**: Use local time, `YYYY-MM-DD HH:mm` (24-hour, no seconds)
|
||||
</step>
|
||||
|
||||
<step name="list">
|
||||
**Subcommand: list — show notes from both scopes.**
|
||||
|
||||
1. Glob `.planning/notes/*.md` (if directory exists) — project notes
|
||||
2. Glob `C:/Users/yaoji/.claude/notes/*.md` (if directory exists) — global notes
|
||||
3. For each file, read frontmatter to get `date` and `promoted` status
|
||||
4. Exclude files where `promoted: true` from active counts (but still show them, dimmed)
|
||||
5. Sort by date, number all active entries sequentially starting at 1
|
||||
6. If total active entries > 20, show only the last 10 with a note about how many were omitted
|
||||
|
||||
**Display format:**
|
||||
|
||||
```
|
||||
Notes:
|
||||
|
||||
Project (.planning/notes/):
|
||||
1. [2026-02-08 14:32] refactor the hook system to support async validators
|
||||
2. [promoted] [2026-02-08 14:40] add rate limiting to the API endpoints
|
||||
3. [2026-02-08 15:10] consider adding a --dry-run flag to build
|
||||
|
||||
Global (C:/Users/yaoji/.claude/notes/):
|
||||
4. [2026-02-08 10:00] cross-project idea about shared config
|
||||
|
||||
{count} active note(s). Use `/gsd:note promote <N>` to convert to a todo.
|
||||
```
|
||||
|
||||
If a scope has no directory or no entries, show: `(no notes)`
|
||||
</step>
|
||||
|
||||
<step name="promote">
|
||||
**Subcommand: promote — convert a note into a todo.**
|
||||
|
||||
1. Run the **list** logic to build the numbered index (both scopes)
|
||||
2. Find entry N from the numbered list
|
||||
3. If N is invalid or refers to an already-promoted note, tell the user and stop
|
||||
4. **Requires `.planning/` directory** — if it doesn't exist, warn: "Todos require a GSD project. Run `/gsd:new-project` to initialize one."
|
||||
5. Ensure `.planning/todos/pending/` directory exists
|
||||
6. Generate todo ID: `{NNN}-{slug}` where NNN is the next sequential number (scan both `.planning/todos/pending/` and `.planning/todos/done/` for the highest existing number, increment by 1, zero-pad to 3 digits) and slug is the first ~4 meaningful words of the note text
|
||||
7. Extract the note text from the source file (body after frontmatter)
|
||||
8. Create `.planning/todos/pending/{id}.md`:
|
||||
|
||||
```yaml
|
||||
---
|
||||
title: "{note text}"
|
||||
status: pending
|
||||
priority: P2
|
||||
source: "promoted from /gsd:note"
|
||||
created: {YYYY-MM-DD}
|
||||
theme: general
|
||||
---
|
||||
|
||||
## Goal
|
||||
|
||||
{note text}
|
||||
|
||||
## Context
|
||||
|
||||
Promoted from quick note captured on {original date}.
|
||||
|
||||
## Acceptance Criteria
|
||||
|
||||
- [ ] {primary criterion derived from note text}
|
||||
```
|
||||
|
||||
9. Mark the source note file as promoted: update its frontmatter to `promoted: true`
|
||||
10. Confirm: `Promoted note {N} to todo {id}: {note text}`
|
||||
</step>
|
||||
|
||||
</process>
|
||||
|
||||
<edge_cases>
|
||||
1. **"list" as note text**: `/gsd:note list of things` saves note "list of things" (subcommand only when `list` is the entire arg)
|
||||
2. **No `.planning/`**: Falls back to global `C:/Users/yaoji/.claude/notes/` — works in any directory
|
||||
3. **Promote without project**: Warns that todos require `.planning/`, suggests `/gsd:new-project`
|
||||
4. **Large files**: `list` shows last 10 when >20 active entries
|
||||
5. **Duplicate slugs**: Append `-2`, `-3` etc. to filename if slug already used on same date
|
||||
6. **`--global` position**: Stripped from anywhere — `--global my idea` and `my idea --global` both save "my idea" globally
|
||||
7. **Promote already-promoted**: Tell user "Note {N} is already promoted" and stop
|
||||
8. **Empty note text after stripping flags**: Treat as `list` subcommand
|
||||
</edge_cases>
|
||||
|
||||
<success_criteria>
|
||||
- [ ] Append: Note file written with correct frontmatter and verbatim text
|
||||
- [ ] Append: No questions asked — instant capture
|
||||
- [ ] List: Both scopes shown with sequential numbering
|
||||
- [ ] List: Promoted notes shown but dimmed
|
||||
- [ ] Promote: Todo created with correct format
|
||||
- [ ] Promote: Source note marked as promoted
|
||||
- [ ] Global fallback: Works when no `.planning/` exists
|
||||
</success_criteria>
|
||||
176
get-shit-done/workflows/pause-work.md
Normal file
176
get-shit-done/workflows/pause-work.md
Normal file
@@ -0,0 +1,176 @@
|
||||
<purpose>
|
||||
Create structured `.planning/HANDOFF.json` and `.continue-here.md` handoff files to preserve complete work state across sessions. The JSON provides machine-readable state for `/gsd:resume-work`; the markdown provides human-readable context.
|
||||
</purpose>
|
||||
|
||||
<required_reading>
|
||||
Read all files referenced by the invoking prompt's execution_context before starting.
|
||||
</required_reading>
|
||||
|
||||
<process>
|
||||
|
||||
<step name="detect">
|
||||
Find current phase directory from most recently modified files:
|
||||
|
||||
```bash
|
||||
# Find most recent phase directory with work
|
||||
ls -lt .planning/phases/*/PLAN.md 2>/dev/null | head -1 | grep -oP 'phases/\K[^/]+'
|
||||
```
|
||||
|
||||
If no active phase detected, ask user which phase they're pausing work on.
|
||||
</step>
|
||||
|
||||
<step name="gather">
|
||||
**Collect complete state for handoff:**
|
||||
|
||||
1. **Current position**: Which phase, which plan, which task
|
||||
2. **Work completed**: What got done this session
|
||||
3. **Work remaining**: What's left in current plan/phase
|
||||
4. **Decisions made**: Key decisions and rationale
|
||||
5. **Blockers/issues**: Anything stuck
|
||||
6. **Human actions pending**: Things that need manual intervention (MCP setup, API keys, approvals, manual testing)
|
||||
7. **Background processes**: Any running servers/watchers that were part of the workflow
|
||||
8. **Files modified**: What's changed but not committed
|
||||
|
||||
Ask user for clarifications if needed via conversational questions.
|
||||
|
||||
**Also inspect SUMMARY.md files for false completions:**
|
||||
```bash
|
||||
# Check for placeholder content in existing summaries
|
||||
grep -l "To be filled\|placeholder\|TBD" .planning/phases/*/*.md 2>/dev/null
|
||||
```
|
||||
Report any summaries with placeholder content as incomplete items.
|
||||
</step>
|
||||
|
||||
<step name="write_structured">
|
||||
**Write structured handoff to `.planning/HANDOFF.json`:**
|
||||
|
||||
```bash
|
||||
timestamp=$(node "C:/Users/yaoji/.claude/get-shit-done/bin/gsd-tools.cjs" current-timestamp full --raw)
|
||||
```
|
||||
|
||||
```json
|
||||
{
|
||||
"version": "1.0",
|
||||
"timestamp": "{timestamp}",
|
||||
"phase": "{phase_number}",
|
||||
"phase_name": "{phase_name}",
|
||||
"phase_dir": "{phase_dir}",
|
||||
"plan": {current_plan_number},
|
||||
"task": {current_task_number},
|
||||
"total_tasks": {total_task_count},
|
||||
"status": "paused",
|
||||
"completed_tasks": [
|
||||
{"id": 1, "name": "{task_name}", "status": "done", "commit": "{short_hash}"},
|
||||
{"id": 2, "name": "{task_name}", "status": "done", "commit": "{short_hash}"},
|
||||
{"id": 3, "name": "{task_name}", "status": "in_progress", "progress": "{what_done}"}
|
||||
],
|
||||
"remaining_tasks": [
|
||||
{"id": 4, "name": "{task_name}", "status": "not_started"},
|
||||
{"id": 5, "name": "{task_name}", "status": "not_started"}
|
||||
],
|
||||
"blockers": [
|
||||
{"description": "{blocker}", "type": "technical|human_action|external", "workaround": "{if any}"}
|
||||
],
|
||||
"human_actions_pending": [
|
||||
{"action": "{what needs to be done}", "context": "{why}", "blocking": true}
|
||||
],
|
||||
"decisions": [
|
||||
{"decision": "{what}", "rationale": "{why}", "phase": "{phase_number}"}
|
||||
],
|
||||
"uncommitted_files": [],
|
||||
"next_action": "{specific first action when resuming}",
|
||||
"context_notes": "{mental state, approach, what you were thinking}"
|
||||
}
|
||||
```
|
||||
</step>
|
||||
|
||||
<step name="write">
|
||||
**Write handoff to `.planning/phases/XX-name/.continue-here.md`:**
|
||||
|
||||
```markdown
|
||||
---
|
||||
phase: XX-name
|
||||
task: 3
|
||||
total_tasks: 7
|
||||
status: in_progress
|
||||
last_updated: [timestamp from current-timestamp]
|
||||
---
|
||||
|
||||
<current_state>
|
||||
[Where exactly are we? Immediate context]
|
||||
</current_state>
|
||||
|
||||
<completed_work>
|
||||
|
||||
- Task 1: [name] - Done
|
||||
- Task 2: [name] - Done
|
||||
- Task 3: [name] - In progress, [what's done]
|
||||
</completed_work>
|
||||
|
||||
<remaining_work>
|
||||
|
||||
- Task 3: [what's left]
|
||||
- Task 4: Not started
|
||||
- Task 5: Not started
|
||||
</remaining_work>
|
||||
|
||||
<decisions_made>
|
||||
|
||||
- Decided to use [X] because [reason]
|
||||
- Chose [approach] over [alternative] because [reason]
|
||||
</decisions_made>
|
||||
|
||||
<blockers>
|
||||
- [Blocker 1]: [status/workaround]
|
||||
</blockers>
|
||||
|
||||
<context>
|
||||
[Mental state, what were you thinking, the plan]
|
||||
</context>
|
||||
|
||||
<next_action>
|
||||
Start with: [specific first action when resuming]
|
||||
</next_action>
|
||||
```
|
||||
|
||||
Be specific enough for a fresh Claude to understand immediately.
|
||||
|
||||
Use `current-timestamp` for last_updated field. You can use init todos (which provides timestamps) or call directly:
|
||||
```bash
|
||||
timestamp=$(node "C:/Users/yaoji/.claude/get-shit-done/bin/gsd-tools.cjs" current-timestamp full --raw)
|
||||
```
|
||||
</step>
|
||||
|
||||
<step name="commit">
|
||||
```bash
|
||||
node "C:/Users/yaoji/.claude/get-shit-done/bin/gsd-tools.cjs" commit "wip: [phase-name] paused at task [X]/[Y]" --files .planning/phases/*/.continue-here.md .planning/HANDOFF.json
|
||||
```
|
||||
</step>
|
||||
|
||||
<step name="confirm">
|
||||
```
|
||||
✓ Handoff created:
|
||||
- .planning/HANDOFF.json (structured, machine-readable)
|
||||
- .planning/phases/[XX-name]/.continue-here.md (human-readable)
|
||||
|
||||
Current state:
|
||||
|
||||
- Phase: [XX-name]
|
||||
- Task: [X] of [Y]
|
||||
- Status: [in_progress/blocked]
|
||||
- Blockers: [count] ({human_actions_pending count} need human action)
|
||||
- Committed as WIP
|
||||
|
||||
To resume: /gsd:resume-work
|
||||
|
||||
```
|
||||
</step>
|
||||
|
||||
</process>
|
||||
|
||||
<success_criteria>
|
||||
- [ ] .continue-here.md created in correct phase directory
|
||||
- [ ] All sections filled with specific content
|
||||
- [ ] Committed as WIP
|
||||
- [ ] User knows location and how to resume
|
||||
</success_criteria>
|
||||
274
get-shit-done/workflows/plan-milestone-gaps.md
Normal file
274
get-shit-done/workflows/plan-milestone-gaps.md
Normal file
@@ -0,0 +1,274 @@
|
||||
<purpose>
|
||||
Create all phases necessary to close gaps identified by `/gsd:audit-milestone`. Reads MILESTONE-AUDIT.md, groups gaps into logical phases, creates phase entries in ROADMAP.md, and offers to plan each phase. One command creates all fix phases — no manual `/gsd:add-phase` per gap.
|
||||
</purpose>
|
||||
|
||||
<required_reading>
|
||||
Read all files referenced by the invoking prompt's execution_context before starting.
|
||||
</required_reading>
|
||||
|
||||
<process>
|
||||
|
||||
## 1. Load Audit Results
|
||||
|
||||
```bash
|
||||
# Find the most recent audit file
|
||||
ls -t .planning/v*-MILESTONE-AUDIT.md 2>/dev/null | head -1
|
||||
```
|
||||
|
||||
Parse YAML frontmatter to extract structured gaps:
|
||||
- `gaps.requirements` — unsatisfied requirements
|
||||
- `gaps.integration` — missing cross-phase connections
|
||||
- `gaps.flows` — broken E2E flows
|
||||
|
||||
If no audit file exists or has no gaps, error:
|
||||
```
|
||||
No audit gaps found. Run `/gsd:audit-milestone` first.
|
||||
```
|
||||
|
||||
## 2. Prioritize Gaps
|
||||
|
||||
Group gaps by priority from REQUIREMENTS.md:
|
||||
|
||||
| Priority | Action |
|
||||
|----------|--------|
|
||||
| `must` | Create phase, blocks milestone |
|
||||
| `should` | Create phase, recommended |
|
||||
| `nice` | Ask user: include or defer? |
|
||||
|
||||
For integration/flow gaps, infer priority from affected requirements.
|
||||
|
||||
## 3. Group Gaps into Phases
|
||||
|
||||
Cluster related gaps into logical phases:
|
||||
|
||||
**Grouping rules:**
|
||||
- Same affected phase → combine into one fix phase
|
||||
- Same subsystem (auth, API, UI) → combine
|
||||
- Dependency order (fix stubs before wiring)
|
||||
- Keep phases focused: 2-4 tasks each
|
||||
|
||||
**Example grouping:**
|
||||
```
|
||||
Gap: DASH-01 unsatisfied (Dashboard doesn't fetch)
|
||||
Gap: Integration Phase 1→3 (Auth not passed to API calls)
|
||||
Gap: Flow "View dashboard" broken at data fetch
|
||||
|
||||
→ Phase 6: "Wire Dashboard to API"
|
||||
- Add fetch to Dashboard.tsx
|
||||
- Include auth header in fetch
|
||||
- Handle response, update state
|
||||
- Render user data
|
||||
```
|
||||
|
||||
## 4. Determine Phase Numbers
|
||||
|
||||
Find highest existing phase:
|
||||
```bash
|
||||
# Get sorted phase list, extract last one
|
||||
PHASES=$(node "C:/Users/yaoji/.claude/get-shit-done/bin/gsd-tools.cjs" phases list)
|
||||
HIGHEST=$(printf '%s\n' "$PHASES" | jq -r '.directories[-1]')
|
||||
```
|
||||
|
||||
New phases continue from there:
|
||||
- If Phase 5 is highest, gaps become Phase 6, 7, 8...
|
||||
|
||||
## 5. Present Gap Closure Plan
|
||||
|
||||
```markdown
|
||||
## Gap Closure Plan
|
||||
|
||||
**Milestone:** {version}
|
||||
**Gaps to close:** {N} requirements, {M} integration, {K} flows
|
||||
|
||||
### Proposed Phases
|
||||
|
||||
**Phase {N}: {Name}**
|
||||
Closes:
|
||||
- {REQ-ID}: {description}
|
||||
- Integration: {from} → {to}
|
||||
Tasks: {count}
|
||||
|
||||
**Phase {N+1}: {Name}**
|
||||
Closes:
|
||||
- {REQ-ID}: {description}
|
||||
- Flow: {flow name}
|
||||
Tasks: {count}
|
||||
|
||||
{If nice-to-have gaps exist:}
|
||||
|
||||
### Deferred (nice-to-have)
|
||||
|
||||
These gaps are optional. Include them?
|
||||
- {gap description}
|
||||
- {gap description}
|
||||
|
||||
---
|
||||
|
||||
Create these {X} phases? (yes / adjust / defer all optional)
|
||||
```
|
||||
|
||||
Wait for user confirmation.
|
||||
|
||||
## 6. Update ROADMAP.md
|
||||
|
||||
Add new phases to current milestone:
|
||||
|
||||
```markdown
|
||||
### Phase {N}: {Name}
|
||||
**Goal:** {derived from gaps being closed}
|
||||
**Requirements:** {REQ-IDs being satisfied}
|
||||
**Gap Closure:** Closes gaps from audit
|
||||
|
||||
### Phase {N+1}: {Name}
|
||||
...
|
||||
```
|
||||
|
||||
## 7. Update REQUIREMENTS.md Traceability Table (REQUIRED)
|
||||
|
||||
For each REQ-ID assigned to a gap closure phase:
|
||||
- Update the Phase column to reflect the new gap closure phase
|
||||
- Reset Status to `Pending`
|
||||
|
||||
Reset checked-off requirements the audit found unsatisfied:
|
||||
- Change `[x]` → `[ ]` for any requirement marked unsatisfied in the audit
|
||||
- Update coverage count at top of REQUIREMENTS.md
|
||||
|
||||
```bash
|
||||
# Verify traceability table reflects gap closure assignments
|
||||
grep -c "Pending" .planning/REQUIREMENTS.md
|
||||
```
|
||||
|
||||
## 8. Create Phase Directories
|
||||
|
||||
```bash
|
||||
mkdir -p ".planning/phases/{NN}-{name}"
|
||||
```
|
||||
|
||||
## 9. Commit Roadmap and Requirements Update
|
||||
|
||||
```bash
|
||||
node "C:/Users/yaoji/.claude/get-shit-done/bin/gsd-tools.cjs" commit "docs(roadmap): add gap closure phases {N}-{M}" --files .planning/ROADMAP.md .planning/REQUIREMENTS.md
|
||||
```
|
||||
|
||||
## 10. Offer Next Steps
|
||||
|
||||
```markdown
|
||||
## ✓ Gap Closure Phases Created
|
||||
|
||||
**Phases added:** {N} - {M}
|
||||
**Gaps addressed:** {count} requirements, {count} integration, {count} flows
|
||||
|
||||
---
|
||||
|
||||
## ▶ Next Up
|
||||
|
||||
**Plan first gap closure phase**
|
||||
|
||||
`/gsd:plan-phase {N}`
|
||||
|
||||
<sub>`/clear` first → fresh context window</sub>
|
||||
|
||||
---
|
||||
|
||||
**Also available:**
|
||||
- `/gsd:execute-phase {N}` — if plans already exist
|
||||
- `cat .planning/ROADMAP.md` — see updated roadmap
|
||||
|
||||
---
|
||||
|
||||
**After all gap phases complete:**
|
||||
|
||||
`/gsd:audit-milestone` — re-audit to verify gaps closed
|
||||
`/gsd:complete-milestone {version}` — archive when audit passes
|
||||
```
|
||||
|
||||
</process>
|
||||
|
||||
<gap_to_phase_mapping>
|
||||
|
||||
## How Gaps Become Tasks
|
||||
|
||||
**Requirement gap → Tasks:**
|
||||
```yaml
|
||||
gap:
|
||||
id: DASH-01
|
||||
description: "User sees their data"
|
||||
reason: "Dashboard exists but doesn't fetch from API"
|
||||
missing:
|
||||
- "useEffect with fetch to /api/user/data"
|
||||
- "State for user data"
|
||||
- "Render user data in JSX"
|
||||
|
||||
becomes:
|
||||
|
||||
phase: "Wire Dashboard Data"
|
||||
tasks:
|
||||
- name: "Add data fetching"
|
||||
files: [src/components/Dashboard.tsx]
|
||||
action: "Add useEffect that fetches /api/user/data on mount"
|
||||
|
||||
- name: "Add state management"
|
||||
files: [src/components/Dashboard.tsx]
|
||||
action: "Add useState for userData, loading, error states"
|
||||
|
||||
- name: "Render user data"
|
||||
files: [src/components/Dashboard.tsx]
|
||||
action: "Replace placeholder with userData.map rendering"
|
||||
```
|
||||
|
||||
**Integration gap → Tasks:**
|
||||
```yaml
|
||||
gap:
|
||||
from_phase: 1
|
||||
to_phase: 3
|
||||
connection: "Auth token → API calls"
|
||||
reason: "Dashboard API calls don't include auth header"
|
||||
missing:
|
||||
- "Auth header in fetch calls"
|
||||
- "Token refresh on 401"
|
||||
|
||||
becomes:
|
||||
|
||||
phase: "Add Auth to Dashboard API Calls"
|
||||
tasks:
|
||||
- name: "Add auth header to fetches"
|
||||
files: [src/components/Dashboard.tsx, src/lib/api.ts]
|
||||
action: "Include Authorization header with token in all API calls"
|
||||
|
||||
- name: "Handle 401 responses"
|
||||
files: [src/lib/api.ts]
|
||||
action: "Add interceptor to refresh token or redirect to login on 401"
|
||||
```
|
||||
|
||||
**Flow gap → Tasks:**
|
||||
```yaml
|
||||
gap:
|
||||
name: "User views dashboard after login"
|
||||
broken_at: "Dashboard data load"
|
||||
reason: "No fetch call"
|
||||
missing:
|
||||
- "Fetch user data on mount"
|
||||
- "Display loading state"
|
||||
- "Render user data"
|
||||
|
||||
becomes:
|
||||
|
||||
# Usually same phase as requirement/integration gap
|
||||
# Flow gaps often overlap with other gap types
|
||||
```
|
||||
|
||||
</gap_to_phase_mapping>
|
||||
|
||||
<success_criteria>
|
||||
- [ ] MILESTONE-AUDIT.md loaded and gaps parsed
|
||||
- [ ] Gaps prioritized (must/should/nice)
|
||||
- [ ] Gaps grouped into logical phases
|
||||
- [ ] User confirmed phase plan
|
||||
- [ ] ROADMAP.md updated with new phases
|
||||
- [ ] REQUIREMENTS.md traceability table updated with gap closure phase assignments
|
||||
- [ ] Unsatisfied requirement checkboxes reset (`[x]` → `[ ]`)
|
||||
- [ ] Coverage count updated in REQUIREMENTS.md
|
||||
- [ ] Phase directories created
|
||||
- [ ] Changes committed (includes REQUIREMENTS.md)
|
||||
- [ ] User knows to run `/gsd:plan-phase` next
|
||||
</success_criteria>
|
||||
754
get-shit-done/workflows/plan-phase.md
Normal file
754
get-shit-done/workflows/plan-phase.md
Normal file
@@ -0,0 +1,754 @@
|
||||
<purpose>
|
||||
Create executable phase prompts (PLAN.md files) for a roadmap phase with integrated research and verification. Default flow: Research (if needed) -> Plan -> Verify -> Done. Orchestrates gsd-phase-researcher, gsd-planner, and gsd-plan-checker agents with a revision loop (max 3 iterations).
|
||||
</purpose>
|
||||
|
||||
<required_reading>
|
||||
Read all files referenced by the invoking prompt's execution_context before starting.
|
||||
|
||||
@C:/Users/yaoji/.claude/get-shit-done/references/ui-brand.md
|
||||
</required_reading>
|
||||
|
||||
<available_agent_types>
|
||||
Valid GSD subagent types (use exact names — do not fall back to 'general-purpose'):
|
||||
- gsd-phase-researcher — Researches technical approaches for a phase
|
||||
- gsd-planner — Creates detailed plans from phase scope
|
||||
- gsd-plan-checker — Reviews plan quality before execution
|
||||
</available_agent_types>
|
||||
|
||||
<process>
|
||||
|
||||
## 1. Initialize
|
||||
|
||||
Load all context in one call (paths only to minimize orchestrator context):
|
||||
|
||||
```bash
|
||||
INIT=$(node "C:/Users/yaoji/.claude/get-shit-done/bin/gsd-tools.cjs" init plan-phase "$PHASE")
|
||||
if [[ "$INIT" == @file:* ]]; then INIT=$(cat "${INIT#@file:}"); fi
|
||||
```
|
||||
|
||||
Parse JSON for: `researcher_model`, `planner_model`, `checker_model`, `research_enabled`, `plan_checker_enabled`, `nyquist_validation_enabled`, `commit_docs`, `phase_found`, `phase_dir`, `phase_number`, `phase_name`, `phase_slug`, `padded_phase`, `has_research`, `has_context`, `has_plans`, `plan_count`, `planning_exists`, `roadmap_exists`, `phase_req_ids`.
|
||||
|
||||
**File paths (for <files_to_read> blocks):** `state_path`, `roadmap_path`, `requirements_path`, `context_path`, `research_path`, `verification_path`, `uat_path`. These are null if files don't exist.
|
||||
|
||||
**If `planning_exists` is false:** Error — run `/gsd:new-project` first.
|
||||
|
||||
## 2. Parse and Normalize Arguments
|
||||
|
||||
Extract from $ARGUMENTS: phase number (integer or decimal like `2.1`), flags (`--research`, `--skip-research`, `--gaps`, `--skip-verify`, `--prd <filepath>`).
|
||||
|
||||
Extract `--prd <filepath>` from $ARGUMENTS. If present, set PRD_FILE to the filepath.
|
||||
|
||||
**If no phase number:** Detect next unplanned phase from roadmap.
|
||||
|
||||
**If `phase_found` is false:** Validate phase exists in ROADMAP.md. If valid, create the directory using `phase_slug` and `padded_phase` from init:
|
||||
```bash
|
||||
mkdir -p ".planning/phases/${padded_phase}-${phase_slug}"
|
||||
```
|
||||
|
||||
**Existing artifacts from init:** `has_research`, `has_plans`, `plan_count`.
|
||||
|
||||
## 3. Validate Phase
|
||||
|
||||
```bash
|
||||
PHASE_INFO=$(node "C:/Users/yaoji/.claude/get-shit-done/bin/gsd-tools.cjs" roadmap get-phase "${PHASE}")
|
||||
```
|
||||
|
||||
**If `found` is false:** Error with available phases. **If `found` is true:** Extract `phase_number`, `phase_name`, `goal` from JSON.
|
||||
|
||||
## 3.5. Handle PRD Express Path
|
||||
|
||||
**Skip if:** No `--prd` flag in arguments.
|
||||
|
||||
**If `--prd <filepath>` provided:**
|
||||
|
||||
1. Read the PRD file:
|
||||
```bash
|
||||
PRD_CONTENT=$(cat "$PRD_FILE" 2>/dev/null)
|
||||
if [ -z "$PRD_CONTENT" ]; then
|
||||
echo "Error: PRD file not found: $PRD_FILE"
|
||||
exit 1
|
||||
fi
|
||||
```
|
||||
|
||||
2. Display banner:
|
||||
```
|
||||
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
|
||||
GSD ► PRD EXPRESS PATH
|
||||
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
|
||||
|
||||
Using PRD: {PRD_FILE}
|
||||
Generating CONTEXT.md from requirements...
|
||||
```
|
||||
|
||||
3. Parse the PRD content and generate CONTEXT.md. The orchestrator should:
|
||||
- Extract all requirements, user stories, acceptance criteria, and constraints from the PRD
|
||||
- Map each to a locked decision (everything in the PRD is treated as a locked decision)
|
||||
- Identify any areas the PRD doesn't cover and mark as "Claude's Discretion"
|
||||
- **Extract canonical refs** from ROADMAP.md for this phase, plus any specs/ADRs referenced in the PRD — expand to full file paths (MANDATORY)
|
||||
- Create CONTEXT.md in the phase directory
|
||||
|
||||
4. Write CONTEXT.md:
|
||||
```markdown
|
||||
# Phase [X]: [Name] - Context
|
||||
|
||||
**Gathered:** [date]
|
||||
**Status:** Ready for planning
|
||||
**Source:** PRD Express Path ({PRD_FILE})
|
||||
|
||||
<domain>
|
||||
## Phase Boundary
|
||||
|
||||
[Extracted from PRD — what this phase delivers]
|
||||
|
||||
</domain>
|
||||
|
||||
<decisions>
|
||||
## Implementation Decisions
|
||||
|
||||
{For each requirement/story/criterion in the PRD:}
|
||||
### [Category derived from content]
|
||||
- [Requirement as locked decision]
|
||||
|
||||
### Claude's Discretion
|
||||
[Areas not covered by PRD — implementation details, technical choices]
|
||||
|
||||
</decisions>
|
||||
|
||||
<canonical_refs>
|
||||
## Canonical References
|
||||
|
||||
**Downstream agents MUST read these before planning or implementing.**
|
||||
|
||||
[MANDATORY. Extract from ROADMAP.md and any docs referenced in the PRD.
|
||||
Use full relative paths. Group by topic area.]
|
||||
|
||||
### [Topic area]
|
||||
- `path/to/spec-or-adr.md` — [What it decides/defines]
|
||||
|
||||
[If no external specs: "No external specs — requirements fully captured in decisions above"]
|
||||
|
||||
</canonical_refs>
|
||||
|
||||
<specifics>
|
||||
## Specific Ideas
|
||||
|
||||
[Any specific references, examples, or concrete requirements from PRD]
|
||||
|
||||
</specifics>
|
||||
|
||||
<deferred>
|
||||
## Deferred Ideas
|
||||
|
||||
[Items in PRD explicitly marked as future/v2/out-of-scope]
|
||||
[If none: "None — PRD covers phase scope"]
|
||||
|
||||
</deferred>
|
||||
|
||||
---
|
||||
|
||||
*Phase: XX-name*
|
||||
*Context gathered: [date] via PRD Express Path*
|
||||
```
|
||||
|
||||
5. Commit:
|
||||
```bash
|
||||
node "C:/Users/yaoji/.claude/get-shit-done/bin/gsd-tools.cjs" commit "docs(${padded_phase}): generate context from PRD" --files "${phase_dir}/${padded_phase}-CONTEXT.md"
|
||||
```
|
||||
|
||||
6. Set `context_content` to the generated CONTEXT.md content and continue to step 5 (Handle Research).
|
||||
|
||||
**Effect:** This completely bypasses step 4 (Load CONTEXT.md) since we just created it. The rest of the workflow (research, planning, verification) proceeds normally with the PRD-derived context.
|
||||
|
||||
## 4. Load CONTEXT.md
|
||||
|
||||
**Skip if:** PRD express path was used (CONTEXT.md already created in step 3.5).
|
||||
|
||||
Check `context_path` from init JSON.
|
||||
|
||||
If `context_path` is not null, display: `Using phase context from: ${context_path}`
|
||||
|
||||
**If `context_path` is null (no CONTEXT.md exists):**
|
||||
|
||||
Use AskUserQuestion:
|
||||
- header: "No context"
|
||||
- question: "No CONTEXT.md found for Phase {X}. Plans will use research and requirements only — your design preferences won't be included. Continue or capture context first?"
|
||||
- options:
|
||||
- "Continue without context" — Plan using research + requirements only
|
||||
- "Run discuss-phase first" — Capture design decisions before planning
|
||||
|
||||
If "Continue without context": Proceed to step 5.
|
||||
If "Run discuss-phase first":
|
||||
**IMPORTANT:** Do NOT invoke discuss-phase as a nested Skill/Task call — AskUserQuestion
|
||||
does not work correctly in nested subcontexts (#1009). Instead, display the command
|
||||
and exit so the user runs it as a top-level command:
|
||||
```
|
||||
Run this command first, then re-run /gsd:plan-phase {X}:
|
||||
|
||||
/gsd:discuss-phase {X}
|
||||
```
|
||||
**Exit the plan-phase workflow. Do not continue.**
|
||||
|
||||
## 5. Handle Research
|
||||
|
||||
**Skip if:** `--gaps` flag or `--skip-research` flag.
|
||||
|
||||
**If `has_research` is true (from init) AND no `--research` flag:** Use existing, skip to step 6.
|
||||
|
||||
**If RESEARCH.md missing OR `--research` flag:**
|
||||
|
||||
**If no explicit flag (`--research` or `--skip-research`) and not `--auto`:**
|
||||
Ask the user whether to research, with a contextual recommendation based on the phase:
|
||||
|
||||
```
|
||||
AskUserQuestion([
|
||||
{
|
||||
question: "Research before planning Phase {X}: {phase_name}?",
|
||||
header: "Research",
|
||||
multiSelect: false,
|
||||
options: [
|
||||
{ label: "Research first (Recommended)", description: "Investigate domain, patterns, and dependencies before planning. Best for new features, unfamiliar integrations, or architectural changes." },
|
||||
{ label: "Skip research", description: "Plan directly from context and requirements. Best for bug fixes, simple refactors, or well-understood tasks." }
|
||||
]
|
||||
}
|
||||
])
|
||||
```
|
||||
|
||||
If user selects "Skip research": skip to step 6.
|
||||
|
||||
**If `--auto` and `research_enabled` is false:** Skip research silently (preserves automated behavior).
|
||||
|
||||
Display banner:
|
||||
```
|
||||
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
|
||||
GSD ► RESEARCHING PHASE {X}
|
||||
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
|
||||
|
||||
◆ Spawning researcher...
|
||||
```
|
||||
|
||||
### Spawn gsd-phase-researcher
|
||||
|
||||
```bash
|
||||
PHASE_DESC=$(node "C:/Users/yaoji/.claude/get-shit-done/bin/gsd-tools.cjs" roadmap get-phase "${PHASE}" | jq -r '.section')
|
||||
```
|
||||
|
||||
Research prompt:
|
||||
|
||||
```markdown
|
||||
<objective>
|
||||
Research how to implement Phase {phase_number}: {phase_name}
|
||||
Answer: "What do I need to know to PLAN this phase well?"
|
||||
</objective>
|
||||
|
||||
<files_to_read>
|
||||
- {context_path} (USER DECISIONS from /gsd:discuss-phase)
|
||||
- {requirements_path} (Project requirements)
|
||||
- {state_path} (Project decisions and history)
|
||||
</files_to_read>
|
||||
|
||||
<additional_context>
|
||||
**Phase description:** {phase_description}
|
||||
**Phase requirement IDs (MUST address):** {phase_req_ids}
|
||||
|
||||
**Project instructions:** Read ./CLAUDE.md if exists — follow project-specific guidelines
|
||||
**Project skills:** Check .claude/skills/ or .agents/skills/ directory (if either exists) — read SKILL.md files, research should account for project skill patterns
|
||||
</additional_context>
|
||||
|
||||
<output>
|
||||
Write to: {phase_dir}/{phase_num}-RESEARCH.md
|
||||
</output>
|
||||
```
|
||||
|
||||
```
|
||||
Task(
|
||||
prompt=research_prompt,
|
||||
subagent_type="gsd-phase-researcher",
|
||||
model="{researcher_model}",
|
||||
description="Research Phase {phase}"
|
||||
)
|
||||
```
|
||||
|
||||
### Handle Researcher Return
|
||||
|
||||
- **`## RESEARCH COMPLETE`:** Display confirmation, continue to step 6
|
||||
- **`## RESEARCH BLOCKED`:** Display blocker, offer: 1) Provide context, 2) Skip research, 3) Abort
|
||||
|
||||
## 5.5. Create Validation Strategy
|
||||
|
||||
Skip if `nyquist_validation_enabled` is false OR `research_enabled` is false.
|
||||
|
||||
If `research_enabled` is false and `nyquist_validation_enabled` is true: warn "Nyquist validation enabled but research disabled — VALIDATION.md cannot be created without RESEARCH.md. Plans will lack validation requirements (Dimension 8)." Continue to step 6.
|
||||
|
||||
**But Nyquist is not applicable for this run** when all of the following are true:
|
||||
- `research_enabled` is false
|
||||
- `has_research` is false
|
||||
- no `--research` flag was provided
|
||||
|
||||
In that case: **skip validation-strategy creation entirely**. Do **not** expect `RESEARCH.md` or `VALIDATION.md` for this run, and continue to Step 6.
|
||||
|
||||
```bash
|
||||
grep -l "## Validation Architecture" "${PHASE_DIR}"/*-RESEARCH.md 2>/dev/null
|
||||
```
|
||||
|
||||
**If found:**
|
||||
1. Read template: `C:/Users/yaoji/.claude/get-shit-done/templates/VALIDATION.md`
|
||||
2. Write to `${PHASE_DIR}/${PADDED_PHASE}-VALIDATION.md` (use Write tool)
|
||||
3. Fill frontmatter: `{N}` → phase number, `{phase-slug}` → slug, `{date}` → current date
|
||||
4. Verify:
|
||||
```bash
|
||||
test -f "${PHASE_DIR}/${PADDED_PHASE}-VALIDATION.md" && echo "VALIDATION_CREATED=true" || echo "VALIDATION_CREATED=false"
|
||||
```
|
||||
5. If `VALIDATION_CREATED=false`: STOP — do not proceed to Step 6
|
||||
6. If `commit_docs`: `commit "docs(phase-${PHASE}): add validation strategy"`
|
||||
|
||||
**If not found:** Warn and continue — plans may fail Dimension 8.
|
||||
|
||||
## 5.6. UI Design Contract Gate
|
||||
|
||||
> Skip if `workflow.ui_phase` is explicitly `false` AND `workflow.ui_safety_gate` is explicitly `false` in `.planning/config.json`. If keys are absent, treat as enabled.
|
||||
|
||||
```bash
|
||||
UI_PHASE_CFG=$(node "C:/Users/yaoji/.claude/get-shit-done/bin/gsd-tools.cjs" config-get workflow.ui_phase 2>/dev/null || echo "true")
|
||||
UI_GATE_CFG=$(node "C:/Users/yaoji/.claude/get-shit-done/bin/gsd-tools.cjs" config-get workflow.ui_safety_gate 2>/dev/null || echo "true")
|
||||
```
|
||||
|
||||
**If both are `false`:** Skip to step 6.
|
||||
|
||||
Check if phase has frontend indicators:
|
||||
|
||||
```bash
|
||||
PHASE_SECTION=$(node "C:/Users/yaoji/.claude/get-shit-done/bin/gsd-tools.cjs" roadmap get-phase "${PHASE}" 2>/dev/null)
|
||||
echo "$PHASE_SECTION" | grep -iE "UI|interface|frontend|component|layout|page|screen|view|form|dashboard|widget" > /dev/null 2>&1
|
||||
HAS_UI=$?
|
||||
```
|
||||
|
||||
**If `HAS_UI` is 0 (frontend indicators found):**
|
||||
|
||||
Check for existing UI-SPEC:
|
||||
```bash
|
||||
UI_SPEC_FILE=$(ls "${PHASE_DIR}"/*-UI-SPEC.md 2>/dev/null | head -1)
|
||||
```
|
||||
|
||||
**If UI-SPEC.md found:** Set `UI_SPEC_PATH=$UI_SPEC_FILE`. Display: `Using UI design contract: ${UI_SPEC_PATH}`
|
||||
|
||||
**If UI-SPEC.md missing AND `UI_GATE_CFG` is `true`:**
|
||||
|
||||
Use AskUserQuestion:
|
||||
- header: "UI Design Contract"
|
||||
- question: "Phase {N} has frontend indicators but no UI-SPEC.md. Generate a design contract before planning?"
|
||||
- options:
|
||||
- "Generate UI-SPEC first" → Display: "Run `/gsd:ui-phase {N}` then re-run `/gsd:plan-phase {N}`". Exit workflow.
|
||||
- "Continue without UI-SPEC" → Continue to step 6.
|
||||
- "Not a frontend phase" → Continue to step 6.
|
||||
|
||||
**If `HAS_UI` is 1 (no frontend indicators):** Skip silently to step 6.
|
||||
|
||||
## 6. Check Existing Plans
|
||||
|
||||
```bash
|
||||
ls "${PHASE_DIR}"/*-PLAN.md 2>/dev/null
|
||||
```
|
||||
|
||||
**If exists:** Offer: 1) Add more plans, 2) View existing, 3) Replan from scratch.
|
||||
|
||||
## 7. Use Context Paths from INIT
|
||||
|
||||
Extract from INIT JSON:
|
||||
|
||||
```bash
|
||||
STATE_PATH=$(printf '%s\n' "$INIT" | jq -r '.state_path // empty')
|
||||
ROADMAP_PATH=$(printf '%s\n' "$INIT" | jq -r '.roadmap_path // empty')
|
||||
REQUIREMENTS_PATH=$(printf '%s\n' "$INIT" | jq -r '.requirements_path // empty')
|
||||
RESEARCH_PATH=$(printf '%s\n' "$INIT" | jq -r '.research_path // empty')
|
||||
VERIFICATION_PATH=$(printf '%s\n' "$INIT" | jq -r '.verification_path // empty')
|
||||
UAT_PATH=$(printf '%s\n' "$INIT" | jq -r '.uat_path // empty')
|
||||
CONTEXT_PATH=$(printf '%s\n' "$INIT" | jq -r '.context_path // empty')
|
||||
```
|
||||
|
||||
## 7.5. Verify Nyquist Artifacts
|
||||
|
||||
Skip if `nyquist_validation_enabled` is false OR `research_enabled` is false.
|
||||
|
||||
Also skip if all of the following are true:
|
||||
- `research_enabled` is false
|
||||
- `has_research` is false
|
||||
- no `--research` flag was provided
|
||||
|
||||
In that no-research path, Nyquist artifacts are **not required** for this run.
|
||||
|
||||
```bash
|
||||
VALIDATION_EXISTS=$(ls "${PHASE_DIR}"/*-VALIDATION.md 2>/dev/null | head -1)
|
||||
```
|
||||
|
||||
If missing and Nyquist is still enabled/applicable — ask user:
|
||||
1. Re-run: `/gsd:plan-phase {PHASE} --research`
|
||||
2. Disable Nyquist with the exact command:
|
||||
`node "C:/Users/yaoji/.claude/get-shit-done/bin/gsd-tools.cjs" config-set workflow.nyquist_validation false`
|
||||
3. Continue anyway (plans fail Dimension 8)
|
||||
|
||||
Proceed to Step 8 only if user selects 2 or 3.
|
||||
|
||||
## 8. Spawn gsd-planner Agent
|
||||
|
||||
Display banner:
|
||||
```
|
||||
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
|
||||
GSD ► PLANNING PHASE {X}
|
||||
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
|
||||
|
||||
◆ Spawning planner...
|
||||
```
|
||||
|
||||
Planner prompt:
|
||||
|
||||
```markdown
|
||||
<planning_context>
|
||||
**Phase:** {phase_number}
|
||||
**Mode:** {standard | gap_closure}
|
||||
|
||||
<files_to_read>
|
||||
- {state_path} (Project State)
|
||||
- {roadmap_path} (Roadmap)
|
||||
- {requirements_path} (Requirements)
|
||||
- {context_path} (USER DECISIONS from /gsd:discuss-phase)
|
||||
- {research_path} (Technical Research)
|
||||
- {verification_path} (Verification Gaps - if --gaps)
|
||||
- {uat_path} (UAT Gaps - if --gaps)
|
||||
- {UI_SPEC_PATH} (UI Design Contract — visual/interaction specs, if exists)
|
||||
</files_to_read>
|
||||
|
||||
**Phase requirement IDs (every ID MUST appear in a plan's `requirements` field):** {phase_req_ids}
|
||||
|
||||
**Project instructions:** Read ./CLAUDE.md if exists — follow project-specific guidelines
|
||||
**Project skills:** Check .claude/skills/ or .agents/skills/ directory (if either exists) — read SKILL.md files, plans should account for project skill rules
|
||||
</planning_context>
|
||||
|
||||
<downstream_consumer>
|
||||
Output consumed by /gsd:execute-phase. Plans need:
|
||||
- Frontmatter (wave, depends_on, files_modified, autonomous)
|
||||
- Tasks in XML format with read_first and acceptance_criteria fields (MANDATORY on every task)
|
||||
- Verification criteria
|
||||
- must_haves for goal-backward verification
|
||||
</downstream_consumer>
|
||||
|
||||
<deep_work_rules>
|
||||
## Anti-Shallow Execution Rules (MANDATORY)
|
||||
|
||||
Every task MUST include these fields — they are NOT optional:
|
||||
|
||||
1. **`<read_first>`** — Files the executor MUST read before touching anything. Always include:
|
||||
- The file being modified (so executor sees current state, not assumptions)
|
||||
- Any "source of truth" file referenced in CONTEXT.md (reference implementations, existing patterns, config files, schemas)
|
||||
- Any file whose patterns, signatures, types, or conventions must be replicated or respected
|
||||
|
||||
2. **`<acceptance_criteria>`** — Verifiable conditions that prove the task was done correctly. Rules:
|
||||
- Every criterion must be checkable with grep, file read, test command, or CLI output
|
||||
- NEVER use subjective language ("looks correct", "properly configured", "consistent with")
|
||||
- ALWAYS include exact strings, patterns, values, or command outputs that must be present
|
||||
- Examples:
|
||||
- Code: `auth.py contains def verify_token(` / `test_auth.py exits 0`
|
||||
- Config: `.env.example contains DATABASE_URL=` / `Dockerfile contains HEALTHCHECK`
|
||||
- Docs: `README.md contains '## Installation'` / `API.md lists all endpoints`
|
||||
- Infra: `deploy.yml has rollback step` / `docker-compose.yml has healthcheck for db`
|
||||
|
||||
3. **`<action>`** — Must include CONCRETE values, not references. Rules:
|
||||
- NEVER say "align X with Y", "match X to Y", "update to be consistent" without specifying the exact target state
|
||||
- ALWAYS include the actual values: config keys, function signatures, SQL statements, class names, import paths, env vars, etc.
|
||||
- If CONTEXT.md has a comparison table or expected values, copy them into the action verbatim
|
||||
- The executor should be able to complete the task from the action text alone, without needing to read CONTEXT.md or reference files (read_first is for verification, not discovery)
|
||||
|
||||
**Why this matters:** Executor agents work from the plan text. Vague instructions like "update the config to match production" produce shallow one-line changes. Concrete instructions like "add DATABASE_URL=postgresql://... , set POOL_SIZE=20, add REDIS_URL=redis://..." produce complete work. The cost of verbose plans is far less than the cost of re-doing shallow execution.
|
||||
</deep_work_rules>
|
||||
|
||||
<quality_gate>
|
||||
- [ ] PLAN.md files created in phase directory
|
||||
- [ ] Each plan has valid frontmatter
|
||||
- [ ] Tasks are specific and actionable
|
||||
- [ ] Every task has `<read_first>` with at least the file being modified
|
||||
- [ ] Every task has `<acceptance_criteria>` with grep-verifiable conditions
|
||||
- [ ] Every `<action>` contains concrete values (no "align X with Y" without specifying what)
|
||||
- [ ] Dependencies correctly identified
|
||||
- [ ] Waves assigned for parallel execution
|
||||
- [ ] must_haves derived from phase goal
|
||||
</quality_gate>
|
||||
```
|
||||
|
||||
```
|
||||
Task(
|
||||
prompt=filled_prompt,
|
||||
subagent_type="gsd-planner",
|
||||
model="{planner_model}",
|
||||
description="Plan Phase {phase}"
|
||||
)
|
||||
```
|
||||
|
||||
## 9. Handle Planner Return
|
||||
|
||||
- **`## PLANNING COMPLETE`:** Display plan count. If `--skip-verify` or `plan_checker_enabled` is false (from init): skip to step 13. Otherwise: step 10.
|
||||
- **`## CHECKPOINT REACHED`:** Present to user, get response, spawn continuation (step 12)
|
||||
- **`## PLANNING INCONCLUSIVE`:** Show attempts, offer: Add context / Retry / Manual
|
||||
|
||||
## 10. Spawn gsd-plan-checker Agent
|
||||
|
||||
Display banner:
|
||||
```
|
||||
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
|
||||
GSD ► VERIFYING PLANS
|
||||
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
|
||||
|
||||
◆ Spawning plan checker...
|
||||
```
|
||||
|
||||
Checker prompt:
|
||||
|
||||
```markdown
|
||||
<verification_context>
|
||||
**Phase:** {phase_number}
|
||||
**Phase Goal:** {goal from ROADMAP}
|
||||
|
||||
<files_to_read>
|
||||
- {PHASE_DIR}/*-PLAN.md (Plans to verify)
|
||||
- {roadmap_path} (Roadmap)
|
||||
- {requirements_path} (Requirements)
|
||||
- {context_path} (USER DECISIONS from /gsd:discuss-phase)
|
||||
- {research_path} (Technical Research — includes Validation Architecture)
|
||||
</files_to_read>
|
||||
|
||||
**Phase requirement IDs (MUST ALL be covered):** {phase_req_ids}
|
||||
|
||||
**Project instructions:** Read ./CLAUDE.md if exists — verify plans honor project guidelines
|
||||
**Project skills:** Check .claude/skills/ or .agents/skills/ directory (if either exists) — verify plans account for project skill rules
|
||||
</verification_context>
|
||||
|
||||
<expected_output>
|
||||
- ## VERIFICATION PASSED — all checks pass
|
||||
- ## ISSUES FOUND — structured issue list
|
||||
</expected_output>
|
||||
```
|
||||
|
||||
```
|
||||
Task(
|
||||
prompt=checker_prompt,
|
||||
subagent_type="gsd-plan-checker",
|
||||
model="{checker_model}",
|
||||
description="Verify Phase {phase} plans"
|
||||
)
|
||||
```
|
||||
|
||||
## 11. Handle Checker Return
|
||||
|
||||
- **`## VERIFICATION PASSED`:** Display confirmation, proceed to step 13.
|
||||
- **`## ISSUES FOUND`:** Display issues, check iteration count, proceed to step 12.
|
||||
|
||||
## 12. Revision Loop (Max 3 Iterations)
|
||||
|
||||
Track `iteration_count` (starts at 1 after initial plan + check).
|
||||
|
||||
**If iteration_count < 3:**
|
||||
|
||||
Display: `Sending back to planner for revision... (iteration {N}/3)`
|
||||
|
||||
Revision prompt:
|
||||
|
||||
```markdown
|
||||
<revision_context>
|
||||
**Phase:** {phase_number}
|
||||
**Mode:** revision
|
||||
|
||||
<files_to_read>
|
||||
- {PHASE_DIR}/*-PLAN.md (Existing plans)
|
||||
- {context_path} (USER DECISIONS from /gsd:discuss-phase)
|
||||
</files_to_read>
|
||||
|
||||
**Checker issues:** {structured_issues_from_checker}
|
||||
</revision_context>
|
||||
|
||||
<instructions>
|
||||
Make targeted updates to address checker issues.
|
||||
Do NOT replan from scratch unless issues are fundamental.
|
||||
Return what changed.
|
||||
</instructions>
|
||||
```
|
||||
|
||||
```
|
||||
Task(
|
||||
prompt=revision_prompt,
|
||||
subagent_type="gsd-planner",
|
||||
model="{planner_model}",
|
||||
description="Revise Phase {phase} plans"
|
||||
)
|
||||
```
|
||||
|
||||
After planner returns -> spawn checker again (step 10), increment iteration_count.
|
||||
|
||||
**If iteration_count >= 3:**
|
||||
|
||||
Display: `Max iterations reached. {N} issues remain:` + issue list
|
||||
|
||||
Offer: 1) Force proceed, 2) Provide guidance and retry, 3) Abandon
|
||||
|
||||
## 13. Requirements Coverage Gate
|
||||
|
||||
After plans pass the checker (or checker is skipped), verify that all phase requirements are covered by at least one plan.
|
||||
|
||||
**Skip if:** `phase_req_ids` is null or TBD (no requirements mapped to this phase).
|
||||
|
||||
**Step 1: Extract requirement IDs claimed by plans**
|
||||
```bash
|
||||
# Collect all requirement IDs from plan frontmatter
|
||||
PLAN_REQS=$(grep -h "requirements_addressed\|requirements:" ${PHASE_DIR}/*-PLAN.md 2>/dev/null | tr -d '[]' | tr ',' '\n' | sed 's/^[[:space:]]*//' | sort -u)
|
||||
```
|
||||
|
||||
**Step 2: Compare against phase requirements from ROADMAP**
|
||||
|
||||
For each REQ-ID in `phase_req_ids`:
|
||||
- If REQ-ID appears in `PLAN_REQS` → covered ✓
|
||||
- If REQ-ID does NOT appear in any plan → uncovered ✗
|
||||
|
||||
**Step 3: Check CONTEXT.md features against plan objectives**
|
||||
|
||||
Read CONTEXT.md `<decisions>` section. Extract feature/capability names. Check each against plan `<objective>` blocks. Features not mentioned in any plan objective → potentially dropped.
|
||||
|
||||
**Step 4: Report**
|
||||
|
||||
If all requirements covered and no dropped features:
|
||||
```
|
||||
✓ Requirements coverage: {N}/{N} REQ-IDs covered by plans
|
||||
```
|
||||
→ Proceed to step 14.
|
||||
|
||||
If gaps found:
|
||||
```
|
||||
## ⚠ Requirements Coverage Gap
|
||||
|
||||
{M} of {N} phase requirements are not assigned to any plan:
|
||||
|
||||
| REQ-ID | Description | Plans |
|
||||
|--------|-------------|-------|
|
||||
| {id} | {from REQUIREMENTS.md} | None |
|
||||
|
||||
{K} CONTEXT.md features not found in plan objectives:
|
||||
- {feature_name} — described in CONTEXT.md but no plan covers it
|
||||
|
||||
Options:
|
||||
1. Re-plan to include missing requirements (recommended)
|
||||
2. Move uncovered requirements to next phase
|
||||
3. Proceed anyway — accept coverage gaps
|
||||
```
|
||||
|
||||
Use AskUserQuestion to present the options.
|
||||
|
||||
## 14. Present Final Status
|
||||
|
||||
Route to `<offer_next>` OR `auto_advance` depending on flags/config.
|
||||
|
||||
## 15. Auto-Advance Check
|
||||
|
||||
Check for auto-advance trigger:
|
||||
|
||||
1. Parse `--auto` flag from $ARGUMENTS
|
||||
2. **Sync chain flag with intent** — if user invoked manually (no `--auto`), clear the ephemeral chain flag from any previous interrupted `--auto` chain. This does NOT touch `workflow.auto_advance` (the user's persistent settings preference):
|
||||
```bash
|
||||
if [[ ! "$ARGUMENTS" =~ --auto ]]; then
|
||||
node "C:/Users/yaoji/.claude/get-shit-done/bin/gsd-tools.cjs" config-set workflow._auto_chain_active false 2>/dev/null
|
||||
fi
|
||||
```
|
||||
3. Read both the chain flag and user preference:
|
||||
```bash
|
||||
AUTO_CHAIN=$(node "C:/Users/yaoji/.claude/get-shit-done/bin/gsd-tools.cjs" config-get workflow._auto_chain_active 2>/dev/null || echo "false")
|
||||
AUTO_CFG=$(node "C:/Users/yaoji/.claude/get-shit-done/bin/gsd-tools.cjs" config-get workflow.auto_advance 2>/dev/null || echo "false")
|
||||
```
|
||||
|
||||
**If `--auto` flag present OR `AUTO_CHAIN` is true OR `AUTO_CFG` is true:**
|
||||
|
||||
Display banner:
|
||||
```
|
||||
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
|
||||
GSD ► AUTO-ADVANCING TO EXECUTE
|
||||
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
|
||||
|
||||
Plans ready. Launching execute-phase...
|
||||
```
|
||||
|
||||
Launch execute-phase using the Skill tool to avoid nested Task sessions (which cause runtime freezes due to deep agent nesting):
|
||||
```
|
||||
Skill(skill="gsd:execute-phase", args="${PHASE} --auto --no-transition")
|
||||
```
|
||||
|
||||
The `--no-transition` flag tells execute-phase to return status after verification instead of chaining further. This keeps the auto-advance chain flat — each phase runs at the same nesting level rather than spawning deeper Task agents.
|
||||
|
||||
**Handle execute-phase return:**
|
||||
- **PHASE COMPLETE** → Display final summary:
|
||||
```
|
||||
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
|
||||
GSD ► PHASE ${PHASE} COMPLETE ✓
|
||||
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
|
||||
|
||||
Auto-advance pipeline finished.
|
||||
|
||||
Next: /gsd:discuss-phase ${NEXT_PHASE} --auto
|
||||
```
|
||||
- **GAPS FOUND / VERIFICATION FAILED** → Display result, stop chain:
|
||||
```
|
||||
Auto-advance stopped: Execution needs review.
|
||||
|
||||
Review the output above and continue manually:
|
||||
/gsd:execute-phase ${PHASE}
|
||||
```
|
||||
|
||||
**If neither `--auto` nor config enabled:**
|
||||
Route to `<offer_next>` (existing behavior).
|
||||
|
||||
</process>
|
||||
|
||||
<offer_next>
|
||||
Output this markdown directly (not as a code block):
|
||||
|
||||
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
|
||||
GSD ► PHASE {X} PLANNED ✓
|
||||
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
|
||||
|
||||
**Phase {X}: {Name}** — {N} plan(s) in {M} wave(s)
|
||||
|
||||
| Wave | Plans | What it builds |
|
||||
|------|-------|----------------|
|
||||
| 1 | 01, 02 | [objectives] |
|
||||
| 2 | 03 | [objective] |
|
||||
|
||||
Research: {Completed | Used existing | Skipped}
|
||||
Verification: {Passed | Passed with override | Skipped}
|
||||
|
||||
───────────────────────────────────────────────────────────────
|
||||
|
||||
## ▶ Next Up
|
||||
|
||||
**Execute Phase {X}** — run all {N} plans
|
||||
|
||||
/gsd:execute-phase {X}
|
||||
|
||||
<sub>/clear first → fresh context window</sub>
|
||||
|
||||
───────────────────────────────────────────────────────────────
|
||||
|
||||
**Also available:**
|
||||
- cat .planning/phases/{phase-dir}/*-PLAN.md — review plans
|
||||
- /gsd:plan-phase {X} --research — re-research first
|
||||
|
||||
───────────────────────────────────────────────────────────────
|
||||
</offer_next>
|
||||
|
||||
<success_criteria>
|
||||
- [ ] .planning/ directory validated
|
||||
- [ ] Phase validated against roadmap
|
||||
- [ ] Phase directory created if needed
|
||||
- [ ] CONTEXT.md loaded early (step 4) and passed to ALL agents
|
||||
- [ ] Research completed (unless --skip-research or --gaps or exists)
|
||||
- [ ] gsd-phase-researcher spawned with CONTEXT.md
|
||||
- [ ] Existing plans checked
|
||||
- [ ] gsd-planner spawned with CONTEXT.md + RESEARCH.md
|
||||
- [ ] Plans created (PLANNING COMPLETE or CHECKPOINT handled)
|
||||
- [ ] gsd-plan-checker spawned with CONTEXT.md
|
||||
- [ ] Verification passed OR user override OR max iterations with user decision
|
||||
- [ ] User sees status between agent spawns
|
||||
- [ ] User knows next steps
|
||||
</success_criteria>
|
||||
450
get-shit-done/workflows/profile-user.md
Normal file
450
get-shit-done/workflows/profile-user.md
Normal file
@@ -0,0 +1,450 @@
|
||||
<purpose>
|
||||
Orchestrate the full developer profiling flow: consent, session analysis (or questionnaire fallback), profile generation, result display, and artifact creation.
|
||||
|
||||
This workflow wires Phase 1 (session pipeline) and Phase 2 (profiling engine) into a cohesive user-facing experience. All heavy lifting is done by existing gsd-tools.cjs subcommands and the gsd-user-profiler agent -- this workflow orchestrates the sequence, handles branching, and provides the UX.
|
||||
</purpose>
|
||||
|
||||
<required_reading>
|
||||
Read all files referenced by the invoking prompt's execution_context before starting.
|
||||
|
||||
Key references:
|
||||
- @C:/Users/yaoji/.claude/get-shit-done/references/ui-brand.md (display patterns)
|
||||
- @C:/Users/yaoji/.claude/get-shit-done/agents/gsd-user-profiler.md (profiler agent definition)
|
||||
- @C:/Users/yaoji/.claude/get-shit-done/references/user-profiling.md (profiling reference doc)
|
||||
</required_reading>
|
||||
|
||||
<process>
|
||||
|
||||
## 1. Initialize
|
||||
|
||||
Parse flags from $ARGUMENTS:
|
||||
- Detect `--questionnaire` flag (skip session analysis, questionnaire-only)
|
||||
- Detect `--refresh` flag (rebuild profile even when one exists)
|
||||
|
||||
Check for existing profile:
|
||||
|
||||
```bash
|
||||
PROFILE_PATH="C:/Users/yaoji/.claude/get-shit-done/USER-PROFILE.md"
|
||||
[ -f "$PROFILE_PATH" ] && echo "EXISTS" || echo "NOT_FOUND"
|
||||
```
|
||||
|
||||
**If profile exists AND --refresh NOT set AND --questionnaire NOT set:**
|
||||
|
||||
Use AskUserQuestion:
|
||||
- header: "Existing Profile"
|
||||
- question: "You already have a profile. What would you like to do?"
|
||||
- options:
|
||||
- "View it" -- Display summary card from existing profile data, then exit
|
||||
- "Refresh it" -- Continue with --refresh behavior
|
||||
- "Cancel" -- Exit workflow
|
||||
|
||||
If "View it": Read USER-PROFILE.md, display its content formatted as a summary card, then exit.
|
||||
If "Refresh it": Set --refresh behavior and continue.
|
||||
If "Cancel": Display "No changes made." and exit.
|
||||
|
||||
**If profile exists AND --refresh IS set:**
|
||||
|
||||
Backup existing profile:
|
||||
```bash
|
||||
cp "C:/Users/yaoji/.claude/get-shit-done/USER-PROFILE.md" "C:/Users/yaoji/.claude/get-shit-done/USER-PROFILE.backup.md"
|
||||
```
|
||||
|
||||
Display: "Re-analyzing your sessions to update your profile."
|
||||
Continue to step 2.
|
||||
|
||||
**If no profile exists:** Continue to step 2.
|
||||
|
||||
---
|
||||
|
||||
## 2. Consent Gate (ACTV-06)
|
||||
|
||||
**Skip if** `--questionnaire` flag is set (no JSONL reading occurs -- jump directly to step 4b).
|
||||
|
||||
Display consent screen:
|
||||
|
||||
```
|
||||
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
|
||||
GSD > PROFILE YOUR CODING STYLE
|
||||
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
|
||||
|
||||
Claude starts every conversation generic. A profile teaches Claude
|
||||
how YOU actually work -- not how you think you work.
|
||||
|
||||
## What We'll Analyze
|
||||
|
||||
Your recent Claude Code sessions, looking for patterns in these
|
||||
8 behavioral dimensions:
|
||||
|
||||
| Dimension | What It Measures |
|
||||
|----------------------|---------------------------------------------|
|
||||
| Communication Style | How you phrase requests (terse vs. detailed) |
|
||||
| Decision Speed | How you choose between options |
|
||||
| Explanation Depth | How much explanation you want with code |
|
||||
| Debugging Approach | How you tackle errors and bugs |
|
||||
| UX Philosophy | How much you care about design vs. function |
|
||||
| Vendor Philosophy | How you evaluate libraries and tools |
|
||||
| Frustration Triggers | What makes you correct Claude |
|
||||
| Learning Style | How you prefer to learn new things |
|
||||
|
||||
## Data Handling
|
||||
|
||||
✓ Reads session files locally (read-only, nothing modified)
|
||||
✓ Analyzes message patterns (not content meaning)
|
||||
✓ Stores profile at C:/Users/yaoji/.claude/get-shit-done/USER-PROFILE.md
|
||||
✗ Nothing is sent to external services
|
||||
✗ Sensitive content (API keys, passwords) is automatically excluded
|
||||
```
|
||||
|
||||
**If --refresh path:**
|
||||
Show abbreviated consent instead:
|
||||
|
||||
```
|
||||
Re-analyzing your sessions to update your profile.
|
||||
Your existing profile has been backed up to USER-PROFILE.backup.md.
|
||||
```
|
||||
|
||||
Use AskUserQuestion:
|
||||
- header: "Refresh"
|
||||
- question: "Continue with profile refresh?"
|
||||
- options:
|
||||
- "Continue" -- Proceed to step 3
|
||||
- "Cancel" -- Exit workflow
|
||||
|
||||
**If default (no --refresh) path:**
|
||||
|
||||
Use AskUserQuestion:
|
||||
- header: "Ready?"
|
||||
- question: "Ready to analyze your sessions?"
|
||||
- options:
|
||||
- "Let's go" -- Proceed to step 3 (session analysis)
|
||||
- "Use questionnaire instead" -- Jump to step 4b (questionnaire path)
|
||||
- "Not now" -- Display "No worries. Run /gsd:profile-user when ready." and exit
|
||||
|
||||
---
|
||||
|
||||
## 3. Session Scan
|
||||
|
||||
Display: "◆ Scanning sessions..."
|
||||
|
||||
Run session scan:
|
||||
```bash
|
||||
SCAN_RESULT=$(node C:/Users/yaoji/.claude/get-shit-done/bin/gsd-tools.cjs scan-sessions --json 2>/dev/null)
|
||||
```
|
||||
|
||||
Parse the JSON output to get session count and project count.
|
||||
|
||||
Display: "✓ Found N sessions across M projects"
|
||||
|
||||
**Determine data sufficiency:**
|
||||
- Count total messages available from the scan result (sum sessions across projects)
|
||||
- If 0 sessions found: Display "No sessions found. Switching to questionnaire." and jump to step 4b
|
||||
- If sessions found: Continue to step 4a
|
||||
|
||||
---
|
||||
|
||||
## 4a. Session Analysis Path
|
||||
|
||||
Display: "◆ Sampling messages..."
|
||||
|
||||
Run profile sampling:
|
||||
```bash
|
||||
SAMPLE_RESULT=$(node C:/Users/yaoji/.claude/get-shit-done/bin/gsd-tools.cjs profile-sample --json 2>/dev/null)
|
||||
```
|
||||
|
||||
Parse the JSON output to get the temp directory path and message count.
|
||||
|
||||
Display: "✓ Sampled N messages from M projects"
|
||||
|
||||
Display: "◆ Analyzing patterns..."
|
||||
|
||||
**Spawn gsd-user-profiler agent using Task tool:**
|
||||
|
||||
Use the Task tool to spawn the `gsd-user-profiler` agent. Provide it with:
|
||||
- The sampled JSONL file path from profile-sample output
|
||||
- The user-profiling reference doc at `C:/Users/yaoji/.claude/get-shit-done/references/user-profiling.md`
|
||||
|
||||
The agent prompt should follow this structure:
|
||||
```
|
||||
Read the profiling reference document and the sampled session messages, then analyze the developer's behavioral patterns across all 8 dimensions.
|
||||
|
||||
Reference: @C:/Users/yaoji/.claude/get-shit-done/references/user-profiling.md
|
||||
Session data: @{temp_dir}/profile-sample.jsonl
|
||||
|
||||
Analyze these messages and return your analysis in the <analysis> JSON format specified in the reference document.
|
||||
```
|
||||
|
||||
**Parse the agent's output:**
|
||||
- Extract the `<analysis>` JSON block from the agent's response
|
||||
- Save analysis JSON to a temp file (in the same temp directory created by profile-sample)
|
||||
|
||||
```bash
|
||||
ANALYSIS_PATH="{temp_dir}/analysis.json"
|
||||
```
|
||||
|
||||
Write the analysis JSON to `$ANALYSIS_PATH`.
|
||||
|
||||
Display: "✓ Analysis complete (N dimensions scored)"
|
||||
|
||||
**Check for thin data:**
|
||||
- Read the analysis JSON and check the total message count
|
||||
- If < 50 messages were analyzed: Note that a questionnaire supplement could improve accuracy. Display: "Note: Limited session data (N messages). Results may have lower confidence."
|
||||
|
||||
Continue to step 5.
|
||||
|
||||
---
|
||||
|
||||
## 4b. Questionnaire Path
|
||||
|
||||
Display: "Using questionnaire to build your profile."
|
||||
|
||||
**Get questions:**
|
||||
```bash
|
||||
QUESTIONS=$(node C:/Users/yaoji/.claude/get-shit-done/bin/gsd-tools.cjs profile-questionnaire --json 2>/dev/null)
|
||||
```
|
||||
|
||||
Parse the questions JSON. It contains 8 questions, one per dimension.
|
||||
|
||||
**Present each question to the user via AskUserQuestion:**
|
||||
|
||||
For each question in the questions array:
|
||||
- header: The dimension name (e.g., "Communication Style")
|
||||
- question: The question text
|
||||
- options: The answer options from the question definition
|
||||
|
||||
Collect all answers into an answers JSON object mapping dimension keys to selected answer values.
|
||||
|
||||
**Save answers to temp file:**
|
||||
```bash
|
||||
ANSWERS_PATH=$(mktemp /tmp/gsd-profile-answers-XXXXXX.json)
|
||||
```
|
||||
|
||||
Write the answers JSON to `$ANSWERS_PATH`.
|
||||
|
||||
**Convert answers to analysis:**
|
||||
```bash
|
||||
ANALYSIS_RESULT=$(node C:/Users/yaoji/.claude/get-shit-done/bin/gsd-tools.cjs profile-questionnaire --answers "$ANSWERS_PATH" --json 2>/dev/null)
|
||||
```
|
||||
|
||||
Parse the analysis JSON from the result.
|
||||
|
||||
Save analysis JSON to a temp file:
|
||||
```bash
|
||||
ANALYSIS_PATH=$(mktemp /tmp/gsd-profile-analysis-XXXXXX.json)
|
||||
```
|
||||
|
||||
Write the analysis JSON to `$ANALYSIS_PATH`.
|
||||
|
||||
Continue to step 5 (skip split resolution since questionnaire handles ambiguity internally).
|
||||
|
||||
---
|
||||
|
||||
## 5. Split Resolution
|
||||
|
||||
**Skip if** questionnaire-only path (splits already handled internally).
|
||||
|
||||
Read the analysis JSON from `$ANALYSIS_PATH`.
|
||||
|
||||
Check each dimension for `cross_project_consistent: false`.
|
||||
|
||||
**For each split detected:**
|
||||
|
||||
Use AskUserQuestion:
|
||||
- header: The dimension name (e.g., "Communication Style")
|
||||
- question: "Your sessions show different patterns:" followed by the split context (e.g., "CLI/backend projects -> terse-direct, Frontend/UI projects -> detailed-structured")
|
||||
- options:
|
||||
- Rating option A (e.g., "terse-direct")
|
||||
- Rating option B (e.g., "detailed-structured")
|
||||
- "Context-dependent (keep both)"
|
||||
|
||||
**If user picks a specific rating:** Update the dimension's `rating` field in the analysis JSON to the selected value.
|
||||
|
||||
**If user picks "Context-dependent":** Keep the dominant rating in the `rating` field. Add a `context_note` to the dimension's summary describing the split (e.g., "Context-dependent: terse in CLI projects, detailed in frontend projects").
|
||||
|
||||
Write updated analysis JSON back to `$ANALYSIS_PATH`.
|
||||
|
||||
---
|
||||
|
||||
## 6. Profile Write
|
||||
|
||||
Display: "◆ Writing profile..."
|
||||
|
||||
```bash
|
||||
node C:/Users/yaoji/.claude/get-shit-done/bin/gsd-tools.cjs write-profile --input "$ANALYSIS_PATH" --json 2>/dev/null
|
||||
```
|
||||
|
||||
Display: "✓ Profile written to C:/Users/yaoji/.claude/get-shit-done/USER-PROFILE.md"
|
||||
|
||||
---
|
||||
|
||||
## 7. Result Display
|
||||
|
||||
Read the analysis JSON from `$ANALYSIS_PATH` to build the display.
|
||||
|
||||
**Show report card table:**
|
||||
|
||||
```
|
||||
## Your Profile
|
||||
|
||||
| Dimension | Rating | Confidence |
|
||||
|----------------------|----------------------|------------|
|
||||
| Communication Style | detailed-structured | HIGH |
|
||||
| Decision Speed | deliberate-informed | MEDIUM |
|
||||
| Explanation Depth | concise | HIGH |
|
||||
| Debugging Approach | hypothesis-driven | MEDIUM |
|
||||
| UX Philosophy | pragmatic | LOW |
|
||||
| Vendor Philosophy | thorough-evaluator | HIGH |
|
||||
| Frustration Triggers | scope-creep | MEDIUM |
|
||||
| Learning Style | self-directed | HIGH |
|
||||
```
|
||||
|
||||
(Populate with actual values from the analysis JSON.)
|
||||
|
||||
**Show highlight reel:**
|
||||
|
||||
Pick 3-4 dimensions with the highest confidence and most evidence signals. Format as:
|
||||
|
||||
```
|
||||
## Highlights
|
||||
|
||||
- **Communication (HIGH):** You consistently provide structured context with
|
||||
headers and problem statements before making requests
|
||||
- **Vendor Choices (HIGH):** You research alternatives thoroughly -- comparing
|
||||
docs, GitHub activity, and bundle sizes before committing
|
||||
- **Frustrations (MEDIUM):** You correct Claude most often for doing things
|
||||
you didn't ask for -- scope creep is your primary trigger
|
||||
```
|
||||
|
||||
Build highlights from the `evidence` array and `summary` fields in the analysis JSON. Use the most compelling evidence quotes. Format each as "You tend to..." or "You consistently..." with evidence attribution.
|
||||
|
||||
**Offer full profile view:**
|
||||
|
||||
Use AskUserQuestion:
|
||||
- header: "Profile"
|
||||
- question: "Want to see the full profile?"
|
||||
- options:
|
||||
- "Yes" -- Read and display the full USER-PROFILE.md content, then continue to step 8
|
||||
- "Continue to artifacts" -- Proceed directly to step 8
|
||||
|
||||
---
|
||||
|
||||
## 8. Artifact Selection (ACTV-05)
|
||||
|
||||
Use AskUserQuestion with multiSelect:
|
||||
- header: "Artifacts"
|
||||
- question: "Which artifacts should I generate?"
|
||||
- options (ALL pre-selected by default):
|
||||
- "/gsd:dev-preferences command file" -- "Load your preferences in any session"
|
||||
- "CLAUDE.md profile section" -- "Add profile to this project's CLAUDE.md"
|
||||
- "Global CLAUDE.md" -- "Add profile to C:/Users/yaoji/.claude/CLAUDE.md for all projects"
|
||||
|
||||
**If no artifacts selected:** Display "No artifacts generated. Your profile is saved at C:/Users/yaoji/.claude/get-shit-done/USER-PROFILE.md" and jump to step 10.
|
||||
|
||||
---
|
||||
|
||||
## 9. Artifact Generation
|
||||
|
||||
Generate selected artifacts sequentially (file I/O is fast, no benefit from parallel agents):
|
||||
|
||||
**For /gsd:dev-preferences (if selected):**
|
||||
|
||||
```bash
|
||||
node C:/Users/yaoji/.claude/get-shit-done/bin/gsd-tools.cjs generate-dev-preferences --analysis "$ANALYSIS_PATH" --json 2>/dev/null
|
||||
```
|
||||
|
||||
Display: "✓ Generated /gsd:dev-preferences at C:/Users/yaoji/.claude/commands/gsd/dev-preferences.md"
|
||||
|
||||
**For CLAUDE.md profile section (if selected):**
|
||||
|
||||
```bash
|
||||
node C:/Users/yaoji/.claude/get-shit-done/bin/gsd-tools.cjs generate-claude-profile --analysis "$ANALYSIS_PATH" --json 2>/dev/null
|
||||
```
|
||||
|
||||
Display: "✓ Added profile section to CLAUDE.md"
|
||||
|
||||
**For Global CLAUDE.md (if selected):**
|
||||
|
||||
```bash
|
||||
node C:/Users/yaoji/.claude/get-shit-done/bin/gsd-tools.cjs generate-claude-profile --analysis "$ANALYSIS_PATH" --global --json 2>/dev/null
|
||||
```
|
||||
|
||||
Display: "✓ Added profile section to C:/Users/yaoji/.claude/CLAUDE.md"
|
||||
|
||||
**Error handling:** If any gsd-tools.cjs call fails, display the error message and use AskUserQuestion to offer "Retry" or "Skip this artifact". On retry, re-run the command. On skip, continue to next artifact.
|
||||
|
||||
---
|
||||
|
||||
## 10. Summary & Refresh Diff
|
||||
|
||||
**If --refresh path:**
|
||||
|
||||
Read both old backup and new analysis to compare dimension ratings/confidence.
|
||||
|
||||
Read the backed-up profile:
|
||||
```bash
|
||||
BACKUP_PATH="C:/Users/yaoji/.claude/get-shit-done/USER-PROFILE.backup.md"
|
||||
```
|
||||
|
||||
Compare each dimension's rating and confidence between old and new. Display diff table showing only changed dimensions:
|
||||
|
||||
```
|
||||
## Changes
|
||||
|
||||
| Dimension | Before | After |
|
||||
|-----------------|-----------------------------|-----------------------------|
|
||||
| Communication | terse-direct (LOW) | detailed-structured (HIGH) |
|
||||
| Debugging | fix-first (MEDIUM) | hypothesis-driven (MEDIUM) |
|
||||
```
|
||||
|
||||
If nothing changed: Display "No changes detected -- your profile is already up to date."
|
||||
|
||||
**Display final summary:**
|
||||
|
||||
```
|
||||
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
|
||||
GSD > PROFILE COMPLETE ✓
|
||||
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
|
||||
|
||||
Your profile: C:/Users/yaoji/.claude/get-shit-done/USER-PROFILE.md
|
||||
```
|
||||
|
||||
Then list paths for each generated artifact:
|
||||
```
|
||||
Artifacts:
|
||||
✓ /gsd:dev-preferences C:/Users/yaoji/.claude/commands/gsd/dev-preferences.md
|
||||
✓ CLAUDE.md section ./CLAUDE.md
|
||||
✓ Global CLAUDE.md C:/Users/yaoji/.claude/CLAUDE.md
|
||||
```
|
||||
|
||||
(Only show artifacts that were actually generated.)
|
||||
|
||||
**Clean up temp files:**
|
||||
|
||||
Remove the temp directory created by profile-sample (contains sample JSONL and analysis JSON):
|
||||
```bash
|
||||
rm -rf "$TEMP_DIR"
|
||||
```
|
||||
|
||||
Also remove any standalone temp files created for questionnaire answers:
|
||||
```bash
|
||||
rm -f "$ANSWERS_PATH" 2>/dev/null
|
||||
rm -f "$ANALYSIS_PATH" 2>/dev/null
|
||||
```
|
||||
|
||||
(Only clean up temp paths that were actually created during this workflow run.)
|
||||
|
||||
</process>
|
||||
|
||||
<success_criteria>
|
||||
- [ ] Initialization detects existing profile and handles all three responses (view/refresh/cancel)
|
||||
- [ ] Consent gate shown for session analysis path, skipped for questionnaire path
|
||||
- [ ] Session scan discovers sessions and reports statistics
|
||||
- [ ] Session analysis path: samples messages, spawns profiler agent, extracts analysis JSON
|
||||
- [ ] Questionnaire path: presents 8 questions, collects answers, converts to analysis JSON
|
||||
- [ ] Split resolution presents context-dependent splits with user resolution options
|
||||
- [ ] Profile written to USER-PROFILE.md via write-profile subcommand
|
||||
- [ ] Result display shows report card table and highlight reel with evidence
|
||||
- [ ] Artifact selection uses multiSelect with all options pre-selected
|
||||
- [ ] Artifacts generated sequentially via gsd-tools.cjs subcommands
|
||||
- [ ] Refresh diff shows changed dimensions when --refresh was used
|
||||
- [ ] Temp files cleaned up on completion
|
||||
</success_criteria>
|
||||
382
get-shit-done/workflows/progress.md
Normal file
382
get-shit-done/workflows/progress.md
Normal file
@@ -0,0 +1,382 @@
|
||||
<purpose>
|
||||
Check project progress, summarize recent work and what's ahead, then intelligently route to the next action — either executing an existing plan or creating the next one. Provides situational awareness before continuing work.
|
||||
</purpose>
|
||||
|
||||
<required_reading>
|
||||
Read all files referenced by the invoking prompt's execution_context before starting.
|
||||
</required_reading>
|
||||
|
||||
<process>
|
||||
|
||||
<step name="init_context">
|
||||
**Load progress context (paths only):**
|
||||
|
||||
```bash
|
||||
INIT=$(node "C:/Users/yaoji/.claude/get-shit-done/bin/gsd-tools.cjs" init progress)
|
||||
if [[ "$INIT" == @file:* ]]; then INIT=$(cat "${INIT#@file:}"); fi
|
||||
```
|
||||
|
||||
Extract from init JSON: `project_exists`, `roadmap_exists`, `state_exists`, `phases`, `current_phase`, `next_phase`, `milestone_version`, `completed_count`, `phase_count`, `paused_at`, `state_path`, `roadmap_path`, `project_path`, `config_path`.
|
||||
|
||||
If `project_exists` is false (no `.planning/` directory):
|
||||
|
||||
```
|
||||
No planning structure found.
|
||||
|
||||
Run /gsd:new-project to start a new project.
|
||||
```
|
||||
|
||||
Exit.
|
||||
|
||||
If missing STATE.md: suggest `/gsd:new-project`.
|
||||
|
||||
**If ROADMAP.md missing but PROJECT.md exists:**
|
||||
|
||||
This means a milestone was completed and archived. Go to **Route F** (between milestones).
|
||||
|
||||
If missing both ROADMAP.md and PROJECT.md: suggest `/gsd:new-project`.
|
||||
</step>
|
||||
|
||||
<step name="load">
|
||||
**Use structured extraction from gsd-tools:**
|
||||
|
||||
Instead of reading full files, use targeted tools to get only the data needed for the report:
|
||||
- `ROADMAP=$(node "C:/Users/yaoji/.claude/get-shit-done/bin/gsd-tools.cjs" roadmap analyze)`
|
||||
- `STATE=$(node "C:/Users/yaoji/.claude/get-shit-done/bin/gsd-tools.cjs" state-snapshot)`
|
||||
|
||||
This minimizes orchestrator context usage.
|
||||
</step>
|
||||
|
||||
<step name="analyze_roadmap">
|
||||
**Get comprehensive roadmap analysis (replaces manual parsing):**
|
||||
|
||||
```bash
|
||||
ROADMAP=$(node "C:/Users/yaoji/.claude/get-shit-done/bin/gsd-tools.cjs" roadmap analyze)
|
||||
```
|
||||
|
||||
This returns structured JSON with:
|
||||
- All phases with disk status (complete/partial/planned/empty/no_directory)
|
||||
- Goal and dependencies per phase
|
||||
- Plan and summary counts per phase
|
||||
- Aggregated stats: total plans, summaries, progress percent
|
||||
- Current and next phase identification
|
||||
|
||||
Use this instead of manually reading/parsing ROADMAP.md.
|
||||
</step>
|
||||
|
||||
<step name="recent">
|
||||
**Gather recent work context:**
|
||||
|
||||
- Find the 2-3 most recent SUMMARY.md files
|
||||
- Use `summary-extract` for efficient parsing:
|
||||
```bash
|
||||
node "C:/Users/yaoji/.claude/get-shit-done/bin/gsd-tools.cjs" summary-extract <path> --fields one_liner
|
||||
```
|
||||
- This shows "what we've been working on"
|
||||
</step>
|
||||
|
||||
<step name="position">
|
||||
**Parse current position from init context and roadmap analysis:**
|
||||
|
||||
- Use `current_phase` and `next_phase` from `$ROADMAP`
|
||||
- Note `paused_at` if work was paused (from `$STATE`)
|
||||
- Count pending todos: use `init todos` or `list-todos`
|
||||
- Check for active debug sessions: `ls .planning/debug/*.md 2>/dev/null | grep -v resolved | wc -l`
|
||||
</step>
|
||||
|
||||
<step name="report">
|
||||
**Generate progress bar from gsd-tools, then present rich status report:**
|
||||
|
||||
```bash
|
||||
# Get formatted progress bar
|
||||
PROGRESS_BAR=$(node "C:/Users/yaoji/.claude/get-shit-done/bin/gsd-tools.cjs" progress bar --raw)
|
||||
```
|
||||
|
||||
Present:
|
||||
|
||||
```
|
||||
# [Project Name]
|
||||
|
||||
**Progress:** {PROGRESS_BAR}
|
||||
**Profile:** [quality/balanced/budget/inherit]
|
||||
|
||||
## Recent Work
|
||||
- [Phase X, Plan Y]: [what was accomplished - 1 line from summary-extract]
|
||||
- [Phase X, Plan Z]: [what was accomplished - 1 line from summary-extract]
|
||||
|
||||
## Current Position
|
||||
Phase [N] of [total]: [phase-name]
|
||||
Plan [M] of [phase-total]: [status]
|
||||
CONTEXT: [✓ if has_context | - if not]
|
||||
|
||||
## Key Decisions Made
|
||||
- [extract from $STATE.decisions[]]
|
||||
- [e.g. jq -r '.decisions[].decision' from state-snapshot]
|
||||
|
||||
## Blockers/Concerns
|
||||
- [extract from $STATE.blockers[]]
|
||||
- [e.g. jq -r '.blockers[].text' from state-snapshot]
|
||||
|
||||
## Pending Todos
|
||||
- [count] pending — /gsd:check-todos to review
|
||||
|
||||
## Active Debug Sessions
|
||||
- [count] active — /gsd:debug to continue
|
||||
(Only show this section if count > 0)
|
||||
|
||||
## What's Next
|
||||
[Next phase/plan objective from roadmap analyze]
|
||||
```
|
||||
|
||||
</step>
|
||||
|
||||
<step name="route">
|
||||
**Determine next action based on verified counts.**
|
||||
|
||||
**Step 1: Count plans, summaries, and issues in current phase**
|
||||
|
||||
List files in the current phase directory:
|
||||
|
||||
```bash
|
||||
ls -1 .planning/phases/[current-phase-dir]/*-PLAN.md 2>/dev/null | wc -l
|
||||
ls -1 .planning/phases/[current-phase-dir]/*-SUMMARY.md 2>/dev/null | wc -l
|
||||
ls -1 .planning/phases/[current-phase-dir]/*-UAT.md 2>/dev/null | wc -l
|
||||
```
|
||||
|
||||
State: "This phase has {X} plans, {Y} summaries."
|
||||
|
||||
**Step 1.5: Check for unaddressed UAT gaps**
|
||||
|
||||
Check for UAT.md files with status "diagnosed" (has gaps needing fixes).
|
||||
|
||||
```bash
|
||||
# Check for diagnosed UAT with gaps
|
||||
grep -l "status: diagnosed" .planning/phases/[current-phase-dir]/*-UAT.md 2>/dev/null
|
||||
```
|
||||
|
||||
Track:
|
||||
- `uat_with_gaps`: UAT.md files with status "diagnosed" (gaps need fixing)
|
||||
|
||||
**Step 2: Route based on counts**
|
||||
|
||||
| Condition | Meaning | Action |
|
||||
|-----------|---------|--------|
|
||||
| uat_with_gaps > 0 | UAT gaps need fix plans | Go to **Route E** |
|
||||
| summaries < plans | Unexecuted plans exist | Go to **Route A** |
|
||||
| summaries = plans AND plans > 0 | Phase complete | Go to Step 3 |
|
||||
| plans = 0 | Phase not yet planned | Go to **Route B** |
|
||||
|
||||
---
|
||||
|
||||
**Route A: Unexecuted plan exists**
|
||||
|
||||
Find the first PLAN.md without matching SUMMARY.md.
|
||||
Read its `<objective>` section.
|
||||
|
||||
```
|
||||
---
|
||||
|
||||
## ▶ Next Up
|
||||
|
||||
**{phase}-{plan}: [Plan Name]** — [objective summary from PLAN.md]
|
||||
|
||||
`/gsd:execute-phase {phase}`
|
||||
|
||||
<sub>`/clear` first → fresh context window</sub>
|
||||
|
||||
---
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
**Route B: Phase needs planning**
|
||||
|
||||
Check if `{phase_num}-CONTEXT.md` exists in phase directory.
|
||||
|
||||
**If CONTEXT.md exists:**
|
||||
|
||||
```
|
||||
---
|
||||
|
||||
## ▶ Next Up
|
||||
|
||||
**Phase {N}: {Name}** — {Goal from ROADMAP.md}
|
||||
<sub>✓ Context gathered, ready to plan</sub>
|
||||
|
||||
`/gsd:plan-phase {phase-number}`
|
||||
|
||||
<sub>`/clear` first → fresh context window</sub>
|
||||
|
||||
---
|
||||
```
|
||||
|
||||
**If CONTEXT.md does NOT exist:**
|
||||
|
||||
```
|
||||
---
|
||||
|
||||
## ▶ Next Up
|
||||
|
||||
**Phase {N}: {Name}** — {Goal from ROADMAP.md}
|
||||
|
||||
`/gsd:discuss-phase {phase}` — gather context and clarify approach
|
||||
|
||||
<sub>`/clear` first → fresh context window</sub>
|
||||
|
||||
---
|
||||
|
||||
**Also available:**
|
||||
- `/gsd:plan-phase {phase}` — skip discussion, plan directly
|
||||
- `/gsd:list-phase-assumptions {phase}` — see Claude's assumptions
|
||||
|
||||
---
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
**Route E: UAT gaps need fix plans**
|
||||
|
||||
UAT.md exists with gaps (diagnosed issues). User needs to plan fixes.
|
||||
|
||||
```
|
||||
---
|
||||
|
||||
## ⚠ UAT Gaps Found
|
||||
|
||||
**{phase_num}-UAT.md** has {N} gaps requiring fixes.
|
||||
|
||||
`/gsd:plan-phase {phase} --gaps`
|
||||
|
||||
<sub>`/clear` first → fresh context window</sub>
|
||||
|
||||
---
|
||||
|
||||
**Also available:**
|
||||
- `/gsd:execute-phase {phase}` — execute phase plans
|
||||
- `/gsd:verify-work {phase}` — run more UAT testing
|
||||
|
||||
---
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
**Step 3: Check milestone status (only when phase complete)**
|
||||
|
||||
Read ROADMAP.md and identify:
|
||||
1. Current phase number
|
||||
2. All phase numbers in the current milestone section
|
||||
|
||||
Count total phases and identify the highest phase number.
|
||||
|
||||
State: "Current phase is {X}. Milestone has {N} phases (highest: {Y})."
|
||||
|
||||
**Route based on milestone status:**
|
||||
|
||||
| Condition | Meaning | Action |
|
||||
|-----------|---------|--------|
|
||||
| current phase < highest phase | More phases remain | Go to **Route C** |
|
||||
| current phase = highest phase | Milestone complete | Go to **Route D** |
|
||||
|
||||
---
|
||||
|
||||
**Route C: Phase complete, more phases remain**
|
||||
|
||||
Read ROADMAP.md to get the next phase's name and goal.
|
||||
|
||||
```
|
||||
---
|
||||
|
||||
## ✓ Phase {Z} Complete
|
||||
|
||||
## ▶ Next Up
|
||||
|
||||
**Phase {Z+1}: {Name}** — {Goal from ROADMAP.md}
|
||||
|
||||
`/gsd:discuss-phase {Z+1}` — gather context and clarify approach
|
||||
|
||||
<sub>`/clear` first → fresh context window</sub>
|
||||
|
||||
---
|
||||
|
||||
**Also available:**
|
||||
- `/gsd:plan-phase {Z+1}` — skip discussion, plan directly
|
||||
- `/gsd:verify-work {Z}` — user acceptance test before continuing
|
||||
|
||||
---
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
**Route D: Milestone complete**
|
||||
|
||||
```
|
||||
---
|
||||
|
||||
## 🎉 Milestone Complete
|
||||
|
||||
All {N} phases finished!
|
||||
|
||||
## ▶ Next Up
|
||||
|
||||
**Complete Milestone** — archive and prepare for next
|
||||
|
||||
`/gsd:complete-milestone`
|
||||
|
||||
<sub>`/clear` first → fresh context window</sub>
|
||||
|
||||
---
|
||||
|
||||
**Also available:**
|
||||
- `/gsd:verify-work` — user acceptance test before completing milestone
|
||||
|
||||
---
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
**Route F: Between milestones (ROADMAP.md missing, PROJECT.md exists)**
|
||||
|
||||
A milestone was completed and archived. Ready to start the next milestone cycle.
|
||||
|
||||
Read MILESTONES.md to find the last completed milestone version.
|
||||
|
||||
```
|
||||
---
|
||||
|
||||
## ✓ Milestone v{X.Y} Complete
|
||||
|
||||
Ready to plan the next milestone.
|
||||
|
||||
## ▶ Next Up
|
||||
|
||||
**Start Next Milestone** — questioning → research → requirements → roadmap
|
||||
|
||||
`/gsd:new-milestone`
|
||||
|
||||
<sub>`/clear` first → fresh context window</sub>
|
||||
|
||||
---
|
||||
```
|
||||
|
||||
</step>
|
||||
|
||||
<step name="edge_cases">
|
||||
**Handle edge cases:**
|
||||
|
||||
- Phase complete but next phase not planned → offer `/gsd:plan-phase [next]`
|
||||
- All work complete → offer milestone completion
|
||||
- Blockers present → highlight before offering to continue
|
||||
- Handoff file exists → mention it, offer `/gsd:resume-work`
|
||||
</step>
|
||||
|
||||
</process>
|
||||
|
||||
<success_criteria>
|
||||
|
||||
- [ ] Rich context provided (recent work, decisions, issues)
|
||||
- [ ] Current position clear with visual progress
|
||||
- [ ] What's next clearly explained
|
||||
- [ ] Smart routing: /gsd:execute-phase if plans exist, /gsd:plan-phase if not
|
||||
- [ ] User confirms before any action
|
||||
- [ ] Seamless handoff to appropriate gsd command
|
||||
</success_criteria>
|
||||
717
get-shit-done/workflows/quick.md
Normal file
717
get-shit-done/workflows/quick.md
Normal file
@@ -0,0 +1,717 @@
|
||||
<purpose>
|
||||
Execute small, ad-hoc tasks with GSD guarantees (atomic commits, STATE.md tracking). Quick mode spawns gsd-planner (quick mode) + gsd-executor(s), tracks tasks in `.planning/quick/`, and updates STATE.md's "Quick Tasks Completed" table.
|
||||
|
||||
With `--discuss` flag: lightweight discussion phase before planning. Surfaces assumptions, clarifies gray areas, captures decisions in CONTEXT.md so the planner treats them as locked.
|
||||
|
||||
With `--full` flag: enables plan-checking (max 2 iterations) and post-execution verification for quality guarantees without full milestone ceremony.
|
||||
|
||||
With `--research` flag: spawns a focused research agent before planning. Investigates implementation approaches, library options, and pitfalls. Use when you're unsure how to approach a task.
|
||||
|
||||
Flags are composable: `--discuss --research --full` gives discussion + research + plan-checking + verification.
|
||||
</purpose>
|
||||
|
||||
<required_reading>
|
||||
Read all files referenced by the invoking prompt's execution_context before starting.
|
||||
</required_reading>
|
||||
|
||||
<process>
|
||||
**Step 1: Parse arguments and get task description**
|
||||
|
||||
Parse `$ARGUMENTS` for:
|
||||
- `--full` flag → store as `$FULL_MODE` (true/false)
|
||||
- `--discuss` flag → store as `$DISCUSS_MODE` (true/false)
|
||||
- `--research` flag → store as `$RESEARCH_MODE` (true/false)
|
||||
- Remaining text → use as `$DESCRIPTION` if non-empty
|
||||
|
||||
If `$DESCRIPTION` is empty after parsing, prompt user interactively:
|
||||
|
||||
```
|
||||
AskUserQuestion(
|
||||
header: "Quick Task",
|
||||
question: "What do you want to do?",
|
||||
followUp: null
|
||||
)
|
||||
```
|
||||
|
||||
Store response as `$DESCRIPTION`.
|
||||
|
||||
If still empty, re-prompt: "Please provide a task description."
|
||||
|
||||
Display banner based on active flags:
|
||||
|
||||
If `$DISCUSS_MODE` and `$RESEARCH_MODE` and `$FULL_MODE`:
|
||||
```
|
||||
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
|
||||
GSD ► QUICK TASK (DISCUSS + RESEARCH + FULL)
|
||||
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
|
||||
|
||||
◆ Discussion + research + plan checking + verification enabled
|
||||
```
|
||||
|
||||
If `$DISCUSS_MODE` and `$FULL_MODE` (no research):
|
||||
```
|
||||
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
|
||||
GSD ► QUICK TASK (DISCUSS + FULL)
|
||||
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
|
||||
|
||||
◆ Discussion + plan checking + verification enabled
|
||||
```
|
||||
|
||||
If `$DISCUSS_MODE` and `$RESEARCH_MODE` (no full):
|
||||
```
|
||||
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
|
||||
GSD ► QUICK TASK (DISCUSS + RESEARCH)
|
||||
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
|
||||
|
||||
◆ Discussion + research enabled
|
||||
```
|
||||
|
||||
If `$RESEARCH_MODE` and `$FULL_MODE` (no discuss):
|
||||
```
|
||||
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
|
||||
GSD ► QUICK TASK (RESEARCH + FULL)
|
||||
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
|
||||
|
||||
◆ Research + plan checking + verification enabled
|
||||
```
|
||||
|
||||
If `$DISCUSS_MODE` only:
|
||||
```
|
||||
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
|
||||
GSD ► QUICK TASK (DISCUSS)
|
||||
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
|
||||
|
||||
◆ Discussion phase enabled — surfacing gray areas before planning
|
||||
```
|
||||
|
||||
If `$RESEARCH_MODE` only:
|
||||
```
|
||||
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
|
||||
GSD ► QUICK TASK (RESEARCH)
|
||||
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
|
||||
|
||||
◆ Research phase enabled — investigating approaches before planning
|
||||
```
|
||||
|
||||
If `$FULL_MODE` only:
|
||||
```
|
||||
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
|
||||
GSD ► QUICK TASK (FULL MODE)
|
||||
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
|
||||
|
||||
◆ Plan checking + verification enabled
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
**Step 2: Initialize**
|
||||
|
||||
```bash
|
||||
INIT=$(node "C:/Users/yaoji/.claude/get-shit-done/bin/gsd-tools.cjs" init quick "$DESCRIPTION")
|
||||
if [[ "$INIT" == @file:* ]]; then INIT=$(cat "${INIT#@file:}"); fi
|
||||
```
|
||||
|
||||
Parse JSON for: `planner_model`, `executor_model`, `checker_model`, `verifier_model`, `commit_docs`, `quick_id`, `slug`, `date`, `timestamp`, `quick_dir`, `task_dir`, `roadmap_exists`, `planning_exists`.
|
||||
|
||||
**If `roadmap_exists` is false:** Error — Quick mode requires an active project with ROADMAP.md. Run `/gsd:new-project` first.
|
||||
|
||||
Quick tasks can run mid-phase - validation only checks ROADMAP.md exists, not phase status.
|
||||
|
||||
---
|
||||
|
||||
**Step 3: Create task directory**
|
||||
|
||||
```bash
|
||||
mkdir -p "${task_dir}"
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
**Step 4: Create quick task directory**
|
||||
|
||||
Create the directory for this quick task:
|
||||
|
||||
```bash
|
||||
QUICK_DIR=".planning/quick/${quick_id}-${slug}"
|
||||
mkdir -p "$QUICK_DIR"
|
||||
```
|
||||
|
||||
Report to user:
|
||||
```
|
||||
Creating quick task ${quick_id}: ${DESCRIPTION}
|
||||
Directory: ${QUICK_DIR}
|
||||
```
|
||||
|
||||
Store `$QUICK_DIR` for use in orchestration.
|
||||
|
||||
---
|
||||
|
||||
**Step 4.5: Discussion phase (only when `$DISCUSS_MODE`)**
|
||||
|
||||
Skip this step entirely if NOT `$DISCUSS_MODE`.
|
||||
|
||||
Display banner:
|
||||
```
|
||||
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
|
||||
GSD ► DISCUSSING QUICK TASK
|
||||
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
|
||||
|
||||
◆ Surfacing gray areas for: ${DESCRIPTION}
|
||||
```
|
||||
|
||||
**4.5a. Identify gray areas**
|
||||
|
||||
Analyze `$DESCRIPTION` to identify 2-4 gray areas — implementation decisions that would change the outcome and that the user should weigh in on.
|
||||
|
||||
Use the domain-aware heuristic to generate phase-specific (not generic) gray areas:
|
||||
- Something users **SEE** → layout, density, interactions, states
|
||||
- Something users **CALL** → responses, errors, auth, versioning
|
||||
- Something users **RUN** → output format, flags, modes, error handling
|
||||
- Something users **READ** → structure, tone, depth, flow
|
||||
- Something being **ORGANIZED** → criteria, grouping, naming, exceptions
|
||||
|
||||
Each gray area should be a concrete decision point, not a vague category. Example: "Loading behavior" not "UX".
|
||||
|
||||
**4.5b. Present gray areas**
|
||||
|
||||
```
|
||||
AskUserQuestion(
|
||||
header: "Gray Areas",
|
||||
question: "Which areas need clarification before planning?",
|
||||
options: [
|
||||
{ label: "${area_1}", description: "${why_it_matters_1}" },
|
||||
{ label: "${area_2}", description: "${why_it_matters_2}" },
|
||||
{ label: "${area_3}", description: "${why_it_matters_3}" },
|
||||
{ label: "All clear", description: "Skip discussion — I know what I want" }
|
||||
],
|
||||
multiSelect: true
|
||||
)
|
||||
```
|
||||
|
||||
If user selects "All clear" → skip to Step 5 (no CONTEXT.md written).
|
||||
|
||||
**4.5c. Discuss selected areas**
|
||||
|
||||
For each selected area, ask 1-2 focused questions via AskUserQuestion:
|
||||
|
||||
```
|
||||
AskUserQuestion(
|
||||
header: "${area_name}",
|
||||
question: "${specific_question_about_this_area}",
|
||||
options: [
|
||||
{ label: "${concrete_choice_1}", description: "${what_this_means}" },
|
||||
{ label: "${concrete_choice_2}", description: "${what_this_means}" },
|
||||
{ label: "${concrete_choice_3}", description: "${what_this_means}" },
|
||||
{ label: "You decide", description: "Claude's discretion" }
|
||||
],
|
||||
multiSelect: false
|
||||
)
|
||||
```
|
||||
|
||||
Rules:
|
||||
- Options must be concrete choices, not abstract categories
|
||||
- Highlight recommended choice where you have a clear opinion
|
||||
- If user selects "Other" with freeform text, switch to plain text follow-up (per questioning.md freeform rule)
|
||||
- If user selects "You decide", capture as Claude's Discretion in CONTEXT.md
|
||||
- Max 2 questions per area — this is lightweight, not a deep dive
|
||||
|
||||
Collect all decisions into `$DECISIONS`.
|
||||
|
||||
**4.5d. Write CONTEXT.md**
|
||||
|
||||
Write `${QUICK_DIR}/${quick_id}-CONTEXT.md` using the standard context template structure:
|
||||
|
||||
```markdown
|
||||
# Quick Task ${quick_id}: ${DESCRIPTION} - Context
|
||||
|
||||
**Gathered:** ${date}
|
||||
**Status:** Ready for planning
|
||||
|
||||
<domain>
|
||||
## Task Boundary
|
||||
|
||||
${DESCRIPTION}
|
||||
|
||||
</domain>
|
||||
|
||||
<decisions>
|
||||
## Implementation Decisions
|
||||
|
||||
### ${area_1_name}
|
||||
- ${decision_from_discussion}
|
||||
|
||||
### ${area_2_name}
|
||||
- ${decision_from_discussion}
|
||||
|
||||
### Claude's Discretion
|
||||
${areas_where_user_said_you_decide_or_areas_not_discussed}
|
||||
|
||||
</decisions>
|
||||
|
||||
<specifics>
|
||||
## Specific Ideas
|
||||
|
||||
${any_specific_references_or_examples_from_discussion}
|
||||
|
||||
[If none: "No specific requirements — open to standard approaches"]
|
||||
|
||||
</specifics>
|
||||
|
||||
<canonical_refs>
|
||||
## Canonical References
|
||||
|
||||
${any_specs_adrs_or_docs_referenced_during_discussion}
|
||||
|
||||
[If none: "No external specs — requirements fully captured in decisions above"]
|
||||
|
||||
</canonical_refs>
|
||||
```
|
||||
|
||||
Note: Quick task CONTEXT.md omits `<code_context>` and `<deferred>` sections (no codebase scouting, no phase scope to defer to). Keep it lean. The `<canonical_refs>` section is included when external docs were referenced — omit it only if no external docs apply.
|
||||
|
||||
Report: `Context captured: ${QUICK_DIR}/${quick_id}-CONTEXT.md`
|
||||
|
||||
---
|
||||
|
||||
**Step 4.75: Research phase (only when `$RESEARCH_MODE`)**
|
||||
|
||||
Skip this step entirely if NOT `$RESEARCH_MODE`.
|
||||
|
||||
Display banner:
|
||||
```
|
||||
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
|
||||
GSD ► RESEARCHING QUICK TASK
|
||||
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
|
||||
|
||||
◆ Investigating approaches for: ${DESCRIPTION}
|
||||
```
|
||||
|
||||
Spawn a single focused researcher (not 4 parallel researchers like full phases — quick tasks need targeted research, not broad domain surveys):
|
||||
|
||||
```
|
||||
Task(
|
||||
prompt="
|
||||
<research_context>
|
||||
|
||||
**Mode:** quick-task
|
||||
**Task:** ${DESCRIPTION}
|
||||
**Output:** ${QUICK_DIR}/${quick_id}-RESEARCH.md
|
||||
|
||||
<files_to_read>
|
||||
- .planning/STATE.md (Project state — what's already built)
|
||||
- .planning/PROJECT.md (Project context)
|
||||
- ./CLAUDE.md (if exists — project-specific guidelines)
|
||||
${DISCUSS_MODE ? '- ' + QUICK_DIR + '/' + quick_id + '-CONTEXT.md (User decisions — research should align with these)' : ''}
|
||||
</files_to_read>
|
||||
|
||||
</research_context>
|
||||
|
||||
<focus>
|
||||
This is a quick task, not a full phase. Research should be concise and targeted:
|
||||
1. Best libraries/patterns for this specific task
|
||||
2. Common pitfalls and how to avoid them
|
||||
3. Integration points with existing codebase
|
||||
4. Any constraints or gotchas worth knowing before planning
|
||||
|
||||
Do NOT produce a full domain survey. Target 1-2 pages of actionable findings.
|
||||
</focus>
|
||||
|
||||
<output>
|
||||
Write research to: ${QUICK_DIR}/${quick_id}-RESEARCH.md
|
||||
Use standard research format but keep it lean — skip sections that don't apply.
|
||||
Return: ## RESEARCH COMPLETE with file path
|
||||
</output>
|
||||
",
|
||||
subagent_type="gsd-phase-researcher",
|
||||
model="{planner_model}",
|
||||
description="Research: ${DESCRIPTION}"
|
||||
)
|
||||
```
|
||||
|
||||
After researcher returns:
|
||||
1. Verify research exists at `${QUICK_DIR}/${quick_id}-RESEARCH.md`
|
||||
2. Report: "Research complete: ${QUICK_DIR}/${quick_id}-RESEARCH.md"
|
||||
|
||||
If research file not found, warn but continue: "Research agent did not produce output — proceeding to planning without research."
|
||||
|
||||
---
|
||||
|
||||
**Step 5: Spawn planner (quick mode)**
|
||||
|
||||
**If `$FULL_MODE`:** Use `quick-full` mode with stricter constraints.
|
||||
|
||||
**If NOT `$FULL_MODE`:** Use standard `quick` mode.
|
||||
|
||||
```
|
||||
Task(
|
||||
prompt="
|
||||
<planning_context>
|
||||
|
||||
**Mode:** ${FULL_MODE ? 'quick-full' : 'quick'}
|
||||
**Directory:** ${QUICK_DIR}
|
||||
**Description:** ${DESCRIPTION}
|
||||
|
||||
<files_to_read>
|
||||
- .planning/STATE.md (Project State)
|
||||
- ./CLAUDE.md (if exists — follow project-specific guidelines)
|
||||
${DISCUSS_MODE ? '- ' + QUICK_DIR + '/' + quick_id + '-CONTEXT.md (User decisions — locked, do not revisit)' : ''}
|
||||
${RESEARCH_MODE ? '- ' + QUICK_DIR + '/' + quick_id + '-RESEARCH.md (Research findings — use to inform implementation choices)' : ''}
|
||||
</files_to_read>
|
||||
|
||||
**Project skills:** Check .claude/skills/ or .agents/skills/ directory (if either exists) — read SKILL.md files, plans should account for project skill rules
|
||||
|
||||
</planning_context>
|
||||
|
||||
<constraints>
|
||||
- Create a SINGLE plan with 1-3 focused tasks
|
||||
- Quick tasks should be atomic and self-contained
|
||||
${RESEARCH_MODE ? '- Research findings are available — use them to inform library/pattern choices' : '- No research phase'}
|
||||
${FULL_MODE ? '- Target ~40% context usage (structured for verification)' : '- Target ~30% context usage (simple, focused)'}
|
||||
${FULL_MODE ? '- MUST generate `must_haves` in plan frontmatter (truths, artifacts, key_links)' : ''}
|
||||
${FULL_MODE ? '- Each task MUST have `files`, `action`, `verify`, `done` fields' : ''}
|
||||
</constraints>
|
||||
|
||||
<output>
|
||||
Write plan to: ${QUICK_DIR}/${quick_id}-PLAN.md
|
||||
Return: ## PLANNING COMPLETE with plan path
|
||||
</output>
|
||||
",
|
||||
subagent_type="gsd-planner",
|
||||
model="{planner_model}",
|
||||
description="Quick plan: ${DESCRIPTION}"
|
||||
)
|
||||
```
|
||||
|
||||
After planner returns:
|
||||
1. Verify plan exists at `${QUICK_DIR}/${quick_id}-PLAN.md`
|
||||
2. Extract plan count (typically 1 for quick tasks)
|
||||
3. Report: "Plan created: ${QUICK_DIR}/${quick_id}-PLAN.md"
|
||||
|
||||
If plan not found, error: "Planner failed to create ${quick_id}-PLAN.md"
|
||||
|
||||
---
|
||||
|
||||
**Step 5.5: Plan-checker loop (only when `$FULL_MODE`)**
|
||||
|
||||
Skip this step entirely if NOT `$FULL_MODE`.
|
||||
|
||||
Display banner:
|
||||
```
|
||||
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
|
||||
GSD ► CHECKING PLAN
|
||||
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
|
||||
|
||||
◆ Spawning plan checker...
|
||||
```
|
||||
|
||||
Checker prompt:
|
||||
|
||||
```markdown
|
||||
<verification_context>
|
||||
**Mode:** quick-full
|
||||
**Task Description:** ${DESCRIPTION}
|
||||
|
||||
<files_to_read>
|
||||
- ${QUICK_DIR}/${quick_id}-PLAN.md (Plan to verify)
|
||||
</files_to_read>
|
||||
|
||||
**Scope:** This is a quick task, not a full phase. Skip checks that require a ROADMAP phase goal.
|
||||
</verification_context>
|
||||
|
||||
<check_dimensions>
|
||||
- Requirement coverage: Does the plan address the task description?
|
||||
- Task completeness: Do tasks have files, action, verify, done fields?
|
||||
- Key links: Are referenced files real?
|
||||
- Scope sanity: Is this appropriately sized for a quick task (1-3 tasks)?
|
||||
- must_haves derivation: Are must_haves traceable to the task description?
|
||||
|
||||
Skip: cross-plan deps (single plan), ROADMAP alignment
|
||||
${DISCUSS_MODE ? '- Context compliance: Does the plan honor locked decisions from CONTEXT.md?' : '- Skip: context compliance (no CONTEXT.md)'}
|
||||
</check_dimensions>
|
||||
|
||||
<expected_output>
|
||||
- ## VERIFICATION PASSED — all checks pass
|
||||
- ## ISSUES FOUND — structured issue list
|
||||
</expected_output>
|
||||
```
|
||||
|
||||
```
|
||||
Task(
|
||||
prompt=checker_prompt,
|
||||
subagent_type="gsd-plan-checker",
|
||||
model="{checker_model}",
|
||||
description="Check quick plan: ${DESCRIPTION}"
|
||||
)
|
||||
```
|
||||
|
||||
**Handle checker return:**
|
||||
|
||||
- **`## VERIFICATION PASSED`:** Display confirmation, proceed to step 6.
|
||||
- **`## ISSUES FOUND`:** Display issues, check iteration count, enter revision loop.
|
||||
|
||||
**Revision loop (max 2 iterations):**
|
||||
|
||||
Track `iteration_count` (starts at 1 after initial plan + check).
|
||||
|
||||
**If iteration_count < 2:**
|
||||
|
||||
Display: `Sending back to planner for revision... (iteration ${N}/2)`
|
||||
|
||||
Revision prompt:
|
||||
|
||||
```markdown
|
||||
<revision_context>
|
||||
**Mode:** quick-full (revision)
|
||||
|
||||
<files_to_read>
|
||||
- ${QUICK_DIR}/${quick_id}-PLAN.md (Existing plan)
|
||||
</files_to_read>
|
||||
|
||||
**Checker issues:** ${structured_issues_from_checker}
|
||||
|
||||
</revision_context>
|
||||
|
||||
<instructions>
|
||||
Make targeted updates to address checker issues.
|
||||
Do NOT replan from scratch unless issues are fundamental.
|
||||
Return what changed.
|
||||
</instructions>
|
||||
```
|
||||
|
||||
```
|
||||
Task(
|
||||
prompt=revision_prompt,
|
||||
subagent_type="gsd-planner",
|
||||
model="{planner_model}",
|
||||
description="Revise quick plan: ${DESCRIPTION}"
|
||||
)
|
||||
```
|
||||
|
||||
After planner returns → spawn checker again, increment iteration_count.
|
||||
|
||||
**If iteration_count >= 2:**
|
||||
|
||||
Display: `Max iterations reached. ${N} issues remain:` + issue list
|
||||
|
||||
Offer: 1) Force proceed, 2) Abort
|
||||
|
||||
---
|
||||
|
||||
**Step 6: Spawn executor**
|
||||
|
||||
Spawn gsd-executor with plan reference:
|
||||
|
||||
```
|
||||
Task(
|
||||
prompt="
|
||||
Execute quick task ${quick_id}.
|
||||
|
||||
<files_to_read>
|
||||
- ${QUICK_DIR}/${quick_id}-PLAN.md (Plan)
|
||||
- .planning/STATE.md (Project state)
|
||||
- ./CLAUDE.md (Project instructions, if exists)
|
||||
- .claude/skills/ or .agents/skills/ (Project skills, if either exists — list skills, read SKILL.md for each, follow relevant rules during implementation)
|
||||
</files_to_read>
|
||||
|
||||
<constraints>
|
||||
- Execute all tasks in the plan
|
||||
- Commit each task atomically
|
||||
- Create summary at: ${QUICK_DIR}/${quick_id}-SUMMARY.md
|
||||
- Do NOT update ROADMAP.md (quick tasks are separate from planned phases)
|
||||
</constraints>
|
||||
",
|
||||
subagent_type="gsd-executor",
|
||||
model="{executor_model}",
|
||||
description="Execute: ${DESCRIPTION}"
|
||||
)
|
||||
```
|
||||
|
||||
After executor returns:
|
||||
1. Verify summary exists at `${QUICK_DIR}/${quick_id}-SUMMARY.md`
|
||||
2. Extract commit hash from executor output
|
||||
3. Report completion status
|
||||
|
||||
**Known Claude Code bug (classifyHandoffIfNeeded):** If executor reports "failed" with error `classifyHandoffIfNeeded is not defined`, this is a Claude Code runtime bug — not a real failure. Check if summary file exists and git log shows commits. If so, treat as successful.
|
||||
|
||||
If summary not found, error: "Executor failed to create ${quick_id}-SUMMARY.md"
|
||||
|
||||
Note: For quick tasks producing multiple plans (rare), spawn executors in parallel waves per execute-phase patterns.
|
||||
|
||||
---
|
||||
|
||||
**Step 6.5: Verification (only when `$FULL_MODE`)**
|
||||
|
||||
Skip this step entirely if NOT `$FULL_MODE`.
|
||||
|
||||
Display banner:
|
||||
```
|
||||
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
|
||||
GSD ► VERIFYING RESULTS
|
||||
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
|
||||
|
||||
◆ Spawning verifier...
|
||||
```
|
||||
|
||||
```
|
||||
Task(
|
||||
prompt="Verify quick task goal achievement.
|
||||
Task directory: ${QUICK_DIR}
|
||||
Task goal: ${DESCRIPTION}
|
||||
|
||||
<files_to_read>
|
||||
- ${QUICK_DIR}/${quick_id}-PLAN.md (Plan)
|
||||
</files_to_read>
|
||||
|
||||
Check must_haves against actual codebase. Create VERIFICATION.md at ${QUICK_DIR}/${quick_id}-VERIFICATION.md.",
|
||||
subagent_type="gsd-verifier",
|
||||
model="{verifier_model}",
|
||||
description="Verify: ${DESCRIPTION}"
|
||||
)
|
||||
```
|
||||
|
||||
Read verification status:
|
||||
```bash
|
||||
grep "^status:" "${QUICK_DIR}/${quick_id}-VERIFICATION.md" | cut -d: -f2 | tr -d ' '
|
||||
```
|
||||
|
||||
Store as `$VERIFICATION_STATUS`.
|
||||
|
||||
| Status | Action |
|
||||
|--------|--------|
|
||||
| `passed` | Store `$VERIFICATION_STATUS = "Verified"`, continue to step 7 |
|
||||
| `human_needed` | Display items needing manual check, store `$VERIFICATION_STATUS = "Needs Review"`, continue |
|
||||
| `gaps_found` | Display gap summary, offer: 1) Re-run executor to fix gaps, 2) Accept as-is. Store `$VERIFICATION_STATUS = "Gaps"` |
|
||||
|
||||
---
|
||||
|
||||
**Step 7: Update STATE.md**
|
||||
|
||||
Update STATE.md with quick task completion record.
|
||||
|
||||
**7a. Check if "Quick Tasks Completed" section exists:**
|
||||
|
||||
Read STATE.md and check for `### Quick Tasks Completed` section.
|
||||
|
||||
**7b. If section doesn't exist, create it:**
|
||||
|
||||
Insert after `### Blockers/Concerns` section:
|
||||
|
||||
**If `$FULL_MODE`:**
|
||||
```markdown
|
||||
### Quick Tasks Completed
|
||||
|
||||
| # | Description | Date | Commit | Status | Directory |
|
||||
|---|-------------|------|--------|--------|-----------|
|
||||
```
|
||||
|
||||
**If NOT `$FULL_MODE`:**
|
||||
```markdown
|
||||
### Quick Tasks Completed
|
||||
|
||||
| # | Description | Date | Commit | Directory |
|
||||
|---|-------------|------|--------|-----------|
|
||||
```
|
||||
|
||||
**Note:** If the table already exists, match its existing column format. If adding `--full` to a project that already has quick tasks without a Status column, add the Status column to the header and separator rows, and leave Status empty for the new row's predecessors.
|
||||
|
||||
**7c. Append new row to table:**
|
||||
|
||||
Use `date` from init:
|
||||
|
||||
**If `$FULL_MODE` (or table has Status column):**
|
||||
```markdown
|
||||
| ${quick_id} | ${DESCRIPTION} | ${date} | ${commit_hash} | ${VERIFICATION_STATUS} | [${quick_id}-${slug}](./quick/${quick_id}-${slug}/) |
|
||||
```
|
||||
|
||||
**If NOT `$FULL_MODE` (and table has no Status column):**
|
||||
```markdown
|
||||
| ${quick_id} | ${DESCRIPTION} | ${date} | ${commit_hash} | [${quick_id}-${slug}](./quick/${quick_id}-${slug}/) |
|
||||
```
|
||||
|
||||
**7d. Update "Last activity" line:**
|
||||
|
||||
Use `date` from init:
|
||||
```
|
||||
Last activity: ${date} - Completed quick task ${quick_id}: ${DESCRIPTION}
|
||||
```
|
||||
|
||||
Use Edit tool to make these changes atomically
|
||||
|
||||
---
|
||||
|
||||
**Step 8: Final commit and completion**
|
||||
|
||||
Stage and commit quick task artifacts:
|
||||
|
||||
Build file list:
|
||||
- `${QUICK_DIR}/${quick_id}-PLAN.md`
|
||||
- `${QUICK_DIR}/${quick_id}-SUMMARY.md`
|
||||
- `.planning/STATE.md`
|
||||
- If `$DISCUSS_MODE` and context file exists: `${QUICK_DIR}/${quick_id}-CONTEXT.md`
|
||||
- If `$RESEARCH_MODE` and research file exists: `${QUICK_DIR}/${quick_id}-RESEARCH.md`
|
||||
- If `$FULL_MODE` and verification file exists: `${QUICK_DIR}/${quick_id}-VERIFICATION.md`
|
||||
|
||||
```bash
|
||||
node "C:/Users/yaoji/.claude/get-shit-done/bin/gsd-tools.cjs" commit "docs(quick-${quick_id}): ${DESCRIPTION}" --files ${file_list}
|
||||
```
|
||||
|
||||
Get final commit hash:
|
||||
```bash
|
||||
commit_hash=$(git rev-parse --short HEAD)
|
||||
```
|
||||
|
||||
Display completion output:
|
||||
|
||||
**If `$FULL_MODE`:**
|
||||
```
|
||||
---
|
||||
|
||||
GSD > QUICK TASK COMPLETE (FULL MODE)
|
||||
|
||||
Quick Task ${quick_id}: ${DESCRIPTION}
|
||||
|
||||
${RESEARCH_MODE ? 'Research: ' + QUICK_DIR + '/' + quick_id + '-RESEARCH.md' : ''}
|
||||
Summary: ${QUICK_DIR}/${quick_id}-SUMMARY.md
|
||||
Verification: ${QUICK_DIR}/${quick_id}-VERIFICATION.md (${VERIFICATION_STATUS})
|
||||
Commit: ${commit_hash}
|
||||
|
||||
---
|
||||
|
||||
Ready for next task: /gsd:quick
|
||||
```
|
||||
|
||||
**If NOT `$FULL_MODE`:**
|
||||
```
|
||||
---
|
||||
|
||||
GSD > QUICK TASK COMPLETE
|
||||
|
||||
Quick Task ${quick_id}: ${DESCRIPTION}
|
||||
|
||||
${RESEARCH_MODE ? 'Research: ' + QUICK_DIR + '/' + quick_id + '-RESEARCH.md' : ''}
|
||||
Summary: ${QUICK_DIR}/${quick_id}-SUMMARY.md
|
||||
Commit: ${commit_hash}
|
||||
|
||||
---
|
||||
|
||||
Ready for next task: /gsd:quick
|
||||
```
|
||||
|
||||
</process>
|
||||
|
||||
<success_criteria>
|
||||
- [ ] ROADMAP.md validation passes
|
||||
- [ ] User provides task description
|
||||
- [ ] `--full`, `--discuss`, and `--research` flags parsed from arguments when present
|
||||
- [ ] Slug generated (lowercase, hyphens, max 40 chars)
|
||||
- [ ] Quick ID generated (YYMMDD-xxx format, 2s Base36 precision)
|
||||
- [ ] Directory created at `.planning/quick/YYMMDD-xxx-slug/`
|
||||
- [ ] (--discuss) Gray areas identified and presented, decisions captured in `${quick_id}-CONTEXT.md`
|
||||
- [ ] (--research) Research agent spawned, `${quick_id}-RESEARCH.md` created
|
||||
- [ ] `${quick_id}-PLAN.md` created by planner (honors CONTEXT.md decisions when --discuss, uses RESEARCH.md findings when --research)
|
||||
- [ ] (--full) Plan checker validates plan, revision loop capped at 2
|
||||
- [ ] `${quick_id}-SUMMARY.md` created by executor
|
||||
- [ ] (--full) `${quick_id}-VERIFICATION.md` created by verifier
|
||||
- [ ] STATE.md updated with quick task row (Status column when --full)
|
||||
- [ ] Artifacts committed
|
||||
</success_criteria>
|
||||
155
get-shit-done/workflows/remove-phase.md
Normal file
155
get-shit-done/workflows/remove-phase.md
Normal file
@@ -0,0 +1,155 @@
|
||||
<purpose>
|
||||
Remove an unstarted future phase from the project roadmap, delete its directory, renumber all subsequent phases to maintain a clean linear sequence, and commit the change. The git commit serves as the historical record of removal.
|
||||
</purpose>
|
||||
|
||||
<required_reading>
|
||||
Read all files referenced by the invoking prompt's execution_context before starting.
|
||||
</required_reading>
|
||||
|
||||
<process>
|
||||
|
||||
<step name="parse_arguments">
|
||||
Parse the command arguments:
|
||||
- Argument is the phase number to remove (integer or decimal)
|
||||
- Example: `/gsd:remove-phase 17` → phase = 17
|
||||
- Example: `/gsd:remove-phase 16.1` → phase = 16.1
|
||||
|
||||
If no argument provided:
|
||||
|
||||
```
|
||||
ERROR: Phase number required
|
||||
Usage: /gsd:remove-phase <phase-number>
|
||||
Example: /gsd:remove-phase 17
|
||||
```
|
||||
|
||||
Exit.
|
||||
</step>
|
||||
|
||||
<step name="init_context">
|
||||
Load phase operation context:
|
||||
|
||||
```bash
|
||||
INIT=$(node "C:/Users/yaoji/.claude/get-shit-done/bin/gsd-tools.cjs" init phase-op "${target}")
|
||||
if [[ "$INIT" == @file:* ]]; then INIT=$(cat "${INIT#@file:}"); fi
|
||||
```
|
||||
|
||||
Extract: `phase_found`, `phase_dir`, `phase_number`, `commit_docs`, `roadmap_exists`.
|
||||
|
||||
Also read STATE.md and ROADMAP.md content for parsing current position.
|
||||
</step>
|
||||
|
||||
<step name="validate_future_phase">
|
||||
Verify the phase is a future phase (not started):
|
||||
|
||||
1. Compare target phase to current phase from STATE.md
|
||||
2. Target must be > current phase number
|
||||
|
||||
If target <= current phase:
|
||||
|
||||
```
|
||||
ERROR: Cannot remove Phase {target}
|
||||
|
||||
Only future phases can be removed:
|
||||
- Current phase: {current}
|
||||
- Phase {target} is current or completed
|
||||
|
||||
To abandon current work, use /gsd:pause-work instead.
|
||||
```
|
||||
|
||||
Exit.
|
||||
</step>
|
||||
|
||||
<step name="confirm_removal">
|
||||
Present removal summary and confirm:
|
||||
|
||||
```
|
||||
Removing Phase {target}: {Name}
|
||||
|
||||
This will:
|
||||
- Delete: .planning/phases/{target}-{slug}/
|
||||
- Renumber all subsequent phases
|
||||
- Update: ROADMAP.md, STATE.md
|
||||
|
||||
Proceed? (y/n)
|
||||
```
|
||||
|
||||
Wait for confirmation.
|
||||
</step>
|
||||
|
||||
<step name="execute_removal">
|
||||
**Delegate the entire removal operation to gsd-tools:**
|
||||
|
||||
```bash
|
||||
RESULT=$(node "C:/Users/yaoji/.claude/get-shit-done/bin/gsd-tools.cjs" phase remove "${target}")
|
||||
```
|
||||
|
||||
If the phase has executed plans (SUMMARY.md files), gsd-tools will error. Use `--force` only if the user confirms:
|
||||
|
||||
```bash
|
||||
RESULT=$(node "C:/Users/yaoji/.claude/get-shit-done/bin/gsd-tools.cjs" phase remove "${target}" --force)
|
||||
```
|
||||
|
||||
The CLI handles:
|
||||
- Deleting the phase directory
|
||||
- Renumbering all subsequent directories (in reverse order to avoid conflicts)
|
||||
- Renaming all files inside renumbered directories (PLAN.md, SUMMARY.md, etc.)
|
||||
- Updating ROADMAP.md (removing section, renumbering all phase references, updating dependencies)
|
||||
- Updating STATE.md (decrementing phase count)
|
||||
|
||||
Extract from result: `removed`, `directory_deleted`, `renamed_directories`, `renamed_files`, `roadmap_updated`, `state_updated`.
|
||||
</step>
|
||||
|
||||
<step name="commit">
|
||||
Stage and commit the removal:
|
||||
|
||||
```bash
|
||||
node "C:/Users/yaoji/.claude/get-shit-done/bin/gsd-tools.cjs" commit "chore: remove phase {target} ({original-phase-name})" --files .planning/
|
||||
```
|
||||
|
||||
The commit message preserves the historical record of what was removed.
|
||||
</step>
|
||||
|
||||
<step name="completion">
|
||||
Present completion summary:
|
||||
|
||||
```
|
||||
Phase {target} ({original-name}) removed.
|
||||
|
||||
Changes:
|
||||
- Deleted: .planning/phases/{target}-{slug}/
|
||||
- Renumbered: {N} directories and {M} files
|
||||
- Updated: ROADMAP.md, STATE.md
|
||||
- Committed: chore: remove phase {target} ({original-name})
|
||||
|
||||
---
|
||||
|
||||
## What's Next
|
||||
|
||||
Would you like to:
|
||||
- `/gsd:progress` — see updated roadmap status
|
||||
- Continue with current phase
|
||||
- Review roadmap
|
||||
|
||||
---
|
||||
```
|
||||
</step>
|
||||
|
||||
</process>
|
||||
|
||||
<anti_patterns>
|
||||
|
||||
- Don't remove completed phases (have SUMMARY.md files) without --force
|
||||
- Don't remove current or past phases
|
||||
- Don't manually renumber — use `gsd-tools phase remove` which handles all renumbering
|
||||
- Don't add "removed phase" notes to STATE.md — git commit is the record
|
||||
- Don't modify completed phase directories
|
||||
</anti_patterns>
|
||||
|
||||
<success_criteria>
|
||||
Phase removal is complete when:
|
||||
|
||||
- [ ] Target phase validated as future/unstarted
|
||||
- [ ] `gsd-tools phase remove` executed successfully
|
||||
- [ ] Changes committed with descriptive message
|
||||
- [ ] User informed of changes
|
||||
</success_criteria>
|
||||
74
get-shit-done/workflows/research-phase.md
Normal file
74
get-shit-done/workflows/research-phase.md
Normal file
@@ -0,0 +1,74 @@
|
||||
<purpose>
|
||||
Research how to implement a phase. Spawns gsd-phase-researcher with phase context.
|
||||
|
||||
Standalone research command. For most workflows, use `/gsd:plan-phase` which integrates research automatically.
|
||||
</purpose>
|
||||
|
||||
<process>
|
||||
|
||||
## Step 0: Resolve Model Profile
|
||||
|
||||
@C:/Users/yaoji/.claude/get-shit-done/references/model-profile-resolution.md
|
||||
|
||||
Resolve model for:
|
||||
- `gsd-phase-researcher`
|
||||
|
||||
## Step 1: Normalize and Validate Phase
|
||||
|
||||
@C:/Users/yaoji/.claude/get-shit-done/references/phase-argument-parsing.md
|
||||
|
||||
```bash
|
||||
PHASE_INFO=$(node "C:/Users/yaoji/.claude/get-shit-done/bin/gsd-tools.cjs" roadmap get-phase "${PHASE}")
|
||||
```
|
||||
|
||||
If `found` is false: Error and exit.
|
||||
|
||||
## Step 2: Check Existing Research
|
||||
|
||||
```bash
|
||||
ls .planning/phases/${PHASE}-*/RESEARCH.md 2>/dev/null
|
||||
```
|
||||
|
||||
If exists: Offer update/view/skip options.
|
||||
|
||||
## Step 3: Gather Phase Context
|
||||
|
||||
```bash
|
||||
INIT=$(node "C:/Users/yaoji/.claude/get-shit-done/bin/gsd-tools.cjs" init phase-op "${PHASE}")
|
||||
if [[ "$INIT" == @file:* ]]; then INIT=$(cat "${INIT#@file:}"); fi
|
||||
# Extract: phase_dir, padded_phase, phase_number, state_path, requirements_path, context_path
|
||||
```
|
||||
|
||||
## Step 4: Spawn Researcher
|
||||
|
||||
```
|
||||
Task(
|
||||
prompt="<objective>
|
||||
Research implementation approach for Phase {phase}: {name}
|
||||
</objective>
|
||||
|
||||
<files_to_read>
|
||||
- {context_path} (USER DECISIONS from /gsd:discuss-phase)
|
||||
- {requirements_path} (Project requirements)
|
||||
- {state_path} (Project decisions and history)
|
||||
</files_to_read>
|
||||
|
||||
<additional_context>
|
||||
Phase description: {description}
|
||||
</additional_context>
|
||||
|
||||
<output>
|
||||
Write to: .planning/phases/${PHASE}-{slug}/${PHASE}-RESEARCH.md
|
||||
</output>",
|
||||
subagent_type="gsd-phase-researcher",
|
||||
model="{researcher_model}"
|
||||
)
|
||||
```
|
||||
|
||||
## Step 5: Handle Return
|
||||
|
||||
- `## RESEARCH COMPLETE` — Display summary, offer: Plan/Dig deeper/Review/Done
|
||||
- `## CHECKPOINT REACHED` — Present to user, spawn continuation
|
||||
- `## RESEARCH INCONCLUSIVE` — Show attempts, offer: Add context/Try different mode/Manual
|
||||
|
||||
</process>
|
||||
325
get-shit-done/workflows/resume-project.md
Normal file
325
get-shit-done/workflows/resume-project.md
Normal file
@@ -0,0 +1,325 @@
|
||||
<trigger>
|
||||
Use this workflow when:
|
||||
- Starting a new session on an existing project
|
||||
- User says "continue", "what's next", "where were we", "resume"
|
||||
- Any planning operation when .planning/ already exists
|
||||
- User returns after time away from project
|
||||
</trigger>
|
||||
|
||||
<purpose>
|
||||
Instantly restore full project context so "Where were we?" has an immediate, complete answer.
|
||||
</purpose>
|
||||
|
||||
<required_reading>
|
||||
@C:/Users/yaoji/.claude/get-shit-done/references/continuation-format.md
|
||||
</required_reading>
|
||||
|
||||
<process>
|
||||
|
||||
<step name="initialize">
|
||||
Load all context in one call:
|
||||
|
||||
```bash
|
||||
INIT=$(node "C:/Users/yaoji/.claude/get-shit-done/bin/gsd-tools.cjs" init resume)
|
||||
if [[ "$INIT" == @file:* ]]; then INIT=$(cat "${INIT#@file:}"); fi
|
||||
```
|
||||
|
||||
Parse JSON for: `state_exists`, `roadmap_exists`, `project_exists`, `planning_exists`, `has_interrupted_agent`, `interrupted_agent_id`, `commit_docs`.
|
||||
|
||||
**If `state_exists` is true:** Proceed to load_state
|
||||
**If `state_exists` is false but `roadmap_exists` or `project_exists` is true:** Offer to reconstruct STATE.md
|
||||
**If `planning_exists` is false:** This is a new project - route to /gsd:new-project
|
||||
</step>
|
||||
|
||||
<step name="load_state">
|
||||
|
||||
Read and parse STATE.md, then PROJECT.md:
|
||||
|
||||
```bash
|
||||
cat .planning/STATE.md
|
||||
cat .planning/PROJECT.md
|
||||
```
|
||||
|
||||
**From STATE.md extract:**
|
||||
|
||||
- **Project Reference**: Core value and current focus
|
||||
- **Current Position**: Phase X of Y, Plan A of B, Status
|
||||
- **Progress**: Visual progress bar
|
||||
- **Recent Decisions**: Key decisions affecting current work
|
||||
- **Pending Todos**: Ideas captured during sessions
|
||||
- **Blockers/Concerns**: Issues carried forward
|
||||
- **Session Continuity**: Where we left off, any resume files
|
||||
|
||||
**From PROJECT.md extract:**
|
||||
|
||||
- **What This Is**: Current accurate description
|
||||
- **Requirements**: Validated, Active, Out of Scope
|
||||
- **Key Decisions**: Full decision log with outcomes
|
||||
- **Constraints**: Hard limits on implementation
|
||||
|
||||
</step>
|
||||
|
||||
<step name="check_incomplete_work">
|
||||
Look for incomplete work that needs attention:
|
||||
|
||||
```bash
|
||||
# Check for structured handoff (preferred — machine-readable)
|
||||
cat .planning/HANDOFF.json 2>/dev/null
|
||||
|
||||
# Check for continue-here files (mid-plan resumption)
|
||||
ls .planning/phases/*/.continue-here*.md 2>/dev/null
|
||||
|
||||
# Check for plans without summaries (incomplete execution)
|
||||
for plan in .planning/phases/*/*-PLAN.md; do
|
||||
summary="${plan/PLAN/SUMMARY}"
|
||||
[ ! -f "$summary" ] && echo "Incomplete: $plan"
|
||||
done 2>/dev/null
|
||||
|
||||
# Check for interrupted agents (use has_interrupted_agent and interrupted_agent_id from init)
|
||||
if [ "$has_interrupted_agent" = "true" ]; then
|
||||
echo "Interrupted agent: $interrupted_agent_id"
|
||||
fi
|
||||
```
|
||||
|
||||
**If HANDOFF.json exists:**
|
||||
|
||||
- This is the primary resumption source — structured data from `/gsd:pause-work`
|
||||
- Parse `status`, `phase`, `plan`, `task`, `total_tasks`, `next_action`
|
||||
- Check `blockers` and `human_actions_pending` — surface these immediately
|
||||
- Check `completed_tasks` for `in_progress` items — these need attention first
|
||||
- Validate `uncommitted_files` against `git status` — flag divergence
|
||||
- Use `context_notes` to restore mental model
|
||||
- Flag: "Found structured handoff — resuming from task {task}/{total_tasks}"
|
||||
- **After successful resumption, delete HANDOFF.json** (it's a one-shot artifact)
|
||||
|
||||
**If .continue-here file exists (fallback):**
|
||||
|
||||
- This is a mid-plan resumption point
|
||||
- Read the file for specific resumption context
|
||||
- Flag: "Found mid-plan checkpoint"
|
||||
|
||||
**If PLAN without SUMMARY exists:**
|
||||
|
||||
- Execution was started but not completed
|
||||
- Flag: "Found incomplete plan execution"
|
||||
|
||||
**If interrupted agent found:**
|
||||
|
||||
- Subagent was spawned but session ended before completion
|
||||
- Read agent-history.json for task details
|
||||
- Flag: "Found interrupted agent"
|
||||
</step>
|
||||
|
||||
<step name="present_status">
|
||||
Present complete project status to user:
|
||||
|
||||
```
|
||||
╔══════════════════════════════════════════════════════════════╗
|
||||
║ PROJECT STATUS ║
|
||||
╠══════════════════════════════════════════════════════════════╣
|
||||
║ Building: [one-liner from PROJECT.md "What This Is"] ║
|
||||
║ ║
|
||||
║ Phase: [X] of [Y] - [Phase name] ║
|
||||
║ Plan: [A] of [B] - [Status] ║
|
||||
║ Progress: [██████░░░░] XX% ║
|
||||
║ ║
|
||||
║ Last activity: [date] - [what happened] ║
|
||||
╚══════════════════════════════════════════════════════════════╝
|
||||
|
||||
[If incomplete work found:]
|
||||
⚠️ Incomplete work detected:
|
||||
- [.continue-here file or incomplete plan]
|
||||
|
||||
[If interrupted agent found:]
|
||||
⚠️ Interrupted agent detected:
|
||||
Agent ID: [id]
|
||||
Task: [task description from agent-history.json]
|
||||
Interrupted: [timestamp]
|
||||
|
||||
Resume with: Task tool (resume parameter with agent ID)
|
||||
|
||||
[If pending todos exist:]
|
||||
📋 [N] pending todos — /gsd:check-todos to review
|
||||
|
||||
[If blockers exist:]
|
||||
⚠️ Carried concerns:
|
||||
- [blocker 1]
|
||||
- [blocker 2]
|
||||
|
||||
[If alignment is not ✓:]
|
||||
⚠️ Brief alignment: [status] - [assessment]
|
||||
```
|
||||
|
||||
</step>
|
||||
|
||||
<step name="determine_next_action">
|
||||
Based on project state, determine the most logical next action:
|
||||
|
||||
**If interrupted agent exists:**
|
||||
→ Primary: Resume interrupted agent (Task tool with resume parameter)
|
||||
→ Option: Start fresh (abandon agent work)
|
||||
|
||||
**If HANDOFF.json exists:**
|
||||
→ Primary: Resume from structured handoff (highest priority — specific task/blocker context)
|
||||
→ Option: Discard handoff and reassess from files
|
||||
|
||||
**If .continue-here file exists:**
|
||||
→ Fallback: Resume from checkpoint
|
||||
→ Option: Start fresh on current plan
|
||||
|
||||
**If incomplete plan (PLAN without SUMMARY):**
|
||||
→ Primary: Complete the incomplete plan
|
||||
→ Option: Abandon and move on
|
||||
|
||||
**If phase in progress, all plans complete:**
|
||||
→ Primary: Advance to next phase (via internal transition workflow)
|
||||
→ Option: Review completed work
|
||||
|
||||
**If phase ready to plan:**
|
||||
→ Check if CONTEXT.md exists for this phase:
|
||||
|
||||
- If CONTEXT.md missing:
|
||||
→ Primary: Discuss phase vision (how user imagines it working)
|
||||
→ Secondary: Plan directly (skip context gathering)
|
||||
- If CONTEXT.md exists:
|
||||
→ Primary: Plan the phase
|
||||
→ Option: Review roadmap
|
||||
|
||||
**If phase ready to execute:**
|
||||
→ Primary: Execute next plan
|
||||
→ Option: Review the plan first
|
||||
</step>
|
||||
|
||||
<step name="offer_options">
|
||||
Present contextual options based on project state:
|
||||
|
||||
```
|
||||
What would you like to do?
|
||||
|
||||
[Primary action based on state - e.g.:]
|
||||
1. Resume interrupted agent [if interrupted agent found]
|
||||
OR
|
||||
1. Execute phase (/gsd:execute-phase {phase})
|
||||
OR
|
||||
1. Discuss Phase 3 context (/gsd:discuss-phase 3) [if CONTEXT.md missing]
|
||||
OR
|
||||
1. Plan Phase 3 (/gsd:plan-phase 3) [if CONTEXT.md exists or discuss option declined]
|
||||
|
||||
[Secondary options:]
|
||||
2. Review current phase status
|
||||
3. Check pending todos ([N] pending)
|
||||
4. Review brief alignment
|
||||
5. Something else
|
||||
```
|
||||
|
||||
**Note:** When offering phase planning, check for CONTEXT.md existence first:
|
||||
|
||||
```bash
|
||||
ls .planning/phases/XX-name/*-CONTEXT.md 2>/dev/null
|
||||
```
|
||||
|
||||
If missing, suggest discuss-phase before plan. If exists, offer plan directly.
|
||||
|
||||
Wait for user selection.
|
||||
</step>
|
||||
|
||||
<step name="route_to_workflow">
|
||||
Based on user selection, route to appropriate workflow:
|
||||
|
||||
- **Execute plan** → Show command for user to run after clearing:
|
||||
```
|
||||
---
|
||||
|
||||
## ▶ Next Up
|
||||
|
||||
**{phase}-{plan}: [Plan Name]** — [objective from PLAN.md]
|
||||
|
||||
`/gsd:execute-phase {phase}`
|
||||
|
||||
<sub>`/clear` first → fresh context window</sub>
|
||||
|
||||
---
|
||||
```
|
||||
- **Plan phase** → Show command for user to run after clearing:
|
||||
```
|
||||
---
|
||||
|
||||
## ▶ Next Up
|
||||
|
||||
**Phase [N]: [Name]** — [Goal from ROADMAP.md]
|
||||
|
||||
`/gsd:plan-phase [phase-number]`
|
||||
|
||||
<sub>`/clear` first → fresh context window</sub>
|
||||
|
||||
---
|
||||
|
||||
**Also available:**
|
||||
- `/gsd:discuss-phase [N]` — gather context first
|
||||
- `/gsd:research-phase [N]` — investigate unknowns
|
||||
|
||||
---
|
||||
```
|
||||
- **Advance to next phase** → ./transition.md (internal workflow, invoked inline — NOT a user command)
|
||||
- **Check todos** → Read .planning/todos/pending/, present summary
|
||||
- **Review alignment** → Read PROJECT.md, compare to current state
|
||||
- **Something else** → Ask what they need
|
||||
</step>
|
||||
|
||||
<step name="update_session">
|
||||
Before proceeding to routed workflow, update session continuity:
|
||||
|
||||
Update STATE.md:
|
||||
|
||||
```markdown
|
||||
## Session Continuity
|
||||
|
||||
Last session: [now]
|
||||
Stopped at: Session resumed, proceeding to [action]
|
||||
Resume file: [updated if applicable]
|
||||
```
|
||||
|
||||
This ensures if session ends unexpectedly, next resume knows the state.
|
||||
</step>
|
||||
|
||||
</process>
|
||||
|
||||
<reconstruction>
|
||||
If STATE.md is missing but other artifacts exist:
|
||||
|
||||
"STATE.md missing. Reconstructing from artifacts..."
|
||||
|
||||
1. Read PROJECT.md → Extract "What This Is" and Core Value
|
||||
2. Read ROADMAP.md → Determine phases, find current position
|
||||
3. Scan \*-SUMMARY.md files → Extract decisions, concerns
|
||||
4. Count pending todos in .planning/todos/pending/
|
||||
5. Check for .continue-here files → Session continuity
|
||||
|
||||
Reconstruct and write STATE.md, then proceed normally.
|
||||
|
||||
This handles cases where:
|
||||
|
||||
- Project predates STATE.md introduction
|
||||
- File was accidentally deleted
|
||||
- Cloning repo without full .planning/ state
|
||||
</reconstruction>
|
||||
|
||||
<quick_resume>
|
||||
If user says "continue" or "go":
|
||||
- Load state silently
|
||||
- Determine primary action
|
||||
- Execute immediately without presenting options
|
||||
|
||||
"Continuing from [state]... [action]"
|
||||
</quick_resume>
|
||||
|
||||
<success_criteria>
|
||||
Resume is complete when:
|
||||
|
||||
- [ ] STATE.md loaded (or reconstructed)
|
||||
- [ ] Incomplete work detected and flagged
|
||||
- [ ] Clear status presented to user
|
||||
- [ ] Contextual next actions offered
|
||||
- [ ] User knows exactly where project stands
|
||||
- [ ] Session continuity updated
|
||||
</success_criteria>
|
||||
146
get-shit-done/workflows/session-report.md
Normal file
146
get-shit-done/workflows/session-report.md
Normal file
@@ -0,0 +1,146 @@
|
||||
<purpose>
|
||||
Generate a post-session summary document capturing work performed, outcomes achieved, and estimated resource usage. Writes SESSION_REPORT.md to .planning/reports/ for human review and stakeholder sharing.
|
||||
</purpose>
|
||||
|
||||
<required_reading>
|
||||
Read all files referenced by the invoking prompt's execution_context before starting.
|
||||
</required_reading>
|
||||
|
||||
<process>
|
||||
|
||||
<step name="gather_session_data">
|
||||
Collect session data from available sources:
|
||||
|
||||
1. **STATE.md** — current phase, milestone, progress, blockers, decisions
|
||||
2. **Git log** — commits made during this session (last 24h or since last report)
|
||||
3. **Plan/Summary files** — plans executed, summaries written
|
||||
4. **ROADMAP.md** — milestone context and phase goals
|
||||
|
||||
```bash
|
||||
# Get recent commits (last 24 hours)
|
||||
git log --oneline --since="24 hours ago" --no-merges 2>/dev/null || echo "No recent commits"
|
||||
|
||||
# Count files changed
|
||||
git diff --stat HEAD~10 HEAD 2>/dev/null | tail -1 || echo "No diff available"
|
||||
```
|
||||
|
||||
Read `.planning/STATE.md` to get:
|
||||
- Current milestone and phase
|
||||
- Progress percentage
|
||||
- Active blockers
|
||||
- Recent decisions
|
||||
|
||||
Read `.planning/ROADMAP.md` to get milestone name and goals.
|
||||
|
||||
Check for existing reports:
|
||||
```bash
|
||||
ls -la .planning/reports/SESSION_REPORT*.md 2>/dev/null || echo "No previous reports"
|
||||
```
|
||||
</step>
|
||||
|
||||
<step name="estimate_usage">
|
||||
Estimate token usage from observable signals:
|
||||
|
||||
- Count of tool calls is not directly available, so estimate from git activity and file operations
|
||||
- Note: This is an **estimate** — exact token counts require API-level instrumentation not available to hooks
|
||||
|
||||
Estimation heuristics:
|
||||
- Each commit ≈ 1 plan cycle (research + plan + execute + verify)
|
||||
- Each plan file ≈ 2,000-5,000 tokens of agent context
|
||||
- Each summary file ≈ 1,000-2,000 tokens generated
|
||||
- Subagent spawns multiply by ~1.5x per agent type used
|
||||
</step>
|
||||
|
||||
<step name="generate_report">
|
||||
Create the report directory and file:
|
||||
|
||||
```bash
|
||||
mkdir -p .planning/reports
|
||||
```
|
||||
|
||||
Write `.planning/reports/SESSION_REPORT.md` (or `.planning/reports/YYYYMMDD-session-report.md` if previous reports exist):
|
||||
|
||||
```markdown
|
||||
# GSD Session Report
|
||||
|
||||
**Generated:** [timestamp]
|
||||
**Project:** [from PROJECT.md title or directory name]
|
||||
**Milestone:** [N] — [milestone name from ROADMAP.md]
|
||||
|
||||
---
|
||||
|
||||
## Session Summary
|
||||
|
||||
**Duration:** [estimated from first to last commit timestamp, or "Single session"]
|
||||
**Phase Progress:** [from STATE.md]
|
||||
**Plans Executed:** [count of summaries written this session]
|
||||
**Commits Made:** [count from git log]
|
||||
|
||||
## Work Performed
|
||||
|
||||
### Phases Touched
|
||||
[List phases worked on with brief description of what was done]
|
||||
|
||||
### Key Outcomes
|
||||
[Bullet list of concrete deliverables: files created, features implemented, bugs fixed]
|
||||
|
||||
### Decisions Made
|
||||
[From STATE.md decisions table, if any were added this session]
|
||||
|
||||
## Files Changed
|
||||
|
||||
[Summary of files modified, created, deleted — from git diff stat]
|
||||
|
||||
## Blockers & Open Items
|
||||
|
||||
[Active blockers from STATE.md]
|
||||
[Any TODO items created during session]
|
||||
|
||||
## Estimated Resource Usage
|
||||
|
||||
| Metric | Estimate |
|
||||
|--------|----------|
|
||||
| Commits | [N] |
|
||||
| Files changed | [N] |
|
||||
| Plans executed | [N] |
|
||||
| Subagents spawned | [estimated] |
|
||||
|
||||
> **Note:** Token and cost estimates require API-level instrumentation.
|
||||
> These metrics reflect observable session activity only.
|
||||
|
||||
---
|
||||
|
||||
*Generated by `/gsd:session-report`*
|
||||
```
|
||||
</step>
|
||||
|
||||
<step name="display_result">
|
||||
Show the user:
|
||||
|
||||
```
|
||||
## Session Report Generated
|
||||
|
||||
📄 `.planning/reports/[filename].md`
|
||||
|
||||
### Highlights
|
||||
- **Commits:** [N]
|
||||
- **Files changed:** [N]
|
||||
- **Phase progress:** [X]%
|
||||
- **Plans executed:** [N]
|
||||
```
|
||||
|
||||
If this is the first report, mention:
|
||||
```
|
||||
💡 Run `/gsd:session-report` at the end of each session to build a history of project activity.
|
||||
```
|
||||
</step>
|
||||
|
||||
</process>
|
||||
|
||||
<success_criteria>
|
||||
- [ ] Session data gathered from STATE.md, git log, and plan files
|
||||
- [ ] Report written to .planning/reports/
|
||||
- [ ] Report includes work summary, outcomes, and file changes
|
||||
- [ ] Filename includes date to prevent overwrites
|
||||
- [ ] Result summary displayed to user
|
||||
</success_criteria>
|
||||
256
get-shit-done/workflows/settings.md
Normal file
256
get-shit-done/workflows/settings.md
Normal file
@@ -0,0 +1,256 @@
|
||||
<purpose>
|
||||
Interactive configuration of GSD workflow agents (research, plan_check, verifier) and model profile selection via multi-question prompt. Updates .planning/config.json with user preferences. Optionally saves settings as global defaults (~/.gsd/defaults.json) for future projects.
|
||||
</purpose>
|
||||
|
||||
<required_reading>
|
||||
Read all files referenced by the invoking prompt's execution_context before starting.
|
||||
</required_reading>
|
||||
|
||||
<process>
|
||||
|
||||
<step name="ensure_and_load_config">
|
||||
Ensure config exists and load current state:
|
||||
|
||||
```bash
|
||||
node "C:/Users/yaoji/.claude/get-shit-done/bin/gsd-tools.cjs" config-ensure-section
|
||||
INIT=$(node "C:/Users/yaoji/.claude/get-shit-done/bin/gsd-tools.cjs" state load)
|
||||
if [[ "$INIT" == @file:* ]]; then INIT=$(cat "${INIT#@file:}"); fi
|
||||
```
|
||||
|
||||
Creates `.planning/config.json` with defaults if missing and loads current config values.
|
||||
</step>
|
||||
|
||||
<step name="read_current">
|
||||
```bash
|
||||
cat .planning/config.json
|
||||
```
|
||||
|
||||
Parse current values (default to `true` if not present):
|
||||
- `workflow.research` — spawn researcher during plan-phase
|
||||
- `workflow.plan_check` — spawn plan checker during plan-phase
|
||||
- `workflow.verifier` — spawn verifier during execute-phase
|
||||
- `workflow.nyquist_validation` — validation architecture research during plan-phase (default: true if absent)
|
||||
- `workflow.ui_phase` — generate UI-SPEC.md design contracts for frontend phases (default: true if absent)
|
||||
- `workflow.ui_safety_gate` — prompt to run /gsd:ui-phase before planning frontend phases (default: true if absent)
|
||||
- `model_profile` — which model each agent uses (default: `balanced`)
|
||||
- `git.branching_strategy` — branching approach (default: `"none"`)
|
||||
</step>
|
||||
|
||||
<step name="present_settings">
|
||||
Use AskUserQuestion with current values pre-selected:
|
||||
|
||||
```
|
||||
AskUserQuestion([
|
||||
{
|
||||
question: "Which model profile for agents?",
|
||||
header: "Model",
|
||||
multiSelect: false,
|
||||
options: [
|
||||
{ label: "Quality", description: "Opus everywhere except verification (highest cost)" },
|
||||
{ label: "Balanced (Recommended)", description: "Opus for planning, Sonnet for research/execution/verification" },
|
||||
{ label: "Budget", description: "Sonnet for writing, Haiku for research/verification (lowest cost)" },
|
||||
{ label: "Inherit", description: "Use current session model for all agents (best for OpenRouter, local models, or runtime model switching)" }
|
||||
]
|
||||
},
|
||||
{
|
||||
question: "Spawn Plan Researcher? (researches domain before planning)",
|
||||
header: "Research",
|
||||
multiSelect: false,
|
||||
options: [
|
||||
{ label: "Yes", description: "Research phase goals before planning" },
|
||||
{ label: "No", description: "Skip research, plan directly" }
|
||||
]
|
||||
},
|
||||
{
|
||||
question: "Spawn Plan Checker? (verifies plans before execution)",
|
||||
header: "Plan Check",
|
||||
multiSelect: false,
|
||||
options: [
|
||||
{ label: "Yes", description: "Verify plans meet phase goals" },
|
||||
{ label: "No", description: "Skip plan verification" }
|
||||
]
|
||||
},
|
||||
{
|
||||
question: "Spawn Execution Verifier? (verifies phase completion)",
|
||||
header: "Verifier",
|
||||
multiSelect: false,
|
||||
options: [
|
||||
{ label: "Yes", description: "Verify must-haves after execution" },
|
||||
{ label: "No", description: "Skip post-execution verification" }
|
||||
]
|
||||
},
|
||||
{
|
||||
question: "Auto-advance pipeline? (discuss → plan → execute automatically)",
|
||||
header: "Auto",
|
||||
multiSelect: false,
|
||||
options: [
|
||||
{ label: "No (Recommended)", description: "Manual /clear + paste between stages" },
|
||||
{ label: "Yes", description: "Chain stages via Task() subagents (same isolation)" }
|
||||
]
|
||||
},
|
||||
{
|
||||
question: "Enable Nyquist Validation? (researches test coverage during planning)",
|
||||
header: "Nyquist",
|
||||
multiSelect: false,
|
||||
options: [
|
||||
{ label: "Yes (Recommended)", description: "Research automated test coverage during plan-phase. Adds validation requirements to plans. Blocks approval if tasks lack automated verify." },
|
||||
{ label: "No", description: "Skip validation research. Good for rapid prototyping or no-test phases." }
|
||||
]
|
||||
},
|
||||
// Note: Nyquist validation depends on research output. If research is disabled,
|
||||
// plan-phase automatically skips Nyquist steps (no RESEARCH.md to extract from).
|
||||
{
|
||||
question: "Enable UI Phase? (generates UI-SPEC.md design contracts for frontend phases)",
|
||||
header: "UI Phase",
|
||||
multiSelect: false,
|
||||
options: [
|
||||
{ label: "Yes (Recommended)", description: "Generate UI design contracts before planning frontend phases. Locks spacing, typography, color, and copywriting." },
|
||||
{ label: "No", description: "Skip UI-SPEC generation. Good for backend-only projects or API phases." }
|
||||
]
|
||||
},
|
||||
{
|
||||
question: "Enable UI Safety Gate? (prompts to run /gsd:ui-phase before planning frontend phases)",
|
||||
header: "UI Gate",
|
||||
multiSelect: false,
|
||||
options: [
|
||||
{ label: "Yes (Recommended)", description: "plan-phase asks to run /gsd:ui-phase first when frontend indicators detected." },
|
||||
{ label: "No", description: "No prompt — plan-phase proceeds without UI-SPEC check." }
|
||||
]
|
||||
},
|
||||
{
|
||||
question: "Git branching strategy?",
|
||||
header: "Branching",
|
||||
multiSelect: false,
|
||||
options: [
|
||||
{ label: "None (Recommended)", description: "Commit directly to current branch" },
|
||||
{ label: "Per Phase", description: "Create branch for each phase (gsd/phase-{N}-{name})" },
|
||||
{ label: "Per Milestone", description: "Create branch for entire milestone (gsd/{version}-{name})" }
|
||||
]
|
||||
},
|
||||
{
|
||||
question: "Enable context window warnings? (injects advisory messages when context is getting full)",
|
||||
header: "Ctx Warnings",
|
||||
multiSelect: false,
|
||||
options: [
|
||||
{ label: "Yes (Recommended)", description: "Warn when context usage exceeds 65%. Helps avoid losing work." },
|
||||
{ label: "No", description: "Disable warnings. Allows Claude to reach auto-compact naturally. Good for long unattended runs." }
|
||||
]
|
||||
}
|
||||
])
|
||||
```
|
||||
</step>
|
||||
|
||||
<step name="update_config">
|
||||
Merge new settings into existing config.json:
|
||||
|
||||
```json
|
||||
{
|
||||
...existing_config,
|
||||
"model_profile": "quality" | "balanced" | "budget" | "inherit",
|
||||
"workflow": {
|
||||
"research": true/false,
|
||||
"plan_check": true/false,
|
||||
"verifier": true/false,
|
||||
"auto_advance": true/false,
|
||||
"nyquist_validation": true/false,
|
||||
"ui_phase": true/false,
|
||||
"ui_safety_gate": true/false
|
||||
},
|
||||
"git": {
|
||||
"branching_strategy": "none" | "phase" | "milestone"
|
||||
},
|
||||
"hooks": {
|
||||
"context_warnings": true/false
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
Write updated config to `.planning/config.json`.
|
||||
</step>
|
||||
|
||||
<step name="save_as_defaults">
|
||||
Ask whether to save these settings as global defaults for future projects:
|
||||
|
||||
```
|
||||
AskUserQuestion([
|
||||
{
|
||||
question: "Save these as default settings for all new projects?",
|
||||
header: "Defaults",
|
||||
multiSelect: false,
|
||||
options: [
|
||||
{ label: "Yes", description: "New projects start with these settings (saved to ~/.gsd/defaults.json)" },
|
||||
{ label: "No", description: "Only apply to this project" }
|
||||
]
|
||||
}
|
||||
])
|
||||
```
|
||||
|
||||
If "Yes": write the same config object (minus project-specific fields like `brave_search`) to `~/.gsd/defaults.json`:
|
||||
|
||||
```bash
|
||||
mkdir -p ~/.gsd
|
||||
```
|
||||
|
||||
Write `~/.gsd/defaults.json` with:
|
||||
```json
|
||||
{
|
||||
"mode": <current>,
|
||||
"granularity": <current>,
|
||||
"model_profile": <current>,
|
||||
"commit_docs": <current>,
|
||||
"parallelization": <current>,
|
||||
"branching_strategy": <current>,
|
||||
"workflow": {
|
||||
"research": <current>,
|
||||
"plan_check": <current>,
|
||||
"verifier": <current>,
|
||||
"auto_advance": <current>,
|
||||
"nyquist_validation": <current>,
|
||||
"ui_phase": <current>,
|
||||
"ui_safety_gate": <current>
|
||||
}
|
||||
}
|
||||
```
|
||||
</step>
|
||||
|
||||
<step name="confirm">
|
||||
Display:
|
||||
|
||||
```
|
||||
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
|
||||
GSD ► SETTINGS UPDATED
|
||||
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
|
||||
|
||||
| Setting | Value |
|
||||
|----------------------|-------|
|
||||
| Model Profile | {quality/balanced/budget/inherit} |
|
||||
| Plan Researcher | {On/Off} |
|
||||
| Plan Checker | {On/Off} |
|
||||
| Execution Verifier | {On/Off} |
|
||||
| Auto-Advance | {On/Off} |
|
||||
| Nyquist Validation | {On/Off} |
|
||||
| UI Phase | {On/Off} |
|
||||
| UI Safety Gate | {On/Off} |
|
||||
| Git Branching | {None/Per Phase/Per Milestone} |
|
||||
| Context Warnings | {On/Off} |
|
||||
| Saved as Defaults | {Yes/No} |
|
||||
|
||||
These settings apply to future /gsd:plan-phase and /gsd:execute-phase runs.
|
||||
|
||||
Quick commands:
|
||||
- /gsd:set-profile <profile> — switch model profile
|
||||
- /gsd:plan-phase --research — force research
|
||||
- /gsd:plan-phase --skip-research — skip research
|
||||
- /gsd:plan-phase --skip-verify — skip plan check
|
||||
```
|
||||
</step>
|
||||
|
||||
</process>
|
||||
|
||||
<success_criteria>
|
||||
- [ ] Current config read
|
||||
- [ ] User presented with 9 settings (profile + 7 workflow toggles + git branching)
|
||||
- [ ] Config updated with model_profile, workflow, and git sections
|
||||
- [ ] User offered to save as global defaults (~/.gsd/defaults.json)
|
||||
- [ ] Changes confirmed to user
|
||||
</success_criteria>
|
||||
228
get-shit-done/workflows/ship.md
Normal file
228
get-shit-done/workflows/ship.md
Normal file
@@ -0,0 +1,228 @@
|
||||
<purpose>
|
||||
Create a pull request from completed phase/milestone work, generate a rich PR body from planning artifacts, optionally run code review, and prepare for merge. Closes the plan → execute → verify → ship loop.
|
||||
</purpose>
|
||||
|
||||
<required_reading>
|
||||
Read all files referenced by the invoking prompt's execution_context before starting.
|
||||
</required_reading>
|
||||
|
||||
<process>
|
||||
|
||||
<step name="initialize">
|
||||
Parse arguments and load project state:
|
||||
|
||||
```bash
|
||||
INIT=$(node "C:/Users/yaoji/.claude/get-shit-done/bin/gsd-tools.cjs" init phase-op "${PHASE_ARG}")
|
||||
if [[ "$INIT" == @file:* ]]; then INIT=$(cat "${INIT#@file:}"); fi
|
||||
```
|
||||
|
||||
Parse from init JSON: `phase_found`, `phase_dir`, `phase_number`, `phase_name`, `padded_phase`, `commit_docs`.
|
||||
|
||||
Also load config for branching strategy:
|
||||
```bash
|
||||
CONFIG=$(node "C:/Users/yaoji/.claude/get-shit-done/bin/gsd-tools.cjs" state load)
|
||||
```
|
||||
|
||||
Extract: `branching_strategy`, `branch_name`.
|
||||
</step>
|
||||
|
||||
<step name="preflight_checks">
|
||||
Verify the work is ready to ship:
|
||||
|
||||
1. **Verification passed?**
|
||||
```bash
|
||||
VERIFICATION=$(cat ${PHASE_DIR}/*-VERIFICATION.md 2>/dev/null)
|
||||
```
|
||||
Check for `status: passed` or `status: human_needed` (with human approval).
|
||||
If no VERIFICATION.md or status is `gaps_found`: warn and ask user to confirm.
|
||||
|
||||
2. **Clean working tree?**
|
||||
```bash
|
||||
git status --short
|
||||
```
|
||||
If uncommitted changes exist: ask user to commit or stash first.
|
||||
|
||||
3. **On correct branch?**
|
||||
```bash
|
||||
CURRENT_BRANCH=$(git branch --show-current)
|
||||
```
|
||||
If on `main`/`master`: warn — should be on a feature branch.
|
||||
If branching_strategy is `none`: offer to create a branch now.
|
||||
|
||||
4. **Remote configured?**
|
||||
```bash
|
||||
git remote -v | head -2
|
||||
```
|
||||
Detect `origin` remote. If no remote: error — can't create PR.
|
||||
|
||||
5. **`gh` CLI available?**
|
||||
```bash
|
||||
which gh && gh auth status 2>&1
|
||||
```
|
||||
If `gh` not found or not authenticated: provide setup instructions and exit.
|
||||
</step>
|
||||
|
||||
<step name="push_branch">
|
||||
Push the current branch to remote:
|
||||
|
||||
```bash
|
||||
git push origin ${CURRENT_BRANCH} 2>&1
|
||||
```
|
||||
|
||||
If push fails (e.g., no upstream): set upstream:
|
||||
```bash
|
||||
git push --set-upstream origin ${CURRENT_BRANCH} 2>&1
|
||||
```
|
||||
|
||||
Report: "Pushed `{branch}` to origin ({commit_count} commits ahead of main)"
|
||||
</step>
|
||||
|
||||
<step name="generate_pr_body">
|
||||
Auto-generate a rich PR body from planning artifacts:
|
||||
|
||||
**1. Title:**
|
||||
```
|
||||
Phase {phase_number}: {phase_name}
|
||||
```
|
||||
Or for milestone: `Milestone {version}: {name}`
|
||||
|
||||
**2. Summary section:**
|
||||
Read ROADMAP.md for phase goal. Read VERIFICATION.md for verification status.
|
||||
|
||||
```markdown
|
||||
## Summary
|
||||
|
||||
**Phase {N}: {Name}**
|
||||
**Goal:** {goal from ROADMAP.md}
|
||||
**Status:** Verified ✓
|
||||
|
||||
{One paragraph synthesized from SUMMARY.md files — what was built}
|
||||
```
|
||||
|
||||
**3. Changes section:**
|
||||
For each SUMMARY.md in the phase directory:
|
||||
```markdown
|
||||
## Changes
|
||||
|
||||
### Plan {plan_id}: {plan_name}
|
||||
{one_liner from SUMMARY.md frontmatter}
|
||||
|
||||
**Key files:**
|
||||
{key-files.created and key-files.modified from SUMMARY.md frontmatter}
|
||||
```
|
||||
|
||||
**4. Requirements section:**
|
||||
```markdown
|
||||
## Requirements Addressed
|
||||
|
||||
{REQ-IDs from plan frontmatter, linked to REQUIREMENTS.md descriptions}
|
||||
```
|
||||
|
||||
**5. Testing section:**
|
||||
```markdown
|
||||
## Verification
|
||||
|
||||
- [x] Automated verification: {pass/fail from VERIFICATION.md}
|
||||
- {human verification items from VERIFICATION.md, if any}
|
||||
```
|
||||
|
||||
**6. Decisions section:**
|
||||
```markdown
|
||||
## Key Decisions
|
||||
|
||||
{Decisions from STATE.md accumulated context relevant to this phase}
|
||||
```
|
||||
</step>
|
||||
|
||||
<step name="create_pr">
|
||||
Create the PR using the generated body:
|
||||
|
||||
```bash
|
||||
gh pr create \
|
||||
--title "Phase ${PHASE_NUMBER}: ${PHASE_NAME}" \
|
||||
--body "${PR_BODY}" \
|
||||
--base main
|
||||
```
|
||||
|
||||
If `--draft` flag was passed: add `--draft`.
|
||||
|
||||
Report: "PR #{number} created: {url}"
|
||||
</step>
|
||||
|
||||
<step name="optional_review">
|
||||
Ask if user wants to trigger a code review:
|
||||
|
||||
```
|
||||
AskUserQuestion:
|
||||
question: "PR created. Run a code review before merge?"
|
||||
options:
|
||||
- label: "Skip review"
|
||||
description: "PR is ready — merge when CI passes"
|
||||
- label: "Self-review"
|
||||
description: "I'll review the diff in the PR myself"
|
||||
- label: "Request review"
|
||||
description: "Request review from a teammate"
|
||||
```
|
||||
|
||||
**If "Request review":**
|
||||
```bash
|
||||
gh pr edit ${PR_NUMBER} --add-reviewer "${REVIEWER}"
|
||||
```
|
||||
|
||||
**If "Self-review":**
|
||||
Report the PR URL and suggest: "Review the diff at {url}/files"
|
||||
</step>
|
||||
|
||||
<step name="track_shipping">
|
||||
Update STATE.md to reflect the shipping action:
|
||||
|
||||
```bash
|
||||
node "C:/Users/yaoji/.claude/get-shit-done/bin/gsd-tools.cjs" state update "Last Activity" "$(date +%Y-%m-%d)"
|
||||
node "C:/Users/yaoji/.claude/get-shit-done/bin/gsd-tools.cjs" state update "Status" "Phase ${PHASE_NUMBER} shipped — PR #${PR_NUMBER}"
|
||||
```
|
||||
|
||||
If `commit_docs` is true:
|
||||
```bash
|
||||
node "C:/Users/yaoji/.claude/get-shit-done/bin/gsd-tools.cjs" commit "docs(${padded_phase}): ship phase ${PHASE_NUMBER} — PR #${PR_NUMBER}" --files .planning/STATE.md
|
||||
```
|
||||
</step>
|
||||
|
||||
<step name="report">
|
||||
```
|
||||
───────────────────────────────────────────────────────────────
|
||||
|
||||
## ✓ Phase {X}: {Name} — Shipped
|
||||
|
||||
PR: #{number} ({url})
|
||||
Branch: {branch} → main
|
||||
Commits: {count}
|
||||
Verification: ✓ Passed
|
||||
Requirements: {N} REQ-IDs addressed
|
||||
|
||||
Next steps:
|
||||
- Review/approve PR
|
||||
- Merge when CI passes
|
||||
- /gsd:complete-milestone (if last phase in milestone)
|
||||
- /gsd:progress (to see what's next)
|
||||
|
||||
───────────────────────────────────────────────────────────────
|
||||
```
|
||||
</step>
|
||||
|
||||
</process>
|
||||
|
||||
<offer_next>
|
||||
After shipping:
|
||||
|
||||
- /gsd:complete-milestone — if all phases in milestone are done
|
||||
- /gsd:progress — see overall project state
|
||||
- /gsd:execute-phase {next} — continue to next phase
|
||||
</offer_next>
|
||||
|
||||
<success_criteria>
|
||||
- [ ] Preflight checks passed (verification, clean tree, branch, remote, gh)
|
||||
- [ ] Branch pushed to remote
|
||||
- [ ] PR created with rich auto-generated body
|
||||
- [ ] STATE.md updated with shipping status
|
||||
- [ ] User knows PR number and next steps
|
||||
</success_criteria>
|
||||
60
get-shit-done/workflows/stats.md
Normal file
60
get-shit-done/workflows/stats.md
Normal file
@@ -0,0 +1,60 @@
|
||||
<purpose>
|
||||
Display comprehensive project statistics including phases, plans, requirements, git metrics, and timeline.
|
||||
</purpose>
|
||||
|
||||
<required_reading>
|
||||
Read all files referenced by the invoking prompt's execution_context before starting.
|
||||
</required_reading>
|
||||
|
||||
<process>
|
||||
|
||||
<step name="gather_stats">
|
||||
Gather project statistics:
|
||||
|
||||
```bash
|
||||
STATS=$(node "$GSD_TOOLS" stats json)
|
||||
if [[ "$STATS" == @file:* ]]; then STATS=$(cat "${STATS#@file:}"); fi
|
||||
```
|
||||
|
||||
Extract fields from JSON: `milestone_version`, `milestone_name`, `phases`, `phases_completed`, `phases_total`, `total_plans`, `total_summaries`, `percent`, `plan_percent`, `requirements_total`, `requirements_complete`, `git_commits`, `git_first_commit_date`, `last_activity`.
|
||||
</step>
|
||||
|
||||
<step name="present_stats">
|
||||
Present to the user with this format:
|
||||
|
||||
```
|
||||
# 📊 Project Statistics — {milestone_version} {milestone_name}
|
||||
|
||||
## Progress
|
||||
[████████░░] X/Y phases (Z%)
|
||||
|
||||
## Plans
|
||||
X/Y plans complete (Z%)
|
||||
|
||||
## Phases
|
||||
| Phase | Name | Plans | Completed | Status |
|
||||
|-------|------|-------|-----------|--------|
|
||||
| ... | ... | ... | ... | ... |
|
||||
|
||||
## Requirements
|
||||
✅ X/Y requirements complete
|
||||
|
||||
## Git
|
||||
- **Commits:** N
|
||||
- **Started:** YYYY-MM-DD
|
||||
- **Last activity:** YYYY-MM-DD
|
||||
|
||||
## Timeline
|
||||
- **Project age:** N days
|
||||
```
|
||||
|
||||
If no `.planning/` directory exists, inform the user to run `/gsd:new-project` first.
|
||||
</step>
|
||||
|
||||
</process>
|
||||
|
||||
<success_criteria>
|
||||
- [ ] Statistics gathered from project state
|
||||
- [ ] Results formatted clearly
|
||||
- [ ] Displayed to user
|
||||
</success_criteria>
|
||||
560
get-shit-done/workflows/transition.md
Normal file
560
get-shit-done/workflows/transition.md
Normal file
@@ -0,0 +1,560 @@
|
||||
<internal_workflow>
|
||||
|
||||
**This is an INTERNAL workflow — NOT a user-facing command.**
|
||||
|
||||
There is no `/gsd:transition` command. This workflow is invoked automatically by
|
||||
`execute-phase` during auto-advance, or inline by the orchestrator after phase
|
||||
verification. Users should never be told to run `/gsd:transition`.
|
||||
|
||||
**Valid user commands for phase progression:**
|
||||
- `/gsd:discuss-phase {N}` — discuss a phase before planning
|
||||
- `/gsd:plan-phase {N}` — plan a phase
|
||||
- `/gsd:execute-phase {N}` — execute a phase
|
||||
- `/gsd:progress` — see roadmap progress
|
||||
|
||||
</internal_workflow>
|
||||
|
||||
<required_reading>
|
||||
|
||||
**Read these files NOW:**
|
||||
|
||||
1. `.planning/STATE.md`
|
||||
2. `.planning/PROJECT.md`
|
||||
3. `.planning/ROADMAP.md`
|
||||
4. Current phase's plan files (`*-PLAN.md`)
|
||||
5. Current phase's summary files (`*-SUMMARY.md`)
|
||||
|
||||
</required_reading>
|
||||
|
||||
<purpose>
|
||||
|
||||
Mark current phase complete and advance to next. This is the natural point where progress tracking and PROJECT.md evolution happen.
|
||||
|
||||
"Planning next phase" = "current phase is done"
|
||||
|
||||
</purpose>
|
||||
|
||||
<process>
|
||||
|
||||
<step name="load_project_state" priority="first">
|
||||
|
||||
Before transition, read project state:
|
||||
|
||||
```bash
|
||||
cat .planning/STATE.md 2>/dev/null
|
||||
cat .planning/PROJECT.md 2>/dev/null
|
||||
```
|
||||
|
||||
Parse current position to verify we're transitioning the right phase.
|
||||
Note accumulated context that may need updating after transition.
|
||||
|
||||
</step>
|
||||
|
||||
<step name="verify_completion">
|
||||
|
||||
Check current phase has all plan summaries:
|
||||
|
||||
```bash
|
||||
ls .planning/phases/XX-current/*-PLAN.md 2>/dev/null | sort
|
||||
ls .planning/phases/XX-current/*-SUMMARY.md 2>/dev/null | sort
|
||||
```
|
||||
|
||||
**Verification logic:**
|
||||
|
||||
- Count PLAN files
|
||||
- Count SUMMARY files
|
||||
- If counts match: all plans complete
|
||||
- If counts don't match: incomplete
|
||||
|
||||
<config-check>
|
||||
|
||||
```bash
|
||||
cat .planning/config.json 2>/dev/null
|
||||
```
|
||||
|
||||
</config-check>
|
||||
|
||||
**If all plans complete:**
|
||||
|
||||
<if mode="yolo">
|
||||
|
||||
```
|
||||
⚡ Auto-approved: Transition Phase [X] → Phase [X+1]
|
||||
Phase [X] complete — all [Y] plans finished.
|
||||
|
||||
Proceeding to mark done and advance...
|
||||
```
|
||||
|
||||
Proceed directly to cleanup_handoff step.
|
||||
|
||||
</if>
|
||||
|
||||
<if mode="interactive" OR="custom with gates.confirm_transition true">
|
||||
|
||||
Ask: "Phase [X] complete — all [Y] plans finished. Ready to mark done and move to Phase [X+1]?"
|
||||
|
||||
Wait for confirmation before proceeding.
|
||||
|
||||
</if>
|
||||
|
||||
**If plans incomplete:**
|
||||
|
||||
**SAFETY RAIL: always_confirm_destructive applies here.**
|
||||
Skipping incomplete plans is destructive — ALWAYS prompt regardless of mode.
|
||||
|
||||
Present:
|
||||
|
||||
```
|
||||
Phase [X] has incomplete plans:
|
||||
- {phase}-01-SUMMARY.md ✓ Complete
|
||||
- {phase}-02-SUMMARY.md ✗ Missing
|
||||
- {phase}-03-SUMMARY.md ✗ Missing
|
||||
|
||||
⚠️ Safety rail: Skipping plans requires confirmation (destructive action)
|
||||
|
||||
Options:
|
||||
1. Continue current phase (execute remaining plans)
|
||||
2. Mark complete anyway (skip remaining plans)
|
||||
3. Review what's left
|
||||
```
|
||||
|
||||
Wait for user decision.
|
||||
|
||||
</step>
|
||||
|
||||
<step name="cleanup_handoff">
|
||||
|
||||
Check for lingering handoffs:
|
||||
|
||||
```bash
|
||||
ls .planning/phases/XX-current/.continue-here*.md 2>/dev/null
|
||||
```
|
||||
|
||||
If found, delete them — phase is complete, handoffs are stale.
|
||||
|
||||
</step>
|
||||
|
||||
<step name="update_roadmap_and_state">
|
||||
|
||||
**Delegate ROADMAP.md and STATE.md updates to gsd-tools:**
|
||||
|
||||
```bash
|
||||
TRANSITION=$(node "C:/Users/yaoji/.claude/get-shit-done/bin/gsd-tools.cjs" phase complete "${current_phase}")
|
||||
```
|
||||
|
||||
The CLI handles:
|
||||
- Marking the phase checkbox as `[x]` complete with today's date
|
||||
- Updating plan count to final (e.g., "3/3 plans complete")
|
||||
- Updating the Progress table (Status → Complete, adding date)
|
||||
- Advancing STATE.md to next phase (Current Phase, Status → Ready to plan, Current Plan → Not started)
|
||||
- Detecting if this is the last phase in the milestone
|
||||
|
||||
Extract from result: `completed_phase`, `plans_executed`, `next_phase`, `next_phase_name`, `is_last_phase`.
|
||||
|
||||
</step>
|
||||
|
||||
<step name="archive_prompts">
|
||||
|
||||
If prompts were generated for the phase, they stay in place.
|
||||
The `completed/` subfolder pattern from create-meta-prompts handles archival.
|
||||
|
||||
</step>
|
||||
|
||||
<step name="evolve_project">
|
||||
|
||||
Evolve PROJECT.md to reflect learnings from completed phase.
|
||||
|
||||
**Read phase summaries:**
|
||||
|
||||
```bash
|
||||
cat .planning/phases/XX-current/*-SUMMARY.md
|
||||
```
|
||||
|
||||
**Assess requirement changes:**
|
||||
|
||||
1. **Requirements validated?**
|
||||
- Any Active requirements shipped in this phase?
|
||||
- Move to Validated with phase reference: `- ✓ [Requirement] — Phase X`
|
||||
|
||||
2. **Requirements invalidated?**
|
||||
- Any Active requirements discovered to be unnecessary or wrong?
|
||||
- Move to Out of Scope with reason: `- [Requirement] — [why invalidated]`
|
||||
|
||||
3. **Requirements emerged?**
|
||||
- Any new requirements discovered during building?
|
||||
- Add to Active: `- [ ] [New requirement]`
|
||||
|
||||
4. **Decisions to log?**
|
||||
- Extract decisions from SUMMARY.md files
|
||||
- Add to Key Decisions table with outcome if known
|
||||
|
||||
5. **"What This Is" still accurate?**
|
||||
- If the product has meaningfully changed, update the description
|
||||
- Keep it current and accurate
|
||||
|
||||
**Update PROJECT.md:**
|
||||
|
||||
Make the edits inline. Update "Last updated" footer:
|
||||
|
||||
```markdown
|
||||
---
|
||||
*Last updated: [date] after Phase [X]*
|
||||
```
|
||||
|
||||
**Example evolution:**
|
||||
|
||||
Before:
|
||||
|
||||
```markdown
|
||||
### Active
|
||||
|
||||
- [ ] JWT authentication
|
||||
- [ ] Real-time sync < 500ms
|
||||
- [ ] Offline mode
|
||||
|
||||
### Out of Scope
|
||||
|
||||
- OAuth2 — complexity not needed for v1
|
||||
```
|
||||
|
||||
After (Phase 2 shipped JWT auth, discovered rate limiting needed):
|
||||
|
||||
```markdown
|
||||
### Validated
|
||||
|
||||
- ✓ JWT authentication — Phase 2
|
||||
|
||||
### Active
|
||||
|
||||
- [ ] Real-time sync < 500ms
|
||||
- [ ] Offline mode
|
||||
- [ ] Rate limiting on sync endpoint
|
||||
|
||||
### Out of Scope
|
||||
|
||||
- OAuth2 — complexity not needed for v1
|
||||
```
|
||||
|
||||
**Step complete when:**
|
||||
|
||||
- [ ] Phase summaries reviewed for learnings
|
||||
- [ ] Validated requirements moved from Active
|
||||
- [ ] Invalidated requirements moved to Out of Scope with reason
|
||||
- [ ] Emerged requirements added to Active
|
||||
- [ ] New decisions logged with rationale
|
||||
- [ ] "What This Is" updated if product changed
|
||||
- [ ] "Last updated" footer reflects this transition
|
||||
|
||||
</step>
|
||||
|
||||
<step name="update_current_position_after_transition">
|
||||
|
||||
**Note:** Basic position updates (Current Phase, Status, Current Plan, Last Activity) were already handled by `gsd-tools phase complete` in the update_roadmap_and_state step.
|
||||
|
||||
Verify the updates are correct by reading STATE.md. If the progress bar needs updating, use:
|
||||
|
||||
```bash
|
||||
PROGRESS=$(node "C:/Users/yaoji/.claude/get-shit-done/bin/gsd-tools.cjs" progress bar --raw)
|
||||
```
|
||||
|
||||
Update the progress bar line in STATE.md with the result.
|
||||
|
||||
**Step complete when:**
|
||||
|
||||
- [ ] Phase number incremented to next phase (done by phase complete)
|
||||
- [ ] Plan status reset to "Not started" (done by phase complete)
|
||||
- [ ] Status shows "Ready to plan" (done by phase complete)
|
||||
- [ ] Progress bar reflects total completed plans
|
||||
|
||||
</step>
|
||||
|
||||
<step name="update_project_reference">
|
||||
|
||||
Update Project Reference section in STATE.md.
|
||||
|
||||
```markdown
|
||||
## Project Reference
|
||||
|
||||
See: .planning/PROJECT.md (updated [today])
|
||||
|
||||
**Core value:** [Current core value from PROJECT.md]
|
||||
**Current focus:** [Next phase name]
|
||||
```
|
||||
|
||||
Update the date and current focus to reflect the transition.
|
||||
|
||||
</step>
|
||||
|
||||
<step name="review_accumulated_context">
|
||||
|
||||
Review and update Accumulated Context section in STATE.md.
|
||||
|
||||
**Decisions:**
|
||||
|
||||
- Note recent decisions from this phase (3-5 max)
|
||||
- Full log lives in PROJECT.md Key Decisions table
|
||||
|
||||
**Blockers/Concerns:**
|
||||
|
||||
- Review blockers from completed phase
|
||||
- If addressed in this phase: Remove from list
|
||||
- If still relevant for future: Keep with "Phase X" prefix
|
||||
- Add any new concerns from completed phase's summaries
|
||||
|
||||
**Example:**
|
||||
|
||||
Before:
|
||||
|
||||
```markdown
|
||||
### Blockers/Concerns
|
||||
|
||||
- ⚠️ [Phase 1] Database schema not indexed for common queries
|
||||
- ⚠️ [Phase 2] WebSocket reconnection behavior on flaky networks unknown
|
||||
```
|
||||
|
||||
After (if database indexing was addressed in Phase 2):
|
||||
|
||||
```markdown
|
||||
### Blockers/Concerns
|
||||
|
||||
- ⚠️ [Phase 2] WebSocket reconnection behavior on flaky networks unknown
|
||||
```
|
||||
|
||||
**Step complete when:**
|
||||
|
||||
- [ ] Recent decisions noted (full log in PROJECT.md)
|
||||
- [ ] Resolved blockers removed from list
|
||||
- [ ] Unresolved blockers kept with phase prefix
|
||||
- [ ] New concerns from completed phase added
|
||||
|
||||
</step>
|
||||
|
||||
<step name="update_session_continuity_after_transition">
|
||||
|
||||
Update Session Continuity section in STATE.md to reflect transition completion.
|
||||
|
||||
**Format:**
|
||||
|
||||
```markdown
|
||||
Last session: [today]
|
||||
Stopped at: Phase [X] complete, ready to plan Phase [X+1]
|
||||
Resume file: None
|
||||
```
|
||||
|
||||
**Step complete when:**
|
||||
|
||||
- [ ] Last session timestamp updated to current date and time
|
||||
- [ ] Stopped at describes phase completion and next phase
|
||||
- [ ] Resume file confirmed as None (transitions don't use resume files)
|
||||
|
||||
</step>
|
||||
|
||||
<step name="offer_next_phase">
|
||||
|
||||
**MANDATORY: Verify milestone status before presenting next steps.**
|
||||
|
||||
**Use the transition result from `gsd-tools phase complete`:**
|
||||
|
||||
The `is_last_phase` field from the phase complete result tells you directly:
|
||||
- `is_last_phase: false` → More phases remain → Go to **Route A**
|
||||
- `is_last_phase: true` → Milestone complete → Go to **Route B**
|
||||
|
||||
The `next_phase` and `next_phase_name` fields give you the next phase details.
|
||||
|
||||
If you need additional context, use:
|
||||
```bash
|
||||
ROADMAP=$(node "C:/Users/yaoji/.claude/get-shit-done/bin/gsd-tools.cjs" roadmap analyze)
|
||||
```
|
||||
|
||||
This returns all phases with goals, disk status, and completion info.
|
||||
|
||||
---
|
||||
|
||||
**Route A: More phases remain in milestone**
|
||||
|
||||
Read ROADMAP.md to get the next phase's name and goal.
|
||||
|
||||
**Check if next phase has CONTEXT.md:**
|
||||
|
||||
```bash
|
||||
ls .planning/phases/*[X+1]*/*-CONTEXT.md 2>/dev/null
|
||||
```
|
||||
|
||||
**If next phase exists:**
|
||||
|
||||
<if mode="yolo">
|
||||
|
||||
**If CONTEXT.md exists:**
|
||||
|
||||
```
|
||||
Phase [X] marked complete.
|
||||
|
||||
Next: Phase [X+1] — [Name]
|
||||
|
||||
⚡ Auto-continuing: Plan Phase [X+1] in detail
|
||||
```
|
||||
|
||||
Exit skill and invoke SlashCommand("/gsd:plan-phase [X+1] --auto")
|
||||
|
||||
**If CONTEXT.md does NOT exist:**
|
||||
|
||||
```
|
||||
Phase [X] marked complete.
|
||||
|
||||
Next: Phase [X+1] — [Name]
|
||||
|
||||
⚡ Auto-continuing: Discuss Phase [X+1] first
|
||||
```
|
||||
|
||||
Exit skill and invoke SlashCommand("/gsd:discuss-phase [X+1] --auto")
|
||||
|
||||
</if>
|
||||
|
||||
<if mode="interactive" OR="custom with gates.confirm_transition true">
|
||||
|
||||
**If CONTEXT.md does NOT exist:**
|
||||
|
||||
```
|
||||
## ✓ Phase [X] Complete
|
||||
|
||||
---
|
||||
|
||||
## ▶ Next Up
|
||||
|
||||
**Phase [X+1]: [Name]** — [Goal from ROADMAP.md]
|
||||
|
||||
`/gsd:discuss-phase [X+1]` — gather context and clarify approach
|
||||
|
||||
<sub>`/clear` first → fresh context window</sub>
|
||||
|
||||
---
|
||||
|
||||
**Also available:**
|
||||
- `/gsd:plan-phase [X+1]` — skip discussion, plan directly
|
||||
- `/gsd:research-phase [X+1]` — investigate unknowns
|
||||
|
||||
---
|
||||
```
|
||||
|
||||
**If CONTEXT.md exists:**
|
||||
|
||||
```
|
||||
## ✓ Phase [X] Complete
|
||||
|
||||
---
|
||||
|
||||
## ▶ Next Up
|
||||
|
||||
**Phase [X+1]: [Name]** — [Goal from ROADMAP.md]
|
||||
<sub>✓ Context gathered, ready to plan</sub>
|
||||
|
||||
`/gsd:plan-phase [X+1]`
|
||||
|
||||
<sub>`/clear` first → fresh context window</sub>
|
||||
|
||||
---
|
||||
|
||||
**Also available:**
|
||||
- `/gsd:discuss-phase [X+1]` — revisit context
|
||||
- `/gsd:research-phase [X+1]` — investigate unknowns
|
||||
|
||||
---
|
||||
```
|
||||
|
||||
</if>
|
||||
|
||||
---
|
||||
|
||||
**Route B: Milestone complete (all phases done)**
|
||||
|
||||
**Clear auto-advance chain flag** — milestone boundary is the natural stopping point:
|
||||
```bash
|
||||
node "C:/Users/yaoji/.claude/get-shit-done/bin/gsd-tools.cjs" config-set workflow._auto_chain_active false
|
||||
```
|
||||
|
||||
<if mode="yolo">
|
||||
|
||||
```
|
||||
Phase {X} marked complete.
|
||||
|
||||
🎉 Milestone {version} is 100% complete — all {N} phases finished!
|
||||
|
||||
⚡ Auto-continuing: Complete milestone and archive
|
||||
```
|
||||
|
||||
Exit skill and invoke SlashCommand("/gsd:complete-milestone {version}")
|
||||
|
||||
</if>
|
||||
|
||||
<if mode="interactive" OR="custom with gates.confirm_transition true">
|
||||
|
||||
```
|
||||
## ✓ Phase {X}: {Phase Name} Complete
|
||||
|
||||
🎉 Milestone {version} is 100% complete — all {N} phases finished!
|
||||
|
||||
---
|
||||
|
||||
## ▶ Next Up
|
||||
|
||||
**Complete Milestone {version}** — archive and prepare for next
|
||||
|
||||
`/gsd:complete-milestone {version}`
|
||||
|
||||
<sub>`/clear` first → fresh context window</sub>
|
||||
|
||||
---
|
||||
|
||||
**Also available:**
|
||||
- Review accomplishments before archiving
|
||||
|
||||
---
|
||||
```
|
||||
|
||||
</if>
|
||||
|
||||
</step>
|
||||
|
||||
</process>
|
||||
|
||||
<implicit_tracking>
|
||||
Progress tracking is IMPLICIT: planning phase N implies phases 1-(N-1) complete. No separate progress step—forward motion IS progress.
|
||||
</implicit_tracking>
|
||||
|
||||
<partial_completion>
|
||||
|
||||
If user wants to move on but phase isn't fully complete:
|
||||
|
||||
```
|
||||
Phase [X] has incomplete plans:
|
||||
- {phase}-02-PLAN.md (not executed)
|
||||
- {phase}-03-PLAN.md (not executed)
|
||||
|
||||
Options:
|
||||
1. Mark complete anyway (plans weren't needed)
|
||||
2. Defer work to later phase
|
||||
3. Stay and finish current phase
|
||||
```
|
||||
|
||||
Respect user judgment — they know if work matters.
|
||||
|
||||
**If marking complete with incomplete plans:**
|
||||
|
||||
- Update ROADMAP: "2/3 plans complete" (not "3/3")
|
||||
- Note in transition message which plans were skipped
|
||||
|
||||
</partial_completion>
|
||||
|
||||
<success_criteria>
|
||||
|
||||
Transition is complete when:
|
||||
|
||||
- [ ] Current phase plan summaries verified (all exist or user chose to skip)
|
||||
- [ ] Any stale handoffs deleted
|
||||
- [ ] ROADMAP.md updated with completion status and plan count
|
||||
- [ ] PROJECT.md evolved (requirements, decisions, description if needed)
|
||||
- [ ] STATE.md updated (position, project reference, context, session)
|
||||
- [ ] Progress table updated
|
||||
- [ ] User knows next steps
|
||||
|
||||
</success_criteria>
|
||||
290
get-shit-done/workflows/ui-phase.md
Normal file
290
get-shit-done/workflows/ui-phase.md
Normal file
@@ -0,0 +1,290 @@
|
||||
<purpose>
|
||||
Generate a UI design contract (UI-SPEC.md) for frontend phases. Orchestrates gsd-ui-researcher and gsd-ui-checker with a revision loop. Inserts between discuss-phase and plan-phase in the lifecycle.
|
||||
|
||||
UI-SPEC.md locks spacing, typography, color, copywriting, and design system decisions before the planner creates tasks. This prevents design debt caused by ad-hoc styling decisions during execution.
|
||||
</purpose>
|
||||
|
||||
<required_reading>
|
||||
@C:/Users/yaoji/.claude/get-shit-done/references/ui-brand.md
|
||||
</required_reading>
|
||||
|
||||
<process>
|
||||
|
||||
## 1. Initialize
|
||||
|
||||
```bash
|
||||
INIT=$(node "C:/Users/yaoji/.claude/get-shit-done/bin/gsd-tools.cjs" 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`, `research_path`.
|
||||
|
||||
Resolve UI agent models:
|
||||
|
||||
```bash
|
||||
UI_RESEARCHER_MODEL=$(node "C:/Users/yaoji/.claude/get-shit-done/bin/gsd-tools.cjs" resolve-model gsd-ui-researcher --raw)
|
||||
UI_CHECKER_MODEL=$(node "C:/Users/yaoji/.claude/get-shit-done/bin/gsd-tools.cjs" resolve-model gsd-ui-checker --raw)
|
||||
```
|
||||
|
||||
Check config:
|
||||
|
||||
```bash
|
||||
UI_ENABLED=$(node "C:/Users/yaoji/.claude/get-shit-done/bin/gsd-tools.cjs" config-get workflow.ui_phase 2>/dev/null || echo "true")
|
||||
```
|
||||
|
||||
**If `UI_ENABLED` is `false`:**
|
||||
```
|
||||
UI 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=$(node "C:/Users/yaoji/.claude/get-shit-done/bin/gsd-tools.cjs" 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 design preferences.
|
||||
Continuing without user decisions — UI researcher will ask all questions.
|
||||
```
|
||||
Continue (non-blocking).
|
||||
|
||||
**If `has_research` is false:**
|
||||
```
|
||||
No RESEARCH.md found for Phase {N}.
|
||||
Note: stack decisions (component library, styling approach) will be asked during UI research.
|
||||
```
|
||||
Continue (non-blocking).
|
||||
|
||||
## 4. Check Existing UI-SPEC
|
||||
|
||||
```bash
|
||||
UI_SPEC_FILE=$(ls "${PHASE_DIR}"/*-UI-SPEC.md 2>/dev/null | head -1)
|
||||
```
|
||||
|
||||
**If exists:** Use AskUserQuestion:
|
||||
- header: "Existing UI-SPEC"
|
||||
- question: "UI-SPEC.md already exists for Phase {N}. What would you like to do?"
|
||||
- options:
|
||||
- "Update — re-run researcher with existing as baseline"
|
||||
- "View — display current UI-SPEC and exit"
|
||||
- "Skip — keep current UI-SPEC, proceed to verification"
|
||||
|
||||
If "View": display file contents, exit.
|
||||
If "Skip": proceed to step 7 (checker).
|
||||
If "Update": continue to step 5.
|
||||
|
||||
## 5. Spawn gsd-ui-researcher
|
||||
|
||||
Display:
|
||||
```
|
||||
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
|
||||
GSD ► UI DESIGN CONTRACT — PHASE {N}
|
||||
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
|
||||
|
||||
◆ Spawning UI researcher...
|
||||
```
|
||||
|
||||
Build prompt:
|
||||
|
||||
```markdown
|
||||
Read C:/Users/yaoji/.claude/agents/gsd-ui-researcher.md for instructions.
|
||||
|
||||
<objective>
|
||||
Create UI design contract for Phase {phase_number}: {phase_name}
|
||||
Answer: "What visual and interaction contracts does this phase need?"
|
||||
</objective>
|
||||
|
||||
<files_to_read>
|
||||
- {state_path} (Project State)
|
||||
- {roadmap_path} (Roadmap)
|
||||
- {requirements_path} (Requirements)
|
||||
- {context_path} (USER DECISIONS from /gsd:discuss-phase)
|
||||
- {research_path} (Technical Research — stack decisions)
|
||||
</files_to_read>
|
||||
|
||||
<output>
|
||||
Write to: {phase_dir}/{padded_phase}-UI-SPEC.md
|
||||
Template: C:/Users/yaoji/.claude/get-shit-done/templates/UI-SPEC.md
|
||||
</output>
|
||||
|
||||
<config>
|
||||
commit_docs: {commit_docs}
|
||||
phase_dir: {phase_dir}
|
||||
padded_phase: {padded_phase}
|
||||
</config>
|
||||
```
|
||||
|
||||
Omit null file paths from `<files_to_read>`.
|
||||
|
||||
```
|
||||
Task(
|
||||
prompt=ui_research_prompt,
|
||||
subagent_type="gsd-ui-researcher",
|
||||
model="{UI_RESEARCHER_MODEL}",
|
||||
description="UI Design Contract Phase {N}"
|
||||
)
|
||||
```
|
||||
|
||||
## 6. Handle Researcher Return
|
||||
|
||||
**If `## UI-SPEC COMPLETE`:**
|
||||
Display confirmation. Continue to step 7.
|
||||
|
||||
**If `## UI-SPEC BLOCKED`:**
|
||||
Display blocker details and options. Exit workflow.
|
||||
|
||||
## 7. Spawn gsd-ui-checker
|
||||
|
||||
Display:
|
||||
```
|
||||
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
|
||||
GSD ► VERIFYING UI-SPEC
|
||||
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
|
||||
|
||||
◆ Spawning UI checker...
|
||||
```
|
||||
|
||||
Build prompt:
|
||||
|
||||
```markdown
|
||||
Read C:/Users/yaoji/.claude/agents/gsd-ui-checker.md for instructions.
|
||||
|
||||
<objective>
|
||||
Validate UI design contract for Phase {phase_number}: {phase_name}
|
||||
Check all 6 dimensions. Return APPROVED or BLOCKED.
|
||||
</objective>
|
||||
|
||||
<files_to_read>
|
||||
- {phase_dir}/{padded_phase}-UI-SPEC.md (UI Design Contract — PRIMARY INPUT)
|
||||
- {context_path} (USER DECISIONS — check compliance)
|
||||
- {research_path} (Technical Research — check stack alignment)
|
||||
</files_to_read>
|
||||
|
||||
<config>
|
||||
ui_safety_gate: {ui_safety_gate config value}
|
||||
</config>
|
||||
```
|
||||
|
||||
```
|
||||
Task(
|
||||
prompt=ui_checker_prompt,
|
||||
subagent_type="gsd-ui-checker",
|
||||
model="{UI_CHECKER_MODEL}",
|
||||
description="Verify UI-SPEC Phase {N}"
|
||||
)
|
||||
```
|
||||
|
||||
## 8. Handle Checker Return
|
||||
|
||||
**If `## UI-SPEC VERIFIED`:**
|
||||
Display dimension results. Proceed to step 10.
|
||||
|
||||
**If `## ISSUES FOUND`:**
|
||||
Display blocking issues. Proceed to step 9.
|
||||
|
||||
## 9. Revision Loop (Max 2 Iterations)
|
||||
|
||||
Track `revision_count` (starts at 0).
|
||||
|
||||
**If `revision_count` < 2:**
|
||||
- Increment `revision_count`
|
||||
- Re-spawn gsd-ui-researcher with revision context:
|
||||
|
||||
```markdown
|
||||
<revision>
|
||||
The UI checker found issues with the current UI-SPEC.md.
|
||||
|
||||
### Issues to Fix
|
||||
{paste blocking issues from checker return}
|
||||
|
||||
Read the existing UI-SPEC.md, fix ONLY the listed issues, re-write the file.
|
||||
Do NOT re-ask the user questions that are already answered.
|
||||
</revision>
|
||||
```
|
||||
|
||||
- After researcher returns → re-spawn checker (step 7)
|
||||
|
||||
**If `revision_count` >= 2:**
|
||||
```
|
||||
Max revision iterations reached. Remaining issues:
|
||||
|
||||
{list remaining issues}
|
||||
|
||||
Options:
|
||||
1. Force approve — proceed with current UI-SPEC (FLAGs become accepted)
|
||||
2. Edit manually — open UI-SPEC.md in editor, re-run /gsd:ui-phase
|
||||
3. Abandon — exit without approving
|
||||
```
|
||||
|
||||
Use AskUserQuestion for the choice.
|
||||
|
||||
## 10. Present Final Status
|
||||
|
||||
Display:
|
||||
```
|
||||
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
|
||||
GSD ► UI-SPEC READY ✓
|
||||
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
|
||||
|
||||
**Phase {N}: {Name}** — UI design contract approved
|
||||
|
||||
Dimensions: 6/6 passed
|
||||
{If any FLAGs: "Recommendations: {N} (non-blocking)"}
|
||||
|
||||
───────────────────────────────────────────────────────────────
|
||||
|
||||
## ▶ Next Up
|
||||
|
||||
**Plan Phase {N}** — planner will use UI-SPEC.md as design context
|
||||
|
||||
`/gsd:plan-phase {N}`
|
||||
|
||||
<sub>/clear first → fresh context window</sub>
|
||||
|
||||
───────────────────────────────────────────────────────────────
|
||||
```
|
||||
|
||||
## 11. Commit (if configured)
|
||||
|
||||
```bash
|
||||
node "C:/Users/yaoji/.claude/get-shit-done/bin/gsd-tools.cjs" commit "docs(${padded_phase}): UI design contract" --files "${PHASE_DIR}/${PADDED_PHASE}-UI-SPEC.md"
|
||||
```
|
||||
|
||||
## 12. Update State
|
||||
|
||||
```bash
|
||||
node "C:/Users/yaoji/.claude/get-shit-done/bin/gsd-tools.cjs" state record-session \
|
||||
--stopped-at "Phase ${PHASE} UI-SPEC approved" \
|
||||
--resume-file "${PHASE_DIR}/${PADDED_PHASE}-UI-SPEC.md"
|
||||
```
|
||||
|
||||
</process>
|
||||
|
||||
<success_criteria>
|
||||
- [ ] Config checked (exit if ui_phase disabled)
|
||||
- [ ] Phase validated against roadmap
|
||||
- [ ] Prerequisites checked (CONTEXT.md, RESEARCH.md — non-blocking warnings)
|
||||
- [ ] Existing UI-SPEC handled (update/view/skip)
|
||||
- [ ] gsd-ui-researcher spawned with correct context and file paths
|
||||
- [ ] UI-SPEC.md created in correct location
|
||||
- [ ] gsd-ui-checker spawned with UI-SPEC.md
|
||||
- [ ] All 6 dimensions evaluated
|
||||
- [ ] Revision loop if BLOCKED (max 2 iterations)
|
||||
- [ ] Final status displayed with next steps
|
||||
- [ ] UI-SPEC.md committed (if commit_docs enabled)
|
||||
- [ ] State updated
|
||||
</success_criteria>
|
||||
157
get-shit-done/workflows/ui-review.md
Normal file
157
get-shit-done/workflows/ui-review.md
Normal file
@@ -0,0 +1,157 @@
|
||||
<purpose>
|
||||
Retroactive 6-pillar visual audit of implemented frontend code. Standalone command that works on any project — GSD-managed or not. Produces scored UI-REVIEW.md with actionable findings.
|
||||
</purpose>
|
||||
|
||||
<required_reading>
|
||||
@C:/Users/yaoji/.claude/get-shit-done/references/ui-brand.md
|
||||
</required_reading>
|
||||
|
||||
<process>
|
||||
|
||||
## 0. Initialize
|
||||
|
||||
```bash
|
||||
INIT=$(node "C:/Users/yaoji/.claude/get-shit-done/bin/gsd-tools.cjs" init phase-op "${PHASE_ARG}")
|
||||
if [[ "$INIT" == @file:* ]]; then INIT=$(cat "${INIT#@file:}"); fi
|
||||
```
|
||||
|
||||
Parse: `phase_dir`, `phase_number`, `phase_name`, `phase_slug`, `padded_phase`, `commit_docs`.
|
||||
|
||||
```bash
|
||||
UI_AUDITOR_MODEL=$(node "C:/Users/yaoji/.claude/get-shit-done/bin/gsd-tools.cjs" resolve-model gsd-ui-auditor --raw)
|
||||
```
|
||||
|
||||
Display banner:
|
||||
```
|
||||
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
|
||||
GSD ► UI AUDIT — PHASE {N}: {name}
|
||||
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
|
||||
```
|
||||
|
||||
## 1. Detect Input State
|
||||
|
||||
```bash
|
||||
SUMMARY_FILES=$(ls "${PHASE_DIR}"/*-SUMMARY.md 2>/dev/null)
|
||||
UI_SPEC_FILE=$(ls "${PHASE_DIR}"/*-UI-SPEC.md 2>/dev/null | head -1)
|
||||
UI_REVIEW_FILE=$(ls "${PHASE_DIR}"/*-UI-REVIEW.md 2>/dev/null | head -1)
|
||||
```
|
||||
|
||||
**If `SUMMARY_FILES` empty:** Exit — "Phase {N} not executed. Run /gsd:execute-phase {N} first."
|
||||
|
||||
**If `UI_REVIEW_FILE` non-empty:** Use AskUserQuestion:
|
||||
- header: "Existing UI Review"
|
||||
- question: "UI-REVIEW.md already exists for Phase {N}."
|
||||
- options:
|
||||
- "Re-audit — run fresh audit"
|
||||
- "View — display current review and exit"
|
||||
|
||||
If "View": display file, exit.
|
||||
If "Re-audit": continue.
|
||||
|
||||
## 2. Gather Context Paths
|
||||
|
||||
Build file list for auditor:
|
||||
- All SUMMARY.md files in phase dir
|
||||
- All PLAN.md files in phase dir
|
||||
- UI-SPEC.md (if exists — audit baseline)
|
||||
- CONTEXT.md (if exists — locked decisions)
|
||||
|
||||
## 3. Spawn gsd-ui-auditor
|
||||
|
||||
```
|
||||
◆ Spawning UI auditor...
|
||||
```
|
||||
|
||||
Build prompt:
|
||||
|
||||
```markdown
|
||||
Read C:/Users/yaoji/.claude/agents/gsd-ui-auditor.md for instructions.
|
||||
|
||||
<objective>
|
||||
Conduct 6-pillar visual audit of Phase {phase_number}: {phase_name}
|
||||
{If UI-SPEC exists: "Audit against UI-SPEC.md design contract."}
|
||||
{If no UI-SPEC: "Audit against abstract 6-pillar standards."}
|
||||
</objective>
|
||||
|
||||
<files_to_read>
|
||||
- {summary_paths} (Execution summaries)
|
||||
- {plan_paths} (Execution plans — what was intended)
|
||||
- {ui_spec_path} (UI Design Contract — audit baseline, if exists)
|
||||
- {context_path} (User decisions, if exists)
|
||||
</files_to_read>
|
||||
|
||||
<config>
|
||||
phase_dir: {phase_dir}
|
||||
padded_phase: {padded_phase}
|
||||
</config>
|
||||
```
|
||||
|
||||
Omit null file paths.
|
||||
|
||||
```
|
||||
Task(
|
||||
prompt=ui_audit_prompt,
|
||||
subagent_type="gsd-ui-auditor",
|
||||
model="{UI_AUDITOR_MODEL}",
|
||||
description="UI Audit Phase {N}"
|
||||
)
|
||||
```
|
||||
|
||||
## 4. Handle Return
|
||||
|
||||
**If `## UI REVIEW COMPLETE`:**
|
||||
|
||||
Display score summary:
|
||||
|
||||
```
|
||||
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
|
||||
GSD ► UI AUDIT COMPLETE ✓
|
||||
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
|
||||
|
||||
**Phase {N}: {Name}** — Overall: {score}/24
|
||||
|
||||
| Pillar | Score |
|
||||
|--------|-------|
|
||||
| Copywriting | {N}/4 |
|
||||
| Visuals | {N}/4 |
|
||||
| Color | {N}/4 |
|
||||
| Typography | {N}/4 |
|
||||
| Spacing | {N}/4 |
|
||||
| Experience Design | {N}/4 |
|
||||
|
||||
Top fixes:
|
||||
1. {fix}
|
||||
2. {fix}
|
||||
3. {fix}
|
||||
|
||||
Full review: {path to UI-REVIEW.md}
|
||||
|
||||
───────────────────────────────────────────────────────────────
|
||||
|
||||
## ▶ Next
|
||||
|
||||
- `/gsd:verify-work {N}` — UAT testing
|
||||
- `/gsd:plan-phase {N+1}` — plan next phase
|
||||
|
||||
<sub>/clear first → fresh context window</sub>
|
||||
|
||||
───────────────────────────────────────────────────────────────
|
||||
```
|
||||
|
||||
## 5. Commit (if configured)
|
||||
|
||||
```bash
|
||||
node "C:/Users/yaoji/.claude/get-shit-done/bin/gsd-tools.cjs" commit "docs(${padded_phase}): UI audit review" --files "${PHASE_DIR}/${PADDED_PHASE}-UI-REVIEW.md"
|
||||
```
|
||||
|
||||
</process>
|
||||
|
||||
<success_criteria>
|
||||
- [ ] Phase validated
|
||||
- [ ] SUMMARY.md files found (execution completed)
|
||||
- [ ] Existing review handled (re-audit/view)
|
||||
- [ ] gsd-ui-auditor spawned with correct context
|
||||
- [ ] UI-REVIEW.md created in phase directory
|
||||
- [ ] Score summary displayed to user
|
||||
- [ ] Next steps presented
|
||||
</success_criteria>
|
||||
323
get-shit-done/workflows/update.md
Normal file
323
get-shit-done/workflows/update.md
Normal file
@@ -0,0 +1,323 @@
|
||||
<purpose>
|
||||
Check for GSD updates via npm, display changelog for versions between installed and latest, obtain user confirmation, and execute clean installation with cache clearing.
|
||||
</purpose>
|
||||
|
||||
<required_reading>
|
||||
Read all files referenced by the invoking prompt's execution_context before starting.
|
||||
</required_reading>
|
||||
|
||||
<process>
|
||||
|
||||
<step name="get_installed_version">
|
||||
Detect whether GSD is installed locally or globally by checking both locations and validating install integrity.
|
||||
|
||||
First, derive `PREFERRED_RUNTIME` from the invoking prompt's `execution_context` path:
|
||||
- Path contains `/.codex/` -> `codex`
|
||||
- Path contains `/.gemini/` -> `gemini`
|
||||
- Path contains `/.config/opencode/` or `/.opencode/` -> `opencode`
|
||||
- Otherwise -> `claude`
|
||||
|
||||
Use `PREFERRED_RUNTIME` as the first runtime checked so `/gsd:update` targets the runtime that invoked it.
|
||||
|
||||
```bash
|
||||
# Runtime candidates: "<runtime>:<config-dir>" stored as an array.
|
||||
# Using an array instead of a space-separated string ensures correct
|
||||
# iteration in both bash and zsh (zsh does not word-split unquoted
|
||||
# variables by default). Fixes #1173.
|
||||
RUNTIME_DIRS=( "claude:.claude" "opencode:.config/opencode" "opencode:.opencode" "gemini:.gemini" "codex:.codex" )
|
||||
|
||||
# PREFERRED_RUNTIME should be set from execution_context before running this block.
|
||||
# If not set, infer from runtime env vars; fallback to claude.
|
||||
if [ -z "$PREFERRED_RUNTIME" ]; then
|
||||
if [ -n "$CODEX_HOME" ]; then
|
||||
PREFERRED_RUNTIME="codex"
|
||||
elif [ -n "$GEMINI_CONFIG_DIR" ]; then
|
||||
PREFERRED_RUNTIME="gemini"
|
||||
elif [ -n "$OPENCODE_CONFIG_DIR" ] || [ -n "$OPENCODE_CONFIG" ]; then
|
||||
PREFERRED_RUNTIME="opencode"
|
||||
elif [ -n "$CLAUDE_CONFIG_DIR" ]; then
|
||||
PREFERRED_RUNTIME="claude"
|
||||
else
|
||||
PREFERRED_RUNTIME="claude"
|
||||
fi
|
||||
fi
|
||||
|
||||
# Reorder entries so preferred runtime is checked first.
|
||||
ORDERED_RUNTIME_DIRS=()
|
||||
for entry in "${RUNTIME_DIRS[@]}"; do
|
||||
runtime="${entry%%:*}"
|
||||
if [ "$runtime" = "$PREFERRED_RUNTIME" ]; then
|
||||
ORDERED_RUNTIME_DIRS+=( "$entry" )
|
||||
fi
|
||||
done
|
||||
for entry in "${RUNTIME_DIRS[@]}"; do
|
||||
runtime="${entry%%:*}"
|
||||
if [ "$runtime" != "$PREFERRED_RUNTIME" ]; then
|
||||
ORDERED_RUNTIME_DIRS+=( "$entry" )
|
||||
fi
|
||||
done
|
||||
|
||||
# Check local first (takes priority only if valid and distinct from global)
|
||||
LOCAL_VERSION_FILE="" LOCAL_MARKER_FILE="" LOCAL_DIR="" LOCAL_RUNTIME=""
|
||||
for entry in "${ORDERED_RUNTIME_DIRS[@]}"; do
|
||||
runtime="${entry%%:*}"
|
||||
dir="${entry#*:}"
|
||||
if [ -f "./$dir/get-shit-done/VERSION" ] || [ -f "./$dir/get-shit-done/workflows/update.md" ]; then
|
||||
LOCAL_RUNTIME="$runtime"
|
||||
LOCAL_VERSION_FILE="./$dir/get-shit-done/VERSION"
|
||||
LOCAL_MARKER_FILE="./$dir/get-shit-done/workflows/update.md"
|
||||
LOCAL_DIR="$(cd "./$dir" 2>/dev/null && pwd)"
|
||||
break
|
||||
fi
|
||||
done
|
||||
|
||||
GLOBAL_VERSION_FILE="" GLOBAL_MARKER_FILE="" GLOBAL_DIR="" GLOBAL_RUNTIME=""
|
||||
for entry in "${ORDERED_RUNTIME_DIRS[@]}"; do
|
||||
runtime="${entry%%:*}"
|
||||
dir="${entry#*:}"
|
||||
if [ -f "$HOME/$dir/get-shit-done/VERSION" ] || [ -f "$HOME/$dir/get-shit-done/workflows/update.md" ]; then
|
||||
GLOBAL_RUNTIME="$runtime"
|
||||
GLOBAL_VERSION_FILE="$HOME/$dir/get-shit-done/VERSION"
|
||||
GLOBAL_MARKER_FILE="$HOME/$dir/get-shit-done/workflows/update.md"
|
||||
GLOBAL_DIR="$(cd "$HOME/$dir" 2>/dev/null && pwd)"
|
||||
break
|
||||
fi
|
||||
done
|
||||
|
||||
# Only treat as LOCAL if the resolved paths differ (prevents misdetection when CWD=$HOME)
|
||||
IS_LOCAL=false
|
||||
if [ -n "$LOCAL_VERSION_FILE" ] && [ -f "$LOCAL_VERSION_FILE" ] && [ -f "$LOCAL_MARKER_FILE" ] && grep -Eq '^[0-9]+\.[0-9]+\.[0-9]+' "$LOCAL_VERSION_FILE"; then
|
||||
if [ -z "$GLOBAL_DIR" ] || [ "$LOCAL_DIR" != "$GLOBAL_DIR" ]; then
|
||||
IS_LOCAL=true
|
||||
fi
|
||||
fi
|
||||
|
||||
if [ "$IS_LOCAL" = true ]; then
|
||||
INSTALLED_VERSION="$(cat "$LOCAL_VERSION_FILE")"
|
||||
INSTALL_SCOPE="LOCAL"
|
||||
TARGET_RUNTIME="$LOCAL_RUNTIME"
|
||||
elif [ -n "$GLOBAL_VERSION_FILE" ] && [ -f "$GLOBAL_VERSION_FILE" ] && [ -f "$GLOBAL_MARKER_FILE" ] && grep -Eq '^[0-9]+\.[0-9]+\.[0-9]+' "$GLOBAL_VERSION_FILE"; then
|
||||
INSTALLED_VERSION="$(cat "$GLOBAL_VERSION_FILE")"
|
||||
INSTALL_SCOPE="GLOBAL"
|
||||
TARGET_RUNTIME="$GLOBAL_RUNTIME"
|
||||
elif [ -n "$LOCAL_RUNTIME" ] && [ -f "$LOCAL_MARKER_FILE" ]; then
|
||||
# Runtime detected but VERSION missing/corrupt: treat as unknown version, keep runtime target
|
||||
INSTALLED_VERSION="0.0.0"
|
||||
INSTALL_SCOPE="LOCAL"
|
||||
TARGET_RUNTIME="$LOCAL_RUNTIME"
|
||||
elif [ -n "$GLOBAL_RUNTIME" ] && [ -f "$GLOBAL_MARKER_FILE" ]; then
|
||||
INSTALLED_VERSION="0.0.0"
|
||||
INSTALL_SCOPE="GLOBAL"
|
||||
TARGET_RUNTIME="$GLOBAL_RUNTIME"
|
||||
else
|
||||
INSTALLED_VERSION="0.0.0"
|
||||
INSTALL_SCOPE="UNKNOWN"
|
||||
TARGET_RUNTIME="claude"
|
||||
fi
|
||||
|
||||
echo "$INSTALLED_VERSION"
|
||||
echo "$INSTALL_SCOPE"
|
||||
echo "$TARGET_RUNTIME"
|
||||
```
|
||||
|
||||
Parse output:
|
||||
- Line 1 = installed version (`0.0.0` means unknown version)
|
||||
- Line 2 = install scope (`LOCAL`, `GLOBAL`, or `UNKNOWN`)
|
||||
- Line 3 = target runtime (`claude`, `opencode`, `gemini`, or `codex`)
|
||||
- If scope is `UNKNOWN`, proceed to install step using `--claude --global` fallback.
|
||||
|
||||
If multiple runtime installs are detected and the invoking runtime cannot be determined from execution_context, ask the user which runtime to update before running install.
|
||||
|
||||
**If VERSION file missing:**
|
||||
```
|
||||
## GSD Update
|
||||
|
||||
**Installed version:** Unknown
|
||||
|
||||
Your installation doesn't include version tracking.
|
||||
|
||||
Running fresh install...
|
||||
```
|
||||
|
||||
Proceed to install step (treat as version 0.0.0 for comparison).
|
||||
</step>
|
||||
|
||||
<step name="check_latest_version">
|
||||
Check npm for latest version:
|
||||
|
||||
```bash
|
||||
npm view get-shit-done-cc version 2>/dev/null
|
||||
```
|
||||
|
||||
**If npm check fails:**
|
||||
```
|
||||
Couldn't check for updates (offline or npm unavailable).
|
||||
|
||||
To update manually: `npx get-shit-done-cc --global`
|
||||
```
|
||||
|
||||
Exit.
|
||||
</step>
|
||||
|
||||
<step name="compare_versions">
|
||||
Compare installed vs latest:
|
||||
|
||||
**If installed == latest:**
|
||||
```
|
||||
## GSD Update
|
||||
|
||||
**Installed:** X.Y.Z
|
||||
**Latest:** X.Y.Z
|
||||
|
||||
You're already on the latest version.
|
||||
```
|
||||
|
||||
Exit.
|
||||
|
||||
**If installed > latest:**
|
||||
```
|
||||
## GSD Update
|
||||
|
||||
**Installed:** X.Y.Z
|
||||
**Latest:** A.B.C
|
||||
|
||||
You're ahead of the latest release (development version?).
|
||||
```
|
||||
|
||||
Exit.
|
||||
</step>
|
||||
|
||||
<step name="show_changes_and_confirm">
|
||||
**If update available**, fetch and show what's new BEFORE updating:
|
||||
|
||||
1. Fetch changelog from GitHub raw URL
|
||||
2. Extract entries between installed and latest versions
|
||||
3. Display preview and ask for confirmation:
|
||||
|
||||
```
|
||||
## GSD Update Available
|
||||
|
||||
**Installed:** 1.5.10
|
||||
**Latest:** 1.5.15
|
||||
|
||||
### What's New
|
||||
────────────────────────────────────────────────────────────
|
||||
|
||||
## [1.5.15] - 2026-01-20
|
||||
|
||||
### Added
|
||||
- Feature X
|
||||
|
||||
## [1.5.14] - 2026-01-18
|
||||
|
||||
### Fixed
|
||||
- Bug fix Y
|
||||
|
||||
────────────────────────────────────────────────────────────
|
||||
|
||||
⚠️ **Note:** The installer performs a clean install of GSD folders:
|
||||
- `commands/gsd/` will be wiped and replaced
|
||||
- `get-shit-done/` will be wiped and replaced
|
||||
- `agents/gsd-*` files will be replaced
|
||||
|
||||
(Paths are relative to detected runtime install location:
|
||||
global: `C:/Users/yaoji/.claude/`, `~/.config/opencode/`, `~/.opencode/`, `~/.gemini/`, or `~/.codex/`
|
||||
local: `./.claude/`, `./.config/opencode/`, `./.opencode/`, `./.gemini/`, or `./.codex/`)
|
||||
|
||||
Your custom files in other locations are preserved:
|
||||
- Custom commands not in `commands/gsd/` ✓
|
||||
- Custom agents not prefixed with `gsd-` ✓
|
||||
- Custom hooks ✓
|
||||
- Your CLAUDE.md files ✓
|
||||
|
||||
If you've modified any GSD files directly, they'll be automatically backed up to `gsd-local-patches/` and can be reapplied with `/gsd:reapply-patches` after the update.
|
||||
```
|
||||
|
||||
Use AskUserQuestion:
|
||||
- Question: "Proceed with update?"
|
||||
- Options:
|
||||
- "Yes, update now"
|
||||
- "No, cancel"
|
||||
|
||||
**If user cancels:** Exit.
|
||||
</step>
|
||||
|
||||
<step name="run_update">
|
||||
Run the update using the install type detected in step 1:
|
||||
|
||||
Build runtime flag from step 1:
|
||||
```bash
|
||||
RUNTIME_FLAG="--$TARGET_RUNTIME"
|
||||
```
|
||||
|
||||
**If LOCAL install:**
|
||||
```bash
|
||||
npx -y get-shit-done-cc@latest "$RUNTIME_FLAG" --local
|
||||
```
|
||||
|
||||
**If GLOBAL install:**
|
||||
```bash
|
||||
npx -y get-shit-done-cc@latest "$RUNTIME_FLAG" --global
|
||||
```
|
||||
|
||||
**If UNKNOWN install:**
|
||||
```bash
|
||||
npx -y get-shit-done-cc@latest --claude --global
|
||||
```
|
||||
|
||||
Capture output. If install fails, show error and exit.
|
||||
|
||||
Clear the update cache so statusline indicator disappears:
|
||||
|
||||
```bash
|
||||
# Clear update cache across all runtime directories
|
||||
for dir in .claude .config/opencode .opencode .gemini .codex; do
|
||||
rm -f "./$dir/cache/gsd-update-check.json"
|
||||
rm -f "$HOME/$dir/cache/gsd-update-check.json"
|
||||
done
|
||||
```
|
||||
|
||||
The SessionStart hook (`gsd-check-update.js`) writes to the detected runtime's cache directory, so all paths must be cleared to prevent stale update indicators.
|
||||
</step>
|
||||
|
||||
<step name="display_result">
|
||||
Format completion message (changelog was already shown in confirmation step):
|
||||
|
||||
```
|
||||
╔═══════════════════════════════════════════════════════════╗
|
||||
║ GSD Updated: v1.5.10 → v1.5.15 ║
|
||||
╚═══════════════════════════════════════════════════════════╝
|
||||
|
||||
⚠️ Restart your runtime to pick up the new commands.
|
||||
|
||||
[View full changelog](https://github.com/glittercowboy/get-shit-done/blob/main/CHANGELOG.md)
|
||||
```
|
||||
</step>
|
||||
|
||||
|
||||
<step name="check_local_patches">
|
||||
After update completes, check if the installer detected and backed up any locally modified files:
|
||||
|
||||
Check for gsd-local-patches/backup-meta.json in the config directory.
|
||||
|
||||
**If patches found:**
|
||||
|
||||
```
|
||||
Local patches were backed up before the update.
|
||||
Run /gsd:reapply-patches to merge your modifications into the new version.
|
||||
```
|
||||
|
||||
**If no patches:** Continue normally.
|
||||
</step>
|
||||
</process>
|
||||
|
||||
<success_criteria>
|
||||
- [ ] Installed version read correctly
|
||||
- [ ] Latest version checked via npm
|
||||
- [ ] Update skipped if already current
|
||||
- [ ] Changelog fetched and displayed BEFORE update
|
||||
- [ ] Clean install warning shown
|
||||
- [ ] User confirmation obtained
|
||||
- [ ] Update executed successfully
|
||||
- [ ] Restart reminder shown
|
||||
</success_criteria>
|
||||
167
get-shit-done/workflows/validate-phase.md
Normal file
167
get-shit-done/workflows/validate-phase.md
Normal file
@@ -0,0 +1,167 @@
|
||||
<purpose>
|
||||
Audit Nyquist validation gaps for a completed phase. Generate missing tests. Update VALIDATION.md.
|
||||
</purpose>
|
||||
|
||||
<required_reading>
|
||||
@C:/Users/yaoji/.claude/get-shit-done/references/ui-brand.md
|
||||
</required_reading>
|
||||
|
||||
<process>
|
||||
|
||||
## 0. Initialize
|
||||
|
||||
```bash
|
||||
INIT=$(node "C:/Users/yaoji/.claude/get-shit-done/bin/gsd-tools.cjs" init phase-op "${PHASE_ARG}")
|
||||
if [[ "$INIT" == @file:* ]]; then INIT=$(cat "${INIT#@file:}"); fi
|
||||
```
|
||||
|
||||
Parse: `phase_dir`, `phase_number`, `phase_name`, `phase_slug`, `padded_phase`.
|
||||
|
||||
```bash
|
||||
AUDITOR_MODEL=$(node "C:/Users/yaoji/.claude/get-shit-done/bin/gsd-tools.cjs" resolve-model gsd-nyquist-auditor --raw)
|
||||
NYQUIST_CFG=$(node "C:/Users/yaoji/.claude/get-shit-done/bin/gsd-tools.cjs" config get workflow.nyquist_validation --raw)
|
||||
```
|
||||
|
||||
If `NYQUIST_CFG` is `false`: exit with "Nyquist validation is disabled. Enable via /gsd:settings."
|
||||
|
||||
Display banner: `GSD > VALIDATE PHASE {N}: {name}`
|
||||
|
||||
## 1. Detect Input State
|
||||
|
||||
```bash
|
||||
VALIDATION_FILE=$(ls "${PHASE_DIR}"/*-VALIDATION.md 2>/dev/null | head -1)
|
||||
SUMMARY_FILES=$(ls "${PHASE_DIR}"/*-SUMMARY.md 2>/dev/null)
|
||||
```
|
||||
|
||||
- **State A** (`VALIDATION_FILE` non-empty): Audit existing
|
||||
- **State B** (`VALIDATION_FILE` empty, `SUMMARY_FILES` non-empty): Reconstruct from artifacts
|
||||
- **State C** (`SUMMARY_FILES` empty): Exit — "Phase {N} not executed. Run /gsd:execute-phase {N} first."
|
||||
|
||||
## 2. Discovery
|
||||
|
||||
### 2a. Read Phase Artifacts
|
||||
|
||||
Read all PLAN and SUMMARY files. Extract: task lists, requirement IDs, key-files changed, verify blocks.
|
||||
|
||||
### 2b. Build Requirement-to-Task Map
|
||||
|
||||
Per task: `{ task_id, plan_id, wave, requirement_ids, has_automated_command }`
|
||||
|
||||
### 2c. Detect Test Infrastructure
|
||||
|
||||
State A: Parse from existing VALIDATION.md Test Infrastructure table.
|
||||
State B: Filesystem scan:
|
||||
|
||||
```bash
|
||||
find . -name "pytest.ini" -o -name "jest.config.*" -o -name "vitest.config.*" -o -name "pyproject.toml" 2>/dev/null | head -10
|
||||
find . \( -name "*.test.*" -o -name "*.spec.*" -o -name "test_*" \) -not -path "*/node_modules/*" 2>/dev/null | head -40
|
||||
```
|
||||
|
||||
### 2d. Cross-Reference
|
||||
|
||||
Match each requirement to existing tests by filename, imports, test descriptions. Record: requirement → test_file → status.
|
||||
|
||||
## 3. Gap Analysis
|
||||
|
||||
Classify each requirement:
|
||||
|
||||
| Status | Criteria |
|
||||
|--------|----------|
|
||||
| COVERED | Test exists, targets behavior, runs green |
|
||||
| PARTIAL | Test exists, failing or incomplete |
|
||||
| MISSING | No test found |
|
||||
|
||||
Build: `{ task_id, requirement, gap_type, suggested_test_path, suggested_command }`
|
||||
|
||||
No gaps → skip to Step 6, set `nyquist_compliant: true`.
|
||||
|
||||
## 4. Present Gap Plan
|
||||
|
||||
Call AskUserQuestion with gap table and options:
|
||||
1. "Fix all gaps" → Step 5
|
||||
2. "Skip — mark manual-only" → add to Manual-Only, Step 6
|
||||
3. "Cancel" → exit
|
||||
|
||||
## 5. Spawn gsd-nyquist-auditor
|
||||
|
||||
```
|
||||
Task(
|
||||
prompt="Read C:/Users/yaoji/.claude/agents/gsd-nyquist-auditor.md for instructions.\n\n" +
|
||||
"<files_to_read>{PLAN, SUMMARY, impl files, VALIDATION.md}</files_to_read>" +
|
||||
"<gaps>{gap list}</gaps>" +
|
||||
"<test_infrastructure>{framework, config, commands}</test_infrastructure>" +
|
||||
"<constraints>Never modify impl files. Max 3 debug iterations. Escalate impl bugs.</constraints>",
|
||||
subagent_type="gsd-nyquist-auditor",
|
||||
model="{AUDITOR_MODEL}",
|
||||
description="Fill validation gaps for Phase {N}"
|
||||
)
|
||||
```
|
||||
|
||||
Handle return:
|
||||
- `## GAPS FILLED` → record tests + map updates, Step 6
|
||||
- `## PARTIAL` → record resolved, move escalated to manual-only, Step 6
|
||||
- `## ESCALATE` → move all to manual-only, Step 6
|
||||
|
||||
## 6. Generate/Update VALIDATION.md
|
||||
|
||||
**State B (create):**
|
||||
1. Read template from `C:/Users/yaoji/.claude/get-shit-done/templates/VALIDATION.md`
|
||||
2. Fill: frontmatter, Test Infrastructure, Per-Task Map, Manual-Only, Sign-Off
|
||||
3. Write to `${PHASE_DIR}/${PADDED_PHASE}-VALIDATION.md`
|
||||
|
||||
**State A (update):**
|
||||
1. Update Per-Task Map statuses, add escalated to Manual-Only, update frontmatter
|
||||
2. Append audit trail:
|
||||
|
||||
```markdown
|
||||
## Validation Audit {date}
|
||||
| Metric | Count |
|
||||
|--------|-------|
|
||||
| Gaps found | {N} |
|
||||
| Resolved | {M} |
|
||||
| Escalated | {K} |
|
||||
```
|
||||
|
||||
## 7. Commit
|
||||
|
||||
```bash
|
||||
git add {test_files}
|
||||
git commit -m "test(phase-${PHASE}): add Nyquist validation tests"
|
||||
|
||||
node "C:/Users/yaoji/.claude/get-shit-done/bin/gsd-tools.cjs" commit "docs(phase-${PHASE}): add/update validation strategy"
|
||||
```
|
||||
|
||||
## 8. Results + Routing
|
||||
|
||||
**Compliant:**
|
||||
```
|
||||
GSD > PHASE {N} IS NYQUIST-COMPLIANT
|
||||
All requirements have automated verification.
|
||||
▶ Next: /gsd:audit-milestone
|
||||
```
|
||||
|
||||
**Partial:**
|
||||
```
|
||||
GSD > PHASE {N} VALIDATED (PARTIAL)
|
||||
{M} automated, {K} manual-only.
|
||||
▶ Retry: /gsd:validate-phase {N}
|
||||
```
|
||||
|
||||
Display `/clear` reminder.
|
||||
|
||||
</process>
|
||||
|
||||
<success_criteria>
|
||||
- [ ] Nyquist config checked (exit if disabled)
|
||||
- [ ] Input state detected (A/B/C)
|
||||
- [ ] State C exits cleanly
|
||||
- [ ] PLAN/SUMMARY files read, requirement map built
|
||||
- [ ] Test infrastructure detected
|
||||
- [ ] Gaps classified (COVERED/PARTIAL/MISSING)
|
||||
- [ ] User gate with gap table
|
||||
- [ ] Auditor spawned with complete context
|
||||
- [ ] All three return formats handled
|
||||
- [ ] VALIDATION.md created or updated
|
||||
- [ ] Test files committed separately
|
||||
- [ ] Results with routing presented
|
||||
</success_criteria>
|
||||
254
get-shit-done/workflows/verify-phase.md
Normal file
254
get-shit-done/workflows/verify-phase.md
Normal file
@@ -0,0 +1,254 @@
|
||||
<purpose>
|
||||
Verify phase goal achievement through goal-backward analysis. Check that the codebase delivers what the phase promised, not just that tasks completed.
|
||||
|
||||
Executed by a verification subagent spawned from execute-phase.md.
|
||||
</purpose>
|
||||
|
||||
<core_principle>
|
||||
**Task completion ≠ Goal achievement**
|
||||
|
||||
A task "create chat component" can be marked complete when the component is a placeholder. The task was done — but the goal "working chat interface" was not achieved.
|
||||
|
||||
Goal-backward verification:
|
||||
1. What must be TRUE for the goal to be achieved?
|
||||
2. What must EXIST for those truths to hold?
|
||||
3. What must be WIRED for those artifacts to function?
|
||||
|
||||
Then verify each level against the actual codebase.
|
||||
</core_principle>
|
||||
|
||||
<required_reading>
|
||||
@C:/Users/yaoji/.claude/get-shit-done/references/verification-patterns.md
|
||||
@C:/Users/yaoji/.claude/get-shit-done/templates/verification-report.md
|
||||
</required_reading>
|
||||
|
||||
<process>
|
||||
|
||||
<step name="load_context" priority="first">
|
||||
Load phase operation context:
|
||||
|
||||
```bash
|
||||
INIT=$(node "C:/Users/yaoji/.claude/get-shit-done/bin/gsd-tools.cjs" init phase-op "${PHASE_ARG}")
|
||||
if [[ "$INIT" == @file:* ]]; then INIT=$(cat "${INIT#@file:}"); fi
|
||||
```
|
||||
|
||||
Extract from init JSON: `phase_dir`, `phase_number`, `phase_name`, `has_plans`, `plan_count`.
|
||||
|
||||
Then load phase details and list plans/summaries:
|
||||
```bash
|
||||
node "C:/Users/yaoji/.claude/get-shit-done/bin/gsd-tools.cjs" roadmap get-phase "${phase_number}"
|
||||
grep -E "^| ${phase_number}" .planning/REQUIREMENTS.md 2>/dev/null
|
||||
ls "$phase_dir"/*-SUMMARY.md "$phase_dir"/*-PLAN.md 2>/dev/null
|
||||
```
|
||||
|
||||
Extract **phase goal** from ROADMAP.md (the outcome to verify, not tasks) and **requirements** from REQUIREMENTS.md if it exists.
|
||||
</step>
|
||||
|
||||
<step name="establish_must_haves">
|
||||
**Option A: Must-haves in PLAN frontmatter**
|
||||
|
||||
Use gsd-tools to extract must_haves from each PLAN:
|
||||
|
||||
```bash
|
||||
for plan in "$PHASE_DIR"/*-PLAN.md; do
|
||||
MUST_HAVES=$(node "C:/Users/yaoji/.claude/get-shit-done/bin/gsd-tools.cjs" frontmatter get "$plan" --field must_haves)
|
||||
echo "=== $plan ===" && echo "$MUST_HAVES"
|
||||
done
|
||||
```
|
||||
|
||||
Returns JSON: `{ truths: [...], artifacts: [...], key_links: [...] }`
|
||||
|
||||
Aggregate all must_haves across plans for phase-level verification.
|
||||
|
||||
**Option B: Use Success Criteria from ROADMAP.md**
|
||||
|
||||
If no must_haves in frontmatter (MUST_HAVES returns error or empty), check for Success Criteria:
|
||||
|
||||
```bash
|
||||
PHASE_DATA=$(node "C:/Users/yaoji/.claude/get-shit-done/bin/gsd-tools.cjs" roadmap get-phase "${phase_number}" --raw)
|
||||
```
|
||||
|
||||
Parse the `success_criteria` array from the JSON output. If non-empty:
|
||||
1. Use each Success Criterion directly as a **truth** (they are already written as observable, testable behaviors)
|
||||
2. Derive **artifacts** (concrete file paths for each truth)
|
||||
3. Derive **key links** (critical wiring where stubs hide)
|
||||
4. Document the must-haves before proceeding
|
||||
|
||||
Success Criteria from ROADMAP.md are the contract — they override PLAN-level must_haves when both exist.
|
||||
|
||||
**Option C: Derive from phase goal (fallback)**
|
||||
|
||||
If no must_haves in frontmatter AND no Success Criteria in ROADMAP:
|
||||
1. State the goal from ROADMAP.md
|
||||
2. Derive **truths** (3-7 observable behaviors, each testable)
|
||||
3. Derive **artifacts** (concrete file paths for each truth)
|
||||
4. Derive **key links** (critical wiring where stubs hide)
|
||||
5. Document derived must-haves before proceeding
|
||||
</step>
|
||||
|
||||
<step name="verify_truths">
|
||||
For each observable truth, determine if the codebase enables it.
|
||||
|
||||
**Status:** ✓ VERIFIED (all supporting artifacts pass) | ✗ FAILED (artifact missing/stub/unwired) | ? UNCERTAIN (needs human)
|
||||
|
||||
For each truth: identify supporting artifacts → check artifact status → check wiring → determine truth status.
|
||||
|
||||
**Example:** Truth "User can see existing messages" depends on Chat.tsx (renders), /api/chat GET (provides), Message model (schema). If Chat.tsx is a stub or API returns hardcoded [] → FAILED. If all exist, are substantive, and connected → VERIFIED.
|
||||
</step>
|
||||
|
||||
<step name="verify_artifacts">
|
||||
Use gsd-tools for artifact verification against must_haves in each PLAN:
|
||||
|
||||
```bash
|
||||
for plan in "$PHASE_DIR"/*-PLAN.md; do
|
||||
ARTIFACT_RESULT=$(node "C:/Users/yaoji/.claude/get-shit-done/bin/gsd-tools.cjs" verify artifacts "$plan")
|
||||
echo "=== $plan ===" && echo "$ARTIFACT_RESULT"
|
||||
done
|
||||
```
|
||||
|
||||
Parse JSON result: `{ all_passed, passed, total, artifacts: [{path, exists, issues, passed}] }`
|
||||
|
||||
**Artifact status from result:**
|
||||
- `exists=false` → MISSING
|
||||
- `issues` not empty → STUB (check issues for "Only N lines" or "Missing pattern")
|
||||
- `passed=true` → VERIFIED (Levels 1-2 pass)
|
||||
|
||||
**Level 3 — Wired (manual check for artifacts that pass Levels 1-2):**
|
||||
```bash
|
||||
grep -r "import.*$artifact_name" src/ --include="*.ts" --include="*.tsx" # IMPORTED
|
||||
grep -r "$artifact_name" src/ --include="*.ts" --include="*.tsx" | grep -v "import" # USED
|
||||
```
|
||||
WIRED = imported AND used. ORPHANED = exists but not imported/used.
|
||||
|
||||
| Exists | Substantive | Wired | Status |
|
||||
|--------|-------------|-------|--------|
|
||||
| ✓ | ✓ | ✓ | ✓ VERIFIED |
|
||||
| ✓ | ✓ | ✗ | ⚠️ ORPHANED |
|
||||
| ✓ | ✗ | - | ✗ STUB |
|
||||
| ✗ | - | - | ✗ MISSING |
|
||||
|
||||
**Export-level spot check (WARNING severity):**
|
||||
|
||||
For artifacts that pass Level 3, spot-check individual exports:
|
||||
- Extract key exported symbols (functions, constants, classes — skip types/interfaces)
|
||||
- For each, grep for usage outside the defining file
|
||||
- Flag exports with zero external call sites as "exported but unused"
|
||||
|
||||
This catches dead stores like `setPlan()` that exist in a wired file but are
|
||||
never actually called. Report as WARNING — may indicate incomplete cross-plan
|
||||
wiring or leftover code from plan revisions.
|
||||
</step>
|
||||
|
||||
<step name="verify_wiring">
|
||||
Use gsd-tools for key link verification against must_haves in each PLAN:
|
||||
|
||||
```bash
|
||||
for plan in "$PHASE_DIR"/*-PLAN.md; do
|
||||
LINKS_RESULT=$(node "C:/Users/yaoji/.claude/get-shit-done/bin/gsd-tools.cjs" verify key-links "$plan")
|
||||
echo "=== $plan ===" && echo "$LINKS_RESULT"
|
||||
done
|
||||
```
|
||||
|
||||
Parse JSON result: `{ all_verified, verified, total, links: [{from, to, via, verified, detail}] }`
|
||||
|
||||
**Link status from result:**
|
||||
- `verified=true` → WIRED
|
||||
- `verified=false` with "not found" → NOT_WIRED
|
||||
- `verified=false` with "Pattern not found" → PARTIAL
|
||||
|
||||
**Fallback patterns (if key_links not in must_haves):**
|
||||
|
||||
| Pattern | Check | Status |
|
||||
|---------|-------|--------|
|
||||
| Component → API | fetch/axios call to API path, response used (await/.then/setState) | WIRED / PARTIAL (call but unused response) / NOT_WIRED |
|
||||
| API → Database | Prisma/DB query on model, result returned via res.json() | WIRED / PARTIAL (query but not returned) / NOT_WIRED |
|
||||
| Form → Handler | onSubmit with real implementation (fetch/axios/mutate/dispatch), not console.log/empty | WIRED / STUB (log-only/empty) / NOT_WIRED |
|
||||
| State → Render | useState variable appears in JSX (`{stateVar}` or `{stateVar.property}`) | WIRED / NOT_WIRED |
|
||||
|
||||
Record status and evidence for each key link.
|
||||
</step>
|
||||
|
||||
<step name="verify_requirements">
|
||||
If REQUIREMENTS.md exists:
|
||||
```bash
|
||||
grep -E "Phase ${PHASE_NUM}" .planning/REQUIREMENTS.md 2>/dev/null
|
||||
```
|
||||
|
||||
For each requirement: parse description → identify supporting truths/artifacts → status: ✓ SATISFIED / ✗ BLOCKED / ? NEEDS HUMAN.
|
||||
</step>
|
||||
|
||||
<step name="scan_antipatterns">
|
||||
Extract files modified in this phase from SUMMARY.md, scan each:
|
||||
|
||||
| Pattern | Search | Severity |
|
||||
|---------|--------|----------|
|
||||
| TODO/FIXME/XXX/HACK | `grep -n -E "TODO\|FIXME\|XXX\|HACK"` | ⚠️ Warning |
|
||||
| Placeholder content | `grep -n -iE "placeholder\|coming soon\|will be here"` | 🛑 Blocker |
|
||||
| Empty returns | `grep -n -E "return null\|return \{\}\|return \[\]\|=> \{\}"` | ⚠️ Warning |
|
||||
| Log-only functions | Functions containing only console.log | ⚠️ Warning |
|
||||
|
||||
Categorize: 🛑 Blocker (prevents goal) | ⚠️ Warning (incomplete) | ℹ️ Info (notable).
|
||||
</step>
|
||||
|
||||
<step name="identify_human_verification">
|
||||
**Always needs human:** Visual appearance, user flow completion, real-time behavior (WebSocket/SSE), external service integration, performance feel, error message clarity.
|
||||
|
||||
**Needs human if uncertain:** Complex wiring grep can't trace, dynamic state-dependent behavior, edge cases.
|
||||
|
||||
Format each as: Test Name → What to do → Expected result → Why can't verify programmatically.
|
||||
</step>
|
||||
|
||||
<step name="determine_status">
|
||||
**passed:** All truths VERIFIED, all artifacts pass levels 1-3, all key links WIRED, no blocker anti-patterns.
|
||||
|
||||
**gaps_found:** Any truth FAILED, artifact MISSING/STUB, key link NOT_WIRED, or blocker found.
|
||||
|
||||
**human_needed:** All automated checks pass but human verification items remain.
|
||||
|
||||
**Score:** `verified_truths / total_truths`
|
||||
</step>
|
||||
|
||||
<step name="generate_fix_plans">
|
||||
If gaps_found:
|
||||
|
||||
1. **Cluster related gaps:** API stub + component unwired → "Wire frontend to backend". Multiple missing → "Complete core implementation". Wiring only → "Connect existing components".
|
||||
|
||||
2. **Generate plan per cluster:** Objective, 2-3 tasks (files/action/verify each), re-verify step. Keep focused: single concern per plan.
|
||||
|
||||
3. **Order by dependency:** Fix missing → fix stubs → fix wiring → verify.
|
||||
</step>
|
||||
|
||||
<step name="create_report">
|
||||
```bash
|
||||
REPORT_PATH="$PHASE_DIR/${PHASE_NUM}-VERIFICATION.md"
|
||||
```
|
||||
|
||||
Fill template sections: frontmatter (phase/timestamp/status/score), goal achievement, artifact table, wiring table, requirements coverage, anti-patterns, human verification, gaps summary, fix plans (if gaps_found), metadata.
|
||||
|
||||
See C:/Users/yaoji/.claude/get-shit-done/templates/verification-report.md for complete template.
|
||||
</step>
|
||||
|
||||
<step name="return_to_orchestrator">
|
||||
Return status (`passed` | `gaps_found` | `human_needed`), score (N/M must-haves), report path.
|
||||
|
||||
If gaps_found: list gaps + recommended fix plan names.
|
||||
If human_needed: list items requiring human testing.
|
||||
|
||||
Orchestrator routes: `passed` → update_roadmap | `gaps_found` → create/execute fixes, re-verify | `human_needed` → present to user.
|
||||
</step>
|
||||
|
||||
</process>
|
||||
|
||||
<success_criteria>
|
||||
- [ ] Must-haves established (from frontmatter or derived)
|
||||
- [ ] All truths verified with status and evidence
|
||||
- [ ] All artifacts checked at all three levels
|
||||
- [ ] All key links verified
|
||||
- [ ] Requirements coverage assessed (if applicable)
|
||||
- [ ] Anti-patterns scanned and categorized
|
||||
- [ ] Human verification items identified
|
||||
- [ ] Overall status determined
|
||||
- [ ] Fix plans generated (if gaps_found)
|
||||
- [ ] VERIFICATION.md created with complete report
|
||||
- [ ] Results returned to orchestrator
|
||||
</success_criteria>
|
||||
584
get-shit-done/workflows/verify-work.md
Normal file
584
get-shit-done/workflows/verify-work.md
Normal file
@@ -0,0 +1,584 @@
|
||||
<purpose>
|
||||
Validate built features through conversational testing with persistent state. Creates UAT.md that tracks test progress, survives /clear, and feeds gaps into /gsd:plan-phase --gaps.
|
||||
|
||||
User tests, Claude records. One test at a time. Plain text responses.
|
||||
</purpose>
|
||||
|
||||
<philosophy>
|
||||
**Show expected, ask if reality matches.**
|
||||
|
||||
Claude presents what SHOULD happen. User confirms or describes what's different.
|
||||
- "yes" / "y" / "next" / empty → pass
|
||||
- Anything else → logged as issue, severity inferred
|
||||
|
||||
No Pass/Fail buttons. No severity questions. Just: "Here's what should happen. Does it?"
|
||||
</philosophy>
|
||||
|
||||
<template>
|
||||
@C:/Users/yaoji/.claude/get-shit-done/templates/UAT.md
|
||||
</template>
|
||||
|
||||
<process>
|
||||
|
||||
<step name="initialize" priority="first">
|
||||
If $ARGUMENTS contains a phase number, load context:
|
||||
|
||||
```bash
|
||||
INIT=$(node "C:/Users/yaoji/.claude/get-shit-done/bin/gsd-tools.cjs" init verify-work "${PHASE_ARG}")
|
||||
if [[ "$INIT" == @file:* ]]; then INIT=$(cat "${INIT#@file:}"); fi
|
||||
```
|
||||
|
||||
Parse JSON for: `planner_model`, `checker_model`, `commit_docs`, `phase_found`, `phase_dir`, `phase_number`, `phase_name`, `has_verification`.
|
||||
</step>
|
||||
|
||||
<step name="check_active_session">
|
||||
**First: Check for active UAT sessions**
|
||||
|
||||
```bash
|
||||
find .planning/phases -name "*-UAT.md" -type f 2>/dev/null | head -5
|
||||
```
|
||||
|
||||
**If active sessions exist AND no $ARGUMENTS provided:**
|
||||
|
||||
Read each file's frontmatter (status, phase) and Current Test section.
|
||||
|
||||
Display inline:
|
||||
|
||||
```
|
||||
## Active UAT Sessions
|
||||
|
||||
| # | Phase | Status | Current Test | Progress |
|
||||
|---|-------|--------|--------------|----------|
|
||||
| 1 | 04-comments | testing | 3. Reply to Comment | 2/6 |
|
||||
| 2 | 05-auth | testing | 1. Login Form | 0/4 |
|
||||
|
||||
Reply with a number to resume, or provide a phase number to start new.
|
||||
```
|
||||
|
||||
Wait for user response.
|
||||
|
||||
- If user replies with number (1, 2) → Load that file, go to `resume_from_file`
|
||||
- If user replies with phase number → Treat as new session, go to `create_uat_file`
|
||||
|
||||
**If active sessions exist AND $ARGUMENTS provided:**
|
||||
|
||||
Check if session exists for that phase. If yes, offer to resume or restart.
|
||||
If no, continue to `create_uat_file`.
|
||||
|
||||
**If no active sessions AND no $ARGUMENTS:**
|
||||
|
||||
```
|
||||
No active UAT sessions.
|
||||
|
||||
Provide a phase number to start testing (e.g., /gsd:verify-work 4)
|
||||
```
|
||||
|
||||
**If no active sessions AND $ARGUMENTS provided:**
|
||||
|
||||
Continue to `create_uat_file`.
|
||||
</step>
|
||||
|
||||
<step name="find_summaries">
|
||||
**Find what to test:**
|
||||
|
||||
Use `phase_dir` from init (or run init if not already done).
|
||||
|
||||
```bash
|
||||
ls "$phase_dir"/*-SUMMARY.md 2>/dev/null
|
||||
```
|
||||
|
||||
Read each SUMMARY.md to extract testable deliverables.
|
||||
</step>
|
||||
|
||||
<step name="extract_tests">
|
||||
**Extract testable deliverables from SUMMARY.md:**
|
||||
|
||||
Parse for:
|
||||
1. **Accomplishments** - Features/functionality added
|
||||
2. **User-facing changes** - UI, workflows, interactions
|
||||
|
||||
Focus on USER-OBSERVABLE outcomes, not implementation details.
|
||||
|
||||
For each deliverable, create a test:
|
||||
- name: Brief test name
|
||||
- expected: What the user should see/experience (specific, observable)
|
||||
|
||||
Examples:
|
||||
- Accomplishment: "Added comment threading with infinite nesting"
|
||||
→ Test: "Reply to a Comment"
|
||||
→ Expected: "Clicking Reply opens inline composer below comment. Submitting shows reply nested under parent with visual indentation."
|
||||
|
||||
Skip internal/non-observable items (refactors, type changes, etc.).
|
||||
|
||||
**Cold-start smoke test injection:**
|
||||
|
||||
After extracting tests from SUMMARYs, scan the SUMMARY files for modified/created file paths. If ANY path matches these patterns:
|
||||
|
||||
`server.ts`, `server.js`, `app.ts`, `app.js`, `index.ts`, `index.js`, `main.ts`, `main.js`, `database/*`, `db/*`, `seed/*`, `seeds/*`, `migrations/*`, `startup*`, `docker-compose*`, `Dockerfile*`
|
||||
|
||||
Then **prepend** this test to the test list:
|
||||
|
||||
- name: "Cold Start Smoke Test"
|
||||
- expected: "Kill any running server/service. Clear ephemeral state (temp DBs, caches, lock files). Start the application from scratch. Server boots without errors, any seed/migration completes, and a primary query (health check, homepage load, or basic API call) returns live data."
|
||||
|
||||
This catches bugs that only manifest on fresh start — race conditions in startup sequences, silent seed failures, missing environment setup — which pass against warm state but break in production.
|
||||
</step>
|
||||
|
||||
<step name="create_uat_file">
|
||||
**Create UAT file with all tests:**
|
||||
|
||||
```bash
|
||||
mkdir -p "$PHASE_DIR"
|
||||
```
|
||||
|
||||
Build test list from extracted deliverables.
|
||||
|
||||
Create file:
|
||||
|
||||
```markdown
|
||||
---
|
||||
status: testing
|
||||
phase: XX-name
|
||||
source: [list of SUMMARY.md files]
|
||||
started: [ISO timestamp]
|
||||
updated: [ISO timestamp]
|
||||
---
|
||||
|
||||
## Current Test
|
||||
<!-- OVERWRITE each test - shows where we are -->
|
||||
|
||||
number: 1
|
||||
name: [first test name]
|
||||
expected: |
|
||||
[what user should observe]
|
||||
awaiting: user response
|
||||
|
||||
## Tests
|
||||
|
||||
### 1. [Test Name]
|
||||
expected: [observable behavior]
|
||||
result: [pending]
|
||||
|
||||
### 2. [Test Name]
|
||||
expected: [observable behavior]
|
||||
result: [pending]
|
||||
|
||||
...
|
||||
|
||||
## Summary
|
||||
|
||||
total: [N]
|
||||
passed: 0
|
||||
issues: 0
|
||||
pending: [N]
|
||||
skipped: 0
|
||||
|
||||
## Gaps
|
||||
|
||||
[none yet]
|
||||
```
|
||||
|
||||
Write to `.planning/phases/XX-name/{phase_num}-UAT.md`
|
||||
|
||||
Proceed to `present_test`.
|
||||
</step>
|
||||
|
||||
<step name="present_test">
|
||||
**Present current test to user:**
|
||||
|
||||
Read Current Test section from UAT file.
|
||||
|
||||
Display using checkpoint box format:
|
||||
|
||||
```
|
||||
╔══════════════════════════════════════════════════════════════╗
|
||||
║ CHECKPOINT: Verification Required ║
|
||||
╚══════════════════════════════════════════════════════════════╝
|
||||
|
||||
**Test {number}: {name}**
|
||||
|
||||
{expected}
|
||||
|
||||
──────────────────────────────────────────────────────────────
|
||||
→ Type "pass" or describe what's wrong
|
||||
──────────────────────────────────────────────────────────────
|
||||
```
|
||||
|
||||
Wait for user response (plain text, no AskUserQuestion).
|
||||
</step>
|
||||
|
||||
<step name="process_response">
|
||||
**Process user response and update file:**
|
||||
|
||||
**If response indicates pass:**
|
||||
- Empty response, "yes", "y", "ok", "pass", "next", "approved", "✓"
|
||||
|
||||
Update Tests section:
|
||||
```
|
||||
### {N}. {name}
|
||||
expected: {expected}
|
||||
result: pass
|
||||
```
|
||||
|
||||
**If response indicates skip:**
|
||||
- "skip", "can't test", "n/a"
|
||||
|
||||
Update Tests section:
|
||||
```
|
||||
### {N}. {name}
|
||||
expected: {expected}
|
||||
result: skipped
|
||||
reason: [user's reason if provided]
|
||||
```
|
||||
|
||||
**If response is anything else:**
|
||||
- Treat as issue description
|
||||
|
||||
Infer severity from description:
|
||||
- Contains: crash, error, exception, fails, broken, unusable → blocker
|
||||
- Contains: doesn't work, wrong, missing, can't → major
|
||||
- Contains: slow, weird, off, minor, small → minor
|
||||
- Contains: color, font, spacing, alignment, visual → cosmetic
|
||||
- Default if unclear: major
|
||||
|
||||
Update Tests section:
|
||||
```
|
||||
### {N}. {name}
|
||||
expected: {expected}
|
||||
result: issue
|
||||
reported: "{verbatim user response}"
|
||||
severity: {inferred}
|
||||
```
|
||||
|
||||
Append to Gaps section (structured YAML for plan-phase --gaps):
|
||||
```yaml
|
||||
- truth: "{expected behavior from test}"
|
||||
status: failed
|
||||
reason: "User reported: {verbatim user response}"
|
||||
severity: {inferred}
|
||||
test: {N}
|
||||
artifacts: [] # Filled by diagnosis
|
||||
missing: [] # Filled by diagnosis
|
||||
```
|
||||
|
||||
**After any response:**
|
||||
|
||||
Update Summary counts.
|
||||
Update frontmatter.updated timestamp.
|
||||
|
||||
If more tests remain → Update Current Test, go to `present_test`
|
||||
If no more tests → Go to `complete_session`
|
||||
</step>
|
||||
|
||||
<step name="resume_from_file">
|
||||
**Resume testing from UAT file:**
|
||||
|
||||
Read the full UAT file.
|
||||
|
||||
Find first test with `result: [pending]`.
|
||||
|
||||
Announce:
|
||||
```
|
||||
Resuming: Phase {phase} UAT
|
||||
Progress: {passed + issues + skipped}/{total}
|
||||
Issues found so far: {issues count}
|
||||
|
||||
Continuing from Test {N}...
|
||||
```
|
||||
|
||||
Update Current Test section with the pending test.
|
||||
Proceed to `present_test`.
|
||||
</step>
|
||||
|
||||
<step name="complete_session">
|
||||
**Complete testing and commit:**
|
||||
|
||||
Update frontmatter:
|
||||
- status: complete
|
||||
- updated: [now]
|
||||
|
||||
Clear Current Test section:
|
||||
```
|
||||
## Current Test
|
||||
|
||||
[testing complete]
|
||||
```
|
||||
|
||||
Commit the UAT file:
|
||||
```bash
|
||||
node "C:/Users/yaoji/.claude/get-shit-done/bin/gsd-tools.cjs" commit "test({phase_num}): complete UAT - {passed} passed, {issues} issues" --files ".planning/phases/XX-name/{phase_num}-UAT.md"
|
||||
```
|
||||
|
||||
Present summary:
|
||||
```
|
||||
## UAT Complete: Phase {phase}
|
||||
|
||||
| Result | Count |
|
||||
|--------|-------|
|
||||
| Passed | {N} |
|
||||
| Issues | {N} |
|
||||
| Skipped| {N} |
|
||||
|
||||
[If issues > 0:]
|
||||
### Issues Found
|
||||
|
||||
[List from Issues section]
|
||||
```
|
||||
|
||||
**If issues > 0:** Proceed to `diagnose_issues`
|
||||
|
||||
**If issues == 0:**
|
||||
```
|
||||
All tests passed. Ready to continue.
|
||||
|
||||
- `/gsd:plan-phase {next}` — Plan next phase
|
||||
- `/gsd:execute-phase {next}` — Execute next phase
|
||||
- `/gsd:ui-review {phase}` — visual quality audit (if frontend files were modified)
|
||||
```
|
||||
</step>
|
||||
|
||||
<step name="diagnose_issues">
|
||||
**Diagnose root causes before planning fixes:**
|
||||
|
||||
```
|
||||
---
|
||||
|
||||
{N} issues found. Diagnosing root causes...
|
||||
|
||||
Spawning parallel debug agents to investigate each issue.
|
||||
```
|
||||
|
||||
- Load diagnose-issues workflow
|
||||
- Follow @C:/Users/yaoji/.claude/get-shit-done/workflows/diagnose-issues.md
|
||||
- Spawn parallel debug agents for each issue
|
||||
- Collect root causes
|
||||
- Update UAT.md with root causes
|
||||
- Proceed to `plan_gap_closure`
|
||||
|
||||
Diagnosis runs automatically - no user prompt. Parallel agents investigate simultaneously, so overhead is minimal and fixes are more accurate.
|
||||
</step>
|
||||
|
||||
<step name="plan_gap_closure">
|
||||
**Auto-plan fixes from diagnosed gaps:**
|
||||
|
||||
Display:
|
||||
```
|
||||
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
|
||||
GSD ► PLANNING FIXES
|
||||
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
|
||||
|
||||
◆ Spawning planner for gap closure...
|
||||
```
|
||||
|
||||
Spawn gsd-planner in --gaps mode:
|
||||
|
||||
```
|
||||
Task(
|
||||
prompt="""
|
||||
<planning_context>
|
||||
|
||||
**Phase:** {phase_number}
|
||||
**Mode:** gap_closure
|
||||
|
||||
<files_to_read>
|
||||
- {phase_dir}/{phase_num}-UAT.md (UAT with diagnoses)
|
||||
- .planning/STATE.md (Project State)
|
||||
- .planning/ROADMAP.md (Roadmap)
|
||||
</files_to_read>
|
||||
|
||||
</planning_context>
|
||||
|
||||
<downstream_consumer>
|
||||
Output consumed by /gsd:execute-phase
|
||||
Plans must be executable prompts.
|
||||
</downstream_consumer>
|
||||
""",
|
||||
subagent_type="gsd-planner",
|
||||
model="{planner_model}",
|
||||
description="Plan gap fixes for Phase {phase}"
|
||||
)
|
||||
```
|
||||
|
||||
On return:
|
||||
- **PLANNING COMPLETE:** Proceed to `verify_gap_plans`
|
||||
- **PLANNING INCONCLUSIVE:** Report and offer manual intervention
|
||||
</step>
|
||||
|
||||
<step name="verify_gap_plans">
|
||||
**Verify fix plans with checker:**
|
||||
|
||||
Display:
|
||||
```
|
||||
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
|
||||
GSD ► VERIFYING FIX PLANS
|
||||
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
|
||||
|
||||
◆ Spawning plan checker...
|
||||
```
|
||||
|
||||
Initialize: `iteration_count = 1`
|
||||
|
||||
Spawn gsd-plan-checker:
|
||||
|
||||
```
|
||||
Task(
|
||||
prompt="""
|
||||
<verification_context>
|
||||
|
||||
**Phase:** {phase_number}
|
||||
**Phase Goal:** Close diagnosed gaps from UAT
|
||||
|
||||
<files_to_read>
|
||||
- {phase_dir}/*-PLAN.md (Plans to verify)
|
||||
</files_to_read>
|
||||
|
||||
</verification_context>
|
||||
|
||||
<expected_output>
|
||||
Return one of:
|
||||
- ## VERIFICATION PASSED — all checks pass
|
||||
- ## ISSUES FOUND — structured issue list
|
||||
</expected_output>
|
||||
""",
|
||||
subagent_type="gsd-plan-checker",
|
||||
model="{checker_model}",
|
||||
description="Verify Phase {phase} fix plans"
|
||||
)
|
||||
```
|
||||
|
||||
On return:
|
||||
- **VERIFICATION PASSED:** Proceed to `present_ready`
|
||||
- **ISSUES FOUND:** Proceed to `revision_loop`
|
||||
</step>
|
||||
|
||||
<step name="revision_loop">
|
||||
**Iterate planner ↔ checker until plans pass (max 3):**
|
||||
|
||||
**If iteration_count < 3:**
|
||||
|
||||
Display: `Sending back to planner for revision... (iteration {N}/3)`
|
||||
|
||||
Spawn gsd-planner with revision context:
|
||||
|
||||
```
|
||||
Task(
|
||||
prompt="""
|
||||
<revision_context>
|
||||
|
||||
**Phase:** {phase_number}
|
||||
**Mode:** revision
|
||||
|
||||
<files_to_read>
|
||||
- {phase_dir}/*-PLAN.md (Existing plans)
|
||||
</files_to_read>
|
||||
|
||||
**Checker issues:**
|
||||
{structured_issues_from_checker}
|
||||
|
||||
</revision_context>
|
||||
|
||||
<instructions>
|
||||
Read existing PLAN.md files. Make targeted updates to address checker issues.
|
||||
Do NOT replan from scratch unless issues are fundamental.
|
||||
</instructions>
|
||||
""",
|
||||
subagent_type="gsd-planner",
|
||||
model="{planner_model}",
|
||||
description="Revise Phase {phase} plans"
|
||||
)
|
||||
```
|
||||
|
||||
After planner returns → spawn checker again (verify_gap_plans logic)
|
||||
Increment iteration_count
|
||||
|
||||
**If iteration_count >= 3:**
|
||||
|
||||
Display: `Max iterations reached. {N} issues remain.`
|
||||
|
||||
Offer options:
|
||||
1. Force proceed (execute despite issues)
|
||||
2. Provide guidance (user gives direction, retry)
|
||||
3. Abandon (exit, user runs /gsd:plan-phase manually)
|
||||
|
||||
Wait for user response.
|
||||
</step>
|
||||
|
||||
<step name="present_ready">
|
||||
**Present completion and next steps:**
|
||||
|
||||
```
|
||||
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
|
||||
GSD ► FIXES READY ✓
|
||||
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
|
||||
|
||||
**Phase {X}: {Name}** — {N} gap(s) diagnosed, {M} fix plan(s) created
|
||||
|
||||
| Gap | Root Cause | Fix Plan |
|
||||
|-----|------------|----------|
|
||||
| {truth 1} | {root_cause} | {phase}-04 |
|
||||
| {truth 2} | {root_cause} | {phase}-04 |
|
||||
|
||||
Plans verified and ready for execution.
|
||||
|
||||
───────────────────────────────────────────────────────────────
|
||||
|
||||
## ▶ Next Up
|
||||
|
||||
**Execute fixes** — run fix plans
|
||||
|
||||
`/clear` then `/gsd:execute-phase {phase} --gaps-only`
|
||||
|
||||
───────────────────────────────────────────────────────────────
|
||||
```
|
||||
</step>
|
||||
|
||||
</process>
|
||||
|
||||
<update_rules>
|
||||
**Batched writes for efficiency:**
|
||||
|
||||
Keep results in memory. Write to file only when:
|
||||
1. **Issue found** — Preserve the problem immediately
|
||||
2. **Session complete** — Final write before commit
|
||||
3. **Checkpoint** — Every 5 passed tests (safety net)
|
||||
|
||||
| Section | Rule | When Written |
|
||||
|---------|------|--------------|
|
||||
| Frontmatter.status | OVERWRITE | Start, complete |
|
||||
| Frontmatter.updated | OVERWRITE | On any file write |
|
||||
| Current Test | OVERWRITE | On any file write |
|
||||
| Tests.{N}.result | OVERWRITE | On any file write |
|
||||
| Summary | OVERWRITE | On any file write |
|
||||
| Gaps | APPEND | When issue found |
|
||||
|
||||
On context reset: File shows last checkpoint. Resume from there.
|
||||
</update_rules>
|
||||
|
||||
<severity_inference>
|
||||
**Infer severity from user's natural language:**
|
||||
|
||||
| User says | Infer |
|
||||
|-----------|-------|
|
||||
| "crashes", "error", "exception", "fails completely" | blocker |
|
||||
| "doesn't work", "nothing happens", "wrong behavior" | major |
|
||||
| "works but...", "slow", "weird", "minor issue" | minor |
|
||||
| "color", "spacing", "alignment", "looks off" | cosmetic |
|
||||
|
||||
Default to **major** if unclear. User can correct if needed.
|
||||
|
||||
**Never ask "how severe is this?"** - just infer and move on.
|
||||
</severity_inference>
|
||||
|
||||
<success_criteria>
|
||||
- [ ] UAT file created with all tests from SUMMARY.md
|
||||
- [ ] Tests presented one at a time with expected behavior
|
||||
- [ ] User responses processed as pass/issue/skip
|
||||
- [ ] Severity inferred from description (never asked)
|
||||
- [ ] Batched writes: on issue, every 5 passes, or completion
|
||||
- [ ] Committed on completion
|
||||
- [ ] If issues: parallel debug agents diagnose root causes
|
||||
- [ ] If issues: gsd-planner creates fix plans (gap_closure mode)
|
||||
- [ ] If issues: gsd-plan-checker verifies fix plans
|
||||
- [ ] If issues: revision loop until plans pass (max 3 iterations)
|
||||
- [ ] Ready for `/gsd:execute-phase --gaps-only` when complete
|
||||
</success_criteria>
|
||||
Reference in New Issue
Block a user