cclaw-cli 0.6.0 → 0.7.0

package/dist/install.js

@@ -3,7 +3,7 @@ import fs from "node:fs/promises";
 import path from "node:path";
 import { promisify } from "node:util";
 import { COMMAND_FILE_ORDER, REQUIRED_DIRS, RUNTIME_ROOT, UTILITY_COMMANDS } from "./constants.js";
-import { writeConfig, createDefaultConfig, readConfig, configPath } from "./config.js";
+import { writeConfig, createDefaultConfig, createProfileConfig, readConfig, configPath } from "./config.js";
 import { commandContract } from "./content/contracts.js";
 import { contextModeFiles, createInitialContextModeState } from "./content/contexts.js";
 import { learnSkillMarkdown, learnCommandContract } from "./content/learnings.js";
@@ -17,7 +17,7 @@ import { contextMonitorScript, promptGuardScript, workflowGuardScript } from "./
 import { META_SKILL_NAME, usingCclawSkillMarkdown } from "./content/meta-skill.js";
 import { ARTIFACT_TEMPLATES, CURSOR_WORKFLOW_RULE_MDC, RULEBOOK_MARKDOWN, buildRulesJson } from "./content/templates.js";
 import { stageSkillFolder, stageSkillMarkdown } from "./content/skills.js";
-import { UTILITY_SKILL_FOLDERS, UTILITY_SKILL_MAP } from "./content/utility-skills.js";
+import { LANGUAGE_RULE_PACK_FOLDERS, LANGUAGE_RULE_PACK_GENERATORS, UTILITY_SKILL_FOLDERS, UTILITY_SKILL_MAP } from "./content/utility-skills.js";
 import { createInitialFlowState } from "./flow-state.js";
 import { ensureDir, exists, writeFileSafe } from "./fs-utils.js";
 import { ensureGitignore, removeGitignorePatterns } from "./gitignore.js";
@@ -165,7 +165,7 @@ async function writeArtifactTemplates(projectRoot) {
         await writeFileSafe(runtimePath(projectRoot, "templates", fileName), content);
     }
 }
-async function writeSkills(projectRoot) {
+async function writeSkills(projectRoot, config) {
     for (const stage of COMMAND_FILE_ORDER) {
         const folder = stageSkillFolder(stage);
         await writeFileSafe(runtimePath(projectRoot, "skills", folder, "SKILL.md"), stageSkillMarkdown(stage));
@@ -183,6 +183,14 @@ async function writeSkills(projectRoot) {
         const generator = UTILITY_SKILL_MAP[folder];
         await writeFileSafe(runtimePath(projectRoot, "skills", folder, "SKILL.md"), generator());
     }
+    const enabledPacks = config?.languageRulePacks ?? [];
+    for (const pack of enabledPacks) {
+        const folder = LANGUAGE_RULE_PACK_FOLDERS[pack];
+        const generator = LANGUAGE_RULE_PACK_GENERATORS[folder];
+        if (!folder || !generator)
+            continue;
+        await writeFileSafe(runtimePath(projectRoot, "skills", folder, "SKILL.md"), generator());
+    }
 }
 async function writeUtilityCommands(projectRoot) {
     await writeFileSafe(runtimePath(projectRoot, "commands", "learn.md"), learnCommandContract());
@@ -574,42 +582,92 @@ to add project-specific skills that complement the managed skills under
 If the skill is general (security, performance, accessibility, etc.) prefer
 contributing it upstream instead — the managed skills receive maintenance.
 
-## File format
+## File format — public API (stable contract)
 
-Each skill lives at \`.cclaw/custom-skills/<folder>/SKILL.md\` with frontmatter:
+Each skill lives at \`.cclaw/custom-skills/<folder>/SKILL.md\`. The format is a
+**stable public API**: \`cclaw sync\` and \`cclaw upgrade\` will not rewrite
+custom skills, and the fields below are guaranteed to be respected by the
+meta-skill router and the stage hooks.
 
-\`\`\`markdown
+### Frontmatter (YAML, required)
+
+\`\`\`yaml
 ---
+# Required fields
 name: <kebab-case-skill-name>
-description: "One sentence describing when this skill applies. Triggers semantic routing."
+description: >
+  One sentence (≤180 chars) that triggers semantic routing. Include the
+  concrete situation and the expected action
+  (e.g. "Audit Kafka topic contracts when a producer or consumer signature changes").
+
+# Optional fields (omit when not applicable)
+stages: [design, spec, tdd, review]    # flow stages this skill applies to
+triggers:
+  - "kafka topic"
+  - "producer.schema"
+  - "consumer.schema"
+hardGate: false                        # true => skill body MUST include a ## HARD-GATE section
+owners: ["@team-messaging"]            # informational routing hint, not enforced
+version: 0.1.0                         # semver; bump when hardGate or algorithm changes
 ---
+\`\`\`
+
+### Field contract
+
+| Field | Type | Required | Meaning |
+|---|---|---|---|
+| \`name\` | string (kebab-case) | yes | Unique id used by the router and by \`/cc-status\` diagnostics. |
+| \`description\` | string ≤180 chars (single line OR YAML \`>\` folded) | yes | Drives semantic routing. Include trigger + action. |
+| \`stages\` | array of flow stages | no | When present, the meta-skill only surfaces this skill during those stages. Omit for "any stage". |
+| \`triggers\` | array of strings | no | Extra literal substrings that route to this skill when found in the user prompt or the active artifact. |
+| \`hardGate\` | boolean | no | When \`true\`, the body MUST include a \`## HARD-GATE\` section; the agent treats the rule as non-skippable. |
+| \`owners\` | array of strings | no | Informational only — surfaced to the user, never enforced. |
+| \`version\` | semver string | no | Bump when you change the HARD-GATE or algorithm so reviewers can spot changes. |
 
+### Body sections (markdown, recommended order)
+
+\`\`\`markdown
 # <Skill title>
 
+## Overview
+One-paragraph summary; context for when this skill is loaded.
+
 ## When to use
-- ...
+- Bullet list of situations where this skill adds value.
 
-## HARD-GATE (optional)
-A non-skippable rule, if any. Phrase it as a refusal, not a recommendation.
+## When NOT to use
+- Situations where loading this skill is context bloat or wrong.
+
+## HARD-GATE   (REQUIRED when frontmatter hardGate: true)
+Phrase it as a refusal:
+> Do not <X> while <Y>.
 
 ## Algorithm / checklist
-1. ...
-2. ...
+1. Concrete, observable steps with evidence (file:line, artifact, or knowledge entry).
+
+## Output protocol
+Where the artifact / chat output lives and what shape it takes.
 
 ## Anti-patterns
-- ...
+- Common failure modes to reject.
 \`\`\`
 
+### Stage association semantics
+
+- \`stages: []\` or missing → skill is available at any stage. The meta-skill still only surfaces it when \`description\` or \`triggers\` match the prompt.
+- \`stages: [review]\` → skill is offered only during the review stage.
+- Custom skills **never** become mandatory delegations. They are opt-in lenses. If you need a mandatory dispatch, add a proper managed specialist under \`.cclaw/skills/\` instead.
+
 ## 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.
+based on the description + triggers + stages frontmatter.
 
-## Removing or replacing
+## Versioning & removal
 
-Custom skills are user-owned. Delete or edit them at any time — \`cclaw sync\`
-will not touch them.
+Custom skills are user-owned. Bump \`version\` when you change the HARD-GATE or
+algorithm; delete or edit them at any time — \`cclaw sync\` will not touch them.
 `;
 const CUSTOM_SKILLS_EXAMPLE = `---
 name: example-custom-skill
@@ -836,7 +894,7 @@ async function materializeRuntime(projectRoot, config, forceStateReset) {
     await cleanStaleFiles(projectRoot);
     await writeCommandContracts(projectRoot);
     await writeUtilityCommands(projectRoot);
-    await writeSkills(projectRoot);
+    await writeSkills(projectRoot, config);
     await writeContextModes(projectRoot);
     await writeArtifactTemplates(projectRoot);
     await writeRulebook(projectRoot);
@@ -854,7 +912,12 @@ async function materializeRuntime(projectRoot, config, forceStateReset) {
     await ensureGitignore(projectRoot);
 }
 export async function initCclaw(options) {
-    const config = createDefaultConfig(options.harnesses, options.track);
+    const config = options.profile
+        ? createProfileConfig(options.profile, {
+            harnesses: options.harnesses,
+            defaultTrack: options.track
+        })
+        : createDefaultConfig(options.harnesses, options.track);
     await writeConfig(options.projectRoot, config);
     await materializeRuntime(options.projectRoot, config, true);
 }

package/dist/policy.js

@@ -85,7 +85,8 @@ export async function policyChecks(projectRoot, options = {}) {
     // --- utility skill checks ---
     const runtimeFile = (relativePath) => `${RUNTIME_ROOT}/${relativePath}`;
     const utilitySkillChecks = [
-        { file: runtimeFile("skills/learnings/SKILL.md"), needle: "## Entry format (append-only)", name: "utility_skill:learnings:entry_format" },
+        { file: runtimeFile("skills/learnings/SKILL.md"), needle: "## Entry format", name: "utility_skill:learnings:entry_format" },
+        { file: runtimeFile("skills/learnings/SKILL.md"), needle: "knowledge.jsonl", name: "utility_skill:learnings:jsonl_mirror" },
         { file: runtimeFile("skills/learnings/SKILL.md"), needle: "## Subcommands", name: "utility_skill:learnings:subcommands" },
         { file: runtimeFile("skills/learnings/SKILL.md"), needle: "## HARD-GATE", name: "utility_skill:learnings:hard_gate" },
         { file: runtimeFile("commands/learn.md"), needle: "## Subcommands", name: "utility_command:learn:subcommands" },

package/dist/runs.d.ts

@@ -24,6 +24,13 @@ export interface ArchiveRunResult {
     featureName: string;
     resetState: FlowState;
     snapshottedStateFiles: string[];
+    /** Knowledge curation hint: total active entries + soft threshold (50). */
+    knowledge: {
+        activeEntryCount: number;
+        softThreshold: number;
+        overThreshold: boolean;
+        knowledgePath: string;
+    };
 }
 export interface ArchiveManifest {
     version: 1;
@@ -48,4 +55,12 @@ export declare function writeFlowState(projectRoot: string, state: FlowState, op
 export declare function ensureRunSystem(projectRoot: string, _options?: EnsureRunSystemOptions): Promise<FlowState>;
 export declare function listRuns(projectRoot: string): Promise<CclawRunMeta[]>;
 export declare function archiveRun(projectRoot: string, featureName?: string): Promise<ArchiveRunResult>;
+/**
+ * Counts active (non-superseded) knowledge entries.
+ * An entry is a markdown H3 heading with the canonical timestamped format produced by
+ * `learn add` / `learn curate`. Entries marked `Supersedes:` themselves are still active;
+ * this helper does not currently follow supersession chains beyond raw count, which is
+ * deliberate — the curator reads the file directly to make the soft-archive plan.
+ */
+export declare function countActiveKnowledgeEntries(text: string): number;
 export {};

package/dist/runs.js

@@ -394,12 +394,46 @@ export async function archiveRun(projectRoot, featureName) {
         snapshottedStateFiles
     };
     await writeFileSafe(path.join(archivePath, "archive-manifest.json"), `${JSON.stringify(manifest, null, 2)}\n`);
+    const knowledgeStats = await readKnowledgeStats(projectRoot);
     return {
         archiveId,
         archivePath,
         archivedAt,
         featureName: feature,
         resetState,
-        snapshottedStateFiles
+        snapshottedStateFiles,
+        knowledge: knowledgeStats
+    };
+}
+const KNOWLEDGE_SOFT_THRESHOLD = 50;
+async function readKnowledgeStats(projectRoot) {
+    const knowledgePath = path.join(projectRoot, RUNTIME_ROOT, "knowledge.md");
+    let activeEntryCount = 0;
+    if (await exists(knowledgePath)) {
+        const text = await fs.readFile(knowledgePath, "utf8");
+        activeEntryCount = countActiveKnowledgeEntries(text);
+    }
+    return {
+        activeEntryCount,
+        softThreshold: KNOWLEDGE_SOFT_THRESHOLD,
+        overThreshold: activeEntryCount > KNOWLEDGE_SOFT_THRESHOLD,
+        knowledgePath: `${RUNTIME_ROOT}/knowledge.md`
     };
 }
+/**
+ * Counts active (non-superseded) knowledge entries.
+ * An entry is a markdown H3 heading with the canonical timestamped format produced by
+ * `learn add` / `learn curate`. Entries marked `Supersedes:` themselves are still active;
+ * this helper does not currently follow supersession chains beyond raw count, which is
+ * deliberate — the curator reads the file directly to make the soft-archive plan.
+ */
+export function countActiveKnowledgeEntries(text) {
+    const lines = text.split(/\r?\n/);
+    let count = 0;
+    for (const line of lines) {
+        if (/^###\s+\d{4}-\d{2}-\d{2}T\d{2}:\d{2}:\d{2}Z\s+\[(rule|pattern|lesson|compound)\]/u.test(line)) {
+            count += 1;
+        }
+    }
+    return count;
+}

package/dist/types.d.ts

@@ -13,6 +13,28 @@ export type FlowTrack = (typeof FLOW_TRACKS)[number];
 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];
+/**
+ * Init profiles pre-fill `cclaw init` flags for common install shapes.
+ *
+ * - `minimal` — single-harness (claude), quick track default, no git hook guards. For solo
+ *   contributors or bugfix-heavy repos where most work is \`quick\` scope.
+ * - `standard` — default harness set, standard track, no git hook guards, advisory guards.
+ *   Matches the pre-profile default behavior.
+ * - `full` — default harness set, standard track, git hook guards on, strict prompt guards.
+ *   For teams that want every safety rail on.
+ */
+export declare const INIT_PROFILES: readonly ["minimal", "standard", "full"];
+export type InitProfile = (typeof INIT_PROFILES)[number];
+/**
+ * Opt-in language rule packs. When enabled in config, `cclaw sync` installs the
+ * corresponding utility skill so the meta-skill router can load language-specific
+ * anti-patterns, idioms, and review heuristics during review/tdd stages.
+ *
+ * Opt-in intentional: cclaw stays language-agnostic by default; rule packs are
+ * additive context that the user must explicitly enable.
+ */
+export declare const LANGUAGE_RULE_PACKS: readonly ["typescript", "python", "go"];
+export type LanguageRulePack = (typeof LANGUAGE_RULE_PACKS)[number];
 export interface VibyConfig {
     version: string;
     flowVersion: string;
@@ -25,6 +47,13 @@ export interface VibyConfig {
     gitHookGuards?: boolean;
     /** Default flow track for new runs (quick = shortened path, standard = full pipeline). */
     defaultTrack?: FlowTrack;
+    /**
+     * Opt-in language rule packs. Each enabled pack materializes a matching utility
+     * skill under `.cclaw/skills/language-<id>/SKILL.md` on next `cclaw sync`. The
+     * meta-skill router loads the pack during review/tdd when the diff touches the
+     * language in question.
+     */
+    languageRulePacks?: LanguageRulePack[];
 }
 export interface TransitionRule {
     from: FlowStage;

package/dist/types.js

@@ -22,3 +22,23 @@ export const TRACK_STAGES = {
     quick: ["spec", "tdd", "review", "ship"]
 };
 export const HARNESS_IDS = ["claude", "cursor", "opencode", "codex"];
+/**
+ * Init profiles pre-fill `cclaw init` flags for common install shapes.
+ *
+ * - `minimal` — single-harness (claude), quick track default, no git hook guards. For solo
+ *   contributors or bugfix-heavy repos where most work is \`quick\` scope.
+ * - `standard` — default harness set, standard track, no git hook guards, advisory guards.
+ *   Matches the pre-profile default behavior.
+ * - `full` — default harness set, standard track, git hook guards on, strict prompt guards.
+ *   For teams that want every safety rail on.
+ */
+export const INIT_PROFILES = ["minimal", "standard", "full"];
+/**
+ * Opt-in language rule packs. When enabled in config, `cclaw sync` installs the
+ * corresponding utility skill so the meta-skill router can load language-specific
+ * anti-patterns, idioms, and review heuristics during review/tdd stages.
+ *
+ * Opt-in intentional: cclaw stays language-agnostic by default; rule packs are
+ * additive context that the user must explicitly enable.
+ */
+export const LANGUAGE_RULE_PACKS = ["typescript", "python", "go"];

package/package.json

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