create-agentic-pdlc 2.0.1 → 2.0.4

package/.github/copilot-instructions.md

@@ -0,0 +1,12 @@
+# Agentic PDLC Instructions for GitHub Copilot Workspace
+
+Hello! You are operating within the Agentic PDLC framework.
+
+Before addressing the user's prompt or executing any task in this workspace, you MUST:
+
+1. Read the `AGENTS.md` file located at the root of this repository. It contains the primary instructions, definitions of done, and absolute invariants you must respect.
+2. Read `docs/pdlc.md` to understand your role in the project lifecycle.
+
+Never violate the invariants described in those files. If a user asks you to do something that contradicts `AGENTS.md`, you must refuse and point out the conflict.
+
+Focus on delivering the absolute minimum required to satisfy the immediate technical specs. Start! 

package/.github/workflows/agent-trigger.yml

@@ -20,7 +20,7 @@ jobs:
       PROJECT_TOKEN: ${{ secrets.PROJECT_TOKEN }}
     steps:
       - name: Update Labels
-        if: ${{ env.PROJECT_TOKEN != '' }}
+        if: ${{ env.PROJECT_TOKEN != '' && !contains('{{IMPLEMENTATION_AGENT_LABEL}}', '{{') }}
         uses: actions/github-script@v7
         with:
           github-token: ${{ env.PROJECT_TOKEN }}
@@ -33,20 +33,21 @@ jobs:
                 owner,
                 repo,
                 issue_number,
-                name: 'upstream:approval'
+                name: 'stage:approval'
               });
             } catch (error) {
-              console.log('Label upstream:approval not found or could not be removed');
+              console.log('Label stage:approval not found or could not be removed');
             }
             
             await github.rest.issues.addLabels({
               owner,
               repo,
               issue_number,
-              labels: ['upstream:development', '{{IMPLEMENTATION_AGENT_LABEL}}', 'agent:working']
+              labels: ['stage:development', '{{IMPLEMENTATION_AGENT_LABEL}}', 'agent:working']
             });
 
       - name: Comment on issue to trigger agent and prevent race conditions
+        if: ${{ !contains('{{IMPLEMENTATION_AGENT_LABEL}}', '{{') }}
         uses: actions/github-script@v7
         with:
           github-token: ${{ secrets.GITHUB_TOKEN }}
@@ -89,6 +90,7 @@ jobs:
       contents: read
     steps:
       - name: Comment on issue to trigger agent
+        if: ${{ !contains('{{IMPLEMENTATION_AGENT_LABEL}}', '{{') }}
         uses: actions/github-script@v7
         with:
           github-token: ${{ secrets.GITHUB_TOKEN }}

package/.github/workflows/auto-approve.yml

@@ -0,0 +1,16 @@
+name: Auto Approve PRs
+on:
+  pull_request:
+    types: [opened, labeled, synchronize]
+
+permissions:
+  pull-requests: write
+
+jobs:
+  auto-approve:
+    runs-on: ubuntu-latest
+    if: contains(github.event.pull_request.labels.*.name, 'auto-approve')
+    steps:
+      - uses: hmarr/auto-approve-action@v4
+        with:
+          github-token: ${{ secrets.GITHUB_TOKEN }}

package/.github/workflows/ci.yml

@@ -20,13 +20,21 @@ jobs:
         run: echo "Replace this with your package manager install command"
 
       - name: Run Linters
-        run: echo "No tests/build needed."
+        if: ${{ !contains('{{LINT_COMMAND}}', '{{') }}
+        run: |
+          {{LINT_COMMAND}}
 
       - name: Typecheck
-        run: echo "No typecheck needed."
+        if: ${{ !contains('{{TYPECHECK_COMMAND}}', '{{') }}
+        run: |
+          {{TYPECHECK_COMMAND}}
 
       - name: Build
-        run: echo "No tests/build needed."
+        if: ${{ !contains('{{BUILD_COMMAND}}', '{{') }}
+        run: |
+          {{BUILD_COMMAND}}
 
       - name: Run Tests
-        run: echo "No tests/build needed."
+        if: ${{ !contains('{{TEST_COMMAND}}', '{{') }}
+        run: |
+          {{TEST_COMMAND}}

package/.github/workflows/npm-publish.yml

@@ -27,7 +27,7 @@ jobs:
           # Strip 'v' from tag (e.g., v1.0.2 -> 1.0.2)
           VERSION=${GITHUB_REF_NAME#v}
           echo "Setting package version to $VERSION"
-          npm version $VERSION --no-git-tag-version
+          npm version $VERSION --no-git-tag-version --allow-same-version
 
       - name: Install Dependencies
         run: npm install

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

@@ -11,6 +11,7 @@ on:
 env:
   PROJECT_ID: "{{PROJECT_ID}}"
   STATUS_FIELD_ID: "{{STATUS_FIELD_ID}}"
+  STATUS_IDEA: "{{ID_IDEA}}"
   STATUS_EXPLORATION: "{{ID_EXPLORATION}}"
   STATUS_BRAINSTORMING: "{{ID_BRAINSTORMING}}"
   STATUS_DETAILING: "{{ID_DETAILING}}"
@@ -30,7 +31,7 @@ jobs:
       PROJECT_TOKEN: ${{ secrets.PROJECT_TOKEN }}
     steps:
       - name: Detect Label and Move Issue
-        if: ${{ env.PROJECT_TOKEN != '' }}
+        if: ${{ env.PROJECT_TOKEN != '' && env.PROJECT_ID != '{{PROJECT_ID}}' }}
         uses: actions/github-script@v7
         with:
           github-token: ${{ env.PROJECT_TOKEN }}
@@ -39,28 +40,28 @@ jobs:
             let targetStatusId = null;
             let stageName = null;
 
-            if (labelName === 'upstream:exploration') {
+            if (labelName === 'stage:exploration') {
               targetStatusId = process.env.STATUS_EXPLORATION;
               stageName = 'Exploration';
-            } else if (labelName === 'upstream:brainstorming') {
+            } else if (labelName === 'stage:brainstorming') {
               targetStatusId = process.env.STATUS_BRAINSTORMING;
               stageName = 'Brainstorming';
-            } else if (labelName === 'upstream:detailing') {
+            } else if (labelName === 'stage:detailing') {
               targetStatusId = process.env.STATUS_DETAILING;
               stageName = 'Detailing';
-            } else if (labelName === 'upstream:approval') {
+            } else if (labelName === 'stage:approval') {
               targetStatusId = process.env.STATUS_APPROVAL;
               stageName = 'Approval';
-            } else if (labelName === 'upstream:development') {
+            } else if (labelName === 'stage:development') {
               targetStatusId = process.env.STATUS_DEVELOPMENT;
               stageName = 'Development';
-            } else if (labelName === 'upstream:testing') {
+            } else if (labelName === 'stage:testing') {
               targetStatusId = process.env.STATUS_TESTING;
               stageName = 'Testing';
             }
 
             if (!targetStatusId) {
-              console.log('No upstream PDLC label found. Skipping.');
+              console.log('No stage PDLC label found. Skipping.');
               return;
             }
 
@@ -86,9 +87,36 @@ jobs:
             await moveItem(node_id, targetStatusId);
             console.log(`Issue #${number} moved to ${stageName}`);
 
-{{OPTIONAL_ARCHITECTURE_VIOLATION_JOB}}
+  # OPTIONAL: Uncomment to enable architecture-violation → Idea
+  # move-violation-to-board:
+  #   name: architecture-violation → 💡 Idea
+  #   if: github.event_name == 'issues' && github.event.action == 'labeled' && github.event.label.name == 'architecture-violation'
+  #   runs-on: ubuntu-latest
+  #   steps:
+  #     - name: Move issue to Idea
+  #       if: ${{ env.PROJECT_TOKEN != '' && env.PROJECT_ID != '{{PROJECT_ID}}' }}
+  #       uses: actions/github-script@v7
+  #       with:
+  #         github-token: ${{ env.PROJECT_TOKEN }}
+  #         script: |
+  #           const { issue: { number, node_id } } = context.payload;
+  #           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: node_id });
+  #           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_IDEA }
+  #             });
+  #           console.log(`Issue #${number} moved to Idea`);
 
   # PR Opened → Move linked issue to Code Review / PR
+  # 💡 VARIANT B (QA Agent): If using an AI QA agent, change `STATUS_CODE_REVIEW_PR` to `STATUS_TESTING` on line ~158
   move-card-on-pr-open:
     name: Open PR → Code Review / PR
     if: github.event_name == 'pull_request' && (github.event.action == 'opened' || github.event.action == 'reopened')
@@ -97,7 +125,7 @@ jobs:
       PROJECT_TOKEN: ${{ secrets.PROJECT_TOKEN }}
     steps:
       - name: Move linked issue to Code Review / PR
-        if: ${{ env.PROJECT_TOKEN != '' }}
+        if: ${{ env.PROJECT_TOKEN != '' && env.PROJECT_ID != '{{PROJECT_ID}}' }}
         uses: actions/github-script@v7
         with:
           github-token: ${{ env.PROJECT_TOKEN }}
@@ -151,7 +179,7 @@ jobs:
       PROJECT_TOKEN: ${{ secrets.PROJECT_TOKEN }}
     steps:
       - name: Swap PR labels
-        if: ${{ env.PROJECT_TOKEN != '' }}
+        if: ${{ env.PROJECT_TOKEN != '' && env.PROJECT_ID != '{{PROJECT_ID}}' }}
         uses: actions/github-script@v7
         with:
           github-token: ${{ env.PROJECT_TOKEN }}
@@ -170,7 +198,7 @@ jobs:
       PROJECT_TOKEN: ${{ secrets.PROJECT_TOKEN }}
     steps:
       - name: Move issue to Production
-        if: ${{ env.PROJECT_TOKEN != '' }}
+        if: ${{ env.PROJECT_TOKEN != '' && env.PROJECT_ID != '{{PROJECT_ID}}' }}
         uses: actions/github-script@v7
         with:
           github-token: ${{ env.PROJECT_TOKEN }}

package/.github/workflows/protect-workflows.yml

@@ -0,0 +1,21 @@
+name: Protect Workflows
+
+on:
+  pull_request:
+    types: [opened, synchronize, reopened, labeled]
+    paths:
+      - '.github/**'
+
+jobs:
+  block-unauthorized-edits:
+    name: Protect .github directory
+    runs-on: ubuntu-latest
+    steps:
+      - name: Check for Human Approval
+        if: ${{ !contains(github.event.pull_request.labels.*.name, 'human-approved') }}
+        run: |
+          echo "🚨 Modifications in the .github/ directory detected."
+          echo "As a security measure, this repository blocks workflow edits by default."
+          echo "If you are an AI Agent, do not add the approval label yourself."
+          echo "If you are the human owner, please add the 'human-approved' label to this PR to allow merging."
+          exit 1

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

@@ -0,0 +1,27 @@
+name: AI QA Agent
+on:
+  pull_request:
+    types: [opened, synchronize, reopened]
+
+permissions:
+  pull-requests: write
+  contents: read
+
+jobs:
+  qa:
+    name: Run AI QA Agent
+    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"
+        env:
+          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
+          PR_URL: ${{ github.event.pull_request.html_url }}

package/SETUP.md

@@ -114,57 +114,38 @@ git push
 
 ---
 
-## Step 7 — Populate the Initial Backlog
+## Step 7 — Ignite the Backlog
 
-For each known idea or feature, create an issue using the convention:
+Forget heavy templates and CLI commands. Just drop your raw idea and let the AI do the heavy lifting:
 
-```bash
-gh issue create \
-  --repo owner/repo \
-  --title "👤 US: [short description]" \
-  --body "**As** [user],
-**I want** [action],
-**so that** [benefit].
+1. Open your **GitHub Project** board.
+2. Under the **Idea** column, click **`+ Add item`**.
+3. Type your feature title and hit **Enter**.
+4. Select **Blank issue**.
+5. In the right sidebar, add a brief description of what you want.
+6. Ask your AI Assistant to read the issue and write the full specification!
+
+Your AI will handle the refinement and automatically move it to the `Specification` stage.
 
 ---
 
-Initial idea issue. Spec to be detailed."
-```
+## (Optional) Architecture Violation Integration
+
+If your project uses an automated architecture auditing tool (e.g., a CI job that creates issues with an `architecture-violation` label), you can easily integrate it with your project board.
 
-Move the issues to the `Idea` column on the board matching your setup.
+Simply open `.github/workflows/project-automation.yml` and uncomment the `move-violation-to-board` job in the `jobs` section. This will automatically move any issues labeled with `architecture-violation` to the `Idea` column on your board.
 
 ---
 
-## (Optional) Architecture Violation Integration
+## (Optional) AI QA Agent Integration (Variant B)
 
-If your project uses an automated architecture auditing tool (e.g., a CI job that creates issues with an `architecture-violation` label), the Setup Mode can automatically add a GitHub Actions job to `project-automation.yml` that moves these issues to the `Idea` column.
-
-If you skipped this during setup but want to add it later, you can append the following job to `.github/workflows/project-automation.yml` under the `jobs` section:
-
-```yaml
-  move-violation-to-board:
-    name: architecture-violation → 💡 Idea
-    if: github.event_name == 'issues' && github.event.label.name == 'architecture-violation'
-    runs-on: ubuntu-latest
-    steps:
-      - uses: actions/github-script@v7
-        with:
-          github-token: ${{ secrets.PROJECT_TOKEN }}
-          script: |
-            const issueNodeId = context.payload.issue.node_id;
-            const addResult = await github.graphql(`
-              mutation($p: ID!, $c: ID!) {
-                addProjectV2ItemById(input: {projectId: $p, contentId: $c}) { item { id } }
-              }`, { p: process.env.PROJECT_ID, c: issueNodeId });
-            const itemId = addResult.addProjectV2ItemById.item.id;
-            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: itemId, f: process.env.STATUS_FIELD_ID,
-                    v: { singleSelectOptionId: process.env.STATUS_IDEA } });
-```
+If you use an AI QA Agent (e.g., QAWolf, a secondary AI script) to test your PRs before Code Review, you can switch to **Variant B**.
+
+Simply open `.github/workflows/project-automation.yml`:
+1. In the `move-card-on-pr-open` job, change the PR destination from `STATUS_CODE_REVIEW_PR` to `STATUS_TESTING`.
+2. Uncomment the `move-card-on-qa-pass` job at the bottom of the file to move tested issues to `Code Review / PR` upon receiving a `qa:pass` label.
+
+If you don't use this, you can safely delete `templates/.github/workflows/qa-agent.yml`.
 
 ---
 

package/adapters/claude-code/skill.md

@@ -19,18 +19,21 @@ Specifically, check for:
 - `.github/workflows/pdlc-health-check.yml`
 
 If any of these files are missing, you are in **Setup Mode**. Do not proceed with feature requests until setup is complete.
-1. Acknowledge that the framework is not yet set up.
-2. Interactively ask the user for required values **one group at a time**:
+1. **Language Detection:** Analyze the user's previous prompts and preferred language. Conduct this entire Setup Mode and ask all your interactive questions in that same language.
+2. Acknowledge that the framework is not yet set up.
+3. Interactively ask the user for required values **one group at a time**:
    - **Project basics:** Project Name, Description, Technical Stack (Structure), and GitHub Username (for CODEOWNERS security).
    - **Commands:** Test command, Lint command, Build command.
    - **Invariants:** Critical business rules agents must never violate (e.g. Human-in-the-loop).
-   - **Board IDs:** PROJECT_ID, STATUS_FIELD_ID, column option IDs (provide standard PDLC options: Idea, Exploration, Brainstorming, Detail Solution, Approval, Development, Testing, Code Review / PR, Merge, Production). Allow user to answer "skip", which means you leave the placeholders intact.
-   - **Architecture Violation:** Ask "Does your project use an automated architecture auditing tool (e.g., a CI job that creates issues with an `architecture-violation` label)?". If yes, replace `{{OPTIONAL_ARCHITECTURE_VIOLATION_JOB}}` in `project-automation.yml` with the job definition (available in the framework documentation). If no, ask if they would like help implementing one, reminding them that it significantly improves their agentic development process. If they decline, remove the placeholder.
+   - **Board IDs:** PROJECT_ID, STATUS_FIELD_ID, column option IDs (provide standard PDLC options: Idea, Exploration, Brainstorming, Detail Solution, Approval, Development, Testing, Code Review / PR, Production). Allow user to answer "skip", which means you leave the placeholders intact.
+   - **Architecture Violation:** Ask "Does your project use an automated architecture auditing tool (e.g., a CI job that creates issues with an `architecture-violation` label)?". If yes, uncomment the `move-violation-to-board` job inside `project-automation.yml`. If no, ask if they would like help implementing one, reminding them that it significantly improves their agentic development process. If they decline, you can leave the job commented out.
+   - **QA Agent (Variant B):** Ask "Do you plan to use an AI QA Agent (e.g. QAWolf or a secondary script) to verify your PRs before Code Review?". If yes, explain you will adopt Variant B: you will change `STATUS_CODE_REVIEW_PR` to `STATUS_TESTING` inside the `move-card-on-pr-open` job in `project-automation.yml` and uncomment the `move-card-on-qa-pass` job. If no, leave the workflow as Variant A (default) and delete the optional `.github/workflows/qa-agent.yml` template.
    - **Implementation agent handle:** e.g., `@google-labs-jules`, or "none".
 3. Generate and write the missing files replacing the `{{SCREAMING_SNAKE_CASE}}` placeholders using the templates logic you know (usually they reside in standard Agentic PDLC templates).
 4. Offer to run the `gh` commands for labels (`spec:approved`, `pr:in-review`, `pr:approved`, `architecture-violation`).
 5. Commit everything with the message: `chore: setup agentic-pdlc framework`.
-6. Conclude Setup Mode.
+6. **IMPORTANT:** Delete this setup prompt file (e.g., `.agentic-setup.md`, `.agentic-setup-prompt.md`, or `.agentic-pdlc/SETUP_PROMPT.md`) from the root or `.agentic-pdlc/` directory to clean up the workspace.
+7. Conclude Setup Mode.
 
 ---
 

package/bin/cli.js

@@ -3,6 +3,7 @@
 const fs = require('fs');
 const path = require('path');
 const readline = require('readline');
+const { execSync, execFileSync } = require('child_process');
 
 // The directory where CLI is executed
 const targetDir = process.cwd();
@@ -14,13 +15,72 @@ const rl = readline.createInterface({
   output: process.stdout
 });
 
+function askQuestion(query) {
+  return new Promise(resolve => rl.question(query, resolve));
+}
+
+// Detect language
+const locale = Intl.DateTimeFormat().resolvedOptions().locale || 'en-US';
+const isPt = locale.toLowerCase().startsWith('pt');
+const isEs = locale.toLowerCase().startsWith('es');
+
+function t(en, pt, es) {
+  if (isPt) return pt;
+  if (isEs) return es || en; // Fallback para inglês se faltar espanhol
+  return en;
+}
+
+const i18n = {
+  welcome: t('🤖 Welcome to Agentic PDLC Boilerplate Bootstrap! 🤖', '🤖 Bem-vindo ao Agentic PDLC Boilerplate Bootstrap! 🤖', '🤖 ¡Bienvenido a Agentic PDLC Boilerplate Bootstrap! 🤖'),
+  checking_gh: t('Checking GitHub CLI (gh) installation...', 'Verificando instalação do GitHub CLI (gh)...', 'Verificando la instalación de GitHub CLI (gh)...'),
+  gh_ok: t('✅ GitHub CLI is authenticated.', '✅ GitHub CLI está autenticado.', '✅ GitHub CLI está autenticado.'),
+  gh_error: t('❌ GitHub CLI (gh) is not installed or not authenticated.', '❌ GitHub CLI (gh) não está instalado ou não autenticado.', '❌ GitHub CLI (gh) no está instalado o no está autenticado.'),
+  gh_install: t('Please install it from https://cli.github.com/ and run "gh auth login" before continuing.\n', 'Por favor, instale em https://cli.github.com/ e rode "gh auth login" antes de continuar.\n', 'Por favor, instálalo desde https://cli.github.com/ y ejecuta "gh auth login" antes de continuar.\n'),
+  ask_agent: t('Which AI Agent will you use for the setup? (e.g. claude, cursor, copilot, antigravity, or other): ', 'Qual Agente de IA você usará para o setup? (ex: claude, cursor, copilot, antigravity, ou outro): ', '¿Qué Agente de IA usarás para la configuración? (ej: claude, cursor, copilot, antigravity, u otro): '),
+  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: '),
+  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.'),
+  scaffolding: t('Scaffolding Agentic PDLC into your project...', 'Injetando Agentic PDLC no seu projeto...', 'Inyectando Agentic PDLC en tu proyecto...'),
+  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')
+};
+
 const cyan = '\x1b[36m';
 const reset = '\x1b[0m';
 const green = '\x1b[32m';
 const yellow = '\x1b[33m';
+const red = '\x1b[31m';
 
 console.log(`${cyan}================================================================${reset}`);
-console.log(`${cyan}🤖 Welcome to Agentic PDLC Boilerplate Bootstrap! 🤖${reset}`);
+console.log(`${cyan}${i18n.welcome}${reset}`);
 console.log(`${cyan}================================================================${reset}\n`);
 
 // Helper function to recursively copy directories
@@ -39,10 +99,169 @@ function copyDirSync(src, dest) {
   }
 }
 
-rl.question('Which AI Agent will you use for the setup? (e.g. claude, cursor, copilot, or other): ', (answer) => {
-  const agent = answer.trim().toLowerCase();
-  
-  console.log(`\n${yellow}Scaffolding Agentic PDLC into your project...${reset}`);
+async function runSetup() {
+  console.log(`${yellow}${i18n.checking_gh}${reset}`);
+  try {
+    execSync('gh auth status', { stdio: 'ignore' });
+    console.log(`${green}${i18n.gh_ok}${reset}\n`);
+  } catch (error) {
+    console.error(`${red}${i18n.gh_error}${reset}`);
+    console.error(`${i18n.gh_install}`);
+    process.exit(1);
+  }
+
+  const agentAnswer = await askQuestion(i18n.ask_agent);
+  const agent = agentAnswer.trim().toLowerCase();
+  if (!['claude', 'cursor', 'copilot'].includes(agent)) {
+    console.log(t(`ℹ️ Generating Universal Setup for '${agent}' (Compatible with any Markdown-reading agent).`, `ℹ️ Gerando Setup Universal para '${agent}' (Compatível com qualquer agente que leia Markdown).`, `ℹ️ Generando Setup Universal para '${agent}' (Compatible con cualquier agente que lea Markdown).`));
+  }
+
+  let repoOwner, repoName, repo;
+  while (true) {
+    let repoUrl = (await askQuestion(i18n.ask_repo)).trim();
+    if (repoUrl.endsWith('/')) repoUrl = repoUrl.slice(0, -1);
+    if (repoUrl.endsWith('.git')) repoUrl = repoUrl.slice(0, -4);
+    const repoParts = repoUrl.split('/');
+    if (repoParts.length >= 2) {
+      repoOwner = repoParts[repoParts.length - 2];
+      repoName = repoParts[repoParts.length - 1];
+      repo = `${repoOwner}/${repoName}`;
+      break;
+    }
+    console.log(`${red}${i18n.invalid_repo}${reset}`);
+  }
+
+  const askProjectName = t(`What is the project name for the board? (default: ${repoName.toUpperCase()}): `, `Qual o nome do projeto em que o board será configurado? (padrão: ${repoName.toUpperCase()}): `, `¿Cuál es el nombre del proyecto en el que se configurará el board? (por defecto: ${repoName.toUpperCase()}): `);
+  const projectNameAnswer = await askQuestion(askProjectName);
+  const projectName = projectNameAnswer.trim() ? projectNameAnswer.trim().toUpperCase() : repoName.toUpperCase();
+  const boardName = `BOARD - ${projectName}`;
+
+  let isOrg = false;
+  try {
+    const ownerType = execFileSync('gh', ['api', `repos/${repo}`, '--jq', '.owner.type']).toString().trim();
+    isOrg = ownerType === 'Organization';
+  } catch (err) {
+    const accountTypeAnswer = await askQuestion(i18n.ask_org);
+    isOrg = accountTypeAnswer.trim().toLowerCase() === 'org' || accountTypeAnswer.trim().toLowerCase() === 'organization';
+  }
+
+  let branchName = 'main';
+  try {
+    branchName = execFileSync('gh', ['api', `repos/${repo}`, '--jq', '.default_branch']).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
+  const labels = [
+    { name: 'stage:exploration', color: '9b59b6', description: 'Issue is being evaluated' },
+    { name: 'stage:brainstorming', color: 'e84393', description: 'Proposed approaches awaiting PM gate' },
+    { name: 'stage:detailing', color: '3498db', description: 'Technical spec is being written' },
+    { name: 'stage:development', color: 'e67e22', description: 'Agent is implementing the spec' },
+    { name: 'stage:testing', color: '8e44ad', description: 'Agent is testing the implementation' },
+    { name: 'spec:approved', color: '0e8a16', description: 'Spec approved — agent can implement' },
+    { name: 'pr:in-review', color: 'e4e669', description: 'PR awaiting code review' },
+    { name: 'pr:approved', color: '0e8a16', description: 'PR approved, ready for merge' },
+    { 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: 'jules', color: '5319e7', description: 'Jules AI Agent' }
+  ];
+
+  console.log(`\n${cyan}${i18n.creating_labels}${reset}`);
+  for (const label of labels) {
+    try {
+      execFileSync('gh', ['label', 'create', label.name, '--color', label.color, '--description', label.description, '--repo', repo, '--force'], { stdio: 'ignore' });
+      console.log(`  ${i18n.label_ok}${label.name}`);
+    } catch (err) {
+      console.log(`  ${i18n.label_warn}${label.name}`);
+    }
+  }
+
+  // Project V2
+  console.log(`\n${cyan}${i18n.creating_project}${reset}`);
+  let ownerId, projectId;
+  try {
+    if (isOrg) {
+      const orgOutput = execFileSync('gh', ['api', 'graphql', '-f', 'query=query($login: String!) { organization(login: $login) { id } }', '-f', `login=${repoOwner}`, '--jq', '.data.organization.id']).toString().trim();
+      ownerId = orgOutput;
+    } else {
+      const userOutput = execFileSync('gh', ['api', 'graphql', '-f', 'query={ viewer { id } }', '--jq', '.data.viewer.id']).toString().trim();
+      ownerId = userOutput;
+    }
+
+    const projectCreateOutput = execFileSync('gh', ['api', 'graphql', '-f', 'query=mutation($owner: ID!, $title: String!) { createProjectV2(input: {ownerId: $owner, title: $title}) { projectV2 { id } } }', '-f', `owner=${ownerId}`, '-f', `title=${boardName}`, '--jq', '.data.createProjectV2.projectV2.id']).toString().trim();
+    projectId = projectCreateOutput;
+
+    console.log(`  ${i18n.project_ok}${projectId})`);
+  } catch (err) {
+    console.log(`  ${i18n.project_err}${err.message}`);
+  }
+
+  let statusFieldId;
+  let optionMap = {};
+
+  if (projectId) {
+    console.log(`  ${cyan}${i18n.config_columns}${reset}`);
+    try {
+      const fieldsOutput = execFileSync('gh', ['api', 'graphql', '-f', 'query=query($projectId: ID!) { node(id: $projectId) { ... on ProjectV2 { fields(first: 20) { nodes { ... on ProjectV2SingleSelectField { id name } } } } } }', '-f', `projectId=${projectId}`, '--jq', '.data.node.fields.nodes[] | select(.name == "Status") | .id']).toString().trim();
+      statusFieldId = fieldsOutput;
+
+      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" }
+        ];
+
+        const updateFieldQuery = `mutation($projectId: ID!, $fieldId: ID!, $options: [ProjectV2SingleSelectFieldOptionInput!]) {
+          updateProjectV2Field(input: {
+            projectId: $projectId,
+            fieldId: $fieldId,
+            singleSelectOptions: $options
+          }) { 
+            projectV2Field { 
+              ... on ProjectV2SingleSelectField {
+                options { id name } 
+              }
+            } 
+          }
+        }`;
+
+        const queryPayload = JSON.stringify({
+          query: updateFieldQuery,
+          variables: {
+            projectId: projectId,
+            fieldId: statusFieldId,
+            options: columns
+          }
+        });
+
+        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;
+        }
+
+        console.log(`  ${i18n.columns_ok}`);
+      }
+    } catch (err) {
+      console.log(`  ${i18n.columns_warn}`);
+    }
+  }
+
+  console.log(`\n${yellow}${i18n.scaffolding}${reset}`);
 
   // We copy the templates folder so the agent has the real text logic to replace and rename
   const sourceTemplates = path.join(sourceDir, 'templates');
@@ -50,7 +269,33 @@ rl.question('Which AI Agent will you use for the setup? (e.g. claude, cursor, co
   
   if (fs.existsSync(sourceTemplates)) {
     copyDirSync(sourceTemplates, targetTemplates);
-    console.log(`✅ Templates copied to .agentic-pdlc/templates/`);
+    console.log(`${i18n.templates_copied}`);
+
+    // Substitute values in docs/pdlc.md automatically
+    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);
+      pdlcContent = pdlcContent.replace(/\\{\\{REPO_NAME\\}\\}/g, () => repoName);
+
+      if (Object.keys(optionMap).length > 0) {
+        pdlcContent = pdlcContent.replace(/\{\{ID_IDEA\}\}/g, optionMap["💡 Idea"] || 'MISSING_ID');
+        pdlcContent = pdlcContent.replace(/\{\{ID_EXPLORATION\}\}/g, optionMap["🔍 Exploration"] || 'MISSING_ID');
+        pdlcContent = pdlcContent.replace(/\{\{ID_BRAINSTORMING\}\}/g, optionMap["🧠 Brainstorming"] || 'MISSING_ID');
+        pdlcContent = pdlcContent.replace(/\{\{ID_DETAIL\}\}/g, optionMap["📐 Detail Solution"] || 'MISSING_ID');
+        pdlcContent = pdlcContent.replace(/\{\{ID_APPROVAL\}\}/g, optionMap["✅ Approval"] || 'MISSING_ID');
+        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');
+      }
+
+      fs.writeFileSync(pdlcDest, pdlcContent);
+      console.log(`${i18n.pdlc_prefilled}`);
+    }
   }
 
   // Handle the specific setup instructions target
@@ -61,15 +306,19 @@ rl.question('Which AI Agent will you use for the setup? (e.g. claude, cursor, co
     if (fs.existsSync(claudeSetupSrc)) {
       const dest = path.join(targetDir, '.agentic-setup.md');
       fs.copyFileSync(claudeSetupSrc, dest);
-      console.log(`✅ Setup agent profile written to .agentic-setup.md`);
-      console.log(`\n${green}🎉 Done! To start the conversational setup:${reset}`);
-      console.log(`${cyan}\tStep 1: Open the Claude Code CLI in your terminal (type 'claude')${reset}`);
-      console.log(`${cyan}\t        [Or open your preferred IDE Agent chat, like Antigravity, Cursor, Codex, GitHub Copilot, etc]${reset}`);
-      console.log(`${cyan}\tStep 2: Paste this exact prompt:${reset}`);
-      console.log(`${yellow}\t        "read .agentic-setup.md to enter Setup Mode."${reset}`);
-      console.log(`\nNote: Once setup is completed, the agent will typically delete .agentic-setup.md to keep your root clean.\n`);
+      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}`);
     } else {
-      console.error(`❌ Could not find claude instruction file at ${claudeSetupSrc}`);
+      console.error(`${i18n.missing_claude}${claudeSetupSrc}`);
     }
   } else if (agent === 'cursor') {
     if (fs.existsSync(cursorSetupSrc)) {
@@ -81,22 +330,24 @@ rl.question('Which AI Agent will you use for the setup? (e.g. claude, cursor, co
       const setupPromptDest = path.join(targetDir, '.agentic-pdlc', 'SETUP_PROMPT.md');
       if (fs.existsSync(claudeSetupSrc)) fs.copyFileSync(claudeSetupSrc, setupPromptDest);
 
-      console.log(`✅ Default cursor rules written to .cursorrules`);
-      console.log(`✅ Framework Setup Instructions written to .agentic-pdlc/SETUP_PROMPT.md`);
-      console.log(`\n${green}🎉 Done! To start the conversational setup:${reset}`);
-      console.log(`${cyan}\t1. Open Cursor${reset}`);
-      console.log(`${cyan}\t2. Open Composer (Cmd+I or Cmd+L) and type: "@.agentic-pdlc/SETUP_PROMPT.md execute Setup Mode"${reset}\n`);
+      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}`);
     } else {
-      console.error(`❌ Could not find cursor instruction file at ${cursorSetupSrc}`);
+      console.error(`${i18n.missing_claude}${cursorSetupSrc}`);
     }
   } else {
     // Generic fallback mapping
-    const dest = path.join(targetDir, '.agentic-setup-prompt.md');
+    const dest = path.join(targetDir, '.agentic-setup.md');
     fs.copyFileSync(claudeSetupSrc, dest);
-    console.log(`✅ Agent generic setup instructions written to .agentic-setup-prompt.md`);
-    console.log(`\n${green}🎉 Done! To start the conversational setup:${reset}`);
-    console.log(`${cyan}Provide the .agentic-setup-prompt.md file to your AI agent and ask it to execute Setup Mode!${reset}\n`);
+    console.log(`${i18n.generic_written}`);
+    console.log(`\n${green}${i18n.cursor_done}${reset}`);
+    console.log(`${cyan}>>> ${i18n.generic_done}${reset}`);
   }
 
   rl.close();
-});
+}
+
+runSetup();

package/docs/pdlc.md

@@ -12,7 +12,6 @@
 | ⚙️ Development | Agent implementing the spec | Label `stage:development` |
 | 🧪 Testing | CI pipeline running | GitHub Actions |
 | 👁 Code Review / PR | PR opened, awaiting human review | GitHub Actions |
-| 🔀 Merge | PR approved, awaiting merge | GitHub Actions |
 | 🚀 Production | Merged | GitHub Actions |
 
 <!--
@@ -40,7 +39,6 @@ REPO         = {{REPO_OWNER}}/{{REPO_NAME}}
 | ⚙️ Development | `{{ID_DEVELOPMENT}}` |
 | 🧪 Testing | `{{ID_TESTING}}` |
 | 👁 Code Review / PR | `{{ID_CODE_REVIEW_PR}}` |
-| 🔀 Merge | `{{ID_MERGE}}` |
 | 🚀 Production | `{{ID_PRODUCTION}}` |
 
 ## Agent × Phase Mapping

package/package.json

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

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

@@ -20,7 +20,7 @@ jobs:
       PROJECT_TOKEN: ${{ secrets.PROJECT_TOKEN }}
     steps:
       - name: Update Labels
-        if: ${{ env.PROJECT_TOKEN != '' }}
+        if: ${{ env.PROJECT_TOKEN != '' && !contains('{{IMPLEMENTATION_AGENT_LABEL}}', '{{') }}
         uses: actions/github-script@v7
         with:
           github-token: ${{ env.PROJECT_TOKEN }}
@@ -33,20 +33,21 @@ jobs:
                 owner,
                 repo,
                 issue_number,
-                name: 'upstream:approval'
+                name: 'stage:approval'
               });
             } catch (error) {
-              console.log('Label upstream:approval not found or could not be removed');
+              console.log('Label stage:approval not found or could not be removed');
             }
             
             await github.rest.issues.addLabels({
               owner,
               repo,
               issue_number,
-              labels: ['upstream:development', '{{IMPLEMENTATION_AGENT_LABEL}}', 'agent:working']
+              labels: ['stage:development', '{{IMPLEMENTATION_AGENT_LABEL}}', 'agent:working']
             });
 
       - name: Comment on issue to trigger agent and prevent race conditions
+        if: ${{ !contains('{{IMPLEMENTATION_AGENT_LABEL}}', '{{') }}
         uses: actions/github-script@v7
         with:
           github-token: ${{ secrets.GITHUB_TOKEN }}
@@ -89,6 +90,7 @@ jobs:
       contents: read
     steps:
       - name: Comment on issue to trigger agent
+        if: ${{ !contains('{{IMPLEMENTATION_AGENT_LABEL}}', '{{') }}
         uses: actions/github-script@v7
         with:
           github-token: ${{ secrets.GITHUB_TOKEN }}

package/templates/.github/workflows/auto-approve.yml

@@ -0,0 +1,16 @@
+name: Auto Approve PRs
+on:
+  pull_request:
+    types: [opened, labeled, synchronize]
+
+permissions:
+  pull-requests: write
+
+jobs:
+  auto-approve:
+    runs-on: ubuntu-latest
+    if: contains(github.event.pull_request.labels.*.name, 'auto-approve')
+    steps:
+      - uses: hmarr/auto-approve-action@v4
+        with:
+          github-token: ${{ secrets.GITHUB_TOKEN }}

package/templates/.github/workflows/ci.yml

@@ -20,13 +20,21 @@ jobs:
         run: echo "Replace this with your package manager install command"
 
       - name: Run Linters
-        run: {{LINT_COMMAND}}
+        if: ${{ !contains('{{LINT_COMMAND}}', '{{') }}
+        run: |
+          {{LINT_COMMAND}}
 
       - name: Typecheck
-        run: {{TYPECHECK_COMMAND}}
+        if: ${{ !contains('{{TYPECHECK_COMMAND}}', '{{') }}
+        run: |
+          {{TYPECHECK_COMMAND}}
 
       - name: Build
-        run: {{BUILD_COMMAND}}
+        if: ${{ !contains('{{BUILD_COMMAND}}', '{{') }}
+        run: |
+          {{BUILD_COMMAND}}
 
       - name: Run Tests
-        run: {{TEST_COMMAND}}
+        if: ${{ !contains('{{TEST_COMMAND}}', '{{') }}
+        run: |
+          {{TEST_COMMAND}}

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

@@ -11,6 +11,7 @@ on:
 env:
   PROJECT_ID: "{{PROJECT_ID}}"
   STATUS_FIELD_ID: "{{STATUS_FIELD_ID}}"
+  STATUS_IDEA: "{{ID_IDEA}}"
   STATUS_EXPLORATION: "{{ID_EXPLORATION}}"
   STATUS_BRAINSTORMING: "{{ID_BRAINSTORMING}}"
   STATUS_DETAILING: "{{ID_DETAILING}}"
@@ -30,7 +31,7 @@ jobs:
       PROJECT_TOKEN: ${{ secrets.PROJECT_TOKEN }}
     steps:
       - name: Detect Label and Move Issue
-        if: ${{ env.PROJECT_TOKEN != '' }}
+        if: ${{ env.PROJECT_TOKEN != '' && env.PROJECT_ID != '{{PROJECT_ID}}' }}
         uses: actions/github-script@v7
         with:
           github-token: ${{ env.PROJECT_TOKEN }}
@@ -39,28 +40,28 @@ jobs:
             let targetStatusId = null;
             let stageName = null;
 
-            if (labelName === 'upstream:exploration') {
+            if (labelName === 'stage:exploration') {
               targetStatusId = process.env.STATUS_EXPLORATION;
               stageName = 'Exploration';
-            } else if (labelName === 'upstream:brainstorming') {
+            } else if (labelName === 'stage:brainstorming') {
               targetStatusId = process.env.STATUS_BRAINSTORMING;
               stageName = 'Brainstorming';
-            } else if (labelName === 'upstream:detailing') {
+            } else if (labelName === 'stage:detailing') {
               targetStatusId = process.env.STATUS_DETAILING;
               stageName = 'Detailing';
-            } else if (labelName === 'upstream:approval') {
+            } else if (labelName === 'stage:approval') {
               targetStatusId = process.env.STATUS_APPROVAL;
               stageName = 'Approval';
-            } else if (labelName === 'upstream:development') {
+            } else if (labelName === 'stage:development') {
               targetStatusId = process.env.STATUS_DEVELOPMENT;
               stageName = 'Development';
-            } else if (labelName === 'upstream:testing') {
+            } else if (labelName === 'stage:testing') {
               targetStatusId = process.env.STATUS_TESTING;
               stageName = 'Testing';
             }
 
             if (!targetStatusId) {
-              console.log('No upstream PDLC label found. Skipping.');
+              console.log('No stage PDLC label found. Skipping.');
               return;
             }
 
@@ -86,9 +87,36 @@ jobs:
             await moveItem(node_id, targetStatusId);
             console.log(`Issue #${number} moved to ${stageName}`);
 
-{{OPTIONAL_ARCHITECTURE_VIOLATION_JOB}}
+  # OPTIONAL: Uncomment to enable architecture-violation → Idea
+  # move-violation-to-board:
+  #   name: architecture-violation → 💡 Idea
+  #   if: github.event_name == 'issues' && github.event.action == 'labeled' && github.event.label.name == 'architecture-violation'
+  #   runs-on: ubuntu-latest
+  #   steps:
+  #     - name: Move issue to Idea
+  #       if: ${{ env.PROJECT_TOKEN != '' && env.PROJECT_ID != '{{PROJECT_ID}}' }}
+  #       uses: actions/github-script@v7
+  #       with:
+  #         github-token: ${{ env.PROJECT_TOKEN }}
+  #         script: |
+  #           const { issue: { number, node_id } } = context.payload;
+  #           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: node_id });
+  #           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_IDEA }
+  #             });
+  #           console.log(`Issue #${number} moved to Idea`);
 
   # PR Opened → Move linked issue to Code Review / PR
+  # 💡 VARIANT B (QA Agent): If using an AI QA agent, change `STATUS_CODE_REVIEW_PR` to `STATUS_TESTING` on line ~158
   move-card-on-pr-open:
     name: Open PR → Code Review / PR
     if: github.event_name == 'pull_request' && (github.event.action == 'opened' || github.event.action == 'reopened')
@@ -97,7 +125,7 @@ jobs:
       PROJECT_TOKEN: ${{ secrets.PROJECT_TOKEN }}
     steps:
       - name: Move linked issue to Code Review / PR
-        if: ${{ env.PROJECT_TOKEN != '' }}
+        if: ${{ env.PROJECT_TOKEN != '' && env.PROJECT_ID != '{{PROJECT_ID}}' }}
         uses: actions/github-script@v7
         with:
           github-token: ${{ env.PROJECT_TOKEN }}
@@ -151,7 +179,7 @@ jobs:
       PROJECT_TOKEN: ${{ secrets.PROJECT_TOKEN }}
     steps:
       - name: Swap PR labels
-        if: ${{ env.PROJECT_TOKEN != '' }}
+        if: ${{ env.PROJECT_TOKEN != '' && env.PROJECT_ID != '{{PROJECT_ID}}' }}
         uses: actions/github-script@v7
         with:
           github-token: ${{ env.PROJECT_TOKEN }}
@@ -170,7 +198,7 @@ jobs:
       PROJECT_TOKEN: ${{ secrets.PROJECT_TOKEN }}
     steps:
       - name: Move issue to Production
-        if: ${{ env.PROJECT_TOKEN != '' }}
+        if: ${{ env.PROJECT_TOKEN != '' && env.PROJECT_ID != '{{PROJECT_ID}}' }}
         uses: actions/github-script@v7
         with:
           github-token: ${{ env.PROJECT_TOKEN }}

package/templates/.github/workflows/protect-workflows.yml

@@ -0,0 +1,21 @@
+name: Protect Workflows
+
+on:
+  pull_request:
+    types: [opened, synchronize, reopened, labeled]
+    paths:
+      - '.github/**'
+
+jobs:
+  block-unauthorized-edits:
+    name: Protect .github directory
+    runs-on: ubuntu-latest
+    steps:
+      - name: Check for Human Approval
+        if: ${{ !contains(github.event.pull_request.labels.*.name, 'human-approved') }}
+        run: |
+          echo "🚨 Modifications in the .github/ directory detected."
+          echo "As a security measure, this repository blocks workflow edits by default."
+          echo "If you are an AI Agent, do not add the approval label yourself."
+          echo "If you are the human owner, please add the 'human-approved' label to this PR to allow merging."
+          exit 1

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

@@ -0,0 +1,27 @@
+name: AI QA Agent
+on:
+  pull_request:
+    types: [opened, synchronize, reopened]
+
+permissions:
+  pull-requests: write
+  contents: read
+
+jobs:
+  qa:
+    name: Run AI QA Agent
+    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"
+        env:
+          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
+          PR_URL: ${{ github.event.pull_request.html_url }}

package/templates/docs/pdlc.md

@@ -10,9 +10,8 @@
 | 📐 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 running | GitHub Actions |
-| 👁 Code Review / PR | PR opened, awaiting human review | GitHub Actions |
-| 🔀 Merge | PR approved, awaiting merge | GitHub Actions |
+| 🧪 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 |
 
 <!--
@@ -20,6 +19,11 @@ Adapt columns as needed. The functional baseline is:
 💡 Idea → ⚙️ Development → 👁 Code Review / PR → 🚀 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)
 
 ```
@@ -40,7 +44,6 @@ REPO         = {{REPO_OWNER}}/{{REPO_NAME}}
 | ⚙️ Development | `{{ID_DEVELOPMENT}}` |
 | 🧪 Testing | `{{ID_TESTING}}` |
 | 👁 Code Review / PR | `{{ID_CODE_REVIEW_PR}}` |
-| 🔀 Merge | `{{ID_MERGE}}` |
 | 🚀 Production | `{{ID_PRODUCTION}}` |
 
 ## Agent × Phase Mapping

package/templates/.github/workflows/upstream-gate.yml

@@ -1,54 +0,0 @@
-name: Upstream Gate 1
-
-on:
-  issue_comment:
-    types: [created]
-
-jobs:
-  evaluate-gate:
-    name: Evaluate Brainstorming Approval
-    if: ${{ !github.event.issue.pull_request && contains(github.event.issue.labels.*.name, 'upstream:brainstorming') }}
-    runs-on: ubuntu-latest
-    env:
-      PROJECT_TOKEN: ${{ secrets.PROJECT_TOKEN }}
-    steps:
-      - name: Check for approval and swap label
-        if: ${{ env.PROJECT_TOKEN != '' }}
-        uses: actions/github-script@v7
-        with:
-          github-token: ${{ env.PROJECT_TOKEN }}
-          script: |
-            const comment = context.payload.comment.body.toLowerCase();
-            const isApproved = 
-              comment.includes('approved') || 
-              comment.includes('lgtm') || 
-              /option\s+[a-z0-9]/i.test(comment) ||
-              /go\s+with\s+[a-z0-9]/i.test(comment) ||
-              /proceed/i.test(comment);
-
-            if (isApproved) {
-              const { owner, repo } = context.repo;
-              const issue_number = context.payload.issue.number;
-
-              console.log('Approval detected, swapping labels...');
-
-              try {
-                await github.rest.issues.removeLabel({
-                  owner,
-                  repo,
-                  issue_number,
-                  name: 'upstream:brainstorming'
-                });
-              } catch (e) {
-                console.log('Could not remove upstream:brainstorming label');
-              }
-
-              await github.rest.issues.addLabels({
-                owner,
-                repo,
-                issue_number,
-                labels: ['upstream:detailing']
-              });
-            } else {
-              console.log('No approval pattern detected in the comment.');
-            }