create-agentic-pdlc 2.2.1 → 2.4.0

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

@@ -6,13 +6,12 @@ on:
   pull_request_review:
     types: [submitted]
   issues:
-    types: [labeled, edited]
+    types: [labeled, edited, closed]
 
 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}}"
@@ -28,22 +27,19 @@ jobs:
     if: github.event_name == 'issues' && github.event.action == 'labeled'
     runs-on: ubuntu-latest
     env:
-      PROJECT_PAT: ${{ secrets.PROJECT_PAT }}
+      PROJECT_TOKEN: ${{ secrets.PROJECT_TOKEN }}
     steps:
       - name: Detect Label and Move Issue
-        if: ${{ env.PROJECT_PAT != '' && env.PROJECT_ID != '{{PROJECT_ID}}' }}
-        uses: actions/github-script@v7
+        if: ${{ env.PROJECT_TOKEN != '' && env.PROJECT_ID != '{{PROJECT_ID}}' }}
+        uses: actions/github-script@v8
         with:
-          github-token: ${{ env.PROJECT_PAT }}
+          github-token: ${{ env.PROJECT_TOKEN }}
           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') {
+            if (labelName === 'stage:brainstorming') {
               targetStatusId = process.env.STATUS_BRAINSTORMING;
               stageName = 'Brainstorming';
             } else if (labelName === 'stage:detailing') {
@@ -55,9 +51,6 @@ jobs:
             } 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) {
@@ -95,13 +88,13 @@ jobs:
       contains(github.event.issue.labels.*.name, 'stage:detailing')
     runs-on: ubuntu-latest
     env:
-      PROJECT_PAT: ${{ secrets.PROJECT_PAT }}
+      PROJECT_TOKEN: ${{ secrets.PROJECT_TOKEN }}
     steps:
       - name: Check spec markers and swap labels
-        if: ${{ env.PROJECT_PAT != '' && env.PROJECT_ID != '{{PROJECT_ID}}' }}
-        uses: actions/github-script@v7
+        if: ${{ env.PROJECT_TOKEN != '' && env.PROJECT_ID != '{{PROJECT_ID}}' }}
+        uses: actions/github-script@v8
         with:
-          github-token: ${{ env.PROJECT_PAT }}
+          github-token: ${{ env.PROJECT_TOKEN }}
           script: |
             const body = context.payload.issue.body ?? '';
             if (!body.includes('## Acceptance Criteria') || !body.includes('## Files to modify')) return;
@@ -113,6 +106,42 @@ jobs:
             await github.rest.issues.removeLabel({ owner, repo, issue_number, name: 'stage:detailing' }).catch(() => {});
             console.log(`Issue #${issue_number} auto-moved to stage:approval`);
 
+  # human-approved on issue → qa:approved on linked open PRs
+  handle-human-approved:
+    name: human-approved → qa:approved on linked PRs
+    if: github.event_name == 'issues' && github.event.action == 'labeled' && github.event.label.name == 'human-approved'
+    runs-on: ubuntu-latest
+    permissions:
+      issues: write
+      pull-requests: write
+    steps:
+      - name: Add qa:approved to linked open PRs
+        uses: actions/github-script@v8
+        with:
+          github-token: ${{ secrets.GITHUB_TOKEN }}
+          script: |
+            const { owner, repo } = context.repo;
+            const issueNumber = context.payload.issue.number;
+            const pattern = new RegExp(`(?:Closes?|Fixes?|Resolves?)\\s+#${issueNumber}\\b`, 'i');
+
+            const prs = await github.paginate(github.rest.pulls.list, {
+              owner, repo, state: 'open', per_page: 100
+            });
+
+            const linked = prs.filter(pr => pattern.test(pr.body ?? ''));
+
+            if (linked.length === 0) {
+              console.log(`No open PRs linking issue #${issueNumber}. Exiting.`);
+              return;
+            }
+
+            for (const pr of linked) {
+              await github.rest.issues.addLabels({
+                owner, repo, issue_number: pr.number, labels: ['qa:approved']
+              }).catch(() => {});
+              console.log(`PR #${pr.number} → qa:approved`);
+            }
+
   # OPTIONAL: Uncomment to enable architecture-violation → Idea
   # move-violation-to-board:
   #   name: architecture-violation → 💡 Idea
@@ -120,10 +149,10 @@ jobs:
   #   runs-on: ubuntu-latest
   #   steps:
   #     - name: Move issue to Idea
-  #       if: ${{ env.PROJECT_PAT != '' && env.PROJECT_ID != '{{PROJECT_ID}}' }}
-  #       uses: actions/github-script@v7
+  #       if: ${{ env.PROJECT_TOKEN != '' && env.PROJECT_ID != '{{PROJECT_ID}}' }}
+  #       uses: actions/github-script@v8
   #       with:
-  #         github-token: ${{ env.PROJECT_PAT }}
+  #         github-token: ${{ env.PROJECT_TOKEN }}
   #         script: |
   #           const { issue: { number, node_id } } = context.payload;
   #           const { addProjectV2ItemById: { item } } = await github.graphql(`
@@ -147,13 +176,13 @@ jobs:
     if: github.event_name == 'pull_request' && (github.event.action == 'opened' || github.event.action == 'reopened')
     runs-on: ubuntu-latest
     env:
-      PROJECT_PAT: ${{ secrets.PROJECT_PAT }}
+      PROJECT_TOKEN: ${{ secrets.PROJECT_TOKEN }}
     steps:
       - name: Move linked issue to Testing
-        if: ${{ env.PROJECT_PAT != '' && env.PROJECT_ID != '{{PROJECT_ID}}' }}
-        uses: actions/github-script@v7
+        if: ${{ env.PROJECT_TOKEN != '' && env.PROJECT_ID != '{{PROJECT_ID}}' }}
+        uses: actions/github-script@v8
         with:
-          github-token: ${{ env.PROJECT_PAT }}
+          github-token: ${{ env.PROJECT_TOKEN }}
           script: |
             const prNumber = context.payload.pull_request.number;
             const { owner, repo } = context.repo;
@@ -201,13 +230,13 @@ jobs:
     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 }}
+      PROJECT_TOKEN: ${{ secrets.PROJECT_TOKEN }}
     steps:
       - name: Move linked issue to Code Review / PR
-        if: ${{ env.PROJECT_PAT != '' && env.PROJECT_ID != '{{PROJECT_ID}}' }}
-        uses: actions/github-script@v7
+        if: ${{ env.PROJECT_TOKEN != '' && env.PROJECT_ID != '{{PROJECT_ID}}' }}
+        uses: actions/github-script@v8
         with:
-          github-token: ${{ env.PROJECT_PAT }}
+          github-token: ${{ env.PROJECT_TOKEN }}
           script: |
             const prNumber = context.payload.pull_request.number;
             const { owner, repo } = context.repo;
@@ -233,6 +262,9 @@ jobs:
               for (const n of linkedIssues) {
                 const { data: issue } = await github.rest.issues.get({ owner, repo, issue_number: n });
                 await moveItem(issue.node_id);
+                if (issue.labels?.some(l => l.name === 'stage:testing')) {
+                  await github.rest.issues.removeLabel({ owner, repo, issue_number: n, name: 'stage:testing' }).catch(() => {});
+                }
                 console.log(`Issue #${n} → Code Review / PR`);
               }
             } else {
@@ -246,13 +278,13 @@ jobs:
     if: github.event_name == 'pull_request_review' && github.event.review.state == 'approved'
     runs-on: ubuntu-latest
     env:
-      PROJECT_PAT: ${{ secrets.PROJECT_PAT }}
+      PROJECT_TOKEN: ${{ secrets.PROJECT_TOKEN }}
     steps:
       - name: Swap PR labels
-        if: ${{ env.PROJECT_PAT != '' && env.PROJECT_ID != '{{PROJECT_ID}}' }}
-        uses: actions/github-script@v7
+        if: ${{ env.PROJECT_TOKEN != '' && env.PROJECT_ID != '{{PROJECT_ID}}' }}
+        uses: actions/github-script@v8
         with:
-          github-token: ${{ env.PROJECT_PAT }}
+          github-token: ${{ env.PROJECT_TOKEN }}
           script: |
             const prNumber = context.payload.pull_request.number;
             const { owner, repo } = context.repo;
@@ -265,13 +297,13 @@ jobs:
     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 }}
+      PROJECT_TOKEN: ${{ secrets.PROJECT_TOKEN }}
     steps:
       - name: Move issue to Production
-        if: ${{ env.PROJECT_PAT != '' && env.PROJECT_ID != '{{PROJECT_ID}}' }}
-        uses: actions/github-script@v7
+        if: ${{ env.PROJECT_TOKEN != '' && env.PROJECT_ID != '{{PROJECT_ID}}' }}
+        uses: actions/github-script@v8
         with:
-          github-token: ${{ env.PROJECT_PAT }}
+          github-token: ${{ env.PROJECT_TOKEN }}
           script: |
             const prNumber = context.payload.pull_request.number;
             const { owner, repo } = context.repo;
@@ -297,8 +329,33 @@ jobs:
               for (const n of linkedIssues) {
                 const { data: issue } = await github.rest.issues.get({ owner, repo, issue_number: n });
                 await moveItem(issue.node_id);
+                if (issue.labels?.some(l => l.name === 'stage:approval')) {
+                  await github.rest.issues.removeLabel({ owner, repo, issue_number: n, name: 'stage:approval' }).catch(() => {});
+                }
                 console.log(`Issue #${n} → Production`);
               }
             } else {
               await moveItem(pr.node_id);
             }
+
+  cleanup-labels-on-close:
+    name: Issue closed → strip stage/agent labels
+    if: github.event_name == 'issues' && github.event.action == 'closed'
+    runs-on: ubuntu-latest
+    steps:
+      - name: Remove transient labels
+        uses: actions/github-script@v8
+        with:
+          github-token: ${{ secrets.GITHUB_TOKEN }}
+          script: |
+            const { owner, repo } = context.repo;
+            const issue_number = context.payload.issue.number;
+            const toRemove = [
+              'stage:brainstorming', 'stage:detailing',
+              'stage:approval', 'stage:development', 'stage:testing',
+              'qa:needs-work', 'pr:in-review', 'jules'
+            ];
+            for (const label of toRemove) {
+              await github.rest.issues.removeLabel({ owner, repo, issue_number, name: label }).catch(() => {});
+            }
+            console.log(`Issue #${issue_number} labels cleaned up`);

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

@@ -13,8 +13,10 @@ jobs:
   qa:
     name: AC Coverage Verification (GitHub Models)
     runs-on: ubuntu-latest
+    env:
+      PROJECT_TOKEN: ${{ secrets.PROJECT_TOKEN }}
     steps:
-      - uses: actions/checkout@v4
+      - uses: actions/checkout@v5.0.1
         with:
           fetch-depth: 0
 
@@ -29,7 +31,7 @@ jobs:
           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)
+          DIFF=$(git diff "$BASE" "$HEAD" | head -c 8000)
 
           # Extract linked issues from PR body
           PR_BODY=$(gh pr view "$PR_NUMBER" --json body --jq '.body // ""')
@@ -49,31 +51,45 @@ jobs:
           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()))')
+          PROMPT_JSON=$(printf '%s' "You are an adversarial product tester. Your mission is to find what the Acceptance Criteria do NOT cover — undefined edge cases, ambiguous states, missing user scenarios. Do NOT review code quality, file structure, or technical consistency.\n\nACCEPTANCE CRITERIA:\n${AC_CONTEXT}\n\nPR DIFF:\n${DIFF}\n\nRespond in exactly 3 lines (do NOT wrap your response in markdown code blocks or any other formatting):\nLine 1: PASS or FAIL (PASS if the PR diff fully satisfies the stated Acceptance Criteria, FAIL if it falls short of covering them)\nLine 2: Gaps: [one-line summary of AC gaps found, or \"none\"]\nLine 3: Not covered: [AC refs where diff falls short, or \"all covered\"]" | 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")
+          RESPONSE="API_ERROR"
+          for attempt in 1 2 3; do
+            RESULT=$(curl -s -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}}]}" \
+              -w "\n__HTTP_STATUS__:%{http_code}" \
+              --max-time 45 2>/dev/null)
+            HTTP_STATUS=$(echo "$RESULT" | grep -o '__HTTP_STATUS__:[0-9]*' | cut -d: -f2)
+            BODY=$(echo "$RESULT" | sed 's/__HTTP_STATUS__:[0-9]*$//')
+            echo "Attempt $attempt: HTTP $HTTP_STATUS"
+            if [ "$HTTP_STATUS" = "200" ]; then RESPONSE="$BODY"; break; fi
+            [ $attempt -lt 3 ] && sleep 20
+          done
 
           if [ "$RESPONSE" = "API_ERROR" ]; then
-            gh pr edit "$PR_NUMBER" --add-label "infra:qa-broken"
+            GH_TOKEN="$PROJECT_TOKEN" gh api "repos/${GITHUB_REPOSITORY}/issues/${PR_NUMBER}/labels" --method POST -f 'labels[]=infra:qa-broken'
             gh pr comment "$PR_NUMBER" --body "🤖 **QA Agent:** Could not reach GitHub Models API. Manual review required."
-            exit 0
+            exit 1
           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")')
+          VERDICT=$(echo "$RESPONSE" | python3 -c 'import json,sys,re; d=json.load(sys.stdin); t=d.get("choices",[{}])[0].get("message",{}).get("content","").strip(); lines=[l for l in t.split("\n") if not l.strip().startswith("```")]; first=lines[0].upper() if lines 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}"
+            GH_TOKEN="$PROJECT_TOKEN" gh api "repos/${GITHUB_REPOSITORY}/issues/${PR_NUMBER}/labels" --method POST -f 'labels[]=qa:approved'
+            gh pr comment "$PR_NUMBER" --body "🤖 **QA Agent:** PASS
+
+${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}"
+            GH_TOKEN="$PROJECT_TOKEN" gh api "repos/${GITHUB_REPOSITORY}/issues/${PR_NUMBER}/labels" --method POST -f 'labels[]=qa:needs-work'
+            gh pr comment "$PR_NUMBER" --body "🤖 **QA Agent:** FAIL
+
+${EXPLANATION}"
           else
-            gh pr edit "$PR_NUMBER" --add-label "infra:qa-broken"
+            GH_TOKEN="$PROJECT_TOKEN" gh api "repos/${GITHUB_REPOSITORY}/issues/${PR_NUMBER}/labels" --method POST -f 'labels[]=infra:qa-broken'
             gh pr comment "$PR_NUMBER" --body "🤖 **QA Agent:** Could not parse GitHub Models response. Manual review required."
+            exit 1
           fi

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

@@ -0,0 +1,51 @@
+name: QA Gate
+
+on:
+  pull_request:
+    types: [opened, synchronize, reopened, labeled, unlabeled]
+
+permissions:
+  pull-requests: read
+
+jobs:
+  qa-gate:
+    name: QA Gate
+    runs-on: ubuntu-latest
+    steps:
+      - name: Check QA status label
+        env:
+          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
+        run: |
+          set -e
+          PR_NUMBER="${{ github.event.pull_request.number }}"
+          REPO="${{ github.repository }}"
+
+          PR_LABELS=$(gh pr view "$PR_NUMBER" --repo "$REPO" --json labels --jq '.labels[].name')
+
+          if echo "$PR_LABELS" | grep -qx "hotfix"; then
+            echo "✅ QA Gate: hotfix label — bypassed."
+            exit 0
+          fi
+
+          if echo "$PR_LABELS" | grep -qx "human-approved"; then
+            echo "✅ QA Gate: human-approved label — manual QA sign-off, bypassed."
+            exit 0
+          fi
+
+          if echo "$PR_LABELS" | grep -qx "qa:approved"; then
+            echo "✅ QA Gate: qa:approved — merge allowed."
+            exit 0
+          fi
+
+          if echo "$PR_LABELS" | grep -qx "infra:qa-broken"; then
+            echo "❌ QA Gate: infra:qa-broken — GitHub Models API unreachable. Manual QA review required before merge."
+            exit 1
+          fi
+
+          if echo "$PR_LABELS" | grep -qx "qa:needs-work"; then
+            echo "❌ QA Gate: qa:needs-work — acceptance criteria not fully met. Fix required before merge."
+            exit 1
+          fi
+
+          echo "❌ QA Gate: no QA label found — AC Coverage Verification has not completed. Wait for the check to finish."
+          exit 1

package/templates/AGENTS.md

@@ -30,40 +30,87 @@ 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. **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.
+1. **Stage Check**: Before applying any label or taking any action, run `gh issue view <N> --json labels,title` to determine the issue's current stage. State: *"Issue #N — [title] — is currently at `<stage>`. Requesting confirmation to advance to `<next>`."* Wait for an explicit stage-advancement signal in this conversation turn. A prioritization signal ("work on X", "tackle X next") does **not** count as confirmation — only an explicit signal counts (e.g. "start brainstorming", "yes advance", "go"). **Exceptions — skip this step and proceed directly**:
+   - `spec:approved` → begin implementation (gate already passed)
+   - `stage:development` or `stage:testing` → issue is owned by automation; do not intervene unless explicitly asked to fix a specific problem
+   - `stage:approval` → spec already written; wait for PM to add `spec:approved` before doing anything
+2. **Initial State**: Apply the `stage:brainstorming` label using the GitHub CLI (`gh issue edit <N> --add-label "stage:brainstorming"`). **Exception — pre-spec'd issue**: if the issue body already contains all required spec sections (`## Problem`, `## Solution`, `## Acceptance Criteria`, `## Edge Cases`, `## Out of Scope`, `## Files to Modify`) — all present and non-empty — apply `stage:approval` directly in a single call instead, skipping `stage:brainstorming` and `stage:detailing`.
+3. Read the issue entirely — understand its type (US/BUG/TASK/SPIKE) and the Acceptance Criteria.
+4. Read `docs/pdlc.md` — understand the PDLC and the Definition of Done in this project.
+5. Read all files mentioned in the issue's technical context.
+6. Implement the **minimum viable change** that satisfies the ACs — do not refactor beyond scope.
+7. Run tests: `{{TEST_COMMAND}}`
+8. Run typecheck (if applicable): `{{TYPECHECK_COMMAND}}`
+9. Create a Pull Request with `Closes #N` in the body — automation moves the board.
 
-### Spec format (Upstream Agents)
+## Spec Format
 
-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:
+When writing or rewriting an issue body during detailing, include ALL sections below. Omitting any section blocks `stage:approval`.
+
+**Destination: the issue body.** Write spec content to the issue body using `gh issue edit <N> --body "..."` — not to a file. A file is acceptable as optional reference only. Automation checks the issue body for `## Acceptance Criteria` and `## Files to Modify` to advance the stage; content that exists only in a file is invisible to it.
 
 ```
-**As** [user],
-**I want** [action],
-**so that** [benefit].
+## Problem
+[1-3 sentences. What fails. Who affected. Measured impact.]
+
+## Sprint Goal / Success Metrics
+| Metric | Baseline | Target | When |
+|--------|----------|--------|------|
 
----
+## Solution
+[Behavioral description of what is built. No implementation details.]
 
 ## Acceptance Criteria
+**AC1 — [name]**
+- Given [precondition]
+- When [action]
+- Then [outcome]
+
+## Edge Cases
+- EC1: [condition] → [expected behavior]
 
-**AC1 — ...**
-- Given ...
-- When ...
-- Then ...
+## Out of Scope
+- [item] — reason
 
-**AC2 — ...**
-...
+## Non-Functional Requirements
+- Performance: [metric with number]
+- Security: [constraint]
+- Reliability: [constraint]
+> For pure docs/markdown issues with zero runtime behavior, include the NFRs section and state "N/A".
 
-## Files to modify
-- `path/to/file.ts` — what changes
+## Files to Modify
+- `path/to/file` — what changes
 ```
 
+## Stage Transition Rules (non-negotiable)
+
+MUST apply `stage:brainstorming` label immediately on starting work — before reading
+any code, before invoking any skill. Then read context and present problem summary
++ 2–3 solution options in a single message.
+
+MUST NOT add `stage:detailing` label until the user has explicitly selected
+an approach in the current conversation turn. Work done in a prior
+planning session does NOT count as confirmation.
+
+MUST NOT add `spec:approved` or `stage:development` — these represent final
+human approval or automation output. Adding them manually triggers irreversible
+automation (Jules dispatch, board move).
+
+MUST NOT manually add `stage:approval` except via the pre-spec'd exception
+below. In the standard flow, `stage:approval` is set after you write a complete
+spec and the user confirms; it is not applied before the spec exists.
+
+Each stage transition requires a fresh explicit signal from the user in the same
+session where the transition happens. The pre-spec'd exception is the only
+deviation from this rule.
+
+**Pre-spec'd exception**: if the issue body already contains all required spec
+sections (`## Problem`, `## Solution`, `## Acceptance Criteria`, `## Edge Cases`,
+`## Out of Scope`, `## Files to Modify`) — all present and non-empty — apply
+`stage:approval` directly in a single `gh issue edit` call, skipping
+`stage:brainstorming` and `stage:detailing`. One label event eliminates the
+race condition that causes the project board to land on the wrong column.
+
 ## Pipeline Updates
 
 To add or configure optional agents (Jules, QA Agent, Sentinel) at any time:
@@ -80,7 +127,11 @@ Run this when the user says anything like "update the pipeline", "update the boa
 - Never open a PR without passing the tests.
 - Never implement beyond the immediate scope of the issue.
 - Never create future-proofing abstractions for hypothetical features.
-- Never add or remove `stage:*` or `qa:*` labels manually. These are owned by GitHub Actions automation and the PM only.
+- The agent MUST NOT apply these labels under any circumstances (PM only):
+  - `spec:approved`: triggers Jules dispatch + board move to Development.
+  - `qa:approved`: triggers board move to Code Review.
+  - `qa:needs-work`: signals the PR requires changes and halts the flow.
+- Never add or remove stage:* labels manually, except: `stage:brainstorming` as the initial label when starting work, or `stage:approval` directly when applying the pre-spec'd exception. All other stage transitions are owned by GitHub Actions automation and the PM.
 {{EXTRA_DONT}}
 
 ## Project Standards

package/templates/docs/pdlc.md

@@ -4,9 +4,8 @@
 
 | Column | Meaning | Who moves the card |
 |---|---|---|
-| 💡 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` |
+| 💡 Idea | Backlog — tell agent: "work on issue #XX" | Don't move manually |
+| 🧠 Brainstorming | AI reading context, proposing approaches and trade-offs | Label `stage:brainstorming` |
 | 📐 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` |
@@ -37,7 +36,6 @@ REPO         = {{REPO_OWNER}}/{{REPO_NAME}}
 | Column | Option ID |
 |---|---|
 | 💡 Idea | `{{ID_IDEA}}` |
-| 🔍 Exploration | `{{ID_EXPLORATION}}` |
 | 🧠 Brainstorming | `{{ID_BRAINSTORMING}}` |
 | 📐 Detail Solution | `{{ID_DETAIL}}` |
 | ✅ Approval | `{{ID_APPROVAL}}` |
@@ -60,7 +58,7 @@ REPO         = {{REPO_OWNER}}/{{REPO_NAME}}
 ```
 [icon] [PREFIX]: [short description, imperative tense]
 
-👤 US:     user story
+✨ feat:   new feature or behavioral change
 🐛 BUG:    bug
 🔧 TASK:   operational task
 🔬 SPIKE:  exploration/evaluation spike
@@ -70,7 +68,6 @@ REPO         = {{REPO_OWNER}}/{{REPO_NAME}}
 
 | Label | Entity | Color | Meaning |
 |---|---|---|---|
-| `stage:exploration` | Issue | Purple | Issue is being evaluated |
 | `stage:brainstorming` | Issue | Pink | Proposed approaches awaiting PM gate |
 | `stage:detailing` | Issue | Blue | Technical spec is being written |
 | `stage:development` | Issue | Orange | Agent is implementing the spec |
@@ -80,16 +77,16 @@ REPO         = {{REPO_OWNER}}/{{REPO_NAME}}
 | `qa:approved` | PR | Green | QA Agent passed — AC coverage verified |
 | `qa:needs-work` | PR | Red | QA Agent failed — PR needs changes |
 | `infra:qa-broken` | PR | Orange | QA Agent error — manual review required |
-| `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:feature` | Issue | Blue | New feature or behavioral change — full flow |
+| `type:task` | Issue | Yellow | Operational/non-functional change — full flow |
+| `type:bug` | Issue | Red | Something broken — full flow |
 | `type:spike` | Issue | Gray | Research/evaluation — never reaches Development |
 
 ## Approval Gates
 
 **Gate 1 — PM/Ideation (Brainstorming):**
-You comment on the issue approving one of the approaches proposed by the ideation agent.
-Format: *"Approved — proceed with option X."*
+Agent presents problem summary + 2–3 solution options in a single message. You select an approach.
+Format: *"Option X"* or *"Go with B"* or *"Approved — proceed with option X."*
 
 **Gate 2 — Tech Lead (Spec):**
 You add the `spec:approved` label to the issue after reviewing the technical spec in the body.
@@ -101,12 +98,23 @@ The `type:*` label is the authoritative signal — set automatically by the agen
 
 | 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) |
+| `type:feature` | brainstorming → Gate 1 → detailing → approval |
+| `type:task` | brainstorming → Gate 1 → detailing → approval |
+| `type:bug` | brainstorming → Gate 1 → detailing → approval |
+| `type:spike` | brainstorming → Gate 1 → 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).
+If no `type:*` label present and agent confidence < 85%, defaults to `type:feature` (safe fallback — never skips gates by omission).
+
+## Bypass Mechanism
+
+Agents MUST NOT skip any stage. The ONLY authorized bypasses are:
+
+| Mechanism | Who authorizes | What it bypasses |
+|---|---|---|
+| `human-approved` label on issue | PM (human) only | All stage gates |
+| Branch prefix `hotfix/` | PM (human) only | PR gate only |
+
+Agents MUST NOT self-authorize a bypass. Stop and ask the PM explicitly.
 
 ## Definition of Done
 

package/.agentic-pdlc/templates/.github/CODEOWNERS

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

package/.agentic-pdlc/templates/.github/copilot-instructions.md

@@ -1,12 +0,0 @@
-# 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!