@polymorphism-tech/morph-spec 4.7.0 → 4.7.1
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 +119 -99
- package/package.json +1 -1
package/README.md
CHANGED
|
@@ -2,8 +2,8 @@
|
|
|
2
2
|
|
|
3
3
|
> Spec-driven development framework for multi-stack projects. Turns feature requests into implementation-ready code through structured, AI-orchestrated phases.
|
|
4
4
|
|
|
5
|
-
**Package:** `@polymorphism-tech/morph-spec`
|
|
6
|
-
**Version:** 4.
|
|
5
|
+
**Package:** `@polymorphism-tech/morph-spec`
|
|
6
|
+
**Version:** 4.7.1
|
|
7
7
|
**Requires:** Node.js 18+, Claude Code
|
|
8
8
|
|
|
9
9
|
---
|
|
@@ -28,30 +28,32 @@ It integrates natively with Claude Code: skills become slash commands, agents be
|
|
|
28
28
|
|
|
29
29
|
Install the CLI globally:
|
|
30
30
|
|
|
31
|
-
```bash
|
|
31
|
+
```bash
|
|
32
32
|
npm install -g @polymorphism-tech/morph-spec
|
|
33
|
-
|
|
33
|
+
```
|
|
34
34
|
|
|
35
35
|
Then initialize in your project:
|
|
36
36
|
|
|
37
|
-
```bash
|
|
37
|
+
```bash
|
|
38
38
|
morph-spec init
|
|
39
|
-
|
|
39
|
+
```
|
|
40
40
|
|
|
41
41
|
Or use the interactive wizard:
|
|
42
42
|
|
|
43
|
-
```bash
|
|
43
|
+
```bash
|
|
44
44
|
morph-spec init --wizard
|
|
45
|
-
|
|
45
|
+
```
|
|
46
46
|
|
|
47
47
|
### Init options
|
|
48
48
|
|
|
49
|
-
|
|
50
|
-
|
|
51
|
-
|
|
|
49
|
+
|
|
50
|
+
| Flag | Description |
|
|
51
|
+
| ------------------ | ----------------------------------------- |
|
|
52
|
+
| `--wizard` | Interactive step-by-step setup |
|
|
52
53
|
| `--skip-detection` | Skip auto-detection of stack and patterns |
|
|
53
|
-
| `--force`
|
|
54
|
-
| `--skip-mcp`
|
|
54
|
+
| `--force` | Overwrite existing installation |
|
|
55
|
+
| `--skip-mcp` | Skip MCP configuration prompt |
|
|
56
|
+
|
|
55
57
|
|
|
56
58
|
After init, open the project in Claude Code. The framework activates automatically via `.claude/settings.local.json`.
|
|
57
59
|
|
|
@@ -59,7 +61,7 @@ After init, open the project in Claude Code. The framework activates automatical
|
|
|
59
61
|
|
|
60
62
|
## Project structure (after init)
|
|
61
63
|
|
|
62
|
-
|
|
64
|
+
```
|
|
63
65
|
your-project/
|
|
64
66
|
├── CLAUDE.md # AI instructions for this project
|
|
65
67
|
├── .morph/
|
|
@@ -84,7 +86,7 @@ your-project/
|
|
|
84
86
|
├── agents/ # Native subagents (37 agents)
|
|
85
87
|
├── rules/ # Path-scoped standards rules
|
|
86
88
|
└── settings.local.json # Hooks configuration (11 hooks)
|
|
87
|
-
|
|
89
|
+
```
|
|
88
90
|
|
|
89
91
|
---
|
|
90
92
|
|
|
@@ -92,21 +94,23 @@ your-project/
|
|
|
92
94
|
|
|
93
95
|
Features move through structured phases. Some are optional depending on feature type.
|
|
94
96
|
|
|
95
|
-
|
|
97
|
+
```
|
|
96
98
|
proposal → setup → [uiux] → design → clarify → tasks → implement → [sync]
|
|
97
|
-
|
|
99
|
+
```
|
|
98
100
|
|
|
99
101
|
Phases in brackets are optional. `uiux` applies to UI-heavy features. `sync` is a post-implementation reconciliation step.
|
|
100
102
|
|
|
101
103
|
### Phase outputs
|
|
102
104
|
|
|
103
|
-
|
|
104
|
-
|
|
105
|
-
|
|
|
106
|
-
|
|
|
107
|
-
|
|
|
108
|
-
|
|
|
109
|
-
|
|
|
105
|
+
|
|
106
|
+
| Phase | Directory | Key files |
|
|
107
|
+
| --------- | -------------- | ------------------------------------------------------------- |
|
|
108
|
+
| Proposal | `0-proposal/` | `proposal.md` |
|
|
109
|
+
| Design | `1-design/` | `spec.md`, `contracts.cs`, `decisions.md` |
|
|
110
|
+
| UI/UX | `2-ui/` | `design-system.md`, `mockups.md`, `components.md`, `flows.md` |
|
|
111
|
+
| Tasks | `3-tasks/` | `tasks.md` |
|
|
112
|
+
| Implement | `4-implement/` | `recap.md` |
|
|
113
|
+
|
|
110
114
|
|
|
111
115
|
### Approval gates
|
|
112
116
|
|
|
@@ -115,9 +119,9 @@ Phases in brackets are optional. `uiux` applies to UI-heavy features. `sync` is
|
|
|
115
119
|
|
|
116
120
|
Check gate status:
|
|
117
121
|
|
|
118
|
-
```bash
|
|
122
|
+
```bash
|
|
119
123
|
morph-spec state show {feature}
|
|
120
|
-
|
|
124
|
+
```
|
|
121
125
|
|
|
122
126
|
---
|
|
123
127
|
|
|
@@ -125,12 +129,14 @@ morph-spec state show {feature}
|
|
|
125
129
|
|
|
126
130
|
These commands are available inside Claude Code after init.
|
|
127
131
|
|
|
128
|
-
|
|
129
|
-
|
|
132
|
+
|
|
133
|
+
| Command | Description |
|
|
134
|
+
| --------------------------- | --------------------------------------------------------- |
|
|
130
135
|
| `/morph-proposal {feature}` | Full spec pipeline (phases 0-4, pauses at approval gates) |
|
|
131
|
-
| `/morph-apply {feature}`
|
|
132
|
-
| `/morph-status`
|
|
133
|
-
| `/morph-preflight`
|
|
136
|
+
| `/morph-apply {feature}` | Implement approved feature (phase 5) |
|
|
137
|
+
| `/morph-status` | Feature status dashboard |
|
|
138
|
+
| `/morph-preflight` | Pre-implementation validation |
|
|
139
|
+
|
|
134
140
|
|
|
135
141
|
---
|
|
136
142
|
|
|
@@ -138,7 +144,7 @@ These commands are available inside Claude Code after init.
|
|
|
138
144
|
|
|
139
145
|
### Project management
|
|
140
146
|
|
|
141
|
-
```bash
|
|
147
|
+
```bash
|
|
142
148
|
morph-spec init # Initialize MORPH in current project
|
|
143
149
|
morph-spec init --wizard # Interactive wizard setup
|
|
144
150
|
morph-spec init --skip-detection # Skip stack auto-detection
|
|
@@ -150,11 +156,11 @@ morph-spec update --templates # Update templates only
|
|
|
150
156
|
morph-spec update --standards # Update standards only
|
|
151
157
|
morph-spec doctor # Check installation health
|
|
152
158
|
morph-spec detect # Detect stack, architecture, patterns
|
|
153
|
-
|
|
159
|
+
```
|
|
154
160
|
|
|
155
161
|
### Feature workflow
|
|
156
162
|
|
|
157
|
-
```bash
|
|
163
|
+
```bash
|
|
158
164
|
morph-spec state list # List all features and their states
|
|
159
165
|
morph-spec state get {feature} # Get feature state
|
|
160
166
|
morph-spec state set {feature} {key} {value}
|
|
@@ -166,11 +172,11 @@ morph-spec task next {feature} # Preview next task
|
|
|
166
172
|
morph-spec status {feature} # Feature status dashboard
|
|
167
173
|
morph-spec diff {feature} # Spec changes since last snapshot
|
|
168
174
|
morph-spec rollback {feature} # Rollback feature to previous phase
|
|
169
|
-
|
|
175
|
+
```
|
|
170
176
|
|
|
171
177
|
### Validation and standards
|
|
172
178
|
|
|
173
|
-
```bash
|
|
179
|
+
```bash
|
|
174
180
|
morph-spec validate # Run all validators
|
|
175
181
|
morph-spec validate {validator} # Run specific validator
|
|
176
182
|
morph-spec standards --list # List all 74 registered standards
|
|
@@ -178,15 +184,15 @@ morph-spec standards --list --category {name}
|
|
|
178
184
|
morph-spec standards --search {query} # Search by name, tag, or ID
|
|
179
185
|
morph-spec standards --show {id} # Print standard content
|
|
180
186
|
morph-spec standards --json # Output as JSON
|
|
181
|
-
|
|
187
|
+
```
|
|
182
188
|
|
|
183
189
|
### Utilities
|
|
184
190
|
|
|
185
|
-
```bash
|
|
191
|
+
```bash
|
|
186
192
|
morph-spec cost {bicep-file} # Estimate Azure resource costs
|
|
187
193
|
morph-spec troubleshoot {keywords} # Search known issues and solutions
|
|
188
194
|
morph-spec state checkpoint {feature} # Save state checkpoint
|
|
189
|
-
|
|
195
|
+
```
|
|
190
196
|
|
|
191
197
|
---
|
|
192
198
|
|
|
@@ -196,19 +202,23 @@ morph-spec includes 37 agents organized in 4 tiers. Tier 1-2 agents are installe
|
|
|
196
202
|
|
|
197
203
|
### Tier 1 — Orchestrators (3)
|
|
198
204
|
|
|
199
|
-
|
|
200
|
-
|
|
201
|
-
|
|
|
202
|
-
| `
|
|
203
|
-
| `
|
|
205
|
+
|
|
206
|
+
| Agent | Role | Active |
|
|
207
|
+
| --------------------- | ------------------------------------------------------ | --------- |
|
|
208
|
+
| `standards-architect` | Chief Architect — enforces standards across all phases | Always |
|
|
209
|
+
| `ai-system-architect` | AI/Agent system design and orchestration | On-demand |
|
|
210
|
+
| `po-pm-advisor` | Product and project advisory | On-demand |
|
|
211
|
+
|
|
204
212
|
|
|
205
213
|
### Tier 2 — Domain Leaders (3)
|
|
206
214
|
|
|
207
|
-
|
|
208
|
-
|
|
209
|
-
|
|
|
210
|
-
| `
|
|
211
|
-
| `
|
|
215
|
+
|
|
216
|
+
| Agent | Squad | Active |
|
|
217
|
+
| ----------------- | ------------------------- | --------- |
|
|
218
|
+
| `dotnet-senior` | Backend squad lead | Always |
|
|
219
|
+
| `azure-architect` | Infrastructure squad lead | Always |
|
|
220
|
+
| `ui-designer` | UI/UX squad lead | On-demand |
|
|
221
|
+
|
|
212
222
|
|
|
213
223
|
### Tier 3 — Specialists (26)
|
|
214
224
|
|
|
@@ -224,13 +234,15 @@ Organized into squads:
|
|
|
224
234
|
|
|
225
235
|
### Tier 4 — Validators (5)
|
|
226
236
|
|
|
227
|
-
|
|
228
|
-
|
|
229
|
-
|
|
|
230
|
-
| `
|
|
231
|
-
| `
|
|
232
|
-
| `
|
|
233
|
-
| `
|
|
237
|
+
|
|
238
|
+
| Agent | Validates |
|
|
239
|
+
| ------------------------------ | --------------------------------------- |
|
|
240
|
+
| `security-expert` | Security vulnerabilities and compliance |
|
|
241
|
+
| `architecture-expert` | Architectural decisions and constraints |
|
|
242
|
+
| `packages-validator` | Package versions and compatibility |
|
|
243
|
+
| `design-system-validator` | Design system adherence |
|
|
244
|
+
| `blazor-concurrency-validator` | Blazor thread safety and concurrency |
|
|
245
|
+
|
|
234
246
|
|
|
235
247
|
---
|
|
236
248
|
|
|
@@ -238,22 +250,25 @@ Organized into squads:
|
|
|
238
250
|
|
|
239
251
|
11 Claude Code hooks are installed into `.claude/settings.local.json` across 8 event types:
|
|
240
252
|
|
|
241
|
-
|
|
242
|
-
|
|
243
|
-
|
|
|
244
|
-
| `
|
|
245
|
-
| `
|
|
246
|
-
| `PreToolUse`
|
|
247
|
-
| `
|
|
248
|
-
| `PostToolUse`
|
|
249
|
-
| `
|
|
250
|
-
| `
|
|
251
|
-
| `
|
|
252
|
-
| `
|
|
253
|
+
|
|
254
|
+
| Event | Hook | Purpose |
|
|
255
|
+
| -------------------- | --------------------------- | -------------------------------------------------------- |
|
|
256
|
+
| `SessionStart` | `inject-morph-context.js` | Injects active feature spec into context (3000 char max) |
|
|
257
|
+
| `UserPromptSubmit` | `protect-spec-files.js` | Guards spec files at approval gates |
|
|
258
|
+
| `PreToolUse` | Bash guard (prompt type) | Detects destructive patterns inline |
|
|
259
|
+
| `PreToolUse` | `validate-feature-phase.js` | Validates phase transitions |
|
|
260
|
+
| `PostToolUse` | `track-output-creation.js` | Tracks feature output files as they are written |
|
|
261
|
+
| `PostToolUse` | `checkpoint-trigger.js` | Auto-checkpoints every 3 completed tasks |
|
|
262
|
+
| `PostToolUseFailure` | `handle-tool-failure.js` | Logs failures to `.morph/logs/tool-failures.log` |
|
|
263
|
+
| `Stop` | `session-summary.js` | Writes session summary on stop |
|
|
264
|
+
| `PreCompact` | `compact-context.js` | Preserves critical context before compaction |
|
|
265
|
+
| `Notification` | `morph-notify.js` | Routes approval gate notifications |
|
|
266
|
+
|
|
253
267
|
|
|
254
268
|
Protected files (via `permissions.deny`):
|
|
269
|
+
|
|
255
270
|
- `.morph/state.json` — never edited directly, CLI only
|
|
256
|
-
- `.morph/framework
|
|
271
|
+
- `.morph/framework/`** — read-only framework content
|
|
257
272
|
|
|
258
273
|
---
|
|
259
274
|
|
|
@@ -261,26 +276,30 @@ Protected files (via `permissions.deny`):
|
|
|
261
276
|
|
|
262
277
|
Path-scoped rules are installed to `.claude/rules/` and activate automatically based on file patterns:
|
|
263
278
|
|
|
264
|
-
|
|
265
|
-
|
|
266
|
-
|
|
|
267
|
-
| `
|
|
268
|
-
| `
|
|
269
|
-
| `
|
|
270
|
-
| `
|
|
279
|
+
|
|
280
|
+
| Rule file | Applies to |
|
|
281
|
+
| ----------------------------- | -------------------------------------------------------- |
|
|
282
|
+
| `morph-workflow.md` | Always active — spec-first mandate, phase commands |
|
|
283
|
+
| `csharp-standards.md` | `**/*.cs`, `**/*.csproj` |
|
|
284
|
+
| `frontend-standards.md` | `**/*.razor`, `**/*.tsx`, `**/*.ts`, `**/*.css` |
|
|
285
|
+
| `testing-standards.md` | `tests/**`, `**/*.test.*`, `**/*.spec.*`, `**/*Tests.cs` |
|
|
286
|
+
| `infrastructure-standards.md` | `**/*.bicep`, `**/Dockerfile`, `**/pipelines/**` |
|
|
287
|
+
|
|
271
288
|
|
|
272
289
|
---
|
|
273
290
|
|
|
274
291
|
## Stack support
|
|
275
292
|
|
|
276
|
-
|
|
277
|
-
|
|
278
|
-
|
|
|
279
|
-
|
|
|
280
|
-
|
|
|
281
|
-
|
|
|
282
|
-
|
|
|
283
|
-
|
|
|
293
|
+
|
|
294
|
+
| Technology | Support |
|
|
295
|
+
| ------------------------------------------- | ------------------------------------------------ |
|
|
296
|
+
| .NET 10 / ASP.NET Core | Full — C# contracts, EF Core, CQRS, Minimal API |
|
|
297
|
+
| Blazor (WebAssembly / Server / MAUI Hybrid) | Full — components, concurrency, design system |
|
|
298
|
+
| Next.js / React / TypeScript | Full — components, routing, state management |
|
|
299
|
+
| Azure (Bicep) | Full — IaC templates, cost estimation, pipelines |
|
|
300
|
+
| GitHub Actions | Full — CI/CD workflow templates |
|
|
301
|
+
| Supabase | Supported via MCP integration |
|
|
302
|
+
|
|
284
303
|
|
|
285
304
|
TypeScript strict mode is enforced by default. See `.morph/framework/standards/` for all coding standards.
|
|
286
305
|
|
|
@@ -290,9 +309,9 @@ TypeScript strict mode is enforced by default. See `.morph/framework/standards/`
|
|
|
290
309
|
|
|
291
310
|
To update the framework files in an existing project:
|
|
292
311
|
|
|
293
|
-
```bash
|
|
312
|
+
```bash
|
|
294
313
|
morph-spec update
|
|
295
|
-
|
|
314
|
+
```
|
|
296
315
|
|
|
297
316
|
This re-syncs `.morph/framework/`, `.claude/skills/`, `.claude/agents/`, `.claude/rules/`, and `CLAUDE.md` with the installed package version. Your `.morph/config/config.json`, `.morph/context/`, and feature outputs are not touched.
|
|
298
317
|
|
|
@@ -305,8 +324,9 @@ After updating, run `morph-spec doctor` to confirm the installation is healthy.
|
|
|
305
324
|
**Never skip phases.** Every feature starts with a proposal. No code is written until the design is approved and a task list exists.
|
|
306
325
|
|
|
307
326
|
**Never edit protected files directly:**
|
|
327
|
+
|
|
308
328
|
- `.morph/state.json` — use `morph-spec state set`
|
|
309
|
-
- `.morph/framework
|
|
329
|
+
- `.morph/framework/`** — read-only, updated by `morph-spec update`
|
|
310
330
|
|
|
311
331
|
**Always document decisions.** Each feature has a `1-design/decisions.md`. Architectural choices go there, not in commit messages.
|
|
312
332
|
|
|
@@ -320,24 +340,24 @@ After updating, run `morph-spec doctor` to confirm the installation is healthy.
|
|
|
320
340
|
|
|
321
341
|
If you are using nvm-windows or a Node version manager, the global bin path may not be on `PATH` in your shell. Use `npx` instead:
|
|
322
342
|
|
|
323
|
-
```bash
|
|
343
|
+
```bash
|
|
324
344
|
npx @polymorphism-tech/morph-spec init
|
|
325
|
-
|
|
345
|
+
```
|
|
326
346
|
|
|
327
347
|
Or add the npm global bin to your PATH:
|
|
328
348
|
|
|
329
|
-
```bash
|
|
349
|
+
```bash
|
|
330
350
|
npm config get prefix
|
|
331
351
|
# Add {prefix}/bin to your PATH
|
|
332
|
-
|
|
352
|
+
```
|
|
333
353
|
|
|
334
354
|
### `morph-spec doctor` reports issues
|
|
335
355
|
|
|
336
356
|
Run doctor to see all checks:
|
|
337
357
|
|
|
338
|
-
```bash
|
|
358
|
+
```bash
|
|
339
359
|
morph-spec doctor
|
|
340
|
-
|
|
360
|
+
```
|
|
341
361
|
|
|
342
362
|
Common fixes:
|
|
343
363
|
|
|
@@ -353,14 +373,14 @@ Windows may block global npm installs without elevated permissions. Options:
|
|
|
353
373
|
1. Run terminal as Administrator (not recommended long-term)
|
|
354
374
|
2. Change npm global prefix to a user-writable directory:
|
|
355
375
|
|
|
356
|
-
```bat
|
|
376
|
+
```bat
|
|
357
377
|
mkdir %APPDATA%\npm-global
|
|
358
378
|
npm config set prefix %APPDATA%\npm-global
|
|
359
379
|
:: Add %APPDATA%\npm-global to your PATH
|
|
360
380
|
npm install -g @polymorphism-tech/morph-spec
|
|
361
|
-
|
|
381
|
+
```
|
|
362
382
|
|
|
363
|
-
|
|
383
|
+
1. Use `npx` for all CLI invocations
|
|
364
384
|
|
|
365
385
|
### Hook not triggering on SessionStart
|
|
366
386
|
|
|
@@ -372,12 +392,12 @@ Ensure `.claude/settings.local.json` is not gitignored in your project. The file
|
|
|
372
392
|
|
|
373
393
|
The framework ships 74 registered standards across 11 categories. Browse them:
|
|
374
394
|
|
|
375
|
-
```bash
|
|
395
|
+
```bash
|
|
376
396
|
morph-spec standards --list
|
|
377
397
|
morph-spec standards --list --category csharp
|
|
378
398
|
morph-spec standards --search "strict mode"
|
|
379
399
|
morph-spec standards --show typescript-strict
|
|
380
|
-
|
|
400
|
+
```
|
|
381
401
|
|
|
382
402
|
Standards are stored in `.morph/framework/standards/STANDARDS.json` and sourced from `.morph/framework/standards/`.
|
|
383
403
|
|
|
@@ -391,4 +411,4 @@ Code generated by morph-spec (contracts, templates, implementation output) belon
|
|
|
391
411
|
|
|
392
412
|
---
|
|
393
413
|
|
|
394
|
-
*morph-spec v4.
|
|
414
|
+
*morph-spec v4.7.0 by [Polymorphism Tech](https://polymorphism.tech)*
|