marcos-ai-bootstrap 0.1.5 → 0.1.7

package/README.md

@@ -1,15 +1,21 @@
 # marcos-ai-bootstrap
 
-AI tools for doing work. No overcomplications.
+[![npm version](https://img.shields.io/npm/v/marcos-ai-bootstrap)](https://www.npmjs.com/package/marcos-ai-bootstrap)
+[![license](https://img.shields.io/npm/l/marcos-ai-bootstrap)](./LICENSE)
+[![CI](https://github.com/marcorpetralia/marcos-ai-bootstrap/actions/workflows/ci.yml/badge.svg)](https://github.com/marcorpetralia/marcos-ai-bootstrap/actions/workflows/ci.yml)
 
-Tool-agnostic agent/skill network that is built around a basic flow of plan -> implement -> deploy -> fix -> deploy etc.
+Simple agent workflows designed for getting work done, as quickly and cheaply as possible whilst ensuring guardrails are followed.
 
-Currently supporting **Claude Code**, **Codex**, and **GitHub Copilot CLI** but easily adjustable to fit your workflow.
+A tool-agnostic agent/skill network that gives Claude Code, Codex, and GitHub Copilot CLI a shared plan → implement → deploy → fix workflow — drop it into any repository with one command.
+
+**Note:** marcos-ai-bootstrap is pre-1.0 and evolving. SemVer stabilizes at `1.0.0`. See ["Releasing to npm"](#releasing-to-npm) for the current version and release process.
 
 See [`HUMAN.md`](./HUMAN.md) for the day-to-day workflow once the network is set up.
 
 ## Quick start: the `marcos-ai-bootstrap` CLI
 
+**Requires Node.js >= 18**
+
 The fastest way to bring this agent network into any repository — no AI turn required,
 works the same on Windows/Mac/Linux, and doesn't care whether the target project is
 Node, Python, Go, or anything else:
@@ -25,15 +31,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 |
 
@@ -57,6 +65,10 @@ npm install -g marcos-ai-bootstrap
 marcos-ai-bootstrap --all
 ```
 
+## Demo
+
+<!-- TODO: GIF/asciinema demo recording coming soon — drop it here -->
+
 ## Repository layout
 
 **Everything the CLI materialises into a target repo is shipped from `src/`; `src/` is the single source of truth.**

package/package.json

@@ -1,11 +1,14 @@
 {
   "name": "marcos-ai-bootstrap",
-  "version": "0.1.5",
+  "version": "0.1.7",
   "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"
   },
   "main": "src/lib/materialize.js",
+  "scripts": {
+    "test": "node --test"
+  },
   "files": [
     "src/bin",
     "src/lib",
@@ -19,7 +22,7 @@
     "src/.github/skills"
   ],
   "engines": {
-    "node": ">=16"
+    "node": ">=18"
   },
   "license": "MIT",
   "repository": {

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/.agents/skills/watch-ci/SKILL.md

@@ -34,7 +34,8 @@ Repeat until green or 5 iterations reached:
 3. **Investigate (HARD only)**: invoke `investigate-codex` with the diagnostic report and triage output; receive a root-cause analysis and fix strategy.
 4. **Fix**: invoke `code-codex` with the triage fix suggestion (EASY) or investigate fix strategy (HARD) to apply the change.
 5. **Validate**: run the narrowest relevant tests, lint, or build command before attempting a new CI run.
-6. **Commit & push**: commit the fix on the current feature branch and push; never push to `main`.
+6. **Commit & push**: because the user invoked this skill to drive CI green, commit
+   the fix and push **on the current feature branch only**; never commit or push to `main`.
 7. **Re-trigger**: use the trigger method determined above.
 8. **Wait**: poll `gh run watch` until the new run completes.
 9. If still failing, go to step 1.
@@ -42,6 +43,8 @@ Repeat until green or 5 iterations reached:
 After 5 iterations without green, stop and report the current state and last error to the user.
 
 ## Guardrails
+- This skill commits and pushes as an explicitly user-invoked action, on the
+  feature branch only — never autonomously and never on `main`.
 - Never push to `main`.
 - Never force-push.
 - 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/.claude/skills/watch-ci/SKILL.md

@@ -34,7 +34,8 @@ Repeat until green or 5 iterations reached:
 3. **Investigate** (HARD only) — invoke the `investigate-claude` agent with the diagnostic report and triage output; receive a root-cause analysis and fix strategy.
 4. **Fix** — invoke the `code-claude` agent with the triage fix suggestion (EASY) or investigate fix strategy (HARD) to apply the change.
 5. **Validate** — run the narrowest relevant tests, lint, or build command before attempting a new CI run.
-6. **Commit & push** — commit the fix on the current feature branch and push; never push to `main`.
+6. **Commit & push** — because the user invoked this skill to drive CI green, commit
+   the fix and push **on the current feature branch only**; never commit or push to `main`.
 7. **Re-trigger** — use the trigger method determined above.
 8. **Wait** — poll `gh run watch` until the new run completes.
 9. If still failing, go to step 1.
@@ -42,6 +43,8 @@ Repeat until green or 5 iterations reached:
 After 5 iterations without green, stop and report the current state and last error to the user.
 
 ## Guardrails
+- This skill commits and pushes as an explicitly user-invoked action, on the
+  feature branch only — never autonomously and never on `main`.
 - Never push to `main`.
 - Never force-push.
 - 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/.github/skills/watch-ci/SKILL.md

@@ -33,7 +33,8 @@ Repeat until green or 5 iterations reached:
 2. **Triage** — invoke the `triage-copilot` agent with the diagnostic report; receive EASY or HARD classification.
 3. **Investigate** (HARD only) — invoke the `investigate-copilot` agent with the diagnostic report and triage output; receive a root-cause analysis and fix strategy.
 4. **Fix** — invoke the `code-copilot` agent with the triage fix suggestion (EASY) or investigate fix strategy (HARD) to apply the change.
-5. **Commit & push** — commit the fix on the current feature branch and push; never push to `main`.
+5. **Commit & push** — because the user invoked this skill to drive CI green, commit
+   the fix and push **on the current feature branch only**; never commit or push to `main`.
 6. **Re-trigger** — use the trigger method determined above.
 7. **Wait** — poll `gh run watch` until the new run completes.
 8. If still failing, go to step 1.
@@ -41,6 +42,8 @@ Repeat until green or 5 iterations reached:
 After 5 iterations without green, stop and report the current state and last error to the user.
 
 ## Guardrails
+- This skill commits and pushes as an explicitly user-invoked action, on the
+  feature branch only — never autonomously and never on `main`.
 - Never push to `main`.
 - Never force-push.
 - Never use `--no-verify`.

package/src/HUMAN.md

@@ -19,7 +19,7 @@ skills are ready to use immediately. See the root `README.md` for all flags (`--
 Once the files are written:
 
 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
+2. Switch to your most capable model at medium effort using **`/model`** (e.g. an Opus-class model, as an interchangeable example — not a requirement)
 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.
 5. use **`/model`** to switch your model to your most powerful model @ low effort (to save tokens)
@@ -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

@@ -30,6 +30,11 @@ Infer the project's platform footprint before installing anything. Inspect, in o
 
 Map the footprint to candidate MCP servers. Common mappings (extend as the ecosystem grows):
 
+> The package/endpoint values below are **illustrative and may churn** — MCP
+> server names, packages, and URLs change upstream. Treat them as starting
+> points and confirm the current command against the server's own docs before
+> installing.
+
 | Signal in repo | Candidate MCP server | Package / endpoint |
 |---|---|---|
 | Azure services, Bicep, `az`, `DefaultAzureCredential` | `azure` | `npx -y @azure/mcp@latest server start` |
@@ -93,9 +98,13 @@ args = ["-y", "<package>", "..."]
 
 ## Guardrails
 
-- **No agent shall commit code.** Agents modify files and write changes; the user owns committing those changes to git.
-- Never commit to main
-- Never push to main
+- **No agent commits or pushes autonomously.** Agents modify files and write
+  changes; the user owns committing and pushing. The single exception is a skill
+  the user has explicitly invoked to do so (e.g. `watch-ci`): such a skill may
+  commit and push **only on a feature branch**, and **only to perform the action
+  the user invoked it for**. It must never commit or push unprompted.
+- **Never commit to `main`.** No exception — the carve-out above never applies to `main`.
+- **Never push to `main`.** No exception — the carve-out above never applies to `main`.
 - Always work on a feature / chore / bugfix branch
 - Never merge a Pull Request
 - Never update cloud infrastructure manually — all changes must go through IAC or deployment pipelines
@@ -113,7 +122,10 @@ Canonical skills:
 **Target resolution:** Accepts nothing (current-branch PR), a PR number, or a pasted PR URL, workflow-run URL, or workflow-file URL. Parses `owner/repo` from URLs and passes `--repo` to `gh` for remote targets.
 **Trigger-aware re-runs:** Inspects the workflow's `on:` block and classifies the trigger as auto-on-push, manual-dispatch, scheduled, or other. Re-triggers by pushing (auto-on-push), by `gh workflow run` (manual-dispatch/other), or stops with an explanation when a scheduled-only workflow cannot be forced.
 **Pipeline:** `log-reader` → `triage` → (`investigate` if HARD) → `code`, then commit/push on the feature branch and loop (max 5 iterations).
-**Guardrails:** Never pushes to `main`, never force-pushes, never `--no-verify`. For remote-repo targets it cannot edit locally, so it watches, diagnoses, and reports the fix back to the user.
+**Guardrails:** Runs only because the user invoked it; on that authority it may
+commit and push its fixes **on the feature branch only**. Never pushes or commits
+to `main`, never force-pushes, never `--no-verify`. For remote-repo targets it
+cannot edit locally, so it watches, diagnoses, and reports the fix back to the user.
 
 ### planner
 **Purpose:** Formalise the two-stage planning flow into a single command. Runs the `planner-discovery` agent (Stage 1: clarifying questions + outline), gates on explicit user approval, then runs the `planner` agent (Stage 2: full implementation plan written to `documents/plans/<YYYYMMDD>-<topic>.md`).
@@ -127,9 +139,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`.
 
 ---
 
@@ -145,7 +162,8 @@ Canonical skills:
 
 ## Documentation Rules
 
-- Update the root `README.md` on every change.
+- Update the root `README.md` when a change affects how the tool is installed,
+  invoked, or what it produces — not for internal-only changes with no user-facing effect.
 - Update the service-level `README.md` inside the affected application on relevant changes.
 - Update documentation last — after implementation and verification are complete.
 - Never leave examples, commands, file paths, or architecture descriptions stale after a change.

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 };