cclaw-cli 0.1.0

package/dist/content/session-hooks.d.ts

@@ -0,0 +1,7 @@
+/**
+ * Session guidelines content for Cclaw.
+ * Describes recommended behavior at session boundaries.
+ * Pure markdown generation — no runtime logic.
+ */
+export declare function sessionHooksSkillMarkdown(): string;
+export declare function sessionHooksAgentsMdBlock(): string;

package/dist/content/session-hooks.js

@@ -0,0 +1,137 @@
+/**
+ * Session guidelines content for Cclaw.
+ * Describes recommended behavior at session boundaries.
+ * Pure markdown generation — no runtime logic.
+ */
+export function sessionHooksSkillMarkdown() {
+    return `---
+name: session
+description: "Session boundary guidelines: what to do when a session starts, ends, or reaches a stop condition."
+---
+
+# Session Guidelines
+
+## Overview
+
+This skill defines recommended behavior at **session boundaries** — start, stop, and resume. These guidelines help agents maintain continuity, avoid losing context, and enforce quality gates at natural breakpoints.
+
+These are prompt-discipline guidelines that complement the real hooks cclaw generates. The hooks handle automatic context injection at session start/stop; these guidelines cover manual steps the agent should follow.
+
+## HARD-GATE
+
+**Never end a session with uncommitted or untested changes.** If you must stop, create a checkpoint first.
+
+## Session Start Protocol
+
+When a new session begins in any harness:
+
+1. **Read flow state:** Load \`.cclaw/state/flow-state.json\` to find the current stage and completed stages.
+2. **Load learnings:** Run \`tail -n 20 .cclaw/learnings.jsonl 2>/dev/null\` and surface the top 3 highest-confidence entries (see learnings skill for dedup/decay).
+3. **Check for in-progress work:** If the last stage is incomplete, remind the user and offer to resume.
+4. **Load suggestion memory:** Read \`.cclaw/state/suggestion-memory.json\` and honor \`enabled=false\` opt-out.
+5. **Read AGENTS.md:** The cclaw block contains routing and rules — follow them.
+
+### What to show the user at session start
+
+\`\`\`
+Cclaw flow state: [current stage] ([N] of 9 stages completed)
+Top learnings: [key1] (confidence N), [key2] (confidence N), [key3] (confidence N)
+Next action: /cc-[stage] to continue, or describe what you'd like to do.
+\`\`\`
+
+## Session Stop Protocol
+
+Before ending a session or when context is full:
+
+1. **Verify no pending changes:** All modified files must be either committed or explicitly reverted.
+2. **Update flow state:** Mark the current stage as its actual status (DONE / DONE_WITH_CONCERNS / BLOCKED).
+3. **Write learnings:** If any insight from this session would save 5+ minutes next time, append to \`.cclaw/learnings.jsonl\`.
+4. **Create checkpoint:** Write a brief status note to the current artifact or as a comment in flow-state.json.
+
+### Stop conditions (agent must halt and report)
+
+- Repeated verification failure (3+ attempts at the same check)
+- Unclear requirements that block progress
+- Security concern discovered that needs human review
+- Context window approaching limit — compact or hand off
+
+## Session Resume Protocol
+
+When resuming work after a break:
+
+1. Re-read \`.cclaw/state/flow-state.json\` (may have changed externally).
+2. Re-read the current stage's artifact to verify it matches your last checkpoint.
+3. Re-load top learnings.
+4. Continue from the last incomplete step — do not restart the stage.
+
+## Proactive Suggestion Memory
+
+Cclaw can emit short stage-specific reminders at session start to reduce misses.
+
+- State file: \`.cclaw/state/suggestion-memory.json\`
+- Default: \`enabled: true\`
+- Persistent opt-out: set \`enabled: false\` and keep the file in repo-local state
+- Optional per-stage mute: add stage names to \`mutedStages\`
+
+Example:
+
+\`\`\`json
+{
+  "enabled": false,
+  "mutedStages": ["plan"],
+  "lastSuggestedStage": "review",
+  "lastSuggestedAt": "2026-04-11T14:30:00Z"
+}
+\`\`\`
+
+## Checkpoint Format
+
+When creating a checkpoint at session boundaries:
+
+\`\`\`json
+{
+  "stage": "build",
+  "status": "in_progress",
+  "lastCompletedStep": "GREEN for task T2",
+  "remainingSteps": ["REFACTOR T2", "RED T3", "GREEN T3", "REFACTOR T3"],
+  "blockers": [],
+  "timestamp": "2026-04-11T14:30:00Z"
+}
+\`\`\`
+
+## Context Management
+
+When approaching context limits:
+
+1. **Prefer subagents** for deep investigation (results return as summary, not full context).
+2. **Compact strategically** — at logical breakpoints (after a stage completes), not mid-task.
+3. **Never compact during:** active debugging, mid-refactor, or while holding uncommitted changes.
+4. **After compaction:** re-read flow state and current artifact before continuing.
+
+## Common Rationalizations
+
+| Rationalization | Reality |
+|---|---|
+| "I'll remember where I was" | Context is lost between sessions. Write it down. |
+| "This is almost done, no need for checkpoint" | "Almost done" is the most dangerous state — changes are half-applied. |
+| "The tests will tell me the state" | Tests tell you pass/fail, not intent or remaining work. |
+
+## Red Flags
+
+- Ending a session with modified but uncommitted files
+- No flow state update after completing work
+- Restarting a stage from scratch instead of resuming from checkpoint
+- Ignoring learnings from prior sessions
+`;
+}
+export function sessionHooksAgentsMdBlock() {
+    return `### Session Guidelines
+
+Session boundary behavior (real hooks inject context automatically; guidelines cover manual steps):
+- **Start:** Hooks inject flow state + top learnings. Check for in-progress work, show status.
+- **Stop:** Hooks remind about checkpoint. Verify no pending changes, update flow state, write learnings.
+- **Resume:** Re-read state, verify artifact, re-load learnings, continue from last step.
+
+Skill: \`.cclaw/skills/session/SKILL.md\`
+`;
+}

package/dist/content/skills.d.ts

@@ -0,0 +1,3 @@
+import type { FlowStage } from "../types.js";
+export declare function stageSkillFolder(stage: FlowStage): string;
+export declare function stageSkillMarkdown(stage: FlowStage): string;

package/dist/content/skills.js

@@ -0,0 +1,257 @@
+import { stageExamples } from "./examples.js";
+import { selfImprovementBlock } from "./learnings.js";
+import { nextCclawCommand, stageAutoSubagentDispatch, stageSchema } from "./stage-schema.js";
+function artifactFileName(artifactPath) {
+    const parts = artifactPath.split("/");
+    return parts[parts.length - 1] ?? artifactPath;
+}
+function rationalizationTable(stage) {
+    const schema = stageSchema(stage);
+    return `| Rationalization | Reality |
+|---|---|
+${schema.rationalizations.map((e) => `| ${e.claim} | ${e.reality} |`).join("\n")}`;
+}
+function cognitivePatternsList(stage) {
+    const schema = stageSchema(stage);
+    if (schema.cognitivePatterns.length === 0)
+        return "";
+    const items = schema.cognitivePatterns
+        .map((p, i) => `${i + 1}. **${p.name}** — ${p.description}`)
+        .join("\n");
+    return `## Cognitive Patterns\n\nThese are thinking instincts, not a checklist. Let them shape your perspective throughout the stage.\n\n${items}\n`;
+}
+function reviewSectionsBlock(stage) {
+    const schema = stageSchema(stage);
+    if (schema.reviewSections.length === 0)
+        return "";
+    const sections = schema.reviewSections.map((sec) => {
+        const points = sec.evaluationPoints.map((p) => `- ${p}`).join("\n");
+        const stop = sec.stopGate
+            ? "\n\n**STOP.** For each issue found in this section, present it ONE AT A TIME. Describe the problem concretely, present 2-3 options, state your recommendation, and explain WHY. Only proceed to the next section after ALL issues in this section are resolved."
+            : "";
+        return `### ${sec.title}\n\nEvaluate:\n${points}${stop}`;
+    }).join("\n\n");
+    return `## Review Sections\n\n**Anti-skip rule:** Never condense, abbreviate, or skip any review section. If a section genuinely has zero findings, say "No issues found" and move on — but you must evaluate it.\n\n${sections}\n`;
+}
+function crossStageTraceBlock(stage) {
+    const trace = stageSchema(stage).crossStageTrace;
+    const reads = trace.readsFrom.length > 0
+        ? trace.readsFrom.map((r) => `- ${r}`).join("\n")
+        : "- (first stage — no upstream artifacts)";
+    const writes = trace.writesTo.length > 0
+        ? trace.writesTo.map((w) => `- ${w}`).join("\n")
+        : "- (final stage — no downstream artifacts)";
+    return `## Cross-Stage Traceability\n\n**Reads from:**\n${reads}\n\n**Writes to:**\n${writes}\n\n**Rule:** ${trace.traceabilityRule}\n`;
+}
+function artifactValidationBlock(stage) {
+    const validations = stageSchema(stage).artifactValidation;
+    if (validations.length === 0)
+        return "";
+    const rows = validations.map((v) => {
+        const req = v.required ? "REQUIRED" : "optional";
+        return `| ${v.section} | ${req} | ${v.validationRule} |`;
+    }).join("\n");
+    return `## Artifact Validation\n\n| Section | Status | Validation Rule |\n|---|---|---|\n${rows}\n`;
+}
+function completionStatusBlock(stage) {
+    const statuses = stageSchema(stage).completionStatus;
+    const items = statuses.map((s) => `- **${s}**`).join("\n");
+    return `## Completion Status\n\nWhen this stage ends, report one of:\n${items}\n`;
+}
+function namedAntiPatternBlock(stage) {
+    const nap = stageSchema(stage).namedAntiPattern;
+    if (!nap)
+        return "";
+    return `## Anti-Pattern: "${nap.title}"\n\n${nap.description}\n`;
+}
+function decisionRecordBlock(stage) {
+    const fmt = stageSchema(stage).decisionRecordFormat;
+    if (!fmt)
+        return "";
+    return `## Decision Record Template\n\nUse this format for every non-trivial architecture or scope decision made during this stage:\n\n\`\`\`\n${fmt}\n\`\`\`\n`;
+}
+function contextLoadingBlock(stage) {
+    const trace = stageSchema(stage).crossStageTrace;
+    const readLines = trace.readsFrom.length > 0
+        ? trace.readsFrom
+            .map((value) => {
+            const fileName = artifactFileName(value);
+            return `- Canonical: \`.cclaw/runs/<activeRunId>/artifacts/${fileName}\` (fallback: \`${value}\`)`;
+        })
+            .join("\n")
+        : "- (first stage — no upstream artifacts)";
+    return `## Context Loading
+
+Before starting stage execution:
+1. Read \`.cclaw/state/flow-state.json\` and capture \`activeRunId\`.
+2. Resolve canonical run artifact root: \`.cclaw/runs/<activeRunId>/artifacts/\`.
+3. Load upstream artifacts required by this stage:
+${readLines}
+4. If canonical run artifact is missing, fallback to the \`.cclaw/artifacts/\` mirror and record that fallback.
+`;
+}
+function autoSubagentDispatchBlock(stage) {
+    const rules = stageAutoSubagentDispatch(stage);
+    if (rules.length === 0)
+        return "";
+    const rows = rules
+        .map((rule) => {
+        const userGate = rule.requiresUserGate ? "required" : "not required";
+        return `| ${rule.agent} | ${rule.mode} | ${rule.when} | ${rule.purpose} | ${userGate} |`;
+    })
+        .join("\n");
+    return `## Automatic Subagent Dispatch
+
+Machine-only work should be delegated to specialist agents automatically according to the matrix below.
+
+| Agent | Mode | When | Purpose | User Gate |
+|---|---|---|---|---|
+${rows}
+
+**Gate rule:** user interaction is required only for approval/override decisions. Do not ask the user to manually trigger machine-only specialist checks.
+`;
+}
+const VERIFICATION_STAGES = ["build", "review", "ship"];
+function verificationBlock(stage) {
+    if (!VERIFICATION_STAGES.includes(stage))
+        return "";
+    return `## Verification Before Completion
+
+**Iron law:** Do not claim this stage is complete without fresh verification evidence from THIS message.
+
+### Gate Function
+For every completion claim, follow this sequence:
+1. **Identify** the verification command (test suite, build, lint, type-check).
+2. **Run** the full command — not a subset, not a cached result.
+3. **Read** the complete output — do not summarize without reading.
+4. **Verify** the output matches the expected success state.
+5. **Only then** make the completion claim with the evidence.
+
+### Evidence Requirements
+| Claim | Requires | NOT Sufficient |
+|---|---|---|
+| "Tests pass" | Fresh test run output showing all pass | "I believe tests pass" or prior run |
+| "Build succeeds" | Fresh build output with exit code 0 | "Should build fine" |
+| "No lint errors" | Fresh linter output | "I didn't introduce any" |
+| "Bug is fixed" | Regression test: remove fix → fails, restore → passes | "The fix looks correct" |
+
+### Forbidden Language
+Do not use these phrases before verification:
+- "Everything works," "All good," "Done," "Successfully completed"
+- "Should be fine," "I'm confident that," "This will work"
+- "Tests should pass," "The build should succeed"
+
+### Regression Test Pattern
+When fixing a bug:
+1. Write a test that reproduces the bug → verify it **fails**.
+2. Apply the fix → verify the test **passes**.
+3. Revert the fix → verify the test **fails again**.
+4. Restore the fix → verify the full suite passes.
+`;
+}
+export function stageSkillFolder(stage) {
+    return stageSchema(stage).skillFolder;
+}
+function quickStartBlock(stage) {
+    const schema = stageSchema(stage);
+    const nextCommand = nextCclawCommand(stage);
+    const topGates = schema.requiredGates.slice(0, 3).map((g) => `\`${g.id}\``).join(", ");
+    return `## Quick Start (minimum compliance)
+
+> **Even if you read nothing else, do these 3 things:**
+> 1. Obey the HARD-GATE below — violating it invalidates the entire stage.
+> 2. Complete every checklist step in order and write the artifact to \`.cclaw/artifacts/${schema.artifactFile}\` (canonical run copy: \`.cclaw/runs/<activeRunId>/artifacts/${schema.artifactFile}\`).
+> 3. Do not claim completion without satisfying gates: ${topGates}${schema.requiredGates.length > 3 ? ` (+${schema.requiredGates.length - 3} more)` : ""}.
+>
+> **Next command after this stage:** ${nextCommand}
+`;
+}
+export function stageSkillMarkdown(stage) {
+    const schema = stageSchema(stage);
+    const nextCommand = nextCclawCommand(stage);
+    const gateList = schema.requiredGates
+        .map((g) => `- \`${g.id}\` — ${g.description}`)
+        .join("\n");
+    const evidenceList = schema.requiredEvidence
+        .map((e) => `- [ ] ${e}`)
+        .join("\n");
+    const checklistItems = schema.checklist
+        .map((item, i) => `${i + 1}. ${item}`)
+        .join("\n");
+    return `---
+name: ${schema.skillName}
+description: "${schema.skillDescription}"
+---
+
+# ${schema.skillName}
+
+${quickStartBlock(stage)}
+## Overview
+${schema.purpose}
+
+## When to Use
+${schema.whenToUse.map((item) => `- ${item}`).join("\n")}
+
+## Inputs
+${schema.inputs.length > 0 ? schema.inputs.map((item) => `- ${item}`).join("\n") : "- (first stage — no required inputs)"}
+
+## Required Context
+${schema.requiredContext.length > 0 ? schema.requiredContext.map((item) => `- ${item}`).join("\n") : "- None beyond this skill"}
+
+${contextLoadingBlock(stage)}
+${autoSubagentDispatchBlock(stage)}
+## Outputs
+${schema.outputs.map((item) => `- ${item}`).join("\n")}
+
+## HARD-GATE
+${schema.hardGate}
+
+## Checklist
+
+You MUST complete these steps in order:
+
+${checklistItems}
+
+${stageExamples(stage)}
+${namedAntiPatternBlock(stage)}
+${cognitivePatternsList(stage)}
+## Interaction Protocol
+${schema.interactionProtocol.map((item, i) => `${i + 1}. ${item}`).join("\n")}
+
+## Required Gates
+${gateList}
+
+## Required Evidence
+${evidenceList}
+
+## Process
+${schema.process.map((item, i) => `${i + 1}. ${item}`).join("\n")}
+
+${reviewSectionsBlock(stage)}
+${verificationBlock(stage)}
+${crossStageTraceBlock(stage)}
+${artifactValidationBlock(stage)}
+${decisionRecordBlock(stage)}
+## Common Rationalizations
+${rationalizationTable(stage)}
+
+## Blockers
+${schema.blockers.length > 0 ? schema.blockers.map((item) => `- ${item}`).join("\n") : "- None — stage can always proceed"}
+
+## Anti-Patterns
+${schema.antiPatterns.map((item) => `- ${item}`).join("\n")}
+
+## Red Flags
+${schema.redFlags.map((item) => `- ${item}`).join("\n")}
+
+${completionStatusBlock(stage)}
+## Verification
+${schema.exitCriteria.map((item) => `- [ ] ${item}`).join("\n")}
+
+${selfImprovementBlock(stage)}
+## Handoff
+- Next command: ${nextCommand}
+- Required artifact: \`.cclaw/artifacts/${schema.artifactFile}\` (canonical: \`.cclaw/runs/<activeRunId>/artifacts/${schema.artifactFile}\`)
+- Stage stays blocked if any required gate is unsatisfied
+`;
+}

package/dist/content/stage-schema.d.ts

@@ -0,0 +1,78 @@
+import type { FlowStage, TransitionRule } from "../types.js";
+export interface StageGate {
+    id: string;
+    description: string;
+}
+export interface StageRationalization {
+    claim: string;
+    reality: string;
+}
+export interface CognitivePattern {
+    name: string;
+    description: string;
+}
+export interface ReviewSection {
+    title: string;
+    evaluationPoints: string[];
+    stopGate: boolean;
+}
+export interface CrossStageTrace {
+    readsFrom: string[];
+    writesTo: string[];
+    traceabilityRule: string;
+}
+export interface ArtifactValidation {
+    section: string;
+    required: boolean;
+    validationRule: string;
+}
+export interface StageAutoSubagentDispatch {
+    agent: "planner" | "spec-reviewer" | "code-reviewer" | "security-reviewer" | "test-author" | "doc-updater";
+    mode: "mandatory" | "proactive";
+    when: string;
+    purpose: string;
+    requiresUserGate: boolean;
+}
+export interface NamedAntiPattern {
+    title: string;
+    description: string;
+}
+export interface StageSchema {
+    stage: FlowStage;
+    skillFolder: string;
+    skillName: string;
+    skillDescription: string;
+    hardGate: string;
+    purpose: string;
+    whenToUse: string[];
+    interactionProtocol: string[];
+    process: string[];
+    requiredGates: StageGate[];
+    requiredEvidence: string[];
+    inputs: string[];
+    requiredContext: string[];
+    outputs: string[];
+    blockers: string[];
+    exitCriteria: string[];
+    antiPatterns: string[];
+    rationalizations: StageRationalization[];
+    redFlags: string[];
+    policyNeedles: string[];
+    artifactFile: string;
+    next: FlowStage | "done";
+    checklist: string[];
+    cognitivePatterns: CognitivePattern[];
+    reviewSections: ReviewSection[];
+    completionStatus: string[];
+    crossStageTrace: CrossStageTrace;
+    artifactValidation: ArtifactValidation[];
+    namedAntiPattern?: NamedAntiPattern;
+    decisionRecordFormat?: string;
+}
+export declare function stageSchema(stage: FlowStage): StageSchema;
+export declare function orderedStageSchemas(): StageSchema[];
+export declare function stageGateIds(stage: FlowStage): string[];
+export declare function nextCclawCommand(stage: FlowStage): string;
+export declare function buildTransitionRules(): TransitionRule[];
+export declare function stagePolicyNeedles(stage: FlowStage): string[];
+export declare function stageAutoSubagentDispatch(stage: FlowStage): StageAutoSubagentDispatch[];