cclaw-cli 0.11.0 → 0.13.0

package/dist/content/core-agents.js

@@ -0,0 +1,225 @@
+/**
+ * Agent persona content for cclaw.
+ *
+ * cclaw materializes markdown agent definitions (`.md` with YAML frontmatter)
+ * under `.cclaw/agents/` for harness delegation. Research work that does not
+ * need isolated subagent context lives in `.cclaw/skills/research/*.md`
+ * playbooks and is executed in-thread by the primary agent.
+ */
+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 roster (core-5) materialized under `.cclaw/agents/`.
+ */
+export const CCLAW_AGENTS = [
+    {
+        name: "planner",
+        description: "MANDATORY for scope/design/plan and PROACTIVE for high-ambiguity work. MUST BE USED when sequencing, dependency mapping, or risk trade-offs are required before coding.",
+        tools: ["Read", "Grep", "Glob", "WebSearch"],
+        model: "deep",
+        activation: "mandatory",
+        relatedStages: ["brainstorm", "scope", "design", "spec", "plan"],
+        body: [
+            "You are an **implementation planning specialist** (staff engineer mindset).",
+            "",
+            "When invoked:",
+            "1. Analyze scope and break it into concrete sub-problems.",
+            "2. Map each sub-problem to existing modules and reusable code.",
+            "3. Produce an ordered execution plan with dependencies and checks.",
+            "4. Highlight risks and unknowns that need user decisions.",
+            "",
+            "**Role boundary:** planning only. Do NOT write production code."
+        ].join("\n")
+    },
+    {
+        name: "reviewer",
+        description: "MANDATORY during review. MUST BE USED to run a two-pass audit: spec compliance first, then correctness/maintainability/performance/architecture.",
+        tools: ["Read", "Grep", "Glob"],
+        model: "balanced",
+        activation: "mandatory",
+        relatedStages: ["spec", "review", "ship"],
+        body: [
+            "You are a **combined spec + code reviewer**.",
+            "",
+            "Run two explicit passes:",
+            "",
+            "1. **Spec pass**",
+            "   - For each acceptance criterion: PASS / PARTIAL / FAIL.",
+            "   - Cite evidence as `file:line`.",
+            "",
+            "2. **Code-quality pass**",
+            "   - Correctness: logic, boundaries, state transitions.",
+            "   - Maintainability: naming, structure, complexity, debt risks.",
+            "   - Performance: avoid obvious hot-path regressions.",
+            "   - Architecture fit: layering and contract stability.",
+            "",
+            "For each finding include:",
+            "- Severity: `Critical` | `Important` | `Suggestion`",
+            "- Location: `file:line`",
+            "- Problem and concrete recommendation",
+            "",
+            "**Trust model:** never rely on implementer claims; verify by reading code."
+        ].join("\n")
+    },
+    {
+        name: "security-reviewer",
+        description: "MANDATORY during review; PROACTIVE during design/ship for trust-boundary changes. Always produce an explicit no-change attestation when no security-relevant surface moved.",
+        tools: ["Read", "Grep", "Glob"],
+        model: "balanced",
+        activation: "mandatory",
+        relatedStages: ["design", "review", "ship"],
+        body: [
+            "You are a **security vulnerability specialist** focused on exploitability.",
+            "",
+            "Check for (non-exhaustive):",
+            "- validation gaps and injection vectors",
+            "- authz/authn boundary violations",
+            "- secret leakage in code/logging",
+            "- unsafe file/system/network operations",
+            "- privilege escalation and trust-boundary misuse",
+            "",
+            "For each finding include:",
+            "- severity aligned to ship risk",
+            "- CWE ID when possible (or UNKNOWN)",
+            "- short proof-of-concept vector",
+            "- concrete control-oriented fix"
+        ].join("\n")
+    },
+    {
+        name: "test-author",
+        description: "MANDATORY in TDD stage. MUST BE USED for RED -> GREEN -> REFACTOR with evidence-first discipline.",
+        tools: ["Read", "Write", "Edit", "Grep", "Glob", "Bash"],
+        model: "balanced",
+        activation: "mandatory",
+        relatedStages: ["tdd"],
+        body: [
+            "You are a **test-driven development** specialist.",
+            "",
+            "**Iron law:** no production code without a failing test first.",
+            "",
+            "Process:",
+            "1. RED: write a failing test for the desired behavior.",
+            "2. Verify RED fails for the right reason.",
+            "3. GREEN: implement minimal code to pass.",
+            "4. Verify GREEN on relevant suite/full suite.",
+            "5. REFACTOR with behavior preserved."
+        ].join("\n")
+    },
+    {
+        name: "doc-updater",
+        description: "MANDATORY at ship and PROACTIVE when behavior/config/public API changes. Keep docs and runbooks in lockstep with shipped behavior.",
+        tools: ["Read", "Write", "Edit", "Grep", "Glob"],
+        model: "fast",
+        activation: "mandatory",
+        relatedStages: ["tdd", "ship"],
+        body: [
+            "You are a **documentation maintenance specialist**.",
+            "",
+            "After code changes, verify and update only stale sections in:",
+            "- README / setup / usage",
+            "- API docs and examples",
+            "- migration and operational notes",
+            "",
+            "Preserve existing tone and structure; avoid rewrites for style alone."
+        ].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 stage entry points to specialist agents.
+ */
+export function agentRoutingTable() {
+    return `| Stage Entry | Primary Agent(s) | Supporting guidance |
+|---|---|---|
+| Brainstorm (start with \`/cc <idea>\`) | planner | Run in-thread research playbooks: \`research/repo-scan.md\`, \`research/learnings-lookup.md\` |
+| Scope / Design / Plan (via \`/cc-next\`) | planner | Use \`research/git-history.md\` (scope) and \`research/framework-docs-lookup.md\` + \`research/best-practices-lookup.md\` (design) as needed |
+| Spec (via \`/cc-next\`) | reviewer | planner (if ambiguity or conflicts remain) |
+| TDD (via \`/cc-next\`) | test-author | doc-updater on public behavior/config changes |
+| Review (via \`/cc-next\`) | reviewer, security-reviewer | conditional second reviewer for high blast-radius diffs |
+| Ship (via \`/cc-next\`) | doc-updater | security-reviewer when release risk is elevated |
+`;
+}
+/**
+ * Cost tier routing for the core-5 agent roster.
+ */
+export function agentCostTierTable() {
+    return `| Tier | Use for | Example agents |
+|---|---|---|
+| \`deep\` | one heavy planning pass per stage | planner |
+| \`balanced\` | review and TDD specialists with stronger reasoning depth | reviewer, security-reviewer, test-author |
+| \`fast\` | bounded maintenance updates with limited blast radius | doc-updater |
+`;
+}
+/**
+ * AGENTS.md-ready section describing cclaw’s specialist delegation model.
+ */
+export function agentsAgentsMdBlock() {
+    return `### Agent Specialists
+
+cclaw materializes **5 core specialist agents** under \`.cclaw/agents/\`.
+
+${agentRoutingTable()}
+
+### Research Playbooks (in-thread)
+
+Research work is no longer modeled as standalone personas. Use in-thread playbooks under \`.cclaw/skills/research/\`:
+
+- \`repo-scan.md\`
+- \`learnings-lookup.md\`
+- \`framework-docs-lookup.md\`
+- \`best-practices-lookup.md\`
+- \`git-history.md\`
+
+### Activation modes
+
+- **Mandatory:** planner (scope/design/plan), reviewer + security-reviewer (review), test-author (tdd), doc-updater (ship).
+- **Proactive:** planner on ambiguity, security-reviewer on trust-boundary movement outside review, doc-updater on behavior/config drift.
+- **On-demand:** none in the core-5 roster; research playbooks are in-thread procedures.
+
+### Cost-aware routing
+
+${agentCostTierTable()}
+
+**Agent files:** \`.cclaw/agents/{name}.md\` — each contains YAML frontmatter with tools and model tier.
+`;
+}

package/dist/content/diff-command.d.ts

@@ -0,0 +1,2 @@
+export declare function diffCommandContract(): string;
+export declare function diffCommandSkillMarkdown(): string;

package/dist/content/diff-command.js

@@ -0,0 +1,83 @@
+import { RUNTIME_ROOT } from "../constants.js";
+const DIFF_SKILL_FOLDER = "flow-diff";
+const DIFF_SKILL_NAME = "flow-diff";
+function flowStatePath() {
+    return `${RUNTIME_ROOT}/state/flow-state.json`;
+}
+function snapshotPath() {
+    return `${RUNTIME_ROOT}/state/flow-state.snapshot.json`;
+}
+export function diffCommandContract() {
+    return `# /cc-diff
+
+## Purpose
+
+Show a visual before/after diff map for flow-state progression.
+
+## HARD-GATE
+
+- Compare against \`${snapshotPath()}\` first; do not overwrite baseline before rendering.
+- If no snapshot exists, initialize baseline and report "baseline created" explicitly.
+
+## Algorithm
+
+1. Read current state from \`${flowStatePath()}\`.
+2. Read baseline from \`${snapshotPath()}\` (if missing -> create baseline from current state and stop).
+3. Compute deltas:
+   - stage transition (\`from -> to\`)
+   - completed stage additions/removals
+   - skipped stage additions/removals
+   - stale stage additions/removals
+   - current-stage gate \`passed\` and \`blocked\` changes
+4. Render a compact diff map (added \`+\`, removed \`-\`, changed \`->\`).
+5. Persist current state back to \`${snapshotPath()}\` as new baseline with \`capturedAt\`.
+
+## Diff Map Format
+
+\`\`\`
+cclaw flow diff
+  stage: design -> spec
+  completed: +design
+  stale: -design
+  gates(spec): +spec_contract_complete  -spec_open_questions_closed
+  blocked(spec): +spec_trace_matrix_missing
+\`\`\`
+
+## Primary skill
+
+**${RUNTIME_ROOT}/skills/${DIFF_SKILL_FOLDER}/SKILL.md**
+`;
+}
+export function diffCommandSkillMarkdown() {
+    return `---
+name: ${DIFF_SKILL_NAME}
+description: "Compare current flow-state against saved snapshot and render gate/stage deltas."
+---
+
+# /cc-diff
+
+## HARD-GATE
+
+Never lose baseline visibility: render deltas before writing a new snapshot.
+
+## Protocol
+
+1. Read \`${flowStatePath()}\`.
+2. Read \`${snapshotPath()}\`.
+3. If snapshot missing:
+   - write baseline snapshot from current state,
+   - print \`flow diff baseline created\`,
+   - stop.
+4. Build deltas for stage, completed/skipped/stale sets, and current-stage gate arrays.
+5. Print a compact diff map with explicit \`+\`, \`-\`, and \`->\` markers.
+6. Write updated snapshot with:
+   - \`capturedAt\` (ISO)
+   - \`state\` (full current flow-state object)
+
+## Validation
+
+- Diff output must be deterministic for identical states ("no changes").
+- Snapshot file stays valid JSON after every run.
+- Do not suppress removed values; removals are first-class evidence.
+`;
+}

package/dist/content/doctor-references.d.ts

@@ -0,0 +1,2 @@
+export declare const DOCTOR_REFERENCE_DIR = ".cclaw/references/doctor";
+export declare const DOCTOR_REFERENCE_MARKDOWN: Record<string, string>;

package/dist/content/doctor-references.js

@@ -0,0 +1,144 @@
+import { RUNTIME_ROOT } from "../constants.js";
+export const DOCTOR_REFERENCE_DIR = `${RUNTIME_ROOT}/references/doctor`;
+export const DOCTOR_REFERENCE_MARKDOWN = {
+    "README.md": `# Doctor Reference Index
+
+Reference docs for \`cclaw doctor\` checks.
+
+## Categories
+
+- \`runtime-layout.md\` - runtime directories, generated commands, and skill files
+- \`hooks-and-lifecycle.md\` - hook wiring and harness lifecycle integration
+- \`harness-and-routing.md\` - harness shims, AGENTS/CLAUDE routing blocks, cursor rule
+- \`state-and-gates.md\` - flow-state integrity and gate evidence contracts
+- \`delegation-and-preamble.md\` - mandatory delegations and preamble budget controls
+- \`traceability.md\` - spec/plan/tdd trace matrix expectations
+- \`tooling-capabilities.md\` - local runtime prerequisites (bash/node/python/jq)
+- \`config-and-policy.md\` - config schema, rules policy, and validation references
+`,
+    "runtime-layout.md": `# Runtime Layout
+
+## Expected surfaces
+
+- \`.cclaw/\` root and generated subdirectories
+- stage command contracts under \`.cclaw/commands/\`
+- stage skills under \`.cclaw/skills/\`
+- utility command contracts (\`start\`, \`next\`, \`learn\`, \`status\`)
+- state files under \`.cclaw/state/\`
+
+## Typical fixes
+
+1. Run \`cclaw sync\` to re-materialize generated assets.
+2. If runtime is severely drifted, run \`cclaw upgrade\`.
+3. Avoid manual edits under generated runtime paths unless explicitly supported.
+`,
+    "hooks-and-lifecycle.md": `# Hooks And Lifecycle
+
+## Expected behavior
+
+- session start rehydrates flow + knowledge digest
+- pre-tool hooks run prompt/workflow guards
+- post-tool hooks run context monitor
+- stop hooks checkpoint progress
+- OpenCode uses plugin-based lifecycle integration
+
+## Typical fixes
+
+1. Re-run \`cclaw sync\` after harness config changes.
+2. Ensure harness is enabled in \`.cclaw/config.yaml\`.
+3. Validate hook JSON shape and remove malformed manual edits.
+`,
+    "harness-and-routing.md": `# Harness And Routing
+
+## Expected behavior
+
+- command shims exist for every enabled harness
+- managed routing block is present in \`AGENTS.md\` (and \`CLAUDE.md\` when applicable)
+- cursor rule mirrors workflow activation guidance
+- opencode plugin path is registered in opencode config
+
+## Typical fixes
+
+1. Confirm \`harnesses\` list in \`.cclaw/config.yaml\`.
+2. Run \`cclaw sync\` to re-generate shims/routing files.
+3. Remove stale harness artifacts for disabled harnesses via \`cclaw sync\`.
+`,
+    "state-and-gates.md": `# State And Gates
+
+## Expected behavior
+
+- \`flow-state.json\` has activeRunId, current stage, and consistent track/skippedStages
+- current-stage gate evidence is internally consistent
+- completed stages only include passed required gates
+
+## Typical fixes
+
+1. Run \`cclaw doctor --reconcile-gates\` to refresh current-stage gate catalog.
+2. Repair inconsistent stage artifacts, then re-run doctor.
+3. Do not manually mutate gate arrays without matching artifact evidence.
+`,
+    "delegation-and-preamble.md": `# Delegation And Preamble
+
+## Delegation contract
+
+- mandatory delegations for the current stage must be completed or waived
+- waivers should include an explicit reason
+- stale entries from previous runs are ignored by current-run checks
+
+## Preamble budget contract
+
+- preamble events are logged to \`.cclaw/state/preamble-log.jsonl\`
+- repeated entries inside cooldown windows indicate noisy preamble behavior
+- in TDD wave mode, emit once per wave unless plan materially changes
+
+## Typical fixes
+
+1. Append missing delegation records with \`completed\` or \`waived\` status.
+2. Record harness-limitation waivers when native delegation is unavailable.
+3. Reduce repeated preamble emissions and keep logs structured (\`ts/stage/trigger/hash\`).
+`,
+    "traceability.md": `# Traceability
+
+## Expected behavior
+
+- spec criteria map to plan tasks
+- plan tasks map to tdd slices/tests
+- no orphaned criteria/tasks/tests when downstream artifacts exist
+
+## Typical fixes
+
+1. Add stable IDs to spec/plan/tdd sections.
+2. Ensure mapping tables include every active criterion/task/slice.
+3. Re-run \`cclaw doctor\` after artifact updates.
+`,
+    "tooling-capabilities.md": `# Tooling Capabilities
+
+## Required
+
+- \`bash\` for runtime hook scripts
+- \`node\` for generated runtime scripts/plugins
+
+## Optional fallback
+
+- at least one of \`python3\` or \`jq\` for JSON parsing fallback paths
+
+## Typical fixes
+
+1. Install missing runtime tools.
+2. Keep at least one JSON fallback parser available (\`python3\` or \`jq\`).
+`,
+    "config-and-policy.md": `# Config And Policy
+
+## Expected behavior
+
+- \`.cclaw/config.yaml\` parses and uses supported keys/values
+- \`.cclaw/rules/rules.json\` matches generated policy schema
+- policy needles and required sections remain present in generated contracts
+
+## Typical fixes
+
+1. Repair invalid config values and run \`cclaw sync\`.
+2. Re-generate policy files via \`cclaw sync\` if drift is detected.
+3. Keep generated contracts aligned with stage schemas and policy needles.
+`
+};

package/dist/content/examples.js

@@ -379,7 +379,7 @@ Execution rule: complete and verify each wave before starting the next wave.
 ## Review Army Contract
 
 - See \`07-review-army.json\`
-- Reconciliation summary: 1 duplicate collapsed (R-1 reported by spec-reviewer and code-reviewer), 0 conflicts
+- Reconciliation summary: 1 duplicate collapsed (R-1 reported by reviewer and security-reviewer), 0 conflicts
 
 ## Review Readiness Dashboard
 

package/dist/content/feature-command.d.ts

@@ -0,0 +1,2 @@
+export declare function featureCommandContract(): string;
+export declare function featureCommandSkillMarkdown(): string;

package/dist/content/feature-command.js

@@ -0,0 +1,120 @@
+import { RUNTIME_ROOT } from "../constants.js";
+const FEATURE_SKILL_FOLDER = "feature-workspaces";
+const FEATURE_SKILL_NAME = "feature-workspaces";
+function activeFeaturePath() {
+    return `${RUNTIME_ROOT}/state/active-feature.json`;
+}
+function featuresRoot() {
+    return `${RUNTIME_ROOT}/features`;
+}
+function runtimeArtifactsPath() {
+    return `${RUNTIME_ROOT}/artifacts`;
+}
+function runtimeStatePath() {
+    return `${RUNTIME_ROOT}/state`;
+}
+export function featureCommandContract() {
+    return `# /cc-feature
+
+## Purpose
+
+Manage multi-feature workspaces without flow-state/artifact collisions.
+
+The active runtime remains:
+- \`${runtimeArtifactsPath()}\` (active artifacts)
+- \`${runtimeStatePath()}\` (active state)
+
+Feature snapshots live under \`${featuresRoot()}/<feature-id>/\`.
+
+## HARD-GATE
+
+- Never overwrite another feature snapshot silently.
+- Before switching feature, snapshot the current active runtime first.
+- Keep \`${activeFeaturePath()}\` as the single source of "current feature".
+
+## Subcommands
+
+### \`/cc-feature status\`
+Show active feature id and snapshot location.
+
+### \`/cc-feature list\`
+List all feature ids in \`${featuresRoot()}/\` (directory names).
+
+### \`/cc-feature new <feature-id>\`
+Create \`${featuresRoot()}/<feature-id>/artifacts\` and \`${featuresRoot()}/<feature-id>/state\`.
+
+Optional flag:
+- \`--clone-active\`: clone current active runtime into the new feature snapshot.
+
+### \`/cc-feature switch <feature-id>\`
+1. Snapshot current active runtime into \`${featuresRoot()}/<active>/\`.
+2. Restore target snapshot from \`${featuresRoot()}/<feature-id>/\` into active runtime:
+   - \`${runtimeArtifactsPath()}\`
+   - \`${runtimeStatePath()}\` (preserve \`active-feature.json\`)
+3. Update \`${activeFeaturePath()}\` with \`activeFeature=<feature-id>\`.
+
+If the target snapshot is empty, initialize runtime as a fresh flow.
+
+## Output
+
+Always print:
+- active feature before
+- active feature after
+- whether snapshot/restore changed files
+
+## Primary skill
+
+**${RUNTIME_ROOT}/skills/${FEATURE_SKILL_FOLDER}/SKILL.md**
+`;
+}
+export function featureCommandSkillMarkdown() {
+    return `---
+name: ${FEATURE_SKILL_NAME}
+description: "Manage cclaw multi-feature workspaces (status/list/new/switch) while preserving active flow runtime."
+---
+
+# /cc-feature — Feature Workspace Manager
+
+## HARD-GATE
+
+Do not switch feature by editing only \`active-feature.json\`. A valid switch must snapshot current runtime and restore target runtime.
+
+## Paths
+
+- Active pointer: \`${activeFeaturePath()}\`
+- Feature snapshots: \`${featuresRoot()}/<feature-id>/\`
+- Active runtime artifacts: \`${runtimeArtifactsPath()}\`
+- Active runtime state: \`${runtimeStatePath()}\`
+
+## Protocol
+
+### status
+1. Read \`${activeFeaturePath()}\`.
+2. Print active feature id and its snapshot folder.
+
+### list
+1. Enumerate directories in \`${featuresRoot()}/\`.
+2. Mark the active one.
+
+### new <feature-id> [--clone-active]
+1. Validate \`feature-id\` (lowercase slug, letters/numbers/dashes).
+2. Create snapshot dirs:
+   - \`${featuresRoot()}/<feature-id>/artifacts\`
+   - \`${featuresRoot()}/<feature-id>/state\`
+3. If \`--clone-active\`: copy active runtime artifacts/state into the new snapshot.
+4. Do not change active feature unless the user explicitly requests switch.
+
+### switch <feature-id>
+1. Read current active feature id.
+2. Snapshot current runtime into current feature snapshot.
+3. Restore target snapshot into active runtime.
+4. Update \`${activeFeaturePath()}\`.
+5. Report stage/run after restore (\`flow-state.json\`).
+
+## Safety checks
+
+- If target feature does not exist: block and suggest \`/cc-feature new <id>\`.
+- If snapshot copy fails: abort switch, keep current active feature unchanged.
+- Preserve global pointer file \`active-feature.json\` when restoring state.
+`;
+}

package/dist/content/harnesses-doc.d.ts

@@ -0,0 +1 @@
+export declare function harnessIntegrationDocMarkdown(): string;