fix: bound agent workflow overhead

claude-skills/backfill/SKILL.md

@@ -3,7 +3,7 @@ name: backfill
 description: 'FluencyLoop safety net. Reconstruct store records for work that shipped without going through the loop — reads a merged diff, records the feature, session, decisions, knowledge, and architectural concepts, and defaults reconstructed decisions to unverified. Use post-merge, or when the user says "fluencyloop backfill", "document this PR after the fact", or "we skipped the loop on this one".'
 ---
 
-# fluencyloop-backfill — reconstruct, make fluent, then flag
+# /fluencyloop:backfill — reconstruct, make fluent, then flag
 
 FluencyLoop never blocks a merge. The safety net for work that skipped the loop is
 **post-merge backfill**: it gives ad-hoc work a home retroactively. Backfilled rationale

claude-skills/diagram-design/SKILL.md

@@ -19,36 +19,33 @@ Do not load the full guide, ask the user to choose a palette, tour templates, or
 alternatives. FluencyLoop owns the surrounding reader design. Produce one restrained,
 self-contained embedded HTML file with inline SVG and CSS.
 
-Work in one bounded pass:
-
-1. Choose the type without asking: use **architecture** for component ownership or system shape,
-   **flowchart** for a directed interaction or decision path, and **sequence** only when message
-   order between distinct actors is the point. For an architectural record, apply the same rule to
-   its ADR mechanism. Load only that one type reference.
-2. Use 4–7 nodes and 3–8 connectors. Show only the relationship that earns the diagram; a product
-   overview must not become a feature inventory. For an **architecture** diagram, default to
-   unlabelled arrows: a small diagram should express routine direction through layout and node
-   subtitles, not cramped connector text. This never overrides the selected type's grammar: label
-   every decision exit in a flowchart and every message in a sequence diagram. Never abbreviate a
-   label merely to make it fit.
-3. Write directly to the requested path. For `product-overview.html`, keep `product.md` as prose;
-   do not add a Mermaid duplicate of the HTML diagram. Use only inline SVG and CSS with system
-   font stacks: no Google Fonts `<link>`, remote `src`/`href`, CSS `url(...)`, scripts, or iframes.
-   Keep the existing light palette as the default. Use `--diagram-canvas`, `--diagram-surface`,
-   `--diagram-ink`, `--diagram-muted`, `--diagram-rule`, and `--diagram-accent` throughout, then
-   add a restrained `:root[data-fluencyloop-theme="dark"]` variable set. The reader supplies that
-   attribute; do not use JavaScript or a system-preference media query.
-4. Draw connectors before cards. Use a straight connector only for aligned endpoints; otherwise use
-   a rounded orthogonal route. Never overlap connector paths or reuse an attach point for separate
-   connectors. A connector or its label must never run behind a non-endpoint card. If a label is
-   necessary, place it only in a clear lane: give its opaque background mask at least 8px of visible
-   space from both the connector and every card. If no lane exists, omit the label or change the
-   layout; do not shrink, clip, or place text beneath a card.
-5. Confirm the file is nonempty, then run `fluencyloop site --ensure --open-once --json` when
-   available so the reader can show it without opening a duplicate tab. Inspect the rendered result before handing off: every label
-   must be readable, with no text behind a card, connector overlap, or viewBox clipping. Do not
-   block the feature if Node is unavailable; say that the prose is available and the diagram will
-   appear when the optional site can run.
+Use the native diagram renderer, not the general diagram workflow:
+
+1. Choose one supported layout without asking: `linear` for a 2–6 step path, `hub` for a shared
+   service/boundary with 2–7 participants, or `layered` for independent adjacent-layer mappings.
+   It supports 2–8 nodes and at most 10 edges. A fan-out or merge uses `hub`, never `layered`.
+2. Run exactly one `fluencyloop diagram` command. Give each node its short id, label, and detail as
+   separate fields, then give the directed edges. For example:
+
+   ```bash
+   fluencyloop diagram --output docs/fluencyloop/diagrams/product-overview.html --layout hub \
+     --title "Dog selection" --hub selection \
+     --node list --label "Dog list" --detail "Chooses a dog" \
+     --node selection --label "Selection service" --detail "Owns selected dog" \
+     --node detail --label "Dog detail" --detail "Reads selected dog" \
+     --edge list selection --edge selection detail
+   ```
+
+   Keep labels at 28 characters or fewer and details at 42 or fewer. The renderer owns canvas
+   height, card positions, routes, attachment points, arrows, dark theme, and no-scroll geometry.
+   Never edit its generated HTML.
+3. If the renderer rejects a graph, omit the diagram. Do not load a type reference, inspect CSS,
+   search the project for styling, browse templates, or escalate to custom SVG during a
+   FluencyLoop feature; prose remains the complete explanation.
+4. Do not run Playwright, browser automation, screenshots, theme checks, or iterative visual
+   inspection. The renderer validates its topology before writing. Confirm only that the file is
+   nonempty, then use `fluencyloop site --ensure --open-once --json` when available. Node remains
+   optional.
 
 ## General diagrams
 

claude-skills/feature/SKILL.md

@@ -3,7 +3,7 @@ name: feature
 description: 'FluencyLoop Stage 2–3. Declare a feature and build it while staying fluent: creates the feature branch, frames its concepts and relationships, then builds in slices, teaching the why of each real decision at the slice boundary and journaling it. Probes the concepts the work needs up front, adapts explanation depth to the developer''s knowledge, and builds/maintains a per-developer knowledge base in ~/.fluencyloop. Use when starting a new unit of work in a repo that has a .fluencyloop/ directory, or when the user says "fluencyloop feature", "start a feature", or describes something they want to build with FluencyLoop.'
 ---
 
-# fluencyloop-feature — declare a feature, build it fluent
+# /fluencyloop:feature — declare a feature, build it fluent
 
 This is the contributor's entry point. A **feature is a branch** (`feature/<slug>`); it owns
 its design reasoning and session journals. You will: (1) declare the feature, (2) frame its
@@ -63,6 +63,11 @@ in the current project directory when needed, then creates FluencyLoop's state.
 continuing. Only stop if `init` itself fails. Do not hand-create `.fluencyloop`, `docs`, or
 `.claude/skills`.
 
+**Report real entry points after a fresh init.** Say that a larger initiative starts with
+`fluencyloop plan "<intent>"` or `/fluencyloop:plan`; one buildable unit starts with
+`fluencyloop feature "<intent>"` or `/fluencyloop:feature`. Never recommend the retired prose
+names `fluencyloop-plan`, `fluencyloop-feature`, `fluencyloop-review`, or `fluencyloop-backfill`.
+
 **Reattach a safe detached checkout.** If `branch` is `HEAD`, `state_matches_branch` is `true`,
 and `state_branch` is nonempty, this is the exact recorded feature tip, not a split. Run `git
 status --porcelain`. If it is empty, run `git checkout <state_branch>`, then rerun the bundled
@@ -353,9 +358,9 @@ Build the feature one **meaningful slice** at a time (a logical, commit-worthy c
 
    ```bash
    fluencyloop knowledge \
-     --component "<name>|<role>|<conditions>" \
-     --component "<name>|<role>|<conditions>|follow-up" \
-     --gotcha "<subject>|<why it is this way or what breaks otherwise>"
+     --component "<name>" --role "<role>" --conditions "<conditions>" \
+     --component "<name>" --role "<role>" --conditions "<conditions>" --status follow-up \
+     --gotcha "<subject>" --why "<why it is this way or what breaks otherwise>"
    ```
 
    **Knowledge transfer** is still irreducible: make it **rich, not a token list**. Capture the
@@ -364,11 +369,10 @@ Build the feature one **meaningful slice** at a time (a logical, commit-worthy c
    `documented`; use `follow-up` only when appropriate. Separate it from decisions: a role you
    explained is knowledge transfer even if no fork was chosen. **About the work, never the
    person** — no competence, prior knowledge, or "who learned what" (committed files, GDPR); the
-   per-developer picture lives only in the calibration profile. Compose and validate every value
-   before the one batched call: each `--component` has exactly three or four **nonempty**
-   pipe-separated fields and each `--gotcha` has exactly two **nonempty** fields. Omit a field
-   instead of emitting `||`. Escape a literal `|` as `\|` and a literal backslash as `\\`. Do not
-   run incomplete, bare, or trial `fluencyloop knowledge` commands to discover this syntax.
+   per-developer picture lives only in the calibration profile. Use the explicit-field form above:
+   quote each value normally; it accepts pipes and Windows paths unchanged. The old compact
+   pipe-delimited form remains only for compatibility. Compose the complete batch before one call;
+   do not run incomplete, bare, or trial `fluencyloop knowledge` commands to discover syntax.
    - **Decisions** *(the script formats them — you supply only the field values)* — for each, run
      `fluencyloop decision` so the block is assembled deterministically; never hand-write the
      bullet schema:
@@ -483,7 +487,10 @@ Write and commit at most these Markdown distillations under
    concepts and behavior, never as a file list.
 2. **Product overview** — refresh `product.md` only when this feature materially changes the
    product's problem, shape, or major flow. A feature that changes nothing at that altitude gets
-   **no overview rewrite**.
+   **no overview rewrite**. Keep it self-contained: do not add a `Related concepts` / `Related
+   records` section or Markdown links to record files. The reader's Records navigation already
+   provides that traversal; raw file references add no explanation and can appear as literal
+   Markdown in its deliberately small prose renderer.
 3. **Concept explanation** — when this feature newly establishes a concept, create
    `concepts/<concept-slug>.md`; revise an existing explanation only when a feature decision contradicts
    it. Do not create a concept explanation merely because the feature touched a concept.
@@ -523,22 +530,22 @@ Choose the visual yourself from the implemented product shape:
 - Otherwise omit the diagram. A short hierarchy, list, or simple before/after statement remains
   prose or a table; never manufacture a visual merely because `product.md` exists.
 
-When it qualifies, load the bundled `diagram-design` skill and invoke its **FluencyLoop embedded
-diagram fast path**. Give it the exact output path and the one relationship to clarify; choose the
-type and write the file in one bounded pass. Do not ask the user to choose the style, type, or
-whether to proceed. The local site embeds that file directly below the overview prose through a
-sandboxed route. Make it one restrained system overview, not a duplicate of every record diagram.
-Keep `product.md` prose-only: do not add a Mermaid copy of the companion HTML. Confirm the file is
-nonempty, then use `fluencyloop site --ensure --open-once --json` when Node is available. It makes
-the result available without opening a duplicate tab. The prose remains complete without the diagram
-and explains the same product shape in words.
+When it qualifies, load the bundled `diagram-design` skill and use its **FluencyLoop native
+renderer**. Give it the output path, a bounded graph (2–8 concise nodes and at most 10 edges), and
+the matching linear, hub, or layered layout. Do not search the codebase for styling, read
+templates, invoke Playwright, take screenshots, inspect themes, or iterate on the diagram. The
+renderer owns geometry, routes, attachment points, dark theme, and no-scroll document height;
+never edit its HTML. If it rejects the graph, omit the overview diagram rather than escalating to
+general diagram design. The local site embeds its output through a sandboxed route. Keep `product.md` prose-only.
+Confirm the file is nonempty, then use
+`fluencyloop site --ensure --open-once --json` when Node is available.
 
 **Do not distill decisions.** Their why was taught and captured contemporaneously by
 `fluencyloop decision`; re-synthesising it is both less trustworthy and unnecessary token spend.
 Keep every distillation person-neutral: describe the product and its constraints, never a
 developer's competence, knowledge, or authorship.
 
-When the feature is ready for a PR, tell the user they can run **fluencyloop-review** to
+When the feature is ready for a PR, tell the user they can run **`/fluencyloop:review`** to
 assemble the reviewer-facing view from the sessions.
 
 **Check what's actually possible here first** — run `gh auth status`. If `gh` isn't installed or
@@ -549,7 +556,7 @@ open the PR (and file plan issues) for them — using the delivery rule above (*
 install from <https://cli.github.com> (pick the command that fits their OS — don't work from a
 hardcoded package-manager list) then `gh auth login`. If `gh` stays unavailable (declined or
 deferred), the hand-off is at most *commit + push*, and a PR can be opened later via
-`fluencyloop-review`. Only run the full **commit + push + open-PR** automation where `gh` works.
+`/fluencyloop:review`. Only run the full **commit + push + open-PR** automation where `gh` works.
 
 **Create PR bodies through a file.** Write the assembled Markdown to a temporary, untracked file
 and call `gh pr create --body-file <path>` (and `gh pr edit --body-file <path>` when correcting it).
@@ -563,8 +570,8 @@ The hand-off is a **behavioral pattern that recurs every feature** — so decide
 once per feature. Check `~/.fluencyloop/preferences.md` (loaded in §0):
 
 - **A preference is already recorded** — honor it silently, and **do not re-ask**. If it says
-  automatic, go ahead and commit + push + open the PR yourself (run fluencyloop-review first) at
-  completion; if manual, just point the user at fluencyloop-review and stop. Stage all
+  automatic, go ahead and commit + push + open the PR yourself (run `/fluencyloop:review` first) at
+  completion; if manual, just point the user at `/fluencyloop:review` and stop. Stage all
   `docs/fluencyloop/store/` records created in this worktree with the handoff; never exclude the
   completed legacy migration from the commit.
 - **No preference yet (this is the first feature)** — ask **exactly once**, via a single

claude-skills/plan/SKILL.md

@@ -1,15 +1,15 @@
 ---
 name: plan
-description: 'FluencyLoop planning stage. Plan a large chunk of work before building it: design and document the overall architecture, break it into task items, sequence them into a roadmap with a critical path, and (optionally) open GitHub issues under a milestone. Produces a committed plan.md that the per-feature loop then builds from — one fluencyloop-feature per task item. Use when the work is too big for a single feature/branch, or when the user says "fluencyloop plan", "plan this", "design the architecture for", "break this down", or "make a roadmap".'
+description: 'FluencyLoop planning stage. Plan a large chunk of work before building it: design and document the overall architecture, break it into task items, sequence them into a roadmap with a critical path, and (optionally) open GitHub issues under a milestone. Produces a committed plan.md that the per-feature loop then builds from — one /fluencyloop:feature per task item. Use when the work is too big for a single feature/branch, or when the user says "fluencyloop plan", "plan this", "design the architecture for", "break this down", or "make a roadmap".'
 ---
 
-# fluencyloop-plan — map a big chunk before you build it
+# /fluencyloop:plan — map a big chunk before you build it
 
-Sits **upstream of `fluencyloop-feature`**. A *feature* is one branch; a **plan** is an
+Sits **upstream of `/fluencyloop:feature`**. A *feature* is one branch; a **plan** is an
 *initiative* that will spawn several features. You will: (1) frame the chunk, (2) analyse
 requirements and surface material gaps, (3) design and show the overall architecture, (4) break
 it into task items, (5) sequence them into a roadmap with a critical path, (6) offer to open
-GitHub tickets under a milestone, (7) hand each task off to `fluencyloop-feature`. The plan is a
+GitHub tickets under a milestone, (7) hand each task off to `/fluencyloop:feature`. The plan is a
 **map you build against, not a spec to ratify** —
 do not over-invest. Keep the developer the architect.
 
@@ -90,10 +90,10 @@ stub**, this plan is where the constitution is born — see §5.
 `dimension → level` map, level ∈ {`fluent`, `familiar`, `learning`, `new`}; per-developer, global,
 never committed) — to set the depth you explain architectural choices at. Missing is fine.
 Planning is also teaching: the same "teach the why, ask whether it is understood, don't lecture"
-posture from `fluencyloop-feature` applies to the architecture decisions here. Apply the
+posture from `/fluencyloop:feature` applies to the architecture decisions here. Apply the
 self-report-only rule above to every architecture explanation.
 
-Is this actually a plan? If the work fits one branch, skip straight to `fluencyloop-feature` —
+Is this actually a plan? If the work fits one branch, skip straight to `/fluencyloop:feature` —
 don't manufacture an initiative. Plans are for chunks that genuinely decompose into several
 features.
 
@@ -195,7 +195,7 @@ may connect concepts to other concepts, components, or planned features.
 
 ## 3. Break it into task items
 
-Decompose the initiative into **task items — each a future `fluencyloop-feature`**. For each,
+Decompose the initiative into **task items — each a future `/fluencyloop:feature`**. For each,
 capture in the `## Task breakdown` table: an `id` (T1, T2, …), a slug-able **intent**, a rough
 **size** (S/M/L), and its **dependencies** (by id). Aim for items that are independently
 build-and-mergeable. Keep them coarse; a task that's really two features is two rows.
@@ -275,10 +275,10 @@ The plan is complete either way — no friction.
 
 ## 7. Hand off to the build loop
 
-The plan is the map; each task item is built with **`fluencyloop-feature`** (one branch per
+The plan is the map; each task item is built with **`/fluencyloop:feature`** (one branch per
 task, from the active development branch — `dev` for the 0.3 milestone), in roadmap order along
 the critical path first. Tell the user that — and that
-`fluencyloop-review` assembles each feature's PR view when it's done. Do not open feature
+`/fluencyloop:review` assembles each feature's PR view when it's done. Do not open feature
 branches yourself here; §7 hands off, it doesn't build.
 
 ## Rules

claude-skills/review/SKILL.md

@@ -3,7 +3,7 @@ name: review
 description: 'FluencyLoop Stage 4. Assemble the reviewer-facing PR view from a feature''s sessions — a feature is a branch, so it assembles itself from git. Use when preparing a PR description, reviewing a FluencyLoop feature, or when the user says "fluencyloop review", "assemble the PR view", or "summarise this feature for review".'
 ---
 
-# fluencyloop-review — Stage 4, assemble the PR view
+# /fluencyloop:review — Stage 4, assemble the PR view
 
 A **feature is a branch**, so the review view assembles itself: no manual linking. You turn
 the feature's sessions into a summary a reviewer can read to get fluent fast.
@@ -112,4 +112,4 @@ explicitly asked.
 - **Surface, don't gate.** Flag unverified trust and constitution conflicts; never block.
 - **Truthful assembly.** Summarise what the sessions actually say; if a decision has no
   journaled `why`, say it's undocumented rather than inventing one — or suggest
-  **fluencyloop-backfill**.
+  **`/fluencyloop:backfill`**.