create-agentic-pdlc 2.1.2 → 2.1.4

package/adapters/claude-code/skill.md

@@ -3,6 +3,8 @@ name: agentic-pdlc
 description: Orchestrates the Agentic Product Development Life Cycle (PDLC) upstream stages (Idea -> Spec) and includes an interactive Setup Mode to initialize the framework.
 ---
 
+> **ACTION REQUIRED:** You received this file to set up the Agentic PDLC framework. Execute **Setup Mode** now — follow the instructions below step by step. Do not summarize; execute.
+
 # Agentic PDLC Orchestrator
 
 You are the upstream brainstorm partner and orchestrator for the Agentic PDLC framework. Your role is primarily to define technical specs based on user ideas.
@@ -40,7 +42,7 @@ If any of these files are missing, you are in **Setup Mode**. Do not proceed wit
      - c) **Yes, activate** — *Uncomment the `move-violation-to-board` job in `project-automation.yml`.* → Activate immediately.
    - **QA Agent:** Ask: *"Do you want to use a QA agent to verify PRs automatically before Code Review?"* Present the options:
      - a) **No (Variant A)** — *PRs go straight to Code Review. Standard and simpler.*
-     - b) **Yes (Variant B), but I need help configuring it** — *PRs pass through a QA Agent before being reviewed. Requires a QA Agent (e.g., QAWolf).* → Guide the user through configuration.
+     - b) **Yes (Variant B), but I need help configuring it** — *PRs pass through a QA Agent before being reviewed. Requires a `GEMINI_API_KEY` secret (free tier available at ai.google.dev).* → Guide the user through configuration.
      - c) **Yes (Variant B), I already have it configured** — *PRs pass through a QA Agent before being reviewed.* → Activate Variant B immediately: change `STATUS_CODE_REVIEW_PR` to `STATUS_TESTING` in the `move-card-on-pr-open` job and uncomment the `move-card-on-qa-pass` job in `project-automation.yml`.
    - **Implementation Agent:** Ask: *"Do you use an autonomous implementation agent? (It implements the features you approve for development)"* Present the options:
      - a) **No** — *No autonomous implementation agent.*

package/bin/cli.js

@@ -40,14 +40,10 @@ const i18n = {
   ask_repo: t('What is your GitHub repository URL? (e.g., https://github.com/YOUR_USER/repo_name): ', 'Qual é a URL do seu repositório no GitHub? (ex: https://github.com/SEU_USUARIO/repo_name): ', '¿Cuál es la URL de tu repositorio en GitHub? (ej: https://github.com/TU_USUARIO/repo_name): '),
   invalid_repo: t('❌ Invalid repository URL. Expected format: https://github.com/OWNER/REPO', '❌ URL de repositório inválida. Formato esperado: https://github.com/OWNER/REPO', '❌ URL de repositorio inválida. Formato esperado: https://github.com/OWNER/REPO'),
   ask_org: t('Does this repository belong to a personal User account (e.g., github.com/rafaeltcosta86) or an Organization (e.g., github.com/google-labs)? (user/org): ', 'Esse repositório pertence a um Usuário pessoal (ex: github.com/rafaeltcosta86) ou a uma Organização (ex: github.com/google-labs)? (user/org): ', '¿Este repositorio pertenece a un Usuario personal (ej: github.com/rafaeltcosta86) o a una Organización (ej: github.com/google-labs)? (user/org): '),
-  ask_branch: t('What is your main branch name? (default: main): ', 'Qual o nome da sua branch principal? (padrão: main): ', '¿Cuál es el nombre de tu rama principal? (por defecto: main): '),
   starting_setup: t('Starting automated repository setup...', 'Iniciando o setup automatizado do repositório...', 'Iniciando la configuración automatizada del repositorio...'),
   creating_labels: t('[1/2] Creating repository labels...', '[1/2] Criando labels no repositório...', '[1/2] Creando etiquetas (labels) en el repositorio...'),
   label_ok: t('✅ Label created: ', '✅ Label criada: ', '✅ Etiqueta creada: '),
   label_warn: t('⚠️ Failed to create label (might already exist): ', '⚠️ Falha ao criar label (talvez já exista): ', '⚠️ Fallo al crear etiqueta (quizás ya exista): '),
-  applying_protection: t('[2/3] Applying branch protection on ', '[2/3] Aplicando proteção de branch em ', '[2/3] Aplicando protección de rama en '),
-  protection_ok: t('✅ Branch protection applied to ', '✅ Proteção de branch aplicada em ', '✅ Protección de rama aplicada a '),
-  protection_warn: t('⚠️ Failed to apply branch protection. (Do you have GitHub Pro or is the repo Public?)', '⚠️ Falha ao aplicar proteção de branch. (Você tem GitHub Pro ou o repo é Público?)', '⚠️ Fallo al aplicar protección de rama. (¿Tienes GitHub Pro o el repositorio es Público?)'),
   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: '),
@@ -60,19 +56,8 @@ const i18n = {
   templates_copied: t('✅ Templates copied to .agentic-pdlc/templates/', '✅ Templates copiados para .agentic-pdlc/templates/', '✅ Plantillas copiadas a .agentic-pdlc/templates/'),
   pdlc_prefilled: t('✅ Pre-filled pdlc.md with Project ID, Status Field ID, and Column Option IDs.', '✅ pdlc.md preenchido com Project ID, Status Field ID, e Column Option IDs.', '✅ pdlc.md completado con Project ID, Status Field ID y Column Option IDs.'),
   setup_written: t('✅ Setup agent profile written to .agentic-setup.md\n', '✅ Perfil de setup do agente salvo em .agentic-setup.md\n', '✅ Perfil de configuración del agente guardado en .agentic-setup.md\n'),
-  framework_scaffolded: t('🎉 Framework files scaffolded to .agentic-pdlc/templates/', '🎉 Arquivos do framework injetados em .agentic-pdlc/templates/', '🎉 Archivos del framework inyectados en .agentic-pdlc/templates/'),
-  next_steps: t('👉 NEXT STEPS:', '👉 PRÓXIMOS PASSOS:', '👉 PRÓXIMOS PASOS:'),
-  step_1: t('1. Open your AI Assistant (Claude, Cursor, Copilot, etc).', '1. Abra o seu Assistente de IA (Claude, Cursor, Copilot, etc).', '1. Abre tu Asistente de IA (Claude, Cursor, Copilot, etc).'),
-  step_2: t('2. Ask it to read the .agentic-setup.md and start Setup Mode in any language you prefer. Example 👇', '2. Peça para ele ler o .agentic-setup.md e iniciar o Setup Mode. Exemplo 👇', '2. Pídele que lea .agentic-setup.md e inicie el Setup Mode. Ejemplo 👇'),
-  note_cleanup: t('Note: The agent will clean up the .agentic-setup.md file automatically when finished.\n', 'Nota: O agente irá limpar o arquivo .agentic-setup.md automaticamente quando terminar.\n', 'Nota: El agente limpiará el archivo .agentic-setup.md automáticamente cuando termine.\n'),
   missing_claude: t('❌ Could not find instruction file at ', '❌ Não foi possível encontrar o arquivo de instrução em ', '❌ No se pudo encontrar el archivo de instrucción en '),
   cursor_rules_written: t('✅ Default cursor rules written to .cursorrules', '✅ Regras padrão do cursor salvas em .cursorrules', '✅ Reglas por defecto de cursor guardadas en .cursorrules'),
-  cursor_setup_written: t('✅ Framework Setup Instructions written to .agentic-pdlc/SETUP_PROMPT.md', '✅ Instruções de Setup do Framework salvas em .agentic-pdlc/SETUP_PROMPT.md', '✅ Instrucciones de Setup del Framework guardadas en .agentic-pdlc/SETUP_PROMPT.md'),
-  cursor_done: t('🎉 Done! To start the conversational setup:', '🎉 Pronto! Para iniciar o setup conversacional:', '🎉 ¡Listo! Para iniciar la configuración conversacional:'),
-  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'),
   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!')
 };
@@ -159,14 +144,6 @@ async function runSetup() {
     isOrg = accountTypeAnswer.trim().toLowerCase() === 'org' || accountTypeAnswer.trim().toLowerCase() === 'organization';
   }
 
-  let branchName = 'main';
-  try {
-    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();
-  }
-
   console.log(`\n${yellow}${i18n.starting_setup}${reset}`);
 
   // Labels
@@ -182,6 +159,7 @@ async function runSetup() {
     { name: 'architecture-violation', color: 'd93f0b', description: 'Invariant violation detected by CI' },
     { name: 'qa:approved', color: '0e8a16', description: 'QA Agent approved the implementation' },
     { name: 'qa:needs-work', color: 'd93f0b', description: 'QA Agent found issues' },
+    { name: 'infra:qa-broken', color: 'F97316', description: 'QA Agent failed to run — manual review required' },
     { name: 'jules', color: '5319e7', description: 'Jules AI Agent' }
   ];
 
@@ -208,7 +186,11 @@ async function runSetup() {
     }
 
     const projectCreateRaw = execFileSync('gh', ['api', 'graphql', '-f', 'query=mutation($owner: ID!, $title: String!) { createProjectV2(input: {ownerId: $owner, title: $title}) { projectV2 { id number } } }', '-f', `owner=${ownerId}`, '-f', `title=${boardName}`]).toString().trim();
-    const projectCreateData = JSON.parse(projectCreateRaw).data.createProjectV2.projectV2;
+    const projectCreateResponse = JSON.parse(projectCreateRaw);
+    if (projectCreateResponse.errors) {
+      throw new Error(projectCreateResponse.errors.map(e => e.message).join('; '));
+    }
+    const projectCreateData = projectCreateResponse.data.createProjectV2.projectV2;
     projectId = projectCreateData.id;
     projectNumber = projectCreateData.number;
 
@@ -328,14 +310,14 @@ async function runSetup() {
       if (statusFieldId) wfContent = wfContent.replace(/\{\{STATUS_FIELD_ID\}\}/g, () => statusFieldId);
       if (Object.keys(optionMap).length > 0) {
         wfContent = wfContent.replace(/\{\{ID_IDEA\}\}/g, optionMap["💡 Idea"] || 'MISSING_ID');
-        wfContent = wfContent.replace(/\{\{ID_EXPLORATION\}\}/g, optionMap["🔍 Exploration"] || 'MISSING_ID');
-        wfContent = wfContent.replace(/\{\{ID_BRAINSTORMING\}\}/g, optionMap["🧠 Brainstorming"] || 'MISSING_ID');
-        wfContent = wfContent.replace(/\{\{ID_DETAILING\}\}/g, optionMap["📐 Detail Solution"] || 'MISSING_ID');
-        wfContent = wfContent.replace(/\{\{ID_APPROVAL\}\}/g, optionMap["✅ Approval"] || 'MISSING_ID');
-        wfContent = wfContent.replace(/\{\{ID_DEVELOPMENT\}\}/g, optionMap["⚙️ Development"] || 'MISSING_ID');
-        wfContent = wfContent.replace(/\{\{ID_TESTING\}\}/g, optionMap["🧪 Testing"] || 'MISSING_ID');
-        wfContent = wfContent.replace(/\{\{ID_CODE_REVIEW_PR\}\}/g, optionMap["👁 Code Review / PR"] || 'MISSING_ID');
-        wfContent = wfContent.replace(/\{\{ID_PRODUCTION\}\}/g, optionMap["🚀 Ready for Production"] || 'MISSING_ID');
+        wfContent = wfContent.replace(/\{\{ID_EXPLORATION\}\}/g, () => optionMap["🔍 Exploration"] || 'MISSING_ID');
+        wfContent = wfContent.replace(/\{\{ID_BRAINSTORMING\}\}/g, () => optionMap["🧠 Brainstorming"] || 'MISSING_ID');
+        wfContent = wfContent.replace(/\{\{ID_DETAILING\}\}/g, () => optionMap["📐 Detail Solution"] || 'MISSING_ID');
+        wfContent = wfContent.replace(/\{\{ID_APPROVAL\}\}/g, () => optionMap["✅ Approval"] || 'MISSING_ID');
+        wfContent = wfContent.replace(/\{\{ID_DEVELOPMENT\}\}/g, () => optionMap["⚙️ Development"] || 'MISSING_ID');
+        wfContent = wfContent.replace(/\{\{ID_TESTING\}\}/g, () => optionMap["🧪 Testing"] || 'MISSING_ID');
+        wfContent = wfContent.replace(/\{\{ID_CODE_REVIEW_PR\}\}/g, () => optionMap["👁 Code Review / PR"] || 'MISSING_ID');
+        wfContent = wfContent.replace(/\{\{ID_PRODUCTION\}\}/g, () => optionMap["🚀 Ready for Production"] || 'MISSING_ID');
       }
       fs.writeFileSync(workflowAutomationPath, wfContent);
     }
@@ -364,26 +346,28 @@ async function runSetup() {
     }
   } else if (agent === 'cursor') {
     if (fs.existsSync(cursorSetupSrc)) {
-      // 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}`);
+
+      if (fs.existsSync(claudeSetupSrc)) {
+        const setupDest = path.join(targetDir, '.agentic-setup.md');
+        fs.copyFileSync(claudeSetupSrc, setupDest);
+        console.log(`${i18n.setup_written}`);
+      }
       printSetupDone();
     } else {
       console.error(`${i18n.missing_claude}${cursorSetupSrc}`);
     }
   } else {
-    // Generic fallback mapping
-    const dest = path.join(targetDir, '.agentic-setup.md');
-    fs.copyFileSync(claudeSetupSrc, dest);
-    console.log(`${i18n.generic_written}`);
-    printSetupDone();
+    if (fs.existsSync(claudeSetupSrc)) {
+      const dest = path.join(targetDir, '.agentic-setup.md');
+      fs.copyFileSync(claudeSetupSrc, dest);
+      console.log(`${i18n.setup_written}`);
+      printSetupDone();
+    } else {
+      console.error(`${i18n.missing_claude}${claudeSetupSrc}`);
+    }
   }
 
   rl.close();

package/package.json

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

package/templates/.github/workflows/project-automation.yml

@@ -2,7 +2,7 @@ name: PDLC Board Automation
 
 on:
   pull_request:
-    types: [opened, reopened, closed]
+    types: [opened, reopened, closed, labeled]
   pull_request_review:
     types: [submitted]
   issues:
@@ -189,6 +189,52 @@ jobs:
             try { await github.rest.issues.removeLabel({ owner, repo, issue_number: prNumber, name: 'pr:in-review' }); } catch {}
             await github.rest.issues.addLabels({ owner, repo, issue_number: prNumber, labels: ['pr:approved'] }).catch(() => {});
 
+  # OPTIONAL: Uncomment for Variant B (QA Agent enabled)
+  # When qa:approved is added to a PR, move linked issue to Code Review / PR
+  # move-card-on-qa-pass:
+  #   name: qa:approved → Code Review / PR
+  #   if: github.event_name == 'pull_request' && github.event.action == 'labeled' && github.event.label.name == 'qa:approved'
+  #   runs-on: ubuntu-latest
+  #   env:
+  #     PROJECT_PAT: ${{ secrets.PROJECT_PAT }}
+  #   steps:
+  #     - name: Move linked issue to Code Review / PR
+  #       if: ${{ env.PROJECT_PAT != '' && env.PROJECT_ID != '{{PROJECT_ID}}' }}
+  #       uses: actions/github-script@v7
+  #       with:
+  #         github-token: ${{ env.PROJECT_PAT }}
+  #         script: |
+  #           const prNumber = context.payload.pull_request.number;
+  #           const { owner, repo } = context.repo;
+  #           const { data: pr } = await github.rest.pulls.get({ owner, repo, pull_number: prNumber });
+  #           const body = pr.body ?? '';
+  #           const linkedIssues = [...body.matchAll(/(?:Closes?|Fixes?|Resolves?)\s+#(\d+)/gi)].map(m => parseInt(m[1]));
+  #           const moveItem = async (nodeId) => {
+  #             const { addProjectV2ItemById: { item } } = await github.graphql(`
+  #               mutation($p: ID!, $c: ID!) {
+  #                 addProjectV2ItemById(input: {projectId: $p, contentId: $c}) { item { id } }
+  #               }`, { p: process.env.PROJECT_ID, c: nodeId });
+  #             await github.graphql(`
+  #               mutation($p: ID!, $i: ID!, $f: ID!, $v: ProjectV2FieldValue!) {
+  #                 updateProjectV2ItemFieldValue(input: {projectId: $p, itemId: $i, fieldId: $f, value: $v}) {
+  #                   projectV2Item { id }
+  #                 }
+  #               }`, {
+  #                 p: process.env.PROJECT_ID, i: item.id, f: process.env.STATUS_FIELD_ID,
+  #                 v: { singleSelectOptionId: process.env.STATUS_CODE_REVIEW_PR }
+  #               });
+  #           };
+  #           if (linkedIssues.length > 0) {
+  #             for (const n of linkedIssues) {
+  #               const { data: issue } = await github.rest.issues.get({ owner, repo, issue_number: n });
+  #               await moveItem(issue.node_id);
+  #               console.log(`Issue #${n} → Code Review / PR`);
+  #             }
+  #           } else {
+  #             await moveItem(pr.node_id);
+  #             console.log(`PR #${prNumber} → Code Review / PR (no linked issue)`);
+  #           }
+
   # PR Merged → Production
   move-card-on-pr-merge:
     name: Merged PR → Production

package/templates/.github/workflows/qa-agent.yml

@@ -6,22 +6,73 @@ on:
 permissions:
   pull-requests: write
   contents: read
+  issues: read
 
 jobs:
   qa:
-    name: Run AI QA Agent
+    name: AC Coverage Verification (Gemini)
     runs-on: ubuntu-latest
     steps:
       - uses: actions/checkout@v4
-      - name: Execute QA Tests
-        run: |
-          echo "Run your QA Agent here."
-          echo "This could be QAWolf, a custom LLM script, or a secondary agent."
-          echo "If tests pass: gh pr edit $PR_URL --add-label 'qa:pass'"
-          echo "If tests fail: gh pr edit $PR_URL --add-label 'qa:fail'"
-          
-          # Example success:
-          # gh pr edit ${{ github.event.pull_request.html_url }} --add-label "qa:pass"
+        with:
+          fetch-depth: 0
+
+      - name: Verify AC Coverage via Gemini
         env:
           GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
-          PR_URL: ${{ github.event.pull_request.html_url }}
+          GEMINI_API_KEY: ${{ secrets.GEMINI_API_KEY }}
+        run: |
+          set -e
+
+          PR_NUMBER="${{ github.event.pull_request.number }}"
+          BASE="${{ github.event.pull_request.base.sha }}"
+          HEAD="${{ github.event.pull_request.head.sha }}"
+
+          # Get PR diff (truncated to 8000 chars to stay within context limits)
+          DIFF=$(git diff "$BASE" "$HEAD" | head -c 8000)
+
+          # Extract linked issues from PR body
+          PR_BODY=$(gh pr view "$PR_NUMBER" --json body --jq '.body // ""')
+          ISSUE_NUMS=$(echo "$PR_BODY" | grep -oiE '(Closes?|Fixes?|Resolves?)\s+#([0-9]+)' | grep -oE '[0-9]+' || true)
+
+          # Build acceptance criteria context
+          AC_CONTEXT=""
+          if [ -n "$ISSUE_NUMS" ]; then
+            for NUM in $ISSUE_NUMS; do
+              ISSUE_BODY=$(gh issue view "$NUM" --json body --jq '.body // ""' 2>/dev/null || echo "")
+              AC_CONTEXT="${AC_CONTEXT}\\n\\n--- Issue #${NUM} ---\\n${ISSUE_BODY}"
+            done
+          fi
+
+          if [ -z "$AC_CONTEXT" ]; then
+            AC_CONTEXT="No linked issue found. Evaluate if the PR description is self-contained."
+          fi
+
+          # Serialize prompt as JSON string and call Gemini API (30s timeout)
+          PROMPT_JSON=$(printf '%s' "You are a senior QA engineer. Review whether this PR diff satisfies the Acceptance Criteria below.\n\nACCEPTANCE CRITERIA:\n${AC_CONTEXT}\n\nPR DIFF:\n${DIFF}\n\nRespond with exactly one word: PASS or FAIL, then on the next line explain briefly why (max 3 sentences)." | python3 -c 'import json,sys; print(json.dumps(sys.stdin.read()))')
+
+          RESPONSE=$(curl -s -X POST \
+            "https://generativelanguage.googleapis.com/v1beta/models/gemini-2.0-flash:generateContent?key=${GEMINI_API_KEY}" \
+            -H "Content-Type: application/json" \
+            -d "{\"contents\":[{\"parts\":[{\"text\":${PROMPT_JSON}}]}]}" \
+            --max-time 30 || echo "API_ERROR")
+
+          if [ "$RESPONSE" = "API_ERROR" ]; then
+            gh pr edit "$PR_NUMBER" --add-label "infra:qa-broken"
+            gh pr comment "$PR_NUMBER" --body "🤖 **QA Agent:** Could not reach Gemini API. Manual review required."
+            exit 0
+          fi
+
+          VERDICT=$(echo "$RESPONSE" | python3 -c 'import json,sys; d=json.load(sys.stdin); t=d.get("candidates",[{}])[0].get("content",{}).get("parts",[{}])[0].get("text","").strip(); print(t.split("\n")[0].upper() if t else "API_ERROR")')
+          EXPLANATION=$(echo "$RESPONSE" | python3 -c 'import json,sys; d=json.load(sys.stdin); t=d.get("candidates",[{}])[0].get("content",{}).get("parts",[{}])[0].get("text","").strip(); lines=t.split("\n",1); print(lines[1].strip() if len(lines)>1 else "")')
+
+          if echo "$VERDICT" | grep -q "^PASS"; then
+            gh pr edit "$PR_NUMBER" --add-label "qa:approved"
+            gh pr comment "$PR_NUMBER" --body "🤖 **QA Agent:** AC coverage verified. ${EXPLANATION}"
+          elif echo "$VERDICT" | grep -q "^FAIL"; then
+            gh pr edit "$PR_NUMBER" --add-label "qa:needs-work"
+            gh pr comment "$PR_NUMBER" --body "🤖 **QA Agent:** AC coverage insufficient. ${EXPLANATION}"
+          else
+            gh pr edit "$PR_NUMBER" --add-label "infra:qa-broken"
+            gh pr comment "$PR_NUMBER" --body "🤖 **QA Agent:** Could not parse Gemini response. Manual review required."
+          fi

package/templates/AGENTS.md

@@ -70,6 +70,7 @@ When detailing a solution in an issue body, you must **always** include both the
 - Never open a PR without passing the tests.
 - Never implement beyond the immediate scope of the issue.
 - Never create future-proofing abstractions for hypothetical features.
+- Never add or remove `stage:*` or `qa:*` labels manually. These are owned by GitHub Actions automation and the PM only.
 {{EXTRA_DONT}}
 
 ## Project Standards

package/templates/docs/pdlc.md

@@ -22,7 +22,7 @@ Adapt columns as needed. The functional baseline is:
 ## 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`.
+- **Variant B (QA Agent Enabled):** PRs land in the `Testing` column first. An AI QA agent verifies the PR, adding `qa:approved` or `qa:needs-work`. Only after a `qa:approved` is the issue moved to `Code Review / PR`.
 
 ## Board Identifiers (GitHub Projects)
 
@@ -77,6 +77,9 @@ REPO         = {{REPO_OWNER}}/{{REPO_NAME}}
 | `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 |
+| `qa:approved` | PR | Green | QA Agent passed — AC coverage verified |
+| `qa:needs-work` | PR | Red | QA Agent failed — PR needs changes |
+| `infra:qa-broken` | PR | Orange | QA Agent error — manual review required |
 
 ## Approval Gates