marcos-ai-bootstrap 0.1.4 → 0.1.6

package/README.md

@@ -23,16 +23,20 @@ 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. It always wires the universal `AGENTS.md`
+entry-point with an `@MARCOS-AI-BOOTSTRAP.md` include, and also appends the tool-native include to
+your selected tool's instruction file (creating each 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` |
+| _(always)_ | `MARCOS-AI-BOOTSTRAP.md`, `HUMAN.md`, `documents/templates/plan-template.md`, and `AGENTS.md` (the universal entry-point, append `@MARCOS-AI-BOOTSTRAP.md` include) |
+| `--claude` | `.claude/agents/*.md`, `.claude/skills/**/SKILL.md`, `CLAUDE.md` (append `@MARCOS-AI-BOOTSTRAP.md` include) |
+| `--codex` | `.codex/agents/*.toml`, `.agents/skills/**/SKILL.md` (Codex reads the always-written `AGENTS.md`) |
+| `--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 +64,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.6",
   "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; scans past PRs, branch names, and commit history and, after user confirmation, customises the `pr` skill's convention profile; 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.
 
@@ -41,10 +53,24 @@ You are the initialize orchestrator. Reconcile this repo's agent network with th
 4. On confirmation, update every reference to the plans directory so the agents write to and read from the correct place: the `planner-codex` and `planner-discovery-codex` agents, the `planner` and `implement` skills, and the `docs-codex` agent's plan-document references. Leave all other paths untouched.
 5. Report the resolved plans location and the list of edited files.
 
+## Phase 4 - PR & contribution convention discovery
+
+Customise the `pr` skill so it matches how THIS repository actually works, learned from its own history rather than assumed defaults.
+
+1. Gather evidence of the repo's conventions:
+   - **Past PRs** - `gh pr list --state merged --limit 50 --json number,title,headRefName,body`. Infer PR-title patterns (Conventional Commits, ticket prefixes like `[ABC-123]`, sentence vs lower case), branch-name patterns (prefixes, separators, casing), and PR-body structure (required sections, checklists).
+   - **Commit subjects** - `git --no-pager log origin/<default-branch> --format='%s' -n 100`. Infer the commit-message convention.
+   - **Contribution config** - `CONTRIBUTING.md`, `.github/pull_request_template.md` (and `PULL_REQUEST_TEMPLATE/`), `.gitmessage`, commit-lint config (`commitlint.config.*`, `.commitlintrc*`, `.czrc`), and any release automation (`release-please*`, `.releaserc*`, `semantic-release`) that constrains commit/PR format.
+   - **Repo settings** - `gh repo view --json defaultBranchRef,mergeCommitAllowed,squashMergeAllowed,rebaseMergeAllowed` for the default branch and allowed merge methods.
+2. Synthesise a concise convention profile: branch-name rules, commit-message rules, PR-title rules, PR-body/template rules, and any release-automation constraints. Prefer the dominant observed pattern; where history is sparse or inconsistent, fall back to the general Conventional Commits defaults and say so explicitly.
+3. Present the inferred profile to the user for confirmation or edits. Do not rewrite the skill without confirmation.
+4. On confirmation, rewrite ONLY the "Repository conventions" block of `.agents/skills/pr/SKILL.md` - the text between the `<!-- CONVENTIONS:START -->` and `<!-- CONVENTIONS:END -->` markers - with the confirmed profile. Leave the rest of the skill untouched.
+5. Report the resolved convention profile and confirm the `pr` skill was updated.
+
 ## Guardrails
 - Never commit or push - you edit agent and skill files and MCP config; the user commits.
 - 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/.agents/skills/pr/SKILL.md

@@ -0,0 +1,39 @@
+---
+name: pr
+description: Open a pull request that follows this repository's conventions for branch names, commit messages, and PR titles and bodies. Verifies you are on a working branch, checks and repairs the branch/commits/title against the active convention profile, pushes, and opens the PR with the GitHub CLI. Never merges the PR.
+---
+
+You are the pr orchestrator. Open a pull request that conforms to this repository's contribution conventions, then hand off to the user to merge. Never merge the PR yourself and never push to the default branch.
+
+## Convention profile
+
+Apply the rules in the "Repository conventions" section below. While that section still holds the shipped defaults, fall back to these widely-used best-practice defaults:
+
+- **Branch names:** short, kebab-case, prefixed by change type - `feat/`, `fix/`, `chore/`, `docs/`, `refactor/`, `test/`. Never commit on the default branch.
+- **Commit messages:** Conventional Commits - `<type>[optional scope][!]: <description>` in the imperative mood, subject <= 72 chars. Types: `feat`, `fix`, `perf`, `refactor`, `docs`, `test`, `build`, `ci`, `chore`, `style`, `revert`. A `!` or `BREAKING CHANGE:` footer marks a breaking change. Validation regex: `^(feat|fix|perf|refactor|docs|test|build|ci|chore|style|revert)(\([^)]+\))?!?: .+`
+- **PR title:** one-line summary in the same style as the commit convention.
+- **PR body:** what changed and why, linked issues, and user-facing impact / testing notes. Honour `.github/pull_request_template.md` if present.
+- **Release automation:** some tools (release-please, semantic-release) only cut a release when a recognised commit type lands on the default branch. If this repo uses one, ensure at least one release-triggering commit (typically `feat`/`fix` or a breaking change) is present when a release is intended.
+
+## Repository conventions
+
+<!-- CONVENTIONS:START -->
+_Not yet customised. Run the `initialize` skill to scan this repository's history (past PRs, branch names, commit subjects, and any CONTRIBUTING / PR-template / commit-lint config) and replace this block with the repo's actual conventions. Until then, the general defaults above apply._
+<!-- CONVENTIONS:END -->
+
+## Steps
+
+1. **Determine the default branch** - `git symbolic-ref --quiet refs/remotes/origin/HEAD` (fallback `gh repo view --json defaultBranchRef -q .defaultBranchRef.name`); call it `<base>`.
+2. **Branch check** - Confirm the current branch is not `<base>` (`git branch --show-current`). If it is, STOP and ask the user to create a working branch that matches the branch-name convention.
+3. **Branch-name check** - Validate the current branch name against the active convention; if it does not match, offer to rename it (`git branch -m <new>`) before pushing.
+4. **Commit check** - List commits not yet on `<base>` (`git --no-pager log origin/<base>..HEAD --format='%H %s'`) and validate each subject against the commit convention. If any fail, propose compliant rewrites and, only on explicit user confirmation, reword them (`git commit --amend` for the tip, `git rebase -i origin/<base>` for earlier commits). Never reword commits already on `<base>`. If a release is intended and the convention requires a release-triggering type, ensure at least one such commit exists.
+5. **Push** - `git push -u origin <branch>`. Never push to `<base>`. Force-push only to complete a reword/rebase the user explicitly approved, and never with `--no-verify`.
+6. **PR title & body** - Derive a title matching the PR-title convention and a body matching the PR-body convention (and template, if any); validate before submitting.
+7. **Open the PR** - `gh pr create --base <base> --title "<title>" --body "<body>"`.
+8. **Report** - Print the PR URL plus any repo-specific merge/release guidance from the conventions section.
+
+## Guardrails
+- Never merge the PR - opening it is the final step; the user merges.
+- Never push to, or commit on, the default branch.
+- Force-push only to complete a reword/rebase the user explicitly approved.
+- Never use `--no-verify`.

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; scans past PRs, branch names, and commit history and, after user confirmation, customises the `pr` skill's convention profile; 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.
 
@@ -41,10 +53,24 @@ You are the initialize orchestrator. Reconcile this repo's agent network with th
 4. On confirmation, update every reference to the plans directory so the agents write to and read from the correct place: the `planner-claude` and `planner-discovery-claude` agents, the `planner` and `implement` skills, and the `docs-claude` agent's plan-document references. Leave all other paths untouched.
 5. Report the resolved plans location and the list of edited files.
 
+## Phase 4 — PR & contribution convention discovery
+
+Customise the `pr` skill so it matches how THIS repository actually works, learned from its own history rather than assumed defaults.
+
+1. Gather evidence of the repo's conventions:
+   - **Past PRs** — `gh pr list --state merged --limit 50 --json number,title,headRefName,body`. Infer PR-title patterns (Conventional Commits, ticket prefixes like `[ABC-123]`, sentence vs lower case), branch-name patterns (prefixes, separators, casing), and PR-body structure (required sections, checklists).
+   - **Commit subjects** — `git --no-pager log origin/<default-branch> --format='%s' -n 100`. Infer the commit-message convention.
+   - **Contribution config** — `CONTRIBUTING.md`, `.github/pull_request_template.md` (and `PULL_REQUEST_TEMPLATE/`), `.gitmessage`, commit-lint config (`commitlint.config.*`, `.commitlintrc*`, `.czrc`), and any release automation (`release-please*`, `.releaserc*`, `semantic-release`) that constrains commit/PR format.
+   - **Repo settings** — `gh repo view --json defaultBranchRef,mergeCommitAllowed,squashMergeAllowed,rebaseMergeAllowed` for the default branch and allowed merge methods.
+2. Synthesise a concise convention profile: branch-name rules, commit-message rules, PR-title rules, PR-body/template rules, and any release-automation constraints. Prefer the dominant observed pattern; where history is sparse or inconsistent, fall back to the general Conventional Commits defaults and say so explicitly.
+3. Present the inferred profile to the user for confirmation or edits. Do not rewrite the skill without confirmation.
+4. On confirmation, rewrite ONLY the "Repository conventions" block of `.claude/skills/pr/SKILL.md` — the text between the `<!-- CONVENTIONS:START -->` and `<!-- CONVENTIONS:END -->` markers — with the confirmed profile. Leave the rest of the skill untouched.
+5. Report the resolved convention profile and confirm the `pr` skill was updated.
+
 ## Guardrails
 - Never commit or push — you edit agent and skill files and MCP config; the user commits.
 - 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/.claude/skills/pr/SKILL.md

@@ -0,0 +1,39 @@
+---
+name: pr
+description: Open a pull request that follows this repository's conventions for branch names, commit messages, and PR titles and bodies. Verifies you are on a working branch, checks and repairs the branch/commits/title against the active convention profile, pushes, and opens the PR with the GitHub CLI. Never merges the PR.
+---
+
+You are the pr orchestrator. Open a pull request that conforms to this repository's contribution conventions, then hand off to the user to merge. Never merge the PR yourself and never push to the default branch.
+
+## Convention profile
+
+Apply the rules in the "Repository conventions" section below. While that section still holds the shipped defaults, fall back to these widely-used best-practice defaults:
+
+- **Branch names:** short, kebab-case, prefixed by change type — `feat/`, `fix/`, `chore/`, `docs/`, `refactor/`, `test/`. Never commit on the default branch.
+- **Commit messages:** Conventional Commits — `<type>[optional scope][!]: <description>` in the imperative mood, subject <= 72 chars. Types: `feat`, `fix`, `perf`, `refactor`, `docs`, `test`, `build`, `ci`, `chore`, `style`, `revert`. A `!` or `BREAKING CHANGE:` footer marks a breaking change. Validation regex: `^(feat|fix|perf|refactor|docs|test|build|ci|chore|style|revert)(\([^)]+\))?!?: .+`
+- **PR title:** one-line summary in the same style as the commit convention.
+- **PR body:** what changed and why, linked issues, and user-facing impact / testing notes. Honour `.github/pull_request_template.md` if present.
+- **Release automation:** some tools (release-please, semantic-release) only cut a release when a recognised commit type lands on the default branch. If this repo uses one, ensure at least one release-triggering commit (typically `feat`/`fix` or a breaking change) is present when a release is intended.
+
+## Repository conventions
+
+<!-- CONVENTIONS:START -->
+_Not yet customised. Run the `initialize` skill to scan this repository's history (past PRs, branch names, commit subjects, and any CONTRIBUTING / PR-template / commit-lint config) and replace this block with the repo's actual conventions. Until then, the general defaults above apply._
+<!-- CONVENTIONS:END -->
+
+## Steps
+
+1. **Determine the default branch** — `git symbolic-ref --quiet refs/remotes/origin/HEAD` (fallback `gh repo view --json defaultBranchRef -q .defaultBranchRef.name`); call it `<base>`.
+2. **Branch check** — Confirm the current branch is not `<base>` (`git branch --show-current`). If it is, STOP and ask the user to create a working branch that matches the branch-name convention.
+3. **Branch-name check** — Validate the current branch name against the active convention; if it does not match, offer to rename it (`git branch -m <new>`) before pushing.
+4. **Commit check** — List commits not yet on `<base>` (`git --no-pager log origin/<base>..HEAD --format='%H %s'`) and validate each subject against the commit convention. If any fail, propose compliant rewrites and, only on explicit user confirmation, reword them (`git commit --amend` for the tip, `git rebase -i origin/<base>` for earlier commits). Never reword commits already on `<base>`. If a release is intended and the convention requires a release-triggering type, ensure at least one such commit exists.
+5. **Push** — `git push -u origin <branch>`. Never push to `<base>`. Force-push only to complete a reword/rebase the user explicitly approved, and never with `--no-verify`.
+6. **PR title & body** — Derive a title matching the PR-title convention and a body matching the PR-body convention (and template, if any); validate before submitting.
+7. **Open the PR** — `gh pr create --base <base> --title "<title>" --body "<body>"`.
+8. **Report** — Print the PR URL plus any repo-specific merge/release guidance from the conventions section.
+
+## Guardrails
+- Never merge the PR — opening it is the final step; the user merges.
+- Never push to, or commit on, the default branch.
+- Force-push only to complete a reword/rebase the user explicitly approved.
+- Never use `--no-verify`.

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; scans past PRs, branch names, and commit history and, after user confirmation, customises the `pr` skill's convention profile; 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.
 
@@ -43,10 +55,24 @@ Role-specific override: `infra-copilot` uses `gpt-5.4`.
 4. On confirmation, update every reference to the plans directory so the agents write to and read from the correct place: the `planner-copilot` and `planner-discovery-copilot` agents, the `planner` and `implement` skills, and the `docs-copilot` agent's plan-document references. Leave all other paths untouched.
 5. Report the resolved plans location and the list of edited files.
 
+## Phase 4 — PR & contribution convention discovery
+
+Customise the `pr` skill so it matches how THIS repository actually works, learned from its own history rather than assumed defaults.
+
+1. Gather evidence of the repo's conventions:
+   - **Past PRs** — `gh pr list --state merged --limit 50 --json number,title,headRefName,body`. Infer PR-title patterns (Conventional Commits, ticket prefixes like `[ABC-123]`, sentence vs lower case), branch-name patterns (prefixes, separators, casing), and PR-body structure (required sections, checklists).
+   - **Commit subjects** — `git --no-pager log origin/<default-branch> --format='%s' -n 100`. Infer the commit-message convention.
+   - **Contribution config** — `CONTRIBUTING.md`, `.github/pull_request_template.md` (and `PULL_REQUEST_TEMPLATE/`), `.gitmessage`, commit-lint config (`commitlint.config.*`, `.commitlintrc*`, `.czrc`), and any release automation (`release-please*`, `.releaserc*`, `semantic-release`) that constrains commit/PR format.
+   - **Repo settings** — `gh repo view --json defaultBranchRef,mergeCommitAllowed,squashMergeAllowed,rebaseMergeAllowed` for the default branch and allowed merge methods.
+2. Synthesise a concise convention profile: branch-name rules, commit-message rules, PR-title rules, PR-body/template rules, and any release-automation constraints. Prefer the dominant observed pattern; where history is sparse or inconsistent, fall back to the general Conventional Commits defaults and say so explicitly.
+3. Present the inferred profile to the user for confirmation or edits. Do not rewrite the skill without confirmation.
+4. On confirmation, rewrite ONLY the "Repository conventions" block of `.github/skills/pr/SKILL.md` — the text between the `<!-- CONVENTIONS:START -->` and `<!-- CONVENTIONS:END -->` markers — with the confirmed profile. Leave the rest of the skill untouched.
+5. Report the resolved convention profile and confirm the `pr` skill was updated.
+
 ## Guardrails
 - Never commit or push — you edit agent and skill files and MCP config; the user commits.
 - 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/.github/skills/pr/SKILL.md

@@ -0,0 +1,39 @@
+---
+name: pr
+description: Open a pull request that follows this repository's conventions for branch names, commit messages, and PR titles and bodies. Verifies you are on a working branch, checks and repairs the branch/commits/title against the active convention profile, pushes, and opens the PR with the GitHub CLI. Never merges the PR.
+---
+
+You are the pr orchestrator. Open a pull request that conforms to this repository's contribution conventions, then hand off to the user to merge. Never merge the PR yourself and never push to the default branch.
+
+## Convention profile
+
+Apply the rules in the "Repository conventions" section below. While that section still holds the shipped defaults, fall back to these widely-used best-practice defaults:
+
+- **Branch names:** short, kebab-case, prefixed by change type — `feat/`, `fix/`, `chore/`, `docs/`, `refactor/`, `test/`. Never commit on the default branch.
+- **Commit messages:** Conventional Commits — `<type>[optional scope][!]: <description>` in the imperative mood, subject <= 72 chars. Types: `feat`, `fix`, `perf`, `refactor`, `docs`, `test`, `build`, `ci`, `chore`, `style`, `revert`. A `!` or `BREAKING CHANGE:` footer marks a breaking change. Validation regex: `^(feat|fix|perf|refactor|docs|test|build|ci|chore|style|revert)(\([^)]+\))?!?: .+`
+- **PR title:** one-line summary in the same style as the commit convention.
+- **PR body:** what changed and why, linked issues, and user-facing impact / testing notes. Honour `.github/pull_request_template.md` if present.
+- **Release automation:** some tools (release-please, semantic-release) only cut a release when a recognised commit type lands on the default branch. If this repo uses one, ensure at least one release-triggering commit (typically `feat`/`fix` or a breaking change) is present when a release is intended.
+
+## Repository conventions
+
+<!-- CONVENTIONS:START -->
+_Not yet customised. Run the `initialize` skill to scan this repository's history (past PRs, branch names, commit subjects, and any CONTRIBUTING / PR-template / commit-lint config) and replace this block with the repo's actual conventions. Until then, the general defaults above apply._
+<!-- CONVENTIONS:END -->
+
+## Steps
+
+1. **Determine the default branch** — `git symbolic-ref --quiet refs/remotes/origin/HEAD` (fallback `gh repo view --json defaultBranchRef -q .defaultBranchRef.name`); call it `<base>`.
+2. **Branch check** — Confirm the current branch is not `<base>` (`git branch --show-current`). If it is, STOP and ask the user to create a working branch that matches the branch-name convention.
+3. **Branch-name check** — Validate the current branch name against the active convention; if it does not match, offer to rename it (`git branch -m <new>`) before pushing.
+4. **Commit check** — List commits not yet on `<base>` (`git --no-pager log origin/<base>..HEAD --format='%H %s'`) and validate each subject against the commit convention. If any fail, propose compliant rewrites and, only on explicit user confirmation, reword them (`git commit --amend` for the tip, `git rebase -i origin/<base>` for earlier commits). Never reword commits already on `<base>`. If a release is intended and the convention requires a release-triggering type, ensure at least one such commit exists.
+5. **Push** — `git push -u origin <branch>`. Never push to `<base>`. Force-push only to complete a reword/rebase the user explicitly approved, and never with `--no-verify`.
+6. **PR title & body** — Derive a title matching the PR-title convention and a body matching the PR-body convention (and template, if any); validate before submitting.
+7. **Open the PR** — `gh pr create --base <base> --title "<title>" --body "<body>"`.
+8. **Report** — Print the PR URL plus any repo-specific merge/release guidance from the conventions section.
+
+## Guardrails
+- Never merge the PR — opening it is the final step; the user merges.
+- Never push to, or commit on, the default branch.
+- Force-push only to complete a reword/rebase the user explicitly approved.
+- Never use `--no-verify`.

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.
@@ -28,4 +29,5 @@ Once the files are written:
 1. **`/planner`** — Give a basic outline of what you want to build. The agent asks clarifying questions and iterates until it has a complete plan for the feature, bugfix, or chore.
 2. **`/clear`** — Clear the context window.
 3. **`/implement`** — Paste the path to the plan that was created, e.g. `documents/plans/20260101-plan.md`.
-4. **`/watch-ci`** — Paste the PR or GitHub Actions run. It watches the build to make sure everything passes, fixing bugs in real time if needed.
+4. **`/pr`** — Open a pull request with Conventional Commit messages so the release-please workflow can cut a release once merged.
+5. **`/watch-ci`** — Paste the PR or GitHub Actions run. It watches the build to make sure everything passes, fixing bugs in real time if needed.

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,14 @@ 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. Scans the repository's history (past merged PRs, branch names, commit subjects, and any CONTRIBUTING / PR-template / commit-lint / release-automation config) and, after user confirmation, customises the `pr` skill's convention profile to match. 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 → PR/commit-convention discovery → user confirmation → customise the `pr` skill → 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 or `pr` conventions 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.
+
+### pr
+**Purpose:** Open a pull request that follows THIS repository's contribution conventions — branch names, commit-message format, PR title, and PR body — defaulting to widely-used best practices (kebab-case typed branches, Conventional Commits) until the `initialize` skill customises the convention profile from the repo's own history. Prevents malformed PRs and, where release automation (e.g. release-please) is in use, the failure mode where a non-conventional commit lands on the default branch and the release is silently skipped.
+**Pipeline:** resolve the default branch → branch check (never the default branch) → validate/repair the branch name and commit subjects against the active convention → push → derive and validate a conventional PR title and body → `gh pr create` → report the PR URL and any repo-specific merge/release guidance.
+**Guardrails:** Never merges the PR — opening it is the final step; the user merges. Never pushes to or commits on the default branch. Force-pushes only to complete a reword/rebase the user explicitly approved. Never uses `--no-verify`.
 
 ---
 

package/src/bin/ai-bootstrap.js

@@ -13,14 +13,19 @@ 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
+  --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)
+                     (Codex reads the always-written root AGENTS.md)
   --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)
+Always written (regardless of tool flags):
+  MARCOS-AI-BOOTSTRAP.md, HUMAN.md (the full tool-agnostic rules + human guide)
+  AGENTS.md         universal entry-point wired with @MARCOS-AI-BOOTSTRAP.md
+                     (created if absent; the include is appended to an existing
+                     file without overwriting your content)
 
 Options:
   --dest <path>     Target directory (default: current working directory)
@@ -90,24 +95,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,51 @@ 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";
+
+// AGENTS.md is the broadest cross-tool convention (read by Codex, the Copilot
+// coding agent, Cursor, Aider, and a growing set of others). It is therefore
+// wired on every invocation, regardless of which tool flags were passed, as a
+// thin @-include of the shipped rules. Tool-native entry-points (CLAUDE.md,
+// .github/copilot-instructions.md) are still written alongside it. Codex reads
+// this same file, so it no longer needs a separate tool-specific entry.
+const CORE_ENTRY = { file: "AGENTS.md", include: "@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, which is now
+    // always written as the universal CORE_ENTRY, so no tool-specific entry is
+    // needed here.
+    entry: null,
   },
   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 +97,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 +121,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" };
 }
 
 /**
@@ -132,6 +169,9 @@ function materialize(tools, opts = {}) {
     results.push(copyOne(cf.src, cf.dest, destRoot, { force, dryRun }));
   }
 
+  // AGENTS.md is wired on every invocation as the universal entry-point.
+  results.push(appendEntry(CORE_ENTRY, destRoot, { dryRun }));
+
   for (const toolName of tools) {
     const tool = TOOLS[toolName];
     if (!tool) continue;
@@ -147,11 +187,11 @@ function materialize(tools, opts = {}) {
       }
     }
     if (tool.entry) {
-      results.push(writeEntry(tool.entry, destRoot, { force, dryRun }));
+      results.push(appendEntry(tool.entry, destRoot, { dryRun }));
     }
   }
 
   return { results, tools, destRoot };
 }
 
-module.exports = { materialize, TOOLS, CORE_FILES, PACKAGE_ROOT };
+module.exports = { materialize, TOOLS, CORE_FILES, CORE_ENTRY, PACKAGE_ROOT };