specweave 1.0.33 → 1.0.34
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/CLAUDE.md +179 -0
- package/dist/src/cli/helpers/init/initial-increment-generator.d.ts.map +1 -1
- package/dist/src/cli/helpers/init/initial-increment-generator.js +12 -10
- package/dist/src/cli/helpers/init/initial-increment-generator.js.map +1 -1
- package/package.json +1 -1
- package/plugins/specweave/skills/increment-planner/SKILL.md +75 -63
package/CLAUDE.md
CHANGED
|
@@ -1,3 +1,181 @@
|
|
|
1
|
+
<!-- SW:META template="claude" version="1.0.33" sections="header,start,autodetect,metarule,rules,workflow,structure,taskformat,secrets,syncing,mapping,testing,limits,troubleshooting,principles,linking,docs" -->
|
|
2
|
+
|
|
3
|
+
<!-- SW:SECTION:header version="1.0.33" -->
|
|
4
|
+
**Framework**: SpecWeave | **Truth**: `spec.md` + `tasks.md`
|
|
5
|
+
<!-- SW:END:header -->
|
|
6
|
+
|
|
7
|
+
<!-- SW:SECTION:start version="1.0.33" -->
|
|
8
|
+
## Getting Started
|
|
9
|
+
|
|
10
|
+
**Initial increment**: `0001-project-setup` (auto-created by `specweave init`)
|
|
11
|
+
|
|
12
|
+
**Options**:
|
|
13
|
+
1. **Start fresh**: `rm -rf .specweave/increments/0001-project-setup` → `/sw:increment "your-feature"`
|
|
14
|
+
2. **Customize**: Edit spec.md and use for setup tasks
|
|
15
|
+
<!-- SW:END:start -->
|
|
16
|
+
|
|
17
|
+
<!-- SW:SECTION:autodetect version="1.0.33" -->
|
|
18
|
+
## Auto-Detection
|
|
19
|
+
|
|
20
|
+
SpecWeave auto-detects product descriptions and routes to `/sw:increment`:
|
|
21
|
+
|
|
22
|
+
**Signals** (5+ = auto-route): Project name | Features list (3+) | Tech stack | Timeline/MVP | Problem statement | Business model
|
|
23
|
+
|
|
24
|
+
**Opt-out phrases**: "Just brainstorm first" | "Don't plan yet" | "Quick discussion" | "Let's explore ideas"
|
|
25
|
+
<!-- SW:END:autodetect -->
|
|
26
|
+
|
|
27
|
+
<!-- SW:SECTION:metarule version="1.0.33" -->
|
|
28
|
+
## Meta-Rule: Think-Before-Act
|
|
29
|
+
|
|
30
|
+
**Satisfy dependencies BEFORE dependent operations.**
|
|
31
|
+
|
|
32
|
+
```
|
|
33
|
+
❌ node script.js → Error → npm run build
|
|
34
|
+
✅ npm run build → node script.js → Success
|
|
35
|
+
```
|
|
36
|
+
<!-- SW:END:metarule -->
|
|
37
|
+
|
|
38
|
+
<!-- SW:SECTION:rules version="1.0.33" -->
|
|
39
|
+
## Rules
|
|
40
|
+
|
|
41
|
+
1. **Files** → `.specweave/increments/####-name/` (spec.md, plan.md, tasks.md at root; reports/, scripts/, logs/ subfolders)
|
|
42
|
+
2. **Update immediately**: `Edit("tasks.md", "[ ] pending", "[x] completed")` + `Edit("spec.md", "[ ] AC-", "[x] AC-")`
|
|
43
|
+
3. **Unique IDs**: Check `ls .specweave/increments/ | grep "^[0-9]" | tail -5`
|
|
44
|
+
4. **Emergency**: "emergency mode" → 1 edit, 50 lines max, no agents
|
|
45
|
+
5. **Root clean**: NEVER create .md/reports/scripts in project root → use increment folders
|
|
46
|
+
<!-- SW:END:rules -->
|
|
47
|
+
|
|
48
|
+
<!-- SW:SECTION:workflow version="1.0.33" -->
|
|
49
|
+
## Workflow
|
|
50
|
+
|
|
51
|
+
`/sw:increment "X"` → `/sw:do` → `/sw:progress` → `/sw:done 0001`
|
|
52
|
+
|
|
53
|
+
| Cmd | Action |
|
|
54
|
+
|-----|--------|
|
|
55
|
+
| `/sw:increment` | Plan feature |
|
|
56
|
+
| `/sw:do` | Execute |
|
|
57
|
+
| `/sw:validate` | Quality check |
|
|
58
|
+
| `/sw:done` | Close |
|
|
59
|
+
| `/sw-github:sync` | GitHub sync |
|
|
60
|
+
| `/sw-jira:sync` | Jira sync |
|
|
61
|
+
|
|
62
|
+
**Natural language**: "Let's build X" → `/sw:increment` | "What's status?" → `/sw:progress` | "We're done" → `/sw:done`
|
|
63
|
+
<!-- SW:END:workflow -->
|
|
64
|
+
|
|
65
|
+
<!-- SW:SECTION:structure version="1.0.33" -->
|
|
66
|
+
## Structure
|
|
67
|
+
|
|
68
|
+
```
|
|
69
|
+
.specweave/
|
|
70
|
+
├── increments/####-name/ # metadata.json, spec.md, tasks.md
|
|
71
|
+
├── docs/internal/
|
|
72
|
+
│ ├── specs/{project}/ # Living docs
|
|
73
|
+
│ ├── architecture/adr/ # ADRs
|
|
74
|
+
│ └── operations/ # Runbooks
|
|
75
|
+
└── config.json
|
|
76
|
+
```
|
|
77
|
+
|
|
78
|
+
**Multi-repo**: Clone to `/repositories`, not root → `repositories/backend/src/...`
|
|
79
|
+
<!-- SW:END:structure -->
|
|
80
|
+
|
|
81
|
+
<!-- SW:SECTION:taskformat version="1.0.33" -->
|
|
82
|
+
## Task Format
|
|
83
|
+
|
|
84
|
+
```markdown
|
|
85
|
+
### T-001: Title
|
|
86
|
+
**User Story**: US-001 | **Satisfies ACs**: AC-US1-01 | **Status**: [x] completed
|
|
87
|
+
**Test**: Given [X] → When [Y] → Then [Z]
|
|
88
|
+
```
|
|
89
|
+
<!-- SW:END:taskformat -->
|
|
90
|
+
|
|
91
|
+
<!-- SW:SECTION:secrets version="1.0.33" -->
|
|
92
|
+
## Secrets Check
|
|
93
|
+
|
|
94
|
+
**BEFORE CLI tools**: Check existing config first!
|
|
95
|
+
```bash
|
|
96
|
+
grep -E "(GITHUB_TOKEN|JIRA_|ADO_)" .env 2>/dev/null
|
|
97
|
+
cat .specweave/config.json | grep -A5 '"sync"'
|
|
98
|
+
gh auth status
|
|
99
|
+
```
|
|
100
|
+
<!-- SW:END:secrets -->
|
|
101
|
+
|
|
102
|
+
<!-- SW:SECTION:syncing version="1.0.33" -->
|
|
103
|
+
## Auto-Sync (Hooks)
|
|
104
|
+
|
|
105
|
+
Post-task: updates tasks.md → living docs → external trackers (if configured)
|
|
106
|
+
|
|
107
|
+
Config: `.specweave/config.json` → `hooks.post_task_completion`
|
|
108
|
+
<!-- SW:END:syncing -->
|
|
109
|
+
|
|
110
|
+
<!-- SW:SECTION:mapping version="1.0.33" -->
|
|
111
|
+
## GitHub Mapping
|
|
112
|
+
|
|
113
|
+
| SpecWeave | GitHub |
|
|
114
|
+
|-----------|--------|
|
|
115
|
+
| Feature FS-XXX | Milestone |
|
|
116
|
+
| Story US-XXX | Issue `[FS-XXX][US-YYY] Title` |
|
|
117
|
+
| Task T-XXX | Checkbox |
|
|
118
|
+
<!-- SW:END:mapping -->
|
|
119
|
+
|
|
120
|
+
<!-- SW:SECTION:testing version="1.0.33" -->
|
|
121
|
+
## Testing
|
|
122
|
+
|
|
123
|
+
BDD in tasks.md | Unit >80% | `.test.ts` (Vitest)
|
|
124
|
+
|
|
125
|
+
```typescript
|
|
126
|
+
// Vitest pattern: vi.fn() not jest.fn(), import not require
|
|
127
|
+
import { vi } from 'vitest';
|
|
128
|
+
vi.mock('fs', () => ({ readFile: vi.fn() }));
|
|
129
|
+
```
|
|
130
|
+
<!-- SW:END:testing -->
|
|
131
|
+
|
|
132
|
+
<!-- SW:SECTION:limits version="1.0.33" -->
|
|
133
|
+
## Limits
|
|
134
|
+
|
|
135
|
+
**Max 1500 lines/file** — extract before adding
|
|
136
|
+
<!-- SW:END:limits -->
|
|
137
|
+
|
|
138
|
+
<!-- SW:SECTION:troubleshooting version="1.0.33" -->
|
|
139
|
+
## Troubleshooting
|
|
140
|
+
|
|
141
|
+
| Issue | Fix |
|
|
142
|
+
|-------|-----|
|
|
143
|
+
| Skills missing | Restart Claude Code |
|
|
144
|
+
| Commands gone | `/plugin list --installed` |
|
|
145
|
+
| Out of sync | `/sw:sync-tasks` |
|
|
146
|
+
| Find increment | `/sw:status` |
|
|
147
|
+
| Root polluted | Move files to `.specweave/increments/####/reports/` |
|
|
148
|
+
| Duplicate IDs | `/sw:fix-duplicates` |
|
|
149
|
+
| External not syncing | Check `config.json` → `external_tracker_sync: true` |
|
|
150
|
+
<!-- SW:END:troubleshooting -->
|
|
151
|
+
|
|
152
|
+
<!-- SW:SECTION:principles version="1.0.33" -->
|
|
153
|
+
## Principles
|
|
154
|
+
|
|
155
|
+
1. **Spec-first**: `/sw:increment` before coding
|
|
156
|
+
2. **Docs = truth**: Specs guide implementation
|
|
157
|
+
3. **Incremental**: Small, validated increments
|
|
158
|
+
4. **Traceable**: All work → specs → ACs
|
|
159
|
+
5. **Clean**: All files in increment folders
|
|
160
|
+
<!-- SW:END:principles -->
|
|
161
|
+
|
|
162
|
+
<!-- SW:SECTION:linking version="1.0.33" -->
|
|
163
|
+
## Bidirectional Linking
|
|
164
|
+
|
|
165
|
+
Tasks ↔ User Stories auto-linked via AC-IDs: `AC-US1-01` → `US-001`
|
|
166
|
+
|
|
167
|
+
Task format: `**AC**: AC-US1-01, AC-US1-02` (CRITICAL for linking)
|
|
168
|
+
<!-- SW:END:linking -->
|
|
169
|
+
|
|
170
|
+
<!-- SW:SECTION:docs version="1.0.33" -->
|
|
171
|
+
## Docs
|
|
172
|
+
|
|
173
|
+
[spec-weave.com](https://spec-weave.com) | `.specweave/docs/internal/`
|
|
174
|
+
<!-- SW:END:docs -->
|
|
175
|
+
|
|
176
|
+
---
|
|
177
|
+
<!-- ↓ ORIGINAL ↓ -->
|
|
178
|
+
|
|
1
179
|
# SpecWeave Development Guide
|
|
2
180
|
|
|
3
181
|
**Project**: SpecWeave - Spec-Driven Development Framework
|
|
@@ -370,3 +548,4 @@ npm run rebuild
|
|
|
370
548
|
- **Internal Docs**: `.specweave/docs/internal/`
|
|
371
549
|
- **ADRs**: `.specweave/docs/internal/architecture/adr/`
|
|
372
550
|
- **Troubleshooting**: `.specweave/docs/internal/troubleshooting/`
|
|
551
|
+
|
|
@@ -1 +1 @@
|
|
|
1
|
-
{"version":3,"file":"initial-increment-generator.d.ts","sourceRoot":"","sources":["../../../../../src/cli/helpers/init/initial-increment-generator.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAYH,MAAM,WAAW,uBAAuB;IACtC,WAAW,EAAE,MAAM,CAAC;IACpB,WAAW,EAAE,MAAM,CAAC;IACpB,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,QAAQ,CAAC,EAAE,MAAM,CAAC;CACnB;AAED;;;;;;;;;GASG;AACH,wBAAsB,wBAAwB,CAAC,OAAO,EAAE,uBAAuB,GAAG,OAAO,CAAC,MAAM,CAAC,
|
|
1
|
+
{"version":3,"file":"initial-increment-generator.d.ts","sourceRoot":"","sources":["../../../../../src/cli/helpers/init/initial-increment-generator.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAYH,MAAM,WAAW,uBAAuB;IACtC,WAAW,EAAE,MAAM,CAAC;IACpB,WAAW,EAAE,MAAM,CAAC;IACpB,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,QAAQ,CAAC,EAAE,MAAM,CAAC;CACnB;AAED;;;;;;;;;GASG;AACH,wBAAsB,wBAAwB,CAAC,OAAO,EAAE,uBAAuB,GAAG,OAAO,CAAC,MAAM,CAAC,CAwDhG"}
|
|
@@ -43,16 +43,9 @@ export async function generateInitialIncrement(options) {
|
|
|
43
43
|
const multiProjectDetection = detectMultiProjectMode(projectPath);
|
|
44
44
|
// Create increment directory
|
|
45
45
|
fs.ensureDirSync(incrementPath);
|
|
46
|
-
// Generate
|
|
47
|
-
|
|
48
|
-
|
|
49
|
-
// Generate plan.md
|
|
50
|
-
const planContent = generatePlanMd(projectName);
|
|
51
|
-
fs.writeFileSync(path.join(incrementPath, 'plan.md'), planContent, 'utf-8');
|
|
52
|
-
// Generate tasks.md
|
|
53
|
-
const tasksContent = generateTasksMd(projectName, techStack);
|
|
54
|
-
fs.writeFileSync(path.join(incrementPath, 'tasks.md'), tasksContent, 'utf-8');
|
|
55
|
-
// Generate metadata.json (use values from config)
|
|
46
|
+
// CRITICAL: Generate metadata.json FIRST!
|
|
47
|
+
// The metadata-json-guard.sh hook blocks spec.md creation if metadata.json doesn't exist.
|
|
48
|
+
// This prevents broken increments that lack proper tracking.
|
|
56
49
|
const metadata = {
|
|
57
50
|
id: incrementId,
|
|
58
51
|
type: IncrementType.FEATURE,
|
|
@@ -64,6 +57,15 @@ export async function generateInitialIncrement(options) {
|
|
|
64
57
|
};
|
|
65
58
|
// Write metadata using explicit rootDir parameter (no process.chdir needed!)
|
|
66
59
|
MetadataManager.write(incrementId, metadata, projectPath);
|
|
60
|
+
// Generate spec.md (now allowed - metadata.json exists)
|
|
61
|
+
const specContent = generateSpecMd(projectName, techStack, testMode, coverageTarget, multiProjectDetection);
|
|
62
|
+
fs.writeFileSync(path.join(incrementPath, 'spec.md'), specContent, 'utf-8');
|
|
63
|
+
// Generate plan.md
|
|
64
|
+
const planContent = generatePlanMd(projectName);
|
|
65
|
+
fs.writeFileSync(path.join(incrementPath, 'plan.md'), planContent, 'utf-8');
|
|
66
|
+
// Generate tasks.md
|
|
67
|
+
const tasksContent = generateTasksMd(projectName, techStack);
|
|
68
|
+
fs.writeFileSync(path.join(incrementPath, 'tasks.md'), tasksContent, 'utf-8');
|
|
67
69
|
return incrementId;
|
|
68
70
|
}
|
|
69
71
|
/**
|
|
@@ -1 +1 @@
|
|
|
1
|
-
{"version":3,"file":"initial-increment-generator.js","sourceRoot":"","sources":["../../../../../src/cli/helpers/init/initial-increment-generator.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAEH,OAAO,KAAK,EAAE,MAAM,6BAA6B,CAAC;AAClD,OAAO,IAAI,MAAM,MAAM,CAAC;AACxB,OAAO,EAAE,eAAe,EAAE,aAAa,EAAqB,MAAM,2CAA2C,CAAC;AAC9G,OAAO,EAAE,eAAe,EAAE,MAAM,6CAA6C,CAAC;AAC9E,OAAO,EACL,sBAAsB,EAGvB,MAAM,0CAA0C,CAAC;AASlD;;;;;;;;;GASG;AACH,MAAM,CAAC,KAAK,UAAU,wBAAwB,CAAC,OAAgC;IAC7E,MAAM,EAAE,WAAW,EAAE,WAAW,EAAE,SAAS,EAAE,QAAQ,GAAG,IAAI,EAAE,GAAG,OAAO,CAAC;IAEzE,MAAM,WAAW,GAAG,oBAAoB,CAAC;IACzC,MAAM,aAAa,GAAG,IAAI,CAAC,IAAI,CAAC,WAAW,EAAE,YAAY,EAAE,YAAY,EAAE,WAAW,CAAC,CAAC;IAEtF,0DAA0D;IAC1D,MAAM,UAAU,GAAG,IAAI,CAAC,IAAI,CAAC,WAAW,EAAE,YAAY,EAAE,aAAa,CAAC,CAAC;IACvE,IAAI,QAAQ,GAAoC,YAAY,CAAC;IAC7D,IAAI,cAAc,GAAG,EAAE,CAAC;IAExB,IAAI,EAAE,CAAC,UAAU,CAAC,UAAU,CAAC,EAAE,CAAC;QAC9B,IAAI,CAAC;YACH,MAAM,MAAM,GAAG,IAAI,CAAC,KAAK,CAAC,EAAE,CAAC,YAAY,CAAC,UAAU,EAAE,OAAO,CAAC,CAAC,CAAC;YAChE,QAAQ,GAAG,MAAM,EAAE,OAAO,EAAE,eAAe,IAAI,YAAY,CAAC;YAC5D,cAAc,GAAG,MAAM,EAAE,OAAO,EAAE,qBAAqB,IAAI,EAAE,CAAC;QAChE,CAAC;QAAC,OAAO,KAAK,EAAE,CAAC;YACf,+CAA+C;QACjD,CAAC;IACH,CAAC;IAED,4BAA4B;IAC5B,MAAM,qBAAqB,GAAG,sBAAsB,CAAC,WAAW,CAAC,CAAC;IAElE,6BAA6B;IAC7B,EAAE,CAAC,aAAa,CAAC,aAAa,CAAC,CAAC;IAEhC,
|
|
1
|
+
{"version":3,"file":"initial-increment-generator.js","sourceRoot":"","sources":["../../../../../src/cli/helpers/init/initial-increment-generator.ts"],"names":[],"mappings":"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"}
|
package/package.json
CHANGED
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
{
|
|
2
2
|
"name": "specweave",
|
|
3
|
-
"version": "1.0.
|
|
3
|
+
"version": "1.0.34",
|
|
4
4
|
"description": "Spec-driven development framework for Claude Code. AI-native workflow with living documentation, intelligent agents, and multilingual support (9 languages). Enterprise-grade traceability with permanent specs and temporary increments.",
|
|
5
5
|
"type": "module",
|
|
6
6
|
"main": "dist/index.js",
|
|
@@ -762,7 +762,67 @@ node plugins/specweave/skills/increment-planner/scripts/feature-utils.js check-i
|
|
|
762
762
|
mkdir -p .specweave/increments/0021-feature-name
|
|
763
763
|
```
|
|
764
764
|
|
|
765
|
-
### STEP 4: Create
|
|
765
|
+
### STEP 4: Create metadata.json FIRST (MANDATORY - CRITICAL ORDER!)
|
|
766
|
+
|
|
767
|
+
**🚨 CRITICAL: metadata.json MUST be created BEFORE spec.md!**
|
|
768
|
+
|
|
769
|
+
The `metadata-json-guard.sh` hook BLOCKS spec.md creation if metadata.json doesn't exist.
|
|
770
|
+
This prevents broken increments that lack proper tracking.
|
|
771
|
+
|
|
772
|
+
**IMPORTANT**: Read `testMode` and `coverageTarget` from `.specweave/config.json`:
|
|
773
|
+
|
|
774
|
+
```bash
|
|
775
|
+
# Read config to get defaultTestMode and defaultCoverageTarget
|
|
776
|
+
cat .specweave/config.json | jq -r '.testing.defaultTestMode // "TDD"'
|
|
777
|
+
cat .specweave/config.json | jq -r '.testing.defaultCoverageTarget // 95'
|
|
778
|
+
```
|
|
779
|
+
|
|
780
|
+
Create `.specweave/increments/0021-feature-name/metadata.json`:
|
|
781
|
+
|
|
782
|
+
```json
|
|
783
|
+
{
|
|
784
|
+
"id": "0021-feature-name",
|
|
785
|
+
"status": "planned",
|
|
786
|
+
"type": "feature",
|
|
787
|
+
"priority": "P1",
|
|
788
|
+
"created": "2025-11-24T12:00:00Z",
|
|
789
|
+
"lastActivity": "2025-11-24T12:00:00Z",
|
|
790
|
+
"testMode": "<VALUE FROM config.testing.defaultTestMode OR 'TDD'>",
|
|
791
|
+
"coverageTarget": <VALUE FROM config.testing.defaultCoverageTarget OR 95>,
|
|
792
|
+
"feature_id": null,
|
|
793
|
+
"epic_id": null,
|
|
794
|
+
"externalLinks": {}
|
|
795
|
+
}
|
|
796
|
+
```
|
|
797
|
+
|
|
798
|
+
**Use Write tool to create this file IMMEDIATELY after creating directory.**
|
|
799
|
+
|
|
800
|
+
**Example Logic**:
|
|
801
|
+
```javascript
|
|
802
|
+
// Read config
|
|
803
|
+
const config = JSON.parse(fs.readFileSync('.specweave/config.json', 'utf8'));
|
|
804
|
+
const testMode = config?.testing?.defaultTestMode || 'TDD';
|
|
805
|
+
const coverageTarget = config?.testing?.defaultCoverageTarget || 95;
|
|
806
|
+
|
|
807
|
+
// Create metadata with config values
|
|
808
|
+
const metadata = {
|
|
809
|
+
id: "0021-feature-name",
|
|
810
|
+
status: "planned",
|
|
811
|
+
type: "feature",
|
|
812
|
+
priority: "P1",
|
|
813
|
+
created: new Date().toISOString(),
|
|
814
|
+
lastActivity: new Date().toISOString(),
|
|
815
|
+
testMode: testMode, // ← FROM CONFIG!
|
|
816
|
+
coverageTarget: coverageTarget, // ← FROM CONFIG!
|
|
817
|
+
feature_id: null,
|
|
818
|
+
epic_id: null,
|
|
819
|
+
externalLinks: {}
|
|
820
|
+
};
|
|
821
|
+
```
|
|
822
|
+
|
|
823
|
+
### STEP 5: Create spec.md Template
|
|
824
|
+
|
|
825
|
+
**⚠️ This step REQUIRES metadata.json to exist (created in STEP 4)!**
|
|
766
826
|
|
|
767
827
|
Create `.specweave/increments/0021-feature-name/spec.md`:
|
|
768
828
|
|
|
@@ -770,7 +830,7 @@ Create `.specweave/increments/0021-feature-name/spec.md`:
|
|
|
770
830
|
|
|
771
831
|
**⚠️ IMPORTANT: Use the correct template based on STEP 0 detection!**
|
|
772
832
|
|
|
773
|
-
####
|
|
833
|
+
#### 5A: Single-Project Template (1-level structure)
|
|
774
834
|
|
|
775
835
|
**Template File**: `templates/spec-single-project.md`
|
|
776
836
|
|
|
@@ -779,7 +839,7 @@ Replace placeholders:
|
|
|
779
839
|
- `{{TEST_MODE}}`, `{{COVERAGE_TARGET}}`
|
|
780
840
|
- **`{{PROJECT_ID}}`** ← MANDATORY (from STEP 0B)
|
|
781
841
|
|
|
782
|
-
####
|
|
842
|
+
#### 5B: Multi-Project Template (2-level structure) - USE THIS!
|
|
783
843
|
|
|
784
844
|
**Template File**: `templates/spec-multi-project.md`
|
|
785
845
|
|
|
@@ -812,7 +872,7 @@ Replace placeholders:
|
|
|
812
872
|
- User stories (2-level) without `**Board**:` field
|
|
813
873
|
- Using unresolved placeholders like `{{PROJECT_ID}}`
|
|
814
874
|
|
|
815
|
-
### STEP
|
|
875
|
+
### STEP 6: Create plan.md Template (OPTIONAL)
|
|
816
876
|
|
|
817
877
|
Create `.specweave/increments/0021-feature-name/plan.md`:
|
|
818
878
|
|
|
@@ -820,19 +880,19 @@ Create `.specweave/increments/0021-feature-name/plan.md`:
|
|
|
820
880
|
|
|
821
881
|
Replace `{{FEATURE_TITLE}}` placeholder. plan.md is OPTIONAL - create only for complex features with architecture decisions.
|
|
822
882
|
|
|
823
|
-
### STEP
|
|
883
|
+
### STEP 7: Create tasks.md Template
|
|
824
884
|
|
|
825
885
|
Create `.specweave/increments/0021-feature-name/tasks.md`:
|
|
826
886
|
|
|
827
887
|
**⚠️ IMPORTANT: Use the correct template based on STEP 0 detection!**
|
|
828
888
|
|
|
829
|
-
####
|
|
889
|
+
#### 7A: Single-Project Template
|
|
830
890
|
|
|
831
891
|
**Template File**: `templates/tasks-single-project.md`
|
|
832
892
|
|
|
833
893
|
Replace `{{FEATURE_TITLE}}` placeholder.
|
|
834
894
|
|
|
835
|
-
####
|
|
895
|
+
#### 7B: Multi-Project Template (umbrella.enabled: true) - USE THIS!
|
|
836
896
|
|
|
837
897
|
**Template File**: `templates/tasks-multi-project.md`
|
|
838
898
|
|
|
@@ -845,59 +905,6 @@ Replace placeholders: `{{FEATURE_TITLE}}`, `{{PROJECT_FE_ID}}`, `{{PROJECT_BE_ID
|
|
|
845
905
|
4. **Test file paths MUST include project folder**: `sw-app-be/tests/`, `sw-app-fe/tests/`
|
|
846
906
|
5. **Dependencies between projects should be explicit**
|
|
847
907
|
|
|
848
|
-
### STEP 7: Create metadata.json (MANDATORY)
|
|
849
|
-
|
|
850
|
-
**IMPORTANT**: Read `testMode` and `coverageTarget` from `.specweave/config.json`:
|
|
851
|
-
|
|
852
|
-
```bash
|
|
853
|
-
# Read config to get defaultTestMode and defaultCoverageTarget
|
|
854
|
-
cat .specweave/config.json | jq -r '.testing.defaultTestMode // "TDD"'
|
|
855
|
-
cat .specweave/config.json | jq -r '.testing.defaultCoverageTarget // 95'
|
|
856
|
-
```
|
|
857
|
-
|
|
858
|
-
Create `.specweave/increments/0021-feature-name/metadata.json`:
|
|
859
|
-
|
|
860
|
-
```json
|
|
861
|
-
{
|
|
862
|
-
"id": "0021-feature-name",
|
|
863
|
-
"status": "planned",
|
|
864
|
-
"type": "feature",
|
|
865
|
-
"priority": "P1",
|
|
866
|
-
"created": "2025-11-24T12:00:00Z",
|
|
867
|
-
"lastActivity": "2025-11-24T12:00:00Z",
|
|
868
|
-
"testMode": "<VALUE FROM config.testing.defaultTestMode OR 'TDD'>",
|
|
869
|
-
"coverageTarget": <VALUE FROM config.testing.defaultCoverageTarget OR 95>,
|
|
870
|
-
"feature_id": null,
|
|
871
|
-
"epic_id": null,
|
|
872
|
-
"externalLinks": {}
|
|
873
|
-
}
|
|
874
|
-
```
|
|
875
|
-
|
|
876
|
-
**Use Write tool to create this file immediately after creating increment.**
|
|
877
|
-
|
|
878
|
-
**Example Logic**:
|
|
879
|
-
```javascript
|
|
880
|
-
// Read config
|
|
881
|
-
const config = JSON.parse(fs.readFileSync('.specweave/config.json', 'utf8'));
|
|
882
|
-
const testMode = config?.testing?.defaultTestMode || 'TDD';
|
|
883
|
-
const coverageTarget = config?.testing?.defaultCoverageTarget || 95;
|
|
884
|
-
|
|
885
|
-
// Create metadata with config values
|
|
886
|
-
const metadata = {
|
|
887
|
-
id: "0021-feature-name",
|
|
888
|
-
status: "planned",
|
|
889
|
-
type: "feature",
|
|
890
|
-
priority: "P1",
|
|
891
|
-
created: new Date().toISOString(),
|
|
892
|
-
lastActivity: new Date().toISOString(),
|
|
893
|
-
testMode: testMode, // ← FROM CONFIG!
|
|
894
|
-
coverageTarget: coverageTarget, // ← FROM CONFIG!
|
|
895
|
-
feature_id: null,
|
|
896
|
-
epic_id: null,
|
|
897
|
-
externalLinks: {}
|
|
898
|
-
};
|
|
899
|
-
```
|
|
900
|
-
|
|
901
908
|
### STEP 8: Guide User to Complete Planning
|
|
902
909
|
|
|
903
910
|
**Output this guidance to user**:
|
|
@@ -1085,9 +1092,11 @@ node plugins/specweave/skills/increment-planner/scripts/generate-short-name.js "
|
|
|
1085
1092
|
**Process**:
|
|
1086
1093
|
1. Get next number: `0015`
|
|
1087
1094
|
2. Generate short name: `user-authentication`
|
|
1088
|
-
3. Create: `.specweave/increments/0015-user-authentication/`
|
|
1089
|
-
4. Create
|
|
1090
|
-
5.
|
|
1095
|
+
3. Create directory: `.specweave/increments/0015-user-authentication/`
|
|
1096
|
+
4. Create **metadata.json FIRST** (required before spec.md)
|
|
1097
|
+
5. Create spec.md (now allowed - metadata.json exists)
|
|
1098
|
+
6. Create tasks.md (plan.md optional for simple features)
|
|
1099
|
+
7. Guide user to complete in main conversation
|
|
1091
1100
|
|
|
1092
1101
|
### Pattern 2: Critical Hotfix
|
|
1093
1102
|
|
|
@@ -1117,6 +1126,9 @@ node plugins/specweave/skills/increment-planner/scripts/generate-short-name.js "
|
|
|
1117
1126
|
|
|
1118
1127
|
## Troubleshooting
|
|
1119
1128
|
|
|
1129
|
+
**Issue**: spec.md Write BLOCKED by guard
|
|
1130
|
+
**Solution**: Create metadata.json FIRST! The `metadata-json-guard.sh` hook blocks spec.md creation until metadata.json exists. Always follow the order: directory → metadata.json → spec.md → tasks.md
|
|
1131
|
+
|
|
1120
1132
|
**Issue**: Feature number conflict
|
|
1121
1133
|
**Solution**: Always run duplicate check before creating increment
|
|
1122
1134
|
|