@patricksardinha/agentkit-cli 0.2.0 → 0.4.0

package/README.md

@@ -16,24 +16,39 @@ When you run `npm create vite@latest`, it scaffolds a complete React project in
 
 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.
 
+You open Claude Code, type one instruction, and it runs the entire workflow autonomously.
+
+---
+
+## Core Design Principle — No AI Inside the Tool
+
+AgentKit contains **no AI**. No API calls, no LLM integration, no costs, no API key required.
+
+This is a deliberate choice. AgentKit is a **structural tool** — it generates the scaffolding, the rules, and the execution framework. The intelligence comes from two places:
+
+- **You** — you optionally write a `PROJECT_BLUEPRINT.md` describing what you want to build
+- **Claude Code** — it either reads your blueprint or asks you questions, decomposes the project into specialized agents, then executes them in sequence
+
+This separation means AgentKit works with any LLM and never becomes outdated
+as AI models improve. The tool itself costs nothing to run — but be aware:
+
+- **Claude Code or any hosted LLM** requires a paid subscription to the
+  provider (Anthropic, OpenAI, etc.)
+- **Local models via Ollama** are free to run, but require a machine with
+  sufficient RAM and ideally a dedicated GPU — a standard laptop may
+  struggle with larger models
+- **AgentKit itself** has no cost, no API key, and no usage limits
+
 ```
-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 (optionally write a blueprint)
+        ↓
+AgentKit CLI (generates the structure)
+        ↓
+Claude Code (discovers or reads blueprint → decomposes → executes)
+        ↓
+Your finished project
 ```
 
-You open Claude Code, type one instruction, and it runs the entire workflow autonomously.
-
 ---
 
 ## The Problem It Solves
@@ -42,194 +57,177 @@ Most developers using Claude Code today work with a single, long-running convers
 
 - **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
+- **Poor decomposition** — most developers don't know how to split work into optimal agents
 
-AgentKit introduces a **structured orchestration layer** that solves all five problems.
+AgentKit solves all five — including the last one, by always delegating decomposition to Claude Code, whether or not you provide a blueprint.
 
 ---
 
 ## How It Works
 
+AgentKit always runs in two phases inside Claude Code. **Phase 0 always runs first**, regardless of whether you provided a blueprint. The difference is only the *source* of information.
+
+### Without blueprint — Phase 0 asks you
+
+```bash
+npx @patricksardinha/agentkit-cli init
 ```
-┌─────────────────────────────────────────────────────────────────┐
-│  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                                     │
-└─────────────────────────────────────────────────────────────────┘
+
+When Claude Code reads the generated PLAYBOOK, it starts with **Phase 0 — Project Discovery**: it asks you three questions directly in the chat and waits for your answers before decomposing anything.
+
 ```
+Claude Code: "Before I start, I need to understand what you want to build.
 
-### The generated files
+  1. What is this project? (one sentence)
+  2. What are the main features you want to build?
+  3. Any tech constraints or architecture preferences?
 
-**`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.
+Please answer and I'll propose an agent decomposition."
 
-**`AGENT_WORKFLOW.md`** — the project roadmap broken into agent-sized tasks. Each entry specifies scope, dependencies, deliverables, and a verifiable success criterion.
+You: "It's a desktop app where I log my dev sessions.
+      Features: session logging, weekly summaries, natural language search.
+      Constraints: Tauri v2, all local, no cloud, Ollama for AI."
 
-**`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.
+Claude Code: "I've decomposed the project into 5 agents:
+  1. Infra & Tauri Setup
+  2. Data Layer (Dexie)
+  3. Ollama Integration
+  4. RAG & Search
+  5. UI & Features
+Should I proceed?"
 
-**`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.
+You: "Yes."  ← then execution begins
+```
 
----
+### With blueprint — Phase 0 reads your file
 
-## Quickstart
+Write a `PROJECT_BLUEPRINT.md` at the root of your project in plain language — just describe what you want to build. No agents, no structure, no technical layers required.
 
 ```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:
+When Claude Code reads the generated PLAYBOOK, it starts with **Phase 0 — Agent Decomposition**: it reads your blueprint and proposes an agent structure before writing any code.
+
 ```
-Read PLAYBOOK.md and execute the procedure.
+Claude Code: "I've read PROJECT_BLUEPRINT.md and decomposed the project into 5 agents:
+  1. Infra & Tauri Setup
+  2. Data Layer (Dexie)
+  3. Ollama Integration
+  4. RAG & Search
+  5. UI & Features
+Should I proceed?"
+
+You: "Yes."  ← then execution begins
 ```
 
----
-
-## 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`:**
+**A good blueprint looks like this:**
 
 ```markdown
-# My App — Blueprint
+# DevLog Desktop — Blueprint
+
+## Goal
+A desktop app where I log my dev sessions as I work.
+At the end of the week it generates a summary I can paste into my standup.
+I also want to search my history in natural language.
 
 ## Features
-- Email/password authentication with Supabase
-- Dashboard with D3 charts (revenue, users, conversion)
-- PDF export of reports
-- Dark/light theme
+- Create a session: what I worked on, how long, blockers encountered
+- Weekly summary generated automatically from local history
+- Natural language search across all past sessions (RAG)
+- Export summaries as markdown for standups
+- Dark/light theme, minimal UI
 
 ## Tech constraints
-- Must work offline (IndexedDB for local data)
-- Tauri desktop build for Windows
-- French and English i18n
+- Desktop app — Tauri v2 (Windows first)
+- All data stays local — no cloud, no auth required
+- React 19 + TypeScript + Tailwind v4
+- Dexie for local storage (IndexedDB)
+- Ollama for local AI (summaries + embeddings) — no API key
 
 ## Architecture notes
-- Supabase for auth + reference data
-- Dexie for local user data
-- No Redux — Context API only
+- No Supabase — bypass auth entirely
+- RAG: generate embeddings with nomic-embed-text, store in Dexie,
+  search by cosine similarity
+- Export via Tauri fs plugin
 ```
 
-**What AgentKit generates from this blueprint:**
+### Phase 1 — Execution (same in both cases)
 
-```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
+Once you validate the decomposition, Claude Code executes each agent autonomously:
 
-## Agent 3 · Local Data Layer
-Scope    : Dexie schema, sync service, offline support
-Criteria : useLiveQuery returns data, npm test passes
+```
+Agent 1 → Infra & Tauri Setup
+  reads  : CLAUDE.md + agents/agent-1-infra/skills.md
+  runs   : npm run tauri:dev
+  ✅ passes → moves to Agent 2
+  ❌ fails  → analyzes error, fixes, retries (max 3 times)
+              → after 3 failures: asks for human intervention
+    ↓
+Agent 2 → Data Layer (Dexie)
+  reads  : CLAUDE.md + agents/agent-2-data/skills.md
+  runs   : npm test
+  ✅ passes → moves to Agent 3
+    ↓
+...
+    ↓
+Agent N → last agent
+  ✅ 🎉 Workflow complete
+```
 
-## Agent 4 · Dashboard & D3 Charts
-Scope    : chart components, data hooks, mock data
-Criteria : charts render, npm test passes
+### The one instruction
 
-## Agent 5 · PDF Export
-Scope    : PDF generation from dashboard data
-Criteria : export produces valid PDF, npm test passes
+In both cases, the instruction to give Claude Code is identical:
 
-## Agent 6 · Desktop & CI/CD
-Scope    : Tauri build, GitHub Actions, release workflow
-Criteria : npm run tauri:build produces installer
+```
+Read PLAYBOOK.md and execute the procedure.
 ```
 
 ---
 
-## 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.
+## The Generated Files
 
 ```
-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
+my-project/
+├── PROJECT_BLUEPRINT.md         ← your input (untouched, optional)
+│
+├── CLAUDE.md                    ← generated: conventions, stack, rules
+├── AGENT_WORKFLOW.md            ← placeholder: Claude Code fills this in Phase 0
+├── PLAYBOOK.md                  ← generated: Phase 0 + Phase 1 execution engine
+│
+└── agents/                      ← generated: per-agent skill folders
+    ├── agent-1-infra/
+    │   └── skills.md            ← fill in infra-specific context
+    ├── agent-2-data/
+    │   └── skills.md            ← fill in data-specific context
+    └── agent-3-features/
+        └── skills.md            ← fill in feature-specific context
 ```
 
-The `skills.md` template generated by AgentKit:
+**`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.
 
-```markdown
-# Skills — Agent 2 · Auth & Supabase
+**`AGENT_WORKFLOW.md`** — starts as a placeholder. Claude Code fills it during Phase 0. Becomes the single source of truth for the project roadmap.
+
+**`PLAYBOOK.md`** — the execution engine. Phase 0 is always present (Discovery or Decomposition depending on whether a blueprint was provided). Phase 1 contains the agent execution loop with retry logic and human escalation.
 
-> This file is read by Agent 2 before starting its work.
-> Fill in what's relevant for your project.
+**`agents/agent-N-slug/skills.md`** — per-agent context files. Auto-generated as templates. Only the relevant agent reads its own file — bounded context by design. Add any `.md` files alongside `skills.md` and the agent reads those too.
+
+---
 
-## Technical context (fill in)
-- Supabase URL      :
-- Tables involved   :
-- Expected RLS      :
+## Optionally Enrich the Skills Files
 
-## Reference documentation (optional)
-<!-- paste API docs, schemas, examples here -->
+Before running Claude Code, drop context-specific `.md` files into any agent's folder:
 
-## Project-specific conventions (optional)
-<!-- e.g. "always use useSession(), never useUser()" -->
+```
+agents/
+├── agent-3-ollama/
+│   ├── skills.md                    ← auto-generated template
+│   └── ollama-api-reference.md      ← you add this: Ollama API docs
+└── agent-4-rag/
+    ├── skills.md
+    └── cosine-similarity-example.md ← you add this: algorithm reference
 ```
 
 ---
@@ -246,13 +244,15 @@ 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
+4. Regenerates `PLAYBOOK.md` **without Phase 0** — the initial decomposition is already done
 
 Then in Claude Code:
 ```
 Read PLAYBOOK.md and execute only the agents that haven't been completed yet.
 ```
 
+Phase 0 only ever runs once — during the initial `agentkit init`. Iterations go straight to execution.
+
 ---
 
 ## Supported Stacks
@@ -267,37 +267,108 @@ Read PLAYBOOK.md and execute only the agents that haven't been completed yet.
 | **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?
+### No AI in the tool — by design
+
+Integrating an LLM into AgentKit would mean choosing a provider, managing API keys, adding costs, and coupling the tool to a specific model that will become outdated. Instead, AgentKit is purely structural — it generates files that any LLM can read and act on. The intelligence lives in Claude Code (or whatever tool you use), not in AgentKit.
+
+### Phase 0 always runs — with or without blueprint
+
+The key insight: most developers don't know how to optimally decompose a project into agents. AgentKit solves this by always delegating decomposition to Claude Code. With a blueprint, Claude Code reads the file. Without one, it asks you three questions. Either way, you never have to think about agents yourself — that's Claude Code's job.
+
+### You write intent, Claude Code writes structure
+
+Whether you write a blueprint or answer questions in chat, you describe *what* you want to build, not *how*. The decomposition into agents — which layer goes first, what the success criteria should be — is always decided by Claude Code during Phase 0.
 
-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.
+### Phase 0 runs once, iterations skip it
 
-### Why per-agent skills instead of one big context?
+Phase 0 is only present in the PLAYBOOK generated by `agentkit init`. When you run `agentkit add --feature`, the regenerated PLAYBOOK goes straight to Phase 1 — the initial planning is done, you're just adding to it.
 
-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.
+### Bounded context per agent
 
-### Why verifiable success criteria?
+Each agent reads only `CLAUDE.md` and its own `skills.md`. An infrastructure agent doesn't see your business logic. A features agent doesn't see your CI/CD configuration. This produces better output and prevents agents from making decisions outside their scope.
 
-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.
+### Verifiable success criteria
+
+Every agent ends with a runnable check — not a goal, a gate. 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.
+This CLI was built using the exact workflow it generates.
+
+### A little note
+
+The `CLAUDE.md`, `AGENT_WORKFLOW.md`, and `PLAYBOOK.md` files at the root of
+this repo are **illustrative** — they were written after the fact to show what
+AgentKit would have generated had it existed at the start of this project.
+This is the inherent bootstrapping paradox: you can't use a tool to build itself
+before the tool exists.
+
+`PROJECT_BLUEPRINT.md` however is **genuine** — it reflects the actual vision
+of the project from the beginning, including the Phase 0 decomposition principle
+that was central to the design.
+
+These four files serve as a concrete, real-world example of what AgentKit
+generates — on the same project rather than a separate demo repo. When you
+use AgentKit on your own project, the files it generates will follow exactly
+this structure.
+
+### How it would have worked
 
 ```
-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
+Step 1 — Write PROJECT_BLUEPRINT.md (genuine)
+  Described the CLI's features, constraints, and architecture in plain language.
+  No agents, no layers — just intent.
+
+Step 2 — npx agentkit init --blueprint PROJECT_BLUEPRINT.md
+  AgentKit detects: Node.js + TypeScript stack
+  Generates: CLAUDE.md, AGENT_WORKFLOW.md (placeholder), PLAYBOOK.md, agents/
+
+Step 3 — "Read PLAYBOOK.md and execute the procedure."
+
+  Phase 0 — Decomposition
+    Claude Code reads PROJECT_BLUEPRINT.md.
+    Proposes 4 agents, waits for validation.
+
+    "I have decomposed the project into 4 agents:
+      1. Infra & Setup
+      2. Detectors
+      3. Generators & Templates
+      4. Commands CLI
+    Should I proceed?"
+
+    Human: "Yes."
+
+  Phase 1 — Execution
+
+    Agent 1 · Infra & Setup
+      skills : agents/agent-1-infra/skills.md
+      runs   : npm run build        ✅
+
+    Agent 2 · Detectors
+      skills : agents/agent-2-detectors/skills.md
+      runs   : npm test             ✅
+
+    Agent 3 · Generators & Templates
+      skills : agents/agent-3-generators/skills.md
+      runs   : npm test             ✅
+
+    Agent 4 · Commands CLI
+      skills : agents/agent-4-commands/skills.md
+      runs   : npm run build && node dist/cli.js --help   ✅
+
+    🎉 Workflow complete
 ```
 
+The `CLAUDE.md`, `AGENT_WORKFLOW.md`, and `PLAYBOOK.md` in this repo show
+exactly what each file looks like after AgentKit generates it and Claude Code
+fills it in. Use them as a reference when writing your own `PROJECT_BLUEPRINT.md`.
+
 ---
 
 ## Project Structure
@@ -316,8 +387,8 @@ agentkit-cli/
 │   ├── generators/
 │   │   ├── claudeMdGenerator.ts
 │   │   ├── workflowGenerator.ts
-│   │   ├── playbookGenerator.ts ← PLAYBOOK.md with full exec logic
-│   │   └── skillsGenerator.ts   ← agents/agent-N-slug/ folders
+│   │   ├── playbookGenerator.ts ← Phase 0 (Discovery or Decomposition) + Phase 1
+│   │   └── skillsGenerator.ts
 │   ├── templates/
 │   │   ├── react.ts
 │   │   ├── nextjs.ts
@@ -329,6 +400,16 @@ agentkit-cli/
 │   └── utils/
 │       └── logger.ts
 ├── tests/
+├── agents/
+│   ├── agent-1-infra/
+│   │   └── skills.md
+│   ├── agent-2-detectors/
+│   │   └── skills.md
+│   ├── agent-3-generators/
+│   │   └── skills.md
+│   └── agent-4-commands/
+│       └── skills.md
+├── PROJECT_BLUEPRINT.md
 ├── CLAUDE.md
 ├── AGENT_WORKFLOW.md
 ├── PLAYBOOK.md
@@ -344,7 +425,7 @@ 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
+3. Register in `src/generators/claudeMdGenerator.ts` and `workflowGenerator.ts`
 4. Add fixtures in `tests/detectors/` and tests in `tests/generators/`
 
 ---

package/agents/agent-1-infra/skills.md

@@ -0,0 +1,46 @@
+# Skills — Agent 1 · Infra & Setup
+
+> This file is read by Agent 1 before starting its work.
+> It contains project-specific context that enriches the agent's understanding
+> beyond what is in CLAUDE.md.
+
+## Technical context
+
+- Package name   : @patricksardinha/agentkit-cli
+- Node.js target : 20+
+- Output formats : ESM + CJS (tsup dual build)
+- Binary name    : `agentkit` (mapped in package.json `bin` field)
+- Registry       : npm (scoped, public)
+
+## publishConfig requirement
+
+The package.json must include:
+```json
+"publishConfig": {
+  "access": "public"
+}
+```
+Without this, npm treats scoped packages as private and blocks publishing.
+
+## GitHub Actions release trigger
+
+The workflow must trigger on `v*` tags only (not branch pushes).
+The npm publish step must use:
+```yaml
+- run: npm publish --access public
+  env:
+    NODE_AUTH_TOKEN: ${{ secrets.NPM_TOKEN }}
+```
+The NPM_TOKEN must be an Automation token (not Granular) to bypass 2FA.
+
+## tsup configuration
+
+Dual output is required for compatibility:
+```ts
+export default defineConfig({
+  entry: ['src/cli.ts'],
+  format: ['esm', 'cjs'],
+  dts: true,
+  clean: true,
+})
+```

package/agents/agent-2-detectors/skills.md

@@ -0,0 +1,38 @@
+# Skills — Agent 2 · Detectors
+
+> This file is read by Agent 2 before starting its work.
+
+## StackInfo type
+
+The detector must return this exact shape:
+
+```typescript
+export interface StackInfo {
+  framework: 'react' | 'nextjs' | 'tauri' | 'fastapi' | 'express' | 'node' | 'unknown'
+  hasTypeScript: boolean
+  extras: string[]   // e.g. ['tailwind', 'prisma', 'testing']
+}
+```
+
+## Detection priority
+
+Frameworks are detected in this order (first match wins):
+1. tauri    — `src-tauri/` directory exists
+2. nextjs   — `next` key in package.json dependencies
+3. react    — `react` key in package.json dependencies
+4. fastapi  — `fastapi` in requirements.txt
+5. express  — `express` key in package.json dependencies
+6. node     — package.json exists (fallback)
+7. unknown  — nothing found
+
+## Extras detection
+
+- typescript : `typescript` in devDependencies OR tsconfig.json exists
+- tailwind   : `tailwindcss` in dependencies or devDependencies
+- prisma     : `prisma` in devDependencies OR prisma/ directory exists
+- testing    : `vitest` or `jest` in devDependencies
+
+## Test fixtures
+
+Use in-memory mock file systems for tests — do not read the actual
+agentkit-cli project files as fixtures, as this creates circular dependencies.