archik 0.10.1 → 0.11.1

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

@@ -2,20 +2,86 @@
 description: Apply the pending suggestion
 ---
 
-# /archik:accept — apply the pending suggestion
+# /archik:accept — apply the pending suggestion and run BUILD → VERIFY
 
-The user wants to accept the pending architecture suggestion.
+This is the **accept branch of the DECIDE gate** in the engineering
+loop, and it opens the **BUILD** and **VERIFY** phases. Don't claim
+done at step 1 — the diagram changed; the code probably hasn't.
 
-Run the CLI — do NOT edit any archik file by hand:
+## Steps
 
-```
-npx archik suggest accept
-```
+1. **Apply the sidecar.** CLI only — never edit any archik file by
+   hand:
+   ```
+   npx archik suggest accept
+   ```
+   If it exits non-zero, surface the error verbatim and stop. Don't
+   try to fix the sidecar by editing it; ask the user how to proceed.
 
-If it exits 0, also run `npx archik validate` to confirm the new main
-file is clean, and tell the user it's applied.
+2. **Validate the merged main file.**
+   ```
+   npx archik validate
+   ```
+   If validation fails after accept, that's a bug — surface the
+   error and stop.
 
-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.
+   If the accepted change has **no code impact** (rename inside a
+   non-code-bearing kind, description-only edit, pure metadata),
+   skip steps 3–6 and jump straight to step 7.
+
+3. **BUILD — plan (HITL).** Translate the diagram delta into a
+   numbered file-level plan and present it for approval **before**
+   touching code:
+   - Each new code-bearing node (`service`, `function`, `worker`,
+     `module`, `page`, `component`, `store`, `hook`) → its
+     `sourcePath` and the concrete files / signatures to land there.
+   - Each new edge that requires code → the corresponding code
+     change (a new `http_call` needs a client; `subscribes` needs a
+     consumer handler; `writes` needs a repository method; etc).
+   - Any node still `status: proposed` → flag it; code must land
+     before flipping to `active`.
+   - Default to **tests-first** when behaviour is clearly bounded.
+   - If `superpowers:writing-plans` is available, use it; else
+     inline.
+
+   End with: *"Approve the plan and I'll implement it, or push back
+   on any step."* Do NOT start coding until approved.
+
+4. **BUILD — implement.** Small reversible commits, one diagram
+   delta per commit where practical, no drive-by refactors.
+   `superpowers:test-driven-development` when available.
+
+   **Back-edge to DESIGN:** if implementation reveals the diagram is
+   wrong (a missing port, a hidden dependency, a boundary that
+   doesn't hold), STOP. Open a fresh `/archik:suggest` to fix the
+   diagram first, then resume. Don't paper over it.
+
+5. **BUILD — self-review.** Before claiming done:
+   - Each new file matches its node's `sourcePath`?
+   - Each new edge corresponds to a real call/handler/query?
+   - Bounded-context boundaries respected (no sneaky cross-context
+     imports)?
+   - Tests cover the new behaviour, not just the happy path?
+   - Any new dependency that isn't in the diagram → drift; queue a
+     follow-up `/archik:suggest`.
+
+   `superpowers:requesting-code-review` when available.
+
+6. **VERIFY.** Evidence before assertions:
+   ```
+   npx archik validate
+   ```
+   Plus the project's tests / typecheck / lint.
+   `superpowers:verification-before-completion` when available.
+   If `docs/architecture.svg` is committed, regenerate it:
+   ```
+   npx archik render --out docs/architecture.svg
+   ```
+
+7. **Close the loop.** End with one concrete next-step offer, not
+   "done":
+   - *"This module wires into four services — worth running
+     `/archik:evolve` to see if the boundaries can be cleaner?"*
+   - *"Want me to schedule a drift check in two weeks?"*
+   - *"This left `payments-worker` as `status: proposed` — flip it
+     to `active` once deployed."*

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

@@ -2,15 +2,45 @@
 description: Discard the pending suggestion
 ---
 
-# /archik:reject — discard the pending suggestion
+# /archik:reject — discard the pending suggestion and learn why
 
-The user wants to throw away the pending architecture suggestion.
+This is the **reject branch of the DECIDE gate** in the engineering
+loop. A rejection without a follow-up question loses information and
+forces a silent retry on the same flawed draft. Don't do that — the
+loop's reject feedback edge is the whole point.
 
-Run the CLI — do NOT delete files manually:
+## Steps
 
-```
-npx archik suggest reject
-```
+1. **Discard the sidecar.** CLI only — never delete files manually:
+   ```
+   npx archik suggest reject
+   ```
+   Surface the result. If there was no pending sidecar, pass that
+   message through unchanged and stop.
 
-Surface the result to the user. If there was no pending sidecar, the
-command will say so — pass that through unchanged.
+2. **Ask one specific clarifying question** before regenerating
+   anything. Pick the axis that the rejection most likely hits — the
+   user's answer becomes a hard constraint on the next draft. Pin it
+   to one of:
+
+   - **Boundary** — *"Did the wrong context own a node? Should
+     `payments-worker` live under `orders` or under `billing`?"*
+   - **Relationship** — *"Was a sync `http_call` wrong where you
+     wanted async `publishes`/`subscribes` over a stream?"*
+   - **Scope** — *"Too big? Want a smaller delta that only touches
+     the queue, not the worker?"*
+   - **Naming** — *"Was the id/name unclear? What would you call
+     it?"*
+   - **Composition** — *"Should this be one node, or split into a
+     port + adapter pair?"*
+   - **Lifecycle** — *"Should the new nodes be `status: proposed`
+     until the code lands, or active now?"*
+
+   Pick exactly one — the most likely fit given what was rejected.
+   Add a fallback: *"Or tell me a different reason and I'll work from
+   that."*
+
+3. **Wait.** Do NOT regenerate the suggestion automatically. The
+   user's answer to step 2 is what shapes the next attempt. When
+   they reply, loop back to the **DESIGN** phase with the rejection
+   reason as a hard constraint and re-stage via `/archik:suggest`.

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

@@ -22,8 +22,37 @@ 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.
 
+## This is the DISCOVER → DESIGN → DECIDE handoff of the engineering loop
+
+The skill defines a 5-phase loop: **Discover → Design → Decide → Build
+→ Verify**. This command covers Discover (grounding) and Design
+(staging the sidecar with rationale), then hands off to the user's
+review and the explicit Decide gate (`/archik:accept` or
+`/archik:reject`). Don't skip clarification just because a slash
+command was typed — clarification is what makes the draft good. Don't
+start Build phase here; that's gated on accept.
+
 ## Steps
 
+0. **Frame + clarify (entering DESIGN).** Before any CLI call, restate
+   the user's intent in one sentence and list 1–3 sharp clarifying
+   questions if any of these are ambiguous in `$ARGUMENTS`:
+   - **Boundary** — which existing context owns this, or is it a new
+     one? (data ownership = bounded context)
+   - **Sync vs async** — request/response (`http_call`) or
+     event-driven (`publishes`/`subscribes` over a stream)?
+   - **Composition** — one node or split (e.g. port + adapter, gateway
+     + service)?
+   - **External integrations** — what third-party touches this?
+   - **Lifecycle** — built now, or `status: proposed` for a planned
+     iteration?
+
+   Skip questions that `$ARGUMENTS` already answers. If the change is
+   trivially small (one node, one edge, no boundary impact), skip the
+   clarify pass entirely and go straight to step 1. **Use judgment;
+   don't ask questions for the sake of asking.** When in doubt, ask
+   the user "you decide?" so they can defer back if they want.
+
 1. **Make sure the canvas is running** so the user can review:
    ```
    npx archik status
@@ -90,17 +119,28 @@ the contract with the user.
    Never write a draft file under `.archik/` and never edit the
    sidecar directly.
 
-5. **Tell the user how to review and what's next**. Surface the
-   canvas URL from step 1 plus the terminal options, then offer a
-   concrete follow-up:
-   - "📝 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`."
-   - One follow-up sentence picking from: implement the new
-     node(s) in code, run `/archik:evolve` if the change exposed
-     architectural smells, regenerate `docs/architecture.svg` if
-     the project commits one. Don't end the turn at "done".
+5. **Narrate the design rationale** in 2–4 short bullets before
+   handing off to review. The user needs to see *why* this shape, not
+   just *what* it is. Cover:
+   - Which **bounded context(s)** the change touches and why those
+     boundaries.
+   - The **separation of concerns** — what each new node owns and why
+     it's its own node (not folded into an existing one).
+   - **Async vs sync** choice and the reason (cross-context coupling
+     should default to async).
+   - Any **alternative you rejected** and the trade-off.
+
+   Keep it tight — bullets, not paragraphs. The diagram does the rest.
+
+6. **Hand off to the DECIDE gate.** Surface the canvas URL plus the
+   terminal options, then state the gate clearly:
+   - "📝 Suggestion ready — open the canvas at <URL> for the diff."
+   - "Terminal: `npx archik suggest show` / `accept` / `reject`."
+   - "**Accept** to enter BUILD (plan → implement → self-review), or
+     **reject** and tell me what didn't fit (boundary? relationship?
+     scope? naming? composition? lifecycle?) so I can revise."
+
+   Do NOT pre-emptively start implementing. Wait for `/archik:accept`.
 
 ## Notes
 

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

@@ -89,6 +89,104 @@ Distinction:
 - **`evolve`** = prescriptive (propose a cleaner shape, then discuss before accepting)
 - **`suggest`** = targeted (apply one feature-sized change from a description)
 
+## The engineering loop (how archik fits into delivering work)
+
+Archik is the front of a five-phase loop that turns intent into
+working, reviewed, validated code. **Every structural change runs the
+loop.** Don't skip phases; don't silently retry on rejection; don't
+paper over a wrong design mid-build — go back.
+
+```
+  ┌────────────┐  q stats / list / source tree.
+  │  DISCOVER  │  Read before write. Map intent onto what already
+  └─────┬──────┘  exists.
+        │
+  ┌─────▼──────┐  Frame intent in one line + 1–3 sharp clarifying Qs.
+  │   DESIGN   │  Stage sidecar (`suggest set`) with rationale:
+  │            │  bounded contexts, sync vs async, composition,
+  └─────┬──────┘  alternatives rejected.       ◄── reject + reason ──┐
+        │                                                            │
+  ┌─────▼──────┐  Canvas diff: accept | reject (why?) | revise.      │
+  │   DECIDE   │ ───────────────────────────────────────────────────►┤
+  └─────┬──────┘                                                     │
+        │ accept                                                     │
+  ┌─────▼──────┐  Plan → Implement → Self-review.                    │
+  │   BUILD    │  Small reversible commits, one delta each.          │
+  │            │  Tests-first when behaviour is clear.               │
+  │            │  If implementation invalidates the design ─────────►┘
+  └─────┬──────┘  loop back to DESIGN — don't paper over.
+        │
+  ┌─────▼──────┐  npx archik validate; tests; drift; regen SVG.
+  │   VERIFY   │  Evidence before assertions. Propose next iteration —
+  └────────────┘  don't end on "done".
+```
+
+| Phase    | Driver       | Output / tool                                              |
+| -------- | ------------ | ---------------------------------------------------------- |
+| Discover | Claude       | `npx archik q ...` + source-tree `ls`                      |
+| Design   | Claude → User | sidecar via `suggest set`, after 1–3 clarifying Qs (HITL) |
+| Decide   | User         | `/archik:accept` or `/archik:reject` (HITL gate)           |
+| Build    | Claude → User | numbered plan (HITL approval), then small commits         |
+| Verify   | Claude       | `npx archik validate` + tests + drift + SVG regen          |
+
+**Two non-obvious feedback edges** (the things real loops have that flat
+lists miss):
+
+1. **Decide → Design on reject.** A rejection is information; ask one
+   specific question (boundary? relationship? scope? naming?
+   composition? lifecycle?), treat the answer as a hard constraint,
+   re-stage. Never silently retry the same draft.
+2. **Build → Design on invalidation.** If implementation reveals the
+   accepted diagram is wrong (a missing port, a hidden dependency, a
+   boundary that doesn't hold), STOP coding. Open a fresh
+   `/archik:suggest` to fix the diagram first, then resume. Code that
+   silently contradicts the diagram is drift before it's even merged.
+
+### Design heuristics — apply these in the DESIGN phase
+
+Before staging a sidecar, run the candidate through this checklist.
+Each item is a yellow flag; flag them out loud in your rationale
+rather than hiding them.
+
+- **One reason to change.** Each new node has a single responsibility
+  expressible in one sentence. If `description` rambles, decompose.
+- **Bounded contexts.** Name the context this change belongs to. A
+  change spanning two contexts is a yellow flag — usually means a
+  missing third (orchestrator, port, gateway).
+- **Async at context boundaries.** Default cross-context coupling to
+  `publishes` / `subscribes` over a stream/queue. `http_call` across
+  contexts is allowed but should be justified (sync-required RPC,
+  query for read-side data).
+- **Composition over sprawl.** Group related nodes under a `module`
+  parent via `parentId`. Flat top-level lists past ~8 nodes are a
+  smell.
+- **Ports & adapters at the edge.** External integrations sit behind
+  an `external` node, never inline inside a service. A port (interface)
+  + adapter (concrete) pair is preferred when the integration could
+  swap.
+- **Public traffic → gateway/auth upstream.** Anything user-facing
+  routes through a `gateway`/`auth` node, not directly to a service.
+- **Failure modes.** Async producers imply DLQ/retry on the consumer;
+  `http_call` implies timeout + circuit. Don't draw the happy path
+  alone.
+- **Lifecycle honesty.** Code-bearing node without code on disk →
+  `status: proposed`. About to be removed → `status: deprecated`. The
+  diagram should track reality, not aspiration.
+
+### Optional sharpening — `superpowers:*` skills (if installed)
+
+The loop is self-contained, but these skills sharpen specific phases
+when the user has them. Check the available-skills list at session
+start; never assume they exist.
+
+| Phase   | Skill                                          |
+| ------- | ---------------------------------------------- |
+| Design  | `superpowers:brainstorming`                    |
+| Build   | `superpowers:writing-plans`,                   |
+|         | `superpowers:test-driven-development`,         |
+|         | `superpowers:requesting-code-review`           |
+| Verify  | `superpowers:verification-before-completion`   |
+
 ## Protocol — three rules
 
 1. **Before** answering structural questions, query via `npx archik q ...`. Never `cat` or `Read` the YAML.
@@ -205,9 +303,17 @@ After a suggestion is accepted, the diagram has changed. Don't just stop — pro
 3. **Diff vs reality.** Offer to spot-check the source tree against the new diagram: *"Should I scan `src/` to confirm the diagram still matches the code?"*
 4. **Render.** If the project commits a rendered SVG (`docs/architecture.svg`), regenerate it: `npx archik render --out docs/architecture.svg`. Offer to do this if such a file exists.
 
-After a rejection, ask one clarifying question — *"Want me to try a smaller change that only touches X?"* — instead of going silent.
+After a rejection, **never go silent and never silently retry the same draft**. Ask a question pinned to one of these axes — the answer becomes a constraint when you regenerate:
+
+- **Boundary** — *"Did the wrong context own a node? e.g. should `payments-worker` live under `orders` or under `billing`?"*
+- **Relationship** — *"Was a sync `http_call` wrong where you wanted `publishes`/`subscribes`?"*
+- **Scope** — *"Too big? Want me to try a smaller delta that only touches the queue, not the worker?"*
+- **Naming** — *"Was the id/name unclear? What would you call it?"*
+- **Composition** — *"Should this be one node, or split into a port + adapter pair?"*
+
+Then loop back to step 2 (Clarify) of the engineering loop with the rejection reason as a hard constraint on the next draft.
 
-The goal: every accepted change ends with the user knowing what's next, not "ok, accepted".
+The goal: every accepted change ends with the user knowing what's next, not "ok, accepted". Every rejection ends with one specific question, not silence.
 
 ## Verification workflow