@patricksardinha/agentkit-cli 0.1.0 → 0.2.0

package/AGENT_WORKFLOW.md

@@ -1,55 +1,55 @@
-# Agent Workflow — AgentKit CLI
-
-## Vue d'ensemble
-Ce projet est construit par 4 agents spécialisés en séquence.
-Chaque agent a un périmètre strict, des inputs définis, et un
-critère de succès vérifiable avant de passer au suivant.
-
-## Phase 1 — Foundation
-
-### Agent 1 · Infra & Setup
-Périmètre : scaffolding du projet Node.js/TS, configuration build
-Lit      : CLAUDE.md section Stack
-Produit  :
-  - package.json (commander, inquirer, chalk, ora, tsup)
-  - tsconfig.json + tsup.config.ts
-  - .github/workflows/release.yml (npm publish on v*)
-  - vitest.config.ts
-  - src/utils/logger.ts
-Critère  : npm run build passe, structure src/ conforme à CLAUDE.md
-
-### Agent 2 · Detectors
-Dépend de : Agent 1
-Périmètre : détection automatique de la stack d'un projet cible
-Produit  :
-  - src/detectors/stackDetector.ts
-    → détecte : React, Next.js, Tauri, Python/FastAPI, Node/Express
-    → lit package.json, requirements.txt, src-tauri/
-  - src/detectors/gitDetector.ts
-    → vérifie si le dossier est un repo git
-  - tests/detectors/stackDetector.test.ts
-Critère  : npm test passe sur des fixtures de projets types
-
-## Phase 2 — Generators (parallélisables)
-
-### Agent 3 · Generators
-Dépend de : Agent 2 (pour stackDetector)
-Périmètre : génération des fichiers CLAUDE.md et AGENT_WORKFLOW.md
-Produit  :
-  - src/generators/claudeMdGenerator.ts
-    → prend StackInfo, retourne string CLAUDE.md adapté
-  - src/generators/workflowGenerator.ts
-    → prend StackInfo, retourne string AGENT_WORKFLOW.md adapté
-  - src/templates/ (un template par stack détectée)
-  - tests/generators/*.test.ts
-Critère  : génère des fichiers valides pour chaque stack supportée
-
-### Agent 4 · Commands CLI
-Dépend de : Agent 2 + Agent 3
-Périmètre : wiring des commandes CLI avec commander.js
-Produit  :
-  - src/commands/init.ts   → npx agentkit init
-  - src/commands/add.ts    → npx agentkit add agent
-  - src/commands/status.ts → npx agentkit status
-  - src/cli.ts             → entry point
+# Agent Workflow — AgentKit CLI
+
+## Vue d'ensemble
+Ce projet est construit par 4 agents spécialisés en séquence.
+Chaque agent a un périmètre strict, des inputs définis, et un
+critère de succès vérifiable avant de passer au suivant.
+
+## Phase 1 — Foundation
+
+### Agent 1 · Infra & Setup
+Périmètre : scaffolding du projet Node.js/TS, configuration build
+Lit      : CLAUDE.md section Stack
+Produit  :
+  - package.json (commander, inquirer, chalk, ora, tsup)
+  - tsconfig.json + tsup.config.ts
+  - .github/workflows/release.yml (npm publish on v*)
+  - vitest.config.ts
+  - src/utils/logger.ts
+Critère  : npm run build passe, structure src/ conforme à CLAUDE.md
+
+### Agent 2 · Detectors
+Dépend de : Agent 1
+Périmètre : détection automatique de la stack d'un projet cible
+Produit  :
+  - src/detectors/stackDetector.ts
+    → détecte : React, Next.js, Tauri, Python/FastAPI, Node/Express
+    → lit package.json, requirements.txt, src-tauri/
+  - src/detectors/gitDetector.ts
+    → vérifie si le dossier est un repo git
+  - tests/detectors/stackDetector.test.ts
+Critère  : npm test passe sur des fixtures de projets types
+
+## Phase 2 — Generators (parallélisables)
+
+### Agent 3 · Generators
+Dépend de : Agent 2 (pour stackDetector)
+Périmètre : génération des fichiers CLAUDE.md et AGENT_WORKFLOW.md
+Produit  :
+  - src/generators/claudeMdGenerator.ts
+    → prend StackInfo, retourne string CLAUDE.md adapté
+  - src/generators/workflowGenerator.ts
+    → prend StackInfo, retourne string AGENT_WORKFLOW.md adapté
+  - src/templates/ (un template par stack détectée)
+  - tests/generators/*.test.ts
+Critère  : génère des fichiers valides pour chaque stack supportée
+
+### Agent 4 · Commands CLI
+Dépend de : Agent 2 + Agent 3
+Périmètre : wiring des commandes CLI avec commander.js
+Produit  :
+  - src/commands/init.ts   → npx agentkit init
+  - src/commands/add.ts    → npx agentkit add agent
+  - src/commands/status.ts → npx agentkit status
+  - src/cli.ts             → entry point
 Critère  : npx agentkit --help affiche toutes les commandes

package/CLAUDE.md

@@ -1,45 +1,45 @@
-# CLAUDE.md — AgentKit CLI
-
-## Rôle de ce fichier
-Ce fichier est lu par tous les agents Claude Code avant toute action.
-Il définit les conventions, la stack, et les règles du projet.
-
-## Projet
-Nom        : agentkit-cli
-Type        : CLI npm open-source (Node.js + TypeScript)
-Objectif    : Scaffolder des workflows multi-agents Claude Code
-Public      : Développeurs fullstack qui utilisent Claude Code
-Registry    : npm (npx agentkit init)
-
-## Stack
-- Runtime    : Node.js 20+, TypeScript 5
-- CLI        : commander.js + inquirer.js + chalk + ora
-- Build      : tsup (ESM + CJS dual output)
-- Tests      : Vitest
-- CI/CD      : GitHub Actions → npm publish on tag v*
-
-## Structure des fichiers
-src/
-  cli.ts          ← entry point (commander setup)
-  commands/       ← une commande = un fichier
-  generators/     ← logique de génération des fichiers
-  detectors/      ← détection de stack (package.json, etc.)
-  templates/      ← templates CLAUDE.md, AGENT_WORKFLOW.md
-  utils/          ← helpers partagés
-tests/            ← Vitest, miroir de src/
-
-## Règles absolues
-1. Chaque commande dans src/commands/ est indépendante
-2. Les templates dans src/templates/ sont des fonctions TS, pas des fichiers .md statiques
-3. Tout output CLI passe par src/utils/logger.ts (jamais console.log direct)
-4. Chaque fichier généré doit avoir un test dans tests/generators/
-5. Zéro dépendance non listée ici sans discussion
-
-## Conventions de commit
-feat: / fix: / test: / docs: / chore: / release:
-
-## Critères de succès (Definition of Done)
-- npx agentkit init fonctionne sur un repo vide
-- npx agentkit init détecte automatiquement React, Next.js, Tauri, Python
-- npm test passe sans erreur
+# CLAUDE.md — AgentKit CLI
+
+## Rôle de ce fichier
+Ce fichier est lu par tous les agents Claude Code avant toute action.
+Il définit les conventions, la stack, et les règles du projet.
+
+## Projet
+Nom        : agentkit-cli
+Type        : CLI npm open-source (Node.js + TypeScript)
+Objectif    : Scaffolder des workflows multi-agents Claude Code
+Public      : Développeurs fullstack qui utilisent Claude Code
+Registry    : npm (npx agentkit init)
+
+## Stack
+- Runtime    : Node.js 20+, TypeScript 5
+- CLI        : commander.js + inquirer.js + chalk + ora
+- Build      : tsup (ESM + CJS dual output)
+- Tests      : Vitest
+- CI/CD      : GitHub Actions → npm publish on tag v*
+
+## Structure des fichiers
+src/
+  cli.ts          ← entry point (commander setup)
+  commands/       ← une commande = un fichier
+  generators/     ← logique de génération des fichiers
+  detectors/      ← détection de stack (package.json, etc.)
+  templates/      ← templates CLAUDE.md, AGENT_WORKFLOW.md
+  utils/          ← helpers partagés
+tests/            ← Vitest, miroir de src/
+
+## Règles absolues
+1. Chaque commande dans src/commands/ est indépendante
+2. Les templates dans src/templates/ sont des fonctions TS, pas des fichiers .md statiques
+3. Tout output CLI passe par src/utils/logger.ts (jamais console.log direct)
+4. Chaque fichier généré doit avoir un test dans tests/generators/
+5. Zéro dépendance non listée ici sans discussion
+
+## Conventions de commit
+feat: / fix: / test: / docs: / chore: / release:
+
+## Critères de succès (Definition of Done)
+- npx agentkit init fonctionne sur un repo vide
+- npx agentkit init détecte automatiquement React, Next.js, Tauri, Python
+- npm test passe sans erreur
 - npx tsc --noEmit passe sans erreur

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Patrick Sardinha
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,327 +1,354 @@
-# AgentKit CLI
-
-> Bootstrap your projects with an AI-native orchestration layer — like `create vite@latest`, but for agentic development with Claude Code.
-
-[![npm version](https://img.shields.io/npm/v/agentkit-cli)](https://www.npmjs.com/package/agentkit-cli)
-[![license](https://img.shields.io/npm/l/agentkit-cli)](./LICENSE)
-[![built with Claude Code](https://img.shields.io/badge/built%20with-Claude%20Code-7c3aed)](https://claude.ai/code)
-
----
-
-## What is AgentKit?
-
-When you run `npm create vite@latest`, it scaffolds a complete React (or Vue, Svelte…) project in seconds — giving you a working structure you can build on immediately instead of configuring everything from scratch.
-
-**AgentKit does the same thing, but for AI-native development.**
-
-It scaffolds the *orchestration layer* that sits on top of any project: the files that tell Claude Code **who** to be, **what** to build, and **how** to divide the work across specialized agents.
-
-```
-Without AgentKit                 With AgentKit
-────────────────                 ──────────────────────────────
-my-project/                      my-project/
-├── src/                         ├── src/
-├── package.json                 ├── package.json
-└── README.md                    ├── README.md
-                                 ├── CLAUDE.md          ← generated
-                                 └── AGENT_WORKFLOW.md  ← generated
-```
-
-You open Claude Code, and instead of spending the first 30 minutes explaining your stack and conventions, you just say: **"Read CLAUDE.md and AGENT_WORKFLOW.md, then run Agent 1."**
-
----
-
-## The Problem It Solves
-
-Most developers using Claude Code today work with a single, long-running conversation. They describe what they want, Claude builds it, they correct, they prompt again. This works — but it has limits:
-
-- **Context gets polluted** — one agent accumulates unrelated concerns
-- **No reusability** — you re-explain conventions on every project
-- **No parallelism** — everything is sequential because there's no coordination layer
-- **No audit trail** — no document captures the decisions made
-
-AgentKit introduces a **structured orchestration layer** that solves all four problems. Your project gets two new files — `CLAUDE.md` and `AGENT_WORKFLOW.md` — that act as standing instructions for a team of specialized agents.
-
----
-
-## How It Works
-
-```
-┌─────────────────────────────────────────────────────────────────┐
-│  Developer runs: npx agentkit init                              │
-└─────────────────────────┬───────────────────────────────────────┘
-                          │
-                          ▼
-┌─────────────────────────────────────────────────────────────────┐
-│  AgentKit CLI                                                   │
-│                                                                 │
-│  1. Scans the project directory                                 │
-│     → reads package.json, Cargo.toml, requirements.txt…         │
-│                                                                 │
-│  2. Detects the stack                                           │
-│     → React · Next.js · Tauri · FastAPI · Express · Node        │
-│     → TypeScript? Tailwind? Prisma? Testing setup?              │
-│                                                                 │
-│  3. Generates adapted files                                     │
-│     → CLAUDE.md    (conventions, stack, commands, rules)        │
-│     → AGENT_WORKFLOW.md  (agents, scope, success criteria)      │
-└─────────────────────────┬───────────────────────────────────────┘
-                          │
-                          ▼
-┌─────────────────────────────────────────────────────────────────┐
-│  Your project — ready for agentic development                   │
-│                                                                 │
-│  Developer opens Claude Code and runs agents one by one:        │
-│                                                                 │
-│  Agent 1 → Infra & Setup     (success: project builds)          │
-│      ↓                                                          │
-│  Agent 2 → Core Feature A    (success: tests pass)              │
-│      ↓                                                          │
-│  Agent 3 → Core Feature B    (success: tests pass)              │
-│      ↓                                                          │
-│  Agent 4 → Docs & Deploy     (success: CI/CD green)             │
-│                                                                 │
-│  Human validates each success criterion before the next agent.  │
-└─────────────────────────────────────────────────────────────────┘
-```
-
-### The two generated files
-
-**`CLAUDE.md`** — the standing brief for every agent. It answers:
-- What is this project and what stack does it use?
-- What are the absolute rules (naming conventions, forbidden patterns, testing requirements)?
-- What commands exist and what do they do?
-- What does "done" look like?
-
-**`AGENT_WORKFLOW.md`** — the project roadmap, broken into agent-sized tasks. Each agent entry specifies:
-- Its scope (what it touches)
-- Its dependencies (which agent must finish first)
-- Its deliverables (what files it produces)
-- Its success criterion (a verifiable, runnable check)
-
----
-
-## Quickstart
-
-```bash
-# In any project directory (empty or existing)
-npx agentkit init
-```
-
-That's it. AgentKit detects your stack and writes the two files.
-
-```bash
-# Add a new specialized agent to an existing workflow
-npx agentkit add agent
-
-# Check the status of your agent workflow
-npx agentkit status
-```
-
----
-
-## Supported Stacks
-
-| Stack | Detected by | Template features |
-|---|---|---|
-| **React** | `react` in `package.json` | TypeScript/JS, Vite, testing setup |
-| **Next.js** | `next` in `package.json` | App Router, Tailwind, Prisma (if present) |
-| **Tauri** | `src-tauri/` directory | Rust backend, IPC commands, Tauri plugins |
-| **FastAPI** | `fastapi` in `requirements.txt` | Python, Pydantic, async patterns |
-| **Express** | `express` in `package.json` | REST API, middleware, auth patterns |
-| **Node.js** | `package.json` (generic) | Scripts, modules, CI/CD |
-| **Unknown** | fallback | Generic workflow, manually editable |
-
-Stack detection is additive — extras like TypeScript, Tailwind, and Prisma are detected on top of the primary framework and enrich the generated templates accordingly.
-
----
-
-## Example Output
-
-### For a React + TypeScript project
-
-`npx agentkit init` in a React/TypeScript/Vite project generates:
-
-```markdown
-# CLAUDE.md — my-app
-
-## Stack
-- Framework : React (TypeScript)
-- Language  : TypeScript
-- Build     : Vite
-
-## Commands
-- `npm run dev`    — development server
-- `npm run build`  — production build
-- `npm test`       — run tests
-
-## Structure
-src/
-  components/   ← UI components (PascalCase)
-  hooks/        ← custom hooks (prefix: use*)
-  pages/        ← page-level components
-  utils/        ← shared helpers
-
-## Conventions
-1. Components in PascalCase
-2. Hooks prefixed with `use`
-3. Props interfaces named `*Props`
-4. All console output through a centralized logger
-```
-
-```markdown
-# Agent Workflow — my-app
-
-## Agents
-
-### Agent 1 · Components
-Scope    : reusable UI components
-Delivers : src/components/
-Criteria : components documented and tested
-
-### Agent 2 · State & Hooks
-Scope    : state management, custom hooks
-Delivers : src/hooks/
-Criteria : hooks unit-tested
-
-### Agent 3 · Pages & Routing
-Scope    : page assembly, react-router
-Delivers : src/pages/
-Criteria : navigation working
-
-### Agent 4 · Tests & CI
-Scope    : test coverage, CI configuration
-Delivers : tests/, .github/workflows/
-Criteria : npm test passes
-```
-
-### For a Tauri project (more complex detection)
-
-A project with `src-tauri/` gets a richer workflow that accounts for the Rust/JS boundary, IPC commands, plugin permissions, and the dual build system:
-
-```markdown
-# Agent Workflow — my-desktop-app
-
-### Agent 1 · Rust Commands
-Scope    : Tauri commands (IPC), permissions
-Delivers : src-tauri/src/commands.rs, tauri.conf.json
-Criteria : `cargo build` passes
-
-### Agent 2 · Frontend UI
-Scope    : TypeScript UI, IPC integration
-Delivers : src/components/, src/utils/
-Criteria : IPC calls functional
-
-### Agent 3 · Build & Packaging
-Scope    : build config, icons, installers
-Delivers : src-tauri/tauri.conf.json, icons/
-Criteria : `npm run tauri build` produces a bundle
-
-### Agent 4 · Tests
-Scope    : Rust tests + frontend tests
-Delivers : src-tauri/tests/, tests/
-Criteria : `cargo test` + `npm test` pass
-```
-
----
-
-## Design Philosophy
-
-### Why not just use a prompt template?
-
-A prompt template lives in your head (or your notes). It gets copy-pasted, drifts between projects, and is lost the moment you close the conversation.
-
-`CLAUDE.md` and `AGENT_WORKFLOW.md` are **project artifacts**. They live in the repo, they're versioned, they're readable by every agent in every session, and they can be reviewed in a pull request like any other code.
-
-### Why separate agents instead of one big conversation?
-
-Each agent has a **bounded context** — it only knows what it needs to know. This has three effects:
-
-1. **Better output** — an agent focused solely on testing isn't distracted by infrastructure concerns
-2. **Human checkpoints** — you validate a success criterion before the next agent starts, catching errors early
-3. **Parallelism** — once dependencies are met, agents that don't depend on each other can run simultaneously
-
-### Why verifiable success criteria?
-
-Every agent in `AGENT_WORKFLOW.md` ends with a criterion like `npm test passes` or `cargo build passes`. These aren't goals — they're **gates**. If the criterion isn't met, you don't prompt the next agent. This makes the workflow deterministic and auditable.
-
----
-
-## Meta: How AgentKit Was Built
-
-AgentKit CLI was built using the same workflow it generates.
-
-The repo contains a `CLAUDE.md` and `AGENT_WORKFLOW.md` that describe how to build the CLI itself. Four specialized agents were used in sequence:
-
-```
-Agent 1 · Infra & Setup
-  → package.json, tsconfig, tsup, vitest, GitHub Actions
-  → success: npm run build passes
-
-Agent 2 · Detectors
-  → src/detectors/stackDetector.ts, gitDetector.ts
-  → success: npm test passes on project fixtures
-
-Agent 3 · Generators & Templates
-  → src/generators/, src/templates/ (one per stack)
-  → success: valid files generated for each supported stack
-
-Agent 4 · Commands CLI
-  → src/commands/init.ts, add.ts, status.ts, src/cli.ts
-  → success: npx agentkit --help shows all commands
-```
-
-The `CLAUDE.md` and `AGENT_WORKFLOW.md` at the root of this repo are the exact files that drove this build process. They are not documentation added after the fact — they are the source of truth that was written first and executed against.
-
----
-
-## Project Structure
-
-```
-agentkit-cli/
-├── src/
-│   ├── cli.ts                  ← entry point (commander.js)
-│   ├── commands/
-│   │   ├── init.ts             ← npx agentkit init
-│   │   ├── add.ts              ← npx agentkit add agent
-│   │   └── status.ts           ← npx agentkit status
-│   ├── detectors/
-│   │   ├── stackDetector.ts    ← reads package.json, Cargo.toml, etc.
-│   │   └── gitDetector.ts      ← checks for .git directory
-│   ├── generators/
-│   │   ├── claudeMdGenerator.ts   ← routes to the right template
-│   │   └── workflowGenerator.ts   ← routes to the right template
-│   ├── templates/
-│   │   ├── react.ts            ← React/Vite template
-│   │   ├── nextjs.ts           ← Next.js App Router template
-│   │   ├── tauri.ts            ← Tauri v2 template
-│   │   ├── fastapi.ts          ← FastAPI template
-│   │   ├── express.ts          ← Express.js template
-│   │   ├── node.ts             ← generic Node.js template
-│   │   └── unknown.ts          ← fallback for unknown stacks
-│   └── utils/
-│       └── logger.ts           ← chalk + ora output helpers
-├── tests/
-├── CLAUDE.md                   ← agent brief for this repo
-├── AGENT_WORKFLOW.md           ← agent workflow for this repo
-├── package.json
-├── tsconfig.json
-└── tsup.config.ts
-```
-
----
-
-## Contributing
-
-Pull requests are welcome. If you add a new stack template:
-
-1. Create `src/templates/your-stack.ts` — export `claudeMd(stack)` and `workflow(stack)`
-2. Add detection logic in `src/detectors/stackDetector.ts`
-3. Register the new case in `src/generators/claudeMdGenerator.ts` and `workflowGenerator.ts`
-4. Add fixtures in `tests/detectors/` and tests in `tests/generators/`
-
----
-
-## License
-
-MIT — © 2026
+# @patricksardinha/agentkit-cli
+
+> Bootstrap any project with an AI-native orchestration layer — like `create vite@latest`, but for agentic development with Claude Code.
+
+[![npm version](https://img.shields.io/npm/v/@patricksardinha/agentkit-cli)](https://www.npmjs.com/package/@patricksardinha/agentkit-cli)
+[![license](https://img.shields.io/npm/l/@patricksardinha/agentkit-cli)](./LICENSE)
+[![built with Claude Code](https://img.shields.io/badge/built%20with-Claude%20Code-7c3aed)](https://claude.ai/code)
+
+---
+
+## What is AgentKit?
+
+When you run `npm create vite@latest`, it scaffolds a complete React project in seconds — giving you a working structure you can build on immediately instead of configuring everything from scratch.
+
+**AgentKit does the same thing, but for AI-native development.**
+
+It scaffolds the *orchestration layer* that sits on top of any project: the files that tell Claude Code **who** to be, **what** to build, **how** to divide the work across specialized agents, and **exactly what to do** — step by step, without you having to prompt each agent manually.
+
+```
+Without AgentKit                 With AgentKit
+────────────────                 ──────────────────────────────
+my-project/                      my-project/
+├── src/                         ├── src/
+├── package.json                 ├── package.json
+└── README.md                    ├── README.md
+                                 ├── CLAUDE.md             ← agent brief
+                                 ├── AGENT_WORKFLOW.md     ← roadmap
+                                 ├── PLAYBOOK.md           ← execution guide
+                                 └── agents/               ← per-agent skills
+                                     ├── agent-1-infra/
+                                     ├── agent-2-auth/
+                                     └── agent-3-features/
+```
+
+You open Claude Code, type one instruction, and it runs the entire workflow autonomously.
+
+---
+
+## The Problem It Solves
+
+Most developers using Claude Code today work with a single, long-running conversation. They describe what they want, Claude builds it, they correct, they prompt again. This works — but it has limits:
+
+- **Context gets polluted** — one agent accumulates unrelated concerns
+- **No reusability** — you re-explain conventions on every project
+- **No parallelism** — everything is sequential without a coordination layer
+- **No audit trail** — no document captures decisions made
+- **Manual orchestration** — you have to manage agent transitions yourself
+
+AgentKit introduces a **structured orchestration layer** that solves all five problems.
+
+---
+
+## How It Works
+
+```
+┌─────────────────────────────────────────────────────────────────┐
+│  Step 1 — You run: npx agentkit init --blueprint BLUEPRINT.md   │
+└─────────────────────────┬───────────────────────────────────────┘
+                          │
+                          ▼
+┌─────────────────────────────────────────────────────────────────┐
+│  AgentKit CLI                                                   │
+│                                                                 │
+│  1. Scans the project directory                                 │
+│     → reads package.json, Cargo.toml, requirements.txt…         │
+│                                                                 │
+│  2. Detects the stack                                           │
+│     → React · Next.js · Tauri · FastAPI · Express · Node        │
+│     → TypeScript? Tailwind? Prisma? Testing setup?              │
+│                                                                 │
+│  3. Reads your blueprint (optional)                             │
+│     → parses features, requirements, architecture notes         │
+│     → generates agents tailored to YOUR features                │
+│                                                                 │
+│  4. Generates the orchestration layer                           │
+│     → CLAUDE.md           (conventions, stack, rules)           │
+│     → AGENT_WORKFLOW.md   (agents, scope, dependencies)         │
+│     → PLAYBOOK.md         (autonomous execution guide)          │
+│     → agents/agent-N-*/   (per-agent skills folders)            │
+└─────────────────────────┬───────────────────────────────────────┘
+                          │
+                          ▼
+┌─────────────────────────────────────────────────────────────────┐
+│  Step 2 — You open Claude Code and type ONE instruction:        │
+│                                                                 │
+│  "Read PLAYBOOK.md and execute the procedure."                  │
+│                                                                 │
+│  Claude Code then runs autonomously:                            │
+│                                                                 │
+│  Agent 1 → Infra & Setup                                        │
+│    runs: npm run build                                          │
+│    ✅ passes → moves to Agent 2                                │
+│    ❌ fails  → analyzes error, fixes, retries (max 3x)         │
+│      ↓                                                          │
+│  Agent 2 → Auth & Data Layer                                    │
+│    runs: npm test                                               │
+│    ✅ passes → moves to Agent 3                                │
+│      ↓                                                          │
+│  Agent 3 → Features                                             │
+│    runs: npm test                                               │
+│    ✅ passes → moves to Agent 4                                │
+│      ↓                                                          │
+│  Agent 4 → Docs & Deploy                                        │
+│    ✅ 🎉 Workflow complete                                     │
+└─────────────────────────────────────────────────────────────────┘
+```
+
+### The generated files
+
+**`CLAUDE.md`** — the standing brief for every agent. Covers stack, conventions, forbidden patterns, commands, and definition of done. Read by every agent at the start of their session.
+
+**`AGENT_WORKFLOW.md`** — the project roadmap broken into agent-sized tasks. Each entry specifies scope, dependencies, deliverables, and a verifiable success criterion.
+
+**`PLAYBOOK.md`** — the key innovation. A single file that Claude Code reads and executes as a complete autonomous workflow. Includes agent prompts, success criteria, retry logic, correction instructions, and human escalation rules. You don't manage agent transitions — Claude Code does.
+
+**`agents/agent-N-slug/`** — per-agent skill folders. Drop any `.md` files here (API docs, DB schemas, business conventions) and the relevant agent will read them before starting its work.
+
+---
+
+## Quickstart
+
+```bash
+# In any project directory
+npx @patricksardinha/agentkit-cli init
+
+# With a blueprint for feature-specific agents
+npx @patricksardinha/agentkit-cli init --blueprint PROJECT_BLUEPRINT.md
+
+# Add a new feature to an existing project
+npx @patricksardinha/agentkit-cli add --feature "add PDF export system"
+
+# Check workflow status
+npx @patricksardinha/agentkit-cli status
+```
+
+Then open Claude Code and type:
+```
+Read PLAYBOOK.md and execute the procedure.
+```
+
+---
+
+## The Blueprint File
+
+The `--blueprint` flag transforms AgentKit from a generic scaffold tool into a project-specific orchestrator.
+
+Without a blueprint, AgentKit generates standard agents based on your stack (Components, Hooks, Pages, Tests for React). With a blueprint, it reads your feature requirements and generates agents tailored to exactly what you want to build.
+
+**Example `PROJECT_BLUEPRINT.md`:**
+
+```markdown
+# My App — Blueprint
+
+## Features
+- Email/password authentication with Supabase
+- Dashboard with D3 charts (revenue, users, conversion)
+- PDF export of reports
+- Dark/light theme
+
+## Tech constraints
+- Must work offline (IndexedDB for local data)
+- Tauri desktop build for Windows
+- French and English i18n
+
+## Architecture notes
+- Supabase for auth + reference data
+- Dexie for local user data
+- No Redux — Context API only
+```
+
+**What AgentKit generates from this blueprint:**
+
+```markdown
+## Agent 1 · Infra & Tauri Setup
+Scope    : Vite + React + Tauri + Tailwind, i18n config
+Criteria : npm run dev opens without error
+
+## Agent 2 · Auth & Supabase
+Scope    : Supabase client, email/password auth, bypass mode
+Criteria : login/logout functional, npm test passes
+
+## Agent 3 · Local Data Layer
+Scope    : Dexie schema, sync service, offline support
+Criteria : useLiveQuery returns data, npm test passes
+
+## Agent 4 · Dashboard & D3 Charts
+Scope    : chart components, data hooks, mock data
+Criteria : charts render, npm test passes
+
+## Agent 5 · PDF Export
+Scope    : PDF generation from dashboard data
+Criteria : export produces valid PDF, npm test passes
+
+## Agent 6 · Desktop & CI/CD
+Scope    : Tauri build, GitHub Actions, release workflow
+Criteria : npm run tauri:build produces installer
+```
+
+---
+
+## Per-Agent Skills
+
+Each agent gets its own folder under `agents/`. Drop any `.md` files there — API documentation, database schemas, business conventions, examples — and the agent reads them before starting.
+
+```
+agents/
+├── agent-2-auth/
+│   ├── skills.md              ← auto-generated template
+│   └── supabase-schema.md     ← you add this: your actual DB schema
+├── agent-4-dashboard/
+│   ├── skills.md
+│   └── chart-specs.md         ← you add this: exact chart requirements
+```
+
+The `skills.md` template generated by AgentKit:
+
+```markdown
+# Skills — Agent 2 · Auth & Supabase
+
+> This file is read by Agent 2 before starting its work.
+> Fill in what's relevant for your project.
+
+## Technical context (fill in)
+- Supabase URL      :
+- Tables involved   :
+- Expected RLS      :
+
+## Reference documentation (optional)
+<!-- paste API docs, schemas, examples here -->
+
+## Project-specific conventions (optional)
+<!-- e.g. "always use useSession(), never useUser()" -->
+```
+
+---
+
+## Handling Future Iterations
+
+When you want to add a feature to an already-built project:
+
+```bash
+npx @patricksardinha/agentkit-cli add --feature "add CSV export to the dashboard"
+```
+
+AgentKit:
+1. Reads your existing `AGENT_WORKFLOW.md` to find the last agent number
+2. Appends a new agent block scoped to the new feature
+3. Creates `agents/agent-N-csv-export/skills.md`
+4. Regenerates `PLAYBOOK.md` with the new agent included
+
+Then in Claude Code:
+```
+Read PLAYBOOK.md and execute only the agents that haven't been completed yet.
+```
+
+---
+
+## Supported Stacks
+
+| Stack | Detected by | Template enrichment |
+|---|---|---|
+| **React** | `react` in `package.json` | TypeScript/JS, Vite, testing |
+| **Next.js** | `next` in `package.json` | App Router, Tailwind, Prisma |
+| **Tauri** | `src-tauri/` directory | Rust/JS boundary, IPC, plugins |
+| **FastAPI** | `fastapi` in `requirements.txt` | Python, Pydantic, async |
+| **Express** | `express` in `package.json` | REST, middleware, auth |
+| **Node.js** | `package.json` (generic) | Scripts, modules, CI/CD |
+| **Unknown** | fallback | Generic editable workflow |
+
+Stack detection is additive — TypeScript, Tailwind, Prisma, and testing setup are detected on top of the primary framework and enrich all generated files accordingly.
+
+---
+
+## Design Philosophy
+
+### Why a PLAYBOOK.md instead of manual prompting?
+
+Without AgentKit, a developer using Claude Code has to write a prompt for Agent 1, wait and validate, write a prompt for Agent 2, handle failures manually, and repeat for every agent. With `PLAYBOOK.md`, you write one instruction. Claude Code handles agent transitions, validates success criteria, retries on failure, and asks for human input only when genuinely blocked.
+
+### Why per-agent skills instead of one big context?
+
+Each agent should only know what it needs. An infrastructure agent doesn't need your business logic conventions. A features agent doesn't need your CI/CD configuration. Bounded context produces better output and prevents agents from making decisions outside their scope.
+
+### Why verifiable success criteria?
+
+Every agent ends with a runnable check (`npm test`, `cargo build`, `npm run build`). These aren't goals — they're gates. The PLAYBOOK enforces them. You always know exactly which agents have succeeded and which haven't.
+
+---
+
+## Meta: AgentKit Was Built With AgentKit
+
+This CLI was built using the exact workflow it generates. The `CLAUDE.md`, `AGENT_WORKFLOW.md`, and `PLAYBOOK.md` at the root of this repo drove the entire build process — written first, executed against, not added after the fact.
+
+```
+Agent 1 · Infra & Setup       → success: npm run build passes
+Agent 2 · Detectors           → success: npm test passes on fixtures
+Agent 3 · Generators          → success: valid files for each stack
+Agent 4 · Commands CLI        → success: npx agentkit --help works
+```
+
+---
+
+## Project Structure
+
+```
+agentkit-cli/
+├── src/
+│   ├── cli.ts
+│   ├── commands/
+│   │   ├── init.ts              ← npx agentkit init [--blueprint]
+│   │   ├── add.ts               ← npx agentkit add --feature
+│   │   └── status.ts            ← npx agentkit status
+│   ├── detectors/
+│   │   ├── stackDetector.ts
+│   │   └── gitDetector.ts
+│   ├── generators/
+│   │   ├── claudeMdGenerator.ts
+│   │   ├── workflowGenerator.ts
+│   │   ├── playbookGenerator.ts ← PLAYBOOK.md with full exec logic
+│   │   └── skillsGenerator.ts   ← agents/agent-N-slug/ folders
+│   ├── templates/
+│   │   ├── react.ts
+│   │   ├── nextjs.ts
+│   │   ├── tauri.ts
+│   │   ├── fastapi.ts
+│   │   ├── express.ts
+│   │   ├── node.ts
+│   │   └── unknown.ts
+│   └── utils/
+│       └── logger.ts
+├── tests/
+├── CLAUDE.md
+├── AGENT_WORKFLOW.md
+├── PLAYBOOK.md
+├── package.json
+└── tsup.config.ts
+```
+
+---
+
+## Contributing
+
+To add a new stack template:
+
+1. Create `src/templates/your-stack.ts` — export `claudeMd(stack)` and `workflow(stack)`
+2. Add detection in `src/detectors/stackDetector.ts`
+3. Register in both generators
+4. Add fixtures in `tests/detectors/` and tests in `tests/generators/`
+
+---
+
+## License
+
+MIT — © 2026 Patrick Sardinha

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@patricksardinha/agentkit-cli",
-  "version": "0.1.0",
+  "version": "0.2.0",
   "publishConfig": {
     "access": "public"
   },