create-agentic-pdlc 2.1.5 → 2.2.0

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

@@ -0,0 +1,278 @@
+name: PDLC Board Automation
+
+on:
+  pull_request:
+    types: [opened, reopened, closed, labeled]
+  pull_request_review:
+    types: [submitted]
+  issues:
+    types: [labeled]
+
+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}}"
+  STATUS_APPROVAL: "{{ID_APPROVAL}}"
+  STATUS_DEVELOPMENT: "{{ID_DEVELOPMENT}}"
+  STATUS_TESTING: "{{ID_TESTING}}"
+  STATUS_CODE_REVIEW_PR: "{{ID_CODE_REVIEW_PR}}"
+  STATUS_PRODUCTION: "{{ID_PRODUCTION}}"
+
+jobs:
+  # Issue Labeled → Move Upstream
+  move-card-on-label:
+    name: Upstream Label → Move Card
+    if: github.event_name == 'issues' && github.event.action == 'labeled'
+    runs-on: ubuntu-latest
+    env:
+      PROJECT_PAT: ${{ secrets.PROJECT_PAT }}
+    steps:
+      - name: Detect Label and Move Issue
+        if: ${{ env.PROJECT_PAT != '' && env.PROJECT_ID != '{{PROJECT_ID}}' }}
+        uses: actions/github-script@v7
+        with:
+          github-token: ${{ env.PROJECT_PAT }}
+          script: |
+            const labelName = context.payload.label.name;
+            let targetStatusId = null;
+            let stageName = null;
+
+            if (labelName === 'stage:exploration') {
+              targetStatusId = process.env.STATUS_EXPLORATION;
+              stageName = 'Exploration';
+            } else if (labelName === 'stage:brainstorming') {
+              targetStatusId = process.env.STATUS_BRAINSTORMING;
+              stageName = 'Brainstorming';
+            } else if (labelName === 'stage:detailing') {
+              targetStatusId = process.env.STATUS_DETAILING;
+              stageName = 'Detailing';
+            } else if (labelName === 'stage:approval') {
+              targetStatusId = process.env.STATUS_APPROVAL;
+              stageName = 'Approval';
+            } else if (labelName === 'stage:development') {
+              targetStatusId = process.env.STATUS_DEVELOPMENT;
+              stageName = 'Development';
+            } else if (labelName === 'stage:testing') {
+              targetStatusId = process.env.STATUS_TESTING;
+              stageName = 'Testing';
+            }
+
+            if (!targetStatusId) {
+              console.log('No stage PDLC label found. Skipping.');
+              return;
+            }
+
+            const { issue: { number, node_id } } = context.payload;
+
+            const moveItem = async (nodeId, statusId) => {
+              const { addProjectV2ItemById: { item } } = await github.graphql(`
+                mutation($p: ID!, $c: ID!) {
+                  addProjectV2ItemById(input: {projectId: $p, contentId: $c}) { item { id } }
+                }`, { p: process.env.PROJECT_ID, c: nodeId });
+
+              await github.graphql(`
+                mutation($p: ID!, $i: ID!, $f: ID!, $v: ProjectV2FieldValue!) {
+                  updateProjectV2ItemFieldValue(input: {projectId: $p, itemId: $i, fieldId: $f, value: $v}) {
+                    projectV2Item { id }
+                  }
+                }`, {
+                  p: process.env.PROJECT_ID, i: item.id, f: process.env.STATUS_FIELD_ID,
+                  v: { singleSelectOptionId: statusId }
+                });
+            };
+
+            await moveItem(node_id, targetStatusId);
+            console.log(`Issue #${number} moved to ${stageName}`);
+
+  # 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_PAT != '' && env.PROJECT_ID != '{{PROJECT_ID}}' }}
+  #       uses: actions/github-script@v7
+  #       with:
+  #         github-token: ${{ env.PROJECT_PAT }}
+  #         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 Testing (Variant B — QA Agent enabled)
+  move-card-on-pr-open:
+    name: Open PR → Testing
+    if: github.event_name == 'pull_request' && (github.event.action == 'opened' || github.event.action == 'reopened')
+    runs-on: ubuntu-latest
+    env:
+      PROJECT_PAT: ${{ secrets.PROJECT_PAT }}
+    steps:
+      - name: Move linked issue to Testing
+        if: ${{ env.PROJECT_PAT != '' && env.PROJECT_ID != '{{PROJECT_ID}}' }}
+        uses: actions/github-script@v7
+        with:
+          github-token: ${{ env.PROJECT_PAT }}
+          script: |
+            const prNumber = context.payload.pull_request.number;
+            const { owner, repo } = context.repo;
+
+            const { data: pr } = await github.rest.pulls.get({ owner, repo, pull_number: prNumber });
+            const body = pr.body ?? '';
+
+            // Extract issues linked via "Closes #N", "Fixes #N", "Resolves #N"
+            const linkedIssues = [...body.matchAll(/(?:Closes?|Fixes?|Resolves?)\s+#(\d+)/gi)]
+              .map(m => parseInt(m[1]));
+
+            const moveItem = async (nodeId) => {
+              const { addProjectV2ItemById: { item } } = await github.graphql(`
+                mutation($p: ID!, $c: ID!) {
+                  addProjectV2ItemById(input: {projectId: $p, contentId: $c}) { item { id } }
+                }`, { p: process.env.PROJECT_ID, c: nodeId });
+
+              await github.graphql(`
+                mutation($p: ID!, $i: ID!, $f: ID!, $v: ProjectV2FieldValue!) {
+                  updateProjectV2ItemFieldValue(input: {projectId: $p, itemId: $i, fieldId: $f, value: $v}) {
+                    projectV2Item { id }
+                  }
+                }`, {
+                  p: process.env.PROJECT_ID, i: item.id, f: process.env.STATUS_FIELD_ID,
+                  v: { singleSelectOptionId: process.env.STATUS_TESTING }
+                });
+            };
+
+            if (linkedIssues.length > 0) {
+              for (const n of linkedIssues) {
+                const { data: issue } = await github.rest.issues.get({ owner, repo, issue_number: n });
+                await moveItem(issue.node_id);
+                console.log(`Issue #${n} → Testing`);
+              }
+            } else {
+              await moveItem(pr.node_id);
+              console.log(`PR #${prNumber} → Testing (no linked issue)`);
+            }
+
+            await github.rest.issues.addLabels({ owner, repo, issue_number: prNumber, labels: ['pr:in-review'] }).catch(() => {});
+
+  # QA Approved → Move linked issue to Code Review / PR
+  move-card-on-qa-pass:
+    name: qa:approved → Code Review / PR
+    if: github.event_name == 'pull_request' && github.event.action == 'labeled' && github.event.label.name == 'qa:approved'
+    runs-on: ubuntu-latest
+    env:
+      PROJECT_PAT: ${{ secrets.PROJECT_PAT }}
+    steps:
+      - name: Move linked issue to Code Review / PR
+        if: ${{ env.PROJECT_PAT != '' && env.PROJECT_ID != '{{PROJECT_ID}}' }}
+        uses: actions/github-script@v7
+        with:
+          github-token: ${{ env.PROJECT_PAT }}
+          script: |
+            const prNumber = context.payload.pull_request.number;
+            const { owner, repo } = context.repo;
+            const { data: pr } = await github.rest.pulls.get({ owner, repo, pull_number: prNumber });
+            const body = pr.body ?? '';
+            const linkedIssues = [...body.matchAll(/(?:Closes?|Fixes?|Resolves?)\s+#(\d+)/gi)].map(m => parseInt(m[1]));
+            const moveItem = async (nodeId) => {
+              const { addProjectV2ItemById: { item } } = await github.graphql(`
+                mutation($p: ID!, $c: ID!) {
+                  addProjectV2ItemById(input: {projectId: $p, contentId: $c}) { item { id } }
+                }`, { p: process.env.PROJECT_ID, c: nodeId });
+              await github.graphql(`
+                mutation($p: ID!, $i: ID!, $f: ID!, $v: ProjectV2FieldValue!) {
+                  updateProjectV2ItemFieldValue(input: {projectId: $p, itemId: $i, fieldId: $f, value: $v}) {
+                    projectV2Item { id }
+                  }
+                }`, {
+                  p: process.env.PROJECT_ID, i: item.id, f: process.env.STATUS_FIELD_ID,
+                  v: { singleSelectOptionId: process.env.STATUS_CODE_REVIEW_PR }
+                });
+            };
+            if (linkedIssues.length > 0) {
+              for (const n of linkedIssues) {
+                const { data: issue } = await github.rest.issues.get({ owner, repo, issue_number: n });
+                await moveItem(issue.node_id);
+                console.log(`Issue #${n} → Code Review / PR`);
+              }
+            } else {
+              await moveItem(pr.node_id);
+              console.log(`PR #${prNumber} → Code Review / PR (no linked issue)`);
+            }
+
+  # Review Approved → Add Label
+  move-card-on-review-approved:
+    name: Approved PR → Add Label
+    if: github.event_name == 'pull_request_review' && github.event.review.state == 'approved'
+    runs-on: ubuntu-latest
+    env:
+      PROJECT_PAT: ${{ secrets.PROJECT_PAT }}
+    steps:
+      - name: Swap PR labels
+        if: ${{ env.PROJECT_PAT != '' && env.PROJECT_ID != '{{PROJECT_ID}}' }}
+        uses: actions/github-script@v7
+        with:
+          github-token: ${{ env.PROJECT_PAT }}
+          script: |
+            const prNumber = context.payload.pull_request.number;
+            const { owner, repo } = context.repo;
+            try { await github.rest.issues.removeLabel({ owner, repo, issue_number: prNumber, name: 'pr:in-review' }); } catch {}
+            await github.rest.issues.addLabels({ owner, repo, issue_number: prNumber, labels: ['pr:approved'] }).catch(() => {});
+
+  # PR Merged → Production
+  move-card-on-pr-merge:
+    name: Merged PR → Production
+    if: github.event_name == 'pull_request' && github.event.action == 'closed' && github.event.pull_request.merged == true
+    runs-on: ubuntu-latest
+    env:
+      PROJECT_PAT: ${{ secrets.PROJECT_PAT }}
+    steps:
+      - name: Move issue to Production
+        if: ${{ env.PROJECT_PAT != '' && env.PROJECT_ID != '{{PROJECT_ID}}' }}
+        uses: actions/github-script@v7
+        with:
+          github-token: ${{ env.PROJECT_PAT }}
+          script: |
+            const prNumber = context.payload.pull_request.number;
+            const { owner, repo } = context.repo;
+            const { data: pr } = await github.rest.pulls.get({ owner, repo, pull_number: prNumber });
+            const body = pr.body ?? '';
+            const linkedIssues = [...body.matchAll(/(?:Closes?|Fixes?|Resolves?)\s+#(\d+)/gi)].map(m => parseInt(m[1]));
+
+            const moveItem = async (nodeId) => {
+              const { addProjectV2ItemById: { item } } = await github.graphql(`
+                mutation($p: ID!, $c: ID!) {
+                  addProjectV2ItemById(input: {projectId: $p, contentId: $c}) { item { id } }
+                }`, { p: process.env.PROJECT_ID, c: nodeId });
+              await github.graphql(`
+                mutation($p: ID!, $i: ID!, $f: ID!, $v: ProjectV2FieldValue!) {
+                  updateProjectV2ItemFieldValue(input: {projectId: $p, itemId: $i, fieldId: $f, value: $v}) {
+                    projectV2Item { id }
+                  }
+                }`, { p: process.env.PROJECT_ID, i: item.id, f: process.env.STATUS_FIELD_ID,
+                      v: { singleSelectOptionId: process.env.STATUS_PRODUCTION } });
+            };
+
+            if (linkedIssues.length > 0) {
+              for (const n of linkedIssues) {
+                const { data: issue } = await github.rest.issues.get({ owner, repo, issue_number: n });
+                await moveItem(issue.node_id);
+                console.log(`Issue #${n} → Production`);
+              }
+            } else {
+              await moveItem(pr.node_id);
+            }

package/.agentic-pdlc/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/.agentic-pdlc/templates/.github/workflows/qa-agent.yml

@@ -0,0 +1,128 @@
+name: AI QA Agent
+on:
+  pull_request:
+    types: [opened, synchronize, reopened]
+
+permissions:
+  pull-requests: write
+  contents: read
+  issues: read
+  models: read
+
+jobs:
+  qa:
+    name: AC Coverage Verification (GitHub Models)
+    runs-on: ubuntu-latest
+    env:
+      PROJECT_PAT: ${{ secrets.PROJECT_PAT }}
+      PROJECT_ID: "{{PROJECT_ID}}"
+      STATUS_FIELD_ID: "{{STATUS_FIELD_ID}}"
+      STATUS_CODE_REVIEW_PR: "{{ID_CODE_REVIEW_PR}}"
+    steps:
+      - uses: actions/checkout@v4
+        with:
+          fetch-depth: 0
+
+      - name: Verify AC Coverage via GitHub Models
+        env:
+          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
+        run: |
+          set -e
+
+          PR_NUMBER="${{ github.event.pull_request.number }}"
+          BASE="${{ github.event.pull_request.base.sha }}"
+          HEAD="${{ github.event.pull_request.head.sha }}"
+
+          # Get PR diff (truncated to 8000 chars to stay within context limits)
+          DIFF=$(git diff "$BASE" "$HEAD" | head -c 64000)
+
+          # Extract linked issues from PR body
+          PR_BODY=$(gh pr view "$PR_NUMBER" --json body --jq '.body // ""')
+          ISSUE_NUMS=$(echo "$PR_BODY" | grep -oiE '(Closes?|Fixes?|Resolves?)\s+#([0-9]+)' | grep -oE '[0-9]+' || true)
+
+          # Build acceptance criteria context
+          AC_CONTEXT=""
+          if [ -n "$ISSUE_NUMS" ]; then
+            for NUM in $ISSUE_NUMS; do
+              ISSUE_BODY=$(gh issue view "$NUM" --json body --jq '.body // ""' 2>/dev/null || echo "")
+              AC_CONTEXT="${AC_CONTEXT}\\n\\n--- Issue #${NUM} ---\\n${ISSUE_BODY}"
+            done
+          fi
+
+          if [ -z "$AC_CONTEXT" ]; then
+            AC_CONTEXT="No linked issue found. Evaluate if the PR description is self-contained."
+          fi
+
+          # Serialize prompt as JSON string and call GitHub Models API (30s timeout)
+          PROMPT_JSON=$(printf '%s' "You are a senior QA engineer. Review whether this PR diff satisfies the Acceptance Criteria below.\n\nACCEPTANCE CRITERIA:\n${AC_CONTEXT}\n\nPR DIFF:\n${DIFF}\n\nFirst line of your response must be exactly one word: PASS or FAIL. Second line: brief explanation (max 3 sentences)." | python3 -c 'import json,sys; print(json.dumps(sys.stdin.read()))')
+
+          RESPONSE=$(curl -sf -X POST \
+            "https://models.github.ai/inference/chat/completions" \
+            -H "Authorization: Bearer ${GITHUB_TOKEN}" \
+            -H "Content-Type: application/json" \
+            -d "{\"model\":\"gpt-4o-mini\",\"messages\":[{\"role\":\"user\",\"content\":${PROMPT_JSON}}]}" \
+            --max-time 30 || echo "API_ERROR")
+
+          if [ "$RESPONSE" = "API_ERROR" ]; then
+            gh pr edit "$PR_NUMBER" --add-label "infra:qa-broken"
+            gh pr comment "$PR_NUMBER" --body "🤖 **QA Agent:** Could not reach GitHub Models API. Manual review required."
+            exit 0
+          fi
+
+          VERDICT=$(echo "$RESPONSE" | python3 -c 'import json,sys,re; d=json.load(sys.stdin); t=d.get("choices",[{}])[0].get("message",{}).get("content","").strip(); first=t.split("\n")[0].upper() if t else ""; print("FAIL" if re.search(r"\bFAIL\b",first) else "PASS" if re.search(r"\bPASS\b",first) else "API_ERROR")')
+          EXPLANATION=$(echo "$RESPONSE" | python3 -c 'import json,sys; d=json.load(sys.stdin); t=d.get("choices",[{}])[0].get("message",{}).get("content","").strip(); lines=t.split("\n",1); print(lines[1].strip() if len(lines)>1 else "")')
+
+          if echo "$VERDICT" | grep -q "^PASS"; then
+            gh pr edit "$PR_NUMBER" --add-label "qa:approved"
+            gh pr comment "$PR_NUMBER" --body "🤖 **QA Agent:** AC coverage verified. ${EXPLANATION}"
+          elif echo "$VERDICT" | grep -q "^FAIL"; then
+            gh pr edit "$PR_NUMBER" --add-label "qa:needs-work"
+            gh pr comment "$PR_NUMBER" --body "🤖 **QA Agent:** AC coverage insufficient. ${EXPLANATION}"
+          else
+            gh pr edit "$PR_NUMBER" --add-label "infra:qa-broken"
+            gh pr comment "$PR_NUMBER" --body "🤖 **QA Agent:** Could not parse GitHub Models response. Manual review required."
+          fi
+
+      - name: Move board card to Code Review on qa:approved
+        if: ${{ env.PROJECT_PAT != '' && env.PROJECT_ID != '{{PROJECT_ID}}' }}
+        uses: actions/github-script@v7
+        with:
+          github-token: ${{ env.PROJECT_PAT }}
+          script: |
+            const prNumber = context.payload.pull_request.number;
+            const { owner, repo } = context.repo;
+
+            const { data: pr } = await github.rest.pulls.get({ owner, repo, pull_number: prNumber });
+            if (!pr.labels.some(l => l.name === 'qa:approved')) {
+              console.log('qa:approved not on PR — skipping board move');
+              return;
+            }
+
+            const body = pr.body ?? '';
+            const linkedIssues = [...body.matchAll(/(?:Closes?|Fixes?|Resolves?)\s+#(\d+)/gi)]
+              .map(m => parseInt(m[1]));
+
+            const moveItem = async (nodeId) => {
+              const { addProjectV2ItemById: { item } } = await github.graphql(`
+                mutation($p: ID!, $c: ID!) {
+                  addProjectV2ItemById(input: {projectId: $p, contentId: $c}) { item { id } }
+                }`, { p: process.env.PROJECT_ID, c: nodeId });
+              await github.graphql(`
+                mutation($p: ID!, $i: ID!, $f: ID!, $v: ProjectV2FieldValue!) {
+                  updateProjectV2ItemFieldValue(input: {projectId: $p, itemId: $i, fieldId: $f, value: $v}) {
+                    projectV2Item { id }
+                  }
+                }`, { p: process.env.PROJECT_ID, i: item.id, f: process.env.STATUS_FIELD_ID,
+                     v: { singleSelectOptionId: process.env.STATUS_CODE_REVIEW_PR } });
+            };
+
+            if (linkedIssues.length > 0) {
+              for (const n of linkedIssues) {
+                const { data: issue } = await github.rest.issues.get({ owner, repo, issue_number: n });
+                await moveItem(issue.node_id);
+                console.log(`Issue #${n} → Code Review / PR`);
+              }
+            } else {
+              await moveItem(pr.node_id);
+              console.log(`PR #${prNumber} → Code Review / PR (no linked issue)`);
+            }

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

@@ -0,0 +1,81 @@
+# {{PROJECT_NAME}} — AI Agent Instructions
+
+This template is the contract between the project and any external AI agent 
+(Claude Code, Cursor, Copilot, Jules, Codex, Sweep, etc.). Read this before committing any change.
+
+## Project Overview
+
+{{PROJECT_DESCRIPTION}}
+
+**Structure:**
+{{PROJECT_STRUCTURE}}
+
+## Before Any Change
+
+```bash
+git fetch origin && git checkout main && git pull
+```
+
+Always start from the current `main` HEAD. Never work over stale snapshots.
+
+## Invariants / Non-negotiable business rules
+
+{{INVARIANTS}}
+<!-- Examples:
+1. **Human-in-the-Loop** — No external side-effect actions without explicit human approval.
+2. **Immutable Audit-Log** — It's strictly forbidden to UPDATE/DELETE on audit_log; INSERT only.
+3. **Credential Isolation** — Decryption occurs only in a specific service.
+-->
+
+## Mandatory Workflow
+
+0. **Identity**: Always prefix your GitHub comments with `🤖 **Agent:** ` to distinguish yourself.
+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)
+
+When detailing a solution in an issue body, you must **always** include both the user story and the acceptance criteria. Never append only the ACs to an existing text; rewrite the full issue body in this standard format:
+
+```
+**As** [user],
+**I want** [action],
+**so that** [benefit].
+
+---
+
+## Acceptance Criteria
+
+**AC1 — ...**
+- Given ...
+- When ...
+- Then ...
+
+**AC2 — ...**
+...
+
+## Files to modify
+- `path/to/file.ts` — what changes
+```
+
+## What NOT to do
+
+- Never commit directly to `main`.
+- Never open a PR without passing the tests.
+- Never implement beyond the immediate scope of the issue.
+- Never create future-proofing abstractions for hypothetical features.
+{{EXTRA_DONT}}
+
+## Project Standards
+
+- **Tests:** `{{TEST_COMMAND}}`
+- **Lint/Types:** `{{LINT_COMMAND}}`
+- **Typecheck:** `{{TYPECHECK_COMMAND}}`
+- **Build:** `{{BUILD_COMMAND}}`
+{{EXTRA_PATTERNS}}

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

@@ -4,7 +4,7 @@
 
 | Column | Meaning | Who moves the card |
 |---|---|---|
-| 💡 Idea | Backlog — every new issue lands here | Manual |
+| 💡 Idea — don't move manually to Exploration | Backlog — tell agent: "work on issue #XX" | Don't move manually |
 | 🔍 Exploration | Claude is analyzing code and context | Label `stage:exploration` |
 | 🧠 Brainstorming | Claude proposed approaches, awaiting PM gate | Label `stage:brainstorming` |
 | 📐 Detail Solution | Claude is writing the technical spec | Label `stage:detailing` |
@@ -77,6 +77,10 @@ REPO         = {{REPO_OWNER}}/{{REPO_NAME}}
 | `spec:approved` | Issue | Green | Gate 2 — agent is cleared to implement |
 | `pr:in-review` | PR | Yellow | Awaiting code review |
 | `pr:approved` | PR | Green | Code review approved |
+| `type:us` | Issue | Blue | New feature or behavioral change — full flow |
+| `type:task` | Issue | Yellow | Operational/non-functional change — skips brainstorming |
+| `type:bug` | Issue | Red | Something broken — skips brainstorming |
+| `type:spike` | Issue | Gray | Research/evaluation — never reaches Development |
 
 ## Approval Gates
 
@@ -90,10 +94,16 @@ This triggers the implementation agent via `agent-trigger.yml`.
 
 ## Shortcuts by Type
 
-- **BUG** — Skips Brainstorming; enters Detail Solution with diagnostics + fix.
-- **TASK** — Skips Brainstorming; enters Detail Solution with operational steps.
-- **SPIKE** — Never reaches Development; delivery is a concluding comment.
-- **US** — Full flow observing both gates.
+The `type:*` label is the authoritative signal — set automatically by the agent via type inference (see `adapters/claude-code/skill.md`). Title prefixes (`🔧 TASK:`, `👤 US:`) are hints for humans; the label drives the flow.
+
+| Label | Flow |
+|---|---|
+| `type:us` | Full flow — exploration → brainstorming → Gate 1 → detailing → approval |
+| `type:task` | Skips brainstorming — exploration → detailing → approval |
+| `type:bug` | Skips brainstorming — exploration → detailing → approval |
+| `type:spike` | Skips brainstorming — exploration → detailing → conclusion comment (never reaches Development) |
+
+If no `type:*` label present and agent confidence < 85%, defaults to `type:us` (safe fallback — never skips gates by omission).
 
 ## Definition of Done
 

package/.agentic-setup-prompt.md

@@ -0,0 +1,73 @@
+---
+name: agentic-pdlc
+description: Orchestrates the Agentic Product Development Life Cycle (PDLC) upstream stages (Idea -> Spec) and includes an interactive Setup Mode to initialize the framework.
+---
+
+# Agentic PDLC Orchestrator
+
+You are the upstream brainstorm partner and orchestrator for the Agentic PDLC framework. Your role is primarily to define technical specs based on user ideas.
+
+## SETUP MODE
+
+If the user invokes you in a new project, you must first check if the PDLC artifacts are present in the repository.
+Specifically, check for:
+- `AGENTS.md`
+- `docs/pdlc.md`
+- `.github/CODEOWNERS`
+- `.github/workflows/project-automation.yml`
+- `.github/workflows/agent-trigger.yml`
+- `.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. **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, 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. **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.
+
+---
+
+## EXECUTION MODE
+
+If `AGENTS.md` and `docs/pdlc.md` are present, you are in **Execution Mode**. 
+
+### 1. Daily Upstream Loop
+Your job is to move issues from "Idea" to "Detail Solution".
+When asked to work on a feature, you will:
+- Explore the code context.
+- Present architectural approaches (Brainstorming).
+- Stop and wait for the human PM's explicit approval (Gate 1).
+
+### 2. Creating the Spec
+Once approved, you will detail the solution directly into the GitHub Issue body. Focus on precise Acceptance Criteria.
+**IMPORTANT:** You must always rewrite the full issue body to include both the user story and the Acceptance Criteria. Do not simply append the ACs to the existing text. Use this format:
+
+```
+**As** [user],
+**I want** [action],
+**so that** [benefit].
+
+---
+
+## Acceptance Criteria
+...
+```
+
+### 3. Handoff
+Do not write code for downstream features! Your goal is to refine the Spec, so the human Tech Lead can label the issue `spec:approved`. This label triggers the downstream agent via `agent-trigger.yml`.
+
+### 4. Moving the Board (Upstream States)
+As you actively work with the user advancing the feature, you MUST use the GitHub CLI to update internal state labels. This triggers GitHub Actions behind the scenes.
+- Starting context evaluation: Run `gh issue edit <N> --add-label "stage:exploration"`
+- Presenting architecture/approaches: Run `gh issue edit <N> --add-label "stage:brainstorming"`
+- Starting to write the technical spec: Run `gh issue edit <N> --add-label "stage:detailing"`