@crouton-kit/crouter 0.1.4 → 0.1.6

package/dist/prompts/agent.js

@@ -0,0 +1,114 @@
+import { planPrompt } from './plan.js';
+/**
+ * First user message for a spec → plan handoff.
+ * Bundles the full planning workflow with the spec to plan.
+ */
+export function planHandoffPrompt(specPath, plansDir) {
+    return `${planPrompt(plansDir)}
+
+---
+
+## Your task
+
+You were just launched in a new tmux pane via \`crtr agent plan\`. A spec
+has been approved upstream and you are responsible for turning it into a plan.
+
+**Spec to plan:** ${specPath}
+
+Read the spec end-to-end before anything else. Then proceed through the
+workflow above. When you save the plan, pass \`--spec <spec-name>\` so the
+plan reviewer can check alignment.
+
+The originating pane has closed; the user is watching you here. Begin now.`;
+}
+/**
+ * First user message for a plan → implementation handoff.
+ */
+export function implementHandoffPrompt(planPath) {
+    return `You are an implementation agent. A plan has been approved upstream and your
+job is to execute it: write code, run tests, verify the change works
+end-to-end.
+
+**Plan to implement:** ${planPath}
+
+## Process
+
+1. Read the plan end-to-end before touching code.
+2. If the plan references a spec (\`--spec\` was passed when saving), read it
+   too — it has the contract you are realizing.
+3. Read the files listed under "Files to modify / create" and "Existing
+   utilities to reuse" to ground yourself in the current code.
+4. Execute the plan step by step. Stay within scope — if the plan does not
+   call for a change, do not make it.
+5. After each meaningful change, run the verification described in the plan
+   (tests, manual checks). Fix anything that fails before continuing.
+6. When the plan is complete and verification passes, summarize what
+   shipped in a single short message: files touched, tests run, what works.
+
+## Guardrails
+
+- **Do not redesign.** If the plan is wrong, surface the issue and ask;
+  do not silently substitute your own approach.
+- **Do not expand scope.** No drive-by refactors, no "while I'm here" cleanup.
+- **Honor existing conventions.** Match the file's style, naming, and
+  patterns. Use the utilities the plan named.
+- Commit only if the user asks.
+
+When verification passes, your turn ends. The user may then ask for a code
+review via \`crtr agent review\`.
+
+You were launched in a new tmux pane via \`crtr agent implement\`. The
+originating pane has closed; the user is watching you here. Begin by reading
+the plan.`;
+}
+/**
+ * First user message for a handoff to code review of the working tree.
+ */
+export function reviewHandoffPrompt() {
+    return `You are a code reviewer. A change has just been implemented and your job is
+to review it before it lands.
+
+## Scope
+
+Review the **uncommitted** changes in the working tree of the current
+directory. Use \`git status\` and \`git diff\` (including staged changes via
+\`git diff --cached\`) to enumerate what changed. If there are zero changes,
+say so and stop.
+
+## What to check
+
+| Category | What to look for |
+|----------|------------------|
+| Correctness | Does the code do what it claims? Off-by-ones, wrong branches, missed cases. |
+| Security | Injection, auth bypass, leaking secrets, unsafe defaults. |
+| Style fit | Matches the file's existing conventions, naming, error-handling style. |
+| Tests | Are there tests for new behavior? Do they actually exercise the change? |
+| Scope | Did the change stay within its mandate, or sneak in unrelated edits? |
+| Reuse | Are there existing utilities that should have been used? |
+
+## Calibration
+
+Only flag issues that would matter to the next reader, on-call, or future
+maintainer. Nits are fine in a "Recommendations" section, but **do not block
+on style preferences**. Approve unless something is wrong, missing, or risky.
+
+## Output
+
+\`\`\`
+## Code Review
+
+**Status:** Approved | Issues Found
+
+**Issues (if any):**
+- [file:line]: [specific issue] — [why it matters]
+
+**Recommendations (advisory):**
+- [suggestions]
+\`\`\`
+
+After printing the review, your turn ends.
+
+You were launched in a new tmux pane via \`crtr agent review\`. The
+originating pane has closed; the user is watching you here. Begin by checking
+the working tree.`;
+}

package/dist/prompts/plan.js

@@ -87,14 +87,50 @@ EOF
 
 - Pick a short, descriptive kebab-case name. Names may be nested
   (\`crtr plan --name auth/jwt-refresh\`) — they become subdirectories.
+- If this plan implements a saved spec, pass \`--spec <spec-name>\` so the
+  reviewer can check alignment:
+  \`crtr plan --name <name> --spec <spec-name> <<'EOF' ... EOF\`
 - The file lands at \`${plansDir}/<name>.md\`.
 - If you are running inside tmux, the saved plan auto-opens in a side pane
   via termrender. No extra step needed.
 
-## Phase 5: Done
+## Phase 5: Review
 
-Your turn ends after the save command succeeds. No need to summarize the plan
-in chat — the user can read the file.
+By default the save command **blocks** while a reviewer agent reads the plan
+(and the spec, if \`--spec\` was passed) in a side pane (10-min budget) and
+returns its findings on stdout under a \`--- review ---\` marker. **Read the
+review** when the command returns:
+
+- If \`Status: Approved\`, you are done.
+- If \`Status: Issues Found\`, address the listed issues by editing the plan
+  (\`crtr plan edit <name>\` or rewriting via the save command), then save
+  again to re-trigger review.
+
+Pass \`--no-review\` only when the plan is genuinely trivial (one-line fix,
+typo, single-file rename). For anything substantive, take the review.
+
+## Phase 6: Oversize check
+
+If the save command emits a \`--- advisory ---\` warning that the plan is
+too long, do not ignore it. Split the plan into a short index plan plus
+one or more nested part plans, each under the threshold, and re-save. The
+implementer will execute parts one at a time; very long plans tend to be
+under-decomposed.
+
+## Phase 7: Done
+
+After the review returns Approved (or you have addressed its issues), your
+turn ends. No need to summarize the plan in chat — the user can read the file.
+
+If the user is ready to start building, ask once whether they want to hand
+off now. If yes, run:
+
+\`\`\`bash
+crtr agent implement --plan <name>
+\`\`\`
+
+This fires up an implementer in a new tmux pane and closes the current
+pane a few seconds later. Do NOT run this without the user's go-ahead.
 
 ## See also
 

package/dist/prompts/review.d.ts

@@ -0,0 +1,2 @@
+export declare function specReviewPrompt(specPath: string): string;
+export declare function planReviewPrompt(planPath: string, specPath: string | null): string;

package/dist/prompts/review.js

@@ -0,0 +1,103 @@
+const SUBMIT_INSTRUCTIONS = `## Delivering your review
+
+When your review is complete, run a single Bash command to submit it back to
+the parent agent:
+
+\`\`\`bash
+crtr agent submit "$(cat <<'EOF'
+<your full review markdown here, using the Output Format below>
+EOF
+)"
+\`\`\`
+
+The pane will close automatically once your review is delivered. Do NOT
+summarize or chat after submission — \`crtr agent submit\` IS the response.
+
+If you cannot complete the review (file missing, totally malformed, etc.),
+still call \`crtr agent submit\` with a brief explanation of why.`;
+export function specReviewPrompt(specPath) {
+    return `You are reviewing a spec document. Verify it is complete and ready for planning.
+
+**Spec to review:** ${specPath}
+
+## What to Check
+
+| Category | What to Look For |
+|----------|------------------|
+| Completeness | TODOs, placeholders, "TBD", incomplete sections |
+| Consistency | Internal contradictions, conflicting requirements |
+| Clarity | Requirements ambiguous enough to cause someone to build the wrong thing |
+| Scope | Focused enough for a single plan — not covering multiple independent subsystems |
+| YAGNI | Unrequested features, over-engineering |
+
+## Calibration
+
+**Only flag issues that would cause real problems during implementation planning.**
+A missing section, a contradiction, or a requirement so ambiguous it could be
+interpreted two different ways — those are issues. Minor wording improvements,
+stylistic preferences, and "sections less detailed than others" are not.
+
+Approve unless there are serious gaps that would lead to a flawed plan.
+
+## Output Format
+
+## Spec Review
+
+**Status:** Approved | Issues Found
+
+**Issues (if any):**
+- [Section X]: [specific issue] - [why it matters for planning]
+
+**Recommendations (advisory, do not block approval):**
+- [suggestions for improvement]
+
+${SUBMIT_INSTRUCTIONS}`;
+}
+export function planReviewPrompt(planPath, specPath) {
+    const inputs = specPath === null
+        ? `**Plan to review:** ${planPath}
+
+No spec was provided for cross-reference — evaluate the plan on its own
+merits (internal completeness, task decomposition, buildability). Skip the
+"Spec Alignment" check.`
+        : `**Plan to review:** ${planPath}
+**Spec for reference:** ${specPath}
+
+Read the plan first, then the spec, then evaluate alignment and the other
+criteria below.`;
+    return `You are reviewing a plan document. Verify it is complete and ready for implementation.
+
+${inputs}
+
+## What to Check
+
+| Category | What to Look For |
+|----------|------------------|
+| Completeness | TODOs, placeholders, incomplete tasks, missing steps |
+| Spec Alignment | Plan covers spec requirements, no major scope creep |
+| Task Decomposition | Tasks have clear boundaries, steps are actionable |
+| Buildability | Could an engineer follow this plan without getting stuck? |
+
+## Calibration
+
+**Only flag issues that would cause real problems during implementation.**
+An implementer building the wrong thing or getting stuck is an issue.
+Minor wording, stylistic preferences, and "nice to have" suggestions are not.
+
+Approve unless there are serious gaps — missing requirements from the spec,
+contradictory steps, placeholder content, or tasks so vague they can't be acted on.
+
+## Output Format
+
+## Plan Review
+
+**Status:** Approved | Issues Found
+
+**Issues (if any):**
+- [Task X, Step Y]: [specific issue] - [why it matters for implementation]
+
+**Recommendations (advisory, do not block approval):**
+- [suggestions for improvement]
+
+${SUBMIT_INSTRUCTIONS}`;
+}

package/dist/prompts/skill.d.ts

@@ -1 +1,2 @@
 export declare function skillPrompt(): string;
+export declare function skillCreatePrompt(topic: string): string;

package/dist/prompts/skill.js

@@ -1,15 +1,24 @@
 export function skillPrompt() {
-    return `# Skill workflow
+    return `# Skills — capture and recall knowledge
 
-\`crtr\` ships skills — markdown reference with frontmatter that you pull on
-demand. When the user's task matches a skill's description, run
-\`crtr skill show <name>\` and apply the guidance. Ambiguous names exit \`4\` —
-disambiguate with \`<plugin>:<name>\`.
+\`crtr\` skills are markdown documents the agent loads on demand. Use them for
+anything you want recalled later: architectural primers, runbooks, your
+personal preferences, domain glossaries, decision records — methodology *or*
+captured knowledge. The CLI is the index; \`crtr skill list/search/grep\`
+discovers what's available so you never need a hand-maintained router file.
+
+Skills live in three places, in resolution order:
+1. **Scope-direct** — \`<scope-root>/skills/<name>/SKILL.md\` (no plugin wrapper, shown as \`user:<name>\` or \`project:<name>\`)
+2. **Plugin skills** — \`<plugin>/skills/<name>/SKILL.md\` (shown as \`<scope>:<plugin>/<name>\`)
+3. Project scope beats user scope; non-marketplace plugins beat marketplace ones.
+
+Ambiguous names exit \`4\` — disambiguate with \`<plugin>:<name>\` or \`_:<name>\`
+for scope-direct.
 
 ## Discover
 
 \`\`\`
-crtr skill list                    # one per line: <scope>:<plugin>/<name>  — <description>
+crtr skill list                    # one per line: <qualifier> — <description>
 crtr skill search <query>          # rank by name, description, keywords
 crtr skill grep <pattern>          # regex search across SKILL.md bodies
 \`\`\`
@@ -19,6 +28,7 @@ crtr skill grep <pattern>          # regex search across SKILL.md bodies
 \`\`\`
 crtr skill show <name>             # print SKILL.md body to stdout
 crtr skill show <plugin>:<name>    # disambiguate when names collide
+crtr skill show _:<name>           # explicit scope-direct
 crtr skill path <name>             # absolute path to SKILL.md
 crtr skill where <name>            # {scope, plugin, path} as JSON
 \`\`\`
@@ -29,10 +39,16 @@ the body.
 ## Author
 
 \`\`\`
-crtr skill new <plugin>:<name> --description "..."   # scaffold a new skill
-crtr skill show authoring-skills                     # the SKILL.md authoring guide
+crtr skill create [topic...]       # walkthrough — pick a template, capture knowledge
+crtr skill new <name>              # bare scaffold, scope-direct (asks for --scope)
+crtr skill new <plugin>:<name>     # bare scaffold inside an existing plugin
+crtr skill show authoring-skills   # the SKILL.md authoring guide
 \`\`\`
 
+Reach for \`create\` when capturing something new — it walks you through choosing
+a template (architectural primer, preference, runbook, glossary, decision,
+freeform) and applies the right research workflow for that template.
+
 ## Toggle
 
 \`\`\`
@@ -47,3 +63,219 @@ crtr skill disable <name>          # hide from list and agent discovery
 - \`4\` — ambiguous name; use \`<plugin>:<name>\`
 `;
 }
+export function skillCreatePrompt(topic) {
+    const topicLine = topic
+        ? `User-provided topic: **${topic}**`
+        : `No topic was provided — ask the user what they want to capture before continuing.`;
+    return `# Capture knowledge as a skill
+
+You are about to author a new \`crtr\` skill — a SKILL.md the agent will recall
+on demand. Skills can capture *any* kind of durable knowledge: architectural
+primers, runbooks, personal preferences, domain glossaries, decision records,
+freeform notes. Don't conflate this with "methodology only" — if the user wants
+the agent to remember something later, a skill is the right shape.
+
+${topicLine}
+
+## Step 1 — Decide the template
+
+Ask the user (use \`AskUserQuestion\` if available) which template fits, with
+your best guess pre-selected. Don't write anything until this is settled.
+
+| Template | When to use | Research workflow |
+|----------|-------------|-------------------|
+| \`primer\` | Architectural/codebase knowledge — "how does X work, why does it exist" | Parallel-explore (Step 3a) |
+| \`preference\` | User preferences, style guides, "remember I like X" | None — just ask 2-3 sharpening questions |
+| \`runbook\` | Operational procedure, incident response, "here's how to do X" | Light — confirm steps with the user |
+| \`glossary\` | Domain terms and invariants | None — list terms, get definitions from user |
+| \`decision\` | ADR-style record: context / decision / consequences | Confirm context and tradeoffs with user |
+| \`freeform\` | Anything else | Ask what shape they want |
+
+If the user is asking for a codebase primer, **also** consider whether the
+subsystem is large enough to justify it. Small/self-evident systems do not
+need a primer — push back and offer to write a one-paragraph note instead.
+
+## Step 2 — Decide the scope and name
+
+Ask the user:
+- **Scope** — \`user\` (lives in \`~/.crouter/skills/\`, available everywhere) or
+  \`project\` (lives in \`<project>/.crouter/skills/\`, only here). Default
+  \`project\` if cwd is inside a project scope; otherwise \`user\`.
+- **Name** — kebab-case slug. Suggest one from the topic.
+
+Check for collisions: \`crtr skill where <name>\`. If it exists, ask whether to
+update the existing one or pick a different name.
+
+## Step 3 — Research (template-specific)
+
+### 3a. \`primer\` — parallel codebase exploration
+
+Dispatch 4–8 \`Explore\` subagents in parallel. Partition by **slice, not by
+directory**:
+
+- **Entry points** — HTTP routes, CLI commands, cron, event handlers, public exports
+- **Data model** — schemas, types, DB tables, key invariants
+- **Control flow** — how a typical request/job traverses the system end-to-end
+- **External integrations** — third-party APIs, queues, services, env vars
+- **Tests** — what's tested reveals what's load-bearing
+- **History** — recent \`git log\` for this area surfaces ongoing work and pain
+- **Cross-cutting** — auth, errors, logging, feature flags as they apply here
+
+Each subagent must return **concrete \`file:line\` references**, *non-obvious*
+facts (skip what's obvious from filenames), naming conventions, and gotchas.
+Reject vague summaries.
+
+### 3b. \`preference\` / \`glossary\` / \`decision\` — interview
+
+Use \`AskUserQuestion\` to batch sharpening questions (≤4 at a time, multiple
+choice with your best guess first). Frame each as "here's my read; is this
+right?" Never write assumptions into the skill — if a fact isn't confirmed by
+code or the user, it doesn't go in.
+
+### 3c. \`runbook\` — walk it
+
+If the procedure exists, run/grep it and confirm. Otherwise, have the user
+narrate it once and read back the steps.
+
+## Step 4 — Verify intent
+
+Before writing, summarize your working hypothesis back to the user in 2-3
+sentences: **what this skill is about and when it should be loaded.** This is
+what code and grep can't tell you. Get a yes or correction.
+
+## Step 5 — Scaffold and write
+
+Run:
+
+\`\`\`
+crtr skill new <name> --scope <user|project> --description "<one-line trigger>"
+\`\`\`
+
+(For a plugin-scoped skill instead, use \`crtr skill new <plugin>:<name>\`.)
+
+This creates \`SKILL.md\` with frontmatter only. Open it and fill the body
+using the template skeleton below for the kind you chose. **Density rules:**
+\`file:line\` over prose; tables where structure fits; skip anything
+self-evident from a 30-second skim of the code; no "this section covers…"
+meta-commentary.
+
+The \`description:\` field drives auto-discovery — front-load the trigger
+keywords the user (or agent) would naturally say. Aim for ≤250 chars.
+
+### Skeletons
+
+**\`primer\`**
+
+\`\`\`markdown
+# <topic>
+
+## Purpose
+Why this exists. The business problem it solves. Who depends on it.
+(1–3 tight paragraphs — what code can't tell you.)
+
+## Architecture
+Components, responsibilities, data/control flow, boundaries.
+
+## File map
+| Path | Role |
+|------|------|
+| \`src/foo/bar.ts\` | … |
+
+## Key concepts
+Domain terms, invariants, non-obvious constraints.
+
+## Entry points
+Where work enters the system, with \`file:line\`.
+
+## Gotchas
+Non-obvious coupling. Things that look broken but aren't. Past footguns.
+
+## Related
+- \`<other-skill>\` — how they interact
+\`\`\`
+
+**\`preference\`**
+
+\`\`\`markdown
+# <topic preferences>
+
+## Rule
+What the user wants.
+
+## Why
+Reason given — past incident, strong preference, constraint.
+
+## How to apply
+When/where this guidance kicks in.
+\`\`\`
+
+**\`runbook\`**
+
+\`\`\`markdown
+# <procedure>
+
+## When to run this
+Triggering condition.
+
+## Steps
+1. …
+2. …
+
+## Verification
+How to confirm success.
+
+## Rollback
+How to undo if something goes wrong.
+\`\`\`
+
+**\`glossary\`**
+
+\`\`\`markdown
+# <domain> glossary
+
+| Term | Definition | Notes |
+|------|------------|-------|
+| … | … | … |
+\`\`\`
+
+**\`decision\`**
+
+\`\`\`markdown
+# <decision title> — <date>
+
+## Context
+What forced the decision.
+
+## Decision
+What we chose.
+
+## Consequences
+What this costs us. What it buys us.
+
+## Alternatives considered
+- …
+\`\`\`
+
+## Step 6 — Verify the skill is discoverable
+
+\`\`\`
+crtr skill where <name>            # confirm path/scope
+crtr skill list                    # confirm it shows up
+crtr skill show <name>             # confirm the body reads well
+\`\`\`
+
+If \`description:\` doesn't trigger the right discoveries, sharpen it. If the
+body is bloated, cut it. Budget ~150 lines for SKILL.md; move deep reference
+into sibling files in the same directory.
+
+## Constraints
+
+- Push back on trivial captures — if a one-line note in CLAUDE.md or a code
+  comment would do, suggest that instead.
+- Never write unconfirmed assumptions into the skill.
+- For updates to an existing skill, diff your draft against the current file
+  and call out what changed and why before writing.
+- Update related skills' \`## Related\` sections if you're adding something
+  that interacts with them.
+`;
+}

package/dist/prompts/spec.js

@@ -98,10 +98,35 @@ EOF
 - If you are running inside tmux, the saved spec auto-opens in a side pane
   via termrender. No extra step needed.
 
-## Phase 5: Done
+## Phase 5: Review
 
-Your turn ends after the save command succeeds. No need to summarize the spec
-in chat — the user can read the file.
+By default the save command **blocks** while a reviewer agent reads the spec
+in a side pane (10-min budget) and returns its findings on stdout under a
+\`--- review ---\` marker. **Read the review** when the command returns:
+
+- If \`Status: Approved\`, you are done.
+- If \`Status: Issues Found\`, address the listed issues by editing the spec
+  (\`crtr spec edit <name>\` or rewriting via the save command), then save
+  again to re-trigger review.
+
+Pass \`--no-review\` only when the spec is genuinely trivial (a paragraph, one
+behavior, no design decisions). For anything substantive, take the review.
+
+## Phase 6: Done
+
+After the review returns Approved (or you have addressed its issues), your
+turn ends. No need to summarize the spec in chat — the user can read the file.
+
+If the user is ready to move into planning, ask once whether they want to
+hand off now. If yes, run:
+
+\`\`\`bash
+crtr agent plan --spec <name>
+\`\`\`
+
+This fires up a planner in a new tmux pane and closes the current pane a
+few seconds later. Do NOT run this without the user's go-ahead — the kill
+is irreversible for this session.
 
 ## See also
 

package/dist/types.d.ts

@@ -59,6 +59,7 @@ export interface ScopeConfig {
     plugins: Record<string, ConfigPluginEntry>;
     skills: Record<string, ConfigSkillEntry>;
     auto_update: AutoUpdateConfig;
+    max_panes_per_window: number;
 }
 export interface ScopeState {
     marketplaces: Record<string, {
@@ -111,6 +112,8 @@ export declare const CONFIG_FILE = "config.json";
 export declare const STATE_FILE = "state.json";
 export declare const SKILL_ENTRY_FILE = "SKILL.md";
 export declare const SKILLS_DIR = "skills";
+export declare const SCOPE_SKILL_PLUGIN = "_";
+export declare const DEFAULT_MAX_PANES_PER_WINDOW = 3;
 export declare function defaultScopeConfig(): ScopeConfig;
 export declare function skillConfigKey(plugin: string, name: string): string;
 export declare function defaultScopeState(): ScopeState;

package/dist/types.js

@@ -16,6 +16,11 @@ export const CONFIG_FILE = 'config.json';
 export const STATE_FILE = 'state.json';
 export const SKILL_ENTRY_FILE = 'SKILL.md';
 export const SKILLS_DIR = 'skills';
+// Sentinel plugin name for skills that live at a scope root (no plugin wrapper).
+// Stored as `<scope-root>/skills/<name>/SKILL.md`. Shown in listings without the
+// `_/` prefix.
+export const SCOPE_SKILL_PLUGIN = '_';
+export const DEFAULT_MAX_PANES_PER_WINDOW = 3;
 export function defaultScopeConfig() {
     return {
         schema_version: SCHEMA_VERSION,
@@ -23,6 +28,7 @@ export function defaultScopeConfig() {
         plugins: {},
         skills: {},
         auto_update: { crtr: 'notify', content: 'notify', interval_hours: 24 },
+        max_panes_per_window: DEFAULT_MAX_PANES_PER_WINDOW,
     };
 }
 export function skillConfigKey(plugin, name) {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@crouton-kit/crouter",
-  "version": "0.1.4",
+  "version": "0.1.6",
   "description": "crtr — fast access to skills, plugins, and marketplaces",
   "type": "module",
   "main": "dist/index.js",