marcos-ai-bootstrap 0.1.0

package/.github/skills/watch-ci/SKILL.md

@@ -0,0 +1,47 @@
+---
+name: watch-ci
+description: Watch a GitHub Actions workflow, auto-fix failures via the agent pipeline (log-reader-copilot → triage-copilot → investigate-copilot → code-copilot), and re-trigger until green. Accepts nothing (current-branch PR), a PR number, or a PR/workflow-run/workflow-file URL.
+---
+
+You are the watch-ci orchestrator. Drive the CI fix loop until the target workflow is green.
+
+## Target resolution
+
+Parse the optional input argument:
+- **Empty** → look up the current-branch PR with `gh pr view`.
+- **Digits only** → treat as a PR number on the current repo.
+- **URL containing `/pull/<n>`** → PR URL; extract `owner/repo` from the URL and pass `--repo owner/repo` to all `gh` calls.
+- **URL containing `/actions/runs/<id>`** → direct run URL; extract the run ID and `owner/repo`.
+- **URL containing `/actions/workflows/<file>`** or **`/blob/<ref>/.github/workflows/<file>`** → workflow-file URL; extract `owner/repo` and the workflow file name.
+
+## Trigger-type detection
+
+After identifying the failing workflow file, fetch its `on:` block and classify:
+
+| `on:` block | Trigger type | Re-trigger method |
+|---|---|---|
+| Contains `push` or `pull_request` | auto-on-push | Commit and push on the feature branch |
+| Contains `workflow_dispatch` (without push/PR) | manual-dispatch | `gh workflow run <file> --repo owner/repo` |
+| Only `schedule` | scheduled-only | **Stop** — cannot force; report the fix to the user |
+| Anything else | manual-dispatch | `gh workflow run <file> --repo owner/repo` |
+
+## Fix loop (max 5 iterations)
+
+Repeat until green or 5 iterations reached:
+
+1. **Collect** — invoke the `log-reader-copilot` agent to gather logs and produce a structured diagnostic report.
+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`.
+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.
+
+After 5 iterations without green, stop and report the current state and last error to the user.
+
+## Guardrails
+- Never push to `main`.
+- Never force-push.
+- Never use `--no-verify`.
+- For remote-repo targets this agent cannot edit locally: diagnose, propose the fix, and report back to the user without pushing.

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Marco Petralia
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,117 @@
+# marcos-ai-bootstrap
+
+AI tools for doing work. No overcomplications.
+
+Tool-agnostic agent/skill network that is built around a basic flow of plan -> implement -> deploy -> fix -> deploy etc.
+
+Currently supporting **Claude Code**, **Codex**, and **GitHub Copilot CLI** but easily adjustable to fit your workflow.
+
+See [`HUMAN.md`](./HUMAN.md) for the day-to-day workflow once the network is set up.
+
+## Quick start: the `marcos-ai-bootstrap` CLI
+
+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:
+
+```bash
+npx marcos-ai-bootstrap --copilot        # GitHub Copilot CLI agents + skills
+npx marcos-ai-bootstrap --claude         # Claude Code agents + skills
+npx marcos-ai-bootstrap --codex          # Codex agents + skills
+npx marcos-ai-bootstrap --claude --codex # combine any subset
+npx marcos-ai-bootstrap --all            # every tool at once
+```
+
+Run it from the root of the repository you want to bootstrap. It writes `AGENTS.md`
+and `HUMAN.md` (the tool-agnostic rules + human guide) alongside
+the agent/skill files for whichever tool(s) you selected:
+
+| Flag | Writes |
+|---|---|
+| `--claude` | `.claude/agents/*.md`, `.claude/skills/**/SKILL.md`, `CLAUDE.md` (`@AGENTS.md` stub) |
+| `--codex` | `.codex/agents/*.toml`, `.agents/skills/**/SKILL.md` |
+| `--copilot` | `.github/agents/*.agent.md`, `.github/skills/**/SKILL.md`, `.github/copilot-instructions.md` |
+| `--all` | all of the above |
+
+### Options
+
+| Flag | Effect |
+|---|---|
+| `--dest <path>` | Target directory (default: current working directory) |
+| `--force` | Overwrite files that already exist (default: skip existing files) |
+| `--dry-run` | Print what would be written without touching disk |
+| `-h`, `--help` | Show usage |
+
+Existing files are never clobbered unless you pass `--force`, so it's safe to re-run
+`marcos-ai-bootstrap` in a repo that already has some of the network materialised (e.g. to add
+`--codex` support to a repo that only had `--copilot` before).
+
+### Installing globally instead of via `npx`
+
+```bash
+npm install -g marcos-ai-bootstrap
+marcos-ai-bootstrap --all
+```
+
+## Repository layout
+
+- `src/AGENTS.md`, `src/HUMAN.md` — the **canonical, shipped** copies. These are the source
+  of truth the CLI reads and writes into target repos (as root-level `AGENTS.md`/`HUMAN.md`).
+- `AGENTS.md`, `HUMAN.md` (repo root) — this repository's **own self-hosting** copies, used
+  by the agent network running against this repo. Kept separate from the shipped `src/` copies
+  and not published to npm.
+- `.claude/`, `.codex/`, `.github/`, `.agents/` — the already-materialised, checked-in
+  agent/skill files for this repo itself, and the templates the `marcos-ai-bootstrap` CLI ships
+  and copies into other repositories.
+- `src/bin/ai-bootstrap.js`, `src/lib/materialize.js` — the CLI implementation.
+- `src/AGENTS-BOOTSTRAP.md` — maintainer-only source of truth for each tool's
+  materialised agent/skill prompt bodies, model tier mappings, and MCP server
+  discovery/policy flow. **Not published to npm and not copied into target repos** —
+  the materialised agent/skill files under `.claude/`, `.codex/`, `.github/`, `.agents/`
+  are the shipped source of truth.
+- `src/extract-agents.py` — maintainer tool: regenerates the `.claude/`, `.codex/`,
+  `.github/`, `.agents/` template files at the repo root from `src/AGENTS-BOOTSTRAP.md`
+  after editing it. Run this after changing `src/AGENTS-BOOTSTRAP.md`, then commit the
+  regenerated templates so `marcos-ai-bootstrap` ships the update.
+
+## Maintaining this repo
+
+1. Edit `src/AGENTS-BOOTSTRAP.md` (the source of truth for agent/skill prompt bodies).
+2. Run `python src/extract-agents.py` to regenerate the materialised template files.
+3. Run `node src/bin/ai-bootstrap.js --all --dry-run --dest <scratch-dir>` to sanity-check
+   the CLI still packages everything correctly.
+4. Commit the changes.
+
+## Releasing to npm
+
+Releases are automated with [release-please](https://github.com/googleapis/release-please)
+via `.github/workflows/release.yml`, so no one commits a version bump or pushes to `main`
+directly.
+
+How it works:
+
+1. On every push to `main`, release-please opens/updates a **Release PR** that bumps the
+   version in `package.json` and updates `CHANGELOG.md`, based on the conventional-commit
+   messages since the last release.
+2. When you're ready to ship, **merge the Release PR**. That merge creates the git tag and
+   a GitHub Release.
+3. The same workflow then publishes to npm with `npm publish --provenance --access public`
+   using OIDC **trusted publishing** (no stored `NPM_TOKEN`).
+
+Bump size is derived from your commit messages:
+
+| Commit type | Result |
+|---|---|
+| `fix:` / `chore:` / `refactor:` … | patch (`0.0.1`) |
+| `feat:` … | minor |
+| `feat!:` or a `BREAKING CHANGE:` footer | major |
+| any commit with a `Release-As: X.Y.Z` footer | forces exactly that version |
+
+So the default cadence is a patch per batch of merged fixes; larger releases happen simply
+by using `feat:` or a breaking-change marker. Non-releasable commits (e.g. `docs:`, `ci:`)
+won't create a Release PR on their own.
+
+**One-time setup on npmjs.com:** configure this repository and the `Release` workflow as a
+[trusted publisher](https://docs.npmjs.com/trusted-publishers) for the `marcos-ai-bootstrap`
+package so OIDC auth works without a token. Also enable "Allow GitHub Actions to create and
+approve pull requests" in the repo's Actions settings so release-please can open the Release PR.

package/package.json

@@ -0,0 +1,37 @@
+{
+  "name": "marcos-ai-bootstrap",
+  "version": "0.1.0",
+  "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",
+  "files": [
+    "src/bin",
+    "src/lib",
+    "src/AGENTS.md",
+    "src/HUMAN.md",
+    ".claude",
+    ".codex",
+    ".agents",
+    ".github/agents",
+    ".github/skills"
+  ],
+  "engines": {
+    "node": ">=16"
+  },
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/marcorpetralia/marcos-ai-bootstrap"
+  },
+  "keywords": [
+    "ai",
+    "agents",
+    "copilot",
+    "claude",
+    "codex",
+    "bootstrap",
+    "cli"
+  ]
+}

package/src/AGENTS.md

@@ -0,0 +1,200 @@
+# Agent Rules
+
+This file is tool-agnostic. Drop it into any repository and reference it from your AI tool's config entry-point (e.g. `CLAUDE.md` via `@AGENTS.md`, `.github/copilot-instructions.md`, `.opencode/instructions.md`) to immediately apply these rules and bootstrap the agent network.
+
+For tool-specific agent materialisation instructions (file templates, model IDs, config paths), see `AGENTS-BOOTSTRAP.md`.
+
+---
+
+## Bootstrap
+
+At the start of every session:
+1. Confirm this file has been read.
+2. Identify which tool you are running under.
+3. Follow the bootstrap instructions in `AGENTS-BOOTSTRAP.md` for that tool to verify the agent network **and the skill network** are fully materialised. Create any missing agents or skills before starting any other work.
+4. Discover, policy-check, and configure the applicable **MCP servers** as described in the MCP Servers section of `AGENTS-BOOTSTRAP.md`. Use MCP servers wherever applicable — prefer them for authoritative, live platform access (e.g. Azure, Cloudflare) over guessing or stale knowledge, subject to organization policy.
+
+---
+
+## 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
+- 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
+
+---
+
+## Skills
+
+Skills are reusable, user-invocable orchestration workflows (slash commands) that drive the agent network. They are tool-specific in how they are materialised — see `AGENTS-BOOTSTRAP.md` for file templates, paths, and discovery rules for your tool.
+
+Canonical skills:
+
+### watch-ci
+**Purpose:** Watch a GitHub Actions workflow, auto-fix failures through the agent pipeline, and re-trigger correctly until the build is green.
+**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.
+
+### 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`).
+**Pipeline:** `planner-discovery` → (user approval) → `planner`.
+**Guardrails:** Never implements or writes code. Stage 2 runs only after the user approves the Stage 1 outline. Only the `planner` agent writes to `documents/plans/`. Hands off to the `implement` skill for execution.
+
+### implement
+**Purpose:** Execute an existing plan from `documents/plans/` (path passed by the user, e.g. `documents/plans/20260622-ui-bugs.md`), dispatching each phase to the agent the plan designates and using the branch the plan names.
+**Target resolution:** Required plan file path. Parses branch, phases, designated agent per phase, files, and acceptance criteria from the plan.
+**Pipeline:** For each phase in order, route to the plan's designated canonical agent (`code` / `docs` / `infra` / `test-runner` / `explorer` / etc.); verify acceptance criteria before advancing.
+**Guardrails:** Never commits or pushes — agents edit files, the user commits. Never works on `main` (uses the plan's branch). Honours each phase's agent designation exactly; stops on a failed phase.
+
+### initialize
+**Purpose:** One-time environment reconciliation. Discovers applicable MCP servers (via the MCP Servers discovery → policy-check → install flow) and, with user approval, installs and wires them into the `infra` and `planner` agents. Discovers where plan documents actually live in the repo and, after explicit user confirmation, wires the `planner`, `implement`, and `docs` agents/skills to that location. Then verifies every agent's configured model exists in the current tool and, for any missing model, prompts the user to pick the closest available match from a dropdown and rewrites the agent files.
+**Pipeline:** MCP discovery → user approval → install + wire agents → plans-location discovery → user confirmation → rewrite plan-location references → model availability check → user picks replacements → rewrite agent files.
+**Guardrails:** Never commits or pushes. Only edits agent/skill files and MCP config — never source code. Never installs a policy-blocked or unapproved server. Never changes the plans location without explicit user confirmation. Idempotent.
+
+---
+
+## Delivery Rules
+
+- Write or update tests first when a change can be covered by automated tests.
+- For bug fixes, add a regression test before changing the implementation.
+- Make the smallest change that fixes the root cause — no broad refactors unless that is the explicit task.
+- Validate each edited slice immediately with the narrowest relevant test, lint, or build command.
+- Do not declare a task done if relevant tests, lint, or type checks are failing (unless the user explicitly accepts that state).
+
+---
+
+## Documentation Rules
+
+- Update the root `README.md` on every change.
+- 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.
+
+---
+
+## Change Discipline
+
+- Prefer focused patches over broad refactors.
+- Preserve existing conventions unless the task explicitly changes them.
+- Do not add dependencies without a concrete need and a corresponding documentation update.
+- If a subdirectory contains its own `AGENTS.md`, follow the more specific file in addition to this one.
+
+---
+
+## Memory Location
+
+- Store task notes, handoff notes, decisions, and implementation checklists as Markdown files under `agents/`.
+- Name files by date and topic, e.g. `agents/2026-05-22-feature-x.md`.
+- Remove or update stale notes when they no longer match the codebase.
+- Do not commit ephemeral scratch notes — only durable decisions and handoffs.
+
+---
+
+## Agent Network
+
+These are the canonical agent roles. They are defined here without tool-specific syntax. See `AGENTS-BOOTSTRAP.md` for how to materialise them in your specific tool.
+
+Model tiers used below:
+- **High** — most capable; use for planning and complex cross-file reasoning (e.g. Opus-class)
+- **Standard** — fast and accurate; use for code, infra, tests, orchestration (e.g. Sonnet-class)
+- **Fast** — lightweight; use for docs and read-only research (e.g. Haiku-class)
+
+---
+
+### planner
+**Tiers:** Standard (Stage 1) → High (Stage 2)
+**Purpose:** Creates structured, phased implementation plans in two gated stages. Writes the final plan to `documents/plans/`. Does not implement — requires explicit user approval between stages and before any code is written.
+
+**Stage 1 — Discovery & Outline (Standard tier)**
+- Ask lots of clarifying questions — be exhaustive. The goal of Stage 1 is to find out everything about what the user has asked for: scope and boundaries, expected behaviour and edge cases, inputs and outputs, affected components, constraints, dependencies, and success criteria. Do not assume — surface every ambiguity and keep asking until nothing material about the task is left unknown.
+- Explore the codebase and any relevant context.
+- Produce a concise outline: goal, high-level phases, open questions.
+- Stop and present the outline. Ask the user for explicit approval to proceed to Stage 2.
+
+**Stage 2 — Full Implementation Plan (High tier)**
+- Using the approved outline, produce a complete plan written to `documents/plans/<date>-<topic>.md`.
+- Plan structure: Goal, Constraints, Phases (objective / agent / files / acceptance criteria), Open questions, Risks.
+- Stop and present the plan. Ask the user for explicit approval before any implementation begins.
+
+**Rules:**
+- Never begin implementation.
+- Specify a branch name in the plan.
+- Cross-reference related notes in `agents/` or existing plans in `documents/plans/`.
+
+### code
+**Tier:** Standard
+**Purpose:** Implements focused code changes — features, bug fixes, explicit refactors.
+**Rules:**
+- Tests first; regression test before fixing a bug.
+- Smallest change that satisfies the requirement. No surrounding cleanup.
+- Validate with the narrowest relevant test or lint command after each edit.
+- Do not touch documentation — hand that off to the docs agent.
+
+### docs
+**Tier:** Fast
+**Purpose:** Updates README files and documentation only. Runs after implementation is verified.
+**Rules:**
+- Never modifies code, config, or infrastructure files.
+- Keep examples, commands, paths, and architecture descriptions accurate.
+- Prefer bullet lists and tables over prose.
+
+### infra
+**Tier:** Standard
+**Purpose:** Modifies infrastructure as code — Bicep, Terraform, pipeline YAML, IAC config.
+**Rules:**
+- Never runs manual CLI commands against shared or production environments.
+- All changes go through IAC files and deployment pipelines.
+- Lint/validate IAC before declaring done.
+- Do not change application code.
+
+### explorer
+**Tier:** Fast
+**Purpose:** Read-only codebase research — finding files, tracing call paths, locating symbols, understanding architecture.
+**Rules:**
+- No file writes, edits, or state-modifying shell commands.
+- Return a concise, structured report.
+- Run independent searches in parallel.
+
+### test-runner
+**Tier:** Standard
+**Purpose:** Runs tests, diagnoses failures, fixes broken tests, adds regression tests.
+**Rules:**
+- Run the narrowest test first (single file / single test) before the full suite.
+- Fix failures with the smallest code change possible.
+- Write a regression test before fixing a bug if one was not provided.
+- Do not change production code beyond what is needed to make tests pass.
+- Report final pass/fail counts before declaring done.
+
+### log-reader
+**Tier:** Fast
+**Purpose:** Stage 1 of bug fix mode. Gathers logs, error messages, and diagnostics from the environment or provided context.
+**Rules:**
+- Read-only. Collect all relevant logs, stack traces, error messages, and diagnostic output.
+- Synthesize findings into a concise diagnostic report.
+- Pass all findings and context to the triage agent for classification.
+- Do not speculate on fixes — focus on accurate data collection and presentation.
+
+### triage
+**Tier:** Standard
+**Purpose:** Stage between log-reader and investigate in CI fix mode. Classifies the failure as easy (fix is immediately obvious and targeted) or hard (requires deeper investigation).
+**Rules:**
+- Receive the diagnostic report from log-reader.
+- Explore the codebase as needed to understand the failing code.
+- Output EASY with a specific file/line fix suggestion, or HARD with starting points for the investigate agent.
+- Never implement the fix.
+- Classify as EASY only when confident the fix is a single targeted change.
+
+### investigate
+**Tier:** High
+**Purpose:** Stage 2 of bug fix mode. Analyzes diagnostics from log-reader and pinpoints root cause.
+**Rules:**
+- Receive and analyze the diagnostic report from log-reader.
+- Explore the codebase to understand the affected systems and call paths.
+- Produce a concise root-cause analysis and recommended fix strategy.
+- Stop before implementation — hand off to the code agent to apply the fix.
+- Do not implement the fix yourself.

package/src/HUMAN.md

@@ -0,0 +1,31 @@
+# Human Guide
+
+A quick reference for working with the AI agent network in this repository.
+
+## First-time setup
+
+Fastest path — use the `marcos-ai-bootstrap` CLI (no AI turn required, works in any repo, any OS):
+
+```powershell
+npx marcos-ai-bootstrap --copilot   # or --claude, --codex, or --all
+```
+
+This instantly writes `AGENTS.md`, `HUMAN.md`, and the fully materialised agent/skill
+files for the tool(s) you chose into the current directory. That's it — the agents and
+skills are ready to use immediately. See the root `README.md` for all flags (`--force`,
+`--dry-run`, `--dest`).
+
+Once the files are written:
+
+1. Confirm `AGENTS.md`, `HUMAN.md`, and your tool's agent/skill files are present in the repo.
+2. Switch to your most powerful model at medium effort using **`/model`** e.g. opus 4.8 @ medium effort
+3. Run the **`/initialize`** skill once to reconcile MCP servers, plan-document location, and model IDs with your environment.
+4. **`/clear`** — Clear the context window.
+5. use **`/model`** to switch your model to your most powerful model @ low effort (to save tokens)
+
+## Basic workflow
+
+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.

package/src/bin/ai-bootstrap.js

@@ -0,0 +1,115 @@
+#!/usr/bin/env node
+"use strict";
+
+const path = require("path");
+const { materialize, TOOLS } = require("../lib/materialize");
+
+const TOOL_NAMES = Object.keys(TOOLS);
+
+const HELP = `
+marcos-ai-bootstrap - materialise a tool-agnostic AI agent/skill network into any repository
+
+Usage:
+  marcos-ai-bootstrap [--claude] [--codex] [--copilot] [--all] [options]
+
+Tool flags (combine as many as you like):
+  --claude          Claude Code agents (.claude/agents), skills (.claude/skills), CLAUDE.md
+  --codex           Codex agents (.codex/agents), skills (.agents/skills)
+  --copilot         GitHub Copilot CLI agents (.github/agents), skills (.github/skills),
+                     .github/copilot-instructions.md
+  --all             All of the above
+
+Always written alongside any tool flag:
+  AGENTS.md, HUMAN.md (tool-agnostic rules + human guide)
+
+Options:
+  --dest <path>     Target directory (default: current working directory)
+  --force           Overwrite files that already exist (default: skip existing files)
+  --dry-run         Show what would be written without writing anything
+  -h, --help        Show this help text
+
+Examples:
+  npx marcos-ai-bootstrap --copilot
+  npx marcos-ai-bootstrap --claude --codex --dry-run
+  npx marcos-ai-bootstrap --all --force
+`;
+
+function parseArgs(argv) {
+  const opts = { tools: [], dest: undefined, force: false, dryRun: false, help: false };
+  for (let i = 0; i < argv.length; i++) {
+    const arg = argv[i];
+    switch (arg) {
+      case "--all":
+        opts.tools = TOOL_NAMES.slice();
+        break;
+      case "--claude":
+      case "--codex":
+      case "--copilot":
+        opts.tools.push(arg.slice(2));
+        break;
+      case "--dest":
+        opts.dest = argv[++i];
+        break;
+      case "--force":
+        opts.force = true;
+        break;
+      case "--dry-run":
+        opts.dryRun = true;
+        break;
+      case "-h":
+      case "--help":
+        opts.help = true;
+        break;
+      default:
+        console.error(`Unknown argument: ${arg}\n`);
+        opts.help = true;
+        opts.unknown = true;
+    }
+  }
+  opts.tools = Array.from(new Set(opts.tools));
+  return opts;
+}
+
+function main() {
+  const opts = parseArgs(process.argv.slice(2));
+
+  if (opts.help || opts.tools.length === 0) {
+    console.log(HELP);
+    process.exit(opts.unknown || opts.tools.length === 0 ? 1 : 0);
+  }
+
+  const destRoot = path.resolve(opts.dest || process.cwd());
+  const { results } = materialize(opts.tools, {
+    destRoot,
+    force: opts.force,
+    dryRun: opts.dryRun,
+  });
+
+  const toolLabels = opts.tools.map((t) => TOOLS[t].label).join(", ");
+  console.log(
+    `${opts.dryRun ? "[dry-run] " : ""}Materialising ${toolLabels} into ${destRoot}\n`
+  );
+
+  const byStatus = { created: [], overwritten: [], "skipped-exists": [], "missing-source": [] };
+  for (const r of results) {
+    (byStatus[r.status] || (byStatus[r.status] = [])).push(r.relPath);
+  }
+
+  for (const r of byStatus.created) console.log(`  created      ${r}`);
+  for (const r of byStatus.overwritten) console.log(`  overwritten  ${r}`);
+  for (const r of byStatus["skipped-exists"]) console.log(`  skipped      ${r} (already exists, use --force to overwrite)`);
+  for (const r of byStatus["missing-source"]) console.log(`  MISSING      ${r} (not bundled in this package)`);
+
+  console.log(
+    `\n${byStatus.created.length} created, ${byStatus.overwritten.length} overwritten, ` +
+      `${byStatus["skipped-exists"].length} skipped, ${results.length} total.`
+  );
+
+  if (!opts.dryRun) {
+    console.log(
+      `\nDone. Open AGENTS.md / HUMAN.md, then start your AI tool in ${destRoot} to begin.`
+    );
+  }
+}
+
+main();