create-agentic-pdlc 2.0.4 → 2.0.6

package/.agentic-pdlc/templates/docs/pdlc.md

@@ -0,0 +1,105 @@
+# PDLC — {{PROJECT_NAME}}
+
+## Board Columns
+
+| Column | Meaning | Who moves the card |
+|---|---|---|
+| 💡 Idea | Backlog — every new issue lands here | Manual |
+| 🔍 Exploration | Claude is analyzing code and context | Label `stage:exploration` |
+| 🧠 Brainstorming | Claude proposed approaches, awaiting PM gate | Label `stage:brainstorming` |
+| 📐 Detail Solution | Claude is writing the technical spec | Label `stage:detailing` |
+| ✅ Approval | Spec ready, awaiting `spec:approved` label | Label `spec:approved` |
+| ⚙️ Development | Agent implementing the spec | Label `stage:development` |
+| 🧪 Testing | CI pipeline or AI QA Agent running (Variant B) | GitHub Actions / QA Agent |
+| 👁 Code Review / PR | PR opened (Variant A) or QA passed (Variant B) | GitHub Actions |
+| 🚀 Ready for Production | Merged | GitHub Actions |
+
+<!--
+Adapt columns as needed. The functional baseline is:
+💡 Idea → ⚙️ Development → 👁 Code Review / PR → 🚀 Ready for Production
+-->
+
+## Workflow Variants (QA Agent)
+
+- **Variant A (Default):** PRs bypass the `Testing` column and land directly in `Code Review / PR`.
+- **Variant B (QA Agent Enabled):** PRs land in the `Testing` column first. An AI QA agent verifies the PR, adding `qa:pass` or `qa:fail`. Only after a `qa:pass` is the issue moved to `Code Review / PR`.
+
+## Board Identifiers (GitHub Projects)
+
+```
+PROJECT_ID   = {{PROJECT_ID}}
+STATUS_FIELD = {{STATUS_FIELD_ID}}
+REPO         = {{REPO_OWNER}}/{{REPO_NAME}}
+```
+
+## Column Option IDs
+
+| Column | Option ID |
+|---|---|
+| 💡 Idea | `{{ID_IDEA}}` |
+| 🔍 Exploration | `{{ID_EXPLORATION}}` |
+| 🧠 Brainstorming | `{{ID_BRAINSTORMING}}` |
+| 📐 Detail Solution | `{{ID_DETAIL}}` |
+| ✅ Approval | `{{ID_APPROVAL}}` |
+| ⚙️ Development | `{{ID_DEVELOPMENT}}` |
+| 🧪 Testing | `{{ID_TESTING}}` |
+| 👁 Code Review / PR | `{{ID_CODE_REVIEW_PR}}` |
+| 🚀 Ready for Production | `{{ID_READY_FOR_PRODUCTION}}` |
+
+## Agent × Phase Mapping
+
+| Phase | Responsible |
+|---|---|
+| 💡 → 📐 (upstream) | Claude (or ideation agent) in conversational session |
+| ⚙️ → 🔀 (downstream) | {{IMPLEMENTATION_AGENT}} (e.g. Jules `@google-labs-jules`) |
+| 👁 Code Review / PR | Human (you) |
+| Automatic transitions | GitHub Actions |
+
+## Issue Title Conventions
+
+```
+[icon] [PREFIX]: [short description, imperative tense]
+
+👤 US:     user story
+🐛 BUG:    bug
+🔧 TASK:   operational task
+🔬 SPIKE:  exploration/evaluation spike
+```
+
+## Labels
+
+| Label | Entity | Color | Meaning |
+|---|---|---|---|
+| `stage:exploration` | Issue | Purple | Issue is being evaluated |
+| `stage:brainstorming` | Issue | Pink | Proposed approaches awaiting PM gate |
+| `stage:detailing` | Issue | Blue | Technical spec is being written |
+| `stage:development` | Issue | Orange | Agent is implementing the spec |
+| `spec:approved` | Issue | Green | Gate 2 — agent is cleared to implement |
+| `pr:in-review` | PR | Yellow | Awaiting code review |
+| `pr:approved` | PR | Green | Code review approved |
+
+## Approval Gates
+
+**Gate 1 — PM/Ideation (Brainstorming):**
+You comment on the issue approving one of the approaches proposed by the ideation agent.
+Format: *"Approved — proceed with option X."*
+
+**Gate 2 — Tech Lead (Spec):**
+You add the `spec:approved` label to the issue after reviewing the technical spec in the body.
+This triggers the implementation agent via `agent-trigger.yml`.
+
+## Shortcuts by Type
+
+- **BUG** — Skips Brainstorming; enters Detail Solution with diagnostics + fix.
+- **TASK** — Skips Brainstorming; enters Detail Solution with operational steps.
+- **SPIKE** — Never reaches Development; delivery is a concluding comment.
+- **US** — Full flow observing both gates.
+
+## Definition of Done
+
+An issue is truly done when:
+- [ ] All Acceptance Criteria described in the body are implemented
+- [ ] Tests passing: `{{TEST_COMMAND}}`
+- [ ] No invariant violations (CI green)
+- [ ] Associated PR explicitly contains `Closes #N`
+- [ ] Basic manual smoke test executed after deploy (when applicable)

package/bin/cli.js

@@ -51,6 +51,8 @@ const i18n = {
   creating_project: t('[2/2] Creating Project V2 Board...', '[2/2] Criando Project V2 Board...', '[2/2] Creando Project V2 Board...'),
   project_ok: t('✅ Project created (ID: ', '✅ Projeto criado (ID: ', '✅ Proyecto creado (ID: '),
   project_err: t('❌ Failed to create project. Error: ', '❌ Falha ao criar o projeto. Erro: ', '❌ Fallo al crear el proyecto. Error: '),
+  link_project_ok: t('✅ Project linked to repository.', '✅ Projeto vinculado ao repositório.', '✅ Proyecto vinculado al repositorio.'),
+  link_project_warn: t('⚠️ Failed to link project to repository. Link it manually in GitHub Projects settings.', '⚠️ Falha ao vincular projeto ao repositório. Faça isso manualmente nas configurações do GitHub Projects.', '⚠️ Fallo al vincular el proyecto al repositorio. Hazlo manualmente en la configuración de GitHub Projects.'),
   config_columns: t('Configuring Project Columns...', 'Configurando colunas do Projeto...', 'Configurando columnas del Proyecto...'),
   columns_ok: t('✅ Project columns configured successfully.', '✅ Colunas do projeto configuradas com sucesso.', '✅ Columnas del proyecto configuradas con éxito.'),
   columns_warn: t('⚠️ Failed to configure project columns. You may need to add them manually.', '⚠️ Falha ao configurar colunas. Você pode precisar adicioná-las manualmente.', '⚠️ Fallo al configurar columnas. Es posible que debas agregarlas manualmente.'),
@@ -70,7 +72,9 @@ const i18n = {
   cursor_step_1: t('\t1. Open Cursor', '\t1. Abra o Cursor', '\t1. Abre Cursor'),
   cursor_step_2: t('\t2. Open Composer (Cmd+I or Cmd+L) and type: "@.agentic-pdlc/SETUP_PROMPT.md execute Setup Mode"\n', '\t2. Abra o Composer (Cmd+I ou Cmd+L) e digite: "@.agentic-pdlc/SETUP_PROMPT.md execute Setup Mode"\n', '\t2. Abre Composer (Cmd+I o Cmd+L) y escribe: "@.agentic-pdlc/SETUP_PROMPT.md execute Setup Mode"\n'),
   generic_written: t('✅ Agent generic setup instructions written to .agentic-setup.md', '✅ Instruções genéricas salvas em .agentic-setup.md', '✅ Instrucciones genéricas guardadas en .agentic-setup.md'),
-  generic_done: t('Tell your AI agent to read and execute the .agentic-setup.md file!\n', 'Diga ao seu agente para ler e executar o arquivo .agentic-setup.md!\n', '¡Dile a tu agente de IA que lea y ejecute el archivo .agentic-setup.md!\n')
+  generic_done: t('Tell your AI agent to read and execute the .agentic-setup.md file!\n', 'Diga ao seu agente para ler e executar o arquivo .agentic-setup.md!\n', '¡Dile a tu agente de IA que lea y ejecute el archivo .agentic-setup.md!\n'),
+  setup_done: t('🎉 All set! Continue the setup with your agent:', '🎉 Aqui tá pronto! Continue o setup com o seu agente:', '🎉 ¡Listo! Continúa el setup con tu agente:'),
+  setup_done_hint: t('>>> Tell it to read and execute the .agentic-setup.md file!', '>>> Diga a ele para ler e executar o arquivo .agentic-setup.md!', '>>> Dile que lea y ejecute el archivo .agentic-setup.md!')
 };
 
 const cyan = '\x1b[36m';
@@ -99,6 +103,16 @@ function copyDirSync(src, dest) {
   }
 }
 
+function printSetupDone() {
+  const line1 = i18n.setup_done;
+  const line2 = i18n.setup_done_hint;
+  const sep = '='.repeat(Math.max(line1.length, line2.length));
+  console.log(`\n${green}${sep}${reset}`);
+  console.log(`${green}${line1}${reset}`);
+  console.log(`${cyan}${line2}${reset}`);
+  console.log(`${green}${sep}${reset}\n`);
+}
+
 async function runSetup() {
   console.log(`${yellow}${i18n.checking_gh}${reset}`);
   try {
@@ -138,7 +152,7 @@ async function runSetup() {
 
   let isOrg = false;
   try {
-    const ownerType = execFileSync('gh', ['api', `repos/${repo}`, '--jq', '.owner.type']).toString().trim();
+    const ownerType = execFileSync('gh', ['api', `repos/${repo}`, '--jq', '.owner.type'], { stdio: ['ignore', 'pipe', 'ignore'] }).toString().trim();
     isOrg = ownerType === 'Organization';
   } catch (err) {
     const accountTypeAnswer = await askQuestion(i18n.ask_org);
@@ -147,7 +161,7 @@ async function runSetup() {
 
   let branchName = 'main';
   try {
-    branchName = execFileSync('gh', ['api', `repos/${repo}`, '--jq', '.default_branch']).toString().trim() || 'main';
+    branchName = execFileSync('gh', ['api', `repos/${repo}`, '--jq', '.default_branch'], { stdio: ['ignore', 'pipe', 'ignore'] }).toString().trim() || 'main';
   } catch (err) {
     const branchAnswer = await askQuestion(i18n.ask_branch);
     if (branchAnswer.trim()) branchName = branchAnswer.trim();
@@ -197,6 +211,15 @@ async function runSetup() {
     projectId = projectCreateOutput;
 
     console.log(`  ${i18n.project_ok}${projectId})`);
+
+    try {
+      const repoNodeId = execFileSync('gh', ['api', `repos/${repo}`, '--jq', '.node_id'], { stdio: ['ignore', 'pipe', 'ignore'] }).toString().trim();
+      execFileSync('gh', ['api', 'graphql', '-f', `query=mutation($projectId: ID!, $repositoryId: ID!) { linkProjectV2ToRepository(input: {projectId: $projectId, repositoryId: $repositoryId}) { repository { name } } }`, '-f', `projectId=${projectId}`, '-f', `repositoryId=${repoNodeId}`], { stdio: 'ignore' });
+      console.log(`  ${i18n.link_project_ok}`);
+    } catch (err) {
+      console.log(`  ${i18n.link_project_warn}`);
+    }
+
   } catch (err) {
     console.log(`  ${i18n.project_err}${err.message}`);
   }
@@ -212,35 +235,33 @@ async function runSetup() {
 
       if (statusFieldId) {
         const columns = [
-          { name: "💡 Idea", description: "Backlog", color: "GRAY" },
-          { name: "🔍 Exploration", description: "Claude is analyzing", color: "PURPLE" },
-          { name: "🧠 Brainstorming", description: "Awaiting PM gate", color: "PINK" },
-          { name: "📐 Detail Solution", description: "Technical spec", color: "BLUE" },
-          { name: "✅ Approval", description: "Spec ready", color: "GREEN" },
-          { name: "⚙️ Development", description: "Agent implementing", color: "ORANGE" },
-          { name: "🧪 Testing", description: "QA testing", color: "RED" },
-          { name: "👁 Code Review / PR", description: "PR opened", color: "YELLOW" },
-          { name: "🚀 Production", description: "Merged", color: "GREEN" }
+          { name: "💡 Idea", description: "Backlog — every new issue lands here", color: "GRAY" },
+          { name: "🔍 Exploration", description: "AI is analyzing code and context", color: "PURPLE" },
+          { name: "🧠 Brainstorming", description: "AI proposed approaches and trade-offs", color: "PINK" },
+          { name: "📐 Detail Solution", description: "AI is writing the technical spec", color: "BLUE" },
+          { name: "✅ Approval", description: "Spec ready, awaiting `spec:approved` label", color: "GREEN" },
+          { name: "⚙️ Development", description: "AI implementing the spec", color: "ORANGE" },
+          { name: "🧪 Testing", description: "QA testing and CI pipeline checks", color: "RED" },
+          { name: "👁 Code Review / PR", description: "PR opened, awaiting your review", color: "YELLOW" },
+          { name: "🚀 Ready for Production", description: "Merged and ready for production", color: "GREEN" }
         ];
 
-        const updateFieldQuery = `mutation($projectId: ID!, $fieldId: ID!, $options: [ProjectV2SingleSelectFieldOptionInput!]) {
+        const updateFieldQuery = `mutation($fieldId: ID!, $options: [ProjectV2SingleSelectFieldOptionInput!]) {
           updateProjectV2Field(input: {
-            projectId: $projectId,
             fieldId: $fieldId,
             singleSelectOptions: $options
-          }) { 
-            projectV2Field { 
+          }) {
+            projectV2Field {
               ... on ProjectV2SingleSelectField {
-                options { id name } 
+                options { id name }
               }
-            } 
+            }
           }
         }`;
 
         const queryPayload = JSON.stringify({
           query: updateFieldQuery,
           variables: {
-            projectId: projectId,
             fieldId: statusFieldId,
             options: columns
           }
@@ -249,7 +270,7 @@ async function runSetup() {
         const updateOutput = execFileSync('gh', ['api', 'graphql', '--input', '-'], { input: queryPayload }).toString().trim();
         const jsonResponse = updateOutput ? JSON.parse(updateOutput) : null;
         const returnedOptions = jsonResponse?.data?.updateProjectV2Field?.projectV2Field?.options || [];
-        
+
         for (const opt of returnedOptions) {
           optionMap[opt.name] = opt.id;
         }
@@ -266,7 +287,7 @@ async function runSetup() {
   // We copy the templates folder so the agent has the real text logic to replace and rename
   const sourceTemplates = path.join(sourceDir, 'templates');
   const targetTemplates = path.join(targetDir, '.agentic-pdlc', 'templates');
-  
+
   if (fs.existsSync(sourceTemplates)) {
     copyDirSync(sourceTemplates, targetTemplates);
     console.log(`${i18n.templates_copied}`);
@@ -275,7 +296,7 @@ async function runSetup() {
     const pdlcDest = path.join(targetTemplates, 'docs', 'pdlc.md');
     if (fs.existsSync(pdlcDest)) {
       let pdlcContent = fs.readFileSync(pdlcDest, 'utf8');
-      
+
       if (projectId) pdlcContent = pdlcContent.replace(/\\{\\{PROJECT_ID\\}\\}/g, () => projectId);
       if (statusFieldId) pdlcContent = pdlcContent.replace(/\\{\\{STATUS_FIELD_ID\\}\\}/g, () => statusFieldId);
       pdlcContent = pdlcContent.replace(/\\{\\{REPO_OWNER\\}\\}/g, () => repoOwner);
@@ -290,7 +311,7 @@ async function runSetup() {
         pdlcContent = pdlcContent.replace(/\{\{ID_DEVELOPMENT\}\}/g, optionMap["⚙️ Development"] || 'MISSING_ID');
         pdlcContent = pdlcContent.replace(/\{\{ID_TESTING\}\}/g, optionMap["🧪 Testing"] || 'MISSING_ID');
         pdlcContent = pdlcContent.replace(/\{\{ID_CODE_REVIEW_PR\}\}/g, optionMap["👁 Code Review / PR"] || 'MISSING_ID');
-        pdlcContent = pdlcContent.replace(/\{\{ID_PRODUCTION\}\}/g, optionMap["🚀 Production"] || 'MISSING_ID');
+        pdlcContent = pdlcContent.replace(/\{\{ID_READY_FOR_PRODUCTION\}\}/g, optionMap["🚀 Ready for Production"] || 'MISSING_ID');
       }
 
       fs.writeFileSync(pdlcDest, pdlcContent);
@@ -307,16 +328,7 @@ async function runSetup() {
       const dest = path.join(targetDir, '.agentic-setup.md');
       fs.copyFileSync(claudeSetupSrc, dest);
       console.log(`${i18n.setup_written}`);
-      console.log(`${green}============================================================${reset}`);
-      console.log(`${green}${i18n.framework_scaffolded}${reset}`);
-      console.log(`${green}============================================================${reset}\n`);
-      console.log(`${yellow}${i18n.next_steps}${reset}`);
-      console.log(`${cyan}${i18n.step_1}${reset}`);
-      console.log(`${cyan}${i18n.step_2}${reset}`);
-      console.log(`${cyan}>>> English: "Read .agentic-setup.md and guide me through the setup."${reset}`);
-      console.log(`${cyan}>>> Español: "Lea el archivo .agentic-setup.md e inicie el Setup Mode"${reset}`);
-      console.log(`${cyan}>>> Português: "Leia o arquivo .agentic-setup.md e inicie o Setup Mode."${reset}\n`);
-      console.log(`${i18n.note_cleanup}`);
+      printSetupDone();
     } else {
       console.error(`${i18n.missing_claude}${claudeSetupSrc}`);
     }
@@ -325,16 +337,14 @@ async function runSetup() {
       // Create .cursorrules which has the general invariants
       const dest = path.join(targetDir, '.cursorrules');
       fs.copyFileSync(cursorSetupSrc, dest);
-      
+
       // Also copy skill.md as a setup prompt for cursor composer
       const setupPromptDest = path.join(targetDir, '.agentic-pdlc', 'SETUP_PROMPT.md');
       if (fs.existsSync(claudeSetupSrc)) fs.copyFileSync(claudeSetupSrc, setupPromptDest);
 
       console.log(`${i18n.cursor_rules_written}`);
       console.log(`${i18n.cursor_setup_written}`);
-      console.log(`\n${green}${i18n.cursor_done}${reset}`);
-      console.log(`${cyan}${i18n.cursor_step_1}${reset}`);
-      console.log(`${cyan}${i18n.cursor_step_2}${reset}`);
+      printSetupDone();
     } else {
       console.error(`${i18n.missing_claude}${cursorSetupSrc}`);
     }
@@ -343,8 +353,7 @@ async function runSetup() {
     const dest = path.join(targetDir, '.agentic-setup.md');
     fs.copyFileSync(claudeSetupSrc, dest);
     console.log(`${i18n.generic_written}`);
-    console.log(`\n${green}${i18n.cursor_done}${reset}`);
-    console.log(`${cyan}>>> ${i18n.generic_done}${reset}`);
+    printSetupDone();
   }
 
   rl.close();

package/docs/pdlc.md

@@ -5,18 +5,18 @@
 | Column | Meaning | Who moves the card |
 |---|---|---|
 | 💡 Idea | Backlog — every new issue lands here | Manual |
-| 🔍 Exploration | Claude is analyzing code and context | Label `stage:exploration` |
-| 🧠 Brainstorming | Claude proposed approaches, awaiting PM gate | Label `stage:brainstorming` |
-| 📐 Detail Solution | Claude is writing the technical spec | Label `stage:detailing` |
-| ✅ Approval | Spec ready, awaiting `spec:approved` label | Label `spec:approved` |
-| ⚙️ Development | Agent implementing the spec | Label `stage:development` |
+| 🔍 Exploration | AI is analyzing code and context | Label `stage:exploration` |
+| 🧠 Brainstorming | AI proposed approaches and trade-offs | Label `stage:brainstorming` |
+| 📐 Detail Solution | AI is writing the technical spec | Label `stage:detailing` |
+| ✅ Approval | Your turn, awaiting `spec:approved` label | Label `spec:approved` |
+| ⚙️ Development | AI implementing the spec | Label `stage:development` |
 | 🧪 Testing | CI pipeline running | GitHub Actions |
 | 👁 Code Review / PR | PR opened, awaiting human review | GitHub Actions |
-| 🚀 Production | Merged | GitHub Actions |
+| 🚀 Ready for Production | Merged | GitHub Actions |
 
 <!--
 Adapt columns as needed. The functional baseline is:
-💡 Idea → ⚙️ Development → 👁 Code Review / PR → 🚀 Production
+💡 Idea → ⚙️ Development → 👁 Code Review / PR → 🚀 Ready for Production
 -->
 
 ## Board Identifiers (GitHub Projects)
@@ -39,7 +39,7 @@ REPO         = {{REPO_OWNER}}/{{REPO_NAME}}
 | ⚙️ Development | `{{ID_DEVELOPMENT}}` |
 | 🧪 Testing | `{{ID_TESTING}}` |
 | 👁 Code Review / PR | `{{ID_CODE_REVIEW_PR}}` |
-| 🚀 Production | `{{ID_PRODUCTION}}` |
+| 🚀 Ready for Production | `{{ID_READY_FOR_PRODUCTION}}` |
 
 ## Agent × Phase Mapping
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "create-agentic-pdlc",
-  "version": "2.0.4",
+  "version": "2.0.6",
   "description": "Agentic PDLC Framework - Conversational setup for your AI coding assistants",
   "type": "commonjs",
   "bin": {

package/scripts/reset-test-project.sh

@@ -0,0 +1,45 @@
+#!/usr/bin/env bash
+# Run from the root of a test project to undo everything npx create-agentic-pdlc creates.
+set -euo pipefail
+
+RED='\033[0;31m'
+GREEN='\033[0;32m'
+YELLOW='\033[1;33m'
+NC='\033[0m'
+
+echo -e "${YELLOW}Resetting agentic-pdlc artifacts in: $(pwd)${NC}\n"
+
+remove() {
+  local target="$1"
+  if [ ! -e "$target" ] && [ ! -L "$target" ]; then
+    echo -e "           skipped  $target (not found)"
+    return
+  fi
+  # Skip files/dirs tracked by git — they predate the setup run
+  if git ls-files --error-unmatch "$target" &>/dev/null 2>&1; then
+    echo -e "  ${YELLOW}protected${NC} $target (tracked by git — skipping)"
+    return
+  fi
+  rm -rf "$target"
+  echo -e "  ${GREEN}removed${NC}  $target"
+}
+
+# --- CLI phase ---
+remove .agentic-pdlc
+remove .agentic-setup.md
+remove .cursorrules
+
+# --- Setup Mode phase (agent-generated) ---
+remove AGENTS.md
+remove docs/pdlc.md
+remove .github/workflows/project-automation.yml
+remove .github/workflows/agent-trigger.yml
+remove .github/workflows/ci.yml
+remove .github/workflows/qa-agent.yml
+
+# Clean up empty dirs left behind
+rmdir --ignore-fail-on-non-empty docs 2>/dev/null || true
+rmdir --ignore-fail-on-non-empty .github/workflows 2>/dev/null || true
+rmdir --ignore-fail-on-non-empty .github 2>/dev/null || true
+
+echo -e "\n${GREEN}Done. Run 'npx create-agentic-pdlc' to start fresh.${NC}"

package/templates/docs/pdlc.md

@@ -12,11 +12,11 @@
 | ⚙️ Development | Agent implementing the spec | Label `stage:development` |
 | 🧪 Testing | CI pipeline or AI QA Agent running (Variant B) | GitHub Actions / QA Agent |
 | 👁 Code Review / PR | PR opened (Variant A) or QA passed (Variant B) | GitHub Actions |
-| 🚀 Production | Merged | GitHub Actions |
+| 🚀 Ready for Production | Merged | GitHub Actions |
 
 <!--
 Adapt columns as needed. The functional baseline is:
-💡 Idea → ⚙️ Development → 👁 Code Review / PR → 🚀 Production
+💡 Idea → ⚙️ Development → 👁 Code Review / PR → 🚀 Ready for Production
 -->
 
 ## Workflow Variants (QA Agent)
@@ -44,7 +44,7 @@ REPO         = {{REPO_OWNER}}/{{REPO_NAME}}
 | ⚙️ Development | `{{ID_DEVELOPMENT}}` |
 | 🧪 Testing | `{{ID_TESTING}}` |
 | 👁 Code Review / PR | `{{ID_CODE_REVIEW_PR}}` |
-| 🚀 Production | `{{ID_PRODUCTION}}` |
+| 🚀 Ready for Production | `{{ID_READY_FOR_PRODUCTION}}` |
 
 ## Agent × Phase Mapping