feat: basecamp-project skill
This commit is contained in:
m3tm3re
132
.pi/gsd/workflows/add-backlog.md
Normal file
132
.pi/gsd/workflows/add-backlog.md
Normal file
@@ -0,0 +1,132 @@
|
||||
<gsd-version v="1.12.4" />
|
||||
|
||||
<gsd-arguments>
|
||||
<settings>
|
||||
<keep-extra-args />
|
||||
</settings>
|
||||
<arg name="idea" type="string" optional />
|
||||
</gsd-arguments>
|
||||
|
||||
<gsd-execute>
|
||||
<display msg="Loading backlog context..." />
|
||||
<shell command="pi-gsd-tools">
|
||||
<args>
|
||||
<arg string="state" />
|
||||
<arg string="json" />
|
||||
<arg string="--raw" />
|
||||
</args>
|
||||
<outs>
|
||||
<suppress-errors />
|
||||
<out type="string" name="state" />
|
||||
</outs>
|
||||
</shell>
|
||||
<shell command="pi-gsd-tools">
|
||||
<args>
|
||||
<arg string="roadmap" />
|
||||
<arg string="analyze" />
|
||||
<arg string="--raw" />
|
||||
</args>
|
||||
<outs>
|
||||
<suppress-errors />
|
||||
<out type="string" name="roadmap" />
|
||||
</outs>
|
||||
</shell>
|
||||
<shell command="pi-gsd-tools">
|
||||
<args>
|
||||
<arg string="current-timestamp" />
|
||||
<arg string="--raw" />
|
||||
</args>
|
||||
<outs>
|
||||
<out type="string" name="timestamp" />
|
||||
</outs>
|
||||
</shell>
|
||||
</gsd-execute>
|
||||
|
||||
## Backlog Context (pre-injected by WXP)
|
||||
|
||||
**Idea:** <gsd-paste name="idea" />
|
||||
|
||||
**Timestamp:** <gsd-paste name="timestamp" />
|
||||
|
||||
**State:**
|
||||
<gsd-paste name="state" />
|
||||
|
||||
**Roadmap Analysis:**
|
||||
<gsd-paste name="roadmap" />
|
||||
|
||||
---
|
||||
|
||||
<purpose>
|
||||
Park an idea as a backlog entry (999.x numbered phase) in ROADMAP.md. Zero friction — one command captures an idea without interrupting current work. The idea sits in the backlog until promoted by `/gsd-review-backlog`.
|
||||
</purpose>
|
||||
|
||||
<process>
|
||||
|
||||
<step name="validate_context">
|
||||
<!-- State, roadmap, and idea pre-injected above via WXP -->
|
||||
|
||||
Check that `.planning/ROADMAP.md` exists (from `state` JSON field `roadmap_exists`).
|
||||
|
||||
**If roadmap missing:**
|
||||
```
|
||||
Error: No ROADMAP.md found. Run /gsd-new-project or /gsd-new-milestone first.
|
||||
```
|
||||
Exit.
|
||||
|
||||
**If idea is empty (no $ARGUMENTS):**
|
||||
Ask the user: "What's the idea? (one sentence description)"
|
||||
Use the response as `idea`.
|
||||
</step>
|
||||
|
||||
<step name="find_next_slot">
|
||||
From the roadmap analysis JSON, extract the `phases` array. Find all phases where `phase_number` starts with `999` (e.g., `999.1`, `999.2`).
|
||||
|
||||
Compute next backlog number:
|
||||
- If no 999.x entries exist → use `999.1`
|
||||
- Otherwise → use `999.(max_decimal + 1)`, e.g., if `999.3` exists → `999.4`
|
||||
|
||||
Set `BACKLOG_NUM` = next available 999.x slot.
|
||||
</step>
|
||||
|
||||
<step name="add_entry">
|
||||
Append to `.planning/ROADMAP.md` under a `## Backlog` section (create the section if missing):
|
||||
|
||||
```markdown
|
||||
- [ ] **Phase {BACKLOG_NUM}**: {idea}
|
||||
```
|
||||
|
||||
Use the roadmap `roadmap add-phase` command if available, or append directly:
|
||||
|
||||
```bash
|
||||
pi-gsd-tools roadmap add-phase "{BACKLOG_NUM}" "{idea}" --raw
|
||||
```
|
||||
|
||||
If the CLI command fails or is unavailable, append manually to ROADMAP.md.
|
||||
</step>
|
||||
|
||||
<step name="commit">
|
||||
```bash
|
||||
pi-gsd-tools commit "docs: add backlog entry {BACKLOG_NUM} - {idea_slug}" --files .planning/ROADMAP.md
|
||||
```
|
||||
</step>
|
||||
|
||||
<step name="confirm">
|
||||
```
|
||||
✓ Backlog entry added
|
||||
|
||||
Phase {BACKLOG_NUM}: {idea}
|
||||
|
||||
---
|
||||
|
||||
Review and promote backlog: /gsd-review-backlog
|
||||
```
|
||||
</step>
|
||||
|
||||
</process>
|
||||
|
||||
<success_criteria>
|
||||
- [ ] ROADMAP.md has new 999.x entry
|
||||
- [ ] 999.x number is sequential (no gaps or duplicates)
|
||||
- [ ] Entry committed to git
|
||||
- [ ] User sees confirmation with the assigned phase number
|
||||
</success_criteria>
|
||||
135
.pi/gsd/workflows/add-phase.md
Normal file
135
.pi/gsd/workflows/add-phase.md
Normal file
@@ -0,0 +1,135 @@
|
||||
<gsd-version v="1.12.5" />
|
||||
|
||||
<gsd-arguments>
|
||||
<settings>
|
||||
<keep-extra-args />
|
||||
</settings>
|
||||
<arg name="description" type="string" optional />
|
||||
</gsd-arguments>
|
||||
|
||||
<gsd-execute>
|
||||
<shell command="pi-gsd-tools">
|
||||
<args>
|
||||
<arg string="init" />
|
||||
<arg string="phase-op" />
|
||||
<arg string="0" />
|
||||
</args>
|
||||
<outs>
|
||||
<out type="string" name="init" />
|
||||
</outs>
|
||||
</shell>
|
||||
<if>
|
||||
<condition>
|
||||
<starts-with>
|
||||
<left name="init" />
|
||||
<right type="string" value="@file:" />
|
||||
</starts-with>
|
||||
</condition>
|
||||
<then>
|
||||
<string-op op="split">
|
||||
<args>
|
||||
<arg name="init" />
|
||||
<arg type="string" value="@file:" />
|
||||
</args>
|
||||
<outs>
|
||||
<out type="string" name="init-file" />
|
||||
</outs>
|
||||
</string-op>
|
||||
<shell command="cat">
|
||||
<args>
|
||||
<arg name="init-file" wrap='"' />
|
||||
</args>
|
||||
<outs>
|
||||
<out type="string" name="init" />
|
||||
</outs>
|
||||
</shell>
|
||||
</then>
|
||||
</if>
|
||||
<shell command="pi-gsd-tools">
|
||||
<args>
|
||||
<arg string="phase" />
|
||||
<arg string="add-batch" />
|
||||
<arg name="description" wrap='"' />
|
||||
</args>
|
||||
<outs>
|
||||
<out type="string" name="batch-result" />
|
||||
</outs>
|
||||
</shell>
|
||||
</gsd-execute>
|
||||
|
||||
## Context (pre-injected by WXP)
|
||||
|
||||
**Init:**
|
||||
<gsd-paste name="init" />
|
||||
|
||||
**Phases added:**
|
||||
<gsd-paste name="batch-result" />
|
||||
|
||||
<process>
|
||||
|
||||
<step name="parse_arguments">
|
||||
If no description was provided (check `<gsd-paste name="description" />` is empty):
|
||||
|
||||
```
|
||||
ERROR: Phase description required
|
||||
Usage: /gsd-add-phase <description>
|
||||
/gsd-add-phase <desc1> + <desc2> + ...
|
||||
Example: /gsd-add-phase Add authentication system
|
||||
```
|
||||
|
||||
Exit.
|
||||
</step>
|
||||
|
||||
<step name="check_result">
|
||||
The `batch-result` JSON above was already executed by WXP before this message
|
||||
reached you. Parse it:
|
||||
|
||||
- If it contains an error field → report the error and exit.
|
||||
- Otherwise extract `phases[]` — each has `phase_number`, `padded`, `name`,
|
||||
`slug`, `directory`.
|
||||
|
||||
Do NOT run `pi-gsd-tools phase add` again, do NOT inspect `.planning/phases/`
|
||||
or ROADMAP.md — everything is already done.
|
||||
</step>
|
||||
|
||||
<step name="completion">
|
||||
Present a completion summary:
|
||||
|
||||
```
|
||||
Added <count> phase(s):
|
||||
|
||||
<for each phase in phases[]>
|
||||
• Phase <phase_number>: <name>
|
||||
Directory: <directory>
|
||||
</for>
|
||||
|
||||
Roadmap updated: .planning/ROADMAP.md
|
||||
State updated: .planning/STATE.md
|
||||
|
||||
---
|
||||
|
||||
## ▶ Next Up
|
||||
|
||||
**Phase <last phase_number>: <last name>**
|
||||
|
||||
`/gsd-plan-phase <last phase_number>`
|
||||
|
||||
<sub>`/clear` first → fresh context window</sub>
|
||||
|
||||
---
|
||||
|
||||
**Also available:**
|
||||
- `/gsd-add-phase <description>` — add another phase
|
||||
- `/gsd-plan-phase <N>` — plan any of the new phases
|
||||
```
|
||||
</step>
|
||||
|
||||
</process>
|
||||
|
||||
<success_criteria>
|
||||
- [ ] `pi-gsd-tools phase add-batch` executed by WXP (not by the agent)
|
||||
- [ ] Phase directories created under `.planning/phases/`
|
||||
- [ ] ROADMAP.md updated with all new phase entries
|
||||
- [ ] STATE.md Roadmap Evolution updated (handled inside add-batch)
|
||||
- [ ] Agent presented the pre-injected result — no filesystem exploration
|
||||
</success_criteria>
|
||||
414
.pi/gsd/workflows/add-tests.md
Normal file
414
.pi/gsd/workflows/add-tests.md
Normal file
@@ -0,0 +1,414 @@
|
||||
<gsd-version v="1.12.4" />
|
||||
|
||||
<gsd-arguments>
|
||||
<settings><keep-extra-args /></settings>
|
||||
<arg name="phase" type="number" />
|
||||
</gsd-arguments>
|
||||
|
||||
<gsd-execute>
|
||||
<shell command="pi-gsd-tools">
|
||||
<args>
|
||||
<arg string="init" />
|
||||
<arg string="phase-op" />
|
||||
</args>
|
||||
<outs>
|
||||
<out type="string" name="init" />
|
||||
</outs>
|
||||
</shell>
|
||||
<if>
|
||||
<condition>
|
||||
<starts-with>
|
||||
<left name="init" />
|
||||
<right type="string" value="@file:" />
|
||||
</starts-with>
|
||||
</condition>
|
||||
<then>
|
||||
<string-op op="split">
|
||||
<args>
|
||||
<arg name="init" />
|
||||
<arg type="string" value="@file:" />
|
||||
</args>
|
||||
<outs>
|
||||
<out type="string" name="init-file" />
|
||||
</outs>
|
||||
</string-op>
|
||||
<shell command="cat">
|
||||
<args>
|
||||
<arg name="init-file" wrap='"' />
|
||||
</args>
|
||||
<outs>
|
||||
<out type="string" name="init" />
|
||||
</outs>
|
||||
</shell>
|
||||
</then>
|
||||
</if>
|
||||
<shell command="pi-gsd-tools">
|
||||
<args>
|
||||
<arg string="state" />
|
||||
<arg string="json" />
|
||||
<arg string="--raw" />
|
||||
</args>
|
||||
<outs>
|
||||
<out type="string" name="state" />
|
||||
</outs>
|
||||
</shell>
|
||||
</gsd-execute>
|
||||
|
||||
## Context (pre-injected)
|
||||
|
||||
**Phase:** <gsd-paste name="phase" />
|
||||
|
||||
**Phase Data:**
|
||||
<gsd-paste name="init" />
|
||||
|
||||
**State:**
|
||||
<gsd-paste name="state" />
|
||||
|
||||
<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:
|
||||
|
||||
<!-- Context pre-injected above via WXP - variables available via <gsd-paste name="..."> -->
|
||||
|
||||
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 || true
|
||||
```
|
||||
|
||||
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 || true
|
||||
```
|
||||
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
|
||||
pi-gsd-tools 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>
|
||||
183
.pi/gsd/workflows/add-todo.md
Normal file
183
.pi/gsd/workflows/add-todo.md
Normal file
@@ -0,0 +1,183 @@
|
||||
<gsd-version v="1.12.4" />
|
||||
|
||||
<gsd-arguments>
|
||||
<settings><keep-extra-args /></settings>
|
||||
<arg name="text" type="string" optional />
|
||||
</gsd-arguments>
|
||||
|
||||
<gsd-execute>
|
||||
<shell command="pi-gsd-tools">
|
||||
<args>
|
||||
<arg string="state" />
|
||||
<arg string="json" />
|
||||
<arg string="--raw" />
|
||||
</args>
|
||||
<outs>
|
||||
<suppress-errors />
|
||||
<out type="string" name="state" />
|
||||
</outs>
|
||||
</shell>
|
||||
</gsd-execute>
|
||||
|
||||
## Context (pre-injected)
|
||||
|
||||
**Todo text:** <gsd-paste name="text" />
|
||||
|
||||
**State:**
|
||||
<gsd-paste name="state" />
|
||||
|
||||
<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:
|
||||
|
||||
<!-- Context pre-injected above via WXP - variables available via <gsd-paste name="..."> -->
|
||||
|
||||
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 || true
|
||||
```
|
||||
|
||||
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=$(pi-gsd-tools 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 the agent 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
|
||||
pi-gsd-tools 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 the agent
|
||||
- [ ] No duplicates (checked and resolved)
|
||||
- [ ] Area consistent with existing todos
|
||||
- [ ] STATE.md updated if exists
|
||||
- [ ] Todo and state committed to git
|
||||
</success_criteria>
|
||||
398
.pi/gsd/workflows/audit-milestone.md
Normal file
398
.pi/gsd/workflows/audit-milestone.md
Normal file
@@ -0,0 +1,398 @@
|
||||
<gsd-version v="1.12.4" />
|
||||
|
||||
<gsd-arguments>
|
||||
<settings>
|
||||
<keep-extra-args />
|
||||
</settings>
|
||||
</gsd-arguments>
|
||||
|
||||
<gsd-execute>
|
||||
<shell command="pi-gsd-tools">
|
||||
<args>
|
||||
<arg string="init" />
|
||||
<arg string="milestone-op" />
|
||||
</args>
|
||||
<outs>
|
||||
<out type="string" name="init" />
|
||||
</outs>
|
||||
</shell>
|
||||
<if>
|
||||
<condition>
|
||||
<starts-with>
|
||||
<left name="init" />
|
||||
<right type="string" value="@file:" />
|
||||
</starts-with>
|
||||
</condition>
|
||||
<then>
|
||||
<string-op op="split">
|
||||
<args>
|
||||
<arg name="init" />
|
||||
<arg type="string" value="@file:" />
|
||||
</args>
|
||||
<outs>
|
||||
<out type="string" name="init-file" />
|
||||
</outs>
|
||||
</string-op>
|
||||
<shell command="cat">
|
||||
<args>
|
||||
<arg name="init-file" wrap='"' />
|
||||
</args>
|
||||
<outs>
|
||||
<out type="string" name="init" />
|
||||
</outs>
|
||||
</shell>
|
||||
</then>
|
||||
</if>
|
||||
<shell command="pi-gsd-tools">
|
||||
<args>
|
||||
<arg string="agent-skills" />
|
||||
<arg string="gsd-integration-checker" />
|
||||
</args>
|
||||
<outs>
|
||||
<suppress-errors />
|
||||
<out type="string" name="agent-skills-checker" />
|
||||
</outs>
|
||||
</shell>
|
||||
<shell command="pi-gsd-tools">
|
||||
<args>
|
||||
<arg string="resolve-model" />
|
||||
<arg string="gsd-integration-checker" />
|
||||
<arg string="--raw" />
|
||||
</args>
|
||||
<outs>
|
||||
<suppress-errors />
|
||||
<out type="string" name="integration-checker-model" />
|
||||
</outs>
|
||||
</shell>
|
||||
</gsd-execute>
|
||||
|
||||
## Milestone Audit Context (pre-injected by WXP)
|
||||
|
||||
**Milestone Init Data:**
|
||||
<gsd-paste name="init" />
|
||||
|
||||
**Integration Checker Model:** <gsd-paste name="integration-checker-model" />
|
||||
|
||||
<process>
|
||||
|
||||
## 0. Initialize Milestone Context
|
||||
|
||||
<!-- Context pre-injected above via WXP - variables available via <gsd-paste name="..."> -->
|
||||
|
||||
Extract from init JSON: `milestone_version`, `milestone_name`, `phase_count`, `completed_phases`, `commit_docs`.
|
||||
|
||||
Resolve integration checker model:
|
||||
```bash
|
||||
integration_checker_model=$(pi-gsd-tools resolve-model gsd-integration-checker --raw)
|
||||
```
|
||||
|
||||
## 1. Determine Milestone Scope
|
||||
|
||||
```bash
|
||||
# Get phases in milestone (sorted numerically, handles decimals)
|
||||
pi-gsd-tools 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=$(pi-gsd-tools 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.
|
||||
${AGENT_SKILLS_CHECKER}",
|
||||
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
|
||||
[ -e "$summary" ] || continue
|
||||
pi-gsd-tools summary-extract "$summary" --fields requirements_completed --pick 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=$(pi-gsd-tools 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>/new 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>/new 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>/new 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>
|
||||
145
.pi/gsd/workflows/audit-uat.md
Normal file
145
.pi/gsd/workflows/audit-uat.md
Normal file
@@ -0,0 +1,145 @@
|
||||
<gsd-version v="1.12.4" />
|
||||
|
||||
<gsd-arguments>
|
||||
<settings><keep-extra-args /></settings>
|
||||
</gsd-arguments>
|
||||
|
||||
<gsd-execute>
|
||||
<shell command="pi-gsd-tools">
|
||||
<args>
|
||||
<arg string="audit-uat" />
|
||||
<arg string="--raw" />
|
||||
</args>
|
||||
<outs>
|
||||
<out type="string" name="audit-data" />
|
||||
</outs>
|
||||
</shell>
|
||||
<shell command="pi-gsd-tools">
|
||||
<args>
|
||||
<arg string="state" />
|
||||
<arg string="json" />
|
||||
<arg string="--raw" />
|
||||
</args>
|
||||
<outs>
|
||||
<out type="string" name="state" />
|
||||
</outs>
|
||||
</shell>
|
||||
</gsd-execute>
|
||||
|
||||
## Audit Data (pre-injected)
|
||||
|
||||
**UAT Audit:**
|
||||
<gsd-paste name="audit-data" />
|
||||
|
||||
**State:**
|
||||
<gsd-paste name="state" />
|
||||
|
||||
<purpose>
|
||||
Cross-phase audit of all UAT and verification files. Finds every outstanding item (pending, skipped, blocked, human_needed), optionally verifies against the codebase to detect stale docs, and produces a prioritized human test plan.
|
||||
</purpose>
|
||||
|
||||
<process>
|
||||
|
||||
<step name="initialize">
|
||||
Run the CLI audit:
|
||||
|
||||
```bash
|
||||
AUDIT=$(pi-gsd-tools audit-uat --raw)
|
||||
```
|
||||
|
||||
Parse JSON for `results` array and `summary` object.
|
||||
|
||||
If `summary.total_items` is 0:
|
||||
```
|
||||
## All Clear
|
||||
|
||||
No outstanding UAT or verification items found across all phases.
|
||||
All tests are passing, resolved, or diagnosed with fix plans.
|
||||
```
|
||||
Stop here.
|
||||
</step>
|
||||
|
||||
<step name="categorize">
|
||||
Group items by what's actionable NOW vs. what needs prerequisites:
|
||||
|
||||
**Testable Now** (no external dependencies):
|
||||
- `pending` - tests never run
|
||||
- `human_uat` - human verification items
|
||||
- `skipped_unresolved` - skipped without clear blocking reason
|
||||
|
||||
**Needs Prerequisites:**
|
||||
- `server_blocked` - needs external server running
|
||||
- `device_needed` - needs physical device (not simulator)
|
||||
- `build_needed` - needs release/preview build
|
||||
- `third_party` - needs external service configuration
|
||||
|
||||
For each item in "Testable Now", use Grep/Read to check if the underlying feature still exists in the codebase:
|
||||
- If the test references a component/function that no longer exists → mark as `stale`
|
||||
- If the test references code that has been significantly rewritten → mark as `needs_update`
|
||||
- Otherwise → mark as `active`
|
||||
</step>
|
||||
|
||||
<step name="present">
|
||||
Present the audit report:
|
||||
|
||||
```
|
||||
## UAT Audit Report
|
||||
|
||||
**{total_items} outstanding items across {total_files} files in {phase_count} phases**
|
||||
|
||||
### Testable Now ({count})
|
||||
|
||||
| # | Phase | Test | Description | Status |
|
||||
| --- | ------- | ----------- | ----------- | --------------------------- |
|
||||
| 1 | {phase} | {test_name} | {expected} | {active/stale/needs_update} |
|
||||
...
|
||||
|
||||
### Needs Prerequisites ({count})
|
||||
|
||||
| # | Phase | Test | Blocked By | Description |
|
||||
| --- | ------- | ----------- | ---------- | ----------- |
|
||||
| 1 | {phase} | {test_name} | {category} | {expected} |
|
||||
...
|
||||
|
||||
### Stale (can be closed) ({count})
|
||||
|
||||
| # | Phase | Test | Why Stale |
|
||||
| --- | ------- | ----------- | --------- |
|
||||
| 1 | {phase} | {test_name} | {reason} |
|
||||
...
|
||||
|
||||
---
|
||||
|
||||
## Recommended Actions
|
||||
|
||||
1. **Close stale items:** `/gsd-verify-work {phase}` - mark stale tests as resolved
|
||||
2. **Run active tests:** Human UAT test plan below
|
||||
3. **When prerequisites met:** Retest blocked items with `/gsd-verify-work {phase}`
|
||||
```
|
||||
</step>
|
||||
|
||||
<step name="test_plan">
|
||||
Generate a human UAT test plan for "Testable Now" + "active" items only:
|
||||
|
||||
Group by what can be tested together (same screen, same feature, same prerequisite):
|
||||
|
||||
```
|
||||
## Human UAT Test Plan
|
||||
|
||||
### Group 1: {category - e.g., "Billing Flow"}
|
||||
Prerequisites: {what needs to be running/configured}
|
||||
|
||||
1. **{Test name}** (Phase {N})
|
||||
- Navigate to: {where}
|
||||
- Do: {action}
|
||||
- Expected: {expected behavior}
|
||||
|
||||
2. **{Test name}** (Phase {N})
|
||||
...
|
||||
|
||||
### Group 2: {category}
|
||||
...
|
||||
```
|
||||
</step>
|
||||
|
||||
</process>
|
||||
697
.pi/gsd/workflows/autonomous.md
Normal file
697
.pi/gsd/workflows/autonomous.md
Normal file
@@ -0,0 +1,697 @@
|
||||
<gsd-version v="1.12.4" />
|
||||
|
||||
<gsd-arguments>
|
||||
<settings><keep-extra-args /></settings>
|
||||
<arg name="from" type="number" optional />
|
||||
<arg name="to" type="number" optional />
|
||||
</gsd-arguments>
|
||||
|
||||
<gsd-execute>
|
||||
<shell command="pi-gsd-tools">
|
||||
<args>
|
||||
<arg string="roadmap" />
|
||||
<arg string="analyze" />
|
||||
<arg string="--raw" />
|
||||
</args>
|
||||
<outs>
|
||||
<out type="string" name="roadmap" />
|
||||
</outs>
|
||||
</shell>
|
||||
<shell command="pi-gsd-tools">
|
||||
<args>
|
||||
<arg string="state" />
|
||||
<arg string="json" />
|
||||
<arg string="--raw" />
|
||||
</args>
|
||||
<outs>
|
||||
<out type="string" name="state" />
|
||||
</outs>
|
||||
</shell>
|
||||
<shell command="pi-gsd-tools">
|
||||
<args>
|
||||
<arg string="init" />
|
||||
<arg string="milestone-op" />
|
||||
</args>
|
||||
<outs>
|
||||
<out type="string" name="milestone-data" />
|
||||
</outs>
|
||||
</shell>
|
||||
<if>
|
||||
<condition>
|
||||
<starts-with>
|
||||
<left name="milestone-data" />
|
||||
<right type="string" value="@file:" />
|
||||
</starts-with>
|
||||
</condition>
|
||||
<then>
|
||||
<string-op op="split">
|
||||
<args>
|
||||
<arg name="milestone-data" />
|
||||
<arg type="string" value="@file:" />
|
||||
</args>
|
||||
<outs>
|
||||
<out type="string" name="milestone-data-file" />
|
||||
</outs>
|
||||
</string-op>
|
||||
<shell command="cat">
|
||||
<args>
|
||||
<arg name="milestone-data-file" wrap='"' />
|
||||
</args>
|
||||
<outs>
|
||||
<out type="string" name="milestone-data" />
|
||||
</outs>
|
||||
</shell>
|
||||
</then>
|
||||
</if>
|
||||
<!-- SET _auto_chain_active when chain starts - cleared by chain completion/pause, not by absence of --auto -->
|
||||
<shell command="pi-gsd-tools">
|
||||
<args>
|
||||
<arg string="config-set" />
|
||||
<arg string="workflow._auto_chain_active" />
|
||||
<arg string="true" />
|
||||
</args>
|
||||
<outs><suppress-errors /></outs>
|
||||
</shell>
|
||||
</gsd-execute>
|
||||
|
||||
## Context (pre-injected)
|
||||
|
||||
**Roadmap:**
|
||||
<gsd-paste name="roadmap" />
|
||||
|
||||
**State:**
|
||||
<gsd-paste name="state" />
|
||||
|
||||
**Milestone Data:**
|
||||
<gsd-paste name="milestone-data" />
|
||||
|
||||
<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:
|
||||
|
||||
<!-- Context pre-injected above via WXP - variables available via <gsd-paste name="..."> -->
|
||||
|
||||
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:
|
||||
|
||||
<!-- Context pre-injected above via WXP - variables available via <gsd-paste name="..."> -->
|
||||
|
||||
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:** Check if discuss is disabled via settings:
|
||||
|
||||
<!-- Context pre-injected above via WXP - variables available via <gsd-paste name="..."> -->
|
||||
|
||||
Check `has_context`. If false → go to handle_blocker: "Smart discuss for phase ${PHASE_NUM} did not produce CONTEXT.md."
|
||||
|
||||
**3a.5. UI Design Contract (Frontend Phases)**
|
||||
|
||||
Check if this phase has frontend indicators and whether a UI-SPEC already exists:
|
||||
|
||||
<!-- Context pre-injected above via WXP - variables available via <gsd-paste name="..."> -->
|
||||
|
||||
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:
|
||||
<!-- Context pre-injected above via WXP - variables available via <gsd-paste name="..."> -->
|
||||
|
||||
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 || true
|
||||
cat .planning/REQUIREMENTS.md 2>/dev/null || true
|
||||
cat .planning/STATE.md 2>/dev/null || true
|
||||
```
|
||||
|
||||
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 || true) | 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 || true
|
||||
```
|
||||
|
||||
**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 || true
|
||||
ls src/components/ src/hooks/ src/lib/ src/utils/ 2>/dev/null || true
|
||||
```
|
||||
|
||||
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=$(pi-gsd-tools 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 "### the agent's Discretion" subsection - "All implementation choices are at the agent'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 the agent'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}
|
||||
...
|
||||
|
||||
### the agent's Discretion
|
||||
{Any "You decide" answers collected - note the agent 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
|
||||
pi-gsd-tools 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=$(pi-gsd-tools 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 || true
|
||||
```
|
||||
|
||||
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 → ui-phase → plan → execute → ui-review 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
|
||||
- [ ] Frontend phases get UI-SPEC generated before planning (step 3a.5) if not already present
|
||||
- [ ] Frontend phases get UI review audit after successful execution (step 3d.5) if UI-SPEC exists
|
||||
- [ ] UI phase and UI review respect workflow.ui_phase and workflow.ui_review config toggles
|
||||
- [ ] UI review is advisory (non-blocking) - phase proceeds to iterate regardless of score
|
||||
</success_criteria>
|
||||
238
.pi/gsd/workflows/check-todos.md
Normal file
238
.pi/gsd/workflows/check-todos.md
Normal file
@@ -0,0 +1,238 @@
|
||||
<gsd-version v="1.12.4" />
|
||||
|
||||
<gsd-arguments>
|
||||
<settings><keep-extra-args /></settings>
|
||||
</gsd-arguments>
|
||||
|
||||
<gsd-execute>
|
||||
<shell command="pi-gsd-tools">
|
||||
<args>
|
||||
<arg string="init" />
|
||||
<arg string="todos" />
|
||||
<arg string="0" />
|
||||
</args>
|
||||
<outs>
|
||||
<out type="string" name="todos-data" />
|
||||
</outs>
|
||||
</shell>
|
||||
<if>
|
||||
<condition>
|
||||
<starts-with>
|
||||
<left name="todos-data" />
|
||||
<right type="string" value="@file:" />
|
||||
</starts-with>
|
||||
</condition>
|
||||
<then>
|
||||
<string-op op="split">
|
||||
<args>
|
||||
<arg name="todos-data" />
|
||||
<arg type="string" value="@file:" />
|
||||
</args>
|
||||
<outs>
|
||||
<out type="string" name="todos-data-file" />
|
||||
</outs>
|
||||
</string-op>
|
||||
<shell command="cat">
|
||||
<args>
|
||||
<arg name="todos-data-file" wrap='"' />
|
||||
</args>
|
||||
<outs>
|
||||
<out type="string" name="todos-data" />
|
||||
</outs>
|
||||
</shell>
|
||||
</then>
|
||||
</if>
|
||||
<shell command="pi-gsd-tools">
|
||||
<args>
|
||||
<arg string="state" />
|
||||
<arg string="json" />
|
||||
<arg string="--raw" />
|
||||
</args>
|
||||
<outs>
|
||||
<out type="string" name="state" />
|
||||
</outs>
|
||||
</shell>
|
||||
</gsd-execute>
|
||||
|
||||
## Context (pre-injected)
|
||||
|
||||
**Todos:**
|
||||
<gsd-paste name="todos-data" />
|
||||
|
||||
**State:**
|
||||
<gsd-paste name="state" />
|
||||
|
||||
<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:
|
||||
|
||||
<!-- Context pre-injected above via WXP - variables available via <gsd-paste name="..."> -->
|
||||
|
||||
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
|
||||
pi-gsd-tools 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>
|
||||
176
.pi/gsd/workflows/cleanup.md
Normal file
176
.pi/gsd/workflows/cleanup.md
Normal file
@@ -0,0 +1,176 @@
|
||||
<gsd-version v="1.12.4" />
|
||||
|
||||
<gsd-arguments>
|
||||
<settings><keep-extra-args /></settings>
|
||||
</gsd-arguments>
|
||||
|
||||
<gsd-execute>
|
||||
<shell command="pi-gsd-tools">
|
||||
<args>
|
||||
<arg string="state" />
|
||||
<arg string="json" />
|
||||
<arg string="--raw" />
|
||||
</args>
|
||||
<outs>
|
||||
<out type="string" name="state" />
|
||||
</outs>
|
||||
</shell>
|
||||
</gsd-execute>
|
||||
|
||||
## Context (pre-injected)
|
||||
|
||||
**State:**
|
||||
<gsd-paste name="state" />
|
||||
|
||||
<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 || true
|
||||
```
|
||||
|
||||
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 || true
|
||||
```
|
||||
|
||||
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
|
||||
pi-gsd-tools 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>
|
||||
295
.pi/gsd/workflows/complete-milestone.md
Normal file
295
.pi/gsd/workflows/complete-milestone.md
Normal file
@@ -0,0 +1,295 @@
|
||||
<gsd-version v="1.12.4" />
|
||||
|
||||
<gsd-arguments>
|
||||
<settings>
|
||||
<keep-extra-args />
|
||||
</settings>
|
||||
<arg name="version" type="string" optional />
|
||||
</gsd-arguments>
|
||||
|
||||
<gsd-execute>
|
||||
<shell command="pi-gsd-tools">
|
||||
<args>
|
||||
<arg string="roadmap" />
|
||||
<arg string="analyze" />
|
||||
<arg string="--raw" />
|
||||
</args>
|
||||
<outs>
|
||||
<out type="string" name="roadmap" />
|
||||
</outs>
|
||||
</shell>
|
||||
<shell command="pi-gsd-tools">
|
||||
<args>
|
||||
<arg string="state" />
|
||||
<arg string="json" />
|
||||
<arg string="--raw" />
|
||||
</args>
|
||||
<outs>
|
||||
<out type="string" name="state" />
|
||||
</outs>
|
||||
</shell>
|
||||
<!-- CLEAR _auto_chain_active - chain ends here -->
|
||||
<shell command="pi-gsd-tools">
|
||||
<args>
|
||||
<arg string="config-set" />
|
||||
<arg string="workflow._auto_chain_active" />
|
||||
<arg string="false" />
|
||||
</args>
|
||||
<outs><suppress-errors /></outs>
|
||||
</shell>
|
||||
</gsd-execute>
|
||||
|
||||
## Milestone Context (pre-injected by WXP)
|
||||
|
||||
**Version to complete:** <gsd-paste name="version" />
|
||||
|
||||
**Roadmap:**
|
||||
<gsd-paste name="roadmap" />
|
||||
|
||||
**State:**
|
||||
<gsd-paste name="state" />
|
||||
|
||||
<process>
|
||||
|
||||
<step name="verify_readiness">
|
||||
|
||||
**Use `roadmap analyze` for comprehensive readiness check:**
|
||||
|
||||
<!-- Context pre-injected above via WXP - variables available via <gsd-paste name="..."> -->
|
||||
|
||||
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
|
||||
pi-gsd-tools 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** - requirements → research → roadmap
|
||||
|
||||
`/gsd-new-milestone`
|
||||
|
||||
<sub>`/new` first → fresh context window</sub>
|
||||
|
||||
---
|
||||
|
||||
**Optional pre-step:** Capture scope intent before the planning session
|
||||
|
||||
`/gsd-discuss-milestone` — crystallize what to build next, then run `/gsd-new-milestone`
|
||||
|
||||
---
|
||||
```
|
||||
|
||||
</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>
|
||||
250
.pi/gsd/workflows/debug.md
Normal file
250
.pi/gsd/workflows/debug.md
Normal file
@@ -0,0 +1,250 @@
|
||||
<gsd-version v="1.12.4" />
|
||||
|
||||
<gsd-arguments>
|
||||
<settings>
|
||||
<keep-extra-args />
|
||||
</settings>
|
||||
<arg name="description" type="string" optional />
|
||||
</gsd-arguments>
|
||||
|
||||
<gsd-execute>
|
||||
<display msg="Loading debug context..." />
|
||||
<shell command="pi-gsd-tools">
|
||||
<args>
|
||||
<arg string="state" />
|
||||
<arg string="json" />
|
||||
<arg string="--raw" />
|
||||
</args>
|
||||
<outs>
|
||||
<suppress-errors />
|
||||
<out type="string" name="state" />
|
||||
</outs>
|
||||
</shell>
|
||||
<shell command="pi-gsd-tools">
|
||||
<args>
|
||||
<arg string="current-timestamp" />
|
||||
<arg string="--raw" />
|
||||
</args>
|
||||
<outs>
|
||||
<out type="string" name="timestamp" />
|
||||
</outs>
|
||||
</shell>
|
||||
<shell command="pi-gsd-tools">
|
||||
<args>
|
||||
<arg string="agent-skills" />
|
||||
<arg string="gsd-debugger" />
|
||||
</args>
|
||||
<outs>
|
||||
<suppress-errors />
|
||||
<out type="string" name="agent-skills-debugger" />
|
||||
</outs>
|
||||
</shell>
|
||||
</gsd-execute>
|
||||
|
||||
## Debug Context (pre-injected by WXP)
|
||||
|
||||
**Problem:** <gsd-paste name="description" />
|
||||
|
||||
**Timestamp:** <gsd-paste name="timestamp" />
|
||||
|
||||
**Project State:**
|
||||
<gsd-paste name="state" />
|
||||
|
||||
**Debugger Skills:**
|
||||
<gsd-paste name="agent-skills-debugger" />
|
||||
|
||||
---
|
||||
|
||||
<purpose>
|
||||
Systematic debugging session. Diagnoses failures, errors, and unexpected behavior using structured root-cause analysis. Spawns gsd-debugger with full project context for focused investigation.
|
||||
|
||||
For post-mortem investigation of completed phases, use `/gsd-forensics` instead.
|
||||
</purpose>
|
||||
|
||||
<available_agent_types>
|
||||
Valid GSD subagent types (use exact names - do not fall back to 'general-purpose'):
|
||||
- gsd-debugger - Diagnoses and fixes issues
|
||||
</available_agent_types>
|
||||
|
||||
<process>
|
||||
|
||||
<step name="gather_context">
|
||||
<!-- State, timestamp, and description pre-injected above via WXP -->
|
||||
|
||||
Load current phase context:
|
||||
|
||||
```bash
|
||||
PHASE_INFO=$(pi-gsd-tools roadmap analyze --raw 2>/dev/null || echo "{}")
|
||||
```
|
||||
|
||||
Extract from state JSON:
|
||||
- `current_phase` - what's being worked on
|
||||
- `last_activity` - when was the last change
|
||||
- `milestone` - current milestone name
|
||||
|
||||
If `description` is empty, ask the user:
|
||||
```
|
||||
What's broken? Describe the symptom in one sentence:
|
||||
(e.g. "auth tokens expire immediately", "build fails with missing module", "tests pass locally but fail in CI")
|
||||
```
|
||||
Store response as `description`.
|
||||
</step>
|
||||
|
||||
<step name="classify_issue">
|
||||
Classify the issue from the description:
|
||||
|
||||
| Symptom pattern | Issue type |
|
||||
|----------------|------------|
|
||||
| Error/exception message | `runtime_error` |
|
||||
| Test failures | `test_failure` |
|
||||
| Build/compile error | `build_error` |
|
||||
| Wrong behavior (no error) | `logic_error` |
|
||||
| Performance problem | `performance` |
|
||||
| Integration failure | `integration` |
|
||||
| Unclear | `unknown` |
|
||||
|
||||
Set `ISSUE_TYPE`.
|
||||
</step>
|
||||
|
||||
<step name="spawn_debugger">
|
||||
Display banner:
|
||||
```
|
||||
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
|
||||
GSD ► DEBUG SESSION
|
||||
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
|
||||
|
||||
Issue: {description}
|
||||
Type: {ISSUE_TYPE}
|
||||
Phase: {current_phase || "not set"}
|
||||
|
||||
◆ Spawning debugger...
|
||||
```
|
||||
|
||||
Resolve model:
|
||||
```bash
|
||||
DEBUGGER_MODEL=$(pi-gsd-tools resolve-model gsd-debugger --raw 2>/dev/null || echo "")
|
||||
```
|
||||
|
||||
Debug prompt:
|
||||
```markdown
|
||||
<objective>
|
||||
Debug the following issue in this project:
|
||||
{description}
|
||||
|
||||
Issue type: {ISSUE_TYPE}
|
||||
Current phase: {current_phase}
|
||||
Milestone: {milestone}
|
||||
</objective>
|
||||
|
||||
<files_to_read>
|
||||
- .planning/STATE.md (Project state and recent decisions)
|
||||
- .planning/ROADMAP.md (Phase context)
|
||||
- ./GEMINI.md or ./CLAUDE.md (Project-specific guidelines, if exists)
|
||||
</files_to_read>
|
||||
|
||||
${AGENT_SKILLS_DEBUGGER}
|
||||
|
||||
<investigation_protocol>
|
||||
1. Reproduce: Identify the minimal steps to trigger the issue
|
||||
2. Isolate: Narrow down to the failing component/file/function
|
||||
3. Root cause: Identify WHY it fails, not just WHERE
|
||||
4. Fix: Implement the smallest change that solves the root cause
|
||||
5. Verify: Confirm the fix works and doesn't introduce regressions
|
||||
|
||||
Always check:
|
||||
- Recent commits (git log --oneline -10) for what changed
|
||||
- Related files for mismatched interfaces or broken contracts
|
||||
- Test suite for existing coverage that should have caught this
|
||||
</investigation_protocol>
|
||||
|
||||
<output_format>
|
||||
## DEBUG COMPLETE
|
||||
|
||||
**Root cause:** [one sentence]
|
||||
**Fix applied:** [what was changed]
|
||||
**Files modified:** [list]
|
||||
**Verification:** [how to confirm it's fixed]
|
||||
|
||||
OR
|
||||
|
||||
## DEBUG BLOCKED
|
||||
|
||||
**Investigated:** [what was tried]
|
||||
**Blocker:** [what additional info is needed]
|
||||
**Next step:** [what the human should provide or check]
|
||||
</output_format>
|
||||
```
|
||||
|
||||
```
|
||||
Task(
|
||||
prompt=debug_prompt,
|
||||
subagent_type="gsd-debugger",
|
||||
model="{DEBUGGER_MODEL}",
|
||||
description="Debug: {description}"
|
||||
)
|
||||
```
|
||||
</step>
|
||||
|
||||
<step name="handle_return">
|
||||
**`## DEBUG COMPLETE`:**
|
||||
|
||||
Display root cause, fix, and verification steps. Offer:
|
||||
```
|
||||
1. Capture as todo (/gsd-add-todo) - if fix not yet applied
|
||||
2. Continue with current phase (/gsd-execute-phase)
|
||||
3. Done
|
||||
```
|
||||
|
||||
**`## DEBUG BLOCKED`:**
|
||||
|
||||
Display blocker and next steps. Offer:
|
||||
```
|
||||
1. Provide additional context and retry
|
||||
2. Try forensics mode (/gsd-forensics) - deeper investigation
|
||||
3. Capture as todo and investigate later
|
||||
```
|
||||
</step>
|
||||
|
||||
<step name="persist_session">
|
||||
If the debug session produced a fix or useful findings, offer to save:
|
||||
|
||||
```bash
|
||||
mkdir -p .planning/debug
|
||||
```
|
||||
|
||||
Write `.planning/debug/{YYYY-MM-DD}-{slug}.md`:
|
||||
```markdown
|
||||
---
|
||||
created: {timestamp}
|
||||
issue: {description}
|
||||
type: {ISSUE_TYPE}
|
||||
phase: {current_phase}
|
||||
status: {resolved|blocked}
|
||||
---
|
||||
|
||||
## Root Cause
|
||||
{root cause summary}
|
||||
|
||||
## Fix
|
||||
{what was changed}
|
||||
|
||||
## Verification
|
||||
{how to confirm}
|
||||
```
|
||||
|
||||
Commit:
|
||||
```bash
|
||||
pi-gsd-tools commit "docs: debug session - {description_slug}" --files .planning/debug/{filename}
|
||||
```
|
||||
</step>
|
||||
|
||||
</process>
|
||||
|
||||
<success_criteria>
|
||||
- [ ] Problem description captured (from arg or prompt)
|
||||
- [ ] Issue classified by type
|
||||
- [ ] gsd-debugger spawned with full project context
|
||||
- [ ] Root cause identified or blocker surfaced
|
||||
- [ ] Fix applied or next steps clear
|
||||
- [ ] Session optionally persisted in .planning/debug/
|
||||
</success_criteria>
|
||||
268
.pi/gsd/workflows/diagnose-issues.md
Normal file
268
.pi/gsd/workflows/diagnose-issues.md
Normal file
@@ -0,0 +1,268 @@
|
||||
<gsd-version v="1.12.4" />
|
||||
|
||||
<gsd-arguments>
|
||||
<settings><keep-extra-args /></settings>
|
||||
</gsd-arguments>
|
||||
|
||||
<gsd-execute>
|
||||
<shell command="pi-gsd-tools">
|
||||
<args>
|
||||
<arg string="state" />
|
||||
<arg string="json" />
|
||||
<arg string="--raw" />
|
||||
</args>
|
||||
<outs>
|
||||
<out type="string" name="state" />
|
||||
</outs>
|
||||
</shell>
|
||||
<shell command="pi-gsd-tools">
|
||||
<args>
|
||||
<arg string="agent-skills" />
|
||||
<arg string="gsd-debugger" />
|
||||
</args>
|
||||
<outs>
|
||||
<suppress-errors />
|
||||
<out type="string" name="agent-skills-debugger" />
|
||||
</outs>
|
||||
</shell>
|
||||
</gsd-execute>
|
||||
|
||||
## Context (pre-injected)
|
||||
|
||||
**State:**
|
||||
<gsd-paste name="state" />
|
||||
|
||||
**Debugger Skills:**
|
||||
<gsd-paste name="agent-skills-debugger" />
|
||||
|
||||
<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>
|
||||
|
||||
<available_agent_types>
|
||||
Valid GSD subagent types (use exact names - do not fall back to 'general-purpose'):
|
||||
- gsd-debugger - Diagnoses and fixes issues
|
||||
</available_agent_types>
|
||||
|
||||
<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">
|
||||
**Load agent skills:**
|
||||
|
||||
```bash
|
||||
AGENT_SKILLS_DEBUGGER=$(pi-gsd-tools agent-skills gsd-debugger 2>/dev/null)
|
||||
```
|
||||
|
||||
**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>\n${AGENT_SKILLS_DEBUGGER}",
|
||||
subagent_type="gsd-debugger",
|
||||
isolation="worktree",
|
||||
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
|
||||
pi-gsd-tools 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>
|
||||
291
.pi/gsd/workflows/discovery-phase.md
Normal file
291
.pi/gsd/workflows/discovery-phase.md
Normal file
@@ -0,0 +1,291 @@
|
||||
<gsd-version v="1.12.4" />
|
||||
|
||||
<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**
|
||||
|
||||
the agent'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 .pi/gsd/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 .pi/gsd/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 .pi/gsd/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 .pi/gsd/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 .pi/gsd/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>
|
||||
467
.pi/gsd/workflows/discuss-milestone.md
Normal file
467
.pi/gsd/workflows/discuss-milestone.md
Normal file
@@ -0,0 +1,467 @@
|
||||
<gsd-version v="2.0.24" />
|
||||
|
||||
<gsd-arguments>
|
||||
<settings>
|
||||
<keep-extra-args />
|
||||
</settings>
|
||||
<arg name="auto" type="flag" flag="--auto" optional />
|
||||
</gsd-arguments>
|
||||
|
||||
<gsd-execute>
|
||||
<shell command="pi-gsd-tools">
|
||||
<args>
|
||||
<arg string="init" />
|
||||
<arg string="milestone-op" />
|
||||
</args>
|
||||
<outs>
|
||||
<out type="string" name="init" />
|
||||
</outs>
|
||||
</shell>
|
||||
<shell command="pi-gsd-tools">
|
||||
<args>
|
||||
<arg string="state" />
|
||||
<arg string="json" />
|
||||
<arg string="--raw" />
|
||||
</args>
|
||||
<outs>
|
||||
<suppress-errors />
|
||||
<out type="string" name="state" />
|
||||
</outs>
|
||||
</shell>
|
||||
<shell command="pi-gsd-tools">
|
||||
<args>
|
||||
<arg string="roadmap" />
|
||||
<arg string="analyze" />
|
||||
<arg string="--raw" />
|
||||
</args>
|
||||
<outs>
|
||||
<suppress-errors />
|
||||
<out type="string" name="roadmap" />
|
||||
</outs>
|
||||
</shell>
|
||||
</gsd-execute>
|
||||
|
||||
## Context (pre-injected)
|
||||
|
||||
**Init:**
|
||||
<gsd-paste name="init" />
|
||||
|
||||
**Project State:**
|
||||
<gsd-paste name="state" />
|
||||
|
||||
**Current Roadmap:**
|
||||
<gsd-paste name="roadmap" />
|
||||
|
||||
---
|
||||
|
||||
<purpose>
|
||||
Crystallize what the next milestone should deliver before starting the planning machinery. You are a thinking partner — a PM who knows what shipped, asks smart questions, and helps the user clarify product scope before committing to a roadmap.
|
||||
|
||||
Output: `.planning/MILESTONE-CONTEXT.md`, consumed by /gsd-new-milestone.
|
||||
|
||||
Optional step — /gsd-new-milestone works without it. The value is separating the "what do we build?" conversation from the requirements and roadmapping machinery.
|
||||
</purpose>
|
||||
|
||||
<philosophy>
|
||||
**User = product owner. Agent = PM/advisor.**
|
||||
|
||||
The user knows:
|
||||
- What users are struggling with
|
||||
- What the next logical product step is
|
||||
- What MUST ship vs nice-to-have
|
||||
- Any hard constraints (tech, team, timeline)
|
||||
|
||||
The user doesn't need to define:
|
||||
- How to structure phases (that's the roadmapper)
|
||||
- Implementation approach (that's research + discuss-phase)
|
||||
- Which requirements to write (that's new-milestone)
|
||||
|
||||
Your job: help the user articulate a clear, scoped milestone intent that new-milestone can turn into requirements and a roadmap.
|
||||
</philosophy>
|
||||
|
||||
<scope_guardrail>
|
||||
**Product-level only.** This discussion is about WHAT the milestone delivers, not HOW.
|
||||
|
||||
**Allowed:**
|
||||
- "Should we tackle X or defer it?"
|
||||
- "What's the must-have vs nice-to-have split?"
|
||||
- "Any hard constraints for this cycle?"
|
||||
- "How will we know this milestone is done?"
|
||||
|
||||
**Not here:**
|
||||
- "Should we use Redis or Postgres for this?"
|
||||
- "Which architecture pattern?"
|
||||
- "How should we structure the phases?"
|
||||
|
||||
If the user goes implementation-level, redirect:
|
||||
```
|
||||
"That's a planning question — /gsd-new-milestone and /gsd-discuss-phase will handle it.
|
||||
For now: do you want [capability] in scope for this milestone?"
|
||||
```
|
||||
</scope_guardrail>
|
||||
|
||||
<answer_validation>
|
||||
After every AskUserQuestion call, check if the response is empty or whitespace-only. If so:
|
||||
1. Retry once with the same parameters
|
||||
2. If still empty, present options as a plain-text numbered list
|
||||
|
||||
**Text mode (`workflow.text_mode: true` or `--text` flag):**
|
||||
Replace ALL AskUserQuestion calls with plain-text numbered lists. User types a number.
|
||||
Required for Claude Code remote sessions where TUI menus don't forward.
|
||||
</answer_validation>
|
||||
|
||||
<process>
|
||||
|
||||
## 1. Initialize
|
||||
|
||||
<!-- Context pre-injected above via WXP -->
|
||||
|
||||
Parse init JSON for: `commit_docs`, `context_window`, `milestone_version`, `milestone_name`, `last_completed_milestone`, `roadmap_exists`, `state_exists`.
|
||||
|
||||
**If `state_exists` is false:**
|
||||
```
|
||||
No .planning/ directory found. Set up a project first:
|
||||
|
||||
/gsd-new-project
|
||||
```
|
||||
Exit workflow.
|
||||
|
||||
Read project files:
|
||||
```bash
|
||||
cat .planning/PROJECT.md 2>/dev/null || true
|
||||
cat .planning/MILESTONES.md 2>/dev/null || true
|
||||
```
|
||||
|
||||
Extract from PROJECT.md: project name, core value, non-negotiables, target users.
|
||||
Extract from MILESTONES.md: what shipped in completed milestones (summaries, not full detail).
|
||||
|
||||
**Read text mode config:**
|
||||
```bash
|
||||
TEXT_MODE=$(pi-gsd-tools config-get workflow.text_mode 2>/dev/null || echo "false")
|
||||
```
|
||||
Enable text mode if `--text` in $ARGUMENTS OR `TEXT_MODE` is `true`.
|
||||
|
||||
## 2. Check Existing MILESTONE-CONTEXT.md
|
||||
|
||||
```bash
|
||||
test -f .planning/MILESTONE-CONTEXT.md && echo "exists" || echo "absent"
|
||||
```
|
||||
|
||||
**If exists:**
|
||||
|
||||
**If `--auto`:** Load existing content, continue to step 3 to refresh it. Log: `[auto] Existing MILESTONE-CONTEXT.md found — refreshing.`
|
||||
|
||||
**Otherwise,** use AskUserQuestion:
|
||||
- header: "Context exists"
|
||||
- question: "MILESTONE-CONTEXT.md already exists. What do you want to do?"
|
||||
- options:
|
||||
- "Update it" — Revise and improve existing context
|
||||
- "View it" — Show current content, then decide
|
||||
- "Skip" — Use as-is, go straight to /gsd-new-milestone
|
||||
|
||||
If "View": display file contents, then re-ask "Update it" / "Skip".
|
||||
If "Skip": display `Next: /gsd-new-milestone` and exit.
|
||||
If "Update": load existing content, continue to step 3.
|
||||
|
||||
**If absent:** Continue to step 3.
|
||||
|
||||
## 3. Retrospective Framing
|
||||
|
||||
Sets the context for "what's next" based on what shipped.
|
||||
|
||||
**If `last_completed_milestone` is not null:**
|
||||
|
||||
Read the matching section in `.planning/MILESTONES.md` for `last_completed_milestone.version`.
|
||||
|
||||
Display (no user input needed):
|
||||
```
|
||||
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
|
||||
Last milestone: [version] — [name]
|
||||
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
|
||||
[2-3 sentence summary of what shipped from MILESTONES.md]
|
||||
```
|
||||
|
||||
Then ask ONE freeform question (plain text, NOT AskUserQuestion):
|
||||
|
||||
> "What feedback or signals are shaping what you want to build next?"
|
||||
|
||||
Wait for response. Use the answer to seed the scope discussion. Do not ask follow-ups from this — carry the insight forward.
|
||||
|
||||
**If `--auto`:** Skip retrospective question. Read STATE.md accumulated context for any signals.
|
||||
|
||||
**If no completed milestones:** Skip retrospective entirely. Continue to step 4.
|
||||
|
||||
## 4. Gather Milestone Intent
|
||||
|
||||
Open question to surface rough direction before structuring.
|
||||
|
||||
Ask (plain text, NOT AskUserQuestion):
|
||||
|
||||
> "What do you want this milestone to deliver? Give me the rough picture — we'll tighten the scope next."
|
||||
|
||||
Wait for response. Parse it for:
|
||||
- Feature/capability mentions → candidates for scope-in
|
||||
- Exclusions or "not yet" signals → candidates for scope-out
|
||||
- Urgency or priority cues
|
||||
- Any constraints mentioned in passing
|
||||
|
||||
Reflect back in 2-3 sentences:
|
||||
```
|
||||
"So the core of this milestone is [X]. You also mentioned [Y],
|
||||
and [Z] sounds like a natural boundary. Is that the right picture?"
|
||||
```
|
||||
|
||||
If they confirm: proceed to step 5 with extracted candidates.
|
||||
If they adjust: incorporate and reflect again. Max 2 loops, then proceed.
|
||||
|
||||
**If `--auto`:** Skip reflection loop. Extract candidates from the intent statement directly and proceed.
|
||||
|
||||
## 5. Scope Discussion
|
||||
|
||||
Turn the rough intent into a clear in/out split.
|
||||
|
||||
**Build candidate list** from:
|
||||
- Step 4's response (feature/capability mentions)
|
||||
- STATE.md accumulated context (pending items, blockers noted)
|
||||
- MILESTONES.md "Future Requirements" or deferred items from last milestone
|
||||
- Any items in `.planning/REQUIREMENTS.md` marked Out of Scope that might be reconsidered
|
||||
|
||||
Group related candidates into clusters (2-4 features per cluster). Present one cluster at a time.
|
||||
|
||||
**For each cluster:**
|
||||
|
||||
If text mode: present as numbered list with multi-select.
|
||||
Otherwise use AskUserQuestion (multiSelect: true):
|
||||
- header: "Scope: [cluster]" (max 12 chars)
|
||||
- question: "Which of these belong in this milestone?"
|
||||
- options: each candidate with a 1-line description
|
||||
|
||||
After all clusters, show a running tally:
|
||||
```
|
||||
Scoped in: [N] capabilities
|
||||
Deferred: [M] capabilities
|
||||
```
|
||||
|
||||
**Explicit exclusions** — after clusters are done:
|
||||
|
||||
If text mode: ask as plain-text.
|
||||
Otherwise use AskUserQuestion:
|
||||
- header: "Out of scope"
|
||||
- question: "Anything to explicitly exclude — even if it seems related?"
|
||||
- options:
|
||||
- "Nothing to add — the scope list covers it"
|
||||
- "Yes, I want to explicitly exclude something"
|
||||
|
||||
If "Yes": ask them to name it (plain text). Capture with reason.
|
||||
|
||||
**If `--auto`:** Include everything mentioned in step 4's intent or with a clear priority signal. Exclude only items the user explicitly flagged as "not now" or "next milestone".
|
||||
|
||||
## 6. Constraints
|
||||
|
||||
Anything that bounds how this milestone must be shaped.
|
||||
|
||||
If text mode: present as numbered multi-select list.
|
||||
Otherwise use AskUserQuestion (multiSelect: true):
|
||||
- header: "Constraints"
|
||||
- question: "Any hard constraints for this milestone?"
|
||||
- options:
|
||||
- "No breaking changes — existing integrations must keep working"
|
||||
- "No new external dependencies"
|
||||
- "Must maintain backwards compatibility with existing data"
|
||||
- "Performance budget — no regressions on key metrics"
|
||||
- "None — this milestone is unconstrained"
|
||||
- "Other — let me describe it"
|
||||
|
||||
If "Other": ask plain text, record result.
|
||||
|
||||
**If `--auto`:** Default to "None" unless PROJECT.md or STATE.md explicitly mentions active constraints.
|
||||
|
||||
## 7. Success Definition
|
||||
|
||||
How does "done" look from the outside?
|
||||
|
||||
Ask (plain text, NOT AskUserQuestion):
|
||||
|
||||
> "Finish this sentence: this milestone is a success when users can ___."
|
||||
|
||||
Wait for response. Parse 1-3 observable outcomes.
|
||||
|
||||
If the response is vague ("when everything works", "when it's polished"), prompt once:
|
||||
|
||||
> "What's a concrete user action that proves it — something you could demo?"
|
||||
|
||||
Capture outcomes. If they list more than 3, keep the 3 most concrete and user-observable.
|
||||
|
||||
**If `--auto`:** Derive success outcomes from scoped capabilities — "user can [primary action]" for each major in-scope cluster.
|
||||
|
||||
## 8. Open Questions
|
||||
|
||||
Surface anything that needs resolving in new-milestone or early research — not as a blocker, but as a signal.
|
||||
|
||||
Ask (plain text):
|
||||
|
||||
> "Any open questions or risks you want the planning session to address early?"
|
||||
|
||||
If they say "no" or give nothing: record "None — scope is clear."
|
||||
If they give questions: capture them for the MILESTONE-CONTEXT.md open_questions section.
|
||||
|
||||
**If `--auto`:** Skip. Default to "None."
|
||||
|
||||
## 9. Write MILESTONE-CONTEXT.md
|
||||
|
||||
Write to `.planning/MILESTONE-CONTEXT.md`:
|
||||
|
||||
```markdown
|
||||
# Milestone Context
|
||||
|
||||
**Gathered:** [ISO date]
|
||||
**Status:** Ready for /gsd-new-milestone
|
||||
|
||||
<milestone_goal>
|
||||
## Goal
|
||||
|
||||
[One sentence distilled from step 4 — what this milestone delivers for users]
|
||||
|
||||
</milestone_goal>
|
||||
|
||||
<scope>
|
||||
## Scope
|
||||
|
||||
### In this milestone
|
||||
|
||||
[For each scoped-in capability, in priority order:]
|
||||
- **[Capability name]**: [1-line description of what it means for users]
|
||||
|
||||
### Explicitly out of scope
|
||||
|
||||
[For each explicit exclusion:]
|
||||
- **[Capability name]**: [reason — "deferred to next milestone", "separate product area", etc.]
|
||||
|
||||
[If no explicit exclusions: "No explicit exclusions — boundary is the in-scope list above"]
|
||||
|
||||
</scope>
|
||||
|
||||
<constraints>
|
||||
## Constraints
|
||||
|
||||
[For each constraint from step 6:]
|
||||
- [Constraint statement]
|
||||
|
||||
[If none: "None — unconstrained milestone"]
|
||||
|
||||
</constraints>
|
||||
|
||||
<success>
|
||||
## Success Definition
|
||||
|
||||
This milestone is successful when:
|
||||
- [Observable user outcome 1]
|
||||
- [Observable user outcome 2]
|
||||
[- [Observable user outcome 3] — only if genuinely distinct]
|
||||
|
||||
</success>
|
||||
|
||||
<open_questions>
|
||||
## Open Questions for Planning
|
||||
|
||||
[Questions from step 8 that new-milestone or early research should address:]
|
||||
- [Question]
|
||||
|
||||
[If none: "None — scope is clear"]
|
||||
|
||||
</open_questions>
|
||||
|
||||
---
|
||||
|
||||
*Milestone context gathered: [date]*
|
||||
*Run /gsd-new-milestone to start planning*
|
||||
```
|
||||
|
||||
## 10. Commit
|
||||
|
||||
```bash
|
||||
pi-gsd-tools commit "docs: capture milestone context" --files .planning/MILESTONE-CONTEXT.md
|
||||
```
|
||||
|
||||
If `commit_docs` is false: skip commit silently.
|
||||
|
||||
## 11. Present Summary and Next Steps
|
||||
|
||||
```
|
||||
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
|
||||
GSD ► MILESTONE CONTEXT CAPTURED ✓
|
||||
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
|
||||
|
||||
**Goal:** [one sentence from context file]
|
||||
|
||||
**In scope ([N] capabilities):**
|
||||
[bullet list]
|
||||
|
||||
**Constraints:** [list or "none"]
|
||||
**Success:** [first observable outcome]
|
||||
|
||||
───────────────────────────────────────────────────────────────
|
||||
|
||||
## ▶ Next Up
|
||||
|
||||
**Start milestone planning** — requirements, research, roadmap
|
||||
|
||||
`/gsd-new-milestone`
|
||||
|
||||
<sub>`/new` first → fresh context window</sub>
|
||||
|
||||
───────────────────────────────────────────────────────────────
|
||||
```
|
||||
|
||||
## 12. Auto-Advance
|
||||
|
||||
1. Parse `--auto` flag from $ARGUMENTS.
|
||||
2. Sync chain flag with intent — clear if not in `--auto` run:
|
||||
```bash
|
||||
if [[ ! "$ARGUMENTS" =~ --auto ]]; then
|
||||
pi-gsd-tools config-set workflow._auto_chain_active false 2>/dev/null
|
||||
fi
|
||||
```
|
||||
3. Read chain flag and config:
|
||||
```bash
|
||||
AUTO_CHAIN=$(pi-gsd-tools config-get workflow._auto_chain_active 2>/dev/null || echo "false")
|
||||
AUTO_CFG=$(pi-gsd-tools config-get workflow.auto_advance 2>/dev/null || echo "false")
|
||||
```
|
||||
|
||||
**If `--auto` OR `AUTO_CHAIN` is true OR `AUTO_CFG` is true:**
|
||||
|
||||
Display:
|
||||
```
|
||||
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
|
||||
GSD ► AUTO-ADVANCING TO NEW-MILESTONE
|
||||
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
|
||||
|
||||
Context captured. Launching new-milestone...
|
||||
```
|
||||
|
||||
Launch:
|
||||
```
|
||||
Skill(skill="gsd-new-milestone", args="--auto ${GSD_WS}")
|
||||
```
|
||||
|
||||
Handle return:
|
||||
- **MILESTONE INITIALIZED** → Display success banner, done.
|
||||
- **CHECKPOINT / BLOCKED** → Stop chain, show: `Continue: /gsd-new-milestone ${GSD_WS}`
|
||||
|
||||
**If not auto:** Step 11 already shown. Done.
|
||||
|
||||
</process>
|
||||
|
||||
<success_criteria>
|
||||
- [ ] .planning/ exists (state_exists check)
|
||||
- [ ] Existing MILESTONE-CONTEXT.md handled (update/view/skip)
|
||||
- [ ] Last completed milestone surfaced for retrospective framing
|
||||
- [ ] Milestone intent gathered via open conversation
|
||||
- [ ] Scope in/out defined per capability cluster
|
||||
- [ ] Hard constraints captured
|
||||
- [ ] Success definition captured as observable user outcomes
|
||||
- [ ] Open questions captured for planning session
|
||||
- [ ] MILESTONE-CONTEXT.md written to .planning/
|
||||
- [ ] Committed (if commit_docs)
|
||||
- [ ] User knows next step: /gsd-new-milestone
|
||||
</success_criteria>
|
||||
725
.pi/gsd/workflows/discuss-phase-assumptions.md
Normal file
725
.pi/gsd/workflows/discuss-phase-assumptions.md
Normal file
@@ -0,0 +1,725 @@
|
||||
<gsd-version v="1.12.4" />
|
||||
|
||||
<gsd-arguments>
|
||||
<settings><keep-extra-args /></settings>
|
||||
<arg name="phase" type="number" />
|
||||
</gsd-arguments>
|
||||
|
||||
<gsd-execute>
|
||||
<shell command="pi-gsd-tools">
|
||||
<args>
|
||||
<arg string="init" />
|
||||
<arg string="phase-op" />
|
||||
</args>
|
||||
<outs>
|
||||
<out type="string" name="init" />
|
||||
</outs>
|
||||
</shell>
|
||||
<if>
|
||||
<condition>
|
||||
<starts-with>
|
||||
<left name="init" />
|
||||
<right type="string" value="@file:" />
|
||||
</starts-with>
|
||||
</condition>
|
||||
<then>
|
||||
<string-op op="split">
|
||||
<args>
|
||||
<arg name="init" />
|
||||
<arg type="string" value="@file:" />
|
||||
</args>
|
||||
<outs>
|
||||
<out type="string" name="init-file" />
|
||||
</outs>
|
||||
</string-op>
|
||||
<shell command="cat">
|
||||
<args>
|
||||
<arg name="init-file" wrap='"' />
|
||||
</args>
|
||||
<outs>
|
||||
<out type="string" name="init" />
|
||||
</outs>
|
||||
</shell>
|
||||
</then>
|
||||
</if>
|
||||
<shell command="pi-gsd-tools">
|
||||
<args>
|
||||
<arg string="state" />
|
||||
<arg string="json" />
|
||||
<arg string="--raw" />
|
||||
</args>
|
||||
<outs>
|
||||
<out type="string" name="state" />
|
||||
</outs>
|
||||
</shell>
|
||||
<shell command="pi-gsd-tools">
|
||||
<args>
|
||||
<arg string="agent-skills" />
|
||||
<arg string="gsd-assumptions-analyzer" />
|
||||
</args>
|
||||
<outs>
|
||||
<suppress-errors />
|
||||
<out type="string" name="agent-skills-analyzer" />
|
||||
</outs>
|
||||
</shell>
|
||||
</gsd-execute>
|
||||
|
||||
## Context (pre-injected)
|
||||
|
||||
**Phase:** <gsd-paste name="phase" />
|
||||
|
||||
**Phase Data:**
|
||||
<gsd-paste name="init" />
|
||||
|
||||
**State:**
|
||||
<gsd-paste name="state" />
|
||||
|
||||
<purpose>
|
||||
Extract implementation decisions that downstream agents need - using codebase-first analysis
|
||||
and assumption surfacing instead of interview-style questioning.
|
||||
|
||||
You are a thinking partner, not an interviewer. Analyze the codebase deeply, surface what you
|
||||
believe based on evidence, and ask the user only to correct what's wrong.
|
||||
</purpose>
|
||||
|
||||
<available_agent_types>
|
||||
Valid GSD subagent types (use exact names - do not fall back to 'general-purpose'):
|
||||
- gsd-assumptions-analyzer - Analyzes codebase to surface implementation assumptions
|
||||
</available_agent_types>
|
||||
|
||||
<downstream_awareness>
|
||||
**CONTEXT.md feeds into:**
|
||||
|
||||
1. **gsd-phase-researcher** - Reads CONTEXT.md to know WHAT to research
|
||||
2. **gsd-planner** - Reads CONTEXT.md to know WHAT decisions are locked
|
||||
|
||||
**Your job:** Capture decisions clearly enough that downstream agents can act on them
|
||||
without asking the user again. Output is identical to discuss mode - same CONTEXT.md format.
|
||||
</downstream_awareness>
|
||||
|
||||
<philosophy>
|
||||
**Assumptions mode philosophy:**
|
||||
|
||||
The user is a visionary, not a codebase archaeologist. They need enough context to evaluate
|
||||
whether your assumptions match their intent - not to answer questions you could figure out
|
||||
by reading the code.
|
||||
|
||||
- Read the codebase FIRST, form opinions SECOND, ask ONLY about what's genuinely unclear
|
||||
- Every assumption must cite evidence (file paths, patterns found)
|
||||
- Every assumption must state consequences if wrong
|
||||
- Minimize user interactions: ~2-4 corrections vs ~15-20 questions
|
||||
</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.
|
||||
|
||||
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 "Deferred Ideas". Don't lose it, don't act on it.
|
||||
</scope_guardrail>
|
||||
|
||||
<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
|
||||
|
||||
**Text mode (`workflow.text_mode: true` in config or `--text` flag):**
|
||||
When text mode is active, do not use AskUserQuestion at all. Present every question as a
|
||||
plain-text numbered list and ask the user to type their choice number.
|
||||
</answer_validation>
|
||||
|
||||
<process>
|
||||
|
||||
<step name="initialize" priority="first">
|
||||
Phase number from argument (required).
|
||||
|
||||
<!-- Context pre-injected above via WXP - variables available via <gsd-paste name="..."> -->
|
||||
|
||||
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 "Update it" (if context exists) or continue without prompting
|
||||
- In `present_assumptions`: skip confirmation gate, proceed directly to write CONTEXT.md
|
||||
- In `correct_assumptions`: auto-select recommended option for each correction
|
||||
- Log each auto-selected choice inline
|
||||
- After completion, auto-advance to plan-phase
|
||||
</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 || true
|
||||
```
|
||||
|
||||
**If exists:**
|
||||
|
||||
**If `--auto`:** Auto-select "Update it". Log: `[auto] Context exists - updating with assumption-based analysis.`
|
||||
|
||||
**Otherwise:** Use AskUserQuestion:
|
||||
- header: "Context"
|
||||
- question: "Phase [X] already has context. What do you want to do?"
|
||||
- options:
|
||||
- "Update it" - Re-analyze codebase and refresh assumptions
|
||||
- "View it" - Show me what's there
|
||||
- "Skip" - Use existing context as-is
|
||||
|
||||
If "Update": Load existing, continue to load_prior_context
|
||||
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 assumption analysis, 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"
|
||||
- "View existing plans"
|
||||
- "Cancel"
|
||||
|
||||
If "Continue and replan after": Continue to load_prior_context.
|
||||
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.
|
||||
|
||||
**Step 1: Read project-level files**
|
||||
```bash
|
||||
cat .planning/PROJECT.md 2>/dev/null || true
|
||||
cat .planning/REQUIREMENTS.md 2>/dev/null || true
|
||||
cat .planning/STATE.md 2>/dev/null || true
|
||||
```
|
||||
|
||||
Extract from these:
|
||||
- **PROJECT.md** - Vision, principles, non-negotiables, user preferences
|
||||
- **REQUIREMENTS.md** - Acceptance criteria, constraints
|
||||
- **STATE.md** - Current progress, any flags
|
||||
|
||||
**Step 2: Read all prior CONTEXT.md files**
|
||||
```bash
|
||||
(find .planning/phases -name "*-CONTEXT.md" 2>/dev/null || true) | 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")
|
||||
|
||||
**Step 3: Build internal `<prior_decisions>` context**
|
||||
|
||||
Structure the extracted information for use in assumption generation.
|
||||
|
||||
**If no prior context exists:** Continue without - expected for early phases.
|
||||
</step>
|
||||
|
||||
<step name="cross_reference_todos">
|
||||
Check if any pending todos are relevant to this phase's scope.
|
||||
|
||||
```bash
|
||||
TODO_MATCHES=$(pi-gsd-tools todo match-phase "${PHASE_NUMBER}")
|
||||
```
|
||||
|
||||
Parse JSON for: `todo_count`, `matches[]`.
|
||||
|
||||
**If `todo_count` is 0:** Skip silently.
|
||||
|
||||
**If matches found:** Present matched todos, use AskUserQuestion (multiSelect) to fold relevant ones into scope.
|
||||
|
||||
**For selected (folded) todos:** Store as `<folded_todos>` for CONTEXT.md `<decisions>` section.
|
||||
**For unselected:** Store as `<reviewed_todos>` for CONTEXT.md `<deferred>` section.
|
||||
|
||||
**Auto mode (`--auto`):** Fold all todos with score >= 0.4 automatically. Log the selection.
|
||||
</step>
|
||||
|
||||
<step name="scout_codebase">
|
||||
Lightweight scan of existing code to inform assumption generation.
|
||||
|
||||
**Step 1: Check for existing codebase maps**
|
||||
```bash
|
||||
ls .planning/codebase/*.md 2>/dev/null || true
|
||||
```
|
||||
|
||||
**If codebase maps exist:** Read relevant ones (CONVENTIONS.md, STRUCTURE.md, STACK.md). Extract reusable components, patterns, integration points. Skip to Step 3.
|
||||
|
||||
**Step 2: If no codebase maps, do targeted grep**
|
||||
|
||||
Extract key terms from phase goal, search for related files.
|
||||
|
||||
```bash
|
||||
grep -rl "{term1}\|{term2}" src/ app/ --include="*.ts" --include="*.tsx" 2>/dev/null | head -10
|
||||
```
|
||||
|
||||
Read the 3-5 most relevant files.
|
||||
|
||||
**Step 3: Build internal `<codebase_context>`**
|
||||
|
||||
Identify reusable assets, established patterns, integration points, and creative options. Store internally for use in deep_codebase_analysis.
|
||||
</step>
|
||||
|
||||
<step name="deep_codebase_analysis">
|
||||
Spawn a `gsd-assumptions-analyzer` agent to deeply analyze the codebase for this phase. This
|
||||
keeps raw file contents out of the main context window, protecting token budget.
|
||||
|
||||
**Resolve calibration tier (if USER-PROFILE.md exists):**
|
||||
|
||||
```bash
|
||||
PROFILE_PATH=".pi/gsd/USER-PROFILE.md"
|
||||
```
|
||||
|
||||
If file exists at PROFILE_PATH:
|
||||
- Priority 1: Read config.json > preferences.vendor_philosophy (project-level override)
|
||||
- Priority 2: Read USER-PROFILE.md Vendor Choices/Philosophy rating (global)
|
||||
- Priority 3: Default to "standard"
|
||||
|
||||
Map to calibration tier:
|
||||
- conservative OR thorough-evaluator → full_maturity (more alternatives, detailed evidence)
|
||||
- opinionated → minimal_decisive (fewer alternatives, decisive recommendations)
|
||||
- pragmatic-fast OR any other value → standard
|
||||
|
||||
If no USER-PROFILE.md: calibration_tier = "standard"
|
||||
|
||||
**Spawn Explore subagent:**
|
||||
|
||||
```
|
||||
Task(subagent_type="gsd-assumptions-analyzer", prompt="""
|
||||
Analyze the codebase for Phase {PHASE}: {phase_name}.
|
||||
|
||||
Phase goal: {roadmap_description}
|
||||
Prior decisions: {prior_decisions_summary}
|
||||
Codebase scout hints: {codebase_context_summary}
|
||||
Calibration: {calibration_tier}
|
||||
|
||||
Your job:
|
||||
1. Read ROADMAP.md phase {PHASE} description
|
||||
2. Read any prior CONTEXT.md files from earlier phases
|
||||
3. Glob/Grep for files related to: {phase_relevant_terms}
|
||||
4. Read 5-15 most relevant source files
|
||||
5. Return structured assumptions
|
||||
|
||||
## Output Format
|
||||
|
||||
Return EXACTLY this structure:
|
||||
|
||||
## Assumptions
|
||||
|
||||
### [Area Name] (e.g., "Technical Approach")
|
||||
- **Assumption:** [Decision statement]
|
||||
- **Why this way:** [Evidence from codebase - cite file paths]
|
||||
- **If wrong:** [Concrete consequence of this being wrong]
|
||||
- **Confidence:** Confident | Likely | Unclear
|
||||
|
||||
(3-5 areas, calibrated by tier:
|
||||
- full_maturity: 3-5 areas, 2-3 alternatives per Likely/Unclear item
|
||||
- standard: 3-4 areas, 2 alternatives per Likely/Unclear item
|
||||
- minimal_decisive: 2-3 areas, decisive single recommendation per item)
|
||||
|
||||
## Needs External Research
|
||||
[Topics where codebase alone is insufficient - library version compatibility,
|
||||
ecosystem best practices, etc. Leave empty if codebase provides enough evidence.]
|
||||
|
||||
${AGENT_SKILLS_ANALYZER}
|
||||
""")
|
||||
```
|
||||
|
||||
Parse the subagent's response. Extract:
|
||||
- `assumptions[]` - each with area, statement, evidence, consequence, confidence
|
||||
- `needs_research[]` - topics requiring external research (may be empty)
|
||||
|
||||
**Initialize canonical refs accumulator:**
|
||||
- Source 1: Copy `Canonical refs:` from ROADMAP.md for this phase, expand to full paths
|
||||
- Source 2: Check REQUIREMENTS.md and PROJECT.md for specs/ADRs referenced
|
||||
- Source 3: Add any docs referenced in codebase scout results
|
||||
</step>
|
||||
|
||||
<step name="external_research">
|
||||
**Skip if:** `needs_research` from deep_codebase_analysis is empty.
|
||||
|
||||
If research topics were flagged, spawn a general-purpose research agent:
|
||||
|
||||
```
|
||||
Task(subagent_type="general-purpose", prompt="""
|
||||
Research the following topics for Phase {PHASE}: {phase_name}.
|
||||
|
||||
Topics needing research:
|
||||
{needs_research_content}
|
||||
|
||||
For each topic, return:
|
||||
- **Finding:** [What you learned]
|
||||
- **Source:** [URL or library docs reference]
|
||||
- **Confidence impact:** [Which assumption this resolves and to what confidence level]
|
||||
|
||||
Use Context7 (resolve-library-id then query-docs) for library-specific questions.
|
||||
Use WebSearch for ecosystem/best-practice questions.
|
||||
""")
|
||||
```
|
||||
|
||||
Merge findings back into assumptions:
|
||||
- Update confidence levels where research resolves ambiguity
|
||||
- Add source attribution to affected assumptions
|
||||
- Store research findings for DISCUSSION-LOG.md
|
||||
|
||||
**If no gaps flagged:** Skip entirely. Most phases will skip this step.
|
||||
</step>
|
||||
|
||||
<step name="present_assumptions">
|
||||
Display all assumptions grouped by area with confidence badges.
|
||||
|
||||
**Format for display:**
|
||||
|
||||
```
|
||||
## Phase {PHASE}: {phase_name} - Assumptions
|
||||
|
||||
Based on codebase analysis, here's what I'd go with:
|
||||
|
||||
### {Area Name}
|
||||
{Confidence badge} **{Assumption statement}**
|
||||
↳ Evidence: {file paths cited}
|
||||
↳ If wrong: {consequence}
|
||||
|
||||
### {Area Name 2}
|
||||
...
|
||||
|
||||
[If external research was done:]
|
||||
### External Research Applied
|
||||
- {Topic}: {Finding} (Source: {URL})
|
||||
```
|
||||
|
||||
**If `--auto`:**
|
||||
- If all assumptions are Confident or Likely: log assumptions, skip to write_context.
|
||||
Log: `[auto] All assumptions Confident/Likely - proceeding to context capture.`
|
||||
- If any assumptions are Unclear: log a warning, auto-select recommended alternative for
|
||||
each Unclear item. Log: `[auto] {N} Unclear assumptions auto-resolved with recommended defaults.`
|
||||
Proceed to write_context.
|
||||
|
||||
**Otherwise:** Use AskUserQuestion:
|
||||
- header: "Assumptions"
|
||||
- question: "These all look right?"
|
||||
- options:
|
||||
- "Yes, proceed" - Write CONTEXT.md with these assumptions as decisions
|
||||
- "Let me correct some" - Select which assumptions to change
|
||||
|
||||
**If "Yes, proceed":** Skip to write_context.
|
||||
**If "Let me correct some":** Continue to correct_assumptions.
|
||||
</step>
|
||||
|
||||
<step name="correct_assumptions">
|
||||
The assumptions are already displayed above from present_assumptions.
|
||||
|
||||
Present a multiSelect where each option's label is the assumption statement and description
|
||||
is the "If wrong" consequence:
|
||||
|
||||
Use AskUserQuestion (multiSelect):
|
||||
- header: "Corrections"
|
||||
- question: "Which assumptions need correcting?"
|
||||
- options: [one per assumption, label = assumption statement, description = "If wrong: {consequence}"]
|
||||
|
||||
For each selected correction, ask ONE focused question:
|
||||
|
||||
Use AskUserQuestion:
|
||||
- header: "{Area Name}"
|
||||
- question: "What should we do instead for: {assumption statement}?"
|
||||
- options: [2-3 concrete alternatives describing user-visible outcomes, recommended option first]
|
||||
|
||||
Record each correction:
|
||||
- Original assumption
|
||||
- User's chosen alternative
|
||||
- Reason (if provided via "Other" free text)
|
||||
|
||||
After all corrections processed, continue to write_context with updated assumptions.
|
||||
|
||||
**Auto mode:** Should not reach this step (--auto skips from present_assumptions).
|
||||
</step>
|
||||
|
||||
<step name="write_context">
|
||||
Create phase directory if needed. Write CONTEXT.md using the standard 6-section format.
|
||||
|
||||
**File:** `${phase_dir}/${padded_phase}-CONTEXT.md`
|
||||
|
||||
Map assumptions to CONTEXT.md sections:
|
||||
- Assumptions → `<decisions>` (each assumption becomes a locked decision: D-01, D-02, etc.)
|
||||
- Corrections → override the original assumption in `<decisions>`
|
||||
- Areas where all assumptions were Confident → marked as locked decisions
|
||||
- Areas with corrections → include user's chosen alternative as the decision
|
||||
- Folded todos → included in `<decisions>` under "### Folded Todos"
|
||||
|
||||
```markdown
|
||||
# Phase {PHASE}: {phase_name} - Context
|
||||
|
||||
**Gathered:** {date} (assumptions mode)
|
||||
**Status:** Ready for planning
|
||||
|
||||
<domain>
|
||||
## Phase Boundary
|
||||
|
||||
{Domain boundary from ROADMAP.md - clear statement of scope anchor}
|
||||
</domain>
|
||||
|
||||
<decisions>
|
||||
## Implementation Decisions
|
||||
|
||||
### {Area Name 1}
|
||||
- **D-01:** {Decision - from assumption or correction}
|
||||
- **D-02:** {Decision}
|
||||
|
||||
### {Area Name 2}
|
||||
- **D-03:** {Decision}
|
||||
|
||||
### the agent's Discretion
|
||||
{Any assumptions where the user confirmed "you decide" or left as-is with Likely confidence}
|
||||
|
||||
### Folded Todos
|
||||
{If any todos were folded into scope}
|
||||
</decisions>
|
||||
|
||||
<canonical_refs>
|
||||
## Canonical References
|
||||
|
||||
**Downstream agents MUST read these before planning or implementing.**
|
||||
|
||||
{Accumulated canonical refs from analyze step - full relative paths}
|
||||
|
||||
[If no external specs: "No external specs - requirements fully captured in decisions above"]
|
||||
</canonical_refs>
|
||||
|
||||
<code_context>
|
||||
## Existing Code Insights
|
||||
|
||||
### Reusable Assets
|
||||
{From codebase scout + Explore subagent findings}
|
||||
|
||||
### Established Patterns
|
||||
{Patterns that constrain/enable this phase}
|
||||
|
||||
### Integration Points
|
||||
{Where new code connects to existing system}
|
||||
</code_context>
|
||||
|
||||
<specifics>
|
||||
## Specific Ideas
|
||||
|
||||
{Any particular references from corrections or user input}
|
||||
|
||||
[If none: "No specific requirements - open to standard approaches"]
|
||||
</specifics>
|
||||
|
||||
<deferred>
|
||||
## Deferred Ideas
|
||||
|
||||
{Ideas mentioned during corrections that are out of scope}
|
||||
|
||||
### Reviewed Todos (not folded)
|
||||
{Todos reviewed but not folded - with reason}
|
||||
|
||||
[If none: "None - analysis stayed within phase scope"]
|
||||
</deferred>
|
||||
```
|
||||
|
||||
Write file.
|
||||
</step>
|
||||
|
||||
<step name="write_discussion_log">
|
||||
Write audit trail of assumptions and corrections.
|
||||
|
||||
**File:** `${phase_dir}/${padded_phase}-DISCUSSION-LOG.md`
|
||||
|
||||
```markdown
|
||||
# Phase {PHASE}: {phase_name} - Discussion Log (Assumptions Mode)
|
||||
|
||||
> **Audit trail only.** Do not use as input to planning, research, or execution agents.
|
||||
> Decisions captured in CONTEXT.md - this log preserves the analysis.
|
||||
|
||||
**Date:** {ISO date}
|
||||
**Phase:** {padded_phase}-{phase_name}
|
||||
**Mode:** assumptions
|
||||
**Areas analyzed:** {comma-separated area names}
|
||||
|
||||
## Assumptions Presented
|
||||
|
||||
### {Area Name}
|
||||
| Assumption | Confidence | Evidence |
|
||||
| ----------- | -------------------------- | ------------ |
|
||||
| {Statement} | {Confident/Likely/Unclear} | {file paths} |
|
||||
|
||||
{Repeat for each area}
|
||||
|
||||
## Corrections Made
|
||||
|
||||
{If corrections were made:}
|
||||
|
||||
### {Area Name}
|
||||
- **Original assumption:** {what the agent assumed}
|
||||
- **User correction:** {what the user chose instead}
|
||||
- **Reason:** {user's rationale, if provided}
|
||||
|
||||
{If no corrections: "No corrections - all assumptions confirmed."}
|
||||
|
||||
## Auto-Resolved
|
||||
|
||||
{If --auto and Unclear items existed:}
|
||||
- {Assumption}: auto-selected {recommended option}
|
||||
|
||||
{If not applicable: omit this section}
|
||||
|
||||
## External Research
|
||||
|
||||
{If research was performed:}
|
||||
- {Topic}: {Finding} (Source: {URL})
|
||||
|
||||
{If no research: omit this section}
|
||||
```
|
||||
|
||||
Write file.
|
||||
</step>
|
||||
|
||||
<step name="git_commit">
|
||||
Commit phase context and discussion log:
|
||||
|
||||
```bash
|
||||
pi-gsd-tools commit "docs(${padded_phase}): capture phase context (assumptions mode)" --files "${phase_dir}/${padded_phase}-CONTEXT.md" "${phase_dir}/${padded_phase}-DISCUSSION-LOG.md"
|
||||
```
|
||||
|
||||
Confirm: "Committed: docs(${padded_phase}): capture phase context (assumptions mode)"
|
||||
</step>
|
||||
|
||||
<step name="update_state">
|
||||
Update STATE.md with session info:
|
||||
|
||||
```bash
|
||||
pi-gsd-tools state record-session \
|
||||
--stopped-at "Phase ${PHASE} context gathered (assumptions mode)" \
|
||||
--resume-file "${phase_dir}/${padded_phase}-CONTEXT.md"
|
||||
```
|
||||
|
||||
Commit STATE.md:
|
||||
|
||||
```bash
|
||||
pi-gsd-tools commit "docs(state): record phase ${PHASE} context session" --files .planning/STATE.md
|
||||
```
|
||||
</step>
|
||||
|
||||
<step name="confirm_creation">
|
||||
Present summary and next steps:
|
||||
|
||||
```
|
||||
Created: .planning/phases/${PADDED_PHASE}-${SLUG}/${PADDED_PHASE}-CONTEXT.md
|
||||
|
||||
## Decisions Captured (Assumptions Mode)
|
||||
|
||||
### {Area Name}
|
||||
- {Key decision} (from assumption / corrected)
|
||||
|
||||
{Repeat per area}
|
||||
|
||||
[If corrections were made:]
|
||||
## Corrections Applied
|
||||
- {Area}: {original} → {corrected}
|
||||
|
||||
[If deferred ideas exist:]
|
||||
## Noted for Later
|
||||
- {Deferred idea} - future phase
|
||||
|
||||
---
|
||||
|
||||
## ▶ Next Up
|
||||
|
||||
**Phase ${PHASE}: {phase_name}** - {Goal from ROADMAP.md}
|
||||
|
||||
`/gsd-plan-phase ${PHASE}`
|
||||
|
||||
<sub>`/new` first → fresh context window</sub>
|
||||
|
||||
---
|
||||
|
||||
**Also available:**
|
||||
- `/gsd-plan-phase ${PHASE} --skip-research` - plan without research
|
||||
- `/gsd-ui-phase ${PHASE}` - generate UI design contract (if frontend work)
|
||||
- Review/edit CONTEXT.md before continuing
|
||||
|
||||
---
|
||||
```
|
||||
</step>
|
||||
|
||||
<step name="auto_advance">
|
||||
Check for auto-advance trigger:
|
||||
|
||||
1. Parse `--auto` flag from $ARGUMENTS
|
||||
2. Sync chain flag:
|
||||
```bash
|
||||
if [[ ! "$ARGUMENTS" =~ --auto ]]; then
|
||||
pi-gsd-tools config-set workflow._auto_chain_active false 2>/dev/null
|
||||
fi
|
||||
```
|
||||
3. Read chain flag and user preference:
|
||||
```bash
|
||||
AUTO_CHAIN=$(pi-gsd-tools config-get workflow._auto_chain_active 2>/dev/null || echo "false")
|
||||
AUTO_CFG=$(pi-gsd-tools config-get workflow.auto_advance 2>/dev/null || echo "false")
|
||||
```
|
||||
|
||||
**If `--auto` flag present AND `AUTO_CHAIN` is not true:**
|
||||
```bash
|
||||
pi-gsd-tools 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 (assumptions mode). Launching plan-phase...
|
||||
```
|
||||
|
||||
Launch: `Skill(skill="gsd-plan-phase", args="${PHASE} --auto")`
|
||||
|
||||
Handle return: PHASE COMPLETE / PLANNING COMPLETE / INCONCLUSIVE / GAPS FOUND
|
||||
(identical handling to discuss-phase.md auto_advance step)
|
||||
|
||||
**If neither `--auto` nor config enabled:**
|
||||
Route to confirm_creation step.
|
||||
</step>
|
||||
|
||||
</process>
|
||||
|
||||
<success_criteria>
|
||||
- Phase validated against roadmap
|
||||
- Prior context loaded (no re-asking decided questions)
|
||||
- Codebase deeply analyzed via Explore subagent (5-15 files read)
|
||||
- Assumptions surfaced with evidence and confidence levels
|
||||
- User confirmed or corrected assumptions (~2-4 interactions max)
|
||||
- Scope creep redirected to deferred ideas
|
||||
- CONTEXT.md captures actual decisions (identical format to discuss mode)
|
||||
- CONTEXT.md includes canonical_refs with full file paths (MANDATORY)
|
||||
- CONTEXT.md includes code_context from codebase analysis
|
||||
- DISCUSSION-LOG.md records assumptions and corrections as audit trail
|
||||
- STATE.md updated with session info
|
||||
- User knows next steps
|
||||
</success_criteria>
|
||||
1087
.pi/gsd/workflows/discuss-phase.md
Normal file
1087
.pi/gsd/workflows/discuss-phase.md
Normal file
File diff suppressed because it is too large
Load Diff
141
.pi/gsd/workflows/do.md
Normal file
141
.pi/gsd/workflows/do.md
Normal file
@@ -0,0 +1,141 @@
|
||||
<gsd-version v="1.12.4" />
|
||||
|
||||
<gsd-arguments>
|
||||
<settings><keep-extra-args /></settings>
|
||||
<arg name="request" type="string" optional />
|
||||
</gsd-arguments>
|
||||
|
||||
<gsd-execute>
|
||||
<shell command="pi-gsd-tools">
|
||||
<args>
|
||||
<arg string="state" />
|
||||
<arg string="reconcile" />
|
||||
<arg string="--raw" />
|
||||
</args>
|
||||
<outs>
|
||||
<suppress-errors />
|
||||
<out type="string" name="reconcile-result" />
|
||||
</outs>
|
||||
</shell>
|
||||
<shell command="pi-gsd-tools">
|
||||
<args>
|
||||
<arg string="state" />
|
||||
<arg string="load" />
|
||||
<arg string="--raw" />
|
||||
</args>
|
||||
<outs>
|
||||
<suppress-errors />
|
||||
<out type="string" name="state" />
|
||||
</outs>
|
||||
</shell>
|
||||
</gsd-execute>
|
||||
|
||||
## Context (pre-injected)
|
||||
|
||||
**Request:** <gsd-paste name="request" />
|
||||
|
||||
**State:**
|
||||
<gsd-paste name="state" />
|
||||
|
||||
<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.**
|
||||
|
||||
<!-- Context pre-injected above via WXP - variables available via <gsd-paste name="..."> -->
|
||||
|
||||
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>
|
||||
426
.pi/gsd/workflows/execute-milestone.md
Normal file
426
.pi/gsd/workflows/execute-milestone.md
Normal file
@@ -0,0 +1,426 @@
|
||||
<gsd-version v="1.12.4" />
|
||||
|
||||
<gsd-arguments>
|
||||
<settings><keep-extra-args /></settings>
|
||||
<arg name="from" type="number" optional />
|
||||
<arg name="uat-threshold" type="number" optional />
|
||||
</gsd-arguments>
|
||||
|
||||
<gsd-execute>
|
||||
<shell command="pi-gsd-tools">
|
||||
<args>
|
||||
<arg string="roadmap" />
|
||||
<arg string="analyze" />
|
||||
<arg string="--raw" />
|
||||
</args>
|
||||
<outs>
|
||||
<out type="string" name="roadmap" />
|
||||
</outs>
|
||||
</shell>
|
||||
<shell command="pi-gsd-tools">
|
||||
<args>
|
||||
<arg string="state" />
|
||||
<arg string="json" />
|
||||
<arg string="--raw" />
|
||||
</args>
|
||||
<outs>
|
||||
<out type="string" name="state" />
|
||||
</outs>
|
||||
</shell>
|
||||
<shell command="pi-gsd-tools">
|
||||
<args>
|
||||
<arg string="progress" />
|
||||
<arg string="json" />
|
||||
<arg string="--raw" />
|
||||
</args>
|
||||
<outs>
|
||||
<out type="string" name="progress" />
|
||||
</outs>
|
||||
</shell>
|
||||
<!-- SET _auto_chain_active when milestone execution chain starts -->
|
||||
<shell command="pi-gsd-tools">
|
||||
<args>
|
||||
<arg string="config-set" />
|
||||
<arg string="workflow._auto_chain_active" />
|
||||
<arg string="true" />
|
||||
</args>
|
||||
<outs><suppress-errors /></outs>
|
||||
</shell>
|
||||
</gsd-execute>
|
||||
|
||||
## Execution Context (pre-injected)
|
||||
|
||||
**Roadmap:**
|
||||
<gsd-paste name="roadmap" />
|
||||
|
||||
**State:**
|
||||
<gsd-paste name="state" />
|
||||
|
||||
**Progress:**
|
||||
<gsd-paste name="progress" />
|
||||
|
||||
# execute-milestone workflow
|
||||
|
||||
Execute all planned phases in the current milestone with scope guardian, UAT gates, and configurable recovery.
|
||||
|
||||
---
|
||||
|
||||
## Worktree Check (always first)
|
||||
|
||||
```bash
|
||||
git worktree list
|
||||
```
|
||||
|
||||
If not in an isolated worktree:
|
||||
> "Large-scale milestone execution should run in an isolated worktree to protect your main branch. Create one now? (y/n, default: y)"
|
||||
|
||||
If yes: `Skill(skill="gsd-new-workspace", args="milestone-exec")`, then continue in the new worktree.
|
||||
If no: warn once, proceed on current branch.
|
||||
|
||||
---
|
||||
|
||||
## Mode Selection (step 1 - always second)
|
||||
|
||||
Ask the user ONE binary question:
|
||||
|
||||
> **"How should I behave when I hit a doubt, error, or scope deviation?"**
|
||||
>
|
||||
> - **Interactive** - Stop and ask me; I'll guide you through it
|
||||
> - **Silent** - Try to self-correct; only surface unrecoverable blockers
|
||||
|
||||
Store as `MODE` (interactive | silent). Do not ask again.
|
||||
|
||||
---
|
||||
|
||||
## Phase Discovery
|
||||
|
||||
```bash
|
||||
pi-gsd-tools roadmap analyze --raw
|
||||
pi-gsd-tools progress json --raw
|
||||
```
|
||||
|
||||
Build execution queue: phases with ≥1 PLAN.md and status ≠ Complete, in roadmap order.
|
||||
|
||||
If queue is empty: "All phases are already complete. Run /gsd-audit-milestone." Stop.
|
||||
|
||||
---
|
||||
|
||||
## Per-Phase Execution Loop
|
||||
|
||||
For each pending phase `N`:
|
||||
|
||||
### A. Scope Pre-check (lightweight, one LLM call)
|
||||
|
||||
Read:
|
||||
- `.planning/REQUIREMENTS.md`
|
||||
- Phase goal + success criteria from ROADMAP.md
|
||||
|
||||
Prompt (internal): *"Does executing this phase risk implementing anything not covered by active requirements, or conflict with what previous phases delivered? Rate: low / medium / high. One sentence reason."*
|
||||
|
||||
- **low** - continue silently
|
||||
- **medium** - log in scope-log, continue
|
||||
- **high + interactive** - surface to user, ask: proceed / adjust phase goal / stop
|
||||
- **high + silent** - log prominently, continue, include in final report
|
||||
|
||||
### B. Execute Phase
|
||||
|
||||
```
|
||||
Skill(skill="gsd-execute-phase", args="${N}")
|
||||
```
|
||||
|
||||
### C. Scope Post-audit (full, one LLM call)
|
||||
|
||||
Read new SUMMARY.md files from the phase directory.
|
||||
|
||||
Check:
|
||||
1. **Undelivered must-haves** - PLAN.md `must_haves` entries absent from SUMMARY
|
||||
2. **Scope creep** - files modified that are outside this phase's stated scope
|
||||
3. **Requirement drift** - work done that has no matching REQUIREMENTS entry
|
||||
|
||||
Classify result as `SCOPE_STATUS`:
|
||||
- **clean** - continue
|
||||
- **drift** - log + warn, continue
|
||||
- **violation** - trigger recovery (see §F)
|
||||
|
||||
### D. Verify
|
||||
|
||||
```
|
||||
Skill(skill="gsd-verify-work", args="${N}")
|
||||
```
|
||||
|
||||
Compute UAT pass rate = passing items / total items.
|
||||
Default threshold: **80%**. Override with `--uat-threshold N`.
|
||||
|
||||
### E. Gate Check
|
||||
|
||||
| Condition | Interactive | Silent |
|
||||
| ------------------------- | ------------------------------ | ---------------------- |
|
||||
| UAT pass rate < threshold | Ask: fix gaps now or continue? | → Recovery loop |
|
||||
| Context remaining < 20% | Warn, ask: stop or continue? | → Write HANDOFF, stop |
|
||||
| SCOPE_STATUS = violation | Surface details, ask | → Recovery loop |
|
||||
| All gates pass | Continue to checkpoint | Continue to checkpoint |
|
||||
|
||||
### F. Recovery Loop
|
||||
|
||||
When triggered:
|
||||
|
||||
```
|
||||
1. pi-gsd-tools validate health --repair
|
||||
2. Self-correct: identify root cause, patch, re-run verification
|
||||
3. Re-check gates
|
||||
4. Gates pass → continue to checkpoint
|
||||
5. Still failing:
|
||||
- Interactive: explain issue, ask user how to resolve, loop from step 2
|
||||
- Silent: write HANDOFF files (see §G), stop
|
||||
```
|
||||
|
||||
### G. Hard Stop - HANDOFF Files
|
||||
|
||||
On unrecoverable stop, write two files matching original GSD pause-work convention:
|
||||
|
||||
**`.planning/HANDOFF.json`** (machine-readable, consumed by `/gsd-resume-work`):
|
||||
```json
|
||||
{
|
||||
"stopped_at": "ISO-timestamp",
|
||||
"phase": "N",
|
||||
"phase_name": "phase name",
|
||||
"stop_reason": "uat_failure | scope_violation | context_exhausted | unrecoverable_error | audit_exhausted | audit_no_result",
|
||||
"outer_cycles": 0,
|
||||
"gaps_store": [],
|
||||
"debt_store": [],
|
||||
"gaps_phases_tried": [],
|
||||
"debt_phases_tried": [],
|
||||
"uat_pass_rate": 75,
|
||||
"scope_status": "violation",
|
||||
"phases_completed": ["1", "2", "3"],
|
||||
"phases_remaining": ["N", "N+1"],
|
||||
"scope_log": ["note 1", "note 2"],
|
||||
"next_action": "Run /gsd-execute-milestone --from N to resume"
|
||||
}
|
||||
```
|
||||
|
||||
**`.planning/phases/NN-name/.continue-here.md`** (human-readable):
|
||||
```markdown
|
||||
---
|
||||
phase: N
|
||||
status: stopped
|
||||
stop_reason: [reason]
|
||||
last_updated: [timestamp]
|
||||
---
|
||||
|
||||
## What happened
|
||||
[Clear explanation of why execution stopped]
|
||||
|
||||
## State at stop
|
||||
- UAT pass rate: X%
|
||||
- Scope status: [clean/drift/violation]
|
||||
- Scope notes: [any flags]
|
||||
|
||||
## How to resume
|
||||
Run: /gsd-execute-milestone --from N
|
||||
Or fix the specific issue first: [specific suggestion]
|
||||
```
|
||||
|
||||
### H. Checkpoint (on success)
|
||||
|
||||
```bash
|
||||
pi-gsd-tools state update current_phase ${N}
|
||||
pi-gsd-tools state update last_activity $(date -u +%Y-%m-%d)
|
||||
pi-gsd-tools commit "chore: complete phase ${N}" --files .planning/
|
||||
```
|
||||
|
||||
Announce: `✓ Phase ${N} complete - UAT: ${pass_rate}% Scope: ${scope_status}`
|
||||
|
||||
---
|
||||
|
||||
## After All Phases - Mode Split
|
||||
|
||||
### Interactive mode
|
||||
|
||||
Do NOT auto-invoke the lifecycle. Surface the execution summary and hand back:
|
||||
|
||||
```
|
||||
━━ execute-milestone: all phases done ━━━━━━━━━━━━
|
||||
✓ Phases: ${done}/${total} complete
|
||||
📊 Avg UAT: ${avg_uat}%
|
||||
⚠ Scope: ${scope_flag_count} flag(s) (details above)
|
||||
|
||||
Next: /gsd-audit-milestone when you are ready to review
|
||||
and close the milestone.
|
||||
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
|
||||
```
|
||||
|
||||
Stop. The user owns the audit decision.
|
||||
|
||||
---
|
||||
|
||||
### Silent mode - Auto Lifecycle
|
||||
|
||||
Only in silent mode. Display transition banner:
|
||||
```
|
||||
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
|
||||
All phases complete → lifecycle: audit → complete → cleanup
|
||||
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
|
||||
```
|
||||
|
||||
Read config once:
|
||||
- `config.workflow.auto_retry_audit` (default: `true`)
|
||||
- `config.workflow.auto_retry_audit_budget` (default: `1`)
|
||||
- `config.workflow.auto_retry_tech_debt` (default: `true`)
|
||||
- `config.workflow.auto_retry_tech_debt_budget` (default: `1`)
|
||||
|
||||
Initialise accumulators (persist across the outer loop):
|
||||
- `gaps_store = []` - unsatisfied requirements not yet resolved
|
||||
- `debt_store = []` - tech debt items not yet resolved
|
||||
- `gaps_phases_tried = []` - inserted phases attempted for gap closure
|
||||
- `debt_phases_tried = []` - inserted phases attempted for debt resolution
|
||||
- `outer_cycles = 0`
|
||||
|
||||
---
|
||||
|
||||
#### OUTER LOOP - Full audit cycle
|
||||
|
||||
`LABEL: outer_loop`
|
||||
|
||||
**Step A - Full audit**
|
||||
|
||||
```
|
||||
Skill(skill="gsd-audit-milestone")
|
||||
```
|
||||
|
||||
If no result / malformed → Write HANDOFF (§G), stop.
|
||||
|
||||
Extract from audit result:
|
||||
- `current_gaps[]` - unsatisfied requirement IDs + affected phase numbers
|
||||
- `current_debt[]` - tech debt items + affected phase numbers
|
||||
|
||||
If both empty → AUDIT PASSED. Proceed to Step D (complete).
|
||||
|
||||
---
|
||||
|
||||
**Step B - Gap closure loop** (only if `current_gaps` non-empty)
|
||||
|
||||
If `auto_retry_audit = false`: add `current_gaps` to `gaps_store`, skip to Step C.
|
||||
|
||||
While `current_gaps` non-empty and `auto_retry_audit_budget > 0`:
|
||||
|
||||
```
|
||||
1. Decrement auto_retry_audit_budget
|
||||
2. Insert a gap-closure phase (decimal after last phase):
|
||||
Skill(skill="gsd-insert-phase", args="${last_phase}.${gap_cycle} 'Gap closure: ${gap_summary}'")
|
||||
3. Plan it with gap context:
|
||||
Skill(skill="gsd-plan-phase", args="${new_phase} --auto")
|
||||
(Pass unsatisfied requirement details as planning context)
|
||||
4. Execute it:
|
||||
Skill(skill="gsd-execute-phase", args="${new_phase}")
|
||||
5. Track: append new_phase to gaps_phases_tried
|
||||
6. Targeted re-audit - affected phases only:
|
||||
Skill(skill="gsd-audit-milestone", args="--phases ${gap_affected_phases}")
|
||||
7. Re-read current_gaps from result
|
||||
- Resolved? current_gaps = [], break loop
|
||||
- Reduced? loop again if budget > 0
|
||||
- Same/worse? loop again if budget > 0
|
||||
```
|
||||
|
||||
After loop:
|
||||
- If `current_gaps` empty → gaps resolved ✅, `gaps_store = []`
|
||||
- If still non-empty → `gaps_store = current_gaps` (budget exhausted or disabled)
|
||||
|
||||
---
|
||||
|
||||
**Step C - Tech debt loop** (only if `current_debt` non-empty)
|
||||
|
||||
If `auto_retry_tech_debt = false`: add `current_debt` to `debt_store`, skip to final gate.
|
||||
|
||||
While `current_debt` non-empty and `auto_retry_tech_debt_budget > 0`:
|
||||
|
||||
```
|
||||
1. Decrement auto_retry_tech_debt_budget
|
||||
2. Insert a debt-resolution phase (decimal after last phase):
|
||||
Skill(skill="gsd-insert-phase", args="${last_phase}.${debt_cycle} 'Tech debt: ${debt_summary}'")
|
||||
3. Plan it with debt context:
|
||||
Skill(skill="gsd-plan-phase", args="${new_phase} --auto")
|
||||
(Pass tech debt item details as planning context)
|
||||
4. Execute it:
|
||||
Skill(skill="gsd-execute-phase", args="${new_phase}")
|
||||
5. Track: append new_phase to debt_phases_tried
|
||||
6. Targeted re-audit - affected phases only:
|
||||
Skill(skill="gsd-audit-milestone", args="--phases ${debt_affected_phases}")
|
||||
7. Re-read current_debt from result
|
||||
- Resolved? current_debt = [], break loop
|
||||
- Reduced? loop again if budget > 0
|
||||
- gaps_found in re-audit? add to gaps_store, break (handled in next outer cycle)
|
||||
```
|
||||
|
||||
After loop:
|
||||
- If `current_debt` empty → debt resolved ✅, `debt_store = []`
|
||||
- If still non-empty → `debt_store = current_debt`
|
||||
|
||||
---
|
||||
|
||||
**Final gate (end of outer loop body)**
|
||||
|
||||
If `gaps_store` empty AND `debt_store` empty:
|
||||
→ AUDIT CLEAN. Proceed to Step D.
|
||||
|
||||
If anything remains in stores:
|
||||
- Increment `outer_cycles`
|
||||
- If outer budget remaining (derived from max of both budgets > 0):
|
||||
→ `GOTO outer_loop` (re-run full audit from top, fresh eyes)
|
||||
- If exhausted:
|
||||
→ Write enriched HANDOFF (§G), stop.
|
||||
|
||||
---
|
||||
|
||||
#### Step D - Complete Milestone
|
||||
|
||||
```
|
||||
Skill(skill="gsd-complete-milestone", args="${milestone_version}")
|
||||
```
|
||||
|
||||
Verify archive produced:
|
||||
```bash
|
||||
ls .planning/milestones/v${milestone_version}-ROADMAP.md 2>/dev/null || true
|
||||
```
|
||||
If absent → Write HANDOFF, stop. Message: "complete-milestone did not produce archive files."
|
||||
|
||||
#### Step E - Cleanup
|
||||
|
||||
```
|
||||
Skill(skill="gsd-cleanup")
|
||||
```
|
||||
|
||||
Cleanup handles its own dry-run and confirmation internally.
|
||||
|
||||
---
|
||||
|
||||
## Worktree Merge (both modes, after lifecycle or summary)
|
||||
|
||||
If running in an isolated worktree, ask:
|
||||
> "Merge this worktree back to your main branch? (y/n, default: y)"
|
||||
|
||||
If yes:
|
||||
```bash
|
||||
git checkout main
|
||||
git merge --no-ff milestone-exec -m "feat: complete milestone ${milestone_version}"
|
||||
git worktree remove milestone-exec
|
||||
```
|
||||
|
||||
If no: leave the worktree open. Tell the user how to merge manually.
|
||||
|
||||
---
|
||||
|
||||
## Final Banner (silent mode only, after full lifecycle)
|
||||
|
||||
```
|
||||
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
|
||||
GSD ► EXECUTE-MILESTONE ▸ COMPLETE 🎉
|
||||
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
|
||||
|
||||
Milestone: ${milestone_version} - ${milestone_name}
|
||||
Phases: ${done}/${total} complete
|
||||
Avg UAT: ${avg_uat}%
|
||||
Lifecycle: audit ✅ → complete ✅ → cleanup ✅
|
||||
|
||||
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
|
||||
```
|
||||
907
.pi/gsd/workflows/execute-phase.md
Normal file
907
.pi/gsd/workflows/execute-phase.md
Normal file
@@ -0,0 +1,907 @@
|
||||
<gsd-version v="1.12.4" />
|
||||
|
||||
<gsd-arguments>
|
||||
<settings>
|
||||
<keep-extra-args />
|
||||
<delimiters>
|
||||
<delimiter type="string" value="\n" />
|
||||
</delimiters>
|
||||
</settings>
|
||||
<arg name="auto-chain-active" type="flag" flag="--auto" optional />
|
||||
<arg name="no-transition" type="flag" flag="--no-transition" optional />
|
||||
<arg name="gaps-only" type="flag" flag="--gaps-only" optional />
|
||||
<arg name="interactive" type="flag" flag="--interactive" optional />
|
||||
<arg name="phase" type="number" />
|
||||
<arg name="user-text" type="string" optional />
|
||||
</gsd-arguments>
|
||||
|
||||
<gsd-execute>
|
||||
<shell command="pi-gsd-tools">
|
||||
<args>
|
||||
<arg string="init" />
|
||||
<arg string="execute-phase" />
|
||||
<arg name="phase" wrap='"' />
|
||||
</args>
|
||||
<outs>
|
||||
<out type="string" name="init" />
|
||||
</outs>
|
||||
</shell>
|
||||
<if>
|
||||
<condition>
|
||||
<starts-with>
|
||||
<left name="init" />
|
||||
<right type="string" value="@file:" />
|
||||
</starts-with>
|
||||
</condition>
|
||||
<then>
|
||||
<string-op op="split">
|
||||
<args>
|
||||
<arg name="init" />
|
||||
<arg type="string" value="@file:" />
|
||||
</args>
|
||||
<outs>
|
||||
<out type="string" name="init-file" />
|
||||
</outs>
|
||||
</string-op>
|
||||
<shell command="cat">
|
||||
<args>
|
||||
<arg name="init-file" wrap='"' />
|
||||
</args>
|
||||
<outs>
|
||||
<out type="string" name="init" />
|
||||
</outs>
|
||||
</shell>
|
||||
</then>
|
||||
</if>
|
||||
<shell command="pi-gsd-tools">
|
||||
<args>
|
||||
<arg string="agent-skills" />
|
||||
<arg string="gsd-executor" />
|
||||
</args>
|
||||
<outs>
|
||||
<suppress-errors />
|
||||
<out type="string" name="agent-skills" />
|
||||
</outs>
|
||||
</shell>
|
||||
</gsd-execute>
|
||||
|
||||
## Execution Context (pre-injected)
|
||||
|
||||
**Phase:** <gsd-paste name="phase" />
|
||||
|
||||
**Phase Init Data:**
|
||||
<gsd-paste name="init" />
|
||||
|
||||
**Agent Skills:**
|
||||
<gsd-paste name="agent-skills" />
|
||||
|
||||
---
|
||||
|
||||
<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:** Subagent spawning does not reliably return completion signals. **Default to
|
||||
sequential inline execution**: read and follow execute-plan.md directly for each plan
|
||||
instead of spawning parallel agents. Only attempt parallel spawning if the user
|
||||
explicitly requests it - and in that case, rely on the spot-check fallback in step 3
|
||||
to detect completion.
|
||||
- **Other runtimes:** If `Task`/`task` tool is unavailable, use sequential inline execution as the
|
||||
fallback. Check for tool availability at runtime rather than assuming based on runtime name.
|
||||
|
||||
**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. Never block indefinitely waiting for a signal - always verify
|
||||
via filesystem and git state.
|
||||
</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 .pi/gsd/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:
|
||||
|
||||
<!-- Init data pre-injected above via WXP: `init`, `agent-skills` variables available -->
|
||||
|
||||
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.
|
||||
|
||||
**Runtime detection for Copilot:**
|
||||
Check if the current runtime is Copilot by testing for the `@gsd-executor` agent pattern
|
||||
or absence of the `Task()` subagent API. If running under Copilot, force sequential inline
|
||||
execution regardless of the `parallelization` setting - Copilot's subagent completion
|
||||
signals are unreliable (see `<runtime_compatibility>`). Set `COPILOT_SEQUENTIAL=true`
|
||||
internally and skip the `execute_waves` step in favor of `check_interactive_mode`'s
|
||||
inline path for each plan.
|
||||
|
||||
**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:
|
||||
<!-- auto-chain-active sync handled above via WXP -->
|
||||
</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 `.pi/gsd/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
|
||||
pi-gsd-tools 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=$(pi-gsd-tools 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 `WAVE_FILTER` is set: also skip plans whose `wave` does not equal `WAVE_FILTER`.
|
||||
|
||||
**Wave safety check:** If `WAVE_FILTER` is set and there are still incomplete plans in any lower wave that match the current execution mode, STOP and tell the user to finish earlier waves first. Do not let Wave 2+ execute while prerequisite earlier-wave plans remain incomplete.
|
||||
|
||||
If all filtered: "No matching incomplete plans" → exit.
|
||||
|
||||
Report:
|
||||
```
|
||||
## Execution Plan
|
||||
|
||||
**Phase {X}: {Name}** - {total_plans} matching plans across {wave_count} wave(s)
|
||||
|
||||
{If WAVE_FILTER is set: `Wave filter active: executing only Wave {WAVE_FILTER}`.}
|
||||
|
||||
| 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 selected 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 context window.
|
||||
For 200k models, this keeps orchestrator context lean (~10-15%).
|
||||
For 1M+ models (Opus 4.6, Sonnet 4.6), richer context can be passed directly.
|
||||
|
||||
```
|
||||
Task(
|
||||
subagent_type="gsd-executor",
|
||||
model="{executor_model}",
|
||||
isolation="worktree",
|
||||
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>
|
||||
|
||||
<parallel_execution>
|
||||
You are running as a PARALLEL executor agent. Use --no-verify on all git
|
||||
commits to avoid pre-commit hook contention with other agents. The
|
||||
orchestrator validates hooks once after all agents complete.
|
||||
For gsd-tools commits: add --no-verify flag.
|
||||
For direct git commits: use git commit --no-verify -m "..."
|
||||
</parallel_execution>
|
||||
|
||||
<execution_context>
|
||||
@.pi/gsd/workflows/execute-plan.md
|
||||
@.pi/gsd/templates/summary.md
|
||||
@.pi/gsd/references/checkpoints.md
|
||||
@.pi/gsd/references/tdd.md
|
||||
</execution_context>
|
||||
|
||||
<files_to_read>
|
||||
Read these files at execution start using the Read tool:
|
||||
- {phase_dir}/{plan_file} (Plan)
|
||||
- .planning/PROJECT.md (Project context - core value, requirements, evolution rules)
|
||||
- .planning/STATE.md (State)
|
||||
- .planning/config.json (Config, if exists)
|
||||
- ./GEMINI.md (Project instructions, if exists - follow project-specific guidelines and coding conventions)
|
||||
- .agent/skills/ or .agents/skills/ (Project skills, if either exists - list skills, read SKILL.md for each, follow relevant rules during implementation)
|
||||
</files_to_read>
|
||||
|
||||
${AGENT_SKILLS}
|
||||
|
||||
<mcp_tools>
|
||||
If GEMINI.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.**
|
||||
|
||||
**Completion signal fallback (Copilot and runtimes where Task() may not return):**
|
||||
|
||||
If a spawned agent does not return a completion signal but appears to have finished
|
||||
its work, do NOT block indefinitely. Instead, verify completion via spot-checks:
|
||||
|
||||
```bash
|
||||
# For each plan in this wave, check if the executor finished:
|
||||
SUMMARY_EXISTS=$(test -f "{phase_dir}/{plan_number}-{plan_padded}-SUMMARY.md" && echo "true" || echo "false")
|
||||
COMMITS_FOUND=$(git log --oneline --all --grep="{phase_number}-{plan_padded}" --since="1 hour ago" | head -1)
|
||||
```
|
||||
|
||||
**If SUMMARY.md exists AND commits are found:** The agent completed successfully -
|
||||
treat as done and proceed to step 4. Log: `"✓ {Plan ID} completed (verified via spot-check - completion signal not received)"`
|
||||
|
||||
**If SUMMARY.md does NOT exist after a reasonable wait:** The agent may still be
|
||||
running or may have failed silently. Check `git log --oneline -5` for recent
|
||||
activity. If commits are still appearing, wait longer. If no activity, report
|
||||
the plan as failed and route to the failure handler in step 5.
|
||||
|
||||
**This fallback applies automatically to all runtimes.** Claude Code's Task() normally
|
||||
returns synchronously, but the fallback ensures resilience if it doesn't.
|
||||
|
||||
4. **Post-wave hook validation (parallel mode only):**
|
||||
|
||||
When agents committed with `--no-verify`, run pre-commit hooks once after the wave:
|
||||
```bash
|
||||
# Run project's pre-commit hooks on the current state
|
||||
git diff --cached --quiet || git stash # stash any unstaged changes
|
||||
git hook run pre-commit 2>&1 || echo "⚠ Pre-commit hooks failed - review before continuing"
|
||||
```
|
||||
If hooks fail: report the failure and ask "Fix hook issues now?" or "Continue to next wave?"
|
||||
|
||||
5. **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
|
||||
pi-gsd-tools 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=$(pi-gsd-tools config-get workflow._auto_chain_active 2>/dev/null || echo "false")
|
||||
AUTO_CFG=$(pi-gsd-tools 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="handle_partial_wave_execution">
|
||||
If `WAVE_FILTER` was used, re-run plan discovery after execution:
|
||||
|
||||
```bash
|
||||
POST_PLAN_INDEX=$(pi-gsd-tools phase-plan-index "${PHASE_NUMBER}")
|
||||
```
|
||||
|
||||
Apply the same "incomplete" filtering rules as earlier:
|
||||
- ignore plans with `has_summary: true`
|
||||
- if `--gaps-only`, only consider `gap_closure: true` plans
|
||||
|
||||
**If incomplete plans still remain anywhere in the phase:**
|
||||
- STOP here
|
||||
- Do NOT run phase verification
|
||||
- Do NOT mark the phase complete in ROADMAP/STATE
|
||||
- Present:
|
||||
|
||||
```markdown
|
||||
## Wave {WAVE_FILTER} Complete
|
||||
|
||||
Selected wave finished successfully. This phase still has incomplete plans, so phase-level verification and completion were intentionally skipped.
|
||||
|
||||
/gsd-execute-phase {phase} ${GSD_WS} # Continue remaining waves
|
||||
/gsd-execute-phase {phase} --wave {next} ${GSD_WS} # Run the next wave explicitly
|
||||
```
|
||||
|
||||
**If no incomplete plans remain after the selected wave finishes:**
|
||||
- continue with the normal phase-level verification and completion flow below
|
||||
- this means the selected wave happened to be the last remaining work in the phase
|
||||
</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=$(pi-gsd-tools 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
|
||||
pi-gsd-tools 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.
|
||||
|
||||
```bash
|
||||
VERIFIER_SKILLS=$(pi-gsd-tools agent-skills gsd-verifier 2>/dev/null)
|
||||
```
|
||||
|
||||
```
|
||||
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.
|
||||
${VERIFIER_SKILLS}",
|
||||
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 ${GSD_WS}` |
|
||||
|
||||
**If human_needed:**
|
||||
|
||||
**Step A: Persist human verification items as UAT file.**
|
||||
|
||||
Create `{phase_dir}/{phase_num}-HUMAN-UAT.md` using UAT template format:
|
||||
|
||||
```markdown
|
||||
---
|
||||
status: partial
|
||||
phase: {phase_num}-{phase_name}
|
||||
source: [{phase_num}-VERIFICATION.md]
|
||||
started: [now ISO]
|
||||
updated: [now ISO]
|
||||
---
|
||||
|
||||
## Current Test
|
||||
|
||||
[awaiting human testing]
|
||||
|
||||
## Tests
|
||||
|
||||
{For each human_verification item from VERIFICATION.md:}
|
||||
|
||||
### {N}. {item description}
|
||||
expected: {expected behavior from VERIFICATION.md}
|
||||
result: [pending]
|
||||
|
||||
## Summary
|
||||
|
||||
total: {count}
|
||||
passed: 0
|
||||
issues: 0
|
||||
pending: {count}
|
||||
skipped: 0
|
||||
blocked: 0
|
||||
|
||||
## Gaps
|
||||
```
|
||||
|
||||
Commit the file:
|
||||
```bash
|
||||
pi-gsd-tools commit "test({phase_num}): persist human verification items as UAT" --files "{phase_dir}/{phase_num}-HUMAN-UAT.md"
|
||||
```
|
||||
|
||||
**Step B: Present to user:**
|
||||
|
||||
```
|
||||
## ✓ Phase {X}: {Name} - Human Verification Required
|
||||
|
||||
All automated checks passed. {N} items need human testing:
|
||||
|
||||
{From VERIFICATION.md human_verification section}
|
||||
|
||||
Items saved to `{phase_num}-HUMAN-UAT.md` - they will appear in `/gsd-progress` and `/gsd-audit-uat`.
|
||||
|
||||
"approved" → continue | Report issues → gap closure
|
||||
```
|
||||
|
||||
**If user says "approved":** Proceed to `update_roadmap`. The HUMAN-UAT.md file persists with `status: partial` and will surface in future progress checks until the user runs `/gsd-verify-work` on it.
|
||||
|
||||
**If user reports issues:** Proceed to gap closure as currently implemented.
|
||||
|
||||
**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 ${GSD_WS}`
|
||||
|
||||
<sub>`/new` first → fresh context window</sub>
|
||||
|
||||
Also: `cat {phase_dir}/{phase_num}-VERIFICATION.md` - full report
|
||||
Also: `/gsd-verify-work {X} ${GSD_WS}` - manual testing first
|
||||
```
|
||||
|
||||
Gap closure cycle: `/gsd-plan-phase {X} --gaps ${GSD_WS}` reads VERIFICATION.md → creates gap plans with `gap_closure: true` → user runs `/gsd-execute-phase {X} --gaps-only ${GSD_WS}` → verifier re-runs.
|
||||
</step>
|
||||
|
||||
<step name="update_roadmap">
|
||||
**Mark phase complete and update all tracking files:**
|
||||
|
||||
```bash
|
||||
COMPLETION=$(pi-gsd-tools 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
|
||||
- Scanning for verification debt (returns `warnings` array)
|
||||
|
||||
Extract from result: `next_phase`, `next_phase_name`, `is_last_phase`, `warnings`, `has_warnings`.
|
||||
|
||||
**If has_warnings is true:**
|
||||
```
|
||||
## Phase {X} marked complete with {N} warnings:
|
||||
|
||||
{list each warning}
|
||||
|
||||
These items are tracked and will appear in `/gsd-progress` and `/gsd-audit-uat`.
|
||||
```
|
||||
|
||||
```bash
|
||||
pi-gsd-tools 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
|
||||
pi-gsd-tools 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=$(pi-gsd-tools config-get workflow._auto_chain_active 2>/dev/null || echo "false")
|
||||
AUTO_CFG=$(pi-gsd-tools 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 `.pi/gsd/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 ${GSD_WS} - see updated roadmap
|
||||
/gsd-discuss-phase {next} ${GSD_WS} - discuss next phase before planning
|
||||
/gsd-plan-phase {next} ${GSD_WS} - plan next phase
|
||||
/gsd-execute-phase {next} ${GSD_WS} - execute next phase
|
||||
```
|
||||
|
||||
Only suggest the commands listed above. Do not invent or hallucinate command names.
|
||||
</step>
|
||||
|
||||
</process>
|
||||
|
||||
<context_efficiency>
|
||||
Orchestrator: ~10-15% context for 200k windows, can use more for 1M+ windows.
|
||||
Subagents: fresh context each (200k-1M depending on model). No polling (Task blocks). No context bleed.
|
||||
|
||||
For 1M+ context models, consider:
|
||||
- Passing richer context (code snippets, dependency outputs) directly to executors instead of just file paths
|
||||
- Running small phases (≤3 plans, no dependencies) inline without subagent spawning overhead
|
||||
- Relaxing /new recommendations - context rot onset is much further out with 5x window
|
||||
</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>
|
||||
551
.pi/gsd/workflows/execute-plan.md
Normal file
551
.pi/gsd/workflows/execute-plan.md
Normal file
@@ -0,0 +1,551 @@
|
||||
<gsd-version v="1.12.4" />
|
||||
|
||||
<gsd-arguments>
|
||||
<settings>
|
||||
<keep-extra-args />
|
||||
</settings>
|
||||
<arg name="phase" type="number" />
|
||||
</gsd-arguments>
|
||||
|
||||
<gsd-execute>
|
||||
<shell command="pi-gsd-tools">
|
||||
<args>
|
||||
<arg string="init" />
|
||||
<arg string="execute-phase" />
|
||||
<arg name="phase" wrap='"' />
|
||||
</args>
|
||||
<outs>
|
||||
<out type="string" name="init" />
|
||||
</outs>
|
||||
</shell>
|
||||
<if>
|
||||
<condition>
|
||||
<starts-with>
|
||||
<left name="init" />
|
||||
<right type="string" value="@file:" />
|
||||
</starts-with>
|
||||
</condition>
|
||||
<then>
|
||||
<string-op op="split">
|
||||
<args>
|
||||
<arg name="init" />
|
||||
<arg type="string" value="@file:" />
|
||||
</args>
|
||||
<outs>
|
||||
<out type="string" name="init-file" />
|
||||
</outs>
|
||||
</string-op>
|
||||
<shell command="cat">
|
||||
<args>
|
||||
<arg name="init-file" wrap='"' />
|
||||
</args>
|
||||
<outs>
|
||||
<out type="string" name="init" />
|
||||
</outs>
|
||||
</shell>
|
||||
</then>
|
||||
</if>
|
||||
</gsd-execute>
|
||||
|
||||
## Execution Context (pre-injected by WXP)
|
||||
|
||||
**Phase:** <gsd-paste name="phase" />
|
||||
|
||||
**Phase Init Data:**
|
||||
<gsd-paste name="init" />
|
||||
|
||||
<process>
|
||||
|
||||
<step name="init_context" priority="first">
|
||||
Load execution context (paths only to minimize orchestrator context):
|
||||
|
||||
<!-- Context pre-injected above via WXP - variables available via <gsd-paste name="..."> -->
|
||||
|
||||
Extract from init JSON: `executor_model`, `commit_docs`, `sub_repos`, `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 || true) | sort
|
||||
(ls .planning/phases/XX-name/*-SUMMARY.md 2>/dev/null || true) | 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, isolation="worktree") 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
|
||||
pi-gsd-tools 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 GEMINI.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 `.pi/gsd/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 running as a parallel executor agent (spawned by execute-phase):**
|
||||
Use `--no-verify` on all commits. Pre-commit hooks cause build lock contention when multiple agents commit simultaneously (e.g., cargo lock fights in Rust projects). The orchestrator validates once after all agents complete.
|
||||
|
||||
**If running as the sole executor (sequential mode):**
|
||||
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. 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.
|
||||
|
||||
<sub_repos_commit_flow>
|
||||
**Sub-repos mode:** If `sub_repos` is configured (non-empty array from init context), use `commit-to-subrepo` instead of standard git commit. This routes files to their correct sub-repo based on path prefix.
|
||||
|
||||
```bash
|
||||
pi-gsd-tools commit-to-subrepo "{type}({phase}-{plan}): {description}" --files file1 file2 ...
|
||||
```
|
||||
|
||||
The command groups files by sub-repo prefix and commits atomically to each. Returns JSON: `{ committed: true, repos: { "backend": { hash: "abc", files: [...] }, ... } }`.
|
||||
|
||||
Record hashes from each repo in the response for SUMMARY tracking.
|
||||
|
||||
**If `sub_repos` is empty or not set:** Use standard git commit flow below.
|
||||
</sub_repos_commit_flow>
|
||||
|
||||
**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 .pi/gsd/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=$(pi-gsd-tools config-get workflow.node_repair 2>/dev/null || echo "true")
|
||||
```
|
||||
|
||||
If `NODE_REPAIR` is `true`: invoke `@./.pi/gsd/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 `.pi/gsd/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 `.pi/gsd/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)
|
||||
pi-gsd-tools state advance-plan
|
||||
|
||||
# Recalculate progress bar from disk state
|
||||
pi-gsd-tools state update-progress
|
||||
|
||||
# Record execution metrics
|
||||
pi-gsd-tools 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)
|
||||
pi-gsd-tools state add-decision \
|
||||
--phase "${PHASE}" --summary-file "${DECISION_TEXT_FILE}" --rationale-file "${RATIONALE_FILE}"
|
||||
|
||||
# Add blockers if any found
|
||||
pi-gsd-tools state add-blocker --text-file "${BLOCKER_TEXT_FILE}"
|
||||
```
|
||||
</step>
|
||||
|
||||
<step name="update_session_continuity">
|
||||
Update session info using gsd-tools:
|
||||
|
||||
```bash
|
||||
pi-gsd-tools 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
|
||||
pi-gsd-tools 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
|
||||
pi-gsd-tools 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
|
||||
pi-gsd-tools 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 || true
|
||||
```
|
||||
|
||||
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
|
||||
pi-gsd-tools 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 || true) | wc -l
|
||||
(ls -1 .planning/phases/[current-phase-dir]/*-SUMMARY.md 2>/dev/null || true) | 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: `/new` 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>
|
||||
107
.pi/gsd/workflows/fast.md
Normal file
107
.pi/gsd/workflows/fast.md
Normal file
@@ -0,0 +1,107 @@
|
||||
<gsd-version v="1.12.4" />
|
||||
|
||||
<purpose>
|
||||
Execute a trivial task inline without subagent overhead. No PLAN.md, no Task spawning,
|
||||
no research, no plan checking. Just: understand → do → commit → log.
|
||||
|
||||
For tasks like: fix a typo, update a config value, add a missing import, rename a
|
||||
variable, commit uncommitted work, add a .gitignore entry, bump a version number.
|
||||
|
||||
Use /gsd-quick for anything that needs multi-step planning or research.
|
||||
</purpose>
|
||||
|
||||
<process>
|
||||
|
||||
<step name="parse_task">
|
||||
Parse `$ARGUMENTS` for the task description.
|
||||
|
||||
If empty, ask:
|
||||
```
|
||||
What's the quick fix? (one sentence)
|
||||
```
|
||||
|
||||
Store as `$TASK`.
|
||||
</step>
|
||||
|
||||
<step name="scope_check">
|
||||
**Before doing anything, verify this is actually trivial.**
|
||||
|
||||
A task is trivial if it can be completed in:
|
||||
- ≤ 3 file edits
|
||||
- ≤ 1 minute of work
|
||||
- No new dependencies or architecture changes
|
||||
- No research needed
|
||||
|
||||
If the task seems non-trivial (multi-file refactor, new feature, needs research),
|
||||
say:
|
||||
|
||||
```
|
||||
This looks like it needs planning. Use /gsd-quick instead:
|
||||
/gsd-quick "{task description}"
|
||||
```
|
||||
|
||||
And stop.
|
||||
</step>
|
||||
|
||||
<step name="execute_inline">
|
||||
Do the work directly:
|
||||
|
||||
1. Read the relevant file(s)
|
||||
2. Make the change(s)
|
||||
3. Verify the change works (run existing tests if applicable, or do a quick sanity check)
|
||||
|
||||
**No PLAN.md.** Just do it.
|
||||
</step>
|
||||
|
||||
<step name="commit">
|
||||
Commit the change atomically:
|
||||
|
||||
```bash
|
||||
git add -A
|
||||
git commit -m "fix: {concise description of what changed}"
|
||||
```
|
||||
|
||||
Use conventional commit format: `fix:`, `feat:`, `docs:`, `chore:`, `refactor:` as appropriate.
|
||||
</step>
|
||||
|
||||
<step name="log_to_state">
|
||||
If `.planning/STATE.md` exists, append to the "Quick Tasks Completed" table.
|
||||
If the table doesn't exist, skip this step silently.
|
||||
|
||||
```bash
|
||||
# Check if STATE.md has quick tasks table
|
||||
if grep -q "Quick Tasks Completed" .planning/STATE.md 2>/dev/null; then
|
||||
# Append entry - workflow handles the format
|
||||
echo "| $(date +%Y-%m-%d) | fast | $TASK | ✅ |" >> .planning/STATE.md
|
||||
fi
|
||||
```
|
||||
</step>
|
||||
|
||||
<step name="done">
|
||||
Report completion:
|
||||
|
||||
```
|
||||
✅ Done: {what was changed}
|
||||
Commit: {short hash}
|
||||
Files: {list of changed files}
|
||||
```
|
||||
|
||||
No next-step suggestions. No workflow routing. Just done.
|
||||
</step>
|
||||
|
||||
</process>
|
||||
|
||||
<guardrails>
|
||||
- NEVER spawn a Task/subagent - this runs inline
|
||||
- NEVER create PLAN.md or SUMMARY.md files
|
||||
- NEVER run research or plan-checking
|
||||
- If the task takes more than 3 file edits, STOP and redirect to /gsd-quick
|
||||
- If you're unsure how to implement it, STOP and redirect to /gsd-quick
|
||||
</guardrails>
|
||||
|
||||
<success_criteria>
|
||||
- [ ] Task completed in current context (no subagents)
|
||||
- [ ] Atomic git commit with conventional message
|
||||
- [ ] STATE.md updated if it exists
|
||||
- [ ] Total operation under 2 minutes wall time
|
||||
</success_criteria>
|
||||
303
.pi/gsd/workflows/forensics.md
Normal file
303
.pi/gsd/workflows/forensics.md
Normal file
@@ -0,0 +1,303 @@
|
||||
<gsd-version v="1.12.4" />
|
||||
|
||||
<gsd-arguments>
|
||||
<settings><keep-extra-args /></settings>
|
||||
</gsd-arguments>
|
||||
|
||||
<gsd-execute>
|
||||
<shell command="pi-gsd-tools">
|
||||
<args>
|
||||
<arg string="state" />
|
||||
<arg string="json" />
|
||||
<arg string="--raw" />
|
||||
</args>
|
||||
<outs>
|
||||
<out type="string" name="state" />
|
||||
</outs>
|
||||
</shell>
|
||||
<shell command="pi-gsd-tools">
|
||||
<args>
|
||||
<arg string="validate" />
|
||||
<arg string="health" />
|
||||
<arg string="--raw" />
|
||||
</args>
|
||||
<outs>
|
||||
<suppress-errors />
|
||||
<out type="string" name="health" />
|
||||
</outs>
|
||||
</shell>
|
||||
</gsd-execute>
|
||||
|
||||
## Context (pre-injected)
|
||||
|
||||
**State:**
|
||||
<gsd-paste name="state" />
|
||||
|
||||
**Health:**
|
||||
<gsd-paste name="health" />
|
||||
|
||||
# Forensics Workflow
|
||||
|
||||
Post-mortem investigation for failed or stuck GSD workflows. Analyzes git history,
|
||||
`.planning/` artifacts, and file system state to detect anomalies and generate a
|
||||
structured diagnostic report.
|
||||
|
||||
**Principle:** This is a read-only investigation. Do not modify project files.
|
||||
Only write the forensic report.
|
||||
|
||||
---
|
||||
|
||||
## Step 1: Get Problem Description
|
||||
|
||||
```bash
|
||||
PROBLEM="$ARGUMENTS"
|
||||
```
|
||||
|
||||
If `$ARGUMENTS` is empty, ask the user:
|
||||
> "What went wrong? Describe the issue - e.g., 'autonomous mode got stuck on phase 3',
|
||||
> 'execute-phase failed silently', 'costs seem unusually high'."
|
||||
|
||||
Record the problem description for the report.
|
||||
|
||||
## Step 2: Gather Evidence
|
||||
|
||||
Collect data from all available sources. Missing sources are fine - adapt to what exists.
|
||||
|
||||
### 2a. Git History
|
||||
|
||||
```bash
|
||||
# Recent commits (last 30)
|
||||
git log --oneline -30
|
||||
|
||||
# Commits with timestamps for gap analysis
|
||||
git log --format="%H %ai %s" -30
|
||||
|
||||
# Files changed in recent commits (detect repeated edits)
|
||||
git log --name-only --format="" -20 | sort | uniq -c | sort -rn | head -20
|
||||
|
||||
# Uncommitted work
|
||||
git status --short
|
||||
git diff --stat
|
||||
```
|
||||
|
||||
Record:
|
||||
- Commit timeline (dates, messages, frequency)
|
||||
- Most-edited files (potential stuck-loop indicator)
|
||||
- Uncommitted changes (potential crash/interruption indicator)
|
||||
|
||||
### 2b. Planning State
|
||||
|
||||
Read these files if they exist:
|
||||
- `.planning/STATE.md` - current milestone, phase, progress, blockers, last session
|
||||
- `.planning/ROADMAP.md` - phase list with status
|
||||
- `.planning/config.json` - workflow configuration
|
||||
|
||||
Extract:
|
||||
- Current phase and its status
|
||||
- Last recorded session stop point
|
||||
- Any blockers or flags
|
||||
|
||||
### 2c. Phase Artifacts
|
||||
|
||||
For each phase directory in `.planning/phases/*/`:
|
||||
|
||||
```bash
|
||||
ls .planning/phases/*/
|
||||
```
|
||||
|
||||
For each phase, check which artifacts exist:
|
||||
- `{padded}-PLAN.md` or `{padded}-PLAN-*.md` (execution plans)
|
||||
- `{padded}-SUMMARY.md` (completion summary)
|
||||
- `{padded}-VERIFICATION.md` (quality verification)
|
||||
- `{padded}-CONTEXT.md` (design decisions)
|
||||
- `{padded}-RESEARCH.md` (pre-planning research)
|
||||
|
||||
Track: which phases have complete artifact sets vs gaps.
|
||||
|
||||
### 2d. Session Reports
|
||||
|
||||
Read `.planning/reports/SESSION_REPORT.md` if it exists - extract last session outcomes,
|
||||
work completed, token estimates.
|
||||
|
||||
### 2e. Git Worktree State
|
||||
|
||||
```bash
|
||||
git worktree list
|
||||
```
|
||||
|
||||
Check for orphaned worktrees (from crashed agents).
|
||||
|
||||
## Step 3: Detect Anomalies
|
||||
|
||||
Evaluate the gathered evidence against these anomaly patterns:
|
||||
|
||||
### Stuck Loop Detection
|
||||
|
||||
**Signal:** Same file appears in 3+ consecutive commits within a short time window.
|
||||
|
||||
```bash
|
||||
# Look for files committed repeatedly in sequence
|
||||
git log --name-only --format="---COMMIT---" -20
|
||||
```
|
||||
|
||||
Parse commit boundaries. If any file appears in 3+ consecutive commits, flag as:
|
||||
- **Confidence HIGH** if the commit messages are similar (e.g., "fix:", "fix:", "fix:" on same file)
|
||||
- **Confidence MEDIUM** if the file appears frequently but commit messages vary
|
||||
|
||||
### Missing Artifact Detection
|
||||
|
||||
**Signal:** Phase appears complete (has commits, is past in roadmap) but lacks expected artifacts.
|
||||
|
||||
For each phase that should be complete:
|
||||
- PLAN.md missing → planning step was skipped
|
||||
- SUMMARY.md missing → phase was not properly closed
|
||||
- VERIFICATION.md missing → quality check was skipped
|
||||
|
||||
### Abandoned Work Detection
|
||||
|
||||
**Signal:** Large gap between last commit and current time, with STATE.md showing mid-execution.
|
||||
|
||||
```bash
|
||||
# Time since last commit
|
||||
git log -1 --format="%ai"
|
||||
```
|
||||
|
||||
If STATE.md shows an active phase but the last commit is >2 hours old and there are
|
||||
uncommitted changes, flag as potential abandonment or crash.
|
||||
|
||||
### Crash/Interruption Detection
|
||||
|
||||
**Signal:** Uncommitted changes + STATE.md shows mid-execution + orphaned worktrees.
|
||||
|
||||
Combine:
|
||||
- `git status` shows modified/staged files
|
||||
- STATE.md has an active execution entry
|
||||
- `git worktree list` shows worktrees beyond the main one
|
||||
|
||||
### Scope Drift Detection
|
||||
|
||||
**Signal:** Recent commits touch files outside the current phase's expected scope.
|
||||
|
||||
Read the current phase PLAN.md to determine expected file paths. Compare against
|
||||
files actually modified in recent commits. Flag any files that are clearly outside
|
||||
the phase's domain.
|
||||
|
||||
### Test Regression Detection
|
||||
|
||||
**Signal:** Commit messages containing "fix test", "revert", or re-commits of test files.
|
||||
|
||||
```bash
|
||||
git log --oneline -20 | grep -iE "fix test|revert|broken|regression|fail"
|
||||
```
|
||||
|
||||
## Step 4: Generate Report
|
||||
|
||||
Create the forensics directory if needed:
|
||||
```bash
|
||||
mkdir -p .planning/forensics
|
||||
```
|
||||
|
||||
Write to `.planning/forensics/report-$(date +%Y%m%d-%H%M%S).md`:
|
||||
|
||||
```markdown
|
||||
# Forensic Report
|
||||
|
||||
**Generated:** {ISO timestamp}
|
||||
**Problem:** {user's description}
|
||||
|
||||
---
|
||||
|
||||
## Evidence Summary
|
||||
|
||||
### Git Activity
|
||||
- **Last commit:** {date} - "{message}"
|
||||
- **Commits (last 30):** {count}
|
||||
- **Time span:** {earliest} → {latest}
|
||||
- **Uncommitted changes:** {yes/no - list if yes}
|
||||
- **Active worktrees:** {count - list if >1}
|
||||
|
||||
### Planning State
|
||||
- **Current milestone:** {version or "none"}
|
||||
- **Current phase:** {number - name - status}
|
||||
- **Last session:** {stopped_at from STATE.md}
|
||||
- **Blockers:** {any flags from STATE.md}
|
||||
|
||||
### Artifact Completeness
|
||||
| Phase | PLAN | CONTEXT | RESEARCH | SUMMARY | VERIFICATION |
|
||||
| --------------------- | ----------------- | ------- | -------- | ------- | ------------ |
|
||||
| {for each phase: name | ✅/❌ per artifact} |
|
||||
|
||||
## Anomalies Detected
|
||||
|
||||
### {Anomaly Type} - {Confidence: HIGH/MEDIUM/LOW}
|
||||
**Evidence:** {specific commits, files, or state data}
|
||||
**Interpretation:** {what this likely means}
|
||||
|
||||
{repeat for each anomaly found}
|
||||
|
||||
## Root Cause Hypothesis
|
||||
|
||||
Based on the evidence above, the most likely explanation is:
|
||||
|
||||
{1-3 sentence hypothesis grounded in the anomalies}
|
||||
|
||||
## Recommended Actions
|
||||
|
||||
1. {Specific, actionable remediation step}
|
||||
2. {Another step if applicable}
|
||||
3. {Recovery command if applicable - e.g., `/gsd-resume-work`, `/gsd-execute-phase N`}
|
||||
|
||||
---
|
||||
|
||||
*Report generated by `/gsd-forensics`. All paths redacted for portability.*
|
||||
```
|
||||
|
||||
**Redaction rules:**
|
||||
- Replace absolute paths with relative paths (strip `$HOME` prefix)
|
||||
- Remove any API keys, tokens, or credentials found in git diff output
|
||||
- Truncate large diffs to first 50 lines
|
||||
|
||||
## Step 5: Present Report
|
||||
|
||||
Display the full forensic report inline.
|
||||
|
||||
## Step 6: Offer Interactive Investigation
|
||||
|
||||
> "Report saved to `.planning/forensics/report-{timestamp}.md`.
|
||||
>
|
||||
> I can dig deeper into any finding. Want me to:
|
||||
> - Trace a specific anomaly to its root cause?
|
||||
> - Read specific files referenced in the evidence?
|
||||
> - Check if a similar issue has been reported before?"
|
||||
|
||||
If the user asks follow-up questions, answer from the evidence already gathered.
|
||||
Read additional files only if specifically needed.
|
||||
|
||||
## Step 7: Offer Issue Creation
|
||||
|
||||
If actionable anomalies were found (HIGH or MEDIUM confidence):
|
||||
|
||||
> "Want me to create a GitHub issue for this? I'll format the findings and redact paths."
|
||||
|
||||
If confirmed:
|
||||
```bash
|
||||
# Check if "bug" label exists before using it
|
||||
BUG_LABEL=$(gh label list --search "bug" --json name -q '.[0].name' 2>/dev/null)
|
||||
LABEL_FLAG=""
|
||||
if [ -n "$BUG_LABEL" ]; then
|
||||
LABEL_FLAG="--label bug"
|
||||
fi
|
||||
|
||||
gh issue create \
|
||||
--title "bug: {concise description from anomaly}" \
|
||||
$LABEL_FLAG \
|
||||
--body "{formatted findings from report}"
|
||||
```
|
||||
|
||||
## Step 8: Update STATE.md
|
||||
|
||||
```bash
|
||||
pi-gsd-tools state record-session \
|
||||
--stopped-at "Forensic investigation complete" \
|
||||
--resume-file ".planning/forensics/report-{timestamp}.md"
|
||||
```
|
||||
205
.pi/gsd/workflows/health.md
Normal file
205
.pi/gsd/workflows/health.md
Normal file
@@ -0,0 +1,205 @@
|
||||
<gsd-version v="1.12.4" />
|
||||
|
||||
<gsd-arguments>
|
||||
<settings><keep-extra-args /></settings>
|
||||
<arg name="repair" type="flag" flag="--repair" optional />
|
||||
</gsd-arguments>
|
||||
|
||||
<gsd-execute>
|
||||
<shell command="pi-gsd-tools">
|
||||
<args>
|
||||
<arg string="validate" />
|
||||
<arg string="health" />
|
||||
<arg string="--raw" />
|
||||
</args>
|
||||
<outs>
|
||||
<out type="string" name="health" />
|
||||
</outs>
|
||||
</shell>
|
||||
</gsd-execute>
|
||||
|
||||
## Health Report (pre-injected)
|
||||
|
||||
<gsd-paste name="health" />
|
||||
|
||||
<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
|
||||
pi-gsd-tools 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
|
||||
|
||||
- [W002] STATE.md references phase 5, but only phases 1-3 exist
|
||||
Fix: Review STATE.md manually before changing it; repair will not overwrite an existing STATE.md
|
||||
|
||||
- [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
|
||||
pi-gsd-tools 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 | No |
|
||||
| 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 when it is missing | 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>
|
||||
|
||||
<stale_task_cleanup>
|
||||
**Windows-specific:** Check for stale Claude Code task directories that accumulate on crash/freeze.
|
||||
These are left behind when subagents are force-killed and consume disk space.
|
||||
|
||||
When `--repair` is active, detect and clean up:
|
||||
|
||||
```bash
|
||||
# Check for stale task directories (older than 24 hours)
|
||||
TASKS_DIR=".agent/tasks"
|
||||
if [ -d "$TASKS_DIR" ]; then
|
||||
STALE_COUNT=$( (find "$TASKS_DIR" -maxdepth 1 -type d -mtime +1 2>/dev/null || true) | wc -l )
|
||||
if [ "$STALE_COUNT" -gt 0 ]; then
|
||||
echo "⚠️ Found $STALE_COUNT stale task directories in .agent/tasks/"
|
||||
echo " These are leftover from crashed subagent sessions."
|
||||
echo " Run: rm -rf .agent/tasks/* (safe - only affects dead sessions)"
|
||||
fi
|
||||
fi
|
||||
```
|
||||
|
||||
Report as info diagnostic: `I002 | info | Stale subagent task directories found | Yes (--repair removes them)`
|
||||
</stale_task_cleanup>
|
||||
608
.pi/gsd/workflows/help.md
Normal file
608
.pi/gsd/workflows/help.md
Normal file
@@ -0,0 +1,608 @@
|
||||
<gsd-version v="1.12.4" />
|
||||
|
||||
<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 the agent is planning to do before it starts.
|
||||
|
||||
- Shows the agent's intended approach for a phase
|
||||
- Lets you course-correct if the agent 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, or run a specific wave.
|
||||
|
||||
- Groups plans by wave (from frontmatter), executes waves sequentially
|
||||
- Plans within each wave run in parallel via Task tool
|
||||
- Optional `--wave N` flag executes only Wave `N` and stops unless the phase is now fully complete
|
||||
- Verifies phase goal after all plans complete
|
||||
- Updates REQUIREMENTS.md, ROADMAP.md, STATE.md
|
||||
|
||||
Usage: `/gsd-execute-phase 5`
|
||||
Usage: `/gsd-execute-phase 5 --wave 2`
|
||||
|
||||
### 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`
|
||||
|
||||
---
|
||||
|
||||
**`/gsd-fast [description]`**
|
||||
Execute a trivial task inline - no subagents, no planning files, no overhead.
|
||||
|
||||
For tasks too small to justify planning: typo fixes, config changes, forgotten commits, simple additions. Runs in the current context, makes the change, commits, and logs to STATE.md.
|
||||
|
||||
- No PLAN.md or SUMMARY.md created
|
||||
- No subagent spawned (runs inline)
|
||||
- ≤ 3 file edits - redirects to `/gsd-quick` if task is non-trivial
|
||||
- Atomic commit with conventional message
|
||||
|
||||
Usage: `/gsd-fast "fix the typo in README"`
|
||||
Usage: `/gsd-fast "add .env to gitignore"`
|
||||
|
||||
### 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
|
||||
- Optional `--reset-phase-numbers` flag restarts numbering at Phase 1 and archives old phase dirs first for safety
|
||||
|
||||
Mirrors `/gsd-new-project` flow for brownfield projects (existing PROJECT.md).
|
||||
|
||||
Usage: `/gsd-new-milestone "v2.0 Features"`
|
||||
Usage: `/gsd-new-milestone --reset-phase-numbers "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 `/new` - 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 `.agent/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`
|
||||
|
||||
---
|
||||
|
||||
**`/gsd-review --phase N [--gemini] [--claude] [--codex] [--all]`**
|
||||
Cross-AI peer review - invoke external AI CLIs to independently review phase plans.
|
||||
|
||||
- Detects available CLIs (gemini, claude, codex)
|
||||
- Each CLI reviews plans independently with the same structured prompt
|
||||
- Produces REVIEWS.md with per-reviewer feedback and consensus summary
|
||||
- Feed reviews back into planning: `/gsd-plan-phase N --reviews`
|
||||
|
||||
Usage: `/gsd-review --phase 3 --all`
|
||||
|
||||
---
|
||||
|
||||
**`/gsd-pr-branch [target]`**
|
||||
Create a clean branch for pull requests by filtering out .planning/ commits.
|
||||
|
||||
- Classifies commits: code-only (include), planning-only (exclude), mixed (include sans .planning/)
|
||||
- Cherry-picks code commits onto a clean branch
|
||||
- Reviewers see only code changes, no GSD artifacts
|
||||
|
||||
Usage: `/gsd-pr-branch` or `/gsd-pr-branch main`
|
||||
|
||||
---
|
||||
|
||||
**`/gsd-plant-seed [idea]`**
|
||||
Capture a forward-looking idea with trigger conditions for automatic surfacing.
|
||||
|
||||
- Seeds preserve WHY, WHEN to surface, and breadcrumbs to related code
|
||||
- Auto-surfaces during `/gsd-new-milestone` when trigger conditions match
|
||||
- Better than deferred items - triggers are checked, not forgotten
|
||||
|
||||
Usage: `/gsd-plant-seed "add real-time notifications when we build the events system"`
|
||||
|
||||
---
|
||||
|
||||
**`/gsd-audit-uat`**
|
||||
Cross-phase audit of all outstanding UAT and verification items.
|
||||
- Scans every phase for pending, skipped, blocked, and human_needed items
|
||||
- Cross-references against codebase to detect stale documentation
|
||||
- Produces prioritized human test plan grouped by testability
|
||||
- Use before starting a new milestone to clear verification debt
|
||||
|
||||
Usage: `/gsd-audit-uat`
|
||||
|
||||
### 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
|
||||
/new
|
||||
/gsd-plan-phase 1 # Create plans for first phase
|
||||
/new
|
||||
/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
|
||||
/new
|
||||
/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 ...
|
||||
/new
|
||||
/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>
|
||||
188
.pi/gsd/workflows/insert-phase.md
Normal file
188
.pi/gsd/workflows/insert-phase.md
Normal file
@@ -0,0 +1,188 @@
|
||||
<gsd-version v="1.12.4" />
|
||||
|
||||
<gsd-arguments>
|
||||
<settings>
|
||||
<keep-extra-args />
|
||||
</settings>
|
||||
<arg name="after-phase" type="number" />
|
||||
<arg name="description" type="string" optional />
|
||||
</gsd-arguments>
|
||||
|
||||
<gsd-execute>
|
||||
<shell command="pi-gsd-tools">
|
||||
<args>
|
||||
<arg string="init" />
|
||||
<arg string="phase-op" />
|
||||
<arg name="after-phase" wrap='"' />
|
||||
</args>
|
||||
<outs>
|
||||
<out type="string" name="init" />
|
||||
</outs>
|
||||
</shell>
|
||||
<if>
|
||||
<condition>
|
||||
<starts-with>
|
||||
<left name="init" />
|
||||
<right type="string" value="@file:" />
|
||||
</starts-with>
|
||||
</condition>
|
||||
<then>
|
||||
<string-op op="split">
|
||||
<args>
|
||||
<arg name="init" />
|
||||
<arg type="string" value="@file:" />
|
||||
</args>
|
||||
<outs>
|
||||
<out type="string" name="init-file" />
|
||||
</outs>
|
||||
</string-op>
|
||||
<shell command="cat">
|
||||
<args>
|
||||
<arg name="init-file" wrap='"' />
|
||||
</args>
|
||||
<outs>
|
||||
<out type="string" name="init" />
|
||||
</outs>
|
||||
</shell>
|
||||
</then>
|
||||
</if>
|
||||
<shell command="pi-gsd-tools">
|
||||
<args>
|
||||
<arg string="state" />
|
||||
<arg string="json" />
|
||||
<arg string="--raw" />
|
||||
</args>
|
||||
<outs>
|
||||
<out type="string" name="state" />
|
||||
</outs>
|
||||
</shell>
|
||||
</gsd-execute>
|
||||
|
||||
## Context (pre-injected by WXP)
|
||||
|
||||
**Insert after phase:** <gsd-paste name="after-phase" />
|
||||
|
||||
**Description:** <gsd-paste name="description" />
|
||||
|
||||
**Phase Init Data:**
|
||||
<gsd-paste name="init" />
|
||||
|
||||
<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:
|
||||
|
||||
<!-- Context pre-injected above via WXP - variables available via <gsd-paste name="..."> -->
|
||||
|
||||
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=$(pi-gsd-tools 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>`/new` 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>
|
||||
228
.pi/gsd/workflows/list-phase-assumptions.md
Normal file
228
.pi/gsd/workflows/list-phase-assumptions.md
Normal file
@@ -0,0 +1,228 @@
|
||||
<gsd-version v="1.12.4" />
|
||||
|
||||
<gsd-arguments>
|
||||
<settings>
|
||||
<keep-extra-args />
|
||||
</settings>
|
||||
<arg name="phase" type="number" />
|
||||
</gsd-arguments>
|
||||
|
||||
<gsd-execute>
|
||||
<shell command="pi-gsd-tools">
|
||||
<args>
|
||||
<arg string="init" />
|
||||
<arg string="phase-op" />
|
||||
<arg name="phase" wrap='"' />
|
||||
</args>
|
||||
<outs>
|
||||
<out type="string" name="init" />
|
||||
</outs>
|
||||
</shell>
|
||||
<if>
|
||||
<condition>
|
||||
<starts-with>
|
||||
<left name="init" />
|
||||
<right type="string" value="@file:" />
|
||||
</starts-with>
|
||||
</condition>
|
||||
<then>
|
||||
<string-op op="split">
|
||||
<args>
|
||||
<arg name="init" />
|
||||
<arg type="string" value="@file:" />
|
||||
</args>
|
||||
<outs>
|
||||
<out type="string" name="init-file" />
|
||||
</outs>
|
||||
</string-op>
|
||||
<shell command="cat">
|
||||
<args>
|
||||
<arg name="init-file" wrap='"' />
|
||||
</args>
|
||||
<outs>
|
||||
<out type="string" name="init" />
|
||||
</outs>
|
||||
</shell>
|
||||
</then>
|
||||
</if>
|
||||
<shell command="pi-gsd-tools">
|
||||
<args>
|
||||
<arg string="state" />
|
||||
<arg string="json" />
|
||||
<arg string="--raw" />
|
||||
</args>
|
||||
<outs>
|
||||
<suppress-errors />
|
||||
<out type="string" name="state" />
|
||||
</outs>
|
||||
</shell>
|
||||
</gsd-execute>
|
||||
|
||||
## Context (pre-injected by WXP)
|
||||
|
||||
**Phase:** <gsd-paste name="phase" />
|
||||
|
||||
**Phase Data:**
|
||||
<gsd-paste name="init" />
|
||||
|
||||
**State:**
|
||||
<gsd-paste name="state" />
|
||||
|
||||
---
|
||||
|
||||
<purpose>
|
||||
Surface the agent's assumptions about a phase before planning, enabling users to correct misconceptions early.
|
||||
|
||||
Key difference from discuss-phase: This is ANALYSIS of what the agent 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, phase data and state are pre-injected above via WXP -->
|
||||
|
||||
Parse `init` JSON for: `phase_found`, `phase_number`, `phase_name`, `phase_slug`, `goal`, `phase_dir`.
|
||||
|
||||
**If `phase_found` is false:**
|
||||
|
||||
```
|
||||
Error: Phase {phase} not found in roadmap.
|
||||
|
||||
Available phases: [list from roadmap]
|
||||
|
||||
Usage: /gsd-list-phase-assumptions [phase-number]
|
||||
Example: /gsd-list-phase-assumptions 3
|
||||
```
|
||||
|
||||
Exit workflow.
|
||||
|
||||
**If `phase_found` is true:** 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 the agent 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 the agent 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 the agent'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 the agent expect complexity or challenges?
|
||||
- "The tricky part is X because..."
|
||||
- "Potential issues: Y, Z"
|
||||
- "I'd watch out for..."
|
||||
|
||||
**5. Dependencies:**
|
||||
What does the agent 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>
|
||||
102
.pi/gsd/workflows/list-workspaces.md
Normal file
102
.pi/gsd/workflows/list-workspaces.md
Normal file
@@ -0,0 +1,102 @@
|
||||
<gsd-version v="1.12.4" />
|
||||
|
||||
<gsd-arguments>
|
||||
<settings><keep-extra-args /></settings>
|
||||
</gsd-arguments>
|
||||
|
||||
<gsd-execute>
|
||||
<shell command="pi-gsd-tools">
|
||||
<args>
|
||||
<arg string="init" />
|
||||
<arg string="list-workspaces" />
|
||||
</args>
|
||||
<outs>
|
||||
<out type="string" name="workspaces-data" />
|
||||
</outs>
|
||||
</shell>
|
||||
<if>
|
||||
<condition>
|
||||
<starts-with>
|
||||
<left name="workspaces-data" />
|
||||
<right type="string" value="@file:" />
|
||||
</starts-with>
|
||||
</condition>
|
||||
<then>
|
||||
<string-op op="split">
|
||||
<args>
|
||||
<arg name="workspaces-data" />
|
||||
<arg type="string" value="@file:" />
|
||||
</args>
|
||||
<outs>
|
||||
<out type="string" name="workspaces-data-file" />
|
||||
</outs>
|
||||
</string-op>
|
||||
<shell command="cat">
|
||||
<args>
|
||||
<arg name="workspaces-data-file" wrap='"' />
|
||||
</args>
|
||||
<outs>
|
||||
<out type="string" name="workspaces-data" />
|
||||
</outs>
|
||||
</shell>
|
||||
</then>
|
||||
</if>
|
||||
</gsd-execute>
|
||||
|
||||
## Workspaces (pre-injected)
|
||||
|
||||
<gsd-paste name="workspaces-data" />
|
||||
|
||||
<purpose>
|
||||
List all GSD workspaces found in ~/gsd-workspaces/ with their status.
|
||||
</purpose>
|
||||
|
||||
<required_reading>
|
||||
Read all files referenced by the invoking prompt's execution_context before starting.
|
||||
</required_reading>
|
||||
|
||||
<process>
|
||||
|
||||
## 1. Setup
|
||||
|
||||
<!-- Context pre-injected above via WXP - variables available via <gsd-paste name="..."> -->
|
||||
|
||||
Parse JSON for: `workspace_base`, `workspaces`, `workspace_count`.
|
||||
|
||||
## 2. Display
|
||||
|
||||
**If `workspace_count` is 0:**
|
||||
|
||||
```
|
||||
No workspaces found in ~/gsd-workspaces/
|
||||
|
||||
Create one with:
|
||||
/gsd-new-workspace --name my-workspace --repos repo1,repo2
|
||||
```
|
||||
|
||||
Done.
|
||||
|
||||
**If workspaces exist:**
|
||||
|
||||
Display a table:
|
||||
|
||||
```
|
||||
GSD Workspaces (~/gsd-workspaces/)
|
||||
|
||||
| Name | Repos | Strategy | GSD Project |
|
||||
| --------- | ----- | -------- | ----------- |
|
||||
| feature-a | 3 | worktree | Yes |
|
||||
| feature-b | 2 | clone | No |
|
||||
|
||||
Manage:
|
||||
cd ~/gsd-workspaces/<name> # Enter a workspace
|
||||
/gsd-remove-workspace <name> # Remove a workspace
|
||||
```
|
||||
|
||||
For each workspace, show:
|
||||
- **Name** - directory name
|
||||
- **Repos** - count from init data
|
||||
- **Strategy** - from WORKSPACE.md
|
||||
- **GSD Project** - whether `.planning/PROJECT.md` exists (Yes/No)
|
||||
|
||||
</process>
|
||||
432
.pi/gsd/workflows/manager.md
Normal file
432
.pi/gsd/workflows/manager.md
Normal file
@@ -0,0 +1,432 @@
|
||||
<gsd-version v="1.12.4" />
|
||||
|
||||
<gsd-arguments>
|
||||
<settings><keep-extra-args /></settings>
|
||||
</gsd-arguments>
|
||||
|
||||
<gsd-execute>
|
||||
<shell command="pi-gsd-tools">
|
||||
<args>
|
||||
<arg string="state" />
|
||||
<arg string="json" />
|
||||
<arg string="--raw" />
|
||||
</args>
|
||||
<outs>
|
||||
<out type="string" name="state" />
|
||||
</outs>
|
||||
</shell>
|
||||
<shell command="pi-gsd-tools">
|
||||
<args>
|
||||
<arg string="roadmap" />
|
||||
<arg string="analyze" />
|
||||
<arg string="--raw" />
|
||||
</args>
|
||||
<outs>
|
||||
<out type="string" name="roadmap" />
|
||||
</outs>
|
||||
</shell>
|
||||
<shell command="pi-gsd-tools">
|
||||
<args>
|
||||
<arg string="init" />
|
||||
<arg string="manager" />
|
||||
</args>
|
||||
<outs>
|
||||
<out type="string" name="manager-data" />
|
||||
</outs>
|
||||
</shell>
|
||||
<if>
|
||||
<condition>
|
||||
<starts-with>
|
||||
<left name="manager-data" />
|
||||
<right type="string" value="@file:" />
|
||||
</starts-with>
|
||||
</condition>
|
||||
<then>
|
||||
<string-op op="split">
|
||||
<args>
|
||||
<arg name="manager-data" />
|
||||
<arg type="string" value="@file:" />
|
||||
</args>
|
||||
<outs>
|
||||
<out type="string" name="manager-data-file" />
|
||||
</outs>
|
||||
</string-op>
|
||||
<shell command="cat">
|
||||
<args>
|
||||
<arg name="manager-data-file" wrap='"' />
|
||||
</args>
|
||||
<outs>
|
||||
<out type="string" name="manager-data" />
|
||||
</outs>
|
||||
</shell>
|
||||
</then>
|
||||
</if>
|
||||
</gsd-execute>
|
||||
|
||||
## Manager Context (pre-injected)
|
||||
|
||||
**State:**
|
||||
<gsd-paste name="state" />
|
||||
|
||||
**Roadmap:**
|
||||
<gsd-paste name="roadmap" />
|
||||
|
||||
**Manager Data:**
|
||||
<gsd-paste name="manager-data" />
|
||||
|
||||
<purpose>
|
||||
|
||||
Interactive command center for managing a milestone from a single terminal. Shows a dashboard of all phases with visual status, dispatches discuss inline and plan/execute as background agents, and loops back to the dashboard after each action. Enables parallel phase work from one terminal.
|
||||
|
||||
</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
|
||||
|
||||
Bootstrap via manager init:
|
||||
|
||||
<!-- Context pre-injected above via WXP - variables available via <gsd-paste name="..."> -->
|
||||
|
||||
Parse JSON for: `milestone_version`, `milestone_name`, `phase_count`, `completed_count`, `in_progress_count`, `phases`, `recommended_actions`, `all_complete`, `waiting_signal`.
|
||||
|
||||
**If error:** Display the error message and exit.
|
||||
|
||||
Display startup banner:
|
||||
|
||||
```
|
||||
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
|
||||
GSD ► MANAGER
|
||||
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
|
||||
|
||||
{milestone_version} - {milestone_name}
|
||||
{phase_count} phases · {completed_count} complete
|
||||
|
||||
✓ Discuss → inline ◆ Plan/Execute → background
|
||||
Dashboard auto-refreshes when background work is active.
|
||||
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
|
||||
```
|
||||
|
||||
Proceed to dashboard step.
|
||||
|
||||
</step>
|
||||
|
||||
<step name="dashboard">
|
||||
|
||||
## 2. Dashboard (Refresh Point)
|
||||
|
||||
**Every time this step is reached**, re-read state from disk to pick up changes from background agents:
|
||||
|
||||
<!-- Context pre-injected above via WXP - variables available via <gsd-paste name="..."> -->
|
||||
|
||||
Parse the full JSON. Build the dashboard display.
|
||||
|
||||
Build dashboard from JSON. Symbols: `✓` done, `◆` active, `○` pending, `·` queued. Progress bar: 20-char `█░`.
|
||||
|
||||
**Status mapping** (disk_status → D P E Status):
|
||||
|
||||
- `complete` → `✓ ✓ ✓` `✓ Complete`
|
||||
- `partial` → `✓ ✓ ◆` `◆ Executing...`
|
||||
- `planned` → `✓ ✓ ○` `○ Ready to execute`
|
||||
- `discussed` → `✓ ○ ·` `○ Ready to plan`
|
||||
- `researched` → `◆ · ·` `○ Ready to plan`
|
||||
- `empty`/`no_directory` + `is_next_to_discuss` → `○ · ·` `○ Ready to discuss`
|
||||
- `empty`/`no_directory` otherwise → `· · ·` `· Up next`
|
||||
- If `is_active`, replace status icon with `◆` and append `(active)`
|
||||
|
||||
If any `is_active` phases, show: `◆ Background: {action} Phase {N}, ...` above grid.
|
||||
|
||||
Use `display_name` (not `name`) for the Phase column - it's pre-truncated to 20 chars with `…` if clipped. Pad all phase names to the same width for alignment.
|
||||
|
||||
Use `deps_display` from init JSON for the Deps column - shows which phases this phase depends on (e.g. `1,3`) or `-` for none.
|
||||
|
||||
Example output:
|
||||
|
||||
```
|
||||
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
|
||||
GSD ► DASHBOARD
|
||||
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
|
||||
████████████░░░░░░░░ 60% (3/5 phases)
|
||||
◆ Background: Planning Phase 4
|
||||
| # | Phase | Deps | D | P | E | Status |
|
||||
| --- | -------------------- | ---- | --- | --- | --- | -------------------- |
|
||||
| 1 | Foundation | - | ✓ | ✓ | ✓ | ✓ Complete |
|
||||
| 2 | API Layer | 1 | ✓ | ✓ | ◆ | ◆ Executing (active) |
|
||||
| 3 | Auth System | 1 | ✓ | ✓ | ○ | ○ Ready to execute |
|
||||
| 4 | Dashboard UI & Set… | 1,2 | ✓ | ◆ | · | ◆ Planning (active) |
|
||||
| 5 | Notifications | - | ○ | · | · | ○ Ready to discuss |
|
||||
| 6 | Polish & Final Mail… | 1-5 | · | · | · | · Up next |
|
||||
```
|
||||
|
||||
**Recommendations section:**
|
||||
|
||||
If `all_complete` is true:
|
||||
|
||||
```
|
||||
╔══════════════════════════════════════════════════════════════╗
|
||||
║ MILESTONE COMPLETE ║
|
||||
╚══════════════════════════════════════════════════════════════╝
|
||||
|
||||
All {phase_count} phases done. Ready for final steps:
|
||||
→ /gsd-verify-work - run acceptance testing
|
||||
→ /gsd-complete-milestone - archive and wrap up
|
||||
```
|
||||
|
||||
Ask user via AskUserQuestion:
|
||||
- **question:** "All phases complete. What next?"
|
||||
- **options:** "Verify work" / "Complete milestone" / "Exit manager"
|
||||
|
||||
Handle responses:
|
||||
- "Verify work": `Skill(skill="gsd-verify-work")` then loop to dashboard.
|
||||
- "Complete milestone": `Skill(skill="gsd-complete-milestone")` then exit.
|
||||
- "Exit manager": Go to exit step.
|
||||
|
||||
**If NOT all_complete**, build compound options from `recommended_actions`:
|
||||
|
||||
**Compound option logic:** Group background actions (plan/execute) together, and pair them with the single inline action (discuss) when one exists. The goal is to present the fewest options possible - one option can dispatch multiple background agents plus one inline action.
|
||||
|
||||
**Building options:**
|
||||
|
||||
1. Collect all background actions (execute and plan recommendations) - there can be multiple of each.
|
||||
2. Collect the inline action (discuss recommendation, if any - there will be at most one since discuss is sequential).
|
||||
3. Build compound options:
|
||||
|
||||
**If there are ANY recommended actions (background, inline, or both):**
|
||||
Create ONE primary "Continue" option that dispatches ALL of them together:
|
||||
- Label: `"Continue"` - always this exact word
|
||||
- Below the label, list every action that will happen. Enumerate ALL recommended actions - do not cap or truncate:
|
||||
```
|
||||
Continue:
|
||||
→ Execute Phase 32 (background)
|
||||
→ Plan Phase 34 (background)
|
||||
→ Discuss Phase 35 (inline)
|
||||
```
|
||||
- This dispatches all background agents first, then runs the inline discuss (if any).
|
||||
- If there is no inline discuss, the dashboard refreshes after spawning background agents.
|
||||
|
||||
**Important:** The Continue option must include EVERY action from `recommended_actions` - not just 2. If there are 3 actions, list 3. If there are 5, list 5.
|
||||
|
||||
4. Always add:
|
||||
- `"Refresh dashboard"`
|
||||
- `"Exit manager"`
|
||||
|
||||
Display recommendations compactly:
|
||||
|
||||
```
|
||||
───────────────────────────────────────────────────────────────
|
||||
▶ Next Steps
|
||||
───────────────────────────────────────────────────────────────
|
||||
|
||||
Continue:
|
||||
→ Execute Phase 32 (background)
|
||||
→ Plan Phase 34 (background)
|
||||
→ Discuss Phase 35 (inline)
|
||||
```
|
||||
|
||||
**Auto-refresh:** If background agents are running (`is_active` is true for any phase), set a 60-second auto-refresh cycle. After presenting the action menu, if no user input is received within 60 seconds, automatically refresh the dashboard. This interval is configurable via `manager_refresh_interval` in GSD config (default: 60 seconds, set to 0 to disable).
|
||||
|
||||
Present via AskUserQuestion:
|
||||
- **question:** "What would you like to do?"
|
||||
- **options:** (compound options as built above + refresh + exit, AskUserQuestion auto-adds "Other")
|
||||
|
||||
**On "Other" (free text):** Parse intent - if it mentions a phase number and action, dispatch accordingly. If unclear, display available actions and loop to action_menu.
|
||||
|
||||
Proceed to handle_action step with the selected action.
|
||||
|
||||
</step>
|
||||
|
||||
<step name="handle_action">
|
||||
|
||||
## 4. Handle Action
|
||||
|
||||
### Refresh Dashboard
|
||||
|
||||
Loop back to dashboard step.
|
||||
|
||||
### Exit Manager
|
||||
|
||||
Go to exit step.
|
||||
|
||||
### Compound Action (background + inline)
|
||||
|
||||
When the user selects a compound option:
|
||||
|
||||
1. **Spawn all background agents first** (plan/execute) - dispatch them in parallel using the Plan Phase N / Execute Phase N handlers below.
|
||||
2. **Then run the inline discuss:**
|
||||
|
||||
```
|
||||
Skill(skill="gsd-discuss-phase", args="{PHASE_NUM}")
|
||||
```
|
||||
|
||||
After discuss completes, loop back to dashboard step (background agents continue running).
|
||||
|
||||
### Discuss Phase N
|
||||
|
||||
Discussion is interactive - needs user input. Run inline:
|
||||
|
||||
```
|
||||
Skill(skill="gsd-discuss-phase", args="{PHASE_NUM}")
|
||||
```
|
||||
|
||||
After discuss completes, loop back to dashboard step.
|
||||
|
||||
### Plan Phase N
|
||||
|
||||
Planning runs autonomously. Spawn a background agent:
|
||||
|
||||
```
|
||||
Task(
|
||||
description="Plan phase {N}: {phase_name}",
|
||||
run_in_background=true,
|
||||
prompt="You are running the GSD plan-phase workflow for phase {N} of the project.
|
||||
|
||||
Working directory: {cwd}
|
||||
Phase: {N} - {phase_name}
|
||||
Goal: {goal}
|
||||
|
||||
Steps:
|
||||
1. Read the plan-phase workflow: cat .pi/gsd/workflows/plan-phase.md
|
||||
2. Run: pi-gsd-tools init plan-phase {N}
|
||||
3. Follow the workflow steps to produce PLAN.md files for this phase.
|
||||
4. If research is enabled in config, run the research step first.
|
||||
5. Spawn a gsd-planner subagent via Task() to create the plans.
|
||||
6. If plan-checker is enabled, spawn a gsd-plan-checker subagent to verify.
|
||||
7. Commit plan files when complete.
|
||||
|
||||
Important: You are running in the background. Do NOT use AskUserQuestion - make autonomous decisions based on project context. If you hit a blocker, write it to STATE.md as a blocker and stop. Do NOT silently work around permission or file access errors - let them fail so the manager can surface them with resolution hints."
|
||||
)
|
||||
```
|
||||
|
||||
Display:
|
||||
|
||||
```
|
||||
◆ Spawning planner for Phase {N}: {phase_name}...
|
||||
```
|
||||
|
||||
Loop back to dashboard step.
|
||||
|
||||
### Execute Phase N
|
||||
|
||||
Execution runs autonomously. Spawn a background agent:
|
||||
|
||||
```
|
||||
Task(
|
||||
description="Execute phase {N}: {phase_name}",
|
||||
run_in_background=true,
|
||||
prompt="You are running the GSD execute-phase workflow for phase {N} of the project.
|
||||
|
||||
Working directory: {cwd}
|
||||
Phase: {N} - {phase_name}
|
||||
Goal: {goal}
|
||||
|
||||
Steps:
|
||||
1. Read the execute-phase workflow: cat .pi/gsd/workflows/execute-phase.md
|
||||
2. Run: pi-gsd-tools init execute-phase {N}
|
||||
3. Follow the workflow steps: discover plans, analyze dependencies, group into waves.
|
||||
4. For each wave, spawn gsd-executor subagents via Task() to execute plans in parallel.
|
||||
5. After all waves complete, spawn a gsd-verifier subagent if verifier is enabled.
|
||||
6. Update ROADMAP.md and STATE.md with progress.
|
||||
7. Commit all changes.
|
||||
|
||||
Important: You are running in the background. Do NOT use AskUserQuestion - make autonomous decisions. Use --no-verify on git commits. If you hit a permission error, file lock, or any access issue, do NOT work around it - let it fail and write the error to STATE.md as a blocker so the manager can surface it with resolution guidance."
|
||||
)
|
||||
```
|
||||
|
||||
Display:
|
||||
|
||||
```
|
||||
◆ Spawning executor for Phase {N}: {phase_name}...
|
||||
```
|
||||
|
||||
Loop back to dashboard step.
|
||||
|
||||
</step>
|
||||
|
||||
<step name="background_completion">
|
||||
|
||||
## 5. Background Agent Completion
|
||||
|
||||
When notified that a background agent completed:
|
||||
|
||||
1. Read the result message from the agent.
|
||||
2. Display a brief notification:
|
||||
|
||||
```
|
||||
✓ {description}
|
||||
{brief summary from agent result}
|
||||
```
|
||||
|
||||
3. Loop back to dashboard step.
|
||||
|
||||
**If the agent reported an error or blocker:**
|
||||
|
||||
Classify the error:
|
||||
|
||||
**Permission / tool access error** (e.g. tool not allowed, permission denied, sandbox restriction):
|
||||
- Parse the error to identify which tool or command was blocked.
|
||||
- Display the error clearly, then offer to fix it:
|
||||
- **question:** "Phase {N} failed - permission denied for `{tool_or_command}`. Want me to add it to settings.local.json so it's allowed?"
|
||||
- **options:** "Add permission and retry" / "Run this phase inline instead" / "Skip and continue"
|
||||
- "Add permission and retry": Use `Skill(skill="update-config")` to add the permission to `settings.local.json`, then re-spawn the background agent. Loop to dashboard.
|
||||
- "Run this phase inline instead": Dispatch the same action (plan/execute) inline via `Skill()` instead of a background Task. Loop to dashboard after.
|
||||
- "Skip and continue": Loop to dashboard (phase stays in current state).
|
||||
|
||||
**Other errors** (git lock, file conflict, logic error, etc.):
|
||||
- Display the error, then offer options via AskUserQuestion:
|
||||
- **question:** "Background agent for Phase {N} encountered an issue: {error}. What next?"
|
||||
- **options:** "Retry" / "Run inline instead" / "Skip and continue" / "View details"
|
||||
- "Retry": Re-spawn the same background agent. Loop to dashboard.
|
||||
- "Run inline instead": Dispatch the action inline via `Skill()`. Loop to dashboard after.
|
||||
- "Skip and continue": Loop to dashboard (phase stays in current state).
|
||||
- "View details": Read STATE.md blockers section, display, then re-present options.
|
||||
|
||||
</step>
|
||||
|
||||
<step name="exit">
|
||||
|
||||
## 6. Exit
|
||||
|
||||
Display final status with progress bar:
|
||||
|
||||
```
|
||||
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
|
||||
GSD ► SESSION END
|
||||
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
|
||||
|
||||
{milestone_version} - {milestone_name}
|
||||
{PROGRESS_BAR} {progress_pct}% ({completed_count}/{phase_count} phases)
|
||||
|
||||
Resume anytime: /gsd-manager
|
||||
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
|
||||
```
|
||||
|
||||
**Note:** Any background agents still running will continue to completion. Their results will be visible on next `/gsd-manager` or `/gsd-progress` invocation.
|
||||
|
||||
</step>
|
||||
|
||||
</process>
|
||||
|
||||
<success_criteria>
|
||||
- [ ] Dashboard displays all phases with correct status indicators (D/P/E/V columns)
|
||||
- [ ] Progress bar shows accurate completion percentage
|
||||
- [ ] Dependency resolution: blocked phases show which deps are missing
|
||||
- [ ] Recommendations prioritize: execute > plan > discuss
|
||||
- [ ] Discuss phases run inline via Skill() - interactive questions work
|
||||
- [ ] Plan phases spawn background Task agents - return to dashboard immediately
|
||||
- [ ] Execute phases spawn background Task agents - return to dashboard immediately
|
||||
- [ ] Dashboard refreshes pick up changes from background agents via disk state
|
||||
- [ ] Background agent completion triggers notification and dashboard refresh
|
||||
- [ ] Background agent errors present retry/skip options
|
||||
- [ ] All-complete state offers verify-work and complete-milestone
|
||||
- [ ] Exit shows final status with resume instructions
|
||||
- [ ] "Other" free-text input parsed for phase number and action
|
||||
- [ ] Manager loop continues until user exits or milestone completes
|
||||
</success_criteria>
|
||||
410
.pi/gsd/workflows/map-codebase.md
Normal file
410
.pi/gsd/workflows/map-codebase.md
Normal file
@@ -0,0 +1,410 @@
|
||||
<gsd-version v="1.12.4" />
|
||||
|
||||
<gsd-arguments>
|
||||
<settings><keep-extra-args /></settings>
|
||||
</gsd-arguments>
|
||||
|
||||
<gsd-execute>
|
||||
<shell command="pi-gsd-tools">
|
||||
<args>
|
||||
<arg string="state" />
|
||||
<arg string="json" />
|
||||
<arg string="--raw" />
|
||||
</args>
|
||||
<outs>
|
||||
<out type="string" name="state" />
|
||||
</outs>
|
||||
</shell>
|
||||
<shell command="pi-gsd-tools">
|
||||
<args>
|
||||
<arg string="agent-skills" />
|
||||
<arg string="gsd-codebase-mapper" />
|
||||
</args>
|
||||
<outs>
|
||||
<suppress-errors />
|
||||
<out type="string" name="agent-skills-mapper" />
|
||||
</outs>
|
||||
</shell>
|
||||
</gsd-execute>
|
||||
|
||||
## Context (pre-injected)
|
||||
|
||||
**State:**
|
||||
<gsd-paste name="state" />
|
||||
|
||||
**Mapper Skills:**
|
||||
<gsd-paste name="agent-skills-mapper" />
|
||||
|
||||
<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>
|
||||
|
||||
<available_agent_types>
|
||||
Valid GSD subagent types (use exact names - do not fall back to 'general-purpose'):
|
||||
- gsd-codebase-mapper - Maps project structure and dependencies
|
||||
</available_agent_types>
|
||||
|
||||
<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 the agent 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:
|
||||
|
||||
<!-- Context pre-injected above via WXP - variables available via <gsd-paste name="..."> -->
|
||||
|
||||
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.
|
||||
|
||||
**How to detect:** Check if you have access to a `Task` tool (may be capitalized as `Task` or lowercase as `task` depending on runtime). If you do NOT have a `Task`/`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_SKILLS_MAPPER}"
|
||||
)
|
||||
```
|
||||
|
||||
**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_SKILLS_MAPPER}"
|
||||
)
|
||||
```
|
||||
|
||||
**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_SKILLS_MAPPER}"
|
||||
)
|
||||
```
|
||||
|
||||
**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.
|
||||
${AGENT_SKILLS_MAPPER}"
|
||||
)
|
||||
```
|
||||
|
||||
Continue to collect_confirmations.
|
||||
</step>
|
||||
|
||||
<step name="collect_confirmations">
|
||||
Wait for all 4 agents to complete using TaskOutput tool.
|
||||
|
||||
**For each agent task_id returned by the Agent tool calls above:**
|
||||
```
|
||||
TaskOutput tool:
|
||||
task_id: "{task_id from Agent result}"
|
||||
block: true
|
||||
timeout: 300000
|
||||
```
|
||||
|
||||
Call TaskOutput for all 4 agents in parallel (single message with 4 TaskOutput calls).
|
||||
|
||||
Once all TaskOutput calls return, 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
|
||||
pi-gsd-tools 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>`/new` 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>
|
||||
239
.pi/gsd/workflows/milestone-summary.md
Normal file
239
.pi/gsd/workflows/milestone-summary.md
Normal file
@@ -0,0 +1,239 @@
|
||||
<gsd-version v="1.12.4" />
|
||||
|
||||
<gsd-arguments>
|
||||
<settings><keep-extra-args /></settings>
|
||||
</gsd-arguments>
|
||||
|
||||
<gsd-execute>
|
||||
<shell command="pi-gsd-tools">
|
||||
<args>
|
||||
<arg string="init" />
|
||||
<arg string="progress" />
|
||||
</args>
|
||||
<outs>
|
||||
<out type="string" name="progress-data" />
|
||||
</outs>
|
||||
</shell>
|
||||
<if>
|
||||
<condition>
|
||||
<starts-with>
|
||||
<left name="progress-data" />
|
||||
<right type="string" value="@file:" />
|
||||
</starts-with>
|
||||
</condition>
|
||||
<then>
|
||||
<string-op op="split">
|
||||
<args>
|
||||
<arg name="progress-data" />
|
||||
<arg type="string" value="@file:" />
|
||||
</args>
|
||||
<outs>
|
||||
<out type="string" name="progress-data-file" />
|
||||
</outs>
|
||||
</string-op>
|
||||
<shell command="cat">
|
||||
<args>
|
||||
<arg name="progress-data-file" wrap='"' />
|
||||
</args>
|
||||
<outs>
|
||||
<out type="string" name="progress-data" />
|
||||
</outs>
|
||||
</shell>
|
||||
</then>
|
||||
</if>
|
||||
<shell command="pi-gsd-tools">
|
||||
<args>
|
||||
<arg string="state" />
|
||||
<arg string="json" />
|
||||
<arg string="--raw" />
|
||||
</args>
|
||||
<outs>
|
||||
<out type="string" name="state" />
|
||||
</outs>
|
||||
</shell>
|
||||
</gsd-execute>
|
||||
|
||||
## Context (pre-injected)
|
||||
|
||||
**Progress:**
|
||||
<gsd-paste name="progress-data" />
|
||||
|
||||
**State:**
|
||||
<gsd-paste name="state" />
|
||||
|
||||
# Milestone Summary Workflow
|
||||
|
||||
Generate a comprehensive, human-friendly project summary from completed milestone artifacts.
|
||||
Designed for team onboarding - a new contributor can read the output and understand the entire project.
|
||||
|
||||
---
|
||||
|
||||
## Step 1: Resolve Version
|
||||
|
||||
<!-- Context pre-injected above via WXP - variables available via <gsd-paste name="..."> -->
|
||||
|
||||
This returns phase metadata. For each phase in the milestone scope:
|
||||
|
||||
- Read `{phase_dir}/{padded}-SUMMARY.md` if it exists - extract `one_liner`, `accomplishments`, `decisions`
|
||||
- Read `{phase_dir}/{padded}-VERIFICATION.md` if it exists - extract status, gaps, deferred items
|
||||
- Read `{phase_dir}/{padded}-CONTEXT.md` if it exists - extract key decisions from `<decisions>` section
|
||||
- Read `{phase_dir}/{padded}-RESEARCH.md` if it exists - note what was researched
|
||||
|
||||
Track which phases have which artifacts.
|
||||
|
||||
**If no phase directories exist** (empty milestone or pre-build state): skip to Step 5 and generate a minimal summary noting "No phases have been executed yet." Do not error - the summary should still capture PROJECT.md and ROADMAP.md content.
|
||||
|
||||
## Step 4: Gather Git Statistics
|
||||
|
||||
Try each method in order until one succeeds:
|
||||
|
||||
**Method 1 - Tagged milestone** (check first):
|
||||
```bash
|
||||
git tag -l "v${VERSION}" | head -1
|
||||
```
|
||||
If the tag exists:
|
||||
```bash
|
||||
git log v${VERSION} --oneline | wc -l
|
||||
git diff --stat $(git log --format=%H --reverse v${VERSION} | head -1)..v${VERSION}
|
||||
```
|
||||
|
||||
**Method 2 - STATE.md date range** (if no tag):
|
||||
Read STATE.md and extract the `started_at` or earliest session date. Use it as the `--since` boundary:
|
||||
```bash
|
||||
git log --oneline --since="<started_at_date>" | wc -l
|
||||
```
|
||||
|
||||
**Method 3 - Earliest phase commit** (if STATE.md has no date):
|
||||
Find the earliest `.planning/phases/` commit:
|
||||
```bash
|
||||
git log --oneline --diff-filter=A -- ".planning/phases/" | tail -1
|
||||
```
|
||||
Use that commit's date as the start boundary.
|
||||
|
||||
**Method 4 - Skip stats** (if none of the above work):
|
||||
Report "Git statistics unavailable - no tag or date range could be determined." This is not an error - the summary continues without the Stats section.
|
||||
|
||||
Extract (when available):
|
||||
- Total commits in milestone
|
||||
- Files changed, insertions, deletions
|
||||
- Timeline (start date → end date)
|
||||
- Contributors (from git log authors)
|
||||
|
||||
## Step 5: Generate Summary Document
|
||||
|
||||
Write to `.planning/reports/MILESTONE_SUMMARY-v${VERSION}.md`:
|
||||
|
||||
```markdown
|
||||
# Milestone v{VERSION} - Project Summary
|
||||
|
||||
**Generated:** {date}
|
||||
**Purpose:** Team onboarding and project review
|
||||
|
||||
---
|
||||
|
||||
## 1. Project Overview
|
||||
|
||||
{From PROJECT.md: "What This Is", core value proposition, target users}
|
||||
{If mid-milestone: note which phases are complete vs in-progress}
|
||||
|
||||
## 2. Architecture & Technical Decisions
|
||||
|
||||
{From CONTEXT.md files across phases: key technical choices}
|
||||
{From SUMMARY.md decisions: patterns, libraries, frameworks chosen}
|
||||
{From PROJECT.md: tech stack if documented}
|
||||
|
||||
Present as a bulleted list of decisions with brief rationale:
|
||||
- **Decision:** {what was chosen}
|
||||
- **Why:** {rationale from CONTEXT.md}
|
||||
- **Phase:** {which phase made this decision}
|
||||
|
||||
## 3. Phases Delivered
|
||||
|
||||
| Phase | Name | Status | One-Liner |
|
||||
| ----- | ---- | ------ | --------- |
|
||||
{For each phase: number, name, status (complete/in-progress/planned), one_liner from SUMMARY.md}
|
||||
|
||||
## 4. Requirements Coverage
|
||||
|
||||
{From REQUIREMENTS.md: list each requirement with status}
|
||||
- ✅ {Requirement met}
|
||||
- ⚠️ {Requirement partially met - note gap}
|
||||
- ❌ {Requirement not met - note reason}
|
||||
|
||||
{If MILESTONE-AUDIT.md exists: include audit verdict}
|
||||
|
||||
## 5. Key Decisions Log
|
||||
|
||||
{Aggregate from all CONTEXT.md <decisions> sections}
|
||||
{Each decision with: ID, description, phase, rationale}
|
||||
|
||||
## 6. Tech Debt & Deferred Items
|
||||
|
||||
{From VERIFICATION.md files: gaps found, anti-patterns noted}
|
||||
{From RETROSPECTIVE.md: lessons learned, what to improve}
|
||||
{From CONTEXT.md <deferred> sections: ideas parked for later}
|
||||
|
||||
## 7. Getting Started
|
||||
|
||||
{Entry points for new contributors:}
|
||||
- **Run the project:** {from PROJECT.md or SUMMARY.md}
|
||||
- **Key directories:** {from codebase structure}
|
||||
- **Tests:** {test command from PROJECT.md or GEMINI.md}
|
||||
- **Where to look first:** {main entry points, core modules}
|
||||
|
||||
---
|
||||
|
||||
## Stats
|
||||
|
||||
- **Timeline:** {start} → {end} ({duration})
|
||||
- **Phases:** {count complete} / {count total}
|
||||
- **Commits:** {count}
|
||||
- **Files changed:** {count} (+{insertions} / -{deletions})
|
||||
- **Contributors:** {list}
|
||||
```
|
||||
|
||||
## Step 6: Write and Commit
|
||||
|
||||
**Overwrite guard:** If `.planning/reports/MILESTONE_SUMMARY-v${VERSION}.md` already exists, ask the user:
|
||||
> "A milestone summary for v{VERSION} already exists. Overwrite it, or view the existing one?"
|
||||
If "view": display existing file and skip to Step 8 (interactive mode). If "overwrite": proceed.
|
||||
|
||||
Create the reports directory if needed:
|
||||
```bash
|
||||
mkdir -p .planning/reports
|
||||
```
|
||||
|
||||
Write the summary, then commit:
|
||||
```bash
|
||||
pi-gsd-tools commit "docs(v${VERSION}): generate milestone summary for onboarding" \
|
||||
--files ".planning/reports/MILESTONE_SUMMARY-v${VERSION}.md"
|
||||
```
|
||||
|
||||
## Step 7: Present Summary
|
||||
|
||||
Display the full summary document inline.
|
||||
|
||||
## Step 8: Offer Interactive Mode
|
||||
|
||||
After presenting the summary:
|
||||
|
||||
> "Summary written to `.planning/reports/MILESTONE_SUMMARY-v{VERSION}.md`.
|
||||
>
|
||||
> I have full context from the build artifacts. Want to ask anything about the project?
|
||||
> Architecture decisions, specific phases, requirements, tech debt - ask away."
|
||||
|
||||
If the user asks questions:
|
||||
- Answer from the artifacts already loaded (CONTEXT.md, SUMMARY.md, VERIFICATION.md, etc.)
|
||||
- Reference specific files and decisions
|
||||
- Stay grounded in what was actually built (not speculation)
|
||||
|
||||
If the user is done:
|
||||
- Suggest next steps: `/gsd-new-milestone`, `/gsd-progress`, or sharing the summary with the team
|
||||
|
||||
## Step 9: Update STATE.md
|
||||
|
||||
```bash
|
||||
pi-gsd-tools state record-session \
|
||||
--stopped-at "Milestone v${VERSION} summary generated" \
|
||||
--resume-file ".planning/reports/MILESTONE_SUMMARY-v${VERSION}.md"
|
||||
```
|
||||
514
.pi/gsd/workflows/new-milestone.md
Normal file
514
.pi/gsd/workflows/new-milestone.md
Normal file
@@ -0,0 +1,514 @@
|
||||
<gsd-version v="1.12.4" />
|
||||
|
||||
<gsd-arguments>
|
||||
<settings>
|
||||
<keep-extra-args />
|
||||
</settings>
|
||||
<arg name="auto" type="flag" flag="--auto" optional />
|
||||
<arg name="skip-research" type="flag" flag="--skip-research" optional />
|
||||
</gsd-arguments>
|
||||
|
||||
<gsd-execute>
|
||||
<shell command="pi-gsd-tools">
|
||||
<args>
|
||||
<arg string="state" />
|
||||
<arg string="json" />
|
||||
<arg string="--raw" />
|
||||
</args>
|
||||
<outs>
|
||||
<out type="string" name="state" />
|
||||
</outs>
|
||||
</shell>
|
||||
<shell command="pi-gsd-tools">
|
||||
<args>
|
||||
<arg string="roadmap" />
|
||||
<arg string="analyze" />
|
||||
<arg string="--raw" />
|
||||
</args>
|
||||
<outs>
|
||||
<out type="string" name="roadmap" />
|
||||
</outs>
|
||||
</shell>
|
||||
</gsd-execute>
|
||||
## Initialization Context (pre-injected by WXP)
|
||||
|
||||
**Project State:**
|
||||
<gsd-paste name="state" />
|
||||
|
||||
|
||||
---
|
||||
|
||||
<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>
|
||||
|
||||
<available_agent_types>
|
||||
Valid GSD subagent types (use exact names - do not fall back to 'general-purpose'):
|
||||
- gsd-project-researcher - Researches project-level technical decisions
|
||||
- gsd-research-synthesizer - Synthesizes findings from parallel research agents
|
||||
- gsd-roadmapper - Creates phased execution roadmaps
|
||||
</available_agent_types>
|
||||
|
||||
<process>
|
||||
|
||||
## 1. Load Context
|
||||
|
||||
Parse `$ARGUMENTS` before doing anything else:
|
||||
- `--reset-phase-numbers` flag → opt into restarting roadmap phase numbering at `1`
|
||||
- remaining text → use as milestone name if present
|
||||
|
||||
If the flag is absent, keep the current behavior of continuing phase numbering from the previous milestone.
|
||||
|
||||
- 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
|
||||
|
||||
## 3.5. Verify Milestone Understanding
|
||||
|
||||
Before writing any files, present a summary of what was gathered and ask for confirmation.
|
||||
|
||||
```
|
||||
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
|
||||
GSD ► MILESTONE SUMMARY
|
||||
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
|
||||
|
||||
**Milestone v[X.Y]: [Name]**
|
||||
|
||||
**Goal:** [One sentence]
|
||||
|
||||
**Target features:**
|
||||
- [Feature 1]
|
||||
- [Feature 2]
|
||||
- [Feature 3]
|
||||
|
||||
**Key context:** [Any important constraints, decisions, or notes from questioning]
|
||||
```
|
||||
|
||||
AskUserQuestion:
|
||||
- header: "Confirm?"
|
||||
- question: "Does this capture what you want to build in this milestone?"
|
||||
- options:
|
||||
- "Looks good" - Proceed to write PROJECT.md
|
||||
- "Adjust" - Let me correct or add details
|
||||
|
||||
**If "Adjust":** Ask what needs changing (plain text, NOT AskUserQuestion). Incorporate changes, re-present the summary. Loop until "Looks good" is selected.
|
||||
|
||||
**If "Looks good":** Proceed to Step 4.
|
||||
|
||||
## 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.
|
||||
|
||||
Ensure the `## Evolution` section exists in PROJECT.md. If missing (projects created before this feature), add it before the footer:
|
||||
|
||||
```markdown
|
||||
## Evolution
|
||||
|
||||
This document evolves at phase transitions and milestone boundaries.
|
||||
|
||||
**After each phase transition** (via `/gsd-transition`):
|
||||
1. Requirements invalidated? → Move to Out of Scope with reason
|
||||
2. Requirements validated? → Move to Validated with phase reference
|
||||
3. New requirements emerged? → Add to Active
|
||||
4. Decisions to log? → Add to Key Decisions
|
||||
5. "What This Is" still accurate? → Update if drifted
|
||||
|
||||
**After each milestone** (via `/gsd-complete-milestone`):
|
||||
1. Full review of all sections
|
||||
2. Core Value check - still the right priority?
|
||||
3. Audit Out of Scope - reasons still valid?
|
||||
4. Update Context with current state
|
||||
```
|
||||
|
||||
## 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).
|
||||
|
||||
<!-- Context pre-injected above via WXP - variables available via <gsd-paste name="..."> -->
|
||||
|
||||
Extract from init JSON: `researcher_model`, `synthesizer_model`, `roadmapper_model`, `commit_docs`, `research_enabled`, `current_milestone`, `project_exists`, `roadmap_exists`, `latest_completed_milestone`, `phase_dir_count`, `phase_archive_path`.
|
||||
|
||||
## 7.5 Reset-phase safety (only when `--reset-phase-numbers`)
|
||||
|
||||
If `--reset-phase-numbers` is active:
|
||||
|
||||
1. Set starting phase number to `1` for the upcoming roadmap.
|
||||
2. If `phase_dir_count > 0`, archive the old phase directories before roadmapping so new `01-*` / `02-*` directories cannot collide with stale milestone directories.
|
||||
|
||||
If `phase_dir_count > 0` and `phase_archive_path` is available:
|
||||
|
||||
```bash
|
||||
mkdir -p "${phase_archive_path}"
|
||||
find .planning/phases -mindepth 1 -maxdepth 1 -type d -exec mv {} "${phase_archive_path}/" \;
|
||||
```
|
||||
|
||||
Then verify `.planning/phases/` no longer contains old milestone directories before continuing.
|
||||
|
||||
If `phase_dir_count > 0` but `phase_archive_path` is missing:
|
||||
- Stop and explain that reset numbering is unsafe without a completed milestone archive target.
|
||||
- Tell the user to complete/archive the previous milestone first, then rerun `/gsd-new-milestone --reset-phase-numbers ${GSD_WS}`.
|
||||
|
||||
## 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>
|
||||
|
||||
${AGENT_SKILLS_RESEARCHER}
|
||||
|
||||
<downstream_consumer>{CONSUMER}</downstream_consumer>
|
||||
|
||||
<quality_gate>{GATES}</quality_gate>
|
||||
|
||||
<output>
|
||||
Write to: .planning/research/{FILE}
|
||||
Use template: .pi/gsd/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>
|
||||
|
||||
${AGENT_SKILLS_SYNTHESIZER}
|
||||
|
||||
Write to: .planning/research/SUMMARY.md
|
||||
Use template: .pi/gsd/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
|
||||
pi-gsd-tools commit "docs: define milestone v[X.Y] requirements" --files .planning/REQUIREMENTS.md
|
||||
```
|
||||
|
||||
## 10. Create Roadmap
|
||||
|
||||
```
|
||||
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
|
||||
GSD ► CREATING ROADMAP
|
||||
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
|
||||
|
||||
◆ Spawning roadmapper...
|
||||
```
|
||||
|
||||
**Starting phase number:**
|
||||
- If `--reset-phase-numbers` is active, start at **Phase 1**
|
||||
- Otherwise, continue from the previous milestone's last phase number (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>
|
||||
|
||||
${AGENT_SKILLS_ROADMAPPER}
|
||||
|
||||
</planning_context>
|
||||
|
||||
<instructions>
|
||||
Create roadmap for milestone v[X.Y]:
|
||||
1. Respect the selected numbering mode:
|
||||
- `--reset-phase-numbers` → start at Phase 1
|
||||
- default behavior → continue from the previous milestone's last phase number
|
||||
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
|
||||
pi-gsd-tools 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] ${GSD_WS}` - gather context and clarify approach
|
||||
|
||||
<sub>`/new` first → fresh context window</sub>
|
||||
|
||||
Also: `/gsd-plan-phase [N] ${GSD_WS}` - 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)
|
||||
- [ ] Phase numbering mode respected (continued or reset)
|
||||
- [ ] All commits made (if planning docs committed)
|
||||
- [ ] User knows next step: `/gsd-discuss-phase [N] ${GSD_WS}`
|
||||
|
||||
**Atomic commits:** Each phase commits its artifacts immediately.
|
||||
</success_criteria>
|
||||
1286
.pi/gsd/workflows/new-project.md
Normal file
1286
.pi/gsd/workflows/new-project.md
Normal file
File diff suppressed because it is too large
Load Diff
287
.pi/gsd/workflows/new-workspace.md
Normal file
287
.pi/gsd/workflows/new-workspace.md
Normal file
@@ -0,0 +1,287 @@
|
||||
<gsd-version v="1.12.4" />
|
||||
|
||||
<gsd-arguments>
|
||||
<settings><keep-extra-args /></settings>
|
||||
<arg name="name" type="string" optional />
|
||||
</gsd-arguments>
|
||||
|
||||
<gsd-execute>
|
||||
<shell command="pi-gsd-tools">
|
||||
<args>
|
||||
<arg string="init" />
|
||||
<arg string="new-workspace" />
|
||||
</args>
|
||||
<outs>
|
||||
<out type="string" name="workspace-data" />
|
||||
</outs>
|
||||
</shell>
|
||||
<if>
|
||||
<condition>
|
||||
<starts-with>
|
||||
<left name="workspace-data" />
|
||||
<right type="string" value="@file:" />
|
||||
</starts-with>
|
||||
</condition>
|
||||
<then>
|
||||
<string-op op="split">
|
||||
<args>
|
||||
<arg name="workspace-data" />
|
||||
<arg type="string" value="@file:" />
|
||||
</args>
|
||||
<outs>
|
||||
<out type="string" name="workspace-data-file" />
|
||||
</outs>
|
||||
</string-op>
|
||||
<shell command="cat">
|
||||
<args>
|
||||
<arg name="workspace-data-file" wrap='"' />
|
||||
</args>
|
||||
<outs>
|
||||
<out type="string" name="workspace-data" />
|
||||
</outs>
|
||||
</shell>
|
||||
</then>
|
||||
</if>
|
||||
</gsd-execute>
|
||||
|
||||
## Context (pre-injected)
|
||||
|
||||
**Workspace name:** <gsd-paste name="name" />
|
||||
|
||||
**Workspace Data:**
|
||||
<gsd-paste name="workspace-data" />
|
||||
|
||||
<purpose>
|
||||
Create an isolated workspace directory with git repo copies (worktrees or clones) and an independent `.planning/` directory. Supports multi-repo orchestration and single-repo feature branch isolation.
|
||||
</purpose>
|
||||
|
||||
<required_reading>
|
||||
Read all files referenced by the invoking prompt's execution_context before starting.
|
||||
</required_reading>
|
||||
|
||||
<process>
|
||||
|
||||
## 1. Setup
|
||||
|
||||
**MANDATORY FIRST STEP - Execute init command:**
|
||||
|
||||
<!-- Context pre-injected above via WXP - variables available via <gsd-paste name="..."> -->
|
||||
|
||||
Parse JSON for: `default_workspace_base`, `child_repos`, `child_repo_count`, `worktree_available`, `is_git_repo`, `cwd_repo_name`, `project_root`.
|
||||
|
||||
## 2. Parse Arguments
|
||||
|
||||
Extract from $ARGUMENTS:
|
||||
- `--name` → `WORKSPACE_NAME` (required)
|
||||
- `--repos` → `REPO_LIST` (comma-separated paths or names)
|
||||
- `--path` → `TARGET_PATH` (defaults to `$default_workspace_base/$WORKSPACE_NAME`)
|
||||
- `--strategy` → `STRATEGY` (defaults to `worktree`)
|
||||
- `--branch` → `BRANCH_NAME` (defaults to `workspace/$WORKSPACE_NAME`)
|
||||
- `--auto` → skip interactive questions
|
||||
|
||||
**If `--name` is missing and not `--auto`:**
|
||||
|
||||
Use AskUserQuestion:
|
||||
- header: "Workspace Name"
|
||||
- question: "What should this workspace be called?"
|
||||
- requireAnswer: true
|
||||
|
||||
## 3. Select Repos
|
||||
|
||||
**If `--repos` is provided:** Parse comma-separated values. For each value:
|
||||
- If it's an absolute path, use it directly
|
||||
- If it's a relative path or name, resolve against `$project_root`
|
||||
- Special case: `.` means current repo (use `$project_root`, name it `$cwd_repo_name`)
|
||||
|
||||
**If `--repos` is NOT provided and not `--auto`:**
|
||||
|
||||
**If `child_repo_count` > 0:**
|
||||
|
||||
Present child repos for selection:
|
||||
|
||||
Use AskUserQuestion:
|
||||
- header: "Select Repos"
|
||||
- question: "Which repos should be included in the workspace?"
|
||||
- options: List each child repo from `child_repos` array by name
|
||||
- multiSelect: true
|
||||
|
||||
**If `child_repo_count` is 0 and `is_git_repo` is true:**
|
||||
|
||||
Use AskUserQuestion:
|
||||
- header: "Current Repo"
|
||||
- question: "No child repos found. Create a workspace with the current repo?"
|
||||
- options:
|
||||
- "Yes - create workspace with current repo" → use current repo
|
||||
- "Cancel" → exit
|
||||
|
||||
**If `child_repo_count` is 0 and `is_git_repo` is false:**
|
||||
|
||||
Error:
|
||||
```
|
||||
No git repos found in the current directory and this is not a git repo.
|
||||
|
||||
Run this command from a directory containing git repos, or specify repos explicitly:
|
||||
/gsd-new-workspace --name my-workspace --repos /path/to/repo1,/path/to/repo2
|
||||
```
|
||||
Exit.
|
||||
|
||||
**If `--auto` and `--repos` is NOT provided:**
|
||||
|
||||
Error:
|
||||
```
|
||||
Error: --auto requires --repos to specify which repos to include.
|
||||
|
||||
Usage:
|
||||
/gsd-new-workspace --name my-workspace --repos repo1,repo2 --auto
|
||||
```
|
||||
Exit.
|
||||
|
||||
## 4. Select Strategy
|
||||
|
||||
**If `--strategy` is provided:** Use it (validate: must be `worktree` or `clone`).
|
||||
|
||||
**If `--strategy` is NOT provided and not `--auto`:**
|
||||
|
||||
Use AskUserQuestion:
|
||||
- header: "Strategy"
|
||||
- question: "How should repos be copied into the workspace?"
|
||||
- options:
|
||||
- "Worktree (recommended) - lightweight, shares .git objects with source repo" → `worktree`
|
||||
- "Clone - fully independent copy, no connection to source repo" → `clone`
|
||||
|
||||
**If `--auto`:** Default to `worktree`.
|
||||
|
||||
## 5. Validate
|
||||
|
||||
Before creating anything, validate:
|
||||
|
||||
1. **Target path** - must not exist or must be empty:
|
||||
```bash
|
||||
if [ -d "$TARGET_PATH" ] && [ "$(ls -A "$TARGET_PATH" 2>/dev/null)" ]; then
|
||||
echo "Error: Target path already exists and is not empty: $TARGET_PATH"
|
||||
echo "Choose a different --name or --path."
|
||||
exit 1
|
||||
fi
|
||||
```
|
||||
|
||||
2. **Source repos exist and are git repos** - for each repo path:
|
||||
```bash
|
||||
if [ ! -d "$REPO_PATH/.git" ]; then
|
||||
echo "Error: Not a git repo: $REPO_PATH"
|
||||
exit 1
|
||||
fi
|
||||
```
|
||||
|
||||
3. **Worktree availability** - if strategy is `worktree` and `worktree_available` is false:
|
||||
```
|
||||
Error: git is not available. Install git or use --strategy clone.
|
||||
```
|
||||
|
||||
Report all validation errors at once, not one at a time.
|
||||
|
||||
## 6. Create Workspace
|
||||
|
||||
```bash
|
||||
mkdir -p "$TARGET_PATH"
|
||||
```
|
||||
|
||||
### For each repo:
|
||||
|
||||
**Worktree strategy:**
|
||||
```bash
|
||||
cd "$SOURCE_REPO_PATH"
|
||||
git worktree add "$TARGET_PATH/$REPO_NAME" -b "$BRANCH_NAME" 2>&1
|
||||
```
|
||||
|
||||
If `git worktree add` fails because the branch already exists, try with a timestamped branch:
|
||||
```bash
|
||||
TIMESTAMP=$(date +%Y%m%d%H%M%S)
|
||||
git worktree add "$TARGET_PATH/$REPO_NAME" -b "${BRANCH_NAME}-${TIMESTAMP}" 2>&1
|
||||
```
|
||||
|
||||
If that also fails, report the error and continue with remaining repos.
|
||||
|
||||
**Clone strategy:**
|
||||
```bash
|
||||
git clone "$SOURCE_REPO_PATH" "$TARGET_PATH/$REPO_NAME" 2>&1
|
||||
cd "$TARGET_PATH/$REPO_NAME"
|
||||
git checkout -b "$BRANCH_NAME" 2>&1
|
||||
```
|
||||
|
||||
Track results: which repos succeeded, which failed, what branch was used.
|
||||
|
||||
## 7. Write WORKSPACE.md
|
||||
|
||||
Write the workspace manifest at `$TARGET_PATH/WORKSPACE.md`:
|
||||
|
||||
```markdown
|
||||
# Workspace: $WORKSPACE_NAME
|
||||
|
||||
Created: $DATE
|
||||
Strategy: $STRATEGY
|
||||
|
||||
## Member Repos
|
||||
|
||||
| Repo | Source | Branch | Strategy |
|
||||
| ---------- | ------------ | ------- | --------- |
|
||||
| $REPO_NAME | $SOURCE_PATH | $BRANCH | $STRATEGY |
|
||||
...for each repo...
|
||||
|
||||
## Notes
|
||||
|
||||
[Add context about what this workspace is for]
|
||||
```
|
||||
|
||||
## 8. Initialize .planning/
|
||||
|
||||
```bash
|
||||
mkdir -p "$TARGET_PATH/.planning"
|
||||
```
|
||||
|
||||
## 9. Report and Next Steps
|
||||
|
||||
**If all repos succeeded:**
|
||||
|
||||
```
|
||||
Workspace created: $TARGET_PATH
|
||||
|
||||
Repos: $REPO_COUNT
|
||||
Strategy: $STRATEGY
|
||||
Branch: $BRANCH_NAME
|
||||
|
||||
Next steps:
|
||||
cd $TARGET_PATH
|
||||
/gsd-new-project # Initialize GSD in the workspace
|
||||
```
|
||||
|
||||
**If some repos failed:**
|
||||
|
||||
```
|
||||
Workspace created with $SUCCESS_COUNT of $TOTAL_COUNT repos: $TARGET_PATH
|
||||
|
||||
Succeeded: repo1, repo2
|
||||
Failed: repo3 (branch already exists), repo4 (not a git repo)
|
||||
|
||||
Next steps:
|
||||
cd $TARGET_PATH
|
||||
/gsd-new-project # Initialize GSD in the workspace
|
||||
```
|
||||
|
||||
**Offer to initialize GSD (if not `--auto`):**
|
||||
|
||||
Use AskUserQuestion:
|
||||
- header: "Initialize GSD"
|
||||
- question: "Would you like to initialize a GSD project in the new workspace?"
|
||||
- options:
|
||||
- "Yes - run /gsd-new-project" → tell user to `cd $TARGET_PATH` first, then run `/gsd-new-project`
|
||||
- "No - I'll set it up later" → done
|
||||
|
||||
</process>
|
||||
|
||||
<success_criteria>
|
||||
- [ ] Workspace directory created at target path
|
||||
- [ ] All specified repos copied (worktree or clone) into workspace
|
||||
- [ ] WORKSPACE.md manifest written with correct repo table
|
||||
- [ ] `.planning/` directory initialized at workspace root
|
||||
- [ ] User informed of workspace path and next steps
|
||||
</success_criteria>
|
||||
145
.pi/gsd/workflows/next.md
Normal file
145
.pi/gsd/workflows/next.md
Normal file
@@ -0,0 +1,145 @@
|
||||
<gsd-version v="1.12.4" />
|
||||
|
||||
<gsd-arguments>
|
||||
<settings><keep-extra-args /></settings>
|
||||
</gsd-arguments>
|
||||
|
||||
<gsd-execute>
|
||||
<shell command="pi-gsd-tools">
|
||||
<args>
|
||||
<arg string="state" />
|
||||
<arg string="reconcile" />
|
||||
<arg string="--raw" />
|
||||
</args>
|
||||
<outs>
|
||||
<suppress-errors />
|
||||
<out type="string" name="reconcile-result" />
|
||||
</outs>
|
||||
</shell>
|
||||
<shell command="pi-gsd-tools">
|
||||
<args>
|
||||
<arg string="state" />
|
||||
<arg string="json" />
|
||||
<arg string="--raw" />
|
||||
</args>
|
||||
<outs>
|
||||
<out type="string" name="state" />
|
||||
</outs>
|
||||
</shell>
|
||||
<shell command="pi-gsd-tools">
|
||||
<args>
|
||||
<arg string="progress" />
|
||||
<arg string="json" />
|
||||
<arg string="--raw" />
|
||||
</args>
|
||||
<outs>
|
||||
<out type="string" name="progress" />
|
||||
</outs>
|
||||
</shell>
|
||||
</gsd-execute>
|
||||
|
||||
## Context (pre-injected)
|
||||
|
||||
**State:**
|
||||
<gsd-paste name="state" />
|
||||
|
||||
**Progress:**
|
||||
<gsd-paste name="progress" />
|
||||
|
||||
<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
|
||||
pi-gsd-tools 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>
|
||||
94
.pi/gsd/workflows/node-repair.md
Normal file
94
.pi/gsd/workflows/node-repair.md
Normal file
@@ -0,0 +1,94 @@
|
||||
<gsd-version v="1.12.4" />
|
||||
|
||||
<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>
|
||||
158
.pi/gsd/workflows/note.md
Normal file
158
.pi/gsd/workflows/note.md
Normal file
@@ -0,0 +1,158 @@
|
||||
<gsd-version v="1.12.4" />
|
||||
|
||||
<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**: `.agent/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 `.agent/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 `.agent/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 (.agent/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 `.agent/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>
|
||||
220
.pi/gsd/workflows/pause-work.md
Normal file
220
.pi/gsd/workflows/pause-work.md
Normal file
@@ -0,0 +1,220 @@
|
||||
<gsd-version v="1.12.4" />
|
||||
|
||||
<gsd-arguments>
|
||||
<settings><keep-extra-args /></settings>
|
||||
</gsd-arguments>
|
||||
|
||||
<gsd-execute>
|
||||
<shell command="pi-gsd-tools">
|
||||
<args>
|
||||
<arg string="state" />
|
||||
<arg string="json" />
|
||||
<arg string="--raw" />
|
||||
</args>
|
||||
<outs>
|
||||
<out type="string" name="state" />
|
||||
</outs>
|
||||
</shell>
|
||||
<shell command="pi-gsd-tools">
|
||||
<args>
|
||||
<arg string="current-timestamp" />
|
||||
<arg string="--raw" />
|
||||
</args>
|
||||
<outs>
|
||||
<out type="string" name="timestamp" />
|
||||
</outs>
|
||||
</shell>
|
||||
<!-- CLEAR _auto_chain_active - chain ends here -->
|
||||
<shell command="pi-gsd-tools">
|
||||
<args>
|
||||
<arg string="config-set" />
|
||||
<arg string="workflow._auto_chain_active" />
|
||||
<arg string="false" />
|
||||
</args>
|
||||
<outs><suppress-errors /></outs>
|
||||
</shell>
|
||||
</gsd-execute>
|
||||
|
||||
## Context (pre-injected)
|
||||
|
||||
**State:**
|
||||
<gsd-paste name="state" />
|
||||
|
||||
**Timestamp:** <gsd-paste name="timestamp" />
|
||||
|
||||
<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 || true) | head -1 | grep -oP 'phases/\K[^/]+' || true
|
||||
```
|
||||
|
||||
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 || true
|
||||
```
|
||||
Report any summaries with placeholder content as incomplete items.
|
||||
</step>
|
||||
|
||||
<step name="write_structured">
|
||||
**Write structured handoff to `.planning/HANDOFF.json`:**
|
||||
|
||||
```bash
|
||||
timestamp=$(pi-gsd-tools 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 the agent to understand immediately.
|
||||
|
||||
Use `current-timestamp` for last_updated field. You can use init todos (which provides timestamps) or call directly:
|
||||
```bash
|
||||
timestamp=$(pi-gsd-tools current-timestamp full --raw)
|
||||
```
|
||||
</step>
|
||||
|
||||
<step name="commit">
|
||||
```bash
|
||||
pi-gsd-tools 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>
|
||||
310
.pi/gsd/workflows/plan-milestone-gaps.md
Normal file
310
.pi/gsd/workflows/plan-milestone-gaps.md
Normal file
@@ -0,0 +1,310 @@
|
||||
<gsd-version v="1.12.4" />
|
||||
|
||||
<gsd-arguments>
|
||||
<settings><keep-extra-args /></settings>
|
||||
</gsd-arguments>
|
||||
|
||||
<gsd-execute>
|
||||
<shell command="pi-gsd-tools">
|
||||
<args>
|
||||
<arg string="roadmap" />
|
||||
<arg string="analyze" />
|
||||
<arg string="--raw" />
|
||||
</args>
|
||||
<outs>
|
||||
<out type="string" name="roadmap" />
|
||||
</outs>
|
||||
</shell>
|
||||
<shell command="pi-gsd-tools">
|
||||
<args>
|
||||
<arg string="state" />
|
||||
<arg string="json" />
|
||||
<arg string="--raw" />
|
||||
</args>
|
||||
<outs>
|
||||
<out type="string" name="state" />
|
||||
</outs>
|
||||
</shell>
|
||||
</gsd-execute>
|
||||
|
||||
## Context (pre-injected)
|
||||
|
||||
**Roadmap:**
|
||||
<gsd-paste name="roadmap" />
|
||||
|
||||
**State:**
|
||||
<gsd-paste name="state" />
|
||||
|
||||
<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 || true) | 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
|
||||
HIGHEST=$(pi-gsd-tools phases list --pick 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
|
||||
pi-gsd-tools 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>`/new` 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>
|
||||
119
.pi/gsd/workflows/plan-milestone.md
Normal file
119
.pi/gsd/workflows/plan-milestone.md
Normal file
@@ -0,0 +1,119 @@
|
||||
<gsd-version v="1.12.4" />
|
||||
|
||||
<gsd-arguments>
|
||||
<settings><keep-extra-args /></settings>
|
||||
<arg name="interactive" type="flag" flag="--interactive" optional />
|
||||
</gsd-arguments>
|
||||
|
||||
<gsd-execute>
|
||||
<shell command="pi-gsd-tools">
|
||||
<args>
|
||||
<arg string="roadmap" />
|
||||
<arg string="analyze" />
|
||||
<arg string="--raw" />
|
||||
</args>
|
||||
<outs>
|
||||
<out type="string" name="roadmap" />
|
||||
</outs>
|
||||
</shell>
|
||||
<shell command="pi-gsd-tools">
|
||||
<args>
|
||||
<arg string="state" />
|
||||
<arg string="json" />
|
||||
<arg string="--raw" />
|
||||
</args>
|
||||
<outs>
|
||||
<out type="string" name="state" />
|
||||
</outs>
|
||||
</shell>
|
||||
</gsd-execute>
|
||||
|
||||
## Context (pre-injected)
|
||||
|
||||
**Roadmap:**
|
||||
<gsd-paste name="roadmap" />
|
||||
|
||||
**State:**
|
||||
<gsd-paste name="state" />
|
||||
|
||||
# plan-milestone workflow
|
||||
|
||||
Plan all unplanned phases in the current milestone in a single orchestrated session.
|
||||
|
||||
---
|
||||
|
||||
## Mode Selection (step 0 - always first)
|
||||
|
||||
Ask the user ONE binary question:
|
||||
|
||||
> **"Should I ask you questions during planning, or plan everything silently and flag doubts at the end?"**
|
||||
>
|
||||
> - **Interactive** - I'll ask targeted questions per phase when I hit real ambiguity
|
||||
> - **Silent** - Plan autonomously; collect flags for review at the end
|
||||
|
||||
Store the answer as `MODE` (interactive | silent). Do not ask again.
|
||||
|
||||
---
|
||||
|
||||
## Phase Discovery
|
||||
|
||||
```bash
|
||||
pi-gsd-tools roadmap analyze --raw
|
||||
pi-gsd-tools state json --raw
|
||||
```
|
||||
|
||||
Identify all phases with **no PLAN.md files** in their phase directory.
|
||||
Skip phases already Complete or already planned. Work in roadmap order.
|
||||
|
||||
---
|
||||
|
||||
## Per-Phase Planning Loop
|
||||
|
||||
For each unplanned phase `N`:
|
||||
|
||||
### 1. Scope Pre-check
|
||||
|
||||
Read `.planning/REQUIREMENTS.md` and the phase entry from ROADMAP.md (goal + success criteria).
|
||||
|
||||
Ask internally: *"Does executing this phase risk implementing anything not covered by active requirements, or conflict with what previous phases were meant to deliver?"*
|
||||
|
||||
Classify risk:
|
||||
- **low** - continue silently
|
||||
- **medium** - log in scope-notes, continue
|
||||
- **high + interactive** - surface to user before proceeding, ask whether to adjust or continue
|
||||
- **high + silent** - log prominently, continue, surface in final summary
|
||||
|
||||
### 2. Plan the Phase
|
||||
|
||||
Invoke:
|
||||
```
|
||||
Skill(skill="gsd-plan-phase", args="${N} --skip-research")
|
||||
```
|
||||
Unless the phase has no RESEARCH.md yet → drop `--skip-research`.
|
||||
In **silent** mode, append `--auto` to suppress discussion prompts inside plan-phase.
|
||||
|
||||
### 3. Checkpoint
|
||||
|
||||
After each phase plan is committed:
|
||||
```bash
|
||||
pi-gsd-tools state update current_phase ${N}
|
||||
```
|
||||
|
||||
Announce: `✓ Phase ${N} planned - ${plan_count} plan(s) created`
|
||||
|
||||
Check context remaining. If < 25%: stop immediately, emit summary of planned vs remaining phases, suggest `/gsd-plan-milestone --from ${next_unplanned}` to continue.
|
||||
|
||||
---
|
||||
|
||||
## Final Summary
|
||||
|
||||
```
|
||||
━━ plan-milestone complete ━━━━━━━━━━━━━━━━━━━━━━━
|
||||
✓ Planned: [phase list]
|
||||
⚠ Flags: [scope notes from high-risk pre-checks]
|
||||
↳ Next: /gsd-execute-milestone
|
||||
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
|
||||
```
|
||||
|
||||
If flags exist and `MODE=interactive`: present them for user review before suggesting execute-milestone.
|
||||
If flags exist and `MODE=silent`: present all flags together at the end.
|
||||
913
.pi/gsd/workflows/plan-phase.md
Normal file
913
.pi/gsd/workflows/plan-phase.md
Normal file
@@ -0,0 +1,913 @@
|
||||
<gsd-version v="1.12.4" />
|
||||
|
||||
<gsd-arguments>
|
||||
<settings>
|
||||
<keep-extra-args />
|
||||
</settings>
|
||||
<arg name="auto-chain-active" type="flag" flag="--auto" optional />
|
||||
<arg name="skip-research" type="flag" flag="--skip-research" optional />
|
||||
<arg name="gaps" type="flag" flag="--gaps" optional />
|
||||
<arg name="skip-verify" type="flag" flag="--skip-verify" optional />
|
||||
<arg name="reviews" type="flag" flag="--reviews" optional />
|
||||
<arg name="text" type="flag" flag="--text" optional />
|
||||
<arg name="phase" type="number" />
|
||||
</gsd-arguments>
|
||||
|
||||
<gsd-execute>
|
||||
<shell command="pi-gsd-tools">
|
||||
<args>
|
||||
<arg string="init" />
|
||||
<arg string="plan-phase" />
|
||||
<arg name="phase" wrap='"' />
|
||||
</args>
|
||||
<outs>
|
||||
<out type="string" name="phase-data" />
|
||||
</outs>
|
||||
</shell>
|
||||
<shell command="pi-gsd-tools">
|
||||
<args>
|
||||
<arg string="state" />
|
||||
<arg string="json" />
|
||||
<arg string="--raw" />
|
||||
</args>
|
||||
<outs>
|
||||
<out type="string" name="state" />
|
||||
</outs>
|
||||
</shell>
|
||||
<shell command="pi-gsd-tools">
|
||||
<args>
|
||||
<arg string="roadmap" />
|
||||
<arg string="get-phase" />
|
||||
<arg name="phase" wrap='"' />
|
||||
</args>
|
||||
<outs>
|
||||
<out type="string" name="roadmap-phase" />
|
||||
</outs>
|
||||
</shell>
|
||||
</gsd-execute>
|
||||
## Planning Context (pre-injected by WXP)
|
||||
|
||||
**Phase:** <gsd-paste name="phase" />
|
||||
|
||||
**Project State:**
|
||||
<gsd-paste name="state" />
|
||||
|
||||
**Phase Roadmap:**
|
||||
<gsd-paste name="roadmap-phase" />
|
||||
|
||||
|
||||
---
|
||||
|
||||
<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.
|
||||
|
||||
@.pi/gsd/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):
|
||||
|
||||
<!-- Init data pre-injected above via WXP -->
|
||||
|
||||
Parse JSON for: `researcher_model`, `planner_model`, `checker_model`, `research_enabled`, `plan_checker_enabled`, `nyquist_validation_enabled`, `commit_docs`, `text_mode`, `phase_found`, `phase_dir`, `phase_number`, `phase_name`, `phase_slug`, `padded_phase`, `has_research`, `has_context`, `has_reviews`, `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`, `reviews_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>`, `--reviews`, `--text`).
|
||||
|
||||
Set `TEXT_MODE=true` if `--text` is present in $ARGUMENTS OR `text_mode` from init JSON is `true`. When `TEXT_MODE` is active, replace every `AskUserQuestion` call with a plain-text numbered list and ask the user to type their choice number. This is required for Claude Code remote sessions (`/rc` mode) where TUI menus don't work through the the agent App.
|
||||
|
||||
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`.
|
||||
|
||||
## 2.5. Validate `--reviews` Prerequisite
|
||||
|
||||
**Skip if:** No `--reviews` flag.
|
||||
|
||||
**If `--reviews` AND `--gaps`:** Error - cannot combine `--reviews` with `--gaps`. These are conflicting modes.
|
||||
|
||||
**If `--reviews` AND `has_reviews` is false (no REVIEWS.md in phase dir):**
|
||||
|
||||
Error:
|
||||
```
|
||||
No REVIEWS.md found for Phase {N}. Run reviews first:
|
||||
|
||||
/gsd-review --phase {N}
|
||||
|
||||
Then re-run /gsd-plan-phase {N} --reviews
|
||||
```
|
||||
Exit workflow.
|
||||
|
||||
## 3. Validate Phase
|
||||
|
||||
```bash
|
||||
PHASE_INFO=$(pi-gsd-tools 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 "the agent'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]
|
||||
|
||||
### the agent'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
|
||||
pi-gsd-tools 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):**
|
||||
|
||||
Read discuss mode for context gate label:
|
||||
```bash
|
||||
DISCUSS_MODE=$(pi-gsd-tools config-get workflow.discuss_mode 2>/dev/null || echo "discuss")
|
||||
```
|
||||
|
||||
If `TEXT_MODE` is true, present as a plain-text numbered list:
|
||||
```
|
||||
No CONTEXT.md found for Phase {X}. Plans will use research and requirements only - your design preferences won't be included.
|
||||
|
||||
1. Continue without context - Plan using research + requirements only
|
||||
[If DISCUSS_MODE is "assumptions":]
|
||||
2. Gather context (assumptions mode) - Analyze codebase and surface assumptions before planning
|
||||
[If DISCUSS_MODE is "discuss" or unset:]
|
||||
2. Run discuss-phase first - Capture design decisions before planning
|
||||
|
||||
Enter number:
|
||||
```
|
||||
|
||||
Otherwise 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
|
||||
If `DISCUSS_MODE` is `"assumptions"`:
|
||||
- "Gather context (assumptions mode)" - Analyze codebase and surface assumptions before planning
|
||||
If `DISCUSS_MODE` is `"discuss"` (or unset):
|
||||
- "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_WS}:
|
||||
|
||||
/gsd-discuss-phase {X} ${GSD_WS}
|
||||
```
|
||||
**Exit the plan-phase workflow. Do not continue.**
|
||||
|
||||
## 5. Handle Research
|
||||
|
||||
**Skip if:** `--gaps` flag or `--skip-research` flag or `--reviews` 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:
|
||||
|
||||
If `TEXT_MODE` is true, present as a plain-text numbered list:
|
||||
```
|
||||
Research before planning Phase {X}: {phase_name}?
|
||||
|
||||
1. Research first (Recommended) - Investigate domain, patterns, and dependencies before planning. Best for new features, unfamiliar integrations, or architectural changes.
|
||||
2. Skip research - Plan directly from context and requirements. Best for bug fixes, simple refactors, or well-understood tasks.
|
||||
|
||||
Enter number:
|
||||
```
|
||||
|
||||
Otherwise use AskUserQuestion:
|
||||
```
|
||||
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=$(pi-gsd-tools roadmap get-phase "${PHASE}" --pick 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>
|
||||
|
||||
${AGENT_SKILLS_RESEARCHER}
|
||||
|
||||
<additional_context>
|
||||
**Phase description:** {phase_description}
|
||||
**Phase requirement IDs (MUST address):** {phase_req_ids}
|
||||
|
||||
**Project instructions:** Read ./GEMINI.md if exists - follow project-specific guidelines
|
||||
**Project skills:** Check .agent/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 || true
|
||||
```
|
||||
|
||||
**If found:**
|
||||
1. Read template: `.pi/gsd/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=$(pi-gsd-tools config-get workflow.ui_phase 2>/dev/null || echo "true")
|
||||
UI_GATE_CFG=$(pi-gsd-tools 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=$(pi-gsd-tools 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`:**
|
||||
|
||||
If `TEXT_MODE` is true, present as a plain-text numbered list:
|
||||
```
|
||||
Phase {N} has frontend indicators but no UI-SPEC.md. Generate a design contract before planning?
|
||||
|
||||
1. Generate UI-SPEC first - Run /gsd-ui-phase {N} then re-run /gsd-plan-phase {N}
|
||||
2. Continue without UI-SPEC
|
||||
3. Not a frontend phase
|
||||
|
||||
Enter number:
|
||||
```
|
||||
|
||||
Otherwise 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} ${GSD_WS}` then re-run `/gsd-plan-phase {N} ${GSD_WS}`". 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 || true
|
||||
```
|
||||
|
||||
**If exists AND `--reviews` flag:** Skip prompt - go straight to replanning (the purpose of `--reviews` is to replan with review feedback).
|
||||
|
||||
**If exists AND no `--reviews` flag:** Offer: 1) Add more plans, 2) View existing, 3) Replan from scratch.
|
||||
|
||||
## 7. Use Context Paths from INIT
|
||||
|
||||
Extract from INIT JSON:
|
||||
|
||||
```bash
|
||||
_gsd_field() { node -e "const o=JSON.parse(process.argv[1]); const v=o[process.argv[2]]; process.stdout.write(v==null?'':String(v))" "$1" "$2"; }
|
||||
STATE_PATH=$(_gsd_field "$INIT" state_path)
|
||||
ROADMAP_PATH=$(_gsd_field "$INIT" roadmap_path)
|
||||
REQUIREMENTS_PATH=$(_gsd_field "$INIT" requirements_path)
|
||||
RESEARCH_PATH=$(_gsd_field "$INIT" research_path)
|
||||
VERIFICATION_PATH=$(_gsd_field "$INIT" verification_path)
|
||||
UAT_PATH=$(_gsd_field "$INIT" uat_path)
|
||||
CONTEXT_PATH=$(_gsd_field "$INIT" context_path)
|
||||
REVIEWS_PATH=$(_gsd_field "$INIT" reviews_path)
|
||||
```
|
||||
|
||||
## 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 ${GSD_WS}`
|
||||
2. Disable Nyquist with the exact command:
|
||||
`pi-gsd-tools 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 | reviews}
|
||||
|
||||
<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)
|
||||
- {reviews_path} (Cross-AI Review Feedback - if --reviews)
|
||||
- {UI_SPEC_PATH} (UI Design Contract - visual/interaction specs, if exists)
|
||||
</files_to_read>
|
||||
|
||||
${AGENT_SKILLS_PLANNER}
|
||||
|
||||
**Phase requirement IDs (every ID MUST appear in a plan's `requirements` field):** {phase_req_ids}
|
||||
|
||||
**Project instructions:** Read ./GEMINI.md if exists - follow project-specific guidelines
|
||||
**Project skills:** Check .agent/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>
|
||||
|
||||
${AGENT_SKILLS_CHECKER}
|
||||
|
||||
**Phase requirement IDs (MUST ALL be covered):** {phase_req_ids}
|
||||
|
||||
**Project instructions:** Read ./GEMINI.md if exists - verify plans honor project guidelines
|
||||
**Project skills:** Check .agent/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>
|
||||
|
||||
${AGENT_SKILLS_PLANNER}
|
||||
|
||||
**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
|
||||
```
|
||||
|
||||
If `TEXT_MODE` is true, present as a plain-text numbered list (options already shown in the block above). Otherwise 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
|
||||
pi-gsd-tools config-set workflow._auto_chain_active false 2>/dev/null
|
||||
fi
|
||||
```
|
||||
3. Read both the chain flag and user preference:
|
||||
```bash
|
||||
AUTO_CHAIN=$(pi-gsd-tools config-get workflow._auto_chain_active 2>/dev/null || echo "false")
|
||||
AUTO_CFG=$(pi-gsd-tools 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 ${GSD_WS}")
|
||||
```
|
||||
|
||||
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 ${GSD_WS}
|
||||
```
|
||||
- **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} ${GSD_WS}
|
||||
```
|
||||
|
||||
**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} ${GSD_WS}
|
||||
|
||||
<sub>/new first → fresh context window</sub>
|
||||
|
||||
───────────────────────────────────────────────────────────────
|
||||
|
||||
**Also available:**
|
||||
- cat .planning/phases/{phase-dir}/*-PLAN.md - review plans
|
||||
- /gsd-plan-phase {X} --research - re-research first
|
||||
- /gsd-review --phase {X} --all - peer review plans with external AIs
|
||||
- /gsd-plan-phase {X} --reviews - replan incorporating review feedback
|
||||
|
||||
───────────────────────────────────────────────────────────────
|
||||
</offer_next>
|
||||
|
||||
<windows_troubleshooting>
|
||||
**Windows users:** If plan-phase freezes during agent spawning (common on Windows due to
|
||||
stdio deadlocks with MCP servers - see Claude Code issue anthropics/claude-code#28126):
|
||||
|
||||
1. **Force-kill:** Close the terminal (Ctrl+C may not work)
|
||||
2. **Clean up orphaned processes:**
|
||||
```powershell
|
||||
# Kill orphaned node processes from stale MCP servers
|
||||
Get-Process node -ErrorAction SilentlyContinue | Where-Object {$_.StartTime -lt (Get-Date).AddHours(-1)} | Stop-Process -Force
|
||||
```
|
||||
3. **Clean up stale task directories:**
|
||||
```powershell
|
||||
# Remove stale subagent task dirs (Claude Code never cleans these on crash)
|
||||
Remove-Item -Recurse -Force "$env:USERPROFILE\.claude\tasks\*" -ErrorAction SilentlyContinue
|
||||
```
|
||||
4. **Reduce MCP server count:** Temporarily disable non-essential MCP servers in settings.json
|
||||
5. **Retry:** Restart Claude Code and run `/gsd-plan-phase` again
|
||||
|
||||
If freezes persist, try `--skip-research` to reduce the agent chain from 3 to 2 agents:
|
||||
```
|
||||
/gsd-plan-phase N --skip-research
|
||||
```
|
||||
</windows_troubleshooting>
|
||||
|
||||
<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>
|
||||
196
.pi/gsd/workflows/plant-seed.md
Normal file
196
.pi/gsd/workflows/plant-seed.md
Normal file
@@ -0,0 +1,196 @@
|
||||
<gsd-version v="1.12.4" />
|
||||
|
||||
<gsd-arguments>
|
||||
<settings><keep-extra-args /></settings>
|
||||
<arg name="idea" type="string" optional />
|
||||
</gsd-arguments>
|
||||
|
||||
<gsd-execute>
|
||||
<shell command="pi-gsd-tools">
|
||||
<args>
|
||||
<arg string="state" />
|
||||
<arg string="json" />
|
||||
<arg string="--raw" />
|
||||
</args>
|
||||
<outs>
|
||||
<out type="string" name="state" />
|
||||
</outs>
|
||||
</shell>
|
||||
</gsd-execute>
|
||||
|
||||
## Context (pre-injected)
|
||||
|
||||
**Idea:** <gsd-paste name="idea" />
|
||||
|
||||
**State:**
|
||||
<gsd-paste name="state" />
|
||||
|
||||
<purpose>
|
||||
Capture a forward-looking idea as a structured seed file with trigger conditions.
|
||||
Seeds auto-surface during /gsd-new-milestone when trigger conditions match the
|
||||
new milestone's scope.
|
||||
|
||||
Seeds beat deferred items because they:
|
||||
- Preserve WHY the idea matters (not just WHAT)
|
||||
- Define WHEN to surface (trigger conditions, not manual scanning)
|
||||
- Track breadcrumbs (code references, related decisions)
|
||||
- Auto-present at the right time via new-milestone scan
|
||||
</purpose>
|
||||
|
||||
<process>
|
||||
|
||||
<step name="parse_idea">
|
||||
Parse `$ARGUMENTS` for the idea summary.
|
||||
|
||||
If empty, ask:
|
||||
```
|
||||
What's the idea? (one sentence)
|
||||
```
|
||||
|
||||
Store as `$IDEA`.
|
||||
</step>
|
||||
|
||||
<step name="create_seed_dir">
|
||||
```bash
|
||||
mkdir -p .planning/seeds
|
||||
```
|
||||
</step>
|
||||
|
||||
<step name="gather_context">
|
||||
Ask focused questions to build a complete seed:
|
||||
|
||||
```
|
||||
AskUserQuestion(
|
||||
header: "Trigger",
|
||||
question: "When should this idea surface? (e.g., 'when we add user accounts', 'next major version', 'when performance becomes a priority')",
|
||||
options: [] // freeform
|
||||
)
|
||||
```
|
||||
|
||||
Store as `$TRIGGER`.
|
||||
|
||||
```
|
||||
AskUserQuestion(
|
||||
header: "Why",
|
||||
question: "Why does this matter? What problem does it solve or what opportunity does it create?",
|
||||
options: []
|
||||
)
|
||||
```
|
||||
|
||||
Store as `$WHY`.
|
||||
|
||||
```
|
||||
AskUserQuestion(
|
||||
header: "Scope",
|
||||
question: "How big is this? (rough estimate)",
|
||||
options: [
|
||||
{ label: "Small", description: "A few hours - could be a quick task" },
|
||||
{ label: "Medium", description: "A phase or two - needs planning" },
|
||||
{ label: "Large", description: "A full milestone - significant effort" }
|
||||
]
|
||||
)
|
||||
```
|
||||
|
||||
Store as `$SCOPE`.
|
||||
</step>
|
||||
|
||||
<step name="collect_breadcrumbs">
|
||||
Search the codebase for relevant references:
|
||||
|
||||
```bash
|
||||
# Find files related to the idea keywords
|
||||
grep -rl "$KEYWORD" --include="*.ts" --include="*.js" --include="*.md" . 2>/dev/null | head -10
|
||||
```
|
||||
|
||||
Also check:
|
||||
- Current STATE.md for related decisions
|
||||
- ROADMAP.md for related phases
|
||||
- todos/ for related captured ideas
|
||||
|
||||
Store relevant file paths as `$BREADCRUMBS`.
|
||||
</step>
|
||||
|
||||
<step name="generate_seed_id">
|
||||
```bash
|
||||
# Find next seed number
|
||||
EXISTING=$( (ls .planning/seeds/SEED-*.md 2>/dev/null || true) | wc -l )
|
||||
NEXT=$((EXISTING + 1))
|
||||
PADDED=$(printf "%03d" $NEXT)
|
||||
```
|
||||
|
||||
Generate slug from idea summary.
|
||||
</step>
|
||||
|
||||
<step name="write_seed">
|
||||
Write `.planning/seeds/SEED-{PADDED}-{slug}.md`:
|
||||
|
||||
```markdown
|
||||
---
|
||||
id: SEED-{PADDED}
|
||||
status: dormant
|
||||
planted: {ISO date}
|
||||
planted_during: {current milestone/phase from STATE.md}
|
||||
trigger_when: {$TRIGGER}
|
||||
scope: {$SCOPE}
|
||||
---
|
||||
|
||||
# SEED-{PADDED}: {$IDEA}
|
||||
|
||||
## Why This Matters
|
||||
|
||||
{$WHY}
|
||||
|
||||
## When to Surface
|
||||
|
||||
**Trigger:** {$TRIGGER}
|
||||
|
||||
This seed should be presented during `/gsd-new-milestone` when the milestone
|
||||
scope matches any of these conditions:
|
||||
- {trigger condition 1}
|
||||
- {trigger condition 2}
|
||||
|
||||
## Scope Estimate
|
||||
|
||||
**{$SCOPE}** - {elaboration based on scope choice}
|
||||
|
||||
## Breadcrumbs
|
||||
|
||||
Related code and decisions found in the current codebase:
|
||||
|
||||
{list of $BREADCRUMBS with file paths}
|
||||
|
||||
## Notes
|
||||
|
||||
{any additional context from the current session}
|
||||
```
|
||||
</step>
|
||||
|
||||
<step name="commit_seed">
|
||||
```bash
|
||||
pi-gsd-tools commit "docs: plant seed - {$IDEA}" --files .planning/seeds/SEED-{PADDED}-{slug}.md
|
||||
```
|
||||
</step>
|
||||
|
||||
<step name="confirm">
|
||||
```
|
||||
✅ Seed planted: SEED-{PADDED}
|
||||
|
||||
"{$IDEA}"
|
||||
Trigger: {$TRIGGER}
|
||||
Scope: {$SCOPE}
|
||||
File: .planning/seeds/SEED-{PADDED}-{slug}.md
|
||||
|
||||
This seed will surface automatically when you run /gsd-new-milestone
|
||||
and the milestone scope matches the trigger condition.
|
||||
```
|
||||
</step>
|
||||
|
||||
</process>
|
||||
|
||||
<success_criteria>
|
||||
- [ ] Seed file created in .planning/seeds/
|
||||
- [ ] Frontmatter includes status, trigger, scope
|
||||
- [ ] Breadcrumbs collected from codebase
|
||||
- [ ] Committed to git
|
||||
- [ ] User shown confirmation with trigger info
|
||||
</success_criteria>
|
||||
131
.pi/gsd/workflows/pr-branch.md
Normal file
131
.pi/gsd/workflows/pr-branch.md
Normal file
@@ -0,0 +1,131 @@
|
||||
<gsd-version v="1.12.4" />
|
||||
|
||||
<purpose>
|
||||
Create a clean branch for pull requests by filtering out .planning/ commits.
|
||||
The PR branch contains only code changes - reviewers don't see GSD artifacts
|
||||
(PLAN.md, SUMMARY.md, STATE.md, CONTEXT.md, etc.).
|
||||
|
||||
Uses git cherry-pick with path filtering to rebuild a clean history.
|
||||
</purpose>
|
||||
|
||||
<process>
|
||||
|
||||
<step name="detect_state">
|
||||
Parse `$ARGUMENTS` for target branch (default: `main`).
|
||||
|
||||
```bash
|
||||
CURRENT_BRANCH=$(git branch --show-current)
|
||||
TARGET=${1:-main}
|
||||
```
|
||||
|
||||
Check preconditions:
|
||||
- Must be on a feature branch (not main/master)
|
||||
- Must have commits ahead of target
|
||||
|
||||
```bash
|
||||
AHEAD=$(git rev-list --count "$TARGET".."$CURRENT_BRANCH" 2>/dev/null)
|
||||
if [ "$AHEAD" = "0" ]; then
|
||||
echo "No commits ahead of $TARGET - nothing to filter."
|
||||
exit 0
|
||||
fi
|
||||
```
|
||||
|
||||
Display:
|
||||
```
|
||||
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
|
||||
GSD ► PR BRANCH
|
||||
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
|
||||
|
||||
Branch: {CURRENT_BRANCH}
|
||||
Target: {TARGET}
|
||||
Commits: {AHEAD} ahead
|
||||
```
|
||||
</step>
|
||||
|
||||
<step name="analyze_commits">
|
||||
Classify commits:
|
||||
|
||||
```bash
|
||||
# Get all commits ahead of target
|
||||
git log --oneline "$TARGET".."$CURRENT_BRANCH" --no-merges
|
||||
```
|
||||
|
||||
For each commit, check if it ONLY touches .planning/ files:
|
||||
|
||||
```bash
|
||||
# For each commit hash
|
||||
FILES=$(git diff-tree --no-commit-id --name-only -r $HASH)
|
||||
ALL_PLANNING=$(echo "$FILES" | grep -v "^\.planning/" | wc -l)
|
||||
```
|
||||
|
||||
Classify:
|
||||
- **Code commits**: Touch at least one non-.planning/ file → INCLUDE
|
||||
- **Planning-only commits**: Touch only .planning/ files → EXCLUDE
|
||||
- **Mixed commits**: Touch both → INCLUDE (planning changes come along)
|
||||
|
||||
Display analysis:
|
||||
```
|
||||
Commits to include: {N} (code changes)
|
||||
Commits to exclude: {N} (planning-only)
|
||||
Mixed commits: {N} (code + planning - included)
|
||||
```
|
||||
</step>
|
||||
|
||||
<step name="create_pr_branch">
|
||||
```bash
|
||||
PR_BRANCH="${CURRENT_BRANCH}-pr"
|
||||
|
||||
# Create PR branch from target
|
||||
git checkout -b "$PR_BRANCH" "$TARGET"
|
||||
```
|
||||
|
||||
Cherry-pick only code commits (in order):
|
||||
|
||||
```bash
|
||||
for HASH in $CODE_COMMITS; do
|
||||
git cherry-pick "$HASH" --no-commit
|
||||
# Remove any .planning/ files that came along in mixed commits
|
||||
git rm -r --cached .planning/ 2>/dev/null || true
|
||||
git commit -C "$HASH"
|
||||
done
|
||||
```
|
||||
|
||||
Return to original branch:
|
||||
```bash
|
||||
git checkout "$CURRENT_BRANCH"
|
||||
```
|
||||
</step>
|
||||
|
||||
<step name="verify">
|
||||
```bash
|
||||
# Verify no .planning/ files in PR branch
|
||||
PLANNING_FILES=$(git diff --name-only "$TARGET".."$PR_BRANCH" | grep "^\.planning/" | wc -l)
|
||||
TOTAL_FILES=$(git diff --name-only "$TARGET".."$PR_BRANCH" | wc -l)
|
||||
PR_COMMITS=$(git rev-list --count "$TARGET".."$PR_BRANCH")
|
||||
```
|
||||
|
||||
Display results:
|
||||
```
|
||||
✅ PR branch created: {PR_BRANCH}
|
||||
|
||||
Original: {AHEAD} commits, {ORIGINAL_FILES} files
|
||||
PR branch: {PR_COMMITS} commits, {TOTAL_FILES} files
|
||||
Planning files: {PLANNING_FILES} (should be 0)
|
||||
|
||||
Next steps:
|
||||
git push origin {PR_BRANCH}
|
||||
gh pr create --base {TARGET} --head {PR_BRANCH}
|
||||
|
||||
Or use /gsd-ship to create the PR automatically.
|
||||
```
|
||||
</step>
|
||||
|
||||
</process>
|
||||
|
||||
<success_criteria>
|
||||
- [ ] PR branch created from target
|
||||
- [ ] Planning-only commits excluded
|
||||
- [ ] No .planning/ files in PR branch diff
|
||||
- [ ] Commit messages preserved from original
|
||||
- [ ] User shown next steps
|
||||
</success_criteria>
|
||||
498
.pi/gsd/workflows/profile-user.md
Normal file
498
.pi/gsd/workflows/profile-user.md
Normal file
@@ -0,0 +1,498 @@
|
||||
<gsd-version v="1.12.4" />
|
||||
|
||||
<gsd-arguments>
|
||||
<settings><keep-extra-args /></settings>
|
||||
</gsd-arguments>
|
||||
|
||||
<gsd-execute>
|
||||
<shell command="pi-gsd-tools">
|
||||
<args>
|
||||
<arg string="scan-sessions" />
|
||||
<arg string="--json" />
|
||||
</args>
|
||||
<outs>
|
||||
<suppress-errors />
|
||||
<out type="string" name="scan-result" />
|
||||
</outs>
|
||||
</shell>
|
||||
<shell command="pi-gsd-tools">
|
||||
<args>
|
||||
<arg string="profile-sample" />
|
||||
<arg string="--json" />
|
||||
</args>
|
||||
<outs>
|
||||
<suppress-errors />
|
||||
<out type="string" name="sample-result" />
|
||||
</outs>
|
||||
</shell>
|
||||
<shell command="pi-gsd-tools">
|
||||
<args>
|
||||
<arg string="state" />
|
||||
<arg string="json" />
|
||||
<arg string="--raw" />
|
||||
</args>
|
||||
<outs>
|
||||
<suppress-errors />
|
||||
<out type="string" name="state" />
|
||||
</outs>
|
||||
</shell>
|
||||
</gsd-execute>
|
||||
|
||||
## Context (pre-injected)
|
||||
|
||||
**Scan Result:**
|
||||
<gsd-paste name="scan-result" />
|
||||
|
||||
**State:**
|
||||
<gsd-paste name="state" />
|
||||
|
||||
<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 pi-gsd-tools 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:
|
||||
- @.pi/gsd/references/ui-brand.md (display patterns)
|
||||
- @.pi/gsd/agents/gsd-user-profiler.md (profiler agent definition)
|
||||
- @.pi/gsd/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=".pi/gsd/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 ".pi/gsd/USER-PROFILE.md" ".pi/gsd/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
|
||||
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
|
||||
|
||||
the agent starts every conversation generic. A profile teaches the agent
|
||||
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 the agent |
|
||||
| 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 .pi/gsd/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=$(pi-gsd-tools 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=$(pi-gsd-tools 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 `.pi/gsd/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: @.pi/gsd/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=$(pi-gsd-tools 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=$(pi-gsd-tools 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
|
||||
pi-gsd-tools write-profile --input "$ANALYSIS_PATH" --json 2>/dev/null
|
||||
```
|
||||
|
||||
Display: "✓ Profile written to .pi/gsd/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 the agent 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"
|
||||
- "GEMINI.md profile section" -- "Add profile to this project's GEMINI.md"
|
||||
- "Global GEMINI.md" -- "Add profile to .agent/GEMINI.md for all projects"
|
||||
|
||||
**If no artifacts selected:** Display "No artifacts generated. Your profile is saved at .pi/gsd/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
|
||||
pi-gsd-tools generate-dev-preferences --analysis "$ANALYSIS_PATH" --json 2>/dev/null
|
||||
```
|
||||
|
||||
Display: "✓ Generated /gsd-dev-preferences at .agent/commands/gsd/dev-preferences.md"
|
||||
|
||||
**For GEMINI.md profile section (if selected):**
|
||||
|
||||
```bash
|
||||
pi-gsd-tools generate-claude-profile --analysis "$ANALYSIS_PATH" --json 2>/dev/null
|
||||
```
|
||||
|
||||
Display: "✓ Added profile section to GEMINI.md"
|
||||
|
||||
**For Global GEMINI.md (if selected):**
|
||||
|
||||
```bash
|
||||
pi-gsd-tools generate-claude-profile --analysis "$ANALYSIS_PATH" --global --json 2>/dev/null
|
||||
```
|
||||
|
||||
Display: "✓ Added profile section to .agent/GEMINI.md"
|
||||
|
||||
**Error handling:** If any pi-gsd-tools 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=".pi/gsd/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: .pi/gsd/USER-PROFILE.md
|
||||
```
|
||||
|
||||
Then list paths for each generated artifact:
|
||||
```
|
||||
Artifacts:
|
||||
✓ /gsd-dev-preferences .agent/commands/gsd/dev-preferences.md
|
||||
✓ GEMINI.md section ./GEMINI.md
|
||||
✓ Global GEMINI.md .agent/GEMINI.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 pi-gsd-tools subcommands
|
||||
- [ ] Refresh diff shows changed dimensions when --refresh was used
|
||||
- [ ] Temp files cleaned up on completion
|
||||
</success_criteria>
|
||||
563
.pi/gsd/workflows/progress.md
Normal file
563
.pi/gsd/workflows/progress.md
Normal file
@@ -0,0 +1,563 @@
|
||||
<gsd-version v="1.12.4" />
|
||||
|
||||
<gsd-arguments>
|
||||
<settings><keep-extra-args /></settings>
|
||||
</gsd-arguments>
|
||||
|
||||
<gsd-execute>
|
||||
<shell command="pi-gsd-tools">
|
||||
<args>
|
||||
<arg string="state" />
|
||||
<arg string="reconcile" />
|
||||
<arg string="--raw" />
|
||||
</args>
|
||||
<outs>
|
||||
<suppress-errors />
|
||||
<out type="string" name="reconcile-result" />
|
||||
</outs>
|
||||
</shell>
|
||||
<shell command="pi-gsd-tools">
|
||||
<args>
|
||||
<arg string="roadmap" />
|
||||
<arg string="analyze" />
|
||||
<arg string="--raw" />
|
||||
</args>
|
||||
<outs>
|
||||
<out type="string" name="roadmap" />
|
||||
</outs>
|
||||
</shell>
|
||||
<shell command="pi-gsd-tools">
|
||||
<args>
|
||||
<arg string="state" />
|
||||
<arg string="json" />
|
||||
<arg string="--raw" />
|
||||
</args>
|
||||
<outs>
|
||||
<out type="string" name="state" />
|
||||
</outs>
|
||||
</shell>
|
||||
<shell command="pi-gsd-tools">
|
||||
<args>
|
||||
<arg string="config-get" />
|
||||
<arg string="workflow.discuss_mode" />
|
||||
<arg string="--raw" />
|
||||
</args>
|
||||
<outs>
|
||||
<suppress-errors />
|
||||
<out type="string" name="config" />
|
||||
</outs>
|
||||
</shell>
|
||||
</gsd-execute>
|
||||
|
||||
## Context (pre-injected)
|
||||
|
||||
**Roadmap:**
|
||||
<gsd-paste name="roadmap" />
|
||||
|
||||
**State:**
|
||||
<gsd-paste name="state" />
|
||||
|
||||
<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):**
|
||||
|
||||
<!-- Context pre-injected above via WXP - variables available via <gsd-paste name="..."> -->
|
||||
|
||||
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`.
|
||||
|
||||
```bash
|
||||
DISCUSS_MODE=$(pi-gsd-tools config-get workflow.discuss_mode 2>/dev/null || echo "discuss")
|
||||
```
|
||||
|
||||
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=$(pi-gsd-tools roadmap analyze)`
|
||||
- `STATE=$(pi-gsd-tools state-snapshot)`
|
||||
|
||||
This minimizes orchestrator context usage.
|
||||
</step>
|
||||
|
||||
<step name="analyze_roadmap">
|
||||
**Get comprehensive roadmap analysis (replaces manual parsing):**
|
||||
|
||||
```bash
|
||||
ROADMAP=$(pi-gsd-tools 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
|
||||
pi-gsd-tools 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 || true) | 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=$(pi-gsd-tools progress bar --raw)
|
||||
```
|
||||
|
||||
Present:
|
||||
|
||||
```
|
||||
# [Project Name]
|
||||
|
||||
**Progress:** {PROGRESS_BAR}
|
||||
**Profile:** [quality/balanced/budget/inherit]
|
||||
**Discuss mode:** {DISCUSS_MODE}
|
||||
|
||||
## 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 || true) | wc -l
|
||||
(ls -1 .planning/phases/[current-phase-dir]/*-SUMMARY.md 2>/dev/null || true) | wc -l
|
||||
(ls -1 .planning/phases/[current-phase-dir]/*-UAT.md 2>/dev/null || true) | 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 or partial (incomplete) testing
|
||||
grep -l "status: diagnosed\|status: partial" .planning/phases/[current-phase-dir]/*-UAT.md 2>/dev/null || true
|
||||
```
|
||||
|
||||
Track:
|
||||
- `uat_with_gaps`: UAT.md files with status "diagnosed" (gaps need fixing)
|
||||
- `uat_partial`: UAT.md files with status "partial" (incomplete testing)
|
||||
|
||||
**Step 1.6: Cross-phase health check**
|
||||
|
||||
Scan ALL phases in the current milestone for outstanding verification debt using the CLI (which respects milestone boundaries via `getMilestonePhaseFilter`):
|
||||
|
||||
```bash
|
||||
DEBT=$(pi-gsd-tools audit-uat --raw 2>/dev/null)
|
||||
```
|
||||
|
||||
Parse JSON for `summary.total_items` and `summary.total_files`.
|
||||
|
||||
Track: `outstanding_debt` - `summary.total_items` from the audit.
|
||||
|
||||
**If outstanding_debt > 0:** Add a warning section to the progress report output (in the `report` step), placed between "## What's Next" and the route suggestion:
|
||||
|
||||
```markdown
|
||||
## Verification Debt ({N} files across prior phases)
|
||||
|
||||
| Phase | File | Issue |
|
||||
| ------- | ---------- | ------------------------------------------------------------------------- |
|
||||
| {phase} | {filename} | {pending_count} pending, {skipped_count} skipped, {blocked_count} blocked |
|
||||
| {phase} | {filename} | human_needed - {count} items |
|
||||
|
||||
Review: `/gsd-audit-uat ${GSD_WS}` - full cross-phase audit
|
||||
Resume testing: `/gsd-verify-work {phase} ${GSD_WS}` - retest specific phase
|
||||
```
|
||||
|
||||
This is a WARNING, not a blocker - routing proceeds normally. The debt is visible so the user can make an informed choice.
|
||||
|
||||
**Step 2: Route based on counts**
|
||||
|
||||
| Condition | Meaning | Action |
|
||||
| ------------------------------- | ----------------------- | ------------------- |
|
||||
| uat_partial > 0 | UAT testing incomplete | Go to **Route E.2** |
|
||||
| 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} ${GSD_WS}`
|
||||
|
||||
<sub>`/new` first → fresh context window</sub>
|
||||
|
||||
---
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
**Route B: Phase needs planning**
|
||||
|
||||
Check if `{phase_num}-CONTEXT.md` exists in phase directory.
|
||||
|
||||
Check if current phase has UI indicators:
|
||||
|
||||
```bash
|
||||
PHASE_SECTION=$(pi-gsd-tools roadmap get-phase "${CURRENT_PHASE}" 2>/dev/null)
|
||||
PHASE_HAS_UI=$(echo "$PHASE_SECTION" | grep -qi "UI hint.*yes" && echo "true" || echo "false")
|
||||
```
|
||||
|
||||
**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} ${GSD_WS}`
|
||||
|
||||
<sub>`/new` first → fresh context window</sub>
|
||||
|
||||
---
|
||||
```
|
||||
|
||||
**If CONTEXT.md does NOT exist AND phase has UI (`PHASE_HAS_UI` is `true`):**
|
||||
|
||||
```
|
||||
---
|
||||
|
||||
## ▶ Next Up
|
||||
|
||||
**Phase {N}: {Name}** - {Goal from ROADMAP.md}
|
||||
|
||||
`/gsd-discuss-phase {phase}` - gather context and clarify approach
|
||||
|
||||
<sub>`/new` first → fresh context window</sub>
|
||||
|
||||
---
|
||||
|
||||
**Also available:**
|
||||
- `/gsd-ui-phase {phase}` - generate UI design contract (recommended for frontend phases)
|
||||
- `/gsd-plan-phase {phase}` - skip discussion, plan directly
|
||||
- `/gsd-list-phase-assumptions {phase}` - see the agent's assumptions
|
||||
|
||||
---
|
||||
```
|
||||
|
||||
**If CONTEXT.md does NOT exist AND phase has no UI:**
|
||||
|
||||
```
|
||||
---
|
||||
|
||||
## ▶ Next Up
|
||||
|
||||
**Phase {N}: {Name}** - {Goal from ROADMAP.md}
|
||||
|
||||
`/gsd-discuss-phase {phase} ${GSD_WS}` - gather context and clarify approach
|
||||
|
||||
<sub>`/new` first → fresh context window</sub>
|
||||
|
||||
---
|
||||
|
||||
**Also available:**
|
||||
- `/gsd-plan-phase {phase} ${GSD_WS}` - skip discussion, plan directly
|
||||
- `/gsd-list-phase-assumptions {phase} ${GSD_WS}` - see the agent'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 ${GSD_WS}`
|
||||
|
||||
<sub>`/new` first → fresh context window</sub>
|
||||
|
||||
---
|
||||
|
||||
**Also available:**
|
||||
- `/gsd-execute-phase {phase} ${GSD_WS}` - execute phase plans
|
||||
- `/gsd-verify-work {phase} ${GSD_WS}` - run more UAT testing
|
||||
|
||||
---
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
**Route E.2: UAT testing incomplete (partial)**
|
||||
|
||||
UAT.md exists with `status: partial` - testing session ended before all items resolved.
|
||||
|
||||
```
|
||||
---
|
||||
|
||||
## Incomplete UAT Testing
|
||||
|
||||
**{phase_num}-UAT.md** has {N} unresolved tests (pending, blocked, or skipped).
|
||||
|
||||
`/gsd-verify-work {phase} ${GSD_WS}` - resume testing from where you left off
|
||||
|
||||
<sub>`/new` first → fresh context window</sub>
|
||||
|
||||
---
|
||||
|
||||
**Also available:**
|
||||
- `/gsd-audit-uat ${GSD_WS}` - full cross-phase UAT audit
|
||||
- `/gsd-execute-phase {phase} ${GSD_WS}` - execute phase plans
|
||||
|
||||
---
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
**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.
|
||||
|
||||
Check if next phase has UI indicators:
|
||||
|
||||
```bash
|
||||
NEXT_PHASE_SECTION=$(pi-gsd-tools roadmap get-phase "$((Z+1))" 2>/dev/null)
|
||||
NEXT_HAS_UI=$(echo "$NEXT_PHASE_SECTION" | grep -qi "UI hint.*yes" && echo "true" || echo "false")
|
||||
```
|
||||
|
||||
**If next phase has UI (`NEXT_HAS_UI` is `true`):**
|
||||
|
||||
```
|
||||
---
|
||||
|
||||
## ✓ Phase {Z} Complete
|
||||
|
||||
## ▶ Next Up
|
||||
|
||||
**Phase {Z+1}: {Name}** - {Goal from ROADMAP.md}
|
||||
|
||||
`/gsd-discuss-phase {Z+1}` - gather context and clarify approach
|
||||
|
||||
<sub>`/new` first → fresh context window</sub>
|
||||
|
||||
---
|
||||
|
||||
**Also available:**
|
||||
- `/gsd-ui-phase {Z+1}` - generate UI design contract (recommended for frontend phases)
|
||||
- `/gsd-plan-phase {Z+1}` - skip discussion, plan directly
|
||||
- `/gsd-verify-work {Z}` - user acceptance test before continuing
|
||||
|
||||
---
|
||||
```
|
||||
|
||||
**If next phase has no UI:**
|
||||
|
||||
```
|
||||
---
|
||||
|
||||
## ✓ Phase {Z} Complete
|
||||
|
||||
## ▶ Next Up
|
||||
|
||||
**Phase {Z+1}: {Name}** - {Goal from ROADMAP.md}
|
||||
|
||||
`/gsd-discuss-phase {Z+1} ${GSD_WS}` - gather context and clarify approach
|
||||
|
||||
<sub>`/new` first → fresh context window</sub>
|
||||
|
||||
---
|
||||
|
||||
**Also available:**
|
||||
- `/gsd-plan-phase {Z+1} ${GSD_WS}` - skip discussion, plan directly
|
||||
- `/gsd-verify-work {Z} ${GSD_WS}` - 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 ${GSD_WS}`
|
||||
|
||||
<sub>`/new` first → fresh context window</sub>
|
||||
|
||||
---
|
||||
|
||||
**Also available:**
|
||||
- `/gsd-verify-work ${GSD_WS}` - 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 ${GSD_WS}`
|
||||
|
||||
<sub>`/new` 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] ${GSD_WS}`
|
||||
- All work complete → offer milestone completion
|
||||
- Blockers present → highlight before offering to continue
|
||||
- Handoff file exists → mention it, offer `/gsd-resume-work ${GSD_WS}`
|
||||
</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>
|
||||
824
.pi/gsd/workflows/quick.md
Normal file
824
.pi/gsd/workflows/quick.md
Normal file
@@ -0,0 +1,824 @@
|
||||
<gsd-version v="1.12.4" />
|
||||
|
||||
<gsd-arguments>
|
||||
<settings>
|
||||
<keep-extra-args />
|
||||
</settings>
|
||||
<arg name="discuss" type="flag" flag="--discuss" optional />
|
||||
<arg name="full" type="flag" flag="--full" optional />
|
||||
<arg name="research" type="flag" flag="--research" optional />
|
||||
<arg name="description" type="string" optional />
|
||||
</gsd-arguments>
|
||||
|
||||
<gsd-execute>
|
||||
<shell command="pi-gsd-tools">
|
||||
<args>
|
||||
<arg string="init" />
|
||||
<arg string="quick" />
|
||||
<arg name="description" wrap='"' />
|
||||
</args>
|
||||
<outs>
|
||||
<out type="string" name="init" />
|
||||
</outs>
|
||||
</shell>
|
||||
<if>
|
||||
<condition>
|
||||
<starts-with>
|
||||
<left name="init" />
|
||||
<right type="string" value="@file:" />
|
||||
</starts-with>
|
||||
</condition>
|
||||
<then>
|
||||
<string-op op="split">
|
||||
<args>
|
||||
<arg name="init" />
|
||||
<arg type="string" value="@file:" />
|
||||
</args>
|
||||
<outs>
|
||||
<out type="string" name="init-file" />
|
||||
</outs>
|
||||
</string-op>
|
||||
<shell command="cat">
|
||||
<args>
|
||||
<arg name="init-file" wrap='"' />
|
||||
</args>
|
||||
<outs>
|
||||
<out type="string" name="init" />
|
||||
</outs>
|
||||
</shell>
|
||||
</then>
|
||||
</if>
|
||||
<shell command="pi-gsd-tools">
|
||||
<args>
|
||||
<arg string="agent-skills" />
|
||||
<arg string="gsd-planner" />
|
||||
</args>
|
||||
<outs>
|
||||
<suppress-errors />
|
||||
<out type="string" name="agent-skills-planner" />
|
||||
</outs>
|
||||
</shell>
|
||||
<shell command="pi-gsd-tools">
|
||||
<args>
|
||||
<arg string="agent-skills" />
|
||||
<arg string="gsd-executor" />
|
||||
</args>
|
||||
<outs>
|
||||
<suppress-errors />
|
||||
<out type="string" name="agent-skills-executor" />
|
||||
</outs>
|
||||
</shell>
|
||||
<shell command="pi-gsd-tools">
|
||||
<args>
|
||||
<arg string="agent-skills" />
|
||||
<arg string="gsd-plan-checker" />
|
||||
</args>
|
||||
<outs>
|
||||
<suppress-errors />
|
||||
<out type="string" name="agent-skills-checker" />
|
||||
</outs>
|
||||
</shell>
|
||||
<shell command="pi-gsd-tools">
|
||||
<args>
|
||||
<arg string="agent-skills" />
|
||||
<arg string="gsd-verifier" />
|
||||
</args>
|
||||
<outs>
|
||||
<suppress-errors />
|
||||
<out type="string" name="agent-skills-verifier" />
|
||||
</outs>
|
||||
</shell>
|
||||
</gsd-execute>
|
||||
|
||||
## Quick Task Context (pre-injected by WXP)
|
||||
|
||||
**Task:** <gsd-paste name="description" />
|
||||
|
||||
**Init Data:**
|
||||
<gsd-paste name="init" />
|
||||
|
||||
<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**
|
||||
|
||||
<!-- Context pre-injected above via WXP - variables available via <gsd-paste name="..."> -->
|
||||
|
||||
Parse JSON for: `planner_model`, `executor_model`, `checker_model`, `verifier_model`, `commit_docs`, `branch_name`, `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 2.5: Handle quick-task branching**
|
||||
|
||||
**If `branch_name` is empty/null:** Skip and continue on the current branch.
|
||||
|
||||
**If `branch_name` is set:** Check out the quick-task branch before any planning commits:
|
||||
|
||||
```bash
|
||||
git checkout -b "$branch_name" 2>/dev/null || git checkout "$branch_name"
|
||||
```
|
||||
|
||||
All quick-task commits for this run stay on that branch. User handles merge/rebase afterward.
|
||||
|
||||
---
|
||||
|
||||
**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: "the agent'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 the agent'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}
|
||||
|
||||
### the agent'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)
|
||||
- ./GEMINI.md (if exists - project-specific guidelines)
|
||||
${DISCUSS_MODE ? '- ' + QUICK_DIR + '/' + quick_id + '-CONTEXT.md (User decisions - research should align with these)' : ''}
|
||||
</files_to_read>
|
||||
|
||||
${AGENT_SKILLS_PLANNER}
|
||||
|
||||
</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)
|
||||
- ./GEMINI.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>
|
||||
|
||||
${AGENT_SKILLS_PLANNER}
|
||||
|
||||
**Project skills:** Check .agent/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>
|
||||
|
||||
${AGENT_SKILLS_CHECKER}
|
||||
|
||||
**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>
|
||||
|
||||
${AGENT_SKILLS_PLANNER}
|
||||
|
||||
**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)
|
||||
- ./GEMINI.md (Project instructions, if exists)
|
||||
- .agent/skills/ or .agents/skills/ (Project skills, if either exists - list skills, read SKILL.md for each, follow relevant rules during implementation)
|
||||
</files_to_read>
|
||||
|
||||
${AGENT_SKILLS_EXECUTOR}
|
||||
|
||||
<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}",
|
||||
isolation="worktree",
|
||||
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>
|
||||
|
||||
${AGENT_SKILLS_VERIFIER}
|
||||
|
||||
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
|
||||
pi-gsd-tools 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 ${GSD_WS}
|
||||
```
|
||||
|
||||
**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 ${GSD_WS}
|
||||
```
|
||||
|
||||
</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>
|
||||
215
.pi/gsd/workflows/remove-phase.md
Normal file
215
.pi/gsd/workflows/remove-phase.md
Normal file
@@ -0,0 +1,215 @@
|
||||
<gsd-version v="1.12.4" />
|
||||
|
||||
<gsd-arguments>
|
||||
<settings><keep-extra-args /></settings>
|
||||
<arg name="phase" type="number" />
|
||||
</gsd-arguments>
|
||||
|
||||
<gsd-execute>
|
||||
<shell command="pi-gsd-tools">
|
||||
<args>
|
||||
<arg string="init" />
|
||||
<arg string="phase-op" />
|
||||
</args>
|
||||
<outs>
|
||||
<out type="string" name="init" />
|
||||
</outs>
|
||||
</shell>
|
||||
<if>
|
||||
<condition>
|
||||
<starts-with>
|
||||
<left name="init" />
|
||||
<right type="string" value="@file:" />
|
||||
</starts-with>
|
||||
</condition>
|
||||
<then>
|
||||
<string-op op="split">
|
||||
<args>
|
||||
<arg name="init" />
|
||||
<arg type="string" value="@file:" />
|
||||
</args>
|
||||
<outs>
|
||||
<out type="string" name="init-file" />
|
||||
</outs>
|
||||
</string-op>
|
||||
<shell command="cat">
|
||||
<args>
|
||||
<arg name="init-file" wrap='"' />
|
||||
</args>
|
||||
<outs>
|
||||
<out type="string" name="init" />
|
||||
</outs>
|
||||
</shell>
|
||||
</then>
|
||||
</if>
|
||||
<shell command="pi-gsd-tools">
|
||||
<args>
|
||||
<arg string="state" />
|
||||
<arg string="json" />
|
||||
<arg string="--raw" />
|
||||
</args>
|
||||
<outs>
|
||||
<out type="string" name="state" />
|
||||
</outs>
|
||||
</shell>
|
||||
</gsd-execute>
|
||||
|
||||
## Context (pre-injected)
|
||||
|
||||
**Phase:** <gsd-paste name="phase" />
|
||||
|
||||
**Phase Data:**
|
||||
<gsd-paste name="init" />
|
||||
|
||||
<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:
|
||||
|
||||
<!-- Context pre-injected above via WXP - variables available via <gsd-paste name="..."> -->
|
||||
|
||||
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=$(pi-gsd-tools 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=$(pi-gsd-tools 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
|
||||
pi-gsd-tools 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>
|
||||
140
.pi/gsd/workflows/remove-workspace.md
Normal file
140
.pi/gsd/workflows/remove-workspace.md
Normal file
@@ -0,0 +1,140 @@
|
||||
<gsd-version v="1.12.4" />
|
||||
|
||||
<gsd-arguments>
|
||||
<settings><keep-extra-args /></settings>
|
||||
<arg name="name" type="string" optional />
|
||||
</gsd-arguments>
|
||||
|
||||
<gsd-execute>
|
||||
<shell command="pi-gsd-tools">
|
||||
<args>
|
||||
<arg string="init" />
|
||||
<arg string="remove-workspace" />
|
||||
</args>
|
||||
<outs>
|
||||
<out type="string" name="workspace-data" />
|
||||
</outs>
|
||||
</shell>
|
||||
<if>
|
||||
<condition>
|
||||
<starts-with>
|
||||
<left name="workspace-data" />
|
||||
<right type="string" value="@file:" />
|
||||
</starts-with>
|
||||
</condition>
|
||||
<then>
|
||||
<string-op op="split">
|
||||
<args>
|
||||
<arg name="workspace-data" />
|
||||
<arg type="string" value="@file:" />
|
||||
</args>
|
||||
<outs>
|
||||
<out type="string" name="workspace-data-file" />
|
||||
</outs>
|
||||
</string-op>
|
||||
<shell command="cat">
|
||||
<args>
|
||||
<arg name="workspace-data-file" wrap='"' />
|
||||
</args>
|
||||
<outs>
|
||||
<out type="string" name="workspace-data" />
|
||||
</outs>
|
||||
</shell>
|
||||
</then>
|
||||
</if>
|
||||
</gsd-execute>
|
||||
|
||||
## Context (pre-injected)
|
||||
|
||||
**Workspace:** <gsd-paste name="name" />
|
||||
|
||||
**Data:**
|
||||
<gsd-paste name="workspace-data" />
|
||||
|
||||
<purpose>
|
||||
Remove a GSD workspace, cleaning up git worktrees and deleting the workspace directory.
|
||||
</purpose>
|
||||
|
||||
<required_reading>
|
||||
Read all files referenced by the invoking prompt's execution_context before starting.
|
||||
</required_reading>
|
||||
|
||||
<process>
|
||||
|
||||
## 1. Setup
|
||||
|
||||
Extract workspace name from $ARGUMENTS.
|
||||
|
||||
<!-- Context pre-injected above via WXP - variables available via <gsd-paste name="..."> -->
|
||||
|
||||
Parse JSON for: `workspace_name`, `workspace_path`, `has_manifest`, `strategy`, `repos`, `repo_count`, `dirty_repos`, `has_dirty_repos`.
|
||||
|
||||
**If no workspace name provided:**
|
||||
|
||||
First run `/gsd-list-workspaces` to show available workspaces, then ask:
|
||||
|
||||
Use AskUserQuestion:
|
||||
- header: "Remove Workspace"
|
||||
- question: "Which workspace do you want to remove?"
|
||||
- requireAnswer: true
|
||||
|
||||
Re-run init with the provided name.
|
||||
|
||||
## 2. Safety Checks
|
||||
|
||||
**If `has_dirty_repos` is true:**
|
||||
|
||||
```
|
||||
Cannot remove workspace "$WORKSPACE_NAME" - the following repos have uncommitted changes:
|
||||
|
||||
- repo1
|
||||
- repo2
|
||||
|
||||
Commit or stash changes in these repos before removing the workspace:
|
||||
cd $WORKSPACE_PATH/repo1
|
||||
git stash # or git commit
|
||||
```
|
||||
|
||||
Exit. Do NOT proceed.
|
||||
|
||||
## 3. Confirm Removal
|
||||
|
||||
Use AskUserQuestion:
|
||||
- header: "Confirm Removal"
|
||||
- question: "Remove workspace '$WORKSPACE_NAME' at $WORKSPACE_PATH? This will delete all files in the workspace directory. Type the workspace name to confirm:"
|
||||
- requireAnswer: true
|
||||
|
||||
**If answer does not match `$WORKSPACE_NAME`:** Exit with "Removal cancelled."
|
||||
|
||||
## 4. Clean Up Worktrees
|
||||
|
||||
**If strategy is `worktree`:**
|
||||
|
||||
For each repo in the workspace:
|
||||
|
||||
```bash
|
||||
cd "$SOURCE_REPO_PATH"
|
||||
git worktree remove "$WORKSPACE_PATH/$REPO_NAME" 2>&1 || true
|
||||
```
|
||||
|
||||
If `git worktree remove` fails, warn but continue:
|
||||
```
|
||||
Warning: Could not remove worktree for $REPO_NAME - source repo may have been moved or deleted.
|
||||
```
|
||||
|
||||
## 5. Delete Workspace Directory
|
||||
|
||||
```bash
|
||||
rm -rf "$WORKSPACE_PATH"
|
||||
```
|
||||
|
||||
## 6. Report
|
||||
|
||||
```
|
||||
Workspace "$WORKSPACE_NAME" removed.
|
||||
|
||||
Path: $WORKSPACE_PATH (deleted)
|
||||
Repos: $REPO_COUNT worktrees cleaned up
|
||||
```
|
||||
|
||||
</process>
|
||||
136
.pi/gsd/workflows/research-phase.md
Normal file
136
.pi/gsd/workflows/research-phase.md
Normal file
@@ -0,0 +1,136 @@
|
||||
<gsd-version v="1.12.4" />
|
||||
|
||||
<gsd-arguments>
|
||||
<settings><keep-extra-args /></settings>
|
||||
<arg name="phase" type="number" />
|
||||
</gsd-arguments>
|
||||
|
||||
<gsd-execute>
|
||||
<shell command="pi-gsd-tools">
|
||||
<args>
|
||||
<arg string="init" />
|
||||
<arg string="phase-op" />
|
||||
</args>
|
||||
<outs>
|
||||
<out type="string" name="init" />
|
||||
</outs>
|
||||
</shell>
|
||||
<if>
|
||||
<condition>
|
||||
<starts-with>
|
||||
<left name="init" />
|
||||
<right type="string" value="@file:" />
|
||||
</starts-with>
|
||||
</condition>
|
||||
<then>
|
||||
<string-op op="split">
|
||||
<args>
|
||||
<arg name="init" />
|
||||
<arg type="string" value="@file:" />
|
||||
</args>
|
||||
<outs>
|
||||
<out type="string" name="init-file" />
|
||||
</outs>
|
||||
</string-op>
|
||||
<shell command="cat">
|
||||
<args>
|
||||
<arg name="init-file" wrap='"' />
|
||||
</args>
|
||||
<outs>
|
||||
<out type="string" name="init" />
|
||||
</outs>
|
||||
</shell>
|
||||
</then>
|
||||
</if>
|
||||
<shell command="pi-gsd-tools">
|
||||
<args>
|
||||
<arg string="roadmap" />
|
||||
<arg string="get-phase" />
|
||||
</args>
|
||||
<outs>
|
||||
<out type="string" name="roadmap-phase" />
|
||||
</outs>
|
||||
</shell>
|
||||
<shell command="pi-gsd-tools">
|
||||
<args>
|
||||
<arg string="agent-skills" />
|
||||
<arg string="gsd-phase-researcher" />
|
||||
</args>
|
||||
<outs>
|
||||
<suppress-errors />
|
||||
<out type="string" name="agent-skills-researcher" />
|
||||
</outs>
|
||||
</shell>
|
||||
</gsd-execute>
|
||||
|
||||
## Context (pre-injected)
|
||||
|
||||
**Phase:** <gsd-paste name="phase" />
|
||||
|
||||
**Phase Data:**
|
||||
<gsd-paste name="init" />
|
||||
|
||||
**Roadmap:**
|
||||
<gsd-paste name="roadmap-phase" />
|
||||
|
||||
<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>
|
||||
|
||||
<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
|
||||
</available_agent_types>
|
||||
|
||||
<process>
|
||||
|
||||
## Step 0: Resolve Model Profile
|
||||
|
||||
@.pi/gsd/references/model-profile-resolution.md
|
||||
|
||||
Resolve model for:
|
||||
- `gsd-phase-researcher`
|
||||
|
||||
## Step 1: Normalize and Validate Phase
|
||||
|
||||
@.pi/gsd/references/phase-argument-parsing.md
|
||||
|
||||
<!-- Context pre-injected above via WXP - variables available via <gsd-paste name="..."> -->
|
||||
|
||||
## 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>
|
||||
|
||||
${AGENT_SKILLS_RESEARCHER}
|
||||
|
||||
<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>
|
||||
386
.pi/gsd/workflows/resume-project.md
Normal file
386
.pi/gsd/workflows/resume-project.md
Normal file
@@ -0,0 +1,386 @@
|
||||
<gsd-version v="1.12.4" />
|
||||
|
||||
<gsd-arguments>
|
||||
<settings><keep-extra-args /></settings>
|
||||
</gsd-arguments>
|
||||
|
||||
<gsd-execute>
|
||||
<shell command="pi-gsd-tools">
|
||||
<args>
|
||||
<arg string="init" />
|
||||
<arg string="resume" />
|
||||
</args>
|
||||
<outs>
|
||||
<out type="string" name="resume-data" />
|
||||
</outs>
|
||||
</shell>
|
||||
<if>
|
||||
<condition>
|
||||
<starts-with>
|
||||
<left name="resume-data" />
|
||||
<right type="string" value="@file:" />
|
||||
</starts-with>
|
||||
</condition>
|
||||
<then>
|
||||
<string-op op="split">
|
||||
<args>
|
||||
<arg name="resume-data" />
|
||||
<arg type="string" value="@file:" />
|
||||
</args>
|
||||
<outs>
|
||||
<out type="string" name="resume-data-file" />
|
||||
</outs>
|
||||
</string-op>
|
||||
<shell command="cat">
|
||||
<args>
|
||||
<arg name="resume-data-file" wrap='"' />
|
||||
</args>
|
||||
<outs>
|
||||
<out type="string" name="resume-data" />
|
||||
</outs>
|
||||
</shell>
|
||||
</then>
|
||||
</if>
|
||||
<shell command="pi-gsd-tools">
|
||||
<args>
|
||||
<arg string="state" />
|
||||
<arg string="json" />
|
||||
<arg string="--raw" />
|
||||
</args>
|
||||
<outs>
|
||||
<out type="string" name="state" />
|
||||
</outs>
|
||||
</shell>
|
||||
</gsd-execute>
|
||||
|
||||
## Resume Context (pre-injected)
|
||||
|
||||
**Resume Data:**
|
||||
<gsd-paste name="resume-data" />
|
||||
|
||||
**State:**
|
||||
<gsd-paste name="state" />
|
||||
|
||||
<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>
|
||||
@.pi/gsd/references/continuation-format.md
|
||||
</required_reading>
|
||||
|
||||
<process>
|
||||
|
||||
<step name="initialize">
|
||||
Load all context in one call:
|
||||
|
||||
<!-- Context pre-injected above via WXP - variables available via <gsd-paste name="..."> -->
|
||||
|
||||
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 || true
|
||||
|
||||
# Check for continue-here files (mid-plan resumption)
|
||||
ls .planning/phases/*/.continue-here*.md 2>/dev/null || true
|
||||
|
||||
# Check for plans without summaries (incomplete execution)
|
||||
for plan in .planning/phases/*/*-PLAN.md; do
|
||||
[ -e "$plan" ] || continue
|
||||
summary="${plan/PLAN/SUMMARY}"
|
||||
[ ! -f "$summary" ] && echo "Incomplete: $plan"
|
||||
done 2>/dev/null || true
|
||||
|
||||
# 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} ${GSD_WS})
|
||||
OR
|
||||
1. Discuss Phase 3 context (/gsd-discuss-phase 3 ${GSD_WS}) [if CONTEXT.md missing]
|
||||
OR
|
||||
1. Plan Phase 3 (/gsd-plan-phase 3 ${GSD_WS}) [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 || true
|
||||
```
|
||||
|
||||
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} ${GSD_WS}`
|
||||
|
||||
<sub>`/new` 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] ${GSD_WS}`
|
||||
|
||||
<sub>`/new` first → fresh context window</sub>
|
||||
|
||||
---
|
||||
|
||||
**Also available:**
|
||||
- `/gsd-discuss-phase [N] ${GSD_WS}` - gather context first
|
||||
- `/gsd-research-phase [N] ${GSD_WS}` - 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>
|
||||
219
.pi/gsd/workflows/review-backlog.md
Normal file
219
.pi/gsd/workflows/review-backlog.md
Normal file
@@ -0,0 +1,219 @@
|
||||
<gsd-version v="1.12.4" />
|
||||
|
||||
<gsd-arguments>
|
||||
<settings><keep-extra-args /></settings>
|
||||
</gsd-arguments>
|
||||
|
||||
<gsd-execute>
|
||||
<display msg="Loading backlog and todos..." />
|
||||
<shell command="pi-gsd-tools">
|
||||
<args>
|
||||
<arg string="init" />
|
||||
<arg string="todos" />
|
||||
<arg string="0" />
|
||||
</args>
|
||||
<outs>
|
||||
<out type="string" name="todos-data" />
|
||||
</outs>
|
||||
</shell>
|
||||
<if>
|
||||
<condition>
|
||||
<starts-with>
|
||||
<left name="todos-data" />
|
||||
<right type="string" value="@file:" />
|
||||
</starts-with>
|
||||
</condition>
|
||||
<then>
|
||||
<string-op op="split">
|
||||
<args>
|
||||
<arg name="todos-data" />
|
||||
<arg type="string" value="@file:" />
|
||||
</args>
|
||||
<outs>
|
||||
<out type="string" name="todos-data-file" />
|
||||
</outs>
|
||||
</string-op>
|
||||
<shell command="cat">
|
||||
<args>
|
||||
<arg name="todos-data-file" wrap='"' />
|
||||
</args>
|
||||
<outs>
|
||||
<out type="string" name="todos-data" />
|
||||
</outs>
|
||||
</shell>
|
||||
</then>
|
||||
</if>
|
||||
<shell command="pi-gsd-tools">
|
||||
<args>
|
||||
<arg string="state" />
|
||||
<arg string="json" />
|
||||
<arg string="--raw" />
|
||||
</args>
|
||||
<outs>
|
||||
<suppress-errors />
|
||||
<out type="string" name="state" />
|
||||
</outs>
|
||||
</shell>
|
||||
<shell command="pi-gsd-tools">
|
||||
<args>
|
||||
<arg string="roadmap" />
|
||||
<arg string="analyze" />
|
||||
<arg string="--raw" />
|
||||
</args>
|
||||
<outs>
|
||||
<suppress-errors />
|
||||
<out type="string" name="roadmap" />
|
||||
</outs>
|
||||
</shell>
|
||||
</gsd-execute>
|
||||
|
||||
## Backlog Review Context (pre-injected by WXP)
|
||||
|
||||
**Todos:**
|
||||
<gsd-paste name="todos-data" />
|
||||
|
||||
**Roadmap:**
|
||||
<gsd-paste name="roadmap" />
|
||||
|
||||
**State:**
|
||||
<gsd-paste name="state" />
|
||||
|
||||
---
|
||||
|
||||
<purpose>
|
||||
Review accumulated backlog items (999.x phases and pending todos) and decide what to do with each: promote to a real phase, convert to a todo, discard, or keep.
|
||||
|
||||
This is the "inbox zero" command for ideas that were parked during active development.
|
||||
</purpose>
|
||||
|
||||
<process>
|
||||
|
||||
<step name="load_backlog">
|
||||
<!-- Context pre-injected above via WXP - variables available via <gsd-paste name="..."> -->
|
||||
|
||||
**Step A: Extract backlog phases from roadmap.**
|
||||
|
||||
From `roadmap` JSON, find all phases where `phase_number` starts with `999` (backlog entries added via `/gsd-add-backlog`).
|
||||
|
||||
**Step B: Extract pending todos from todos data.**
|
||||
|
||||
From `todos-data` JSON, extract `todos` array with fields: `id`, `title`, `area`, `created`, `problem`.
|
||||
|
||||
**If both backlog phases and todos are empty:**
|
||||
```
|
||||
Nothing in the backlog. The queue is clear.
|
||||
|
||||
To capture an idea: /gsd-add-backlog <idea>
|
||||
To capture a todo: /gsd-add-todo <task>
|
||||
```
|
||||
Exit.
|
||||
</step>
|
||||
|
||||
<step name="present_inventory">
|
||||
Display a combined inventory:
|
||||
|
||||
```
|
||||
## Backlog Review
|
||||
|
||||
### 999.x Backlog Phases ({N} items)
|
||||
| Phase | Idea | Added |
|
||||
|-------|------|-------|
|
||||
| 999.1 | {idea} | {date} |
|
||||
| 999.2 | {idea} | {date} |
|
||||
|
||||
### Pending Todos ({M} items)
|
||||
| # | Title | Area | Created |
|
||||
|---|-------|------|---------|
|
||||
| 1 | {title} | {area} | {date} |
|
||||
| 2 | {title} | {area} | {date} |
|
||||
|
||||
**Total:** {N+M} items to review
|
||||
```
|
||||
|
||||
Ask:
|
||||
```
|
||||
Options:
|
||||
1. Review each item interactively (recommended)
|
||||
2. Promote a specific backlog phase → real phase number
|
||||
3. Work on a specific todo
|
||||
4. Discard a backlog phase
|
||||
5. Done (keep everything)
|
||||
```
|
||||
</step>
|
||||
|
||||
<step name="interactive_review">
|
||||
**If user chooses interactive review:**
|
||||
|
||||
For each backlog phase (999.x), present:
|
||||
```
|
||||
## Phase 999.{N}: {idea}
|
||||
|
||||
Options:
|
||||
1. Promote to next available phase slot ← recommended if actionable
|
||||
2. Convert to a todo (more granular)
|
||||
3. Keep in backlog
|
||||
4. Discard (remove from ROADMAP.md)
|
||||
```
|
||||
|
||||
**Promote:** Remove the 999.x entry, add as a properly numbered phase at the end of the current milestone using:
|
||||
```bash
|
||||
pi-gsd-tools roadmap add-phase "{next_available_number}" "{idea_text}" --raw
|
||||
```
|
||||
Then remove the 999.x placeholder:
|
||||
```bash
|
||||
pi-gsd-tools roadmap remove-phase "999.{N}" --raw
|
||||
```
|
||||
|
||||
**Convert to todo:** Create a todo file (see `/gsd-add-todo` workflow) and remove the 999.x phase entry.
|
||||
|
||||
**Discard:**
|
||||
```bash
|
||||
pi-gsd-tools roadmap remove-phase "999.{N}" --raw
|
||||
```
|
||||
|
||||
For each pending todo, present:
|
||||
```
|
||||
## Todo: {title}
|
||||
Area: {area}
|
||||
Problem: {problem excerpt}
|
||||
|
||||
Options:
|
||||
1. Work on this now → promote to current phase plan
|
||||
2. Keep as todo
|
||||
3. Promote to backlog phase
|
||||
4. Mark done (won't be worked on)
|
||||
```
|
||||
</step>
|
||||
|
||||
<step name="commit_changes">
|
||||
After all reviews, commit any ROADMAP.md changes and completed todos:
|
||||
|
||||
```bash
|
||||
pi-gsd-tools commit "docs: backlog review - promoted {X} items, discarded {Y}" --files .planning/ROADMAP.md .planning/todos/done/
|
||||
```
|
||||
|
||||
Display summary:
|
||||
```
|
||||
## Backlog Review Complete
|
||||
|
||||
✓ Promoted: {list of promoted items}
|
||||
✓ Converted: {list of todos created}
|
||||
✓ Discarded: {count}
|
||||
→ Kept: {count remaining}
|
||||
|
||||
{If phases promoted:}
|
||||
Next: /gsd-plan-phase {new_phase_number}
|
||||
```
|
||||
</step>
|
||||
|
||||
</process>
|
||||
|
||||
<success_criteria>
|
||||
- [ ] All 999.x backlog phases listed
|
||||
- [ ] All pending todos listed
|
||||
- [ ] Each item reviewed with a clear decision
|
||||
- [ ] Promotions written to ROADMAP.md
|
||||
- [ ] Discards removed from ROADMAP.md
|
||||
- [ ] Changes committed to git
|
||||
- [ ] User knows what's next
|
||||
</success_criteria>
|
||||
256
.pi/gsd/workflows/review.md
Normal file
256
.pi/gsd/workflows/review.md
Normal file
@@ -0,0 +1,256 @@
|
||||
<gsd-version v="1.12.4" />
|
||||
|
||||
<gsd-arguments>
|
||||
<settings><keep-extra-args /></settings>
|
||||
<arg name="phase" type="number" />
|
||||
</gsd-arguments>
|
||||
|
||||
<gsd-execute>
|
||||
<shell command="pi-gsd-tools">
|
||||
<args>
|
||||
<arg string="init" />
|
||||
<arg string="phase-op" />
|
||||
</args>
|
||||
<outs>
|
||||
<out type="string" name="init" />
|
||||
</outs>
|
||||
</shell>
|
||||
<if>
|
||||
<condition>
|
||||
<starts-with>
|
||||
<left name="init" />
|
||||
<right type="string" value="@file:" />
|
||||
</starts-with>
|
||||
</condition>
|
||||
<then>
|
||||
<string-op op="split">
|
||||
<args>
|
||||
<arg name="init" />
|
||||
<arg type="string" value="@file:" />
|
||||
</args>
|
||||
<outs>
|
||||
<out type="string" name="init-file" />
|
||||
</outs>
|
||||
</string-op>
|
||||
<shell command="cat">
|
||||
<args>
|
||||
<arg name="init-file" wrap='"' />
|
||||
</args>
|
||||
<outs>
|
||||
<out type="string" name="init" />
|
||||
</outs>
|
||||
</shell>
|
||||
</then>
|
||||
</if>
|
||||
<shell command="pi-gsd-tools">
|
||||
<args>
|
||||
<arg string="state" />
|
||||
<arg string="json" />
|
||||
<arg string="--raw" />
|
||||
</args>
|
||||
<outs>
|
||||
<out type="string" name="state" />
|
||||
</outs>
|
||||
</shell>
|
||||
</gsd-execute>
|
||||
|
||||
## Context (pre-injected)
|
||||
|
||||
**Phase:** <gsd-paste name="phase" />
|
||||
|
||||
**Phase Data:**
|
||||
<gsd-paste name="init" />
|
||||
|
||||
<purpose>
|
||||
Cross-AI peer review - invoke external AI CLIs to independently review phase plans.
|
||||
Each CLI gets the same prompt (PROJECT.md context, phase plans, requirements) and
|
||||
produces structured feedback. Results are combined into REVIEWS.md for the planner
|
||||
to incorporate via --reviews flag.
|
||||
|
||||
This implements adversarial review: different AI models catch different blind spots.
|
||||
A plan that survives review from 2-3 independent AI systems is more robust.
|
||||
</purpose>
|
||||
|
||||
<process>
|
||||
|
||||
<step name="detect_clis">
|
||||
Check which AI CLIs are available on the system:
|
||||
|
||||
<!-- Context pre-injected above via WXP - variables available via <gsd-paste name="..."> -->
|
||||
|
||||
Read from init: `phase_dir`, `phase_number`, `padded_phase`.
|
||||
|
||||
Then read:
|
||||
1. `.planning/PROJECT.md` (first 80 lines - project context)
|
||||
2. Phase section from `.planning/ROADMAP.md`
|
||||
3. All `*-PLAN.md` files in the phase directory
|
||||
4. `*-CONTEXT.md` if present (user decisions)
|
||||
5. `*-RESEARCH.md` if present (domain research)
|
||||
6. `.planning/REQUIREMENTS.md` (requirements this phase addresses)
|
||||
</step>
|
||||
|
||||
<step name="build_prompt">
|
||||
Build a structured review prompt:
|
||||
|
||||
```markdown
|
||||
# Cross-AI Plan Review Request
|
||||
|
||||
You are reviewing implementation plans for a software project phase.
|
||||
Provide structured feedback on plan quality, completeness, and risks.
|
||||
|
||||
## Project Context
|
||||
{first 80 lines of PROJECT.md}
|
||||
|
||||
## Phase {N}: {phase name}
|
||||
### Roadmap Section
|
||||
{roadmap phase section}
|
||||
|
||||
### Requirements Addressed
|
||||
{requirements for this phase}
|
||||
|
||||
### User Decisions (CONTEXT.md)
|
||||
{context if present}
|
||||
|
||||
### Research Findings
|
||||
{research if present}
|
||||
|
||||
### Plans to Review
|
||||
{all PLAN.md contents}
|
||||
|
||||
## Review Instructions
|
||||
|
||||
Analyze each plan and provide:
|
||||
|
||||
1. **Summary** - One-paragraph assessment
|
||||
2. **Strengths** - What's well-designed (bullet points)
|
||||
3. **Concerns** - Potential issues, gaps, risks (bullet points with severity: HIGH/MEDIUM/LOW)
|
||||
4. **Suggestions** - Specific improvements (bullet points)
|
||||
5. **Risk Assessment** - Overall risk level (LOW/MEDIUM/HIGH) with justification
|
||||
|
||||
Focus on:
|
||||
- Missing edge cases or error handling
|
||||
- Dependency ordering issues
|
||||
- Scope creep or over-engineering
|
||||
- Security considerations
|
||||
- Performance implications
|
||||
- Whether the plans actually achieve the phase goals
|
||||
|
||||
Output your review in markdown format.
|
||||
```
|
||||
|
||||
Write to a temp file: `/tmp/gsd-review-prompt-{phase}.md`
|
||||
</step>
|
||||
|
||||
<step name="invoke_reviewers">
|
||||
For each selected CLI, invoke in sequence (not parallel - avoid rate limits):
|
||||
|
||||
**Gemini:**
|
||||
```bash
|
||||
gemini -p "$(cat /tmp/gsd-review-prompt-{phase}.md)" 2>/dev/null > /tmp/gsd-review-gemini-{phase}.md
|
||||
```
|
||||
|
||||
**the agent (separate session):**
|
||||
```bash
|
||||
claude -p "$(cat /tmp/gsd-review-prompt-{phase}.md)" --no-input 2>/dev/null > /tmp/gsd-review-claude-{phase}.md
|
||||
```
|
||||
|
||||
**Codex:**
|
||||
```bash
|
||||
codex exec --skip-git-repo-check "$(cat /tmp/gsd-review-prompt-{phase}.md)" 2>/dev/null > /tmp/gsd-review-codex-{phase}.md
|
||||
```
|
||||
|
||||
If a CLI fails, log the error and continue with remaining CLIs.
|
||||
|
||||
Display progress:
|
||||
```
|
||||
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
|
||||
GSD ► CROSS-AI REVIEW - Phase {N}
|
||||
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
|
||||
|
||||
◆ Reviewing with {CLI}... done ✓
|
||||
◆ Reviewing with {CLI}... done ✓
|
||||
```
|
||||
</step>
|
||||
|
||||
<step name="write_reviews">
|
||||
Combine all review responses into `{phase_dir}/{padded_phase}-REVIEWS.md`:
|
||||
|
||||
```markdown
|
||||
---
|
||||
phase: {N}
|
||||
reviewers: [gemini, claude, codex]
|
||||
reviewed_at: {ISO timestamp}
|
||||
plans_reviewed: [{list of PLAN.md files}]
|
||||
---
|
||||
|
||||
# Cross-AI Plan Review - Phase {N}
|
||||
|
||||
## Gemini Review
|
||||
|
||||
{gemini review content}
|
||||
|
||||
---
|
||||
|
||||
## the agent Review
|
||||
|
||||
{claude review content}
|
||||
|
||||
---
|
||||
|
||||
## Codex Review
|
||||
|
||||
{codex review content}
|
||||
|
||||
---
|
||||
|
||||
## Consensus Summary
|
||||
|
||||
{synthesize common concerns across all reviewers}
|
||||
|
||||
### Agreed Strengths
|
||||
{strengths mentioned by 2+ reviewers}
|
||||
|
||||
### Agreed Concerns
|
||||
{concerns raised by 2+ reviewers - highest priority}
|
||||
|
||||
### Divergent Views
|
||||
{where reviewers disagreed - worth investigating}
|
||||
```
|
||||
|
||||
Commit:
|
||||
```bash
|
||||
pi-gsd-tools commit "docs: cross-AI review for phase {N}" --files {phase_dir}/{padded_phase}-REVIEWS.md
|
||||
```
|
||||
</step>
|
||||
|
||||
<step name="present_results">
|
||||
Display summary:
|
||||
|
||||
```
|
||||
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
|
||||
GSD ► REVIEW COMPLETE
|
||||
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
|
||||
|
||||
Phase {N} reviewed by {count} AI systems.
|
||||
|
||||
Consensus concerns:
|
||||
{top 3 shared concerns}
|
||||
|
||||
Full review: {padded_phase}-REVIEWS.md
|
||||
|
||||
To incorporate feedback into planning:
|
||||
/gsd-plan-phase {N} --reviews
|
||||
```
|
||||
|
||||
Clean up temp files.
|
||||
</step>
|
||||
|
||||
</process>
|
||||
|
||||
<success_criteria>
|
||||
- [ ] At least one external CLI invoked successfully
|
||||
- [ ] REVIEWS.md written with structured feedback
|
||||
- [ ] Consensus summary synthesized from multiple reviewers
|
||||
- [ ] Temp files cleaned up
|
||||
- [ ] User knows how to use feedback (/gsd-plan-phase --reviews)
|
||||
</success_criteria>
|
||||
195
.pi/gsd/workflows/session-report.md
Normal file
195
.pi/gsd/workflows/session-report.md
Normal file
@@ -0,0 +1,195 @@
|
||||
<gsd-version v="1.12.4" />
|
||||
|
||||
<gsd-execute>
|
||||
<display msg="Loading session context..." />
|
||||
<shell command="pi-gsd-tools">
|
||||
<args>
|
||||
<arg string="state" />
|
||||
<arg string="json" />
|
||||
<arg string="--raw" />
|
||||
</args>
|
||||
<outs>
|
||||
<suppress-errors />
|
||||
<out type="string" name="state" />
|
||||
</outs>
|
||||
</shell>
|
||||
<shell command="pi-gsd-tools">
|
||||
<args>
|
||||
<arg string="current-timestamp" />
|
||||
<arg string="--raw" />
|
||||
</args>
|
||||
<outs>
|
||||
<out type="string" name="timestamp" />
|
||||
</outs>
|
||||
</shell>
|
||||
<shell command="pi-gsd-tools">
|
||||
<args>
|
||||
<arg string="roadmap" />
|
||||
<arg string="analyze" />
|
||||
<arg string="--raw" />
|
||||
</args>
|
||||
<outs>
|
||||
<suppress-errors />
|
||||
<out type="string" name="roadmap" />
|
||||
</outs>
|
||||
</shell>
|
||||
</gsd-execute>
|
||||
|
||||
## Session Context (pre-injected by WXP)
|
||||
|
||||
**Generated:** <gsd-paste name="timestamp" />
|
||||
|
||||
**State:**
|
||||
<gsd-paste name="state" />
|
||||
|
||||
**Roadmap:**
|
||||
<gsd-paste name="roadmap" />
|
||||
|
||||
---
|
||||
|
||||
<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>
|
||||
135
.pi/gsd/workflows/set-profile.md
Normal file
135
.pi/gsd/workflows/set-profile.md
Normal file
@@ -0,0 +1,135 @@
|
||||
<gsd-version v="1.12.4" />
|
||||
|
||||
<gsd-arguments>
|
||||
<settings>
|
||||
<keep-extra-args />
|
||||
</settings>
|
||||
<arg name="profile" type="string" optional />
|
||||
</gsd-arguments>
|
||||
|
||||
<gsd-execute>
|
||||
<display msg="Loading model profile config..." />
|
||||
<shell command="pi-gsd-tools">
|
||||
<args>
|
||||
<arg string="config-get" />
|
||||
<arg string="workflow" />
|
||||
<arg string="--raw" />
|
||||
</args>
|
||||
<outs>
|
||||
<suppress-errors />
|
||||
<out type="string" name="workflow-config" />
|
||||
</outs>
|
||||
</shell>
|
||||
<json-parse src="workflow-config" out="current-profile" path="$.model_profile" />
|
||||
</gsd-execute>
|
||||
|
||||
## Profile Context (pre-injected by WXP)
|
||||
|
||||
**Requested profile:** <gsd-paste name="profile" />
|
||||
|
||||
**Current profile:** <gsd-paste name="current-profile" />
|
||||
|
||||
**Full workflow config:**
|
||||
<gsd-paste name="workflow-config" />
|
||||
|
||||
---
|
||||
|
||||
<purpose>
|
||||
Set the active model profile, controlling which Claude model each GSD agent uses.
|
||||
One command replaces the full /gsd-settings flow for the common case of switching profiles.
|
||||
|
||||
Profiles: `quality` | `balanced` | `budget` | `inherit`
|
||||
</purpose>
|
||||
|
||||
<profile_reference>
|
||||
|
||||
| Profile | Planner | Executor | Researcher | Verifier | Use when |
|
||||
|---------|---------|---------|------------|---------|---------|
|
||||
| `quality` | opus | opus | opus | sonnet | Critical architecture, quota available |
|
||||
| `balanced` | opus | sonnet | sonnet | sonnet | Normal development (default) |
|
||||
| `budget` | sonnet | sonnet | haiku | haiku | Conserving quota, high-volume work |
|
||||
| `inherit` | inherit | inherit | inherit | inherit | OpenRouter / local models / session switching |
|
||||
|
||||
</profile_reference>
|
||||
|
||||
<process>
|
||||
|
||||
<step name="resolve_profile">
|
||||
<!-- Profile arg and current config pre-injected above via WXP -->
|
||||
|
||||
**If `profile` is empty (no argument provided):**
|
||||
|
||||
Show current profile and available options:
|
||||
|
||||
```
|
||||
## Current Model Profile
|
||||
|
||||
Active: {current-profile || "balanced (default)"}
|
||||
|
||||
Available profiles:
|
||||
quality - Opus everywhere (highest quality, highest cost)
|
||||
balanced - Opus for planning, Sonnet for execution (recommended)
|
||||
budget - Sonnet/Haiku mix (lowest cost)
|
||||
inherit - Use the current session model for all agents
|
||||
|
||||
Usage: /gsd-set-profile <profile>
|
||||
|
||||
To configure individual agents and other settings: /gsd-settings
|
||||
```
|
||||
|
||||
Exit (display only, no changes).
|
||||
</step>
|
||||
|
||||
<step name="validate_profile">
|
||||
Validate that the provided `profile` value is one of: `quality`, `balanced`, `budget`, `inherit`.
|
||||
|
||||
**If invalid:**
|
||||
```
|
||||
Error: Unknown profile '{profile}'.
|
||||
|
||||
Valid profiles: quality, balanced, budget, inherit
|
||||
|
||||
Example: /gsd-set-profile balanced
|
||||
```
|
||||
Exit.
|
||||
</step>
|
||||
|
||||
<step name="apply_profile">
|
||||
Apply the profile:
|
||||
|
||||
```bash
|
||||
pi-gsd-tools config-set-model-profile {profile}
|
||||
```
|
||||
|
||||
This updates `.planning/config.json` with the new model profile.
|
||||
</step>
|
||||
|
||||
<step name="confirm">
|
||||
```
|
||||
✓ Model profile set to: {profile}
|
||||
|
||||
{profile description}
|
||||
|
||||
Planner: {model}
|
||||
Executor: {model}
|
||||
Researcher: {model}
|
||||
Verifier: {model}
|
||||
|
||||
To configure more options: /gsd-settings
|
||||
```
|
||||
|
||||
Where "profile description" maps:
|
||||
- `quality` → "Maximum reasoning power. Opus for all decision-making agents."
|
||||
- `balanced` → "Smart allocation. Opus for planning, Sonnet for execution and verification."
|
||||
- `budget` → "Minimal Opus usage. Sonnet for writing, Haiku for research and verification."
|
||||
- `inherit` → "Follow the current session model. Required for non-Anthropic providers."
|
||||
</step>
|
||||
|
||||
</process>
|
||||
|
||||
<success_criteria>
|
||||
- [ ] Profile validated against allowed values
|
||||
- [ ] .planning/config.json updated with new profile
|
||||
- [ ] Confirmation shows per-agent model assignments
|
||||
- [ ] Link to /gsd-settings for advanced configuration
|
||||
</success_criteria>
|
||||
304
.pi/gsd/workflows/settings.md
Normal file
304
.pi/gsd/workflows/settings.md
Normal file
@@ -0,0 +1,304 @@
|
||||
<gsd-version v="1.12.4" />
|
||||
|
||||
<gsd-arguments>
|
||||
<settings><keep-extra-args /></settings>
|
||||
</gsd-arguments>
|
||||
|
||||
<gsd-execute>
|
||||
<shell command="pi-gsd-tools">
|
||||
<args>
|
||||
<arg string="state" />
|
||||
<arg string="load" />
|
||||
<arg string="--raw" />
|
||||
</args>
|
||||
<outs>
|
||||
<suppress-errors />
|
||||
<out type="string" name="state" />
|
||||
</outs>
|
||||
</shell>
|
||||
</gsd-execute>
|
||||
|
||||
## Context (pre-injected)
|
||||
|
||||
**State:**
|
||||
<gsd-paste name="state" />
|
||||
|
||||
<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:
|
||||
|
||||
<!-- Context pre-injected above via WXP - variables available via <gsd-paste name="..."> -->
|
||||
|
||||
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 /new + 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 the agent to reach auto-compact naturally. Good for long unattended runs." }
|
||||
]
|
||||
},
|
||||
{
|
||||
question: "Research best practices before asking questions? (web search during new-project and discuss-phase)",
|
||||
header: "Research Qs",
|
||||
multiSelect: false,
|
||||
options: [
|
||||
{ label: "No (Recommended)", description: "Ask questions directly. Faster, uses fewer tokens." },
|
||||
{ label: "Yes", description: "Search web for best practices before each question group. More informed questions but uses more tokens." }
|
||||
]
|
||||
},
|
||||
{
|
||||
question: "Skip discuss-phase in autonomous mode? (use ROADMAP phase goals as spec)",
|
||||
header: "Skip Discuss",
|
||||
multiSelect: false,
|
||||
options: [
|
||||
{ label: "No (Recommended)", description: "Run smart discuss before each phase - surfaces gray areas and captures decisions." },
|
||||
{ label: "Yes", description: "Skip discuss in /gsd-autonomous - chain directly to plan. Best for backend/pipeline work where phase descriptions are the spec." }
|
||||
]
|
||||
}
|
||||
])
|
||||
```
|
||||
</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,
|
||||
"text_mode": true/false,
|
||||
"research_before_questions": true/false,
|
||||
"discuss_mode": "discuss" | "assumptions",
|
||||
"skip_discuss": true/false
|
||||
},
|
||||
"git": {
|
||||
"branching_strategy": "none" | "phase" | "milestone",
|
||||
"quick_branch_template": <string|null>
|
||||
},
|
||||
"hooks": {
|
||||
"context_warnings": true/false,
|
||||
"workflow_guard": 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>,
|
||||
"quick_branch_template": <current>,
|
||||
"workflow": {
|
||||
"research": <current>,
|
||||
"plan_check": <current>,
|
||||
"verifier": <current>,
|
||||
"auto_advance": <current>,
|
||||
"nyquist_validation": <current>,
|
||||
"ui_phase": <current>,
|
||||
"ui_safety_gate": <current>,
|
||||
"skip_discuss": <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} |
|
||||
| Skip Discuss | {On/Off} |
|
||||
| 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 10 settings (profile + 8 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>
|
||||
263
.pi/gsd/workflows/ship.md
Normal file
263
.pi/gsd/workflows/ship.md
Normal file
@@ -0,0 +1,263 @@
|
||||
<gsd-version v="1.12.4" />
|
||||
|
||||
<gsd-arguments>
|
||||
<settings><keep-extra-args /></settings>
|
||||
</gsd-arguments>
|
||||
|
||||
<gsd-execute>
|
||||
<shell command="pi-gsd-tools">
|
||||
<args>
|
||||
<arg string="state" />
|
||||
<arg string="json" />
|
||||
<arg string="--raw" />
|
||||
</args>
|
||||
<outs>
|
||||
<out type="string" name="state" />
|
||||
</outs>
|
||||
</shell>
|
||||
<shell command="pi-gsd-tools">
|
||||
<args>
|
||||
<arg string="validate" />
|
||||
<arg string="health" />
|
||||
<arg string="--raw" />
|
||||
</args>
|
||||
<outs>
|
||||
<suppress-errors />
|
||||
<out type="string" name="health" />
|
||||
</outs>
|
||||
</shell>
|
||||
</gsd-execute>
|
||||
|
||||
## Context (pre-injected)
|
||||
|
||||
**State:**
|
||||
<gsd-paste name="state" />
|
||||
|
||||
**Health:**
|
||||
<gsd-paste name="health" />
|
||||
|
||||
<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:
|
||||
|
||||
<!-- Context pre-injected above via WXP - variables available via <gsd-paste name="..."> -->
|
||||
|
||||
Parse from init JSON: `phase_found`, `phase_dir`, `phase_number`, `phase_name`, `padded_phase`, `commit_docs`.
|
||||
|
||||
Also load config for branching strategy:
|
||||
```bash
|
||||
CONFIG=$(pi-gsd-tools 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
|
||||
pi-gsd-tools state update "Last Activity" "$(date +%Y-%m-%d)"
|
||||
pi-gsd-tools state update "Status" "Phase ${PHASE_NUMBER} shipped - PR #${PR_NUMBER}"
|
||||
```
|
||||
|
||||
If `commit_docs` is true:
|
||||
```bash
|
||||
pi-gsd-tools 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>
|
||||
83
.pi/gsd/workflows/stats.md
Normal file
83
.pi/gsd/workflows/stats.md
Normal file
@@ -0,0 +1,83 @@
|
||||
<gsd-version v="1.12.4" />
|
||||
|
||||
<gsd-arguments>
|
||||
<settings><keep-extra-args /></settings>
|
||||
</gsd-arguments>
|
||||
|
||||
<gsd-execute>
|
||||
<shell command="pi-gsd-tools">
|
||||
<args>
|
||||
<arg string="stats" />
|
||||
<arg string="json" />
|
||||
<arg string="--raw" />
|
||||
</args>
|
||||
<outs>
|
||||
<out type="string" name="stats" />
|
||||
</outs>
|
||||
</shell>
|
||||
</gsd-execute>
|
||||
|
||||
## Stats (pre-injected)
|
||||
|
||||
<gsd-paste name="stats" />
|
||||
|
||||
<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=$(pi-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>
|
||||
213
.pi/gsd/workflows/thread.md
Normal file
213
.pi/gsd/workflows/thread.md
Normal file
@@ -0,0 +1,213 @@
|
||||
<gsd-version v="1.12.4" />
|
||||
|
||||
<gsd-arguments>
|
||||
<settings>
|
||||
<keep-extra-args />
|
||||
</settings>
|
||||
<arg name="subcommand" type="string" optional />
|
||||
<arg name="name" type="string" optional />
|
||||
</gsd-arguments>
|
||||
|
||||
<gsd-execute>
|
||||
<display msg="Loading thread context..." />
|
||||
<shell command="pi-gsd-tools">
|
||||
<args>
|
||||
<arg string="state" />
|
||||
<arg string="json" />
|
||||
<arg string="--raw" />
|
||||
</args>
|
||||
<outs>
|
||||
<suppress-errors />
|
||||
<out type="string" name="state" />
|
||||
</outs>
|
||||
</shell>
|
||||
<shell command="pi-gsd-tools">
|
||||
<args>
|
||||
<arg string="current-timestamp" />
|
||||
<arg string="--raw" />
|
||||
</args>
|
||||
<outs>
|
||||
<out type="string" name="timestamp" />
|
||||
</outs>
|
||||
</shell>
|
||||
</gsd-execute>
|
||||
|
||||
## Thread Context (pre-injected by WXP)
|
||||
|
||||
**Subcommand:** <gsd-paste name="subcommand" />
|
||||
**Name:** <gsd-paste name="name" />
|
||||
**Timestamp:** <gsd-paste name="timestamp" />
|
||||
|
||||
**State:**
|
||||
<gsd-paste name="state" />
|
||||
|
||||
---
|
||||
|
||||
<purpose>
|
||||
Manage context threads — saved conversation checkpoints that can be resumed later.
|
||||
A thread is a snapshot of the current agent context (active phase, decisions, blockers) that
|
||||
survives `/clear` and can be handed off between sessions.
|
||||
|
||||
Subcommands: list, new [name], switch <name>
|
||||
</purpose>
|
||||
|
||||
<process>
|
||||
|
||||
<step name="route">
|
||||
<!-- Context pre-injected above via WXP -->
|
||||
|
||||
Parse `subcommand` and `name` from injected variables.
|
||||
|
||||
Route by subcommand:
|
||||
- `list` (or empty) → **list_threads**
|
||||
- `new [name]` → **new_thread**
|
||||
- `switch <name>` → **switch_thread**
|
||||
- Unknown → show help
|
||||
</step>
|
||||
|
||||
<step name="list_threads">
|
||||
Scan for thread files:
|
||||
|
||||
```bash
|
||||
ls .planning/threads/*.md 2>/dev/null || echo "no threads"
|
||||
```
|
||||
|
||||
**If no threads exist:**
|
||||
```
|
||||
No saved threads.
|
||||
|
||||
Create one to preserve context across /clear:
|
||||
/gsd-thread new <optional-name>
|
||||
```
|
||||
Exit.
|
||||
|
||||
**If threads found:**
|
||||
|
||||
For each thread file, read frontmatter and display:
|
||||
```
|
||||
## Context Threads
|
||||
|
||||
| Name | Phase | Created | Summary |
|
||||
|------|-------|---------|---------|
|
||||
| {name} | {phase} | {date} | {one-line} |
|
||||
|
||||
---
|
||||
Switch to a thread: /gsd-thread switch <name>
|
||||
Create a new thread: /gsd-thread new [name]
|
||||
```
|
||||
</step>
|
||||
|
||||
<step name="new_thread">
|
||||
Capture the current context as a named thread.
|
||||
|
||||
**Resolve name:**
|
||||
- If `name` is provided, use it
|
||||
- Otherwise generate from state: `{phase-slug}-{date}` (e.g., `auth-2025-01-15`)
|
||||
|
||||
**Ensure directory:**
|
||||
```bash
|
||||
mkdir -p .planning/threads
|
||||
```
|
||||
|
||||
**Collect current context from state JSON:**
|
||||
- `current_phase` + `phase_name`
|
||||
- `milestone`
|
||||
- `last_activity`
|
||||
- Recent decisions (last 3 from STATE.md decisions table)
|
||||
- Active blockers
|
||||
|
||||
**Write `.planning/threads/{name}.md`:**
|
||||
```markdown
|
||||
---
|
||||
name: {name}
|
||||
created: {timestamp}
|
||||
phase: {current_phase}
|
||||
phase_name: {phase_name}
|
||||
milestone: {milestone}
|
||||
status: active
|
||||
---
|
||||
|
||||
## Thread: {name}
|
||||
|
||||
**Saved:** {timestamp}
|
||||
**Phase:** {current_phase}: {phase_name}
|
||||
**Milestone:** {milestone}
|
||||
|
||||
## Context Snapshot
|
||||
|
||||
{Summary of what's in progress: what was being worked on, key decisions made, any open questions}
|
||||
|
||||
## State at Save
|
||||
|
||||
[Key fields from STATE.md: current position, last activity, blockers]
|
||||
|
||||
## Resume Instructions
|
||||
|
||||
To resume this thread:
|
||||
1. `/clear` - start fresh context
|
||||
2. `/gsd-thread switch {name}` - restore this thread's context
|
||||
3. `/gsd-resume-work` - re-orient with full project state
|
||||
```
|
||||
|
||||
**Commit:**
|
||||
```bash
|
||||
pi-gsd-tools commit "docs: save context thread '{name}'" --files .planning/threads/{name}.md
|
||||
```
|
||||
|
||||
**Confirm:**
|
||||
```
|
||||
✓ Thread saved: {name}
|
||||
|
||||
Phase: {current_phase}: {phase_name}
|
||||
File: .planning/threads/{name}.md
|
||||
|
||||
Safe to /clear. Resume with: /gsd-thread switch {name}
|
||||
```
|
||||
</step>
|
||||
|
||||
<step name="switch_thread">
|
||||
**Require `name`:** If empty, list available threads and ask user to choose.
|
||||
|
||||
```bash
|
||||
cat .planning/threads/{name}.md 2>/dev/null || echo "Thread '{name}' not found."
|
||||
```
|
||||
|
||||
**If not found:**
|
||||
```
|
||||
Thread '{name}' not found.
|
||||
Available: [list]
|
||||
```
|
||||
Exit.
|
||||
|
||||
**If found:**
|
||||
|
||||
Read the thread file and display its full context:
|
||||
```
|
||||
## Restoring Thread: {name}
|
||||
|
||||
**Saved:** {created}
|
||||
**Phase:** {phase}: {phase_name}
|
||||
|
||||
[Display the Context Snapshot section verbatim]
|
||||
|
||||
---
|
||||
Thread context restored. Continuing from saved state.
|
||||
|
||||
Next:
|
||||
- /gsd-execute-phase {phase} - continue executing
|
||||
- /gsd-plan-phase {phase} - re-plan if context changed
|
||||
- /gsd-resume-work - full project orientation
|
||||
```
|
||||
|
||||
Mark the thread as resumed by updating its frontmatter `status: resumed` and adding a `resumed:` timestamp field.
|
||||
</step>
|
||||
|
||||
</process>
|
||||
|
||||
<success_criteria>
|
||||
- [ ] Subcommand routed correctly
|
||||
- [ ] list: shows all saved threads with phase context
|
||||
- [ ] new: saves full state snapshot to .planning/threads/
|
||||
- [ ] switch: displays saved context and marks thread resumed
|
||||
- [ ] Thread files committed to git
|
||||
</success_criteria>
|
||||
733
.pi/gsd/workflows/transition.md
Normal file
733
.pi/gsd/workflows/transition.md
Normal file
@@ -0,0 +1,733 @@
|
||||
<gsd-version v="1.12.4" />
|
||||
|
||||
<gsd-arguments>
|
||||
<settings><keep-extra-args /></settings>
|
||||
</gsd-arguments>
|
||||
|
||||
<gsd-execute>
|
||||
<shell command="pi-gsd-tools">
|
||||
<args>
|
||||
<arg string="state" />
|
||||
<arg string="reconcile" />
|
||||
<arg string="--raw" />
|
||||
</args>
|
||||
<outs>
|
||||
<suppress-errors />
|
||||
<out type="string" name="reconcile-result" />
|
||||
</outs>
|
||||
</shell>
|
||||
<shell command="pi-gsd-tools">
|
||||
<args>
|
||||
<arg string="roadmap" />
|
||||
<arg string="analyze" />
|
||||
<arg string="--raw" />
|
||||
</args>
|
||||
<outs>
|
||||
<out type="string" name="roadmap" />
|
||||
</outs>
|
||||
</shell>
|
||||
<shell command="pi-gsd-tools">
|
||||
<args>
|
||||
<arg string="state" />
|
||||
<arg string="json" />
|
||||
<arg string="--raw" />
|
||||
</args>
|
||||
<outs>
|
||||
<out type="string" name="state" />
|
||||
</outs>
|
||||
</shell>
|
||||
<shell command="pi-gsd-tools">
|
||||
<args>
|
||||
<arg string="workstream" />
|
||||
<arg string="list" />
|
||||
<arg string="--raw" />
|
||||
</args>
|
||||
<outs>
|
||||
<suppress-errors />
|
||||
<out type="string" name="workstreams" />
|
||||
</outs>
|
||||
</shell>
|
||||
</gsd-execute>
|
||||
|
||||
## Context (pre-injected)
|
||||
|
||||
**Roadmap:**
|
||||
<gsd-paste name="roadmap" />
|
||||
|
||||
**State:**
|
||||
<gsd-paste name="state" />
|
||||
|
||||
**Workstreams:**
|
||||
<gsd-paste name="workstreams" />
|
||||
|
||||
<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 || true
|
||||
cat .planning/PROJECT.md 2>/dev/null || true
|
||||
```
|
||||
|
||||
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 || true) | sort
|
||||
(ls .planning/phases/XX-current/*-SUMMARY.md 2>/dev/null || true) | 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 || true
|
||||
```
|
||||
|
||||
</config-check>
|
||||
|
||||
**Check for verification debt in this phase:**
|
||||
|
||||
```bash
|
||||
# Count outstanding items in current phase
|
||||
OUTSTANDING=""
|
||||
for f in .planning/phases/XX-current/*-UAT.md .planning/phases/XX-current/*-VERIFICATION.md; do
|
||||
[ -f "$f" ] || continue
|
||||
grep -q "result: pending\|result: blocked\|status: partial\|status: human_needed\|status: diagnosed" "$f" && OUTSTANDING="$OUTSTANDING\n$(basename $f)"
|
||||
done
|
||||
```
|
||||
|
||||
**If OUTSTANDING is not empty:**
|
||||
|
||||
Append to the completion confirmation message (regardless of mode):
|
||||
|
||||
```
|
||||
Outstanding verification items in this phase:
|
||||
{list filenames}
|
||||
|
||||
These will carry forward as debt. Review: `/gsd-audit-uat`
|
||||
```
|
||||
|
||||
This does NOT block transition - it ensures the user sees the debt before confirming.
|
||||
|
||||
**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 || true
|
||||
```
|
||||
|
||||
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=$(pi-gsd-tools 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=$(pi-gsd-tools 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` → Last phase done → **Check for workstream collisions first**
|
||||
|
||||
The `next_phase` and `next_phase_name` fields give you the next phase details.
|
||||
|
||||
If you need additional context, use:
|
||||
```bash
|
||||
ROADMAP=$(pi-gsd-tools roadmap analyze)
|
||||
```
|
||||
|
||||
This returns all phases with goals, disk status, and completion info.
|
||||
|
||||
---
|
||||
|
||||
**Workstream collision check (when `is_last_phase: true`):**
|
||||
|
||||
Before routing to Route B, check whether other workstreams are still active.
|
||||
This prevents one workstream from advancing or completing the milestone while
|
||||
other workstreams are still working on their phases.
|
||||
|
||||
**Skip this check if NOT in workstream mode** (i.e., `GSD_WORKSTREAM` is not set / flat mode).
|
||||
In flat mode, go directly to **Route B**.
|
||||
|
||||
```bash
|
||||
# Only check if we're in workstream mode
|
||||
if [ -n "$GSD_WORKSTREAM" ]; then
|
||||
WS_LIST=$(pi-gsd-tools workstream list --raw)
|
||||
fi
|
||||
```
|
||||
|
||||
Parse the JSON result. The output has `{ mode, workstreams: [...] }`.
|
||||
Each workstream entry has: `name`, `status`, `current_phase`, `phase_count`, `completed_phases`.
|
||||
|
||||
Filter out the current workstream (`$GSD_WORKSTREAM`) and any workstreams with
|
||||
status containing "milestone complete" or "archived" (case-insensitive).
|
||||
The remaining entries are **other active workstreams**.
|
||||
|
||||
- **If other active workstreams exist** → Go to **Route B1**
|
||||
- **If NO other active workstreams** (or flat mode) → Go to **Route B**
|
||||
|
||||
---
|
||||
|
||||
**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 || true
|
||||
```
|
||||
|
||||
**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 ${GSD_WS}")
|
||||
|
||||
**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 ${GSD_WS}")
|
||||
|
||||
</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] ${GSD_WS}` - gather context and clarify approach
|
||||
|
||||
<sub>`/new` first → fresh context window</sub>
|
||||
|
||||
---
|
||||
|
||||
**Also available:**
|
||||
- `/gsd-plan-phase [X+1] ${GSD_WS}` - skip discussion, plan directly
|
||||
- `/gsd-research-phase [X+1] ${GSD_WS}` - 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] ${GSD_WS}`
|
||||
|
||||
<sub>`/new` first → fresh context window</sub>
|
||||
|
||||
---
|
||||
|
||||
**Also available:**
|
||||
- `/gsd-discuss-phase [X+1] ${GSD_WS}` - revisit context
|
||||
- `/gsd-research-phase [X+1] ${GSD_WS}` - investigate unknowns
|
||||
|
||||
---
|
||||
```
|
||||
|
||||
</if>
|
||||
|
||||
---
|
||||
|
||||
**Route B1: Workstream done, other workstreams still active**
|
||||
|
||||
This route is reached when `is_last_phase: true` AND the collision check found
|
||||
other active workstreams. Do NOT suggest completing the milestone or advancing
|
||||
to the next milestone - other workstreams are still working.
|
||||
|
||||
**Clear auto-advance chain flag** - workstream boundary is the natural stopping point:
|
||||
|
||||
```bash
|
||||
pi-gsd-tools config-set workflow._auto_chain_active false
|
||||
```
|
||||
|
||||
<if mode="yolo">
|
||||
|
||||
Override auto-advance: do NOT auto-continue to milestone completion.
|
||||
Present the blocking information and stop.
|
||||
|
||||
</if>
|
||||
|
||||
Present (all modes):
|
||||
|
||||
```
|
||||
## ✓ Phase {X}: {Phase Name} Complete
|
||||
|
||||
This workstream's phases are complete. Other workstreams are still active:
|
||||
|
||||
| Workstream | Status | Phase | Progress |
|
||||
| ---------- | -------- | --------------- | -------------------------------- |
|
||||
| {name} | {status} | {current_phase} | {completed_phases}/{phase_count} |
|
||||
| ... | ... | ... | ... |
|
||||
|
||||
---
|
||||
|
||||
## Next Steps
|
||||
|
||||
Archive this workstream:
|
||||
|
||||
`/gsd-workstreams complete {current_ws_name} ${GSD_WS}`
|
||||
|
||||
See overall milestone progress:
|
||||
|
||||
`/gsd-workstreams progress ${GSD_WS}`
|
||||
|
||||
<sub>Milestone completion will be available once all workstreams finish.</sub>
|
||||
|
||||
---
|
||||
```
|
||||
|
||||
Do NOT suggest `/gsd-complete-milestone` or `/gsd-new-milestone`.
|
||||
Do NOT auto-invoke any further slash commands.
|
||||
|
||||
**Stop here.** The user must explicitly decide what to do next.
|
||||
|
||||
---
|
||||
|
||||
**Route B: Milestone complete (all phases done)**
|
||||
|
||||
**This route is only reached when:**
|
||||
- `is_last_phase: true` AND no other active workstreams exist (or flat mode)
|
||||
|
||||
**Clear auto-advance chain flag** - milestone boundary is the natural stopping point:
|
||||
|
||||
```bash
|
||||
pi-gsd-tools 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} ${GSD_WS}")
|
||||
|
||||
</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} ${GSD_WS}`
|
||||
|
||||
<sub>`/new` 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>
|
||||
384
.pi/gsd/workflows/ui-phase.md
Normal file
384
.pi/gsd/workflows/ui-phase.md
Normal file
@@ -0,0 +1,384 @@
|
||||
<gsd-version v="1.12.5" />
|
||||
|
||||
<gsd-arguments>
|
||||
<settings><keep-extra-args /></settings>
|
||||
<arg name="phase" type="number" />
|
||||
</gsd-arguments>
|
||||
|
||||
<gsd-execute>
|
||||
<shell command="pi-gsd-tools">
|
||||
<args>
|
||||
<arg string="init" />
|
||||
<arg string="plan-phase" />
|
||||
<arg name="phase" wrap='"' />
|
||||
</args>
|
||||
<outs>
|
||||
<out type="string" name="init" />
|
||||
</outs>
|
||||
</shell>
|
||||
<if>
|
||||
<condition>
|
||||
<starts-with>
|
||||
<left name="init" />
|
||||
<right type="string" value="@file:" />
|
||||
</starts-with>
|
||||
</condition>
|
||||
<then>
|
||||
<string-op op="split">
|
||||
<args>
|
||||
<arg name="init" />
|
||||
<arg type="string" value="@file:" />
|
||||
</args>
|
||||
<outs>
|
||||
<out type="string" name="init-file" />
|
||||
</outs>
|
||||
</string-op>
|
||||
<shell command="cat">
|
||||
<args>
|
||||
<arg name="init-file" wrap='"' />
|
||||
</args>
|
||||
<outs>
|
||||
<out type="string" name="init" />
|
||||
</outs>
|
||||
</shell>
|
||||
</then>
|
||||
</if>
|
||||
<shell command="pi-gsd-tools">
|
||||
<args>
|
||||
<arg string="resolve-model" />
|
||||
<arg string="gsd-ui-researcher" />
|
||||
<arg string="--raw" />
|
||||
</args>
|
||||
<outs>
|
||||
<suppress-errors />
|
||||
<out type="string" name="ui-researcher-model" />
|
||||
</outs>
|
||||
</shell>
|
||||
<shell command="pi-gsd-tools">
|
||||
<args>
|
||||
<arg string="agent-skills" />
|
||||
<arg string="gsd-ui-researcher" />
|
||||
</args>
|
||||
<outs>
|
||||
<suppress-errors />
|
||||
<out type="string" name="agent-skills-ui-researcher" />
|
||||
</outs>
|
||||
</shell>
|
||||
<shell command="pi-gsd-tools">
|
||||
<args>
|
||||
<arg string="agent-skills" />
|
||||
<arg string="gsd-ui-checker" />
|
||||
</args>
|
||||
<outs>
|
||||
<suppress-errors />
|
||||
<out type="string" name="agent-skills-ui-checker" />
|
||||
</outs>
|
||||
</shell>
|
||||
</gsd-execute>
|
||||
|
||||
## Context (pre-injected)
|
||||
|
||||
**Phase:** <gsd-paste name="phase" />
|
||||
|
||||
**Init Data:**
|
||||
<gsd-paste name="init" />
|
||||
|
||||
**UI Researcher Model:** <gsd-paste name="ui-researcher-model" />
|
||||
|
||||
<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>
|
||||
@.pi/gsd/references/ui-brand.md
|
||||
</required_reading>
|
||||
|
||||
<available_agent_types>
|
||||
Valid GSD subagent types (use exact names - do not fall back to 'general-purpose'):
|
||||
- gsd-ui-researcher - Researches UI/UX approaches
|
||||
- gsd-ui-checker - Reviews UI implementation quality
|
||||
</available_agent_types>
|
||||
|
||||
<process>
|
||||
|
||||
## 1. Initialize
|
||||
|
||||
<!-- Context pre-injected above via WXP - variables available via <gsd-paste name="..."> -->
|
||||
|
||||
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=$(pi-gsd-tools resolve-model gsd-ui-researcher --raw)
|
||||
UI_CHECKER_MODEL=$(pi-gsd-tools resolve-model gsd-ui-checker --raw)
|
||||
```
|
||||
|
||||
Check config:
|
||||
|
||||
```bash
|
||||
UI_ENABLED=$(pi-gsd-tools 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=$(pi-gsd-tools 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 .pi/gsd/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>
|
||||
|
||||
${AGENT_SKILLS_UI}
|
||||
|
||||
<output>
|
||||
Write to: {phase_dir}/{padded_phase}-UI-SPEC.md
|
||||
Template: .pi/gsd/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 .pi/gsd/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>
|
||||
|
||||
${AGENT_SKILLS_UI_CHECKER}
|
||||
|
||||
<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>/new first → fresh context window</sub>
|
||||
|
||||
───────────────────────────────────────────────────────────────
|
||||
```
|
||||
|
||||
## 11. Commit (if configured)
|
||||
|
||||
```bash
|
||||
pi-gsd-tools commit "docs(${padded_phase}): UI design contract" --files "${PHASE_DIR}/${PADDED_PHASE}-UI-SPEC.md"
|
||||
```
|
||||
|
||||
## 12. Update State
|
||||
|
||||
```bash
|
||||
pi-gsd-tools 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>
|
||||
237
.pi/gsd/workflows/ui-review.md
Normal file
237
.pi/gsd/workflows/ui-review.md
Normal file
@@ -0,0 +1,237 @@
|
||||
<gsd-version v="1.12.4" />
|
||||
|
||||
<gsd-arguments>
|
||||
<settings><keep-extra-args /></settings>
|
||||
<arg name="phase" type="number" />
|
||||
</gsd-arguments>
|
||||
|
||||
<gsd-execute>
|
||||
<shell command="pi-gsd-tools">
|
||||
<args>
|
||||
<arg string="init" />
|
||||
<arg string="phase-op" />
|
||||
</args>
|
||||
<outs>
|
||||
<out type="string" name="init" />
|
||||
</outs>
|
||||
</shell>
|
||||
<if>
|
||||
<condition>
|
||||
<starts-with>
|
||||
<left name="init" />
|
||||
<right type="string" value="@file:" />
|
||||
</starts-with>
|
||||
</condition>
|
||||
<then>
|
||||
<string-op op="split">
|
||||
<args>
|
||||
<arg name="init" />
|
||||
<arg type="string" value="@file:" />
|
||||
</args>
|
||||
<outs>
|
||||
<out type="string" name="init-file" />
|
||||
</outs>
|
||||
</string-op>
|
||||
<shell command="cat">
|
||||
<args>
|
||||
<arg name="init-file" wrap='"' />
|
||||
</args>
|
||||
<outs>
|
||||
<out type="string" name="init" />
|
||||
</outs>
|
||||
</shell>
|
||||
</then>
|
||||
</if>
|
||||
<shell command="pi-gsd-tools">
|
||||
<args>
|
||||
<arg string="resolve-model" />
|
||||
<arg string="gsd-ui-auditor" />
|
||||
<arg string="--raw" />
|
||||
</args>
|
||||
<outs>
|
||||
<suppress-errors />
|
||||
<out type="string" name="ui-auditor-model" />
|
||||
</outs>
|
||||
</shell>
|
||||
<shell command="pi-gsd-tools">
|
||||
<args>
|
||||
<arg string="agent-skills" />
|
||||
<arg string="gsd-ui-reviewer" />
|
||||
</args>
|
||||
<outs>
|
||||
<suppress-errors />
|
||||
<out type="string" name="agent-skills-ui-reviewer" />
|
||||
</outs>
|
||||
</shell>
|
||||
</gsd-execute>
|
||||
|
||||
## Context (pre-injected)
|
||||
|
||||
**Phase:** <gsd-paste name="phase" />
|
||||
|
||||
**Phase Data:**
|
||||
<gsd-paste name="init" />
|
||||
|
||||
**UI Auditor Model:** <gsd-paste name="ui-auditor-model" />
|
||||
|
||||
<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>
|
||||
@.pi/gsd/references/ui-brand.md
|
||||
</required_reading>
|
||||
|
||||
<available_agent_types>
|
||||
Valid GSD subagent types (use exact names - do not fall back to 'general-purpose'):
|
||||
- gsd-ui-auditor - Audits UI against design requirements
|
||||
</available_agent_types>
|
||||
|
||||
<process>
|
||||
|
||||
## 0. Initialize
|
||||
|
||||
<!-- Context pre-injected above via WXP - variables available via <gsd-paste name="..."> -->
|
||||
|
||||
Parse: `phase_dir`, `phase_number`, `phase_name`, `phase_slug`, `padded_phase`, `commit_docs`.
|
||||
|
||||
```bash
|
||||
UI_AUDITOR_MODEL=$(pi-gsd-tools 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 .pi/gsd/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>
|
||||
|
||||
${AGENT_SKILLS_UI_REVIEWER}
|
||||
|
||||
<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>/new first → fresh context window</sub>
|
||||
|
||||
───────────────────────────────────────────────────────────────
|
||||
```
|
||||
|
||||
## 5. Commit (if configured)
|
||||
|
||||
```bash
|
||||
pi-gsd-tools 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>
|
||||
325
.pi/gsd/workflows/update.md
Normal file
325
.pi/gsd/workflows/update.md
Normal file
@@ -0,0 +1,325 @@
|
||||
<gsd-version v="1.12.4" />
|
||||
|
||||
<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: `.agent/`, `~/.config/opencode/`, `~/.opencode/`, `~/.gemini/`, or `~/.codex/`
|
||||
local: `./.agent/`, `./.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 GEMINI.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/gsd-build/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>
|
||||
247
.pi/gsd/workflows/validate-phase.md
Normal file
247
.pi/gsd/workflows/validate-phase.md
Normal file
@@ -0,0 +1,247 @@
|
||||
<gsd-version v="1.12.4" />
|
||||
|
||||
<gsd-arguments>
|
||||
<settings>
|
||||
<keep-extra-args />
|
||||
</settings>
|
||||
<arg name="phase" type="number" />
|
||||
</gsd-arguments>
|
||||
|
||||
<gsd-execute>
|
||||
<shell command="pi-gsd-tools">
|
||||
<args>
|
||||
<arg string="init" />
|
||||
<arg string="phase-op" />
|
||||
<arg name="phase" wrap='"' />
|
||||
</args>
|
||||
<outs>
|
||||
<out type="string" name="init" />
|
||||
</outs>
|
||||
</shell>
|
||||
<if>
|
||||
<condition>
|
||||
<starts-with>
|
||||
<left name="init" />
|
||||
<right type="string" value="@file:" />
|
||||
</starts-with>
|
||||
</condition>
|
||||
<then>
|
||||
<string-op op="split">
|
||||
<args>
|
||||
<arg name="init" />
|
||||
<arg type="string" value="@file:" />
|
||||
</args>
|
||||
<outs>
|
||||
<out type="string" name="init-file" />
|
||||
</outs>
|
||||
</string-op>
|
||||
<shell command="cat">
|
||||
<args>
|
||||
<arg name="init-file" wrap='"' />
|
||||
</args>
|
||||
<outs>
|
||||
<out type="string" name="init" />
|
||||
</outs>
|
||||
</shell>
|
||||
</then>
|
||||
</if>
|
||||
<shell command="pi-gsd-tools">
|
||||
<args>
|
||||
<arg string="agent-skills" />
|
||||
<arg string="gsd-nyquist-auditor" />
|
||||
</args>
|
||||
<outs>
|
||||
<suppress-errors />
|
||||
<out type="string" name="agent-skills-auditor" />
|
||||
</outs>
|
||||
</shell>
|
||||
<shell command="pi-gsd-tools">
|
||||
<args>
|
||||
<arg string="resolve-model" />
|
||||
<arg string="gsd-nyquist-auditor" />
|
||||
<arg string="--raw" />
|
||||
</args>
|
||||
<outs>
|
||||
<suppress-errors />
|
||||
<out type="string" name="auditor-model" />
|
||||
</outs>
|
||||
</shell>
|
||||
<shell command="pi-gsd-tools">
|
||||
<args>
|
||||
<arg string="config-get" />
|
||||
<arg string="workflow.nyquist_validation" />
|
||||
<arg string="--raw" />
|
||||
</args>
|
||||
<outs>
|
||||
<suppress-errors />
|
||||
<out type="string" name="nyquist-cfg" />
|
||||
</outs>
|
||||
</shell>
|
||||
</gsd-execute>
|
||||
|
||||
## Initialization Context (pre-injected by WXP)
|
||||
|
||||
**Phase:** <gsd-paste name="phase" />
|
||||
|
||||
**Phase Init Data:**
|
||||
<gsd-paste name="init" />
|
||||
|
||||
**Auditor Model:** <gsd-paste name="auditor-model" />
|
||||
|
||||
<process>
|
||||
|
||||
## 0. Initialize
|
||||
|
||||
<!-- Context pre-injected above via WXP - variables available via <gsd-paste name="..."> -->
|
||||
|
||||
Parse: `phase_dir`, `phase_number`, `phase_name`, `phase_slug`, `padded_phase`.
|
||||
|
||||
```bash
|
||||
AUDITOR_MODEL=$(pi-gsd-tools resolve-model gsd-nyquist-auditor --raw)
|
||||
NYQUIST_CFG=$(pi-gsd-tools 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} ${GSD_WS} 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 .pi/gsd/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>" +
|
||||
"${AGENT_SKILLS_AUDITOR}",
|
||||
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 `.pi/gsd/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"
|
||||
|
||||
pi-gsd-tools 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 ${GSD_WS}
|
||||
```
|
||||
|
||||
**Partial:**
|
||||
```
|
||||
GSD > PHASE {N} VALIDATED (PARTIAL)
|
||||
{M} automated, {K} manual-only.
|
||||
▶ Retry: /gsd-validate-phase {N} ${GSD_WS}
|
||||
```
|
||||
|
||||
Display `/new` 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>
|
||||
326
.pi/gsd/workflows/verify-phase.md
Normal file
326
.pi/gsd/workflows/verify-phase.md
Normal file
@@ -0,0 +1,326 @@
|
||||
<gsd-version v="1.12.4" />
|
||||
|
||||
<gsd-arguments>
|
||||
<settings><keep-extra-args /></settings>
|
||||
<arg name="phase" type="number" />
|
||||
</gsd-arguments>
|
||||
|
||||
<gsd-execute>
|
||||
<shell command="pi-gsd-tools">
|
||||
<args>
|
||||
<arg string="init" />
|
||||
<arg string="phase-op" />
|
||||
</args>
|
||||
<outs>
|
||||
<out type="string" name="init" />
|
||||
</outs>
|
||||
</shell>
|
||||
<if>
|
||||
<condition>
|
||||
<starts-with>
|
||||
<left name="init" />
|
||||
<right type="string" value="@file:" />
|
||||
</starts-with>
|
||||
</condition>
|
||||
<then>
|
||||
<string-op op="split">
|
||||
<args>
|
||||
<arg name="init" />
|
||||
<arg type="string" value="@file:" />
|
||||
</args>
|
||||
<outs>
|
||||
<out type="string" name="init-file" />
|
||||
</outs>
|
||||
</string-op>
|
||||
<shell command="cat">
|
||||
<args>
|
||||
<arg name="init-file" wrap='"' />
|
||||
</args>
|
||||
<outs>
|
||||
<out type="string" name="init" />
|
||||
</outs>
|
||||
</shell>
|
||||
</then>
|
||||
</if>
|
||||
<shell command="pi-gsd-tools">
|
||||
<args>
|
||||
<arg string="roadmap" />
|
||||
<arg string="get-phase" />
|
||||
</args>
|
||||
<outs>
|
||||
<out type="string" name="roadmap-phase" />
|
||||
</outs>
|
||||
</shell>
|
||||
<shell command="pi-gsd-tools">
|
||||
<args>
|
||||
<arg string="state" />
|
||||
<arg string="json" />
|
||||
<arg string="--raw" />
|
||||
</args>
|
||||
<outs>
|
||||
<out type="string" name="state" />
|
||||
</outs>
|
||||
</shell>
|
||||
</gsd-execute>
|
||||
|
||||
## Context (pre-injected)
|
||||
|
||||
**Phase:** <gsd-paste name="phase" />
|
||||
|
||||
**Phase Data:**
|
||||
<gsd-paste name="init" />
|
||||
|
||||
**Roadmap:**
|
||||
<gsd-paste name="roadmap-phase" />
|
||||
|
||||
<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>
|
||||
@.pi/gsd/references/verification-patterns.md
|
||||
@.pi/gsd/templates/verification-report.md
|
||||
</required_reading>
|
||||
|
||||
<process>
|
||||
|
||||
<step name="load_context" priority="first">
|
||||
Load phase operation context:
|
||||
|
||||
<!-- Context pre-injected above via WXP - variables available via <gsd-paste name="..."> -->
|
||||
|
||||
Extract from init JSON: `phase_dir`, `phase_number`, `phase_name`, `has_plans`, `plan_count`.
|
||||
|
||||
Then load phase details and list plans/summaries:
|
||||
```bash
|
||||
pi-gsd-tools roadmap get-phase "${phase_number}"
|
||||
grep -E "^| ${phase_number}" .planning/REQUIREMENTS.md 2>/dev/null || true
|
||||
ls "$phase_dir"/*-SUMMARY.md "$phase_dir"/*-PLAN.md 2>/dev/null || true
|
||||
```
|
||||
|
||||
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=$(pi-gsd-tools 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=$(pi-gsd-tools 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=$(pi-gsd-tools 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=$(pi-gsd-tools 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 || true
|
||||
```
|
||||
|
||||
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 .pi/gsd/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>
|
||||
693
.pi/gsd/workflows/verify-work.md
Normal file
693
.pi/gsd/workflows/verify-work.md
Normal file
@@ -0,0 +1,693 @@
|
||||
<gsd-version v="1.12.4" />
|
||||
|
||||
<gsd-arguments>
|
||||
<settings>
|
||||
<keep-extra-args />
|
||||
</settings>
|
||||
<arg name="phase" type="number" optional />
|
||||
<arg name="plan" type="flag" flag="--plan" optional />
|
||||
</gsd-arguments>
|
||||
|
||||
<gsd-execute>
|
||||
<if>
|
||||
<condition>
|
||||
<equals>
|
||||
<left name="phase" />
|
||||
<right type="string" value="" />
|
||||
</equals>
|
||||
</condition>
|
||||
<else>
|
||||
<shell command="pi-gsd-tools">
|
||||
<args>
|
||||
<arg string="init" />
|
||||
<arg string="verify-work" />
|
||||
<arg name="phase" wrap='"' />
|
||||
</args>
|
||||
<outs>
|
||||
<out type="string" name="init" />
|
||||
</outs>
|
||||
</shell>
|
||||
<if>
|
||||
<condition>
|
||||
<starts-with>
|
||||
<left name="init" />
|
||||
<right type="string" value="@file:" />
|
||||
</starts-with>
|
||||
</condition>
|
||||
<then>
|
||||
<string-op op="split">
|
||||
<args>
|
||||
<arg name="init" />
|
||||
<arg type="string" value="@file:" />
|
||||
</args>
|
||||
<outs>
|
||||
<out type="string" name="init-file" />
|
||||
</outs>
|
||||
</string-op>
|
||||
<shell command="cat">
|
||||
<args>
|
||||
<arg name="init-file" wrap='"' />
|
||||
</args>
|
||||
<outs>
|
||||
<out type="string" name="init" />
|
||||
</outs>
|
||||
</shell>
|
||||
</then>
|
||||
</if>
|
||||
<shell command="pi-gsd-tools">
|
||||
<args>
|
||||
<arg string="agent-skills" />
|
||||
<arg string="gsd-planner" />
|
||||
</args>
|
||||
<outs>
|
||||
<suppress-errors />
|
||||
<out type="string" name="agent-skills-planner" />
|
||||
</outs>
|
||||
</shell>
|
||||
<shell command="pi-gsd-tools">
|
||||
<args>
|
||||
<arg string="agent-skills" />
|
||||
<arg string="gsd-plan-checker" />
|
||||
</args>
|
||||
<outs>
|
||||
<suppress-errors />
|
||||
<out type="string" name="agent-skills-checker" />
|
||||
</outs>
|
||||
</shell>
|
||||
</else>
|
||||
</if>
|
||||
</gsd-execute>
|
||||
|
||||
## Initialization Context (pre-injected by WXP)
|
||||
|
||||
**Phase:** <gsd-paste name="phase" />
|
||||
|
||||
**Phase Init Data:**
|
||||
<gsd-paste name="init" />
|
||||
|
||||
<process>
|
||||
|
||||
<step name="initialize" priority="first">
|
||||
If $ARGUMENTS contains a phase number, load context:
|
||||
|
||||
<!-- Context pre-injected above via WXP - variables available via <gsd-paste name="..."> -->
|
||||
|
||||
Parse JSON for: `planner_model`, `checker_model`, `commit_docs`, `phase_found`, `phase_dir`, `phase_number`, `phase_name`, `has_verification`, `uat_path`.
|
||||
</step>
|
||||
|
||||
<step name="check_active_session">
|
||||
**First: Check for active UAT sessions**
|
||||
|
||||
```bash
|
||||
(find .planning/phases -name "*-UAT.md" -type f 2>/dev/null || true) | 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 || true
|
||||
```
|
||||
|
||||
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:**
|
||||
|
||||
Render the checkpoint from the structured UAT file instead of composing it freehand:
|
||||
|
||||
```bash
|
||||
CHECKPOINT=$(pi-gsd-tools uat render-checkpoint --file "$uat_path" --raw)
|
||||
if [[ "$CHECKPOINT" == @file:* ]]; then CHECKPOINT=$(cat "${CHECKPOINT#@file:}"); fi
|
||||
```
|
||||
|
||||
Display the returned checkpoint EXACTLY as-is:
|
||||
|
||||
```
|
||||
{CHECKPOINT}
|
||||
```
|
||||
|
||||
**Critical response hygiene:**
|
||||
- Your entire response MUST equal `{CHECKPOINT}` byte-for-byte.
|
||||
- Do NOT add commentary before or after the block.
|
||||
- If you notice protocol/meta markers such as `to=all:`, role-routing text, XML system tags, hidden instruction markers, ad copy, or any unrelated suffix, discard the draft and output `{CHECKPOINT}` only.
|
||||
|
||||
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 indicates blocked:**
|
||||
- "blocked", "can't test - server not running", "need physical device", "need release build"
|
||||
- Or any response containing: "server", "blocked", "not running", "physical device", "release build"
|
||||
|
||||
Infer blocked_by tag from response:
|
||||
- Contains: server, not running, gateway, API → `server`
|
||||
- Contains: physical, device, hardware, real phone → `physical-device`
|
||||
- Contains: release, preview, build, EAS → `release-build`
|
||||
- Contains: stripe, twilio, third-party, configure → `third-party`
|
||||
- Contains: depends on, prior phase, prerequisite → `prior-phase`
|
||||
- Default: `other`
|
||||
|
||||
Update Tests section:
|
||||
```
|
||||
### {N}. {name}
|
||||
expected: {expected}
|
||||
result: blocked
|
||||
blocked_by: {inferred tag}
|
||||
reason: "{verbatim user response}"
|
||||
```
|
||||
|
||||
Note: Blocked tests do NOT go into the Gaps section (they aren't code issues - they're prerequisite gates).
|
||||
|
||||
**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:**
|
||||
|
||||
**Determine final status:**
|
||||
|
||||
Count results:
|
||||
- `pending_count`: tests with `result: [pending]`
|
||||
- `blocked_count`: tests with `result: blocked`
|
||||
- `skipped_no_reason`: tests with `result: skipped` and no `reason` field
|
||||
|
||||
```
|
||||
if pending_count > 0 OR blocked_count > 0 OR skipped_no_reason > 0:
|
||||
status: partial
|
||||
# Session ended but not all tests resolved
|
||||
else:
|
||||
status: complete
|
||||
# All tests have a definitive result (pass, issue, or skipped-with-reason)
|
||||
```
|
||||
|
||||
Update frontmatter:
|
||||
- status: {computed status}
|
||||
- updated: [now]
|
||||
|
||||
Clear Current Test section:
|
||||
```
|
||||
## Current Test
|
||||
|
||||
[testing complete]
|
||||
```
|
||||
|
||||
Commit the UAT file:
|
||||
```bash
|
||||
pi-gsd-tools 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 @.pi/gsd/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>
|
||||
|
||||
${AGENT_SKILLS_PLANNER}
|
||||
|
||||
</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>
|
||||
|
||||
${AGENT_SKILLS_CHECKER}
|
||||
|
||||
</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>
|
||||
|
||||
${AGENT_SKILLS_PLANNER}
|
||||
|
||||
**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
|
||||
|
||||
`/new` 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>
|
||||
215
.pi/gsd/workflows/workstreams.md
Normal file
215
.pi/gsd/workflows/workstreams.md
Normal file
@@ -0,0 +1,215 @@
|
||||
<gsd-version v="1.12.4" />
|
||||
|
||||
<gsd-arguments>
|
||||
<settings>
|
||||
<keep-extra-args />
|
||||
</settings>
|
||||
<arg name="subcommand" type="string" optional />
|
||||
<arg name="name" type="string" optional />
|
||||
</gsd-arguments>
|
||||
|
||||
<gsd-execute>
|
||||
<display msg="Loading workstream state..." />
|
||||
<shell command="pi-gsd-tools">
|
||||
<args>
|
||||
<arg string="workstream" />
|
||||
<arg string="list" />
|
||||
<arg string="--raw" />
|
||||
</args>
|
||||
<outs>
|
||||
<suppress-errors />
|
||||
<out type="string" name="ws-list" />
|
||||
</outs>
|
||||
</shell>
|
||||
<shell command="pi-gsd-tools">
|
||||
<args>
|
||||
<arg string="workstream" />
|
||||
<arg string="get" />
|
||||
<arg string="--raw" />
|
||||
</args>
|
||||
<outs>
|
||||
<suppress-errors />
|
||||
<out type="string" name="ws-active" />
|
||||
</outs>
|
||||
</shell>
|
||||
<shell command="pi-gsd-tools">
|
||||
<args>
|
||||
<arg string="state" />
|
||||
<arg string="json" />
|
||||
<arg string="--raw" />
|
||||
</args>
|
||||
<outs>
|
||||
<suppress-errors />
|
||||
<out type="string" name="state" />
|
||||
</outs>
|
||||
</shell>
|
||||
</gsd-execute>
|
||||
|
||||
## Workstream Context (pre-injected by WXP)
|
||||
|
||||
**Subcommand:** <gsd-paste name="subcommand" />
|
||||
**Name:** <gsd-paste name="name" />
|
||||
|
||||
**Active workstream:** <gsd-paste name="ws-active" />
|
||||
|
||||
**Workstream list:**
|
||||
<gsd-paste name="ws-list" />
|
||||
|
||||
**State:**
|
||||
<gsd-paste name="state" />
|
||||
|
||||
---
|
||||
|
||||
<purpose>
|
||||
Manage GSD workstreams — isolated parallel tracks of work within a project.
|
||||
Each workstream has its own ROADMAP.md, STATE.md, and phase history.
|
||||
|
||||
Subcommands: list, create <name>, switch <name>, status [name], complete <name>
|
||||
</purpose>
|
||||
|
||||
<process>
|
||||
|
||||
<step name="route">
|
||||
<!-- Context pre-injected above via WXP -->
|
||||
|
||||
Parse `subcommand` and `name` from injected variables.
|
||||
|
||||
**Route by subcommand:**
|
||||
|
||||
| Subcommand | Action |
|
||||
|------------|--------|
|
||||
| `list` (or empty) | → **list_workstreams** |
|
||||
| `create <name>` | → **create_workstream** |
|
||||
| `switch <name>` | → **switch_workstream** |
|
||||
| `status [name]` | → **show_status** |
|
||||
| `complete <name>` | → **complete_workstream** |
|
||||
|
||||
**If subcommand is unrecognised:** Show help (see offer_help step).
|
||||
</step>
|
||||
|
||||
<step name="list_workstreams">
|
||||
<!-- ws-list and ws-active are pre-injected -->
|
||||
|
||||
Parse `ws-list` JSON for workstream entries. Display:
|
||||
|
||||
```
|
||||
## Workstreams
|
||||
|
||||
Active: {ws-active || "(none — on main planning root)"}
|
||||
|
||||
| Name | Status | Phases | Progress |
|
||||
|------|--------|--------|---------|
|
||||
| {name} | {active|inactive} | {phase_count} | {pct}% |
|
||||
| ... | ... | ... | ... |
|
||||
|
||||
---
|
||||
/gsd-workstreams create <name> - create a new workstream
|
||||
/gsd-workstreams switch <name> - switch to a workstream
|
||||
/gsd-workstreams status <name> - detailed workstream status
|
||||
/gsd-workstreams complete <name> - close a workstream
|
||||
```
|
||||
|
||||
**If no workstreams exist:**
|
||||
```
|
||||
No workstreams yet. You're working in the main planning root.
|
||||
|
||||
Create a workstream to isolate parallel work:
|
||||
/gsd-workstreams create <name>
|
||||
```
|
||||
</step>
|
||||
|
||||
<step name="create_workstream">
|
||||
**Require `name`:**
|
||||
If `name` is empty, ask: "Workstream name? (lowercase, no spaces — e.g. mobile-app, api-v2)"
|
||||
|
||||
Validate: lowercase alphanumeric with hyphens/underscores only.
|
||||
|
||||
```bash
|
||||
pi-gsd-tools workstream create {name}
|
||||
```
|
||||
|
||||
Confirm:
|
||||
```
|
||||
✓ Workstream '{name}' created
|
||||
|
||||
To switch to it: /gsd-workstreams switch {name}
|
||||
```
|
||||
</step>
|
||||
|
||||
<step name="switch_workstream">
|
||||
**Require `name`:** If empty, list available workstreams and ask user to choose.
|
||||
|
||||
```bash
|
||||
pi-gsd-tools workstream set {name}
|
||||
```
|
||||
|
||||
Confirm:
|
||||
```
|
||||
✓ Switched to workstream: {name}
|
||||
|
||||
All subsequent GSD commands will operate within this workstream.
|
||||
To return to main: /gsd-workstreams switch main
|
||||
```
|
||||
</step>
|
||||
|
||||
<step name="show_status">
|
||||
**Target:** `name` if provided, otherwise the active workstream.
|
||||
|
||||
```bash
|
||||
pi-gsd-tools workstream status {name}
|
||||
```
|
||||
|
||||
Display the full status output including phase progress, open todos, and blockers.
|
||||
</step>
|
||||
|
||||
<step name="complete_workstream">
|
||||
**Require `name`:** If empty, ask which workstream to complete.
|
||||
|
||||
Confirm before completing:
|
||||
```
|
||||
Complete workstream '{name}'?
|
||||
|
||||
This will:
|
||||
- Mark all phases as complete
|
||||
- Archive the workstream planning files
|
||||
|
||||
Continue? (yes / no)
|
||||
```
|
||||
|
||||
If yes:
|
||||
```bash
|
||||
pi-gsd-tools workstream complete {name}
|
||||
```
|
||||
|
||||
Confirm:
|
||||
```
|
||||
✓ Workstream '{name}' completed and archived.
|
||||
```
|
||||
</step>
|
||||
|
||||
<step name="offer_help">
|
||||
```
|
||||
## /gsd-workstreams
|
||||
|
||||
Manage parallel tracks of work within a project.
|
||||
|
||||
Usage:
|
||||
/gsd-workstreams - list all workstreams
|
||||
/gsd-workstreams create <name> - create a new workstream
|
||||
/gsd-workstreams switch <name> - activate a workstream
|
||||
/gsd-workstreams status [name] - show workstream details
|
||||
/gsd-workstreams complete <name> - close a finished workstream
|
||||
|
||||
Current: {ws-active || "main planning root"}
|
||||
```
|
||||
</step>
|
||||
|
||||
</process>
|
||||
|
||||
<success_criteria>
|
||||
- [ ] Active workstream pre-injected (no runtime read needed)
|
||||
- [ ] Workstream list pre-injected
|
||||
- [ ] Subcommand routed correctly
|
||||
- [ ] Each action calls the appropriate CLI command
|
||||
- [ ] Confirmations displayed after mutations
|
||||
</success_criteria>
|
||||
Reference in New Issue
Block a user