marcos-ai-bootstrap 0.1.4 → 0.1.5

package/README.md

@@ -23,16 +23,18 @@ npx marcos-ai-bootstrap --all            # every tool at once
 ```
 
 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
+core files—`MARCOS-AI-BOOTSTRAP.md`, `HUMAN.md` (the full 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
+the agent/skill files for whichever tool(s) you selected, and appends an `@MARCOS-AI-BOOTSTRAP.md`
+include to your tool's instruction file (creating it only if absent, never overwriting existing content).
+The Stage-2 planner agents
 (planner-copilot, planner-claude, planner-codex) read the plan template before writing plans.
 
 | Flag | Writes |
 |---|---|
-| `--claude` | `.claude/agents/*.md`, `.claude/skills/**/SKILL.md`, `CLAUDE.md` (`@AGENTS.md` stub) |
-| `--codex` | `.codex/agents/*.toml`, `.agents/skills/**/SKILL.md` |
-| `--copilot` | `.github/agents/*.agent.md`, `.github/skills/**/SKILL.md`, `.github/copilot-instructions.md` |
+| `--claude` | `.claude/agents/*.md`, `.claude/skills/**/SKILL.md`, `CLAUDE.md` (append `@MARCOS-AI-BOOTSTRAP.md` include) |
+| `--codex` | `.codex/agents/*.toml`, `.agents/skills/**/SKILL.md`, `AGENTS.md` (append `@MARCOS-AI-BOOTSTRAP.md` include) |
+| `--copilot` | `.github/agents/*.agent.md`, `.github/skills/**/SKILL.md`, `.github/copilot-instructions.md` (append `@../MARCOS-AI-BOOTSTRAP.md` include) |
 | `--all` | all of the above |
 
 ### Options
@@ -60,27 +62,26 @@ marcos-ai-bootstrap --all
 **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/MARCOS-AI-BOOTSTRAP.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.
+- `MARCOS-AI-BOOTSTRAP.md`, `HUMAN.md` (repo root) — this repository's own self-hosted rules copies, used by the agent network running against this repo. The root `AGENTS.md`, `CLAUDE.md`, and `.github/copilot-instructions.md` are thin entry-points that `@`-include `MARCOS-AI-BOOTSTRAP.md`.
 - `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. 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`.
+- `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 `MARCOS-AI-BOOTSTRAP.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`, then syncs this repo's root self-hosted copies from `src/` (unless `--src-only` is passed). 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 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.
+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/` **and** sync this repo's root self-hosted copies from `src/` (it invokes the CLI for you). Pass `--src-only` to write `src/` alone.
+3. Run `node src/bin/ai-bootstrap.js --all --dry-run --dest <scratch-dir>` to sanity-check the CLI packages everything correctly.
+4. Commit the changes.
 
 ## Releasing to npm
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "marcos-ai-bootstrap",
-  "version": "0.1.4",
+  "version": "0.1.5",
   "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"
@@ -9,7 +9,7 @@
   "files": [
     "src/bin",
     "src/lib",
-    "src/AGENTS.md",
+    "src/MARCOS-AI-BOOTSTRAP.md",
     "src/HUMAN.md",
     "src/documents/templates",
     "src/.claude",

package/src/.agents/skills/initialize/SKILL.md

@@ -1,13 +1,25 @@
 ---
 name: initialize
-description: One-time environment reconciliation. Discovers applicable MCP servers and, with user approval, installs and wires them into the infra/planner agents; discovers where plan documents actually live and, after user confirmation, wires the planner/implement/docs agents to that location; then verifies every agent's configured model exists in Codex and, for any missing model, prompts the user to pick the closest available match and rewrites the agent files. Never commits.
+description: One-time environment reconciliation. First wires this tool's instruction file to the shipped MARCOS-AI-BOOTSTRAP.md rules (appending an @-include, never overwriting; creating the file if absent). Discovers applicable MCP servers and, with user approval, installs and wires them into the infra/planner agents; discovers where plan documents actually live and, after user confirmation, wires the planner/implement/docs agents to that location; then always prompts the user to choose the model for each tier/role (pre-selecting the current model, or the closest available match when it is unavailable) and rewrites the agent files. Never commits.
 ---
 
-You are the initialize orchestrator. Reconcile this repo's agent network with the current environment in three phases. This skill only edits agent and skill files and MCP config; it never touches source code and never commits.
+You are the initialize orchestrator. Reconcile this repo's agent network with the current environment in the phases below. This skill only edits agent and skill files, the tool's instruction entry-point, and MCP config; it never touches source code and never commits.
+
+## Phase 0 - Rules-file include wiring
+
+The full agent rules ship as `MARCOS-AI-BOOTSTRAP.md` at the repo root. Ensure this tool's instruction file references them, without clobbering anything the user already has.
+
+1. Locate the instruction file: `AGENTS.md`.
+2. If it exists and already references `MARCOS-AI-BOOTSTRAP.md`, leave it untouched.
+3. If it exists but does not reference it, APPEND (never overwrite) a short block:
+   > # Marcos AI-Bootstrap
+   >
+   > This repository uses the Marcos AI-Bootstrap agent/skill network. See `@MARCOS-AI-BOOTSTRAP.md` for the agent rules, the MCP server flow, and the canonical agent/skill roles.
+4. If it does not exist, create it containing that block.
 
 ## Phase 1 - MCP server discovery & wiring
 
-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.
+1. Run the discovery -> policy-check -> install/verify flow from the "MCP Servers" section of `MARCOS-AI-BOOTSTRAP.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:
@@ -19,9 +31,9 @@ You are the initialize orchestrator. Reconcile this repo's agent network with th
 
 1. Enumerate the models Codex currently exposes. Build the set of available model IDs.
 2. For each file in `.codex/agents/*.toml`, read the `model = "..."` value and its intended tier (High / Standard / Fast) from the tier table below.
-3. For every `model` value that is NOT in the available set:
-   - Determine the closest available match - prefer another model in the same tier/family, else the next tier down, else the nearest capability.
-   - Use a dropdown prompt (multiple choice) listing the available models, pre-selecting the closest match, and ask the user to confirm the replacement for that tier.
+3. For every tier (High / Standard / Fast), ALWAYS prompt the user to choose the model - even when the currently configured model is available:
+   - Pick the pre-selected default: the currently configured model if it is in the available set; otherwise the closest available match - prefer another model in the same tier/family, else the next tier down, else the nearest capability.
+   - Use a dropdown prompt (multiple choice) listing every available model, pre-selecting the default from the previous step, and ask the user to confirm or change the model for that tier.
    - Rewrite the agent file's `model = "..."` line with the chosen model. Apply the same choice to every agent sharing that tier so the default profile stays consistent.
 4. Report the final tier -> model mapping and the list of edited files.
 
@@ -46,5 +58,5 @@ You are the initialize orchestrator. Reconcile this repo's agent network with th
 - Never install an MCP server that policy blocks or that the user has not approved.
 - Never let an MCP server perform mutating operations against shared or production environments; the infra guardrails still apply.
 - Never change the plans location without explicit user confirmation.
-- Only edit files under `.codex/agents/`, `.agents/skills/`, and the tool's MCP config. Do not modify source code.
-- Idempotent: re-running makes no changes when servers are already wired, the plans location already matches, and every configured model is available.
+- Only edit files under `.codex/agents/`, `.agents/skills/`, the tool's instruction entry-point (`AGENTS.md`), and the tool's MCP config. Do not modify source code.
+- Idempotent for MCP wiring and the plans location: re-running makes no changes when servers are already wired and the plans location already matches. Model selection is always offered - re-running re-prompts for each tier, but keeping the current selection leaves the files unchanged.

package/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 of `AGENTS.md` 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 `MARCOS-AI-BOOTSTRAP.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/src/.claude/agents/planner-claude.md

@@ -9,7 +9,7 @@ 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 of `AGENTS.md` 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 `MARCOS-AI-BOOTSTRAP.md` for the discovery and policy-check flow.
 
 ## Plan template
 Before drafting, read `documents/templates/plan-template.md` and follow its

package/src/.claude/skills/initialize/SKILL.md

@@ -1,13 +1,25 @@
 ---
 name: initialize
-description: One-time environment reconciliation. Discovers applicable MCP servers and, with user approval, installs and wires them into the infra/planner agents; discovers where plan documents actually live and, after user confirmation, wires the planner/implement/docs agents to that location; then verifies every agent's configured model exists in Claude Code and, for any missing model, prompts the user to pick the closest available match and rewrites the agent files. Never commits.
+description: One-time environment reconciliation. First wires this tool's instruction file to the shipped MARCOS-AI-BOOTSTRAP.md rules (appending an @-include, never overwriting; creating the file if absent). Discovers applicable MCP servers and, with user approval, installs and wires them into the infra/planner agents; discovers where plan documents actually live and, after user confirmation, wires the planner/implement/docs agents to that location; then always prompts the user to choose the model for each tier/role (pre-selecting the current model, or the closest available match when it is unavailable) and rewrites the agent files. Never commits.
 ---
 
-You are the initialize orchestrator. Reconcile this repo's agent network with the current environment in three phases. This skill only edits agent and skill files and MCP config; it never touches source code and never commits.
+You are the initialize orchestrator. Reconcile this repo's agent network with the current environment in the phases below. This skill only edits agent and skill files, the tool's instruction entry-point, and MCP config; it never touches source code and never commits.
+
+## Phase 0 — Rules-file include wiring
+
+The full agent rules ship as `MARCOS-AI-BOOTSTRAP.md` at the repo root. Ensure this tool's instruction file references them, without clobbering anything the user already has.
+
+1. Locate the instruction file: `CLAUDE.md`.
+2. If it exists and already references `MARCOS-AI-BOOTSTRAP.md`, leave it untouched.
+3. If it exists but does not reference it, APPEND (never overwrite) a short block:
+   > # Marcos AI-Bootstrap
+   >
+   > This repository uses the Marcos AI-Bootstrap agent/skill network. See `@MARCOS-AI-BOOTSTRAP.md` for the agent rules, the MCP server flow, and the canonical agent/skill roles.
+4. If it does not exist, create it containing that block.
 
 ## Phase 1 — MCP server discovery & wiring
 
-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.
+1. Run the discovery → policy-check → install/verify flow from the "MCP Servers" section of `MARCOS-AI-BOOTSTRAP.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:
@@ -19,9 +31,9 @@ You are the initialize orchestrator. Reconcile this repo's agent network with th
 
 1. Enumerate the models Claude Code currently exposes (the `/model` picker / managed settings). Build the set of available model IDs.
 2. For each file in `.claude/agents/*.md`, read the `model:` frontmatter value and its intended tier (High / Standard / Fast) from the tier table below.
-3. For every `model:` value that is NOT in the available set:
-   - Determine the closest available match — prefer another model in the same tier/family, else the next tier down, else the nearest capability.
-   - Use a dropdown prompt (multiple choice) listing the available models, pre-selecting the closest match, and ask the user to confirm the replacement for that tier.
+3. For every tier (High / Standard / Fast), ALWAYS prompt the user to choose the model — even when the currently configured model is available:
+   - Pick the pre-selected default: the currently configured model if it is in the available set; otherwise the closest available match — prefer another model in the same tier/family, else the next tier down, else the nearest capability.
+   - Use a dropdown prompt (multiple choice) listing every available model, pre-selecting the default from the previous step, and ask the user to confirm or change the model for that tier.
    - Rewrite the agent file's `model:` line with the chosen model. Apply the same choice to every agent sharing that tier so the default profile stays consistent.
 4. Report the final tier → model mapping and the list of edited files.
 
@@ -46,5 +58,5 @@ You are the initialize orchestrator. Reconcile this repo's agent network with th
 - Never install an MCP server that policy blocks or that the user has not approved.
 - Never let an MCP server perform mutating operations against shared or production environments; the infra guardrails still apply.
 - Never change the plans location without explicit user confirmation.
-- Only edit files under `.claude/agents/`, `.claude/skills/`, and the tool's MCP config. Do not modify source code.
-- Idempotent: re-running makes no changes when servers are already wired, the plans location already matches, and every configured model is available.
+- Only edit files under `.claude/agents/`, `.claude/skills/`, the tool's instruction entry-point (`CLAUDE.md`), and the tool's MCP config. Do not modify source code.
+- Idempotent for MCP wiring and the plans location: re-running makes no changes when servers are already wired and the plans location already matches. Model selection is always offered — re-running re-prompts for each tier, but keeping the current selection leaves the files unchanged.

package/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 of `AGENTS.md` 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 `MARCOS-AI-BOOTSTRAP.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/src/.codex/agents/planner-codex.toml

@@ -8,7 +8,7 @@ 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 of `AGENTS.md` 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 `MARCOS-AI-BOOTSTRAP.md` for the discovery and policy-check flow.
 
 ## Plan template
 Before drafting, read `documents/templates/plan-template.md` and follow its

package/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 of `AGENTS.md` 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 `MARCOS-AI-BOOTSTRAP.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/src/.github/agents/planner-copilot.agent.md

@@ -9,7 +9,7 @@ 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 of `AGENTS.md` 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 `MARCOS-AI-BOOTSTRAP.md` for the discovery and policy-check flow.
 
 ## Plan template
 Before drafting, read `documents/templates/plan-template.md` and follow its

package/src/.github/skills/initialize/SKILL.md

@@ -1,13 +1,25 @@
 ---
 name: initialize
-description: One-time environment reconciliation. Discovers applicable MCP servers and, with user approval, installs and wires them into the infra/planner agents; discovers where plan documents actually live and, after user confirmation, wires the planner/implement/docs agents to that location; then verifies every agent's configured model exists in GitHub Copilot CLI and, for any missing model, prompts the user to pick the closest available match and rewrites the agent files. Never commits.
+description: One-time environment reconciliation. First wires this tool's instruction file to the shipped MARCOS-AI-BOOTSTRAP.md rules (appending an @-include, never overwriting; creating the file if absent). Discovers applicable MCP servers and, with user approval, installs and wires them into the infra/planner agents; discovers where plan documents actually live and, after user confirmation, wires the planner/implement/docs agents to that location; then always prompts the user to choose the model for each tier/role (pre-selecting the current model, or the closest available match when it is unavailable) and rewrites the agent files. Never commits.
 ---
 
-You are the initialize orchestrator. Reconcile this repo's agent network with the current environment in three phases. This skill only edits agent and skill files and MCP config; it never touches source code and never commits.
+You are the initialize orchestrator. Reconcile this repo's agent network with the current environment in the phases below. This skill only edits agent and skill files, the tool's instruction entry-point, and MCP config; it never touches source code and never commits.
+
+## Phase 0 — Rules-file include wiring
+
+The full agent rules ship as `MARCOS-AI-BOOTSTRAP.md` at the repo root. Ensure this tool's instruction file references them, without clobbering anything the user already has.
+
+1. Locate the instruction file: `.github/copilot-instructions.md`.
+2. If it exists and already references `MARCOS-AI-BOOTSTRAP.md`, leave it untouched.
+3. If it exists but does not reference it, APPEND (never overwrite) a short block:
+   > # Marcos AI-Bootstrap
+   >
+   > This repository uses the Marcos AI-Bootstrap agent/skill network. See `@../MARCOS-AI-BOOTSTRAP.md` for the agent rules, the MCP server flow, and the canonical agent/skill roles.
+4. If it does not exist, create it containing that block.
 
 ## Phase 1 — MCP server discovery & wiring
 
-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.
+1. Run the discovery → policy-check → install/verify flow from the "MCP Servers" section of `MARCOS-AI-BOOTSTRAP.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:
@@ -19,9 +31,9 @@ You are the initialize orchestrator. Reconcile this repo's agent network with th
 
 1. Enumerate the models Copilot CLI currently exposes (the `/model` picker). Build the set of available model IDs.
 2. For each file in `.github/agents/*.agent.md`, read the `model:` frontmatter value and its intended tier (High / Standard / Fast) from the tier table below. Note the `infra-copilot` role-specific override (`gpt-5.4`).
-3. For every `model:` value that is NOT in the available set:
-   - Determine the closest available match — prefer another model in the same tier/family, else the next tier down, else the nearest capability. For a missing role override (`gpt-5.4` on infra), offer the closest available GPT model first.
-   - Use a dropdown prompt (multiple choice) listing the available models, pre-selecting the closest match, and ask the user to confirm the replacement for that tier or role.
+3. For every tier (High / Standard / Fast) and the `infra-copilot` role override, ALWAYS prompt the user to choose the model — even when the currently configured model is available:
+   - Pick the pre-selected default: the currently configured model if it is in the available set; otherwise the closest available match — prefer another model in the same tier/family, else the next tier down, else the nearest capability. For the `infra-copilot` role override (`gpt-5.4`), offer the closest available GPT model first.
+   - Use a dropdown prompt (multiple choice) listing every available model, pre-selecting the default from the previous step, and ask the user to confirm or change the model for that tier or role.
    - Rewrite the agent file's `model:` line with the chosen model. Apply the same choice to every agent sharing that tier so the mixed default profile stays consistent.
 4. Report the final tier/role → model mapping and the list of edited files.
 
@@ -48,5 +60,5 @@ Role-specific override: `infra-copilot` uses `gpt-5.4`.
 - Never install an MCP server that policy blocks or that the user has not approved.
 - Never let an MCP server perform mutating operations against shared or production environments; the infra guardrails still apply.
 - Never change the plans location without explicit user confirmation.
-- Only edit files under `.github/agents/`, `.github/skills/`, and the tool's MCP config. Do not modify source code.
-- Idempotent: re-running makes no changes when servers are already wired, the plans location already matches, and every configured model is available.
+- Only edit files under `.github/agents/`, `.github/skills/`, the tool's instruction entry-point (`.github/copilot-instructions.md`), and the tool's MCP config. Do not modify source code.
+- Idempotent for MCP wiring and the plans location: re-running makes no changes when servers are already wired and the plans location already matches. Model selection is always offered — re-running re-prompts for each tier/role, but keeping the current selection leaves the files unchanged.

package/src/HUMAN.md

@@ -10,14 +10,15 @@ Fastest path — use the `marcos-ai-bootstrap` CLI (no AI turn required, works i
 npx marcos-ai-bootstrap --copilot   # or --claude, --codex, or --all
 ```
 
-This instantly writes `AGENTS.md`, `HUMAN.md`, and the fully materialised agent/skill
+This instantly writes `MARCOS-AI-BOOTSTRAP.md`, `HUMAN.md`, an `@MARCOS-AI-BOOTSTRAP.md` include in
+your tool's instruction file, and the fully materialised agent/skill
 files for the tool(s) you chose into the current directory. That's it — the agents and
 skills are ready to use immediately. See the root `README.md` for all flags (`--force`,
 `--dry-run`, `--dest`).
 
 Once the files are written:
 
-1. Confirm `AGENTS.md`, `HUMAN.md`, and your tool's agent/skill files are present in the repo.
+1. Confirm `MARCOS-AI-BOOTSTRAP.md`, `HUMAN.md`, and your tool's agent/skill files are present in the repo.
 2. Switch to your most powerful model at medium effort using **`/model`** e.g. opus 4.8 @ medium effort
 3. Run the **`/initialize`** skill once to reconcile MCP servers, plan-document location, and model IDs with your environment.
 4. **`/clear`** — Clear the context window.

package/src/{AGENTS.md → MARCOS-AI-BOOTSTRAP.md}

@@ -1,6 +1,6 @@
 # Agent Rules
 
-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.
+This file is tool-agnostic and ships as `MARCOS-AI-BOOTSTRAP.md` at the repo root. Reference it from your AI tool's instruction entry-point (e.g. `CLAUDE.md` or `AGENTS.md` via `@MARCOS-AI-BOOTSTRAP.md`, or `.github/copilot-instructions.md` via `@../MARCOS-AI-BOOTSTRAP.md`) so these rules apply without overwriting instructions you already have. The `marcos-ai-bootstrap` CLI and the `initialize` skill append that reference for you (creating the entry-point file if it does not exist).
 
 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.
 
@@ -127,9 +127,9 @@ Canonical skills:
 **Guardrails:** Never commits or pushes — agents edit files, the user commits. Never works on `main` (uses the plan's branch). Honours each phase's agent designation exactly; stops on a failed phase.
 
 ### initialize
-**Purpose:** One-time environment reconciliation. Discovers applicable MCP servers (via the MCP Servers discovery → policy-check → install flow) and, with user approval, installs and wires them into the `infra` and `planner` agents. Discovers where plan documents actually live in the repo and, after explicit user confirmation, wires the `planner`, `implement`, and `docs` agents/skills to that location. Then verifies every agent's configured model exists in the current tool and, for any missing model, prompts the user to pick the closest available match from a dropdown and rewrites the agent files.
-**Pipeline:** MCP discovery → user approval → install + wire agents → plans-location discovery → user confirmation → rewrite plan-location references → model availability check → user picks replacements → rewrite agent files.
-**Guardrails:** Never commits or pushes. Only edits agent/skill files and MCP config — never source code. Never installs a policy-blocked or unapproved server. Never changes the plans location without explicit user confirmation. Idempotent.
+**Purpose:** One-time environment reconciliation. First ensures the tool's instruction file (`CLAUDE.md`, `AGENTS.md`, or `.github/copilot-instructions.md`) references the shipped `MARCOS-AI-BOOTSTRAP.md` rules — appending a short `@MARCOS-AI-BOOTSTRAP.md` include (never overwriting existing content), or creating the file if it does not exist. Discovers applicable MCP servers (via the MCP Servers discovery → policy-check → install flow) and, with user approval, installs and wires them into the `infra` and `planner` agents. Discovers where plan documents actually live in the repo and, after explicit user confirmation, wires the `planner`, `implement`, and `docs` agents/skills to that location. Then always prompts the user, via a dropdown, to choose the model for each tier/role — pre-selecting the currently configured model when it is available, or the closest available match when it is not — and rewrites the agent files.
+**Pipeline:** rules-file include wiring → MCP discovery → user approval → install + wire agents → plans-location discovery → user confirmation → rewrite plan-location references → enumerate available models → user chooses model per tier/role (always) → rewrite agent files.
+**Guardrails:** Never commits or pushes. Only edits agent/skill files, the tool's instruction entry-point, and MCP config — never source code. Appends to (never clobbers) an existing instruction file. Never installs a policy-blocked or unapproved server. Never changes the plans location without explicit user confirmation. Idempotent for include wiring, MCP wiring, and the plans location; model selection is always offered, but keeping the current choice leaves files unchanged.
 
 ---
 

package/src/bin/ai-bootstrap.js

@@ -13,14 +13,16 @@ Usage:
   marcos-ai-bootstrap [--claude] [--codex] [--copilot] [--all] [options]
 
 Tool flags (combine as many as you like):
-  --claude          Claude Code agents (.claude/agents), skills (.claude/skills), CLAUDE.md
-  --codex           Codex agents (.codex/agents), skills (.agents/skills)
+  --claude          Claude Code agents (.claude/agents), skills (.claude/skills),
+                     CLAUDE.md (@MARCOS-AI-BOOTSTRAP.md include, appended if it exists)
+  --codex           Codex agents (.codex/agents), skills (.agents/skills),
+                     AGENTS.md (@MARCOS-AI-BOOTSTRAP.md include, appended if it exists)
   --copilot         GitHub Copilot CLI agents (.github/agents), skills (.github/skills),
-                     .github/copilot-instructions.md
+                     .github/copilot-instructions.md (@../MARCOS-AI-BOOTSTRAP.md include)
   --all             All of the above
 
 Always written alongside any tool flag:
-  AGENTS.md, HUMAN.md (tool-agnostic rules + human guide)
+  MARCOS-AI-BOOTSTRAP.md, HUMAN.md (the full tool-agnostic rules + human guide)
 
 Options:
   --dest <path>     Target directory (default: current working directory)
@@ -90,24 +92,34 @@ function main() {
     `${opts.dryRun ? "[dry-run] " : ""}Materialising ${toolLabels} into ${destRoot}\n`
   );
 
-  const byStatus = { created: [], overwritten: [], "skipped-exists": [], "missing-source": [] };
+  const byStatus = {
+    created: [],
+    overwritten: [],
+    appended: [],
+    "already-wired": [],
+    "skipped-exists": [],
+    "missing-source": [],
+  };
   for (const r of results) {
     (byStatus[r.status] || (byStatus[r.status] = [])).push(r.relPath);
   }
 
   for (const r of byStatus.created) console.log(`  created      ${r}`);
   for (const r of byStatus.overwritten) console.log(`  overwritten  ${r}`);
+  for (const r of byStatus.appended) console.log(`  appended     ${r} (@MARCOS-AI-BOOTSTRAP.md include added)`);
+  for (const r of byStatus["already-wired"]) console.log(`  ok           ${r} (already references MARCOS-AI-BOOTSTRAP.md)`);
   for (const r of byStatus["skipped-exists"]) console.log(`  skipped      ${r} (already exists, use --force to overwrite)`);
   for (const r of byStatus["missing-source"]) console.log(`  MISSING      ${r} (not bundled in this package)`);
 
   console.log(
     `\n${byStatus.created.length} created, ${byStatus.overwritten.length} overwritten, ` +
-      `${byStatus["skipped-exists"].length} skipped, ${results.length} total.`
+      `${byStatus.appended.length} appended, ${byStatus["skipped-exists"].length} skipped, ` +
+      `${results.length} total.`
   );
 
   if (!opts.dryRun) {
     console.log(
-      `\nDone. Open AGENTS.md / HUMAN.md, then start your AI tool in ${destRoot} to begin.`
+      `\nDone. Open MARCOS-AI-BOOTSTRAP.md / HUMAN.md, then start your AI tool in ${destRoot} to begin.`
     );
   }
 }

package/src/lib/materialize.js

@@ -7,18 +7,21 @@ const PACKAGE_ROOT = path.resolve(__dirname, "..", "..");
 
 // 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.
+// the leading "src/" stripped (e.g. src/MARCOS-AI-BOOTSTRAP.md ->
+// MARCOS-AI-BOOTSTRAP.md, src/.github/agents/foo -> .github/agents/foo). This
+// repo's own root-level self-hosting copies 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.
+// package-relative source (under src/) to the target-relative destination. The
+// full agent rules ship as MARCOS-AI-BOOTSTRAP.md so they never collide with a
+// user's own AGENTS.md / CLAUDE.md; the tool entry-points below only *reference*
+// this file via an appended @-include.
 const CORE_FILES = [
-  { src: "src/AGENTS.md", dest: "AGENTS.md" },
+  { src: "src/MARCOS-AI-BOOTSTRAP.md", dest: "MARCOS-AI-BOOTSTRAP.md" },
   { src: "src/HUMAN.md", dest: "HUMAN.md" },
   {
     src: "src/documents/templates/plan-template.md",
@@ -26,30 +29,41 @@ const CORE_FILES = [
   },
 ];
 
+// The short block appended to a tool's instruction file. `ref` is the tool-
+// correct @-include path to MARCOS-AI-BOOTSTRAP.md (relative to the entry file).
+function includeBlock(ref) {
+  return (
+    "# Marcos AI-Bootstrap\n\n" +
+    "This repository uses the Marcos AI-Bootstrap agent/skill network. See " +
+    ref +
+    " for the agent rules, the MCP server flow, and the canonical agent/skill roles.\n"
+  );
+}
+
+// Marker used to detect an already-wired instruction file (idempotency).
+const INCLUDE_MARKER = "MARCOS-AI-BOOTSTRAP.md";
+
 const TOOLS = {
   claude: {
     label: "Claude Code",
     dirs: [".claude/agents", ".claude/skills"],
-    entry: {
-      file: "CLAUDE.md",
-      content: "@AGENTS.md\n",
-    },
+    // Claude reads CLAUDE.md; @-imports resolve relative to it (repo root).
+    entry: { file: "CLAUDE.md", include: "@MARCOS-AI-BOOTSTRAP.md" },
   },
   codex: {
     label: "Codex",
     dirs: [".codex/agents", ".agents/skills"],
-    // Codex loads AGENTS.md directly from the workspace root; no separate
-    // config entry-point file is required.
+    // Codex loads AGENTS.md directly from the workspace root.
+    entry: { file: "AGENTS.md", include: "@MARCOS-AI-BOOTSTRAP.md" },
   },
   copilot: {
     label: "GitHub Copilot CLI",
     dirs: [".github/agents", ".github/skills"],
+    // Copilot reads .github/copilot-instructions.md; the rules file sits one
+    // directory up at the repo root.
     entry: {
       file: path.join(".github", "copilot-instructions.md"),
-      content:
-        "# Copilot instructions\n\n" +
-        "See [AGENTS.md](../AGENTS.md) for the agent rules and the agent/skill " +
-        "network that has been materialised into this repository.\n",
+      include: "@../MARCOS-AI-BOOTSTRAP.md",
     },
   },
 };
@@ -73,7 +87,7 @@ function listFiles(dir) {
 
 /**
  * Copy a single file from the package root to the destination root. The source
- * and destination relative paths may differ (e.g. src/AGENTS.md -> AGENTS.md).
+ * and destination relative paths may differ (e.g. src/MARCOS-AI-BOOTSTRAP.md -> MARCOS-AI-BOOTSTRAP.md).
  * Returns a status object keyed by the destination path.
  */
 function copyOne(srcRel, destRel, destRoot, { force, dryRun }) {
@@ -97,20 +111,33 @@ function copyOne(srcRel, destRel, destRoot, { force, dryRun }) {
 }
 
 /**
- * Write a small generated entry-point file (e.g. CLAUDE.md,
- * .github/copilot-instructions.md) rather than copying from the package.
+ * Wire a tool's instruction entry-point (e.g. CLAUDE.md,
+ * .github/copilot-instructions.md, AGENTS.md) to the shipped
+ * MARCOS-AI-BOOTSTRAP.md rules. Never overwrites existing user content: if the
+ * file already references the rules file it is left untouched; otherwise the
+ * include block is appended. The file is created with just the block if absent.
  */
-function writeEntry(entry, destRoot, { force, dryRun }) {
+function appendEntry(entry, destRoot, { dryRun }) {
   const dest = path.join(destRoot, entry.file);
-  const exists = fs.existsSync(dest);
-  if (exists && !force) {
-    return { relPath: entry.file, status: "skipped-exists" };
+  const block = includeBlock(entry.include);
+
+  if (fs.existsSync(dest)) {
+    const current = fs.readFileSync(dest, "utf8");
+    if (current.includes(INCLUDE_MARKER)) {
+      return { relPath: entry.file, status: "already-wired" };
+    }
+    if (!dryRun) {
+      const sep = current.length === 0 || current.endsWith("\n") ? "\n" : "\n\n";
+      fs.appendFileSync(dest, sep + block);
+    }
+    return { relPath: entry.file, status: "appended" };
   }
+
   if (!dryRun) {
     fs.mkdirSync(path.dirname(dest), { recursive: true });
-    fs.writeFileSync(dest, entry.content, "utf8");
+    fs.writeFileSync(dest, block, "utf8");
   }
-  return { relPath: entry.file, status: exists ? "overwritten" : "created" };
+  return { relPath: entry.file, status: "created" };
 }
 
 /**
@@ -147,7 +174,7 @@ function materialize(tools, opts = {}) {
       }
     }
     if (tool.entry) {
-      results.push(writeEntry(tool.entry, destRoot, { force, dryRun }));
+      results.push(appendEntry(tool.entry, destRoot, { dryRun }));
     }
   }