marcos-ai-bootstrap 0.1.5 → 0.1.6

package/README.md

@@ -25,15 +25,17 @@ 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—`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, and appends an `@MARCOS-AI-BOOTSTRAP.md`
-include to your tool's instruction file (creating it only if absent, never overwriting existing content).
+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 |
 |---|---|
+| _(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`, `AGENTS.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 |
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "marcos-ai-bootstrap",
-  "version": "0.1.5",
+  "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"

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

@@ -1,6 +1,6 @@
 ---
 name: initialize
-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.
+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 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.
@@ -53,6 +53,20 @@ The full agent rules ship as `MARCOS-AI-BOOTSTRAP.md` at the repo root. Ensure t
 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.

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/skills/initialize/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: initialize
-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.
+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 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.
@@ -53,6 +53,20 @@ The full agent rules ship as `MARCOS-AI-BOOTSTRAP.md` at the repo root. Ensure t
 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.

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/.github/skills/initialize/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: initialize
-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.
+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 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.
@@ -55,6 +55,20 @@ 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.

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

@@ -29,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/MARCOS-AI-BOOTSTRAP.md

@@ -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. 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.
+**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

@@ -15,14 +15,17 @@ Usage:
 Tool flags (combine as many as you like):
   --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)
+  --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 (@../MARCOS-AI-BOOTSTRAP.md include)
   --all             All of the above
 
-Always written alongside any tool flag:
+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)

package/src/lib/materialize.js

@@ -43,6 +43,14 @@ function includeBlock(ref) {
 // 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",
@@ -53,8 +61,10 @@ const TOOLS = {
   codex: {
     label: "Codex",
     dirs: [".codex/agents", ".agents/skills"],
-    // Codex loads AGENTS.md directly from the workspace root.
-    entry: { file: "AGENTS.md", include: "@MARCOS-AI-BOOTSTRAP.md" },
+    // 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",
@@ -159,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;
@@ -181,4 +194,4 @@ function materialize(tools, opts = {}) {
   return { results, tools, destRoot };
 }
 
-module.exports = { materialize, TOOLS, CORE_FILES, PACKAGE_ROOT };
+module.exports = { materialize, TOOLS, CORE_FILES, CORE_ENTRY, PACKAGE_ROOT };