@patricksardinha/agentkit-cli 0.2.0 → 0.4.0

package/src/generators/playbookGenerator.ts

@@ -3,46 +3,146 @@ import type { Agent } from '../types/agent.js'
 export interface PlaybookInput {
   agents: Agent[]
   projectName: string
+  hasBlueprint: boolean
 }
 
-export function generatePlaybook({ agents, projectName }: PlaybookInput): string {
+export function generatePlaybook({ agents, projectName, hasBlueprint }: PlaybookInput): string {
   const agentBlocks = agents.map((a) => agentBlock(a)).join('\n---\n\n')
 
+  const phase0 = hasBlueprint
+    ? `## 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 0 — Project Discovery (run this first)
+
+> No \`PROJECT_BLUEPRINT.md\` was provided.
+> Before writing any code, Claude Code asks the user what they want to build,
+> then decomposes the project into agents — exactly as if a blueprint had been provided.
+
+**Ask the user these questions and wait for their answers:**
+
+1. What is this project? (one sentence describing the goal)
+2. What are the main features you want to build? (list them)
+3. Are there any tech constraints or architecture preferences?
+   (e.g. offline-only, specific DB, no auth, specific framework)
+
+**Once you have the answers, 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.
+
+---
+
+`
+
   return `# PLAYBOOK.md — ${projectName}
 
-> Donne cette instruction à Claude Code : 'Lis PLAYBOOK.md et exécute la procédure.'
+> **One instruction to give Claude Code:**
+> "Read PLAYBOOK.md and execute the procedure."
+>
+> Claude Code handles the rest autonomously — project discovery or blueprint reading,
+> agent decomposition, execution, success validation, retries, and human escalation.
+> No API key required. No additional cost beyond your LLM subscription.
 
-## 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)
+## Global Execution Rules
 
-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é**
+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\`
 
-## Agents
+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.**
+
+---
+
+${phase0}## Phase 1 — Execution
 
 ${agentBlocks}
 
-## Itérations futures
+---
+
+## Future Iterations
 
-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
+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
+4. Execution resumes at the new agent only — completed agents are not rerun
 
-## Validation humaine requise
+When you receive the instruction to continue after an iteration:
+> "Read PLAYBOOK.md and execute only the agents that haven't been completed yet."
 
-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
+---
+
+## 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 the detected stack and the user's stated constraints
+- **Destructive operation**: overwriting files not listed in deliverables
+- **End of Phase 0**: agent decomposition must be validated before execution
 `
 }
 
@@ -51,26 +151,26 @@ function agentBlock(agent: Agent): string {
   const outputLines =
     agent.outputs.length > 0
       ? agent.outputs.map((o) => `- ${o}`).join('\n')
-      : '- (voir skills.md pour le détail)'
+      : '- (see skills.md for details)'
 
-  return `### ${agent.fullName}
+  return `### Agent ${agent.number} · ${agent.name}
 
-**Périmètre** : ${agent.scope}
+**Scope**: ${agent.scope}
 
-**Skills** : \`${skillsPath}\`
+**Skills**: \`${skillsPath}\`
 
-**Fichiers produits** :
+**Deliverables**:
 ${outputLines}
 
-**Critère de succès** :
+**Success criterion**:
 \`\`\`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
+**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
 `
-}
+}

package/src/generators/workflowGenerator.ts

@@ -1,6 +1,4 @@
 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'
@@ -9,8 +7,8 @@ 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)
+export function generateWorkflow(stack: StackInfo, blueprintContent?: string, projectName?: string): string {
+  if (blueprintContent) return blueprintPlaceholder(projectName ?? stack.framework)
 
   switch (stack.framework) {
     case 'react':   return react.workflow(stack)
@@ -23,40 +21,15 @@ export function generateWorkflow(stack: StackInfo, blueprintContent?: string): s
   }
 }
 
-function blueprintWorkflow(stack: StackInfo, blueprintContent: string): string {
-  const features = parseBlueprint(blueprintContent)
+function blueprintPlaceholder(projectName: string): string {
+  return `# AGENT_WORKFLOW.md — ${projectName}
 
-  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)`
-  })
+> This file will be filled in by Claude Code during Phase 0.
+> Claude Code will read PROJECT_BLUEPRINT.md, propose a decomposition,
+> and replace this content after human validation.
 
-  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')}
+*Waiting for Phase 0 decomposition...*
 `
 }

package/tests/commands/add.test.ts

@@ -116,7 +116,7 @@ describe('addFeatureToProject', () => {
   it('throws an error when AGENT_WORKFLOW.md is missing', async () => {
     tempDir = await mkdtemp(join(tmpdir(), 'agentkit-add-test-'))
     await expect(addFeatureToProject('Add feature', tempDir)).rejects.toThrow(
-      'AGENT_WORKFLOW.md introuvable',
+      'AGENT_WORKFLOW.md not found in',
     )
   })
 

package/tests/generators/blueprintSupport.test.ts

@@ -63,27 +63,30 @@ describe('generateClaudeMd with blueprint', () => {
     expect(generateClaudeMd(REACT_STACK)).toBe(generateClaudeMd(REACT_STACK, undefined))
   })
 
-  it('includes a Features section when blueprint is provided', () => {
+  it('adds the blueprint note when blueprint is provided', () => {
     const result = generateClaudeMd(REACT_STACK, BLUEPRINT)
-    expect(result).toContain('## Features (Blueprint)')
-    expect(result).toContain('Authentication')
-    expect(result).toContain('Dashboard')
-    expect(result).toContain('API')
+    expect(result).toContain('PROJECT_BLUEPRINT.md is present')
+    expect(result).toContain('Phase 0')
   })
 
-  it('includes blueprint sub-items', () => {
+  it('does NOT include a Features (Blueprint) section', () => {
     const result = generateClaudeMd(REACT_STACK, BLUEPRINT)
-    expect(result).toContain('JWT tokens')
-    expect(result).toContain('User statistics')
+    expect(result).not.toContain('## Features (Blueprint)')
   })
 
-  it('places Features section before Conventions', () => {
+  it('does NOT include blueprint sub-items as feature bullets', () => {
     const result = generateClaudeMd(REACT_STACK, BLUEPRINT)
-    const featIdx = result.indexOf('## Features (Blueprint)')
+    expect(result).not.toContain('JWT tokens')
+    expect(result).not.toContain('User statistics')
+  })
+
+  it('places blueprint note before Conventions', () => {
+    const result = generateClaudeMd(REACT_STACK, BLUEPRINT)
+    const noteIdx = result.indexOf('PROJECT_BLUEPRINT.md is present')
     const convIdx = result.indexOf('## Conventions')
-    expect(featIdx).toBeGreaterThan(-1)
+    expect(noteIdx).toBeGreaterThan(-1)
     expect(convIdx).toBeGreaterThan(-1)
-    expect(featIdx).toBeLessThan(convIdx)
+    expect(noteIdx).toBeLessThan(convIdx)
   })
 
   it('still contains stack-specific content', () => {
@@ -98,33 +101,35 @@ describe('generateWorkflow with blueprint', () => {
     expect(generateWorkflow(REACT_STACK)).toBe(generateWorkflow(REACT_STACK, undefined))
   })
 
-  it('generates one agent per blueprint feature plus a CI agent', () => {
+  it('returns a Phase 0 placeholder instead of agent blocks', () => {
     const result = generateWorkflow(REACT_STACK, BLUEPRINT)
-    expect(result).toContain('Agent 1 · Authentication')
-    expect(result).toContain('Agent 2 · Dashboard')
-    expect(result).toContain('Agent 3 · API')
-    expect(result).toContain('Agent 4 · Tests & CI')
+    expect(result).toContain('AGENT_WORKFLOW.md')
+    expect(result).toContain('Phase 0')
+    expect(result).toContain('PROJECT_BLUEPRINT.md')
+    expect(result).toContain('Waiting for Phase 0 decomposition')
   })
 
-  it('each agent block is parseable by extractAgentsFromWorkflow', () => {
+  it('does NOT generate agent blocks from blueprint sections', () => {
     const result = generateWorkflow(REACT_STACK, BLUEPRINT)
-    const agents = extractAgentsFromWorkflow(result)
-    expect(agents).toHaveLength(4)
-    expect(agents[0].name).toBe('Authentication')
-    expect(agents[0].slug).toBe('authentication')
-    expect(agents[3].name).toBe('Tests & CI')
-    expect(agents[3].slug).toBe('tests-ci')
+    expect(result).not.toContain('Agent 1')
+    expect(result).not.toContain('Authentication')
+    expect(result).not.toContain('Dashboard')
+    expect(result).not.toContain('Tests & CI')
   })
 
-  it('includes blueprint feature items as outputs', () => {
+  it('does NOT include blueprint feature items as outputs', () => {
     const result = generateWorkflow(REACT_STACK, BLUEPRINT)
-    expect(result).toContain('JWT tokens')
-    expect(result).toContain('User statistics')
+    expect(result).not.toContain('JWT tokens')
+    expect(result).not.toContain('User statistics')
+  })
+
+  it('uses projectName in heading when provided', () => {
+    const result = generateWorkflow(REACT_STACK, BLUEPRINT, 'my-app')
+    expect(result).toContain('AGENT_WORKFLOW.md — my-app')
   })
 
-  it('includes stack information in the header', () => {
+  it('falls back to framework name when projectName is omitted', () => {
     const result = generateWorkflow(REACT_STACK, BLUEPRINT)
-    expect(result).toContain('react')
-    expect(result).toContain('typescript')
+    expect(result).toContain('AGENT_WORKFLOW.md — react')
   })
 })

package/tests/generators/claudeMdGenerator.test.ts

@@ -83,4 +83,52 @@ describe('generateClaudeMd', () => {
     expect(typeof result).toBe('string')
     expect(result.length).toBeGreaterThan(0)
   })
+
+  describe('blueprint note', () => {
+    const blueprint = `# My Project\n\n## Goal\nBuild something\n\n## Features\n- Auth\n- Dashboard\n`
+
+    it('adds the blueprint note when blueprintContent is provided', () => {
+      const result = generateClaudeMd(makeStack('react'), blueprint)
+      expect(result).toContain('PROJECT_BLUEPRINT.md is present')
+      expect(result).toContain('Phase 0')
+    })
+
+    it('does NOT list blueprint sections as features', () => {
+      const result = generateClaudeMd(makeStack('react'), blueprint)
+      expect(result).not.toContain('Features (Blueprint)')
+      expect(result).not.toContain('**Goal**')
+      expect(result).not.toContain('**Features**')
+    })
+
+    it('still contains the stack-based template content', () => {
+      const result = generateClaudeMd(makeStack('react'), blueprint)
+      expect(result).toContain('React')
+      expect(result).toContain('## Stack')
+      expect(result).toContain('## Commands')
+    })
+
+    it('adds blueprint note for unknown stack with blueprint', () => {
+      const result = generateClaudeMd(makeStack('unknown'), blueprint)
+      expect(result).toContain('PROJECT_BLUEPRINT.md is present')
+      expect(result).toContain('Phase 0')
+    })
+
+    it('returns base template unchanged when blueprintContent is absent', () => {
+      const withBlueprint = generateClaudeMd(makeStack('react'), blueprint)
+      const withoutBlueprint = generateClaudeMd(makeStack('react'))
+      expect(withBlueprint).not.toBe(withoutBlueprint)
+      expect(withoutBlueprint).not.toContain('PROJECT_BLUEPRINT.md is present')
+    })
+
+    it('adds blueprint note for every framework', () => {
+      const frameworks: StackInfo['framework'][] = [
+        'react', 'nextjs', 'tauri', 'fastapi', 'express', 'node', 'unknown',
+      ]
+      for (const framework of frameworks) {
+        const result = generateClaudeMd(makeStack(framework), blueprint)
+        expect(result).toContain('PROJECT_BLUEPRINT.md is present')
+        expect(result).not.toContain('Features (Blueprint)')
+      }
+    })
+  })
 })