@patricksardinha/agentkit-cli 0.2.0 → 0.3.0

package/agents/agent-3-generators/skills.md

@@ -0,0 +1,43 @@
+# Skills — Agent 3 · Generators & Templates
+
+> This file is read by Agent 3 before starting its work.
+
+## Template function signature
+
+Every template file must export exactly these two functions:
+
+```typescript
+export function claudeMd(stack: StackInfo): string
+export function workflow(stack: StackInfo): string
+```
+
+The `workflow()` function returns a markdown string. The workflowGenerator
+is responsible for parsing that string into an `Agent[]` array.
+
+## Agent type
+
+```typescript
+export interface Agent {
+  number: number        // 1, 2, 3…
+  slug: string          // 'infra', 'auth', 'features'…
+  name: string          // 'Infra & Setup', 'Auth & Supabase'…
+  scope: string         // one-line description
+  outputs: string[]
+  criterion: string   // the runnable bash command
+}
+```
+
+## Blueprint parsing
+
+When `blueprintContent` is provided, parse `## Feature` sections
+using simple line splitting — no external markdown parser needed.
+Extract bullet points under each `##` heading and use them to name
+and scope the generated agents.
+
+## playbookGenerator rules
+
+The PLAYBOOK.md must always start with the one-instruction block:
+> "Read PLAYBOOK.md and execute the procedure."
+
+The retry limit is always 3. The escalation section is always present.
+Do not make these values configurable — consistency is the point.

package/agents/agent-4-commands/skills.md

@@ -0,0 +1,37 @@
+# Skills — Agent 4 · Commands CLI
+
+> This file is read by Agent 4 before starting its work.
+
+## Commander.js setup
+
+The CLI binary is `agentkit`. The three subcommands are:
+- `init [options]`   with `--blueprint <path>`
+- `add [options]`    with `--feature <description>`
+- `status`
+
+## init command behavior
+
+1. Run gitDetector — warn but don't block if not a git repo
+2. Run stackDetector on process.cwd()
+3. If --blueprint provided: read file, warn if path doesn't exist
+4. Call claudeMdGenerator(stack, blueprintContent?)
+5. Call workflowGenerator(stack, blueprintContent?) → { markdown, agents }
+6. Call playbookGenerator(agents, projectName)
+7. Call skillsGenerator(agents)
+8. Write all files — never overwrite existing files without --force flag
+
+## add command behavior
+
+1. Check AGENT_WORKFLOW.md exists — error if not (run init first)
+2. Parse existing agents to find the last number
+3. Generate new agent block from --feature description
+4. Append to AGENT_WORKFLOW.md
+5. Create agents/agent-{N+1}-{slug}/skills.md
+6. Regenerate PLAYBOOK.md entirely (not append — full regeneration)
+
+## Output rules
+
+- Use logger.ts for all output — never console.log directly
+- Use ora spinner during file generation
+- Use chalk.green for success, chalk.yellow for warnings, chalk.red for errors
+- Always print a summary of generated files at the end of init

package/dist/cli.cjs

@@ -684,67 +684,163 @@ ${agentBlocks.join("\n\n")}
 }
 
 // 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
 
-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 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
 
-## 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\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
 `;
 }
 
@@ -899,7 +995,7 @@ function registerInit(program2) {
     const claudeMdContent = generateClaudeMd(stack, blueprintContent);
     const workflowContent = generateWorkflow(stack, blueprintContent);
     const agents = extractAgentsFromWorkflow(workflowContent);
-    const playbookContent = generatePlaybook({ agents, projectName });
+    const playbookContent = generatePlaybook({ agents, projectName, hasBlueprint: !!blueprintContent });
     await (0, import_promises4.writeFile)(claudeMdPath, claudeMdContent, "utf-8");
     await (0, import_promises4.writeFile)(workflowPath, workflowContent, "utf-8");
     await (0, import_promises4.writeFile)(playbookPath, playbookContent, "utf-8");
@@ -927,7 +1023,7 @@ async function addFeatureToProject(description, projectDir) {
   try {
     workflowContent = await (0, import_promises5.readFile)(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;
@@ -961,7 +1057,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 (0, import_promises5.writeFile)(playbookPath, playbookContent, "utf-8");
   return {
     agent: newAgent,
@@ -969,13 +1069,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);
@@ -984,14 +1084,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 = (0, import_node_path6.join)(cwd, "AGENT_WORKFLOW.md");
     let existing = "";
     try {
       existing = await (0, import_promises5.readFile)(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;
@@ -1000,23 +1100,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");
@@ -1028,7 +1128,7 @@ ${outputLines}
 Crit\xE8re   : ${answers.criterion}
 `;
     await (0, import_promises5.writeFile)(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`);
   });
 }