@patricksardinha/agentkit-cli 0.1.0 → 0.3.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/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/playbookGenerator.test.ts

@@ -10,7 +10,7 @@ const sampleAgents: Agent[] = [
     name: 'Infra & Setup',
     fullName: 'Agent 1 · Infra & Setup',
     slug: 'infra-setup',
-    scope: 'scaffolding du projet',
+    scope: 'project scaffolding',
     outputs: ['package.json', 'tsconfig.json'],
     criterion: 'npm run build',
   },
@@ -19,76 +19,166 @@ const sampleAgents: Agent[] = [
     name: 'Components',
     fullName: 'Agent 2 · Components',
     slug: 'components',
-    scope: 'composants UI réutilisables',
+    scope: 'reusable UI components',
     outputs: ['src/components/'],
     criterion: 'npm test',
   },
 ]
 
-describe('generatePlaybook', () => {
-  it('returns a non-empty string', () => {
-    const result = generatePlaybook({ agents: sampleAgents, projectName: 'my-app' })
-    expect(typeof result).toBe('string')
-    expect(result.length).toBeGreaterThan(0)
+// ─── Common behaviour (both modes) ────────────────────────────────────────────
+
+describe('generatePlaybook (common)', () => {
+  for (const hasBlueprint of [true, false]) {
+    const label = hasBlueprint ? 'hasBlueprint: true' : 'hasBlueprint: false'
+
+    it(`[${label}] returns a non-empty string`, () => {
+      const result = generatePlaybook({ agents: sampleAgents, projectName: 'my-app', hasBlueprint })
+      expect(typeof result).toBe('string')
+      expect(result.length).toBeGreaterThan(0)
+    })
+
+    it(`[${label}] contains the project name`, () => {
+      const result = generatePlaybook({ agents: sampleAgents, projectName: 'my-app', hasBlueprint })
+      expect(result).toContain('my-app')
+    })
+
+    it(`[${label}] contains the one-instruction block`, () => {
+      const result = generatePlaybook({ agents: sampleAgents, projectName: 'my-app', hasBlueprint })
+      expect(result).toContain('Read PLAYBOOK.md and execute the procedure')
+    })
+
+    it(`[${label}] contains global execution rules`, () => {
+      const result = generatePlaybook({ agents: sampleAgents, projectName: 'my-app', hasBlueprint })
+      expect(result).toContain('Global Execution Rules')
+      expect(result).toContain('max 3 attempts')
+      expect(result).toContain('human validation')
+      expect(result).toContain('Never move to the next agent')
+    })
+
+    it(`[${label}] always contains Phase 0`, () => {
+      const result = generatePlaybook({ agents: sampleAgents, projectName: 'my-app', hasBlueprint })
+      expect(result).toContain('Phase 0')
+    })
+
+    it(`[${label}] always contains Phase 1`, () => {
+      const result = generatePlaybook({ agents: sampleAgents, projectName: 'my-app', hasBlueprint })
+      expect(result).toContain('Phase 1')
+    })
+
+    it(`[${label}] Phase 0 comes before Phase 1`, () => {
+      const result = generatePlaybook({ agents: sampleAgents, projectName: 'my-app', hasBlueprint })
+      expect(result.indexOf('Phase 0')).toBeLessThan(result.indexOf('Phase 1'))
+    })
+
+    it(`[${label}] contains a block for each agent`, () => {
+      const result = generatePlaybook({ agents: sampleAgents, projectName: 'my-app', hasBlueprint })
+      for (const agent of sampleAgents) {
+        expect(result).toContain(agent.fullName)
+        expect(result).toContain(agent.scope)
+        expect(result).toContain(`agents/agent-${agent.number}-${agent.slug}/skills.md`)
+      }
+    })
+
+    it(`[${label}] each agent block contains outputs and criterion`, () => {
+      const result = generatePlaybook({ agents: sampleAgents, projectName: 'my-app', hasBlueprint })
+      expect(result).toContain('package.json')
+      expect(result).toContain('npm run build')
+      expect(result).toContain('src/components/')
+      expect(result).toContain('npm test')
+    })
+
+    it(`[${label}] contains the future iterations section`, () => {
+      const result = generatePlaybook({ agents: sampleAgents, projectName: 'my-app', hasBlueprint })
+      expect(result).toContain('Future Iterations')
+      expect(result).toContain('agentkit add --feature')
+    })
+
+    it(`[${label}] contains the human validation section`, () => {
+      const result = generatePlaybook({ agents: sampleAgents, projectName: 'my-app', hasBlueprint })
+      expect(result).toContain('Human Validation Required')
+      expect(result).toContain('3 consecutive failures')
+      expect(result).toContain('Missing external dependency')
+      expect(result).toContain('End of Phase 0')
+    })
+
+    it(`[${label}] handles an empty agents list gracefully`, () => {
+      const result = generatePlaybook({ agents: [], projectName: 'empty-project', hasBlueprint })
+      expect(typeof result).toBe('string')
+      expect(result).toContain('empty-project')
+    })
+  }
+})
+
+// ─── Phase 0 with blueprint (Decomposition mode) ──────────────────────────────
+
+describe('generatePlaybook Phase 0 — Decomposition (hasBlueprint: true)', () => {
+  it('contains the decomposition title', () => {
+    const result = generatePlaybook({ agents: sampleAgents, projectName: 'my-app', hasBlueprint: true })
+    expect(result).toContain('Agent Decomposition')
+  })
+
+  it('references PROJECT_BLUEPRINT.md', () => {
+    const result = generatePlaybook({ agents: sampleAgents, projectName: 'my-app', hasBlueprint: true })
+    expect(result).toContain('PROJECT_BLUEPRINT.md')
+  })
+
+  it('contains decomposition rules', () => {
+    const result = generatePlaybook({ agents: sampleAgents, projectName: 'my-app', hasBlueprint: true })
+    expect(result).toContain('Maximum 6 agents')
+    expect(result).toContain('AGENT_WORKFLOW.md')
   })
 
-  it('contains the project name', () => {
-    const result = generatePlaybook({ agents: sampleAgents, projectName: 'my-app' })
-    expect(result).toContain('my-app')
+  it('contains the validation gate', () => {
+    const result = generatePlaybook({ agents: sampleAgents, projectName: 'my-app', hasBlueprint: true })
+    expect(result).toContain('Should I proceed')
   })
 
-  it('starts with the unique instruction', () => {
-    const result = generatePlaybook({ agents: sampleAgents, projectName: 'my-app' })
-    expect(result).toContain("Donne cette instruction à Claude Code")
-    expect(result).toContain("Lis PLAYBOOK.md et exécute la procédure")
+  it('does NOT contain Project Discovery language', () => {
+    const result = generatePlaybook({ agents: sampleAgents, projectName: 'my-app', hasBlueprint: true })
+    expect(result).not.toContain('Project Discovery')
+    expect(result).not.toContain('Ask the user these questions')
   })
+})
+
+// ─── Phase 0 without blueprint (Discovery mode) ───────────────────────────────
 
-  it('contains global execution rules', () => {
-    const result = generatePlaybook({ agents: sampleAgents, projectName: 'my-app' })
-    expect(result).toContain('Règles d\'exécution globales')
-    expect(result).toContain('3 tentatives')
-    expect(result).toContain('validation humaine')
-    expect(result).toContain('Ne jamais passer')
+describe('generatePlaybook Phase 0 — Discovery (hasBlueprint: false)', () => {
+  it('contains the discovery title', () => {
+    const result = generatePlaybook({ agents: sampleAgents, projectName: 'my-app', hasBlueprint: false })
+    expect(result).toContain('Project Discovery')
   })
 
-  it('contains a block for each agent', () => {
-    const result = generatePlaybook({ agents: sampleAgents, projectName: 'my-app' })
-    for (const agent of sampleAgents) {
-      expect(result).toContain(agent.fullName)
-      expect(result).toContain(agent.scope)
-      expect(result).toContain(`agents/agent-${agent.number}-${agent.slug}/skills.md`)
-    }
+  it('instructs Claude Code to ask the user questions', () => {
+    const result = generatePlaybook({ agents: sampleAgents, projectName: 'my-app', hasBlueprint: false })
+    expect(result).toContain('Ask the user these questions')
+    expect(result).toContain('What is this project')
+    expect(result).toContain('What are the main features')
   })
 
-  it('each agent block contains outputs and criterion', () => {
-    const result = generatePlaybook({ agents: sampleAgents, projectName: 'my-app' })
-    expect(result).toContain('package.json')
-    expect(result).toContain('npm run build')
-    expect(result).toContain('src/components/')
-    expect(result).toContain('npm test')
+  it('still contains decomposition rules', () => {
+    const result = generatePlaybook({ agents: sampleAgents, projectName: 'my-app', hasBlueprint: false })
+    expect(result).toContain('Maximum 6 agents')
+    expect(result).toContain('AGENT_WORKFLOW.md')
   })
 
-  it('contains the "Itérations futures" section', () => {
-    const result = generatePlaybook({ agents: sampleAgents, projectName: 'my-app' })
-    expect(result).toContain('Itérations futures')
-    expect(result).toContain('agentkit add --feature')
+  it('still contains the validation gate', () => {
+    const result = generatePlaybook({ agents: sampleAgents, projectName: 'my-app', hasBlueprint: false })
+    expect(result).toContain('Should I proceed')
   })
 
-  it('contains the human validation section', () => {
-    const result = generatePlaybook({ agents: sampleAgents, projectName: 'my-app' })
-    expect(result).toContain('Validation humaine requise')
-    expect(result).toContain('3 échecs consécutifs')
-    expect(result).toContain('Dépendance externe manquante')
-    expect(result).toContain('Conflit')
+  it('does NOT reference PROJECT_BLUEPRINT.md as a file to read', () => {
+    const result = generatePlaybook({ agents: sampleAgents, projectName: 'my-app', hasBlueprint: false })
+    expect(result).not.toContain('A `PROJECT_BLUEPRINT.md` was provided')
   })
 
-  it('handles an empty agents list gracefully', () => {
-    const result = generatePlaybook({ agents: [], projectName: 'empty-project' })
-    expect(typeof result).toBe('string')
-    expect(result).toContain('empty-project')
+  it('does NOT contain Agent Decomposition title', () => {
+    const result = generatePlaybook({ agents: sampleAgents, projectName: 'my-app', hasBlueprint: false })
+    expect(result).not.toContain('Agent Decomposition (run this first)')
   })
 })
 
+// ─── toSlug ───────────────────────────────────────────────────────────────────
+
 describe('toSlug', () => {
   it('converts name to lowercase hyphenated slug', () => {
     expect(toSlug('Infra & Setup')).toBe('infra-setup')
@@ -104,6 +194,8 @@ describe('toSlug', () => {
   })
 })
 
+// ─── extractAgentsFromWorkflow ────────────────────────────────────────────────
+
 describe('extractAgentsFromWorkflow', () => {
   it('extracts agents from a workflow string matching template format', () => {
     const workflow = `# Agent Workflow — React Project
@@ -149,4 +241,4 @@ Critère   : npm run build
   it('returns empty array for content with no agent blocks', () => {
     expect(extractAgentsFromWorkflow('# Just a title\nNo agents here.')).toEqual([])
   })
-})
+})