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.
- package/.agents/skills/implement/SKILL.md +48 -48
- package/.agents/skills/initialize/SKILL.md +50 -50
- package/.agents/skills/planner/SKILL.md +30 -30
- package/.agents/skills/watch-ci/SKILL.md +49 -49
- package/.claude/agents/code-claude.md +18 -18
- package/.claude/agents/docs-claude.md +14 -14
- package/.claude/agents/explorer-claude.md +14 -14
- package/.claude/agents/infra-claude.md +17 -17
- package/.claude/agents/investigate-claude.md +25 -25
- package/.claude/agents/log-reader-claude.md +21 -21
- package/.claude/agents/planner-claude.md +37 -37
- package/.claude/agents/planner-discovery-claude.md +24 -24
- package/.claude/agents/test-runner-claude.md +16 -16
- package/.claude/agents/triage-claude.md +46 -46
- package/.claude/skills/implement/SKILL.md +48 -48
- package/.claude/skills/initialize/SKILL.md +50 -50
- package/.claude/skills/planner/SKILL.md +30 -30
- package/.claude/skills/watch-ci/SKILL.md +49 -49
- package/.codex/agents/code-codex.toml +19 -19
- package/.codex/agents/docs-codex.toml +16 -16
- package/.codex/agents/explorer-codex.toml +15 -15
- package/.codex/agents/infra-codex.toml +18 -18
- package/.codex/agents/investigate-codex.toml +25 -25
- package/.codex/agents/log-reader-codex.toml +22 -22
- package/.codex/agents/planner-codex.toml +37 -37
- package/.codex/agents/planner-discovery-codex.toml +24 -24
- package/.codex/agents/test-runner-codex.toml +17 -17
- package/.codex/agents/triage-codex.toml +46 -46
- package/.github/agents/code-copilot.agent.md +18 -18
- package/.github/agents/docs-copilot.agent.md +14 -14
- package/.github/agents/explorer-copilot.agent.md +14 -14
- package/.github/agents/infra-copilot.agent.md +17 -17
- package/.github/agents/investigate-copilot.agent.md +25 -25
- package/.github/agents/log-reader-copilot.agent.md +21 -21
- package/.github/agents/planner-copilot.agent.md +37 -37
- package/.github/agents/planner-discovery-copilot.agent.md +24 -24
- package/.github/agents/test-runner-copilot.agent.md +16 -16
- package/.github/agents/triage-copilot.agent.md +46 -46
- package/.github/skills/implement/SKILL.md +44 -44
- package/.github/skills/initialize/SKILL.md +52 -52
- package/.github/skills/planner/SKILL.md +30 -30
- package/.github/skills/watch-ci/SKILL.md +47 -47
- package/LICENSE +21 -21
- package/README.md +116 -117
- package/package.json +37 -37
- package/src/AGENTS.md +200 -200
- package/src/HUMAN.md +31 -31
- package/src/bin/ai-bootstrap.js +115 -115
- 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
|
-
|
|
102
|
-
|
|
103
|
-
|
|
104
|
-
|
|
105
|
-
|
|
106
|
-
|
|
107
|
-
|
|
108
|
-
|
|
|
109
|
-
|
|
110
|
-
|
|
111
|
-
|
|
112
|
-
|
|
113
|
-
|
|
114
|
-
|
|
115
|
-
|
|
116
|
-
|
|
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.
|
|
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
|
+
}
|