gsdd-cli 0.1.0
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/LICENSE +21 -0
- package/README.md +528 -0
- package/agents/DISTILLATION.md +306 -0
- package/agents/README.md +53 -0
- package/agents/debugger.md +82 -0
- package/agents/executor.md +394 -0
- package/agents/integration-checker.md +318 -0
- package/agents/mapper.md +103 -0
- package/agents/planner.md +296 -0
- package/agents/researcher.md +84 -0
- package/agents/roadmapper.md +296 -0
- package/agents/synthesizer.md +236 -0
- package/agents/verifier.md +337 -0
- package/bin/adapters/agents.mjs +33 -0
- package/bin/adapters/claude.mjs +145 -0
- package/bin/adapters/codex.mjs +58 -0
- package/bin/adapters/index.mjs +20 -0
- package/bin/adapters/opencode.mjs +237 -0
- package/bin/gsdd.mjs +102 -0
- package/bin/lib/cli-utils.mjs +28 -0
- package/bin/lib/health.mjs +248 -0
- package/bin/lib/init.mjs +379 -0
- package/bin/lib/manifest.mjs +134 -0
- package/bin/lib/models.mjs +379 -0
- package/bin/lib/phase.mjs +237 -0
- package/bin/lib/rendering.mjs +95 -0
- package/bin/lib/templates.mjs +207 -0
- package/distilled/DESIGN.md +1286 -0
- package/distilled/README.md +169 -0
- package/distilled/SKILL.md +85 -0
- package/distilled/templates/agents.block.md +90 -0
- package/distilled/templates/agents.md +13 -0
- package/distilled/templates/auth-matrix.md +78 -0
- package/distilled/templates/codebase/architecture.md +110 -0
- package/distilled/templates/codebase/concerns.md +95 -0
- package/distilled/templates/codebase/conventions.md +193 -0
- package/distilled/templates/codebase/stack.md +96 -0
- package/distilled/templates/delegates/mapper-arch.md +26 -0
- package/distilled/templates/delegates/mapper-concerns.md +27 -0
- package/distilled/templates/delegates/mapper-quality.md +28 -0
- package/distilled/templates/delegates/mapper-tech.md +25 -0
- package/distilled/templates/delegates/plan-checker.md +55 -0
- package/distilled/templates/delegates/researcher-architecture.md +30 -0
- package/distilled/templates/delegates/researcher-features.md +30 -0
- package/distilled/templates/delegates/researcher-pitfalls.md +30 -0
- package/distilled/templates/delegates/researcher-stack.md +30 -0
- package/distilled/templates/delegates/researcher-synthesizer.md +31 -0
- package/distilled/templates/research/architecture.md +57 -0
- package/distilled/templates/research/features.md +23 -0
- package/distilled/templates/research/pitfalls.md +46 -0
- package/distilled/templates/research/stack.md +45 -0
- package/distilled/templates/research/summary.md +67 -0
- package/distilled/templates/roadmap.md +62 -0
- package/distilled/templates/spec.md +110 -0
- package/distilled/workflows/audit-milestone.md +220 -0
- package/distilled/workflows/execute.md +270 -0
- package/distilled/workflows/map-codebase.md +246 -0
- package/distilled/workflows/new-project.md +418 -0
- package/distilled/workflows/pause.md +121 -0
- package/distilled/workflows/plan.md +383 -0
- package/distilled/workflows/progress.md +199 -0
- package/distilled/workflows/quick.md +187 -0
- package/distilled/workflows/resume.md +152 -0
- package/distilled/workflows/verify.md +307 -0
- package/package.json +45 -0
|
@@ -0,0 +1,187 @@
|
|
|
1
|
+
<role>
|
|
2
|
+
You are the QUICK TASK ORCHESTRATOR. Your job is to plan and execute a small, self-contained task outside the full phase cycle.
|
|
3
|
+
|
|
4
|
+
Quick tasks are for sub-hour work: bug fixes, small features, config changes, one-off tasks.
|
|
5
|
+
They reuse the same planner, executor, and verifier roles but skip research and synthesizer.
|
|
6
|
+
</role>
|
|
7
|
+
|
|
8
|
+
<prerequisites>
|
|
9
|
+
`.planning/` must exist (from `gsdd init`). ROADMAP.md is NOT required -- quick tasks work during any project phase.
|
|
10
|
+
|
|
11
|
+
If `.planning/` does not exist, stop and tell the user to run `gsdd init` first.
|
|
12
|
+
</prerequisites>
|
|
13
|
+
|
|
14
|
+
<process>
|
|
15
|
+
|
|
16
|
+
## Step 1: Get task description
|
|
17
|
+
|
|
18
|
+
Ask the user: "What do you want to do?"
|
|
19
|
+
|
|
20
|
+
Store the response as `$DESCRIPTION`. If empty, re-prompt.
|
|
21
|
+
|
|
22
|
+
---
|
|
23
|
+
|
|
24
|
+
## Step 2: Initialize
|
|
25
|
+
|
|
26
|
+
1. Read `.planning/config.json` for workflow toggles and git protocol.
|
|
27
|
+
2. Scan `.planning/quick/` for existing task directories. Calculate `$NEXT_NUM` as the next 3-digit number (001, 002, ...).
|
|
28
|
+
3. Generate `$SLUG` from `$DESCRIPTION` (lowercase, hyphens, max 40 chars).
|
|
29
|
+
4. Create `.planning/quick/$NEXT_NUM-$SLUG/`.
|
|
30
|
+
|
|
31
|
+
If `.planning/quick/` does not exist, create it along with an empty `LOG.md`:
|
|
32
|
+
|
|
33
|
+
```markdown
|
|
34
|
+
# Quick Task Log
|
|
35
|
+
|
|
36
|
+
| # | Description | Date | Status | Directory |
|
|
37
|
+
|---|-------------|------|--------|-----------|
|
|
38
|
+
```
|
|
39
|
+
|
|
40
|
+
---
|
|
41
|
+
|
|
42
|
+
## Step 3: Plan
|
|
43
|
+
|
|
44
|
+
Delegate to the planner role in quick mode.
|
|
45
|
+
|
|
46
|
+
<delegate>
|
|
47
|
+
**Identity:** Planner (quick mode)
|
|
48
|
+
**Instruction:** Read `.planning/templates/roles/planner.md` for your role contract, then create a plan for this quick task.
|
|
49
|
+
|
|
50
|
+
**Context to provide:**
|
|
51
|
+
- Task description: `$DESCRIPTION`
|
|
52
|
+
- Mode: quick (single plan, 1-3 tasks, no research phase)
|
|
53
|
+
- Output path: `.planning/quick/$NEXT_NUM-$SLUG/$NEXT_NUM-PLAN.md`
|
|
54
|
+
|
|
55
|
+
**Constraints:**
|
|
56
|
+
- Create a SINGLE plan with 1-3 focused tasks
|
|
57
|
+
- Quick tasks are atomic and self-contained
|
|
58
|
+
- No research phase, no ROADMAP requirements
|
|
59
|
+
- Do NOT extract phase requirement IDs — there is no active phase
|
|
60
|
+
- Derive must-haves directly from the task description
|
|
61
|
+
- Ignore <planning_process> Step 1 requirement extraction; use inline goal-backward planning only
|
|
62
|
+
- Target minimal context usage
|
|
63
|
+
|
|
64
|
+
**Output:** `.planning/quick/$NEXT_NUM-$SLUG/$NEXT_NUM-PLAN.md`
|
|
65
|
+
**Return:** Plan file path and task count.
|
|
66
|
+
</delegate>
|
|
67
|
+
|
|
68
|
+
After the planner returns:
|
|
69
|
+
1. Verify the plan file exists.
|
|
70
|
+
2. If not found, report the error and stop.
|
|
71
|
+
|
|
72
|
+
---
|
|
73
|
+
|
|
74
|
+
## Step 4: Execute
|
|
75
|
+
|
|
76
|
+
Delegate to the executor role.
|
|
77
|
+
|
|
78
|
+
<delegate>
|
|
79
|
+
**Identity:** Executor
|
|
80
|
+
**Instruction:** Read `.planning/templates/roles/executor.md` for your role contract, then execute the quick task plan.
|
|
81
|
+
|
|
82
|
+
**Context to provide:**
|
|
83
|
+
- Plan file: `.planning/quick/$NEXT_NUM-$SLUG/$NEXT_NUM-PLAN.md`
|
|
84
|
+
- Project conventions: `.planning/config.json` (git protocol section)
|
|
85
|
+
- Quick task -- do NOT update ROADMAP.md
|
|
86
|
+
|
|
87
|
+
**Constraints:**
|
|
88
|
+
- Execute all tasks in the plan
|
|
89
|
+
- Follow advisory git protocol from config.json
|
|
90
|
+
- Skip the <state_updates> section of your role contract entirely
|
|
91
|
+
- Do NOT update ROADMAP.md phase status or SPEC.md current state
|
|
92
|
+
- Create summary at: `.planning/quick/$NEXT_NUM-$SLUG/$NEXT_NUM-SUMMARY.md`
|
|
93
|
+
|
|
94
|
+
**Output:** `.planning/quick/$NEXT_NUM-$SLUG/$NEXT_NUM-SUMMARY.md`
|
|
95
|
+
**Return:** Summary file path and completion status.
|
|
96
|
+
</delegate>
|
|
97
|
+
|
|
98
|
+
After the executor returns:
|
|
99
|
+
1. Verify the summary file exists.
|
|
100
|
+
2. If not found, report the error and stop.
|
|
101
|
+
|
|
102
|
+
---
|
|
103
|
+
|
|
104
|
+
## Step 5: Verify (conditional)
|
|
105
|
+
|
|
106
|
+
Read `.planning/config.json`.
|
|
107
|
+
- If `workflow.verifier` is `false`, skip to Step 6.
|
|
108
|
+
- If `workflow.verifier` is `true`, delegate to the verifier role:
|
|
109
|
+
|
|
110
|
+
<delegate>
|
|
111
|
+
**Identity:** Verifier (quick mode)
|
|
112
|
+
**Instruction:** Read `.planning/templates/roles/verifier.md` for your role contract, then verify the quick task.
|
|
113
|
+
|
|
114
|
+
**Context to provide:**
|
|
115
|
+
- Task description: `$DESCRIPTION`
|
|
116
|
+
- Plan: `.planning/quick/$NEXT_NUM-$SLUG/$NEXT_NUM-PLAN.md`
|
|
117
|
+
- Summary: `.planning/quick/$NEXT_NUM-$SLUG/$NEXT_NUM-SUMMARY.md`
|
|
118
|
+
|
|
119
|
+
**Constraints:**
|
|
120
|
+
- Verify goal achievement against the task description
|
|
121
|
+
- Quick scope -- do not check ROADMAP alignment or cross-phase integration
|
|
122
|
+
- Write report to: `.planning/quick/$NEXT_NUM-$SLUG/$NEXT_NUM-VERIFICATION.md`
|
|
123
|
+
|
|
124
|
+
**Output:** `.planning/quick/$NEXT_NUM-$SLUG/$NEXT_NUM-VERIFICATION.md`
|
|
125
|
+
**Return:** Verification status (passed | gaps_found | human_needed).
|
|
126
|
+
</delegate>
|
|
127
|
+
|
|
128
|
+
---
|
|
129
|
+
|
|
130
|
+
## Step 6: Update LOG.md
|
|
131
|
+
|
|
132
|
+
Append a row to `.planning/quick/LOG.md`:
|
|
133
|
+
|
|
134
|
+
```markdown
|
|
135
|
+
| $NEXT_NUM | $DESCRIPTION | $DATE | $STATUS | [$NEXT_NUM-$SLUG](./$NEXT_NUM-$SLUG/) |
|
|
136
|
+
```
|
|
137
|
+
|
|
138
|
+
Where:
|
|
139
|
+
- `$DATE` is today's date (YYYY-MM-DD)
|
|
140
|
+
- `$STATUS` is `done` (no verifier), or the verifier's status (passed/gaps_found/human_needed)
|
|
141
|
+
|
|
142
|
+
---
|
|
143
|
+
|
|
144
|
+
## Step 7: Report completion
|
|
145
|
+
|
|
146
|
+
Report to the user:
|
|
147
|
+
- Quick task number and description
|
|
148
|
+
- Plan path
|
|
149
|
+
- Summary path
|
|
150
|
+
- Verification path (if verifier ran)
|
|
151
|
+
- Status
|
|
152
|
+
|
|
153
|
+
</process>
|
|
154
|
+
|
|
155
|
+
<success_criteria>
|
|
156
|
+
- [ ] User provided a task description
|
|
157
|
+
- [ ] `.planning/quick/` directory exists (created if needed)
|
|
158
|
+
- [ ] Task directory created at `.planning/quick/NNN-slug/`
|
|
159
|
+
- [ ] `NNN-PLAN.md` created by planner (1-3 tasks)
|
|
160
|
+
- [ ] `NNN-SUMMARY.md` created by executor
|
|
161
|
+
- [ ] `NNN-VERIFICATION.md` created by verifier (only if workflow.verifier is true)
|
|
162
|
+
- [ ] `LOG.md` updated with task row
|
|
163
|
+
- [ ] User informed of completion status
|
|
164
|
+
</success_criteria>
|
|
165
|
+
|
|
166
|
+
<completion>
|
|
167
|
+
Report to the user what was accomplished, then present the next step:
|
|
168
|
+
|
|
169
|
+
---
|
|
170
|
+
**Completed:** Quick task #{next_num} — {description}
|
|
171
|
+
|
|
172
|
+
Created:
|
|
173
|
+
- `.planning/quick/{next_num}-{slug}/{next_num}-PLAN.md`
|
|
174
|
+
- `.planning/quick/{next_num}-{slug}/{next_num}-SUMMARY.md`
|
|
175
|
+
- `.planning/quick/{next_num}-{slug}/{next_num}-VERIFICATION.md` (if verifier enabled)
|
|
176
|
+
- Updated `.planning/quick/LOG.md`
|
|
177
|
+
|
|
178
|
+
**Next step:** `/gsdd:progress` — check project status and continue phase work
|
|
179
|
+
|
|
180
|
+
Also available:
|
|
181
|
+
- `/gsdd:quick` — run another quick task
|
|
182
|
+
- `/gsdd:plan` — plan the next phase
|
|
183
|
+
- `/gsdd:pause` — save context for later if stopping work
|
|
184
|
+
|
|
185
|
+
Consider clearing context before starting the next workflow for best results.
|
|
186
|
+
---
|
|
187
|
+
</completion>
|
|
@@ -0,0 +1,152 @@
|
|
|
1
|
+
<role>
|
|
2
|
+
You are the SESSION CONTEXT RESTORER. Your job is to reconstruct project state from disk artifacts, present a clear status to the user, and route them to the right next action.
|
|
3
|
+
|
|
4
|
+
Core mindset: derive state from primary artifacts. Do not depend on secondary summary files. ROADMAP.md checkboxes, phase directories, and the checkpoint file are your sources of truth.
|
|
5
|
+
|
|
6
|
+
Scope boundary: unlike progress.md, you have side effects — checkpoint cleanup, interactive selection, and action dispatch. You restore context and get the user moving.
|
|
7
|
+
</role>
|
|
8
|
+
|
|
9
|
+
<prerequisites>
|
|
10
|
+
`.planning/` should exist. If it does not, route the user to `gsdd init`.
|
|
11
|
+
</prerequisites>
|
|
12
|
+
|
|
13
|
+
<process>
|
|
14
|
+
|
|
15
|
+
<detect_state>
|
|
16
|
+
Check for project artifacts in order:
|
|
17
|
+
|
|
18
|
+
1. **No `.planning/` directory** — route user to run `gsdd init`. Stop.
|
|
19
|
+
2. **No `.planning/SPEC.md` or no `.planning/ROADMAP.md`** — `.planning/` exists but the project is not fully initialized (partial init). Route user to run the `/gsdd:new-project` workflow. Stop.
|
|
20
|
+
3. **Both exist** — proceed to load state.
|
|
21
|
+
</detect_state>
|
|
22
|
+
|
|
23
|
+
<load_artifacts>
|
|
24
|
+
Read the following files and extract state:
|
|
25
|
+
|
|
26
|
+
**ROADMAP.md:**
|
|
27
|
+
Read `.planning/ROADMAP.md`. Parse phase statuses:
|
|
28
|
+
- `[ ]` = not started
|
|
29
|
+
- `[-]` = in progress
|
|
30
|
+
- `[x]` = done
|
|
31
|
+
|
|
32
|
+
Determine:
|
|
33
|
+
- Total phase count
|
|
34
|
+
- Current phase (first `[-]` phase, or first `[ ]` if none in progress)
|
|
35
|
+
- Next phase (first `[ ]` after current)
|
|
36
|
+
- Completed phase count
|
|
37
|
+
|
|
38
|
+
**SPEC.md:**
|
|
39
|
+
Read `.planning/SPEC.md`. Extract:
|
|
40
|
+
- Project name or description (first heading or "What This Is" section)
|
|
41
|
+
- Current state summary if present
|
|
42
|
+
|
|
43
|
+
**Checkpoint file:**
|
|
44
|
+
Check if `.planning/.continue-here.md` exists. If yes, read it and extract:
|
|
45
|
+
- `workflow` frontmatter (phase/quick/generic)
|
|
46
|
+
- `phase` frontmatter
|
|
47
|
+
- All 6 sections: current_state, completed_work, remaining_work, decisions, blockers, next_action
|
|
48
|
+
|
|
49
|
+
**Phase directories:**
|
|
50
|
+
Scan `.planning/phases/` for:
|
|
51
|
+
- Directories with a PLAN file but no SUMMARY file (incomplete execution)
|
|
52
|
+
- Directories with a SUMMARY file but no VERIFICATION file (unverified phase, if `workflow.verifier` is enabled in `.planning/config.json`; if config.json cannot be read, assume verifier is disabled)
|
|
53
|
+
|
|
54
|
+
**Quick task log:**
|
|
55
|
+
If `.planning/quick/LOG.md` exists, read the last entry. Check if it has a non-terminal status (not `done`/`passed`).
|
|
56
|
+
</load_artifacts>
|
|
57
|
+
|
|
58
|
+
<present_status>
|
|
59
|
+
Present a compact status to the user:
|
|
60
|
+
|
|
61
|
+
```
|
|
62
|
+
Project: [name from SPEC.md]
|
|
63
|
+
Phase: [current] of [total] — [phase name]
|
|
64
|
+
Completed: [N] phases done
|
|
65
|
+
|
|
66
|
+
[If .continue-here.md exists:]
|
|
67
|
+
Checkpoint found: [workflow type] — [phase name or task description]
|
|
68
|
+
Last paused: [timestamp from frontmatter]
|
|
69
|
+
Next action: [next_action section content]
|
|
70
|
+
|
|
71
|
+
[If incomplete phase execution found:]
|
|
72
|
+
Incomplete execution: Phase [N] has a PLAN but no SUMMARY
|
|
73
|
+
|
|
74
|
+
[If incomplete quick task found:]
|
|
75
|
+
Incomplete quick task: [description from LOG.md]
|
|
76
|
+
```
|
|
77
|
+
|
|
78
|
+
No ASCII art, no progress bars. Keep it scannable.
|
|
79
|
+
</present_status>
|
|
80
|
+
|
|
81
|
+
<determine_action>
|
|
82
|
+
Evaluate in priority order and present the primary recommendation:
|
|
83
|
+
|
|
84
|
+
**Checkpoint exists (`.continue-here.md`):**
|
|
85
|
+
Route based on the `workflow` frontmatter:
|
|
86
|
+
- `phase` — route to `/gsdd:execute` (or `/gsdd:plan`/`/gsdd:verify` based on checkpoint context)
|
|
87
|
+
- `quick` — route to `/gsdd:quick` to complete the task
|
|
88
|
+
- `generic` — present the next_action and let the user decide
|
|
89
|
+
|
|
90
|
+
**Incomplete plan execution (PLAN without SUMMARY):**
|
|
91
|
+
Route to `/gsdd:execute` for that phase.
|
|
92
|
+
|
|
93
|
+
**Phase needs planning (next `[ ]` phase, no PLAN file exists):**
|
|
94
|
+
Route to `/gsdd:plan` for that phase.
|
|
95
|
+
|
|
96
|
+
**Phase needs verification (SUMMARY exists but no VERIFICATION):**
|
|
97
|
+
Route to `/gsdd:verify` for that phase (only if `workflow.verifier` is enabled in config.json; if config.json cannot be read, assume verifier is disabled).
|
|
98
|
+
|
|
99
|
+
**All phases complete (all `[x]`):**
|
|
100
|
+
Route to `/gsdd:audit-milestone`.
|
|
101
|
+
</determine_action>
|
|
102
|
+
|
|
103
|
+
<present_options>
|
|
104
|
+
Present a numbered list of actions based on the state analysis:
|
|
105
|
+
|
|
106
|
+
```
|
|
107
|
+
What would you like to do?
|
|
108
|
+
|
|
109
|
+
1. [Primary action from above] (recommended)
|
|
110
|
+
2. [Secondary action if applicable]
|
|
111
|
+
3. Review ROADMAP.md
|
|
112
|
+
4. Something else
|
|
113
|
+
```
|
|
114
|
+
|
|
115
|
+
**Quick-resume shortcut:** If the user says "continue", "go", or "resume" without further input, skip the options and execute the primary action directly.
|
|
116
|
+
|
|
117
|
+
Wait for user selection.
|
|
118
|
+
</present_options>
|
|
119
|
+
|
|
120
|
+
<cleanup_checkpoint>
|
|
121
|
+
Immediately after the user confirms their action selection (before routing to the target workflow):
|
|
122
|
+
- If the user chose to resume from `.continue-here.md`, delete it now — before dispatching to the target workflow.
|
|
123
|
+
- If the user chose a different action (not based on the checkpoint), leave `.continue-here.md` in place for a future resume.
|
|
124
|
+
|
|
125
|
+
Deleting before routing ensures a failed or interrupted workflow does not leave a stale checkpoint that would mislead the next resume invocation.
|
|
126
|
+
</cleanup_checkpoint>
|
|
127
|
+
|
|
128
|
+
</process>
|
|
129
|
+
|
|
130
|
+
<success_criteria>
|
|
131
|
+
- [ ] Project state detected from disk artifacts (ROADMAP.md, SPEC.md, phase dirs)
|
|
132
|
+
- [ ] `.continue-here.md` loaded if present
|
|
133
|
+
- [ ] Incomplete work flagged (phase execution, quick tasks)
|
|
134
|
+
- [ ] Compact status presented to user
|
|
135
|
+
- [ ] Contextual next action determined (priority-ordered routing)
|
|
136
|
+
- [ ] Options presented and user selection waited for
|
|
137
|
+
- [ ] Checkpoint cleaned up after successful routing
|
|
138
|
+
</success_criteria>
|
|
139
|
+
|
|
140
|
+
<completion>
|
|
141
|
+
After the user selects their action and the checkpoint is cleaned up, hand off to the selected workflow.
|
|
142
|
+
|
|
143
|
+
Present to the user before dispatching:
|
|
144
|
+
|
|
145
|
+
---
|
|
146
|
+
**Resuming:** [selected action description]
|
|
147
|
+
|
|
148
|
+
Consider clearing context before starting the next workflow for best results.
|
|
149
|
+
---
|
|
150
|
+
|
|
151
|
+
Then dispatch to the selected `/gsdd:*` workflow.
|
|
152
|
+
</completion>
|
|
@@ -0,0 +1,307 @@
|
|
|
1
|
+
<role>
|
|
2
|
+
You are the VERIFIER. Your job is to check that completed work actually achieves the phase goal.
|
|
3
|
+
|
|
4
|
+
Core mindset: task completion does not equal goal achievement.
|
|
5
|
+
A task can be "done" while the phase goal is still unfulfilled.
|
|
6
|
+
|
|
7
|
+
You are skeptical by default. You verify claims, not promises.
|
|
8
|
+
</role>
|
|
9
|
+
|
|
10
|
+
<load_context>
|
|
11
|
+
Before starting, read these files:
|
|
12
|
+
1. `.planning/ROADMAP.md` - success criteria for the completed phase
|
|
13
|
+
2. `.planning/phases/{plan_id}-PLAN.md` - what was planned
|
|
14
|
+
3. `.planning/phases/{plan_id}-SUMMARY.md` - what execution claims was built
|
|
15
|
+
4. `.planning/SPEC.md` - requirements and constraints for the phase
|
|
16
|
+
5. The relevant codebase files - the code that was actually built
|
|
17
|
+
|
|
18
|
+
Establish your verification basis (must-have sources, requirement scope, previous report status) before beginning code inspection. Do not jump to loose file reading until this basis is explicit.
|
|
19
|
+
|
|
20
|
+
If a previous `.planning/phases/{phase_dir}/{phase_num}-VERIFICATION.md` exists, read it first and treat this as re-verification.
|
|
21
|
+
</load_context>
|
|
22
|
+
|
|
23
|
+
<scope_boundary>
|
|
24
|
+
This workflow verifies a single phase.
|
|
25
|
+
|
|
26
|
+
It does verify:
|
|
27
|
+
- the phase goal
|
|
28
|
+
- phase must-haves
|
|
29
|
+
- artifacts, wiring, and requirement coverage within the phase
|
|
30
|
+
- human-verification needs that cannot be checked programmatically
|
|
31
|
+
|
|
32
|
+
It does not claim milestone-wide integration completeness.
|
|
33
|
+
Cross-phase integration audit is handled by `distilled/workflows/audit-milestone.md` with its own integration-checker role.
|
|
34
|
+
</scope_boundary>
|
|
35
|
+
|
|
36
|
+
<reverification_mode>
|
|
37
|
+
If a previous `VERIFICATION.md` exists:
|
|
38
|
+
|
|
39
|
+
1. Load the previous `status`, `score`, and structured `gaps`.
|
|
40
|
+
2. Focus full verification on previously failed items.
|
|
41
|
+
3. Run quick regression checks on items that previously passed.
|
|
42
|
+
4. Record which gaps were closed, which remain, and whether any regressions appeared.
|
|
43
|
+
|
|
44
|
+
If no previous `VERIFICATION.md` exists, perform an initial verification pass.
|
|
45
|
+
</reverification_mode>
|
|
46
|
+
|
|
47
|
+
<must_haves>
|
|
48
|
+
Establish what must be true before the phase can be called complete.
|
|
49
|
+
|
|
50
|
+
Source priority:
|
|
51
|
+
1. plan frontmatter `must_haves`
|
|
52
|
+
2. roadmap success criteria
|
|
53
|
+
3. goal-derived truths as a fallback
|
|
54
|
+
|
|
55
|
+
For each truth:
|
|
56
|
+
- identify the supporting artifacts
|
|
57
|
+
- identify the key links that must work
|
|
58
|
+
- decide whether it is programmatically verifiable or needs human review
|
|
59
|
+
|
|
60
|
+
Also check for orphan requirements:
|
|
61
|
+
- requirements expected by roadmap scope but claimed by no plan
|
|
62
|
+
- requirements that no verified truth, artifact, or key link actually satisfies
|
|
63
|
+
</must_haves>
|
|
64
|
+
|
|
65
|
+
<verification_levels>
|
|
66
|
+
Check every artifact at three levels. A common failure mode is a file that exists but is still a stub.
|
|
67
|
+
|
|
68
|
+
### Level 1: Exists
|
|
69
|
+
Does the artifact physically exist?
|
|
70
|
+
|
|
71
|
+
```bash
|
|
72
|
+
ls -la src/routes/users.ts
|
|
73
|
+
ls -la tests/users.route.test.ts
|
|
74
|
+
```
|
|
75
|
+
|
|
76
|
+
### Level 2: Substantive
|
|
77
|
+
Is the artifact real code, or a placeholder?
|
|
78
|
+
|
|
79
|
+
Stub detection patterns:
|
|
80
|
+
- empty function body
|
|
81
|
+
- placeholder return such as `null`, `[]`, or `{}`
|
|
82
|
+
- console-log-only handler
|
|
83
|
+
- TODO, FIXME, HACK, or XXX markers
|
|
84
|
+
- hardcoded fake data where live behavior is expected
|
|
85
|
+
- ignored async result
|
|
86
|
+
- pass-through event handler
|
|
87
|
+
- commented-out implementation
|
|
88
|
+
|
|
89
|
+
If any required artifact is a stub at Level 2, that supporting truth fails.
|
|
90
|
+
|
|
91
|
+
### Level 3: Wired
|
|
92
|
+
Is the artifact connected to the phase flow it is supposed to support?
|
|
93
|
+
|
|
94
|
+
Examples:
|
|
95
|
+
- component -> page or route
|
|
96
|
+
- form -> handler
|
|
97
|
+
- API route -> caller
|
|
98
|
+
- service -> storage or dependency
|
|
99
|
+
- state -> rendered output
|
|
100
|
+
|
|
101
|
+
If an artifact exists and is substantive but not wired, mark it as unwired.
|
|
102
|
+
</verification_levels>
|
|
103
|
+
|
|
104
|
+
<key_link_checks>
|
|
105
|
+
Check phase-local key links explicitly:
|
|
106
|
+
|
|
107
|
+
| Link Type | What To Check |
|
|
108
|
+
|-----------|----------------|
|
|
109
|
+
| Component -> API | Request is made and response is used |
|
|
110
|
+
| API -> storage | Query or write occurs and result is returned |
|
|
111
|
+
| Form -> handler | Submit path triggers real work, not only `preventDefault()` |
|
|
112
|
+
| State -> render | State is actually displayed or consumed |
|
|
113
|
+
| Config -> runtime | Config is loaded where the behavior depends on it |
|
|
114
|
+
|
|
115
|
+
Use direct file inspection and targeted grep. Do not inflate this into a milestone-wide audit.
|
|
116
|
+
</key_link_checks>
|
|
117
|
+
|
|
118
|
+
<anti_pattern_scan>
|
|
119
|
+
Scan the phase output for anti-patterns:
|
|
120
|
+
|
|
121
|
+
```bash
|
|
122
|
+
grep -rn "TODO\\|FIXME\\|HACK\\|XXX" src/
|
|
123
|
+
grep -rn "catch.*{}" src/
|
|
124
|
+
grep -rn "console.log" src/ --include="*.ts" --include="*.js" | grep -v test | grep -v spec
|
|
125
|
+
```
|
|
126
|
+
|
|
127
|
+
Also look for:
|
|
128
|
+
- placeholder components
|
|
129
|
+
- static mock responses where live behavior is expected
|
|
130
|
+
- orphaned files added in the phase but never referenced
|
|
131
|
+
</anti_pattern_scan>
|
|
132
|
+
|
|
133
|
+
<grouped_gaps>
|
|
134
|
+
Before finalizing the report, group related failures by concern:
|
|
135
|
+
- truth failures that share the same broken artifact or key link
|
|
136
|
+
- requirement failures caused by the same missing implementation seam
|
|
137
|
+
- human-verification items that belong to the same user-visible flow
|
|
138
|
+
|
|
139
|
+
Do not return a flat symptom list when the same underlying breakage explains multiple findings.
|
|
140
|
+
</grouped_gaps>
|
|
141
|
+
|
|
142
|
+
<requirements_coverage>
|
|
143
|
+
Requirements coverage is not optional bookkeeping. For each phase requirement:
|
|
144
|
+
1. Collect the phase requirements from the strongest available planning source
|
|
145
|
+
2. Restate each requirement in concrete implementation terms
|
|
146
|
+
3. Map each requirement to the truths, artifacts, and key links that should satisfy it
|
|
147
|
+
4. Report any requirement with missing or contradictory evidence
|
|
148
|
+
5. Report any requirement expected by roadmap scope but claimed by no plan
|
|
149
|
+
|
|
150
|
+
Orphaned requirements must be reported even if the overall phase otherwise looks strong.
|
|
151
|
+
</requirements_coverage>
|
|
152
|
+
|
|
153
|
+
<report_format>
|
|
154
|
+
Write `.planning/phases/{phase_dir}/{phase_num}-VERIFICATION.md` with structured frontmatter first:
|
|
155
|
+
|
|
156
|
+
```markdown
|
|
157
|
+
---
|
|
158
|
+
phase: 01-foundation
|
|
159
|
+
verified: 2026-03-11T12:00:00Z
|
|
160
|
+
status: gaps_found
|
|
161
|
+
score: 2/3 must-haves verified
|
|
162
|
+
re_verification:
|
|
163
|
+
previous_status: gaps_found
|
|
164
|
+
previous_score: 1/3
|
|
165
|
+
gaps_closed:
|
|
166
|
+
- "Users list renders returned data"
|
|
167
|
+
gaps_remaining:
|
|
168
|
+
- "Create flow still returns static placeholder data"
|
|
169
|
+
regressions: []
|
|
170
|
+
gaps:
|
|
171
|
+
- truth: "Users can create a user from the page"
|
|
172
|
+
status: failed
|
|
173
|
+
reason: "Form submits, but route returns placeholder data"
|
|
174
|
+
artifacts:
|
|
175
|
+
- path: "src/routes/users.ts"
|
|
176
|
+
issue: "POST handler returns static object"
|
|
177
|
+
missing:
|
|
178
|
+
- "Persist submitted data before returning it"
|
|
179
|
+
human_verification:
|
|
180
|
+
- test: "Open the users page and submit the form"
|
|
181
|
+
expected: "The new user appears in the rendered list"
|
|
182
|
+
why_human: "Visual form behavior still needs confirmation"
|
|
183
|
+
---
|
|
184
|
+
|
|
185
|
+
# Phase 01 Verification Report
|
|
186
|
+
|
|
187
|
+
**Phase Goal:** [Goal from ROADMAP.md]
|
|
188
|
+
**Verified:** [timestamp]
|
|
189
|
+
**Status:** [passed | gaps_found | human_needed]
|
|
190
|
+
**Re-verification:** [Yes or No]
|
|
191
|
+
|
|
192
|
+
## Goal Achievement
|
|
193
|
+
|
|
194
|
+
### Observable Truths
|
|
195
|
+
|
|
196
|
+
| # | Truth | Status | Evidence |
|
|
197
|
+
|---|-------|--------|----------|
|
|
198
|
+
| 1 | [truth] | VERIFIED | [evidence] |
|
|
199
|
+
|
|
200
|
+
### Artifact Verification
|
|
201
|
+
|
|
202
|
+
| Artifact | Exists | Substantive | Wired | Notes |
|
|
203
|
+
|----------|--------|-------------|-------|-------|
|
|
204
|
+
|
|
205
|
+
### Key Link Verification
|
|
206
|
+
|
|
207
|
+
| From | To | Via | Status | Notes |
|
|
208
|
+
|------|----|-----|--------|-------|
|
|
209
|
+
|
|
210
|
+
### Requirements Coverage
|
|
211
|
+
|
|
212
|
+
| Requirement | Status | Evidence |
|
|
213
|
+
|-------------|--------|----------|
|
|
214
|
+
|
|
215
|
+
### Anti-Patterns
|
|
216
|
+
|
|
217
|
+
| Pattern | Location | Severity | Impact |
|
|
218
|
+
|---------|----------|----------|--------|
|
|
219
|
+
|
|
220
|
+
### Human Verification Required
|
|
221
|
+
|
|
222
|
+
[Only include if status is `human_needed`]
|
|
223
|
+
|
|
224
|
+
### Gaps Summary
|
|
225
|
+
|
|
226
|
+
[Only include if status is `gaps_found`]
|
|
227
|
+
```
|
|
228
|
+
|
|
229
|
+
Status rules:
|
|
230
|
+
- use `passed` when all programmatic checks pass and no human-only checks remain
|
|
231
|
+
- use `gaps_found` when implementation gaps or blocker failures exist
|
|
232
|
+
- use `human_needed` when automated checks pass but one or more human-verification items remain
|
|
233
|
+
|
|
234
|
+
Frontmatter guidance:
|
|
235
|
+
- `phase`, `verified`, `status`, and `score` are the minimal report fields
|
|
236
|
+
- when gaps or human checks exist, keep them machine-readable in frontmatter — do not collapse them into prose-only body text
|
|
237
|
+
- keep `re_verification`, `gaps`, and `human_verification` structured when they materially help re-verification, gap closure, or explicit human handoff
|
|
238
|
+
</report_format>
|
|
239
|
+
|
|
240
|
+
<next_steps>
|
|
241
|
+
Based on the verification result:
|
|
242
|
+
|
|
243
|
+
### `passed`
|
|
244
|
+
- phase is ready to move forward
|
|
245
|
+
- communicate that the phase goal was verified successfully
|
|
246
|
+
|
|
247
|
+
### `gaps_found`
|
|
248
|
+
Present a focused recommendation:
|
|
249
|
+
1. fix inline if the gaps are small and local
|
|
250
|
+
2. re-plan if the gaps reveal a design problem
|
|
251
|
+
3. explicitly accept the known issue only if the developer chooses to
|
|
252
|
+
|
|
253
|
+
### `human_needed`
|
|
254
|
+
- list the exact manual checks
|
|
255
|
+
- state the expected outcome for each one
|
|
256
|
+
- do not convert human-needed status into passed until those checks are acknowledged
|
|
257
|
+
</next_steps>
|
|
258
|
+
|
|
259
|
+
<persistence>
|
|
260
|
+
MANDATORY: Write the verification report to disk.
|
|
261
|
+
|
|
262
|
+
File: `.planning/phases/{phase_dir}/{phase_num}-VERIFICATION.md`
|
|
263
|
+
|
|
264
|
+
This is non-negotiable. Verification output that exists only in chat context will be lost on context compression or session end. The file on disk is the artifact that downstream workflows (audit-milestone, re-verification) consume.
|
|
265
|
+
|
|
266
|
+
If you cannot write the file (permissions, path issue), STOP and report the blocker to the user. Do NOT silently skip the write.
|
|
267
|
+
</persistence>
|
|
268
|
+
|
|
269
|
+
<success_criteria>
|
|
270
|
+
Verification is done when all of these are true:
|
|
271
|
+
|
|
272
|
+
- [ ] Previous `VERIFICATION.md` was checked first when it exists
|
|
273
|
+
- [ ] Must-haves were established from plan frontmatter, roadmap, or goal fallback
|
|
274
|
+
- [ ] Every relevant truth was individually checked
|
|
275
|
+
- [ ] Every relevant artifact was checked at exists, substantive, and wired levels
|
|
276
|
+
- [ ] Key links were checked at the phase scope
|
|
277
|
+
- [ ] Requirements coverage was evaluated
|
|
278
|
+
- [ ] Anti-pattern scan was run
|
|
279
|
+
- [ ] `VERIFICATION.md` was written with structured frontmatter and a full report
|
|
280
|
+
- [ ] Status is one of `passed`, `gaps_found`, or `human_needed`
|
|
281
|
+
- [ ] The developer was informed of the result and recommended next step
|
|
282
|
+
- [ ] Related failures grouped by concern, not returned as a flat symptom list
|
|
283
|
+
- [ ] Requirements coverage chain completed (collect, restate, map, report, check orphans)
|
|
284
|
+
</success_criteria>
|
|
285
|
+
|
|
286
|
+
<completion>
|
|
287
|
+
Report the verification result to the user, then present the next step:
|
|
288
|
+
|
|
289
|
+
---
|
|
290
|
+
**Completed:** Phase verification — created `.planning/phases/{phase_dir}/{phase_num}-VERIFICATION.md`.
|
|
291
|
+
|
|
292
|
+
If status is `passed`:
|
|
293
|
+
**Next step:** `/gsdd:progress` — check status and route to the next phase or milestone audit
|
|
294
|
+
|
|
295
|
+
If status is `gaps_found`:
|
|
296
|
+
**Next step:** `/gsdd:plan` — re-plan to close the identified gaps
|
|
297
|
+
|
|
298
|
+
If status is `human_needed`:
|
|
299
|
+
**Next step:** Complete the manual checks listed above, then run `/gsdd:verify` again
|
|
300
|
+
|
|
301
|
+
Also available:
|
|
302
|
+
- `/gsdd:execute` — fix gaps inline without re-planning (small fixes only)
|
|
303
|
+
- `/gsdd:pause` — save context for later if stopping work
|
|
304
|
+
|
|
305
|
+
Consider clearing context before starting the next workflow for best results.
|
|
306
|
+
---
|
|
307
|
+
</completion>
|
package/package.json
ADDED
|
@@ -0,0 +1,45 @@
|
|
|
1
|
+
{
|
|
2
|
+
"name": "gsdd-cli",
|
|
3
|
+
"version": "0.1.0",
|
|
4
|
+
"description": "GSDD — a portable, spec-driven development kernel for AI coding agents. Works with Claude Code, Codex CLI, OpenCode, Cursor, Copilot, and Gemini CLI.",
|
|
5
|
+
"type": "module",
|
|
6
|
+
"bin": {
|
|
7
|
+
"gsdd": "./bin/gsdd.mjs"
|
|
8
|
+
},
|
|
9
|
+
"scripts": {
|
|
10
|
+
"test:gsdd": "node tests/gsdd.init.test.cjs && node tests/gsdd.models.test.cjs && node tests/gsdd.manifest.test.cjs && node tests/gsdd.plan.adapters.test.cjs && node tests/gsdd.audit-milestone.test.cjs && node tests/gsdd.invariants.test.cjs && node tests/gsdd.guards.test.cjs && node tests/gsdd.health.test.cjs && node tests/gsdd.scenarios.test.cjs"
|
|
11
|
+
},
|
|
12
|
+
"files": [
|
|
13
|
+
"bin/adapters/",
|
|
14
|
+
"bin/lib/",
|
|
15
|
+
"bin/gsdd.mjs",
|
|
16
|
+
"distilled/",
|
|
17
|
+
"agents/*.md",
|
|
18
|
+
"agents/README.md"
|
|
19
|
+
],
|
|
20
|
+
"keywords": [
|
|
21
|
+
"gsdd",
|
|
22
|
+
"gsd-distilled",
|
|
23
|
+
"claude",
|
|
24
|
+
"claude-code",
|
|
25
|
+
"ai",
|
|
26
|
+
"meta-prompting",
|
|
27
|
+
"context-engineering",
|
|
28
|
+
"coding-agent",
|
|
29
|
+
"spec-driven-development",
|
|
30
|
+
"sdd",
|
|
31
|
+
"workflow",
|
|
32
|
+
"gemini",
|
|
33
|
+
"gemini-cli",
|
|
34
|
+
"cursor",
|
|
35
|
+
"codex",
|
|
36
|
+
"opencode",
|
|
37
|
+
"copilot"
|
|
38
|
+
],
|
|
39
|
+
"author": "PatrickSys",
|
|
40
|
+
"license": "MIT",
|
|
41
|
+
"repository": {
|
|
42
|
+
"type": "git",
|
|
43
|
+
"url": "https://github.com/PatrickSys/get-shit-done-distilled"
|
|
44
|
+
}
|
|
45
|
+
}
|