archik 0.12.50 → 0.14.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 +194 -254
- package/dist/cli/archik.mjs +712 -371
- package/dist/ui/assets/index-Cd7sGYmr.js +226 -0
- package/dist/ui/assets/index-EA4oKR1S.css +1 -0
- package/dist/ui/index.html +2 -2
- package/package.json +1 -1
- package/skills/archik/SKILL.md +82 -5
- package/dist/ui/assets/index-DVBaG20X.css +0 -1
- package/dist/ui/assets/index-Dl4i5i09.js +0 -226
package/README.md
CHANGED
|
@@ -9,94 +9,94 @@
|
|
|
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 (`--run` executes them); `archik hooks install` gates every commit
|
|
45
|
+
- 🤝 **Team-ready** — semantic merge driver for YAML, node ownership with CODEOWNERS sync, and governance constraints (architecture fitness rules)
|
|
46
|
+
- 🔬 **Verified at every altitude** — `validate` proves the model is consistent, `drift --edges` proves it matches the code's import graph, `otel check` proves it matches production traffic
|
|
47
|
+
- 🚀 **Fast adoption** — `archik import compose` / `import mermaid` bootstrap a diagram from what you already have; `/archik:spawn` mirrors an existing source tree
|
|
48
|
+
- 📦 **Zero runtime dependencies** in the published package
|
|
46
49
|
|
|
47
|
-
##
|
|
50
|
+
## Installation
|
|
51
|
+
|
|
52
|
+
Requires **Node.js ≥ 20**.
|
|
48
53
|
|
|
49
54
|
```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
|
|
55
|
+
npx archik@latest init # scaffolds .archik/main.archik.yaml
|
|
56
|
+
# + installs the Claude skill and /archik:* commands
|
|
53
57
|
```
|
|
54
58
|
|
|
55
|
-
|
|
59
|
+
Or as a Claude Code plugin:
|
|
56
60
|
|
|
57
61
|
```
|
|
58
|
-
/
|
|
59
|
-
|
|
60
|
-
# on fresh projects, suggests /archik:spawn on existing
|
|
61
|
-
# codebases, surfaces trace status if already modelled)
|
|
62
|
+
/plugin marketplace add bacharSalleh/archik
|
|
63
|
+
/plugin install archik@archik
|
|
62
64
|
```
|
|
63
65
|
|
|
64
|
-
|
|
66
|
+
Both paths install the same skill and slash commands. The plugin still uses the `archik` npm binary, so Node is needed either way.
|
|
65
67
|
|
|
66
|
-
|
|
67
|
-
|
|
68
|
-
|
|
69
|
-
|
|
68
|
+
## Quick start
|
|
69
|
+
|
|
70
|
+
```bash
|
|
71
|
+
npx archik init # 1. scaffold
|
|
72
|
+
npx archik start # 2. open the live canvas (http://localhost:5173)
|
|
70
73
|
```
|
|
71
74
|
|
|
72
|
-
|
|
75
|
+
Then, in Claude Code:
|
|
73
76
|
|
|
74
|
-
|
|
77
|
+
```
|
|
78
|
+
/archik:bootstrap # 3. always your first message — detects project
|
|
79
|
+
# state and routes to the right next step
|
|
80
|
+
```
|
|
75
81
|
|
|
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>
|
|
82
|
+
Day-to-day:
|
|
81
83
|
|
|
82
|
-
|
|
84
|
+
| You type | You get |
|
|
85
|
+
| --- | --- |
|
|
86
|
+
| `/archik:suggest <feature>` | A staged diagram change, shown as a green/red diff overlay on the canvas — accept or reject |
|
|
87
|
+
| `/archik:usecase <name>` | A use case with flows, slices, and test paths |
|
|
88
|
+
| `/archik:trace` | "Are we done?" — the coverage matrix |
|
|
83
89
|
|
|
84
|
-
**
|
|
90
|
+
**Already have docker-compose or Mermaid diagrams?** Skip the blank canvas:
|
|
85
91
|
|
|
86
92
|
```bash
|
|
87
|
-
npx archik
|
|
88
|
-
|
|
89
|
-
|
|
90
|
-
**Claude Code plugin** — for the marketplace flow:
|
|
91
|
-
|
|
92
|
-
```
|
|
93
|
-
/plugin marketplace add bacharSalleh/archik
|
|
94
|
-
/plugin install archik@archik
|
|
93
|
+
npx archik import compose --out .archik/main.archik.yaml
|
|
94
|
+
npx archik import mermaid docs/architecture.mmd --out .archik/main.archik.yaml
|
|
95
95
|
```
|
|
96
96
|
|
|
97
|
-
|
|
97
|
+
Compose services become nodes (postgres → `database`, redis → `cache`, kafka → `stream`, …), build contexts become `sourcePath`s, and `depends_on` becomes edges. The Mermaid importer parses the flowchart subset: shaped nodes map to kinds, subgraphs become module parents, arrows become labelled edges.
|
|
98
98
|
|
|
99
|
-
##
|
|
99
|
+
## The YAML
|
|
100
100
|
|
|
101
101
|
```yaml
|
|
102
102
|
version: "1.0"
|
|
@@ -105,264 +105,204 @@ nodes:
|
|
|
105
105
|
- id: api
|
|
106
106
|
kind: service
|
|
107
107
|
name: Support API
|
|
108
|
-
sourcePath: src/api
|
|
108
|
+
sourcePath: src/api # must exist on disk — validator-enforced
|
|
109
109
|
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
|
|
110
|
+
owner: team-support # optional — who to talk to
|
|
117
111
|
- id: claude
|
|
118
112
|
kind: llm
|
|
119
113
|
name: Claude
|
|
120
114
|
description: LLM backend for draft generation.
|
|
121
115
|
edges:
|
|
122
|
-
- id: api-
|
|
116
|
+
- id: api-claude
|
|
123
117
|
from: api
|
|
124
|
-
to: agent
|
|
125
|
-
relationship: invokes
|
|
126
|
-
- id: agent-claude
|
|
127
|
-
from: agent
|
|
128
118
|
to: claude
|
|
129
119
|
relationship: invokes
|
|
130
|
-
label: draft reply
|
|
131
120
|
```
|
|
132
121
|
|
|
133
|
-
|
|
122
|
+
One file per layer, every link cross-checked by the validator:
|
|
134
123
|
|
|
135
|
-
|
|
124
|
+
| Layer | File | Captures |
|
|
125
|
+
| --- | --- | --- |
|
|
126
|
+
| Structure | `.archik/main.archik.yaml` | Services, databases, queues, agents, LLMs, edges |
|
|
127
|
+
| Actors | `*.archik.actors.yaml` | Who initiates use cases |
|
|
128
|
+
| Requirements | `.archik/usecases/*.archik.uc.yaml` | Flows + slices that name **test paths** |
|
|
129
|
+
| Behaviour | `*.archik.seq.yaml` | UML-subset sequence diagrams |
|
|
130
|
+
| Progress | `*.archik.alphas.yaml` | Essence/SEMAT alphas, machine-verified |
|
|
136
131
|
|
|
137
|
-
|
|
132
|
+
Full schema: `npx archik schema` (also `schema seq | uc | actors`).
|
|
138
133
|
|
|
139
|
-
|
|
140
|
-
Actor → Use case → Slice → Tests on disk → Seq diagram → Participant nodes → sourcePath on disk
|
|
141
|
-
```
|
|
134
|
+
## Everyday workflow
|
|
142
135
|
|
|
143
|
-
|
|
136
|
+
```bash
|
|
137
|
+
# What am I touching on this branch? Which tests cover it?
|
|
138
|
+
npx archik affected --since main
|
|
144
139
|
|
|
145
|
-
|
|
146
|
-
|
|
140
|
+
# …and run exactly those tests (vitest/jest/playwright/mocha auto-detected)
|
|
141
|
+
npx archik affected --since main --run
|
|
142
|
+
|
|
143
|
+
# What does this branch change architecturally?
|
|
144
|
+
npx archik diff origin/main # add --out diff.svg for the visual
|
|
147
145
|
|
|
148
|
-
|
|
149
|
-
|
|
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
|
|
146
|
+
# Is the diagram still telling the truth?
|
|
147
|
+
npx archik validate && npx archik drift
|
|
155
148
|
|
|
156
|
-
|
|
149
|
+
# Do the EDGES match the code? (TS/JS import-graph verification)
|
|
150
|
+
npx archik drift --edges # shadow + phantom edge detection
|
|
151
|
+
|
|
152
|
+
# Are we done?
|
|
153
|
+
npx archik trace
|
|
157
154
|
```
|
|
158
155
|
|
|
159
|
-
|
|
156
|
+
`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.
|
|
160
157
|
|
|
161
|
-
|
|
158
|
+
`drift --edges` scans the imports under every node's `sourcePath` and reports **shadow edges** (code imports across nodes with no declared edge) and **phantom edges** (structural edges with no import in either direction). Gate every commit locally with:
|
|
162
159
|
|
|
163
160
|
```bash
|
|
164
|
-
npx archik
|
|
161
|
+
npx archik hooks install # pre-commit: archik validate
|
|
165
162
|
```
|
|
166
163
|
|
|
167
|
-
##
|
|
168
|
-
|
|
169
|
-
**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.
|
|
164
|
+
## AI integration
|
|
170
165
|
|
|
171
|
-
**
|
|
166
|
+
**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.
|
|
172
167
|
|
|
173
|
-
**
|
|
168
|
+
**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, plus **resources** (`archik://schema`, `archik://stats`, `archik://trace`, `archik://validate`, `archik://drift`) and **prompts** (`propose-change`, `review-architecture`) that encode the same working loop the Claude Code skill teaches:
|
|
174
169
|
|
|
175
|
-
|
|
176
|
-
|
|
177
|
-
|
|
178
|
-
|
|
179
|
-
|
|
180
|
-
|
|
181
|
-
|
|
182
|
-
|
|
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 |
|
|
170
|
+
```jsonc
|
|
171
|
+
// .cursor/mcp.json, claude_desktop_config.json, etc.
|
|
172
|
+
{
|
|
173
|
+
"mcpServers": {
|
|
174
|
+
"archik": { "command": "npx", "args": ["archik", "mcp"] }
|
|
175
|
+
}
|
|
176
|
+
}
|
|
177
|
+
```
|
|
189
178
|
|
|
190
|
-
|
|
179
|
+
## Team workflow
|
|
191
180
|
|
|
192
|
-
|
|
181
|
+
**Semantic merges.** Stop resolving line-based YAML conflicts — nodes and edges are id-keyed, so most merges are mechanical:
|
|
193
182
|
|
|
194
|
-
|
|
183
|
+
```bash
|
|
184
|
+
npx archik merge-driver --install # once per clone; .gitattributes line is committed
|
|
185
|
+
```
|
|
195
186
|
|
|
196
|
-
|
|
197
|
-
| --------------------- | --------------------------------------------------------------------------- |
|
|
198
|
-
| `/archik:bootstrap` | Detects project state (fresh / has-code / already-modelled) and routes to the right next action — asks for a brief if you're starting from scratch, suggests `/archik:spawn` if there's existing code, surfaces the trace status if you're already running the loop. |
|
|
187
|
+
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.
|
|
199
188
|
|
|
200
|
-
**
|
|
189
|
+
**Ownership.** `owner: team-billing` on a node answers "who do I talk to": `archik q describe payments-db`, `archik q list --owner team-billing`. And `archik owners sync` writes one CODEOWNERS rule per owned node into a managed block (hand-authored rules untouched), with `archik owners check` as the CI gate so review routing can't drift from the model.
|
|
201
190
|
|
|
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 |
|
|
191
|
+
**Governance constraints.** Architecture fitness rules, enforced by `archik validate` on every run:
|
|
211
192
|
|
|
212
|
-
|
|
193
|
+
```yaml
|
|
194
|
+
constraints:
|
|
195
|
+
- id: billing-isolation
|
|
196
|
+
description: Only billing-context nodes may write to billing-db.
|
|
197
|
+
forbidEdge:
|
|
198
|
+
relationship: writes
|
|
199
|
+
from: { notParent: billing }
|
|
200
|
+
to: { id: billing-db }
|
|
201
|
+
- id: services-owned
|
|
202
|
+
description: Every service and worker declares an owning team.
|
|
203
|
+
requireOwner: { kinds: [service, worker] }
|
|
204
|
+
```
|
|
213
205
|
|
|
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 |
|
|
206
|
+
Intentional exceptions are grandfathered by id in an `except` list — visible in review, never silent.
|
|
220
207
|
|
|
221
|
-
|
|
208
|
+
## Verified against production
|
|
222
209
|
|
|
223
|
-
|
|
210
|
+
Map nodes to your tracing backend's service names (`metadata.otelService`, node id as the fallback), export the service-dependency graph, and let archik compare:
|
|
224
211
|
|
|
212
|
+
```bash
|
|
213
|
+
curl -s "http://jaeger:16686/api/dependencies?endTs=$(date +%s)000&lookback=86400000" > deps.json
|
|
214
|
+
npx archik otel check --graph deps.json
|
|
225
215
|
```
|
|
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
|
-
|
|
306
|
-
1. `.archik/main.archik.yaml` (preferred — keeps the project root tidy)
|
|
307
|
-
2. `architecture.archik.yaml` (legacy root location — still fully supported)
|
|
308
216
|
|
|
309
|
-
|
|
217
|
+
Undeclared production calls — traffic the diagram doesn't admit to — fail the check; declared wire edges that saw no traffic are reported informationally. That completes the truth chain: `validate` proves the model is consistent, `drift --edges` proves it matches the code, `otel check` proves it matches production.
|
|
310
218
|
|
|
311
|
-
##
|
|
219
|
+
## CI
|
|
312
220
|
|
|
313
|
-
|
|
314
|
-
|
|
315
|
-
**Via the npm CLI:**
|
|
221
|
+
Plain commands:
|
|
316
222
|
|
|
317
223
|
```bash
|
|
318
|
-
|
|
319
|
-
|
|
224
|
+
archik validate # schema + cross-file integrity + constraints
|
|
225
|
+
archik drift # diagram vs source tree
|
|
226
|
+
archik trace --fail-on partial # block merge on incomplete traceability
|
|
227
|
+
archik render --theme light --out docs/architecture.svg
|
|
320
228
|
```
|
|
321
229
|
|
|
322
|
-
|
|
323
|
-
|
|
324
|
-
**Via Claude Code's plugin marketplace:**
|
|
230
|
+
Or the GitHub Action, which runs all three and posts a sticky PR comment with the architecture diff vs the base branch:
|
|
325
231
|
|
|
326
|
-
```
|
|
327
|
-
|
|
328
|
-
|
|
232
|
+
```yaml
|
|
233
|
+
# .github/workflows/archik.yml
|
|
234
|
+
name: archik
|
|
235
|
+
on: [pull_request]
|
|
236
|
+
permissions:
|
|
237
|
+
contents: read
|
|
238
|
+
pull-requests: write
|
|
239
|
+
jobs:
|
|
240
|
+
archik:
|
|
241
|
+
runs-on: ubuntu-latest
|
|
242
|
+
steps:
|
|
243
|
+
- uses: actions/checkout@v4
|
|
244
|
+
- uses: bacharSalleh/archik@main
|
|
245
|
+
with:
|
|
246
|
+
trace-fail-on: partial # optional gate; omit for report-only
|
|
329
247
|
```
|
|
330
248
|
|
|
331
|
-
|
|
249
|
+
Inputs: `path`, `working-directory`, `validate`, `drift`, `trace-fail-on`, `compare-ref`, `comment`, `github-token`, `version`.
|
|
332
250
|
|
|
333
|
-
##
|
|
251
|
+
## CLI reference
|
|
252
|
+
|
|
253
|
+
Every command supports `--help`; agent-facing commands support `--json`.
|
|
254
|
+
|
|
255
|
+
| Command | What it does |
|
|
256
|
+
| --- | --- |
|
|
257
|
+
| `archik init` | Scaffold + install the Claude skill and slash commands |
|
|
258
|
+
| `archik dev` / `start` / `stop` / `status` | Live canvas lifecycle (foreground / detached) |
|
|
259
|
+
| `archik validate [path]` | Schema + cross-file + constraints (exit 1 on error) |
|
|
260
|
+
| `archik render --out <svg>` | Headless SVG render (`--seq <path>` for sequence diagrams) |
|
|
261
|
+
| `archik watch` | Re-render SVG on every change |
|
|
262
|
+
| `archik q <sub>` | Query: `describe` `deps` `dependents` `impact` `list` `edges` `stats` `usecases` `describe-usecase` `actors` `sequences` |
|
|
263
|
+
| `archik diff <a> [b]` | Diff two files **or git refs**; one arg = that ref vs working tree |
|
|
264
|
+
| `archik affected` | Changed files → nodes, slices, tests to run (`--since <ref>`, `--files`, `--run` to execute them) |
|
|
265
|
+
| `archik trace` | Coverage matrix (`--fail-on partial\|none` for CI) |
|
|
266
|
+
| `archik drift` | sourcePath / test-path gaps vs the source tree (`--edges` verifies edges vs the TS/JS import graph) |
|
|
267
|
+
| `archik otel check --graph <f>` | Verify edges against a production service-dependency graph |
|
|
268
|
+
| `archik suggest <sub>` | Suggestion sidecar lifecycle: `show` `set` `accept` `reject` |
|
|
269
|
+
| `archik alpha <sub>` | Essence alphas: `show`, `promote` (machine-checked), `demote` |
|
|
270
|
+
| `archik import compose\|mermaid [file]` | Bootstrap a document from docker-compose or a Mermaid flowchart |
|
|
271
|
+
| `archik merge-driver --install` | Semantic git merge for `*.archik.yaml` |
|
|
272
|
+
| `archik hooks install` | Pre-commit hook running `archik validate` (`--with-drift` optional) |
|
|
273
|
+
| `archik owners sync\|check` | Keep CODEOWNERS in step with node owners |
|
|
274
|
+
| `archik mcp` | MCP server over stdio (tools + resources + prompts) for non-Claude-Code agents |
|
|
275
|
+
| `archik schema [seq\|uc\|actors]` | Print the document schemas |
|
|
276
|
+
| `archik upgrade` | Upgrade + refresh installed skill/commands |
|
|
277
|
+
|
|
278
|
+
Default file resolution: `.archik/main.archik.yaml`, falling back to the legacy `architecture.archik.yaml` (both present = error).
|
|
334
279
|
|
|
335
|
-
|
|
280
|
+
## When to use it (and when not to)
|
|
336
281
|
|
|
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
|
|
282
|
+
**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
283
|
|
|
342
|
-
**Skip it when**
|
|
284
|
+
**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
285
|
|
|
344
|
-
|
|
345
|
-
|
|
346
|
-
|
|
286
|
+
| | archik | Mermaid / PlantUML | Structurizr |
|
|
287
|
+
| --- | --- | --- | --- |
|
|
288
|
+
| Source format | Plain YAML | Custom DSL | Structurizr DSL |
|
|
289
|
+
| AI-editor integration | **Skill + MCP** | None | None |
|
|
290
|
+
| Use cases / test traceability | **Mechanical** | No | No |
|
|
291
|
+
| Drift detection | **Yes** | No | No |
|
|
292
|
+
| Governance constraints | **Yes** | No | No |
|
|
293
|
+
| Validator | **Schema + cross-file + ECB** | Syntax only | Syntax only |
|
|
347
294
|
|
|
348
|
-
|
|
295
|
+
## Contributing
|
|
349
296
|
|
|
350
|
-
|
|
297
|
+
See [CONTRIBUTING.md](./CONTRIBUTING.md). Development:
|
|
351
298
|
|
|
352
299
|
```bash
|
|
353
|
-
|
|
354
|
-
archik
|
|
355
|
-
|
|
356
|
-
|
|
300
|
+
npm install
|
|
301
|
+
npm run archik -- --help # run the CLI from source
|
|
302
|
+
npm test # vitest
|
|
303
|
+
npm run typecheck
|
|
357
304
|
```
|
|
358
305
|
|
|
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
306
|
## License
|
|
367
307
|
|
|
368
308
|
MIT © [Bashar](https://github.com/bacharSalleh)
|