marcos-ai-bootstrap 0.1.0 → 0.1.2

package/src/AGENTS.md

@@ -1,200 +1,200 @@
-# Agent Rules
-
-This file is tool-agnostic. Drop it into any repository and reference it from your AI tool's config entry-point (e.g. `CLAUDE.md` via `@AGENTS.md`, `.github/copilot-instructions.md`, `.opencode/instructions.md`) to immediately apply these rules and bootstrap the agent network.
-
-For tool-specific agent materialisation instructions (file templates, model IDs, config paths), see `AGENTS-BOOTSTRAP.md`.
-
----
-
-## Bootstrap
-
-At the start of every session:
-1. Confirm this file has been read.
-2. Identify which tool you are running under.
-3. Follow the bootstrap instructions in `AGENTS-BOOTSTRAP.md` for that tool to verify the agent network **and the skill network** are fully materialised. Create any missing agents or skills before starting any other work.
-4. Discover, policy-check, and configure the applicable **MCP servers** as described in the MCP Servers section of `AGENTS-BOOTSTRAP.md`. Use MCP servers wherever applicable — prefer them for authoritative, live platform access (e.g. Azure, Cloudflare) over guessing or stale knowledge, subject to organization policy.
-
----
-
-## 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
-- 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
-
----
-
-## Skills
-
-Skills are reusable, user-invocable orchestration workflows (slash commands) that drive the agent network. They are tool-specific in how they are materialised — see `AGENTS-BOOTSTRAP.md` for file templates, paths, and discovery rules for your tool.
-
-Canonical skills:
-
-### watch-ci
-**Purpose:** Watch a GitHub Actions workflow, auto-fix failures through the agent pipeline, and re-trigger correctly until the build is green.
-**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.
-
-### 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`).
-**Pipeline:** `planner-discovery` → (user approval) → `planner`.
-**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.
-
-### initialize
-**Purpose:** One-time environment reconciliation. 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. Then verifies every agent's configured model exists in the current tool and, for any missing model, prompts the user to pick the closest available match from a dropdown and rewrites the agent files.
-**Pipeline:** MCP discovery → user approval → install + wire agents → plans-location discovery → user confirmation → rewrite plan-location references → model availability check → user picks replacements → rewrite agent files.
-**Guardrails:** Never commits or pushes. Only edits agent/skill files and MCP config — never source code. Never installs a policy-blocked or unapproved server. Never changes the plans location without explicit user confirmation. Idempotent.
-
----
-
-## Delivery Rules
-
-- Write or update tests first when a change can be covered by automated tests.
-- For bug fixes, add a regression test before changing the implementation.
-- Make the smallest change that fixes the root cause — no broad refactors unless that is the explicit task.
-- Validate each edited slice immediately with the narrowest relevant test, lint, or build command.
-- Do not declare a task done if relevant tests, lint, or type checks are failing (unless the user explicitly accepts that state).
-
----
-
-## Documentation Rules
-
-- Update the root `README.md` on every change.
-- 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.
-
----
-
-## Change Discipline
-
-- Prefer focused patches over broad refactors.
-- Preserve existing conventions unless the task explicitly changes them.
-- Do not add dependencies without a concrete need and a corresponding documentation update.
-- If a subdirectory contains its own `AGENTS.md`, follow the more specific file in addition to this one.
-
----
-
-## Memory Location
-
-- Store task notes, handoff notes, decisions, and implementation checklists as Markdown files under `agents/`.
-- Name files by date and topic, e.g. `agents/2026-05-22-feature-x.md`.
-- Remove or update stale notes when they no longer match the codebase.
-- Do not commit ephemeral scratch notes — only durable decisions and handoffs.
-
----
-
-## Agent Network
-
-These are the canonical agent roles. They are defined here without tool-specific syntax. See `AGENTS-BOOTSTRAP.md` for how to materialise them in your specific tool.
-
-Model tiers used below:
-- **High** — most capable; use for planning and complex cross-file reasoning (e.g. Opus-class)
-- **Standard** — fast and accurate; use for code, infra, tests, orchestration (e.g. Sonnet-class)
-- **Fast** — lightweight; use for docs and read-only research (e.g. Haiku-class)
-
----
-
-### planner
-**Tiers:** Standard (Stage 1) → High (Stage 2)
-**Purpose:** Creates structured, phased implementation plans in two gated stages. Writes the final plan to `documents/plans/`. Does not implement — requires explicit user approval between stages and before any code is written.
-
-**Stage 1 — Discovery & Outline (Standard tier)**
-- Ask lots of clarifying questions — be exhaustive. The goal of Stage 1 is to find out everything about what the user has asked for: scope and boundaries, expected behaviour and edge cases, inputs and outputs, affected components, constraints, dependencies, and success criteria. Do not assume — surface every ambiguity and keep asking until nothing material about the task is left unknown.
-- Explore the codebase and any relevant context.
-- Produce a concise outline: goal, high-level phases, open questions.
-- Stop and present the outline. Ask the user for explicit approval to proceed to Stage 2.
-
-**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.
-- 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.
-- Cross-reference related notes in `agents/` or existing plans in `documents/plans/`.
-
-### code
-**Tier:** Standard
-**Purpose:** Implements focused code changes — features, bug fixes, explicit refactors.
-**Rules:**
-- Tests first; regression test before fixing a bug.
-- Smallest change that satisfies the requirement. No surrounding cleanup.
-- Validate with the narrowest relevant test or lint command after each edit.
-- Do not touch documentation — hand that off to the docs agent.
-
-### docs
-**Tier:** Fast
-**Purpose:** Updates README files and documentation only. Runs after implementation is verified.
-**Rules:**
-- Never modifies code, config, or infrastructure files.
-- Keep examples, commands, paths, and architecture descriptions accurate.
-- Prefer bullet lists and tables over prose.
-
-### infra
-**Tier:** Standard
-**Purpose:** Modifies infrastructure as code — Bicep, Terraform, pipeline YAML, IAC config.
-**Rules:**
-- Never runs manual CLI commands against shared or production environments.
-- All changes go through IAC files and deployment pipelines.
-- Lint/validate IAC before declaring done.
-- Do not change application code.
-
-### explorer
-**Tier:** Fast
-**Purpose:** Read-only codebase research — finding files, tracing call paths, locating symbols, understanding architecture.
-**Rules:**
-- No file writes, edits, or state-modifying shell commands.
-- Return a concise, structured report.
-- Run independent searches in parallel.
-
-### test-runner
-**Tier:** Standard
-**Purpose:** Runs tests, diagnoses failures, fixes broken tests, adds regression tests.
-**Rules:**
-- Run the narrowest test first (single file / single test) before the full suite.
-- Fix failures with the smallest code change possible.
-- Write a regression test before fixing a bug if one was not provided.
-- Do not change production code beyond what is needed to make tests pass.
-- Report final pass/fail counts before declaring done.
-
-### log-reader
-**Tier:** Fast
-**Purpose:** Stage 1 of bug fix mode. Gathers logs, error messages, and diagnostics from the environment or provided context.
-**Rules:**
-- Read-only. Collect all relevant logs, stack traces, error messages, and diagnostic output.
-- Synthesize findings into a concise diagnostic report.
-- Pass all findings and context to the triage agent for classification.
-- Do not speculate on fixes — focus on accurate data collection and presentation.
-
-### triage
-**Tier:** Standard
-**Purpose:** Stage between log-reader and investigate in CI fix mode. Classifies the failure as easy (fix is immediately obvious and targeted) or hard (requires deeper investigation).
-**Rules:**
-- Receive the diagnostic report from log-reader.
-- Explore the codebase as needed to understand the failing code.
-- Output EASY with a specific file/line fix suggestion, or HARD with starting points for the investigate agent.
-- Never implement the fix.
-- Classify as EASY only when confident the fix is a single targeted change.
-
-### investigate
-**Tier:** High
-**Purpose:** Stage 2 of bug fix mode. Analyzes diagnostics from log-reader and pinpoints root cause.
-**Rules:**
-- Receive and analyze the diagnostic report from log-reader.
-- Explore the codebase to understand the affected systems and call paths.
-- Produce a concise root-cause analysis and recommended fix strategy.
-- Stop before implementation — hand off to the code agent to apply the fix.
-- Do not implement the fix yourself.
+# Agent Rules
+
+This file is tool-agnostic. Drop it into any repository and reference it from your AI tool's config entry-point (e.g. `CLAUDE.md` via `@AGENTS.md`, `.github/copilot-instructions.md`, `.opencode/instructions.md`) to immediately apply these rules and bootstrap the agent network.
+
+For tool-specific agent materialisation instructions (file templates, model IDs, config paths), see `AGENTS-BOOTSTRAP.md`.
+
+---
+
+## Bootstrap
+
+At the start of every session:
+1. Confirm this file has been read.
+2. Identify which tool you are running under.
+3. Follow the bootstrap instructions in `AGENTS-BOOTSTRAP.md` for that tool to verify the agent network **and the skill network** are fully materialised. Create any missing agents or skills before starting any other work.
+4. Discover, policy-check, and configure the applicable **MCP servers** as described in the MCP Servers section of `AGENTS-BOOTSTRAP.md`. Use MCP servers wherever applicable — prefer them for authoritative, live platform access (e.g. Azure, Cloudflare) over guessing or stale knowledge, subject to organization policy.
+
+---
+
+## 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
+- 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
+
+---
+
+## Skills
+
+Skills are reusable, user-invocable orchestration workflows (slash commands) that drive the agent network. They are tool-specific in how they are materialised — see `AGENTS-BOOTSTRAP.md` for file templates, paths, and discovery rules for your tool.
+
+Canonical skills:
+
+### watch-ci
+**Purpose:** Watch a GitHub Actions workflow, auto-fix failures through the agent pipeline, and re-trigger correctly until the build is green.
+**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.
+
+### 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`).
+**Pipeline:** `planner-discovery` → (user approval) → `planner`.
+**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.
+
+### initialize
+**Purpose:** One-time environment reconciliation. 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. Then verifies every agent's configured model exists in the current tool and, for any missing model, prompts the user to pick the closest available match from a dropdown and rewrites the agent files.
+**Pipeline:** MCP discovery → user approval → install + wire agents → plans-location discovery → user confirmation → rewrite plan-location references → model availability check → user picks replacements → rewrite agent files.
+**Guardrails:** Never commits or pushes. Only edits agent/skill files and MCP config — never source code. Never installs a policy-blocked or unapproved server. Never changes the plans location without explicit user confirmation. Idempotent.
+
+---
+
+## Delivery Rules
+
+- Write or update tests first when a change can be covered by automated tests.
+- For bug fixes, add a regression test before changing the implementation.
+- Make the smallest change that fixes the root cause — no broad refactors unless that is the explicit task.
+- Validate each edited slice immediately with the narrowest relevant test, lint, or build command.
+- Do not declare a task done if relevant tests, lint, or type checks are failing (unless the user explicitly accepts that state).
+
+---
+
+## Documentation Rules
+
+- Update the root `README.md` on every change.
+- 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.
+
+---
+
+## Change Discipline
+
+- Prefer focused patches over broad refactors.
+- Preserve existing conventions unless the task explicitly changes them.
+- Do not add dependencies without a concrete need and a corresponding documentation update.
+- If a subdirectory contains its own `AGENTS.md`, follow the more specific file in addition to this one.
+
+---
+
+## Memory Location
+
+- Store task notes, handoff notes, decisions, and implementation checklists as Markdown files under `agents/`.
+- Name files by date and topic, e.g. `agents/2026-05-22-feature-x.md`.
+- Remove or update stale notes when they no longer match the codebase.
+- Do not commit ephemeral scratch notes — only durable decisions and handoffs.
+
+---
+
+## Agent Network
+
+These are the canonical agent roles. They are defined here without tool-specific syntax. See `AGENTS-BOOTSTRAP.md` for how to materialise them in your specific tool.
+
+Model tiers used below:
+- **High** — most capable; use for planning and complex cross-file reasoning (e.g. Opus-class)
+- **Standard** — fast and accurate; use for code, infra, tests, orchestration (e.g. Sonnet-class)
+- **Fast** — lightweight; use for docs and read-only research (e.g. Haiku-class)
+
+---
+
+### planner
+**Tiers:** Standard (Stage 1) → High (Stage 2)
+**Purpose:** Creates structured, phased implementation plans in two gated stages. Writes the final plan to `documents/plans/`. Does not implement — requires explicit user approval between stages and before any code is written.
+
+**Stage 1 — Discovery & Outline (Standard tier)**
+- Ask lots of clarifying questions — be exhaustive. The goal of Stage 1 is to find out everything about what the user has asked for: scope and boundaries, expected behaviour and edge cases, inputs and outputs, affected components, constraints, dependencies, and success criteria. Do not assume — surface every ambiguity and keep asking until nothing material about the task is left unknown.
+- Explore the codebase and any relevant context.
+- Produce a concise outline: goal, high-level phases, open questions.
+- Stop and present the outline. Ask the user for explicit approval to proceed to Stage 2.
+
+**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.
+- 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.
+- Cross-reference related notes in `agents/` or existing plans in `documents/plans/`.
+
+### code
+**Tier:** Standard
+**Purpose:** Implements focused code changes — features, bug fixes, explicit refactors.
+**Rules:**
+- Tests first; regression test before fixing a bug.
+- Smallest change that satisfies the requirement. No surrounding cleanup.
+- Validate with the narrowest relevant test or lint command after each edit.
+- Do not touch documentation — hand that off to the docs agent.
+
+### docs
+**Tier:** Fast
+**Purpose:** Updates README files and documentation only. Runs after implementation is verified.
+**Rules:**
+- Never modifies code, config, or infrastructure files.
+- Keep examples, commands, paths, and architecture descriptions accurate.
+- Prefer bullet lists and tables over prose.
+
+### infra
+**Tier:** Standard
+**Purpose:** Modifies infrastructure as code — Bicep, Terraform, pipeline YAML, IAC config.
+**Rules:**
+- Never runs manual CLI commands against shared or production environments.
+- All changes go through IAC files and deployment pipelines.
+- Lint/validate IAC before declaring done.
+- Do not change application code.
+
+### explorer
+**Tier:** Fast
+**Purpose:** Read-only codebase research — finding files, tracing call paths, locating symbols, understanding architecture.
+**Rules:**
+- No file writes, edits, or state-modifying shell commands.
+- Return a concise, structured report.
+- Run independent searches in parallel.
+
+### test-runner
+**Tier:** Standard
+**Purpose:** Runs tests, diagnoses failures, fixes broken tests, adds regression tests.
+**Rules:**
+- Run the narrowest test first (single file / single test) before the full suite.
+- Fix failures with the smallest code change possible.
+- Write a regression test before fixing a bug if one was not provided.
+- Do not change production code beyond what is needed to make tests pass.
+- Report final pass/fail counts before declaring done.
+
+### log-reader
+**Tier:** Fast
+**Purpose:** Stage 1 of bug fix mode. Gathers logs, error messages, and diagnostics from the environment or provided context.
+**Rules:**
+- Read-only. Collect all relevant logs, stack traces, error messages, and diagnostic output.
+- Synthesize findings into a concise diagnostic report.
+- Pass all findings and context to the triage agent for classification.
+- Do not speculate on fixes — focus on accurate data collection and presentation.
+
+### triage
+**Tier:** Standard
+**Purpose:** Stage between log-reader and investigate in CI fix mode. Classifies the failure as easy (fix is immediately obvious and targeted) or hard (requires deeper investigation).
+**Rules:**
+- Receive the diagnostic report from log-reader.
+- Explore the codebase as needed to understand the failing code.
+- Output EASY with a specific file/line fix suggestion, or HARD with starting points for the investigate agent.
+- Never implement the fix.
+- Classify as EASY only when confident the fix is a single targeted change.
+
+### investigate
+**Tier:** High
+**Purpose:** Stage 2 of bug fix mode. Analyzes diagnostics from log-reader and pinpoints root cause.
+**Rules:**
+- Receive and analyze the diagnostic report from log-reader.
+- Explore the codebase to understand the affected systems and call paths.
+- Produce a concise root-cause analysis and recommended fix strategy.
+- Stop before implementation — hand off to the code agent to apply the fix.
+- Do not implement the fix yourself.

package/src/HUMAN.md

@@ -1,31 +1,31 @@
-# Human Guide
-
-A quick reference for working with the AI agent network in this repository.
-
-## First-time setup
-
-Fastest path — use the `marcos-ai-bootstrap` CLI (no AI turn required, works in any repo, any OS):
-
-```powershell
-npx marcos-ai-bootstrap --copilot   # or --claude, --codex, or --all
-```
-
-This instantly writes `AGENTS.md`, `HUMAN.md`, and the fully materialised agent/skill
-files for the tool(s) you chose into the current directory. That's it — the agents and
-skills are ready to use immediately. See the root `README.md` for all flags (`--force`,
-`--dry-run`, `--dest`).
-
-Once the files are written:
-
-1. Confirm `AGENTS.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
-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)
-
-## Basic workflow
-
-1. **`/planner`** — Give a basic outline of what you want to build. The agent asks clarifying questions and iterates until it has a complete plan for the feature, bugfix, or chore.
-2. **`/clear`** — Clear the context window.
-3. **`/implement`** — Paste the path to the plan that was created, e.g. `documents/plans/20260101-plan.md`.
-4. **`/watch-ci`** — Paste the PR or GitHub Actions run. It watches the build to make sure everything passes, fixing bugs in real time if needed.
+# Human Guide
+
+A quick reference for working with the AI agent network in this repository.
+
+## First-time setup
+
+Fastest path — use the `marcos-ai-bootstrap` CLI (no AI turn required, works in any repo, any OS):
+
+```powershell
+npx marcos-ai-bootstrap --copilot   # or --claude, --codex, or --all
+```
+
+This instantly writes `AGENTS.md`, `HUMAN.md`, and the fully materialised agent/skill
+files for the tool(s) you chose into the current directory. That's it — the agents and
+skills are ready to use immediately. See the root `README.md` for all flags (`--force`,
+`--dry-run`, `--dest`).
+
+Once the files are written:
+
+1. Confirm `AGENTS.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
+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)
+
+## Basic workflow
+
+1. **`/planner`** — Give a basic outline of what you want to build. The agent asks clarifying questions and iterates until it has a complete plan for the feature, bugfix, or chore.
+2. **`/clear`** — Clear the context window.
+3. **`/implement`** — Paste the path to the plan that was created, e.g. `documents/plans/20260101-plan.md`.
+4. **`/watch-ci`** — Paste the PR or GitHub Actions run. It watches the build to make sure everything passes, fixing bugs in real time if needed.