5-phase-workflow 1.0.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/README.md +332 -0
- package/bin/install.js +408 -0
- package/docs/workflow-guide.md +1024 -0
- package/package.json +34 -0
- package/src/agents/integration-agent.md +219 -0
- package/src/agents/review-processor.md +160 -0
- package/src/agents/step-executor.md +108 -0
- package/src/agents/step-fixer.md +132 -0
- package/src/agents/step-verifier.md +125 -0
- package/src/agents/verification-agent.md +411 -0
- package/src/commands/5/configure.md +309 -0
- package/src/commands/5/discuss-feature.md +393 -0
- package/src/commands/5/implement-feature.md +502 -0
- package/src/commands/5/plan-feature.md +285 -0
- package/src/commands/5/plan-implementation.md +376 -0
- package/src/commands/5/quick-implement.md +263 -0
- package/src/commands/5/review-code.md +583 -0
- package/src/commands/5/verify-implementation.md +277 -0
- package/src/hooks/statusline.js +53 -0
- package/src/settings.json +6 -0
- package/src/skills/build-project/SKILL.md +277 -0
- package/src/skills/configure-project/SKILL.md +355 -0
- package/src/skills/generate-readme/EXAMPLES.md +168 -0
- package/src/skills/generate-readme/SKILL.md +123 -0
- package/src/skills/generate-readme/TEMPLATE.md +141 -0
- package/src/skills/run-tests/SKILL.md +365 -0
- package/src/templates/ARCHITECTURE.md +64 -0
- package/src/templates/CONCERNS.md +75 -0
- package/src/templates/CONVENTIONS.md +75 -0
- package/src/templates/INTEGRATIONS.md +65 -0
- package/src/templates/STACK.md +60 -0
- package/src/templates/STRUCTURE.md +60 -0
- package/src/templates/TESTING.md +107 -0
|
@@ -0,0 +1,309 @@
|
|
|
1
|
+
---
|
|
2
|
+
name: 5:configure
|
|
3
|
+
description: Phase 1 of project configuration. Analyzes project, gathers preferences, and creates a configuration feature spec. Follow up with /5:plan-implementation CONFIGURE.
|
|
4
|
+
allowed-tools: Read, Write, Bash, Glob, Grep, AskUserQuestion
|
|
5
|
+
context: inherit
|
|
6
|
+
user-invocable: true
|
|
7
|
+
---
|
|
8
|
+
|
|
9
|
+
# Configure (Phase 1 - Plan Feature for Project Configuration)
|
|
10
|
+
|
|
11
|
+
## Overview
|
|
12
|
+
|
|
13
|
+
This command is **Phase 1** of the 5-phase workflow applied to project configuration itself. It analyzes the project, asks the user questions, and outputs a feature spec at `.5/CONFIGURE/feature.md`.
|
|
14
|
+
|
|
15
|
+
After running this command, proceed through the standard phases:
|
|
16
|
+
1. **`/5:configure`** (this command) - Plan the configuration feature
|
|
17
|
+
2. `/5:plan-implementation CONFIGURE` - Create implementation plan
|
|
18
|
+
3. `/5:implement-feature CONFIGURE` - Execute configuration (uses `configure-project` skill)
|
|
19
|
+
4. `/5:verify-implementation` - Verify configuration
|
|
20
|
+
5. `/5:review-code` - Review generated files
|
|
21
|
+
|
|
22
|
+
## Configuration Process
|
|
23
|
+
|
|
24
|
+
### Step 1: Analyze Project (auto-detect, no user interaction)
|
|
25
|
+
|
|
26
|
+
Perform all detection silently, collecting results for Step 2.
|
|
27
|
+
|
|
28
|
+
**1a. Check for existing config:**
|
|
29
|
+
```bash
|
|
30
|
+
if [ -f ".claude/.5/config.json" ]; then
|
|
31
|
+
# Config exists - will ask user in Step 2
|
|
32
|
+
fi
|
|
33
|
+
```
|
|
34
|
+
|
|
35
|
+
**1b. Detect project type** by examining files:
|
|
36
|
+
|
|
37
|
+
```javascript
|
|
38
|
+
// Node.js/JavaScript/TypeScript
|
|
39
|
+
if (exists('package.json')) {
|
|
40
|
+
const pkg = readJSON('package.json');
|
|
41
|
+
|
|
42
|
+
if (pkg.dependencies?.['next'] || pkg.devDependencies?.['next'])
|
|
43
|
+
return 'nextjs';
|
|
44
|
+
if (pkg.dependencies?.['@nestjs/core'])
|
|
45
|
+
return 'nestjs';
|
|
46
|
+
if (pkg.dependencies?.['express'])
|
|
47
|
+
return 'express';
|
|
48
|
+
if (pkg.dependencies?.['react'])
|
|
49
|
+
return 'react';
|
|
50
|
+
if (pkg.dependencies?.['vue'])
|
|
51
|
+
return 'vue';
|
|
52
|
+
|
|
53
|
+
return 'javascript';
|
|
54
|
+
}
|
|
55
|
+
|
|
56
|
+
// Java
|
|
57
|
+
if (exists('build.gradle') || exists('build.gradle.kts'))
|
|
58
|
+
return 'gradle-java';
|
|
59
|
+
if (exists('pom.xml'))
|
|
60
|
+
return 'maven-java';
|
|
61
|
+
|
|
62
|
+
// Python
|
|
63
|
+
if (exists('requirements.txt') || exists('pyproject.toml')) {
|
|
64
|
+
if (exists('manage.py')) return 'django';
|
|
65
|
+
if (exists('app.py') || exists('wsgi.py')) return 'flask';
|
|
66
|
+
return 'python';
|
|
67
|
+
}
|
|
68
|
+
|
|
69
|
+
// Rust
|
|
70
|
+
if (exists('Cargo.toml'))
|
|
71
|
+
return 'rust';
|
|
72
|
+
|
|
73
|
+
// Go
|
|
74
|
+
if (exists('go.mod'))
|
|
75
|
+
return 'go';
|
|
76
|
+
|
|
77
|
+
// Ruby
|
|
78
|
+
if (exists('Gemfile')) {
|
|
79
|
+
if (exists('config/routes.rb')) return 'rails';
|
|
80
|
+
return 'ruby';
|
|
81
|
+
}
|
|
82
|
+
|
|
83
|
+
return 'unknown';
|
|
84
|
+
```
|
|
85
|
+
|
|
86
|
+
**1c. Detect build/test commands** based on project type:
|
|
87
|
+
|
|
88
|
+
| Type | Build Command | Test Command |
|
|
89
|
+
|------|--------------|--------------|
|
|
90
|
+
| javascript | `npm run build` | `npm test` |
|
|
91
|
+
| nextjs | `npm run build` | `npm test` |
|
|
92
|
+
| nestjs | `npm run build` | `npm test` |
|
|
93
|
+
| express | `npm run build \|\| tsc` | `npm test` |
|
|
94
|
+
| gradle-java | `./gradlew build -x test -x javadoc --offline` | `./gradlew test --offline` |
|
|
95
|
+
| maven-java | `mvn package -DskipTests` | `mvn test` |
|
|
96
|
+
| python | `python -m py_compile **/*.py` | `pytest` |
|
|
97
|
+
| django | `python manage.py check` | `python manage.py test` |
|
|
98
|
+
| rust | `cargo build` | `cargo test` |
|
|
99
|
+
| go | `go build ./...` | `go test ./...` |
|
|
100
|
+
|
|
101
|
+
**1d. Detect available tools:**
|
|
102
|
+
|
|
103
|
+
```bash
|
|
104
|
+
# CodeRabbit CLI
|
|
105
|
+
if command -v coderabbit &> /dev/null; then
|
|
106
|
+
coderabbit_available=true
|
|
107
|
+
if coderabbit auth status | grep -q "authenticated"; then
|
|
108
|
+
coderabbit_authenticated=true
|
|
109
|
+
fi
|
|
110
|
+
fi
|
|
111
|
+
|
|
112
|
+
# IDE MCP (JetBrains) - check if MCP tools are available
|
|
113
|
+
```
|
|
114
|
+
|
|
115
|
+
**1e. Check CLAUDE.md:**
|
|
116
|
+
- If `CLAUDE.md` exists, read its content
|
|
117
|
+
|
|
118
|
+
**1f. Scan existing skills:**
|
|
119
|
+
- Check `.claude/skills/` for existing project-specific skills
|
|
120
|
+
|
|
121
|
+
### Step 2: Gather User Preferences (interactive via AskUserQuestion)
|
|
122
|
+
|
|
123
|
+
**2a. If config exists:**
|
|
124
|
+
- "Configuration already exists. What would you like to do?"
|
|
125
|
+
- Options: "Update existing", "Start fresh", "Cancel"
|
|
126
|
+
- If Cancel: stop here
|
|
127
|
+
|
|
128
|
+
**2b. Confirm project type:**
|
|
129
|
+
- "Detected project type: {detected-type}. Is this correct?"
|
|
130
|
+
- Options: "Yes (recommended)", "No, choose manually"
|
|
131
|
+
- If manual, present list: JavaScript/TypeScript, Next.js, NestJS, Express, React, Vue, Java (Gradle), Java (Maven), Python, Django, Flask, Rust, Go, Ruby on Rails, Other
|
|
132
|
+
|
|
133
|
+
**2c. Ticket ID pattern:**
|
|
134
|
+
- "How do you track work items in this project?"
|
|
135
|
+
- Options:
|
|
136
|
+
1. "JIRA-style (e.g., PROJ-1234)" - Pattern: `[A-Z]+-\\d+`
|
|
137
|
+
2. "GitHub Issues (e.g., #123)" - Pattern: `#\\d+`
|
|
138
|
+
3. "Linear (e.g., ENG-1234)" - Pattern: `[A-Z]{3}-\\d+`
|
|
139
|
+
4. "No tracking / skip" - Pattern: null
|
|
140
|
+
- Follow-up: "Extract ticket ID from branch name?" - Options: "Yes (recommended)", "No"
|
|
141
|
+
|
|
142
|
+
**2d. Branch naming convention:**
|
|
143
|
+
- "What branch naming convention do you use?"
|
|
144
|
+
- Options:
|
|
145
|
+
1. "ticket-id/description (e.g., PROJ-1234/add-feature)"
|
|
146
|
+
2. "feature/description (e.g., feature/add-login)"
|
|
147
|
+
3. "Custom pattern"
|
|
148
|
+
4. "No convention"
|
|
149
|
+
|
|
150
|
+
**2e. Confirm build/test commands:**
|
|
151
|
+
- "Suggested build command: `{command}`. Use this?"
|
|
152
|
+
- Options: "Yes (recommended)", "Customize", "None (no build step)"
|
|
153
|
+
- "Suggested test command: `{command}`. Use this?"
|
|
154
|
+
- Options: "Yes (recommended)", "Customize", "None (no test step)"
|
|
155
|
+
|
|
156
|
+
**2f. Confirm CLAUDE.md generation:**
|
|
157
|
+
- "Generate/update CLAUDE.md? This will analyze your codebase to document structure and conventions."
|
|
158
|
+
- Options: "Yes (recommended)", "Skip"
|
|
159
|
+
|
|
160
|
+
**2g. Confirm project-specific skills:**
|
|
161
|
+
- Present proposed skills based on detected project type (see skill table in configure-project/SKILL.md)
|
|
162
|
+
- "These project-specific skills were detected for your {project-type} project: {skill-list}. Confirm or customize?"
|
|
163
|
+
- Options: "Use these (recommended)", "Customize", "Skip skill generation"
|
|
164
|
+
|
|
165
|
+
### Step 3: Create Feature Spec
|
|
166
|
+
|
|
167
|
+
Write `.5/CONFIGURE/feature.md` containing all gathered data:
|
|
168
|
+
|
|
169
|
+
```markdown
|
|
170
|
+
# Feature: Project Configuration
|
|
171
|
+
|
|
172
|
+
## Summary
|
|
173
|
+
Configure the 5-phase workflow for this {project-type} project. Creates config.json, generates CLAUDE.md with codebase analysis, and creates project-specific skills.
|
|
174
|
+
|
|
175
|
+
## Requirements
|
|
176
|
+
|
|
177
|
+
### Requirement 1: Create config.json
|
|
178
|
+
Create `.claude/.5/config.json` with the following values:
|
|
179
|
+
- Project type: {project-type}
|
|
180
|
+
- Ticket pattern: {pattern}
|
|
181
|
+
- Extract from branch: {yes/no}
|
|
182
|
+
- Branch convention: {convention}
|
|
183
|
+
- Build command: {build-command}
|
|
184
|
+
- Test command: {test-command}
|
|
185
|
+
- Build timeout: 120000ms
|
|
186
|
+
- Test timeout: 300000ms
|
|
187
|
+
- CodeRabbit: {available/not-available}, authenticated: {yes/no}
|
|
188
|
+
- IDE integration: {available/not-available}, type: {type}
|
|
189
|
+
- Review tool: {coderabbit/none}
|
|
190
|
+
|
|
191
|
+
### Requirement 2: Generate Documentation Files
|
|
192
|
+
Analyze the codebase and generate modular documentation:
|
|
193
|
+
|
|
194
|
+
**Create separate documentation files in `.5/` folder:**
|
|
195
|
+
- `.5/ARCHITECTURE.md` - Architectural patterns and layers
|
|
196
|
+
- `.5/STACK.md` - Technology stack and dependencies
|
|
197
|
+
- `.5/STRUCTURE.md` - Directory layout and organization
|
|
198
|
+
- `.5/CONVENTIONS.md` - Coding standards and patterns
|
|
199
|
+
- `.5/TESTING.md` - Test framework and patterns
|
|
200
|
+
- `.5/INTEGRATIONS.md` - External services and APIs
|
|
201
|
+
- `.5/CONCERNS.md` - Tech debt, bugs, and risks
|
|
202
|
+
|
|
203
|
+
**Create CLAUDE.md as navigation hub:**
|
|
204
|
+
- Quick reference section with links to all `.5/*.md` files
|
|
205
|
+
- Project overview and build commands
|
|
206
|
+
- "Getting Started" guide with references to appropriate files
|
|
207
|
+
- Mandatory coding guidelines:
|
|
208
|
+
1. Types should be clear and types should be available when possible
|
|
209
|
+
2. Use doc (jsdoc, javadoc, pydoc, etc) concisely. No doc is better than meaningless doc
|
|
210
|
+
3. Keep files short and structured
|
|
211
|
+
4. Extract methods, classes
|
|
212
|
+
5. Respect SRP and DRY
|
|
213
|
+
6. Make code maintainable and modular
|
|
214
|
+
|
|
215
|
+
**Preserve existing content:**
|
|
216
|
+
- If CLAUDE.md already exists, preserve user-written custom sections
|
|
217
|
+
|
|
218
|
+
### Requirement 3: Generate Project-Specific Skills
|
|
219
|
+
Generate the following skills in `.claude/skills/`:
|
|
220
|
+
{List of confirmed skills, e.g.:}
|
|
221
|
+
- create-component: Creates a React component following project conventions
|
|
222
|
+
- create-hook: Creates a custom React hook following project conventions
|
|
223
|
+
- create-context: Creates a React context provider following project conventions
|
|
224
|
+
|
|
225
|
+
Each skill should:
|
|
226
|
+
- Follow standard SKILL.md frontmatter pattern
|
|
227
|
+
- Derive patterns from existing code in the project
|
|
228
|
+
- Include file naming and location conventions
|
|
229
|
+
- Include template/pattern based on existing examples
|
|
230
|
+
|
|
231
|
+
## Acceptance Criteria
|
|
232
|
+
- [ ] `.claude/.5/config.json` exists with correct values (no `steps` array)
|
|
233
|
+
- [ ] `.5/` directory created
|
|
234
|
+
- [ ] All 7 documentation files exist and are populated:
|
|
235
|
+
- [ ] `.5/ARCHITECTURE.md`
|
|
236
|
+
- [ ] `.5/STACK.md`
|
|
237
|
+
- [ ] `.5/STRUCTURE.md`
|
|
238
|
+
- [ ] `.5/CONVENTIONS.md`
|
|
239
|
+
- [ ] `.5/TESTING.md`
|
|
240
|
+
- [ ] `.5/INTEGRATIONS.md`
|
|
241
|
+
- [ ] `.5/CONCERNS.md`
|
|
242
|
+
- [ ] `CLAUDE.md` exists with references to `.5/` files
|
|
243
|
+
- [ ] CLAUDE.md contains 6 coding guidelines
|
|
244
|
+
- [ ] No placeholder text like `{YYYY-MM-DD}` remains unfilled
|
|
245
|
+
- [ ] All specified project-specific skills are generated in `.claude/skills/`
|
|
246
|
+
- [ ] Generated skills reference actual project conventions
|
|
247
|
+
- [ ] If CLAUDE.md existed before, user-written sections are preserved
|
|
248
|
+
```
|
|
249
|
+
|
|
250
|
+
**Important:** Use `mkdir -p .5/CONFIGURE` before writing the feature spec.
|
|
251
|
+
|
|
252
|
+
### Step 4: Guide User to Next Phase
|
|
253
|
+
|
|
254
|
+
Tell the user:
|
|
255
|
+
|
|
256
|
+
1. "Configuration feature planned at `.5/CONFIGURE/feature.md`"
|
|
257
|
+
2. "Next: Run `/5:plan-implementation CONFIGURE`"
|
|
258
|
+
3. "Then: `/5:implement-feature CONFIGURE` -> `/5:verify-implementation` -> `/5:review-code`"
|
|
259
|
+
|
|
260
|
+
## DO NOT
|
|
261
|
+
|
|
262
|
+
- DO NOT write config.json directly (that's Phase 3's job via the configure-project skill)
|
|
263
|
+
- DO NOT create CLAUDE.md directly (that's Phase 3's job)
|
|
264
|
+
- DO NOT generate skills directly (that's Phase 3's job)
|
|
265
|
+
- DO NOT skip user interaction - always confirm detected values
|
|
266
|
+
- DO NOT assume project structure - always detect or ask
|
|
267
|
+
|
|
268
|
+
## Example Usage
|
|
269
|
+
|
|
270
|
+
```
|
|
271
|
+
User: /5:configure
|
|
272
|
+
|
|
273
|
+
[Step 1: Auto-detection runs silently]
|
|
274
|
+
|
|
275
|
+
Claude: "Detected project type: Next.js. Is this correct?"
|
|
276
|
+
User: "Yes"
|
|
277
|
+
|
|
278
|
+
Claude: "How do you track work items?"
|
|
279
|
+
User: "GitHub Issues"
|
|
280
|
+
|
|
281
|
+
Claude: "Extract ticket ID from branch name?"
|
|
282
|
+
User: "Yes"
|
|
283
|
+
|
|
284
|
+
Claude: "Branch naming convention?"
|
|
285
|
+
User: "feature/description"
|
|
286
|
+
|
|
287
|
+
Claude: "Build command: `npm run build`. Use this?"
|
|
288
|
+
User: "Yes"
|
|
289
|
+
|
|
290
|
+
Claude: "Test command: `npm test`. Use this?"
|
|
291
|
+
User: "Yes"
|
|
292
|
+
|
|
293
|
+
Claude: "Generate CLAUDE.md with codebase analysis?"
|
|
294
|
+
User: "Yes"
|
|
295
|
+
|
|
296
|
+
Claude: "Proposed skills for Next.js: create-page, create-api-route, create-component. Confirm?"
|
|
297
|
+
User: "Use these"
|
|
298
|
+
|
|
299
|
+
Claude: [Writes .5/CONFIGURE/feature.md]
|
|
300
|
+
Claude: "Configuration feature planned at `.5/CONFIGURE/feature.md`"
|
|
301
|
+
Claude: "Next: Run `/5:plan-implementation CONFIGURE`"
|
|
302
|
+
```
|
|
303
|
+
|
|
304
|
+
## Related Documentation
|
|
305
|
+
|
|
306
|
+
- [5-Phase Workflow Guide](../../docs/workflow-guide.md)
|
|
307
|
+
- [configure-project skill](../../skills/configure-project/SKILL.md)
|
|
308
|
+
- [/5:plan-feature command](./plan-feature.md)
|
|
309
|
+
- [/5:plan-implementation command](./plan-implementation.md)
|
|
@@ -0,0 +1,393 @@
|
|
|
1
|
+
---
|
|
2
|
+
name: 5:discuss-feature
|
|
3
|
+
description: Discusses and refines an existing feature specification through iterative Q&A. Use after /plan-feature when requirements need clarification or changes. Updates the feature spec based on discussion.
|
|
4
|
+
allowed-tools: Read, Write, Glob, Grep, Task, AskUserQuestion
|
|
5
|
+
context: inherit
|
|
6
|
+
user-invocable: true
|
|
7
|
+
---
|
|
8
|
+
|
|
9
|
+
# Discuss Feature Specification (Phase 1 - Optional Iteration)
|
|
10
|
+
|
|
11
|
+
## Overview
|
|
12
|
+
|
|
13
|
+
This skill is part of **Phase 1** (Feature Planning) of the 5-phase workflow:
|
|
14
|
+
1. **Feature Planning** - Initial requirements gathering (`/plan-feature`), then optional iteration (`/discuss-feature`)
|
|
15
|
+
2. **Implementation Planning** - Map to technical components
|
|
16
|
+
3. **Orchestrated Implementation** - Execute with state tracking
|
|
17
|
+
4. **Verify Implementation** - Check completeness and correctness
|
|
18
|
+
5. **Code Review** - Apply automated quality improvements
|
|
19
|
+
|
|
20
|
+
This skill enables **optional iterative refinement** of feature specs after initial planning through discussion, clarification, and requirement changes. Use it when the initial spec needs adjustments before proceeding to implementation planning.
|
|
21
|
+
|
|
22
|
+
## Use Cases
|
|
23
|
+
|
|
24
|
+
Use this skill when:
|
|
25
|
+
- Requirements need clarification after initial planning
|
|
26
|
+
- User wants to add/modify/remove requirements
|
|
27
|
+
- Scope needs adjustment
|
|
28
|
+
- Technical constraints discovered during exploration
|
|
29
|
+
- Alternative approaches need evaluation
|
|
30
|
+
- Feature complexity needs reduction
|
|
31
|
+
- Acceptance criteria need refinement
|
|
32
|
+
|
|
33
|
+
## Prerequisites
|
|
34
|
+
|
|
35
|
+
Before invoking this skill, ensure:
|
|
36
|
+
1. Feature spec exists at `.5/{feature-name}/feature.md`
|
|
37
|
+
2. You have the feature name or ticket ID ready (e.g., "PROJ-1234-add-feature")
|
|
38
|
+
|
|
39
|
+
## Discussion Process
|
|
40
|
+
|
|
41
|
+
### Step 1: Extract Feature Name
|
|
42
|
+
|
|
43
|
+
If user provides only ticket ID (e.g., "PROJ-1234"), find the feature file:
|
|
44
|
+
- Use Glob: `.5/{TICKET-ID}-*-*/feature.md` (pattern from config)
|
|
45
|
+
- Match the ticket ID
|
|
46
|
+
- If multiple matches, ask user to specify
|
|
47
|
+
- If no match found, inform user and suggest running `/plan-feature` first
|
|
48
|
+
|
|
49
|
+
If user provides full feature name (e.g., "PROJ-1234-add-feature"), use directly.
|
|
50
|
+
|
|
51
|
+
### Step 2: Read Feature Specification
|
|
52
|
+
|
|
53
|
+
Read the feature spec from `.5/{feature-name}/feature.md`.
|
|
54
|
+
|
|
55
|
+
Extract current state:
|
|
56
|
+
- Ticket ID
|
|
57
|
+
- Summary
|
|
58
|
+
- Requirements (functional and non-functional)
|
|
59
|
+
- Constraints
|
|
60
|
+
- Affected domains
|
|
61
|
+
- Entity definitions
|
|
62
|
+
- Business rules
|
|
63
|
+
- Acceptance criteria
|
|
64
|
+
- Alternatives considered
|
|
65
|
+
- Questions & Answers
|
|
66
|
+
|
|
67
|
+
### Step 3: Initial Discussion Prompt
|
|
68
|
+
|
|
69
|
+
**FIRST ACTION:** Ask the user what they want to discuss using AskUserQuestion.
|
|
70
|
+
|
|
71
|
+
Prompt to use:
|
|
72
|
+
|
|
73
|
+
"What would you like to discuss or change about this feature?"
|
|
74
|
+
|
|
75
|
+
Provide context options for common scenarios:
|
|
76
|
+
- "Clarify existing requirements"
|
|
77
|
+
- "Add new requirements"
|
|
78
|
+
- "Remove or simplify requirements"
|
|
79
|
+
- "Change scope or approach"
|
|
80
|
+
- "Discuss technical constraints"
|
|
81
|
+
- "Review acceptance criteria"
|
|
82
|
+
- "Other (specify)"
|
|
83
|
+
|
|
84
|
+
Use `multiSelect: false` to get single focus area initially.
|
|
85
|
+
|
|
86
|
+
### Step 4: Contextual Exploration (Optional)
|
|
87
|
+
|
|
88
|
+
Based on the user's focus area, explore the codebase if needed:
|
|
89
|
+
|
|
90
|
+
**For technical constraint discussions:**
|
|
91
|
+
- Search for similar implementations
|
|
92
|
+
- Check existing patterns
|
|
93
|
+
- Identify integration points
|
|
94
|
+
|
|
95
|
+
**For scope changes:**
|
|
96
|
+
- Verify affected modules
|
|
97
|
+
- Check dependencies
|
|
98
|
+
- Identify ripple effects
|
|
99
|
+
|
|
100
|
+
Use Task tool with subagent_type=Explore for complex exploration.
|
|
101
|
+
|
|
102
|
+
### Step 5: Interactive Q&A
|
|
103
|
+
|
|
104
|
+
Based on the discussion topic, ask targeted follow-up questions using AskUserQuestion.
|
|
105
|
+
|
|
106
|
+
**Question types by topic:**
|
|
107
|
+
|
|
108
|
+
**Clarify Requirements:**
|
|
109
|
+
- "The current requirement says X. Should it also handle Y scenario?"
|
|
110
|
+
- "How should the system behave when Z happens?"
|
|
111
|
+
- "Are there edge cases we haven't considered?"
|
|
112
|
+
|
|
113
|
+
**Add Requirements:**
|
|
114
|
+
- "What is the expected behavior for this new requirement?"
|
|
115
|
+
- "How does this interact with existing requirement X?"
|
|
116
|
+
- "Should this be in scope or future work?"
|
|
117
|
+
|
|
118
|
+
**Simplify/Remove:**
|
|
119
|
+
- "If we remove X, what's the minimum viable version?"
|
|
120
|
+
- "Can we defer Y to a future iteration?"
|
|
121
|
+
- "Would simpler approach Z meet the core need?"
|
|
122
|
+
|
|
123
|
+
**Change Approach:**
|
|
124
|
+
- "What are the pros/cons of approach A vs B?"
|
|
125
|
+
- "Have you considered alternative C?"
|
|
126
|
+
- "What's the trade-off we're trying to optimize?"
|
|
127
|
+
|
|
128
|
+
**Technical Constraints:**
|
|
129
|
+
- "Is performance constraint X realistic?"
|
|
130
|
+
- "Should we use existing component Y instead?"
|
|
131
|
+
- "How will this integrate with system Z?"
|
|
132
|
+
|
|
133
|
+
**Acceptance Criteria:**
|
|
134
|
+
- "How will we verify requirement X is met?"
|
|
135
|
+
- "What does success look like for this feature?"
|
|
136
|
+
- "Are there specific test scenarios?"
|
|
137
|
+
|
|
138
|
+
### Step 6: Iterative Refinement
|
|
139
|
+
|
|
140
|
+
After each round of Q&A:
|
|
141
|
+
1. Summarize what you've learned
|
|
142
|
+
2. Ask: "Would you like to discuss anything else about this feature?"
|
|
143
|
+
3. Provide options:
|
|
144
|
+
- "Yes, discuss another aspect"
|
|
145
|
+
- "Yes, continue this topic"
|
|
146
|
+
- "No, update the spec"
|
|
147
|
+
|
|
148
|
+
Allow multiple rounds of discussion until user is satisfied.
|
|
149
|
+
|
|
150
|
+
### Step 7: Update Feature Specification
|
|
151
|
+
|
|
152
|
+
When user indicates they're done discussing, update `.5/{feature-name}/feature.md`:
|
|
153
|
+
|
|
154
|
+
**Update these sections based on discussion:**
|
|
155
|
+
|
|
156
|
+
1. **Summary** - If core understanding changed
|
|
157
|
+
2. **Problem Statement** - If motivation clarified
|
|
158
|
+
3. **Requirements** - Add/modify/remove based on discussion
|
|
159
|
+
4. **Constraints** - Add new constraints discovered
|
|
160
|
+
5. **Affected Domains** - If scope changed
|
|
161
|
+
6. **Entity/Component Definitions** - If data model changed
|
|
162
|
+
7. **Business Rules** - If logic clarified
|
|
163
|
+
8. **Acceptance Criteria** - Add/refine verification criteria
|
|
164
|
+
9. **Alternatives Considered** - Document discussed alternatives
|
|
165
|
+
10. **Questions & Answers** - Append new Q&A from this session
|
|
166
|
+
|
|
167
|
+
**Preserve existing content** - Only update sections that changed during discussion.
|
|
168
|
+
|
|
169
|
+
**Track changes** - Add a "Discussion History" section if it doesn't exist:
|
|
170
|
+
|
|
171
|
+
```markdown
|
|
172
|
+
## Discussion History
|
|
173
|
+
|
|
174
|
+
### Session 1: {Date} - {Topic}
|
|
175
|
+
**Changes made:**
|
|
176
|
+
- Added requirement: {X}
|
|
177
|
+
- Clarified: {Y}
|
|
178
|
+
- Removed: {Z}
|
|
179
|
+
|
|
180
|
+
**Rationale:** {Why these changes}
|
|
181
|
+
```
|
|
182
|
+
|
|
183
|
+
### Step 8: Inform Developer
|
|
184
|
+
|
|
185
|
+
After updating the spec, tell the developer:
|
|
186
|
+
|
|
187
|
+
1. "Feature specification updated at `.5/{feature-name}/feature.md`"
|
|
188
|
+
2. Summarize key changes:
|
|
189
|
+
- "Added: {X}"
|
|
190
|
+
- "Modified: {Y}"
|
|
191
|
+
- "Removed: {Z}"
|
|
192
|
+
3. Ask: "Would you like to:"
|
|
193
|
+
- "Discuss more (run /discuss-feature again)"
|
|
194
|
+
- "Proceed to implementation planning (run /plan-implementation {feature-name})"
|
|
195
|
+
- "Review the updated spec first"
|
|
196
|
+
|
|
197
|
+
## Instructions Summary
|
|
198
|
+
|
|
199
|
+
1. **Extract feature name** - From user input or by matching ticket ID
|
|
200
|
+
2. **Read feature spec** - Load current state from `.5/{feature-name}/feature.md`
|
|
201
|
+
3. **Ask initial question** - What do they want to discuss?
|
|
202
|
+
4. **Explore if needed** - Understand codebase context
|
|
203
|
+
5. **Interactive Q&A** - Multiple rounds of clarifying questions
|
|
204
|
+
6. **Iterate** - Allow continued discussion
|
|
205
|
+
7. **Update feature spec** - Modify relevant sections
|
|
206
|
+
8. **Track changes** - Document discussion history
|
|
207
|
+
9. **Inform developer** - Summarize changes and next steps
|
|
208
|
+
|
|
209
|
+
## Key Principles
|
|
210
|
+
|
|
211
|
+
1. **User-driven** - Follow user's focus areas, don't prescribe
|
|
212
|
+
2. **Iterative** - Allow multiple discussion rounds
|
|
213
|
+
3. **Contextual** - Explore codebase when relevant
|
|
214
|
+
4. **Challenge constructively** - Question complexity, suggest alternatives
|
|
215
|
+
5. **Document evolution** - Track how requirements changed
|
|
216
|
+
6. **Preserve history** - Keep previous Q&A, add new discussions
|
|
217
|
+
7. **Clear next steps** - Guide user on what to do next
|
|
218
|
+
|
|
219
|
+
## DO NOT in This Skill
|
|
220
|
+
|
|
221
|
+
- DO NOT rewrite the entire feature spec (only update changed sections)
|
|
222
|
+
- DO NOT skip asking what the user wants to discuss
|
|
223
|
+
- DO NOT create new feature specs (use /plan-feature for that)
|
|
224
|
+
- DO NOT proceed to technical planning (that's Phase 2's job)
|
|
225
|
+
- DO NOT start implementation
|
|
226
|
+
- DO NOT delete previous Q&A sections (append to them)
|
|
227
|
+
|
|
228
|
+
## Discussion Patterns
|
|
229
|
+
|
|
230
|
+
### Pattern 1: Scope Reduction
|
|
231
|
+
User: "This is too complex, can we simplify?"
|
|
232
|
+
Skill:
|
|
233
|
+
1. Ask: "What's the minimum viable version?"
|
|
234
|
+
2. Ask: "Which requirements are must-have vs nice-to-have?"
|
|
235
|
+
3. Present options for phased approach
|
|
236
|
+
4. Update spec with reduced scope
|
|
237
|
+
|
|
238
|
+
### Pattern 2: Requirement Addition
|
|
239
|
+
User: "We need to also handle X scenario"
|
|
240
|
+
Skill:
|
|
241
|
+
1. Ask: "How should X scenario work?"
|
|
242
|
+
2. Ask: "How does X interact with existing requirement Y?"
|
|
243
|
+
3. Ask: "Should X be in this feature or separate?"
|
|
244
|
+
4. Update requirements section
|
|
245
|
+
|
|
246
|
+
### Pattern 3: Technical Feasibility
|
|
247
|
+
User: "Can we reuse existing component Z?"
|
|
248
|
+
Skill:
|
|
249
|
+
1. Explore: Find component Z implementation
|
|
250
|
+
2. Ask: "Does Z fully meet the need or need extension?"
|
|
251
|
+
3. Present trade-offs: reuse vs custom
|
|
252
|
+
4. Update affected domains and approach
|
|
253
|
+
|
|
254
|
+
### Pattern 4: Acceptance Criteria
|
|
255
|
+
User: "How do we verify this works?"
|
|
256
|
+
Skill:
|
|
257
|
+
1. Ask: "What's the happy path test?"
|
|
258
|
+
2. Ask: "What edge cases should we test?"
|
|
259
|
+
3. Ask: "What does failure look like?"
|
|
260
|
+
4. Update acceptance criteria section
|
|
261
|
+
|
|
262
|
+
### Pattern 5: Alternative Evaluation
|
|
263
|
+
User: "Should we use approach A or B?"
|
|
264
|
+
Skill:
|
|
265
|
+
1. Ask: "What's the goal: simplicity, performance, flexibility?"
|
|
266
|
+
2. Present pros/cons of each approach
|
|
267
|
+
3. Ask: "What constraints matter most?"
|
|
268
|
+
4. Update alternatives considered section
|
|
269
|
+
|
|
270
|
+
## Example Workflow
|
|
271
|
+
|
|
272
|
+
### Example 1: Scope Clarification
|
|
273
|
+
|
|
274
|
+
```
|
|
275
|
+
User: /discuss-feature PROJ-1234-add-feature
|
|
276
|
+
|
|
277
|
+
Skill: [Reads feature spec]
|
|
278
|
+
Skill: "What would you like to discuss or change about this feature?"
|
|
279
|
+
|
|
280
|
+
User: "Clarify existing requirements"
|
|
281
|
+
|
|
282
|
+
Skill: "The current spec mentions 'emergency schedule window'. Should this support:
|
|
283
|
+
- Single time window per product?
|
|
284
|
+
- Multiple overlapping windows?
|
|
285
|
+
- Recurring schedules?
|
|
286
|
+
What level of complexity do you need?"
|
|
287
|
+
|
|
288
|
+
User: "Just single window per product for now"
|
|
289
|
+
|
|
290
|
+
Skill: "Should we support updating/deleting the window after it's set?"
|
|
291
|
+
|
|
292
|
+
User: "Yes, full CRUD"
|
|
293
|
+
|
|
294
|
+
Skill: "Would you like to discuss anything else about this feature?"
|
|
295
|
+
|
|
296
|
+
User: "No, update the spec"
|
|
297
|
+
|
|
298
|
+
Skill: [Updates Requirements and Acceptance Criteria sections]
|
|
299
|
+
Skill: "Feature specification updated. Changes:
|
|
300
|
+
- Clarified: Single emergency window per product (not multiple)
|
|
301
|
+
- Added: Full CRUD operations for emergency windows
|
|
302
|
+
Would you like to proceed to implementation planning? Run: /plan-implementation PROJ-1234-add-feature"
|
|
303
|
+
```
|
|
304
|
+
|
|
305
|
+
### Example 2: Adding Requirements
|
|
306
|
+
|
|
307
|
+
```
|
|
308
|
+
User: /discuss-feature PROJ-1234
|
|
309
|
+
|
|
310
|
+
Skill: [Finds PROJ-1234-add-feature.md]
|
|
311
|
+
Skill: "What would you like to discuss or change about this feature?"
|
|
312
|
+
|
|
313
|
+
User: "Add new requirements"
|
|
314
|
+
|
|
315
|
+
Skill: "What new requirement would you like to add?"
|
|
316
|
+
|
|
317
|
+
User: "We need to notify customers when emergency schedule is activated"
|
|
318
|
+
|
|
319
|
+
Skill: "How should notifications be delivered?
|
|
320
|
+
- Email only
|
|
321
|
+
- SMS only
|
|
322
|
+
- Both email and SMS
|
|
323
|
+
- Configurable per customer"
|
|
324
|
+
|
|
325
|
+
User: "Email only for now"
|
|
326
|
+
|
|
327
|
+
Skill: "Should notification be:
|
|
328
|
+
- Immediate when emergency schedule is created?
|
|
329
|
+
- When emergency window starts?
|
|
330
|
+
- Both?"
|
|
331
|
+
|
|
332
|
+
User: "When emergency window starts"
|
|
333
|
+
|
|
334
|
+
Skill: "Would you like to discuss anything else?"
|
|
335
|
+
|
|
336
|
+
User: "No, update the spec"
|
|
337
|
+
|
|
338
|
+
Skill: [Updates Requirements, adds email notification requirement]
|
|
339
|
+
Skill: [Updates Affected Domains, adds email service integration]
|
|
340
|
+
Skill: [Updates Acceptance Criteria, adds notification verification]
|
|
341
|
+
Skill: "Feature specification updated. Changes:
|
|
342
|
+
- Added: Email notification when emergency window starts
|
|
343
|
+
- Added: Integration with email service
|
|
344
|
+
Review the changes and run: /plan-implementation 12345-implement-your-new-feature when ready"
|
|
345
|
+
```
|
|
346
|
+
|
|
347
|
+
### Example 3: Simplification
|
|
348
|
+
|
|
349
|
+
```
|
|
350
|
+
User: /discuss-feature PROJ-1234-add-feature
|
|
351
|
+
|
|
352
|
+
Skill: "What would you like to discuss or change about this feature?"
|
|
353
|
+
|
|
354
|
+
User: "Remove or simplify requirements"
|
|
355
|
+
|
|
356
|
+
Skill: "Current requirements include:
|
|
357
|
+
1. Emergency schedule CRUD
|
|
358
|
+
2. Email notifications
|
|
359
|
+
3. Audit logging
|
|
360
|
+
4. Analytics tracking
|
|
361
|
+
Which are critical for MVP?"
|
|
362
|
+
|
|
363
|
+
User: "Just #1 and #3. We can add notifications and analytics later"
|
|
364
|
+
|
|
365
|
+
Skill: "So we'll keep emergency schedule CRUD and audit logging, defer notifications and analytics to future work?"
|
|
366
|
+
|
|
367
|
+
User: "Correct"
|
|
368
|
+
|
|
369
|
+
Skill: [Updates Requirements, moves #2 and #4 to "Future Enhancements" section]
|
|
370
|
+
Skill: [Updates Affected Domains, removes email and analytics integrations]
|
|
371
|
+
Skill: "Feature specification updated. Changes:
|
|
372
|
+
- Removed: Email notifications (moved to future enhancements)
|
|
373
|
+
- Removed: Analytics tracking (moved to future enhancements)
|
|
374
|
+
- Kept: Core CRUD and audit logging
|
|
375
|
+
The simplified scope should reduce implementation complexity significantly."
|
|
376
|
+
```
|
|
377
|
+
|
|
378
|
+
## Tips for Effective Discussion
|
|
379
|
+
|
|
380
|
+
1. **Read the spec first** - Understand current state before asking questions
|
|
381
|
+
2. **Focus on one topic** - Don't try to discuss everything at once
|
|
382
|
+
3. **Ask open questions** - Let user explain their thinking
|
|
383
|
+
4. **Present options** - Give user choices with pros/cons
|
|
384
|
+
5. **Challenge gently** - "Have you considered..." not "You should..."
|
|
385
|
+
6. **Summarize often** - Confirm understanding before moving on
|
|
386
|
+
7. **Track rationale** - Document WHY decisions were made
|
|
387
|
+
8. **Be patient** - Allow multiple rounds until clarity emerges
|
|
388
|
+
|
|
389
|
+
## Related Documentation
|
|
390
|
+
|
|
391
|
+
- [5-Phase Workflow Guide](../docs/workflow-guide.md)
|
|
392
|
+
- [plan-feature command](./plan-feature.md)
|
|
393
|
+
- [plan-implementation command](./plan-implementation.md)
|