marcos-ai-bootstrap 0.1.6 → 0.1.7

package/README.md

@@ -1,15 +1,21 @@
 # marcos-ai-bootstrap
 
-AI tools for doing work. No overcomplications.
+[![npm version](https://img.shields.io/npm/v/marcos-ai-bootstrap)](https://www.npmjs.com/package/marcos-ai-bootstrap)
+[![license](https://img.shields.io/npm/l/marcos-ai-bootstrap)](./LICENSE)
+[![CI](https://github.com/marcorpetralia/marcos-ai-bootstrap/actions/workflows/ci.yml/badge.svg)](https://github.com/marcorpetralia/marcos-ai-bootstrap/actions/workflows/ci.yml)
 
-Tool-agnostic agent/skill network that is built around a basic flow of plan -> implement -> deploy -> fix -> deploy etc.
+Simple agent workflows designed for getting work done, as quickly and cheaply as possible whilst ensuring guardrails are followed.
 
-Currently supporting **Claude Code**, **Codex**, and **GitHub Copilot CLI** but easily adjustable to fit your workflow.
+A tool-agnostic agent/skill network that gives Claude Code, Codex, and GitHub Copilot CLI a shared plan → implement → deploy → fix workflow — drop it into any repository with one command.
+
+**Note:** marcos-ai-bootstrap is pre-1.0 and evolving. SemVer stabilizes at `1.0.0`. See ["Releasing to npm"](#releasing-to-npm) for the current version and release process.
 
 See [`HUMAN.md`](./HUMAN.md) for the day-to-day workflow once the network is set up.
 
 ## Quick start: the `marcos-ai-bootstrap` CLI
 
+**Requires Node.js >= 18**
+
 The fastest way to bring this agent network into any repository — no AI turn required,
 works the same on Windows/Mac/Linux, and doesn't care whether the target project is
 Node, Python, Go, or anything else:
@@ -59,6 +65,10 @@ npm install -g marcos-ai-bootstrap
 marcos-ai-bootstrap --all
 ```
 
+## Demo
+
+<!-- TODO: GIF/asciinema demo recording coming soon — drop it here -->
+
 ## Repository layout
 
 **Everything the CLI materialises into a target repo is shipped from `src/`; `src/` is the single source of truth.**

package/package.json

@@ -1,11 +1,14 @@
 {
   "name": "marcos-ai-bootstrap",
-  "version": "0.1.6",
+  "version": "0.1.7",
   "description": "Materialise the AI-Bootstrap agent/skill network (Claude Code, Codex, GitHub Copilot CLI) into any repository from the command line.",
   "bin": {
     "marcos-ai-bootstrap": "src/bin/ai-bootstrap.js"
   },
   "main": "src/lib/materialize.js",
+  "scripts": {
+    "test": "node --test"
+  },
   "files": [
     "src/bin",
     "src/lib",
@@ -19,7 +22,7 @@
     "src/.github/skills"
   ],
   "engines": {
-    "node": ">=16"
+    "node": ">=18"
   },
   "license": "MIT",
   "repository": {

package/src/.agents/skills/watch-ci/SKILL.md

@@ -34,7 +34,8 @@ Repeat until green or 5 iterations reached:
 3. **Investigate (HARD only)**: invoke `investigate-codex` with the diagnostic report and triage output; receive a root-cause analysis and fix strategy.
 4. **Fix**: invoke `code-codex` with the triage fix suggestion (EASY) or investigate fix strategy (HARD) to apply the change.
 5. **Validate**: run the narrowest relevant tests, lint, or build command before attempting a new CI run.
-6. **Commit & push**: commit the fix on the current feature branch and push; never push to `main`.
+6. **Commit & push**: because the user invoked this skill to drive CI green, commit
+   the fix and push **on the current feature branch only**; never commit or push to `main`.
 7. **Re-trigger**: use the trigger method determined above.
 8. **Wait**: poll `gh run watch` until the new run completes.
 9. If still failing, go to step 1.
@@ -42,6 +43,8 @@ Repeat until green or 5 iterations reached:
 After 5 iterations without green, stop and report the current state and last error to the user.
 
 ## Guardrails
+- This skill commits and pushes as an explicitly user-invoked action, on the
+  feature branch only — never autonomously and never on `main`.
 - Never push to `main`.
 - Never force-push.
 - Never use `--no-verify`.

package/src/.claude/skills/watch-ci/SKILL.md

@@ -34,7 +34,8 @@ Repeat until green or 5 iterations reached:
 3. **Investigate** (HARD only) — invoke the `investigate-claude` agent with the diagnostic report and triage output; receive a root-cause analysis and fix strategy.
 4. **Fix** — invoke the `code-claude` agent with the triage fix suggestion (EASY) or investigate fix strategy (HARD) to apply the change.
 5. **Validate** — run the narrowest relevant tests, lint, or build command before attempting a new CI run.
-6. **Commit & push** — commit the fix on the current feature branch and push; never push to `main`.
+6. **Commit & push** — because the user invoked this skill to drive CI green, commit
+   the fix and push **on the current feature branch only**; never commit or push to `main`.
 7. **Re-trigger** — use the trigger method determined above.
 8. **Wait** — poll `gh run watch` until the new run completes.
 9. If still failing, go to step 1.
@@ -42,6 +43,8 @@ Repeat until green or 5 iterations reached:
 After 5 iterations without green, stop and report the current state and last error to the user.
 
 ## Guardrails
+- This skill commits and pushes as an explicitly user-invoked action, on the
+  feature branch only — never autonomously and never on `main`.
 - Never push to `main`.
 - Never force-push.
 - Never use `--no-verify`.

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

@@ -33,7 +33,8 @@ Repeat until green or 5 iterations reached:
 2. **Triage** — invoke the `triage-copilot` agent with the diagnostic report; receive EASY or HARD classification.
 3. **Investigate** (HARD only) — invoke the `investigate-copilot` agent with the diagnostic report and triage output; receive a root-cause analysis and fix strategy.
 4. **Fix** — invoke the `code-copilot` agent with the triage fix suggestion (EASY) or investigate fix strategy (HARD) to apply the change.
-5. **Commit & push** — commit the fix on the current feature branch and push; never push to `main`.
+5. **Commit & push** — because the user invoked this skill to drive CI green, commit
+   the fix and push **on the current feature branch only**; never commit or push to `main`.
 6. **Re-trigger** — use the trigger method determined above.
 7. **Wait** — poll `gh run watch` until the new run completes.
 8. If still failing, go to step 1.
@@ -41,6 +42,8 @@ Repeat until green or 5 iterations reached:
 After 5 iterations without green, stop and report the current state and last error to the user.
 
 ## Guardrails
+- This skill commits and pushes as an explicitly user-invoked action, on the
+  feature branch only — never autonomously and never on `main`.
 - Never push to `main`.
 - Never force-push.
 - Never use `--no-verify`.

package/src/HUMAN.md

@@ -19,7 +19,7 @@ skills are ready to use immediately. See the root `README.md` for all flags (`--
 Once the files are written:
 
 1. Confirm `MARCOS-AI-BOOTSTRAP.md`, `HUMAN.md`, and your tool's agent/skill files are present in the repo.
-2. Switch to your most powerful model at medium effort using **`/model`** e.g. opus 4.8 @ medium effort
+2. Switch to your most capable model at medium effort using **`/model`** (e.g. an Opus-class model, as an interchangeable example — not a requirement)
 3. Run the **`/initialize`** skill once to reconcile MCP servers, plan-document location, and model IDs with your environment.
 4. **`/clear`** — Clear the context window.
 5. use **`/model`** to switch your model to your most powerful model @ low effort (to save tokens)

package/src/MARCOS-AI-BOOTSTRAP.md

@@ -30,6 +30,11 @@ Infer the project's platform footprint before installing anything. Inspect, in o
 
 Map the footprint to candidate MCP servers. Common mappings (extend as the ecosystem grows):
 
+> The package/endpoint values below are **illustrative and may churn** — MCP
+> server names, packages, and URLs change upstream. Treat them as starting
+> points and confirm the current command against the server's own docs before
+> installing.
+
 | Signal in repo | Candidate MCP server | Package / endpoint |
 |---|---|---|
 | Azure services, Bicep, `az`, `DefaultAzureCredential` | `azure` | `npx -y @azure/mcp@latest server start` |
@@ -93,9 +98,13 @@ args = ["-y", "<package>", "..."]
 
 ## Guardrails
 
-- **No agent shall commit code.** Agents modify files and write changes; the user owns committing those changes to git.
-- Never commit to main
-- Never push to main
+- **No agent commits or pushes autonomously.** Agents modify files and write
+  changes; the user owns committing and pushing. The single exception is a skill
+  the user has explicitly invoked to do so (e.g. `watch-ci`): such a skill may
+  commit and push **only on a feature branch**, and **only to perform the action
+  the user invoked it for**. It must never commit or push unprompted.
+- **Never commit to `main`.** No exception — the carve-out above never applies to `main`.
+- **Never push to `main`.** No exception — the carve-out above never applies to `main`.
 - Always work on a feature / chore / bugfix branch
 - Never merge a Pull Request
 - Never update cloud infrastructure manually — all changes must go through IAC or deployment pipelines
@@ -113,7 +122,10 @@ Canonical skills:
 **Target resolution:** Accepts nothing (current-branch PR), a PR number, or a pasted PR URL, workflow-run URL, or workflow-file URL. Parses `owner/repo` from URLs and passes `--repo` to `gh` for remote targets.
 **Trigger-aware re-runs:** Inspects the workflow's `on:` block and classifies the trigger as auto-on-push, manual-dispatch, scheduled, or other. Re-triggers by pushing (auto-on-push), by `gh workflow run` (manual-dispatch/other), or stops with an explanation when a scheduled-only workflow cannot be forced.
 **Pipeline:** `log-reader` → `triage` → (`investigate` if HARD) → `code`, then commit/push on the feature branch and loop (max 5 iterations).
-**Guardrails:** Never pushes to `main`, never force-pushes, never `--no-verify`. For remote-repo targets it cannot edit locally, so it watches, diagnoses, and reports the fix back to the user.
+**Guardrails:** Runs only because the user invoked it; on that authority it may
+commit and push its fixes **on the feature branch only**. Never pushes or commits
+to `main`, never force-pushes, never `--no-verify`. For remote-repo targets it
+cannot edit locally, so it watches, diagnoses, and reports the fix back to the user.
 
 ### planner
 **Purpose:** Formalise the two-stage planning flow into a single command. Runs the `planner-discovery` agent (Stage 1: clarifying questions + outline), gates on explicit user approval, then runs the `planner` agent (Stage 2: full implementation plan written to `documents/plans/<YYYYMMDD>-<topic>.md`).
@@ -150,7 +162,8 @@ Canonical skills:
 
 ## Documentation Rules
 
-- Update the root `README.md` on every change.
+- Update the root `README.md` when a change affects how the tool is installed,
+  invoked, or what it produces — not for internal-only changes with no user-facing effect.
 - Update the service-level `README.md` inside the affected application on relevant changes.
 - Update documentation last — after implementation and verification are complete.
 - Never leave examples, commands, file paths, or architecture descriptions stale after a change.