@patricksardinha/agentkit-cli 0.2.0 → 0.3.0

package/AGENT_WORKFLOW.md

@@ -1,55 +1,129 @@
-# 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
+# AGENT_WORKFLOW.md — @patricksardinha/agentkit-cli
+
+> This file was filled in by Claude Code during Phase 0 — Agent Decomposition.
+> It was proposed to the human and validated before execution began.
+>
+> Original proposal:
+> "I have decomposed the project into 4 agents:
+>   1. Infra & Setup
+>   2. Detectors
+>   3. Generators & Templates
+>   4. Commands CLI
+> Should I proceed?"
+>
+> Human: "Yes."
+
+---
+
+## Agent 1 · Infra & Setup
+
+**Scope:** scaffold the Node.js/TypeScript project, configure all build
+and test tooling, set up GitHub Actions for automated npm publishing.
+
+**Depends on:** nothing — this is the foundation
+
+**Skills:** `agents/agent-1-infra/skills.md`
+
+**Deliverables:**
+- `package.json` with all dependencies (commander, inquirer, chalk, ora, tsup, vitest)
+- `tsconfig.json` and `tsup.config.ts`
+- `vitest.config.ts`
+- `.github/workflows/release.yml` — npm publish on `v*` tag push
+- `src/utils/logger.ts` — chalk + ora output helpers
+
+**Success criterion:**
+```bash
+npm run build
+```
+
+---
+
+## Agent 2 · Detectors
+
+**Scope:** implement pure detection functions that read a target project
+directory and return a typed `StackInfo` object. No filesystem writes,
+no side effects.
+
+**Depends on:** Agent 1
+
+**Skills:** `agents/agent-2-detectors/skills.md`
+
+**Deliverables:**
+- `src/detectors/stackDetector.ts`
+  - Detects: react, nextjs, tauri, fastapi, express, node, unknown
+  - Detects extras: typescript, tailwind, prisma, testing
+  - Returns a typed `StackInfo` object
+- `src/detectors/gitDetector.ts`
+  - Returns true if the target directory contains a `.git` folder
+- `src/types/stack.ts` — `StackInfo` interface
+- `tests/detectors/stackDetector.test.ts` — fixtures for each stack
+
+**Success criterion:**
+```bash
+npm test
+```
+
+---
+
+## Agent 3 · Generators & Templates
+
+**Scope:** implement one template per stack and four generators that compose
+them into output files. The `playbookGenerator` is the core deliverable —
+it generates Phase 0 (Discovery or Decomposition) and Phase 1 (execution loop).
+
+**Depends on:** Agent 2
+
+**Skills:** `agents/agent-3-generators/skills.md`
+
+**Deliverables:**
+- `src/templates/` — one file per stack: react, nextjs, tauri, fastapi, express, node, unknown
+  - Each exports `claudeMd(stack: StackInfo): string` and `workflow(stack: StackInfo): string`
+- `src/generators/claudeMdGenerator.ts` — routes to the right template
+- `src/generators/workflowGenerator.ts` — routes + returns `Agent[]`
+- `src/generators/playbookGenerator.ts`
+  - `hasBlueprint: true` → Phase 0 reads PROJECT_BLUEPRINT.md
+  - `hasBlueprint: false` → Phase 0 asks the user three questions
+  - Phase 1 always present with retry logic and human escalation
+- `src/generators/skillsGenerator.ts` — creates `agents/agent-N-slug/skills.md`
+- `src/types/agent.ts` — `Agent` interface
+- `tests/generators/*.test.ts` — one test file per generator
+
+**Success criterion:**
+```bash
+npm test
+```
+
+---
+
+## Agent 4 · Commands CLI
+
+**Scope:** wire all generators and detectors into the three CLI commands
+using commander.js. This agent composes existing modules — it writes no
+business logic.
+
+**Depends on:** Agents 2 and 3
+
+**Skills:** `agents/agent-4-commands/skills.md`
+
+**Deliverables:**
+- `src/commands/init.ts`
+  - Detects stack with `stackDetector`
+  - Accepts `--blueprint <path>` — reads file, warns if path missing
+  - Calls all four generators in order
+  - Writes CLAUDE.md, AGENT_WORKFLOW.md, PLAYBOOK.md to project root
+  - Calls `skillsGenerator` to create `agents/` folder structure
+  - Never overwrites existing files without `--force`
+- `src/commands/add.ts`
+  - Accepts `--feature <description>`
+  - Reads existing AGENT_WORKFLOW.md to find last agent number
+  - Appends new agent block, creates `agents/agent-{N+1}-{slug}/skills.md`
+  - Regenerates PLAYBOOK.md **without Phase 0** (`hasBlueprint: false`)
+- `src/commands/status.ts`
+  - Reads AGENT_WORKFLOW.md and displays current state
+- `src/cli.ts` — registers all three commands with commander
+- `tests/commands/init.test.ts`
+
+**Success criterion:**
+```bash
+npm run build && node dist/cli.js --help
+```

package/CLAUDE.md

@@ -1,45 +1,70 @@
-# CLAUDE.md — AgentKit CLI
+# CLAUDE.md — @patricksardinha/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.
+> This file was generated by AgentKit from PROJECT_BLUEPRINT.md.
+> It is read by every agent before starting its work.
 
-## 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)
+## Project
+
+| Field      | Value                                              |
+|------------|----------------------------------------------------|
+| Name       | @patricksardinha/agentkit-cli                      |
+| Type       | Open-source npm CLI (Node.js + TypeScript)         |
+| Goal       | Scaffold AI-native orchestration layers for Claude Code |
+| Audience   | Fullstack developers using Claude Code             |
+| Registry   | npm — `npx @patricksardinha/agentkit-cli 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*
+- CI/CD      : GitHub Actions → npm publish on tag `v*`
+- Package    : scoped (`@patricksardinha/agentkit-cli`), public access
+
+## Project Structure
 
-## 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
+  commands/       ← one file per command (init, add, status)
+  generators/     ← file generation logic
+  detectors/      ← stack detection (pure functions, no side effects)
+  templates/      ← one file per stack (react, nextjs, tauri, fastapi, express, node, unknown)
+  types/          ← shared TypeScript interfaces (Agent, StackInfo…)
+  utils/          ← shared helpers (logger.ts)
+tests/            ← Vitest, mirrors src/ structure
+agents/           ← per-agent skills files (read by Claude Code)
+```
+
+## Absolute Rules
+
+1. Every command in `src/commands/` is self-contained — no shared mutable state
+2. Templates in `src/templates/` are TypeScript functions, never static `.md` files
+3. All terminal output goes through `src/utils/logger.ts` — never `console.log` directly
+4. Every generator has a corresponding test in `tests/generators/`
+5. Detectors are pure functions — they read the filesystem and return data, no writes
+6. Zero dependencies added without updating this file
+7. Never touch files outside your current agent's defined scope
+
+## Commands
+
+| Command               | Description                                      |
+|-----------------------|--------------------------------------------------|
+| `npm run build`       | Compile TypeScript → dist/ (tsup)                |
+| `npm test`            | Run all tests (Vitest)                           |
+| `npm run test:watch`  | Watch mode                                       |
+| `npx tsc --noEmit`    | Type check without emitting                      |
+| `npm run lint`        | ESLint on src/ and tests/                        |
+
+## Commit Conventions
+
+`feat:` / `fix:` / `test:` / `docs:` / `chore:` / `release:`
+
+## Definition of Done
+
+- `npm run build` passes without error
+- `npm test` passes without error
+- `npx tsc --noEmit` passes without error
+- `node dist/cli.js --help` shows all three commands
+- Every new generator has a test file

package/PLAYBOOK.md

@@ -0,0 +1,192 @@
+# PLAYBOOK.md — @patricksardinha/agentkit-cli
+
+> **One instruction to give Claude Code:**
+> "Read PLAYBOOK.md and execute the procedure."
+>
+> Claude Code handles the rest autonomously — blueprint reading, agent decomposition,
+> execution, success validation, retries, and human escalation.
+> No API key required. No additional cost beyond your LLM subscription.
+
+---
+
+## Global Execution Rules
+
+Before each agent:
+1. Read `CLAUDE.md`
+2. Read `agents/agent-{N}-{slug}/skills.md` (current agent's file)
+3. Read the agent's section in `AGENT_WORKFLOW.md`
+
+After each agent:
+- Run the success criterion command
+- ✅ Passes → announce "✅ Agent N complete" and move to the next
+- ❌ Fails  → analyze the root cause, fix, rerun (max 3 attempts)
+- After 3 consecutive failures → stop and ask for human validation
+
+**Never move to the next agent without a passing success criterion.**
+**Stay strictly within your current agent's defined scope.**
+
+---
+
+## Phase 0 — Agent Decomposition (run this first)
+
+> A `PROJECT_BLUEPRINT.md` was provided.
+> Claude Code reads it and decomposes the project into specialized agents
+> before writing a single line of code.
+
+**Read these files in order:**
+1. `CLAUDE.md`
+2. `PROJECT_BLUEPRINT.md`
+
+**Then decompose the project into agents** following these rules:
+
+- One agent = one coherent technical layer (never mix two layers)
+- Each agent must have a runnable success criterion (`npm test`, `cargo build`…)
+- Agents must be ordered by dependency (no feature without infra first)
+- Maximum 6 agents — if you have more, group related ones
+- Always respect this order:
+  1. Infra & Configuration
+  2. Data layer (DB schema, models, services)
+  3. External integrations (auth, APIs, local services like Ollama)
+  4. UI & pages
+  5. Advanced features (RAG, export, realtime…)
+  6. Build & release (CI/CD, packaging, installers)
+
+**Write the result directly into `AGENT_WORKFLOW.md`** — replace its current
+content with your decomposition.
+
+**Then ask for human validation:**
+> "I have decomposed the project into N agents: [list them].
+> Should I proceed with execution?"
+
+Wait for confirmation before moving to Phase 1.
+
+---
+
+## Phase 1 — Execution
+
+### Agent 1 · Infra & Setup
+
+**Scope**: scaffold the Node.js/TypeScript project, configure build and test tooling, set up GitHub Actions.
+
+**Skills**: `agents/agent-1-infra/skills.md`
+
+**Deliverables**:
+- package.json (commander, inquirer, chalk, ora, tsup, vitest)
+- tsconfig.json and tsup.config.ts
+- vitest.config.ts
+- .github/workflows/release.yml
+- src/utils/logger.ts
+
+**Success criterion**:
+```bash
+npm run build
+```
+
+**On failure**:
+1. Read the full error output
+2. Fix the root cause — not the symptoms
+3. Rerun the success criterion (max 3 attempts)
+4. After 3 failures → ask for human validation
+
+---
+
+### Agent 2 · Detectors
+
+**Scope**: implement pure detection functions, no side effects.
+
+**Skills**: `agents/agent-2-detectors/skills.md`
+
+**Deliverables**:
+- src/detectors/stackDetector.ts
+- src/detectors/gitDetector.ts
+- src/types/stack.ts
+- tests/detectors/stackDetector.test.ts
+
+**Success criterion**:
+```bash
+npm test
+```
+
+**On failure**:
+1. Read the full error output
+2. Fix the root cause — not the symptoms
+3. Rerun the success criterion (max 3 attempts)
+4. After 3 failures → ask for human validation
+
+---
+
+### Agent 3 · Generators & Templates
+
+**Scope**: one template per stack, four generators composing them into output files.
+
+**Skills**: `agents/agent-3-generators/skills.md`
+
+**Deliverables**:
+- src/templates/ (react, nextjs, tauri, fastapi, express, node, unknown)
+- src/generators/claudeMdGenerator.ts
+- src/generators/workflowGenerator.ts
+- src/generators/playbookGenerator.ts
+- src/generators/skillsGenerator.ts
+- src/types/agent.ts
+- tests/generators/*.test.ts
+
+**Success criterion**:
+```bash
+npm test
+```
+
+**On failure**:
+1. Read the full error output
+2. Fix the root cause — not the symptoms
+3. Rerun the success criterion (max 3 attempts)
+4. After 3 failures → ask for human validation
+
+---
+
+### Agent 4 · Commands CLI
+
+**Scope**: wire generators and detectors into CLI commands. No business logic — composition only.
+
+**Skills**: `agents/agent-4-commands/skills.md`
+
+**Deliverables**:
+- src/commands/init.ts (--blueprint support)
+- src/commands/add.ts (--feature support)
+- src/commands/status.ts
+- src/cli.ts
+- tests/commands/init.test.ts
+
+**Success criterion**:
+```bash
+npm run build && node dist/cli.js --help
+```
+
+**On failure**:
+1. Read the full error output
+2. Fix the root cause — not the symptoms
+3. Rerun the success criterion (max 3 attempts)
+4. After 3 failures → ask for human validation
+
+---
+
+## Future Iterations
+
+When a new agent is added via `agentkit add --feature <description>`:
+1. A new agent block is appended to `AGENT_WORKFLOW.md`
+2. The folder `agents/agent-{N}-{slug}/` is created with `skills.md`
+3. This `PLAYBOOK.md` is regenerated to include the new agent — **without Phase 0**
+4. Execution resumes at the new agent only — completed agents are not rerun
+
+When you receive the instruction to continue after an iteration:
+> "Read PLAYBOOK.md and execute only the agents that haven't been completed yet."
+
+---
+
+## Human Validation Required
+
+Stop and wait for confirmation in these situations:
+- **3 consecutive failures** on the same success criterion
+- **Missing external dependency**: API key, env variable, unavailable service
+- **Conflict** between `PROJECT_BLUEPRINT.md` and the detected stack
+- **Destructive operation**: overwriting files not listed in deliverables
+- **End of Phase 0**: agent decomposition must be validated before execution

package/PROJECT_BLUEPRINT.md

@@ -0,0 +1,52 @@
+# AgentKit CLI — Project Blueprint
+
+## Goal
+
+Build an open-source CLI tool that scaffolds an AI-native orchestration layer
+on top of any project. Developers run one command and get a structured set of
+files that tell Claude Code who to be, what to build, and how to divide work
+across specialized agents — including a PLAYBOOK.md that Claude Code reads and
+executes autonomously from start to finish, with no manual prompting between agents.
+
+## Features
+
+- Detect the project stack automatically by reading package.json, Cargo.toml,
+  src-tauri/, and requirements.txt
+- Generate CLAUDE.md adapted to the detected stack (conventions, commands, rules)
+- Generate AGENT_WORKFLOW.md as a placeholder — Claude Code fills it during Phase 0
+- Generate PLAYBOOK.md with two phases:
+    - Phase 0: if a blueprint is provided, Claude Code reads it and decomposes
+      the project into agents; if not, Claude Code asks the user three questions
+      and decomposes from the answers. Either way, decomposition is validated
+      by the human before execution begins.
+    - Phase 1: Claude Code executes each agent in sequence, validates success
+      criteria, retries on failure (max 3), and escalates to the human if blocked.
+- Generate agents/agent-N-slug/ folders with skills.md templates for per-agent
+  context injection
+- Support --blueprint flag to provide a PROJECT_BLUEPRINT.md
+- Support agentkit add --feature to append a new agent and regenerate PLAYBOOK.md
+  without Phase 0 (decomposition is already done)
+- Support agentkit status to display the current workflow state
+
+## Tech constraints
+
+- Node.js 20+ CLI, published to npm as a scoped package (@patricksardinha/agentkit-cli)
+- TypeScript 5, compiled with tsup (ESM + CJS dual output)
+- commander.js for CLI parsing, inquirer.js for interactive prompts,
+  chalk + ora for terminal output
+- Vitest for unit tests
+- GitHub Actions for CI/CD — npm publish automatically on tag v*
+- No API calls at runtime — all generation is local and static
+- No AI integrated in the tool itself — AgentKit is purely structural
+
+## Architecture notes
+
+- One file per command in src/commands/
+- One file per stack in src/templates/ (each exports claudeMd(stack) and workflow(stack))
+- Generators in src/generators/ compose templates into output files
+- Detectors in src/detectors/ are pure functions with no side effects —
+  they read the filesystem and return a typed StackInfo object
+- All user-facing output goes through src/utils/logger.ts (never console.log directly)
+- Every generator has a corresponding test file in tests/generators/
+- The stack detector enriches CLAUDE.md with the right commands and conventions —
+  the agent decomposition itself is always delegated to Claude Code via Phase 0