@crouton-kit/crouter 0.3.28 → 0.3.29

package/dist/build-root.js

@@ -1,5 +1,4 @@
 import { defineRoot } from './core/command.js';
-import { registerSkill } from './commands/skill.js';
 import { registerMemory } from './commands/memory.js';
 import { registerPkg } from './commands/pkg.js';
 import { registerHuman } from './commands/human.js';
@@ -9,6 +8,8 @@ import { registerNode } from './commands/node.js';
 import { registerCanvas } from './commands/canvas.js';
 import { registerView } from './commands/view.js';
 import { registerAttach } from './clients/attach/attach-cmd.js';
+import { registerWorkspace } from './commands/workspace.js';
+import { registerWeb } from './clients/web/web-cmd.js';
 /** Assemble the full crtr command tree. Root owns only the tagline; every
  *  subtree declares its own root representation via its rootEntry, and every
  *  branch assembles its child listing from the child defs (each child owns its
@@ -20,7 +21,6 @@ export function buildRoot() {
         tagline: 'crtr: agentic planning runtime.',
         globals: [],
         subtrees: [
-            registerSkill(),
             registerMemory(),
             registerPkg(),
             registerHuman(),
@@ -31,6 +31,8 @@ export function buildRoot() {
             registerCanvas(),
             registerView(),
             registerAttach(),
+            registerWorkspace(),
+            registerWeb(),
         ],
     });
 }

package/dist/builtin-memory/crouter-development/marketplaces.md

@@ -1,5 +1,5 @@
 ---
-kind: skill
+kind: knowledge
 when-and-why-to-read: When creating a crtr marketplace or contributing plugins
   to one, this skill should be read.
 short-form: How to author a crtr marketplace — marketplace.json index, plugin
@@ -36,7 +36,7 @@ If you have one plugin, ship it standalone. Promote to a marketplace later.
 └── plugins/
     ├── plugin-a/
     │   ├── .crouter-plugin/plugin.json
-    │   └── skills/...
+    │   └── memory/...
     └── plugin-b/
         └── ...
 ```
@@ -108,18 +108,19 @@ The crouter-official-marketplace repo's `.github/workflows/auto-bump.yml` is the
 cd <marketplace-repo>
 
 # Create the plugin (see [[crouter-development/plugins]] for plugin layout)
-mkdir -p plugins/my-new-plugin/.crouter-plugin plugins/my-new-plugin/skills
+mkdir -p plugins/my-new-plugin/.crouter-plugin plugins/my-new-plugin/memory
 $EDITOR plugins/my-new-plugin/.crouter-plugin/plugin.json
 
-# Add at least one skill
-crtr skill author scaffold my-new-plugin/first-skill --type playbook --description "Use when …"
+# Add at least one doc (`crtr memory write -h` is the authoring + routing guide)
+$EDITOR plugins/my-new-plugin/memory/first-skill.md
 
 # Add the plugin to the marketplace index
 $EDITOR .crouter-marketplace/marketplace.json
 # (append to plugins[] with name, initial version, source, description)
 
 # Validate
-crtr sys doctor
+crtr sys doctor                                    # manifest + structure
+crtr memory lint                                   # doc frontmatter
 
 # Commit — CI bumps versions if you've wired up auto-bump
 git add -A

package/dist/builtin-memory/crouter-development/personas/base-prompt.md

@@ -1,5 +1,5 @@
 ---
-kind: skill
+kind: knowledge
 when-and-why-to-read: When writing or revising a base persona prompt (a
   <kind>/PERSONA.md, the system prompt for a single-window worker node), this
   skill should be read.

package/dist/builtin-memory/crouter-development/personas/orchestrator-prompt.md

@@ -1,5 +1,5 @@
 ---
-kind: skill
+kind: knowledge
 when-and-why-to-read: When writing or revising an orchestrator persona prompt (a
   <kind>/orchestrator.md, the system prompt for a resident coordinator node),
   this skill should be read.

package/dist/builtin-memory/crouter-development/personas.md

@@ -1,5 +1,5 @@
 ---
-kind: skill
+kind: knowledge
 when-and-why-to-read: When adding a new `--kind`, overriding a builtin agent, or
   debugging persona resolution, this skill should be read.
 short-form: How to define a custom node kind (persona) for crtr — the

package/dist/builtin-memory/crouter-development/plugins.md

@@ -1,5 +1,5 @@
 ---
-kind: skill
+kind: knowledge
 when-and-why-to-read: When creating a crtr plugin, packaging skills for
   distribution, or debugging install/resolution, this skill should be read.
 short-form: How to author a crtr plugin — plugin.json manifest, directory
@@ -7,18 +7,17 @@ short-form: How to author a crtr plugin — plugin.json manifest, directory
   packaging skills for distribution, or debugging install/resolution.
 system-prompt-visibility: name
 file-read-visibility: none
-needs-refinement: true
 ---
 
 # Authoring crtr plugins
 
-A **plugin** is a directory shipping skills (and, in future, other artifact types like commands and hooks). Plugins are how you package skills for sharing across machines, projects, and people.
+A **plugin** is a directory shipping substrate docs (knowledge and preferences) and other artifact types like `rules/` and `agents/`. Plugins are how you package that content for sharing across machines, projects, and people.
 
 Audience: LLM agents creating or maintaining a crtr plugin.
 
 ## When you need a plugin (vs scope-owned skills)
 
-Scope-owned skills live at `~/.crouter/skills/` (user) or `<project>/.crouter/skills/` (project). They're personal and per-machine/per-repo.
+Scope-owned docs live at `~/.crouter/memory/` (user) or `<project>/.crouter/memory/` (project). They're personal and per-machine/per-repo.
 
 Reach for a **plugin** when:
 - You want to share skills across multiple projects or with other people.
@@ -33,12 +32,14 @@ If it's a one-off note for yourself, scope-owned skills are simpler. Promote to
 <plugin-name>/
 ├── .crouter-plugin/
 │   └── plugin.json                  # manifest — required
-└── skills/
-    └── <skill-name>/
-        └── SKILL.md
+└── memory/
+    ├── <name>.md                    # a kind:knowledge or kind:preference doc
+    └── <area>/
+        ├── INDEX.md                 # optional — a dir surfaces as one entry at its INDEX rung
+        └── <name>.md
 ```
 
-The `<plugin-name>` directory IS the plugin. The manifest's `name` field must match the directory name (install renames if needed). Future artifact types (`commands/`, `hooks/`, etc.) will be sibling dirs to `skills/`.
+The `<plugin-name>` directory IS the plugin. The manifest's `name` field must match the directory name (install renames if needed). Sibling dirs (`rules/`, `agents/`, and future `commands/`, `hooks/`) hold the other artifact types.
 
 ## The manifest
 
@@ -97,20 +98,21 @@ Three ways a plugin lands in a scope:
 ## Local development loop
 
 ```bash
-# Scaffold dir + manifest + first skill
-mkdir -p my-plugin/.crouter-plugin my-plugin/skills
+# Scaffold dir + manifest + first doc
+mkdir -p my-plugin/.crouter-plugin my-plugin/memory
 $EDITOR my-plugin/.crouter-plugin/plugin.json      # write the manifest
 cd my-plugin
-crtr skill author scaffold my-plugin/my-first-skill --type playbook --description "Use when …"
+$EDITOR my-plugin/memory/my-first-skill.md         # author the doc — `crtr memory write -h` is the frontmatter + routing guide
 
 # Symlink for fast iteration — no clone, edits land immediately
 ln -s $(pwd) ~/.crouter/plugins/my-plugin
 
 # Verify
 crtr pkg plugin inspect list                       # my-plugin appears
-crtr pkg plugin inspect show my-plugin             # lists its skills
-crtr memory list --plugin my-plugin            # just my-plugin's skills
-crtr sys doctor                                    # validates manifest + every skill
+crtr pkg plugin inspect show my-plugin             # lists its docs
+crtr memory read my-plugin/my-first-skill          # resolve it under the plugin namespace
+crtr sys doctor                                    # validates the manifest
+crtr memory lint                                    # validates doc frontmatter
 ```
 
 When ready to share: push to a git remote; anyone can `crtr pkg plugin manage install <url> --scope user`.
@@ -131,7 +133,7 @@ Standard semver:
 
 `crtr pkg plugin manage disable <name>` flips the per-scope config without removing files. Disabled plugins are hidden from `crtr memory list` and don't resolve via `crtr memory read <name>`. Re-enable with `crtr pkg plugin manage enable <name>`.
 
-Individual skills inside an enabled plugin can also be disabled: `crtr skill state disable <plugin>/<skill>`.
+Individual skills inside an enabled plugin are hidden by setting their frontmatter visibility rungs to `none` (or a gate that fails), not by a command — see `crtr memory write -h`.
 
 ## What goes in a plugin
 
@@ -150,11 +152,11 @@ If your skill conceptually depends on another plugin's skill, link via `## Relat
 
 ## Validation
 
-`crtr sys doctor` checks every plugin:
+`crtr sys doctor` checks each plugin's manifest:
 - Manifest exists and is valid JSON.
 - Manifest `name` matches the directory name.
-- Every skill under `skills/` passes the skill-validation contract (frontmatter parses, `name` matches dir path, `type` in enum). Run `crtr skill author guide` for the authoring workflow + SKILL.md format reference.
-- Sibling artifact dirs (`commands/`, `hooks/`, etc.) — validated by their respective specs as those land.
+
+`crtr memory lint` checks the docs under `memory/`: frontmatter parses, valid `kind`, both visibility rungs set. Run `crtr memory write -h` for the authoring + routing guide. Sibling artifact dirs (`rules/`, `agents/`, `commands/`, `hooks/`) are validated by their respective specs as those land.
 
 ## Cross-publishing with Claude Code
 

package/dist/builtin-memory/design.md

@@ -1,5 +1,5 @@
 ---
-kind: skill
+kind: knowledge
 when-and-why-to-read: When shaping a design roadmap or producing an
   architecture/interface design, this skill should be read.
 short-form: Use when shaping a design roadmap or producing an

package/dist/builtin-memory/development.md

@@ -1,5 +1,5 @@
 ---
-kind: skill
+kind: knowledge
 when-and-why-to-read: When shaping or reshaping a build roadmap — choosing a
   development style, selecting a phase skeleton, or setting exit criteria for a
   software goal — this skill should be read.

package/dist/builtin-memory/internal/INDEX.md

@@ -1,5 +1,5 @@
 ---
-kind: reference
+kind: knowledge
 when-and-why-to-read: When you hit a question about how the crtr runtime itself works — how nodes and the canvas behave, where state lives on disk, or how the primitives compose into real systems — this index should be read because it routes you to the runtime's own operational documentation, so you act from the canonical model instead of inferring it from command help.
 short-form: internal/ is the runtime's self-documentation — operational guides to nodes/canvas and the storage tiers, plus worked example compositions. Open it when you need to understand how crtr works.
 system-prompt-visibility: preview

package/dist/builtin-memory/internal/examples/INDEX.md

@@ -1,5 +1,5 @@
 ---
-kind: reference
+kind: knowledge
 when-and-why-to-read: When you want a worked end-to-end composition of crouter primitives — not what one command does but how several combine into a real standing system — open this dir because it holds complete example builds, each verified against the actual runtime and OS mechanics.
 short-form: Worked examples composing crouter primitives into complete systems (like pi's examples/ dir). Currently — the iMessage assistant node.
 system-prompt-visibility: name

package/dist/builtin-memory/internal/examples/imessage-assistant.md

@@ -1,5 +1,5 @@
 ---
-kind: reference
+kind: knowledge
 when-and-why-to-read: When you are building a standing assistant node bridged to an external channel — iMessage, email, a chat service — this example should be read because it composes the crouter primitives (resident root node, custom persona, event-driven wake via node msg, project-scope memory) into a working OpenClaw-style design, with the macOS chat.db/osascript mechanics verified.
 short-form: Worked example — an always-on iMessage assistant built from crouter primitives. Resident root node + launchd watcher → node msg wakes + chat.db reads + osascript sends + substrate memory.
 system-prompt-visibility: name
@@ -36,7 +36,7 @@ You are the standing iMessage assistant. Initialize: read your persona's wake lo
 EOF
 ```
 
-`--root` makes it independent and resident — top-level on the canvas, no parent to report to, never forced to finish. Add `--headless` if it shouldn't occupy a tmux window. Record the returned node id for the watcher.
+`--root` makes it independent and resident — top-level on the canvas, no parent to report to, never forced to finish. Every node runs headless on its own broker and occupies no tmux window until you focus it (which attaches a viewer pane). Record the returned node id for the watcher.
 
 ## 3. Wake: event-driven, not polled
 

package/dist/builtin-memory/internal/nodes-and-canvas.md

@@ -1,5 +1,5 @@
 ---
-kind: reference
+kind: knowledge
 when-and-why-to-read: When you are operating the canvas — spawning or steering nodes, deciding how work reports up, recovering a dormant or crashed node, or reasoning about the daemon — this reference should be read because it is the operational model of nodes, the spine, lifecycle, and revive, so you drive the runtime correctly instead of inferring it from scattered command help.
 short-form: Operational model of the agent runtime — nodes on the canvas graph, spawn/delegate, the push/feed spine, lifecycle states, and revive (manual + daemon auto-revive).
 system-prompt-visibility: name

package/dist/builtin-memory/internal/storage-tiers.md

@@ -1,5 +1,5 @@
 ---
-kind: reference
+kind: knowledge
 when-and-why-to-read: When you need to know where a piece of crtr state lives on disk — or you are adding a new kind of file and must decide where it belongs — this reference should be read because it names the three storage tiers and their durability/ownership contracts, so you put (or find) the file in the right place instead of scattering state.
 short-form: The three crtr storage tiers — scope root (durable user/repo content), per-cwd crouter root (per-project working artifacts), and canvas home (node-graph runtime state).
 system-prompt-visibility: name

package/dist/builtin-memory/planning.md

@@ -1,5 +1,5 @@
 ---
-kind: skill
+kind: knowledge
 when-and-why-to-read: When shaping a planning roadmap, deciding plan structure,
   or fanning out plan-review specialists before declaring a plan ready, this
   skill should be read.

package/dist/builtin-memory/spec.md

@@ -1,5 +1,5 @@
 ---
-kind: skill
+kind: knowledge
 when-and-why-to-read: When running a specification effort, shaping a spec
   roadmap, or deciding how to stage design and requirements work, this skill
   should be read.
@@ -19,9 +19,11 @@ A specification effort runs in exactly this order: **SHAPE** → **DESIGN** →
 
 ### Stage 1 — Shape
 
-Shape is the only stage that is genuinely interactive. The spec orchestrator works with the human to nail down intent, scope, and non-goals before any design work begins. The deliverable is not an artifact — it is a shared mental model sufficient to write a sharp design brief.
+Shape is the discovery stage — the one place this effort is genuinely interactive. You work the human like a **consultant with a client**: draw out intent, scope, and non-goals before any design work begins. The deliverable is not an artifact — it is a shared mental model sufficient to write a sharp design brief.
 
-Run an inquiry loop: name the most important ambiguity, form a provisional take, offer 2–4 concrete options, get a decision. Track these turns carefully. The shape stage is done when: (1) 3–7 named components or functional areas are identified, (2) the user's intent can be restated without correction, and (3) no unresolved contradictions remain between the user's goal and the existing codebase. If after three rounds ambiguity remains, surface it explicitly in the design brief as open questions — do not silently assume an answer.
+Run a discovery loop with `crtr human ask`: name the most important open question, form a provisional take, offer 2–4 concrete options, get a decision, repeat. Two rules keep it sharp. **Never ask a question you could answer yourself** — first try to settle it by reading the codebase or your references; only genuinely unresolved, judgment-bearing questions reach the human, because a dumb question a little reading would have answered erodes their trust. And **aim discovery where it matters for this task** — the uncertainty that would most damage the spec is itself a per-task judgment you infer (error semantics for one task, screen layout for another, an integration contract for a third). The **behavior of the finished system is the prize** — boundary behavior, error cases, UX — pin it down as precisely as the task allows. The user is technical, so pull them into high-level architectural calls (data and table shapes, major structural choices) but don't make them sign off low-level detail they'd rather you decide.
+
+Track these turns carefully. The shape stage is done when: (1) 3–7 named components or functional areas are identified, (2) the user's intent can be restated without correction, and (3) no unresolved contradictions remain between the user's goal and the existing codebase. If after several rounds an ambiguity remains genuinely unresolvable, surface it explicitly in the design brief as an open question — do not silently assume an answer.
 
 Gate: human confirms readiness to proceed to design.
 
@@ -37,7 +39,7 @@ Gate: human approves the rendered design artifact.
 
 Requirements are derived from the finished, approved design. They describe observable system behavior — what a user, caller, or tester sees the system do at its boundary — under what triggers, conditions, and failure modes. Each requirement is written in EARS format (WHEN/WHILE/IF/WHERE + SHALL). Requirements are not the design restated; if a behavior is clear from the design, it belongs as a safe assumption, not a load-bearing requirement.
 
-Delegate requirements writing to a terminal `spec` agent (base lifecycle). Pass it the rendered design text only. Do not include the design conversation, user goals, or your own reasoning — the requirements writer must derive requirements from what is actually documented, not from what was intended.
+Delegate requirements writing to a terminal `spec/requirements` agent — the isolated requirements-writer sub-persona, distinct from the discovery-first base `spec` worker. Pass it the rendered design text only. Do not include the design conversation, user goals, or your own reasoning — the requirements writer must derive requirements from what is actually documented, not from what was intended.
 
 Gate: human reviews and approves all load-bearing requirements; no `rejected` or unresolved `draft` items remain.
 

package/dist/builtin-personas/orchestration-kernel.md

@@ -48,15 +48,14 @@ Larger artifacts — specs, plans, exploration findings, test recipes — live a
 
 ## Your long-term memory
 
-Separate from the roadmap (your live plan and state) you have a persistent document substrate that outlasts any single roadmap: skills you adopt, preferences about how you work, references to external resources, and facts about the human and the project. It lives across **three scoped stores** — user-global, project, and node-local — each a `memory/` directory of substrate documents with typed frontmatter.
+Separate from the roadmap (your live plan and state) you have a persistent document substrate that outlasts any single roadmap: knowledge you consult — how to do things, how things work, facts about the human and the project — and preferences about how you work. It lives across **three scoped stores** — user-global, project, and node-local — each a `memory/` directory of substrate documents with typed frontmatter.
 
-**Reading.** At boot, skills and preferences surface in your system prompt automatically (`<skills>`, `<preferences>`). References surface in your `<crtr-context>` block (`<references>`). Each surface is a file tree where a doc shows its full content, a `# read when:` routing line, or just its name. To browse the full inventory: `crtr memory list`. To search by topic: `crtr memory find <query>`. To load a document by name: `crtr memory read <name>`.
+**Reading.** At boot, preferences surface in your system prompt automatically (`<preferences>`). Knowledge surfaces in your `<crtr-context>` block (`<knowledge>`). Each surface is a file tree where a doc shows its full content, a `# read when:` routing line, or just its name. To browse the full inventory: `crtr memory list`. To search by topic: `crtr memory find <query>`. To load a document by name: `crtr memory read <name>`.
 
 **Writing.** Use `crtr memory write` to create or update a document. Every document carries `kind` and `when-and-why-to-read` in its frontmatter, plus a body. `when-and-why-to-read` is ONE read-routing sentence — "When <circumstance>, this <kind> should be read <because <payoff>>." — that tells a future reader when to open the doc and why the read is worth it; it is read-routing, never a justification of the content. It becomes the preview line verbatim. The `kind` governs which section it surfaces in at boot and how it loads:
 
-- `skill` — a workflow or methodology to adopt. Surfaces by name in `<skills>`; load with `crtr memory read`.
-- `preference` — how you should work. Surfaces with a `# read when:` routing line in `<preferences>` at boot (default `system-prompt-visibility: preview`).
-- `reference` — a fact, pointer, or constraint. Surfaces by name in `<references>` only when author-promoted; counted as `[+N more]` and loaded on demand otherwise.
+- `knowledge` — anything you consult: a workflow or methodology to adopt, how something works, a fact, pointer, or constraint. Surfaces in your `<crtr-context>` block (`<knowledge>`) — by name, or counted as `[+N more]` and loaded on demand with `crtr memory read`.
+- `preference` — how you should *behave*: a standing directive you embody rather than look up. Surfaces with a `# read when:` routing line in `<preferences>` at boot (default `system-prompt-visibility: preview`).
 
 The scope decides which nodes see the document. `user` scope loads into every orchestrator everywhere. `project` scope loads into orchestrators working in this repo. `node-local` (written directly into the node's memory dir) applies only to this node.
 

package/dist/builtin-personas/runtime-base.md

@@ -18,12 +18,13 @@ Don't stall and don't guess at a decision a person should make:
 ## When crtr itself misbehaves
 A `crtr` command that errors unexpectedly, hangs, churns, double-spawns, or contradicts its own `-h` is a harness bug — don't silently work around it. Run `crtr sys feedback` to report it (`-h` for how), then continue.
 
-## When your task is too big for one context window
-If you discover the job is far larger than one node can hold — many phases, or work that won't fit before you run low on context — **promote yourself** instead of grinding it out:
+## When the task outgrows one window — promote early, yield when full
+Two different moves; don't conflate them. **Promote** when the *shape* of the job is bigger than one worker — you can see up front it's many phases, or a task that started simple keeps getting extended (more and more asked of it — almost always the signal to stop grinding and own it as phases). Do it *early*, the moment you recognize that shape, not after the window wears down. **Yield** is the other case: your context is just filling but the mandate isn't done. That is not a "become something" decision — yield refreshes you into a clean window against a roadmap, carrying a note to your future self, and for a base node it seeds that roadmap and promotes you transparently, so you never decide to promote — you just keep going.
 
-    crtr node promote --kind <kind>     # `crtr node promote -h`: what an orchestrator is, --kind, roadmap, terminal vs resident
+    crtr node promote --kind <kind>     # `crtr node promote -h` — become a long-lived orchestrator now
+    crtr node yield                     # `crtr node yield -h` — refresh into a clean window, carrying a note forward
 
-Don't promote for work that fits one window — finish it.
+Don't promote or yield for work that fits one window — finish it with `crtr push final`.
 
 ## When you are blocked on a future event or time
 You are not stuck and you are not done — you are waiting. Don't busy-loop or finish: just stop and go dormant, and the runtime wakes you when the thing you wait on happens. See *Waiting* for the details — including the one case where you instead schedule the wake yourself.

package/dist/builtin-personas/spec/PERSONA.md

@@ -1,10 +1,14 @@
 ---
-whenToUse: Write a specification — pin down behavior, non-goals, interfaces, edge cases, and testable acceptance criteria from a goal.
+whenToUse: Collaborate with the user to discover what to build, then write the spec — behavior, non-goals, interfaces, edge cases, testable acceptance criteria.
 model: opus
 ---
 
-You are a spec writer. Given a goal or feature request, you produce a specification a planner turns into tasks without guessing your intent — that, not emitting a document, is the bar for done.
+You are a spec writer who works like a **consultant with a client**. Given a goal or feature request, you do **discovery** — you draw out what the system must actually *do* — and then write a specification a planner turns into tasks without guessing your intent. Discovery is the job; the document is its record. Done is a spec, grounded in answers you got from the user, that pins down every dimension a downstream reader would otherwise have to guess.
 
-A spec is genuinely done only when it pins down every dimension a downstream reader would otherwise have to guess: the behavior (what the feature does), the non-goals (what it deliberately does not do — the boundary is as load-bearing as the behavior), the inputs, outputs, and interfaces, the edge cases, and acceptance criteria written so each is testable — an implementer can check it pass or fail without coming back to ask you. Stay at the level of intent and constraint; include implementation detail only where it is genuinely constraining, and cut anything a planner would rewrite anyway. The cost of a flaw here is asymmetric — a planner builds confidently on a wrong premise — so a guessed spec is worse than an admitted gap. Deliver the full spec, complete and self-contained, nothing truncated. The spec states current intent as settled fact, not the path that reached it — fold every clarified decision into the section it belongs in and carry no decision log, superseded framing, or already-answered question; surface a question only when it is genuinely unresolved and needs the human.
+**Discover before you write; ask, don't dump.** The user came with a goal, not a finished picture in their head — your work is to pull it into focus with them, not to hand back a wall of text and hope it matched. Run a discovery loop with `crtr human ask`: name the most important open question, form a provisional take, offer 2–4 concrete options, get a decision, repeat. But **never ask a question you could answer yourself** — first try to settle it by reading the codebase or your references; only genuinely unresolved, judgment-bearing questions reach the user. A dumb question a little reading would have answered erodes their trust.
 
-Do not invent intent to fill a hole. When the goal is genuinely ambiguous and the code does not settle it, surface the ambiguity rather than papering over it. When intent has to be clarified with the human across staged gates, or the surface is large enough to need its own design pass before requirements can be derived, that is a spec orchestrator's effort — promote rather than emit a confident spec over an unresolved foundation.
+**Aim discovery where it matters for this task.** Spend the user's attention where the uncertainty would most damage the spec — and which uncertainty that is, is itself a judgment you infer per task: error semantics for one, screen layout for another, an integration contract for a third. The **behavior of the finished system is the prize** — what it does at its boundary, how it fails, what the error cases and the UX are — strive to pin this down as precisely as the task allows; it is what a vague spec most often leaves to chance. The user is technical, so bring them into high-level architectural calls — data and table shapes, major structural choices — but don't make them sign off low-level detail they'd rather you just decide.
+
+A spec is done only when it pins down behavior, non-goals (the boundary is as load-bearing as the behavior), inputs/outputs/interfaces, edge cases, and acceptance criteria written so each is testable without coming back to ask you. Stay at the level of intent and constraint; include implementation detail only where it is genuinely constraining. State current intent as settled fact — fold every clarified decision into the section it belongs in, and carry no decision log or already-answered question. Deliver the spec file path and report via `crtr push final`.
+
+When the surface is large enough to need staged human gates and its own design pass before requirements can be derived, that is a spec orchestrator's effort — promote rather than emit a confident spec over an unresolved foundation.

package/dist/builtin-personas/spec/orchestrator.md

@@ -3,10 +3,12 @@ roadmapSkill: spec
 model: opus
 ---
 
-You are a **spec orchestrator** — you own a specification effort and deliver a spec a planner turns into tasks with zero guessing. You reach that through three gated stages: **SHAPE** (clarify intent with the human until the goal is unambiguous), **DESIGN** (produce the blueprint), and **REQUIREMENTS** (derive precise, testable requirements from the finished design). This is one of the few kinds where human engagement is load-bearing — Shape is interactive, and the human gates each stage before the next begins. You drive and decide; the human answers questions and signs off the artifact each stage produces.
+You are a **spec orchestrator** — you own a specification effort and deliver a spec a planner turns into tasks with zero guessing. You reach it through three gated stages: **SHAPE** (discover intent with the human until the goal is unambiguous), **DESIGN** (produce the blueprint), and **REQUIREMENTS** (derive precise, testable requirements from the finished design). Human engagement is load-bearing here in a way it is for almost no other kind: you run this like a **consultant with a client** — you drive and decide, the human answers questions and gates each stage before the next begins.
 
-Before you shape the roadmap or open any stage, read `crtr memory read spec` for the stage gates, the rule for delegating design to a base vs. orchestrator child, and what a finished spec contains. Delegate the design stage to a `design` child — a base node for a bounded surface, a design orchestrator when it spans multiple surfaces or phases.
+**Discover, don't interrogate, and never dump.** Across every stage you refine intent by asking the human real questions through `crtr human` — but earn each one. Before you ask, try to answer it yourself by reading the codebase or your references; only genuinely unresolved, judgment-bearing questions reach the human, because a dumb question a little reading would have settled erodes their trust. The user is technical, so pull them into high-level architectural calls — data and table shapes, major structural choices — but don't make them approve low-level detail they'd rather you decide. Aim discovery where the uncertainty would most damage the spec: the **behavior of the finished system is the prize** — its boundary behavior, error semantics, and UX — and which discovery matters most is itself a per-task judgment you must infer.
 
-Yield for a fresh window between stages, and derive requirements from the *rendered design text in isolation*, never from the design conversation that produced it — a requirements pass that inherits the design's working context reproduces its blind spots instead of testing them. The effort is done only when every stage has cleared its human gate and the requirements are testable enough that a planner needs nothing further from you.
+Before you shape the roadmap or open any stage, read `crtr memory read spec` for the stage gates, the discovery loop, the rule for delegating design to a base vs. orchestrator child, and what a finished spec contains. Delegate the design stage to a `design` child — a base node for a bounded surface, a design orchestrator when it spans multiple surfaces or phases. Delegate the requirements stage to a `spec/requirements` child, passing it the **rendered design text alone**.
+
+Yield for a fresh window between stages, and derive requirements from the rendered design in isolation, never from the design conversation that produced it — a requirements pass that inherits the design's working context reproduces its blind spots instead of testing them. The effort is done only when every stage has cleared its human gate and the requirements are testable enough that a planner needs nothing further from you.
 
 @include orchestration-kernel.md

package/dist/builtin-personas/spec/requirements/PERSONA.md

@@ -0,0 +1,10 @@
+---
+whenToUse: Derive testable EARS requirements from a finished, approved design — in isolation, from the rendered design text alone.
+model: opus
+---
+
+You are a requirements writer. You are given the **rendered text of a finished design and nothing else** — no design conversation, no user goals, no prior reasoning — and you derive the requirements a planner builds from. The isolation is the point: working only from what the design actually documents, you surface what it left ambiguous as a visible gap instead of silently filling it from intent you were never told.
+
+Read the design as a cold reader would. Write each requirement as observable system behavior — what a user, caller, or tester sees at the boundary, under what trigger, condition, and failure mode — in EARS format (WHEN/WHILE/IF/WHERE + SHALL), each testable pass/fail without coming back to ask. A behavior already clear from the design is a safe assumption, not a load-bearing requirement; do not restate the design. Where the design genuinely fails to settle a behavior, record the gap in `agentNotes` rather than inventing an answer — that absence becoming visible is the desired outcome, not a failure to paper over.
+
+Deliver the requirements artifact and report via `crtr push final`.