cclaw-cli 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,100 @@
+# cclaw
+
+**A focused, installer-first workflow that turns AI coding sessions into predictable shipped outcomes.**
+
+`cclaw` gives your agent one clear path:
+**brainstorm -> scope -> design -> spec -> plan -> test -> build -> review -> ship**
+
+No giant command jungle. No runtime daemon. No process theater.
+Just a disciplined flow that stays lightweight and works across major coding harnesses.
+
+## How It Works
+
+```mermaid
+flowchart LR
+    A[Idea] --> B[Brainstorm]
+    B --> C[Scope]
+    C --> D[Design]
+    D --> E[Spec]
+    E --> F[Plan]
+    F --> G[Test]
+    G --> H[Build]
+    H --> I[Review]
+    I --> J[Ship]
+```
+
+```mermaid
+sequenceDiagram
+    participant U as User
+    participant H as Harness
+    participant V as cclaw Hooks + Skills
+    participant S as State + Learnings
+    U->>H: /cc-brainstorm
+    H->>V: Load stage contract + HARD-GATE
+    V->>S: Read context (state/learnings)
+    V-->>H: Structured execution guidance
+    H->>S: Write artifacts + checkpoint
+    S-->>U: Next stage is explicit
+```
+
+## Why `cclaw` Wins In Practice
+
+- **Low cognitive load:** one canonical stage flow instead of dozens of competing paths.
+- **Installer-first architecture:** generates files and hooks; does not run a hidden control plane.
+- **Hard-gated quality:** each stage has non-skippable constraints that reduce AI drift.
+- **Cross-harness parity:** same behavior model across Claude Code, Cursor, Codex, OpenCode.
+- **Compounding context:** flow state + learnings get rehydrated on new sessions automatically.
+- **Run-scoped execution:** each flow works against an active run with explicit handoff state.
+
+## Compared To Top References
+
+| System | Strongest trait | Where `cclaw` is better |
+|---|---|---|
+| **Superpowers** | Rich skill ecosystem and mature workflows | Smaller operational surface, tighter stage discipline, faster onboarding for teams that want one default path |
+| **G-Stack** | Deep multi-role orchestration (CEO/design/eng/release style) | Less overhead, fewer moving parts, easier to keep deterministic in day-to-day product delivery |
+| **Everything Claude Code** | Broad command catalog and flexible patterns | Lower command entropy, clearer defaults, less decision fatigue for regular execution |
+
+`cclaw` is intentionally opinionated: it optimizes for **signal over volume**.
+
+## 60-Second Start
+
+```bash
+npx cclaw-cli init
+```
+
+Then run in your harness:
+
+```text
+/cc-brainstorm
+```
+
+Core installer lifecycle:
+
+```bash
+npx cclaw-cli sync
+npx cclaw-cli doctor
+npx cclaw-cli upgrade
+npx cclaw-cli uninstall
+```
+
+## What Gets Generated
+
+```text
+.cclaw/
+├── skills/
+├── commands/
+├── hooks/
+├── templates/
+├── artifacts/                # active mirror for current run (fallback path)
+├── state/
+├── runs/
+│   └── <activeRunId>/
+│       ├── artifacts/        # canonical run artifacts
+│       ├── run.json
+│       └── 00-handoff.md
+└── learnings.jsonl
+```
+
+## License
+
+[MIT](./LICENSE)

package/dist/cli.d.ts

@@ -0,0 +1,10 @@
+#!/usr/bin/env node
+import type { HarnessId } from "./types.js";
+type CommandName = "init" | "sync" | "doctor" | "upgrade" | "uninstall";
+interface ParsedArgs {
+    command?: CommandName;
+    harnesses?: HarnessId[];
+}
+declare function parseHarnesses(raw: string): HarnessId[];
+declare function parseArgs(argv: string[]): ParsedArgs;
+export { parseArgs, parseHarnesses };

package/dist/cli.js

@@ -0,0 +1,101 @@
+#!/usr/bin/env node
+import process from "node:process";
+import path from "node:path";
+import { fileURLToPath } from "node:url";
+import { HARNESS_IDS } from "./types.js";
+import { doctorChecks, doctorSucceeded } from "./doctor.js";
+import { initCclaw, syncCclaw, uninstallCclaw, upgradeCclaw } from "./install.js";
+import { error, info } from "./logger.js";
+const INSTALLER_COMMANDS = ["init", "sync", "doctor", "upgrade", "uninstall"];
+function usage() {
+    return `cclaw - installer-first flow toolkit
+
+Usage:
+  cclaw init [--harnesses=claude,cursor,opencode,codex]
+  cclaw sync
+  cclaw doctor
+  cclaw upgrade
+  cclaw uninstall
+`;
+}
+function parseHarnesses(raw) {
+    const requested = raw
+        .split(",")
+        .map((item) => item.trim())
+        .filter(Boolean);
+    const invalid = requested.filter((item) => !HARNESS_IDS.includes(item));
+    if (invalid.length > 0) {
+        throw new Error(`Unknown harnesses: ${invalid.join(", ")}`);
+    }
+    return requested;
+}
+function parseArgs(argv) {
+    const [commandRaw, ...flags] = argv;
+    const command = INSTALLER_COMMANDS.includes(commandRaw)
+        ? commandRaw
+        : undefined;
+    const parsed = { command };
+    for (const flag of flags) {
+        if (flag.startsWith("--harnesses=")) {
+            parsed.harnesses = parseHarnesses(flag.replace("--harnesses=", ""));
+        }
+    }
+    return parsed;
+}
+async function runCommand(parsed, ctx) {
+    const command = parsed.command;
+    if (!command) {
+        ctx.stderr.write(usage());
+        return 1;
+    }
+    if (command === "init") {
+        await initCclaw({
+            projectRoot: ctx.cwd,
+            harnesses: parsed.harnesses
+        });
+        info(ctx, "Initialized .cclaw runtime and generated harness shims");
+        return 0;
+    }
+    if (command === "sync") {
+        await syncCclaw(ctx.cwd);
+        info(ctx, "Synchronized harness shims from current .cclaw config");
+        return 0;
+    }
+    if (command === "doctor") {
+        const checks = await doctorChecks(ctx.cwd);
+        for (const check of checks) {
+            ctx.stdout.write(`${check.ok ? "PASS" : "FAIL"} ${check.name} :: ${check.details}\n`);
+        }
+        return doctorSucceeded(checks) ? 0 : 2;
+    }
+    if (command === "upgrade") {
+        await upgradeCclaw(ctx.cwd);
+        info(ctx, "Upgraded .cclaw runtime and regenerated generated files");
+        return 0;
+    }
+    await uninstallCclaw(ctx.cwd);
+    info(ctx, "Removed .cclaw runtime and generated shim files");
+    return 0;
+}
+async function main() {
+    const parsed = parseArgs(process.argv.slice(2));
+    const ctx = {
+        cwd: process.cwd(),
+        stdout: process.stdout,
+        stderr: process.stderr
+    };
+    try {
+        const code = await runCommand(parsed, ctx);
+        process.exitCode = code;
+    }
+    catch (err) {
+        error(ctx, err instanceof Error ? err.message : "Unknown error");
+        process.exitCode = 1;
+    }
+}
+const entryPath = process.argv[1] ? path.resolve(process.argv[1]) : "";
+const modulePath = fileURLToPath(import.meta.url);
+if (entryPath === modulePath) {
+    void main();
+}
+export { parseArgs, parseHarnesses };

package/dist/config.d.ts

@@ -0,0 +1,5 @@
+import type { HarnessId, CclawConfig } from "./types.js";
+export declare function configPath(projectRoot: string): string;
+export declare function createDefaultConfig(harnesses?: HarnessId[]): CclawConfig;
+export declare function readConfig(projectRoot: string): Promise<CclawConfig>;
+export declare function writeConfig(projectRoot: string, config: CclawConfig): Promise<void>;

package/dist/config.js

@@ -0,0 +1,70 @@
+import fs from "node:fs/promises";
+import path from "node:path";
+import { parse, stringify } from "yaml";
+import { DEFAULT_HARNESSES, FLOW_VERSION, RUNTIME_ROOT, CCLAW_VERSION } from "./constants.js";
+import { exists, writeFileSafe } from "./fs-utils.js";
+import { HARNESS_IDS } from "./types.js";
+const CONFIG_PATH = `${RUNTIME_ROOT}/config.yaml`;
+const HARNESS_ID_SET = new Set(HARNESS_IDS);
+const SUPPORTED_HARNESSES_TEXT = HARNESS_IDS.join(", ");
+function configFixExample() {
+    return `harnesses:
+  - claude
+  - cursor`;
+}
+function configValidationError(configFilePath, reason) {
+    return new Error(`Invalid cclaw config at ${configFilePath}: ${reason}\n` +
+        `Supported harnesses: ${SUPPORTED_HARNESSES_TEXT}\n` +
+        `Example config:\n${configFixExample()}\n` +
+        `After fixing, run: cclaw sync`);
+}
+export function configPath(projectRoot) {
+    return path.join(projectRoot, CONFIG_PATH);
+}
+export function createDefaultConfig(harnesses = DEFAULT_HARNESSES) {
+    return {
+        version: CCLAW_VERSION,
+        flowVersion: FLOW_VERSION,
+        harnesses
+    };
+}
+export async function readConfig(projectRoot) {
+    const fullPath = configPath(projectRoot);
+    if (!(await exists(fullPath))) {
+        return createDefaultConfig();
+    }
+    let parsedUnknown;
+    try {
+        parsedUnknown = parse(await fs.readFile(fullPath, "utf8"));
+    }
+    catch {
+        return createDefaultConfig();
+    }
+    const parsed = (parsedUnknown && typeof parsedUnknown === "object"
+        ? parsedUnknown
+        : {});
+    const hasHarnessesField = Object.prototype.hasOwnProperty.call(parsed, "harnesses");
+    if (hasHarnessesField && !Array.isArray(parsed.harnesses)) {
+        throw configValidationError(fullPath, `"harnesses" must be an array`);
+    }
+    const configuredHarnesses = (parsed.harnesses ?? []);
+    const invalidHarnesses = configuredHarnesses.filter((harness) => typeof harness !== "string" || !HARNESS_ID_SET.has(harness));
+    if (invalidHarnesses.length > 0) {
+        const formatted = invalidHarnesses
+            .map((item) => (typeof item === "string" ? item : JSON.stringify(item)))
+            .join(", ");
+        throw configValidationError(fullPath, `unknown harness id(s): ${formatted}`);
+    }
+    const validatedHarnesses = configuredHarnesses;
+    const harnesses = hasHarnessesField
+        ? [...new Set(validatedHarnesses)]
+        : DEFAULT_HARNESSES;
+    return {
+        version: parsed.version ?? CCLAW_VERSION,
+        flowVersion: parsed.flowVersion ?? FLOW_VERSION,
+        harnesses
+    };
+}
+export async function writeConfig(projectRoot, config) {
+    await writeFileSafe(configPath(projectRoot), stringify(config));
+}

package/dist/constants.d.ts

@@ -0,0 +1,12 @@
+import type { FlowStage, HarnessId } from "./types.js";
+/** Hidden runtime directory at project root (dot-prefixed). */
+export declare const RUNTIME_ROOT = ".cclaw";
+export declare const CCLAW_VERSION = "0.1.0";
+export declare const FLOW_VERSION = "1.0.0";
+export declare const DEFAULT_HARNESSES: HarnessId[];
+export declare const REQUIRED_DIRS: readonly [".cclaw", ".cclaw/commands", ".cclaw/skills", ".cclaw/templates", ".cclaw/artifacts", ".cclaw/state", ".cclaw/runs", ".cclaw/rules", ".cclaw/adapters", ".cclaw/agents", ".cclaw/hooks"];
+export declare const REQUIRED_GITIGNORE_PATTERNS: readonly ["# cclaw generated artifacts", ".cclaw/", ".claude/commands/cc-*.md", ".cursor/commands/cc-*.md", ".opencode/commands/cc-*.md", ".codex/commands/cc-*.md", ".claude/hooks/hooks.json", ".cursor/hooks.json", ".codex/hooks.json"];
+export declare const COMMAND_FILE_ORDER: FlowStage[];
+export declare const UTILITY_COMMANDS: readonly ["learn", "autoplan"];
+export declare const SUBAGENT_SKILL_FOLDERS: readonly ["subagent-dev", "parallel-dispatch"];
+export type UtilityCommand = (typeof UTILITY_COMMANDS)[number];

package/dist/constants.js

@@ -0,0 +1,50 @@
+/** Hidden runtime directory at project root (dot-prefixed). */
+export const RUNTIME_ROOT = ".cclaw";
+export const CCLAW_VERSION = "0.1.0";
+export const FLOW_VERSION = "1.0.0";
+export const DEFAULT_HARNESSES = [
+    "claude",
+    "cursor",
+    "opencode",
+    "codex"
+];
+export const REQUIRED_DIRS = [
+    RUNTIME_ROOT,
+    `${RUNTIME_ROOT}/commands`,
+    `${RUNTIME_ROOT}/skills`,
+    `${RUNTIME_ROOT}/templates`,
+    `${RUNTIME_ROOT}/artifacts`,
+    `${RUNTIME_ROOT}/state`,
+    `${RUNTIME_ROOT}/runs`,
+    `${RUNTIME_ROOT}/rules`,
+    `${RUNTIME_ROOT}/adapters`,
+    `${RUNTIME_ROOT}/agents`,
+    `${RUNTIME_ROOT}/hooks`
+];
+export const REQUIRED_GITIGNORE_PATTERNS = [
+    "# cclaw generated artifacts",
+    `${RUNTIME_ROOT}/`,
+    ".claude/commands/cc-*.md",
+    ".cursor/commands/cc-*.md",
+    ".opencode/commands/cc-*.md",
+    ".codex/commands/cc-*.md",
+    ".claude/hooks/hooks.json",
+    ".cursor/hooks.json",
+    ".codex/hooks.json"
+];
+export const COMMAND_FILE_ORDER = [
+    "brainstorm",
+    "scope",
+    "design",
+    "spec",
+    "plan",
+    "test",
+    "build",
+    "review",
+    "ship"
+];
+export const UTILITY_COMMANDS = ["learn", "autoplan"];
+export const SUBAGENT_SKILL_FOLDERS = [
+    "subagent-dev",
+    "parallel-dispatch"
+];

package/dist/content/agents.d.ts

@@ -0,0 +1,39 @@
+/**
+ * Agent persona content for Cclaw.
+ *
+ * Cclaw emits markdown agent definitions (`.md` with YAML frontmatter) that harnesses
+ * use for specialist delegation. Agents are isolated context windows with constrained
+ * tools; skills remain procedural recipes.
+ */
+export interface AgentDefinition {
+    /** Kebab-case identifier, e.g. `"spec-reviewer"`. */
+    name: string;
+    /** When to invoke — include PROACTIVE / MUST BE USED style guidance for harnesses. */
+    description: string;
+    /** Allowed tools for this agent (harness-specific names). */
+    tools: string[];
+    /** Model tier for routing cost/latency vs depth. */
+    model: "fast" | "balanced" | "deep";
+    /** How the harness should treat activation relative to flow context. */
+    activation: "proactive" | "on-demand" | "mandatory";
+    /** Cclaw flow stages this agent is designed to support. */
+    relatedStages: string[];
+    /** Markdown body rendered below the YAML frontmatter. */
+    body: string;
+}
+/**
+ * Canonical specialist agents Cclaw can materialize under `.cclaw/agents/`.
+ */
+export declare const CCLAW_AGENTS: AgentDefinition[];
+/**
+ * Render a complete Cclaw agent markdown file (YAML frontmatter + body).
+ */
+export declare function agentMarkdown(agent: AgentDefinition): string;
+/**
+ * Markdown table mapping Cclaw slash commands to recommended specialist agents.
+ */
+export declare function agentRoutingTable(): string;
+/**
+ * AGENTS.md-ready section describing Cclaw’s specialist delegation model.
+ */
+export declare function agentsAgentsMdBlock(): string;

package/dist/content/agents.js

@@ -0,0 +1,244 @@
+/**
+ * Agent persona content for Cclaw.
+ *
+ * Cclaw emits markdown agent definitions (`.md` with YAML frontmatter) that harnesses
+ * use for specialist delegation. Agents are isolated context windows with constrained
+ * tools; skills remain procedural recipes.
+ */
+function yamlScalarString(value) {
+    // JSON double-quoted strings are valid YAML scalars and escape reliably.
+    return JSON.stringify(value);
+}
+function yamlFlowSequence(values) {
+    return JSON.stringify(values);
+}
+/**
+ * Canonical specialist agents Cclaw can materialize under `.cclaw/agents/`.
+ */
+export const CCLAW_AGENTS = [
+    {
+        name: "planner",
+        description: "PROACTIVE: Use for complex features, ambiguous requirements, or multi-area refactors. MUST BE USED when the user asks for a plan, breakdown, sequencing, or risk register before coding.",
+        tools: ["Read", "Grep", "Glob", "WebSearch"],
+        model: "deep",
+        activation: "proactive",
+        relatedStages: ["brainstorm", "scope", "design", "spec", "plan"],
+        body: [
+            "You are an **implementation planning specialist** (staff engineer mindset).",
+            "",
+            "Expert at decomposing complex requirements into actionable plans. When invoked:",
+            "",
+            "1. **Analyze** the request scope and identify sub-problems (including implicit ones).",
+            "2. **Map** sub-problems to existing code, modules, and reusable components (cite what you read).",
+            "3. **Produce** a structured plan with:",
+            "   - dependency graph (what blocks what)",
+            "   - task ordering (parallelizable vs sequential)",
+            "   - effort estimates (T-shirt sizes are fine; justify uncertainty)",
+            "4. **Flag** risks, unknowns, and decisions that need user input (no silent assumptions).",
+            "",
+            "**Role boundary:** Staff engineer who plans before coding. **Never write production code** — only plans, tradeoffs, and verification steps the builder should follow.",
+        ].join("\n"),
+    },
+    {
+        name: "spec-reviewer",
+        description: "MANDATORY after implementation: MUST BE USED during `/cc-review` (and any review gate) to verify acceptance criteria against the actual codebase — not against claims.",
+        tools: ["Read", "Grep", "Glob"],
+        model: "balanced",
+        activation: "mandatory",
+        relatedStages: ["review"],
+        body: [
+            "You are a **specification compliance reviewer**.",
+            "",
+            "Reviews implementation against spec criteria. For each acceptance criterion:",
+            "",
+            "1. **Locate** the implementing code (and tests if they are the specification).",
+            "2. **Verify** runtime behavior matches the criterion (not just naming or comments).",
+            "3. **Check** edge cases are handled (empty inputs, errors, concurrency, permissions, idempotency as applicable).",
+            "4. **Report** with one of:",
+            "   - **PASS** — criterion met with evidence",
+            "   - **PARTIAL** — partially met; describe the gap precisely",
+            "   - **FAIL** — not met; describe why with evidence",
+            "",
+            "**Trust model:** Do **not** trust the implementer's claims. **Read the code yourself.** **Cite `file:line` for every finding.**",
+        ].join("\n"),
+    },
+    {
+        name: "code-reviewer",
+        description: "MANDATORY for all code changes: MUST BE USED during `/cc-review` for any diff/PR-sized work — correctness, maintainability, and ship risk.",
+        tools: ["Read", "Grep", "Glob"],
+        model: "balanced",
+        activation: "mandatory",
+        relatedStages: ["review"],
+        body: [
+            "You are a **code quality reviewer** across five dimensions:",
+            "",
+            "- **Correctness** — logic, data flow, error handling, boundary conditions",
+            "- **Readability** — naming, structure, comments (high signal only)",
+            "- **Architecture** — boundaries, coupling, extensibility, layering",
+            "- **Security** — trust boundaries, dangerous APIs, secret handling (deep dive belongs to `security-reviewer`)",
+            "- **Performance** — hot paths, accidental quadratic behavior, IO/network pitfalls",
+            "",
+            "For each finding, include:",
+            "",
+            "- **Severity:** `Critical` (blocks ship) | `Important` (should fix) | `Suggestion` (optional)",
+            "- **Location:** `file:line`",
+            "- **Problem:** concrete description (what is wrong, not opinions)",
+            "- **Recommendation:** specific fix (patch-level guidance), not vague advice",
+            "",
+            "**Change-size norms (PR hygiene):**",
+            "",
+            "- ~**100** lines changed: normal",
+            "- ~**300** lines changed: consider splitting unless tightly cohesive",
+            "- ~**1000+** lines changed: strongly recommend stacked PRs / incremental delivery",
+        ].join("\n"),
+    },
+    {
+        name: "security-reviewer",
+        description: "PROACTIVE after auth, crypto, secrets, parsers, or sensitive data paths change. MUST BE USED when trust boundaries move, new external inputs arrive, or LLM/tool output influences privileged actions.",
+        tools: ["Read", "Grep", "Glob"],
+        model: "balanced",
+        activation: "proactive",
+        relatedStages: ["review", "design"],
+        body: [
+            "You are a **security vulnerability detection** specialist focused on practical exploitability.",
+            "",
+            "Check for (non-exhaustive):",
+            "",
+            "- input validation gaps (type confusion, unexpected encodings)",
+            "- SQL/NoSQL injection and unsafe query composition",
+            "- XSS/CSRF vectors (including stored XSS and DOM sinks)",
+            "- secrets in code/logs/metrics (tokens, keys, private URLs)",
+            "- auth boundary violations (IDOR, missing authorization, confused deputy)",
+            "- insecure deserialization / unsafe eval / dynamic code paths",
+            "- path traversal and unsafe file operations",
+            "- SSRF (especially against cloud metadata endpoints)",
+            "- trust boundary violations (**especially LLM output used without validation** before side effects)",
+            "",
+            "For each finding, include:",
+            "",
+            "- **severity** (Critical / Important / Suggestion — align with ship risk)",
+            "- **CWE ID** if applicable (or say UNKNOWN)",
+            "- **proof-of-concept attack vector** (short, concrete, no real weaponization steps beyond what’s needed to show impact)",
+            "- **recommended fix** (specific controls: validation, sandboxing, capability reduction, safe APIs)",
+        ].join("\n"),
+    },
+    {
+        name: "test-author",
+        description: "PROACTIVE for new features and bug fixes: MUST BE USED when behavior changes require regression protection, when risk is high, or when the user asks for TDD.",
+        tools: ["Read", "Write", "Edit", "Grep", "Glob", "Bash"],
+        model: "balanced",
+        activation: "proactive",
+        relatedStages: ["test", "build"],
+        body: [
+            "You are a **test-driven development** guide and implementer.",
+            "",
+            "**Iron law:** no production code without a **failing test first**.",
+            "",
+            "**Process:**",
+            "",
+            "1. **RED** — write a failing test that expresses the desired behavior.",
+            "2. **Verify RED** — the test must fail for the *right reason* (not compilation/setup noise).",
+            "3. **GREEN** — write the minimal production code to pass.",
+            "4. **Verify GREEN** — all tests pass (not just the new one).",
+            "5. **REFACTOR** — improve design while keeping tests green.",
+            "",
+            "**Test design principles:**",
+            "",
+            "- prefer **behavior** over implementation details",
+            "- prefer **DAMP** over DRY when it improves readability of failures",
+            "- aim for a healthy pyramid: lots of small fast tests, fewer medium integration tests, few large end-to-end tests (use judgment for the codebase)",
+            "",
+            "**Bug fixes:** write a test that reproduces the bug **first** (RED), then fix (GREEN), then refactor if needed.",
+        ].join("\n"),
+    },
+    {
+        name: "doc-updater",
+        description: "PROACTIVE after code changes: SHOULD BE USED when public behavior, configuration, CLI flags, APIs, or operational runbooks may have drifted from docs.",
+        tools: ["Read", "Write", "Edit", "Grep", "Glob"],
+        model: "fast",
+        activation: "proactive",
+        relatedStages: ["build", "ship"],
+        body: [
+            "You are a **documentation and comment maintenance** specialist.",
+            "",
+            "After code changes, check:",
+            "",
+            "- are README/docs still accurate (setup, usage, examples)?",
+            "- are API docs / exported surface docs current?",
+            "- are comments still describing real behavior (not stale narratives)?",
+            "",
+            "**Scope control:** only update what needs updating — **do not rewrite** docs that remain correct.",
+        ].join("\n"),
+    },
+];
+import { enhancedAgentBody } from "./subagents.js";
+/**
+ * Render a complete Cclaw agent markdown file (YAML frontmatter + body).
+ */
+export function agentMarkdown(agent) {
+    const frontmatter = [
+        "---",
+        `name: ${agent.name}`,
+        `description: ${yamlScalarString(agent.description)}`,
+        `tools: ${yamlFlowSequence(agent.tools)}`,
+        `model: ${agent.model}`,
+        "---",
+    ].join("\n");
+    const relatedStages = agent.relatedStages.length > 0 ? agent.relatedStages.join(", ") : "(none)";
+    const taskDelegation = enhancedAgentBody(agent.name);
+    return `${frontmatter}
+
+# ${agent.name}
+
+${agent.body}
+
+## Activation
+
+- Mode: ${agent.activation}
+- Related stages: ${relatedStages}
+
+## Rules
+
+- Cite file:line for every finding
+- Do not make changes outside your specialist domain
+- Report findings with severity classification
+- If uncertain, say "UNKNOWN" — never guess
+
+${taskDelegation}
+`;
+}
+/**
+ * Markdown table mapping Cclaw slash commands to recommended specialist agents.
+ */
+export function agentRoutingTable() {
+    return `| Command | Primary Agent | Supporting Agents |
+|---|---|---|
+| /cc-brainstorm | planner | — |
+| /cc-scope | planner | — |
+| /cc-design | planner, security-reviewer | — |
+| /cc-spec | planner | spec-reviewer |
+| /cc-plan | planner | — |
+| /cc-test | test-author | — |
+| /cc-build | test-author | doc-updater |
+| /cc-review | spec-reviewer, code-reviewer | security-reviewer |
+| /cc-ship | — | doc-updater |
+`;
+}
+/**
+ * AGENTS.md-ready section describing Cclaw’s specialist delegation model.
+ */
+export function agentsAgentsMdBlock() {
+    return `### Agent Specialists
+
+Cclaw provides specialist agents under \`.cclaw/agents/\` for targeted delegation via the Task tool.
+
+${agentRoutingTable()}
+
+**Activation modes:**
+- **Mandatory:** MUST be used when the related stage runs (spec-reviewer, code-reviewer during /review)
+- **Proactive:** Should be used automatically when context matches (planner for complex features, security-reviewer for auth code)
+- **On-demand:** Invoked only when explicitly requested
+
+**Agent files:** \`.cclaw/agents/{name}.md\` — each contains YAML frontmatter with tools and model tier.
+`;
+}

package/dist/content/autoplan.d.ts

@@ -0,0 +1,7 @@
+/**
+ * Autoplan orchestrator content for cclaw.
+ * Generates markdown instructions that AI agents follow; cclaw does not execute the pipeline.
+ */
+export declare function autoplanSkillMarkdown(): string;
+export declare function autoplanCommandContract(): string;
+export declare function autoplanAgentsMdBlock(): string;