archik 0.12.38 → 0.12.39
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 +175 -132
- package/package.json +1 -1
package/README.md
CHANGED
|
@@ -5,7 +5,8 @@
|
|
|
5
5
|
<h1 align="center">archik</h1>
|
|
6
6
|
|
|
7
7
|
<p align="center">
|
|
8
|
-
<em>
|
|
8
|
+
<em>Architecture-as-code your AI editor actually reads —<br/>
|
|
9
|
+
with use cases, sequence diagrams, and tests wired end-to-end.</em>
|
|
9
10
|
</p>
|
|
10
11
|
|
|
11
12
|
[](https://www.npmjs.com/package/archik)
|
|
@@ -20,26 +21,30 @@
|
|
|
20
21
|
<img src="https://cdn.jsdelivr.net/npm/archik/docs/hero.svg?v=2" alt="Sample Archik diagram of an LLM-assisted support system" width="780">
|
|
21
22
|
</p>
|
|
22
23
|
|
|
23
|
-
|
|
24
|
-
describes what the system actually looks like. Services, databases,
|
|
25
|
-
queues, agents, LLMs, the edges between them. Plain YAML, schema-
|
|
26
|
-
validated, no coordinates, no proprietary format.
|
|
24
|
+
## The problems this fixes
|
|
27
25
|
|
|
28
|
-
|
|
29
|
-
self-contained SVG. The [Claude Code skill and `/archik:*` slash
|
|
30
|
-
commands](#for-claude-code--other-llms) install automatically with
|
|
31
|
-
`archik init`, so the model edits the same file you do — *the
|
|
32
|
-
diagram and the codebase stop drifting because Claude treats the
|
|
33
|
-
diagram as the spec*.
|
|
26
|
+
If you've ever:
|
|
34
27
|
|
|
35
|
-
|
|
36
|
-
|
|
37
|
-
|
|
38
|
-
|
|
28
|
+
- Asked an AI agent **"where would I add X?"** and watched it guess from filenames
|
|
29
|
+
- Shipped a feature and realised **the architecture doc hasn't been right since 2023**
|
|
30
|
+
- Tried to answer **"are we done?"** and gotten back vibes instead of evidence
|
|
31
|
+
- Watched a diagram drift from the code because **someone dragged a box and forgot to write it down**
|
|
39
32
|
|
|
40
|
-
|
|
33
|
+
…then you know the gap. archik closes it with one YAML file as the spec, a CLI that's the only way to edit it, and a validator that catches every drift before merge.
|
|
34
|
+
|
|
35
|
+
## What you get
|
|
36
|
+
|
|
37
|
+
| Layer | File | What it captures |
|
|
38
|
+
| -------------------- | ----------------------------------- | ------------------------------------------------------------------------- |
|
|
39
|
+
| **Structure** | `.archik/main.archik.yaml` | Services, databases, queues, agents, LLMs, the edges between them |
|
|
40
|
+
| **Actors** | `*.archik.actors.yaml` | Who initiates use cases (humans, external systems, schedulers) |
|
|
41
|
+
| **Requirements** | `.archik/usecases/*.archik.uc.yaml` | What each actor wants — flows + slices that name **test paths** |
|
|
42
|
+
| **Behaviour** | `*.archik.seq.yaml` | UML-subset sequence diagrams, ECB-checked when bound to a slice |
|
|
43
|
+
| **Progress** | `*.archik.alphas.yaml` | Essence/SEMAT alphas with **mechanically-verified** state transitions |
|
|
41
44
|
|
|
42
|
-
|
|
45
|
+
Every link between layers is a YAML cross-reference. The validator rejects breaks at every step — slice with missing test files, seq diagram without a `realizes` block, node whose `sourcePath` no longer resolves on disk, participant node missing a `seqFiles` backref. Orphans are caught at lint time, not in code review.
|
|
46
|
+
|
|
47
|
+
## Quickstart
|
|
43
48
|
|
|
44
49
|
```bash
|
|
45
50
|
npx archik@latest init # scaffolds .archik/main.archik.yaml +
|
|
@@ -47,17 +52,16 @@ npx archik@latest init # scaffolds .archik/main.archik.yaml +
|
|
|
47
52
|
npx archik@latest start # opens the live canvas at http://localhost:5173
|
|
48
53
|
```
|
|
49
54
|
|
|
50
|
-
Then in Claude Code
|
|
55
|
+
Then in Claude Code:
|
|
51
56
|
|
|
52
57
|
```
|
|
53
|
-
/archik:spawn
|
|
54
|
-
/archik:
|
|
55
|
-
/archik:
|
|
58
|
+
/archik:spawn # mirror your real source tree as the first diagram
|
|
59
|
+
/archik:suggest <feature> # propose changes for a specific feature
|
|
60
|
+
/archik:usecase <name> # author a use case with slices + tests
|
|
61
|
+
/archik:trace # "am I done?" — the coverage matrix
|
|
56
62
|
```
|
|
57
63
|
|
|
58
|
-
|
|
59
|
-
|
|
60
|
-
Done with the canvas? `npx archik stop`.
|
|
64
|
+
`/archik:suggest` and `/archik:usecase` stage reviewable artifacts — diff overlay on the canvas, accept or reject. **Claude never edits YAML by hand**; the skill enforces CLI-only access.
|
|
61
65
|
|
|
62
66
|
<p align="center">
|
|
63
67
|
<video src="https://github.com/bacharSalleh/archik/raw/main/docs/record.mp4" poster="https://cdn.jsdelivr.net/gh/bacharSalleh/archik@main/docs/archik.gif" width="780" controls muted autoplay loop playsinline>
|
|
@@ -65,16 +69,22 @@ Done with the canvas? `npx archik stop`.
|
|
|
65
69
|
</video>
|
|
66
70
|
</p>
|
|
67
71
|
|
|
68
|
-
|
|
72
|
+
## Two install paths, same outcome
|
|
69
73
|
|
|
70
|
-
|
|
74
|
+
**npm** — the canonical install, includes the CLI and the canvas:
|
|
75
|
+
|
|
76
|
+
```bash
|
|
77
|
+
npx archik@latest init
|
|
78
|
+
```
|
|
79
|
+
|
|
80
|
+
**Claude Code plugin** — for the marketplace flow:
|
|
71
81
|
|
|
72
82
|
```
|
|
73
83
|
/plugin marketplace add bacharSalleh/archik
|
|
74
84
|
/plugin install archik@archik
|
|
75
85
|
```
|
|
76
86
|
|
|
77
|
-
The plugin still
|
|
87
|
+
Either path lands the same skill + the same 11 slash commands. The plugin still uses the `archik` npm binary for the actual work, so you need Node available either way. See [Manual install](#manual-install) for adding the integration to projects that don't use `archik init`.
|
|
78
88
|
|
|
79
89
|
## What you write
|
|
80
90
|
|
|
@@ -85,14 +95,19 @@ nodes:
|
|
|
85
95
|
- id: api
|
|
86
96
|
kind: service
|
|
87
97
|
name: Support API
|
|
88
|
-
|
|
98
|
+
sourcePath: src/api
|
|
99
|
+
description: REST API serving the customer support frontend.
|
|
100
|
+
stereotype: boundary
|
|
89
101
|
- id: agent
|
|
90
102
|
kind: agent
|
|
91
103
|
name: Support Agent
|
|
92
|
-
|
|
104
|
+
sourcePath: src/agent
|
|
105
|
+
description: Drafts replies, escalates risky ones to a human.
|
|
106
|
+
stereotype: control
|
|
93
107
|
- id: claude
|
|
94
108
|
kind: llm
|
|
95
109
|
name: Claude
|
|
110
|
+
description: LLM backend for draft generation.
|
|
96
111
|
edges:
|
|
97
112
|
- id: api-agent
|
|
98
113
|
from: api
|
|
@@ -105,110 +120,91 @@ edges:
|
|
|
105
120
|
label: draft reply
|
|
106
121
|
```
|
|
107
122
|
|
|
108
|
-
No `x
|
|
109
|
-
|
|
110
|
-
## What it gives you
|
|
111
|
-
|
|
112
|
-
- **Live canvas** — `archik dev` (foreground) or `archik start` / `stop` (detached, multi-project).
|
|
113
|
-
- **27 node kinds** across compute, data, messaging, networking, hexagonal, AI/ML, identity, observability, cloud, UI, and external.
|
|
114
|
-
- **12 relationships** with distinct visual styling — `http_call`, `invokes`, `reads`, `writes`, `publishes`, `subscribes`, `streams_to`, `routes_to`, `implements`, `depends_on`, `has_a`, `uses`.
|
|
115
|
-
- **Drag-to-connect, multi-select, undo/redo, compact view, themed (dark / light), notes per node, color overrides on edges.**
|
|
116
|
-
- **CI-ready CLI** — `validate`, `render` (headless SVG), `watch`, `drift` (source-tree gaps), `trace` (coverage matrix with `--fail-on partial|none`).
|
|
117
|
-
- **AI skill + slash commands** — `archik init` installs both automatically. Eleven `/archik:*` commands cover the structural surface (`spawn`, `evolve`, `suggest`, `describe`, `dev`, `accept`, `reject`) plus the requirements layer (`actor`, `usecase`, `trace`, `alpha`).
|
|
118
|
-
|
|
119
|
-
## Beyond the diagram — use cases, traceability, alphas
|
|
123
|
+
No `x`/`y`/`width` — layout is computed by [ELK](https://eclipse.dev/elk/) on every render. The schema rejects coordinates so diffs stay meaningful and diagrams stop drifting because someone moved a box.
|
|
120
124
|
|
|
121
|
-
The
|
|
122
|
-
layer that closes the Jacobson chain — *who acts → what they want →
|
|
123
|
-
how the system behaves at runtime → which structural nodes participate
|
|
124
|
-
→ which tests prove it*. Every link is a YAML cross-reference and the
|
|
125
|
-
validator rejects breaks at every step.
|
|
125
|
+
## The killer feature: the Jacobson chain
|
|
126
126
|
|
|
127
|
-
|
|
128
|
-
| ------------------------------ | ----------------------------------- | ------------------------------------------------------------- |
|
|
129
|
-
| **Actors** | `*.archik.actors.yaml` | Who initiates use cases — humans, external systems, schedulers |
|
|
130
|
-
| **Use cases + slices** | `.archik/usecases/*.archik.uc.yaml` | What each actor wants, with slim slices that name test paths |
|
|
131
|
-
| **Sequence diagrams** | `*.archik.seq.yaml` | How a slice plays out at runtime (ECB-checked when bound to a slice via `realizes`) |
|
|
132
|
-
| **Alphas (Essence / SEMAT)** | `*.archik.alphas.yaml` | Project-wide progress dials with mechanically-verified states |
|
|
127
|
+
The diagram is the start. The thing that actually answers *"are we done?"* is the chain that runs from a stakeholder request all the way down to a passing test:
|
|
133
128
|
|
|
134
|
-
|
|
135
|
-
|
|
136
|
-
|
|
137
|
-
button shows live trace status (`✓ all traced` / `◐ N to finish` /
|
|
138
|
-
`○ N untraced`), and `/__archik/usecases` is a dedicated page with
|
|
139
|
-
master/detail rail, slice cards with clickable test paths, and direct
|
|
140
|
-
links to each realising sequence diagram.
|
|
129
|
+
```
|
|
130
|
+
Actor → Use case → Slice → Tests on disk → Seq diagram → Participant nodes → sourcePath on disk
|
|
131
|
+
```
|
|
141
132
|
|
|
142
|
-
|
|
143
|
-
points at a seq file, the seq must point back; if a seq diagram
|
|
144
|
-
realises a slice, every participant node must list that seq in its
|
|
145
|
-
`seqFiles` array. Orphans get caught at lint time, not in code review.
|
|
133
|
+
Every arrow is a YAML cross-reference. `npx archik trace` walks the chain and prints a coverage matrix:
|
|
146
134
|
|
|
147
|
-
|
|
135
|
+
```
|
|
136
|
+
$ npx archik trace
|
|
148
137
|
|
|
149
|
-
|
|
138
|
+
USE CASE / SLICE TST RZ ECB FILE
|
|
139
|
+
~ drift/clean 1t — — .archik/usecases/drift.archik.uc.yaml
|
|
140
|
+
~ drift/missing-source 1t — — .archik/usecases/drift.archik.uc.yaml
|
|
141
|
+
~ render/arch-svg 1t — — .archik/usecases/render.archik.uc.yaml
|
|
142
|
+
~ suggest-accept/happy 1t ✓ 2/4 .archik/usecases/suggest-accept.archik.uc.yaml
|
|
143
|
+
~ suggest-accept/rejected 1t — — .archik/usecases/suggest-accept.archik.uc.yaml
|
|
144
|
+
~ validate/clean 1t — — .archik/usecases/validate.archik.uc.yaml
|
|
150
145
|
|
|
151
|
-
|
|
146
|
+
totals: 9 slices across 4 use cases — 0 full, 9 partial, 0 untraced
|
|
147
|
+
```
|
|
152
148
|
|
|
153
|
-
|
|
149
|
+
Same data lives on screen — the **Use cases** toolbar button shows live status (`✓ all traced` / `◐ N to finish` / `○ N untraced`), and `/__archik/usecases` is a dedicated page with master/detail rail, slice cards with test paths, and direct links to each realising sequence diagram.
|
|
154
150
|
|
|
155
|
-
|
|
151
|
+
In CI:
|
|
156
152
|
|
|
157
|
-
|
|
158
|
-
|
|
159
|
-
|
|
160
|
-
| `/archik:evolve` | Propose a cleaner bounded-context refactor |
|
|
161
|
-
| `/archik:suggest <feature>` | Propose changes for a specific feature |
|
|
162
|
-
| `/archik:describe <id>` | Explain a node and its connections |
|
|
163
|
-
| `/archik:dev` | Open the live canvas |
|
|
164
|
-
| `/archik:accept` | Apply the pending suggestion |
|
|
165
|
-
| `/archik:reject` | Discard the pending suggestion |
|
|
153
|
+
```bash
|
|
154
|
+
npx archik trace --fail-on partial # exit 1 if anything's not fully traced
|
|
155
|
+
```
|
|
166
156
|
|
|
167
|
-
|
|
157
|
+
## In your workflow
|
|
168
158
|
|
|
169
|
-
|
|
170
|
-
| ------------------------------------ | --------------------------------------------------------------------------- |
|
|
171
|
-
| `/archik:actor <id>` | Add or update an actor in the actor index |
|
|
172
|
-
| `/archik:usecase <name>` | Author a use case (actors + flows + slices + tests) |
|
|
173
|
-
| `/archik:trace` | Show the use case × slice × test × seq × ECB coverage matrix |
|
|
174
|
-
| `/archik:alpha [show \| promote …]` | Read the project's alpha state, or promote one with a criteria check |
|
|
159
|
+
**Adding a feature.** Type `/archik:suggest add Stripe webhook handler`. Claude grounds in the current diagram, asks 1–3 clarifying questions, and stages a sidecar with the proposed shape. You review the green/red diff overlay on the canvas. Accept and the YAML is updated atomically; the next step is the build plan.
|
|
175
160
|
|
|
176
|
-
|
|
161
|
+
**Tracking the work.** `/archik:usecase <name>` writes a `*.archik.uc.yaml` with flows, slices, and test paths. Each active slice's test files must exist on disk — the validator rejects empty promises. As code lands, slices flip from "tests-only" to "fully traced" once their realisation seq exists.
|
|
177
162
|
|
|
178
|
-
|
|
179
|
-
/archik:spawn # mirror what's there now
|
|
180
|
-
# → review on the canvas, accept
|
|
181
|
-
/archik:evolve # propose a cleaner shape
|
|
182
|
-
# → discuss with Claude, accept (or iterate)
|
|
183
|
-
/archik:suggest add Stripe webhook handler
|
|
184
|
-
# → small, targeted change
|
|
185
|
-
```
|
|
163
|
+
**Closing the milestone.** `/archik:trace` surfaces what's left. `/archik:alpha promote requirements addressed` runs the criteria check before advancing — over-claiming is a hard error. `npx archik drift` catches sourcePath gaps from the source tree side.
|
|
186
164
|
|
|
187
|
-
|
|
165
|
+
## How it differs
|
|
188
166
|
|
|
189
|
-
|
|
167
|
+
| | archik | Mermaid / PlantUML | Structurizr | ADRs |
|
|
168
|
+
| --------------------- | --------------------- | ------------------ | ---------------- | ------------------ |
|
|
169
|
+
| Diagram source format | Plain YAML | Custom DSL | Structurizr DSL | Markdown prose |
|
|
170
|
+
| Layout | Auto (ELK), no coords | Auto | Auto | N/A |
|
|
171
|
+
| Live canvas | Yes (browser) | Some renderers | Yes | No |
|
|
172
|
+
| Headless render to CI | Yes (SVG) | Yes | Yes | No |
|
|
173
|
+
| AI-editor integration | **First-class** | None | None | None |
|
|
174
|
+
| Use cases / slices | **Yes** | No | No | Sometimes informal |
|
|
175
|
+
| Sequence diagrams | **Yes (UML subset)** | Yes | No | No |
|
|
176
|
+
| Test ↔ requirement traceability | **Mechanical** | No | No | No |
|
|
177
|
+
| Drift detection | **Yes (`drift`)** | No | No | No |
|
|
178
|
+
| Validator | **Schema + cross-file + ECB rules** | Syntax only | Syntax only | None |
|
|
190
179
|
|
|
191
|
-
If you
|
|
180
|
+
If all you need is a one-off rendered diagram, Mermaid is faster. If you need the diagram to **stay accurate across an LLM-assisted refactor** and **prove the system does what the requirements say**, that's archik.
|
|
192
181
|
|
|
193
|
-
|
|
182
|
+
## All slash commands
|
|
194
183
|
|
|
195
|
-
|
|
196
|
-
npx archik@latest skill --user # install skill into ~/.claude/skills (all projects)
|
|
197
|
-
npx archik@latest commands --user # install /archik:* into ~/.claude/commands (all projects)
|
|
198
|
-
```
|
|
184
|
+
**Structural diagram** (the original surface):
|
|
199
185
|
|
|
200
|
-
|
|
186
|
+
| Command | What it does |
|
|
187
|
+
| --------------------------- | ------------------------------------------------------ |
|
|
188
|
+
| `/archik:spawn` | Bootstrap a diagram by mirroring your real source tree |
|
|
189
|
+
| `/archik:evolve` | Propose a cleaner bounded-context refactor |
|
|
190
|
+
| `/archik:suggest <feature>` | Propose changes for a specific feature |
|
|
191
|
+
| `/archik:describe <id>` | Explain a node and its connections |
|
|
192
|
+
| `/archik:dev` | Open the live canvas |
|
|
193
|
+
| `/archik:accept` | Apply the pending suggestion |
|
|
194
|
+
| `/archik:reject` | Discard the pending suggestion |
|
|
201
195
|
|
|
202
|
-
**
|
|
196
|
+
**Requirements + traceability** (the Jacobson layer):
|
|
203
197
|
|
|
204
|
-
|
|
205
|
-
|
|
206
|
-
|
|
207
|
-
|
|
198
|
+
| Command | What it does |
|
|
199
|
+
| ------------------------------------ | ----------------------------------------------------------- |
|
|
200
|
+
| `/archik:actor <id>` | Add or update an actor in the actor index |
|
|
201
|
+
| `/archik:usecase <name>` | Author a use case (actors + flows + slices + tests) |
|
|
202
|
+
| `/archik:trace` | Show the coverage matrix + the next concrete action |
|
|
203
|
+
| `/archik:alpha [show \| promote …]` | Read or move project alphas with a machine-checked criteria |
|
|
208
204
|
|
|
209
|
-
|
|
205
|
+
The skill enforces a hard rule: **Claude talks to archik only through `npx archik`** — never `Read`, `Write`, or `Edit` on a YAML file directly. Queries through `npx archik q`, suggestions through `npx archik suggest set`, lifecycle through `npx archik suggest accept | reject`. You own the file; the CLI is the contract.
|
|
210
206
|
|
|
211
|
-
##
|
|
207
|
+
## CLI reference
|
|
212
208
|
|
|
213
209
|
```
|
|
214
210
|
archik init [path] Scaffold a starter .archik/main.archik.yaml
|
|
@@ -229,12 +225,16 @@ archik validate [path] Validate against the schema (CI-friendly, exit code 1 o
|
|
|
229
225
|
archik render [path] Render to a self-contained SVG file
|
|
230
226
|
--out <file> output path (default: diagram.svg)
|
|
231
227
|
--theme <name> "dark" (default) or "light"
|
|
228
|
+
--seq <path> render a sequence diagram instead of the structural one
|
|
232
229
|
archik watch [path] Re-render to SVG on every file change (Ctrl+C to stop)
|
|
233
230
|
|
|
234
231
|
archik trace [path] Use case × slice × test × seq × ECB coverage matrix
|
|
235
232
|
--json structured rows + summary
|
|
236
233
|
--fail-on <level> exit 1 on partial | none (CI gate)
|
|
237
234
|
--use-case <id> filter to one use case
|
|
235
|
+
--actor <id> filter to use cases involving an actor
|
|
236
|
+
--status <s> filter slices by status (active|proposed|deprecated)
|
|
237
|
+
--coverage <l> filter rows by level (full|partial|none)
|
|
238
238
|
archik drift [path] Surface gaps where a node's sourcePath or a slice's
|
|
239
239
|
tests path no longer resolves on disk
|
|
240
240
|
|
|
@@ -244,12 +244,6 @@ archik alpha [sub] Project-wide alpha state (Essence / SEMAT)
|
|
|
244
244
|
--note '<text>' captures the rationale
|
|
245
245
|
demote <a> <s> walk back to an earlier state on the ladder
|
|
246
246
|
|
|
247
|
-
archik upgrade Pull the latest archik via the project's package manager
|
|
248
|
-
(auto-detects npm / pnpm / yarn / bun from the lockfile)
|
|
249
|
-
then refreshes SKILL.md + slash commands from the new binary
|
|
250
|
-
--skip-install just refresh artifacts; don't reinstall
|
|
251
|
-
--user install to ~/.claude (global skill)
|
|
252
|
-
|
|
253
247
|
archik suggest [sub] Manage Claude's pending architecture suggestion
|
|
254
248
|
show summarise the pending sidecar (default; --json supported)
|
|
255
249
|
set <draft> validate a draft YAML and stage it as the sidecar
|
|
@@ -260,49 +254,98 @@ archik suggest [sub] Manage Claude's pending architecture suggestion
|
|
|
260
254
|
accept apply the sidecar over the main file
|
|
261
255
|
reject discard the sidecar
|
|
262
256
|
|
|
257
|
+
archik q [sub] Query the diagram (--json supported on every subcommand)
|
|
258
|
+
describe <id> one node, full detail
|
|
259
|
+
deps <id> what does this node depend on?
|
|
260
|
+
dependents <id> what depends on this node?
|
|
261
|
+
impact <id> who breaks if this is removed?
|
|
262
|
+
list all nodes (with --kind / --parent / --status / --search filters)
|
|
263
|
+
edges all edges (with --from / --to / --rel filters)
|
|
264
|
+
stats node + edge counts by kind/relationship
|
|
265
|
+
usecases use case index (--actor filters)
|
|
266
|
+
describe-usecase <id> one use case, full detail
|
|
267
|
+
actors actor index
|
|
268
|
+
sequences sequence diagram index (--node filters)
|
|
269
|
+
|
|
270
|
+
archik upgrade Pull the latest archik via the project's package manager
|
|
271
|
+
(auto-detects npm / pnpm / yarn / bun from the lockfile)
|
|
272
|
+
then refreshes SKILL.md + slash commands from the new binary
|
|
273
|
+
--skip-install just refresh artifacts; don't reinstall
|
|
274
|
+
|
|
263
275
|
archik skill Install the Claude skill for AI editing
|
|
264
276
|
--user install into ~/.claude/skills (all projects)
|
|
265
277
|
--force overwrite an existing skill
|
|
266
278
|
archik commands Install the /archik:* slash commands for Claude Code
|
|
267
279
|
--user install into ~/.claude/commands (all projects)
|
|
268
280
|
--force overwrite existing commands
|
|
281
|
+
archik schema [variant] Print the document schema as a reference (--json supported)
|
|
282
|
+
(no arg) architecture document
|
|
283
|
+
seq sequence diagram
|
|
284
|
+
uc use case
|
|
285
|
+
actors actors file
|
|
269
286
|
```
|
|
270
287
|
|
|
271
288
|
Without a `[path]` argument, archik resolves the file in this order:
|
|
272
289
|
|
|
273
|
-
1. `.archik/main.archik.yaml` (preferred
|
|
290
|
+
1. `.archik/main.archik.yaml` (preferred — keeps the project root tidy)
|
|
274
291
|
2. `architecture.archik.yaml` (legacy root location — still fully supported)
|
|
275
292
|
|
|
276
|
-
If both exist the command errors out and asks you to pick one.
|
|
293
|
+
If both exist the command errors out and asks you to pick one.
|
|
277
294
|
|
|
278
|
-
|
|
295
|
+
## Manual install
|
|
279
296
|
|
|
280
|
-
|
|
297
|
+
If you already have an archik file and just want to add the Claude integration to it:
|
|
298
|
+
|
|
299
|
+
**Via the npm CLI:**
|
|
281
300
|
|
|
282
301
|
```bash
|
|
283
|
-
#
|
|
284
|
-
archik
|
|
302
|
+
npx archik@latest skill --user # install skill into ~/.claude/skills (all projects)
|
|
303
|
+
npx archik@latest commands --user # install /archik:* into ~/.claude/commands (all projects)
|
|
304
|
+
```
|
|
305
|
+
|
|
306
|
+
Drop the `--user` flag to scope to the current project only.
|
|
307
|
+
|
|
308
|
+
**Via Claude Code's plugin marketplace:**
|
|
285
309
|
|
|
286
|
-
# Generate a committable SVG of your architecture for the docs site
|
|
287
|
-
archik render --theme light --out docs/architecture.svg
|
|
288
310
|
```
|
|
311
|
+
/plugin marketplace add bacharSalleh/archik
|
|
312
|
+
/plugin install archik@archik
|
|
313
|
+
```
|
|
314
|
+
|
|
315
|
+
Either path leaves the same skill + the same 11 slash commands in the same target directories.
|
|
316
|
+
|
|
317
|
+
## When to use it (and when not to)
|
|
318
|
+
|
|
319
|
+
**Use archik when**
|
|
320
|
+
|
|
321
|
+
- Your project has more than ~5 components and you want the diagram to stay accurate
|
|
322
|
+
- You're using Claude Code (or any AI agent) to author code, and you want the agent to reason about structure instead of guess from filenames
|
|
323
|
+
- You're shipping in milestones and want "are we done?" to be mechanically answerable
|
|
324
|
+
- You have CI and want a gate that fails on architectural drift
|
|
289
325
|
|
|
290
|
-
|
|
326
|
+
**Skip it when**
|
|
291
327
|
|
|
292
|
-
|
|
328
|
+
- It's a one-file script or a throwaway prototype
|
|
329
|
+
- The architecture diagram is for a slide deck (use Mermaid)
|
|
330
|
+
- You don't have a build step or CI
|
|
331
|
+
|
|
332
|
+
The full schema reference (every node kind, every relationship, common patterns, hard rules) lives in [`skills/archik/SKILL.md`](skills/archik/SKILL.md) — installed automatically by `archik init` so Claude reads it before doing structural work.
|
|
333
|
+
|
|
334
|
+
## Use it in CI
|
|
293
335
|
|
|
294
336
|
```bash
|
|
295
|
-
archik
|
|
296
|
-
|
|
337
|
+
archik validate # schema + cross-file integrity
|
|
338
|
+
archik drift # source-tree gaps
|
|
339
|
+
archik trace --fail-on partial # block merge on incomplete traceability
|
|
340
|
+
archik render --theme light --out docs/architecture.svg # commit a static SVG
|
|
297
341
|
```
|
|
298
342
|
|
|
299
|
-
Or read it directly in this repo: [`.claude/skills/archik/SKILL.md`](.claude/skills/archik/SKILL.md).
|
|
300
|
-
|
|
301
343
|
## Design notes
|
|
302
344
|
|
|
303
|
-
- The YAML is the only persistent truth
|
|
304
|
-
- Layout is non-negotiable
|
|
305
|
-
-
|
|
345
|
+
- **The YAML is the only persistent truth.** The canvas is a stateless projection that reloads on every file change (live-reload via SSE).
|
|
346
|
+
- **Layout is non-negotiable.** ELK lays out every render. Putting an `x`/`y`/`width` field at any level fails schema validation. No more "the diagram drifted because someone dragged a box."
|
|
347
|
+
- **Single instance per file** is enforced via a lock file in `$TMPDIR/archik-cli/`, so parallel `dev`/`start` against the same YAML are rejected with a friendly error.
|
|
348
|
+
- **The published npm package** ships only the bundled binary, the canvas assets, the skill, and the 11 slash commands. Zero runtime dependencies.
|
|
306
349
|
|
|
307
350
|
## License
|
|
308
351
|
|
package/package.json
CHANGED
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
{
|
|
2
2
|
"name": "archik",
|
|
3
|
-
"version": "0.12.
|
|
3
|
+
"version": "0.12.39",
|
|
4
4
|
"description": "The shared vocabulary between you and Claude Code, at the engineering level. Plain-YAML architecture diagrams with a live browser canvas, headless SVG render in CI, and an installable Claude skill so the model treats the diagram as the spec.",
|
|
5
5
|
"keywords": [
|
|
6
6
|
"architecture",
|