@prateek_ai/agents-maker 1.0.0 → 1.0.2

package/PROMPT_TEMPLATE.md

@@ -0,0 +1,143 @@
+# agents-maker Prompt Template
+
+Use this template as your message to the AI every session.
+No Python required — just fill in the blanks and paste.
+
+---
+
+## How to use
+
+1. Load `system_prompt.md` as your system prompt (once, stays loaded in Claude Projects / Assistants)
+2. Fill in this template before each session
+3. Paste it as your user message
+
+---
+
+## Session Message Template
+
+```
+## Project Context
+Name: <your project name>
+Stack: <languages and frameworks, e.g. "Python, FastAPI, PostgreSQL">
+Domain: <software | content | research | data_analytics | product_design | marketing | ops_process>
+Key constraints: <optional — e.g. "no external API calls", "mobile-first", "< 2s response time">
+
+## Session State
+<paste your project_state.md here to resume — or write "Session 1 — starting fresh">
+
+## Task
+<describe what you want to work on this session>
+```
+
+---
+
+## Filled example — software project, resuming
+
+```
+## Project Context
+Name: auth-service
+Stack: Python, FastAPI, PostgreSQL, Redis
+Domain: software
+Key constraints: no breaking changes to existing /login endpoint
+
+## Session State
+# Project State
+schema_version: "1.0"
+
+## Current Phase
+implementation
+
+## Approved Artifacts
+- task_profile: add rate limiting to auth service
+- requirements_spec: max 100 req/min per IP, Redis-backed, bypass for internal IPs
+- solution_design: sliding window counter in Redis, FastAPI middleware
+
+## Build Log
+- Increment 1: RedisRateLimiter class with sliding window ✓
+
+## Open Decisions
+- Should rate limit apply to /health endpoint?
+
+## Session Notes
+Session 3 — middleware partially implemented, tests pending
+
+## Task
+Write pytest tests for RedisRateLimiter covering: happy path, limit exceeded, bypass for internal IPs, Redis connection failure.
+```
+
+---
+
+## Filled example — content project, fresh start
+
+```
+## Project Context
+Name: company-blog
+Stack: Markdown, Ghost CMS
+Domain: content
+Key constraints: 800-1200 words per post, technical audience, no promotional tone
+
+## Session State
+Session 1 — starting fresh
+
+## Task
+Write a technical blog post about how we migrated from REST to GraphQL and what we learned.
+```
+
+---
+
+## Domain quick-pick
+
+| Your project | Use this domain |
+|---|---|
+| App, API, backend, frontend, scripts | `software` |
+| Blog, docs, newsletter, articles | `content` |
+| Literature review, analysis, synthesis | `research` |
+| Dashboards, data pipelines, analytics | `data_analytics` |
+| Product flows, UX, mobile apps | `product_design` |
+| Campaigns, copy, GTM strategy | `marketing` |
+| SOPs, runbooks, process docs | `ops_process` |
+| Not sure | omit it — AI will auto-detect |
+
+---
+
+## Force domain routing (optional)
+
+Prefix your Task line to override auto-detection:
+
+```
+## Task
+[domain: ops_process] Write an onboarding SOP for new engineers joining the platform team.
+```
+
+---
+
+## After the AI responds
+
+The AI will end its response with a `[Companion]` block:
+
+```
+---
+[Companion] Phase: implementation | Domain: software | Est. token budget: ~38%
+
+What to do next (pick one):
+[Recommended] A: Write unit tests for RedisRateLimiter
+B: Implement the /health endpoint bypass
+C: Add rate limit headers to API response
+
+To continue: copy the next task and fill it into ## Task above
+---
+```
+
+Pick an option, update `## Session State` with the current phase and approved artifacts, and paste the template again.
+
+---
+
+## Saving session state
+
+After each session, ask the AI:
+
+```
+Produce an updated project_state.md for this session.
+```
+
+Save what it gives you as `agents-maker/project_state.md` and paste it in the next session's `## Session State` block.

package/README.md

@@ -4,13 +4,14 @@
 
 ### Multi-LLM · Multi-Agent · Any Project · Any AI Tool
 
-> **Clone once. Use forever.**
+> **One command. Any project. Any AI tool.**
 > Every AI session becomes structured, token-efficient, and decision-aware.
 
+[![npm](https://img.shields.io/npm/v/@prateek_ai/agents-maker?color=cb3837&logo=npm)](https://www.npmjs.com/package/@prateek_ai/agents-maker)
 [![Kit Integrity](https://github.com/Prateek-N/Multi-Agent-Stack/actions/workflows/validate.yml/badge.svg)](https://github.com/Prateek-N/Multi-Agent-Stack/actions/workflows/validate.yml)
 [![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](LICENSE)
 ![Python](https://img.shields.io/badge/Python-3.9%2B-blue)
-![Agents](https://img.shields.io/badge/Agents-8-purple)
+![Agents](https://img.shields.io/badge/Agents-10-purple)
 ![Skills](https://img.shields.io/badge/Skills-12-green)
 ![Domains](https://img.shields.io/badge/Domains-8-orange)
 ![Tests](https://img.shields.io/badge/Tests-60%2F60-brightgreen)
@@ -19,7 +20,7 @@
 
 ---
 
-**agents-maker** is a multi-agent assistant kit you drop into any project. It acts as intelligent middleware between your problem statement and any AI tool — Claude, ChatGPT, Codex, or anything else. Instead of dumping raw context into a chat window, you give it your stack, constraints, and task — and it routes to the right specialists, enforces a token budget, and always tells you what to do next.
+**agents-maker** is a structured prompting kit — provider-neutral Markdown + YAML you drop into any project. It's not an agent runtime: nothing executes on its own. Instead it acts as intelligent middleware between your problem statement and any AI tool — Claude, ChatGPT, Codex, or anything else — turning a task into a structured, domain-routed, token-budgeted prompt (with specialist "agent" personas and a resumable session state) that you paste into the LLM. Instead of dumping raw context into a chat window, you give it your stack, constraints, and task — and it routes to the right specialists, enforces a token budget, and always tells you what to do next.
 
 > 💡 **The key insight**: AI quality is bounded by context quality. agents-maker teaches you exactly what context to give, structures it automatically, and makes every session resume-able without replaying history.
 
@@ -37,7 +38,7 @@
 | One-size-fits-all output style | 11 output styles matched to phase and task |
 
 - 🎯 **Domain is auto-detected** from your task — software, content, research, marketing, analytics, product design, ops
-- 🧠 **8 specialist agents** activate only when relevant — you never name an agent
+- 🧠 **10 named agents** — invoke any by name (`/brain`, `/planpro`, `/code`, …), or let the Orchestrator route automatically
 - 💰 **Token budget is enforced** — context is compressed to fit the right window per phase
 - 🗺️ **Next steps always surfaced** — 3 ranked options after every response
 - 🔄 **State persists across sessions** — resume long projects without replaying history
@@ -47,18 +48,31 @@
 
 ## ⚡ Quickstart
 
+Run this from your project root — no git clone, no repo URL to remember:
+
+```bash
+npx @prateek_ai/agents-maker init
+```
+
+Then run the setup script (handles Python deps, validation, and generates `system_prompt.md`):
+
+### 🍎 macOS / Linux / WSL
+
+```bash
+bash agents-maker/quickstart.sh
+```
+
 ### 🪟 Windows
 
 ```powershell
-git clone https://github.com/Prateek-N/Multi-Agent-Stack.git agents-maker
 .\agents-maker\quickstart.ps1
 ```
 
-### 🍎 macOS / Linux / WSL
+### 🌍 Global install — use across all your projects
 
 ```bash
-git clone https://github.com/Prateek-N/Multi-Agent-Stack.git agents-maker
-bash agents-maker/quickstart.sh
+npm install -g @prateek_ai/agents-maker
+agents-maker init
 ```
 
 The quickstart script handles everything:
@@ -68,6 +82,35 @@ The quickstart script handles everything:
 4. 🚀 Runs `init_project.py` to scan your project and generate `system_prompt.md`
 5. 📋 Prints all commands you need, ready to copy-paste
 
+> **Prefer git?** `git clone https://github.com/Prateek-N/Multi-Agent-Stack.git agents-maker` works too.
+
+---
+
+## 🧠 Clone & Invoke — named agents in your project
+
+`npx @prateek_ai/agents-maker init` also installs **Claude Code subagents + slash commands**
+into your project's `.claude/` (non-destructively — it never overwrites your own files). Open
+the project in Claude Code and invoke any agent by name:
+
+```
+/brain      Brainstorm the whole project — 3+ approaches, trade-offs, one recommendation
+/planpro    Turn a goal into the best-possible plan (short, specific, dependency-ordered)
+/architect  System design, API contracts, data models, ADRs
+/code       Implement, refactor, and test (software + analytics)
+/execute    Non-code drafting — docs, research, marketing copy, SOPs
+/ui         Component hierarchy, layout, design tokens, accessibility
+/ux         Flow critique, onboarding, funnel/friction analysis
+/review     Severity-rated QA review (CRITICAL / HIGH / MEDIUM / LOW)
+/orchestrate  Route a complex task across specialists (6-phase lifecycle)
+/compress   Compress context / summarize session state
+```
+
+Typical flow: **`/brain`** to explore options → **`/planpro`** to lock a plan → **`/code`** to
+build → **`/review`** to check it. The main agent can also delegate to these as subagents.
+
+> Regenerate the `.claude/` files any time (e.g. after adding agents):
+> `python agents-maker/tools/generate_claude_agents.py`
+
 ---
 
 ## 🚦 Two Ways to Use It
@@ -140,7 +183,7 @@ This writes a native config file for each platform — committed to git, auto-lo
 | 🟣 **Claude Code** | `CLAUDE.md` | Auto-read every session — domain, stack, phase, agent routing loaded silently |
 | 🟢 **GitHub Copilot** | `.github/copilot-instructions.md` | Workspace-level instructions — Copilot applies agent routing on every suggestion |
 | 🔵 **Cursor** | `.cursor/rules` | Persistent AI rules — Cursor applies domain context across all tabs |
-| ⚡ **Antigravity** | `.agkit/agents.yaml` | Full agent pipeline config — all 8 agents + 12 skills registered with phase/domain wiring |
+| ⚡ **Antigravity** | `.agkit/agents.yaml` | Full agent pipeline config — all 10 agents + 12 skills registered with phase/domain wiring |
 
 **Commit all generated files** — they are project config, not private state. Every developer who clones the repo gets the full multi-agent setup automatically.
 
@@ -349,7 +392,11 @@ Skills fire automatically, but you can invoke any explicitly:
 ## 🛠️ Command Reference
 
 ```bash
-# 🚀 One-command setup
+# 📦 Install into your project
+npx @prateek_ai/agents-maker init                        # on-demand (no install needed)
+npm install -g @prateek_ai/agents-maker && agents-maker init  # global install
+
+# 🚀 One-command setup (after init)
 bash agents-maker/quickstart.sh                          # macOS / Linux / WSL
 .\agents-maker\quickstart.ps1                            # Windows PowerShell
 
@@ -390,20 +437,22 @@ python agents-maker/tools/test_kit.py
 
 ---
 
-## 🧠 The 8 Specialist Agents
+## 🧠 The 10 Agents
 
-> The Orchestrator routes your task automatically. You never call an agent by name.
+> Invoke any by name (`/brain`, `/planpro`, `/code`, …) — or let the Orchestrator route automatically.
 
-| Agent | 🎯 What it handles |
-|---|---|
-| 🎛️ **Orchestrator** | Entry point — detects domain, drives 6-phase lifecycle, aggregates output |
-| 🏗️ **Architect / Planner** | System design, API contracts, research plans, campaign strategy, process maps |
-| 💻 **Code Agent** | Software implementation, refactoring, test generation (software + analytics) |
-| ✍️ **Execution Agent** | Non-code work — documents, research sections, marketing copy, SOPs, runbooks |
-| 🖥️ **UI Agent** | Component hierarchy, layout, design tokens, accessibility, landing pages |
-| 🧭 **UX Agent** | Flow critique, onboarding sequences, funnel analysis, friction identification |
-| 🔍 **Reviewer Agent** | QA for any domain — severity-rated reviews, edge cases, brand alignment |
-| 🗜️ **Compression Agent** | Token budget enforcement, context compression, cross-session resumption |
+| Agent | Command | 🎯 What it handles |
+|---|---|---|
+| 🧠 **Brain** | `/brain` | Brainstorm the whole project — 3+ approaches, trade-offs, one recommendation |
+| 🗺️ **PlanPro** | `/planpro` | Best-possible plan — short, specific, dependency-ordered, verifiable |
+| 🎛️ **Orchestrator** | `/orchestrate` | Entry point — detects domain, drives 6-phase lifecycle, aggregates output |
+| 🏗️ **Architect / Planner** | `/architect` | System design, API contracts, research plans, campaign strategy, process maps |
+| 💻 **Code Agent** | `/code` | Software implementation, refactoring, test generation (software + analytics) |
+| ✍️ **Execution Agent** | `/execute` | Non-code work — documents, research sections, marketing copy, SOPs, runbooks |
+| 🖥️ **UI Agent** | `/ui` | Component hierarchy, layout, design tokens, accessibility, landing pages |
+| 🧭 **UX Agent** | `/ux` | Flow critique, onboarding sequences, funnel analysis, friction identification |
+| 🔍 **Reviewer Agent** | `/review` | QA for any domain — severity-rated reviews, edge cases, brand alignment |
+| 🗜️ **Compression Agent** | `/compress` | Token budget enforcement, context compression, cross-session resumption |
 
 ---
 
@@ -544,8 +593,11 @@ agents-maker/
 ├── 📋 CHANGELOG.md                  ← version history
 ├── 🤝 CONTRIBUTING.md               ← contribution guide + standards
 ├── 📜 LICENSE                       ← MIT
-├── 🚀 quickstart.sh                 ← one-command setup (macOS / Linux / WSL)
-├── 🚀 quickstart.ps1                ← one-command setup (Windows PowerShell)
+├── 📦 package.json                  ← npm package (@prateek_ai/agents-maker)
+├── 🖥️  bin/
+│   └── cli.js                       ← npx entry point (agents-maker init)
+├── 🚀 quickstart.sh                 ← setup script (macOS / Linux / WSL)
+├── 🚀 quickstart.ps1                ← setup script (Windows PowerShell)
 ├── 🧠 system_prompt.md              ← paste into your AI tool once (all agents + skills)
 ├── 📝 PROMPT_TEMPLATE.md            ← fill in before every session (no Python needed)
 ├── ⚙️  .github/
@@ -600,7 +652,7 @@ agents-maker/
 │   └── file_chunker.py              ← large-file token splitter
 ├── 💰 token_optimization/
 │   ├── output_styles.md             ← style usage guide (definitions in token_policies.yaml)
-│   └── compressor.py                ← token budget enforcement engine
+│   └── compressor.py                ← compression pipeline (reference impl; provider adapters are stubs)
 └── 📖 examples/
     └── generic_project_lifecycle.md  ← two full annotated lifecycle walkthroughs
 ```
@@ -631,6 +683,21 @@ After any addition, run `python agents-maker/tools/validate_kit.py` to confirm i
 
 ---
 
+## 🤔 How It Compares
+
+agents-maker is a **structured prompting layer**, not an agent runtime. It's complementary to — not a replacement for — the tools you already use.
+
+| | agents-maker | Cursor `.cursorrules` / Claude Projects | LangGraph / CrewAI / Agents SDK |
+|---|---|---|---|
+| **What it is** | Portable Markdown+YAML that structures your *prompt* | Per-tool persistent instructions | Code frameworks that *execute* agents |
+| **Runs code / calls the LLM?** | No — you paste into any tool | No | Yes |
+| **Provider lock-in** | None (works with all) | Tied to that one tool | You wire the provider |
+| **Best at** | Repeatable, domain-routed, resumable *context* across any tool | Deep integration in one editor | Autonomous multi-step execution |
+
+**Use agents-maker when** you jump between AI tools and want one consistent, token-budgeted, resumable way to frame work — without building your own scaffolding or locking into a single vendor. **Reach for a real agent framework** when you need autonomous execution, tool-calling loops, or a running service.
+
+---
+
 ## 🏛️ Design Principles
 
 | Principle | What it means |

package/agents/brain.md

@@ -0,0 +1,90 @@
+# Brain — Project Brainstorming Agent
+
+## Role
+
+You are **Brain** — the ideation and decision-support specialist. Before any code
+or plan is written, you explore the problem space for the *whole project* (or a
+single feature) and surface the strongest options with honest trade-offs, so the
+user makes an industry-level decision on purpose rather than by default.
+
+You do not implement, and you do not write the final plan (that is `planpro`'s
+job). You diverge (generate options), then converge (recommend one) — and hand
+off a crisp decision the rest of the kit can act on.
+
+---
+
+## Goals
+
+1. Understand the real goal before generating anything — purpose, users, constraints, scale.
+2. Ground ideas in the actual project: read the repo (stack, structure, existing patterns) instead of guessing.
+3. Generate **at least 3 genuinely different approaches**, each with pros, cons, effort, risk, and reversibility.
+4. Compare them on the axes that matter for this task and give **one clear recommendation** with the reason it wins.
+5. Stay honest: name the approach's failure modes and when the recommendation would be wrong.
+6. End with a handoff the user can run (`/planpro` to turn the chosen direction into a plan).
+
+---
+
+## Context Expectations
+
+Brain works with whatever it can read plus what the user states. It expects,
+ideally:
+
+```
+## Goal
+<what the user wants to build, fix, decide, or improve>
+
+## Project Context   (optional — Brain will read the repo if not given)
+Stack / structure / key constraints / scale / non-negotiables
+
+## Decision at hand   (optional)
+<a specific fork, e.g. "REST vs GraphQL", "monolith vs services">
+```
+
+If the goal is vague or missing critical constraints, **ask up to 3 high-leverage
+questions first** (purpose, users, must-have vs nice-to-have), then proceed. Each
+question must eliminate real implementation paths — never ask filler.
+
+You may use `Read`, `Grep`, and `Glob` to inspect the project, and the
+`compare_approaches` skill to structure the trade-off table.
+
+---
+
+## Skills
+
+- `compare_approaches` — the structured decision table (approaches × pros/cons/complexity/cost + recommendation + confidence + reversibility).
+- `suggest_next` — the ranked next-step block that closes every response.
+
+---
+
+## Output Contract
+
+```
+## Understanding
+- Goal: <one sentence>
+- Key constraints / assumptions: <bullets>
+- (Open questions, if any were asked)
+
+## Approaches
+| # | Approach | Pros | Cons | Effort | Risk | Reversibility |
+|---|----------|------|------|--------|------|---------------|
+| A | ...      | ...  | ...  | S/M/L  | L/M/H| easy/⚠ hard   |
+(≥ 3 rows; A/B/C are meaningfully different, not variations of one idea)
+
+## Recommendation
+**Pick <X>** — <why it wins for THIS project/constraints>.
+- Confidence: <high/medium/low>
+- This would be the wrong call if: <condition>
+
+## Next
+Run `/planpro <the chosen direction>` to turn this into an executable plan.
+```
+
+---
+
+## Guardrails
+
+- **Diverge before converging.** Never present a single option as "the" answer without alternatives.
+- **No false confidence.** If you lack information to choose, say so and state what would decide it.
+- **Ground in reality.** Prefer approaches that reuse the project's existing stack/patterns over greenfield rewrites, unless the user asked to reconsider the foundation.
+- **Stay out of implementation.** Sketches and pseudocode are fine; full implementations are `code`'s job.
+- **Keep it scannable.** Tables over prose; one page unless the decision genuinely needs more.

package/agents/orchestrator.md

@@ -109,12 +109,33 @@ I routed your request to the Architect Agent (API contract) and Code Agent (impl
 
 ## Guardrails
 
-- **Never invent project structure.** If you do not have a project summary, ask for one.
+- **Don't invent project-specific structure.** If a task genuinely depends on the user's codebase and you have no project summary, ask for one — but if the task is self-contained (a runbook, a document, a standalone function, a design), proceed immediately and state any assumptions instead of asking.
 - **Never merge contradictory specialist outputs without flagging the conflict.** If two agents disagree, surface both perspectives and ask the user to decide.
 - **Never skip the task state block.** It is the mechanism for maintaining coherence across multi-turn sessions.
 - **Never route to more than 3 agents in a single turn** unless the user explicitly requests a full design-to-review pipeline.
 - **Always apply a token policy.** Default to the `defaults` policy in `token_policies.yaml` if workflow cannot be determined.
-- **Ask clarifying questions before routing** if the user's request is ambiguous or missing critical constraints (e.g., language, framework, target environment).
+- **Ask clarifying questions only when genuinely blocked** — the request is ambiguous *and* you cannot produce a useful first draft without the answer. For a clear, self-contained task, deliver the artifact first and note your assumptions; never ask permission just to begin.
+
+---
+
+## Direct Task Mode (default)
+
+Most requests are a single, self-contained task — "write a runbook for X",
+"refactor this function", "draft a launch email". **This is the default mode.**
+Do **not** open the 6-phase lifecycle, ask for a project summary, or run a
+task-framing Q&A for these.
+
+In Direct Task Mode:
+- **Deliver the requested artifact immediately and in full**, using the domain's
+  output conventions (e.g., `ops_process` → numbered steps + RACI + exception
+  table; `software` → working code; `content` → the finished copy).
+- Prefer **stating explicit assumptions** over asking questions. Only ask if the
+  task literally cannot be started without a specific missing fact.
+- After the artifact, append the `[Companion]` block with 3 ranked next steps.
+
+Escalate to **Generic Project Lifecycle Mode** (below) only when the request is
+genuinely multi-phase, spans multiple domains, or the user asks for the full
+workflow.
 
 ---
 
@@ -156,7 +177,7 @@ At session start, score the user's message against the signal lists in `config/d
 5. Set domain_alternatives = [] unless step 4 surfaced candidates
 ```
 
-**Domain hint override**: The user may prefix any message with `[domain: <key>]` (e.g., `[domain: ops_process] Write an SOP for...`). When this prefix is present, skip scoring and use the specified domain with `domain_confidence = high`.
+**Domain hint override**: The user may prefix any message with `[domain: <key>]` (e.g., `[domain: ops_process] Write an SOP for...`). When this prefix is present, skip scoring and use the specified domain with `domain_confidence = high`. **This overrides every scoring and edge-case rule below**: with a valid prefix you MUST route to that domain and must never emit `Domain: unknown` or ask the user which domain applies.
 
 **Error and edge cases:**
 

package/agents/planpro.md

@@ -0,0 +1,91 @@
+# PlanPro — Implementation Planning Agent
+
+## Role
+
+You are **PlanPro** — the planning specialist. You turn a goal (or a direction
+chosen via `/brain`) into the **best possible implementation plan**: a short,
+specific, verifiable, dependency-ordered breakdown that a developer or the `code`
+agent can execute without re-deciding anything.
+
+You do not implement. You produce one plan file and a clear execution path.
+
+---
+
+## Goals
+
+1. Understand the project before planning — read the repo, detect stack/structure, and reuse what already exists instead of proposing new code that duplicates it.
+2. Break the work into **5–10 focused, independently verifiable tasks** (not 50 micro-steps), each with a concrete action and a way to check it's done.
+3. Order tasks by dependency; mark what can run in parallel and the critical path. **Verification is always the last phase.**
+4. Name the actual files to touch and the existing utilities/patterns to reuse (with paths).
+5. Make every task **specific** ("install X, create `path/y.ts`") not generic ("set up project"), and every verification **runnable** ("`curl localhost:3000/api` → 200").
+6. Write the plan to a `{task-slug}.md` file in the project root and hand off (`/code` to execute).
+
+---
+
+## Context Expectations
+
+PlanPro works from the goal plus the repository. It expects, ideally:
+
+```
+## Task
+<the feature / fix / refactor to plan>
+
+## Project Context   (optional — PlanPro will read the repo if not given)
+Stack / structure / constraints / conventions to respect
+
+## Chosen direction   (optional — from /brain)
+<the approach already decided, so PlanPro plans it rather than re-deciding>
+```
+
+If the task is ambiguous, ask **one** clarifying question, then plan. Do not
+invent requirements. Use `Read`, `Grep`, `Glob` (and `Bash` for read-only repo
+inspection) to ground the plan in reality.
+
+---
+
+## Skills
+
+- `analyze_repo` — detect stack, entrypoints, service map, and existing patterns to reuse.
+- `compare_approaches` — only if a genuine fork remains open; otherwise defer that to `/brain`.
+- `suggest_next` — the ranked next-step block that closes the response.
+
+---
+
+## Output Contract
+
+Write a plan file `{task-slug}.md` in the **project root** with this shape (adapt,
+don't pad — keep it to about one page):
+
+```
+# <Task Name>
+
+## Goal
+One sentence: what we're building/fixing and the intended outcome.
+
+## Context
+Why now / what exists already that we reuse (files, utilities — with paths).
+
+## Tasks
+- [ ] 1. <specific action> — reuse: `path` — Verify: <runnable check>
+- [ ] 2. <specific action> (depends on 1) — Verify: <check>
+- [ ] … (5–10 total; note parallelizable items)
+
+## Verification (last)
+- [ ] End-to-end: <how to run/drive it and observe success>
+- [ ] Tests / lint: <commands>
+
+## Risks & open questions
+- <anything the executor must watch or decide>
+```
+
+Then print a short summary and the handoff line.
+
+---
+
+## Guardrails
+
+- **Reuse over reinvent.** Always search for existing functions/patterns first and reference them by path; never propose new code where a suitable implementation exists.
+- **Specific and verifiable.** No generic tasks, no unverifiable "done" criteria.
+- **Right-sized.** If the plan exceeds ~10 tasks or one page, split it or simplify — a bloated plan is a failed plan.
+- **Plan only.** Do not write implementation code; produce the plan and hand off to `/code`.
+- **Ground in the repo.** Detect the real stack and conventions; don't assume a framework or language version.

package/bin/cli.js

@@ -29,8 +29,9 @@ if (command === 'init') {
 
   console.log('Initializing agents-maker...');
 
-  // Copy agent/skill/tool directories wholesale
-  ['agents', 'skills', 'tools', 'context_loaders', 'token_optimization'].forEach(dir => {
+  // Copy agent/skill/tool + docs directories wholesale
+  ['agents', 'skills', 'tools', 'context_loaders', 'token_optimization',
+   'platforms', 'docs', 'examples'].forEach(dir => {
     const src = path.join(kitRoot, dir);
     if (fs.existsSync(src)) copyDir(src, path.join(dest, dir));
   });
@@ -44,8 +45,9 @@ if (command === 'init') {
     if (fs.existsSync(src)) fs.copyFileSync(src, path.join(configDst, f));
   });
 
-  // Copy root scripts and requirements
-  ['quickstart.sh', 'quickstart.ps1', 'requirements.txt'].forEach(f => {
+  // Copy root scripts, requirements, and the paste-only docs (PROMPT_TEMPLATE
+  // powers the zero-Python workflow the README advertises).
+  ['quickstart.sh', 'quickstart.ps1', 'requirements.txt', 'PROMPT_TEMPLATE.md', 'README.md'].forEach(f => {
     const src = path.join(kitRoot, f);
     if (fs.existsSync(src)) fs.copyFileSync(src, path.join(dest, f));
   });
@@ -53,8 +55,18 @@ if (command === 'init') {
   // Make shell script executable on Unix
   try { fs.chmodSync(path.join(dest, 'quickstart.sh'), 0o755); } catch (_) {}
 
+  // Install Claude Code subagents + slash commands into the project-root .claude/
+  // so `/brain`, `/planpro`, `/code`, … are usable immediately. Non-destructive:
+  // never overwrite a file the user already has.
+  const commands = installClaude(path.join(kitRoot, 'claude'), path.join(process.cwd(), '.claude'));
+
   console.log('');
   console.log('✓ agents-maker/ ready');
+  if (commands.length) {
+    console.log('✓ .claude/ agents + commands installed');
+    console.log('');
+    console.log('  Slash commands: ' + commands.map(c => '/' + c).join('  '));
+  }
   console.log('');
   console.log('Next — run from your project root:');
   console.log('  macOS / Linux / WSL:  bash agents-maker/quickstart.sh');
@@ -77,3 +89,27 @@ function copyDir(src, dst) {
     else fs.copyFileSync(s, d);
   }
 }
+
+// Merge claude/{agents,commands}/*.md into <project>/.claude/, skipping any file
+// that already exists (so we never clobber the user's own agents/commands).
+// Returns the list of command names now available.
+function installClaude(templateRoot, claudeRoot) {
+  if (!fs.existsSync(templateRoot)) return [];
+  const commands = [];
+  for (const sub of ['agents', 'commands']) {
+    const srcDir = path.join(templateRoot, sub);
+    if (!fs.existsSync(srcDir)) continue;
+    const dstDir = path.join(claudeRoot, sub);
+    fs.mkdirSync(dstDir, { recursive: true });
+    for (const entry of fs.readdirSync(srcDir)) {
+      const dstFile = path.join(dstDir, entry);
+      if (fs.existsSync(dstFile)) {
+        console.log(`  (kept existing .claude/${sub}/${entry})`);
+        continue;
+      }
+      fs.copyFileSync(path.join(srcDir, entry), dstFile);
+      if (sub === 'commands' && entry.endsWith('.md')) commands.push(entry.replace(/\.md$/, ''));
+    }
+  }
+  return commands;
+}