create-agentic-pdlc 2.0.1 → 2.0.3

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

@@ -137,34 +137,21 @@ Move the issues to the `Idea` column on the board matching your setup.
 
 ## (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), 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 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.
+
+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) AI QA Agent Integration (Variant B)
+
+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

@@ -24,8 +24,9 @@ If any of these files are missing, you are in **Setup Mode**. Do not proceed wit
    - **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`).

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.3",
   "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.');
-            }