archik 0.6.21 → 0.7.1

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

@@ -0,0 +1,21 @@
+---
+description: Apply the pending suggestion
+---
+
+# /archik:accept — apply the pending suggestion
+
+The user wants to accept the pending architecture suggestion.
+
+Run the CLI — do NOT edit any archik file by hand:
+
+```
+npx archik suggest accept
+```
+
+If it exits 0, also run `npx archik validate` to confirm the new main
+file is clean, and tell the user it's applied.
+
+If it exits non-zero (no sidecar present, or the sidecar fails to
+parse), surface the error to the user verbatim and stop. Do not
+attempt to fix the sidecar by editing it; ask the user how they
+want to proceed.

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

@@ -0,0 +1,28 @@
+---
+description: Explain a node and its connections
+argument-hint: <node-id>
+---
+
+# /archik:describe — explain a node from the archik diagram
+
+The user wants details about the node with id **$ARGUMENTS**.
+
+Use the query CLI — do NOT `cat` or read any archik YAML directly:
+
+```
+npx archik q describe $ARGUMENTS
+```
+
+If you need adjacent context, also run:
+
+```
+npx archik q deps $ARGUMENTS
+npx archik q dependents $ARGUMENTS
+```
+
+Summarize what came back in plain prose: the node's kind and stack,
+what it depends on, what depends on it, and any responsibilities or
+notes. Don't dump the raw CLI output unless the user asks for it.
+
+If the CLI exits 1 (unknown id), tell the user and offer to run
+`npx archik q list` to find the right id.

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

@@ -0,0 +1,24 @@
+---
+description: Start the live canvas in the browser
+---
+
+# /archik:dev — open the archik canvas
+
+The user wants the live archik canvas running so they can see the
+diagram and review suggestions visually.
+
+Run the CLI — do NOT spawn dev servers any other way:
+
+```
+npx archik status
+```
+
+If nothing is running for this project, start it detached:
+
+```
+npx archik start
+```
+
+Surface the URL it prints (or the existing URL from `status`) so the
+user can click straight to it. Do not try to open the browser
+yourself.

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

@@ -0,0 +1,127 @@
+---
+description: Propose a cleaner modular architecture
+argument-hint: [optional focus area, e.g. "payments domain"]
+---
+
+# /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 the full proposed end-state** in a workspace temp file:
+   `/tmp/archik-evolve-<short-id>.yaml`. Constraints:
+
+   - 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.
+
+5. **Stage the draft via the CLI**:
+   ```
+   npx archik suggest set --note "evolve: <one-line summary>" /tmp/archik-evolve-<id>.yaml
+   ```
+   Fix and re-run on validation errors. Never patch the sidecar
+   directly.
+
+6. **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"), update the
+draft in the same temp file and re-run `npx archik suggest set` —
+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

@@ -0,0 +1,16 @@
+---
+description: Discard the pending suggestion
+---
+
+# /archik:reject — discard the pending suggestion
+
+The user wants to throw away the pending architecture suggestion.
+
+Run the CLI — do NOT delete files manually:
+
+```
+npx archik suggest reject
+```
+
+Surface the result to the user. If there was no pending sidecar, the
+command will say so — pass that through unchanged.

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

@@ -0,0 +1,144 @@
+---
+description: Bootstrap the diagram from the source tree
+---
+
+# /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.** Write the full proposed end-state to
+   `/tmp/archik-spawn-<short-id>.yaml`. If you generated sub-files,
+   write each one to its own temp file (`/tmp/archik-spawn-<sub>-<id>.yaml`)
+   and `suggest set` them too — but only the main file becomes a
+   sidecar. The sub-files need to live at their final
+   `.archik/<id>.archik.yaml` paths *before* you stage the main
+   draft, otherwise cross-file validation fails. So:
+
+   a. For each `archikFile: .archik/<id>.archik.yaml` you reference,
+      stage that sub-file first with its own
+      `npx archik suggest set` … then accept it immediately
+      (`npx archik suggest accept`) so the file is on disk under
+      `.archik/<id>.archik.yaml`. Yes, this is a chain of
+      micro-commits — that's the only CLI-blessed way to land
+      sub-files.
+   b. After all sub-files exist, stage the main draft:
+      ```
+      npx archik suggest set --note "spawn: mirror source tree" /tmp/archik-spawn-<id>.yaml
+      ```
+   c. If `suggest set` reports validation errors, fix the temp
+      file and re-run. 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

@@ -0,0 +1,73 @@
+---
+description: Propose diagram changes from a feature description
+argument-hint: <feature description>
+---
+
+# /archik:suggest — propose architecture changes
+
+The user wants you to capture the structural impact of a feature in
+the archik diagram. The user-facing description is:
+
+**$ARGUMENTS**
+
+This slash command IS the user's confirmation that they want a
+sidecar suggestion. Skip the "want me to update the YAML?" question
+and produce one now.
+
+## 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/`,
+on `architecture.archik.yaml`, or on any sidecar. The CLI is the
+sanctioned interface; everything else is a manual edit and breaks
+the contract with the user.
+
+## Steps
+
+1. **Make sure the canvas is running** so the user can review:
+   ```
+   npx archik status
+   ```
+   If nothing is running for this project, start it detached:
+   ```
+   npx archik start
+   ```
+   Note the URL it prints — you'll surface it at the end.
+
+2. **Ground yourself in the current diagram** using the query CLI
+   (do not `cat` the YAML):
+   ```
+   npx archik q stats
+   npx archik q list
+   ```
+   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.
+
+4. **Stage the draft as the sidecar via the CLI**:
+   ```
+   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
+   step 1 plus the terminal options:
+   - "📝 Suggestion ready — open the canvas at <URL> and use the
+     **Review** banner to see added/removed/changed nodes."
+   - "Or from the terminal: `npx archik suggest show` /
+     `npx archik suggest accept` / `npx archik suggest reject`."
+
+## Notes
+
+- If a sidecar already exists, `suggest set` overwrites it. Mention
+  to the user that you replaced their previous pending suggestion.
+- If `npx archik` is unreachable (offline, sandboxed), STOP and tell
+  the user. Do not fall back to writing YAML by hand.