archik 0.9.2 → 0.10.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/.claude/commands/archik/evolve.md +8 -3
- package/.claude/commands/archik/spawn.md +5 -1
- package/.claude/commands/archik/suggest.md +11 -5
- package/.claude/skills/archik/SKILL.md +22 -22
- package/dist/cli/archik.mjs +173 -173
- package/dist/ui/assets/index-D0bEW_9Y.js +223 -0
- package/dist/ui/assets/{index-nse9tpWd.css → index-DnDEbNgO.css} +1 -1
- package/dist/ui/index.html +2 -2
- package/package.json +1 -1
- package/dist/ui/assets/index-D0-QorMW.js +0 -220
|
@@ -109,9 +109,14 @@ any file under `.archik/`.
|
|
|
109
109
|
`sourcePath:` that exists on disk — the validator rejects
|
|
110
110
|
fabricated paths. If the refactor proposes a not-yet-built
|
|
111
111
|
module (e.g. extracting a `payments` context that doesn't have
|
|
112
|
-
a directory yet),
|
|
113
|
-
|
|
114
|
-
|
|
112
|
+
a directory yet), mark the node `status: proposed` and omit
|
|
113
|
+
`sourcePath` — the validator exempts proposed nodes from the
|
|
114
|
+
requirement. The canvas renders proposed nodes with a dashed
|
|
115
|
+
indigo border so the user sees they're planned. Edges into /
|
|
116
|
+
out of a proposed node should also carry `status: proposed`
|
|
117
|
+
until the code lands.
|
|
118
|
+
- Every node MUST have a non-empty `description` explaining
|
|
119
|
+
what it does. Don't introduce a node without one.
|
|
115
120
|
- Every change should be motivated by step 3, not by aesthetics.
|
|
116
121
|
|
|
117
122
|
If `suggest set` reports validation errors, re-run with the
|
|
@@ -66,7 +66,11 @@ archik suggest set` stages it.
|
|
|
66
66
|
- **Manifest files**: `package.json` `name`, `Cargo.toml`,
|
|
67
67
|
`go.mod`, `pyproject.toml` give canonical component names.
|
|
68
68
|
- **`README` / `description`**: pull a one-line summary if
|
|
69
|
-
present
|
|
69
|
+
present. Description is REQUIRED on every node — if there's
|
|
70
|
+
no README and no obvious one-liner in code comments, write
|
|
71
|
+
a short sentence yourself describing what the directory /
|
|
72
|
+
module does (its responsibility, not just its name). The
|
|
73
|
+
validator rejects nodes without a description.
|
|
70
74
|
- **Stack hints**: `package.json` deps (Next.js, Express, Fastify,
|
|
71
75
|
Hono → service/frontend), `go.mod`, `requirements.txt`,
|
|
72
76
|
`Gemfile`. Set `stack` only when the signal is clear.
|
|
@@ -63,11 +63,17 @@ the contract with the user.
|
|
|
63
63
|
**Every new code-bearing node** (`service`, `function`, `worker`,
|
|
64
64
|
`module`, `page`, `component`, `store`, `hook`) must declare a
|
|
65
65
|
`sourcePath:` that you have verified exists on disk. The
|
|
66
|
-
validator rejects fabricated paths. If the source doesn't
|
|
67
|
-
yet (you're proposing a not-yet-built component),
|
|
68
|
-
|
|
69
|
-
|
|
70
|
-
|
|
66
|
+
validator rejects fabricated paths. If the source doesn't
|
|
67
|
+
exist yet (you're proposing a not-yet-built component), mark
|
|
68
|
+
the node `status: proposed` and omit `sourcePath` — the
|
|
69
|
+
validator exempts proposed nodes from the requirement and the
|
|
70
|
+
canvas renders them with a dashed indigo border so the user
|
|
71
|
+
sees they're planned.
|
|
72
|
+
|
|
73
|
+
**Every node must also declare a non-empty `description`** that
|
|
74
|
+
explains what the node DOES (its responsibility / behaviour),
|
|
75
|
+
not just its kind or name. Empty / missing descriptions are
|
|
76
|
+
rejected by the validator.
|
|
71
77
|
|
|
72
78
|
```bash
|
|
73
79
|
npx archik suggest set --note "$ARGUMENTS" - <<'YAML'
|
|
@@ -27,41 +27,41 @@ You MUST NOT use `Read`, `Write`, or `Edit` against any file under `.archik/`, a
|
|
|
27
27
|
|
|
28
28
|
If `npx archik` is unreachable (offline, sandboxed, missing), STOP and tell the user. Do NOT fall back to reading or editing YAML by hand.
|
|
29
29
|
|
|
30
|
-
## File modes —
|
|
31
|
-
|
|
32
|
-
Archik files have **three modes**, selected by filename suffix. Validation strictness differs per mode — picking the wrong one will either reject your draft or pollute the canonical architecture with greenfield speculation.
|
|
30
|
+
## File modes — two modes, picked by filename
|
|
33
31
|
|
|
34
32
|
| Suffix | Mode | When to use | sourcePath rule |
|
|
35
33
|
| ---------------------------------- | ------------ | ---------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------- |
|
|
36
34
|
| `*.archik.yaml` | **normal** | The canonical architecture of code that exists. | Required for code-bearing kinds; **must exist on disk** (validated). |
|
|
37
35
|
| `*.archik.suggested.yaml` | **suggested**| A pending change to a normal file. Owned by `suggest set`. Becomes normal on `suggest accept`. | Same rules as normal — it'll become normal when accepted. |
|
|
38
|
-
| `*.archik.discussion.yaml` | **discussion**| Greenfield / exploratory drafts: a brand-new project, an "what if we built X?" sketch, an option. | `sourcePath` is **optional**, and may point at paths that don't exist yet. |
|
|
39
36
|
|
|
40
|
-
|
|
37
|
+
There is **no separate "discussion" file mode**. Greenfield / exploratory work — a node you want in the diagram before its code exists — is expressed via `status: proposed` on the affected nodes (and edges); see the next section. The diagram stays the canonical architecture.
|
|
41
38
|
|
|
42
|
-
**
|
|
43
|
-
- Are you describing real code that exists in this repo? → **normal** (or **suggested** if proposing a change).
|
|
44
|
-
- Are you sketching a not-yet-built system, or proposing an architecture for a new project? → **discussion**. Don't pollute the main file with speculation.
|
|
45
|
-
- Are you adding a `sourcePath` for a node whose code is going to be created soon? → **discussion**, then move to **normal** once the code exists.
|
|
39
|
+
**Code-bearing kinds** (those that must declare `sourcePath`): `service`, `function`, `worker`, `module`, `page`, `component`, `store`, `hook`. Other kinds (`external`, `cloud`, `prompt`, `llm`, `route`, `interface`, `adapter`, `port`, `database`, `cache`, `queue`, `topic`, `stream`, `gateway`, `cdn`, `agent`, `frontend`, `vectordb`, `storage`, `auth`, `observability`, `tool`, `custom`) are exempt.
|
|
46
40
|
|
|
47
|
-
If `suggest set` rejects your draft with a `sourcePath` error, the right answer is usually one of: (a) fix the path to point at real code, (b)
|
|
41
|
+
If `suggest set` rejects your draft with a `sourcePath` error, the right answer is usually one of: (a) fix the path to point at real code, (b) use a non-code-bearing kind (e.g., `external` for a third-party service), or (c) mark the node `status: proposed` if it's a planned-but-not-built component (see "Lifecycle status" below).
|
|
48
42
|
|
|
49
|
-
##
|
|
43
|
+
## Required `description` — every node, every time
|
|
50
44
|
|
|
51
|
-
|
|
45
|
+
`description` is **required** on every node — empty strings rejected, missing values rejected. The description must explain **what the node does** — its responsibility, the work it performs, why it exists — not just restate its `kind` or `name`.
|
|
52
46
|
|
|
53
|
-
|
|
54
|
-
|
|
55
|
-
|
|
56
|
-
|
|
57
|
-
|
|
47
|
+
> Bad: *"A service."* *"The orders module."* *"Frontend."*
|
|
48
|
+
> Good: *"Owns order placement and status — accepts cart payloads, validates inventory, writes to `orders` and emits `order.placed` to the stream."*
|
|
49
|
+
|
|
50
|
+
Two reasons it's enforced:
|
|
51
|
+
1. The diagram is the shared map between you and the user. A node without a description is a black box neither of you can reason about.
|
|
52
|
+
2. When the user asks *"what does X do?"*, you should be answering from `npx archik q describe X`, not from intuition. That answer is only useful if the description was written with care.
|
|
58
53
|
|
|
59
|
-
|
|
54
|
+
## Lifecycle status — `proposed`, `active`, `deprecated` (nodes AND edges)
|
|
60
55
|
|
|
61
|
-
|
|
62
|
-
|
|
56
|
+
Both **nodes and edges** carry an optional `status` field — same enum, same defaults, same visual treatment. Use it to keep the canonical diagram honest about what's built vs. what's planned vs. what's going away.
|
|
57
|
+
|
|
58
|
+
| status | When | sourcePath rule (nodes only) | Visual |
|
|
59
|
+
| ------------------------- | --------------------------------------------------------------------------------------------- | ---------------------------------------------------------- | ------------------------------------- |
|
|
60
|
+
| absent / `active` | Built and live (default). | Required for code-bearing kinds, must exist on disk. | Standard solid stroke. |
|
|
61
|
+
| `proposed` | Planned for the next iteration — belongs in the canonical map but isn't built yet. | Optional. If you supply one, it must still exist on disk. | Dashed indigo border, reduced opacity. |
|
|
62
|
+
| `deprecated` | Being phased out; reads/writes shouldn't depend on it going forward. | Optional. Same on-disk rule as `proposed` if you set one. | Dashed amber border + strikethrough on the name. |
|
|
63
63
|
|
|
64
|
-
|
|
64
|
+
For edges, `status: proposed` expresses "this dependency is planned" (e.g. *"orders-api will start subscribing to `payments.completed` next sprint"* — set the new edge's `status: proposed` until the code lands). `archik drift` and the validator both respect the lifecycle so proposed nodes don't trigger missing-source warnings before they're built.
|
|
65
65
|
|
|
66
66
|
## Other validation rules worth pre-empting
|
|
67
67
|
|
|
@@ -109,7 +109,7 @@ Then `ls -F . src/ services/ packages/ apps/ 2>/dev/null` for the source tree. B
|
|
|
109
109
|
|
|
110
110
|
When the user asks "where would I add X?", you should already have the answer because you ran the queries above.
|
|
111
111
|
|
|
112
|
-
**Every code-bearing node you propose for a normal/suggested file must declare a `sourcePath` that you have verified exists on disk** (e.g. `ls src/payments/worker.ts` before authoring `sourcePath: src/payments/worker.ts`). The validator rejects fabricated paths — and the rejection is non-negotiable, exactly so hallucinated nodes can't slip into the canonical architecture. If the source doesn't exist yet,
|
|
112
|
+
**Every code-bearing node you propose for a normal/suggested file must declare a `sourcePath` that you have verified exists on disk** (e.g. `ls src/payments/worker.ts` before authoring `sourcePath: src/payments/worker.ts`). The validator rejects fabricated paths — and the rejection is non-negotiable, exactly so hallucinated nodes can't slip into the canonical architecture. If the source doesn't exist yet, mark the node `status: proposed` and omit `sourcePath` (or set one that points where the code WILL live, but it has to actually exist by the time you flip the status to active).
|
|
113
113
|
|
|
114
114
|
## Authoring drafts (sidecar workflow)
|
|
115
115
|
|