@devobsessed/code-captain 0.0.8 → 0.0.9
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 +35 -27
- package/bin/install.js +1165 -978
- package/claude-code/agents/code-captain.md +15 -3
- package/copilot/chatmodes/Code Captain.chatmode.md +30 -9
- package/copilot/prompts/create-adr.prompt.md +6 -4
- package/copilot/prompts/create-spec.prompt.md +60 -40
- package/copilot/prompts/explain-code.prompt.md +7 -20
- package/copilot/prompts/research.prompt.md +14 -27
- package/cursor/README.md +72 -68
- package/cursor/cc.mdc +13 -35
- package/cursor/commands/create-adr.md +6 -12
- package/cursor/commands/create-spec.md +66 -54
- package/cursor/commands/edit-spec.md +2 -15
- package/cursor/commands/execute-task.md +7 -15
- package/cursor/commands/explain-code.md +16 -32
- package/cursor/commands/initialize.md +18 -17
- package/cursor/commands/new-command.md +168 -77
- package/cursor/commands/plan-product.md +7 -13
- package/cursor/commands/research.md +4 -23
- package/cursor/commands/status.md +28 -28
- package/cursor/commands/swab.md +4 -12
- package/manifest.json +104 -207
- package/package.json +2 -3
- package/cursor/cc.md +0 -156
- package/windsurf/README.md +0 -254
- package/windsurf/rules/cc.md +0 -5
- package/windsurf/workflows/create-adr.md +0 -331
- package/windsurf/workflows/create-spec.md +0 -280
- package/windsurf/workflows/edit-spec.md +0 -273
- package/windsurf/workflows/execute-task.md +0 -276
- package/windsurf/workflows/explain-code.md +0 -288
- package/windsurf/workflows/initialize.md +0 -298
- package/windsurf/workflows/new-command.md +0 -321
- package/windsurf/workflows/plan-product.md +0 -330
- package/windsurf/workflows/research.md +0 -240
- package/windsurf/workflows/status.md +0 -213
- package/windsurf/workflows/swab.md +0 -212
|
@@ -1,36 +1,34 @@
|
|
|
1
|
-
# Enhanced Create Spec Command (
|
|
1
|
+
# Enhanced Create Spec Command (create-spec)
|
|
2
2
|
|
|
3
3
|
## Overview
|
|
4
4
|
|
|
5
5
|
Generate comprehensive feature specifications using a contract-first approach that ensures complete alignment between developer and AI before creating any supporting files. This command eliminates presumptuous file creation by establishing a clear "contract" through structured clarification rounds.
|
|
6
6
|
|
|
7
|
-
## Usage
|
|
8
|
-
|
|
9
|
-
```bash
|
|
10
|
-
cc: create-spec "rough feature description"
|
|
11
|
-
```
|
|
12
|
-
|
|
13
7
|
## Command Process
|
|
14
8
|
|
|
15
9
|
### Phase 1: Contract Establishment (No File Creation)
|
|
16
10
|
|
|
17
11
|
**Mission Statement:**
|
|
12
|
+
|
|
18
13
|
> Your goal is to turn my rough feature idea into a very clear work specification. You will deliver the complete spec package only after we both agree on the requirements contract. **Important: Challenge ideas that don't make technical or business sense - it's better to surface concerns early than build the wrong thing.**
|
|
19
14
|
|
|
20
15
|
#### Step 1.1: Initial Context Scan
|
|
16
|
+
|
|
21
17
|
- Scan existing `.code-captain/specs/` for related specifications
|
|
22
18
|
- Analyze current codebase architecture and patterns using `codebase_search`
|
|
23
19
|
- Load project context files (`tech-stack.md`, `code-style.md`, `objective.md`)
|
|
24
20
|
- **Output:** Context summary (no files created yet)
|
|
25
21
|
|
|
26
22
|
#### Step 1.2: Gap Analysis & Silent Enumeration
|
|
23
|
+
|
|
27
24
|
**Internal Process (not shown to user):**
|
|
25
|
+
|
|
28
26
|
- Silently list every missing fact, constraint, or requirement
|
|
29
27
|
- Identify ambiguities in the initial description
|
|
30
28
|
- Note potential integration points and dependencies
|
|
31
29
|
- Catalog unknowns across these domains:
|
|
32
30
|
- Purpose & business value
|
|
33
|
-
- Target audience & user personas
|
|
31
|
+
- Target audience & user personas
|
|
34
32
|
- Technical constraints & requirements
|
|
35
33
|
- Success criteria & acceptance tests
|
|
36
34
|
- Scope boundaries (in/out of scope)
|
|
@@ -41,7 +39,9 @@ cc: create-spec "rough feature description"
|
|
|
41
39
|
- Risk tolerance & implementation approach
|
|
42
40
|
|
|
43
41
|
#### Step 1.3: Structured Clarification Loop
|
|
42
|
+
|
|
44
43
|
**Rules:**
|
|
44
|
+
|
|
45
45
|
- Ask ONE focused question at a time
|
|
46
46
|
- After each answer, re-scan codebase for additional context if relevant
|
|
47
47
|
- Continue until reaching 95% confidence on deliverable
|
|
@@ -51,6 +51,7 @@ cc: create-spec "rough feature description"
|
|
|
51
51
|
- **Challenge ideas that don't make technical or business sense** - better to surface concerns early than build the wrong thing
|
|
52
52
|
|
|
53
53
|
**Critical Analysis Responsibility:**
|
|
54
|
+
|
|
54
55
|
- If requirements seem technically infeasible with current architecture, explain why and suggest alternatives
|
|
55
56
|
- If scope seems too large for a single feature, recommend breaking it down
|
|
56
57
|
- If user requests conflict with existing patterns found in codebase, point out the inconsistency
|
|
@@ -58,40 +59,45 @@ cc: create-spec "rough feature description"
|
|
|
58
59
|
- If performance/security/scalability concerns arise, surface them proactively
|
|
59
60
|
|
|
60
61
|
**Pushback Phrasing Examples:**
|
|
62
|
+
|
|
61
63
|
- "I see a potential issue with [requirement] because [technical reason]. Would [alternative approach] work better?"
|
|
62
64
|
- "Based on your existing codebase, [proposed approach] might conflict with [existing pattern]. How should we handle this?"
|
|
63
65
|
- "The scope you're describing sounds like it might be 3-4 separate features. Should we focus on [core piece] first?"
|
|
64
66
|
- "I'm concerned that [requirement] could create [specific problem]. Have you considered [alternative]?"
|
|
65
67
|
|
|
66
68
|
**Question Categories (examples):**
|
|
69
|
+
|
|
67
70
|
- "What specific user problem does this solve, and who experiences it?"
|
|
68
|
-
- "Should this integrate with [existing system found in codebase], or remain separate?"
|
|
71
|
+
- "Should this integrate with [existing system found in codebase], or remain separate?"
|
|
69
72
|
- "What does 'success' look like - how will we measure if this works?"
|
|
70
73
|
- "Are there performance requirements (response time, throughput, scale)?"
|
|
71
74
|
- "What UI/UX constraints exist - web only, mobile responsive, accessibility needs?"
|
|
72
75
|
- "What's your risk tolerance - prefer stable/proven approaches or cutting-edge solutions?"
|
|
73
76
|
|
|
74
77
|
**Transition to Contract:**
|
|
78
|
+
|
|
75
79
|
- When confidence is high, present contract without declaring it "final"
|
|
76
80
|
- Use phrases like "I think I have enough to create a solid contract" or "Based on our discussion, here's what I understand"
|
|
77
81
|
- Always leave room for more questions if needed
|
|
78
82
|
|
|
79
83
|
#### Step 1.4: Echo Check (Contract Proposal)
|
|
84
|
+
|
|
80
85
|
When confident, present a contract proposal with any concerns surfaced:
|
|
81
86
|
|
|
82
87
|
**Format:**
|
|
88
|
+
|
|
83
89
|
```
|
|
84
90
|
## Specification Contract
|
|
85
91
|
|
|
86
92
|
**Deliverable:** [One clear sentence describing what will be built]
|
|
87
93
|
|
|
88
|
-
**Must Include:** [Critical requirement that makes this valuable]
|
|
94
|
+
**Must Include:** [Critical requirement that makes this valuable]
|
|
89
95
|
|
|
90
96
|
**Hardest Constraint:** [Biggest technical/business limitation to navigate]
|
|
91
97
|
|
|
92
98
|
**Success Criteria:** [How we'll know it's working correctly]
|
|
93
99
|
|
|
94
|
-
**Scope Boundaries:**
|
|
100
|
+
**Scope Boundaries:**
|
|
95
101
|
- Included: [2-3 key features]
|
|
96
102
|
- Excluded: [2-3 things we won't build]
|
|
97
103
|
|
|
@@ -106,7 +112,7 @@ When confident, present a contract proposal with any concerns surfaced:
|
|
|
106
112
|
---
|
|
107
113
|
Options:
|
|
108
114
|
- Type 'yes' to lock this contract and create the spec package
|
|
109
|
-
- Type 'edit: [your changes]' to modify the contract
|
|
115
|
+
- Type 'edit: [your changes]' to modify the contract
|
|
110
116
|
- Type 'risks' to explore potential implementation risks in detail
|
|
111
117
|
- Type 'blueprint' to see the planned folder structure and documents
|
|
112
118
|
- Ask more questions if anything needs clarification
|
|
@@ -117,46 +123,32 @@ Options:
|
|
|
117
123
|
**Triggered only after user confirms contract with 'yes'**
|
|
118
124
|
|
|
119
125
|
#### Step 2.1: Initialize Tracking
|
|
126
|
+
|
|
120
127
|
```bash
|
|
121
128
|
# Use todo_write to track creation process
|
|
122
|
-
1.
|
|
123
|
-
2.
|
|
124
|
-
3.
|
|
125
|
-
4.
|
|
126
|
-
5.
|
|
127
|
-
6.
|
|
128
|
-
7. Present package for user review and validation
|
|
129
|
+
1. Get current date and create spec folder structure
|
|
130
|
+
2. Generate core specification document
|
|
131
|
+
3. Create user stories with acceptance criteria
|
|
132
|
+
4. Generate technical sub-specifications
|
|
133
|
+
5. Create implementation task breakdown
|
|
134
|
+
6. Present package for user review and validation
|
|
129
135
|
```
|
|
130
136
|
|
|
131
137
|
#### Step 2.2: Determine Current Date
|
|
132
|
-
**Objective:** Get current date for folder naming and document timestamps
|
|
133
|
-
|
|
134
|
-
**Date Determination Process:**
|
|
135
|
-
|
|
136
|
-
1. Read the current UTC date from the system clock and format as `YYYY-MM-DD`.
|
|
137
|
-
2. Store it for naming:
|
|
138
|
-
`.code-captain/specs/[DATE]-[feature-name]/`
|
|
139
138
|
|
|
140
|
-
|
|
141
|
-
1. **STATE**: "I need to confirm today's date for the specification folder"
|
|
142
|
-
2. **ASK**: "What is today's date? (YYYY-MM-DD format)"
|
|
143
|
-
3. **WAIT** for user response
|
|
144
|
-
4. **VALIDATE** format matches `^\d{4}-\d{2}-\d{2}$`
|
|
145
|
-
- year: 2024-2030
|
|
146
|
-
- month: 01-12
|
|
147
|
-
- day: 01-31
|
|
148
|
-
5. **STORE** date for folder naming
|
|
139
|
+
Get current date by running: `npx @devobsessed/code-captain date`
|
|
149
140
|
|
|
150
|
-
|
|
151
|
-
-
|
|
152
|
-
- **IF** both_methods_fail: ERROR "Unable to determine current date"
|
|
141
|
+
This returns the current date in `YYYY-MM-DD` format for folder naming:
|
|
142
|
+
`.code-captain/specs/[DATE]-[feature-name]/`
|
|
153
143
|
|
|
154
144
|
#### Step 2.3: Create Directory Structure
|
|
145
|
+
|
|
155
146
|
**Generated folder (using determined date):**
|
|
147
|
+
|
|
156
148
|
```
|
|
157
149
|
.code-captain/specs/[DATE]-{feature-name}/
|
|
158
150
|
├── spec.md # Main specification (from contract)
|
|
159
|
-
├── spec-lite.md # Condensed version for AI context
|
|
151
|
+
├── spec-lite.md # Condensed version for AI context
|
|
160
152
|
├── user-stories/ # Individual user story files
|
|
161
153
|
│ ├── README.md # Overview and progress tracking
|
|
162
154
|
│ ├── story-1-{name}.md # Individual user story with focused tasks
|
|
@@ -166,12 +158,13 @@ Options:
|
|
|
166
158
|
├── technical-spec.md # Architecture & implementation details
|
|
167
159
|
├── database-schema.md # Database changes (if needed)
|
|
168
160
|
├── api-spec.md # API documentation (if needed)
|
|
169
|
-
└── ui-wireframes.md # UI/UX specifications (if needed)
|
|
161
|
+
└── ui-wireframes.md # UI/UX specifications (if needed)
|
|
170
162
|
```
|
|
171
163
|
|
|
172
164
|
#### Step 2.4: Generate Core Documents
|
|
173
165
|
|
|
174
166
|
**spec.md** - Built directly from the locked contract:
|
|
167
|
+
|
|
175
168
|
```markdown
|
|
176
169
|
# [Feature Name] Specification
|
|
177
170
|
|
|
@@ -180,46 +173,51 @@ Options:
|
|
|
180
173
|
> Contract Locked: ✅
|
|
181
174
|
|
|
182
175
|
## Contract Summary
|
|
176
|
+
|
|
183
177
|
[Echo check content verbatim]
|
|
184
178
|
|
|
185
179
|
## Detailed Requirements
|
|
180
|
+
|
|
186
181
|
[Expanded from clarification responses]
|
|
187
182
|
|
|
188
183
|
## Implementation Approach
|
|
184
|
+
|
|
189
185
|
[Technical strategy based on codebase analysis]
|
|
190
186
|
```
|
|
191
187
|
|
|
192
188
|
**user-stories/ folder structure** - Individual user story files for better organization:
|
|
193
189
|
|
|
194
190
|
**user-stories/README.md** - Overview and progress tracking:
|
|
191
|
+
|
|
195
192
|
```markdown
|
|
196
193
|
# User Stories Overview
|
|
197
194
|
|
|
198
|
-
> **Specification:** [Feature Name]
|
|
199
|
-
> **Created:** [DATE]
|
|
200
|
-
> **Status:** Planning
|
|
195
|
+
> **Specification:** [Feature Name] > **Created:** [DATE] > **Status:** Planning
|
|
201
196
|
|
|
202
197
|
## Stories Summary
|
|
203
198
|
|
|
204
|
-
| Story | Title
|
|
205
|
-
|
|
206
|
-
| 1
|
|
207
|
-
| 2
|
|
208
|
-
| 3
|
|
199
|
+
| Story | Title | Status | Tasks | Progress |
|
|
200
|
+
| ----- | ------------- | ----------- | ----- | -------- |
|
|
201
|
+
| 1 | [Story title] | Not Started | 5 | 0/5 |
|
|
202
|
+
| 2 | [Story title] | Not Started | 4 | 0/4 |
|
|
203
|
+
| 3 | [Story title] | Not Started | 6 | 0/6 |
|
|
209
204
|
|
|
210
205
|
**Total Progress:** 0/15 tasks (0%)
|
|
211
206
|
|
|
212
207
|
## Story Dependencies
|
|
208
|
+
|
|
213
209
|
- Story 2 depends on Story 1 completion
|
|
214
210
|
- Story 3 can run parallel to Story 2
|
|
215
211
|
|
|
216
212
|
## Quick Links
|
|
213
|
+
|
|
217
214
|
- [Story 1: User Login](./story-1-user-login.md)
|
|
218
215
|
- [Story 2: Password Reset](./story-2-password-reset.md)
|
|
219
216
|
- [Story 3: Profile Management](./story-3-profile-management.md)
|
|
220
217
|
```
|
|
221
218
|
|
|
222
219
|
**user-stories/story-1-{name}.md** - Individual story files (max 5-7 tasks each):
|
|
220
|
+
|
|
223
221
|
```markdown
|
|
224
222
|
# Story 1: [Title from contract deliverable]
|
|
225
223
|
|
|
@@ -228,27 +226,32 @@ Options:
|
|
|
228
226
|
> **Dependencies:** None
|
|
229
227
|
|
|
230
228
|
## User Story
|
|
229
|
+
|
|
231
230
|
**As a** [user type from clarification]
|
|
232
231
|
**I want to** [action from contract]
|
|
233
232
|
**So that** [value from contract must-include]
|
|
234
233
|
|
|
235
234
|
## Acceptance Criteria
|
|
235
|
+
|
|
236
236
|
- [ ] Given [context], when [action], then [outcome]
|
|
237
237
|
- [ ] Given [context], when [action], then [outcome]
|
|
238
238
|
- [ ] Given [context], when [action], then [outcome]
|
|
239
239
|
|
|
240
240
|
## Implementation Tasks
|
|
241
|
+
|
|
241
242
|
- [ ] 1.1 Write tests for [specific component]
|
|
242
243
|
- [ ] 1.2 [Focused technical step]
|
|
243
|
-
- [ ] 1.3 [Focused technical step]
|
|
244
|
+
- [ ] 1.3 [Focused technical step]
|
|
244
245
|
- [ ] 1.4 [Focused technical step]
|
|
245
246
|
- [ ] 1.5 Verify acceptance criteria are met
|
|
246
247
|
- [ ] 1.6 Verify all tests pass
|
|
247
248
|
|
|
248
249
|
## Notes
|
|
250
|
+
|
|
249
251
|
[Any specific technical considerations, risks, or dependencies for this story]
|
|
250
252
|
|
|
251
253
|
## Definition of Done
|
|
254
|
+
|
|
252
255
|
- [ ] All tasks completed
|
|
253
256
|
- [ ] All acceptance criteria met
|
|
254
257
|
- [ ] Tests passing
|
|
@@ -272,6 +275,7 @@ Options:
|
|
|
272
275
|
**user-stories/ folder** - Organized individual story files with focused task groups:
|
|
273
276
|
|
|
274
277
|
**Structure Philosophy:**
|
|
278
|
+
|
|
275
279
|
- Each user story gets its own file for better organization
|
|
276
280
|
- Implementation tasks are kept small and focused (max 5-7 per story)
|
|
277
281
|
- Complex stories are broken into multiple smaller stories
|
|
@@ -280,6 +284,7 @@ Options:
|
|
|
280
284
|
- Each story follows TDD: test → implement → verify acceptance criteria
|
|
281
285
|
|
|
282
286
|
**Benefits of Folder Structure:**
|
|
287
|
+
|
|
283
288
|
- **Manageability**: Each file stays focused and readable
|
|
284
289
|
- **Navigation**: Easy to find and work on specific stories
|
|
285
290
|
- **Parallel Work**: Multiple developers can work on different stories
|
|
@@ -288,12 +293,14 @@ Options:
|
|
|
288
293
|
- **Traceability**: Every technical task traces to user value
|
|
289
294
|
|
|
290
295
|
**File Organization:**
|
|
296
|
+
|
|
291
297
|
- **README.md**: Overview, progress summary, dependencies
|
|
292
298
|
- **story-N-{name}.md**: Individual stories with focused tasks (5-7 tasks max)
|
|
293
299
|
- **Story Naming**: Clear, descriptive names for easy identification
|
|
294
300
|
- **Task Numbering**: N.1, N.2, N.3... within each story file
|
|
295
301
|
|
|
296
302
|
**Task Breakdown Strategy:**
|
|
303
|
+
|
|
297
304
|
- If a story would have >7 tasks, split into multiple stories
|
|
298
305
|
- Each story should deliver standalone user value
|
|
299
306
|
- Tasks within a story should be cohesive and related
|
|
@@ -303,12 +310,13 @@ Options:
|
|
|
303
310
|
#### Step 2.7: Final Package Review & User Validation
|
|
304
311
|
|
|
305
312
|
Present complete package with file references:
|
|
313
|
+
|
|
306
314
|
```
|
|
307
315
|
✅ Specification package created successfully!
|
|
308
316
|
|
|
309
317
|
📁 .code-captain/specs/[DATE]-feature-name/
|
|
310
318
|
├── 📋 spec.md - Main specification document
|
|
311
|
-
├── 📝 spec-lite.md - AI context summary
|
|
319
|
+
├── 📝 spec-lite.md - AI context summary
|
|
312
320
|
├── 👥 user-stories/ - Individual user story files
|
|
313
321
|
│ ├── 📊 README.md - Overview and progress tracking
|
|
314
322
|
│ ├── 📝 story-1-{name}.md - Focused story with 5-7 tasks
|
|
@@ -345,22 +353,26 @@ Once you're satisfied with the specification, I can help you start implementatio
|
|
|
345
353
|
## Key Improvements Over Original
|
|
346
354
|
|
|
347
355
|
### 1. Contract-First Approach
|
|
356
|
+
|
|
348
357
|
- **No presumptuous file creation** - Nothing gets built until contract is locked
|
|
349
358
|
- **Structured clarification** - One question at a time, building understanding
|
|
350
359
|
- **Echo check validation** - Clear contract summary before proceeding
|
|
351
360
|
|
|
352
|
-
### 2. Codebase-Aware Questioning
|
|
361
|
+
### 2. Codebase-Aware Questioning
|
|
362
|
+
|
|
353
363
|
- **Context scanning between questions** - Each answer triggers fresh codebase analysis
|
|
354
364
|
- **Integration-focused queries** - Questions shaped by what exists in the codebase
|
|
355
365
|
- **Architecture consistency** - Recommendations align with existing patterns
|
|
356
366
|
|
|
357
367
|
### 3. User Control & Transparency
|
|
368
|
+
|
|
358
369
|
- **Clear decision points** - User explicitly approves before file creation
|
|
359
|
-
- **Risk assessment option** - Can explore implementation risks before committing
|
|
370
|
+
- **Risk assessment option** - Can explore implementation risks before committing
|
|
360
371
|
- **Blueprint preview** - Can see planned structure before creation
|
|
361
372
|
- **Edit capability** - Can modify contract before locking
|
|
362
373
|
|
|
363
374
|
### 4. Efficient Clarification Process
|
|
375
|
+
|
|
364
376
|
- **Gap enumeration** - Systematically identifies all unknowns
|
|
365
377
|
- **95% confidence threshold** - Stops asking when ready to deliver
|
|
366
378
|
- **Token efficiency** - Focused questions, no verbose explanations during clarification
|
|
@@ -368,7 +380,7 @@ Once you're satisfied with the specification, I can help you start implementatio
|
|
|
368
380
|
## Example Usage Flow
|
|
369
381
|
|
|
370
382
|
```
|
|
371
|
-
Developer:
|
|
383
|
+
Developer: /create-spec "real-time multiplayer chat with blockchain integration"
|
|
372
384
|
|
|
373
385
|
Agent: I'm ready to help you create a comprehensive specification.
|
|
374
386
|
|
|
@@ -382,7 +394,7 @@ First question: You mentioned "real-time multiplayer chat with blockchain integr
|
|
|
382
394
|
|
|
383
395
|
Developer: I want messages to be permanently stored and verifiable, plus users should pay crypto to send messages to prevent spam
|
|
384
396
|
|
|
385
|
-
Agent: I understand the anti-spam goal, but I'm concerned about the user experience. If users have to wait 30+ seconds for transaction confirmation before each message appears, that breaks the "real-time" chat experience.
|
|
397
|
+
Agent: I understand the anti-spam goal, but I'm concerned about the user experience. If users have to wait 30+ seconds for transaction confirmation before each message appears, that breaks the "real-time" chat experience.
|
|
386
398
|
|
|
387
399
|
Would a hybrid approach work better - immediate message delivery with blockchain settlement in the background? Or are you thinking of a different model where users pre-purchase message credits?
|
|
388
400
|
|
|
@@ -1,22 +1,9 @@
|
|
|
1
|
-
# Enhanced Edit Spec Command (
|
|
1
|
+
# Enhanced Edit Spec Command (edit-spec)
|
|
2
2
|
|
|
3
3
|
## Overview
|
|
4
4
|
|
|
5
5
|
Modify existing feature specifications using a contract-first approach that ensures complete alignment between developer and AI before updating any supporting files. This command prevents assumptions by establishing a clear "modification contract" through structured clarification rounds.
|
|
6
6
|
|
|
7
|
-
## Usage
|
|
8
|
-
|
|
9
|
-
```bash
|
|
10
|
-
cc: edit-spec [spec-identifier] "proposed changes description"
|
|
11
|
-
```
|
|
12
|
-
|
|
13
|
-
**Examples:**
|
|
14
|
-
```bash
|
|
15
|
-
cc: edit-spec "user-authentication" "add social login options"
|
|
16
|
-
cc: edit-spec "2024-01-15-payment-gateway" "change from Stripe to PayPal"
|
|
17
|
-
cc: edit-spec "latest" "remove the mobile app requirement"
|
|
18
|
-
```
|
|
19
|
-
|
|
20
7
|
## Command Process
|
|
21
8
|
|
|
22
9
|
### Phase 1: Specification Loading & Change Contract (No File Modifications)
|
|
@@ -338,7 +325,7 @@ The original version is safely backed up in the backups folder. If you need to r
|
|
|
338
325
|
## Example Usage Flow
|
|
339
326
|
|
|
340
327
|
```
|
|
341
|
-
Developer:
|
|
328
|
+
Developer: /edit-spec "user-auth" "add biometric authentication"
|
|
342
329
|
|
|
343
330
|
Agent: I found your user authentication specification from 2024-01-15. Let me load the current state...
|
|
344
331
|
|
|
@@ -1,17 +1,9 @@
|
|
|
1
|
-
# Execute Task Command (
|
|
1
|
+
# Execute Task Command (execute-task)
|
|
2
2
|
|
|
3
3
|
## Overview
|
|
4
4
|
|
|
5
5
|
Execute a specific task and its sub-tasks systematically following a Test-Driven Development (TDD) workflow. This command reads task specifications from `.code-captain/specs/` directories and implements features with comprehensive testing, following established code standards and best practices.
|
|
6
6
|
|
|
7
|
-
## Usage
|
|
8
|
-
|
|
9
|
-
```bash
|
|
10
|
-
cc: execute-task
|
|
11
|
-
```
|
|
12
|
-
|
|
13
|
-
**Note:** This command automatically detects and lists available task specifications for selection, or executes a specific task if context is clear.
|
|
14
|
-
|
|
15
7
|
## CRITICAL REQUIREMENT: 100% Test Pass Rate
|
|
16
8
|
|
|
17
9
|
**⚠️ ZERO TOLERANCE FOR FAILING TESTS ⚠️**
|
|
@@ -77,7 +69,7 @@ Use `todo_write` to track the execution process:
|
|
|
77
69
|
1. **If multiple specs exist**: Present selection menu with spec dates and story summaries
|
|
78
70
|
2. **If single spec exists**: Show available stories and their tasks within that specification
|
|
79
71
|
3. **If story/task specified**: Validate story exists and select specific task for execution
|
|
80
|
-
4. **If no specs exist**: Guide user to run
|
|
72
|
+
4. **If no specs exist**: Guide user to run `/create-spec` first
|
|
81
73
|
|
|
82
74
|
**Selection format:**
|
|
83
75
|
```
|
|
@@ -417,7 +409,7 @@ REQUIRED ACTIONS:
|
|
|
417
409
|
|
|
418
410
|
**Specification dependency:**
|
|
419
411
|
|
|
420
|
-
- Requires existing spec created by
|
|
412
|
+
- Requires existing spec created by `/create-spec`
|
|
421
413
|
- Uses story breakdown from `user-stories/` folder in spec directories
|
|
422
414
|
- Loads individual story files: `user-stories/story-N-{name}.md`
|
|
423
415
|
- Tracks progress in `user-stories/README.md`
|
|
@@ -431,8 +423,8 @@ REQUIRED ACTIONS:
|
|
|
431
423
|
|
|
432
424
|
**Cross-command integration:**
|
|
433
425
|
|
|
434
|
-
- Complements
|
|
435
|
-
- Can trigger
|
|
426
|
+
- Complements `/create-spec` for complete development workflow
|
|
427
|
+
- Can trigger `/research` if unknown technologies encountered
|
|
436
428
|
- Integrates with testing and validation workflows
|
|
437
429
|
|
|
438
430
|
## Quality Standards
|
|
@@ -464,7 +456,7 @@ REQUIRED ACTIONS:
|
|
|
464
456
|
|
|
465
457
|
**Common failure scenarios:**
|
|
466
458
|
|
|
467
|
-
- **No specifications found**: Guide to
|
|
459
|
+
- **No specifications found**: Guide to `/create-spec`
|
|
468
460
|
- **Test framework issues**: Provide setup guidance
|
|
469
461
|
- **Implementation conflicts**: Suggest conflict resolution
|
|
470
462
|
- **Performance issues**: Recommend optimization approaches
|
|
@@ -482,7 +474,7 @@ Update story status and notes section to document the blocking issue.
|
|
|
482
474
|
**Resolution strategies:**
|
|
483
475
|
|
|
484
476
|
1. Try alternative implementation approach
|
|
485
|
-
2. Research solution using
|
|
477
|
+
2. Research solution using `/research`
|
|
486
478
|
3. Break down task into smaller components
|
|
487
479
|
4. Maximum 3 attempts before escalating or documenting as blocked
|
|
488
480
|
|
|
@@ -7,7 +7,7 @@ The `explain-code` command provides comprehensive, AI-powered explanations of co
|
|
|
7
7
|
## Command Syntax
|
|
8
8
|
|
|
9
9
|
```bash
|
|
10
|
-
|
|
10
|
+
/explain-code [target]
|
|
11
11
|
```
|
|
12
12
|
|
|
13
13
|
## Parameters
|
|
@@ -31,19 +31,19 @@ The command automatically:
|
|
|
31
31
|
|
|
32
32
|
```bash
|
|
33
33
|
# Explain a specific function
|
|
34
|
-
|
|
34
|
+
/explain-code calculateUserDiscount
|
|
35
35
|
|
|
36
36
|
# Explain a class
|
|
37
|
-
|
|
37
|
+
/explain-code PaymentProcessor
|
|
38
38
|
|
|
39
39
|
# Explain entire file
|
|
40
|
-
|
|
40
|
+
/explain-code src/auth/AuthService.js
|
|
41
41
|
|
|
42
42
|
# Explain specific line range
|
|
43
|
-
|
|
43
|
+
/explain-code "src/utils/helpers.js:45-78"
|
|
44
44
|
|
|
45
45
|
# Explain currently selected code in IDE
|
|
46
|
-
|
|
46
|
+
/explain-code current-selection
|
|
47
47
|
```
|
|
48
48
|
|
|
49
49
|
## Output Structure
|
|
@@ -139,36 +139,20 @@ Files are named using the format: `[DATE]-[target-name].md` where DATE is YYYY-M
|
|
|
139
139
|
|
|
140
140
|
## Auto-Save Behavior
|
|
141
141
|
|
|
142
|
-
All explanations are automatically saved to `.code-captain/explanations/` using the format `[DATE]-[target-name].md`.
|
|
142
|
+
All explanations are automatically saved to `.code-captain/explanations/` using the format `[DATE]-[target-name].md`.
|
|
143
143
|
|
|
144
|
-
|
|
144
|
+
Get current date by running: `npx @devobsessed/code-captain date`
|
|
145
145
|
|
|
146
|
-
|
|
147
|
-
|
|
148
|
-
1. Read the current UTC date from the system clock and format as `YYYY-MM-DD`.
|
|
149
|
-
2. Store it for naming:
|
|
150
|
-
`.code-captain/explanations/[DATE]-[target-name].md`
|
|
151
|
-
|
|
152
|
-
### Fallback Method: User Confirmation
|
|
153
|
-
|
|
154
|
-
If system clock access isn't available:
|
|
155
|
-
|
|
156
|
-
1. **STATE**: "I need to confirm today's date for the explanation file"
|
|
157
|
-
2. **ASK**: "What is today's date? (YYYY-MM-DD format)"
|
|
158
|
-
3. **WAIT** for user response
|
|
159
|
-
4. **VALIDATE** format matches `^\d{4}-\d{2}-\d{2}$`
|
|
160
|
-
5. **STORE** date for file naming
|
|
161
|
-
|
|
162
|
-
**Example filename:** `.code-captain/explanations/2024-01-15-AuthenticationFlow.md`
|
|
146
|
+
**Example filename:** `.code-captain/explanations/2025-09-27-AuthenticationFlow.md`
|
|
163
147
|
|
|
164
148
|
## Integration Points
|
|
165
149
|
|
|
166
150
|
### With Other Commands
|
|
167
151
|
```bash
|
|
168
152
|
# Saved explanations can be referenced by other commands
|
|
169
|
-
|
|
170
|
-
|
|
171
|
-
|
|
153
|
+
/research authentication
|
|
154
|
+
/create-spec payment-processing
|
|
155
|
+
/execute-task "optimize the user search"
|
|
172
156
|
|
|
173
157
|
# AI can access saved explanations from .code-captain/explanations/
|
|
174
158
|
# to provide better context for other commands
|
|
@@ -184,16 +168,16 @@ cc: execute-task "optimize the user search"
|
|
|
184
168
|
|
|
185
169
|
```bash
|
|
186
170
|
# List all saved explanations
|
|
187
|
-
|
|
171
|
+
/list-explanations
|
|
188
172
|
|
|
189
173
|
# Search explanations
|
|
190
|
-
|
|
174
|
+
/search-explanations "authentication"
|
|
191
175
|
|
|
192
176
|
# Show explanation history
|
|
193
|
-
|
|
177
|
+
/explanation-history calculateDiscount
|
|
194
178
|
|
|
195
179
|
# Update outdated explanations when code changes
|
|
196
|
-
|
|
180
|
+
/refresh-explanations --check-code-changes
|
|
197
181
|
```
|
|
198
182
|
|
|
199
183
|
## Diagram Types Generated
|
|
@@ -109,21 +109,21 @@ After technical foundation is complete, provide clear next steps:
|
|
|
109
109
|
|
|
110
110
|
Your development environment is now set up and documented:
|
|
111
111
|
- Technology stack documented and configured
|
|
112
|
-
- Development tools and standards established
|
|
112
|
+
- Development tools and standards established
|
|
113
113
|
- Project structure and configuration ready
|
|
114
114
|
|
|
115
115
|
## Recommended Next Steps:
|
|
116
116
|
|
|
117
117
|
### For New Products:
|
|
118
|
-
|
|
118
|
+
/plan-product "your product idea" - Define product vision, strategy, and roadmap
|
|
119
119
|
|
|
120
120
|
### For Existing Products:
|
|
121
|
-
|
|
122
|
-
|
|
121
|
+
/create-spec "feature description" - Create detailed feature specifications
|
|
122
|
+
/execute-task - Implement features with TDD workflow
|
|
123
123
|
|
|
124
124
|
### For Research:
|
|
125
|
-
|
|
126
|
-
|
|
125
|
+
/research "topic" - Conduct systematic technical research
|
|
126
|
+
/create-adr "decision" - Document architectural decisions
|
|
127
127
|
|
|
128
128
|
Ready to define your product strategy and start building!
|
|
129
129
|
```
|
|
@@ -262,15 +262,15 @@ Your existing project has been analyzed and documented:
|
|
|
262
262
|
## Recommended Next Steps:
|
|
263
263
|
|
|
264
264
|
### For Product Strategy (Recommended First):
|
|
265
|
-
|
|
265
|
+
/plan-product "enhanced product vision" - Define product strategy and roadmap
|
|
266
266
|
|
|
267
267
|
### For Feature Development:
|
|
268
|
-
|
|
269
|
-
|
|
268
|
+
/create-spec "feature description" - Create detailed feature specifications
|
|
269
|
+
/execute-task - Implement features following established patterns
|
|
270
270
|
|
|
271
271
|
### For Technical Improvements:
|
|
272
|
-
|
|
273
|
-
|
|
272
|
+
/research "technical topic" - Research solutions for identified gaps
|
|
273
|
+
/create-adr "technical decision" - Document architectural improvements
|
|
274
274
|
|
|
275
275
|
Ready to define your product strategy and enhance your codebase!
|
|
276
276
|
```
|
|
@@ -284,26 +284,27 @@ Ready to define your product strategy and enhance your codebase!
|
|
|
284
284
|
**MANDATORY**: The initialize command MUST end with a message that prominently recommends `plan-product` as the next logical step for both greenfield and brownfield projects. This is required because:
|
|
285
285
|
|
|
286
286
|
1. Initialize handles ONLY technical foundation
|
|
287
|
-
2. plan-product handles product strategy and vision
|
|
287
|
+
2. plan-product handles product strategy and vision
|
|
288
288
|
3. Users need both for complete project setup
|
|
289
289
|
4. plan-product should be the next step before feature development
|
|
290
290
|
|
|
291
291
|
**Required message format**:
|
|
292
|
+
|
|
292
293
|
```
|
|
293
294
|
🚀 Technical Foundation Complete! / 🔍 Technical Foundation Analysis Complete!
|
|
294
295
|
|
|
295
296
|
## Recommended Next Steps:
|
|
296
297
|
|
|
297
298
|
### For Product Strategy (Recommended First):
|
|
298
|
-
|
|
299
|
+
/plan-product "your product idea/vision" - Define product strategy and roadmap
|
|
299
300
|
|
|
300
301
|
### For Feature Development:
|
|
301
|
-
|
|
302
|
-
|
|
302
|
+
/create-spec "feature description" - Create detailed feature specifications
|
|
303
|
+
/execute-task - Implement features
|
|
303
304
|
|
|
304
305
|
### For Technical Improvements:
|
|
305
|
-
|
|
306
|
-
|
|
306
|
+
/research "topic" - Research solutions for gaps
|
|
307
|
+
/create-adr "decision" - Document architectural decisions
|
|
307
308
|
```
|
|
308
309
|
|
|
309
310
|
---
|