specflow-cc 1.6.2 → 1.7.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/CHANGELOG.md +27 -0
- package/README.md +20 -1
- package/agents/impl-reviewer.md +18 -0
- package/agents/spec-auditor.md +62 -1
- package/commands/sf/audit.md +132 -1
- package/commands/sf/help.md +15 -2
- package/commands/sf/revise.md +234 -4
- package/commands/sf/status.md +1 -0
- package/package.json +1 -1
- package/templates/spec.md +1 -1
- package/templates/state.md +2 -2
package/CHANGELOG.md
CHANGED
|
@@ -5,6 +5,33 @@ All notable changes to SpecFlow will be documented in this file.
|
|
|
5
5
|
The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
|
|
6
6
|
and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
|
|
7
7
|
|
|
8
|
+
## [1.7.0] - 2026-01-28
|
|
9
|
+
|
|
10
|
+
### Added
|
|
11
|
+
|
|
12
|
+
- **AI pre-analysis of external feedback** — `/sf:revise` now analyzes imported external audit items before showing review options
|
|
13
|
+
- Provides recommendations: ✓ Apply / ? Discuss / ✗ Skip with reasoning
|
|
14
|
+
- New "Apply recommended" option to apply only recommended items
|
|
15
|
+
- `--no-analysis` flag to skip pre-analysis and go directly to manual review
|
|
16
|
+
|
|
17
|
+
### Changed
|
|
18
|
+
|
|
19
|
+
- `/sf:audit --import` workflow now flows through AI analysis step by default
|
|
20
|
+
- Updated help documentation with new flag
|
|
21
|
+
|
|
22
|
+
---
|
|
23
|
+
|
|
24
|
+
## [1.6.3] - 2026-01-28
|
|
25
|
+
|
|
26
|
+
### Added
|
|
27
|
+
|
|
28
|
+
- `/sf:audit --import "feedback"` — Import external feedback (code reviews, security audits) for critical evaluation
|
|
29
|
+
- `/sf:revise` detects external audits and offers per-item evaluation (Apply/Skip/Discuss/Defer)
|
|
30
|
+
- New `external_review` status in state machine
|
|
31
|
+
- Strategic sanity check in auditor agents
|
|
32
|
+
|
|
33
|
+
---
|
|
34
|
+
|
|
8
35
|
## [1.6.0] - 2026-01-25
|
|
9
36
|
|
|
10
37
|
### Added
|
package/README.md
CHANGED
|
@@ -305,7 +305,7 @@ Six months later, you can read the spec and understand not just *what* was built
|
|
|
305
305
|
|---------|-------------|
|
|
306
306
|
| `/sf:init` | Initialize project |
|
|
307
307
|
| `/sf:new "task"` | Create specification |
|
|
308
|
-
| `/sf:audit` | Audit spec
|
|
308
|
+
| `/sf:audit` | Audit spec or import external feedback |
|
|
309
309
|
| `/sf:revise` | Revise based on audit feedback |
|
|
310
310
|
| `/sf:run` | Implement specification |
|
|
311
311
|
| `/sf:review` | Review implementation (fresh context) |
|
|
@@ -319,6 +319,13 @@ Six months later, you can read the spec and understand not just *what* was built
|
|
|
319
319
|
/sf:quick "fix button color" # Skip full workflow for trivial tasks
|
|
320
320
|
```
|
|
321
321
|
|
|
322
|
+
**Audit options:**
|
|
323
|
+
|
|
324
|
+
```bash
|
|
325
|
+
/sf:audit # Audit active spec (fresh context)
|
|
326
|
+
/sf:audit --import "[Critical] ..." # Import external feedback for review
|
|
327
|
+
```
|
|
328
|
+
|
|
322
329
|
**Revise options:**
|
|
323
330
|
|
|
324
331
|
```bash
|
|
@@ -328,6 +335,18 @@ Six months later, you can read the spec and understand not just *what* was built
|
|
|
328
335
|
/sf:revise "custom..." # Custom instructions
|
|
329
336
|
```
|
|
330
337
|
|
|
338
|
+
**External feedback workflow:**
|
|
339
|
+
|
|
340
|
+
```bash
|
|
341
|
+
/sf:audit --import "[Critical] SQL injection; [Major] Add rate limiting"
|
|
342
|
+
/sf:revise # AI analyzes feedback, then shows review options
|
|
343
|
+
/sf:revise --no-analysis # Skip AI analysis, go directly to manual review
|
|
344
|
+
```
|
|
345
|
+
|
|
346
|
+
When reviewing external feedback, Claude first analyzes each item against the
|
|
347
|
+
specification and provides recommendations (✓ Apply / ? Discuss / ✗ Skip)
|
|
348
|
+
before showing interactive options.
|
|
349
|
+
|
|
331
350
|
### Research & Clarification
|
|
332
351
|
|
|
333
352
|
| Command | Description |
|
package/agents/impl-reviewer.md
CHANGED
|
@@ -148,6 +148,23 @@ For each created/modified file:
|
|
|
148
148
|
- [ ] Logic flow is easy to follow
|
|
149
149
|
- [ ] Future maintainers can understand without extensive context
|
|
150
150
|
|
|
151
|
+
### 4.8 Implementation Reality Check (light)
|
|
152
|
+
|
|
153
|
+
During code review, watch for signals that the specification itself may have been misdirected:
|
|
154
|
+
|
|
155
|
+
**Trigger conditions:**
|
|
156
|
+
- Implementation is significantly simpler/more complex than spec anticipated
|
|
157
|
+
- Code solves a different problem than what spec described
|
|
158
|
+
- Obvious better approach emerged during implementation but wasn't taken
|
|
159
|
+
- Implementation contradicts PROJECT.md goals or patterns
|
|
160
|
+
|
|
161
|
+
**If triggered:**
|
|
162
|
+
- Do NOT block the review for this
|
|
163
|
+
- Add **WARNING** (not Critical): "Implementation concern: {description}. Consider `/sf:discuss` before `/sf:done`"
|
|
164
|
+
- Continue with normal review process
|
|
165
|
+
|
|
166
|
+
**Note:** This is a safety net, not a primary check. Strategic issues should be caught earlier by `spec-auditor`.
|
|
167
|
+
|
|
151
168
|
## Step 5: Categorize Findings
|
|
152
169
|
|
|
153
170
|
Organize into:
|
|
@@ -299,6 +316,7 @@ Options:
|
|
|
299
316
|
- [ ] Architecture alignment verified
|
|
300
317
|
- [ ] No unnecessary duplication
|
|
301
318
|
- [ ] Cognitive load acceptable
|
|
319
|
+
- [ ] Implementation reality check performed (strategic red flags)
|
|
302
320
|
- [ ] Findings categorized
|
|
303
321
|
- [ ] Review recorded in spec
|
|
304
322
|
- [ ] STATE.md updated
|
package/agents/spec-auditor.md
CHANGED
|
@@ -48,6 +48,7 @@ You are intentionally given NO context about how the spec was created. This ensu
|
|
|
48
48
|
6. **Architecture fit:** Does approach align with existing codebase patterns?
|
|
49
49
|
7. **Non-duplication:** Does this avoid reinventing existing solutions?
|
|
50
50
|
8. **Cognitive load:** Will this be easy for developers to understand and maintain?
|
|
51
|
+
9. **Strategic fit:** Does this solve the RIGHT problem for the project's goals?
|
|
51
52
|
|
|
52
53
|
## Context Quality Curve
|
|
53
54
|
|
|
@@ -300,6 +301,64 @@ Set NEEDS_DECOMPOSITION if ANY of:
|
|
|
300
301
|
- Missing Goal Analysis on medium/large spec → Warning
|
|
301
302
|
- Partial Goal Analysis → Warning per missing subsection
|
|
302
303
|
|
|
304
|
+
## Step 3.8: Strategic Sanity Check
|
|
305
|
+
|
|
306
|
+
Evaluate whether the specification addresses the RIGHT problem, not just whether it's well-formed.
|
|
307
|
+
|
|
308
|
+
### 3.8.1 Extract Assumptions
|
|
309
|
+
|
|
310
|
+
Identify all implicit and explicit assumptions in the specification:
|
|
311
|
+
|
|
312
|
+
1. **Problem assumptions:** What does the spec assume about the problem being solved?
|
|
313
|
+
2. **Solution assumptions:** What does the spec assume about the chosen approach?
|
|
314
|
+
3. **Context assumptions:** What does the spec assume about the environment/constraints?
|
|
315
|
+
|
|
316
|
+
Document each assumption:
|
|
317
|
+
```
|
|
318
|
+
| # | Assumption | If wrong, impact |
|
|
319
|
+
|---|------------|------------------|
|
|
320
|
+
| A1 | {assumption} | {what breaks} |
|
|
321
|
+
| A2 | {assumption} | {what breaks} |
|
|
322
|
+
```
|
|
323
|
+
|
|
324
|
+
### 3.8.2 Project Alignment Check
|
|
325
|
+
|
|
326
|
+
Compare against PROJECT.md:
|
|
327
|
+
|
|
328
|
+
- [ ] Task aligns with stated project goals
|
|
329
|
+
- [ ] Approach fits project's architectural direction
|
|
330
|
+
- [ ] Effort is proportional to expected value
|
|
331
|
+
- [ ] No contradiction with existing constraints or decisions
|
|
332
|
+
|
|
333
|
+
### 3.8.3 Alternative Solutions Check
|
|
334
|
+
|
|
335
|
+
Consider whether obvious alternatives were evaluated:
|
|
336
|
+
|
|
337
|
+
- [ ] Is there a simpler solution that achieves 80% of the value?
|
|
338
|
+
- [ ] Is there an existing solution (in codebase or ecosystem) being ignored?
|
|
339
|
+
- [ ] Are we solving the root cause or just a symptom?
|
|
340
|
+
|
|
341
|
+
### 3.8.4 Red Flags Detection
|
|
342
|
+
|
|
343
|
+
Watch for patterns that indicate strategic errors:
|
|
344
|
+
|
|
345
|
+
| Red Flag | Detection | Action |
|
|
346
|
+
|----------|-----------|--------|
|
|
347
|
+
| Scope mismatch | Large effort for minor improvement | Warning |
|
|
348
|
+
| Symptom treatment | Fixing output without addressing cause | Critical |
|
|
349
|
+
| Reinventing wheel | Custom solution when standard exists | Warning |
|
|
350
|
+
| Direction conflict | Contradicts recent project decisions | Critical |
|
|
351
|
+
| Assumption fragility | Success depends on unverified assumptions | Warning |
|
|
352
|
+
|
|
353
|
+
### 3.8.5 Strategic Verdict
|
|
354
|
+
|
|
355
|
+
**If concerns found:**
|
|
356
|
+
- Minor concerns → Add to **Recommendations** with prefix `[Strategic]`
|
|
357
|
+
- Major concerns → Add **Critical** issue: "Strategic concern: {description}. Recommend `/sf:discuss` before proceeding."
|
|
358
|
+
|
|
359
|
+
**If no concerns:**
|
|
360
|
+
- Add to audit output: "Strategic fit: ✓ Aligned with project goals"
|
|
361
|
+
|
|
303
362
|
## Step 4: Generate Implementation Tasks (for large specs)
|
|
304
363
|
|
|
305
364
|
If scope is large, generate the Implementation Tasks section:
|
|
@@ -566,7 +625,9 @@ Choose one:
|
|
|
566
625
|
<success_criteria>
|
|
567
626
|
- [ ] Specification fully read
|
|
568
627
|
- [ ] PROJECT.md context loaded
|
|
569
|
-
- [ ] All
|
|
628
|
+
- [ ] All 9 dimensions evaluated (clarity, completeness, testability, scope, feasibility, architecture, duplication, cognitive load, strategic fit)
|
|
629
|
+
- [ ] Assumptions extracted and impact assessed
|
|
630
|
+
- [ ] Project alignment verified
|
|
570
631
|
- [ ] Issues categorized (critical vs recommendations)
|
|
571
632
|
- [ ] Audit recorded in spec's Audit History
|
|
572
633
|
- [ ] STATE.md updated
|
package/commands/sf/audit.md
CHANGED
|
@@ -1,6 +1,7 @@
|
|
|
1
1
|
---
|
|
2
2
|
name: sf:audit
|
|
3
3
|
description: Audit the active specification in a fresh context
|
|
4
|
+
argument-hint: "[SPEC-XXX] [--import \"feedback\"]"
|
|
4
5
|
allowed-tools:
|
|
5
6
|
- Read
|
|
6
7
|
- Write
|
|
@@ -8,10 +9,13 @@ allowed-tools:
|
|
|
8
9
|
- Glob
|
|
9
10
|
- Grep
|
|
10
11
|
- Task
|
|
12
|
+
- AskUserQuestion
|
|
11
13
|
---
|
|
12
14
|
|
|
13
15
|
<purpose>
|
|
14
16
|
Audit the active specification using a fresh context subagent. The auditor evaluates clarity, completeness, testability, scope, and feasibility without bias from the creation process.
|
|
17
|
+
|
|
18
|
+
Also supports importing external feedback (from code reviews, security audits, team discussions) for critical evaluation and selective application.
|
|
15
19
|
</purpose>
|
|
16
20
|
|
|
17
21
|
<context>
|
|
@@ -52,7 +56,7 @@ Exit.
|
|
|
52
56
|
|
|
53
57
|
Read the active spec file: `.specflow/specs/SPEC-XXX.md`
|
|
54
58
|
|
|
55
|
-
**If status is not 'draft' or 'revision_requested':**
|
|
59
|
+
**If status is not 'draft', 'auditing', or 'revision_requested':**
|
|
56
60
|
```
|
|
57
61
|
Specification SPEC-XXX is already audited (status: {status}).
|
|
58
62
|
|
|
@@ -60,6 +64,133 @@ Use `/sf:run` to implement or `/sf:status` to see current state.
|
|
|
60
64
|
```
|
|
61
65
|
Exit.
|
|
62
66
|
|
|
67
|
+
## Step 3.5: Check for --import Flag
|
|
68
|
+
|
|
69
|
+
Parse arguments for `--import "feedback text"` pattern.
|
|
70
|
+
|
|
71
|
+
**If --import flag present:** Go to Step 4-IMPORT
|
|
72
|
+
**Otherwise:** Continue to Step 4 (internal audit)
|
|
73
|
+
|
|
74
|
+
---
|
|
75
|
+
|
|
76
|
+
## Step 4-IMPORT: Import External Feedback
|
|
77
|
+
|
|
78
|
+
### 4.1 Parse External Feedback
|
|
79
|
+
|
|
80
|
+
Extract the feedback text from the `--import` argument.
|
|
81
|
+
|
|
82
|
+
**Expected formats in feedback:**
|
|
83
|
+
- `[Critical]` or `[CRITICAL]` — blocking issues
|
|
84
|
+
- `[Major]` or `[Recommend]` — should fix
|
|
85
|
+
- `[Minor]` or `[Optional]` — nice to have
|
|
86
|
+
- Numbered lists (1. 2. 3.)
|
|
87
|
+
- Bullet points (- or *)
|
|
88
|
+
|
|
89
|
+
If no severity markers found, treat all items as `[Major]`.
|
|
90
|
+
|
|
91
|
+
### 4.2 Structure the Feedback
|
|
92
|
+
|
|
93
|
+
Parse items into structured format:
|
|
94
|
+
|
|
95
|
+
```
|
|
96
|
+
Critical Issues:
|
|
97
|
+
1. {item}
|
|
98
|
+
2. {item}
|
|
99
|
+
|
|
100
|
+
Major Issues:
|
|
101
|
+
3. {item}
|
|
102
|
+
4. {item}
|
|
103
|
+
|
|
104
|
+
Minor Issues:
|
|
105
|
+
5. {item}
|
|
106
|
+
```
|
|
107
|
+
|
|
108
|
+
### 4.3 Get Next Audit Version
|
|
109
|
+
|
|
110
|
+
```bash
|
|
111
|
+
AUDIT_COUNT=$(grep -c "### Audit v" .specflow/specs/SPEC-XXX.md 2>/dev/null || echo 0)
|
|
112
|
+
EXTERNAL_COUNT=$(grep -c "### External Audit" .specflow/specs/SPEC-XXX.md 2>/dev/null || echo 0)
|
|
113
|
+
NEXT_VERSION=$((AUDIT_COUNT + EXTERNAL_COUNT + 1))
|
|
114
|
+
```
|
|
115
|
+
|
|
116
|
+
### 4.4 Append to Audit History
|
|
117
|
+
|
|
118
|
+
Append to the spec's `## Audit History` section:
|
|
119
|
+
|
|
120
|
+
```markdown
|
|
121
|
+
### External Audit v{N} ({date} {time})
|
|
122
|
+
**Source:** External review
|
|
123
|
+
**Status:** PENDING_REVIEW
|
|
124
|
+
|
|
125
|
+
**Critical Issues:**
|
|
126
|
+
1. {parsed critical item}
|
|
127
|
+
2. {parsed critical item}
|
|
128
|
+
|
|
129
|
+
**Major Issues:**
|
|
130
|
+
3. {parsed major item}
|
|
131
|
+
|
|
132
|
+
**Minor Issues:**
|
|
133
|
+
4. {parsed minor item}
|
|
134
|
+
|
|
135
|
+
---
|
|
136
|
+
*Imported feedback requires review before application.*
|
|
137
|
+
*Use `/sf:revise` to critically evaluate and selectively apply.*
|
|
138
|
+
```
|
|
139
|
+
|
|
140
|
+
### 4.5 Update Spec Status
|
|
141
|
+
|
|
142
|
+
In spec frontmatter, set: `status: revision_requested`
|
|
143
|
+
|
|
144
|
+
### 4.6 Update STATE.md
|
|
145
|
+
|
|
146
|
+
Update STATE.md:
|
|
147
|
+
- Status → "external_review"
|
|
148
|
+
- Next Step → "/sf:revise"
|
|
149
|
+
- Add decision: "Imported external feedback for SPEC-XXX"
|
|
150
|
+
|
|
151
|
+
### 4.7 Display Import Result
|
|
152
|
+
|
|
153
|
+
```
|
|
154
|
+
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
|
|
155
|
+
EXTERNAL FEEDBACK IMPORTED
|
|
156
|
+
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
|
|
157
|
+
|
|
158
|
+
**Specification:** SPEC-XXX
|
|
159
|
+
**Source:** External review
|
|
160
|
+
|
|
161
|
+
### Imported Items
|
|
162
|
+
|
|
163
|
+
**Critical:** {count} items
|
|
164
|
+
**Major:** {count} items
|
|
165
|
+
**Minor:** {count} items
|
|
166
|
+
|
|
167
|
+
### Preview
|
|
168
|
+
|
|
169
|
+
{Show first 2-3 items as preview}
|
|
170
|
+
|
|
171
|
+
---
|
|
172
|
+
|
|
173
|
+
📄 File: .specflow/specs/SPEC-XXX.md
|
|
174
|
+
|
|
175
|
+
---
|
|
176
|
+
|
|
177
|
+
## Next Step
|
|
178
|
+
|
|
179
|
+
`/sf:revise` — critically review and selectively apply
|
|
180
|
+
|
|
181
|
+
Options:
|
|
182
|
+
• `/sf:revise` — interactive review (recommended)
|
|
183
|
+
• `/sf:revise all` — apply all items
|
|
184
|
+
• `/sf:revise 1,2,5` — apply specific items
|
|
185
|
+
• `/sf:discuss SPEC-XXX` — discuss items before deciding
|
|
186
|
+
|
|
187
|
+
<sub>External feedback should be critically evaluated, not blindly applied.</sub>
|
|
188
|
+
```
|
|
189
|
+
|
|
190
|
+
Exit.
|
|
191
|
+
|
|
192
|
+
---
|
|
193
|
+
|
|
63
194
|
## Step 4: Determine Model Profile
|
|
64
195
|
|
|
65
196
|
Check `.specflow/config.json` for model profile setting:
|
package/commands/sf/help.md
CHANGED
|
@@ -128,6 +128,8 @@ Read the command file and extract:
|
|
|
128
128
|
```
|
|
129
129
|
/sf:audit # Audit active specification
|
|
130
130
|
/sf:audit SPEC-003 # Audit specific specification
|
|
131
|
+
/sf:audit --import "[Critical] No error handling; [Major] Add logging"
|
|
132
|
+
/sf:audit --import "Security review: 1. SQL injection in search 2. XSS in comments"
|
|
131
133
|
```
|
|
132
134
|
```
|
|
133
135
|
|
|
@@ -146,11 +148,22 @@ Read the command file and extract:
|
|
|
146
148
|
## Examples
|
|
147
149
|
|
|
148
150
|
```
|
|
149
|
-
/sf:revise # Interactive — shows audit comments
|
|
151
|
+
/sf:revise # Interactive — shows audit comments with analysis
|
|
150
152
|
/sf:revise all # Apply all audit comments
|
|
151
153
|
/sf:revise 1,2 # Apply only comments 1 and 2
|
|
154
|
+
/sf:revise --no-analysis # Skip pre-analysis, go directly to review mode
|
|
152
155
|
/sf:revise "add error handling, ignore item 3"
|
|
153
156
|
```
|
|
157
|
+
|
|
158
|
+
## Flags
|
|
159
|
+
|
|
160
|
+
| Flag | Description |
|
|
161
|
+
|------|-------------|
|
|
162
|
+
| `--no-analysis` | Skip AI pre-analysis of external feedback |
|
|
163
|
+
|
|
164
|
+
**Note:** For external audits, Claude analyzes each feedback item and provides
|
|
165
|
+
recommendations (Apply/Discuss/Skip) before showing review options. Use
|
|
166
|
+
`--no-analysis` to skip this and go directly to manual review.
|
|
154
167
|
```
|
|
155
168
|
|
|
156
169
|
**For `/sf:split`:**
|
|
@@ -209,7 +222,7 @@ Workflow: Spec → Audit → Revise → Run → Review → Fix → Done
|
|
|
209
222
|
|--------------|-----------------------------------------|
|
|
210
223
|
| /sf:init | Initialize project, analyze codebase |
|
|
211
224
|
| /sf:new | Create specification from task |
|
|
212
|
-
| /sf:audit | Audit
|
|
225
|
+
| /sf:audit | Audit spec or import external feedback |
|
|
213
226
|
| /sf:revise | Revise spec based on audit feedback |
|
|
214
227
|
| /sf:run | Execute specification |
|
|
215
228
|
| /sf:review | Review implementation (fresh context) |
|
package/commands/sf/revise.md
CHANGED
|
@@ -63,16 +63,88 @@ Exit.
|
|
|
63
63
|
|
|
64
64
|
## Step 4: Extract Latest Audit
|
|
65
65
|
|
|
66
|
-
Find the most recent
|
|
66
|
+
Find the most recent audit section in Audit History. Can be:
|
|
67
|
+
- `### Audit v[N]` — internal audit
|
|
68
|
+
- `### External Audit v[N]` — imported external feedback
|
|
67
69
|
|
|
68
70
|
**If no audit exists:**
|
|
69
71
|
```
|
|
70
72
|
Specification SPEC-XXX has no audit history.
|
|
71
73
|
|
|
72
|
-
Run `/sf:audit` first to get feedback
|
|
74
|
+
Run `/sf:audit` first to get feedback,
|
|
75
|
+
or `/sf:audit --import "feedback"` to import external review.
|
|
73
76
|
```
|
|
74
77
|
Exit.
|
|
75
78
|
|
|
79
|
+
**Determine audit type:**
|
|
80
|
+
```bash
|
|
81
|
+
LATEST_AUDIT=$(grep -E "^### (External )?Audit v[0-9]+" .specflow/specs/SPEC-XXX.md | tail -1)
|
|
82
|
+
if echo "$LATEST_AUDIT" | grep -q "External"; then
|
|
83
|
+
AUDIT_TYPE="external"
|
|
84
|
+
else
|
|
85
|
+
AUDIT_TYPE="internal"
|
|
86
|
+
fi
|
|
87
|
+
```
|
|
88
|
+
|
|
89
|
+
## Step 4.5: Pre-analyze External Feedback
|
|
90
|
+
|
|
91
|
+
**Only for external audits (AUDIT_TYPE="external"):**
|
|
92
|
+
|
|
93
|
+
Skip this step if:
|
|
94
|
+
- `--no-analysis` flag is present in arguments
|
|
95
|
+
- AUDIT_TYPE is "internal"
|
|
96
|
+
|
|
97
|
+
### Analysis Process
|
|
98
|
+
|
|
99
|
+
Read the specification and project context, then analyze each external feedback item:
|
|
100
|
+
|
|
101
|
+
For each item in the external audit:
|
|
102
|
+
1. Check if the issue actually exists in the current specification
|
|
103
|
+
2. Evaluate relevance to the specification's scope and goals
|
|
104
|
+
3. Consider project architecture and constraints
|
|
105
|
+
4. Determine recommendation: Apply / Discuss / Skip
|
|
106
|
+
|
|
107
|
+
### Display Analysis Results
|
|
108
|
+
|
|
109
|
+
```
|
|
110
|
+
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
|
|
111
|
+
ANALYSIS: EXTERNAL FEEDBACK — SPEC-XXX
|
|
112
|
+
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
|
|
113
|
+
|
|
114
|
+
Based on specification context and project architecture:
|
|
115
|
+
|
|
116
|
+
| # | Item | Recommendation | Reason |
|
|
117
|
+
|---|------|----------------|--------|
|
|
118
|
+
| 1 | {issue description} | ✓ Apply | {why it's relevant} |
|
|
119
|
+
| 2 | {issue description} | ✓ Apply | {why it's relevant} |
|
|
120
|
+
| 3 | {issue description} | ? Discuss | {why clarification needed} |
|
|
121
|
+
| 4 | {issue description} | ✗ Skip | {why not applicable} |
|
|
122
|
+
|
|
123
|
+
**Summary:** {N} recommended, {M} need discussion, {K} likely irrelevant
|
|
124
|
+
|
|
125
|
+
---
|
|
126
|
+
```
|
|
127
|
+
|
|
128
|
+
### Recommendation Criteria
|
|
129
|
+
|
|
130
|
+
**✓ Apply** — recommend when:
|
|
131
|
+
- Issue clearly exists in the specification
|
|
132
|
+
- Fix aligns with specification goals
|
|
133
|
+
- Within scope of current work
|
|
134
|
+
|
|
135
|
+
**? Discuss** — recommend when:
|
|
136
|
+
- Issue may be valid but requires clarification
|
|
137
|
+
- Trade-offs need user decision
|
|
138
|
+
- Significant architectural change implied
|
|
139
|
+
|
|
140
|
+
**✗ Skip** — recommend when:
|
|
141
|
+
- Issue doesn't exist in current specification
|
|
142
|
+
- Clearly out of scope for this specification
|
|
143
|
+
- Based on incorrect assumptions about the project
|
|
144
|
+
- Would conflict with explicit requirements
|
|
145
|
+
|
|
146
|
+
Continue to Step 5 with analysis context available.
|
|
147
|
+
|
|
76
148
|
## Step 5: Parse Arguments
|
|
77
149
|
|
|
78
150
|
| Argument | Action |
|
|
@@ -80,11 +152,23 @@ Exit.
|
|
|
80
152
|
| (none) | Interactive mode — show comments, ask what to fix |
|
|
81
153
|
| "all" | Apply all critical issues AND recommendations |
|
|
82
154
|
| "1,2,3" | Apply only numbered items |
|
|
155
|
+
| "--no-analysis" | Skip pre-analysis, go directly to review mode |
|
|
83
156
|
| "..." | Treat as custom revision instructions |
|
|
84
157
|
|
|
158
|
+
**Check for `--no-analysis` flag:**
|
|
159
|
+
```bash
|
|
160
|
+
if echo "$ARGS" | grep -q "\-\-no-analysis"; then
|
|
161
|
+
SKIP_ANALYSIS=true
|
|
162
|
+
# Remove flag from args for further processing
|
|
163
|
+
ARGS=$(echo "$ARGS" | sed 's/--no-analysis//g' | xargs)
|
|
164
|
+
fi
|
|
165
|
+
```
|
|
166
|
+
|
|
85
167
|
### If Interactive Mode (no arguments):
|
|
86
168
|
|
|
87
|
-
Display audit comments:
|
|
169
|
+
Display audit comments with context about source:
|
|
170
|
+
|
|
171
|
+
**For internal audit:**
|
|
88
172
|
|
|
89
173
|
```
|
|
90
174
|
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
|
|
@@ -111,6 +195,89 @@ Use AskUserQuestion with options:
|
|
|
111
195
|
- "Fix critical only (1, 2)" → treat as "1,2"
|
|
112
196
|
- "Custom selection" → ask for numbers or description
|
|
113
197
|
|
|
198
|
+
**For external audit (requires critical evaluation):**
|
|
199
|
+
|
|
200
|
+
**If pre-analysis was performed (Step 4.5):**
|
|
201
|
+
|
|
202
|
+
```
|
|
203
|
+
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
|
|
204
|
+
REVIEW EXTERNAL FEEDBACK: SPEC-XXX
|
|
205
|
+
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
|
|
206
|
+
|
|
207
|
+
External Audit (v{N}) — with analysis:
|
|
208
|
+
|
|
209
|
+
| # | Item | Severity | Recommendation | Reason |
|
|
210
|
+
|---|------|----------|----------------|--------|
|
|
211
|
+
| 1 | {issue} | Critical | ✓ Apply | {reason} |
|
|
212
|
+
| 2 | {issue} | Critical | ✓ Apply | {reason} |
|
|
213
|
+
| 3 | {issue} | Major | ? Discuss | {reason} |
|
|
214
|
+
| 4 | {issue} | Major | ✗ Skip | {reason} |
|
|
215
|
+
| 5 | {issue} | Minor | ✓ Apply | {reason} |
|
|
216
|
+
|
|
217
|
+
**Analysis:** {N} recommended, {M} need discussion, {K} skip suggested
|
|
218
|
+
|
|
219
|
+
---
|
|
220
|
+
|
|
221
|
+
How to proceed?
|
|
222
|
+
```
|
|
223
|
+
|
|
224
|
+
Use AskUserQuestion with options:
|
|
225
|
+
- "Apply recommended" → apply items marked ✓ Apply (recommended)
|
|
226
|
+
- "Review each item" → interactive per-item evaluation
|
|
227
|
+
- "Apply all" → apply everything (ignore analysis)
|
|
228
|
+
- "Select specific" → ask for numbers
|
|
229
|
+
|
|
230
|
+
**If pre-analysis was skipped (`--no-analysis` or internal flow):**
|
|
231
|
+
|
|
232
|
+
```
|
|
233
|
+
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
|
|
234
|
+
REVIEW EXTERNAL FEEDBACK: SPEC-XXX
|
|
235
|
+
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
|
|
236
|
+
|
|
237
|
+
⚠️ External feedback requires critical evaluation.
|
|
238
|
+
Not all suggestions may be applicable or correct.
|
|
239
|
+
|
|
240
|
+
External Audit (v{N}) items:
|
|
241
|
+
|
|
242
|
+
**Critical:**
|
|
243
|
+
1. [Issue 1]
|
|
244
|
+
2. [Issue 2]
|
|
245
|
+
|
|
246
|
+
**Major:**
|
|
247
|
+
3. [Issue 3]
|
|
248
|
+
4. [Issue 4]
|
|
249
|
+
|
|
250
|
+
**Minor:**
|
|
251
|
+
5. [Issue 5]
|
|
252
|
+
|
|
253
|
+
---
|
|
254
|
+
|
|
255
|
+
How to proceed?
|
|
256
|
+
```
|
|
257
|
+
|
|
258
|
+
Use AskUserQuestion with options:
|
|
259
|
+
- "Review each item" → interactive per-item evaluation (recommended)
|
|
260
|
+
- "Apply all" → apply everything (use with caution)
|
|
261
|
+
- "Apply critical only" → treat as critical items
|
|
262
|
+
- "Select specific" → ask for numbers
|
|
263
|
+
|
|
264
|
+
**If "Review each item" selected:**
|
|
265
|
+
|
|
266
|
+
For each item, use AskUserQuestion:
|
|
267
|
+
```
|
|
268
|
+
Item {N}: {issue description}
|
|
269
|
+
|
|
270
|
+
Evaluate this feedback:
|
|
271
|
+
```
|
|
272
|
+
|
|
273
|
+
Options:
|
|
274
|
+
- "Apply" — implement this change
|
|
275
|
+
- "Skip" — not applicable, with reason
|
|
276
|
+
- "Discuss" — need clarification
|
|
277
|
+
- "Defer" — valid but out of scope
|
|
278
|
+
|
|
279
|
+
Record each decision in Response section.
|
|
280
|
+
|
|
114
281
|
## Step 6: Determine Model Profile
|
|
115
282
|
|
|
116
283
|
Check `.specflow/config.json` for model profile setting:
|
|
@@ -163,6 +330,8 @@ The agent will:
|
|
|
163
330
|
|
|
164
331
|
## Step 9: Display Result
|
|
165
332
|
|
|
333
|
+
**For internal audit:**
|
|
334
|
+
|
|
166
335
|
```
|
|
167
336
|
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
|
|
168
337
|
REVISION COMPLETE
|
|
@@ -194,6 +363,50 @@ The agent will:
|
|
|
194
363
|
<sub>/clear recommended → auditor needs fresh context</sub>
|
|
195
364
|
```
|
|
196
365
|
|
|
366
|
+
**For external audit:**
|
|
367
|
+
|
|
368
|
+
```
|
|
369
|
+
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
|
|
370
|
+
EXTERNAL FEEDBACK REVIEWED
|
|
371
|
+
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
|
|
372
|
+
|
|
373
|
+
**Specification:** SPEC-XXX
|
|
374
|
+
**External Audit:** v{N} → Response v{N}
|
|
375
|
+
|
|
376
|
+
### Decisions Summary
|
|
377
|
+
|
|
378
|
+
| # | Item | Decision | Reason |
|
|
379
|
+
|---|------|----------|--------|
|
|
380
|
+
| 1 | {short description} | ✓ Applied | — |
|
|
381
|
+
| 2 | {short description} | ✗ Skipped | {reason} |
|
|
382
|
+
| 3 | {short description} | ⏸ Deferred | Out of scope |
|
|
383
|
+
| 4 | {short description} | ? Discuss | Needs clarification |
|
|
384
|
+
|
|
385
|
+
**Applied:** {count} | **Skipped:** {count} | **Deferred:** {count}
|
|
386
|
+
|
|
387
|
+
{If any items marked "Discuss":}
|
|
388
|
+
### Needs Discussion
|
|
389
|
+
|
|
390
|
+
Items {N, M} require clarification before deciding.
|
|
391
|
+
|
|
392
|
+
---
|
|
393
|
+
|
|
394
|
+
📄 File: .specflow/specs/SPEC-XXX.md
|
|
395
|
+
|
|
396
|
+
---
|
|
397
|
+
|
|
398
|
+
## Next Steps
|
|
399
|
+
|
|
400
|
+
{If items need discussion:}
|
|
401
|
+
`/sf:discuss SPEC-XXX` — clarify items {N, M}
|
|
402
|
+
|
|
403
|
+
{If all decided:}
|
|
404
|
+
`/sf:audit` — re-audit with applied changes
|
|
405
|
+
|
|
406
|
+
{If deferred items exist:}
|
|
407
|
+
<sub>Deferred items saved to `.specflow/todos/` for future consideration.</sub>
|
|
408
|
+
```
|
|
409
|
+
|
|
197
410
|
</workflow>
|
|
198
411
|
|
|
199
412
|
<fallback>
|
|
@@ -223,7 +436,7 @@ RESPONSE_COUNT=$(grep -c "### Response v" .specflow/specs/SPEC-XXX.md 2>/dev/nul
|
|
|
223
436
|
NEXT_VERSION=$((RESPONSE_COUNT + 1))
|
|
224
437
|
```
|
|
225
438
|
|
|
226
|
-
|
|
439
|
+
**For internal audit, append:**
|
|
227
440
|
|
|
228
441
|
```markdown
|
|
229
442
|
### Response v{N} ({date} {time})
|
|
@@ -234,6 +447,23 @@ Append to Audit History:
|
|
|
234
447
|
2. [✓/✗] {Item} — {what was done}
|
|
235
448
|
```
|
|
236
449
|
|
|
450
|
+
**For external audit, append:**
|
|
451
|
+
|
|
452
|
+
```markdown
|
|
453
|
+
### Response v{N} ({date} {time})
|
|
454
|
+
**Source:** External Audit v{M}
|
|
455
|
+
**Review Type:** {interactive | bulk}
|
|
456
|
+
|
|
457
|
+
**Decisions:**
|
|
458
|
+
| # | Item | Decision | Reason |
|
|
459
|
+
|---|------|----------|--------|
|
|
460
|
+
| 1 | {description} | Applied | — |
|
|
461
|
+
| 2 | {description} | Skipped | {reason} |
|
|
462
|
+
| 3 | {description} | Deferred | {reason} |
|
|
463
|
+
|
|
464
|
+
**Summary:** Applied {X}/{Y} items, Skipped {Z}, Deferred {W}
|
|
465
|
+
```
|
|
466
|
+
|
|
237
467
|
### Update Status
|
|
238
468
|
|
|
239
469
|
In spec frontmatter: `status: auditing`
|
package/commands/sf/status.md
CHANGED
|
@@ -70,6 +70,7 @@ Based on current status:
|
|
|
70
70
|
| idle | `/sf:new "task"` — create specification |
|
|
71
71
|
| drafting | `/sf:audit` — audit specification |
|
|
72
72
|
| revision_requested | `/sf:revise` — fix issues |
|
|
73
|
+
| external_review | `/sf:revise` — review external feedback |
|
|
73
74
|
| audited | `/sf:run` — implement |
|
|
74
75
|
| running | Continue implementation or `/sf:review` |
|
|
75
76
|
| reviewing | `/sf:fix` or `/sf:done` |
|
package/package.json
CHANGED
package/templates/spec.md
CHANGED
|
@@ -1,7 +1,7 @@
|
|
|
1
1
|
---
|
|
2
2
|
id: SPEC-XXX
|
|
3
3
|
type: feature | refactor | bugfix
|
|
4
|
-
status: draft | audited | running | review | done
|
|
4
|
+
status: draft | auditing | revision_requested | audited | running | review | done
|
|
5
5
|
priority: high | medium | low
|
|
6
6
|
complexity: small | medium | large
|
|
7
7
|
created: YYYY-MM-DD
|
package/templates/state.md
CHANGED
|
@@ -5,8 +5,8 @@
|
|
|
5
5
|
## Current Position
|
|
6
6
|
|
|
7
7
|
- **Active Specification:** [none | SPEC-XXX]
|
|
8
|
-
- **Status:** [idle | drafting | auditing | running | reviewing]
|
|
9
|
-
- **Next Step:** [/sf:new | /sf:audit | /sf:run | /sf:review | /sf:done]
|
|
8
|
+
- **Status:** [idle | drafting | auditing | revision_requested | external_review | running | reviewing]
|
|
9
|
+
- **Next Step:** [/sf:new | /sf:audit | /sf:revise | /sf:run | /sf:review | /sf:done]
|
|
10
10
|
|
|
11
11
|
## Queue
|
|
12
12
|
|