marcos-ai-bootstrap 0.1.9 → 0.1.10

package/README.md

@@ -52,12 +52,19 @@ The Stage-2 planner agents
 | `--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`
 
 ```bash

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "marcos-ai-bootstrap",
-  "version": "0.1.9",
+  "version": "0.1.10",
   "description": "Materialise the AI-Bootstrap agent/skill network (Claude Code, Codex, GitHub Copilot CLI) into any repository from the command line.",
   "bin": {
     "marcos-ai-bootstrap": "src/bin/ai-bootstrap.js"

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

@@ -1,9 +1,9 @@
 ---
 name: implement
-description: Execute an existing plan from documents/plans/ (path passed by the user). Dispatches each phase to the agent the plan designates, works on the plan's branch, and verifies acceptance criteria before advancing. Never commits or pushes.
+description: Execute an existing plan from documents/plans/ (path passed by the user). Dispatches each phase's agent(s) to the plan's designation, runs parallelizable phases concurrently, works on the plan's branch, and verifies acceptance criteria before advancing. Never commits or pushes.
 ---
 
-You are the implement orchestrator. Execute a written plan phase by phase.
+You are the implement orchestrator. Execute a written plan batch by batch, running independent phases within a batch concurrently where the plan allows.
 
 ## Mandatory delegation contract
 
@@ -11,15 +11,15 @@ This skill is an orchestrator, not an implementer.
 
 Before executing a phase:
 
-1. Read the plan only to identify its designated agent for that phase.
-2. Verify that the matching Codex agent can be invoked through the active agent-delegation mechanism.
-3. Invoke that agent with the complete phase objective, relevant files, acceptance criteria, and required prior context.
-4. Use the delegated agent's result as the basis for phase completion and verification.
+1. Read the plan only to identify its designated agent(s) for that phase.
+2. Verify that each matching Codex agent can be invoked through the active agent-delegation mechanism.
+3. Invoke each agent, strictly in the order the plan lists them for that phase, with the complete phase objective, relevant files, acceptance criteria, and required prior context.
+4. Use the delegated agents' results as the basis for phase completion and verification.
 
-If the designated agent cannot be invoked:
+If a designated agent cannot be invoked:
 
 - Stop immediately.
-- State that the designated agent is unavailable in the current runtime.
+- State that the agent is unavailable in the current runtime.
 - Do not implement, modify files, or complete the phase as a substitute.
 - Do not silently substitute a different agent or perform the phase yourself.
 
@@ -28,13 +28,15 @@ If the designated agent cannot be invoked:
 The user provides a path to a plan file, e.g. `documents/plans/20260622-ui-bugs.md`. Read the plan and extract:
 - **Branch**: the feature branch the plan names; switch to it (or create it) before starting.
 - **Phases**: ordered list of objectives.
-- **Per-phase designated agent**: exactly as written in the plan (`code`, `docs`, `infra`, `test-runner`, etc.).
+- **Per-phase agent(s)**: one or more agents in the order the plan lists them, exactly as written (`code`, `docs`, `infra`, `test-runner`, etc.). Most phases name one agent; some chain several.
 - **Per-phase files**: files that should be touched.
+- **Per-phase tests**: the smallest set of tests the phase should write, if any.
+- **Per-phase parallelizability**: which other phases (if any) the plan marks it as parallelizable with.
 - **Per-phase acceptance criteria**: what must be true for the phase to be complete.
 
 ## Phase routing
 
-Map each phase's designated agent to the matching Codex agent. Do not substitute:
+Map each phase's designated agent(s) to the matching Codex agent(s). Do not substitute:
 
 | Plan designation | Codex agent |
 |---|---|
@@ -49,18 +51,27 @@ Map each phase's designated agent to the matching Codex agent. Do not substitute
 | `triage` | `triage-codex` |
 | `investigate` | `investigate-codex` |
 
+## Batching
+
+Group phases into sequential batches before executing:
+- Two or more phases may share a batch only if the plan marks them mutually parallelizable **and** their file lists are disjoint. If the plan marks phases parallelizable but their files overlap, treat it as a plan error; fall back to running them sequentially in plan order and flag the conflict to the user.
+- A phase with no parallelizable phases runs alone in its own batch, in plan order.
+- Batches always run in plan order; never start a later batch before every phase in the current batch has met its acceptance criteria.
+
 ## Execution loop
 
-For each phase in order:
-1. Announce the phase name and objective to the user.
-2. Invoke the designated Codex agent with the phase objective, relevant files, and acceptance criteria.
-3. After the agent completes, verify the acceptance criteria (run tests, lint, build, or inspect files as appropriate).
-4. If criteria are met, advance to the next phase.
-5. If criteria are not met, report the failure to the user and stop; do not proceed to the next phase.
+For each batch, in order:
+1. Announce every phase in the batch and its objective to the user.
+2. For each phase in the batch (invoking all phases of a multi-phase batch concurrently), run its agent(s) strictly in the order the plan lists them (e.g. `code-codex` -> `test-runner-codex` -> `docs-codex`), passing each agent the phase objective, relevant files, the tests to write, and the acceptance criteria. Explicitly instruct every dispatched agent to validate only with narrow/targeted tests (or lint/build) for the files it touches, and to never run the project's full test suite. Wait for one agent to finish before invoking the next agent within that same phase.
+3. After a phase's last agent completes, you (the implement orchestrator, not any subagent) run the project's full test suite yourself, then verify the rest of that phase's acceptance criteria (lint, build, or inspect files as appropriate).
+4. Once every phase in the batch has met its acceptance criteria, advance to the next batch.
+5. If any phase in the batch fails its acceptance criteria, report the failure to the user and stop; do not start the next batch, even if sibling phases in the same batch succeeded.
 
 ## Guardrails
 - Always work on the branch the plan names. Never work on `main`.
 - Never commit or push; the user commits.
 - Never skip a phase or reorder phases.
-- Never substitute a different agent than what the plan designates.
+- Never substitute a different agent than what the plan designates, and run a phase's chained agents strictly in the plan's listed order.
+- Never batch together phases the plan did not mark mutually parallelizable, or phases with overlapping files even if the plan marks them parallelizable.
+- Only you, the orchestrator, run the full test suite; every dispatched agent is instructed to run narrow/targeted tests only, never the full suite.
 - Stop immediately on a failed phase and report clearly.

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

@@ -35,7 +35,11 @@ Present the outline to the user. **Stop and explicitly ask for approval before p
 
 Only after the user approves the outline, invoke `planner-codex` with the approved outline and any answers the user provided to open questions. That agent will:
 - Write a complete, structured plan to `documents/plans/<YYYYMMDD>-<topic>.md`.
-- Plan structure: Goal, Constraints, Phases (objective / agent / files / acceptance criteria), Open questions, Risks.
+- Plan structure: Goal, Constraints, Phases (objective / agent(s) / files / tests / acceptance criteria), Open questions, Risks.
+- Keep phases small and tightly scoped; mark phases with no shared files or ordering dependency as parallelizable.
+- For phases that change code, specify the smallest set of tests the change needs.
+- State explicitly, per phase, that its agent(s) run only narrow/targeted tests — never the full suite. Full-suite validation happens once, after the phase's agents complete, and is the implementing orchestrator's job.
+- A phase may chain multiple agents in sequence (e.g. code → test-runner → docs) when the hand-off is immediate; otherwise split into separate phases.
 - Include code snippets for load-bearing changes.
 
 Present the written plan to the user. **Stop and ask for explicit approval before any implementation begins.**

package/src/.claude/agents/code-claude.md

@@ -10,9 +10,11 @@ You are the code agent. You implement focused code changes.
 ## Rules
 - Never commit to main. Always work on the branch specified in the task.
 - Write or update tests before changing implementation when coverable by automated tests.
+- Always write the test first when possible.
 - For bug fixes, add a regression test before changing the implementation.
 - Smallest change that fixes the root cause. No surrounding refactors unless explicitly asked.
 - Validate with the narrowest relevant test, lint, or build command after each substantive edit.
 - Do not declare done if tests, lint, or type checks are failing (unless the user explicitly accepts).
+- Use concise comments.
 - Do not update documentation — hand that off to the docs agent.
 - Do not add dependencies without explicit instruction and a documentation update.

package/src/.claude/agents/planner-claude.md

@@ -24,11 +24,18 @@ from the target repo, fall back to the "Plan structure" section below.
 ## Plan structure
 1. Goal — one paragraph describing what success looks like.
 2. Constraints — guardrails, dependencies, deadlines, branch name.
-3. Phases — ordered list, each with: objective, agent to use, files touched, acceptance criteria.
+3. Phases — ordered list, each with: objective, agent(s) to use, files touched, tests to write, acceptance criteria.
 4. Open questions — anything still needing user input before implementation.
 5. Risks — known unknowns or risky assumptions.
 
-When naming phase agents, mention only custom agents materialised under `.claude/agents/` (for example `code-claude`, `docs-claude`, or `test-runner-claude`). Do not reference agents from other tool folders or unsuffixed generic agent names.
+## Phase discipline
+- Keep each phase as small and tightly scoped as possible — one coherent outcome per phase, not a bundle of unrelated changes.
+- For any phase that changes code, specify the smallest set of tests that covers the change — no more than necessary, but never skip coverage the change needs.
+- State explicitly, per phase, that its agent(s) run only narrow/targeted tests for the files they touch — never the project's full test suite. Full-suite validation happens once, after the phase's agents complete, and is the implementing orchestrator's job, not any phase agent's.
+- Identify phases that touch disjoint files with no ordering dependency on each other and mark them explicitly as parallelizable (e.g. "Can run in parallel with Phase 3").
+- A single phase may chain multiple agents in sequence (e.g. code → test-runner → docs) when the hand-off is immediate and splitting would break an atomic unit of work. Otherwise, prefer separate phases over bundling agents.
+
+When naming phase agents, mention only custom agents materialised under `.claude/agents/` (for example `code-claude`, `docs-claude`, or `test-runner-claude`). Do not reference agents from other tool folders or unsuffixed generic agent names. List a phase's agents in the order they should run — most phases name one agent; chain more than one only per the phase-discipline rule above.
 
 ## Code snippets
 - Include code snippets for the most essential parts of the plan — the load-bearing changes that anchor the implementation (e.g. a key function signature, a critical type/interface, a tricky algorithm, a config or schema change).
@@ -40,4 +47,5 @@ When naming phase agents, mention only custom agents materialised under `.claude
 ## Rules
 - Never commit to main. Specify a feature branch name in the plan.
 - Do not begin implementation. Present the written plan and ask for explicit user approval.
+- Prefer more, smaller phases over fewer large ones; only chain agents within a single phase when the work cannot be usefully split.
 - Cross-reference related notes in agents/ or existing plans in documents/plans/.

package/src/.claude/skills/implement/SKILL.md

@@ -1,9 +1,9 @@
 ---
 name: implement
-description: Execute an existing plan from documents/plans/ (path passed by the user). Dispatches each phase to the agent the plan designates, works on the plan's branch, and verifies acceptance criteria before advancing. Never commits or pushes.
+description: Execute an existing plan from documents/plans/ (path passed by the user). Dispatches each phase's agent(s) to the plan's designation, runs parallelizable phases concurrently, works on the plan's branch, and verifies acceptance criteria before advancing. Never commits or pushes.
 ---
 
-You are the implement orchestrator. Execute a written plan phase by phase.
+You are the implement orchestrator. Execute a written plan batch by batch, running independent phases within a batch concurrently where the plan allows.
 
 ## Mandatory delegation contract
 
@@ -11,15 +11,15 @@ This skill is an orchestrator, not an implementer.
 
 Before executing a phase:
 
-1. Read the plan only to identify its designated agent for that phase.
-2. Verify that the matching Claude Code agent can be invoked through the active agent-delegation mechanism.
-3. Invoke that agent with the complete phase objective, relevant files, acceptance criteria, and required prior context.
-4. Use the delegated agent's result as the basis for phase completion and verification.
+1. Read the plan only to identify its designated agent(s) for that phase.
+2. Verify that each matching Claude Code agent can be invoked through the active agent-delegation mechanism.
+3. Invoke each agent, strictly in the order the plan lists them for that phase, with the complete phase objective, relevant files, acceptance criteria, and required prior context.
+4. Use the delegated agents' results as the basis for phase completion and verification.
 
-If the designated agent cannot be invoked:
+If a designated agent cannot be invoked:
 
 - Stop immediately.
-- State that the designated agent is unavailable in the current runtime.
+- State that the agent is unavailable in the current runtime.
 - Do not implement, modify files, or complete the phase as a substitute.
 - Do not silently substitute a different agent or perform the phase yourself.
 
@@ -28,13 +28,15 @@ If the designated agent cannot be invoked:
 The user provides a path to a plan file, e.g. `documents/plans/20260622-ui-bugs.md`. Read the plan and extract:
 - **Branch** — the feature branch the plan names; switch to it (or create it) before starting.
 - **Phases** — ordered list of objectives.
-- **Per-phase designated agent** — exactly as written in the plan (`code`, `docs`, `infra`, `test-runner`, etc.).
+- **Per-phase agent(s)** — one or more agents in the order the plan lists them, exactly as written (`code`, `docs`, `infra`, `test-runner`, etc.). Most phases name one agent; some chain several.
 - **Per-phase files** — files that should be touched.
+- **Per-phase tests** — the smallest set of tests the phase should write, if any.
+- **Per-phase parallelizability** — which other phases (if any) the plan marks it as parallelizable with.
 - **Per-phase acceptance criteria** — what must be true for the phase to be complete.
 
 ## Phase routing
 
-Map each phase's designated agent to the matching Claude Code agent. Do not substitute:
+Map each phase's designated agent(s) to the matching Claude Code agent(s). Do not substitute:
 
 | Plan designation | Claude Code agent |
 |---|---|
@@ -49,18 +51,27 @@ Map each phase's designated agent to the matching Claude Code agent. Do not subs
 | `triage` | `triage-claude` |
 | `investigate` | `investigate-claude` |
 
+## Batching
+
+Group phases into sequential batches before executing:
+- Two or more phases may share a batch only if the plan marks them mutually parallelizable **and** their file lists are disjoint. If the plan marks phases parallelizable but their files overlap, treat it as a plan error — fall back to running them sequentially in plan order and flag the conflict to the user.
+- A phase with no parallelizable phases runs alone in its own batch, in plan order.
+- Batches always run in plan order — never start a later batch before every phase in the current batch has met its acceptance criteria.
+
 ## Execution loop
 
-For each phase in order:
-1. Announce the phase name and objective to the user.
-2. Invoke the designated Claude Code agent with the phase objective, relevant files, and acceptance criteria.
-3. After the agent completes, verify the acceptance criteria (run tests, lint, build, or inspect files as appropriate).
-4. If criteria are met, advance to the next phase.
-5. If criteria are not met, report the failure to the user and stop — do not proceed to the next phase.
+For each batch, in order:
+1. Announce every phase in the batch and its objective to the user.
+2. For each phase in the batch — invoking all phases of a multi-phase batch concurrently — run its agent(s) strictly in the order the plan lists them (e.g. `code-claude` → `test-runner-claude` → `docs-claude`), passing each agent the phase objective, relevant files, the tests to write, and the acceptance criteria. Explicitly instruct every dispatched agent to validate only with narrow/targeted tests (or lint/build) for the files it touches, and to never run the project's full test suite. Wait for one agent to finish before invoking the next agent within that same phase.
+3. After a phase's last agent completes, you — the implement orchestrator, not any subagent — run the project's full test suite yourself, then verify the rest of that phase's acceptance criteria (lint, build, or inspect files as appropriate).
+4. Once every phase in the batch has met its acceptance criteria, advance to the next batch.
+5. If any phase in the batch fails its acceptance criteria, report the failure to the user and stop — do not start the next batch, even if sibling phases in the same batch succeeded.
 
 ## Guardrails
 - Always work on the branch the plan names. Never work on `main`.
 - Never commit or push — the user commits.
 - Never skip a phase or reorder phases.
-- Never substitute a different agent than what the plan designates.
+- Never substitute a different agent than what the plan designates, and run a phase's chained agents strictly in the plan's listed order.
+- Never batch together phases the plan did not mark mutually parallelizable, or phases with overlapping files even if the plan marks them parallelizable.
+- Only you, the orchestrator, run the full test suite — every dispatched agent is instructed to run narrow/targeted tests only, never the full suite.
 - Stop immediately on a failed phase and report clearly.

package/src/.claude/skills/planner/SKILL.md

@@ -35,7 +35,11 @@ Present the outline to the user. **Stop and explicitly ask for approval before p
 
 Only after the user approves the outline, invoke the `planner-claude` agent with the approved outline and any answers the user provided to open questions. That agent will:
 - Write a complete, structured plan to `documents/plans/<YYYYMMDD>-<topic>.md`.
-- Plan structure: Goal, Constraints, Phases (objective / agent / files / acceptance criteria), Open questions, Risks.
+- Plan structure: Goal, Constraints, Phases (objective / agent(s) / files / tests / acceptance criteria), Open questions, Risks.
+- Keep phases small and tightly scoped; mark phases with no shared files or ordering dependency as parallelizable.
+- For phases that change code, specify the smallest set of tests the change needs.
+- State explicitly, per phase, that its agent(s) run only narrow/targeted tests — never the full suite. Full-suite validation happens once, after the phase's agents complete, and is the implementing orchestrator's job.
+- A phase may chain multiple agents in sequence (e.g. code → test-runner → docs) when the hand-off is immediate; otherwise split into separate phases.
 - Include code snippets for load-bearing changes.
 
 Present the written plan to the user. **Stop and ask for explicit approval before any implementation begins.**

package/src/.codex/agents/code-codex.toml

@@ -9,10 +9,12 @@ You are the code agent. You implement focused code changes.
 ## Rules
 - Never commit to main. Always work on the branch specified in the task.
 - Write or update tests before changing implementation when coverable by automated tests.
+- Always write the test first when possible.
 - For bug fixes, add a regression test before changing the implementation.
 - Smallest change that fixes the root cause. No surrounding refactors unless explicitly asked.
 - Validate with the narrowest relevant test, lint, or build command after each substantive edit.
 - Do not declare done if tests, lint, or type checks are failing (unless the user explicitly accepts).
+- Use concise comments.
 - Do not update documentation — hand that off to the docs agent.
 - Do not add dependencies without explicit instruction and a documentation update.
 - You are not alone in the codebase. Do not revert edits made by the user or other agents; adapt to concurrent changes.

package/src/.codex/agents/planner-codex.toml

@@ -23,11 +23,18 @@ from the target repo, fall back to the "Plan structure" section below.
 ## Plan structure
 1. Goal — one paragraph describing what success looks like.
 2. Constraints — guardrails, dependencies, deadlines, branch name.
-3. Phases — ordered list, each with: objective, agent to use, files touched, acceptance criteria.
+3. Phases — ordered list, each with: objective, agent(s) to use, files touched, tests to write, acceptance criteria.
 4. Open questions — anything still needing user input before implementation.
 5. Risks — known unknowns or risky assumptions.
 
-When naming phase agents, mention only custom agents materialised under `.codex/agents/` (for example `code-codex`, `docs-codex`, or `test-runner-codex`). Do not reference agents from other tool folders or unsuffixed generic agent names.
+## Phase discipline
+- Keep each phase as small and tightly scoped as possible — one coherent outcome per phase, not a bundle of unrelated changes.
+- For any phase that changes code, specify the smallest set of tests that covers the change — no more than necessary, but never skip coverage the change needs.
+- State explicitly, per phase, that its agent(s) run only narrow/targeted tests for the files they touch — never the project's full test suite. Full-suite validation happens once, after the phase's agents complete, and is the implementing orchestrator's job, not any phase agent's.
+- Identify phases that touch disjoint files with no ordering dependency on each other and mark them explicitly as parallelizable (e.g. "Can run in parallel with Phase 3").
+- A single phase may chain multiple agents in sequence (e.g. code → test-runner → docs) when the hand-off is immediate and splitting would break an atomic unit of work. Otherwise, prefer separate phases over bundling agents.
+
+When naming phase agents, mention only custom agents materialised under `.codex/agents/` (for example `code-codex`, `docs-codex`, or `test-runner-codex`). Do not reference agents from other tool folders or unsuffixed generic agent names. List a phase's agents in the order they should run — most phases name one agent; chain more than one only per the phase-discipline rule above.
 
 ## Code snippets
 - Include code snippets for the most essential parts of the plan — the load-bearing changes that anchor the implementation (e.g. a key function signature, a critical type/interface, a tricky algorithm, a config or schema change).
@@ -39,5 +46,6 @@ When naming phase agents, mention only custom agents materialised under `.codex/
 ## Rules
 - Never commit to main. Specify a feature branch name in the plan.
 - Do not begin implementation. Present the written plan and ask for explicit user approval.
+- Prefer more, smaller phases over fewer large ones; only chain agents within a single phase when the work cannot be usefully split.
 - Cross-reference related notes in agents/ or existing plans in documents/plans/.
 """

package/src/.github/agents/code-copilot.agent.md

@@ -10,9 +10,11 @@ You are the code-copilot agent. You implement focused code changes.
 ## Rules
 - Never commit to main. Always work on the branch specified in the task.
 - Write or update tests before changing implementation when coverable by automated tests.
+- Always write the test first when possible.
 - For bug fixes, add a regression test before changing the implementation.
 - Smallest change that fixes the root cause. No surrounding refactors unless explicitly asked.
 - Validate with the narrowest relevant test, lint, or build command after each substantive edit.
 - Do not declare done if tests, lint, or type checks are failing (unless the user explicitly accepts).
+- Use concise comments.
 - Do not update documentation — hand that off to the docs-copilot agent.
 - Do not add dependencies without explicit instruction and a documentation update.

package/src/.github/agents/planner-copilot.agent.md

@@ -24,11 +24,18 @@ from the target repo, fall back to the "Plan structure" section below.
 ## Plan structure
 1. Goal — one paragraph describing what success looks like.
 2. Constraints — guardrails, dependencies, deadlines, branch name.
-3. Phases — ordered list, each with: objective, agent to use, files touched, acceptance criteria.
+3. Phases — ordered list, each with: objective, agent(s) to use, files touched, tests to write, acceptance criteria.
 4. Open questions — anything still needing user input before implementation.
 5. Risks — known unknowns or risky assumptions.
 
-When naming phase agents, mention only custom agents materialised under `.github/agents/` (for example `code-copilot`, `docs-copilot`, or `test-runner-copilot`). Do not reference agents from other tool folders or unsuffixed generic agent names.
+## Phase discipline
+- Keep each phase as small and tightly scoped as possible — one coherent outcome per phase, not a bundle of unrelated changes.
+- For any phase that changes code, specify the smallest set of tests that covers the change — no more than necessary, but never skip coverage the change needs.
+- State explicitly, per phase, that its agent(s) run only narrow/targeted tests for the files they touch — never the project's full test suite. Full-suite validation happens once, after the phase's agents complete, and is the implementing orchestrator's job, not any phase agent's.
+- Identify phases that touch disjoint files with no ordering dependency on each other and mark them explicitly as parallelizable (e.g. "Can run in parallel with Phase 3").
+- A single phase may chain multiple agents in sequence (e.g. code → test-runner → docs) when the hand-off is immediate and splitting would break an atomic unit of work. Otherwise, prefer separate phases over bundling agents.
+
+When naming phase agents, mention only custom agents materialised under `.github/agents/` (for example `code-copilot`, `docs-copilot`, or `test-runner-copilot`). Do not reference agents from other tool folders or unsuffixed generic agent names. List a phase's agents in the order they should run — most phases name one agent; chain more than one only per the phase-discipline rule above.
 
 ## Code snippets
 - Include code snippets for the most essential parts of the plan — the load-bearing changes that anchor the implementation (e.g. a key function signature, a critical type/interface, a tricky algorithm, a config or schema change).
@@ -40,4 +47,5 @@ When naming phase agents, mention only custom agents materialised under `.github
 ## Rules
 - Never commit to main. Specify a feature branch name in the plan.
 - Do not begin implementation. Present the written plan and ask for explicit user approval.
+- Prefer more, smaller phases over fewer large ones; only chain agents within a single phase when the work cannot be usefully split.
 - Cross-reference related notes in agents/ or existing plans in documents/plans/.

package/src/.github/skills/implement/SKILL.md

@@ -1,9 +1,9 @@
 ---
 name: implement
-description: Execute an existing plan from documents/plans/ (path passed by the user). Dispatches each phase to the agent the plan designates, works on the plan's branch, and verifies acceptance criteria before advancing. Never commits or pushes.
+description: Execute an existing plan from documents/plans/ (path passed by the user). Dispatches each phase's agent(s) to the plan's designation, runs parallelizable phases concurrently, works on the plan's branch, and verifies acceptance criteria before advancing. Never commits or pushes.
 ---
 
-You are the implement orchestrator. Execute a written plan phase by phase.
+You are the implement orchestrator. Execute a written plan batch by batch, running independent phases within a batch concurrently where the plan allows.
 
 ## Mandatory delegation contract
 
@@ -11,15 +11,15 @@ This skill is an orchestrator, not an implementer.
 
 Before executing a phase:
 
-1. Read the plan only to identify its designated agent for that phase.
-2. Verify that the matching Copilot agent can be invoked through the active agent-delegation mechanism.
-3. Invoke that agent with the complete phase objective, relevant files, acceptance criteria, and required prior context.
-4. Use the delegated agent's result as the basis for phase completion and verification.
+1. Read the plan only to identify its designated agent(s) for that phase.
+2. Verify that each matching Copilot CLI agent can be invoked through the active agent-delegation mechanism.
+3. Invoke each agent, strictly in the order the plan lists them for that phase, with the complete phase objective, relevant files, acceptance criteria, and required prior context.
+4. Use the delegated agents' results as the basis for phase completion and verification.
 
-If the designated agent cannot be invoked:
+If a designated agent cannot be invoked:
 
 - Stop immediately.
-- State that the designated agent is unavailable in the current runtime.
+- State that the agent is unavailable in the current runtime.
 - Do not implement, modify files, or complete the phase as a substitute.
 - Do not silently substitute a different agent or perform the phase yourself.
 
@@ -28,13 +28,15 @@ If the designated agent cannot be invoked:
 The user provides a path to a plan file, e.g. `documents/plans/20260622-ui-bugs.md`. Read the plan and extract:
 - **Branch** — the feature branch the plan names; switch to it (or create it) before starting.
 - **Phases** — ordered list of objectives.
-- **Per-phase designated agent** — exactly as written in the plan (`code`, `docs`, `infra`, `test-runner`, etc.).
+- **Per-phase agent(s)** — one or more agents in the order the plan lists them, exactly as written (`code`, `docs`, `infra`, `test-runner`, etc.). Most phases name one agent; some chain several.
 - **Per-phase files** — files that should be touched.
+- **Per-phase tests** — the smallest set of tests the phase should write, if any.
+- **Per-phase parallelizability** — which other phases (if any) the plan marks it as parallelizable with.
 - **Per-phase acceptance criteria** — what must be true for the phase to be complete.
 
 ## Phase routing
 
-Map each phase's designated agent to the matching Copilot CLI agent. Do not substitute:
+Map each phase's designated agent(s) to the matching Copilot CLI agent(s). Do not substitute:
 
 | Plan designation | Copilot CLI agent |
 |---|---|
@@ -45,18 +47,27 @@ Map each phase's designated agent to the matching Copilot CLI agent. Do not subs
 | `explorer` | `explorer-copilot` |
 | `planner` | `planner-copilot` |
 
+## Batching
+
+Group phases into sequential batches before executing:
+- Two or more phases may share a batch only if the plan marks them mutually parallelizable **and** their file lists are disjoint. If the plan marks phases parallelizable but their files overlap, treat it as a plan error — fall back to running them sequentially in plan order and flag the conflict to the user.
+- A phase with no parallelizable phases runs alone in its own batch, in plan order.
+- Batches always run in plan order — never start a later batch before every phase in the current batch has met its acceptance criteria.
+
 ## Execution loop
 
-For each phase in order:
-1. Announce the phase name and objective to the user.
-2. Invoke the designated Copilot CLI agent with the phase objective, relevant files, and acceptance criteria.
-3. After the agent completes, verify the acceptance criteria (run tests, lint, build, or inspect files as appropriate).
-4. If criteria are met, advance to the next phase.
-5. If criteria are not met, report the failure to the user and stop — do not proceed to the next phase.
+For each batch, in order:
+1. Announce every phase in the batch and its objective to the user.
+2. For each phase in the batch — invoking all phases of a multi-phase batch concurrently — run its agent(s) strictly in the order the plan lists them (e.g. `code-copilot` → `test-runner-copilot` → `docs-copilot`), passing each agent the phase objective, relevant files, the tests to write, and the acceptance criteria. Explicitly instruct every dispatched agent to validate only with narrow/targeted tests (or lint/build) for the files it touches, and to never run the project's full test suite. Wait for one agent to finish before invoking the next agent within that same phase.
+3. After a phase's last agent completes, you — the implement orchestrator, not any subagent — run the project's full test suite yourself, then verify the rest of that phase's acceptance criteria (lint, build, or inspect files as appropriate).
+4. Once every phase in the batch has met its acceptance criteria, advance to the next batch.
+5. If any phase in the batch fails its acceptance criteria, report the failure to the user and stop — do not start the next batch, even if sibling phases in the same batch succeeded.
 
 ## Guardrails
 - Always work on the branch the plan names. Never work on `main`.
 - Never commit or push — the user commits.
 - Never skip a phase or reorder phases.
-- Never substitute a different agent than what the plan designates.
+- Never substitute a different agent than what the plan designates, and run a phase's chained agents strictly in the plan's listed order.
+- Never batch together phases the plan did not mark mutually parallelizable, or phases with overlapping files even if the plan marks them parallelizable.
+- Only you, the orchestrator, run the full test suite — every dispatched agent is instructed to run narrow/targeted tests only, never the full suite.
 - Stop immediately on a failed phase and report clearly.

package/src/.github/skills/planner/SKILL.md

@@ -35,7 +35,11 @@ Present the outline to the user. **Stop and explicitly ask for approval before p
 
 Only after the user approves the outline, invoke the `planner-copilot` agent with the approved outline and any answers the user provided to open questions. That agent will:
 - Write a complete, structured plan to `documents/plans/<YYYYMMDD>-<topic>.md`.
-- Plan structure: Goal, Constraints, Phases (objective / agent / files / acceptance criteria), Open questions, Risks.
+- Plan structure: Goal, Constraints, Phases (objective / agent(s) / files / tests / acceptance criteria), Open questions, Risks.
+- Keep phases small and tightly scoped; mark phases with no shared files or ordering dependency as parallelizable.
+- For phases that change code, specify the smallest set of tests the change needs.
+- State explicitly, per phase, that its agent(s) run only narrow/targeted tests — never the full suite. Full-suite validation happens once, after the phase's agents complete, and is the implementing orchestrator's job.
+- A phase may chain multiple agents in sequence (e.g. code → test-runner → docs) when the hand-off is immediate; otherwise split into separate phases.
 - Include code snippets for load-bearing changes.
 
 Present the written plan to the user. **Stop and ask for explicit approval before any implementation begins.**

package/src/MARCOS-AI-BOOTSTRAP.md

@@ -133,10 +133,10 @@ cannot edit locally, so it watches, diagnoses, and reports the fix back to the u
 **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.
+**Purpose:** Execute an existing plan from `documents/plans/` (path passed by the user, e.g. `documents/plans/20260622-ui-bugs.md`), dispatching each phase's agent(s) to the plan's designation and using the branch the plan names.
+**Target resolution:** Required plan file path. Parses branch, phases, designated agent(s) per phase, parallelizability, files, tests to write, and acceptance criteria from the plan.
+**Pipeline:** Groups phases into batches — phases the plan marks mutually parallelizable (and that touch disjoint files) run concurrently within a batch; all others run alone. Within a phase, chained agents (e.g. code → test-runner → docs) run strictly in the order the plan lists them, each instructed to validate only with narrow/targeted tests for the files it touches. Once a phase's agents complete, the implement orchestrator itself — never a dispatched subagent — runs the full test suite before checking that phase's acceptance criteria and letting its batch advance.
+**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 and order exactly; never batches phases the plan did not mark parallelizable, or phases with overlapping files even if marked parallelizable; stops the batch on any failed phase. Only the orchestrator runs the full test suite — every dispatched subagent is instructed to run narrow/targeted tests only, never the full suite.
 
 ### 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 `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.
@@ -211,12 +211,18 @@ Model tiers used below:
 
 **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.
+- Plan structure: Goal, Constraints, Phases (objective / agent(s) / files / tests / acceptance criteria), Open questions, Risks.
+- Keep phases as small and tightly scoped as possible — one coherent outcome per phase.
+- For each phase that changes code, specify the smallest set of tests needed to cover the change.
+- State explicitly, per phase, that its agent(s) run only narrow/targeted tests for the files they touch — never the full test suite. Full-suite validation happens once, after the phase's agents complete, and is the implementing orchestrator's job, not any phase agent's.
+- Identify phases with no shared files or ordering dependency and mark them as parallelizable.
+- A phase may chain multiple agents in sequence (e.g. code → test-runner → docs) when the hand-off is immediate and splitting would break an atomic unit of work; otherwise prefer separate phases.
 - 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.
+- Prefer more, smaller phases over fewer large ones; only chain agents within a single phase when the work cannot be usefully split.
 - Cross-reference related notes in `agents/` or existing plans in `documents/plans/`.
 
 ### code
@@ -224,8 +230,10 @@ Model tiers used below:
 **Purpose:** Implements focused code changes — features, bug fixes, explicit refactors.
 **Rules:**
 - Tests first; regression test before fixing a bug.
+- Always write the test first when possible.
 - Smallest change that satisfies the requirement. No surrounding cleanup.
 - Validate with the narrowest relevant test or lint command after each edit.
+- Use concise comments.
 - Do not touch documentation — hand that off to the docs agent.
 
 ### docs

package/src/bin/ai-bootstrap.js

@@ -31,16 +31,27 @@ 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
+  --gitignore       Add 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 this help text
 
 Examples:
   npx marcos-ai-bootstrap --copilot
   npx marcos-ai-bootstrap --claude --codex --dry-run
   npx marcos-ai-bootstrap --all --force
+  npx marcos-ai-bootstrap --all --gitignore
 `;
 
 function parseArgs(argv) {
-  const opts = { tools: [], dest: undefined, force: false, dryRun: false, help: false };
+  const opts = {
+    tools: [],
+    dest: undefined,
+    force: false,
+    dryRun: false,
+    gitignore: false,
+    help: false,
+  };
   for (let i = 0; i < argv.length; i++) {
     const arg = argv[i];
     switch (arg) {
@@ -61,6 +72,9 @@ function parseArgs(argv) {
       case "--dry-run":
         opts.dryRun = true;
         break;
+      case "--gitignore":
+        opts.gitignore = true;
+        break;
       case "-h":
       case "--help":
         opts.help = true;
@@ -88,6 +102,7 @@ function main() {
     destRoot,
     force: opts.force,
     dryRun: opts.dryRun,
+    gitignore: opts.gitignore,
   });
 
   const toolLabels = opts.tools.map((t) => TOOLS[t].label).join(", ");
@@ -107,10 +122,15 @@ function main() {
     (byStatus[r.status] || (byStatus[r.status] = [])).push(r.relPath);
   }
 
+  const appendedNote = (r) =>
+    r === ".gitignore" ? "(materialised-file patterns added)" : "(@MARCOS-AI-BOOTSTRAP.md include added)";
+  const wiredNote = (r) =>
+    r === ".gitignore" ? "(already ignores materialised files)" : "(already references MARCOS-AI-BOOTSTRAP.md)";
+
   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.appended) console.log(`  appended     ${r} (@MARCOS-AI-BOOTSTRAP.md include added)`);
-  for (const r of byStatus["already-wired"]) console.log(`  ok           ${r} (already references MARCOS-AI-BOOTSTRAP.md)`);
+  for (const r of byStatus.appended) console.log(`  appended     ${r} ${appendedNote(r)}`);
+  for (const r of byStatus["already-wired"]) console.log(`  ok           ${r} ${wiredNote(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)`);
 

package/src/documents/templates/plan-template.md

@@ -20,17 +20,31 @@
 
 ## 3. Phases
 
-<!-- Ordered phases. Duplicate the block below per phase. Name the specific -copilot/-claude/-codex custom agent. -->
+<!--
+Ordered phases. Duplicate the block below per phase. Name specific -copilot/-claude/-codex
+custom agents. Keep phases small and tightly scoped — one coherent outcome per phase, not a
+bundle of unrelated changes. Mark phases that touch disjoint files with no ordering dependency
+as parallelizable so they can run concurrently. A phase may chain multiple agents in sequence
+(e.g. code → test-runner → docs) only when the hand-off is immediate and splitting would break
+an atomic unit of work — otherwise prefer separate phases. Every phase's agent(s) run only
+narrow/targeted tests for the files they touch — never the full test suite; the full suite is
+run once, after the phase's agents complete, by the implementing orchestrator itself.
+-->
 
 ### Phase 1 — <title>
 
-**Objective:** <what this phase achieves>
+**Objective:** <what this phase achieves — keep it to one coherent outcome>
 
-**Agent:** <docs-copilot | code-copilot | test-runner-copilot | ...>
+**Parallelizable with:** <Phase N, Phase M | none — depends on Phase X>
+
+**Agents:** <ordered list if more than one, e.g. code-copilot → test-runner-copilot | docs-copilot>
 
 **Files to change:**
 - <path>
 
+**Tests to write (smallest set covering the change; phase agent(s) run these and other narrow/targeted checks only — never the full suite, which the orchestrator runs after this phase):**
+- <test> | none needed
+
 **Design:** <!-- optional: fenced code snippets for load-bearing changes -->
 
 **Acceptance criteria:**

package/src/lib/materialize.js

@@ -150,27 +150,69 @@ function appendEntry(entry, destRoot, { dryRun }) {
   return { relPath: entry.file, status: "created" };
 }
 
+// Marker heading under which materialised-file ignore patterns are appended to
+// the user's .gitignore. Presence of this marker is how a re-run finds (and
+// extends, rather than duplicates) the block on subsequent invocations.
+const GITIGNORE_MARKER = "# Marcos AI-Bootstrap (materialised files)";
+
+/**
+ * Append any ignore patterns not already present in the destination
+ * .gitignore, under a marker heading (added once). Idempotent: re-running
+ * with the same or a subset of patterns writes nothing further.
+ */
+function writeGitignoreEntries(patterns, destRoot, { dryRun }) {
+  const dest = path.join(destRoot, ".gitignore");
+  const exists = fs.existsSync(dest);
+  const current = exists ? fs.readFileSync(dest, "utf8") : "";
+  const currentLines = new Set(current.split(/\r?\n/).map((l) => l.trim()));
+
+  const missing = patterns.filter((p) => !currentLines.has(p));
+  if (missing.length === 0) {
+    return { relPath: ".gitignore", status: exists ? "already-wired" : "created" };
+  }
+
+  const hasMarker = current.includes(GITIGNORE_MARKER);
+  const block = (hasMarker ? "" : GITIGNORE_MARKER + "\n") + missing.join("\n") + "\n";
+
+  if (!dryRun) {
+    const sep = current.length === 0 ? "" : current.endsWith("\n") ? "\n" : "\n\n";
+    fs.mkdirSync(path.dirname(dest), { recursive: true });
+    fs.appendFileSync(dest, sep + block);
+  }
+  return { relPath: ".gitignore", status: exists ? "appended" : "created" };
+}
+
 /**
  * Materialise the requested tools' agent/skill files, plus the tool-agnostic
  * core files (AGENTS.md, HUMAN.md), into destRoot.
  *
  * @param {string[]} tools - subset of Object.keys(TOOLS)
- * @param {object} opts - { destRoot, force, dryRun }
+ * @param {object} opts - { destRoot, force, dryRun, gitignore }
+ *   gitignore: when true, materialised files are added to the destination's
+ *   .gitignore instead of being tracked, and no instruction entry-point
+ *   (AGENTS.md, CLAUDE.md, .github/copilot-instructions.md) is created or
+ *   amended.
  * @returns {{results: Array, tools: string[]}}
  */
 function materialize(tools, opts = {}) {
   const destRoot = path.resolve(opts.destRoot || process.cwd());
   const force = !!opts.force;
   const dryRun = !!opts.dryRun;
+  const gitignore = !!opts.gitignore;
 
   const results = [];
+  const ignorePatterns = [];
 
   for (const cf of CORE_FILES) {
     results.push(copyOne(cf.src, cf.dest, destRoot, { force, dryRun }));
+    ignorePatterns.push(cf.dest);
   }
 
-  // AGENTS.md is wired on every invocation as the universal entry-point.
-  results.push(appendEntry(CORE_ENTRY, destRoot, { dryRun }));
+  // AGENTS.md is wired on every invocation as the universal entry-point,
+  // unless --gitignore asked us not to touch the user's instruction files.
+  if (!gitignore) {
+    results.push(appendEntry(CORE_ENTRY, destRoot, { dryRun }));
+  }
 
   for (const toolName of tools) {
     const tool = TOOLS[toolName];
@@ -185,13 +227,25 @@ function materialize(tools, opts = {}) {
         const destRel = path.posix.join(toPosix(dir), rel);
         results.push(copyOne(srcRel, destRel, destRoot, { force, dryRun }));
       }
+      ignorePatterns.push(toPosix(dir) + "/");
     }
-    if (tool.entry) {
+    if (tool.entry && !gitignore) {
       results.push(appendEntry(tool.entry, destRoot, { dryRun }));
     }
   }
 
+  if (gitignore) {
+    results.push(writeGitignoreEntries(ignorePatterns, destRoot, { dryRun }));
+  }
+
   return { results, tools, destRoot };
 }
 
-module.exports = { materialize, TOOLS, CORE_FILES, CORE_ENTRY, PACKAGE_ROOT };
+module.exports = {
+  materialize,
+  TOOLS,
+  CORE_FILES,
+  CORE_ENTRY,
+  PACKAGE_ROOT,
+  GITIGNORE_MARKER,
+};