@structured-vibe-coding/core 0.5.3 → 0.6.0

package/README.md

@@ -30,7 +30,7 @@ const change = await createChange({
 await advanceStage(root, config, change.id);
 ```
 
-See the [repository README](https://github.com/structured-vibe-coding/spec-driven-development) for workflows, customization, and CLI docs.
+See the [docs hub](https://github.com/structured-vibe-coding/spec-driven-development/blob/main/docs/README.md) and [repository README](https://github.com/structured-vibe-coding/spec-driven-development) for workflows, customization, and CLI docs.
 
 ## License
 

package/defaults/memory/index.md

@@ -0,0 +1,36 @@
+# Documentation map
+
+Parent page for **stable** project docs. Humans and coding agents: start here, then open only what you need.
+
+| Kind | Where | Lifetime |
+|------|--------|----------|
+| **This map + memory** | `memory/*.md` | Long-lived |
+| **Active change** | `changes/<id>/` (see `.sdd/active-context.md`) | Until complete |
+| **Finished work** | `archive/<id>/` | History |
+| **Optional domains** | `domains/` | Long-lived by area |
+
+## Stable docs
+
+| Topic | File |
+|-------|------|
+| Product / vision | [product.md](product.md) |
+| Architecture | [architecture.md](architecture.md) |
+| Coding & process conventions | [conventions.md](conventions.md) |
+
+Add rows here when you introduce new durable docs (e.g. `security.md`, `ops.md`).
+
+## Active work
+
+1. Run `sdd status` (or open `.sdd/active-context.md`).
+2. Read stage artifacts under the active change folder only.
+3. Prefer small updates to change packs; **promote** lasting decisions into `memory/` after `sdd complete`.
+
+## Ownership (suggested)
+
+| Area | Owner |
+|------|--------|
+| `memory/*` | Tech lead / architect |
+| Current `changes/<id>/` | Author of the change (PR owner) |
+| `domains/<name>/` | Domain owner (if used) |
+
+Keep this map short. Link out; do not paste large designs here.

package/dist/{agents-5YI2CWAB.js → agents-O5ABMQJQ.js}

@@ -14,7 +14,7 @@ import {
   parseIntegration,
   refreshActiveAgentContext,
   renderThinAgent
-} from "./chunk-CHDYZIOH.js";
+} from "./chunk-QTHYRKMK.js";
 export {
   AGENT_INTEGRATIONS,
   AGENT_TARGET_OPTIONS,

package/dist/{chunk-CHDYZIOH.js → chunk-QTHYRKMK.js}

@@ -594,6 +594,7 @@ async function buildAgentPrompt(ctx, config, projectRoot) {
   parts.push("");
   parts.push(`## Artifacts to read`);
   const memoryHint = join3(projectRoot, config.memory_path);
+  parts.push(`- Documentation map (if present): ${memoryHint}/index.md`);
   parts.push(`- Memory: ${memoryHint}/`);
   for (const s of ctx.stages) {
     for (const a of s.artifacts) {
@@ -638,6 +639,20 @@ var AGENT_INTEGRATIONS = [
     installUrl: "https://docs.anthropic.com/en/docs/claude-code",
     rolePath: (roleId) => `.claude/agents/${roleId}.md`,
     agentsMdRow: "| Claude Code | `.claude/agents/` (`sdd`, `sdd-planner`, `sdd-implementer`, `sdd-reviewer`) |"
+  },
+  {
+    id: "grok",
+    key: "grok",
+    aliases: ["grok-build", "grokbuild", "xai", "xai-grok"],
+    label: "Grok Build",
+    hint: ".grok/rules/sdd.md + AGENTS.md (terminal TUI from xAI)",
+    requiresCli: false,
+    cliBinary: "grok",
+    installUrl: "https://docs.x.ai",
+    // Single rules file: Grok auto-loads all .grok/rules/*.md
+    rolePath: () => `.grok/rules/sdd.md`,
+    rolesToInstall: ["sdd"],
+    agentsMdRow: "| Grok Build | `.grok/rules/sdd.md` + `AGENTS.md` (reads protocol + active-context; run `sdd` in shell) |"
   }
 ];
 var ALL_AGENT_TARGETS = AGENT_INTEGRATIONS.map((i) => i.id);
@@ -680,7 +695,7 @@ function parseIntegration(raw) {
   }
   if (IDE_NAMES.has(p)) {
     throw new Error(
-      `"${p}" is an IDE, not an AI coding agent. Choose: copilot or claude (Claude Code).`
+      `"${p}" is an IDE, not an AI coding agent. Choose: ${AGENT_INTEGRATIONS.map((i) => i.key).join(", ")}.`
     );
   }
   for (const integ of AGENT_INTEGRATIONS) {
@@ -760,7 +775,8 @@ async function installAgentIntegration(opts) {
   };
   await write(join4(".sdd", "protocol.md"), PROTOCOL_MD);
   await refreshActiveAgentContext(root);
-  for (const role of SDD_AGENT_ROLES) {
+  const roles = integ.rolesToInstall?.length ? SDD_AGENT_ROLES.filter((r) => integ.rolesToInstall.includes(r.id)) : SDD_AGENT_ROLES;
+  for (const role of roles) {
     await write(integ.rolePath(role.id), renderThinAgent(role));
   }
   await write("AGENTS.md", renderAgentsMd(integ));
@@ -885,7 +901,7 @@ This repo uses **Structured Vibe Coding** (\`sdd\`). Agents must follow this fil
 |------|--------|
 | Process state | \`changes/<id>/meta.yaml\` (workflow, stage, gates) |
 | Current task snapshot | \`.sdd/active-context.md\` |
-| Stable product/tech rules | \`memory/*.md\` |
+| Stable product/tech rules | \`memory/*.md\` (start at \`memory/index.md\` if present) |
 | Stage artifacts | files in \`changes/<id>/\` for the active change |
 
 ## Required read order
@@ -893,7 +909,7 @@ This repo uses **Structured Vibe Coding** (\`sdd\`). Agents must follow this fil
 1. \`.sdd/active-context.md\`
 2. This file (\`.sdd/protocol.md\`)
 3. \`meta.yaml\` + artifacts for the **current stage** (and prior stages if needed)
-4. \`memory/\` when architecture or conventions matter
+4. \`memory/index.md\` (documentation map) if present, then linked memory pages when architecture or conventions matter
 
 ## Stage behavior
 
@@ -941,6 +957,7 @@ AI coding agents are **not** the same as IDEs: VS Code, Cursor, and IntelliJ hos
 |------------|--|
 | Live task | \`.sdd/active-context.md\` |
 | Playbook | \`.sdd/protocol.md\` |
+| Doc map (stable) | \`memory/index.md\` if present |
 
 | AI agent | Files |
 |----------|--------|

package/dist/index.d.ts

@@ -1161,9 +1161,9 @@ declare function completeChange(projectRoot: string, config: Config, changeId: s
 
 /**
  * AI coding agents (not IDEs).
- * Speckit-style: one integration at a time; public keys are short (`copilot`, `claude`).
+ * Speckit-style: one integration at a time; public keys: `copilot` | `claude` | `grok`.
  */
-type AgentTarget = "copilot" | "claude-code";
+type AgentTarget = "copilot" | "claude-code" | "grok";
 /** Registry entry — add a new AI agent by appending here only. */
 interface AgentIntegration {
     id: AgentTarget;
@@ -1178,6 +1178,12 @@ interface AgentIntegration {
     cliBinary?: string;
     /** Relative path for a thin role agent file. */
     rolePath: (roleId: string) => string;
+    /**
+     * Which thin roles to install. Default: all SDD_AGENT_ROLES.
+     * Grok loads every `*.md` under `.grok/rules/`, so only install the router
+     * role there to avoid conflicting planner/implementer instructions.
+     */
+    rolesToInstall?: SddAgentRoleId[];
     /** One markdown table row for AGENTS.md. */
     agentsMdRow: string;
 }
@@ -1245,7 +1251,7 @@ declare function renderThinAgent(role: SddAgentRole): string;
 /** Write .sdd/active-context.md for the current change. */
 declare function refreshActiveAgentContext(projectRoot: string): Promise<string | null>;
 /** Single playbook — only long agent-facing content we author once. */
-declare const PROTOCOL_MD = "# SDD protocol\n\nThis repo uses **Structured Vibe Coding** (`sdd`). Agents must follow this file plus `.sdd/active-context.md`. Do not invent a parallel process.\n\n## Source of truth\n\n| What | Where |\n|------|--------|\n| Process state | `changes/<id>/meta.yaml` (workflow, stage, gates) |\n| Current task snapshot | `.sdd/active-context.md` |\n| Stable product/tech rules | `memory/*.md` |\n| Stage artifacts | files in `changes/<id>/` for the active change |\n\n## Required read order\n\n1. `.sdd/active-context.md`\n2. This file (`.sdd/protocol.md`)\n3. `meta.yaml` + artifacts for the **current stage** (and prior stages if needed)\n4. `memory/` when architecture or conventions matter\n\n## Stage behavior\n\n| Stage kind | Agent focus |\n|------------|-------------|\n| intent / feature / stories | Clarify scope; write short artifacts |\n| design / lld / db / research / hl_arb | Specs and decisions; minimal product code |\n| tasks | Break work into implementable checklist |\n| implement | Code only for this change; follow tasks/acceptance |\n| local_verify | Check acceptance; fix only; prepare for complete |\n\n## Hard rules\n\n1. **Do not skip hard gates.** If blocked, tell the human to run `sdd gate approve` (or fix the gate).\n2. **Stay in scope** of the active change title/intent. No drive-by refactors or new features.\n3. **Honor constraints** in `arb-decision.md`, design, and memory non-negotiables.\n4. **Local verify** is part of done when the workflow has a verify stage: `sdd verify`.\n5. Prefer small, reviewable diffs.\n\n## Commands (human / shell)\n\n```bash\nsdd status\nsdd next\nsdd agent              # print handoff\nsdd agents refresh     # refresh active-context.md\nsdd verify\nsdd complete\n```\n\n## Out of scope for agents\n\n- Replacing CI/CD or team process tools\n- Deleting `.sdd` / archive history\n- Claiming complete without verify when required\n";
+declare const PROTOCOL_MD = "# SDD protocol\n\nThis repo uses **Structured Vibe Coding** (`sdd`). Agents must follow this file plus `.sdd/active-context.md`. Do not invent a parallel process.\n\n## Source of truth\n\n| What | Where |\n|------|--------|\n| Process state | `changes/<id>/meta.yaml` (workflow, stage, gates) |\n| Current task snapshot | `.sdd/active-context.md` |\n| Stable product/tech rules | `memory/*.md` (start at `memory/index.md` if present) |\n| Stage artifacts | files in `changes/<id>/` for the active change |\n\n## Required read order\n\n1. `.sdd/active-context.md`\n2. This file (`.sdd/protocol.md`)\n3. `meta.yaml` + artifacts for the **current stage** (and prior stages if needed)\n4. `memory/index.md` (documentation map) if present, then linked memory pages when architecture or conventions matter\n\n## Stage behavior\n\n| Stage kind | Agent focus |\n|------------|-------------|\n| intent / feature / stories | Clarify scope; write short artifacts |\n| design / lld / db / research / hl_arb | Specs and decisions; minimal product code |\n| tasks | Break work into implementable checklist |\n| implement | Code only for this change; follow tasks/acceptance |\n| local_verify | Check acceptance; fix only; prepare for complete |\n\n## Hard rules\n\n1. **Do not skip hard gates.** If blocked, tell the human to run `sdd gate approve` (or fix the gate).\n2. **Stay in scope** of the active change title/intent. No drive-by refactors or new features.\n3. **Honor constraints** in `arb-decision.md`, design, and memory non-negotiables.\n4. **Local verify** is part of done when the workflow has a verify stage: `sdd verify`.\n5. Prefer small, reviewable diffs.\n\n## Commands (human / shell)\n\n```bash\nsdd status\nsdd next\nsdd agent              # print handoff\nsdd agents refresh     # refresh active-context.md\nsdd verify\nsdd complete\n```\n\n## Out of scope for agents\n\n- Replacing CI/CD or team process tools\n- Deleting `.sdd` / archive history\n- Claiming complete without verify when required\n";
 
 interface InitOptions {
     projectRoot: string;

package/dist/index.js

@@ -73,7 +73,7 @@ import {
   workflowsDir,
   writeText,
   writeYaml
-} from "./chunk-CHDYZIOH.js";
+} from "./chunk-QTHYRKMK.js";
 
 // src/change.ts
 import { join as join2 } from "pathe";
@@ -185,7 +185,7 @@ async function createChange(input) {
   await materializeStageArtifacts(projectRoot, config, id, workflow, meta, firstStage);
   await setActiveChange(projectRoot, config, id);
   try {
-    const { refreshActiveAgentContext: refreshActiveAgentContext2 } = await import("./agents-5YI2CWAB.js");
+    const { refreshActiveAgentContext: refreshActiveAgentContext2 } = await import("./agents-O5ABMQJQ.js");
     await refreshActiveAgentContext2(projectRoot);
   } catch {
   }
@@ -281,7 +281,7 @@ async function advanceStage(projectRoot, config, changeId, opts) {
     stage
   );
   try {
-    const { refreshActiveAgentContext: refreshActiveAgentContext2 } = await import("./agents-5YI2CWAB.js");
+    const { refreshActiveAgentContext: refreshActiveAgentContext2 } = await import("./agents-O5ABMQJQ.js");
     await refreshActiveAgentContext2(projectRoot);
   } catch {
   }
@@ -478,6 +478,21 @@ async function initProject(opts) {
   if (await pathExists(mSrc)) {
     await copyDir(mSrc, mDest);
   } else {
+    await writeText(
+      join4(mDest, "index.md"),
+      `# Documentation map
+
+Parent page for **stable** project docs. Start here, then open only what you need.
+
+| Topic | File |
+|-------|------|
+| Product | [product.md](product.md) |
+| Architecture | [architecture.md](architecture.md) |
+| Conventions | [conventions.md](conventions.md) |
+
+Active work: \`.sdd/active-context.md\` and \`changes/<id>/\`.
+`
+    );
     await writeText(
       join4(mDest, "product.md"),
       "# Product\n\n<!-- What are you building? -->\n"
@@ -512,9 +527,13 @@ This directory configures local Spec-Driven Development for this repo.
 - \`config.yaml\` \u2014 project settings and per-change policy
 - \`workflows/\` \u2014 YAML workflow packs (customize freely)
 - \`templates/\` \u2014 markdown templates for stage artifacts
+- \`protocol.md\` / \`active-context.md\` \u2014 agent playbook + live task (after agent install)
 
 Work lives in \`../changes/\` and completed work in \`../archive/\`.
 
+**Documentation map (stable):** \`../memory/index.md\`  
+**Change-scoped docs:** \`../changes/<id>/\`
+
 ## Quick commands
 
 \`\`\`bash

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@structured-vibe-coding/core",
-  "version": "0.5.3",
+  "version": "0.6.0",
   "description": "Core engine for structured vibe coding (local-first Spec-Driven Development)",
   "type": "module",
   "main": "./dist/index.js",