archik 0.7.3 → 0.7.5

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

@@ -74,7 +74,16 @@ any file under `.archik/`.
    the highest-impact subset and tell the user the rest is round
    two.
 
-4. **Author + stage in one step.** Pipe the full proposed
+4. **Lock in the schema before authoring.** Run this once so you
+   draft against the actual shape, not from intuition:
+   ```
+   npx archik schema
+   ```
+   Note which fields are arrays vs strings; every edge needs an
+   `id`. Validation errors on the first attempt are almost always
+   one of these two patterns.
+
+5. **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:
 
@@ -100,7 +109,7 @@ any file under `.archik/`.
    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:
+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."*

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

@@ -43,7 +43,17 @@ archik suggest set` stages it.
      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
+3. **Lock in the schema.** Run this before drafting any YAML —
+   the prose below describes the workflow, not the field shapes.
+   The CLI is the schema:
+   ```
+   npx archik schema
+   ```
+   Pay attention to which fields are arrays vs strings, and that
+   every edge requires an `id` (kebab-case). Authoring from
+   intuition produces predictable validation errors.
+
+4. **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`.
@@ -73,13 +83,13 @@ archik suggest set` stages it.
    - **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
+5. **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.
+6. **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.
@@ -88,7 +98,7 @@ archik suggest set` stages it.
      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
+7. **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`).
@@ -102,7 +112,7 @@ archik suggest set` stages it.
    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
+8. **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
@@ -121,12 +131,30 @@ archik suggest set` stages it.
       nodes: [ ... ]
       edges: [ ... ]
       YAML
+      # mechanical: puts sub-file on disk so the main draft's
+      # archikFile: pointer validates. NOT the user's review gate
+      # on the main draft — that one is always left as a sidecar.
       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.
 
+      **Narrate each auto-accept with its rationale**, not just
+      "accept each". The user must be able to tell from your status
+      line that you are NOT bypassing their `/archik:accept` review
+      on the main draft. Example narration:
+
+      > Auto-accepting `agent` sub-file so the main draft can
+      > reference it via `archikFile:` — the next `suggest set`
+      > would fail validation otherwise. The main draft will still
+      > be left as a sidecar for you to review.
+
+      The main draft (step 8b) is always left as a sidecar.
+      `/archik:accept` is the user's gate; `npx archik suggest
+      accept <sub-file>` here is mechanical plumbing for the
+      cross-file reference, not a substitute for that gate.
+
    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`:
@@ -144,7 +172,8 @@ archik suggest set` stages it.
    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:
+9. **Tell the user how to review and what's next.** Surface the
+   canvas URL plus the natural follow-up:
    - "📝 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

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

@@ -43,7 +43,18 @@ the contract with the user.
    If `$ARGUMENTS` mentions a specific node by name, also run
    `npx archik q describe <id>` for it.
 
-3. **Author + stage in one step.** Pipe the draft straight into
+3. **Lock in the schema.** Run this before drafting any YAML —
+   the prose in this file describes the workflow, not the field
+   shapes. The CLI is the schema:
+   ```
+   npx archik schema
+   ```
+   Pay attention to which fields are arrays (`notes`,
+   `responsibilities`, `interfaces`) and which are required
+   strings (every edge needs an `id`). Authoring from intuition
+   produces predictable validation errors.
+
+4. **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
@@ -64,12 +75,17 @@ the contract with the user.
    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:
+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".
 
 ## Notes