@fernado03/zoo-flow 0.3.4 → 0.4.0

package/bin/zoo-flow.js

@@ -80,6 +80,47 @@ function backupIfExists(projectRoot, backupDir, relativePath) {
   return true;
 }
 
+const ZOO_FLOW_GITIGNORE_MARKER = "# Zoo Flow — local context scaffolding";
+
+function appendZooFlowToGitignore(projectRoot) {
+  const gi = path.join(projectRoot, ".gitignore");
+
+  if (pathExists(gi)) {
+    const content = fs.readFileSync(gi, "utf8");
+    if (content.includes(ZOO_FLOW_GITIGNORE_MARKER)) return false;
+    const addition = `\n${ZOO_FLOW_GITIGNORE_MARKER} (never committed)\n.zoo-flow/\n`;
+    fs.appendFileSync(gi, addition);
+    return true;
+  }
+
+  const fresh = `${ZOO_FLOW_GITIGNORE_MARKER} (never committed)\n.zoo-flow/\n`;
+  fs.writeFileSync(gi, fresh);
+  return true;
+}
+
+function migrateRootContextDocs(projectRoot) {
+  const moved = [];
+  const targetFlowDir = path.join(projectRoot, ".zoo-flow");
+  fs.mkdirSync(targetFlowDir, { recursive: true });
+
+  const rootContext = path.join(projectRoot, "CONTEXT.md");
+  const targetContext = path.join(targetFlowDir, "CONTEXT.md");
+  if (pathExists(rootContext) && !pathExists(targetContext)) {
+    fs.copyFileSync(rootContext, targetContext);
+    moved.push("CONTEXT.md");
+  }
+
+  const rootAdr = path.join(projectRoot, "docs", "adr");
+  const targetAdr = path.join(targetFlowDir, "docs", "adr");
+  if (pathExists(rootAdr)) {
+    fs.mkdirSync(targetAdr, { recursive: true });
+    copyRecursive(rootAdr, targetAdr);
+    moved.push("docs/adr/");
+  }
+
+  return moved;
+}
+
 function makeTimestamp() {
   return new Date().toISOString().replace(/[:.]/g, "-");
 }
@@ -265,13 +306,17 @@ Run again with --force to back up and overwrite:
   copyRecursive(sourceRoomodes, targetRoomodes);
   copyRecursive(sourceRoo, targetRoo);
 
+  const didAddGitignore = appendZooFlowToGitignore(projectRoot);
+
   console.log(`
 Zoo Flow installed.
 
 Copied:
   - .roomodes
   - .roo/
-
+  - .zoo-flow/CONTEXT.md
+  - .zoo-flow/docs/adr/0001-record-architecture-decisions.md
+${didAddGitignore ? "  - appended .zoo-flow/ to .gitignore\n" : ""}
 ${didBackup ? `Backup:\n  ${backupDir}\n` : ""}Next:
   1. Reload VS Code
   2. Open Zoo Code
@@ -328,6 +373,12 @@ Run:
   }
 
   if (dryRun) {
+    const rootContext = path.join(projectRoot, "CONTEXT.md");
+    const rootAdr = path.join(projectRoot, "docs", "adr");
+    const wouldMigrate =
+      (pathExists(rootContext) ? ["CONTEXT.md"] : [])
+        .concat(pathExists(rootAdr) ? ["docs/adr/"] : []);
+
     console.log(`
 Zoo Flow update dry run.
 
@@ -336,6 +387,8 @@ ${hasRoomodes ? "  - .roomodes\n" : ""}${hasRoo ? "  - .roo/\n" : ""}
 Would replace with latest template:
   - .roomodes
   - .roo/
+${wouldMigrate.length > 0 ? `\nWould migrate to .zoo-flow/:\n${wouldMigrate.map((p) => `  - ${p}\n`).join("")}` : ""}
+Would append .zoo-flow/ to .gitignore (idempotent).
 
 Run this to update:
   npx @fernado03/zoo-flow@latest update
@@ -356,20 +409,22 @@ Run this to update:
   copyRecursive(sourceRoomodes, targetRoomodes);
   copyRecursive(sourceRoo, targetRoo);
 
+  const moved = migrateRootContextDocs(projectRoot);
+  appendZooFlowToGitignore(projectRoot);
+
   console.log(`
 Zoo Flow updated.
 
 Replaced:
   - .roomodes
   - .roo/
-
-${didBackup ? `Backup:\n  ${backupDir}\n\nTo restore the previous config:\n  rm -rf .roomodes .roo\n  cp -R ${backupDir}/. .\n` : ""}
-Next:
+${moved.length > 0 ? `\nMigrated to .zoo-flow/:\n${moved.map((p) => `  - ${p}\n`).join("")}` : ""}
+${didBackup ? `Backup:\n  ${backupDir}\n\nTo restore the previous config:\n  rm -rf .roomodes .roo\n  cp -R ${backupDir}/. .\n` : ""}Next:
   1. Reload VS Code
   2. Open Zoo Code
   3. Confirm the three custom modes still appear
 `);
-}
+}
 
 if (!command || command === "--help" || command === "-h") {
   console.log(HELP);

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@fernado03/zoo-flow",
   "description": "Workflow control plane for Zoo Code.",
-  "version": "0.3.4",
+  "version": "0.4.0",
   "type": "module",
   "bin": {
     "zoo-flow": "bin/zoo-flow.js"

package/templates/full/.roo/commands/explore.md

@@ -4,7 +4,7 @@ argument-hint: <feature or folder to map>
 mode: system-architect
 ---
 EXECUTION RULES:
-1. READ: `CONTEXT.md`, `CONTEXT-MAP.md`, `docs/adr/`, `FLOW.md`, `ARCHITECTURE.md`, `APP_MAP.md` in target area.
+1. APPLY the slot discovery rule from `.roo/skills/engineering/grill-with-docs/CONTEXT-FORMAT.md` to the target area. Missing slots are not an error. If no slots are populated, output one line before step 2: "No context docs found. Run /grill-with-docs to start CONTEXT.md, or continue without context."
 2. RUN skill: `.roo/skills/engineering/zoom-out/SKILL.md`.
 3. OUTPUT MAP: Create markdown with sections: Domain language, Modules, Data flow, Seams/callers, ADRs, Open questions.
 4. NEXT STEPS: Suggest `/grill-with-docs`, `/feature`, `/refactor`, or `/fix`. DO NOT auto-launch.

package/templates/full/.roo/commands/update-docs.md

@@ -8,6 +8,8 @@ Update repo documentation so it matches the current code. Surgical edits only
 
 Skill: `.roo/skills/engineering/update-docs/SKILL.md`
 
+Apply the slot discovery rule from `.roo/skills/engineering/grill-with-docs/CONTEXT-FORMAT.md` to locate the target doc. If the slot is empty, ask once: "No <slot> found. Create a stub at .zoo-flow/<slot>? (yes / pick-existing / skip)".
+
 Do NOT use this for:
 
 - Domain glossary terms — use `/grill-with-docs`

package/templates/full/.roo/skills/engineering/commit-and-document/SKILL.md

@@ -120,7 +120,18 @@ Date via `date +%Y-%m-%d`. Create `docs/journal/<YYYY-MM-DD>/` if missing. Write
 <Gotchas/follow-ups, one paragraph max. Skip if nothing worth saying.>
 ```
 
-## 7. Confirm
+## 7. Surface stale docs (if any)
+
+Read `git diff --cached --stat`. If any staged path overlaps with a path
+referenced in `.zoo-flow/CONTEXT.md`, `.zoo-flow/ARCHITECTURE.md`,
+`.zoo-flow/APP_MAP.md`, or any nearby `FLOW.md`, output exactly one line
+before "Confirm":
+
+  "Public surface may have drifted. Run /update-docs? (yes / skip)"
+
+On `yes` → suggest `/update-docs <area>`. On `skip` → continue.
+
+## 8. Confirm
 
 Report: commit hash + message, journal entry path, whether `.gitignore` was updated, and any issue actions taken. Close with: "All of `docs/` is gitignored, so this entry stays local."
 

package/templates/full/.roo/skills/engineering/grill-with-docs/CONTEXT-FORMAT.md

@@ -26,29 +26,38 @@ _Avoid_: Purchase, transaction
 - Include domain terms only; exclude generic programming terms.
 - Group under headings when useful.
 
-## Layout
+## Slots
 
-Single-context:
-- `CONTEXT.md`
-- `docs/adr/`
+| Slot | File (if present) | Authored by | Default location |
+|---|---|---|---|
+| Domain language | `CONTEXT.md` | User via /grill-with-docs | `.zoo-flow/CONTEXT.md` |
+| Decisions | `docs/adr/<NNNN-slug>.md` | User via /grill-with-docs | `.zoo-flow/docs/adr/` |
+| Subsystem flow | `FLOW.md` | Subsystem owner | Next to the code |
+| App map | `APP_MAP.md` | User via /update-docs | `.zoo-flow/APP_MAP.md` |
+| Architecture | `ARCHITECTURE.md` | User via /update-docs | `.zoo-flow/ARCHITECTURE.md` |
+| Setup | `README.md` | Project owner | Project root |
 
-Multi-context:
-- `CONTEXT-MAP.md`
-- Per-context `CONTEXT.md` + optional `docs/adr/`
+## Discovery rule (used by /explore, /update-docs, /grill-with-docs)
 
-Detection:
-1. If `CONTEXT-MAP.md`, read map + relevant contexts.
-2. Else if root `CONTEXT.md`, use it.
-3. Else create root `CONTEXT.md` lazily on first resolved term.
-4. If context ambiguous, ask.
+For each slot, in this order:
 
-## Companion docs
+1. If the file exists at the documented location, read it.
+2. If the slot is empty/missing, that is **not an error**. The user has
+   not authored it yet. Do not invent content. Do not lazy-create unless
+   the calling command explicitly says so (e.g. /grill-with-docs on a
+   first resolved term).
+3. If the calling command depends on a populated slot and none exist,
+   surface once: "Slot `<name>` not yet authored. Run /grill-with-docs
+   to fill, or continue without."
 
-Canonical names for code-explanation docs (read by `/explore`, edited by `/update-docs`):
+## Multi-context (rare)
 
-- `FLOW.md` — subsystem flow / data path; lives next to the code it describes.
-- `APP_MAP.md` — app-wide module/navigation map; root-level.
-- `ARCHITECTURE.md` — system-level structure, constraints, seams; root-level.
-- `README.md` — setup and usage; root-level.
+A single project can hold multiple domain contexts when subsystems do
+not share language. Use:
 
-Use these names when creating new docs of these kinds. A subsystem may have its own `FLOW.md`; `APP_MAP.md` and `ARCHITECTURE.md` are typically singular per repo.
+- `.zoo-flow/CONTEXT-MAP.md` — index of contexts.
+- `.zoo-flow/contexts/<slug>/CONTEXT.md` — per-context.
+- `.zoo-flow/contexts/<slug>/docs/adr/` — per-context ADRs.
+
+`/grill-with-docs` and `/explore` consult the map first, then the
+relevant per-context file.

package/templates/full/.zoo-flow/CONTEXT.md

@@ -0,0 +1,8 @@
+# Context
+<!-- Domain language, terms, and ambiguities for this project. Run /grill-with-docs to fill. -->
+
+## Language
+<!-- Term: 1-2 sentence definition. _Avoid_: aliases. -->
+
+## Flagged ambiguities
+<!-- "X means Y, not Z." -->

package/templates/full/.zoo-flow/docs/adr/0001-record-architecture-decisions.md

@@ -0,0 +1,22 @@
+# 1. Record architecture decisions
+
+Date: <YYYY-MM-DD>
+
+## Status
+
+Accepted.
+
+## Context
+
+We need to record significant architectural decisions so future contributors
+(including AI agents) understand why the project is shaped the way it is.
+Use this template: copy the file, rename to `NNNN-slug.md`, fill the three
+sections below.
+
+## Decision
+
+What we chose to do.
+
+## Consequences
+
+What becomes easier. What becomes harder. What we trade away.