archik 0.12.50 → 0.13.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/README.md +174 -262
- package/dist/cli/archik.mjs +540 -357
- package/dist/ui/assets/{index-Dl4i5i09.js → index-D08Zt2_n.js} +86 -86
- package/dist/ui/index.html +1 -1
- package/package.json +1 -1
- package/skills/archik/SKILL.md +58 -5
package/README.md
CHANGED
|
@@ -9,94 +9,92 @@
|
|
|
9
9
|
with use cases, sequence diagrams, and tests wired end-to-end.</em>
|
|
10
10
|
</p>
|
|
11
11
|
|
|
12
|
-
|
|
13
|
-
|
|
14
|
-
|
|
15
|
-
|
|
16
|
-
|
|
17
|
-
|
|
18
|
-
|
|
12
|
+
<p align="center">
|
|
13
|
+
<a href="https://www.npmjs.com/package/archik"><img src="https://badge.fury.io/js/archik.svg" alt="npm version"></a>
|
|
14
|
+
<a href="https://github.com/bacharSalleh/archik/actions/workflows/ci.yml"><img src="https://github.com/bacharSalleh/archik/actions/workflows/ci.yml/badge.svg" alt="CI"></a>
|
|
15
|
+
<a href="https://github.com/bacharSalleh/archik/stargazers"><img src="https://img.shields.io/github/stars/bacharSalleh/archik" alt="GitHub stars"></a>
|
|
16
|
+
<a href="https://www.npmjs.com/package/archik"><img src="https://img.shields.io/npm/dm/archik" alt="npm downloads"></a>
|
|
17
|
+
<a href="./LICENSE"><img src="https://img.shields.io/npm/l/archik?color=blue" alt="license"></a>
|
|
18
|
+
<a href="https://nodejs.org"><img src="https://img.shields.io/node/v/archik?color=339933&logo=node.js&logoColor=white" alt="node"></a>
|
|
19
|
+
</p>
|
|
19
20
|
|
|
20
21
|
<p align="center">
|
|
21
|
-
<img src="https://cdn.jsdelivr.net/npm/archik/docs/hero.svg?v=2" alt="Sample Archik diagram
|
|
22
|
+
<img src="https://cdn.jsdelivr.net/npm/archik/docs/hero.svg?v=2" alt="Sample Archik diagram" width="780">
|
|
22
23
|
</p>
|
|
23
24
|
|
|
24
|
-
|
|
25
|
+
---
|
|
25
26
|
|
|
26
|
-
|
|
27
|
+
## What is archik?
|
|
27
28
|
|
|
28
|
-
|
|
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**
|
|
29
|
+
Your architecture lives in **plain YAML**. A **CLI** is the only way to edit it, a **validator** rejects every drift before merge, and a **live canvas** renders it in the browser. AI agents (Claude Code, or anything that speaks MCP) read the same YAML as their map of your system — so they reason about structure instead of guessing from filenames.
|
|
32
30
|
|
|
33
|
-
|
|
31
|
+
One chain runs from a stakeholder request all the way to a passing test, and every link is mechanically checked:
|
|
34
32
|
|
|
35
|
-
|
|
33
|
+
```
|
|
34
|
+
Actor → Use case → Slice → Tests on disk → Seq diagram → Nodes → Source code on disk
|
|
35
|
+
```
|
|
36
36
|
|
|
37
|
-
|
|
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 |
|
|
37
|
+
## Features
|
|
44
38
|
|
|
45
|
-
|
|
39
|
+
- 📐 **Plain-YAML diagrams** — no DSL, no coordinates; layout is computed by [ELK](https://eclipse.dev/elk/) on every render, so diffs stay meaningful
|
|
40
|
+
- 🖥️ **Live canvas** — `archik dev` opens a browser canvas that reloads on every file change; headless SVG render for docs and CI
|
|
41
|
+
- 🤖 **AI-native** — installable Claude Code skill + 12 slash commands, and an MCP server for Cursor, Windsurf, Copilot, Claude Desktop, Zed
|
|
42
|
+
- ✅ **Validator, not convention** — schema, cross-file references, `sourcePath` existence, use-case/actor/seq integrity, ECB rules
|
|
43
|
+
- 🔍 **Traceability** — `archik trace` proves which use case slices are tested and realized; `--fail-on` gates CI
|
|
44
|
+
- 🌿 **Git-aware** — `archik diff origin/main` shows what a branch changes architecturally; `archik affected` maps changed files to nodes, slices, and tests
|
|
45
|
+
- 🤝 **Team-ready** — semantic merge driver for YAML, node ownership, and governance constraints (architecture fitness rules)
|
|
46
|
+
- 🚀 **Fast adoption** — `archik import compose` bootstraps a diagram from docker-compose; `/archik:spawn` mirrors an existing source tree
|
|
47
|
+
- 📦 **Zero runtime dependencies** in the published package
|
|
46
48
|
|
|
47
|
-
##
|
|
49
|
+
## Installation
|
|
50
|
+
|
|
51
|
+
Requires **Node.js ≥ 20**.
|
|
48
52
|
|
|
49
53
|
```bash
|
|
50
|
-
npx archik@latest init # scaffolds .archik/main.archik.yaml
|
|
51
|
-
# installs the Claude skill
|
|
52
|
-
npx archik@latest start # opens the live canvas at http://localhost:5173
|
|
54
|
+
npx archik@latest init # scaffolds .archik/main.archik.yaml
|
|
55
|
+
# + installs the Claude skill and /archik:* commands
|
|
53
56
|
```
|
|
54
57
|
|
|
55
|
-
|
|
58
|
+
Or as a Claude Code plugin:
|
|
56
59
|
|
|
57
60
|
```
|
|
58
|
-
/
|
|
59
|
-
|
|
60
|
-
# on fresh projects, suggests /archik:spawn on existing
|
|
61
|
-
# codebases, surfaces trace status if already modelled)
|
|
61
|
+
/plugin marketplace add bacharSalleh/archik
|
|
62
|
+
/plugin install archik@archik
|
|
62
63
|
```
|
|
63
64
|
|
|
64
|
-
|
|
65
|
+
Both paths install the same skill and slash commands. The plugin still uses the `archik` npm binary, so Node is needed either way.
|
|
65
66
|
|
|
66
|
-
|
|
67
|
-
|
|
68
|
-
|
|
69
|
-
|
|
67
|
+
## Quick start
|
|
68
|
+
|
|
69
|
+
```bash
|
|
70
|
+
npx archik init # 1. scaffold
|
|
71
|
+
npx archik start # 2. open the live canvas (http://localhost:5173)
|
|
70
72
|
```
|
|
71
73
|
|
|
72
|
-
|
|
74
|
+
Then, in Claude Code:
|
|
73
75
|
|
|
74
|
-
|
|
76
|
+
```
|
|
77
|
+
/archik:bootstrap # 3. always your first message — detects project
|
|
78
|
+
# state and routes to the right next step
|
|
79
|
+
```
|
|
75
80
|
|
|
76
|
-
|
|
77
|
-
<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>
|
|
78
|
-
<img src="https://cdn.jsdelivr.net/gh/bacharSalleh/archik@main/docs/archik.gif" alt="Archik canvas demo" width="780">
|
|
79
|
-
</video>
|
|
80
|
-
</p>
|
|
81
|
+
Day-to-day:
|
|
81
82
|
|
|
82
|
-
|
|
83
|
+
| You type | You get |
|
|
84
|
+
| --- | --- |
|
|
85
|
+
| `/archik:suggest <feature>` | A staged diagram change, shown as a green/red diff overlay on the canvas — accept or reject |
|
|
86
|
+
| `/archik:usecase <name>` | A use case with flows, slices, and test paths |
|
|
87
|
+
| `/archik:trace` | "Are we done?" — the coverage matrix |
|
|
83
88
|
|
|
84
|
-
**
|
|
89
|
+
**Already containerised?** Skip the blank canvas:
|
|
85
90
|
|
|
86
91
|
```bash
|
|
87
|
-
npx archik
|
|
92
|
+
npx archik import compose --out .archik/main.archik.yaml
|
|
88
93
|
```
|
|
89
94
|
|
|
90
|
-
|
|
95
|
+
Compose services become nodes (postgres → `database`, redis → `cache`, kafka → `stream`, …), build contexts become `sourcePath`s, and `depends_on` becomes edges.
|
|
91
96
|
|
|
92
|
-
|
|
93
|
-
/plugin marketplace add bacharSalleh/archik
|
|
94
|
-
/plugin install archik@archik
|
|
95
|
-
```
|
|
96
|
-
|
|
97
|
-
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`.
|
|
98
|
-
|
|
99
|
-
## What you write
|
|
97
|
+
## The YAML
|
|
100
98
|
|
|
101
99
|
```yaml
|
|
102
100
|
version: "1.0"
|
|
@@ -105,264 +103,178 @@ nodes:
|
|
|
105
103
|
- id: api
|
|
106
104
|
kind: service
|
|
107
105
|
name: Support API
|
|
108
|
-
sourcePath: src/api
|
|
106
|
+
sourcePath: src/api # must exist on disk — validator-enforced
|
|
109
107
|
description: REST API serving the customer support frontend.
|
|
110
|
-
|
|
111
|
-
- id: agent
|
|
112
|
-
kind: agent
|
|
113
|
-
name: Support Agent
|
|
114
|
-
sourcePath: src/agent
|
|
115
|
-
description: Drafts replies, escalates risky ones to a human.
|
|
116
|
-
stereotype: control
|
|
108
|
+
owner: team-support # optional — who to talk to
|
|
117
109
|
- id: claude
|
|
118
110
|
kind: llm
|
|
119
111
|
name: Claude
|
|
120
112
|
description: LLM backend for draft generation.
|
|
121
113
|
edges:
|
|
122
|
-
- id: api-
|
|
114
|
+
- id: api-claude
|
|
123
115
|
from: api
|
|
124
|
-
to: agent
|
|
125
|
-
relationship: invokes
|
|
126
|
-
- id: agent-claude
|
|
127
|
-
from: agent
|
|
128
116
|
to: claude
|
|
129
117
|
relationship: invokes
|
|
130
|
-
label: draft reply
|
|
131
118
|
```
|
|
132
119
|
|
|
133
|
-
|
|
120
|
+
One file per layer, every link cross-checked by the validator:
|
|
134
121
|
|
|
135
|
-
|
|
122
|
+
| Layer | File | Captures |
|
|
123
|
+
| --- | --- | --- |
|
|
124
|
+
| Structure | `.archik/main.archik.yaml` | Services, databases, queues, agents, LLMs, edges |
|
|
125
|
+
| Actors | `*.archik.actors.yaml` | Who initiates use cases |
|
|
126
|
+
| Requirements | `.archik/usecases/*.archik.uc.yaml` | Flows + slices that name **test paths** |
|
|
127
|
+
| Behaviour | `*.archik.seq.yaml` | UML-subset sequence diagrams |
|
|
128
|
+
| Progress | `*.archik.alphas.yaml` | Essence/SEMAT alphas, machine-verified |
|
|
136
129
|
|
|
137
|
-
|
|
130
|
+
Full schema: `npx archik schema` (also `schema seq | uc | actors`).
|
|
138
131
|
|
|
139
|
-
|
|
140
|
-
Actor → Use case → Slice → Tests on disk → Seq diagram → Participant nodes → sourcePath on disk
|
|
141
|
-
```
|
|
142
|
-
|
|
143
|
-
Every arrow is a YAML cross-reference. `npx archik trace` walks the chain and prints a coverage matrix:
|
|
144
|
-
|
|
145
|
-
```
|
|
146
|
-
$ npx archik trace
|
|
147
|
-
|
|
148
|
-
USE CASE / SLICE TST RZ ECB FILE
|
|
149
|
-
~ drift/clean 1t — — .archik/usecases/drift.archik.uc.yaml
|
|
150
|
-
~ drift/missing-source 1t — — .archik/usecases/drift.archik.uc.yaml
|
|
151
|
-
~ render/arch-svg 1t — — .archik/usecases/render.archik.uc.yaml
|
|
152
|
-
~ suggest-accept/happy 1t ✓ 2/4 .archik/usecases/suggest-accept.archik.uc.yaml
|
|
153
|
-
~ suggest-accept/rejected 1t — — .archik/usecases/suggest-accept.archik.uc.yaml
|
|
154
|
-
~ validate/clean 1t — — .archik/usecases/validate.archik.uc.yaml
|
|
155
|
-
|
|
156
|
-
totals: 9 slices across 4 use cases — 0 full, 9 partial, 0 untraced
|
|
157
|
-
```
|
|
158
|
-
|
|
159
|
-
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.
|
|
160
|
-
|
|
161
|
-
In CI:
|
|
132
|
+
## Everyday workflow
|
|
162
133
|
|
|
163
134
|
```bash
|
|
164
|
-
|
|
165
|
-
|
|
135
|
+
# What am I touching on this branch? Which tests cover it?
|
|
136
|
+
npx archik affected --since main
|
|
166
137
|
|
|
167
|
-
|
|
138
|
+
# What does this branch change architecturally?
|
|
139
|
+
npx archik diff origin/main # add --out diff.svg for the visual
|
|
168
140
|
|
|
169
|
-
|
|
141
|
+
# Is the diagram still telling the truth?
|
|
142
|
+
npx archik validate && npx archik drift
|
|
170
143
|
|
|
171
|
-
|
|
172
|
-
|
|
173
|
-
|
|
174
|
-
|
|
175
|
-
## How it differs
|
|
144
|
+
# Are we done?
|
|
145
|
+
npx archik trace
|
|
146
|
+
```
|
|
176
147
|
|
|
177
|
-
|
|
178
|
-
| --------------------- | --------------------- | ------------------ | ---------------- | ------------------ |
|
|
179
|
-
| Diagram source format | Plain YAML | Custom DSL | Structurizr DSL | Markdown prose |
|
|
180
|
-
| Layout | Auto (ELK), no coords | Auto | Auto | N/A |
|
|
181
|
-
| Live canvas | Yes (browser) | Some renderers | Yes | No |
|
|
182
|
-
| Headless render to CI | Yes (SVG) | Yes | Yes | No |
|
|
183
|
-
| AI-editor integration | **First-class** | None | None | None |
|
|
184
|
-
| Use cases / slices | **Yes** | No | No | Sometimes informal |
|
|
185
|
-
| Sequence diagrams | **Yes (UML subset)** | Yes | No | No |
|
|
186
|
-
| Test ↔ requirement traceability | **Mechanical** | No | No | No |
|
|
187
|
-
| Drift detection | **Yes (`drift`)** | No | No | No |
|
|
188
|
-
| Validator | **Schema + cross-file + ECB rules** | Syntax only | Syntax only | None |
|
|
148
|
+
`affected` walks the chain backwards: changed files → nodes (via `sourcePath`) → use case slices (via tests and sequence-diagram participants) → tests to run — and flags changed files no node or test claims.
|
|
189
149
|
|
|
190
|
-
|
|
150
|
+
## AI integration
|
|
191
151
|
|
|
192
|
-
|
|
152
|
+
**Claude Code** (deepest integration): `archik init` installs a skill that enforces one hard rule — *Claude talks to archik only through the CLI*, never by editing YAML directly. Reads go through `archik q`, writes through `archik suggest set`, and you approve every structural change on the canvas.
|
|
193
153
|
|
|
194
|
-
**
|
|
154
|
+
**Everything else** (MCP): `archik mcp` runs a stdio [Model Context Protocol](https://modelcontextprotocol.io) server exposing the same contract — 20 tools covering schema, queries, trace, validate, drift, affected, and the suggestion lifecycle:
|
|
195
155
|
|
|
196
|
-
|
|
197
|
-
|
|
198
|
-
|
|
156
|
+
```jsonc
|
|
157
|
+
// .cursor/mcp.json, claude_desktop_config.json, etc.
|
|
158
|
+
{
|
|
159
|
+
"mcpServers": {
|
|
160
|
+
"archik": { "command": "npx", "args": ["archik", "mcp"] }
|
|
161
|
+
}
|
|
162
|
+
}
|
|
163
|
+
```
|
|
199
164
|
|
|
200
|
-
|
|
165
|
+
## Team workflow
|
|
201
166
|
|
|
202
|
-
|
|
203
|
-
| --------------------------- | ------------------------------------------------------ |
|
|
204
|
-
| `/archik:spawn` | Mirror your real source tree as the first diagram |
|
|
205
|
-
| `/archik:evolve` | Propose a cleaner bounded-context refactor |
|
|
206
|
-
| `/archik:suggest <feature>` | Propose changes for a specific feature |
|
|
207
|
-
| `/archik:describe <id>` | Explain a node and its connections |
|
|
208
|
-
| `/archik:dev` | Open the live canvas |
|
|
209
|
-
| `/archik:accept` | Apply the pending suggestion |
|
|
210
|
-
| `/archik:reject` | Discard the pending suggestion |
|
|
167
|
+
**Semantic merges.** Stop resolving line-based YAML conflicts — nodes and edges are id-keyed, so most merges are mechanical:
|
|
211
168
|
|
|
212
|
-
|
|
169
|
+
```bash
|
|
170
|
+
npx archik merge-driver --install # once per clone; .gitattributes line is committed
|
|
171
|
+
```
|
|
213
172
|
|
|
214
|
-
|
|
215
|
-
| ------------------------------------ | ----------------------------------------------------------- |
|
|
216
|
-
| `/archik:actor <id>` | Add or update an actor in the actor index |
|
|
217
|
-
| `/archik:usecase <name>` | Author a use case (actors + flows + slices + tests) |
|
|
218
|
-
| `/archik:trace` | Show the coverage matrix + the next concrete action |
|
|
219
|
-
| `/archik:alpha [show \| promote …]` | Read or move project alphas with a machine-checked criteria |
|
|
173
|
+
Both branches added nodes → keep both. One side changed a field → take it. Same field changed differently, or modify-vs-delete → a real conflict, reported precisely.
|
|
220
174
|
|
|
221
|
-
|
|
175
|
+
**Ownership.** `owner: team-billing` on a node answers "who do I talk to": `archik q describe payments-db`, `archik q list --owner team-billing`.
|
|
222
176
|
|
|
223
|
-
|
|
177
|
+
**Governance constraints.** Architecture fitness rules, enforced by `archik validate` on every run:
|
|
224
178
|
|
|
179
|
+
```yaml
|
|
180
|
+
constraints:
|
|
181
|
+
- id: billing-isolation
|
|
182
|
+
description: Only billing-context nodes may write to billing-db.
|
|
183
|
+
forbidEdge:
|
|
184
|
+
relationship: writes
|
|
185
|
+
from: { notParent: billing }
|
|
186
|
+
to: { id: billing-db }
|
|
187
|
+
- id: services-owned
|
|
188
|
+
description: Every service and worker declares an owning team.
|
|
189
|
+
requireOwner: { kinds: [service, worker] }
|
|
225
190
|
```
|
|
226
|
-
archik init [path] Scaffold a starter .archik/main.archik.yaml
|
|
227
|
-
(also installs the Claude skill + /archik:* slash commands by default)
|
|
228
|
-
--no-skill skip installing the Claude skill
|
|
229
|
-
--no-commands skip installing the /archik:* slash commands
|
|
230
|
-
|
|
231
|
-
archik dev [path] Open the canvas in your browser (foreground, Ctrl+C to stop)
|
|
232
|
-
archik start [path] Same as dev, but detached — prompt returns immediately
|
|
233
|
-
archik stop [path] Stop the background server started with `archik start`
|
|
234
|
-
archik status List running archik instances across all projects
|
|
235
|
-
(dev / start share these flags)
|
|
236
|
-
--port <n> dev server port (default 5173)
|
|
237
|
-
--host <addr> bind address (default 127.0.0.1)
|
|
238
|
-
--no-open don't auto-open the browser
|
|
239
|
-
|
|
240
|
-
archik validate [path] Validate against the schema (CI-friendly, exit code 1 on error)
|
|
241
|
-
archik render [path] Render to a self-contained SVG file
|
|
242
|
-
--out <file> output path (default: diagram.svg)
|
|
243
|
-
--theme <name> "dark" (default) or "light"
|
|
244
|
-
--seq <path> render a sequence diagram instead of the structural one
|
|
245
|
-
archik watch [path] Re-render to SVG on every file change (Ctrl+C to stop)
|
|
246
|
-
|
|
247
|
-
archik trace [path] Use case × slice × test × seq × ECB coverage matrix
|
|
248
|
-
--json structured rows + summary
|
|
249
|
-
--fail-on <level> exit 1 on partial | none (CI gate)
|
|
250
|
-
--use-case <id> filter to one use case
|
|
251
|
-
--actor <id> filter to use cases involving an actor
|
|
252
|
-
--status <s> filter slices by status (active|proposed|deprecated)
|
|
253
|
-
--coverage <l> filter rows by level (full|partial|none)
|
|
254
|
-
archik drift [path] Surface gaps where a node's sourcePath or a slice's
|
|
255
|
-
tests path no longer resolves on disk
|
|
256
|
-
|
|
257
|
-
archik alpha [sub] Project-wide alpha state (Essence / SEMAT)
|
|
258
|
-
show snapshot with ✓ / ? / ✗ verification
|
|
259
|
-
promote <a> <s> advance an alpha — runs criteria first;
|
|
260
|
-
--note '<text>' captures the rationale
|
|
261
|
-
demote <a> <s> walk back to an earlier state on the ladder
|
|
262
|
-
|
|
263
|
-
archik suggest [sub] Manage Claude's pending architecture suggestion
|
|
264
|
-
show summarise the pending sidecar (default; --json supported)
|
|
265
|
-
set <draft> validate a draft YAML and stage it as the sidecar
|
|
266
|
-
--note '<text>' set metadata.suggestion.note
|
|
267
|
-
--main <path> override main file detection
|
|
268
|
-
--json structured output
|
|
269
|
-
- read draft from stdin
|
|
270
|
-
accept apply the sidecar over the main file
|
|
271
|
-
reject discard the sidecar
|
|
272
|
-
|
|
273
|
-
archik q [sub] Query the diagram (--json supported on every subcommand)
|
|
274
|
-
describe <id> one node, full detail
|
|
275
|
-
deps <id> what does this node depend on?
|
|
276
|
-
dependents <id> what depends on this node?
|
|
277
|
-
impact <id> who breaks if this is removed?
|
|
278
|
-
list all nodes (with --kind / --parent / --status / --search filters)
|
|
279
|
-
edges all edges (with --from / --to / --rel filters)
|
|
280
|
-
stats node + edge counts by kind/relationship
|
|
281
|
-
usecases use case index (--actor filters)
|
|
282
|
-
describe-usecase <id> one use case, full detail
|
|
283
|
-
actors actor index
|
|
284
|
-
sequences sequence diagram index (--node filters)
|
|
285
|
-
|
|
286
|
-
archik upgrade Pull the latest archik via the project's package manager
|
|
287
|
-
(auto-detects npm / pnpm / yarn / bun from the lockfile)
|
|
288
|
-
then refreshes SKILL.md + slash commands from the new binary
|
|
289
|
-
--skip-install just refresh artifacts; don't reinstall
|
|
290
|
-
|
|
291
|
-
archik skill Install the Claude skill for AI editing
|
|
292
|
-
--user install into ~/.claude/skills (all projects)
|
|
293
|
-
--force overwrite an existing skill
|
|
294
|
-
archik commands Install the /archik:* slash commands for Claude Code
|
|
295
|
-
--user install into ~/.claude/commands (all projects)
|
|
296
|
-
--force overwrite existing commands
|
|
297
|
-
archik schema [variant] Print the document schema as a reference (--json supported)
|
|
298
|
-
(no arg) architecture document
|
|
299
|
-
seq sequence diagram
|
|
300
|
-
uc use case
|
|
301
|
-
actors actors file
|
|
302
|
-
```
|
|
303
|
-
|
|
304
|
-
Without a `[path]` argument, archik resolves the file in this order:
|
|
305
191
|
|
|
306
|
-
|
|
307
|
-
2. `architecture.archik.yaml` (legacy root location — still fully supported)
|
|
192
|
+
Intentional exceptions are grandfathered by id in an `except` list — visible in review, never silent.
|
|
308
193
|
|
|
309
|
-
|
|
194
|
+
## CI
|
|
310
195
|
|
|
311
|
-
|
|
312
|
-
|
|
313
|
-
If you already have an archik file and just want to add the Claude integration to it:
|
|
314
|
-
|
|
315
|
-
**Via the npm CLI:**
|
|
196
|
+
Plain commands:
|
|
316
197
|
|
|
317
198
|
```bash
|
|
318
|
-
|
|
319
|
-
|
|
199
|
+
archik validate # schema + cross-file integrity + constraints
|
|
200
|
+
archik drift # diagram vs source tree
|
|
201
|
+
archik trace --fail-on partial # block merge on incomplete traceability
|
|
202
|
+
archik render --theme light --out docs/architecture.svg
|
|
320
203
|
```
|
|
321
204
|
|
|
322
|
-
|
|
205
|
+
Or the GitHub Action, which runs all three and posts a sticky PR comment with the architecture diff vs the base branch:
|
|
323
206
|
|
|
324
|
-
|
|
325
|
-
|
|
326
|
-
|
|
327
|
-
|
|
328
|
-
|
|
207
|
+
```yaml
|
|
208
|
+
# .github/workflows/archik.yml
|
|
209
|
+
name: archik
|
|
210
|
+
on: [pull_request]
|
|
211
|
+
permissions:
|
|
212
|
+
contents: read
|
|
213
|
+
pull-requests: write
|
|
214
|
+
jobs:
|
|
215
|
+
archik:
|
|
216
|
+
runs-on: ubuntu-latest
|
|
217
|
+
steps:
|
|
218
|
+
- uses: actions/checkout@v4
|
|
219
|
+
- uses: bacharSalleh/archik@main
|
|
220
|
+
with:
|
|
221
|
+
trace-fail-on: partial # optional gate; omit for report-only
|
|
329
222
|
```
|
|
330
223
|
|
|
331
|
-
|
|
224
|
+
Inputs: `path`, `working-directory`, `validate`, `drift`, `trace-fail-on`, `compare-ref`, `comment`, `github-token`, `version`.
|
|
332
225
|
|
|
333
|
-
##
|
|
226
|
+
## CLI reference
|
|
227
|
+
|
|
228
|
+
Every command supports `--help`; agent-facing commands support `--json`.
|
|
229
|
+
|
|
230
|
+
| Command | What it does |
|
|
231
|
+
| --- | --- |
|
|
232
|
+
| `archik init` | Scaffold + install the Claude skill and slash commands |
|
|
233
|
+
| `archik dev` / `start` / `stop` / `status` | Live canvas lifecycle (foreground / detached) |
|
|
234
|
+
| `archik validate [path]` | Schema + cross-file + constraints (exit 1 on error) |
|
|
235
|
+
| `archik render --out <svg>` | Headless SVG render (`--seq <path>` for sequence diagrams) |
|
|
236
|
+
| `archik watch` | Re-render SVG on every change |
|
|
237
|
+
| `archik q <sub>` | Query: `describe` `deps` `dependents` `impact` `list` `edges` `stats` `usecases` `describe-usecase` `actors` `sequences` |
|
|
238
|
+
| `archik diff <a> [b]` | Diff two files **or git refs**; one arg = that ref vs working tree |
|
|
239
|
+
| `archik affected` | Changed files → nodes, slices, tests to run (`--since <ref>`, `--files`) |
|
|
240
|
+
| `archik trace` | Coverage matrix (`--fail-on partial\|none` for CI) |
|
|
241
|
+
| `archik drift` | sourcePath / test-path gaps vs the source tree |
|
|
242
|
+
| `archik suggest <sub>` | Suggestion sidecar lifecycle: `show` `set` `accept` `reject` |
|
|
243
|
+
| `archik alpha <sub>` | Essence alphas: `show`, `promote` (machine-checked), `demote` |
|
|
244
|
+
| `archik import compose [file]` | Bootstrap a document from docker-compose |
|
|
245
|
+
| `archik merge-driver --install` | Semantic git merge for `*.archik.yaml` |
|
|
246
|
+
| `archik mcp` | MCP server over stdio for non-Claude-Code agents |
|
|
247
|
+
| `archik schema [seq\|uc\|actors]` | Print the document schemas |
|
|
248
|
+
| `archik upgrade` | Upgrade + refresh installed skill/commands |
|
|
249
|
+
|
|
250
|
+
Default file resolution: `.archik/main.archik.yaml`, falling back to the legacy `architecture.archik.yaml` (both present = error).
|
|
334
251
|
|
|
335
|
-
|
|
252
|
+
## When to use it (and when not to)
|
|
336
253
|
|
|
337
|
-
|
|
338
|
-
- 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
|
|
339
|
-
- You're shipping in milestones and want "are we done?" to be mechanically answerable
|
|
340
|
-
- You have CI and want a gate that fails on architectural drift
|
|
254
|
+
**Use archik when** your project has more than ~5 components, you ship with an AI agent and want it to reason about structure, you want "are we done?" to be mechanically answerable, or you want CI to fail on architectural drift.
|
|
341
255
|
|
|
342
|
-
**Skip it when**
|
|
256
|
+
**Skip it when** it's a one-file script, the diagram is for a slide deck (use Mermaid), or you have no build step or CI.
|
|
343
257
|
|
|
344
|
-
|
|
345
|
-
|
|
346
|
-
|
|
258
|
+
| | archik | Mermaid / PlantUML | Structurizr |
|
|
259
|
+
| --- | --- | --- | --- |
|
|
260
|
+
| Source format | Plain YAML | Custom DSL | Structurizr DSL |
|
|
261
|
+
| AI-editor integration | **Skill + MCP** | None | None |
|
|
262
|
+
| Use cases / test traceability | **Mechanical** | No | No |
|
|
263
|
+
| Drift detection | **Yes** | No | No |
|
|
264
|
+
| Governance constraints | **Yes** | No | No |
|
|
265
|
+
| Validator | **Schema + cross-file + ECB** | Syntax only | Syntax only |
|
|
347
266
|
|
|
348
|
-
|
|
267
|
+
## Contributing
|
|
349
268
|
|
|
350
|
-
|
|
269
|
+
See [CONTRIBUTING.md](./CONTRIBUTING.md). Development:
|
|
351
270
|
|
|
352
271
|
```bash
|
|
353
|
-
|
|
354
|
-
archik
|
|
355
|
-
|
|
356
|
-
|
|
272
|
+
npm install
|
|
273
|
+
npm run archik -- --help # run the CLI from source
|
|
274
|
+
npm test # vitest
|
|
275
|
+
npm run typecheck
|
|
357
276
|
```
|
|
358
277
|
|
|
359
|
-
## Design notes
|
|
360
|
-
|
|
361
|
-
- **The YAML is the only persistent truth.** The canvas is a stateless projection that reloads on every file change (live-reload via SSE).
|
|
362
|
-
- **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."
|
|
363
|
-
- **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.
|
|
364
|
-
- **The published npm package** ships only the bundled binary, the canvas assets, the skill, and the 11 slash commands. Zero runtime dependencies.
|
|
365
|
-
|
|
366
278
|
## License
|
|
367
279
|
|
|
368
280
|
MIT © [Bashar](https://github.com/bacharSalleh)
|