archik 0.7.0 → 0.7.2

package/.claude/commands/archik/accept.md

@@ -1,5 +1,5 @@
 ---
-description: Apply the pending archik suggestion sidecar over the main file
+description: Apply the pending suggestion
 ---
 
 # /archik:accept — apply the pending suggestion

package/.claude/commands/archik/describe.md

@@ -1,5 +1,5 @@
 ---
-description: Describe a node in the archik diagram and its incoming/outgoing edges
+description: Show a node's connections
 argument-hint: <node-id>
 ---
 

package/.claude/commands/archik/dev.md

@@ -1,5 +1,5 @@
 ---
-description: Start the archik live canvas in the browser (detached)
+description: Open the live canvas
 ---
 
 # /archik:dev — open the archik canvas

package/.claude/commands/archik/evolve.md

@@ -0,0 +1,136 @@
+---
+description: Propose a cleaner modular refactor
+argument-hint: [optional focus area]
+---
+
+# /archik:evolve — propose a cleaner, bounded architecture
+
+The user wants you to look at the current diagram with a critical
+eye and **propose a refactor toward a cleaner modular architecture
+with clear bounded contexts**. Stage the proposal as a sidecar so
+the diff overlay highlights what would change, then **wait for the
+user to discuss before they accept** — evolve is a conversation,
+not a one-shot.
+
+If `$ARGUMENTS` is non-empty, treat it as the area to focus on
+(e.g. *"payments domain"*, *"the orders module"*, *"async wiring
+between services"*). If empty, evaluate the whole diagram.
+
+## CLI-only — do not touch archik files directly
+
+You MUST interact with archik exclusively through the `npx archik`
+CLI. Drafts go to a workspace temp file, then `npx archik suggest
+set` stages them. Do NOT use `Read`, `Write`, or `Edit` against
+any file under `.archik/`.
+
+## Steps
+
+1. **Make sure the canvas is running**: `npx archik status` →
+   `npx archik start` if needed. Note the URL for step 6.
+
+2. **Ground yourself in the current shape** via the query CLI:
+   ```
+   npx archik q stats
+   npx archik q list
+   npx archik q edges
+   ```
+   If `$ARGUMENTS` names a specific area, also:
+   ```
+   npx archik q describe <id>
+   npx archik q deps <id>
+   npx archik q dependents <id>
+   npx archik q impact <id>
+   ```
+   Refuse politely and stop if the diagram has fewer than 3 nodes
+   — there's nothing meaningful to evolve. Suggest `/archik:spawn`
+   first.
+
+3. **Identify smells and missing structure.** Don't propose change
+   for change's sake — every modification should fix one of:
+
+   - **Bounded contexts unclear.** Several services share a
+     domain language but aren't grouped → wrap in a `module`
+     container per context.
+   - **God service.** One node owns too many responsibilities or
+     reaches into too many domains → split along bounded
+     contexts, with the original kept only as the API surface
+     facing the outside.
+   - **Leaky boundaries.** Cross-context `reads` / `writes`
+     directly on another context's database → introduce a `port`
+     + `adapter` pair, or replace with `publishes` / `subscribes`
+     events.
+   - **Missing hexagonal structure** at external boundaries.
+     Direct `http_call` to Stripe / OpenAI / payment processor →
+     introduce a `port` (the abstract contract) and an `adapter`
+     (the concrete impl), with `implements` between them.
+   - **Cyclic dependencies** between modules — should be inverted
+     (events) or broken (extract shared kernel).
+   - **Anaemic queues.** Two services connected by `http_call`
+     for what's clearly an async fire-and-forget → introduce a
+     `queue` or `topic` and rewire to `publishes` / `subscribes`.
+
+   Aim for 3–8 changes — enough to be meaningful, few enough that
+   the user can reason about each. If you'd need more, propose
+   the highest-impact subset and tell the user the rest is round
+   two.
+
+4. **Author + stage in one step.** Pipe the full proposed
+   end-state directly into `npx archik suggest set -` via a
+   heredoc — no temp files, no `/tmp/` paths:
+
+   ```bash
+   npx archik suggest set --note "evolve: <one-line summary>" - <<'YAML'
+   version: "1.0"
+   name: My Architecture
+   nodes:
+     # full proposed end-state — every node, not just the delta
+   edges:
+     # ...
+   YAML
+   ```
+
+   Constraints when authoring the YAML:
+   - Preserve every existing node id you keep — only add or remove
+     ids, never rename. Renames break diff and require the user to
+     manually re-link references in code.
+   - Don't drop `description`, `responsibilities`, or `notes`
+     fields the user authored. Carry them over verbatim.
+   - Every change should be motivated by step 3, not by aesthetics.
+
+   If `suggest set` reports validation errors, re-run with the
+   corrected YAML. Never patch the sidecar directly.
+
+5. **Open the discussion.** Print, in this order:
+
+   a. The canvas URL with: *"📝 Evolved diagram staged — open
+      <URL> and toggle Review to see green / red / amber overlays."*
+   b. A numbered, plain-English summary of the proposed changes,
+      grouped by motivation (e.g. *"1. Extract a `payments`
+      bounded context from `orders`. Why: payment logic was leaking
+      into order placement…"*). Keep each item to 2–3 sentences.
+   c. An explicit invitation: *"Tell me what you'd like to keep,
+      drop, or rework before you accept. I can re-stage with
+      changes — `/archik:accept` is whenever you're ready."*
+
+   **Do NOT auto-accept.** Even if the user said "evolve and apply"
+   in shorthand, evolve always stops at the staged sidecar so the
+   diff is reviewable.
+
+## Iterating
+
+If the user pushes back on specific items ("keep the orders
+service whole; only fix the Stripe integration"), re-run
+`npx archik suggest set -` with the revised YAML — it overwrites
+the previous sidecar. Acknowledge what you changed
+since the last round so the user doesn't have to re-read the
+whole diff.
+
+## Notes
+
+- Evolve is bounded-context-aware but doesn't blindly apply DDD.
+  If the project is genuinely small and a single service is the
+  right answer, say so and stage no changes — better than
+  inventing structure for its own sake.
+- If you'd need to look at code (not just the diagram) to make a
+  responsible recommendation, say so up front and ask for
+  permission to read specific files. Don't silently expand scope.

package/.claude/commands/archik/reject.md

@@ -1,5 +1,5 @@
 ---
-description: Discard the pending archik suggestion sidecar
+description: Discard the pending suggestion
 ---
 
 # /archik:reject — discard the pending suggestion

package/.claude/commands/archik/spawn.md

@@ -0,0 +1,164 @@
+---
+description: Mirror the source tree as a diagram
+---
+
+# /archik:spawn — mirror the codebase as an archik diagram
+
+The user wants a first-pass archik diagram that **reflects the
+project as it actually is right now**, not as it should be. Read
+the source tree, infer the components and the wiring, stage the
+result as a suggestion sidecar so the user can review it on the
+canvas before accepting.
+
+Use `/archik:evolve` afterwards if they want a cleaner version.
+Spawn = mirror. Evolve = improve.
+
+## CLI-only — do not touch archik files directly
+
+You MUST interact with archik exclusively through the `npx archik`
+CLI. Do NOT use `Read`, `Write`, or `Edit` on any file under
+`.archik/`. Your draft goes to a workspace temp file, then `npx
+archik suggest set` stages it.
+
+## Steps
+
+1. **Make sure the canvas is running** so the user can review:
+   ```
+   npx archik status
+   ```
+   If nothing is running, start it detached: `npx archik start`.
+   Note the URL.
+
+2. **Check what's already there** — if the project already has a
+   meaningful archik file, this command will *replace* it via the
+   suggestion workflow. Confirm with the user before proceeding
+   when the diagram has substance:
+   ```
+   npx archik q stats
+   ```
+   - 0 nodes / starter scaffold (web + api + db, the `archik init`
+     default) → proceed silently.
+   - Real content → tell the user "I'm about to replace the
+     current diagram with a fresh one mirroring the source tree —
+     this will produce a sidecar you can review or reject. Want me
+     to continue?" Wait for confirmation.
+
+3. **Map the source tree.** Walk the project from cwd, paying
+   attention to conventional layouts. Don't recurse into
+   `node_modules`, `dist`, `build`, `.git`, `.next`,
+   `target`, `venv`, `.venv`, or `vendor`.
+
+   Useful signals (apply only if they fit the project — never
+   invent structure):
+   - **Top-level dirs**: `apps/`, `services/`, `packages/`, `src/`,
+     `cmd/`, `internal/`, `lambdas/`, `workers/`, `agents/`.
+     Each child usually maps to one node.
+   - **Manifest files**: `package.json` `name`, `Cargo.toml`,
+     `go.mod`, `pyproject.toml` give canonical component names.
+   - **`README` / `description`**: pull a one-line summary if
+     present; otherwise omit `description` rather than fabricate.
+   - **Stack hints**: `package.json` deps (Next.js, Express, Fastify,
+     Hono → service/frontend), `go.mod`, `requirements.txt`,
+     `Gemfile`. Set `stack` only when the signal is clear.
+   - **Datastores**: a `migrations/` folder, a `schema.sql`,
+     `prisma/`, `drizzle/`, `flyway/`, references to Postgres /
+     MySQL / Redis / Mongo / S3 / Pinecone / pgvector in deps or
+     env files → corresponding `database` / `cache` / `vectordb` /
+     `storage` node.
+   - **Queues / streams**: SQS / RabbitMQ / Kafka / Kinesis client
+     deps or config → `queue` / `topic` / `stream` node.
+   - **External APIs**: Stripe, OpenAI, Anthropic, Twilio, GitHub
+     SDKs in deps → `external` (or `llm` for OpenAI / Anthropic)
+     nodes.
+   - **Frontends**: `apps/web`, `apps/mobile`, `client/`,
+     `packages/ui` apps that ship a UI → `frontend`.
+
+4. **Choose the kind for each node.** Default: `service`. Use the
+   taxonomy from the skill — `function` for serverless, `worker`
+   for background consumers, `agent` for LLM-driven agents, etc.
+   When unsure, pick the closest fit and add a `notes:` entry
+   explaining the inference rather than picking `custom`.
+
+5. **Nest by structure**, mirroring the directories.
+   - Top-level grouping dir (e.g. `services/`) → a `module` container.
+   - Each child dir → a node with `parentId` pointing at the container.
+   - If a node has substantial internal structure (e.g.
+     `services/orders/{api,domain,db}`), emit a stub
+     `archikFile: .archik/<id>.archik.yaml` and *also* draft that
+     sub-file. Don't nest beyond two levels in the main file —
+     drill-down is what `archikFile` is for.
+
+6. **Wire the edges.** Be conservative — only add an edge when you
+   have actual evidence:
+   - Cross-package imports → `depends_on` or a more specific
+     relationship (`uses`, `invokes`).
+   - HTTP route handlers calling another service's endpoint →
+     `http_call`.
+   - DB client usage → `reads` / `writes`.
+   - Queue producer / consumer code → `publishes` / `subscribes`.
+   - Webhook handlers (e.g. `/webhooks/stripe`) → `webhook` from
+     the external node.
+
+   When in doubt, leave the edge out. The user will add it via
+   `/archik:suggest` later.
+
+7. **Stage the draft.** Pipe the YAML straight into `npx archik
+   suggest set -` via a heredoc — no temp files, no `/tmp/` paths.
+   Sub-files come first because the main draft references them via
+   `archikFile`, and `suggest set` validates that those targets
+   exist on disk.
+
+   a. **Each sub-file**: the parent file doesn't exist yet, so
+      pass `--allow-orphan` to opt in to writing a sidecar for a
+      missing main. Then accept it so the file lands at
+      `.archik/<id>.archik.yaml`:
+      ```bash
+      npx archik suggest set --main .archik/<id>.archik.yaml \
+                             --allow-orphan \
+                             --note "spawn: <id> internals" - <<'YAML'
+      version: "1.0"
+      name: <Id> Internals
+      nodes: [ ... ]
+      edges: [ ... ]
+      YAML
+      npx archik suggest accept .archik/<id>.archik.yaml
+      ```
+      Repeat for every sub-file. The `accept` step is what makes
+      the file real on disk — without it the orphan sidecar lingers
+      and the canvas shows it as "(pending)" rather than rendering it.
+
+   b. **Main draft**: once all sub-files exist (i.e. their
+      `accept`s succeeded), stage the main one. No `--allow-orphan`
+      needed because the main file already exists from `archik init`:
+      ```bash
+      npx archik suggest set --note "spawn: mirror source tree" - <<'YAML'
+      version: "1.0"
+      name: My Architecture
+      nodes:
+        # full proposed end-state, with archikFile pointers
+      edges:
+        # ...
+      YAML
+      ```
+
+   c. If `suggest set` reports validation errors, re-run with the
+      corrected YAML. Never edit the sidecar by hand.
+
+8. **Tell the user how to review.** Surface the canvas URL plus:
+   - "📝 Initial diagram staged from source tree — open the
+     canvas at <URL> and use Review to see the proposed nodes."
+   - "Looks wrong? Run `/archik:reject` and we'll iterate. Or run
+     `/archik:evolve` after accepting if you want a cleaner
+     bounded-context version."
+
+## Notes
+
+- Spawn is descriptive, not prescriptive. Don't reorganize, split,
+  or merge components — just mirror what's there. Cleanup is
+  `/archik:evolve`'s job.
+- Don't fabricate edges to fill gaps in the diagram. An incomplete
+  but accurate diagram is more useful than a complete-looking but
+  wrong one.
+- If the source tree is one big monolith with no obvious
+  decomposition, output a single node and tell the user — don't
+  invent fake sub-services.

package/.claude/commands/archik/suggest.md

@@ -1,5 +1,5 @@
 ---
-description: Propose architecture changes to the archik diagram from a feature description
+description: Propose a diagram change
 argument-hint: <feature description>
 ---
 
@@ -43,22 +43,28 @@ the contract with the user.
    If `$ARGUMENTS` mentions a specific node by name, also run
    `npx archik q describe <id>` for it.
 
-3. **Author the draft** in a workspace temp file (NOT under
-   `.archik/`). Use the path `/tmp/archik-draft-<short-id>.yaml`.
-   The draft is the *full proposed end-state* of the document — every
-   node and edge, not just the delta. Follow the schema, kinds, and
-   relationships documented in the archik skill.
+3. **Author + stage in one step.** Pipe the draft straight into
+   `npx archik suggest set -` via a heredoc — no temp file, no
+   `/tmp/` paths. The CLI validates the schema, checks cross-file
+   references, stamps `metadata.suggestion`, and atomically writes
+   `.archik/main.archik.suggested.yaml`:
 
-4. **Stage the draft as the sidecar via the CLI**:
+   ```bash
+   npx archik suggest set --note "$ARGUMENTS" - <<'YAML'
+   version: "1.0"
+   name: My Architecture
+   nodes:
+     # full proposed end-state — every node, not just the delta
+   edges:
+     # full proposed end-state — every edge, not just the delta
+   YAML
    ```
-   npx archik suggest set /tmp/archik-draft-<id>.yaml --note "$ARGUMENTS"
-   ```
-   This validates the schema, checks cross-file references, stamps
-   `metadata.suggestion`, and atomically renames it into place. If
-   the command exits non-zero, fix the reported errors in the temp
-   file and re-run — never edit the sidecar directly.
 
-5. **Tell the user how to review**. Surface the canvas URL from
+   If the command exits non-zero, re-run with the corrected YAML.
+   Never write a draft file under `.archik/` and never edit the
+   sidecar directly.
+
+4. **Tell the user how to review**. Surface the canvas URL from
    step 1 plus the terminal options:
    - "📝 Suggestion ready — open the canvas at <URL> and use the
      **Review** banner to see added/removed/changed nodes."

package/.claude/skills/archik/SKILL.md

@@ -51,12 +51,32 @@ If `npx archik` is unreachable (offline, sandboxed, missing), STOP
 and tell the user. Do NOT fall back to reading or editing YAML by
 hand — that breaks the contract and silently desyncs the canvas.
 
-The user-facing slash commands (`/archik:suggest`,
-`/archik:describe`, `/archik:accept`, `/archik:reject`,
-`/archik:dev`) are thin shims over this same CLI. When a user types
-`/archik:suggest <description>`, treat it as direct authorisation to
-run the sidecar workflow now — skip the "want me to update the YAML?"
-question.
+The user-facing slash commands are thin shims over this same CLI:
+
+| Command                | Purpose                                       |
+| ---------------------- | --------------------------------------------- |
+| `/archik:spawn`        | Bootstrap a diagram from the source tree       |
+| `/archik:evolve`       | Propose a cleaner bounded-context refactor    |
+| `/archik:suggest <…>`  | Propose changes from a feature description    |
+| `/archik:describe <id>`| Explain a node and its connections            |
+| `/archik:accept`       | Apply the pending suggestion                  |
+| `/archik:reject`       | Discard the pending suggestion                |
+| `/archik:dev`          | Start the live canvas                         |
+
+When a user types `/archik:suggest <description>`, `/archik:spawn`,
+or `/archik:evolve`, treat it as direct authorisation to run the
+sidecar workflow now — skip the "want me to update the YAML?"
+question. Each command's body file under `.claude/commands/archik/`
+has the detailed protocol for that specific verb; follow it.
+
+Three things separate the proposal commands:
+
+- **`spawn`** is *descriptive* — mirror the source tree as it is.
+- **`evolve`** is *prescriptive* — propose a cleaner shape, then
+  wait for the user to discuss before they accept. Never
+  auto-accepts.
+- **`suggest`** is *targeted* — apply one feature-sized change
+  from a user description.
 
 ## Protocol
 

package/README.md

@@ -26,10 +26,11 @@ queues, agents, LLMs, the edges between them. Plain YAML, schema-
 validated, no coordinates, no proprietary format.
 
 Open it in your browser for a live canvas. Render it in CI for a
-self-contained SVG. Install the [Claude Code skill](#for-claude-code--other-llms)
-so the model edits the same file you do — *the diagram and the
-codebase stop drifting because Claude treats the diagram as the
-spec*.
+self-contained SVG. The [Claude Code skill and `/archik:*` slash
+commands](#for-claude-code--other-llms) install automatically with
+`archik init`, so the model edits the same file you do — *the
+diagram and the codebase stop drifting because Claude treats the
+diagram as the spec*.
 
 If you've ever asked an AI agent "where would I add X?" and watched
 it guess from filenames, archik is the fix: the YAML answers the
@@ -38,13 +39,25 @@ work.
 
 ## Quickstart
 
+Two terminal commands, then talk to Claude:
+
 ```bash
-npx archik init       # scaffold .archik/main.archik.yaml in cwd
-npx archik start      # canvas at http://localhost:5173 (background)
-npx archik stop       # done
+npx archik@latest init       # scaffolds .archik/main.archik.yaml +
+                             # installs the Claude skill + /archik:* slash commands
+npx archik@latest start      # opens the live canvas at http://localhost:5173
 ```
 
-That's the whole onboarding. The canvas saves edits straight back to the YAML; the file is the truth, the canvas is a projection.
+Then in Claude Code, type:
+
+```
+/archik:spawn               # mirror your real source tree as the first diagram
+/archik:evolve              # propose a cleaner bounded-context refactor
+/archik:suggest <feature>   # propose changes for a specific feature
+```
+
+Each `/archik:*` command stages a suggestion sidecar — **Review** in the canvas, then **Accept** or **Reject**. No manual YAML editing on either side: you click in the browser, Claude drives through the CLI.
+
+Done with the canvas? `npx archik stop`.
 
 <p align="center">
   <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>
@@ -90,28 +103,49 @@ No `x` / `y` / `width` — layout is computed by [ELK](https://eclipse.dev/elk/)
 - **12 relationships** with distinct visual styling — `http_call`, `invokes`, `reads`, `writes`, `publishes`, `subscribes`, `streams_to`, `routes_to`, `implements`, `depends_on`, `has_a`, `uses`.
 - **Drag-to-connect, multi-select, undo/redo, compact view, themed (dark / light), notes per node, color overrides on edges.**
 - **CI-ready CLI** — `validate`, `render` (headless SVG), `watch`, `check` (drift between YAML and source dirs).
-- **AI skill + slash commands** — `archik skill --user` installs the Claude Code skill; `archik commands --user` installs `/archik:suggest`, `/archik:accept`, `/archik:reject`, `/archik:describe`, and `/archik:dev` so Claude drives the diagram entirely through the CLI.
+- **AI skill + slash commands** — `archik init` installs both automatically. Seven `/archik:*` commands (`spawn`, `evolve`, `suggest`, `describe`, `dev`, `accept`, `reject`) drive the diagram entirely through the CLI, so Claude never edits YAML by hand.
 
 ## For Claude Code & other LLMs
 
-The whole reason Archik uses YAML instead of a binary format: **the file is the shared map between you and the model**. Run:
+The whole reason archik uses YAML instead of a binary format: **the file is the shared map between you and the model**. `npx archik@latest init` drops both the Claude skill and the seven slash commands into your project — no separate setup.
 
-```bash
-archik skill --user        # install the skill into ~/.claude/skills
-archik commands --user     # install the /archik:* slash commands into ~/.claude/commands
-```
+The skill enforces a hard rule: **Claude talks to archik only through the `npx archik` CLI** — never `Read`, `Write`, or `Edit` on a YAML directly. Queries go 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.
 
-(Or just `archik init` in a fresh project — both land automatically.)
+### The seven slash commands
 
-The skill enforces a hard rule: **Claude interacts with archik only through the `npx archik` CLI** — never `Read`, `Write`, or `Edit` on a YAML directly. Queries go through `npx archik q`, suggestions through `npx archik suggest set`, lifecycle through `npx archik suggest accept | reject`. The user owns the file; the CLI is the contract.
+| Command                     | What it does                                                |
+| --------------------------- | ----------------------------------------------------------- |
+| `/archik:spawn`             | Bootstrap a diagram by mirroring your real source tree      |
+| `/archik:evolve`            | Propose a cleaner bounded-context refactor                  |
+| `/archik:suggest <feature>` | Propose changes for a specific feature                      |
+| `/archik:describe <id>`     | Explain a node and its connections                          |
+| `/archik:dev`               | Open the live canvas                                        |
+| `/archik:accept`            | Apply the pending suggestion                                |
+| `/archik:reject`            | Discard the pending suggestion                              |
 
-Day-to-day this looks like:
+A typical first-day flow:
 
 ```
-/archik:suggest add a payments worker that subscribes to the orders queue
+/archik:spawn                     # mirror what's there now
+                                  #   → review on the canvas, accept
+/archik:evolve                    # propose a cleaner shape
+                                  #   → discuss with Claude, accept (or iterate)
+/archik:suggest add Stripe webhook handler
+                                  #   → small, targeted change
+```
+
+Each command stages a sidecar via `npx archik suggest set`. The canvas shows a green/red/amber diff overlay; you click Accept or Reject — or `/archik:accept` / `/archik:reject` from the terminal. Same outcome either way.
+
+### Manual install (existing projects without `archik init`)
+
+If you already have an archik file and just want to add the Claude integration:
+
+```bash
+npx archik@latest skill --user        # install skill into ~/.claude/skills (all projects)
+npx archik@latest commands --user     # install /archik:* into ~/.claude/commands (all projects)
 ```
 
-Claude grounds itself with `npx archik q stats`, drafts a full proposal in a temp file, runs `npx archik suggest set` to stage it as the canonical sidecar, and surfaces the canvas URL so you can review the diff overlay and Accept/Reject in the browser. No manual YAML edits, no chance of the canvas and the file disagreeing.
+Drop the `--user` flag to scope to the current project only.
 
 ## Commands