create-agentic-pdlc 2.0.0 → 2.0.3

package/.github/CODEOWNERS

@@ -0,0 +1,5 @@
+# This file prevents autonomous agents from modifying core security, automation, and instruction rules
+# without explicit approval from the repository owner.
+
+.github/ @rafaeltcosta86
+AGENTS.md @rafaeltcosta86

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/AGENTS.md

@@ -27,13 +27,14 @@ Always start from the current `main` HEAD. Never work over stale snapshots.
 ## Mandatory Workflow
 
 0. **Identity**: Always prefix your GitHub comments with `🤖 **Agent:** ` to distinguish yourself.
-1. Read the issue entirely — understand its type (US/BUG/TASK/SPIKE) and the Acceptance Criteria.
-2. Read `docs/pdlc.md` — understand the PDLC and the Definition of Done in this project.
-3. Read all files mentioned in the issue's technical context.
-4. Implement the **minimum viable change** that satisfies the ACs — do not refactor beyond scope.
-5. Run tests: `echo "No tests/build needed."`
-6. Run typecheck: `echo "No typecheck needed."`
-7. Create a Pull Request with `Closes #N` in the body — automation moves the board.
+1. **Initial State**: When beginning work on a new issue, your very first action must be to apply the `stage:exploration` label using the GitHub CLI (`gh issue edit <N> --add-label "stage:exploration"`).
+2. Read the issue entirely — understand its type (US/BUG/TASK/SPIKE) and the Acceptance Criteria.
+3. Read `docs/pdlc.md` — understand the PDLC and the Definition of Done in this project.
+4. Read all files mentioned in the issue's technical context.
+5. Implement the **minimum viable change** that satisfies the ACs — do not refactor beyond scope.
+6. Run tests: `echo "No tests/build needed."`
+7. Run typecheck: `echo "No typecheck needed."`
+8. Create a Pull Request with `Closes #N` in the body — automation moves the board.
 
 ## What NOT to do
 

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/bin/cli.js

@@ -63,8 +63,10 @@ rl.question('Which AI Agent will you use for the setup? (e.g. claude, cursor, co
       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}\t1. Type 'claude'${reset}`);
-      console.log(`${cyan}\t2. Ask Claude to "read .agentic-setup.md to enter Setup Mode."${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`);
     } else {
       console.error(`❌ Could not find claude instruction file at ${claudeSetupSrc}`);

package/docs/flow.md

@@ -2,6 +2,19 @@
 
 This document describes the full lifecycle of a card on the agentic-pdlc board — who acts at each stage, what triggers each transition, which labels are added or removed, and where human gates are required.
 
+```mermaid
+stateDiagram-v2
+    direction LR
+    Idea --> Exploration : stage:exploration
+    Exploration --> Brainstorming : stage:brainstorming
+    Brainstorming --> Detailing : Gate 1 (PM)
+    Detailing --> Approval : stage:approval
+    Approval --> Development : Gate 2 (spec:approved)
+    Development --> Testing : stage:testing
+    Testing --> CodeReview : PR Opened
+    CodeReview --> Production : Gate 3 (PR Merged)
+```
+
 ---
 
 ## Roles
@@ -21,17 +34,17 @@ This document describes the full lifecycle of a card on the agentic-pdlc board
 ## Step-by-Step Flow
 
 ### 💡 Idea
-Issue exists in the backlog with no `upstream:` label.
+Issue exists in the backlog with no `stage:` label.
 
 ---
 
 ### 🔍 Exploration
 
 **Trigger (two equivalent paths):**
-- PM tells Claude directly in chat → Claude adds `upstream:exploration` to the issue, OR
-- PM adds `upstream:exploration` directly to the issue
+- PM tells Claude directly in chat → Claude adds `stage:exploration` to the issue, OR
+- PM adds `stage:exploration` directly to the issue
 
-**Workflow:** `project-automation.yml` detects `upstream:exploration` → moves card to Exploration.
+**Workflow:** `project-automation.yml` detects `stage:exploration` → moves card to Exploration.
 
 **Who works:** Claude reads relevant code and context.
 
@@ -43,7 +56,7 @@ Issue exists in the backlog with no `upstream:` label.
 
 **Actions:**
 - Claude posts a comment on the issue with findings and 2–3 proposed approaches
-- Claude swaps `upstream:exploration` → `upstream:brainstorming`
+- Claude swaps `stage:exploration` → `stage:brainstorming`
 
 **Workflow:** `project-automation.yml` moves card to Brainstorming.
 
@@ -57,14 +70,14 @@ Issue exists in the backlog with no `upstream:` label.
 
 ### 📐 Detail Solution ← Gate 1
 
-**Trigger:** `upstream-gate.yml` detects PM approval comment on a `upstream:brainstorming` issue → swaps `upstream:brainstorming` → `upstream:detailing` via `PROJECT_TOKEN`.
+**Trigger:** `upstream-gate.yml` detects PM approval comment on a `stage:brainstorming` issue → swaps `stage:brainstorming` → `stage:detailing` via `PROJECT_TOKEN`.
 
 **Who works:** Claude rewrites the issue body with:
 1. User story (`As… I want… So that…`)
 2. Acceptance Criteria (AC1, AC2, …)
 3. Files to modify
 
-**After spec is written:** Claude swaps `upstream:detailing` → `upstream:approval`.
+**After spec is written:** Claude swaps `stage:detailing` → `stage:approval`.
 
 **Workflow:** `project-automation.yml` moves card to Approval.
 
@@ -75,8 +88,8 @@ Issue exists in the backlog with no `upstream:` label.
 **⏸ Human gate (Gate 2 — PM + TL):** Both PM (business decisions) and TL (technical decisions) review the spec. When both are satisfied, PM adds label `spec:approved`.
 
 **Workflow:** `agent-trigger.yml` detects `spec:approved` →
-1. Removes `upstream:approval`
-2. Adds `upstream:development`
+1. Removes `stage:approval`
+2. Adds `stage:development`
 3. Adds specific agent label (e.g., `jules`)
 4. Posts a structured comment with implementation instructions for the Agent
 
@@ -88,7 +101,7 @@ Issue exists in the backlog with no `upstream:` label.
 
 **Who works:** Implementation Agent implements the spec strictly within the Acceptance Criteria.
 
-**When done:** Agent adds `upstream:testing` before running tests.
+**When done:** Agent adds `stage:testing` before running tests.
 
 **Workflow:** `project-automation.yml` moves card to Testing.
 
@@ -128,12 +141,12 @@ Issue exists in the backlog with no `upstream:` label.
 
 | Label | Added by | Removed by |
 |-------|----------|------------|
-| `upstream:exploration` | PM (human) or Claude | Claude |
-| `upstream:brainstorming` | Claude | `upstream-gate.yml` |
-| `upstream:detailing` | `upstream-gate.yml` | Claude |
-| `upstream:approval` | Claude | `agent-trigger.yml` |
-| `upstream:development` | `agent-trigger.yml` | Impl. Agent |
-| `upstream:testing` | Impl. Agent | `project-automation.yml` (on PR open) |
+| `stage:exploration` | PM (human) or Claude | Claude |
+| `stage:brainstorming` | Claude | `upstream-gate.yml` |
+| `stage:detailing` | `upstream-gate.yml` | Claude |
+| `stage:approval` | Claude | `agent-trigger.yml` |
+| `stage:development` | `agent-trigger.yml` | Impl. Agent |
+| `stage:testing` | Impl. Agent | `project-automation.yml` (on PR open) |
 | `spec:approved` | PM (human) | — |
 | `agent_label` (e.g. `jules`, `sweep`) | `agent-trigger.yml` | — |
 | `pr:in-review` | `project-automation.yml` | `project-automation.yml` |

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,7 +1,7 @@
 {
   "name": "create-agentic-pdlc",
-  "version": "2.0.0",
-  "description": "Scaffold the Agentic PDLC framework effortlessly",
+  "version": "2.0.3",
+  "description": "Agentic PDLC Framework - Conversational setup for your AI coding assistants",
   "type": "commonjs",
   "bin": {
     "create-agentic-pdlc": "./bin/cli.js"

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/AGENTS.md

@@ -30,13 +30,14 @@ Always start from the current `main` HEAD. Never work over stale snapshots.
 ## Mandatory Workflow
 
 0. **Identity**: Always prefix your GitHub comments with `🤖 **Agent:** ` to distinguish yourself.
-1. Read the issue entirely — understand its type (US/BUG/TASK/SPIKE) and the Acceptance Criteria.
-2. Read `docs/pdlc.md` — understand the PDLC and the Definition of Done in this project.
-3. Read all files mentioned in the issue's technical context.
-4. Implement the **minimum viable change** that satisfies the ACs — do not refactor beyond scope.
-5. Run tests: `{{TEST_COMMAND}}`
-6. Run typecheck (if applicable): `{{TYPECHECK_COMMAND}}`
-7. Create a Pull Request with `Closes #N` in the body — automation moves the board.
+1. **Initial State**: When beginning work on a new issue, your very first action must be to apply the `stage:exploration` label using the GitHub CLI (`gh issue edit <N> --add-label "stage:exploration"`).
+2. Read the issue entirely — understand its type (US/BUG/TASK/SPIKE) and the Acceptance Criteria.
+3. Read `docs/pdlc.md` — understand the PDLC and the Definition of Done in this project.
+4. Read all files mentioned in the issue's technical context.
+5. Implement the **minimum viable change** that satisfies the ACs — do not refactor beyond scope.
+6. Run tests: `{{TEST_COMMAND}}`
+7. Run typecheck (if applicable): `{{TYPECHECK_COMMAND}}`
+8. Create a Pull Request with `Closes #N` in the body — automation moves the board.
 
 ### Spec format (Upstream Agents)
 

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