marcos-ai-bootstrap 0.1.3 → 0.1.4

package/README.md

@@ -22,9 +22,11 @@ npx marcos-ai-bootstrap --claude --codex # combine any subset
 npx marcos-ai-bootstrap --all            # every tool at once
 ```
 
-Run it from the root of the repository you want to bootstrap. It writes `AGENTS.md`
-and `HUMAN.md` (the tool-agnostic rules + human guide) alongside
-the agent/skill files for whichever tool(s) you selected:
+Run it from the root of the repository you want to bootstrap. It writes three always-present
+core files—`AGENTS.md`, `HUMAN.md` (the tool-agnostic rules + human guide), and
+`documents/templates/plan-template.md` (an empty scaffold for future implementation plans)—alongside
+the agent/skill files for whichever tool(s) you selected. The Stage-2 planner agents
+(planner-copilot, planner-claude, planner-codex) read the plan template before writing plans.
 
 | Flag | Writes |
 |---|---|
@@ -55,33 +57,30 @@ marcos-ai-bootstrap --all
 
 ## Repository layout
 
-- `src/AGENTS.md`, `src/HUMAN.md` — the **canonical, shipped** copies. These are the source
-  of truth the CLI reads and writes into target repos (as root-level `AGENTS.md`/`HUMAN.md`).
-- `AGENTS.md`, `HUMAN.md` (repo root) — this repository's **own self-hosting** copies, used
-  by the agent network running against this repo. Kept separate from the shipped `src/` copies
-  and not published to npm.
-- `.claude/`, `.codex/`, `.github/`, `.agents/` — the already-materialised, checked-in
-  agent/skill files for this repo itself, and the templates the `marcos-ai-bootstrap` CLI ships
-  and copies into other repositories.
+**Everything the CLI materialises into a target repo is shipped from `src/`; `src/` is the single source of truth.**
+
+**Shipped source of truth files (in `src/`):**
+- `src/AGENTS.md`, `src/HUMAN.md` — canonical agent network and human workflow rules.
+- `src/documents/templates/plan-template.md` — canonical plan template scaffold.
+- `src/.claude/agents/`, `src/.claude/skills/`, `src/.codex/agents/`, `src/.codex/`, `src/.github/agents/`, `src/.github/skills/`, `src/.agents/skills/` — tool agent/skill template files materialised by the CLI.
+
+**Self-hosted copies (repo root) — NOT published to npm:**
+- `AGENTS.md`, `HUMAN.md` (repo root) — this repository's own self-hosted copies, used by the agent network running against this repo.
+- `documents/templates/plan-template.md`, `.claude/`, `.codex/`, `.github/agents/`, `.github/skills/`, `.agents/skills/` — regenerated from `src/` for this repo's own agents (not shipped).
+- `.github/workflows/` — this repo's own CI/CD; not shipped.
+
+**Tooling:**
 - `src/bin/ai-bootstrap.js`, `src/lib/materialize.js` — the CLI implementation.
-- `src/AGENTS-BOOTSTRAP.md` — maintainer-only source of truth for each tool's
-  materialised agent/skill prompt bodies and model tier mappings. The MCP server
-  discovery/policy flow now lives in the **MCP Servers** section of `AGENTS.md` (which
-  is shipped); this file references it. **Not published to npm and not copied into target
-  repos** — the materialised agent/skill files under `.claude/`, `.codex/`, `.github/`,
-  `.agents/` are the shipped source of truth.
-- `src/extract-agents.py` — maintainer tool: regenerates the `.claude/`, `.codex/`,
-  `.github/`, `.agents/` template files at the repo root from `src/AGENTS-BOOTSTRAP.md`
-  after editing it. Run this after changing `src/AGENTS-BOOTSTRAP.md`, then commit the
-  regenerated templates so `marcos-ai-bootstrap` ships the update.
+- `src/AGENTS-BOOTSTRAP.md` — maintainer-only source of truth for each tool's materialised agent/skill prompt bodies and model tier mappings. References the MCP server discovery flow from the shipped `AGENTS.md`. Not published to npm.
+- `src/extract-agents.py` — maintainer tool: regenerates the shipped agent/skill template files under `src/.claude/`, `src/.codex/`, `src/.github/agents/`, `src/.github/skills/`, `src/.agents/skills/` from `src/AGENTS-BOOTSTRAP.md` after editing. Run this after changing `src/AGENTS-BOOTSTRAP.md`.
 
 ## Maintaining this repo
 
 1. Edit `src/AGENTS-BOOTSTRAP.md` (the source of truth for agent/skill prompt bodies).
-2. Run `python src/extract-agents.py` to regenerate the materialised template files.
-3. Run `node src/bin/ai-bootstrap.js --all --dry-run --dest <scratch-dir>` to sanity-check
-   the CLI still packages everything correctly.
-4. Commit the changes.
+2. Run `python src/extract-agents.py` to regenerate the shipped agent/skill templates under `src/.claude/`, `src/.codex/`, `src/.github/agents/`, `src/.github/skills/`, `src/.agents/skills/`.
+3. Run `node src/bin/ai-bootstrap.js --all --force --dest .` to regenerate this repo's root self-hosted copies from `src/`.
+4. Run `node src/bin/ai-bootstrap.js --all --dry-run --dest <scratch-dir>` to sanity-check the CLI packages everything correctly.
+5. Commit the changes.
 
 ## Releasing to npm
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "marcos-ai-bootstrap",
-  "version": "0.1.3",
+  "version": "0.1.4",
   "description": "Materialise the AI-Bootstrap agent/skill network (Claude Code, Codex, GitHub Copilot CLI) into any repository from the command line.",
   "bin": {
     "marcos-ai-bootstrap": "src/bin/ai-bootstrap.js"
@@ -11,11 +11,12 @@
     "src/lib",
     "src/AGENTS.md",
     "src/HUMAN.md",
-    ".claude",
-    ".codex",
-    ".agents",
-    ".github/agents",
-    ".github/skills"
+    "src/documents/templates",
+    "src/.claude",
+    "src/.codex",
+    "src/.agents",
+    "src/.github/agents",
+    "src/.github/skills"
   ],
   "engines": {
     "node": ">=16"

package/{.claude → src/.claude}/agents/planner-claude.md

@@ -11,6 +11,12 @@ You are the planner. You run Stage 2 of the two-stage planning process.
 Take the approved outline from Stage 1 and produce a complete implementation plan written to documents/plans/<YYYYMMDD>-<topic>.md (e.g. documents/plans/20260408-calendar.md).
 Before drafting the plan, check whether any discovered, policy-approved MCP servers are relevant to the task; initialize or use the relevant ones where available, and incorporate what you learn into the plan. Query the server that matches each platform the plan touches (e.g. `azure` for Azure/IAC work, `cloudflare` for Cloudflare Workers/DNS/edge work) and fold its findings into the plan. See the MCP Servers section of `AGENTS.md` for the discovery and policy-check flow.
 
+## Plan template
+Before drafting, read `documents/templates/plan-template.md` and follow its
+section structure exactly (title, metadata block, Goal, Constraints +
+Cross-references, Phases, Open questions, Risks). If the template is missing
+from the target repo, fall back to the "Plan structure" section below.
+
 ## File naming
 - Name the plan file `<YYYYMMDD>-<topic>.md` using today's date with no separators in the date, e.g. `20260408-calendar.md`.
 - Use a short, kebab-case topic slug.

package/{.claude → src/.claude}/agents/planner-discovery-claude.md

@@ -15,6 +15,7 @@ You are the planner-discovery agent. You run Stage 1 of the two-stage planning p
    - High-level phases (name + one-sentence objective each)
    - Open questions still needing user input
    - Proposed plan filename in the form `<YYYYMMDD>-<topic>.md` (e.g. `20260408-calendar.md`) for the planner agent to use.
+   For reference, the final plan will follow the structure in `documents/templates/plan-template.md`.
 4. Present the outline to the user and explicitly ask for approval before Stage 2 begins.
 
 ## Rules

package/{.codex → src/.codex}/agents/planner-codex.toml

@@ -10,6 +10,12 @@ You are the planner. You run Stage 2 of the two-stage planning process.
 Take the approved outline from Stage 1 and produce a complete implementation plan written to documents/plans/<YYYYMMDD>-<topic>.md (e.g. documents/plans/20260408-calendar.md).
 Before drafting the plan, check whether any discovered, policy-approved MCP servers are relevant to the task; initialize or use the relevant ones where available, and incorporate what you learn into the plan. Query the server that matches each platform the plan touches (e.g. `azure` for Azure/IAC work, `cloudflare` for Cloudflare Workers/DNS/edge work) and fold its findings into the plan. See the MCP Servers section of `AGENTS.md` for the discovery and policy-check flow.
 
+## Plan template
+Before drafting, read `documents/templates/plan-template.md` and follow its
+section structure exactly (title, metadata block, Goal, Constraints +
+Cross-references, Phases, Open questions, Risks). If the template is missing
+from the target repo, fall back to the "Plan structure" section below.
+
 ## File naming
 - Name the plan file `<YYYYMMDD>-<topic>.md` using today's date with no separators in the date, e.g. `20260408-calendar.md`.
 - Use a short, kebab-case topic slug.

package/{.codex → src/.codex}/agents/planner-discovery-codex.toml

@@ -14,6 +14,7 @@ You are the planner-discovery agent. You run Stage 1 of the two-stage planning p
    - High-level phases (name + one-sentence objective each)
    - Open questions still needing user input
    - Proposed plan filename in the form `<YYYYMMDD>-<topic>.md` (e.g. `20260408-calendar.md`) for the planner agent to use.
+   For reference, the final plan will follow the structure in `documents/templates/plan-template.md`.
 4. Present the outline to the user and explicitly ask for approval before Stage 2 begins.
 
 ## Rules

package/{.github → src/.github}/agents/planner-copilot.agent.md

@@ -11,6 +11,12 @@ You are the planner-copilot agent. You run Stage 2 of the two-stage planning pro
 Take the approved outline from Stage 1 and produce a complete implementation plan written to documents/plans/<YYYYMMDD>-<topic>.md (e.g. documents/plans/20260408-calendar.md).
 Before drafting the plan, check whether any discovered, policy-approved MCP servers are relevant to the task; initialize or use the relevant ones where available, and incorporate what you learn into the plan. Query the server that matches each platform the plan touches (e.g. `azure` for Azure/IAC work, `cloudflare` for Cloudflare Workers/DNS/edge work) and fold its findings into the plan. See the MCP Servers section of `AGENTS.md` for the discovery and policy-check flow.
 
+## Plan template
+Before drafting, read `documents/templates/plan-template.md` and follow its
+section structure exactly (title, metadata block, Goal, Constraints +
+Cross-references, Phases, Open questions, Risks). If the template is missing
+from the target repo, fall back to the "Plan structure" section below.
+
 ## File naming
 - Name the plan file `<YYYYMMDD>-<topic>.md` using today's date with no separators in the date, e.g. `20260408-calendar.md`.
 - Use a short, kebab-case topic slug.

package/{.github → src/.github}/agents/planner-discovery-copilot.agent.md

@@ -15,6 +15,7 @@ You are the planner-discovery-copilot agent. You run Stage 1 of the two-stage pl
    - High-level phases (name + one-sentence objective each)
    - Open questions still needing user input
    - Proposed plan filename in the form `<YYYYMMDD>-<topic>.md` (e.g. `20260408-calendar.md`) for the planner-copilot agent to use.
+   For reference, the final plan will follow the structure in `documents/templates/plan-template.md`.
 4. Present the outline to the user and explicitly ask for approval before Stage 2 begins.
 
 ## Rules

package/src/documents/templates/plan-template.md

@@ -0,0 +1,47 @@
+# <Plan title>
+
+**Date:** <YYYY-MM-DD>
+**Branch:** <type/YYYYMMDD-topic-slug>
+**Mode:** <planning mode / stage>
+
+## 1. Goal
+
+<!-- One paragraph describing what success looks like when this plan is complete. -->
+
+## 2. Constraints
+
+<!-- Bullet list of guardrails, dependencies, deadlines, and the feature branch name. Never commit to main. -->
+- <constraint>
+
+### Cross-references
+
+<!-- Link related notes under agents/ and existing plans under documents/plans/. -->
+- <path or link>
+
+## 3. Phases
+
+<!-- Ordered phases. Duplicate the block below per phase. Name the specific -copilot/-claude/-codex custom agent. -->
+
+### Phase 1 — <title>
+
+**Objective:** <what this phase achieves>
+
+**Agent:** <docs-copilot | code-copilot | test-runner-copilot | ...>
+
+**Files to change:**
+- <path>
+
+**Design:** <!-- optional: fenced code snippets for load-bearing changes -->
+
+**Acceptance criteria:**
+- <verifiable outcome>
+
+## Open questions
+
+<!-- Anything still needing user input before implementation. -->
+- <question>
+
+## Risks
+
+<!-- Known unknowns or risky assumptions. -->
+- <risk>

package/src/lib/materialize.js

@@ -5,12 +5,25 @@ const path = require("path");
 
 const PACKAGE_ROOT = path.resolve(__dirname, "..", "..");
 
-// Canonical, shipped source-of-truth core files live under src/ so they stay
-// separate from this repo's own self-hosting AGENTS.md/HUMAN.md at the root.
-// Each entry maps the package-relative source to the target-relative destination.
+// Everything the CLI materialises into a target repo ships from a single
+// source-of-truth directory: src/. The destination path is the source path with
+// the leading "src/" stripped (e.g. src/AGENTS.md -> AGENTS.md, src/.github/
+// agents/foo -> .github/agents/foo). This repo's own root-level self-hosting
+// copies (AGENTS.md, .claude/, .github/agents, ...) are generated from these
+// src/ sources and are not themselves published to npm.
+const SRC_DIR = "src";
+
+const toPosix = (p) => p.split(path.sep).join("/");
+
+// Canonical, shipped source-of-truth core files. Each entry maps the
+// package-relative source (under src/) to the target-relative destination.
 const CORE_FILES = [
   { src: "src/AGENTS.md", dest: "AGENTS.md" },
   { src: "src/HUMAN.md", dest: "HUMAN.md" },
+  {
+    src: "src/documents/templates/plan-template.md",
+    dest: "documents/templates/plan-template.md",
+  },
 ];
 
 const TOOLS = {
@@ -123,10 +136,14 @@ function materialize(tools, opts = {}) {
     const tool = TOOLS[toolName];
     if (!tool) continue;
     for (const dir of tool.dirs) {
-      const files = listFiles(path.join(PACKAGE_ROOT, dir));
+      // Sources live under src/<dir>; the destination drops the src/ prefix.
+      const srcDir = path.join(PACKAGE_ROOT, SRC_DIR, dir);
+      const files = listFiles(srcDir);
       for (const abs of files) {
-        const relPath = path.relative(PACKAGE_ROOT, abs);
-        results.push(copyOne(relPath, relPath, destRoot, { force, dryRun }));
+        const rel = toPosix(path.relative(srcDir, abs));
+        const srcRel = path.posix.join(SRC_DIR, toPosix(dir), rel);
+        const destRel = path.posix.join(toPosix(dir), rel);
+        results.push(copyOne(srcRel, destRel, destRoot, { force, dryRun }));
       }
     }
     if (tool.entry) {