@entelligentsia/forgecli 0.1.0 → 0.3.0

package/dist/extensions/forgecli/refresh-kb-links.js

@@ -0,0 +1,228 @@
+// refresh-kb-links.ts — TypeScript port of forge/forge/skills/refresh-kb-links/SKILL.md
+//
+// Scans coding-agent instruction files (CLAUDE.md, AGENTS.md, etc.) and
+// ensures each has up-to-date managed sections linking to the Forge KB and
+// workflows. Called directly by Phase 4 step 4-9 (Tomoshibi) during
+// /forge:init and registered as the /forge:refresh-kb-links command handler.
+//
+// Per PLAN.md sub-decision #5 (F7 fix): TS port is the only valid implementation;
+// forge/forge/skills/refresh-kb-links/SKILL.md is a markdown body with no
+// runnable .cjs entry point.
+//
+// Iron Law 6: no shell-string interpolation.
+// Iron Law 1: reads .forge/config.json — no writes to forge/ source.
+import * as fs from "node:fs";
+import * as path from "node:path";
+// ── Known agent instruction files ─────────────────────────────────────────
+const AGENT_INSTRUCTION_FILES = [
+    "CLAUDE.md",
+    "AGENTS.md",
+    "AGENT.md",
+    "GEMINI.md",
+    ".cursorrules",
+    ".github/copilot-instructions.md",
+];
+// ── Known workflow files ───────────────────────────────────────────────────
+const WORKFLOW_ENTRIES = [
+    { file: "plan_task.md", label: "Plan", purpose: "Research codebase → implementation plan" },
+    { file: "implement_plan.md", label: "Implement", purpose: "Execute approved plan → code changes" },
+    { file: "fix_bug.md", label: "Fix bug", purpose: "Triage → fix → verify" },
+    {
+        file: "orchestrate_task.md",
+        label: "Run task",
+        purpose: "Full task pipeline (plan → implement → review → commit)",
+    },
+    { file: "run_sprint.md", label: "Run sprint", purpose: "Full sprint orchestration" },
+    { file: "architect_sprint_plan.md", label: "Sprint plan", purpose: "Sprint planning and task decomposition" },
+    {
+        file: "architect_sprint_intake.md",
+        label: "Sprint intake",
+        purpose: "Sprint intake and requirements elicitation",
+    },
+];
+// ── Managed section markers ────────────────────────────────────────────────
+const KB_OPEN_PREFIX = "<!-- forge-kb-links";
+const KB_CLOSE = "<!-- /forge-kb-links -->";
+const WF_OPEN_PREFIX = "<!-- forge-workflow-links";
+const WF_CLOSE = "<!-- /forge-workflow-links -->";
+// ── Content generators ─────────────────────────────────────────────────────
+function buildKbSection(cwd, kbPath) {
+    const rows = [
+        { label: "MASTER_INDEX", file: `${kbPath}/MASTER_INDEX.md`, desc: "All sprints, tasks, bugs, and features" },
+        {
+            label: "Architecture",
+            file: `${kbPath}/architecture/INDEX.md`,
+            desc: "Stack, processes, database, routing, deployment",
+        },
+        {
+            label: "Business Domain",
+            file: `${kbPath}/business-domain/INDEX.md`,
+            desc: "Entity model and domain concepts",
+        },
+    ].filter((r) => fs.existsSync(path.join(cwd, r.file)));
+    if (rows.length === 0)
+        return "";
+    const tableRows = rows.map((r) => `| [${r.label}](${r.file}) | ${r.desc} |`).join("\n");
+    return [
+        `<!-- forge-kb-links: managed by Forge — do not edit manually -->`,
+        `## Forge Knowledge Base`,
+        ``,
+        `| Index | Contents |`,
+        `|-------|----------|`,
+        tableRows,
+        ``,
+        `Personas live in \`.forge/personas/\`.`,
+        KB_CLOSE,
+    ].join("\n");
+}
+function buildWorkflowSection(cwd) {
+    const rows = WORKFLOW_ENTRIES.filter((e) => fs.existsSync(path.join(cwd, ".forge", "workflows", e.file)));
+    if (rows.length === 0)
+        return "";
+    const tableRows = rows.map((e) => `| [${e.label}](.forge/workflows/${e.file}) | ${e.purpose} |`).join("\n");
+    return [
+        `<!-- forge-workflow-links: managed by Forge — do not edit manually -->`,
+        `## Forge Workflows`,
+        ``,
+        `| Workflow | Purpose |`,
+        `|----------|---------|`,
+        tableRows,
+        WF_CLOSE,
+    ].join("\n");
+}
+// ── Section replacement ────────────────────────────────────────────────────
+/**
+ * Replace or append a managed section in a file's content.
+ * If the section already exists (detected by open-prefix), replaces it.
+ * Otherwise, appends it to the end.
+ */
+function upsertSection(content, openPrefix, closeMarker, newSection) {
+    if (!newSection)
+        return content; // nothing to inject
+    // Find existing section
+    const openIdx = content.indexOf(openPrefix);
+    if (openIdx !== -1) {
+        const closeIdx = content.indexOf(closeMarker, openIdx);
+        if (closeIdx !== -1) {
+            const endIdx = closeIdx + closeMarker.length;
+            // Replace existing section
+            return content.slice(0, openIdx) + newSection + content.slice(endIdx);
+        }
+    }
+    // Append at end, ensuring a blank line separator
+    const trimmed = content.trimEnd();
+    return trimmed + "\n\n" + newSection + "\n";
+}
+// ── Main exported function ─────────────────────────────────────────────────
+/**
+ * Run the refresh-kb-links operation on the project at `cwd`.
+ *
+ * Returns a result record with counts and human-readable messages.
+ * Never throws — errors are captured as messages.
+ */
+export async function runRefreshKbLinks(cwd) {
+    const result = {
+        filesUpdated: 0,
+        filesSkipped: 0,
+        messages: [],
+    };
+    // Read kbPath from .forge/config.json
+    let kbPath = "engineering";
+    try {
+        const configRaw = fs.readFileSync(path.join(cwd, ".forge", "config.json"), "utf8");
+        const config = JSON.parse(configRaw);
+        const paths = config.paths;
+        if (paths && typeof paths.engineering === "string" && paths.engineering) {
+            kbPath = paths.engineering;
+        }
+    }
+    catch {
+        // Config not present — use default kbPath
+    }
+    const kbSection = buildKbSection(cwd, kbPath);
+    const wfSection = buildWorkflowSection(cwd);
+    if (!kbSection && !wfSection) {
+        result.messages.push("△ refresh-kb-links: no KB or workflow files found to link.");
+        return result;
+    }
+    for (const filename of AGENT_INSTRUCTION_FILES) {
+        const filePath = path.join(cwd, filename);
+        let content;
+        try {
+            content = fs.readFileSync(filePath, "utf8");
+        }
+        catch {
+            // File does not exist — skip
+            result.filesSkipped++;
+            continue;
+        }
+        let updated = content;
+        if (kbSection) {
+            updated = upsertSection(updated, KB_OPEN_PREFIX, KB_CLOSE, kbSection);
+        }
+        if (wfSection) {
+            updated = upsertSection(updated, WF_OPEN_PREFIX, WF_CLOSE, wfSection);
+        }
+        if (updated !== content) {
+            try {
+                fs.writeFileSync(filePath, updated, "utf8");
+                result.filesUpdated++;
+                result.messages.push(`〇 refresh-kb-links: updated ${filename}`);
+            }
+            catch (err) {
+                const e = err;
+                result.messages.push(`△ refresh-kb-links: failed to write ${filename}: ${e.message ?? "unknown"}`);
+            }
+        }
+        else {
+            result.filesSkipped++;
+        }
+    }
+    // Handle .cursor/rules/*.mdc files
+    const cursorRulesDir = path.join(cwd, ".cursor", "rules");
+    if (fs.existsSync(cursorRulesDir)) {
+        try {
+            const mdcFiles = fs.readdirSync(cursorRulesDir).filter((f) => f.endsWith(".mdc"));
+            for (const mdcFile of mdcFiles) {
+                const filePath = path.join(cursorRulesDir, mdcFile);
+                let content;
+                try {
+                    content = fs.readFileSync(filePath, "utf8");
+                }
+                catch {
+                    result.filesSkipped++;
+                    continue;
+                }
+                let updated = content;
+                if (kbSection) {
+                    updated = upsertSection(updated, KB_OPEN_PREFIX, KB_CLOSE, kbSection);
+                }
+                if (wfSection) {
+                    updated = upsertSection(updated, WF_OPEN_PREFIX, WF_CLOSE, wfSection);
+                }
+                if (updated !== content) {
+                    fs.writeFileSync(filePath, updated, "utf8");
+                    result.filesUpdated++;
+                    result.messages.push(`〇 refresh-kb-links: updated .cursor/rules/${mdcFile}`);
+                }
+                else {
+                    result.filesSkipped++;
+                }
+            }
+        }
+        catch {
+            // Skip if unreadable
+        }
+    }
+    return result;
+}
+// ── Handler factory ────────────────────────────────────────────────────────
+/**
+ * Get a standalone refresh-kb-links handler suitable for direct invocation
+ * from Phase 4 step 4-9. Returns a function that takes cwd and calls
+ * runRefreshKbLinks.
+ */
+export function getRefreshKbLinksHandler() {
+    return runRefreshKbLinks;
+}
+//# sourceMappingURL=refresh-kb-links.js.map

package/dist/extensions/forgecli/refresh-kb-links.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"refresh-kb-links.js","sourceRoot":"","sources":["../../../src/extensions/forgecli/refresh-kb-links.ts"],"names":[],"mappings":"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"}

package/dist/extensions/forgecli/store-validator.d.ts

@@ -0,0 +1,13 @@
+export interface StoreValidatorResult {
+    ok: boolean;
+    reason: string;
+}
+/**
+ * Validate a store entity payload by spawning `store-cli.cjs validate`.
+ *
+ * @param entity    Entity type: "task" | "sprint" | "bug" | "event" | …
+ * @param payload   The raw payload (will be JSON.stringify'd if object; passed as-is if string).
+ * @param forgeRoot Absolute path to the Forge plugin root — locates store-cli.cjs.
+ * @returns         `{ ok: true, reason: "" }` on success, `{ ok: false, reason: <stderr> }` on failure.
+ */
+export declare function validateStoreCLIPayload(entity: string, payload: unknown, forgeRoot: string): StoreValidatorResult;

package/dist/extensions/forgecli/store-validator.js

@@ -0,0 +1,35 @@
+// Store-CLI payload validator — FORGE-S18-T03
+//
+// Spawns `store-cli.cjs validate <entity> '<json>'` synchronously and surfaces
+// any schema error as a structured result. This module is the sole point of
+// contact between hook-dispatcher.ts and store-cli's validation logic.
+//
+// Why spawnSync?
+//   pi's tool_call handler is synchronous — the event system does not support
+//   async handlers. spawnSync completes before the block result is returned to pi.
+import { spawnSync } from "node:child_process";
+import * as path from "node:path";
+/**
+ * Validate a store entity payload by spawning `store-cli.cjs validate`.
+ *
+ * @param entity    Entity type: "task" | "sprint" | "bug" | "event" | …
+ * @param payload   The raw payload (will be JSON.stringify'd if object; passed as-is if string).
+ * @param forgeRoot Absolute path to the Forge plugin root — locates store-cli.cjs.
+ * @returns         `{ ok: true, reason: "" }` on success, `{ ok: false, reason: <stderr> }` on failure.
+ */
+export function validateStoreCLIPayload(entity, payload, forgeRoot) {
+    const storeCliPath = path.join(forgeRoot, "tools", "store-cli.cjs");
+    const payloadStr = typeof payload === "string" ? payload : JSON.stringify(payload);
+    const result = spawnSync(process.execPath, // node
+    [storeCliPath, "validate", entity, payloadStr], { encoding: "utf8", timeout: 10_000 });
+    // Non-zero exit code or error signal → validation failed.
+    if (result.status !== 0 || result.error) {
+        const reason = result.stderr?.trim() ||
+            result.error?.message ||
+            `store-cli validate exited with code ${String(result.status)}` ||
+            "validation failed (no error message)";
+        return { ok: false, reason };
+    }
+    return { ok: true, reason: "" };
+}
+//# sourceMappingURL=store-validator.js.map

package/dist/extensions/forgecli/store-validator.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"store-validator.js","sourceRoot":"","sources":["../../../src/extensions/forgecli/store-validator.ts"],"names":[],"mappings":"AAAA,8CAA8C;AAC9C,EAAE;AACF,+EAA+E;AAC/E,4EAA4E;AAC5E,uEAAuE;AACvE,EAAE;AACF,iBAAiB;AACjB,8EAA8E;AAC9E,mFAAmF;AAEnF,OAAO,EAAE,SAAS,EAAE,MAAM,oBAAoB,CAAC;AAC/C,OAAO,KAAK,IAAI,MAAM,WAAW,CAAC;AAOlC;;;;;;;GAOG;AACH,MAAM,UAAU,uBAAuB,CAAC,MAAc,EAAE,OAAgB,EAAE,SAAiB;IAC1F,MAAM,YAAY,GAAG,IAAI,CAAC,IAAI,CAAC,SAAS,EAAE,OAAO,EAAE,eAAe,CAAC,CAAC;IAEpE,MAAM,UAAU,GAAG,OAAO,OAAO,KAAK,QAAQ,CAAC,CAAC,CAAC,OAAO,CAAC,CAAC,CAAC,IAAI,CAAC,SAAS,CAAC,OAAO,CAAC,CAAC;IAEnF,MAAM,MAAM,GAAG,SAAS,CACvB,OAAO,CAAC,QAAQ,EAAE,OAAO;IACzB,CAAC,YAAY,EAAE,UAAU,EAAE,MAAM,EAAE,UAAU,CAAC,EAC9C,EAAE,QAAQ,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM,EAAE,CACrC,CAAC;IAEF,0DAA0D;IAC1D,IAAI,MAAM,CAAC,MAAM,KAAK,CAAC,IAAI,MAAM,CAAC,KAAK,EAAE,CAAC;QACzC,MAAM,MAAM,GACX,MAAM,CAAC,MAAM,EAAE,IAAI,EAAE;YACrB,MAAM,CAAC,KAAK,EAAE,OAAO;YACrB,uCAAuC,MAAM,CAAC,MAAM,CAAC,MAAM,CAAC,EAAE;YAC9D,sCAAsC,CAAC;QACxC,OAAO,EAAE,EAAE,EAAE,KAAK,EAAE,MAAM,EAAE,CAAC;IAC9B,CAAC;IAED,OAAO,EAAE,EAAE,EAAE,IAAI,EAAE,MAAM,EAAE,EAAE,EAAE,CAAC;AACjC,CAAC"}

package/dist/extensions/forgecli/transition-guard.d.ts

@@ -0,0 +1,20 @@
+export interface TransitionGuardResult {
+    allowed: boolean;
+    reason: string;
+}
+export interface TransitionGuardInput {
+    entity: string;
+    entityId: string;
+    toStatus: string;
+}
+/**
+ * Check whether a status transition is legal.
+ *
+ * Fail-open: if the current status cannot be read, returns
+ * `{ allowed: true, reason: "lookup-failed" }`. The caller
+ * should audit-log this outcome but MUST NOT block the operation.
+ *
+ * @param input     Entity, entity ID, and target status.
+ * @param forgeRoot Absolute path to the Forge plugin root.
+ */
+export declare function checkTransition(input: TransitionGuardInput, forgeRoot: string): TransitionGuardResult;

package/dist/extensions/forgecli/transition-guard.js

@@ -0,0 +1,125 @@
+// Status-transition guard — FORGE-S18-T03
+//
+// Encodes the legal status-transition table for each entity (task, sprint, bug)
+// and checks whether a proposed transition is allowed.
+//
+// The guard reads the current status from disk via `store-cli read` (spawnSync).
+// Fail-open: if the current-status lookup fails for any reason, the guard returns
+// { allowed: true } and sets reason="lookup-failed". The caller (hook-dispatcher)
+// logs this as "lookup-failed" under FORGE_HOOK_AUDIT=1 but never blocks the
+// operation — a lookup failure must not block a valid operation.
+import { spawnSync } from "node:child_process";
+import * as path from "node:path";
+// ── Legal transition tables ───────────────────────────────────────────────────
+//
+// Derived from task.schema.json, sprint.schema.json, bug.schema.json status enums.
+// Each entry: fromStatus → Set<toStatus>
+const TASK_TRANSITIONS = {
+    draft: new Set(["planned", "blocked", "escalated", "abandoned"]),
+    planned: new Set(["plan-approved", "plan-revision-required", "blocked", "escalated", "abandoned"]),
+    "plan-approved": new Set(["implementing", "blocked", "escalated", "abandoned"]),
+    implementing: new Set(["implemented", "code-revision-required", "blocked", "escalated", "abandoned"]),
+    implemented: new Set(["review-approved", "blocked", "escalated", "abandoned"]),
+    "review-approved": new Set(["approved", "blocked", "escalated", "abandoned"]),
+    approved: new Set(["committed", "blocked", "escalated", "abandoned"]),
+    "plan-revision-required": new Set(["planned", "blocked", "escalated", "abandoned"]),
+    "code-revision-required": new Set(["implementing", "blocked", "escalated", "abandoned"]),
+    // Terminal / sink states — can only be re-opened by --force.
+    blocked: new Set(["blocked", "escalated", "abandoned"]),
+    escalated: new Set(["blocked", "escalated", "abandoned"]),
+    abandoned: new Set(["blocked", "escalated", "abandoned"]),
+    committed: new Set(["blocked", "escalated", "abandoned"]),
+};
+const SPRINT_TRANSITIONS = {
+    planning: new Set(["active", "abandoned"]),
+    active: new Set(["completed", "partially-completed", "blocked", "abandoned"]),
+    completed: new Set(["retrospective-done"]),
+    "partially-completed": new Set(["retrospective-done"]),
+    "retrospective-done": new Set([]),
+    blocked: new Set(["active", "abandoned"]),
+    abandoned: new Set([]),
+};
+const BUG_TRANSITIONS = {
+    reported: new Set(["triaged", "abandoned"]),
+    triaged: new Set(["in-progress", "abandoned"]),
+    "in-progress": new Set(["fixed", "abandoned"]),
+    fixed: new Set(["verified"]),
+    verified: new Set([]),
+    abandoned: new Set([]),
+};
+const ENTITY_TABLES = {
+    task: TASK_TRANSITIONS,
+    sprint: SPRINT_TRANSITIONS,
+    bug: BUG_TRANSITIONS,
+};
+function legalNextStates(entity, fromStatus) {
+    const table = ENTITY_TABLES[entity];
+    if (!table)
+        return [];
+    const allowed = table[fromStatus];
+    return allowed ? [...allowed] : [];
+}
+// ── Current-status lookup (fail-open) ────────────────────────────────────────
+/**
+ * Read the current status of an entity from the store via `store-cli read`.
+ * Returns the status string on success, or null on any failure (fail-open).
+ */
+function readCurrentStatus(entity, entityId, forgeRoot) {
+    const storeCliPath = path.join(forgeRoot, "tools", "store-cli.cjs");
+    try {
+        const result = spawnSync(process.execPath, [storeCliPath, "read", entity, entityId], {
+            encoding: "utf8",
+            timeout: 10_000,
+        });
+        if (result.status !== 0 || result.error)
+            return null;
+        const stdout = result.stdout?.trim();
+        if (!stdout)
+            return null;
+        // store-cli read emits JSON; parse and extract the status field.
+        const record = JSON.parse(stdout);
+        const status = record.status;
+        return typeof status === "string" ? status : null;
+    }
+    catch {
+        // Any parse error or subprocess error → fail-open.
+        return null;
+    }
+}
+/**
+ * Check whether a status transition is legal.
+ *
+ * Fail-open: if the current status cannot be read, returns
+ * `{ allowed: true, reason: "lookup-failed" }`. The caller
+ * should audit-log this outcome but MUST NOT block the operation.
+ *
+ * @param input     Entity, entity ID, and target status.
+ * @param forgeRoot Absolute path to the Forge plugin root.
+ */
+export function checkTransition(input, forgeRoot) {
+    const { entity, entityId, toStatus } = input;
+    // Lookup current status — fail-open on any error.
+    const fromStatus = readCurrentStatus(entity, entityId, forgeRoot);
+    if (fromStatus === null) {
+        return {
+            allowed: true,
+            reason: "lookup-failed",
+        };
+    }
+    const table = ENTITY_TABLES[entity];
+    if (!table) {
+        // Unknown entity type — allow through (future-proofing).
+        return { allowed: true, reason: "" };
+    }
+    const allowed = table[fromStatus]?.has(toStatus) ?? false;
+    if (allowed) {
+        return { allowed: true, reason: "" };
+    }
+    const legal = legalNextStates(entity, fromStatus);
+    const legalStr = legal.length > 0 ? legal.join(", ") : "(none)";
+    return {
+        allowed: false,
+        reason: `${fromStatus} → ${toStatus} is not a legal transition for ${entity}. Legal next states from ${fromStatus}: ${legalStr}.`,
+    };
+}
+//# sourceMappingURL=transition-guard.js.map

package/dist/extensions/forgecli/transition-guard.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"transition-guard.js","sourceRoot":"","sources":["../../../src/extensions/forgecli/transition-guard.ts"],"names":[],"mappings":"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"}

package/dist/forge-payload/.base-pack/commands/approve.md

@@ -0,0 +1,22 @@
+---
+name: approve
+description: Final architect approval gate for a completed task
+---
+
+# /{{PREFIX}}:approve
+
+Read the approve workflow and follow it.
+
+## Locate the Forge plugin
+
+```
+FORGE_ROOT: !`echo "${CLAUDE_PLUGIN_ROOT}"`
+```
+
+## Execute
+
+Read `.forge/workflows/architect_approve.md` and follow it.
+
+## Arguments
+
+$ARGUMENTS

package/dist/forge-payload/.base-pack/commands/collate.md

@@ -0,0 +1,22 @@
+---
+name: collate
+description: Regenerate KB documents from the JSON store
+---
+
+# /{{PREFIX}}:collate
+
+Read the collate workflow and follow it.
+
+## Locate the Forge plugin
+
+```
+FORGE_ROOT: !`echo "${CLAUDE_PLUGIN_ROOT}"`
+```
+
+## Execute
+
+Read `.forge/workflows/collator_agent.md` and follow it.
+
+## Arguments
+
+$ARGUMENTS

package/dist/forge-payload/.base-pack/commands/commit.md

@@ -0,0 +1,22 @@
+---
+name: commit
+description: Stage and commit completed task artifacts
+---
+
+# /{{PREFIX}}:commit
+
+Read the commit workflow and follow it.
+
+## Locate the Forge plugin
+
+```
+FORGE_ROOT: !`echo "${CLAUDE_PLUGIN_ROOT}"`
+```
+
+## Execute
+
+Read `.forge/workflows/commit_task.md` and follow it.
+
+## Arguments
+
+$ARGUMENTS

package/dist/forge-payload/.base-pack/commands/enhance.md

@@ -0,0 +1,37 @@
+---
+name: enhance
+description: Progressive project-specific enrichment of structural elements
+---
+
+# /{{PREFIX}}:enhance
+
+Run the enhancement agent to enrich structural elements with project-specific knowledge.
+
+## Locate the Forge plugin
+
+```
+FORGE_ROOT: !`echo "${CLAUDE_PLUGIN_ROOT}"`
+```
+
+## Purpose
+
+The enhancement agent observes the project and enriches structural elements
+over time. It makes absolutely essential minimal modifications, preferring
+runtime mix-in (KB references, `{{placeholder}}` substitution, `project-context.json`)
+over modifying base artifacts.
+
+## Behavior
+
+1. Read `structure-versions.json` to determine current overlay level
+2. Read `project-context.json` for current project specifics
+3. Read KB changes since last enhancement
+4. Scan codebase for patterns discovered since last enhancement
+5. Compare current `.forge/` artifacts against base-pack baseline
+6. For each artifact, determine what project-specific enrichment is warranted
+7. Apply the minimal modification principle
+8. Propose diffs (Phase 2+) or auto-apply (Phase 1)
+9. Create new overlay version in `structure-versions.json` if needed
+
+## Arguments
+
+$ARGUMENTS

package/dist/forge-payload/.base-pack/commands/fix-bug.md

@@ -0,0 +1,22 @@
+---
+name: fix-bug
+description: Triage, diagnose, and fix a bug
+---
+
+# /{{PREFIX}}:fix-bug
+
+Read the fix-bug workflow and follow it.
+
+## Locate the Forge plugin
+
+```
+FORGE_ROOT: !`echo "${CLAUDE_PLUGIN_ROOT}"`
+```
+
+## Execute
+
+Read `.forge/workflows/fix_bug.md` and follow it.
+
+## Arguments
+
+$ARGUMENTS

package/dist/forge-payload/.base-pack/commands/implement.md

@@ -0,0 +1,22 @@
+---
+name: implement
+description: Execute the approved implementation plan for a task
+---
+
+# /{{PREFIX}}:implement
+
+Read the implement workflow and follow it.
+
+## Locate the Forge plugin
+
+```
+FORGE_ROOT: !`echo "${CLAUDE_PLUGIN_ROOT}"`
+```
+
+## Execute
+
+Read `.forge/workflows/implement_plan.md` and follow it.
+
+## Arguments
+
+$ARGUMENTS

package/dist/forge-payload/.base-pack/commands/plan.md

@@ -0,0 +1,22 @@
+---
+name: plan
+description: Design and document the implementation plan for a task
+---
+
+# /{{PREFIX}}:plan
+
+Read the plan workflow and follow it.
+
+## Locate the Forge plugin
+
+```
+FORGE_ROOT: !`echo "${CLAUDE_PLUGIN_ROOT}"`
+```
+
+## Execute
+
+Read `.forge/workflows/plan_task.md` and follow it.
+
+## Arguments
+
+$ARGUMENTS

package/dist/forge-payload/.base-pack/commands/quiz-agent.md

@@ -0,0 +1,22 @@
+---
+name: quiz-agent
+description: Verify an agent has loaded and understood the project knowledge base
+---
+
+# /{{PREFIX}}:quiz-agent
+
+Read the quiz-agent workflow and follow it.
+
+## Locate the Forge plugin
+
+```
+FORGE_ROOT: !`echo "${CLAUDE_PLUGIN_ROOT}"`
+```
+
+## Execute
+
+Read `.forge/workflows/quiz_agent.md` and follow it.
+
+## Arguments
+
+$ARGUMENTS