@crouton-kit/crouter 0.1.8 → 0.2.2

package/dist/prompts/skill.js

@@ -5,6 +5,22 @@ Skills are markdown the agent loads on demand. **Audience: future LLM agent
 sessions, not humans.** Write for the model: terse, decision-first, dense.
 The CLI is the index — \`crtr skill list/search/grep\` discovers what's saved.
 
+## Route by intent
+
+If a query follows this prompt, route based on it. Run the suggested command
+first, then act on its output.
+
+- **Capture** ("save", "remember", "build context for", "make a skill"):
+  \`crtr skill create [topic]\` — picks template, hints next command.
+- **Find** ("what do we have on X", "skill for Y"):
+  \`crtr skill search <query>\` → \`crtr skill show <name>\` on best hit.
+- **Load by name** ("show me X"): \`crtr skill show <name>\`.
+- **List all**: \`crtr skill list\`.
+- **No intent given / query empty**: ask the user what they want before running.
+
+Don't load \`create\` and \`template\` outputs in the same turn — \`create\` decides
+the type, then call \`template\`.
+
 Locations (resolution order):
 1. **Scope-direct** \`<scope-root>/skills/<name>/SKILL.md\` → \`user:<name>\` / \`project:<name>\`
 2. **Plugin skills** \`<plugin>/skills/<name>/SKILL.md\` → \`<scope>:<plugin>/<name>\`
@@ -32,14 +48,30 @@ crtr skill where <name>            # {scope, plugin, path} JSON
 ## Author (progressive disclosure)
 
 \`\`\`
-crtr skill create [topic...]       # pick a template type
-crtr skill template <type> [topic] # workflow + skeleton for that type
-crtr skill new <name>              # bare scaffold, scope-direct
+crtr skill create [topic...]            # pick a template type
+crtr skill template <type> [topic]      # workflow + skeleton for that type
+crtr skill new <name> --type <type>     # bare scaffold with typed frontmatter
 \`\`\`
 
+Five types — pick by what the agent does after reading:
+
+- \`playbook\` — decide (judgment, heuristics, when-to-use)
+- \`primer\` — navigate (codebase facts, architecture)
+- \`reference\` — look up (stable facts, tables)
+- \`runbook\` — execute (numbered procedure)
+- \`freeform\` — none of the above (catchall)
+
 Don't load \`create\` and \`template\` in the same turn — \`create\` decides the
 type, then call \`template\`.
 
+## Neighbors auto-append
+
+\`crtr skill show <name>\` appends a \`## Neighbors\` section listing siblings
+(same parent dir) and nested skills. Skill bodies should write \`## Related\`
+**only** for cross-plugin or distant refs — within-plugin links are redundant.
+
+Suppress with \`crtr skill show <name> --no-neighbors\`.
+
 ## Toggle
 
 \`\`\`
@@ -65,11 +97,22 @@ ${topicLine}
 
 ## Templates
 
-- \`primer\` — codebase/architectural knowledge ("how does X work, why, what
-  are the gotchas"). Triggers parallel-explore research.
-- \`playbook\` — methodology/judgment ("how to think about X"). The
-  \`authoring:skills\`-style skill that teaches decisions, not facts.
-- \`freeform\` — anything else (glossary, decision record, runbook, prefs).
+Pick by what the agent does after reading the skill:
+
+- \`playbook\` — **decide**. Judgment, heuristics, when-to-use / when-not-to-use.
+  Examples: skill-authoring, debugging methodology. Most skills are this.
+- \`primer\` — **navigate**. Codebase/architectural facts. *"How does this
+  subsystem work, why, what are the gotchas."* Triggers parallel-explore.
+- \`reference\` — **look up**. Stable facts: protocol fields, API surface,
+  glossaries, lookup tables. Source of truth is external (spec, docs).
+- \`runbook\` — **execute**. Numbered procedure with decision points and
+  rollback. Examples: deploy, incident response, review workflow.
+- \`freeform\` — **none of the above**. Catchall for decision records, prefs,
+  miscellany.
+
+Litmus: *"when X, do Y"* → playbook. *"these are the fields of Y"* →
+reference. *"step 1, step 2, step 3"* → runbook. *"how X is built inside
+this repo"* → primer.
 
 ## Next
 
@@ -87,6 +130,7 @@ ${topicLine}
 
 - Subsystem is small/self-evident → suggest CLAUDE.md note instead of primer.
 - "Topic" is really a one-off task → don't capture; just do the work.
+- Content is one-off lookup that lives elsewhere → link to it, don't mirror.
 `;
 }
 export function skillTemplatePrompt(type, topic) {
@@ -95,9 +139,13 @@ export function skillTemplatePrompt(type, topic) {
         return primerTemplatePrompt(topic);
     if (t === 'playbook')
         return playbookTemplatePrompt(topic);
+    if (t === 'reference')
+        return referenceTemplatePrompt(topic);
+    if (t === 'runbook')
+        return runbookTemplatePrompt(topic);
     if (t === 'freeform')
         return freeformTemplatePrompt(topic);
-    return `unknown template type: ${type}\nvalid: primer | playbook | freeform\nrun \`crtr skill create\` to pick.\n`;
+    return `unknown template type: ${type}\nvalid: playbook | primer | reference | runbook | freeform\nrun \`crtr skill create\` to pick.\n`;
 }
 function topicLine(topic) {
     return topic
@@ -160,7 +208,7 @@ assumptions.**
 ## 5. Scaffold
 
 \`\`\`
-crtr skill new <name> --scope project --description "<what+when, ≤250 chars, front-loaded triggers>"
+crtr skill new <name> --type primer --scope project --description "<what+when, ≤250 chars, front-loaded triggers>"
 \`\`\`
 
 ## 6. Write the body
@@ -188,11 +236,12 @@ Domain terms, invariants, non-obvious constraints.
 
 ## Gotchas
 Non-obvious coupling. Looks-broken-but-isn't. Past footguns.
-
-## Related
-- \`<other-skill>\` — interaction
 \`\`\`
 
+**No \`## Related\` for within-plugin siblings** — the CLI auto-appends a
+\`## Neighbors\` section on \`crtr skill show\`. Add a manual \`## Related\`
+only for cross-plugin or distant refs.
+
 **Density rules:**
 - \`file:line\` over prose
 - Tables where structure fits
@@ -213,7 +262,7 @@ Sharpen description if discovery misses. Cut body if bloated.
 ## Updates
 
 If updating existing primer: diff draft vs current, call out changes + why
-before writing. Update related skills' \`## Related\` sections.
+before writing.
 `;
 }
 function playbookTemplatePrompt(topic) {
@@ -259,7 +308,7 @@ PR over many small ones for refactors here, because review churn dominates"*
 ## 3. Scaffold
 
 \`\`\`
-crtr skill new <name> --scope <user|project> --description "<what it teaches + when to load, ≤250 chars, front-loaded triggers>"
+crtr skill new <name> --type playbook --scope <user|project> --description "<what it teaches + when to load, ≤250 chars, front-loaded triggers>"
 \`\`\`
 
 ## 4. Density rules
@@ -298,11 +347,12 @@ to read the whole thing for value, you've buried the judgment.
 
 ## Failure modes
 - **<name>**: what it looks like; how to avoid
-
-## Related
-- \`<other-skill>\` — interaction
 \`\`\`
 
+**No \`## Related\` for within-plugin siblings** — the CLI auto-appends a
+\`## Neighbors\` section on \`crtr skill show\`. Add a manual \`## Related\`
+only for cross-plugin or distant refs.
+
 ## 6. Progressive disclosure
 
 If deep reference is needed:
@@ -331,18 +381,17 @@ For canonical SKILL.md authoring (frontmatter fields, argument passing,
 dynamic context, subagent forking, hooks):
 
 \`\`\`
-crtr skill show authoring-skills
+crtr skill show crouter-development/skills
 \`\`\`
 
-The playbook above gives you structure + density rules. \`authoring-skills\`
-covers the SKILL.md surface itself.
+The playbook above gives you structure + density rules.
+\`crouter-development/skills\` covers the SKILL.md surface itself.
 
 ## Constraints
 
-- Topic fails litmus? → \`crtr skill template freeform\` or \`primer\`.
+- Topic fails litmus? → \`crtr skill template freeform\`, \`reference\`, or \`runbook\`.
 - No unconfirmed heuristics — if not from user experience or clear principle,
   leave it out.
-- Update related skills' \`## Related\` if interactions exist.
 `;
 }
 function freeformTemplatePrompt(topic) {
@@ -375,7 +424,7 @@ or grep, omit it.
 ## 3. Scope + name + scaffold
 
 \`\`\`
-crtr skill new <name> --scope <user|project> --description "<what+when, ≤250 chars, front-loaded triggers>"
+crtr skill new <name> --type freeform --scope <user|project> --description "<what+when, ≤250 chars, front-loaded triggers>"
 \`\`\`
 
 ## 4. Body — pick the closest skeleton
@@ -425,11 +474,226 @@ crtr skill search <keyword>
 
 ## Switch templates if needed
 
-If the content is actually methodology or codebase knowledge:
+Content actually fits a typed template?
+
+\`\`\`
+crtr skill template playbook ${topic ? topic : '<topic>'}     # decide
+crtr skill template primer ${topic ? topic : '<topic>'}       # navigate codebase
+crtr skill template reference ${topic ? topic : '<topic>'}    # look up stable facts
+crtr skill template runbook ${topic ? topic : '<topic>'}      # execute a procedure
+\`\`\`
+`;
+}
+function referenceTemplatePrompt(topic) {
+    return `# Reference — lookup-fact skill
+
+**Audience: future LLM agent sessions.** Captures *stable lookup facts* an
+agent will grep or scan: protocol fields, API surfaces, glossaries, enum
+tables, status-code maps. Source of truth lives *outside* the skill (RFC,
+spec, vendor docs); the skill is a fast in-repo cache.
+
+${topicLine(topic)}
+
+## Litmus test
+
+> Would you *grep* this rather than *read* it?
+
+If you'd skim end-to-end → it's not reference. If you'd jump straight to
+the row you need → reference. If you'd make a decision after reading →
+\`crtr skill template playbook\`. If you'd execute steps → \`runbook\`.
+
+**Reference markers:** mostly tables · stable across releases · authoritative
+source elsewhere · agent loads to *answer*, not to *think*.
+
+## 1. Confirm reference, not playbook
+
+Use \`AskUserQuestion\` (≤4, multi-choice, best-guess first):
+
+- The lookup the agent will perform (e.g., "what does HTTP 423 mean")
+- Stability: does this change every release? If yes, push back — link the
+  upstream source instead of mirroring it.
+- Authoritative source URL (cite in the body)
+
+Skip if the topic is clearly facts (RFCs, public API). **Never invent
+field/flag/code values** — pull verbatim from source.
+
+## 2. Scope + name
+
+- **Scope**: \`user\` for cross-project facts. \`project\` for repo-specific.
+- **Name**: noun-phrase. \`http-status-codes\` not \`learn-http-status\`.
+- Check \`crtr skill where <name>\`.
+
+## 3. Scaffold
+
+\`\`\`
+crtr skill new <name> --type reference --scope <user|project> --description "<what to look up + when to load, ≤250 chars>"
+\`\`\`
+
+## 4. Density rules
+
+Reference skills are *load and scan*, not *load and read*. Optimize for jump-to-row.
+
+- Tables for anything multi-row. Columns: most-queried field first.
+- One topic per file. Split if it doesn't fit one screen.
+- Source URL at the top — agent verifies before trusting cached facts.
+- No prose paragraphs longer than 2 lines.
+- Skip *why* — playbooks teach why. Reference teaches what.
+
+## 5. Body skeleton
+
+\`\`\`markdown
+# <topic> reference
+
+**Source of truth:** <URL or spec name>
+**Last verified:** <date — when an agent should re-check>
+
+## <table 1 title>
+| <field> | <value> | <notes> |
+|---------|---------|---------|
+| …       | …       | …       |
+
+## <table 2 title>
+…
+
+## Edge cases / gotchas
+- Brief bullets. *What* is misleading, not *why*.
+\`\`\`
+
+**No \`## Related\` for within-plugin siblings** — auto-appended by the CLI.
+
+## 6. Progressive disclosure
+
+If reference is large, split:
+
+\`\`\`
+<skill-dir>/
+  SKILL.md           # top-level index + most-queried table
+  full-table.md      # the full set
+  examples.md        # rarely-needed worked examples
+\`\`\`
+
+SKILL.md links to siblings (\`see [full-table.md](full-table.md)\`).
+
+## 7. Verify
 
 \`\`\`
-crtr skill template playbook ${topic ? topic : '<topic>'}
-crtr skill template primer ${topic ? topic : '<topic>'}
+crtr skill where <name>
+crtr skill show <name>
+crtr skill search <keyword>
 \`\`\`
+
+Search must surface the skill on a typical lookup query. Sharpen the
+description if it doesn't.
+
+## Constraints
+
+- No invented values. If you can't cite the source, leave the row out.
+- Topic teaches *judgment*, not facts? → \`crtr skill template playbook\`.
+- Topic is a *procedure*? → \`crtr skill template runbook\`.
+- Source updates faster than you'll update the skill? → don't capture; link.
+`;
+}
+function runbookTemplatePrompt(topic) {
+    return `# Runbook — procedure skill
+
+**Audience: future LLM agent sessions.** Captures a *procedure* the agent
+executes: numbered steps, decision points, verification, rollback. Examples:
+deploy, incident response, review workflow, release cut.
+
+${topicLine(topic)}
+
+## Litmus test
+
+> After loading this, does the agent *do steps in order*?
+
+If yes → runbook. If the agent makes a decision and stops → \`playbook\`. If
+the agent looks up a value → \`reference\`. If neither fits → \`freeform\`.
+
+**Runbook markers:** numbered steps · ordering matters · has rollback or
+verification · maps an outcome to a known sequence.
+
+## 1. Capture the procedure
+
+Use \`AskUserQuestion\` (≤4, multi-choice, best-guess first):
+
+- The trigger (when does the agent run this?)
+- Steps in order — explicit, atomic. *"Update X"* is not atomic; *"run
+  \\\`pnpm db:migrate\\\` and confirm exit 0"* is.
+- Decision points within the sequence (when does the agent branch?)
+- Rollback / verification (how to confirm success; how to undo on failure)
+
+Push back on vagueness. *"Deploy to prod"* is a label; *"run \\\`pnpm build\\\`,
+push to \\\`main\\\`, wait for green CI, click promote"* is a runbook step.
+
+## 2. Scope + name
+
+- **Scope**: \`project\` for repo-specific procedures. \`user\` for cross-project.
+- **Name**: verb-phrase. \`deploy-to-prod\` not \`production-deployment-guide\`.
+- Check \`crtr skill where <name>\`.
+
+## 3. Scaffold
+
+\`\`\`
+crtr skill new <name> --type runbook --scope <user|project> --description "<when to run + outcome, ≤250 chars, front-loaded trigger>"
+\`\`\`
+
+## 4. Density rules
+
+- Steps are commands, not advice. Each step is something the agent can verify.
+- Decision points get explicit branches, not "use judgment."
+- Verification belongs in-line, after the step that produces the change.
+- Rollback is mandatory if the procedure changes prod state.
+
+## 5. Body skeleton
+
+\`\`\`markdown
+# <procedure>
+
+## When to run
+- <trigger>
+
+## Pre-flight
+- [ ] <thing that must be true before starting>
+
+## Steps
+
+1. **<atomic action>** — \\\`<command>\\\`
+   Verify: <observation that confirms success>
+   If <error condition>: <what to do>
+
+2. **<atomic action>** — …
+
+## Decision points
+
+- After step N, if X then go to step M; else continue.
+
+## Verification (post-flight)
+- [ ] <how to confirm the procedure succeeded end-to-end>
+
+## Rollback
+1. <reverse-order undo steps with their own verification>
+\`\`\`
+
+**No \`## Related\` for within-plugin siblings** — auto-appended by the CLI.
+
+## 6. Verify
+
+\`\`\`
+crtr skill where <name>
+crtr skill show <name>
+crtr skill search <keyword>
+\`\`\`
+
+Walk through the runbook mentally. Each step verifiable? Each decision
+explicit? Rollback covers the state changes? If any answer is no, fix
+before shipping.
+
+## Constraints
+
+- Steps without verification are wishes. Add the verify line or cut the step.
+- "Use your judgment at step 4" → either turn step 4 into a playbook
+  reference, or write the decision criteria explicitly.
+- A procedure that's actually one command isn't a runbook — make it a
+  CLAUDE.md note.
 `;
 }

package/dist/prompts/spec.js

@@ -12,6 +12,10 @@ Specs for this directory live at:
 If a relevant prior spec already exists there, read it first. Treat an
 existing spec as the starting point — extend or revise rather than restart.
 
+**Anti-pattern: do not fish for clarifications upfront.** Draft a concrete
+spec first based on your investigation, *then* iterate. A specific draft the
+user can react to converges faster than a list of questions in a vacuum.
+
 ## Phase 1: Shape
 
 Build a comprehensive picture of the problem and the relevant code. Surface
@@ -36,18 +40,25 @@ should be:
 - **Behavior-focused** — describes what the system does, not how.
 - **Scoped** — covers one observable behavior.
 
-Prefer EARS-style phrasing where it fits (\`When <trigger>, the system shall
-<behavior>\`), but do not force it. Group requirements by capability.
+Group requirements by capability. Plain English is fine for most things. If
+a requirement is conditional or stateful enough that phrasing gets fuzzy,
+EARS templates can sharpen it (\`When <trigger>, the system shall <behavior>\`
+or \`If <condition>, then the system shall <response>\`) — reach for them
+when they earn their keep, not by default.
 
-You may launch a Plan agent to draft requirements for a specific capability
-in parallel, but for small specs writing them yourself is usually faster.
+For larger / multi-component designs, before moving on it's worth walking
+the design end-to-end as a sanity check: at each step from trigger to
+final state, ask whether preconditions, state, failure handling, and
+handoffs between components are actually specified. Skip this for small
+self-contained specs — it's the kind of thing that catches bugs in the
+seams, so apply it where there are seams.
 
 ## Phase 3: Deepen
 
 - Read the critical files identified during Phase 1 to deepen your
   understanding before locking decisions.
-- Reconcile the requirements against the shape — if a requirement reveals a
-  gap in the design, refine the design before saving.
+- Reconcile requirements against the shape — if a requirement reveals a gap
+  in the design, refine the design before saving.
 - Use **AskUserQuestion** for any remaining ambiguities. Bias toward asking
   when a decision is non-obvious or when the user's intent is genuinely
   unclear.
@@ -74,10 +85,10 @@ outcome. Include relevant constraints — user goals, stakeholders, deadlines.>
 they were chosen. Reference existing code with \`file_path:line_number\`.>
 
 ## Requirements
-<grouped behavioral requirements. Each one testable.>
+<grouped behavioral requirements. Each one testable. Plain English is fine.>
 
 ### <Capability A>
-- When <trigger>, the system shall <behavior>.
+- <one observable behavior>
 - ...
 
 ### <Capability B>
@@ -96,7 +107,11 @@ EOF
   (\`crtr spec --name auth/refresh-tokens\`).
 - The file lands at \`${specsDir}/<name>.md\`.
 - If you are running inside tmux, the saved spec auto-opens in a side pane
-  via termrender. No extra step needed.
+  (or a new window when the current one is full) via termrender. The pane
+  is **live** — it re-renders whenever the file changes on disk. For small
+  tweaks, **edit the file path directly with the Edit tool** instead of
+  re-running the heredoc save; the pane updates in place. Re-save via
+  heredoc only when you want to re-trigger the reviewer.
 
 ## Phase 5: Review
 

package/dist/types.d.ts

@@ -1,4 +1,4 @@
-export type Scope = 'user' | 'project';
+export type Scope = 'user' | 'project' | 'builtin';
 export declare const ExitCode: {
     readonly SUCCESS: 0;
     readonly GENERAL: 1;
@@ -71,10 +71,14 @@ export interface ScopeState {
     last_self_check?: string;
     bootstrap_done?: boolean;
 }
+export declare const SKILL_TYPES: readonly ["playbook", "primer", "reference", "runbook", "freeform"];
+export type SkillType = (typeof SKILL_TYPES)[number];
+export declare function isSkillType(v: unknown): v is SkillType;
 export interface SkillFrontmatter {
     name: string;
     description?: string;
     keywords?: string[];
+    type?: SkillType;
 }
 export interface Skill {
     name: string;
@@ -92,6 +96,7 @@ export interface InstalledPlugin {
     root: string;
     manifest: PluginManifest;
     enabled: boolean;
+    builtin?: boolean;
     sourceMarketplace?: string;
     version?: string;
 }

package/dist/types.js

@@ -7,6 +7,10 @@ export const ExitCode = {
     NETWORK: 5,
 };
 export const SCHEMA_VERSION = 1;
+export const SKILL_TYPES = ['playbook', 'primer', 'reference', 'runbook', 'freeform'];
+export function isSkillType(v) {
+    return typeof v === 'string' && SKILL_TYPES.includes(v);
+}
 export const PLUGIN_MANIFEST_DIR = '.crouter-plugin';
 export const PLUGIN_MANIFEST_FILE = 'plugin.json';
 export const MARKETPLACE_MANIFEST_DIR = '.crouter-marketplace';

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@crouton-kit/crouter",
-  "version": "0.1.8",
+  "version": "0.2.2",
   "description": "crtr — fast access to skills, plugins, and marketplaces",
   "type": "module",
   "main": "dist/index.js",
@@ -23,7 +23,7 @@
     "bin"
   ],
   "scripts": {
-    "build": "tsc",
+    "build": "tsc && rm -rf dist/builtin-skills && cp -R src/builtin-skills dist/builtin-skills",
     "dev": "tsx src/cli.ts",
     "link": "npm link",
     "prepublishOnly": "npm run build"