@wairon/cli 5.1.1-dev.107 → 5.1.1-dev.109

package/docs/design/connecting-agent-entrypoint.md

@@ -0,0 +1,167 @@
+# Teaching the connecting agent — the MCP entrypoint
+
+> Status: 7.1–7.5 all shipped. Written against wairon 5.1.0.
+> Source request: "Teaching the connecting agent: wairon needs the entrypoint,
+> packs only adjust it" (2026-07-27).
+
+---
+
+## The governing principle
+
+**wairon owns the SDD model, so wairon must teach it.** If an agent connecting to
+a wairon MCP server does not know what SDD is, what the stereotypes mean, or in
+what order to use the `sdd_*` tools, supplying that is wairon's default — not
+each wrapper's. A pack appends its **platform delta** ("and here is what each of
+those means in Make.com") and never restates the model, which would drift on
+every wairon release.
+
+Every item below is shaped by that split.
+
+---
+
+## Shipped
+
+### 7.1 — `instructions` on `initialize`
+
+`createMcpServer` returns MCP `instructions`, the protocol's field for "how to
+use this server", which clients inject into the agent's system prompt. Composed
+by `instructions_specialist` (`src/core/instructions.ts`), it carries the L0→L5
+tree shape, the authoring order by tool name, the fact that the `sdd_*` schemas
+are self-describing, the bound project's governing `projectType`/profile, the
+loaded packs, and the directive to read `wairon-skill://sdd-architect` **before**
+authoring — with a pointer per published skill resource.
+
+Deliberately short and pointer-heavy (~2.9 KB for this repo; a test pins a 6 KB
+ceiling): the depth lives in `templates/skills/*.md`, and this is the map that
+sends an agent to read them.
+
+Composed **per `createMcpServer` call**, so the hosted per-request scoped server
+(`server/request.ts:652`) reports its own bound project rather than a snapshot.
+Never throws — a failed pack load or an uninitialized project degrades to
+wairon's own briefing, because a connecting agent must always be taught
+something.
+
+Path: `mcp_server` → `mcp_skills_adapter` → `skills_portal` →
+`skills_resource_orchestrator` → `instructions_specialist`. `sdd_mcp` stays a
+transport subsystem.
+
+### 7.2 — pack-contributed instruction blocks
+
+`DeclarativePackSchema.instructions` accepts a bare string, one block, or a list,
+normalized to `PackInstructionBlock[]`:
+
+```yaml
+instructions:
+  - text: Applies to every project this pack governs.
+  - text: Router branches never appear in a spec — model them as narrative branch steps.
+    profile: [make-automation]
+```
+
+Appended after wairon's text under `## From pack "<name>"`, in **pack load
+order** — the one merged field whose order is semantic, so blocks are never
+deduped or overwritten. `profile` scopes a block to the governing profile exactly
+as declarative assertions scope theirs; a block scoped to a profile that cannot
+be resolved is **withheld**, so platform doctrine never leaks into an unrelated
+project.
+
+---
+
+## Shipped (continued)
+
+### 7.4 — skills as MCP prompts — SHIPPED
+
+Resources are pull-only; prompts are what makes a skill *discoverable* to a human
+driving an agent (as a slash command or attachable context).
+
+- Register a prompts capability mirroring `listSkillResources()` — the SDK
+  exposes `registerPrompt`, so the set cannot drift from the resource mirror.
+- Prompt name = skill id (`sdd-architect`, `appenser-make-implementer`); the
+  handler returns the skill markdown as a message.
+- Resources stay for programmatic reads. Hosted inherits this via the shared
+  factory, as the resource mirror already does.
+- Test over an in-memory transport (`client.listPrompts()` / `getPrompt()`),
+  matching `tests/mcp/skill-resources.test.ts`.
+
+### 7.5 — variant guidance over MCP — SHIPPED
+
+`agent_resolver.buildVariantGuidance` (`src/core/agent_resolver.ts:216`) is the
+right hook for platform implementation guidance — it attaches to the component
+the implementer is holding, with no doctrine duplication. But it only reaches
+**generated agent files**, so hosted/cloud agents never see it.
+
+- **Lift the composition into `src/core/variants.ts`** so the agent renderer and
+  the MCP path share one implementation instead of a second copy that drifts.
+- `sdd_get_spec` on a variant-tagged component returns the resolved variant
+  guidance and its same-variant siblings as a clearly-derived, **read-only**
+  field, documented in the tool description as not part of the spec.
+- Naming the active variants in the `initialize` instructions was **not** built —
+  see the outcome note below. The request said "and/or", and the `sdd_get_spec`
+  half is the substantive one.
+
+### 7.3 — pack skills that EXTEND a builtin — SHIPPED
+
+Today `PackSkillSchema` is `{id, source, targets}` and pack skills are namespaced
+`<pack>-<id>` so they cannot shadow `sdd-*`. A platform delta can therefore only
+exist as a **parallel** skill (`appenser-make-implementer` beside `sdd-implement`),
+leaving the agent to notice both and reconcile them — and tempting every wrapper
+to fork the builtin wholesale, which is worse for everyone.
+
+```yaml
+skills:
+  - extends: sdd-implement          # builtin skill name
+    source: skills/make-implementer/SKILL.md
+  - id: make-control-plane          # unchanged: a genuinely new skill
+    source: skills/make-control-plane/SKILL.md
+```
+
+- `PackSkillSchema` becomes a union; `extends` must name a builtin
+  (`SKILL_NAMES`), and an unknown target **fails the pack load loudly** — the
+  `assertions` precedent: an old wairon must never silently not-apply a newer
+  pack's doctrine.
+- The pack section is appended to the builtin under `## Platform: <pack>`
+  (multiple packs in load order), on install **and** on `resources/read`. The
+  builtin stays wairon's, so an upgrade still updates it.
+- An extending skill contributes **no separate resource** — it composes into the
+  builtin's descriptor.
+
+**The trap:** `checkSkillFreshness` (`src/core/skills.ts:166`) byte-compares the
+installed file against the raw builtin template. Left alone, every extended skill
+reports permanently **stale** in `wairon doctor`. It must compare against the
+*composed* expectation.
+
+Also touched: `exportSddSkills` (write composed), `readSkillResource` /
+`readResource` (return composed), `listSkillResources` (descriptors), and the
+`pack_skill` type spec.
+
+---
+
+## Sequencing (as built)
+
+7.4 → 7.5 → 7.3, in ascending order of blast radius, after the pack-scoping work
+(`docs/design/pack-scoping.md`) had settled the selection model — 7.3's
+composition runs over whatever pack set resolution yields.
+
+---
+
+## Outcome notes
+
+**7.5 — one half deliberately not built.** The request said "include the resolved
+variant guidance in `sdd_get_spec` … **and/or** name the active variants in the
+`initialize` instructions". The first is done. The second is not: reading the
+variant registry from the instructions composer would be an `sdd_skills` →
+`sdd_core` hop onto an internal Adapter, which the boundary rules refuse, and
+routing it through the core portal would mean a barrel import cycle for what is
+only a pointer. The substantive requirement — guidance reaching a hosted agent —
+is satisfied by the tool that hands an implementer its component.
+
+**7.3 — the trap was real.** `checkSkillFreshness` byte-compared installed skills
+against the raw builtin template. Left alone, every extended skill would have
+reported permanently *stale* in `wairon doctor`, telling users to run `generate`
+on a loop. It now compares against what `exportSddSkills` would write.
+
+**A latent bug found while testing 7.5.** `requireSpecs()` in `mcp/server.ts`
+lazily required a relative path, which does not resolve under the test runner — so
+every `sdd_*` tool built on it failed with a module error instead of running. No
+test had ever driven one through an MCP client, so nothing caught it. The
+remaining lazy requires in that file (loader / validation / provision) are the
+same latent landmine for any future test that exercises those tools.

package/docs/design/execution-budgets.md

@@ -0,0 +1,199 @@
+# Execution budgets — the resource axis of the topology
+
+> Status: **implemented**. Written against wairon 5.1.x. The measurements below
+> come from three archived Claude Code sessions of this project's own
+> development, read out of the session transcripts rather than estimated.
+
+---
+
+## The problem
+
+The derived topology answered one question about each agent — *what does it own*
+— and nothing about a second one that turns out to cost real money: *what does
+its work cost to do*.
+
+In a delegating workflow that gap has a specific, measurable shape. A Claude
+Code subagent's `model` field defaults to `inherit`. An agent file that omits it
+silently adopts the parent session's model. With a frontier-tier parent and no
+agent files on disk at all, **1,860 of 2,176 subagent turns ran on the most
+expensive tier** across the three sessions measured — not by anyone's decision,
+but by a default nobody had reason to look at.
+
+Two things are worth stating because they are commonly assumed and were both
+wrong here:
+
+- **Per-spawn startup duplication is not the problem.** Subagents do reload
+  CLAUDE.md and tool schemas from scratch — measured at 13.5k–32.5k tokens
+  against a main session's 44–46k. But the whole CLAUDE.md chain came to ~2,400
+  tokens: 8% of a subagent's startup and **0.2% of subagent spend**. Eliminating
+  it entirely would save ~2%.
+- **Delegation was still correct.** Running the same work inline in a session
+  already averaging 271k context would have added a large context-carry
+  surcharge on every turn, and would have forced repeated compaction. The
+  problem was never *whether* to delegate; it was that every delegation was
+  constituted by default.
+
+A default that expensive cannot be fixed by instruction text. A prompt asking an
+orchestrator to choose models deliberately competes for attention with the task,
+and loses — the sessions measured had exactly such a policy, stated by the
+maintainer, and it lost 85% of the time. It has to be configuration.
+
+---
+
+## The model
+
+Four layers, tool-agnostic until the last. The split is what lets one derivation
+serve a local Claude Code session, a hosted MCP client, and a tool that cannot
+select models at all.
+
+| Layer | File | Holds |
+|-------|------|-------|
+| **Execution profile** | `models/execution.ts`, `core/execution_profile.ts` | What the work *is like*: `breadth`, `writes`, `reasoningDepth`, `delegates`. Says nothing about models. |
+| **Budget policy** | `core/budget_policy.ts` | What that *earns*: capability tier, effort, turn ceiling, tool class, delegation rights, MCP access. Named in tiers, never vendor models. |
+| **Target emitter** | `exporters/claude.ts` | The per-tool *encoding*. Deliberately not generic. |
+| **Brief** | `core/agent_resolver.ts` | The same budget, carried advisory to whoever spawns from it. |
+
+### Derivation needs no spec authoring
+
+Every input already exists on a resolved `AgentRecord`:
+
+- `reasoningDepth` reads the **component stereotype**, which the vocabulary
+  already encodes. A Store, Index, Registry or Adapter is plumbing that its L3
+  contract and L5 narrative fully describe. An Orchestrator, Supervisor or
+  Specialist carries the decisions. Inventing a second classification alongside
+  the stereotype would have meant two things to keep in agreement.
+- `breadth` reads owned-path spread and whether `readPaths` sweeps the tree.
+- `writes` reads the **role**, not the path count — see the reversals below.
+- `delegates` reads the template.
+
+### Tiers, not model names
+
+`ExecutionBudget.modelTier` is `small | standard | large | frontier`. Mapping a
+tier onto a real model is the *consumer's* job, because only the consumer knows
+what its host tool understands. The Claude Code exporter maps to model
+**aliases** (`haiku`, `sonnet`, `opus`, `fable`) rather than pinned ids, so
+generated files keep working across model releases.
+
+### The dial
+
+`execution.tier` defaults to `off`, and each step is a strict superset of the
+constraints below it — raising it can only tighten a budget, never loosen one.
+That property is what makes the dial safe to turn without auditing every agent.
+
+`free` is defined as having *no* quality tradeoff, which is why it expresses no
+model choice at all: picking a model is a quality decision. An absent
+`modelTier` is not the same as a default one, and the exporter omits the field
+rather than substituting.
+
+---
+
+## Enforce versus advise
+
+Both delivery paths carry the budget, and they are not equivalent:
+
+- A **generated agent file** can *enforce*. Front-matter binds: `model`,
+  `effort`, `maxTurns`, `tools`, `mcpServers` are read by the host before the
+  agent runs.
+- A **live brief** can only *advise*. The caller spawning from the brief is what
+  applies it.
+
+That asymmetry is deliberate rather than a gap — a brief is consumed by tools
+wairon does not control. It also matters practically: `materializeAgentFiles`
+defaults to **off**, so the brief is the path most projects actually use, and a
+budget that only reached generated files would have reached almost nobody.
+
+The same line explains the hosted story. Budgets are declarative data and travel
+fine over the hosted MCP surface as an advisory block on the brief. Front-matter,
+hooks and settings are filesystem artifacts and only the local CLI can write
+them. This is the same split hosted pack management already draws — declarative
+over the API, code packs via filesystem — rather than a second rule.
+
+---
+
+## Two things derivation deliberately never produces
+
+### `frontier` is not an owner tier
+
+Derivation caps deep reasoning at `large`, at every dial setting including
+`aggressive`. `frontier` is reachable only by an explicit per-agent override.
+
+The reasoning is that a frontier-capable model is a **sparring partner** for a
+question the specs do not settle, not a way to operate a component day to day.
+Given a tree that is already specced and decided, an owner that genuinely needs
+frontier capability to function is usually a component doing too much — the same
+smell `GOD_COMPONENT` reports, arrived at from a different direction. So it stays
+a decision only the user can make, and `wairon execution show` surfaces every
+agent pinned there.
+
+### `orchestrate` is not derived either
+
+The `orchestrate` tool class — the thin grant that withholds bulk-content tools
+from a pure router — exists because a manager that can read files will read
+them, and then it accumulates context exactly like a main session, which is the
+whole thing delegation was supposed to avoid.
+
+But **every agent in a wairon topology owns and authors something**. Domain
+owners write the specs and source they own; even a chained-subproject owner
+writes its mount spec. Stripping their write tools would not make them cheaper,
+it would make them broken. The genuine pure router in this workflow is the
+human's own main session, which is not a wairon agent at all.
+
+So `orchestrate` stays in the vocabulary as an override-selectable class for a
+manager someone defines by hand, and derivation never assigns it.
+
+---
+
+## Reversals worth recording
+
+Both were found by generating into a real project rather than by reading the
+code, and both are pinned by regression tests.
+
+**`writes` was inferred from owned-path count.** An implementer whose source
+path could not be inferred came out with zero owned paths, therefore
+`writes: false`, therefore `tools: Read, Grep, Glob` — an implementer that
+cannot implement, produced silently. `writes` is now a property of the role. A
+missing path is a topology gap to fix, not a reason to demote an agent.
+
+**Budget front-matter leaked into other targets.** `cursor`, `copilot` and
+`codex` all reuse `ClaudeExporter` for the agent-file shape. Enabling budgets
+therefore wrote `model`, `maxTurns` and `mcpServers` into files for tools that do
+not implement Claude Code's subagent contract. Those keys would be ignored, which
+is worse than absent: a budget sitting in the file reads as enforced when nothing
+enforces it. The shape is still shared; the encoding is now per-tool, opt-in at
+the exporter registry once a target's own fields are verified.
+
+---
+
+## Deliberately out of scope
+
+**Session-hygiene hooks and a context statusline.** Both would cut real tokens —
+rewriting noisy commands so their output does not enter context verbatim, and
+showing live context size instead of periodically re-measuring it. Neither
+belongs here. They are identical for every project regardless of its spec tree,
+so wairon would be deriving them from nothing, and wiring them means writing into
+a hand-maintained `settings.json` with no marker-based reconcile available,
+unlike every other file wairon generates. Generated skills are not a precedent:
+those *are* wairon's domain.
+
+**A conformance rule for frontier overrides.** `validate` gates the spec tree;
+an override lives in project config, and `lint.allow` attaches to specs. The
+finding actually wanted — "this component is doing too much" — is already
+`GOD_COMPONENT`. The override warning lives in `wairon execution show`, where the
+config it reports on lives.
+
+---
+
+## Open
+
+- **Precedence between an agent file's `model:` and the
+  `CLAUDE_CODE_SUBAGENT_MODEL` environment variable is unverified.** The env var
+  short-circuits Claude Code's model-resolution chain when set to anything but
+  `inherit`; whether explicit front-matter still wins decides whether a global
+  floor and per-role pinning compose or conflict.
+- **Whether `effort`, `maxTurns` and `mcpServers` in agent front-matter are
+  honoured** by a given Claude Code build. Documented, not yet measured.
+- **Topology scale.** A large project generates 30–50 subsystem agents (and would
+  generate 1000+ with component implementers on). Because briefs resolve on
+  demand by id, nothing needs a materialized catalog — but agent *discovery*
+  still enumerates everything, which argues for scoping discovery to a domain.
+  Separate concern from budgets.