marcos-ai-bootstrap 0.1.0 → 0.1.2

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (49) hide show
  1. package/.agents/skills/implement/SKILL.md +48 -48
  2. package/.agents/skills/initialize/SKILL.md +50 -50
  3. package/.agents/skills/planner/SKILL.md +30 -30
  4. package/.agents/skills/watch-ci/SKILL.md +49 -49
  5. package/.claude/agents/code-claude.md +18 -18
  6. package/.claude/agents/docs-claude.md +14 -14
  7. package/.claude/agents/explorer-claude.md +14 -14
  8. package/.claude/agents/infra-claude.md +17 -17
  9. package/.claude/agents/investigate-claude.md +25 -25
  10. package/.claude/agents/log-reader-claude.md +21 -21
  11. package/.claude/agents/planner-claude.md +37 -37
  12. package/.claude/agents/planner-discovery-claude.md +24 -24
  13. package/.claude/agents/test-runner-claude.md +16 -16
  14. package/.claude/agents/triage-claude.md +46 -46
  15. package/.claude/skills/implement/SKILL.md +48 -48
  16. package/.claude/skills/initialize/SKILL.md +50 -50
  17. package/.claude/skills/planner/SKILL.md +30 -30
  18. package/.claude/skills/watch-ci/SKILL.md +49 -49
  19. package/.codex/agents/code-codex.toml +19 -19
  20. package/.codex/agents/docs-codex.toml +16 -16
  21. package/.codex/agents/explorer-codex.toml +15 -15
  22. package/.codex/agents/infra-codex.toml +18 -18
  23. package/.codex/agents/investigate-codex.toml +25 -25
  24. package/.codex/agents/log-reader-codex.toml +22 -22
  25. package/.codex/agents/planner-codex.toml +37 -37
  26. package/.codex/agents/planner-discovery-codex.toml +24 -24
  27. package/.codex/agents/test-runner-codex.toml +17 -17
  28. package/.codex/agents/triage-codex.toml +46 -46
  29. package/.github/agents/code-copilot.agent.md +18 -18
  30. package/.github/agents/docs-copilot.agent.md +14 -14
  31. package/.github/agents/explorer-copilot.agent.md +14 -14
  32. package/.github/agents/infra-copilot.agent.md +17 -17
  33. package/.github/agents/investigate-copilot.agent.md +25 -25
  34. package/.github/agents/log-reader-copilot.agent.md +21 -21
  35. package/.github/agents/planner-copilot.agent.md +37 -37
  36. package/.github/agents/planner-discovery-copilot.agent.md +24 -24
  37. package/.github/agents/test-runner-copilot.agent.md +16 -16
  38. package/.github/agents/triage-copilot.agent.md +46 -46
  39. package/.github/skills/implement/SKILL.md +44 -44
  40. package/.github/skills/initialize/SKILL.md +52 -52
  41. package/.github/skills/planner/SKILL.md +30 -30
  42. package/.github/skills/watch-ci/SKILL.md +47 -47
  43. package/LICENSE +21 -21
  44. package/README.md +116 -117
  45. package/package.json +37 -37
  46. package/src/AGENTS.md +200 -200
  47. package/src/HUMAN.md +31 -31
  48. package/src/bin/ai-bootstrap.js +115 -115
  49. package/src/lib/materialize.js +140 -140
@@ -1,30 +1,30 @@
1
- ---
2
- name: planner
3
- description: Formalise the two-stage planning flow. Stage 1 runs planner-discovery-copilot (clarifying questions + concise outline); Stage 2 runs planner-copilot to write the full plan to documents/plans/ after explicit user approval. Never writes code.
4
- ---
5
-
6
- You are the planner orchestrator. Drive the two-stage planning flow.
7
-
8
- ## Stage 1 — Discovery & Outline
9
-
10
- Invoke the `planner-discovery-copilot` agent with the user's task description and any relevant context. That agent will:
11
- - Ask exhaustive clarifying questions about scope, behaviour, constraints, and success criteria.
12
- - Explore the codebase.
13
- - Return a concise outline: Goal, high-level phases, open questions, and a proposed plan filename (`<YYYYMMDD>-<topic>.md`).
14
-
15
- Present the outline to the user. **Stop and explicitly ask for approval before proceeding to Stage 2.**
16
-
17
- ## Stage 2 — Full Implementation Plan
18
-
19
- 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:
20
- - Write a complete, structured plan to `documents/plans/<YYYYMMDD>-<topic>.md`.
21
- - Plan structure: Goal, Constraints, Phases (objective / agent / files / acceptance criteria), Open questions, Risks.
22
- - Include code snippets for load-bearing changes.
23
-
24
- Present the written plan to the user. **Stop and ask for explicit approval before any implementation begins.**
25
-
26
- ## Guardrails
27
- - Never write code or modify source files.
28
- - Never commit or push.
29
- - Only the `planner-copilot` agent writes to `documents/plans/`.
30
- - Hand off to the `implement` skill when the user is ready to execute the plan.
1
+ ---
2
+ name: planner
3
+ description: Formalise the two-stage planning flow. Stage 1 runs planner-discovery-copilot (clarifying questions + concise outline); Stage 2 runs planner-copilot to write the full plan to documents/plans/ after explicit user approval. Never writes code.
4
+ ---
5
+
6
+ You are the planner orchestrator. Drive the two-stage planning flow.
7
+
8
+ ## Stage 1 — Discovery & Outline
9
+
10
+ Invoke the `planner-discovery-copilot` agent with the user's task description and any relevant context. That agent will:
11
+ - Ask exhaustive clarifying questions about scope, behaviour, constraints, and success criteria.
12
+ - Explore the codebase.
13
+ - Return a concise outline: Goal, high-level phases, open questions, and a proposed plan filename (`<YYYYMMDD>-<topic>.md`).
14
+
15
+ Present the outline to the user. **Stop and explicitly ask for approval before proceeding to Stage 2.**
16
+
17
+ ## Stage 2 — Full Implementation Plan
18
+
19
+ 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:
20
+ - Write a complete, structured plan to `documents/plans/<YYYYMMDD>-<topic>.md`.
21
+ - Plan structure: Goal, Constraints, Phases (objective / agent / files / acceptance criteria), Open questions, Risks.
22
+ - Include code snippets for load-bearing changes.
23
+
24
+ Present the written plan to the user. **Stop and ask for explicit approval before any implementation begins.**
25
+
26
+ ## Guardrails
27
+ - Never write code or modify source files.
28
+ - Never commit or push.
29
+ - Only the `planner-copilot` agent writes to `documents/plans/`.
30
+ - Hand off to the `implement` skill when the user is ready to execute the plan.
@@ -1,47 +1,47 @@
1
- ---
2
- name: watch-ci
3
- 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.
4
- ---
5
-
6
- You are the watch-ci orchestrator. Drive the CI fix loop until the target workflow is green.
7
-
8
- ## Target resolution
9
-
10
- Parse the optional input argument:
11
- - **Empty** → look up the current-branch PR with `gh pr view`.
12
- - **Digits only** → treat as a PR number on the current repo.
13
- - **URL containing `/pull/<n>`** → PR URL; extract `owner/repo` from the URL and pass `--repo owner/repo` to all `gh` calls.
14
- - **URL containing `/actions/runs/<id>`** → direct run URL; extract the run ID and `owner/repo`.
15
- - **URL containing `/actions/workflows/<file>`** or **`/blob/<ref>/.github/workflows/<file>`** → workflow-file URL; extract `owner/repo` and the workflow file name.
16
-
17
- ## Trigger-type detection
18
-
19
- After identifying the failing workflow file, fetch its `on:` block and classify:
20
-
21
- | `on:` block | Trigger type | Re-trigger method |
22
- |---|---|---|
23
- | Contains `push` or `pull_request` | auto-on-push | Commit and push on the feature branch |
24
- | Contains `workflow_dispatch` (without push/PR) | manual-dispatch | `gh workflow run <file> --repo owner/repo` |
25
- | Only `schedule` | scheduled-only | **Stop** — cannot force; report the fix to the user |
26
- | Anything else | manual-dispatch | `gh workflow run <file> --repo owner/repo` |
27
-
28
- ## Fix loop (max 5 iterations)
29
-
30
- Repeat until green or 5 iterations reached:
31
-
32
- 1. **Collect** — invoke the `log-reader-copilot` agent to gather logs and produce a structured diagnostic report.
33
- 2. **Triage** — invoke the `triage-copilot` agent with the diagnostic report; receive EASY or HARD classification.
34
- 3. **Investigate** (HARD only) — invoke the `investigate-copilot` agent with the diagnostic report and triage output; receive a root-cause analysis and fix strategy.
35
- 4. **Fix** — invoke the `code-copilot` agent with the triage fix suggestion (EASY) or investigate fix strategy (HARD) to apply the change.
36
- 5. **Commit & push** — commit the fix on the current feature branch and push; never push to `main`.
37
- 6. **Re-trigger** — use the trigger method determined above.
38
- 7. **Wait** — poll `gh run watch` until the new run completes.
39
- 8. If still failing, go to step 1.
40
-
41
- After 5 iterations without green, stop and report the current state and last error to the user.
42
-
43
- ## Guardrails
44
- - Never push to `main`.
45
- - Never force-push.
46
- - Never use `--no-verify`.
47
- - For remote-repo targets this agent cannot edit locally: diagnose, propose the fix, and report back to the user without pushing.
1
+ ---
2
+ name: watch-ci
3
+ 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.
4
+ ---
5
+
6
+ You are the watch-ci orchestrator. Drive the CI fix loop until the target workflow is green.
7
+
8
+ ## Target resolution
9
+
10
+ Parse the optional input argument:
11
+ - **Empty** → look up the current-branch PR with `gh pr view`.
12
+ - **Digits only** → treat as a PR number on the current repo.
13
+ - **URL containing `/pull/<n>`** → PR URL; extract `owner/repo` from the URL and pass `--repo owner/repo` to all `gh` calls.
14
+ - **URL containing `/actions/runs/<id>`** → direct run URL; extract the run ID and `owner/repo`.
15
+ - **URL containing `/actions/workflows/<file>`** or **`/blob/<ref>/.github/workflows/<file>`** → workflow-file URL; extract `owner/repo` and the workflow file name.
16
+
17
+ ## Trigger-type detection
18
+
19
+ After identifying the failing workflow file, fetch its `on:` block and classify:
20
+
21
+ | `on:` block | Trigger type | Re-trigger method |
22
+ |---|---|---|
23
+ | Contains `push` or `pull_request` | auto-on-push | Commit and push on the feature branch |
24
+ | Contains `workflow_dispatch` (without push/PR) | manual-dispatch | `gh workflow run <file> --repo owner/repo` |
25
+ | Only `schedule` | scheduled-only | **Stop** — cannot force; report the fix to the user |
26
+ | Anything else | manual-dispatch | `gh workflow run <file> --repo owner/repo` |
27
+
28
+ ## Fix loop (max 5 iterations)
29
+
30
+ Repeat until green or 5 iterations reached:
31
+
32
+ 1. **Collect** — invoke the `log-reader-copilot` agent to gather logs and produce a structured diagnostic report.
33
+ 2. **Triage** — invoke the `triage-copilot` agent with the diagnostic report; receive EASY or HARD classification.
34
+ 3. **Investigate** (HARD only) — invoke the `investigate-copilot` agent with the diagnostic report and triage output; receive a root-cause analysis and fix strategy.
35
+ 4. **Fix** — invoke the `code-copilot` agent with the triage fix suggestion (EASY) or investigate fix strategy (HARD) to apply the change.
36
+ 5. **Commit & push** — commit the fix on the current feature branch and push; never push to `main`.
37
+ 6. **Re-trigger** — use the trigger method determined above.
38
+ 7. **Wait** — poll `gh run watch` until the new run completes.
39
+ 8. If still failing, go to step 1.
40
+
41
+ After 5 iterations without green, stop and report the current state and last error to the user.
42
+
43
+ ## Guardrails
44
+ - Never push to `main`.
45
+ - Never force-push.
46
+ - Never use `--no-verify`.
47
+ - For remote-repo targets this agent cannot edit locally: diagnose, propose the fix, and report back to the user without pushing.
package/LICENSE CHANGED
@@ -1,21 +1,21 @@
1
- MIT License
2
-
3
- Copyright (c) 2026 Marco Petralia
4
-
5
- Permission is hereby granted, free of charge, to any person obtaining a copy
6
- of this software and associated documentation files (the "Software"), to deal
7
- in the Software without restriction, including without limitation the rights
8
- to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
9
- copies of the Software, and to permit persons to whom the Software is
10
- furnished to do so, subject to the following conditions:
11
-
12
- The above copyright notice and this permission notice shall be included in all
13
- copies or substantial portions of the Software.
14
-
15
- THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
16
- IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
17
- FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
18
- AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
19
- LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
20
- OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
21
- SOFTWARE.
1
+ MIT License
2
+
3
+ Copyright (c) 2026 Marco Petralia
4
+
5
+ Permission is hereby granted, free of charge, to any person obtaining a copy
6
+ of this software and associated documentation files (the "Software"), to deal
7
+ in the Software without restriction, including without limitation the rights
8
+ to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
9
+ copies of the Software, and to permit persons to whom the Software is
10
+ furnished to do so, subject to the following conditions:
11
+
12
+ The above copyright notice and this permission notice shall be included in all
13
+ copies or substantial portions of the Software.
14
+
15
+ THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
16
+ IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
17
+ FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
18
+ AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
19
+ LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
20
+ OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
21
+ SOFTWARE.
package/README.md CHANGED
@@ -1,117 +1,116 @@
1
- # marcos-ai-bootstrap
2
-
3
- AI tools for doing work. No overcomplications.
4
-
5
- Tool-agnostic agent/skill network that is built around a basic flow of plan -> implement -> deploy -> fix -> deploy etc.
6
-
7
- Currently supporting **Claude Code**, **Codex**, and **GitHub Copilot CLI** but easily adjustable to fit your workflow.
8
-
9
- See [`HUMAN.md`](./HUMAN.md) for the day-to-day workflow once the network is set up.
10
-
11
- ## Quick start: the `marcos-ai-bootstrap` CLI
12
-
13
- The fastest way to bring this agent network into any repository — no AI turn required,
14
- works the same on Windows/Mac/Linux, and doesn't care whether the target project is
15
- Node, Python, Go, or anything else:
16
-
17
- ```bash
18
- npx marcos-ai-bootstrap --copilot # GitHub Copilot CLI agents + skills
19
- npx marcos-ai-bootstrap --claude # Claude Code agents + skills
20
- npx marcos-ai-bootstrap --codex # Codex agents + skills
21
- npx marcos-ai-bootstrap --claude --codex # combine any subset
22
- npx marcos-ai-bootstrap --all # every tool at once
23
- ```
24
-
25
- Run it from the root of the repository you want to bootstrap. It writes `AGENTS.md`
26
- and `HUMAN.md` (the tool-agnostic rules + human guide) alongside
27
- the agent/skill files for whichever tool(s) you selected:
28
-
29
- | Flag | Writes |
30
- |---|---|
31
- | `--claude` | `.claude/agents/*.md`, `.claude/skills/**/SKILL.md`, `CLAUDE.md` (`@AGENTS.md` stub) |
32
- | `--codex` | `.codex/agents/*.toml`, `.agents/skills/**/SKILL.md` |
33
- | `--copilot` | `.github/agents/*.agent.md`, `.github/skills/**/SKILL.md`, `.github/copilot-instructions.md` |
34
- | `--all` | all of the above |
35
-
36
- ### Options
37
-
38
- | Flag | Effect |
39
- |---|---|
40
- | `--dest <path>` | Target directory (default: current working directory) |
41
- | `--force` | Overwrite files that already exist (default: skip existing files) |
42
- | `--dry-run` | Print what would be written without touching disk |
43
- | `-h`, `--help` | Show usage |
44
-
45
- Existing files are never clobbered unless you pass `--force`, so it's safe to re-run
46
- `marcos-ai-bootstrap` in a repo that already has some of the network materialised (e.g. to add
47
- `--codex` support to a repo that only had `--copilot` before).
48
-
49
- ### Installing globally instead of via `npx`
50
-
51
- ```bash
52
- npm install -g marcos-ai-bootstrap
53
- marcos-ai-bootstrap --all
54
- ```
55
-
56
- ## Repository layout
57
-
58
- - `src/AGENTS.md`, `src/HUMAN.md` — the **canonical, shipped** copies. These are the source
59
- of truth the CLI reads and writes into target repos (as root-level `AGENTS.md`/`HUMAN.md`).
60
- - `AGENTS.md`, `HUMAN.md` (repo root) — this repository's **own self-hosting** copies, used
61
- by the agent network running against this repo. Kept separate from the shipped `src/` copies
62
- and not published to npm.
63
- - `.claude/`, `.codex/`, `.github/`, `.agents/` — the already-materialised, checked-in
64
- agent/skill files for this repo itself, and the templates the `marcos-ai-bootstrap` CLI ships
65
- and copies into other repositories.
66
- - `src/bin/ai-bootstrap.js`, `src/lib/materialize.js` — the CLI implementation.
67
- - `src/AGENTS-BOOTSTRAP.md` — maintainer-only source of truth for each tool's
68
- materialised agent/skill prompt bodies, model tier mappings, and MCP server
69
- discovery/policy flow. **Not published to npm and not copied into target repos** —
70
- the materialised agent/skill files under `.claude/`, `.codex/`, `.github/`, `.agents/`
71
- are the shipped source of truth.
72
- - `src/extract-agents.py` — maintainer tool: regenerates the `.claude/`, `.codex/`,
73
- `.github/`, `.agents/` template files at the repo root from `src/AGENTS-BOOTSTRAP.md`
74
- after editing it. Run this after changing `src/AGENTS-BOOTSTRAP.md`, then commit the
75
- regenerated templates so `marcos-ai-bootstrap` ships the update.
76
-
77
- ## Maintaining this repo
78
-
79
- 1. Edit `src/AGENTS-BOOTSTRAP.md` (the source of truth for agent/skill prompt bodies).
80
- 2. Run `python src/extract-agents.py` to regenerate the materialised template files.
81
- 3. Run `node src/bin/ai-bootstrap.js --all --dry-run --dest <scratch-dir>` to sanity-check
82
- the CLI still packages everything correctly.
83
- 4. Commit the changes.
84
-
85
- ## Releasing to npm
86
-
87
- Releases are automated with [release-please](https://github.com/googleapis/release-please)
88
- via `.github/workflows/release.yml`, so no one commits a version bump or pushes to `main`
89
- directly.
90
-
91
- How it works:
92
-
93
- 1. On every push to `main`, release-please opens/updates a **Release PR** that bumps the
94
- version in `package.json` and updates `CHANGELOG.md`, based on the conventional-commit
95
- messages since the last release.
96
- 2. When you're ready to ship, **merge the Release PR**. That merge creates the git tag and
97
- a GitHub Release.
98
- 3. The same workflow then publishes to npm with `npm publish --provenance --access public`
99
- using OIDC **trusted publishing** (no stored `NPM_TOKEN`).
100
-
101
- Bump size is derived from your commit messages:
102
-
103
- | Commit type | Result |
104
- |---|---|
105
- | `fix:` / `chore:` / `refactor:` … | patch (`0.0.1`) |
106
- | `feat:` … | minor |
107
- | `feat!:` or a `BREAKING CHANGE:` footer | major |
108
- | any commit with a `Release-As: X.Y.Z` footer | forces exactly that version |
109
-
110
- So the default cadence is a patch per batch of merged fixes; larger releases happen simply
111
- by using `feat:` or a breaking-change marker. Non-releasable commits (e.g. `docs:`, `ci:`)
112
- won't create a Release PR on their own.
113
-
114
- **One-time setup on npmjs.com:** configure this repository and the `Release` workflow as a
115
- [trusted publisher](https://docs.npmjs.com/trusted-publishers) for the `marcos-ai-bootstrap`
116
- package so OIDC auth works without a token. Also enable "Allow GitHub Actions to create and
117
- approve pull requests" in the repo's Actions settings so release-please can open the Release PR.
1
+ # marcos-ai-bootstrap
2
+
3
+ AI tools for doing work. No overcomplications.
4
+
5
+ Tool-agnostic agent/skill network that is built around a basic flow of plan -> implement -> deploy -> fix -> deploy etc.
6
+
7
+ Currently supporting **Claude Code**, **Codex**, and **GitHub Copilot CLI** but easily adjustable to fit your workflow.
8
+
9
+ See [`HUMAN.md`](./HUMAN.md) for the day-to-day workflow once the network is set up.
10
+
11
+ ## Quick start: the `marcos-ai-bootstrap` CLI
12
+
13
+ The fastest way to bring this agent network into any repository — no AI turn required,
14
+ works the same on Windows/Mac/Linux, and doesn't care whether the target project is
15
+ Node, Python, Go, or anything else:
16
+
17
+ ```bash
18
+ npx marcos-ai-bootstrap --copilot # GitHub Copilot CLI agents + skills
19
+ npx marcos-ai-bootstrap --claude # Claude Code agents + skills
20
+ npx marcos-ai-bootstrap --codex # Codex agents + skills
21
+ npx marcos-ai-bootstrap --claude --codex # combine any subset
22
+ npx marcos-ai-bootstrap --all # every tool at once
23
+ ```
24
+
25
+ Run it from the root of the repository you want to bootstrap. It writes `AGENTS.md`
26
+ and `HUMAN.md` (the tool-agnostic rules + human guide) alongside
27
+ the agent/skill files for whichever tool(s) you selected:
28
+
29
+ | Flag | Writes |
30
+ |---|---|
31
+ | `--claude` | `.claude/agents/*.md`, `.claude/skills/**/SKILL.md`, `CLAUDE.md` (`@AGENTS.md` stub) |
32
+ | `--codex` | `.codex/agents/*.toml`, `.agents/skills/**/SKILL.md` |
33
+ | `--copilot` | `.github/agents/*.agent.md`, `.github/skills/**/SKILL.md`, `.github/copilot-instructions.md` |
34
+ | `--all` | all of the above |
35
+
36
+ ### Options
37
+
38
+ | Flag | Effect |
39
+ |---|---|
40
+ | `--dest <path>` | Target directory (default: current working directory) |
41
+ | `--force` | Overwrite files that already exist (default: skip existing files) |
42
+ | `--dry-run` | Print what would be written without touching disk |
43
+ | `-h`, `--help` | Show usage |
44
+
45
+ Existing files are never clobbered unless you pass `--force`, so it's safe to re-run
46
+ `marcos-ai-bootstrap` in a repo that already has some of the network materialised (e.g. to add
47
+ `--codex` support to a repo that only had `--copilot` before).
48
+
49
+ ### Installing globally instead of via `npx`
50
+
51
+ ```bash
52
+ npm install -g marcos-ai-bootstrap
53
+ marcos-ai-bootstrap --all
54
+ ```
55
+
56
+ ## Repository layout
57
+
58
+ - `src/AGENTS.md`, `src/HUMAN.md` — the **canonical, shipped** copies. These are the source
59
+ of truth the CLI reads and writes into target repos (as root-level `AGENTS.md`/`HUMAN.md`).
60
+ - `AGENTS.md`, `HUMAN.md` (repo root) — this repository's **own self-hosting** copies, used
61
+ by the agent network running against this repo. Kept separate from the shipped `src/` copies
62
+ and not published to npm.
63
+ - `.claude/`, `.codex/`, `.github/`, `.agents/` — the already-materialised, checked-in
64
+ agent/skill files for this repo itself, and the templates the `marcos-ai-bootstrap` CLI ships
65
+ and copies into other repositories.
66
+ - `src/bin/ai-bootstrap.js`, `src/lib/materialize.js` — the CLI implementation.
67
+ - `src/AGENTS-BOOTSTRAP.md` — maintainer-only source of truth for each tool's
68
+ materialised agent/skill prompt bodies, model tier mappings, and MCP server
69
+ discovery/policy flow. **Not published to npm and not copied into target repos** —
70
+ the materialised agent/skill files under `.claude/`, `.codex/`, `.github/`, `.agents/`
71
+ are the shipped source of truth.
72
+ - `src/extract-agents.py` — maintainer tool: regenerates the `.claude/`, `.codex/`,
73
+ `.github/`, `.agents/` template files at the repo root from `src/AGENTS-BOOTSTRAP.md`
74
+ after editing it. Run this after changing `src/AGENTS-BOOTSTRAP.md`, then commit the
75
+ regenerated templates so `marcos-ai-bootstrap` ships the update.
76
+
77
+ ## Maintaining this repo
78
+
79
+ 1. Edit `src/AGENTS-BOOTSTRAP.md` (the source of truth for agent/skill prompt bodies).
80
+ 2. Run `python src/extract-agents.py` to regenerate the materialised template files.
81
+ 3. Run `node src/bin/ai-bootstrap.js --all --dry-run --dest <scratch-dir>` to sanity-check
82
+ the CLI still packages everything correctly.
83
+ 4. Commit the changes.
84
+
85
+ ## Releasing to npm
86
+
87
+ Releases are automated with [release-please](https://github.com/googleapis/release-please)
88
+ via `.github/workflows/release.yml`, so no one commits a version bump or pushes to `main`
89
+ directly.
90
+
91
+ How it works:
92
+
93
+ 1. On every push to `main`, release-please opens/updates a **Release PR** that bumps the
94
+ version in `package.json` and updates `CHANGELOG.md`, based on the conventional-commit
95
+ messages since the last release.
96
+ 2. When you're ready to ship, **merge the Release PR**. That merge creates the git tag and
97
+ a GitHub Release.
98
+ 3. The same workflow then publishes to npm with `npm publish --provenance --access public`
99
+ using OIDC **trusted publishing** (no stored `NPM_TOKEN`).
100
+
101
+ The published package appears at
102
+ [npmjs.com/package/marcos-ai-bootstrap](https://www.npmjs.com/package/marcos-ai-bootstrap).
103
+
104
+ Bump size is derived from your commit messages. While the package is pre-1.0, the config
105
+ (`bump-minor-pre-major`, `bump-patch-for-minor-pre-major`) keeps breaking changes off the
106
+ major version:
107
+
108
+ | Commit type | Result (pre-1.0) |
109
+ |---|---|
110
+ | `fix:` / `feat:` / `refactor:` … | patch (e.g. `0.1.0` → `0.1.1`) |
111
+ | `feat!:` or a `BREAKING CHANGE:` footer | minor (e.g. `0.1.0` → `0.2.0`) |
112
+ | any commit with a `Release-As: X.Y.Z` footer | forces exactly that version |
113
+
114
+ Cut `1.0.0` with a `Release-As: 1.0.0` commit when the API is stable; after that, standard
115
+ SemVer applies (`feat:` → minor, breaking → major). Non-releasable commits (e.g. `docs:`,
116
+ `ci:`) won't create a Release PR on their own.
package/package.json CHANGED
@@ -1,37 +1,37 @@
1
- {
2
- "name": "marcos-ai-bootstrap",
3
- "version": "0.1.0",
4
- "description": "Materialise the AI-Bootstrap agent/skill network (Claude Code, Codex, GitHub Copilot CLI) into any repository from the command line.",
5
- "bin": {
6
- "marcos-ai-bootstrap": "src/bin/ai-bootstrap.js"
7
- },
8
- "main": "src/lib/materialize.js",
9
- "files": [
10
- "src/bin",
11
- "src/lib",
12
- "src/AGENTS.md",
13
- "src/HUMAN.md",
14
- ".claude",
15
- ".codex",
16
- ".agents",
17
- ".github/agents",
18
- ".github/skills"
19
- ],
20
- "engines": {
21
- "node": ">=16"
22
- },
23
- "license": "MIT",
24
- "repository": {
25
- "type": "git",
26
- "url": "https://github.com/marcorpetralia/marcos-ai-bootstrap"
27
- },
28
- "keywords": [
29
- "ai",
30
- "agents",
31
- "copilot",
32
- "claude",
33
- "codex",
34
- "bootstrap",
35
- "cli"
36
- ]
37
- }
1
+ {
2
+ "name": "marcos-ai-bootstrap",
3
+ "version": "0.1.2",
4
+ "description": "Materialise the AI-Bootstrap agent/skill network (Claude Code, Codex, GitHub Copilot CLI) into any repository from the command line.",
5
+ "bin": {
6
+ "marcos-ai-bootstrap": "src/bin/ai-bootstrap.js"
7
+ },
8
+ "main": "src/lib/materialize.js",
9
+ "files": [
10
+ "src/bin",
11
+ "src/lib",
12
+ "src/AGENTS.md",
13
+ "src/HUMAN.md",
14
+ ".claude",
15
+ ".codex",
16
+ ".agents",
17
+ ".github/agents",
18
+ ".github/skills"
19
+ ],
20
+ "engines": {
21
+ "node": ">=16"
22
+ },
23
+ "license": "MIT",
24
+ "repository": {
25
+ "type": "git",
26
+ "url": "https://github.com/marcorpetralia/marcos-ai-bootstrap"
27
+ },
28
+ "keywords": [
29
+ "ai",
30
+ "agents",
31
+ "copilot",
32
+ "claude",
33
+ "codex",
34
+ "bootstrap",
35
+ "cli"
36
+ ]
37
+ }