marcos-ai-bootstrap 0.1.2 → 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,32 +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, model tier mappings, and MCP server
-  discovery/policy flow. **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.2",
+  "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/{.agents → src/.agents}/skills/initialize/SKILL.md

@@ -7,7 +7,7 @@ You are the initialize orchestrator. Reconcile this repo's agent network with th
 
 ## Phase 1 - MCP server discovery & wiring
 
-1. Run the discovery -> policy-check -> install/verify flow from the "MCP Servers" section of `AGENTS-BOOTSTRAP.md` (Steps 1-4). Inspect repo docs, IAC/config, and dependency manifests to infer the platform footprint and map it to candidate servers.
+1. Run the discovery -> policy-check -> install/verify flow from the "MCP Servers" section of `AGENTS.md` (Steps 1-4). Inspect repo docs, IAC/config, and dependency manifests to infer the platform footprint and map it to candidate servers.
 2. Present the candidate servers to the user. Apply the Step 2 policy check and honour the most restrictive source. Never install a policy-blocked server. Install only servers the user explicitly confirms.
 3. Configure each approved server in `~/.codex/config.toml` (or the project-scoped `.codex`) under `[mcp_servers.<name>]`, then verify with `codex mcp list`.
 4. Wire the approved servers into the agents:

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

@@ -11,7 +11,7 @@ You are the infra agent. You modify infrastructure as code only.
 - Never commit to main. Always work on the branch specified in the task.
 - Never run manual CLI commands (az, aws, gcloud, kubectl) against shared or production environments.
 - All changes must be made in IAC files and applied through the deployment pipeline.
-- Use the discovered, policy-approved MCP servers that match the platform a task touches (e.g. `azure` for Azure/IAC, `cloudflare` for Workers/DNS/edge) plus any read-only docs server for reference material, whenever they are available. See the MCP Servers section for the discovery and policy-check flow.
+- Use the discovered, policy-approved MCP servers that match the platform a task touches (e.g. `azure` for Azure/IAC, `cloudflare` for Workers/DNS/edge) plus any read-only docs server for reference material, whenever they are available. See the MCP Servers section of `AGENTS.md` for the discovery and policy-check flow.
 - Validate IAC (e.g. az bicep build) before declaring done.
 - Delegate documentation updates to the docs agent.
 - Do not change application code — that belongs to the code agent.

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

@@ -9,7 +9,13 @@ You are the planner. You run Stage 2 of the two-stage planning process.
 
 ## Your job
 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 for the discovery and policy-check flow.
+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`.

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/{.claude → src/.claude}/skills/initialize/SKILL.md

@@ -7,7 +7,7 @@ You are the initialize orchestrator. Reconcile this repo's agent network with th
 
 ## Phase 1 — MCP server discovery & wiring
 
-1. Run the discovery → policy-check → install/verify flow from the "MCP Servers" section of `AGENTS-BOOTSTRAP.md` (Steps 1–4). Inspect repo docs, IAC/config, and dependency manifests to infer the platform footprint and map it to candidate servers.
+1. Run the discovery → policy-check → install/verify flow from the "MCP Servers" section of `AGENTS.md` (Steps 1–4). Inspect repo docs, IAC/config, and dependency manifests to infer the platform footprint and map it to candidate servers.
 2. Present the candidate servers to the user. Apply the Step 2 policy check and honour the most restrictive source. Never install a policy-blocked server. Install only servers the user explicitly confirms.
 3. Install each approved server with `claude mcp add <name> -- <command...>` and verify with `claude mcp list`.
 4. Wire the approved servers into the agents:

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

@@ -10,7 +10,7 @@ You are the infra agent. You modify infrastructure as code only.
 - Never commit to main. Always work on the branch specified in the task.
 - Never run manual CLI commands (az, aws, gcloud, kubectl) against shared or production environments.
 - All changes must be made in IAC files and applied through the deployment pipeline.
-- Use the discovered, policy-approved MCP servers that match the platform a task touches (e.g. `azure` for Azure/IAC, `cloudflare` for Workers/DNS/edge) plus any read-only docs server for reference material, whenever they are available. See the MCP Servers section for the discovery and policy-check flow.
+- Use the discovered, policy-approved MCP servers that match the platform a task touches (e.g. `azure` for Azure/IAC, `cloudflare` for Workers/DNS/edge) plus any read-only docs server for reference material, whenever they are available. See the MCP Servers section of `AGENTS.md` for the discovery and policy-check flow.
 - Validate IAC (e.g. az bicep build) before declaring done.
 - Delegate documentation updates to the docs agent.
 - Do not change application code — that belongs to the code agent.

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

@@ -8,7 +8,13 @@ You are the planner. You run Stage 2 of the two-stage planning process.
 
 ## Your job
 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 for the discovery and policy-check flow.
+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`.

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/infra-copilot.agent.md

@@ -11,7 +11,7 @@ You are the infra-copilot agent. You modify infrastructure as code only.
 - Never commit to main. Always work on the branch specified in the task.
 - Never run manual CLI commands (az, aws, gcloud, kubectl) against shared or production environments.
 - All changes must be made in IAC files and applied through the deployment pipeline.
-- Use the discovered, policy-approved MCP servers that match the platform a task touches (e.g. `azure` for Azure/IAC, `cloudflare` for Workers/DNS/edge) plus any read-only docs server for reference material, whenever they are available. See the MCP Servers section for the discovery and policy-check flow.
+- Use the discovered, policy-approved MCP servers that match the platform a task touches (e.g. `azure` for Azure/IAC, `cloudflare` for Workers/DNS/edge) plus any read-only docs server for reference material, whenever they are available. See the MCP Servers section of `AGENTS.md` for the discovery and policy-check flow.
 - Validate IAC (e.g. az bicep build) before declaring done.
 - Delegate documentation updates to the docs-copilot agent.
 - Do not change application code — that belongs to the code-copilot agent.

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

@@ -9,7 +9,13 @@ You are the planner-copilot agent. You run Stage 2 of the two-stage planning pro
 
 ## Your job
 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 for the discovery and policy-check flow.
+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`.

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/{.github → src/.github}/skills/initialize/SKILL.md

@@ -7,7 +7,7 @@ You are the initialize orchestrator. Reconcile this repo's agent network with th
 
 ## Phase 1 — MCP server discovery & wiring
 
-1. Run the discovery → policy-check → install/verify flow from the "MCP Servers" section of `AGENTS-BOOTSTRAP.md` (Steps 1–4). Inspect repo docs, IAC/config, and dependency manifests to infer the platform footprint and map it to candidate servers.
+1. Run the discovery → policy-check → install/verify flow from the "MCP Servers" section of `AGENTS.md` (Steps 1–4). Inspect repo docs, IAC/config, and dependency manifests to infer the platform footprint and map it to candidate servers.
 2. Present the candidate servers to the user. Apply the Step 2 policy check and honour the most restrictive source. Never install a policy-blocked server. Install only servers the user explicitly confirms.
 3. Configure each approved server in `~/.copilot/mcp-config.json` (or the project-scoped equivalent) under `mcpServers`, then verify with `/mcp`.
 4. Wire the approved servers into the agents:

package/src/AGENTS.md

@@ -2,7 +2,7 @@
 
 This file is tool-agnostic. Drop it into any repository and reference it from your AI tool's config entry-point (e.g. `CLAUDE.md` via `@AGENTS.md`, `.github/copilot-instructions.md`, `.opencode/instructions.md`) to immediately apply these rules and bootstrap the agent network.
 
-For tool-specific agent materialisation instructions (file templates, model IDs, config paths), see `AGENTS-BOOTSTRAP.md`.
+The agent and skill files for your specific tool are materialised into the repository by the `marcos-ai-bootstrap` CLI (under `.claude/`, `.codex/`, `.github/`, or `.agents/`). This file is the tool-agnostic source of truth for the rules, the MCP server flow, and the canonical agent/skill roles.
 
 ---
 
@@ -11,8 +11,83 @@ For tool-specific agent materialisation instructions (file templates, model IDs,
 At the start of every session:
 1. Confirm this file has been read.
 2. Identify which tool you are running under.
-3. Follow the bootstrap instructions in `AGENTS-BOOTSTRAP.md` for that tool to verify the agent network **and the skill network** are fully materialised. Create any missing agents or skills before starting any other work.
-4. Discover, policy-check, and configure the applicable **MCP servers** as described in the MCP Servers section of `AGENTS-BOOTSTRAP.md`. Use MCP servers wherever applicable — prefer them for authoritative, live platform access (e.g. Azure, Cloudflare) over guessing or stale knowledge, subject to organization policy.
+3. Verify the agent network **and the skill network** for that tool are present — the materialised agent/skill files under `.claude/`, `.codex/`, `.github/`, or `.agents/`. If any are missing, re-run the `marcos-ai-bootstrap` CLI for your tool to restore them before starting any other work.
+4. Discover, policy-check, and configure the applicable **MCP servers** as described in the [MCP Servers](#mcp-servers) section below. Use MCP servers wherever applicable — prefer them for authoritative, live platform access (e.g. Azure, Cloudflare) over guessing or stale knowledge, subject to organization policy.
+
+---
+
+## MCP Servers
+
+MCP servers give the infra and planner agents authoritative, live access to the platforms a project actually uses. Rather than hardcoding a fixed list, the bootstrap **discovers** which servers are applicable to the current repository and **respects organization policy** on what may be installed. At the start of every session, after confirming the agent network is present, run the discovery → policy-check → install/verify flow below.
+
+### Step 1 — Discover applicable servers
+
+Infer the project's platform footprint before installing anything. Inspect, in order:
+
+1. **Repository docs** — root `README.md`, service-level `README.md` files, `CLAUDE.md` / `AGENTS.md`, `docs/`, and `documents/plans/`. Look for named platforms and tooling (e.g. Azure, Cloudflare, AWS, GCP, GitHub, PostgreSQL, Stripe, Sentry).
+2. **IAC and config** — `*.bicep`, `*.tf`, `wrangler.toml`, `docker-compose*.yml`, pipeline YAML under `.github/workflows/` or `.azure/`, and environment-variable tables. These reveal the deploy targets an infra agent will touch.
+3. **Dependency manifests** — `package.json`, provider SDKs, and CLIs already vendored in the repo.
+
+Map the footprint to candidate MCP servers. Common mappings (extend as the ecosystem grows):
+
+| Signal in repo | Candidate MCP server | Package / endpoint |
+|---|---|---|
+| Azure services, Bicep, `az`, `DefaultAzureCredential` | `azure` | `npx -y @azure/mcp@latest server start` |
+| Azure/Microsoft docs reference need | `microsoft-learn` (read-only docs) | hosted — `https://learn.microsoft.com/api/mcp` |
+| Cloudflare Workers, `wrangler.toml`, DNS/edge | `cloudflare` | `npx -y mcp-remote https://docs.mcp.cloudflare.com/sse` (docs); other Cloudflare servers use `https://<name>.mcp.cloudflare.com/sse` |
+| GitHub-centric workflows / PR automation | `github` | `npx -y @modelcontextprotocol/server-github` |
+
+If the repo shows no clear signal for a platform, **do not install its server** — surface it as a suggestion to the user instead of adding it silently.
+
+### Step 2 — Check organization policy
+
+Before installing any discovered server, confirm it is permitted. Check, in order, and honour the most restrictive:
+
+1. **Repo-scoped allowlist** — an `mcp-allowlist` / `mcp-policy` entry in `AGENTS.md`, a `.mcp-policy.json` / `.mcp-allowed.json` file at the repo root, or an `mcp` section in the tool's project config.
+2. **Tool/user-scoped policy** — the tool's own managed-settings or enterprise policy (e.g. Claude Code managed settings, Copilot org policy, Codex config). If a tool exposes an allowed/blocked MCP list, treat it as authoritative.
+3. **Explicit user confirmation** — if no policy source exists, list the servers you intend to install and ask the user to confirm before adding any that require network access or credentials.
+
+Never install a server that policy blocks. If a needed server is blocked, note the limitation to the user and continue without it.
+
+### Step 3 — Which agents use them
+
+- **infra agents** (`infra-claude`, `infra-copilot`, `infra-codex`) — use the discovered, policy-approved servers matching the platform a task touches (e.g. `azure` for Bicep, `cloudflare` for Workers/DNS), alongside any read-only docs server for reference material.
+- **planner agents** (`planner-claude`, `planner-copilot`, `planner-codex`) — check which approved servers are relevant to the plan, query them, and fold the findings into the plan.
+
+### Step 4 — Verify and install per tool
+
+Install only servers that passed Steps 1–2. Substitute the discovered server name/package for the `<name>` / `<package>` placeholders.
+
+**Claude Code** — check with `claude mcp list`, then:
+
+```powershell
+claude mcp add <name> -- <command...>
+# e.g. claude mcp add azure -- npx -y @azure/mcp@latest server start
+```
+
+**GitHub Copilot CLI** — configure in `~/.copilot/mcp-config.json` (or project-scoped equivalent), verify with `/mcp`:
+
+```json
+{
+  "mcpServers": {
+    "<name>": { "command": "npx", "args": ["-y", "<package>", "..."] }
+  }
+}
+```
+
+**Codex** — configure in `~/.codex/config.toml` (or project-scoped `.codex`), verify with `codex mcp list`:
+
+```toml
+[mcp_servers.<name>]
+command = "npx"
+args = ["-y", "<package>", "..."]
+```
+
+### Notes
+
+- The Azure MCP server authenticates with your existing Azure credential chain (Azure CLI login / managed identity / `DefaultAzureCredential`). Ensure you are signed in before relying on it.
+- Cloudflare remote servers prompt for OAuth authorization on first connect via `mcp-remote`.
+- Never let an MCP server perform manual mutating operations against shared or production environments — the infra guardrails (all changes go through IAC and pipelines) still apply. Use these servers for reference, inspection, and planning.
 
 ---
 
@@ -29,7 +104,7 @@ At the start of every session:
 
 ## Skills
 
-Skills are reusable, user-invocable orchestration workflows (slash commands) that drive the agent network. They are tool-specific in how they are materialised — see `AGENTS-BOOTSTRAP.md` for file templates, paths, and discovery rules for your tool.
+Skills are reusable, user-invocable orchestration workflows (slash commands) that drive the agent network. The `marcos-ai-bootstrap` CLI materialises them for your tool (e.g. `.claude/skills/`, `.github/skills/`, `.agents/skills/`).
 
 Canonical skills:
 
@@ -97,7 +172,7 @@ Canonical skills:
 
 ## Agent Network
 
-These are the canonical agent roles. They are defined here without tool-specific syntax. See `AGENTS-BOOTSTRAP.md` for how to materialise them in your specific tool.
+These are the canonical agent roles. They are defined here without tool-specific syntax. The `marcos-ai-bootstrap` CLI materialises them for your specific tool.
 
 Model tiers used below:
 - **High** — most capable; use for planning and complex cross-file reasoning (e.g. Opus-class)

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) {