synarcx 0.3.1 → 0.3.3
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 +307 -296
- package/dist/core/init.js +4 -1
- package/dist/core/migration.js +5 -5
- package/dist/core/profiles.d.ts +10 -2
- package/dist/core/profiles.js +20 -1
- package/dist/core/shared/skill-generation.js +12 -12
- package/dist/core/specs-apply.js +8 -3
- package/dist/core/templates/workflows/debug.js +20 -3
- package/dist/core/templates/workflows/refactor.js +58 -5
- package/dist/core/templates/workflows/review.js +324 -273
- package/dist/core/templates/workflows/sync.js +62 -18
- package/dist/core/update.d.ts +6 -0
- package/dist/core/update.js +25 -2
- package/package.json +1 -1
package/README.md
CHANGED
|
@@ -1,296 +1,307 @@
|
|
|
1
|
-
# SynArcX
|
|
2
|
-
|
|
3
|
-
  
|
|
4
|
-
|
|
5
|
-
> Structured engineering workflows for AI coding assistants — persistent project memory, spec-driven development, and architecture drift prevention across every session.
|
|
6
|
-
|
|
7
|
-
Works with **Claude Code, Cursor, GitHub Copilot, Cline, Windsurf, Codex**, and more AI coding tools.
|
|
8
|
-
|
|
9
|
-
---
|
|
10
|
-
|
|
11
|
-
## The Problem: Architecture Drift in AI-Assisted Development
|
|
12
|
-
|
|
13
|
-
AI coding assistants like Claude Code and Cursor lose context fast. Requirements live in chat history. Architecture decisions vanish between sessions. Generated code drifts from design intent.
|
|
14
|
-
|
|
15
|
-
Without an explicit workflow, AI-generated code gradually drifts from your architecture — each session introduces small misalignments that compound into structural debt. This is architecture drift, and it gets worse the longer the project runs.
|
|
16
|
-
|
|
17
|
-
SynArcX fixes this by adding a lightweight spec layer between you and your AI — so both you and the assistant agree on what to build before any code is written.
|
|
18
|
-
|
|
19
|
-
---
|
|
20
|
-
|
|
21
|
-
## Why Not Just Prompt Better?
|
|
22
|
-
|
|
23
|
-
Better prompts help, but they don't survive session resets, tool switches, or team handoffs. Every new session starts cold. Every new contributor re-explains the same constraints.
|
|
24
|
-
|
|
25
|
-
SynArcX makes your engineering decisions durable. The `constitution.md` is always there. The specs don't live in someone's chat history.
|
|
26
|
-
|
|
27
|
-
---
|
|
28
|
-
|
|
29
|
-
## Why Not Just Use Another Spec Format?
|
|
30
|
-
|
|
31
|
-
Spec formats describe *what* to build.
|
|
32
|
-
|
|
33
|
-
SynArcX structures *how you get there* from exploration to proposal to implementation, and helps keep AI-generated changes aligned with the evolving codebase at every stage, not just at planning time.
|
|
34
|
-
|
|
35
|
-
If you already have markdown specs in your repo, `/syn:sync` will incorporate them into the `constitution.md`.
|
|
36
|
-
|
|
37
|
-
---
|
|
38
|
-
|
|
39
|
-
## What Happens If You Ignore SynArcX?
|
|
40
|
-
|
|
41
|
-
Nothing breaks immediately. That's the problem.
|
|
42
|
-
|
|
43
|
-
```
|
|
44
|
-
Week 1 AI reads the codebase, builds the feature correctly.
|
|
45
|
-
|
|
46
|
-
Week 3 New session. AI re-derives context from code alone.
|
|
47
|
-
Small assumptions diverge from your actual design.
|
|
48
|
-
|
|
49
|
-
Week 6 Three sessions in. The auth module now does things
|
|
50
|
-
no spec ever said it should. The AI was "helpful."
|
|
51
|
-
|
|
52
|
-
Week 10 You're untangling AI-introduced architecture violations
|
|
53
|
-
instead of shipping features. The specs live in a chat
|
|
54
|
-
log nobody can find.
|
|
55
|
-
```
|
|
56
|
-
|
|
57
|
-
SynArcX makes the spec the source of truth, not the chat history.
|
|
58
|
-
|
|
59
|
-
---
|
|
60
|
-
|
|
61
|
-
## Install
|
|
62
|
-
|
|
63
|
-
Requires **Node.js 20+**
|
|
64
|
-
|
|
65
|
-
```bash
|
|
66
|
-
npm install -g synarcx
|
|
67
|
-
```
|
|
68
|
-
|
|
69
|
-
```bash
|
|
70
|
-
pnpm add -g synarcx
|
|
71
|
-
```
|
|
72
|
-
|
|
73
|
-
Verify:
|
|
74
|
-
|
|
75
|
-
```bash
|
|
76
|
-
synarcx --help
|
|
77
|
-
```
|
|
78
|
-
|
|
79
|
-
---
|
|
80
|
-
|
|
81
|
-
## Quick Start
|
|
82
|
-
|
|
83
|
-
```bash
|
|
84
|
-
cd your-project
|
|
85
|
-
synarcx init
|
|
86
|
-
```
|
|
87
|
-
|
|
88
|
-
Then in your AI coding tool:
|
|
89
|
-
|
|
90
|
-
1. `/syn:sync` — scan the project and generate the `constitution.md` (persistent project memory)
|
|
91
|
-
2. `/syn:explore "your idea"` — think through the problem with your AI
|
|
92
|
-
3. `/syn:propose "my-feature"` — create proposal, specs, design, and tasks in one step
|
|
93
|
-
4. `/syn:clarify` — sharpen artifacts with targeted questions + auto consistency check
|
|
94
|
-
5. `/syn:apply` — implement the tasks
|
|
95
|
-
6. `/syn:review` — verify implementation, run sanity checks,
|
|
96
|
-
|
|
97
|
-
For specific cases, use these instead of `/syn:explore`:
|
|
98
|
-
|
|
99
|
-
* For bugs: use `/syn:debug`.
|
|
100
|
-
* For structural improvements: use `/syn:refactor`.
|
|
101
|
-
* For small low-risk changes (typos, config tweaks): use `/syn:quick` with no artifacts, just apply.
|
|
102
|
-
|
|
103
|
-
---
|
|
104
|
-
|
|
105
|
-
## How It Works: Spec-Driven AI Coding Workflow
|
|
106
|
-
|
|
107
|
-
**Without SynArcX, development drift compounds silently:**
|
|
108
|
-
|
|
109
|
-
```
|
|
110
|
-
Session 1 ──► Session 2 ──► Session 3 ──► Session N
|
|
111
|
-
✓ correct ~ close ✗ diverged ✗✗ structural debt
|
|
112
|
-
(nobody noticed)
|
|
113
|
-
```
|
|
114
|
-
|
|
115
|
-
**With SynArcX — alignment is maintained explicitly:**
|
|
116
|
-
|
|
117
|
-
```
|
|
118
|
-
Session 1 ──► constitution.md ──► Session 2 ──► constitution.md ──► Session N
|
|
119
|
-
✓ correct (updated) ✓ correct (updated) ✓ correct
|
|
120
|
-
|
|
121
|
-
specs · architecture · intent preserved across every reset
|
|
122
|
-
```
|
|
123
|
-
|
|
124
|
-
---
|
|
125
|
-
|
|
126
|
-
**The workflow:**
|
|
127
|
-
|
|
128
|
-
```
|
|
129
|
-
|
|
130
|
-
|
|
131
|
-
explore ──┐
|
|
132
|
-
debug ──┤
|
|
133
|
-
|
|
134
|
-
│
|
|
135
|
-
refactor ──┘
|
|
136
|
-
|
|
137
|
-
|
|
138
|
-
|
|
139
|
-
|
|
140
|
-
|
|
141
|
-
|
|
142
|
-
|
|
143
|
-
|
|
144
|
-
|
|
145
|
-
|
|
146
|
-
|
|
147
|
-
|
|
148
|
-
|
|
149
|
-
|
|
150
|
-
|
|
151
|
-
|
|
152
|
-
|
|
153
|
-
|
|
154
|
-
|
|
155
|
-
|
|
156
|
-
|
|
157
|
-
|
|
158
|
-
|
|
159
|
-
|
|
160
|
-
|
|
161
|
-
|
|
162
|
-
|
|
163
|
-
|
|
164
|
-
|
|
165
|
-
```
|
|
166
|
-
|
|
167
|
-
|
|
168
|
-
|
|
169
|
-
|
|
170
|
-
|
|
171
|
-
|
|
172
|
-
|
|
173
|
-
|
|
174
|
-
|
|
175
|
-
|
|
176
|
-
##
|
|
177
|
-
-
|
|
178
|
-
|
|
179
|
-
|
|
180
|
-
|
|
181
|
-
|
|
182
|
-
|
|
183
|
-
|
|
184
|
-
|
|
185
|
-
|
|
186
|
-
|
|
187
|
-
|
|
188
|
-
|
|
189
|
-
|
|
190
|
-
|
|
191
|
-
|
|
192
|
-
|
|
193
|
-
|
|
194
|
-
|
|
195
|
-
|
|
196
|
-
|
|
|
197
|
-
|
|
|
198
|
-
|
|
199
|
-
|
|
200
|
-
|
|
201
|
-
|
|
202
|
-
|
|
203
|
-
|
|
|
204
|
-
|
|
|
205
|
-
| `
|
|
206
|
-
| `
|
|
207
|
-
| `
|
|
208
|
-
|
|
209
|
-
|
|
210
|
-
|
|
211
|
-
|
|
212
|
-
|
|
213
|
-
|
|
214
|
-
|
|
215
|
-
|
|
216
|
-
|
|
217
|
-
|
|
218
|
-
|
|
219
|
-
|
|
220
|
-
|
|
|
221
|
-
|
|
|
222
|
-
| `
|
|
223
|
-
| `
|
|
224
|
-
| `
|
|
225
|
-
|
|
226
|
-
|
|
227
|
-
|
|
228
|
-
Artifacts
|
|
229
|
-
|
|
230
|
-
|
|
231
|
-
|
|
232
|
-
|
|
233
|
-
|
|
234
|
-
|
|
|
235
|
-
|
|
|
236
|
-
|
|
|
237
|
-
|
|
|
238
|
-
|
|
|
239
|
-
|
|
240
|
-
|
|
241
|
-
|
|
242
|
-
|
|
243
|
-
|
|
244
|
-
|
|
245
|
-
|
|
246
|
-
|
|
247
|
-
|
|
248
|
-
|
|
249
|
-
|
|
250
|
-
|
|
251
|
-
|
|
252
|
-
|
|
253
|
-
|
|
254
|
-
|
|
255
|
-
|
|
256
|
-
|
|
257
|
-
|
|
258
|
-
|
|
259
|
-
|
|
260
|
-
|
|
261
|
-
|
|
262
|
-
|
|
263
|
-
|
|
264
|
-
|
|
265
|
-
|
|
266
|
-
|
|
267
|
-
|
|
268
|
-
|
|
269
|
-
|
|
270
|
-
|
|
271
|
-
-
|
|
272
|
-
-
|
|
273
|
-
-
|
|
274
|
-
|
|
275
|
-
|
|
276
|
-
|
|
277
|
-
|
|
278
|
-
|
|
279
|
-
|
|
280
|
-
|
|
281
|
-
|
|
282
|
-
|
|
283
|
-
|
|
284
|
-
|
|
285
|
-
|
|
286
|
-
|
|
287
|
-
|
|
288
|
-
|
|
289
|
-
|
|
290
|
-
|
|
291
|
-
|
|
292
|
-
|
|
293
|
-
|
|
294
|
-
|
|
295
|
-
|
|
296
|
-
|
|
1
|
+
# SynArcX
|
|
2
|
+
|
|
3
|
+
  
|
|
4
|
+
|
|
5
|
+
> Structured engineering workflows for AI coding assistants — persistent project memory, spec-driven development, and architecture drift prevention across every session.
|
|
6
|
+
|
|
7
|
+
Works with **Claude Code, Cursor, GitHub Copilot, Cline, Windsurf, Codex**, and more AI coding tools.
|
|
8
|
+
|
|
9
|
+
---
|
|
10
|
+
|
|
11
|
+
## The Problem: Architecture Drift in AI-Assisted Development
|
|
12
|
+
|
|
13
|
+
AI coding assistants like Claude Code and Cursor lose context fast. Requirements live in chat history. Architecture decisions vanish between sessions. Generated code drifts from design intent.
|
|
14
|
+
|
|
15
|
+
Without an explicit workflow, AI-generated code gradually drifts from your architecture — each session introduces small misalignments that compound into structural debt. This is architecture drift, and it gets worse the longer the project runs.
|
|
16
|
+
|
|
17
|
+
SynArcX fixes this by adding a lightweight spec layer between you and your AI — so both you and the assistant agree on what to build before any code is written.
|
|
18
|
+
|
|
19
|
+
---
|
|
20
|
+
|
|
21
|
+
## Why Not Just Prompt Better?
|
|
22
|
+
|
|
23
|
+
Better prompts help, but they don't survive session resets, tool switches, or team handoffs. Every new session starts cold. Every new contributor re-explains the same constraints.
|
|
24
|
+
|
|
25
|
+
SynArcX makes your engineering decisions durable. The `constitution.md` is always there. The specs don't live in someone's chat history.
|
|
26
|
+
|
|
27
|
+
---
|
|
28
|
+
|
|
29
|
+
## Why Not Just Use Another Spec Format?
|
|
30
|
+
|
|
31
|
+
Spec formats describe *what* to build.
|
|
32
|
+
|
|
33
|
+
SynArcX structures *how you get there* from exploration to proposal to implementation, and helps keep AI-generated changes aligned with the evolving codebase at every stage, not just at planning time.
|
|
34
|
+
|
|
35
|
+
If you already have markdown specs in your repo, `/syn:sync` will incorporate them into the `constitution.md`.
|
|
36
|
+
|
|
37
|
+
---
|
|
38
|
+
|
|
39
|
+
## What Happens If You Ignore SynArcX?
|
|
40
|
+
|
|
41
|
+
Nothing breaks immediately. That's the problem.
|
|
42
|
+
|
|
43
|
+
```
|
|
44
|
+
Week 1 AI reads the codebase, builds the feature correctly.
|
|
45
|
+
|
|
46
|
+
Week 3 New session. AI re-derives context from code alone.
|
|
47
|
+
Small assumptions diverge from your actual design.
|
|
48
|
+
|
|
49
|
+
Week 6 Three sessions in. The auth module now does things
|
|
50
|
+
no spec ever said it should. The AI was "helpful."
|
|
51
|
+
|
|
52
|
+
Week 10 You're untangling AI-introduced architecture violations
|
|
53
|
+
instead of shipping features. The specs live in a chat
|
|
54
|
+
log nobody can find.
|
|
55
|
+
```
|
|
56
|
+
|
|
57
|
+
SynArcX makes the spec the source of truth, not the chat history.
|
|
58
|
+
|
|
59
|
+
---
|
|
60
|
+
|
|
61
|
+
## Install
|
|
62
|
+
|
|
63
|
+
Requires **Node.js 20+**
|
|
64
|
+
|
|
65
|
+
```bash
|
|
66
|
+
npm install -g synarcx
|
|
67
|
+
```
|
|
68
|
+
|
|
69
|
+
```bash
|
|
70
|
+
pnpm add -g synarcx
|
|
71
|
+
```
|
|
72
|
+
|
|
73
|
+
Verify:
|
|
74
|
+
|
|
75
|
+
```bash
|
|
76
|
+
synarcx --help
|
|
77
|
+
```
|
|
78
|
+
|
|
79
|
+
---
|
|
80
|
+
|
|
81
|
+
## Quick Start
|
|
82
|
+
|
|
83
|
+
```bash
|
|
84
|
+
cd your-project
|
|
85
|
+
synarcx init
|
|
86
|
+
```
|
|
87
|
+
|
|
88
|
+
Then in your AI coding tool:
|
|
89
|
+
|
|
90
|
+
1. `/syn:sync` — scan the project and generate the `constitution.md` (persistent project memory)
|
|
91
|
+
2. `/syn:explore "your idea"` — think through the problem with your AI
|
|
92
|
+
3. `/syn:propose "my-feature"` — create proposal, specs, design, and tasks in one step
|
|
93
|
+
4. `/syn:clarify` — sharpen artifacts with targeted questions + auto consistency check
|
|
94
|
+
5. `/syn:apply` — implement the tasks
|
|
95
|
+
6. `/syn:review` — verify implementation, run sanity checks, then choose: archive (auto spec sync), add more work (scope-gated), or start a new change
|
|
96
|
+
|
|
97
|
+
For specific cases, use these instead of `/syn:explore`:
|
|
98
|
+
|
|
99
|
+
* For bugs: use `/syn:debug`.
|
|
100
|
+
* For structural improvements: use `/syn:refactor`.
|
|
101
|
+
* For small low-risk changes (typos, config tweaks): use `/syn:quick` with no artifacts, just apply.
|
|
102
|
+
|
|
103
|
+
---
|
|
104
|
+
|
|
105
|
+
## How It Works: Spec-Driven AI Coding Workflow
|
|
106
|
+
|
|
107
|
+
**Without SynArcX, development drift compounds silently:**
|
|
108
|
+
|
|
109
|
+
```
|
|
110
|
+
Session 1 ──► Session 2 ──► Session 3 ──► Session N
|
|
111
|
+
✓ correct ~ close ✗ diverged ✗✗ structural debt
|
|
112
|
+
(nobody noticed)
|
|
113
|
+
```
|
|
114
|
+
|
|
115
|
+
**With SynArcX — alignment is maintained explicitly:**
|
|
116
|
+
|
|
117
|
+
```
|
|
118
|
+
Session 1 ──► constitution.md ──► Session 2 ──► constitution.md ──► Session N
|
|
119
|
+
✓ correct (updated) ✓ correct (updated) ✓ correct
|
|
120
|
+
|
|
121
|
+
specs · architecture · intent preserved across every reset
|
|
122
|
+
```
|
|
123
|
+
|
|
124
|
+
---
|
|
125
|
+
|
|
126
|
+
**The workflow:**
|
|
127
|
+
|
|
128
|
+
```
|
|
129
|
+
quick ─────────────────────────────────────┐
|
|
130
|
+
│
|
|
131
|
+
explore ──┐ │
|
|
132
|
+
debug ──┤ ▼
|
|
133
|
+
├───► propose ──► clarify ──► apply ──► review
|
|
134
|
+
│ ▲ ▲ │
|
|
135
|
+
refactor ──┘ │ │ │
|
|
136
|
+
│ │ │
|
|
137
|
+
│ │ ┌───────────────┼───────────────┐
|
|
138
|
+
│ │ ▼ ▼ ▼
|
|
139
|
+
│ add more work new change archive
|
|
140
|
+
│ │ │
|
|
141
|
+
└─────────────────────────────────┘ ▼
|
|
142
|
+
sync ──────────────────────────────────────────────────────────► constitution
|
|
143
|
+
```
|
|
144
|
+
|
|
145
|
+
Each step suggests the next — you decide when to advance. Works in Claude Code, Cursor, Cline, and any AI coding tool that supports slash commands.
|
|
146
|
+
|
|
147
|
+
- `sync` generates the `constitution.md` — run once, re-run when the project shifts. Also runs a daily version check (prompts to auto-update) and checks for pending spec syncs from recently archived changes.
|
|
148
|
+
- `explore`, `debug`, and `refactor` are entry points that hand off to `propose`
|
|
149
|
+
- `quick` skips the pipeline for small, low-risk changes
|
|
150
|
+
- Run `synarcx update` in your terminal to refresh all skill and command files after installing a new version
|
|
151
|
+
- `review` is a three-way fork:
|
|
152
|
+
- **Archive now**: auto-syncs delta specs to main spec via `buildUpdatedSpec()`, writes `.pending-sync.json` marker, moves to archive. If spec sync fails, the change is already safely in archive; retry on next sync run.
|
|
153
|
+
- **Add more work**: scope gate reads proposal capabilities + design goals/non-goals. In-scope → update artifacts, MUST `/syn:clarify` then `/syn:apply` then `/syn:review` again (loop). Out-of-scope → offer archive then route to `/syn:propose`.
|
|
154
|
+
- **Start a new change**: routes to `/syn:propose`.
|
|
155
|
+
|
|
156
|
+
Each change gets its own folder under `synspec/changes/` with:
|
|
157
|
+
|
|
158
|
+
```
|
|
159
|
+
synspec/changes/my-feature/
|
|
160
|
+
├── proposal.md # what and why
|
|
161
|
+
├── design.md # how to build it
|
|
162
|
+
├── tasks.md # implementation checklist
|
|
163
|
+
└── specs/
|
|
164
|
+
└── *.md # what the system shall do
|
|
165
|
+
```
|
|
166
|
+
|
|
167
|
+
### Persistent Project Memory
|
|
168
|
+
|
|
169
|
+
`constitution.md` is the core of SynArcX. Generated by `/syn:sync`, it preserves architectural intent, conventions, constraints, and engineering decisions across AI sessions — keeping specifications, architecture, and implementation in sync.
|
|
170
|
+
|
|
171
|
+
Unlike documentation, the constitution is optimized for AI operational context — not human reading.
|
|
172
|
+
|
|
173
|
+
A typical `constitution.md` includes:
|
|
174
|
+
|
|
175
|
+
```markdown
|
|
176
|
+
## Architecture Principles
|
|
177
|
+
- All API routes are RESTful, no GraphQL
|
|
178
|
+
- Business logic lives in /services, not controllers
|
|
179
|
+
|
|
180
|
+
## Module Boundaries
|
|
181
|
+
- auth/ owns all token lifecycle — nothing else touches JWTs
|
|
182
|
+
|
|
183
|
+
## Known Pitfalls
|
|
184
|
+
- DB migrations must be backwards-compatible (rolling deploys)
|
|
185
|
+
|
|
186
|
+
## Coding Patterns
|
|
187
|
+
- Use Result<T, E> for fallible operations, never throw in services
|
|
188
|
+
```
|
|
189
|
+
|
|
190
|
+
---
|
|
191
|
+
|
|
192
|
+
## Commands
|
|
193
|
+
|
|
194
|
+
Used inside your AI coding tool (Claude Code, Cursor, Cline, etc.):
|
|
195
|
+
|
|
196
|
+
| Command | Description |
|
|
197
|
+
| ----------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
|
|
198
|
+
| `/syn:sync` | Scan project, run guardrail Q&A, generate/update `constitution.md`. Checks pending spec syncs from archived changes first. Auto-checks for synarcx updates once daily. |
|
|
199
|
+
| `/syn:explore` | Think through ideas, investigate problems, clarify requirements |
|
|
200
|
+
| `/syn:debug` | Diagnose a known error (3-phase analysis), then prompts `/syn:propose` |
|
|
201
|
+
| `/syn:refactor` | Map current vs target structure, then prompts `/syn:propose` |
|
|
202
|
+
| `/syn:quick` | Fast-path for small low-risk changes — inline preview, confirm, apply |
|
|
203
|
+
| `/syn:propose` | Create a new change with proposal, specs, design, and tasks |
|
|
204
|
+
| `/syn:clarify` | Targeted Q&A (adaptive limit) + auto consistency checks in one command |
|
|
205
|
+
| `/syn:analyze` | Standalone cross-artifact consistency check (auto-run by clarify) |
|
|
206
|
+
| `/syn:apply` | Implement tasks from a change's task list |
|
|
207
|
+
| `/syn:review` | Verify implementation, run sanity checks, and three-way fork: archive (auto spec sync), add more work (scope gate), or start new change |
|
|
208
|
+
|
|
209
|
+
### CLI Commands
|
|
210
|
+
|
|
211
|
+
Used in your terminal:
|
|
212
|
+
|
|
213
|
+
| Command | Description |
|
|
214
|
+
| ------------------- | ------------------------------------------------------------ |
|
|
215
|
+
| `synarcx init` | Set up SynArcX workflow structure in your repository |
|
|
216
|
+
| `synarcx update` | Refresh skill and command files for all configured tools |
|
|
217
|
+
| `synarcx sync` | Regenerate `constitution.md` |
|
|
218
|
+
| `synarcx explore` | Open explore session |
|
|
219
|
+
| `synarcx propose` | Create a structured change proposal |
|
|
220
|
+
| `synarcx clarify` | Targeted Q&A (adaptive limit) + auto consistency checks |
|
|
221
|
+
| `synarcx analyze` | Cross-artifact consistency check (standalone) |
|
|
222
|
+
| `synarcx apply` | Execute implementation tasks |
|
|
223
|
+
| `synarcx review` | Verify implementation, run sanity checks, archive when clean |
|
|
224
|
+
| `synarcx quick` | Fast-path execution for small changes |
|
|
225
|
+
|
|
226
|
+
---
|
|
227
|
+
|
|
228
|
+
## Artifacts
|
|
229
|
+
|
|
230
|
+
Each workflow stage produces explicit, reviewable files:
|
|
231
|
+
|
|
232
|
+
| Artifact | Purpose |
|
|
233
|
+
| ------------------- | -------------------------------------------------- |
|
|
234
|
+
| `proposal.md` | Problem framing : what, why, and scope |
|
|
235
|
+
| `specs/*.md` | Clarified requirements : what the system shall do |
|
|
236
|
+
| `design.md` | Architectural reasoning : how to build it |
|
|
237
|
+
| `tasks.md` | Implementation checklist |
|
|
238
|
+
| `constitution.md` | Persistent project memory for AI agents |
|
|
239
|
+
|
|
240
|
+
Artifacts create a traceable chain from requirements → reasoning → implementation → architecture decisions.
|
|
241
|
+
|
|
242
|
+
---
|
|
243
|
+
|
|
244
|
+
## SynArcX vs. Unstructured AI Coding
|
|
245
|
+
|
|
246
|
+
| Capability | AI Coding Without SynArcX | With SynArcX |
|
|
247
|
+
| ------------------------------------- | ------------------------- | ------------------------------------ |
|
|
248
|
+
| Persistent engineering memory | Lost between sessions | Preserved in `constitution.md` |
|
|
249
|
+
| Structured specification flow | Informal, chat-based | Explicit staged workflow |
|
|
250
|
+
| Architecture-aware changes | Inconsistent | Built into every step |
|
|
251
|
+
| Artifact traceability | None | Proposal → spec → design → tasks |
|
|
252
|
+
| Session continuity | Weak | Persistent across tools and sessions |
|
|
253
|
+
| Structured, traceable workflow stages | Rare | Core design |
|
|
254
|
+
| Low-risk fast path | Manual | `/syn:quick` |
|
|
255
|
+
|
|
256
|
+
---
|
|
257
|
+
|
|
258
|
+
## Supported AI Coding Tools
|
|
259
|
+
|
|
260
|
+
SynArcX works with Claude Code, Cursor, GitHub Copilot, Cline, Windsurf, Codex, Gemini, OpenCode, and more. Slash commands are generated per tool on `synarcx init` — each tool gets its own command syntax automatically.
|
|
261
|
+
|
|
262
|
+
---
|
|
263
|
+
|
|
264
|
+
## Built for AI-Assisted Software Engineering Teams
|
|
265
|
+
|
|
266
|
+
SynArcX is evolving toward an architecture-aware workflow system for long-running AI-assisted software engineering. It is designed for:
|
|
267
|
+
|
|
268
|
+
- long-running projects with evolving requirements
|
|
269
|
+
- architecture-sensitive systems where drift is costly
|
|
270
|
+
- AI-assisted engineering teams
|
|
271
|
+
- spec-driven development practices
|
|
272
|
+
- multi-session and multi-tool workflows
|
|
273
|
+
- controlled implementation pipelines
|
|
274
|
+
|
|
275
|
+
---
|
|
276
|
+
|
|
277
|
+
## Status
|
|
278
|
+
|
|
279
|
+
**v0.3.x** — `syn:review` three-way fork (archive with auto spec sync, scope-gated add-more-work, or start new change); `syn:sync` extended with pending spec sync backstop for recently archived changes; archive writes `.pending-sync.json` marker consumed by sync; atomic spec writes prevent half-written corruption; retroactive fix for broken main spec format; seamless upgrade from v0.2.x (auto-migrates to `core` profile)
|
|
280
|
+
|
|
281
|
+
Active development roadmap:
|
|
282
|
+
|
|
283
|
+
- stronger repository cognition
|
|
284
|
+
- architecture-aware execution validation
|
|
285
|
+
- context continuity across tool switches
|
|
286
|
+
- structured, traceable AI engineering pipelines
|
|
287
|
+
|
|
288
|
+
---
|
|
289
|
+
|
|
290
|
+
## Development
|
|
291
|
+
|
|
292
|
+
```bash
|
|
293
|
+
git clone https://github.com/funara/synarcx
|
|
294
|
+
cd synarcx
|
|
295
|
+
pnpm install
|
|
296
|
+
pnpm build
|
|
297
|
+
pnpm link --global
|
|
298
|
+
|
|
299
|
+
# rebuild after edits:
|
|
300
|
+
pnpm build
|
|
301
|
+
```
|
|
302
|
+
|
|
303
|
+
---
|
|
304
|
+
|
|
305
|
+
## License
|
|
306
|
+
|
|
307
|
+
MIT
|
package/dist/core/init.js
CHANGED
|
@@ -19,7 +19,7 @@ import { generateCommands, CommandAdapterRegistry, } from './command-generation/
|
|
|
19
19
|
import { detectLegacyArtifacts, cleanupLegacyArtifacts, formatCleanupSummary, formatDetectionSummary, } from './legacy-cleanup.js';
|
|
20
20
|
import { getToolsWithSkillsDir, getToolStates, getSkillTemplates, getCommandContents, generateSkillContent, } from './shared/index.js';
|
|
21
21
|
import { getGlobalConfig } from './global-config.js';
|
|
22
|
-
import { getProfileWorkflows } from './profiles.js';
|
|
22
|
+
import { getProfileWorkflows, syncNewCoreWorkflowsToCustomProfile } from './profiles.js';
|
|
23
23
|
import { DEFAULT_SCHEMA } from './shared/workflow-registry.js';
|
|
24
24
|
import { removeSkillDirs, removeCommandFiles } from './shared/artifact-cleanup.js';
|
|
25
25
|
import { getAvailableTools } from './available-tools.js';
|
|
@@ -60,6 +60,9 @@ export class InitCommand {
|
|
|
60
60
|
// Migration check: migrate existing projects to profile system (task 7.3)
|
|
61
61
|
if (extendMode) {
|
|
62
62
|
migrateIfNeeded(projectPath, detectedTools);
|
|
63
|
+
// Ensure custom-profile users receive any new commands added since their last init
|
|
64
|
+
// (e.g. syn:review added in 0.3.x). Runs after migration so the profile is settled.
|
|
65
|
+
syncNewCoreWorkflowsToCustomProfile(getGlobalConfig());
|
|
63
66
|
}
|
|
64
67
|
// Show animated welcome screen (interactive mode only)
|
|
65
68
|
const canPrompt = this.canPromptInteractively();
|