forgecraft-mcp 1.0.2 → 1.2.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/dist/tools/scaffold-spec-stubs.d.ts +43 -0
- package/dist/tools/scaffold-spec-stubs.d.ts.map +1 -1
- package/dist/tools/scaffold-spec-stubs.js +142 -0
- package/dist/tools/scaffold-spec-stubs.js.map +1 -1
- package/dist/tools/scaffold-writer.d.ts.map +1 -1
- package/dist/tools/scaffold-writer.js +11 -3
- package/dist/tools/scaffold-writer.js.map +1 -1
- package/package.json +1 -1
- package/templates/universal/instructions.yaml +82 -8
|
@@ -2,6 +2,8 @@
|
|
|
2
2
|
* scaffold-spec-stubs: Spec stub writers for scaffold_project.
|
|
3
3
|
*
|
|
4
4
|
* Manages UNFILLED stub documents that are detectable by check_cascade.
|
|
5
|
+
* Diagram stubs are structured (real Mermaid syntax with placeholder labels)
|
|
6
|
+
* so they function as grammar production rules from day one, not empty files.
|
|
5
7
|
*/
|
|
6
8
|
export declare const USE_CASES_STUB = "<!-- UNFILLED: Use Cases -->\n# Use Cases\n\n## UC-01: [Name]\n**Actor**: <!-- FILL: who? -->\n**Precondition**: <!-- FILL: what must be true before? -->\n**Steps**: <!-- FILL: numbered steps -->\n**Success**: <!-- FILL: what changed? -->\n\n## UC-02: [Name]\n<!-- FILL -->\n\n## UC-03: [Name]\n<!-- FILL -->\n";
|
|
7
9
|
/**
|
|
@@ -11,6 +13,47 @@ export declare const USE_CASES_STUB = "<!-- UNFILLED: Use Cases -->\n# Use Cases
|
|
|
11
13
|
* @returns Stub content with UNFILLED markers
|
|
12
14
|
*/
|
|
13
15
|
export declare function buildC4ContextStub(projectName: string): string;
|
|
16
|
+
/**
|
|
17
|
+
* Build the UNFILLED stub content for a sequence diagram.
|
|
18
|
+
*
|
|
19
|
+
* Emits a structured Mermaid sequenceDiagram with participant declarations and
|
|
20
|
+
* labelled message arrows — a real grammar production rule, not an empty file.
|
|
21
|
+
*
|
|
22
|
+
* @param feature - Human-readable feature name (e.g. "User Authentication")
|
|
23
|
+
* @returns Stub content with UNFILLED markers and structural Mermaid syntax
|
|
24
|
+
*/
|
|
25
|
+
export declare function buildSequenceDiagramStub(feature: string): string;
|
|
26
|
+
/**
|
|
27
|
+
* Build the UNFILLED stub content for a state machine diagram.
|
|
28
|
+
*
|
|
29
|
+
* Emits a stateDiagram-v2 with an initial transition, named states, transitions
|
|
30
|
+
* between them, and terminal states — a grammar that directly generates state
|
|
31
|
+
* transition test cases.
|
|
32
|
+
*
|
|
33
|
+
* @param entityName - Domain entity whose lifecycle is modelled (e.g. "Order")
|
|
34
|
+
* @returns Stub content with UNFILLED markers and structural Mermaid syntax
|
|
35
|
+
*/
|
|
36
|
+
export declare function buildStateMachineDiagramStub(entityName: string): string;
|
|
37
|
+
/**
|
|
38
|
+
* Build the UNFILLED stub content for a user flow / flowchart diagram.
|
|
39
|
+
*
|
|
40
|
+
* Emits a flowchart TD with Start/End rounded nodes, a decision diamond, and
|
|
41
|
+
* labelled edges — the script for E2E tests and user documentation in one artifact.
|
|
42
|
+
*
|
|
43
|
+
* @param ucName - Use case name (e.g. "UC-01: Register User")
|
|
44
|
+
* @returns Stub content with UNFILLED markers and structural Mermaid syntax
|
|
45
|
+
*/
|
|
46
|
+
export declare function buildFlowDiagramStub(ucName: string): string;
|
|
47
|
+
/**
|
|
48
|
+
* Build the UNFILLED stub content for a C4 Container diagram.
|
|
49
|
+
*
|
|
50
|
+
* Emits Container declarations and Rel statements for a multi-container system —
|
|
51
|
+
* the topology layer that C4 Context does not capture.
|
|
52
|
+
*
|
|
53
|
+
* @param projectName - Human-readable project name for the diagram title
|
|
54
|
+
* @returns Stub content with UNFILLED markers and structural Mermaid syntax
|
|
55
|
+
*/
|
|
56
|
+
export declare function buildC4ContainerStub(projectName: string): string;
|
|
14
57
|
/**
|
|
15
58
|
* Write a spec stub file. Only creates when the file does not exist, or when
|
|
16
59
|
* force=true AND the existing file still contains the UNFILLED marker.
|
|
@@ -1 +1 @@
|
|
|
1
|
-
{"version":3,"file":"scaffold-spec-stubs.d.ts","sourceRoot":"","sources":["../../src/tools/scaffold-spec-stubs.ts"],"names":[],"mappings":"AAAA
|
|
1
|
+
{"version":3,"file":"scaffold-spec-stubs.d.ts","sourceRoot":"","sources":["../../src/tools/scaffold-spec-stubs.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAKH,eAAO,MAAM,cAAc,2TAc1B,CAAC;AAEF;;;;;GAKG;AACH,wBAAgB,kBAAkB,CAAC,WAAW,EAAE,MAAM,GAAG,MAAM,CAY9D;AAED;;;;;;;;GAQG;AACH,wBAAgB,wBAAwB,CAAC,OAAO,EAAE,MAAM,GAAG,MAAM,CA4BhE;AAED;;;;;;;;;GASG;AACH,wBAAgB,4BAA4B,CAAC,UAAU,EAAE,MAAM,GAAG,MAAM,CA0BvE;AAED;;;;;;;;GAQG;AACH,wBAAgB,oBAAoB,CAAC,MAAM,EAAE,MAAM,GAAG,MAAM,CAyB3D;AAED;;;;;;;;GAQG;AACH,wBAAgB,oBAAoB,CAAC,WAAW,EAAE,MAAM,GAAG,MAAM,CAoBhE;AAED;;;;;;;;;;GAUG;AACH,wBAAgB,aAAa,CAC3B,YAAY,EAAE,MAAM,EACpB,QAAQ,EAAE,MAAM,EAChB,OAAO,EAAE,MAAM,EACf,KAAK,EAAE,OAAO,EACd,YAAY,EAAE,MAAM,EAAE,EACtB,YAAY,EAAE,MAAM,EAAE,GACrB,IAAI,CAgBN"}
|
|
@@ -2,6 +2,8 @@
|
|
|
2
2
|
* scaffold-spec-stubs: Spec stub writers for scaffold_project.
|
|
3
3
|
*
|
|
4
4
|
* Manages UNFILLED stub documents that are detectable by check_cascade.
|
|
5
|
+
* Diagram stubs are structured (real Mermaid syntax with placeholder labels)
|
|
6
|
+
* so they function as grammar production rules from day one, not empty files.
|
|
5
7
|
*/
|
|
6
8
|
import { existsSync, readFileSync, writeFileSync, mkdirSync } from "node:fs";
|
|
7
9
|
import { dirname } from "node:path";
|
|
@@ -39,6 +41,146 @@ C4Context
|
|
|
39
41
|
\`\`\`
|
|
40
42
|
`;
|
|
41
43
|
}
|
|
44
|
+
/**
|
|
45
|
+
* Build the UNFILLED stub content for a sequence diagram.
|
|
46
|
+
*
|
|
47
|
+
* Emits a structured Mermaid sequenceDiagram with participant declarations and
|
|
48
|
+
* labelled message arrows — a real grammar production rule, not an empty file.
|
|
49
|
+
*
|
|
50
|
+
* @param feature - Human-readable feature name (e.g. "User Authentication")
|
|
51
|
+
* @returns Stub content with UNFILLED markers and structural Mermaid syntax
|
|
52
|
+
*/
|
|
53
|
+
export function buildSequenceDiagramStub(feature) {
|
|
54
|
+
return `<!-- UNFILLED: Sequence Diagram — ${feature} -->
|
|
55
|
+
<!-- Replace participant labels and messages with real actors and contracts -->
|
|
56
|
+
# Sequence Diagram: ${feature}
|
|
57
|
+
|
|
58
|
+
\`\`\`mermaid
|
|
59
|
+
sequenceDiagram
|
|
60
|
+
participant Client as <!-- FILL: initiating actor, e.g. Browser / CLI / Service -->
|
|
61
|
+
participant API as <!-- FILL: entry-point service, e.g. API Gateway -->
|
|
62
|
+
participant Service as <!-- FILL: domain service, e.g. AuthService -->
|
|
63
|
+
participant Store as <!-- FILL: persistence layer, e.g. Database -->
|
|
64
|
+
|
|
65
|
+
Note over Client,Store: <!-- FILL: describe the primary flow in one sentence -->
|
|
66
|
+
|
|
67
|
+
Client->>API: <!-- FILL: request, e.g. POST /login {credentials} -->
|
|
68
|
+
API->>Service: <!-- FILL: delegate, e.g. authenticate(credentials) -->
|
|
69
|
+
Service->>Store: <!-- FILL: query, e.g. findUserByEmail(email) -->
|
|
70
|
+
Store-->>Service: <!-- FILL: result, e.g. User | null -->
|
|
71
|
+
|
|
72
|
+
alt <!-- FILL: failure case, e.g. User not found or wrong password -->
|
|
73
|
+
Service-->>API: <!-- FILL: error response, e.g. AuthError -->
|
|
74
|
+
API-->>Client: <!-- FILL: HTTP error, e.g. 401 Unauthorized -->
|
|
75
|
+
else <!-- FILL: success case -->
|
|
76
|
+
Service-->>API: <!-- FILL: success result, e.g. JWT token -->
|
|
77
|
+
API-->>Client: <!-- FILL: HTTP success, e.g. 200 OK {token} -->
|
|
78
|
+
end
|
|
79
|
+
\`\`\`
|
|
80
|
+
`;
|
|
81
|
+
}
|
|
82
|
+
/**
|
|
83
|
+
* Build the UNFILLED stub content for a state machine diagram.
|
|
84
|
+
*
|
|
85
|
+
* Emits a stateDiagram-v2 with an initial transition, named states, transitions
|
|
86
|
+
* between them, and terminal states — a grammar that directly generates state
|
|
87
|
+
* transition test cases.
|
|
88
|
+
*
|
|
89
|
+
* @param entityName - Domain entity whose lifecycle is modelled (e.g. "Order")
|
|
90
|
+
* @returns Stub content with UNFILLED markers and structural Mermaid syntax
|
|
91
|
+
*/
|
|
92
|
+
export function buildStateMachineDiagramStub(entityName) {
|
|
93
|
+
return `<!-- UNFILLED: State Machine — ${entityName} -->
|
|
94
|
+
<!-- Replace state names (Draft, Pending, Active, etc.) and transition labels -->
|
|
95
|
+
<!-- with the actual lifecycle states of your domain entity. -->
|
|
96
|
+
# State Machine: ${entityName}
|
|
97
|
+
|
|
98
|
+
\`\`\`mermaid
|
|
99
|
+
stateDiagram-v2
|
|
100
|
+
[*] --> Draft
|
|
101
|
+
|
|
102
|
+
Draft --> Pending: submit()
|
|
103
|
+
Pending --> Active: approve()
|
|
104
|
+
Pending --> Rejected: reject()
|
|
105
|
+
Active --> Completed: complete()
|
|
106
|
+
Active --> Cancelled: cancel()
|
|
107
|
+
|
|
108
|
+
Completed --> [*]
|
|
109
|
+
Rejected --> [*]
|
|
110
|
+
Cancelled --> [*]
|
|
111
|
+
|
|
112
|
+
note right of Active
|
|
113
|
+
FILL: add invariant or constraint
|
|
114
|
+
e.g. "requires valid payment method"
|
|
115
|
+
end note
|
|
116
|
+
\`\`\`
|
|
117
|
+
`;
|
|
118
|
+
}
|
|
119
|
+
/**
|
|
120
|
+
* Build the UNFILLED stub content for a user flow / flowchart diagram.
|
|
121
|
+
*
|
|
122
|
+
* Emits a flowchart TD with Start/End rounded nodes, a decision diamond, and
|
|
123
|
+
* labelled edges — the script for E2E tests and user documentation in one artifact.
|
|
124
|
+
*
|
|
125
|
+
* @param ucName - Use case name (e.g. "UC-01: Register User")
|
|
126
|
+
* @returns Stub content with UNFILLED markers and structural Mermaid syntax
|
|
127
|
+
*/
|
|
128
|
+
export function buildFlowDiagramStub(ucName) {
|
|
129
|
+
return `<!-- UNFILLED: Flow Diagram — ${ucName} -->
|
|
130
|
+
<!-- Replace node labels and edge conditions with real user journey steps -->
|
|
131
|
+
# Flow: ${ucName}
|
|
132
|
+
|
|
133
|
+
\`\`\`mermaid
|
|
134
|
+
flowchart TD
|
|
135
|
+
Start([<!-- FILL: trigger, e.g. User opens registration page -->])
|
|
136
|
+
|
|
137
|
+
Start --> Input[<!-- FILL: first action, e.g. Fill in name, email, password -->]
|
|
138
|
+
Input --> Validate{<!-- FILL: validation check, e.g. All fields valid? -->}
|
|
139
|
+
|
|
140
|
+
Validate -->|<!-- FILL: failure label, e.g. Invalid -->| Error[<!-- FILL: error action, e.g. Show validation errors -->]
|
|
141
|
+
Error --> Input
|
|
142
|
+
|
|
143
|
+
Validate -->|<!-- FILL: success label, e.g. Valid -->| Process[<!-- FILL: main action, e.g. Create account -->]
|
|
144
|
+
Process --> Check{<!-- FILL: guard check, e.g. Email already exists? -->}
|
|
145
|
+
|
|
146
|
+
Check -->|<!-- FILL: conflict label, e.g. Yes -->| Conflict[<!-- FILL: conflict action, e.g. Show duplicate email error -->]
|
|
147
|
+
Conflict --> End([<!-- FILL: exit label, e.g. User corrects email -->])
|
|
148
|
+
|
|
149
|
+
Check -->|<!-- FILL: proceed label, e.g. No -->| Success[<!-- FILL: success action, e.g. Send confirmation email -->]
|
|
150
|
+
Success --> End
|
|
151
|
+
\`\`\`
|
|
152
|
+
`;
|
|
153
|
+
}
|
|
154
|
+
/**
|
|
155
|
+
* Build the UNFILLED stub content for a C4 Container diagram.
|
|
156
|
+
*
|
|
157
|
+
* Emits Container declarations and Rel statements for a multi-container system —
|
|
158
|
+
* the topology layer that C4 Context does not capture.
|
|
159
|
+
*
|
|
160
|
+
* @param projectName - Human-readable project name for the diagram title
|
|
161
|
+
* @returns Stub content with UNFILLED markers and structural Mermaid syntax
|
|
162
|
+
*/
|
|
163
|
+
export function buildC4ContainerStub(projectName) {
|
|
164
|
+
return `<!-- UNFILLED: C4 Container Diagram -->
|
|
165
|
+
<!-- Replace container labels, technology fields, and relations with your stack -->
|
|
166
|
+
# Container Diagram — ${projectName}
|
|
167
|
+
|
|
168
|
+
\`\`\`mermaid
|
|
169
|
+
C4Container
|
|
170
|
+
title Container Diagram: ${projectName}
|
|
171
|
+
|
|
172
|
+
Person(user, "<!-- FILL: actor name -->", "<!-- FILL: actor description -->")
|
|
173
|
+
|
|
174
|
+
Container(web, "<!-- FILL: frontend name, e.g. Web Application -->", "<!-- FILL: technology, e.g. React -->", "<!-- FILL: responsibility -->")
|
|
175
|
+
Container(api, "<!-- FILL: backend name, e.g. API Server -->", "<!-- FILL: technology, e.g. Node.js / Express -->", "<!-- FILL: responsibility -->")
|
|
176
|
+
Container(db, "<!-- FILL: database name, e.g. Primary Database -->", "<!-- FILL: technology, e.g. PostgreSQL -->", "<!-- FILL: responsibility -->")
|
|
177
|
+
|
|
178
|
+
Rel(user, web, "<!-- FILL: interaction, e.g. Uses -->", "<!-- FILL: protocol, e.g. HTTPS -->")
|
|
179
|
+
Rel(web, api, "<!-- FILL: call, e.g. API calls -->", "<!-- FILL: protocol, e.g. REST / JSON -->")
|
|
180
|
+
Rel(api, db, "<!-- FILL: query, e.g. Reads and writes -->", "<!-- FILL: protocol, e.g. SQL -->")
|
|
181
|
+
\`\`\`
|
|
182
|
+
`;
|
|
183
|
+
}
|
|
42
184
|
/**
|
|
43
185
|
* Write a spec stub file. Only creates when the file does not exist, or when
|
|
44
186
|
* force=true AND the existing file still contains the UNFILLED marker.
|
|
@@ -1 +1 @@
|
|
|
1
|
-
{"version":3,"file":"scaffold-spec-stubs.js","sourceRoot":"","sources":["../../src/tools/scaffold-spec-stubs.ts"],"names":[],"mappings":"AAAA
|
|
1
|
+
{"version":3,"file":"scaffold-spec-stubs.js","sourceRoot":"","sources":["../../src/tools/scaffold-spec-stubs.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAEH,OAAO,EAAE,UAAU,EAAE,YAAY,EAAE,aAAa,EAAE,SAAS,EAAE,MAAM,SAAS,CAAC;AAC7E,OAAO,EAAE,OAAO,EAAE,MAAM,WAAW,CAAC;AAEpC,MAAM,CAAC,MAAM,cAAc,GAAG;;;;;;;;;;;;;;CAc7B,CAAC;AAEF;;;;;GAKG;AACH,MAAM,UAAU,kBAAkB,CAAC,WAAmB;IACpD,OAAO;;;;;0BAKiB,WAAW;;oBAEjB,WAAW;;;CAG9B,CAAC;AACF,CAAC;AAED;;;;;;;;GAQG;AACH,MAAM,UAAU,wBAAwB,CAAC,OAAe;IACtD,OAAO,qCAAqC,OAAO;;sBAE/B,OAAO;;;;;;;;;;;;;;;;;;;;;;;;CAwB5B,CAAC;AACF,CAAC;AAED;;;;;;;;;GASG;AACH,MAAM,UAAU,4BAA4B,CAAC,UAAkB;IAC7D,OAAO,kCAAkC,UAAU;;;mBAGlC,UAAU;;;;;;;;;;;;;;;;;;;;;CAqB5B,CAAC;AACF,CAAC;AAED;;;;;;;;GAQG;AACH,MAAM,UAAU,oBAAoB,CAAC,MAAc;IACjD,OAAO,iCAAiC,MAAM;;UAEtC,MAAM;;;;;;;;;;;;;;;;;;;;;CAqBf,CAAC;AACF,CAAC;AAED;;;;;;;;GAQG;AACH,MAAM,UAAU,oBAAoB,CAAC,WAAmB;IACtD,OAAO;;wBAEe,WAAW;;;;+BAIJ,WAAW;;;;;;;;;;;;CAYzC,CAAC;AACF,CAAC;AAED;;;;;;;;;;GAUG;AACH,MAAM,UAAU,aAAa,CAC3B,YAAoB,EACpB,QAAgB,EAChB,OAAe,EACf,KAAc,EACd,YAAsB,EACtB,YAAsB;IAEtB,SAAS,CAAC,OAAO,CAAC,QAAQ,CAAC,EAAE,EAAE,SAAS,EAAE,IAAI,EAAE,CAAC,CAAC;IAElD,IAAI,CAAC,UAAU,CAAC,QAAQ,CAAC,EAAE,CAAC;QAC1B,aAAa,CAAC,QAAQ,EAAE,OAAO,EAAE,OAAO,CAAC,CAAC;QAC1C,YAAY,CAAC,IAAI,CAAC,YAAY,CAAC,CAAC;QAChC,OAAO;IACT,CAAC;IAED,MAAM,QAAQ,GAAG,YAAY,CAAC,QAAQ,EAAE,OAAO,CAAC,CAAC;IACjD,IAAI,KAAK,IAAI,QAAQ,CAAC,QAAQ,CAAC,eAAe,CAAC,EAAE,CAAC;QAChD,aAAa,CAAC,QAAQ,EAAE,OAAO,EAAE,OAAO,CAAC,CAAC;QAC1C,YAAY,CAAC,IAAI,CAAC,YAAY,CAAC,CAAC;IAClC,CAAC;SAAM,CAAC;QACN,YAAY,CAAC,IAAI,CAAC,YAAY,CAAC,CAAC;IAClC,CAAC;AACH,CAAC"}
|
|
@@ -1 +1 @@
|
|
|
1
|
-
{"version":3,"file":"scaffold-writer.d.ts","sourceRoot":"","sources":["../../src/tools/scaffold-writer.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAIH,OAAO,KAAK,EAAE,gBAAgB,EAAgB,MAAM,oBAAoB,CAAC;AAEzE,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,yBAAyB,CAAC;AAEhE,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,yBAAyB,CAAC;AAK7D,OAAO,KAAK,EAAE,kBAAkB,EAAE,MAAM,gCAAgC,CAAC;
|
|
1
|
+
{"version":3,"file":"scaffold-writer.d.ts","sourceRoot":"","sources":["../../src/tools/scaffold-writer.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAIH,OAAO,KAAK,EAAE,gBAAgB,EAAgB,MAAM,oBAAoB,CAAC;AAEzE,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,yBAAyB,CAAC;AAEhE,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,yBAAyB,CAAC;AAK7D,OAAO,KAAK,EAAE,kBAAkB,EAAE,MAAM,gCAAgC,CAAC;AAoBzE,MAAM,WAAW,kBAAkB;IACjC,QAAQ,CAAC,WAAW,EAAE,MAAM,CAAC;IAC7B,QAAQ,CAAC,YAAY,EAAE,MAAM,CAAC;IAC9B,QAAQ,CAAC,QAAQ,EAAE,YAAY,GAAG,QAAQ,CAAC;IAC3C,QAAQ,CAAC,KAAK,EAAE,OAAO,CAAC;IACxB,QAAQ,CAAC,QAAQ,EAAE,OAAO,CAAC;IAC3B,QAAQ,CAAC,cAAc,EAAE,MAAM,EAAE,CAAC;CACnC;AAED,MAAM,WAAW,mBAAmB;IAClC,QAAQ,CAAC,YAAY,EAAE,MAAM,EAAE,CAAC;IAChC,QAAQ,CAAC,YAAY,EAAE,MAAM,EAAE,CAAC;CACjC;AAED;;;;;;;;;;;;GAYG;AACH,wBAAgB,kBAAkB,CAChC,KAAK,EAAE,kBAAkB,EACzB,QAAQ,EAAE,UAAU,CAAC,OAAO,gBAAgB,CAAC,EAC7C,OAAO,EAAE,aAAa,EACtB,eAAe,EAAE,MAAM,EACvB,UAAU,EAAE,MAAM,EAClB,eAAe,EAAE,MAAM,EACvB,kBAAkB,EAAE,kBAAkB,EACtC,UAAU,EAAE,gBAAgB,GAAG,IAAI,GAClC,mBAAmB,CAoOrB"}
|
|
@@ -12,7 +12,7 @@ import { writeFileIfMissing } from "../shared/filesystem.js";
|
|
|
12
12
|
import { ensureGateDirs } from "../shared/project-gates.js";
|
|
13
13
|
import { resolveTemplatePlaceholders } from "../shared/template-resolver.js";
|
|
14
14
|
import { PROJECT_SPECIFIC_TEMPLATE, EXCEPTIONS_TEMPLATE, PROJECT_GATES_TEMPLATE, renderAdrsReadme, renderGitignore, renderSmokeTestsReadme, renderLoadTestsReadme, } from "./scaffold-templates.js";
|
|
15
|
-
import { buildC4ContextStub, USE_CASES_STUB, writeSpecStub } from "./scaffold-spec-stubs.js";
|
|
15
|
+
import { buildC4ContextStub, buildC4ContainerStub, buildSequenceDiagramStub, buildStateMachineDiagramStub, buildFlowDiagramStub, USE_CASES_STUB, writeSpecStub, } from "./scaffold-spec-stubs.js";
|
|
16
16
|
/**
|
|
17
17
|
* Write all scaffold files for a project.
|
|
18
18
|
*
|
|
@@ -64,7 +64,9 @@ export function writeScaffoldFiles(input, composed, context, statusMdContent, pr
|
|
|
64
64
|
? join(input.project_dir, targetConfig.directory, targetConfig.filename)
|
|
65
65
|
: join(input.project_dir, targetConfig.filename);
|
|
66
66
|
mkdirSync(dirname(outputPath), { recursive: true });
|
|
67
|
-
const relativePath = targetConfig.directory
|
|
67
|
+
const relativePath = targetConfig.directory
|
|
68
|
+
? `${targetConfig.directory}/${targetConfig.filename}`
|
|
69
|
+
: targetConfig.filename;
|
|
68
70
|
trackWrite(relativePath, outputPath, resolveTemplatePlaceholders(content, placeholderContext));
|
|
69
71
|
}
|
|
70
72
|
}
|
|
@@ -73,6 +75,10 @@ export function writeScaffoldFiles(input, composed, context, statusMdContent, pr
|
|
|
73
75
|
trackWrite("docs/PRD.md", join(input.project_dir, "docs", "PRD.md"), prdContent);
|
|
74
76
|
trackWrite("docs/TechSpec.md", join(input.project_dir, "docs", "TechSpec.md"), techSpecContent);
|
|
75
77
|
writeSpecStub("docs/diagrams/c4-context.md", join(input.project_dir, "docs", "diagrams", "c4-context.md"), buildC4ContextStub(input.project_name), input.force, filesCreated, filesSkipped);
|
|
78
|
+
writeSpecStub("docs/diagrams/c4-container.md", join(input.project_dir, "docs", "diagrams", "c4-container.md"), buildC4ContainerStub(input.project_name), input.force, filesCreated, filesSkipped);
|
|
79
|
+
writeSpecStub("docs/diagrams/sequence-primary.md", join(input.project_dir, "docs", "diagrams", "sequence-primary.md"), buildSequenceDiagramStub("Primary Flow"), input.force, filesCreated, filesSkipped);
|
|
80
|
+
writeSpecStub("docs/diagrams/state-primary.md", join(input.project_dir, "docs", "diagrams", "state-primary.md"), buildStateMachineDiagramStub("Primary Entity"), input.force, filesCreated, filesSkipped);
|
|
81
|
+
writeSpecStub("docs/diagrams/flow-primary.md", join(input.project_dir, "docs", "diagrams", "flow-primary.md"), buildFlowDiagramStub("UC-01: Primary Use Case"), input.force, filesCreated, filesSkipped);
|
|
76
82
|
writeSpecStub("docs/use-cases.md", join(input.project_dir, "docs", "use-cases.md"), USE_CASES_STUB, input.force, filesCreated, filesSkipped);
|
|
77
83
|
const adrsDir = join(input.project_dir, "docs", "adrs");
|
|
78
84
|
mkdirSync(adrsDir, { recursive: true });
|
|
@@ -86,7 +92,9 @@ export function writeScaffoldFiles(input, composed, context, statusMdContent, pr
|
|
|
86
92
|
try {
|
|
87
93
|
chmodSync(hookPath, 0o755);
|
|
88
94
|
}
|
|
89
|
-
catch {
|
|
95
|
+
catch {
|
|
96
|
+
/* chmod may fail on Windows */
|
|
97
|
+
}
|
|
90
98
|
}
|
|
91
99
|
if (composed.skills.length > 0) {
|
|
92
100
|
const commandsDir = join(input.project_dir, ".claude", "commands");
|
|
@@ -1 +1 @@
|
|
|
1
|
-
{"version":3,"file":"scaffold-writer.js","sourceRoot":"","sources":["../../src/tools/scaffold-writer.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAEH,OAAO,EAAE,SAAS,EAAE,SAAS,EAAE,UAAU,EAAE,aAAa,EAAE,MAAM,SAAS,CAAC;AAC1E,OAAO,EAAE,IAAI,EAAE,OAAO,EAAE,MAAM,WAAW,CAAC;AAE1C,OAAO,EAAE,qBAAqB,EAAE,MAAM,oBAAoB,CAAC;AAE3D,OAAO,EAAE,qBAAqB,EAAE,WAAW,EAAE,MAAM,yBAAyB,CAAC;AAE7E,OAAO,EAAE,kBAAkB,EAAE,MAAM,kCAAkC,CAAC;AACtE,OAAO,EAAE,kBAAkB,EAAE,MAAM,yBAAyB,CAAC;AAC7D,OAAO,EAAE,cAAc,EAAE,MAAM,4BAA4B,CAAC;AAC5D,OAAO,EAAE,2BAA2B,EAAE,MAAM,gCAAgC,CAAC;AAE7E,OAAO,EACL,yBAAyB,EACzB,mBAAmB,EACnB,sBAAsB,EACtB,gBAAgB,EAChB,eAAe,EACf,sBAAsB,EACtB,qBAAqB,GACtB,MAAM,yBAAyB,CAAC;AACjC,OAAO,
|
|
1
|
+
{"version":3,"file":"scaffold-writer.js","sourceRoot":"","sources":["../../src/tools/scaffold-writer.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAEH,OAAO,EAAE,SAAS,EAAE,SAAS,EAAE,UAAU,EAAE,aAAa,EAAE,MAAM,SAAS,CAAC;AAC1E,OAAO,EAAE,IAAI,EAAE,OAAO,EAAE,MAAM,WAAW,CAAC;AAE1C,OAAO,EAAE,qBAAqB,EAAE,MAAM,oBAAoB,CAAC;AAE3D,OAAO,EAAE,qBAAqB,EAAE,WAAW,EAAE,MAAM,yBAAyB,CAAC;AAE7E,OAAO,EAAE,kBAAkB,EAAE,MAAM,kCAAkC,CAAC;AACtE,OAAO,EAAE,kBAAkB,EAAE,MAAM,yBAAyB,CAAC;AAC7D,OAAO,EAAE,cAAc,EAAE,MAAM,4BAA4B,CAAC;AAC5D,OAAO,EAAE,2BAA2B,EAAE,MAAM,gCAAgC,CAAC;AAE7E,OAAO,EACL,yBAAyB,EACzB,mBAAmB,EACnB,sBAAsB,EACtB,gBAAgB,EAChB,eAAe,EACf,sBAAsB,EACtB,qBAAqB,GACtB,MAAM,yBAAyB,CAAC;AACjC,OAAO,EACL,kBAAkB,EAClB,oBAAoB,EACpB,wBAAwB,EACxB,4BAA4B,EAC5B,oBAAoB,EACpB,cAAc,EACd,aAAa,GACd,MAAM,0BAA0B,CAAC;AAgBlC;;;;;;;;;;;;GAYG;AACH,MAAM,UAAU,kBAAkB,CAChC,KAAyB,EACzB,QAA6C,EAC7C,OAAsB,EACtB,eAAuB,EACvB,UAAkB,EAClB,eAAuB,EACvB,kBAAsC,EACtC,UAAmC;IAEnC,MAAM,YAAY,GAAa,EAAE,CAAC;IAClC,MAAM,YAAY,GAAa,EAAE,CAAC;IAClC,MAAM,aAAa,GAAG,KAAK,CAAC,cAAgC,CAAC;IAE7D,SAAS,UAAU,CACjB,YAAoB,EACpB,QAAgB,EAChB,OAAe;QAEf,MAAM,MAAM,GAAG,kBAAkB,CAAC,QAAQ,EAAE,OAAO,EAAE,KAAK,CAAC,KAAK,CAAC,CAAC;QAClE,IAAI,MAAM,KAAK,SAAS,EAAE,CAAC;YACzB,YAAY,CAAC,IAAI,CAAC,YAAY,CAAC,CAAC;QAClC,CAAC;aAAM,CAAC;YACN,YAAY,CAAC,IAAI,CAAC,YAAY,CAAC,CAAC;QAClC,CAAC;IACH,CAAC;IAED,KAAK,MAAM,KAAK,IAAI,QAAQ,CAAC,gBAAgB,EAAE,CAAC;QAC9C,MAAM,QAAQ,GAAG,IAAI,CAAC,KAAK,CAAC,WAAW,EAAE,KAAK,CAAC,IAAI,CAAC,CAAC;QACrD,IAAI,KAAK,CAAC,IAAI,KAAK,WAAW,EAAE,CAAC;YAC/B,SAAS,CAAC,QAAQ,EAAE,EAAE,SAAS,EAAE,IAAI,EAAE,CAAC,CAAC;YACzC,YAAY,CAAC,IAAI,CAAC,GAAG,KAAK,CAAC,IAAI,GAAG,CAAC,CAAC;QACtC,CAAC;IACH,CAAC;IAED,KAAK,MAAM,MAAM,IAAI,aAAa,EAAE,CAAC;QACnC,MAAM,YAAY,GAAG,qBAAqB,CAAC,MAAM,CAAC,CAAC;QACnD,IAAI,MAAM,KAAK,QAAQ,IAAI,KAAK,CAAC,QAAQ,KAAK,KAAK,EAAE,CAAC;YACpD,MAAM,aAAa,GAAG,kBAAkB,CACtC,QAAQ,CAAC,iBAAiB,EAC1B,OAAO,CACR,CAAC;YACF,KAAK,MAAM,IAAI,IAAI,aAAa,EAAE,CAAC;gBACjC,MAAM,QAAQ,GAAG,IAAI,CAAC,KAAK,CAAC,WAAW,EAAE,IAAI,CAAC,YAAY,CAAC,CAAC;gBAC5D,SAAS,CAAC,OAAO,CAAC,QAAQ,CAAC,EAAE,EAAE,SAAS,EAAE,IAAI,EAAE,CAAC,CAAC;gBAClD,UAAU,CACR,IAAI,CAAC,YAAY,EACjB,QAAQ,EACR,2BAA2B,CAAC,IAAI,CAAC,OAAO,EAAE,kBAAkB,CAAC,CAC9D,CAAC;YACJ,CAAC;YACD,MAAM,mBAAmB,GAAG,IAAI,CAC9B,KAAK,CAAC,WAAW,EACjB,SAAS,EACT,WAAW,EACX,qBAAqB,CACtB,CAAC;YACF,UAAU,CACR,uCAAuC,EACvC,mBAAmB,EACnB,yBAAyB,CAC1B,CAAC;QACJ,CAAC;aAAM,CAAC;YACN,MAAM,OAAO,GAAG,qBAAqB,CACnC,QAAQ,CAAC,iBAAiB,EAC1B,OAAO,EACP,MAAM,EACN,EAAE,OAAO,EAAE,UAAU,EAAE,OAAO,EAAE,CACjC,CAAC;YACF,MAAM,UAAU,GAAG,YAAY,CAAC,SAAS;gBACvC,CAAC,CAAC,IAAI,CAAC,KAAK,CAAC,WAAW,EAAE,YAAY,CAAC,SAAS,EAAE,YAAY,CAAC,QAAQ,CAAC;gBACxE,CAAC,CAAC,IAAI,CAAC,KAAK,CAAC,WAAW,EAAE,YAAY,CAAC,QAAQ,CAAC,CAAC;YACnD,SAAS,CAAC,OAAO,CAAC,UAAU,CAAC,EAAE,EAAE,SAAS,EAAE,IAAI,EAAE,CAAC,CAAC;YACpD,MAAM,YAAY,GAAG,YAAY,CAAC,SAAS;gBACzC,CAAC,CAAC,GAAG,YAAY,CAAC,SAAS,IAAI,YAAY,CAAC,QAAQ,EAAE;gBACtD,CAAC,CAAC,YAAY,CAAC,QAAQ,CAAC;YAC1B,UAAU,CACR,YAAY,EACZ,UAAU,EACV,2BAA2B,CAAC,OAAO,EAAE,kBAAkB,CAAC,CACzD,CAAC;QACJ,CAAC;IACH,CAAC;IAED,UAAU,CACR,WAAW,EACX,IAAI,CAAC,KAAK,CAAC,WAAW,EAAE,WAAW,CAAC,EACpC,eAAe,CAChB,CAAC;IAEF,SAAS,CAAC,IAAI,CAAC,KAAK,CAAC,WAAW,EAAE,MAAM,CAAC,EAAE,EAAE,SAAS,EAAE,IAAI,EAAE,CAAC,CAAC;IAChE,UAAU,CACR,aAAa,EACb,IAAI,CAAC,KAAK,CAAC,WAAW,EAAE,MAAM,EAAE,QAAQ,CAAC,EACzC,UAAU,CACX,CAAC;IACF,UAAU,CACR,kBAAkB,EAClB,IAAI,CAAC,KAAK,CAAC,WAAW,EAAE,MAAM,EAAE,aAAa,CAAC,EAC9C,eAAe,CAChB,CAAC;IAEF,aAAa,CACX,6BAA6B,EAC7B,IAAI,CAAC,KAAK,CAAC,WAAW,EAAE,MAAM,EAAE,UAAU,EAAE,eAAe,CAAC,EAC5D,kBAAkB,CAAC,KAAK,CAAC,YAAY,CAAC,EACtC,KAAK,CAAC,KAAK,EACX,YAAY,EACZ,YAAY,CACb,CAAC;IACF,aAAa,CACX,+BAA+B,EAC/B,IAAI,CAAC,KAAK,CAAC,WAAW,EAAE,MAAM,EAAE,UAAU,EAAE,iBAAiB,CAAC,EAC9D,oBAAoB,CAAC,KAAK,CAAC,YAAY,CAAC,EACxC,KAAK,CAAC,KAAK,EACX,YAAY,EACZ,YAAY,CACb,CAAC;IACF,aAAa,CACX,mCAAmC,EACnC,IAAI,CAAC,KAAK,CAAC,WAAW,EAAE,MAAM,EAAE,UAAU,EAAE,qBAAqB,CAAC,EAClE,wBAAwB,CAAC,cAAc,CAAC,EACxC,KAAK,CAAC,KAAK,EACX,YAAY,EACZ,YAAY,CACb,CAAC;IACF,aAAa,CACX,gCAAgC,EAChC,IAAI,CAAC,KAAK,CAAC,WAAW,EAAE,MAAM,EAAE,UAAU,EAAE,kBAAkB,CAAC,EAC/D,4BAA4B,CAAC,gBAAgB,CAAC,EAC9C,KAAK,CAAC,KAAK,EACX,YAAY,EACZ,YAAY,CACb,CAAC;IACF,aAAa,CACX,+BAA+B,EAC/B,IAAI,CAAC,KAAK,CAAC,WAAW,EAAE,MAAM,EAAE,UAAU,EAAE,iBAAiB,CAAC,EAC9D,oBAAoB,CAAC,yBAAyB,CAAC,EAC/C,KAAK,CAAC,KAAK,EACX,YAAY,EACZ,YAAY,CACb,CAAC;IACF,aAAa,CACX,mBAAmB,EACnB,IAAI,CAAC,KAAK,CAAC,WAAW,EAAE,MAAM,EAAE,cAAc,CAAC,EAC/C,cAAc,EACd,KAAK,CAAC,KAAK,EACX,YAAY,EACZ,YAAY,CACb,CAAC;IAEF,MAAM,OAAO,GAAG,IAAI,CAAC,KAAK,CAAC,WAAW,EAAE,MAAM,EAAE,MAAM,CAAC,CAAC;IACxD,SAAS,CAAC,OAAO,EAAE,EAAE,SAAS,EAAE,IAAI,EAAE,CAAC,CAAC;IACxC,UAAU,CACR,qBAAqB,EACrB,IAAI,CAAC,OAAO,EAAE,WAAW,CAAC,EAC1B,gBAAgB,CAAC,KAAK,CAAC,YAAY,CAAC,CACrC,CAAC;IAEF,UAAU,CACR,cAAc,EACd,IAAI,CAAC,KAAK,CAAC,WAAW,EAAE,cAAc,CAAC,EACvC,kFAAkF,CACnF,CAAC;IAEF,MAAM,QAAQ,GAAG,IAAI,CAAC,KAAK,CAAC,WAAW,EAAE,SAAS,EAAE,OAAO,CAAC,CAAC;IAC7D,SAAS,CAAC,QAAQ,EAAE,EAAE,SAAS,EAAE,IAAI,EAAE,CAAC,CAAC;IACzC,KAAK,MAAM,IAAI,IAAI,QAAQ,CAAC,KAAK,EAAE,CAAC;QAClC,MAAM,QAAQ,GAAG,IAAI,CAAC,QAAQ,EAAE,IAAI,CAAC,QAAQ,CAAC,CAAC;QAC/C,UAAU,CAAC,iBAAiB,IAAI,CAAC,QAAQ,EAAE,EAAE,QAAQ,EAAE,IAAI,CAAC,MAAM,CAAC,CAAC;QACpE,IAAI,CAAC;YACH,SAAS,CAAC,QAAQ,EAAE,KAAK,CAAC,CAAC;QAC7B,CAAC;QAAC,MAAM,CAAC;YACP,+BAA+B;QACjC,CAAC;IACH,CAAC;IAED,IAAI,QAAQ,CAAC,MAAM,CAAC,MAAM,GAAG,CAAC,EAAE,CAAC;QAC/B,MAAM,WAAW,GAAG,IAAI,CAAC,KAAK,CAAC,WAAW,EAAE,SAAS,EAAE,UAAU,CAAC,CAAC;QACnE,SAAS,CAAC,WAAW,EAAE,EAAE,SAAS,EAAE,IAAI,EAAE,CAAC,CAAC;QAC5C,KAAK,MAAM,KAAK,IAAI,QAAQ,CAAC,MAAM,EAAE,CAAC;YACpC,MAAM,YAAY,GAAG,WAAW,CAAC,KAAK,CAAC,OAAO,EAAE,OAAO,CAAC,CAAC;YACzD,MAAM,SAAS,GAAG,IAAI,CAAC,WAAW,EAAE,KAAK,CAAC,QAAQ,CAAC,CAAC;YACpD,UAAU,CAAC,oBAAoB,KAAK,CAAC,QAAQ,EAAE,EAAE,SAAS,EAAE,YAAY,CAAC,CAAC;QAC5E,CAAC;IACH,CAAC;IAED,UAAU,CACR,YAAY,EACZ,IAAI,CAAC,KAAK,CAAC,WAAW,EAAE,YAAY,CAAC,EACrC,eAAe,CAAC,KAAK,CAAC,QAAQ,CAAC,CAChC,CAAC;IAEF,MAAM,aAAa,GAAG,IAAI,CAAC,KAAK,CAAC,WAAW,EAAE,aAAa,CAAC,CAAC;IAC7D,SAAS,CAAC,aAAa,EAAE,EAAE,SAAS,EAAE,IAAI,EAAE,CAAC,CAAC;IAC9C,MAAM,cAAc,GAAG,IAAI,CAAC,aAAa,EAAE,iBAAiB,CAAC,CAAC;IAC9D,IAAI,CAAC,UAAU,CAAC,cAAc,CAAC,EAAE,CAAC;QAChC,aAAa,CAAC,cAAc,EAAE,mBAAmB,EAAE,OAAO,CAAC,CAAC;QAC5D,YAAY,CAAC,IAAI,CAAC,6BAA6B,CAAC,CAAC;IACnD,CAAC;SAAM,CAAC;QACN,YAAY,CAAC,IAAI,CAAC,6BAA6B,CAAC,CAAC;IACnD,CAAC;IAED,MAAM,gBAAgB,GAAG,IAAI,CAAC,aAAa,EAAE,oBAAoB,CAAC,CAAC;IACnE,IAAI,CAAC,UAAU,CAAC,gBAAgB,CAAC,EAAE,CAAC;QAClC,aAAa,CAAC,gBAAgB,EAAE,sBAAsB,EAAE,OAAO,CAAC,CAAC;QACjE,YAAY,CAAC,IAAI,CAAC,gCAAgC,CAAC,CAAC;IACtD,CAAC;SAAM,CAAC;QACN,YAAY,CAAC,IAAI,CAAC,gCAAgC,CAAC,CAAC;IACtD,CAAC;IACD,cAAc,CAAC,KAAK,CAAC,WAAW,CAAC,CAAC;IAElC,IAAI,UAAU,EAAE,UAAU,EAAE,CAAC;QAC3B,MAAM,QAAQ,GAAG,IAAI,CAAC,KAAK,CAAC,WAAW,EAAE,OAAO,EAAE,OAAO,CAAC,CAAC;QAC3D,MAAM,OAAO,GAAG,IAAI,CAAC,KAAK,CAAC,WAAW,EAAE,OAAO,EAAE,MAAM,CAAC,CAAC;QACzD,MAAM,UAAU,GAAG,IAAI,CAAC,KAAK,CAAC,WAAW,EAAE,aAAa,EAAE,SAAS,CAAC,CAAC;QACrE,SAAS,CAAC,QAAQ,EAAE,EAAE,SAAS,EAAE,IAAI,EAAE,CAAC,CAAC;QACzC,SAAS,CAAC,OAAO,EAAE,EAAE,SAAS,EAAE,IAAI,EAAE,CAAC,CAAC;QACxC,SAAS,CAAC,UAAU,EAAE,EAAE,SAAS,EAAE,IAAI,EAAE,CAAC,CAAC;QAC3C,UAAU,CACR,uBAAuB,EACvB,IAAI,CAAC,QAAQ,EAAE,WAAW,CAAC,EAC3B,sBAAsB,CAAC,UAAU,CAAC,UAAU,CAAC,CAC9C,CAAC;QACF,UAAU,CACR,sBAAsB,EACtB,IAAI,CAAC,OAAO,EAAE,WAAW,CAAC,EAC1B,qBAAqB,CAAC,UAAU,CAAC,UAAU,CAAC,CAC7C,CAAC;QACF,UAAU,CACR,8BAA8B,EAC9B,IAAI,CAAC,UAAU,EAAE,UAAU,CAAC,EAC5B,EAAE,CACH,CAAC;IACJ,CAAC;IAED,OAAO,EAAE,YAAY,EAAE,YAAY,EAAE,CAAC;AACxC,CAAC"}
|
package/package.json
CHANGED
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
{
|
|
2
2
|
"name": "forgecraft-mcp",
|
|
3
|
-
"version": "1.0
|
|
3
|
+
"version": "1.2.0",
|
|
4
4
|
"mcpName": "io.github.jghiringhelli/forgecraft",
|
|
5
5
|
"description": "CLI + MCP sentinel for engineering standards — SOLID, testing, architecture, CI/CD — auto-tailored to your stack. Minimal MCP footprint (~200 tokens) via CLI-first design.",
|
|
6
6
|
"type": "module",
|
|
@@ -891,10 +891,14 @@ blocks:
|
|
|
891
891
|
Update the following in order — skip any that do not exist in this project:
|
|
892
892
|
1. **spec.md** — update the relevant feature section (APIs, behavior, contract changes)
|
|
893
893
|
2. **docs/adrs/** — add an ADR if a new architectural decision was made
|
|
894
|
-
3. **docs/diagrams/c4-*.md** — update
|
|
895
|
-
or external dependency was added
|
|
896
|
-
|
|
897
|
-
|
|
894
|
+
3. **docs/diagrams/c4-*.md** — update `c4-context.md` or `c4-container.md` if a new
|
|
895
|
+
module, container, or external dependency was added. Diagrams must be written to disk
|
|
896
|
+
as fenced Mermaid blocks — updating prose that references a diagram is not an update.
|
|
897
|
+
4. **docs/diagrams/sequence-*.md / state-*.md / flow-*.md** — update or create the
|
|
898
|
+
relevant diagram file for the changed surface. Sequence diagrams must name real
|
|
899
|
+
participants; state diagrams must name real states and transitions; flow diagrams must
|
|
900
|
+
have entry/exit nodes and decision diamonds. A file containing only `<!-- UNFILLED -->`
|
|
901
|
+
markers is a specification gap, not a completed diagram.
|
|
898
902
|
5. **docs/TechSpec.md** — update module list, API reference, or technology choice sections
|
|
899
903
|
6. **docs/use-cases.md** — update or add use cases if new actor interactions were introduced
|
|
900
904
|
7. **Status.md** — always update: what changed, current state, next steps
|
|
@@ -929,6 +933,69 @@ blocks:
|
|
|
929
933
|
- **Bias toward explicit over clever** — readability wins over brevity.
|
|
930
934
|
- When in doubt, ask rather than assume.
|
|
931
935
|
|
|
936
|
+
- id: agent-mechanics
|
|
937
|
+
tier: core
|
|
938
|
+
title: "Agent Mechanical Constraints"
|
|
939
|
+
content: |
|
|
940
|
+
## Agent Mechanical Constraints — Non-Negotiable Overrides
|
|
941
|
+
|
|
942
|
+
These rules exist because the model has hard constraints that silently produce wrong
|
|
943
|
+
results without them. Each override targets a specific failure mode observed in practice.
|
|
944
|
+
|
|
945
|
+
### 1. Step 0 — Dead Code First
|
|
946
|
+
Before ANY structural refactor on a file > 300 LOC:
|
|
947
|
+
1. Delete all dead props, unused exports, unused imports, and debug logs.
|
|
948
|
+
2. Commit that cleanup separately under `chore(scope): strip dead code`.
|
|
949
|
+
3. Only then begin the real work.
|
|
950
|
+
Dead code accelerates context compaction. Every orphaned import is budget spent on
|
|
951
|
+
tokens that contribute nothing to the task.
|
|
952
|
+
|
|
953
|
+
### 2. Phase Limit — 5 Files Maximum
|
|
954
|
+
Never attempt multi-file refactors in a single response. Break work into explicit phases.
|
|
955
|
+
Each phase must touch **no more than 5 files**. Complete Phase N, verify it compiles and
|
|
956
|
+
all tests pass, then wait for explicit approval before Phase N+1.
|
|
957
|
+
Why: context compaction fires around 167K tokens and discards all intermediate reasoning,
|
|
958
|
+
file reads, and decision chains. Keeping phases small prevents mid-task compaction.
|
|
959
|
+
|
|
960
|
+
### 3. Senior Dev Override
|
|
961
|
+
The model's default system-level directives instruct it to "try the simplest approach
|
|
962
|
+
first" and "avoid refactoring beyond what was asked." These are active constraints that
|
|
963
|
+
fight your intent on architectural tasks.
|
|
964
|
+
**Override them explicitly** when quality requires it:
|
|
965
|
+
> "What would a senior, experienced, perfectionist dev reject in code review? Fix all of it."
|
|
966
|
+
This reframes what "done" means. System-level brevity mandates yield to an explicit
|
|
967
|
+
quality bar stated in the prompt.
|
|
968
|
+
|
|
969
|
+
### 4. Sub-Agent Parallelism for Large Tasks
|
|
970
|
+
For tasks spanning > 5 independent files, **launch parallel sub-agents** (5–8 files per
|
|
971
|
+
agent). Each agent gets its own isolated context window and compaction cycle.
|
|
972
|
+
Sequential processing of large tasks guarantees context decay by the later files.
|
|
973
|
+
Batching into parallel agents multiplies the effective working memory proportionally.
|
|
974
|
+
|
|
975
|
+
### 5. File Read Budget — 2,000-Line Cap
|
|
976
|
+
Each file read is hard-capped at 2,000 lines. Everything past that is silently truncated.
|
|
977
|
+
The model does not know what it didn't see — it will hallucinate the rest.
|
|
978
|
+
**For any file over 500 LOC**: read in sequential chunks using `offset` and `limit`
|
|
979
|
+
parameters. Never assume a single read captured the full file.
|
|
980
|
+
|
|
981
|
+
### 6. Tool Result Truncation
|
|
982
|
+
Tool results exceeding ~50,000 characters are truncated to a 2,000-byte preview.
|
|
983
|
+
The model works from the preview and does not know results were cut.
|
|
984
|
+
If any search returns suspiciously few results: re-run it with narrower scope
|
|
985
|
+
(single directory, stricter glob). State explicitly when truncation may have occurred.
|
|
986
|
+
|
|
987
|
+
### 7. Grep Is Not an AST
|
|
988
|
+
`grep` is raw text pattern matching. It cannot distinguish a function call from a
|
|
989
|
+
comment, a type reference from a string literal, or an import from one module vs another.
|
|
990
|
+
On any rename or signature change, search **separately** for:
|
|
991
|
+
- Direct calls and references
|
|
992
|
+
- Type-level references (interfaces, generics, `typeof`)
|
|
993
|
+
- String literals containing the name
|
|
994
|
+
- Dynamic imports and `require()` calls
|
|
995
|
+
- Re-exports and barrel file entries (`index.ts`, `__init__.py`)
|
|
996
|
+
- Test files and mocks
|
|
997
|
+
Never assume a single grep caught everything. Verify or expect regressions.
|
|
998
|
+
|
|
932
999
|
- id: code-generation-verification
|
|
933
1000
|
tier: core
|
|
934
1001
|
title: "Code Generation — Self-Verify Loop"
|
|
@@ -1211,10 +1278,10 @@ blocks:
|
|
|
1211
1278
|
|---|---|---|
|
|
1212
1279
|
| **Architectural constitution** (`CLAUDE.md` / `AGENTS.md` / `.cursor/rules/` / `.github/copilot-instructions.md`) | Defines what is and is not a valid sentence in this system. Governs every AI interaction. Agent-agnostic concept; filename is agent-specific. | Core |
|
|
1213
1280
|
| **Architecture Decision Records (ADRs)** | Documents why the grammar evolved. Prevents the AI from "correcting" intentional decisions that appear suboptimal without context. | Core |
|
|
1214
|
-
| **C4 diagrams / structural diagrams** (PlantUML, Mermaid) | The parsed structural representation: system context, container topology, component composition. Static structure at a glance for any agent entering the codebase. | Recommended |
|
|
1215
|
-
| **Sequence diagrams** | Fix the inter-component protocol: which call, in which order, with which contracts. A sequence diagram specifying that auth precedes data fetch is an unambiguous ordering constraint. The AI has two valid sentences: the one matching the diagram, and deviations from it. | Recommended |
|
|
1216
|
-
| **State machine diagrams** | Enumerate every valid state and every valid transition. Directly generate state transition test cases and user-facing modal behavior documentation. | When system has states |
|
|
1217
|
-
| **User flow diagrams** | Define the expected journey from entry to outcome. Simultaneously the script for every E2E test in that flow and the user journey narrative for the manual. | Recommended |
|
|
1281
|
+
| **C4 diagrams / structural diagrams** (PlantUML, Mermaid) | The parsed structural representation: system context, container topology, component composition. Static structure at a glance for any agent entering the codebase. **Emit as files in P1** — `docs/diagrams/c4-context.md` and `docs/diagrams/c4-container.md`. A diagram referenced in prose but not written to disk provides zero structural constraint. | Recommended |
|
|
1282
|
+
| **Sequence diagrams** | Fix the inter-component protocol: which call, in which order, with which contracts. A sequence diagram specifying that auth precedes data fetch is an unambiguous ordering constraint. The AI has two valid sentences: the one matching the diagram, and deviations from it. **Emit as `docs/diagrams/sequence-[feature].md` in P1** with real `participant` declarations and message arrows — not an empty file. | Recommended |
|
|
1283
|
+
| **State machine diagrams** | Enumerate every valid state and every valid transition. Directly generate state transition test cases and user-facing modal behavior documentation. **Emit as `docs/diagrams/state-[entity].md` in P1** with real `stateDiagram-v2` states and transitions — these become the source of truth for state transition tests. | When system has states |
|
|
1284
|
+
| **User flow diagrams** | Define the expected journey from entry to outcome. Simultaneously the script for every E2E test in that flow and the user journey narrative for the manual. **Emit as `docs/diagrams/flow-[usecase].md` in P1** with real `flowchart` Start/End nodes and decision diamonds. | Recommended |
|
|
1218
1285
|
| **Use cases** | Single, precise descriptions of an interaction. One use case seeds three artifacts: implementation contract, acceptance test, user documentation. See `use-case-triple-derivation`. | Recommended |
|
|
1219
1286
|
| **Schema definitions** (DB, API, events) | The vocabulary of the system with constraints formally stated. Types, relations, validation rules, value ranges. | Core |
|
|
1220
1287
|
| **Living documentation** (derived) | OpenAPI from decorators/schemas; TypeDoc/JSDoc auto-published; Storybook from component specs; README sections from centralized specs. Documentation maintained separately from code drifts — documentation derived from the same artifacts cannot be wrong in a way the code is right. | Recommended |
|
|
@@ -1226,6 +1293,13 @@ blocks:
|
|
|
1226
1293
|
| **Status.md** | Session bridge: current implementation state, what was completed, where the session stopped, what was tried. The Auditable property requires both that the record exists and that the next session begins by reading it. | Core |
|
|
1227
1294
|
| **MCP tools and environment tooling** | The tools available to the agent define what operations are possible. Bounded tool access is bounded agency. Specification governs not just code but the system that can act. | Optional |
|
|
1228
1295
|
|
|
1296
|
+
> **Emit, Don't Reference.** Every diagram type above that is marked "Recommended" or
|
|
1297
|
+
> higher must be written as a file on disk with real, parseable content. A spec that
|
|
1298
|
+
> says "a sequence diagram should be created later" is not a grammar production rule — it
|
|
1299
|
+
> is a forward reference. Forward references do not constrain the AI. Only emitted files
|
|
1300
|
+
> do. If a diagram file exists but still contains `<!-- UNFILLED -->`, it is a known gap.
|
|
1301
|
+
> Known gaps must be on the cascade backlog; they are not acceptable as a final state.
|
|
1302
|
+
|
|
1229
1303
|
### The Six Properties (self-test)
|
|
1230
1304
|
A generative specification satisfies all six. Use as an inspection checklist:
|
|
1231
1305
|
- **Self-describing**: Does the system explain its own architecture, decisions, and conventions from its own artifacts?
|