cclaw-cli 0.5.17 → 0.6.0

package/dist/flow-state.js

@@ -1,7 +1,28 @@
 import { COMMAND_FILE_ORDER } from "./constants.js";
 import { buildTransitionRules, orderedStageSchemas, stageGateIds } from "./content/stage-schema.js";
+import { FLOW_STAGES, FLOW_TRACKS, TRACK_STAGES } from "./types.js";
 export const TRANSITION_RULES = buildTransitionRules();
-export function createInitialFlowState(activeRunId = "active") {
+export function isFlowTrack(value) {
+    return typeof value === "string" && FLOW_TRACKS.includes(value);
+}
+export function trackStages(track) {
+    return [...TRACK_STAGES[track]];
+}
+export function skippedStagesForTrack(track) {
+    const inTrack = new Set(TRACK_STAGES[track]);
+    return FLOW_STAGES.filter((stage) => !inTrack.has(stage));
+}
+export function firstStageForTrack(track) {
+    const stages = TRACK_STAGES[track];
+    return stages[0] ?? "brainstorm";
+}
+export function createInitialFlowState(activeRunIdOrOptions = "active", maybeTrack) {
+    const options = typeof activeRunIdOrOptions === "string"
+        ? { activeRunId: activeRunIdOrOptions, track: maybeTrack }
+        : activeRunIdOrOptions;
+    const activeRunId = options.activeRunId ?? "active";
+    const track = options.track ?? "standard";
+    const skippedStages = skippedStagesForTrack(track);
     const stageGateCatalog = {};
     for (const schema of orderedStageSchemas()) {
         stageGateCatalog[schema.stage] = {
@@ -12,10 +33,12 @@ export function createInitialFlowState(activeRunId = "active") {
     }
     return {
         activeRunId,
-        currentStage: "brainstorm",
+        currentStage: firstStageForTrack(track),
         completedStages: [],
         guardEvidence: {},
-        stageGateCatalog
+        stageGateCatalog,
+        track,
+        skippedStages
     };
 }
 export function canTransition(from, to) {
@@ -25,17 +48,33 @@ export function getTransitionGuards(from, to) {
     const match = TRANSITION_RULES.find((rule) => rule.from === from && rule.to === to);
     return match ? [...match.guards] : [];
 }
-export function nextStage(stage) {
-    const index = COMMAND_FILE_ORDER.indexOf(stage);
-    if (index < 0 || index === COMMAND_FILE_ORDER.length - 1) {
+export function nextStage(stage, track = "standard") {
+    const ordered = TRACK_STAGES[track];
+    const index = ordered.indexOf(stage);
+    if (index < 0) {
+        const fallback = COMMAND_FILE_ORDER.indexOf(stage);
+        if (fallback < 0 || fallback === COMMAND_FILE_ORDER.length - 1) {
+            return null;
+        }
+        return COMMAND_FILE_ORDER[fallback + 1];
+    }
+    if (index === ordered.length - 1) {
         return null;
     }
-    return COMMAND_FILE_ORDER[index + 1];
+    return ordered[index + 1];
 }
-export function previousStage(stage) {
-    const index = COMMAND_FILE_ORDER.indexOf(stage);
-    if (index <= 0) {
+export function previousStage(stage, track = "standard") {
+    const ordered = TRACK_STAGES[track];
+    const index = ordered.indexOf(stage);
+    if (index === 0) {
         return null;
     }
-    return COMMAND_FILE_ORDER[index - 1];
+    if (index < 0) {
+        const fallback = COMMAND_FILE_ORDER.indexOf(stage);
+        if (fallback <= 0) {
+            return null;
+        }
+        return COMMAND_FILE_ORDER[fallback - 1];
+    }
+    return ordered[index - 1];
 }

package/dist/harness-adapters.js

@@ -124,6 +124,7 @@ export async function syncHarnessShims(projectRoot, harnesses) {
         await writeFileSafe(path.join(commandDir, "cc.md"), utilityShimContent(harness, "cc", "flow-start", "start.md"));
         await writeFileSafe(path.join(commandDir, "cc-next.md"), utilityShimContent(harness, "next", "flow-next-step", "next.md"));
         await writeFileSafe(path.join(commandDir, "cc-learn.md"), utilityShimContent(harness, "learn", "learnings", "learn.md"));
+        await writeFileSafe(path.join(commandDir, "cc-status.md"), utilityShimContent(harness, "status", "flow-status", "status.md"));
     }
     await syncAgentFiles(projectRoot);
     await syncAgentsMd(projectRoot);

package/dist/install.d.ts

@@ -1,7 +1,8 @@
-import type { HarnessId } from "./types.js";
+import type { FlowTrack, HarnessId } from "./types.js";
 export interface InitOptions {
     projectRoot: string;
     harnesses?: HarnessId[];
+    track?: FlowTrack;
 }
 export declare function initCclaw(options: InitOptions): Promise<void>;
 export declare function syncCclaw(projectRoot: string): Promise<void>;

package/dist/install.js

@@ -9,9 +9,10 @@ import { contextModeFiles, createInitialContextModeState } from "./content/conte
 import { learnSkillMarkdown, learnCommandContract } from "./content/learnings.js";
 import { nextCommandContract, nextCommandSkillMarkdown } from "./content/next-command.js";
 import { startCommandContract, startCommandSkillMarkdown } from "./content/start-command.js";
+import { statusCommandContract, statusCommandSkillMarkdown } from "./content/status-command.js";
 import { subagentDrivenDevSkill, parallelAgentsSkill } from "./content/subagents.js";
 import { sessionHooksSkillMarkdown } from "./content/session-hooks.js";
-import { sessionStartScript, stopCheckpointScript, opencodePluginJs, claudeHooksJson, cursorHooksJson, codexHooksJson } from "./content/hooks.js";
+import { sessionStartScript, stopCheckpointScript, preCompactScript, opencodePluginJs, claudeHooksJson, cursorHooksJson, codexHooksJson } from "./content/hooks.js";
 import { contextMonitorScript, promptGuardScript, workflowGuardScript } from "./content/observe.js";
 import { META_SKILL_NAME, usingCclawSkillMarkdown } from "./content/meta-skill.js";
 import { ARTIFACT_TEMPLATES, CURSOR_WORKFLOW_RULE_MDC, RULEBOOK_MARKDOWN, buildRulesJson } from "./content/templates.js";
@@ -173,6 +174,7 @@ async function writeSkills(projectRoot) {
     await writeFileSafe(runtimePath(projectRoot, "skills", "learnings", "SKILL.md"), learnSkillMarkdown());
     await writeFileSafe(runtimePath(projectRoot, "skills", "flow-next-step", "SKILL.md"), nextCommandSkillMarkdown());
     await writeFileSafe(runtimePath(projectRoot, "skills", "flow-start", "SKILL.md"), startCommandSkillMarkdown());
+    await writeFileSafe(runtimePath(projectRoot, "skills", "flow-status", "SKILL.md"), statusCommandSkillMarkdown());
     await writeFileSafe(runtimePath(projectRoot, "skills", "subagent-dev", "SKILL.md"), subagentDrivenDevSkill());
     await writeFileSafe(runtimePath(projectRoot, "skills", "parallel-dispatch", "SKILL.md"), parallelAgentsSkill());
     await writeFileSafe(runtimePath(projectRoot, "skills", "session", "SKILL.md"), sessionHooksSkillMarkdown());
@@ -186,6 +188,7 @@ async function writeUtilityCommands(projectRoot) {
     await writeFileSafe(runtimePath(projectRoot, "commands", "learn.md"), learnCommandContract());
     await writeFileSafe(runtimePath(projectRoot, "commands", "next.md"), nextCommandContract());
     await writeFileSafe(runtimePath(projectRoot, "commands", "start.md"), startCommandContract());
+    await writeFileSafe(runtimePath(projectRoot, "commands", "status.md"), statusCommandContract());
 }
 function toObject(value) {
     if (!value || typeof value !== "object" || Array.isArray(value)) {
@@ -482,6 +485,7 @@ async function writeHooks(projectRoot, config) {
     await ensureDir(hooksDir);
     await writeFileSafe(path.join(hooksDir, "session-start.sh"), sessionStartScript());
     await writeFileSafe(path.join(hooksDir, "stop-checkpoint.sh"), stopCheckpointScript());
+    await writeFileSafe(path.join(hooksDir, "pre-compact.sh"), preCompactScript());
     await writeFileSafe(path.join(hooksDir, "prompt-guard.sh"), promptGuardScript({
         strictMode: config.promptGuardMode === "strict"
     }));
@@ -493,6 +497,7 @@ async function writeHooks(projectRoot, config) {
         for (const script of [
             "session-start.sh",
             "stop-checkpoint.sh",
+            "pre-compact.sh",
             "prompt-guard.sh",
             "workflow-guard.sh",
             "context-monitor.sh",
@@ -542,6 +547,101 @@ async function ensureKnowledgeStore(projectRoot) {
         await writeFileSafe(storePath, "# Project Knowledge\n\n");
     }
 }
+async function ensureCustomSkillsScaffold(projectRoot) {
+    const customDir = runtimePath(projectRoot, "custom-skills");
+    await ensureDir(customDir);
+    const readmePath = path.join(customDir, "README.md");
+    if (!(await exists(readmePath))) {
+        await writeFileSafe(readmePath, CUSTOM_SKILLS_README);
+    }
+    const examplePath = path.join(customDir, "example", "SKILL.md");
+    if (!(await exists(examplePath))) {
+        await writeFileSafe(examplePath, CUSTOM_SKILLS_EXAMPLE);
+    }
+}
+const CUSTOM_SKILLS_README = `# Custom Skills (sync-safe)
+
+This directory is **never overwritten** by \`cclaw sync\` or \`cclaw upgrade\`. Use it
+to add project-specific skills that complement the managed skills under
+\`.cclaw/skills/\`.
+
+## When to add a custom skill
+
+- A repeatable lens specific to **this project** (e.g. "billing-domain", "kafka-message-contracts").
+- A team convention you want every agent session to load.
+- A domain checklist that does not generalize to other projects.
+
+If the skill is general (security, performance, accessibility, etc.) prefer
+contributing it upstream instead — the managed skills receive maintenance.
+
+## File format
+
+Each skill lives at \`.cclaw/custom-skills/<folder>/SKILL.md\` with frontmatter:
+
+\`\`\`markdown
+---
+name: <kebab-case-skill-name>
+description: "One sentence describing when this skill applies. Triggers semantic routing."
+---
+
+# <Skill title>
+
+## When to use
+- ...
+
+## HARD-GATE (optional)
+A non-skippable rule, if any. Phrase it as a refusal, not a recommendation.
+
+## Algorithm / checklist
+1. ...
+2. ...
+
+## Anti-patterns
+- ...
+\`\`\`
+
+## Routing
+
+Custom skills are surfaced via the \`using-cclaw\` meta-skill at session start.
+Mention the skill name in your prompt or let the agent semantic-route to it
+based on the description.
+
+## Removing or replacing
+
+Custom skills are user-owned. Delete or edit them at any time — \`cclaw sync\`
+will not touch them.
+`;
+const CUSTOM_SKILLS_EXAMPLE = `---
+name: example-custom-skill
+description: "Replace this with a one-sentence description that triggers when the skill should be used. Delete or rename this folder when you add a real skill."
+---
+
+# Example Custom Skill
+
+This is a placeholder. Use it as a starting template, then delete or rename
+the \`example/\` folder.
+
+## When to use
+
+- A real, repeatable situation in **this** project that needs a consistent lens.
+
+## HARD-GATE (optional)
+
+Drop this section if no hard rule applies. Keep it crisp:
+
+> Do not <X> while <Y>.
+
+## Algorithm
+
+1. Step one — observable, file:line evidence required.
+2. Step two — produce a named artifact, not a vibe.
+3. Step three — escalate / hand off / record knowledge entry.
+
+## Anti-patterns
+
+- Treating this skill as advisory when the situation matches the trigger.
+- Loading this skill when the situation clearly does not match (context bloat).
+`;
 async function ensureSessionStateFiles(projectRoot) {
     const stateDir = runtimePath(projectRoot, "state");
     await ensureDir(stateDir);
@@ -623,12 +723,12 @@ async function syncDisabledHarnessArtifacts(projectRoot, harnesses) {
         await removeManagedOpenCodePluginConfig(projectRoot, OPENCODE_PLUGIN_REL_PATH);
     }
 }
-async function writeState(projectRoot, forceReset = false) {
+async function writeState(projectRoot, config, forceReset = false) {
     const statePath = runtimePath(projectRoot, "state", "flow-state.json");
     if (!forceReset && (await exists(statePath))) {
         return;
     }
-    const state = createInitialFlowState();
+    const state = createInitialFlowState("active", config.defaultTrack ?? "standard");
     await writeFileSafe(statePath, `${JSON.stringify(state, null, 2)}\n`);
 }
 async function writeAdapterManifest(projectRoot, harnesses) {
@@ -740,11 +840,12 @@ async function materializeRuntime(projectRoot, config, forceStateReset) {
     await writeContextModes(projectRoot);
     await writeArtifactTemplates(projectRoot);
     await writeRulebook(projectRoot);
-    await writeState(projectRoot, forceStateReset);
+    await writeState(projectRoot, config, forceStateReset);
     await ensureRunSystem(projectRoot, { createIfMissing: false });
     await ensureSessionStateFiles(projectRoot);
     await writeAdapterManifest(projectRoot, harnesses);
     await ensureKnowledgeStore(projectRoot);
+    await ensureCustomSkillsScaffold(projectRoot);
     await writeHooks(projectRoot, config);
     await syncDisabledHarnessArtifacts(projectRoot, harnesses);
     await syncManagedGitHooks(projectRoot, config);
@@ -753,7 +854,7 @@ async function materializeRuntime(projectRoot, config, forceStateReset) {
     await ensureGitignore(projectRoot);
 }
 export async function initCclaw(options) {
-    const config = createDefaultConfig(options.harnesses);
+    const config = createDefaultConfig(options.harnesses, options.track);
     await writeConfig(options.projectRoot, config);
     await materializeRuntime(options.projectRoot, config, true);
 }
@@ -828,7 +929,7 @@ function stripManagedHookCommands(value) {
 }
 function isManagedRuntimeHookCommand(command) {
     const normalized = command.trim().replace(/\s+/gu, " ");
-    return /(^|\s)(?:bash\s+)?(?:\.\/)?\.cclaw\/hooks\/(?:session-start|stop-checkpoint|prompt-guard|workflow-guard|context-monitor)\.sh(?:\s|$)/u.test(normalized);
+    return /(^|\s)(?:bash\s+)?(?:\.\/)?\.cclaw\/hooks\/(?:session-start|stop-checkpoint|pre-compact|prompt-guard|workflow-guard|context-monitor)\.sh(?:\s|$)/u.test(normalized);
 }
 async function removeManagedHookEntries(hookFilePath) {
     if (!(await exists(hookFilePath)))

package/dist/runs.js

@@ -1,7 +1,7 @@
 import fs from "node:fs/promises";
 import path from "node:path";
 import { COMMAND_FILE_ORDER, RUNTIME_ROOT } from "./constants.js";
-import { canTransition, createInitialFlowState } from "./flow-state.js";
+import { canTransition, createInitialFlowState, isFlowTrack, skippedStagesForTrack } from "./flow-state.js";
 import { ensureDir, exists, withDirectoryLock, writeFileSafe } from "./fs-utils.js";
 export class InvalidStageTransitionError extends Error {
     from;
@@ -156,8 +156,27 @@ function sanitizeStageGateCatalog(value, fallback) {
     }
     return next;
 }
+function coerceTrack(value) {
+    return isFlowTrack(value) ? value : "standard";
+}
+function sanitizeSkippedStages(value, track) {
+    const trackDefault = skippedStagesForTrack(track);
+    if (!Array.isArray(value)) {
+        return trackDefault;
+    }
+    const seen = new Set();
+    const out = [];
+    for (const raw of value) {
+        if (isFlowStage(raw) && !seen.has(raw)) {
+            seen.add(raw);
+            out.push(raw);
+        }
+    }
+    return out.length > 0 ? out : trackDefault;
+}
 function coerceFlowState(parsed) {
-    const next = createInitialFlowState();
+    const track = coerceTrack(parsed.track);
+    const next = createInitialFlowState("active", track);
     const activeRunIdRaw = parsed.activeRunId;
     const activeRunId = typeof activeRunIdRaw === "string" && activeRunIdRaw.trim().length > 0
         ? activeRunIdRaw.trim()
@@ -167,7 +186,9 @@ function coerceFlowState(parsed) {
         currentStage: isFlowStage(parsed.currentStage) ? parsed.currentStage : next.currentStage,
         completedStages: sanitizeCompletedStages(parsed.completedStages),
         guardEvidence: sanitizeGuardEvidence(parsed.guardEvidence),
-        stageGateCatalog: sanitizeStageGateCatalog(parsed.stageGateCatalog, next.stageGateCatalog)
+        stageGateCatalog: sanitizeStageGateCatalog(parsed.stageGateCatalog, next.stageGateCatalog),
+        track,
+        skippedStages: sanitizeSkippedStages(parsed.skippedStages, track)
     };
 }
 function toArchiveDate(date = new Date()) {

package/dist/types.d.ts

@@ -1,5 +1,16 @@
 export declare const FLOW_STAGES: readonly ["brainstorm", "scope", "design", "spec", "plan", "tdd", "review", "ship"];
 export type FlowStage = (typeof FLOW_STAGES)[number];
+export declare const FLOW_TRACKS: readonly ["quick", "standard"];
+export type FlowTrack = (typeof FLOW_TRACKS)[number];
+/**
+ * Ordered stages that make up each flow track.
+ *
+ * - `standard` runs the full 8-stage pipeline (default — same as before tracks existed).
+ * - `quick` skips the upstream product stages (brainstorm/scope/design/plan) for
+ *   small bug fixes or single-purpose changes where the spec is already known.
+ *   It still keeps the non-negotiable safety gates: spec → tdd → review → ship.
+ */
+export declare const TRACK_STAGES: Record<FlowTrack, readonly FlowStage[]>;
 export declare const HARNESS_IDS: readonly ["claude", "cursor", "opencode", "codex"];
 export type HarnessId = (typeof HARNESS_IDS)[number];
 export interface VibyConfig {
@@ -12,6 +23,8 @@ export interface VibyConfig {
     promptGuardMode?: "advisory" | "strict";
     /** When true, cclaw installs managed git pre-commit/pre-push wrappers. */
     gitHookGuards?: boolean;
+    /** Default flow track for new runs (quick = shortened path, standard = full pipeline). */
+    defaultTrack?: FlowTrack;
 }
 export interface TransitionRule {
     from: FlowStage;

package/dist/types.js

@@ -8,4 +8,17 @@ export const FLOW_STAGES = [
     "review",
     "ship"
 ];
+export const FLOW_TRACKS = ["quick", "standard"];
+/**
+ * Ordered stages that make up each flow track.
+ *
+ * - `standard` runs the full 8-stage pipeline (default — same as before tracks existed).
+ * - `quick` skips the upstream product stages (brainstorm/scope/design/plan) for
+ *   small bug fixes or single-purpose changes where the spec is already known.
+ *   It still keeps the non-negotiable safety gates: spec → tdd → review → ship.
+ */
+export const TRACK_STAGES = {
+    standard: FLOW_STAGES,
+    quick: ["spec", "tdd", "review", "ship"]
+};
 export const HARNESS_IDS = ["claude", "cursor", "opencode", "codex"];

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "cclaw-cli",
-  "version": "0.5.17",
+  "version": "0.6.0",
   "description": "Installer-first flow toolkit for coding agents",
   "type": "module",
   "bin": {