marcos-ai-bootstrap 0.1.6 → 0.1.8

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:
@@ -59,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.**
@@ -110,10 +120,13 @@ major version:
 
 | Commit type | Result (pre-1.0) |
 |---|---|
-| `fix:` / `feat:` / `refactor:` … | patch (e.g. `0.1.0` → `0.1.1`) |
+| `fix:` / `feat:` | patch (e.g. `0.1.0` → `0.1.1`) |
 | `feat!:` or a `BREAKING CHANGE:` footer | minor (e.g. `0.1.0` → `0.2.0`) |
 | any commit with a `Release-As: X.Y.Z` footer | forces exactly that version |
 
+These commit types do **not** trigger a release on their own: `refactor:`, `chore:`,
+`docs:`, `perf:`, `test:`, `ci:`, `build:`, `style:`. (`bump-patch-for-minor-pre-major`
+only sizes a bump that is already triggered — it does not make these types releasable.)
+
 Cut `1.0.0` with a `Release-As: 1.0.0` commit when the API is stable; after that, standard
-SemVer applies (`feat:` → minor, breaking → major). Non-releasable commits (e.g. `docs:`,
-`ci:`) won't create a Release PR on their own.
+SemVer applies (`feat:` → minor, breaking → major).

package/package.json

@@ -1,11 +1,14 @@
 {
   "name": "marcos-ai-bootstrap",
-  "version": "0.1.6",
+  "version": "0.1.8",
   "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; 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.
+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 `pull-request` 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,7 +55,7 @@ The full agent rules ship as `MARCOS-AI-BOOTSTRAP.md` at the repo root. Ensure t
 
 ## 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.
+Customise the `pull-request` 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).
@@ -64,8 +64,8 @@ Customise the `pr` skill so it matches how THIS repository actually works, learn
    - **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.
+4. On confirmation, rewrite ONLY the "Repository conventions" block of `.agents/skills/pull-request/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 `pull-request` skill was updated.
 
 ## Guardrails
 - Never commit or push - you edit agent and skill files and MCP config; the user commits.

package/src/.agents/skills/{pr → pull-request}/SKILL.md

@@ -1,9 +1,9 @@
 ---
-name: pr
+name: pull-request
 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.
+You are the pull-request 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
 

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; 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.
+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 `pull-request` 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,7 +55,7 @@ The full agent rules ship as `MARCOS-AI-BOOTSTRAP.md` at the repo root. Ensure t
 
 ## 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.
+Customise the `pull-request` 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).
@@ -64,8 +64,8 @@ Customise the `pr` skill so it matches how THIS repository actually works, learn
    - **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.
+4. On confirmation, rewrite ONLY the "Repository conventions" block of `.claude/skills/pull-request/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 `pull-request` skill was updated.
 
 ## Guardrails
 - Never commit or push — you edit agent and skill files and MCP config; the user commits.

package/src/.claude/skills/{pr → pull-request}/SKILL.md

@@ -1,9 +1,9 @@
 ---
-name: pr
+name: pull-request
 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.
+You are the pull-request 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
 

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; 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.
+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 `pull-request` 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.
@@ -57,7 +57,7 @@ Role-specific override: `infra-copilot` uses `gpt-5.4`.
 
 ## 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.
+Customise the `pull-request` 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).
@@ -66,8 +66,8 @@ Customise the `pr` skill so it matches how THIS repository actually works, learn
    - **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.
+4. On confirmation, rewrite ONLY the "Repository conventions" block of `.github/skills/pull-request/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 `pull-request` skill was updated.
 
 ## Guardrails
 - Never commit or push — you edit agent and skill files and MCP config; the user commits.

package/src/.github/skills/{pr → pull-request}/SKILL.md

@@ -1,9 +1,9 @@
 ---
-name: pr
+name: pull-request
 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.
+You are the pull-request 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
 

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,5 +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. **`/pr`** — Open a pull request with Conventional Commit messages so the release-please workflow can cut a release once merged.
+4. **`/pull-request`** — 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,11 +139,11 @@ 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. 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.
+**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 `pull-request` 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 `pull-request` 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 `pull-request` 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
+### pull-request
 **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`.
@@ -150,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.