@structured-vibe-coding/core 0.5.3 → 0.5.4

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-4Z3YZRUK.js}

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

package/dist/{chunk-CHDYZIOH.js → chunk-I45MAHM6.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) {
@@ -885,7 +886,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 +894,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 +942,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

@@ -1245,7 +1245,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-I45MAHM6.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-4Z3YZRUK.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-4Z3YZRUK.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.5.4",
   "description": "Core engine for structured vibe coding (local-first Spec-Driven Development)",
   "type": "module",
   "main": "./dist/index.js",