catalyst-os 2.0.2 → 2.0.3
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.
|
@@ -0,0 +1,31 @@
|
|
|
1
|
+
# /challenge-spec
|
|
2
|
+
|
|
3
|
+
Stress-test a shaped spec by interviewing the user across every branch of the design tree.
|
|
4
|
+
|
|
5
|
+
> **Lifecycle position:** `/catalyze-spec` → **`/challenge-spec`** *(optional)* → `/forge-spec` → `/audit-spec` → `/seal-spec`
|
|
6
|
+
>
|
|
7
|
+
> **Optional gate.** Use when a spec has real design surface area and you want every branch resolved before tests are written. Skip it for trivial specs.
|
|
8
|
+
|
|
9
|
+
## Usage
|
|
10
|
+
|
|
11
|
+
```
|
|
12
|
+
/challenge-spec @2026-05-13-stripe-integration
|
|
13
|
+
```
|
|
14
|
+
|
|
15
|
+
## Pre-computed Context
|
|
16
|
+
|
|
17
|
+
```bash
|
|
18
|
+
# Spec state for challenge
|
|
19
|
+
echo "=== SPEC FILES ===" && ls .catalyst/specs/*$ARGUMENTS*/ 2>/dev/null || echo "No spec found for: $ARGUMENTS"
|
|
20
|
+
echo "=== SPEC STATUS ===" && head -20 .catalyst/specs/*$ARGUMENTS*/spec.md 2>/dev/null || echo "No spec.md"
|
|
21
|
+
echo "=== OPEN QUESTIONS ===" && grep -A 20 "## Open Questions" .catalyst/specs/*$ARGUMENTS*/spec.md 2>/dev/null || echo "No Open Questions section"
|
|
22
|
+
echo "=== TASKS EXIST? ===" && ls .catalyst/specs/*$ARGUMENTS*/tasks.md 2>/dev/null && echo "WARNING: tasks.md exists — use /update-spec instead" || echo "No tasks.md (expected)"
|
|
23
|
+
```
|
|
24
|
+
|
|
25
|
+
---
|
|
26
|
+
|
|
27
|
+
**Invoke skill:** `spec-challenge`
|
|
28
|
+
|
|
29
|
+
**Orchestrator:** Main thread (direct interview). Spawn Seer if a question becomes a codebase research task.
|
|
30
|
+
|
|
31
|
+
**Process skills used:** `brainstorming` (form, not 9-question cap), `agent-delegation`
|
|
@@ -0,0 +1,139 @@
|
|
|
1
|
+
# Spec Challenge
|
|
2
|
+
|
|
3
|
+
> **When to invoke:** When stress-testing a freshly shaped spec — interviewing the user across every branch of the design tree until shared understanding is reached.
|
|
4
|
+
> **Invoked by:** `/challenge-spec` command.
|
|
5
|
+
> **Position:** Optional intermediate step between `/catalyze-spec` and `/forge-spec`.
|
|
6
|
+
|
|
7
|
+
## Purpose
|
|
8
|
+
|
|
9
|
+
Shaping produces a spec. Challenge proves the spec is forge-ready. The orchestrator interviews the user one question at a time about every unresolved branch — assumptions, edge cases, integration points, scope ambiguity — patching `spec.md` and logging the trail to `handoff.md` as each answer lands.
|
|
10
|
+
|
|
11
|
+
This is not a sign-off step. It is an interrogation step. The bar is "every branch of the design tree resolved", not "user said yes".
|
|
12
|
+
|
|
13
|
+
## Skills Referenced
|
|
14
|
+
|
|
15
|
+
- `brainstorming` — same form (one question at a time, recommend an answer, acknowledge before moving on). The 9-question cap **does not apply** here; challenge is exhaustive by design.
|
|
16
|
+
- `agent-delegation` — if a question becomes a research task, spawn Seer/Scout rather than guessing.
|
|
17
|
+
|
|
18
|
+
## When NOT to Use
|
|
19
|
+
|
|
20
|
+
- Spec is trivial (rename, copy change, single-file fix) — go straight to `/forge-spec`.
|
|
21
|
+
- Spec is still in DRAFT and missing whole sections — finish `/catalyze-spec` first.
|
|
22
|
+
- Implementation has already started (`tasks.md` exists with completed tasks) — use `/update-spec` instead.
|
|
23
|
+
- Spec is COMPLETE — challenge is meaningless after the fact.
|
|
24
|
+
|
|
25
|
+
## Prerequisites
|
|
26
|
+
|
|
27
|
+
- Target spec folder exists at `.catalyst/specs/{slug}/`.
|
|
28
|
+
- `spec.md` exists with at minimum: Overview, Requirements, Acceptance Criteria, Technical Approach.
|
|
29
|
+
- `handoff.md` exists (create if missing — Catalyst should have left one).
|
|
30
|
+
|
|
31
|
+
If any prerequisite is missing, STOP and tell the user to run or finish `/catalyze-spec` first.
|
|
32
|
+
|
|
33
|
+
## Workflow
|
|
34
|
+
|
|
35
|
+
### Phase 1: Inventory the Decision Tree
|
|
36
|
+
|
|
37
|
+
Read in order: `spec.md`, `research.md`, `handoff.md`, plus any assets.
|
|
38
|
+
|
|
39
|
+
Build a working list (kept in your head or a scratch section in `handoff.md`) of every branch that needs resolution. Look for:
|
|
40
|
+
|
|
41
|
+
| Source | What to extract |
|
|
42
|
+
|--------|-----------------|
|
|
43
|
+
| `spec.md` → Open Questions | Each one is an explicit branch. |
|
|
44
|
+
| `spec.md` → Requirements | Vague verbs ("handle", "support", "manage") hide branches. |
|
|
45
|
+
| `spec.md` → Acceptance Criteria | Missing thresholds, missing failure modes. |
|
|
46
|
+
| `spec.md` → Out of Scope | Anything that *could* be in scope but isn't justified. |
|
|
47
|
+
| `spec.md` → Technical Approach | Library/framework choices without a stated reason. |
|
|
48
|
+
| `research.md` | Findings the spec didn't actually use. |
|
|
49
|
+
| `handoff.md` | Prior decisions that may now be in tension. |
|
|
50
|
+
|
|
51
|
+
Surface anything that, if guessed wrong, would cause `/forge-spec` to backtrack.
|
|
52
|
+
|
|
53
|
+
### Phase 2: Codebase First, User Second
|
|
54
|
+
|
|
55
|
+
> **Rule from grill-me:** "If a question can be answered by exploring the codebase, explore the codebase instead."
|
|
56
|
+
|
|
57
|
+
Before asking the user anything, walk the list and ask: can I answer this myself? Use `Read`, `grep`, or spawn **Seer** for deeper analysis. Only the residue — genuine product/scope/intent decisions — goes to the user.
|
|
58
|
+
|
|
59
|
+
### Phase 3: The Interview
|
|
60
|
+
|
|
61
|
+
For each remaining branch, ask **one question at a time** following these rules:
|
|
62
|
+
|
|
63
|
+
1. **Lead with your recommendation.** "I'd recommend X because Y. Agree, or push back?"
|
|
64
|
+
2. **Multiple choice when options exist.** Numbered. Each option has a one-line tradeoff.
|
|
65
|
+
3. **Acknowledge the answer.** One sentence. Connect it to the next question.
|
|
66
|
+
4. **Walk depth-first.** If an answer opens a new branch, resolve that branch before returning to the trunk.
|
|
67
|
+
5. **Resolve dependencies in order.** Don't ask about caching strategy before storage backend is chosen.
|
|
68
|
+
6. **No artificial cap.** Keep going until every branch is resolved. Stop only when:
|
|
69
|
+
- The user says "good enough" / "ship it" / "stop".
|
|
70
|
+
- You can no longer surface a branch that would cause `/forge-spec` to backtrack.
|
|
71
|
+
|
|
72
|
+
### Phase 4: Patch As You Go
|
|
73
|
+
|
|
74
|
+
After **each** resolved question, update the spec immediately. Do not batch.
|
|
75
|
+
|
|
76
|
+
**`spec.md` patches** — find the right home for the answer:
|
|
77
|
+
|
|
78
|
+
| Answer type | Goes in |
|
|
79
|
+
|-------------|---------|
|
|
80
|
+
| Removes an unknown | Delete from Open Questions |
|
|
81
|
+
| Adds a verifiable behavior | Append to Acceptance Criteria |
|
|
82
|
+
| Tightens scope | Add to Requirements or Out of Scope |
|
|
83
|
+
| Picks a library/pattern | Update Technical Approach |
|
|
84
|
+
| Reframes the problem | Update Overview / User Stories |
|
|
85
|
+
|
|
86
|
+
**`handoff.md` log** — append every Q&A under a `## Challenge Log` section:
|
|
87
|
+
|
|
88
|
+
```markdown
|
|
89
|
+
## Challenge Log
|
|
90
|
+
|
|
91
|
+
### {YYYY-MM-DD HH:MM} — {short topic}
|
|
92
|
+
**Q:** {the question, including the recommendation you led with}
|
|
93
|
+
**A:** {user's answer, verbatim or close to it}
|
|
94
|
+
**Spec impact:** {which section of spec.md was patched and how}
|
|
95
|
+
```
|
|
96
|
+
|
|
97
|
+
The log is the audit trail. Future-you (or anyone running `/primer-spec`) can read it and understand *why* the spec looks the way it does.
|
|
98
|
+
|
|
99
|
+
### Phase 5: Close Out
|
|
100
|
+
|
|
101
|
+
When the interview ends:
|
|
102
|
+
|
|
103
|
+
1. Re-read `spec.md` end-to-end. Check that patches are coherent and don't contradict each other.
|
|
104
|
+
2. Confirm Open Questions is empty (or every remaining item is explicitly deferred with a note).
|
|
105
|
+
3. Append a closing entry to `handoff.md`:
|
|
106
|
+
```markdown
|
|
107
|
+
### Challenge complete — {YYYY-MM-DD HH:MM}
|
|
108
|
+
Branches resolved: {N}
|
|
109
|
+
Spec sections updated: {list}
|
|
110
|
+
Deferred (not blocking forge): {list or "none"}
|
|
111
|
+
```
|
|
112
|
+
4. Leave `spec.md` Status as `DRAFT` — challenge does not mark the spec ready for production. `/forge-spec` is still next.
|
|
113
|
+
|
|
114
|
+
## Output
|
|
115
|
+
|
|
116
|
+
```
|
|
117
|
+
Spec challenged.
|
|
118
|
+
|
|
119
|
+
Branches resolved: {N}
|
|
120
|
+
spec.md sections updated: {list}
|
|
121
|
+
handoff.md: +Challenge Log ({N} entries)
|
|
122
|
+
Deferred: {list or "none"}
|
|
123
|
+
|
|
124
|
+
Next steps:
|
|
125
|
+
- /forge-spec @{slug} to start TDD build
|
|
126
|
+
- /update-spec @{slug} "..." if you want further structural changes first
|
|
127
|
+
```
|
|
128
|
+
|
|
129
|
+
## Anti-Patterns
|
|
130
|
+
|
|
131
|
+
| Anti-Pattern | Fix |
|
|
132
|
+
|--------------|-----|
|
|
133
|
+
| Asking the user something `grep` would answer | Phase 2 first — codebase before user. |
|
|
134
|
+
| Batching 4 questions because "they're related" | One at a time. Always. Related questions go in sequence, not in a list. |
|
|
135
|
+
| Asking without a recommendation | Lead with your pick + why. The user's job is to push back, not to design from scratch. |
|
|
136
|
+
| Logging answers in batch at the end | Patch `spec.md` and append to `handoff.md` after each answer — context is freshest then. |
|
|
137
|
+
| Stopping at 9 questions because brainstorming says so | Brainstorming caps apply to scoping. Challenge is exhaustive — keep going until branches are resolved. |
|
|
138
|
+
| Treating user's "looks fine" as resolution | If you have a branch in mind, ask it. "Looks fine" without a specific answer is not a resolution. |
|
|
139
|
+
| Marking spec READY / APPROVED at the end | Status stays DRAFT. `/forge-spec` is next. Challenge is not approval. |
|
|
@@ -174,7 +174,8 @@ REMINDER: /forge-spec follows strict TDD
|
|
|
174
174
|
4. Tests must PASS (green phase)
|
|
175
175
|
|
|
176
176
|
Next steps:
|
|
177
|
+
- /challenge-spec @YYYY-MM-DD-{slug} (optional) to interrogate every branch before tests are written
|
|
177
178
|
- /forge-spec @YYYY-MM-DD-{slug} to start TDD build
|
|
178
179
|
```
|
|
179
180
|
|
|
180
|
-
**IMPORTANT: Do NOT suggest `/seal-spec` after spec shaping.** `/seal-spec` is only for committing a fully built and validated implementation — it is the FINAL step, not a plan-approval step. The correct flow is: `/catalyze-spec` → `/forge-spec` → `/audit-spec` → `/seal-spec`.
|
|
181
|
+
**IMPORTANT: Do NOT suggest `/seal-spec` after spec shaping.** `/seal-spec` is only for committing a fully built and validated implementation — it is the FINAL step, not a plan-approval step. The correct flow is: `/catalyze-spec` → *(optional)* `/challenge-spec` → `/forge-spec` → `/audit-spec` → `/seal-spec`.
|
|
@@ -42,6 +42,7 @@ Skills tell you HOW. User instructions tell you WHAT.
|
|
|
42
42
|
| Skill | Path | Load when... |
|
|
43
43
|
|-------|------|-------------|
|
|
44
44
|
| **spec-shaping** | `.claude/skills/spec-shaping/SKILL.md` | `/catalyze-spec` — shaping a new specification |
|
|
45
|
+
| **spec-challenge** | `.claude/skills/spec-challenge/SKILL.md` | `/challenge-spec` — interrogating a shaped spec branch by branch (optional) |
|
|
45
46
|
| **build-orchestration** | `.claude/skills/build-orchestration/SKILL.md` | `/forge-spec` — implementing a specification |
|
|
46
47
|
| **spec-validation** | `.claude/skills/spec-validation/SKILL.md` | `/audit-spec` — quality checks on implementation |
|
|
47
48
|
| **spec-approval** | `.claude/skills/spec-approval/SKILL.md` | `/seal-spec` — final commit and archival |
|
package/README.md
CHANGED
|
@@ -10,6 +10,7 @@
|
|
|
10
10
|
npx catalyst-os # Install to your project
|
|
11
11
|
/catalyze-project # Initialize project foundation
|
|
12
12
|
/catalyze-spec "description" # Shape a feature specification
|
|
13
|
+
/challenge-spec @spec-name # (optional) Interrogate the spec branch by branch
|
|
13
14
|
/forge-spec @spec-name # Implement with TDD
|
|
14
15
|
/audit-spec @spec-name # Run quality checks
|
|
15
16
|
/seal-spec @spec-name # Accept and archive
|
|
@@ -44,6 +45,7 @@ Then run `/catalyze-project` to initialize — this detects your workspace type,
|
|
|
44
45
|
│ ├── receiving-code-review/
|
|
45
46
|
│ ├── workspace-detection/
|
|
46
47
|
│ ├── spec-shaping/
|
|
48
|
+
│ ├── spec-challenge/
|
|
47
49
|
│ ├── build-orchestration/
|
|
48
50
|
│ ├── spec-validation/
|
|
49
51
|
│ ├── spec-approval/
|
|
@@ -102,6 +104,7 @@ Without this, skills are optional documentation. With it, they're mandatory proc
|
|
|
102
104
|
| Skill | Command | Purpose |
|
|
103
105
|
|-------|---------|---------|
|
|
104
106
|
| `spec-shaping` | `/catalyze-spec` | Shape feature requests into specifications |
|
|
107
|
+
| `spec-challenge` | `/challenge-spec` | Interrogate a shaped spec branch by branch (optional) |
|
|
105
108
|
| `build-orchestration` | `/forge-spec` | DAG-based TDD implementation |
|
|
106
109
|
| `spec-validation` | `/audit-spec` | Quality checks via Guardian agents |
|
|
107
110
|
| `spec-approval` | `/seal-spec` | Final verification and archival |
|
|
@@ -185,6 +188,10 @@ Guardians (Quality)
|
|
|
185
188
|
└──────────────┘ └──────────────┘ └──────────────┘ └──────────────┘
|
|
186
189
|
Context full? New conversation?
|
|
187
190
|
Run /primer-spec @slug to restore awareness before continuing.
|
|
191
|
+
|
|
192
|
+
Optional gate between CATALYZE and FORGE:
|
|
193
|
+
/challenge-spec @slug — interrogate every branch of the design tree
|
|
194
|
+
before tests are written. Patches spec.md, logs to handoff.md.
|
|
188
195
|
```
|
|
189
196
|
|
|
190
197
|
---
|
|
@@ -195,6 +202,7 @@ Guardians (Quality)
|
|
|
195
202
|
|---------|-------------|--------|
|
|
196
203
|
| `/catalyze-project` | Start new project | mission.md, roadmap.md, tech-stack.md |
|
|
197
204
|
| `/catalyze-spec "feature"` | New feature request | spec.md, research.md |
|
|
205
|
+
| `/challenge-spec @slug` | Stress-test the spec before forging (optional) | spec.md (patched), handoff.md (Challenge Log) |
|
|
198
206
|
| `/forge-spec @slug` | Implement feature | tasks.md (updated) |
|
|
199
207
|
| `/primer-spec @slug` | Restore context (new conversation) | Brief status summary |
|
|
200
208
|
| `/audit-spec @slug` | Quality checks | validation.md, handoff.md |
|