marcos-ai-bootstrap

Simple agent workflows designed for getting work done, as quickly and cheaply as possible whilst ensuring guardrails are followed.

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" for the current version and release process.

See 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:

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 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. 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 (Codex reads the always-written AGENTS.md) | | --copilot | .github/agents/*.agent.md, .github/skills/**/SKILL.md, .github/copilot-instructions.md (append @../MARCOS-AI-BOOTSTRAP.md include) | | --all | all of the above |

Options

| 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 | | --gitignore | Add the materialised agents/skills/templates to .gitignore instead of tracking them, and skip wiring any instruction entry-point (AGENTS.md, CLAUDE.md, .github/copilot-instructions.md) | | -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).

Pass --gitignore if you'd rather not commit the materialised network to your repo — useful for a personal/local setup, or when your team hasn't agreed to check it in yet. It appends the relevant paths under a # Marcos AI-Bootstrap (materialised files) heading in .gitignore (creating the file if absent, extending it on re-run without duplicating entries) and leaves your own AGENTS.md/CLAUDE.md/.github/copilot-instructions.md untouched.

Installing globally instead of via npx

npm install -g marcos-ai-bootstrap
marcos-ai-bootstrap --all

Demo

Repository layout

Everything the CLI materialises into a target repo is shipped from src/; src/ is the single source of truth.

Shipped source of truth files (in src/):

• src/MARCOS-AI-BOOTSTRAP.md, src/HUMAN.md — canonical agent network and human workflow rules.
• src/documents/templates/plan-template.md — canonical plan template scaffold.
• src/.claude/agents/, src/.claude/skills/, src/.codex/agents/, src/.codex/, src/.github/agents/, src/.github/skills/, src/.agents/skills/ — tool agent/skill template files materialised by the CLI.

Self-hosted copies (repo root) — NOT published to npm:

• MARCOS-AI-BOOTSTRAP.md, HUMAN.md (repo root) — this repository's own self-hosted rules copies, used by the agent network running against this repo. The root AGENTS.md, CLAUDE.md, and .github/copilot-instructions.md are thin entry-points that @-include MARCOS-AI-BOOTSTRAP.md.
• documents/templates/plan-template.md, .claude/, .codex/, .github/agents/, .github/skills/, .agents/skills/ — regenerated from src/ for this repo's own agents (not shipped).
• .github/workflows/ — this repo's own CI/CD; not shipped.

Tooling:

• src/bin/ai-bootstrap.js, src/lib/materialize.js — the CLI implementation.
• src/AGENTS-BOOTSTRAP.md — maintainer-only source of truth for each tool's materialised agent/skill prompt bodies and model tier mappings. References the MCP server discovery flow from the shipped MARCOS-AI-BOOTSTRAP.md. Not published to npm.
• src/extract-agents.py — maintainer tool: regenerates the shipped agent/skill template files under src/.claude/, src/.codex/, src/.github/agents/, src/.github/skills/, src/.agents/skills/ from src/AGENTS-BOOTSTRAP.md, then syncs this repo's root self-hosted copies from src/ (unless --src-only is passed). Run this after changing src/AGENTS-BOOTSTRAP.md.

Maintaining this repo

1. Edit src/AGENTS-BOOTSTRAP.md (the source of truth for agent/skill prompt bodies).
2. Run python src/extract-agents.py to regenerate the shipped agent/skill templates under src/.claude/, src/.codex/, src/.github/agents/, src/.github/skills/, src/.agents/skills/ and sync this repo's root self-hosted copies from src/ (it invokes the CLI for you). Pass --src-only to write src/ alone.
3. Run node src/bin/ai-bootstrap.js --all --dry-run --dest <scratch-dir> to sanity-check the CLI packages everything correctly.
4. Commit the changes.

Releasing to npm

Releases are automated with 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).

The published package appears at npmjs.com/package/marcos-ai-bootstrap.

Bump size is derived from your commit messages. While the package is pre-1.0, the config (bump-minor-pre-major, bump-patch-for-minor-pre-major) keeps breaking changes off the major version:

| Commit type | Result (pre-1.0) | |---|---| | 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).