@patricksardinha/agentkit-cli 0.1.0

package/src/generators/claudeMdGenerator.ts

@@ -0,0 +1,42 @@
+import type { StackInfo } from '../detectors/stackDetector.js'
+import { parseBlueprint } from '../utils/blueprintParser.js'
+import * as react from '../templates/react.js'
+import * as nextjs from '../templates/nextjs.js'
+import * as tauri from '../templates/tauri.js'
+import * as fastapi from '../templates/fastapi.js'
+import * as express from '../templates/express.js'
+import * as node from '../templates/node.js'
+import * as unknown from '../templates/unknown.js'
+
+export function generateClaudeMd(stack: StackInfo, blueprintContent?: string): string {
+  let base: string
+  switch (stack.framework) {
+    case 'react':   base = react.claudeMd(stack); break
+    case 'nextjs':  base = nextjs.claudeMd(stack); break
+    case 'tauri':   base = tauri.claudeMd(stack); break
+    case 'fastapi': base = fastapi.claudeMd(stack); break
+    case 'express': base = express.claudeMd(stack); break
+    case 'node':    base = node.claudeMd(stack); break
+    default:        base = unknown.claudeMd(stack)
+  }
+
+  if (!blueprintContent) return base
+
+  const features = parseBlueprint(blueprintContent)
+  if (features.length === 0) return base
+
+  const featureLines = features
+    .map((f, i) => {
+      const sub = f.items.length > 0 ? '\n' + f.items.map((it) => `   - ${it}`).join('\n') : ''
+      return `${i + 1}. **${f.name}**${sub}`
+    })
+    .join('\n')
+
+  const featureSection = `\n## Features (Blueprint)\n\n${featureLines}\n`
+
+  const conventionsIdx = base.indexOf('\n## Conventions')
+  if (conventionsIdx !== -1) {
+    return base.slice(0, conventionsIdx) + featureSection + base.slice(conventionsIdx)
+  }
+  return base + featureSection
+}

package/src/generators/playbookGenerator.ts

@@ -0,0 +1,76 @@
+import type { Agent } from '../types/agent.js'
+
+export interface PlaybookInput {
+  agents: Agent[]
+  projectName: string
+}
+
+export function generatePlaybook({ agents, projectName }: PlaybookInput): string {
+  const agentBlocks = agents.map((a) => agentBlock(a)).join('\n---\n\n')
+
+  return `# PLAYBOOK.md — ${projectName}
+
+> Donne cette instruction à Claude Code : 'Lis PLAYBOOK.md et exécute la procédure.'
+
+## Règles d'exécution globales
+
+Avant chaque agent :
+1. Lire \`CLAUDE.md\`
+2. Lire \`agents/agent-{N}-{slug}/skills.md\` (le fichier de l'agent courant)
+
+Après chaque agent :
+- Exécuter le critère de succès
+- Si succès → annoncer "✅ Agent N terminé" et passer au suivant
+- Si échec → analyser la cause racine, corriger, réexécuter (max 3 tentatives)
+- Après 3 échecs consécutifs → pause et demander validation humaine
+- **Ne jamais passer à l'agent suivant sans critère validé**
+
+## Agents
+
+${agentBlocks}
+
+## Itérations futures
+
+Lorsqu'un nouvel agent est ajouté via \`agentkit add --feature <description>\` :
+1. Un nouveau bloc agent est ajouté à la fin de \`AGENT_WORKFLOW.md\`
+2. Le dossier \`agents/agent-{N}-{slug}/\` est créé avec \`skills.md\` et \`context.md\`
+3. Ce \`PLAYBOOK.md\` est régénéré automatiquement pour inclure le nouvel agent
+4. L'exécution reprend à ce nouvel agent uniquement — les agents précédents ne sont pas réexécutés
+
+## Validation humaine requise
+
+Les cas suivants nécessitent une pause et une confirmation humaine avant de continuer :
+- **3 échecs consécutifs** sur le critère de succès d'un agent
+- **Dépendance externe manquante** : clé API, variable d'environnement non définie, service tiers inaccessible
+- **Conflit** entre le blueprint fourni (\`--blueprint\`) et la stack détectée automatiquement
+`
+}
+
+function agentBlock(agent: Agent): string {
+  const skillsPath = `agents/agent-${agent.number}-${agent.slug}/skills.md`
+  const outputLines =
+    agent.outputs.length > 0
+      ? agent.outputs.map((o) => `- ${o}`).join('\n')
+      : '- (voir skills.md pour le détail)'
+
+  return `### ${agent.fullName}
+
+**Périmètre** : ${agent.scope}
+
+**Skills** : \`${skillsPath}\`
+
+**Fichiers produits** :
+${outputLines}
+
+**Critère de succès** :
+\`\`\`bash
+${agent.criterion || 'npm run build && npm test'}
+\`\`\`
+
+**En cas d'échec** :
+1. Analyser le message d'erreur complet
+2. Corriger la cause racine (pas les symptômes)
+3. Réexécuter le critère (max 3 tentatives)
+4. Après 3 échecs → demander validation humaine
+`
+}

package/src/generators/skillsGenerator.ts

@@ -0,0 +1,56 @@
+import { mkdir, writeFile } from 'node:fs/promises'
+import { join } from 'node:path'
+import type { Agent } from '../types/agent.js'
+
+export async function generateSkills(agents: Agent[], outputDir: string): Promise<void> {
+  for (const agent of agents) {
+    const agentDir = join(outputDir, 'agents', `agent-${agent.number}-${agent.slug}`)
+    await mkdir(agentDir, { recursive: true })
+    await writeFile(join(agentDir, 'skills.md'), skillsMd(agent), 'utf-8')
+    await writeFile(join(agentDir, 'context.md'), contextMd(agent), 'utf-8')
+  }
+}
+
+function skillsMd(agent: Agent): string {
+  return `# Skills — ${agent.fullName}
+
+> Ce fichier est lu par l'agent avant de commencer.
+
+## Contexte technique
+
+<!-- À remplir : bibliothèques, versions, décisions d'architecture spécifiques à cet agent -->
+
+## Documentation de référence
+
+<!-- À remplir : liens vers docs, exemples, ADRs pertinents -->
+
+## Conventions spécifiques
+
+<!-- À remplir : règles propres à cet agent (naming, patterns, structure de fichiers) -->
+`
+}
+
+function contextMd(agent: Agent): string {
+  const outputLines =
+    agent.outputs.length > 0
+      ? agent.outputs.map((o) => `- ${o}`).join('\n')
+      : '- (voir AGENT_WORKFLOW.md)'
+
+  return `# Context — ${agent.fullName}
+
+> Ce fichier fournit le contexte additionnel à l'agent avant exécution.
+> À compléter avant de lancer cet agent.
+
+## Périmètre
+
+${agent.scope}
+
+## Fichiers produits attendus
+
+${outputLines}
+
+## Critère de succès
+
+\`${agent.criterion || 'npm run build && npm test'}\`
+`
+}

package/src/generators/workflowGenerator.ts

@@ -0,0 +1,62 @@
+import type { StackInfo } from '../detectors/stackDetector.js'
+import { parseBlueprint } from '../utils/blueprintParser.js'
+import { toSlug } from '../utils/agentParser.js'
+import * as react from '../templates/react.js'
+import * as nextjs from '../templates/nextjs.js'
+import * as tauri from '../templates/tauri.js'
+import * as fastapi from '../templates/fastapi.js'
+import * as express from '../templates/express.js'
+import * as node from '../templates/node.js'
+import * as unknown from '../templates/unknown.js'
+
+export function generateWorkflow(stack: StackInfo, blueprintContent?: string): string {
+  if (blueprintContent) return blueprintWorkflow(stack, blueprintContent)
+
+  switch (stack.framework) {
+    case 'react':   return react.workflow(stack)
+    case 'nextjs':  return nextjs.workflow(stack)
+    case 'tauri':   return tauri.workflow(stack)
+    case 'fastapi': return fastapi.workflow(stack)
+    case 'express': return express.workflow(stack)
+    case 'node':    return node.workflow(stack)
+    default:        return unknown.workflow(stack)
+  }
+}
+
+function blueprintWorkflow(stack: StackInfo, blueprintContent: string): string {
+  const features = parseBlueprint(blueprintContent)
+
+  const agentBlocks = features.map((feature, i) => {
+    const n = i + 1
+    const slug = toSlug(feature.name)
+    const outputLines =
+      feature.items.length > 0
+        ? feature.items.map((item) => `  - ${item}`).join('\n')
+        : `  - src/${slug}/`
+    return `### Agent ${n} · ${feature.name}
+Périmètre : Implémenter la fonctionnalité ${feature.name.toLowerCase()}
+Produit   :
+${outputLines}
+Critère   : npm test (tests ${feature.name.toLowerCase()} passent)`
+  })
+
+  const ciN = features.length + 1
+  agentBlocks.push(
+    `### Agent ${ciN} · Tests & CI
+Périmètre : Couverture de tests complète et configuration du pipeline CI
+Produit   :
+  - tests/
+  - .github/workflows/
+Critère   : npm test passe, pipeline CI vert`,
+  )
+
+  return `# Agent Workflow — ${stack.framework} (Blueprint)
+
+## Stack détectée
+Framework: ${stack.framework} | Language: ${stack.language}
+
+## Agents
+
+${agentBlocks.join('\n\n')}
+`
+}

package/src/templates/express.ts

@@ -0,0 +1,64 @@
+import type { StackInfo } from '../detectors/stackDetector.js'
+
+export function claudeMd(stack: StackInfo): string {
+  const lang = stack.hasTypeScript ? 'TypeScript' : 'JavaScript'
+  const hasPrisma = stack.extras.includes('prisma')
+  return `# CLAUDE.md — Express Project
+
+## Stack
+- Framework : Express (${lang})
+- Language  : ${lang}
+- Runtime   : Node.js 20+
+${hasPrisma ? '- Database  : Prisma ORM\n' : ''}
+## Commands
+- \`npm run dev\`   — development server (nodemon)
+- \`npm run build\` — compile TypeScript
+- \`npm start\`     — production server
+- \`npm test\`      — run tests
+
+## Structure
+src/
+  routes/       ← Express routers (one per domain)
+  controllers/  ← request handlers
+  services/     ← business logic
+  middleware/   ← Express middleware
+  utils/        ← shared helpers
+
+## Conventions
+1. Routes grouped by domain in \`src/routes/\`
+2. Business logic in \`src/services/\`, not in controllers
+3. Middleware for cross-cutting concerns (auth, validation)
+4. Tout output console passe par un logger centralisé
+`
+}
+
+export function workflow(stack: StackInfo): string {
+  const lang = stack.hasTypeScript ? 'TypeScript' : 'JavaScript'
+  return `# Agent Workflow — Express Project
+
+## Stack détectée
+Framework: Express | Language: ${lang}
+
+## Agents
+
+### Agent 1 · Data & Models
+Périmètre : modèles de données, accès DB
+Produit   : src/models/, src/services/db.ts
+Critère   : connexion DB fonctionnelle
+
+### Agent 2 · Services
+Périmètre : logique métier
+Produit   : src/services/
+Critère   : services testés unitairement
+
+### Agent 3 · Routes & Controllers
+Périmètre : routes Express, validation, auth
+Produit   : src/routes/, src/controllers/, src/middleware/
+Critère   : endpoints répondent correctement
+
+### Agent 4 · Tests & CI
+Périmètre : tests d'intégration, configuration CI
+Produit   : tests/, .github/workflows/
+Critère   : npm test passe
+`
+}

package/src/templates/fastapi.ts

@@ -0,0 +1,63 @@
+import type { StackInfo } from '../detectors/stackDetector.js'
+
+export function claudeMd(_stack: StackInfo): string {
+  return `# CLAUDE.md — FastAPI Project
+
+## Stack
+- Framework : FastAPI (Python)
+- Language  : Python 3.11+
+- Server    : Uvicorn
+- Validation: Pydantic v2
+
+## Commands
+- \`uvicorn main:app --reload\` — development server (http://localhost:8000)
+- \`pytest\`                    — run tests
+- \`pip install -r requirements.txt\` — install dependencies
+
+## Structure
+app/
+  main.py       ← FastAPI app entry point
+  routers/      ← API route groups
+  models/       ← Pydantic models
+  services/     ← business logic
+  dependencies/ ← FastAPI dependencies (DI)
+tests/          ← pytest tests
+
+## Conventions
+1. Routers grouped by domain in \`app/routers/\`
+2. Pydantic models for all request/response bodies
+3. Business logic in \`app/services/\`, not in routes
+4. Async endpoints by default (\`async def\`)
+5. Environment variables via \`python-dotenv\` + \`pydantic-settings\`
+`
+}
+
+export function workflow(_stack: StackInfo): string {
+  return `# Agent Workflow — FastAPI Project
+
+## Stack détectée
+Framework: FastAPI | Language: Python
+
+## Agents
+
+### Agent 1 · Models & Schemas
+Périmètre : modèles Pydantic, schémas DB (SQLAlchemy/SQLModel)
+Produit   : app/models/
+Critère   : modèles validés, migrations propres
+
+### Agent 2 · Services
+Périmètre : logique métier, accès base de données
+Produit   : app/services/
+Critère   : services testés unitairement (pytest)
+
+### Agent 3 · Routers & API
+Périmètre : routes FastAPI, dépendances, auth
+Produit   : app/routers/, app/dependencies/
+Critère   : endpoints documentés (OpenAPI), tests d'intégration
+
+### Agent 4 · Tests & CI
+Périmètre : couverture pytest, configuration CI
+Produit   : tests/, .github/workflows/
+Critère   : \`pytest\` passe à 100%
+`
+}

package/src/templates/nextjs.ts

@@ -0,0 +1,63 @@
+import type { StackInfo } from '../detectors/stackDetector.js'
+
+export function claudeMd(stack: StackInfo): string {
+  const hasTailwind = stack.extras.includes('tailwind')
+  const hasPrisma = stack.extras.includes('prisma')
+  return `# CLAUDE.md — Next.js Project
+
+## Stack
+- Framework : Next.js (TypeScript)
+- Rendering : App Router (RSC + Client Components)
+- Styling   : ${hasTailwind ? 'Tailwind CSS' : 'CSS Modules'}
+${hasPrisma ? '- Database  : Prisma ORM\n' : ''}
+## Commands
+- \`npm run dev\`   — development server (http://localhost:3000)
+- \`npm run build\` — production build
+- \`npm start\`     — production server
+- \`npm test\`      — run tests
+
+## Structure
+src/
+  app/          ← App Router pages and layouts
+  components/   ← shared UI components
+  lib/          ← server utilities, db clients
+  utils/        ← shared helpers
+
+## Conventions
+1. Server Components by default, \`'use client'\` only when needed
+2. API routes in \`src/app/api/\`
+3. Environment variables via \`src/env.ts\` (validated)
+4. Tout output console passe par un logger centralisé
+`
+}
+
+export function workflow(stack: StackInfo): string {
+  const hasPrisma = stack.extras.includes('prisma')
+  return `# Agent Workflow — Next.js Project
+
+## Stack détectée
+Framework: Next.js | Language: TypeScript
+
+## Agents
+
+### Agent 1 · Data Layer
+Périmètre : schéma${hasPrisma ? ' Prisma' : ''}, types, server actions
+Produit   : src/lib/, ${hasPrisma ? 'prisma/schema.prisma' : 'src/types/'}
+Critère   : types compilent, migrations propres
+
+### Agent 2 · UI Components
+Périmètre : composants réutilisables (Server + Client)
+Produit   : src/components/
+Critère   : composants rendus sans erreur
+
+### Agent 3 · Pages & Layout
+Périmètre : App Router, layouts, pages
+Produit   : src/app/
+Critère   : navigation fonctionnelle, build passe
+
+### Agent 4 · API & Tests
+Périmètre : API routes, tests e2e/unitaires
+Produit   : src/app/api/, tests/
+Critère   : npm test passe
+`
+}

package/src/templates/node.ts

@@ -0,0 +1,54 @@
+import type { StackInfo } from '../detectors/stackDetector.js'
+
+export function claudeMd(stack: StackInfo): string {
+  const lang = stack.hasTypeScript ? 'TypeScript' : 'JavaScript'
+  return `# CLAUDE.md — Node.js Project
+
+## Stack
+- Runtime  : Node.js 20+
+- Language : ${lang}
+
+## Commands
+- \`npm run dev\`   — development (with watch)
+- \`npm run build\` — compile${stack.hasTypeScript ? ' TypeScript' : ''}
+- \`npm start\`     — run production build
+- \`npm test\`      — run tests
+
+## Structure
+src/
+  index.ts      ← entry point
+  lib/          ← core library code
+  utils/        ← shared helpers
+
+## Conventions
+1. Modules follow single-responsibility principle
+2. Async/await over callbacks
+3. Tout output console passe par un logger centralisé
+`
+}
+
+export function workflow(stack: StackInfo): string {
+  const lang = stack.hasTypeScript ? 'TypeScript' : 'JavaScript'
+  return `# Agent Workflow — Node.js Project
+
+## Stack détectée
+Runtime: Node.js | Language: ${lang}
+
+## Agents
+
+### Agent 1 · Core Library
+Périmètre : logique principale
+Produit   : src/lib/
+Critère   : module fonctionne et testé
+
+### Agent 2 · CLI / API
+Périmètre : interface utilisateur (CLI ou API)
+Produit   : src/index.ts, src/cli.ts
+Critère   : commandes fonctionnelles
+
+### Agent 3 · Tests & CI
+Périmètre : couverture de tests, configuration CI
+Produit   : tests/, .github/workflows/
+Critère   : npm test passe
+`
+}

package/src/templates/react.ts

@@ -0,0 +1,61 @@
+import type { StackInfo } from '../detectors/stackDetector.js'
+
+export function claudeMd(stack: StackInfo): string {
+  const lang = stack.hasTypeScript ? 'TypeScript' : 'JavaScript'
+  const testLine = stack.extras.includes('testing') ? '- `npm test`      — run tests\n' : ''
+  return `# CLAUDE.md — React Project
+
+## Stack
+- Framework : React (${lang})
+- Language  : ${lang}
+- Build     : Vite
+
+## Commands
+- \`npm run dev\`   — development server
+- \`npm run build\` — production build
+${testLine}
+## 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. Tout output console passe par un logger centralisé
+`
+}
+
+export function workflow(stack: StackInfo): string {
+  const lang = stack.hasTypeScript ? 'TypeScript' : 'JavaScript'
+  return `# Agent Workflow — React Project
+
+## Stack détectée
+Framework: React | Language: ${lang}
+
+## Agents
+
+### Agent 1 · Components
+Périmètre : composants UI réutilisables
+Produit   : src/components/
+Critère   : composants documentés et testés
+
+### Agent 2 · State & Hooks
+Périmètre : state management, hooks personnalisés
+Produit   : src/hooks/
+Critère   : hooks testés unitairement
+
+### Agent 3 · Pages & Routing
+Périmètre : assemblage des pages, react-router
+Produit   : src/pages/
+Critère   : navigation fonctionnelle
+
+### Agent 4 · Tests & CI
+Périmètre : couverture de tests, configuration CI
+Produit   : tests/, .github/workflows/
+Critère   : npm test passe
+`
+}

package/src/templates/tauri.ts

@@ -0,0 +1,65 @@
+import type { StackInfo } from '../detectors/stackDetector.js'
+
+export function claudeMd(stack: StackInfo): string {
+  const lang = stack.hasTypeScript ? 'TypeScript' : 'JavaScript'
+  return `# CLAUDE.md — Tauri Project
+
+## Stack
+- Framework : Tauri (Rust + ${lang} frontend)
+- Language  : Rust (backend) + ${lang} (frontend)
+- Build     : Cargo + Vite
+
+## Commands
+- \`npm run tauri dev\`   — development (hot reload)
+- \`npm run tauri build\` — production bundle
+- \`npm run build\`       — frontend only
+- \`npm test\`            — run tests
+
+## Structure
+src/            ← frontend (${lang})
+  components/
+  utils/
+src-tauri/      ← Rust backend
+  src/
+    main.rs     ← Tauri entry point
+    commands.rs ← Tauri commands (IPC)
+  tauri.conf.json
+
+## Conventions
+1. IPC commands defined in \`src-tauri/src/commands.rs\`
+2. Frontend invokes via \`@tauri-apps/api/tauri\`
+3. No direct filesystem access from frontend
+4. Tout output console passe par un logger centralisé
+`
+}
+
+export function workflow(stack: StackInfo): string {
+  const lang = stack.hasTypeScript ? 'TypeScript' : 'JavaScript'
+  return `# Agent Workflow — Tauri Project
+
+## Stack détectée
+Framework: Tauri | Language: Rust + ${lang}
+
+## Agents
+
+### Agent 1 · Rust Commands
+Périmètre : commandes Tauri (IPC), permissions
+Produit   : src-tauri/src/commands.rs, tauri.conf.json
+Critère   : \`cargo build\` passe
+
+### Agent 2 · Frontend UI
+Périmètre : interface ${lang}, intégration IPC
+Produit   : src/components/, src/utils/
+Critère   : appels IPC fonctionnels
+
+### Agent 3 · Build & Packaging
+Périmètre : configuration build, icônes, installeurs
+Produit   : src-tauri/tauri.conf.json, icons/
+Critère   : \`npm run tauri build\` produit un bundle
+
+### Agent 4 · Tests
+Périmètre : tests Rust + tests frontend
+Produit   : src-tauri/tests/, tests/
+Critère   : \`cargo test\` + \`npm test\` passent
+`
+}

package/src/templates/unknown.ts

@@ -0,0 +1,45 @@
+import type { StackInfo } from '../detectors/stackDetector.js'
+
+export function claudeMd(_stack: StackInfo): string {
+  return `# CLAUDE.md
+
+## Stack
+Stack non détectée automatiquement — à remplir manuellement.
+
+## Commands
+- À définir selon le projet
+
+## Structure
+src/    ← code source
+tests/  ← tests
+
+## Conventions
+1. Tout output console passe par un logger centralisé
+2. À compléter selon les conventions du projet
+`
+}
+
+export function workflow(_stack: StackInfo): string {
+  return `# Agent Workflow
+
+## Stack détectée
+Stack inconnue — workflow générique.
+
+## Agents
+
+### Agent 1 · Setup
+Périmètre : configuration initiale du projet
+Produit   : structure de base
+Critère   : projet compilable
+
+### Agent 2 · Core
+Périmètre : logique principale
+Produit   : src/
+Critère   : fonctionnalités principales opérationnelles
+
+### Agent 3 · Tests
+Périmètre : couverture de tests
+Produit   : tests/
+Critère   : tests passent
+`
+}

package/src/types/agent.ts

@@ -0,0 +1,9 @@
+export interface Agent {
+  number: number
+  name: string
+  fullName: string
+  slug: string
+  scope: string
+  outputs: string[]
+  criterion: string
+}