@patricksardinha/agentkit-cli 0.2.0 → 0.4.0

package/dist/cli.js

@@ -91,25 +91,6 @@ async function isGitRepo(projectPath) {
   }
 }
 
-// src/utils/blueprintParser.ts
-function parseBlueprint(content) {
-  const features = [];
-  const sectionRegex = /^## (.+)$/gm;
-  const sections = [];
-  let m;
-  while ((m = sectionRegex.exec(content)) !== null) {
-    sections.push({ name: m[1].trim(), start: m.index });
-  }
-  for (let i = 0; i < sections.length; i++) {
-    const section = sections[i];
-    const end = i + 1 < sections.length ? sections[i + 1].start : content.length;
-    const body = content.slice(section.start, end);
-    const items = [...body.matchAll(/^[-*]\s+(.+)$/gm)].map((r) => r[1].trim());
-    features.push({ name: section.name, items });
-  }
-  return features;
-}
-
 // src/templates/react.ts
 function claudeMd(stack) {
   const lang = stack.hasTypeScript ? "TypeScript" : "JavaScript";
@@ -544,73 +525,17 @@ function generateClaudeMd(stack, blueprintContent) {
       base = claudeMd7(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 = `
-## Features (Blueprint)
-
-${featureLines}
-`;
+  const blueprintNote = "\n> A PROJECT_BLUEPRINT.md is present \u2014 Claude Code will read it during Phase 0.\n";
   const conventionsIdx = base.indexOf("\n## Conventions");
   if (conventionsIdx !== -1) {
-    return base.slice(0, conventionsIdx) + featureSection + base.slice(conventionsIdx);
-  }
-  return base + featureSection;
-}
-
-// src/utils/agentParser.ts
-function toSlug(name) {
-  return name.toLowerCase().replace(/[·•&]/g, " ").replace(/[^\w\s-]/g, "").trim().replace(/\s+/g, "-").replace(/-+/g, "-").replace(/^-|-$/g, "");
-}
-function getFieldValue(lines, pattern) {
-  for (const line of lines) {
-    const m = line.match(pattern);
-    if (m) return (m[1] ?? "").trim();
-  }
-  return "";
-}
-function extractAgentsFromWorkflow(content) {
-  const agents = [];
-  const blocks = content.split(/(?=^### Agent \d)/m).filter((b) => /^### Agent \d/.test(b.trimStart()));
-  for (const block of blocks) {
-    const lines = block.split("\n");
-    const headerMatch = lines[0].match(/^### Agent (\d+)\s*[·•]\s*(.+)$/);
-    if (!headerMatch) continue;
-    const number = parseInt(headerMatch[1], 10);
-    const name = headerMatch[2].trim();
-    const fullName = `Agent ${number} \xB7 ${name}`;
-    const slug = toSlug(name);
-    const scope = getFieldValue(lines, /Périmètre\s*:\s*(.+)/);
-    const criterion = getFieldValue(lines, /Critère[s]?\s*:\s*(.+)/);
-    const outputs = [];
-    const produitIdx = lines.findIndex((l) => /Produit\s*:/.test(l));
-    if (produitIdx !== -1) {
-      const inlineVal = (lines[produitIdx].match(/Produit\s*:\s*(.+)/)?.[1] ?? "").trim();
-      if (inlineVal) {
-        outputs.push(inlineVal);
-      } else {
-        for (let i = produitIdx + 1; i < lines.length; i++) {
-          const line = lines[i];
-          if (/^\s+[-]/.test(line)) {
-            outputs.push(line.trim().replace(/^-\s*/, ""));
-          } else if (line.trim() !== "" && !/^\s/.test(line)) {
-            break;
-          }
-        }
-      }
-    }
-    agents.push({ number, name, fullName, slug, scope, outputs, criterion });
+    return base.slice(0, conventionsIdx) + blueprintNote + base.slice(conventionsIdx);
   }
-  return agents;
+  return base + blueprintNote;
 }
 
 // src/generators/workflowGenerator.ts
-function generateWorkflow(stack, blueprintContent) {
-  if (blueprintContent) return blueprintWorkflow(stack, blueprintContent);
+function generateWorkflow(stack, blueprintContent, projectName) {
+  if (blueprintContent) return blueprintPlaceholder(projectName ?? stack.framework);
   switch (stack.framework) {
     case "react":
       return workflow(stack);
@@ -628,100 +553,177 @@ function generateWorkflow(stack, blueprintContent) {
       return workflow7(stack);
   }
 }
-function blueprintWorkflow(stack, blueprintContent) {
-  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} \xB7 ${feature.name}
-P\xE9rim\xE8tre : Impl\xE9menter la fonctionnalit\xE9 ${feature.name.toLowerCase()}
-Produit   :
-${outputLines}
-Crit\xE8re   : npm test (tests ${feature.name.toLowerCase()} passent)`;
-  });
-  const ciN = features.length + 1;
-  agentBlocks.push(
-    `### Agent ${ciN} \xB7 Tests & CI
-P\xE9rim\xE8tre : Couverture de tests compl\xE8te et configuration du pipeline CI
-Produit   :
-  - tests/
-  - .github/workflows/
-Crit\xE8re   : npm test passe, pipeline CI vert`
-  );
-  return `# Agent Workflow \u2014 ${stack.framework} (Blueprint)
+function blueprintPlaceholder(projectName) {
+  return `# AGENT_WORKFLOW.md \u2014 ${projectName}
 
-## Stack d\xE9tect\xE9e
-Framework: ${stack.framework} | Language: ${stack.language}
+> 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.
 
-## Agents
+---
 
-${agentBlocks.join("\n\n")}
+*Waiting for Phase 0 decomposition...*
 `;
 }
 
 // src/generators/playbookGenerator.ts
-function generatePlaybook({ agents, projectName }) {
+function generatePlaybook({ agents, projectName, hasBlueprint }) {
   const agentBlocks = agents.map((a) => agentBlock(a)).join("\n---\n\n");
+  const phase0 = hasBlueprint ? `## Phase 0 \u2014 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\`\u2026)
+- Agents must be ordered by dependency (no feature without infra first)
+- Maximum 6 agents \u2014 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\u2026)
+  6. Build & release (CI/CD, packaging, installers)
+
+**Write the result directly into \`AGENT_WORKFLOW.md\`** \u2014 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 \u2014 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 \u2014 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\`\u2026)
+- Agents must be ordered by dependency (no feature without infra first)
+- Maximum 6 agents \u2014 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\u2026)
+  6. Build & release (CI/CD, packaging, installers)
+
+**Write the result directly into \`AGENT_WORKFLOW.md\`** \u2014 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 \u2014 ${projectName}
 
-> Donne cette instruction \xE0 Claude Code : 'Lis PLAYBOOK.md et ex\xE9cute la proc\xE9dure.'
+> **One instruction to give Claude Code:**
+> "Read PLAYBOOK.md and execute the procedure."
+>
+> Claude Code handles the rest autonomously \u2014 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\xE8gles d'ex\xE9cution 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\xE8s chaque agent :
-- Ex\xE9cuter le crit\xE8re de succ\xE8s
-- Si succ\xE8s \u2192 annoncer "\u2705 Agent N termin\xE9" et passer au suivant
-- Si \xE9chec \u2192 analyser la cause racine, corriger, r\xE9ex\xE9cuter (max 3 tentatives)
-- Apr\xE8s 3 \xE9checs cons\xE9cutifs \u2192 pause et demander validation humaine
-- **Ne jamais passer \xE0 l'agent suivant sans crit\xE8re valid\xE9**
+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
+- \u2705 Passes \u2192 announce "\u2705 Agent N complete" and move to the next
+- \u274C Fails  \u2192 analyze the root cause, fix, rerun (max 3 attempts)
+- After 3 consecutive failures \u2192 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 \u2014 Execution
 
 ${agentBlocks}
 
-## It\xE9rations futures
+---
+
+## 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
+4. Execution resumes at the new agent only \u2014 completed agents are not rerun
 
-Lorsqu'un nouvel agent est ajout\xE9 via \`agentkit add --feature <description>\` :
-1. Un nouveau bloc agent est ajout\xE9 \xE0 la fin de \`AGENT_WORKFLOW.md\`
-2. Le dossier \`agents/agent-{N}-{slug}/\` est cr\xE9\xE9 avec \`skills.md\` et \`context.md\`
-3. Ce \`PLAYBOOK.md\` est r\xE9g\xE9n\xE9r\xE9 automatiquement pour inclure le nouvel agent
-4. L'ex\xE9cution reprend \xE0 ce nouvel agent uniquement \u2014 les agents pr\xE9c\xE9dents ne sont pas r\xE9ex\xE9cut\xE9s
+When you receive the instruction to continue after an iteration:
+> "Read PLAYBOOK.md and execute only the agents that haven't been completed yet."
 
-## Validation humaine requise
+---
 
-Les cas suivants n\xE9cessitent une pause et une confirmation humaine avant de continuer :
-- **3 \xE9checs cons\xE9cutifs** sur le crit\xE8re de succ\xE8s d'un agent
-- **D\xE9pendance externe manquante** : cl\xE9 API, variable d'environnement non d\xE9finie, service tiers inaccessible
-- **Conflit** entre le blueprint fourni (\`--blueprint\`) et la stack d\xE9tect\xE9e 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
 `;
 }
 function agentBlock(agent) {
   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\xE9tail)";
-  return `### ${agent.fullName}
+  const outputLines = agent.outputs.length > 0 ? agent.outputs.map((o) => `- ${o}`).join("\n") : "- (see skills.md for details)";
+  return `### Agent ${agent.number} \xB7 ${agent.name}
 
-**P\xE9rim\xE8tre** : ${agent.scope}
+**Scope**: ${agent.scope}
 
-**Skills** : \`${skillsPath}\`
+**Skills**: \`${skillsPath}\`
 
-**Fichiers produits** :
+**Deliverables**:
 ${outputLines}
 
-**Crit\xE8re de succ\xE8s** :
+**Success criterion**:
 \`\`\`bash
 ${agent.criterion || "npm run build && npm test"}
 \`\`\`
 
-**En cas d'\xE9chec** :
-1. Analyser le message d'erreur complet
-2. Corriger la cause racine (pas les sympt\xF4mes)
-3. R\xE9ex\xE9cuter le crit\xE8re (max 3 tentatives)
-4. Apr\xE8s 3 \xE9checs \u2192 demander validation humaine
+**On failure**:
+1. Read the full error output
+2. Fix the root cause \u2014 not the symptoms
+3. Rerun the success criterion (max 3 attempts)
+4. After 3 failures \u2192 ask for human validation
 `;
 }
 
@@ -775,6 +777,52 @@ ${outputLines}
 `;
 }
 
+// src/utils/agentParser.ts
+function toSlug(name) {
+  return name.toLowerCase().replace(/[·•&]/g, " ").replace(/[^\w\s-]/g, "").trim().replace(/\s+/g, "-").replace(/-+/g, "-").replace(/^-|-$/g, "");
+}
+function getFieldValue(lines, pattern) {
+  for (const line of lines) {
+    const m = line.match(pattern);
+    if (m) return (m[1] ?? "").trim();
+  }
+  return "";
+}
+function extractAgentsFromWorkflow(content) {
+  const agents = [];
+  const blocks = content.split(/(?=^### Agent \d)/m).filter((b) => /^### Agent \d/.test(b.trimStart()));
+  for (const block of blocks) {
+    const lines = block.split("\n");
+    const headerMatch = lines[0].match(/^### Agent (\d+)\s*[·•]\s*(.+)$/);
+    if (!headerMatch) continue;
+    const number = parseInt(headerMatch[1], 10);
+    const name = headerMatch[2].trim();
+    const fullName = `Agent ${number} \xB7 ${name}`;
+    const slug = toSlug(name);
+    const scope = getFieldValue(lines, /Périmètre\s*:\s*(.+)/);
+    const criterion = getFieldValue(lines, /Critère[s]?\s*:\s*(.+)/);
+    const outputs = [];
+    const produitIdx = lines.findIndex((l) => /Produit\s*:/.test(l));
+    if (produitIdx !== -1) {
+      const inlineVal = (lines[produitIdx].match(/Produit\s*:\s*(.+)/)?.[1] ?? "").trim();
+      if (inlineVal) {
+        outputs.push(inlineVal);
+      } else {
+        for (let i = produitIdx + 1; i < lines.length; i++) {
+          const line = lines[i];
+          if (/^\s+[-]/.test(line)) {
+            outputs.push(line.trim().replace(/^-\s*/, ""));
+          } else if (line.trim() !== "" && !/^\s/.test(line)) {
+            break;
+          }
+        }
+      }
+    }
+    agents.push({ number, name, fullName, slug, scope, outputs, criterion });
+  }
+  return agents;
+}
+
 // src/utils/logger.ts
 import chalk from "chalk";
 var logger = {
@@ -874,9 +922,9 @@ function registerInit(program2) {
     }
     const genSpinner = ora("G\xE9n\xE9ration des fichiers\u2026").start();
     const claudeMdContent = generateClaudeMd(stack, blueprintContent);
-    const workflowContent = generateWorkflow(stack, blueprintContent);
+    const workflowContent = generateWorkflow(stack, blueprintContent, projectName);
     const agents = extractAgentsFromWorkflow(workflowContent);
-    const playbookContent = generatePlaybook({ agents, projectName });
+    const playbookContent = generatePlaybook({ agents, projectName, hasBlueprint: !!blueprintContent });
     await writeFile2(claudeMdPath, claudeMdContent, "utf-8");
     await writeFile2(workflowPath, workflowContent, "utf-8");
     await writeFile2(playbookPath, playbookContent, "utf-8");
@@ -904,7 +952,7 @@ async function addFeatureToProject(description, projectDir) {
   try {
     workflowContent = await readFile3(workflowPath, "utf-8");
   } catch {
-    throw new Error(`AGENT_WORKFLOW.md introuvable dans ${projectDir} \u2014 lancez agentkit init`);
+    throw new Error(`AGENT_WORKFLOW.md not found in ${projectDir} \u2014 run agentkit init first`);
   }
   const existingAgents = extractAgentsFromWorkflow(workflowContent);
   const nextNumber = existingAgents.length + 1;
@@ -938,7 +986,11 @@ Crit\xE8re   : npm run build && npm test
   } catch {
   }
   const allAgents = [...existingAgents, newAgent];
-  const playbookContent = generatePlaybook({ agents: allAgents, projectName });
+  const playbookContent = generatePlaybook({
+    agents: allAgents,
+    projectName,
+    hasBlueprint: false
+  });
   await writeFile3(playbookPath, playbookContent, "utf-8");
   return {
     agent: newAgent,
@@ -946,13 +998,13 @@ Crit\xE8re   : npm run build && npm test
   };
 }
 function registerAdd(program2) {
-  const addCmd = program2.command("add").description("Ajoute des ressources au projet agentkit").option("--feature <description>", "Ajoute un agent depuis une description de feature et r\xE9g\xE9n\xE8re PLAYBOOK.md").action(async (options) => {
+  const addCmd = program2.command("add").description("Add resources to the agentkit project").option("--feature <description>", "Add an agent from a feature description and regenerate PLAYBOOK.md").action(async (options) => {
     if (options.feature) {
       try {
         const result = await addFeatureToProject(options.feature, process.cwd());
-        logger.success(`Agent ajout\xE9   : ${result.agent.fullName}`);
-        logger.success(`Dossier cr\xE9\xE9   : agents/agent-${result.agent.number}-${result.agent.slug}/`);
-        logger.success("PLAYBOOK.md    : r\xE9g\xE9n\xE9r\xE9");
+        logger.success(`Agent added    : ${result.agent.fullName}`);
+        logger.success(`Folder created : agents/agent-${result.agent.number}-${result.agent.slug}/`);
+        logger.success("PLAYBOOK.md    : regenerated");
       } catch (err) {
         logger.error(err instanceof Error ? err.message : String(err));
         process.exit(1);
@@ -961,14 +1013,14 @@ function registerAdd(program2) {
       addCmd.help();
     }
   });
-  addCmd.command("agent").description("Ajoute un nouvel agent dans AGENT_WORKFLOW.md (interactif)").action(async () => {
+  addCmd.command("agent").description("Add a new agent to AGENT_WORKFLOW.md (interactive)").action(async () => {
     const cwd = process.cwd();
     const workflowPath = join5(cwd, "AGENT_WORKFLOW.md");
     let existing = "";
     try {
       existing = await readFile3(workflowPath, "utf-8");
     } catch {
-      logger.error("AGENT_WORKFLOW.md introuvable \u2014 lancez d'abord : agentkit init");
+      logger.error("AGENT_WORKFLOW.md not found \u2014 run agentkit init first");
       process.exit(1);
     }
     const agentCount = (existing.match(/^### Agent \d+/gm) ?? []).length;
@@ -977,23 +1029,23 @@ function registerAdd(program2) {
       {
         type: "input",
         name: "name",
-        message: `Nom de l'agent (ex: "Agent ${nextNumber} \xB7 Feature X") :`,
+        message: `Agent name (e.g. "Agent ${nextNumber} \xB7 Feature X"):`,
         default: `Agent ${nextNumber}`
       },
       {
         type: "input",
         name: "scope",
-        message: "P\xE9rim\xE8tre (une phrase) :"
+        message: "Scope (one sentence):"
       },
       {
         type: "input",
         name: "outputs",
-        message: "Fichiers produits (s\xE9par\xE9s par des virgules) :"
+        message: "Deliverables (comma-separated):"
       },
       {
         type: "input",
         name: "criterion",
-        message: "Crit\xE8re de succ\xE8s :"
+        message: "Success criterion:"
       }
     ]);
     const outputLines = answers.outputs.split(",").map((o) => `  - ${o.trim()}`).join("\n");
@@ -1005,7 +1057,7 @@ ${outputLines}
 Crit\xE8re   : ${answers.criterion}
 `;
     await writeFile3(workflowPath, existing + agentSection, "utf-8");
-    logger.success(`Agent "${answers.name}" ajout\xE9 dans AGENT_WORKFLOW.md`);
+    logger.success(`Agent "${answers.name}" added to AGENT_WORKFLOW.md`);
   });
 }