create-agentic-pdlc 2.2.1 → 2.3.0

package/CLAUDE.md

@@ -1,9 +1,57 @@
+# agentic-pdlc
+
+**What it is:** npm CLI (`npx create-agentic-pdlc`) that installs a PDLC workflow for AI agent projects. Stack: Markdown + GitHub Actions YAML only — never complex Node/Python/Bash scripts.
+
+**Workflow:** `stage:brainstorming` → `stage:detailing` → `spec:approved` → `stage:development` → PR → merge. Labels move the board automatically.
+
+## Session Startup
+
+Read: `AGENTS.md` (mandatory contract), `docs/pdlc.md` (board + labels — only when operating on the board).
+Run: `gh issue list --state open --label "stage:development" --json number,title --jq '.[] | "#\(.number) \(.title)"'`
+
 # PDLC Stage Gate
 
 NEVER run `gh pr create` unless one of these is true:
-- The linked issue has label `stage:approval`
+- The linked issue has label `spec:approved`
 - The branch name starts with `hotfix/`
 
-Advance stages first: `exploration` → `brainstorming` → `detailing` → `approval`
+NEVER edit files, create branches, or commit unless the linked issue has label `spec:approved` (set by human PM only) or the branch name starts with `hotfix/`.
+
+Advance stages first: `brainstorming` → `detailing` → `approval` → (human adds `spec:approved`) → `development`
+
+The PreToolUse hook will block `gh pr create` automatically if this rule is violated.
+
+## Human-in-the-Loop
+
+| Transition | Gate |
+|---|---|
+| → `stage:brainstorming` | Autonomous — apply immediately |
+| → `stage:detailing` | Ask user — present problem summary + options, wait for choice |
+| → `stage:approval` | **Autonomous** — agent completes spec end-to-end, advances without asking |
+| `spec:approved` | **Human PM only** — agent waits; never adds this label |
+| → `stage:development` | Human applies `spec:approved` label — that IS the gate |
+
+**Detailing is fully autonomous.** Write the complete spec, add it to the issue, advance to `stage:approval` — no confirmation needed. Then **stop and wait** for human to add `spec:approved` before any implementation.
+
+## 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 any approval-trigger label under any
+circumstances — these are set by the PM (human) only, after reviewing the spec
+in the issue body. Adding them triggers irreversible automation (Jules dispatch,
+board move).
+
+MUST NOT add or remove `stage:development`, `spec:approved`, or `qa:*` labels —
+these are owned by GitHub Actions automation and the PM. The agent is responsible
+for applying `stage:brainstorming`, `stage:detailing`, and `stage:approval` as
+part of the prescribed workflow above.
 
-The PreToolUse hook will block the action automatically if this rule is violated.
+Each stage transition requires a fresh explicit signal from the user in the same
+session where the transition happens. These rules have no exceptions.

package/SETUP.md

@@ -12,6 +12,8 @@ Estimated time: 2-3 hours (including GitHub Projects setup).
 - GitHub Projects enabled on your account/organization
 - Implementation agent connected to the repository (e.g., Jules: github.com/google-labs/jules)
 
+> **Jules users:** After installing the Jules GitHub App at [github.com/settings/installations](https://github.com/settings/installations), set `JULES_ENABLED=true` at **repo → Settings → Variables → Actions** to enable Jules dispatch. If this variable is absent, agent comments are silently skipped — no false "dispatched" messages.
+
 ---
 
 ## Step 1 — Create the GitHub Project Board

package/adapters/claude-code/skill.md

@@ -48,6 +48,10 @@ If any of these files are missing, you are in **Setup Mode**. Do not proceed wit
      - a) **No** — *No autonomous implementation agent.*
      - b) **@google-labs-jules** — *Jules (recommended if you don't have one).*
      - c) **Other** — *Enter the agent's handle.*
+
+     When writing `agent-trigger.yml`, set `{{IMPLEMENTATION_AGENT_LABEL}}` as follows:
+     - Jules (`@google-labs-jules`): use `jules` — this is the native label the Jules GitHub App watches. **Do NOT use `agent:jules`** — Jules does not watch that label and the trigger will silently fail.
+     - Other agents: use the handle without `@`, lowercase (e.g. `@my-agent` → `my-agent`).
 5. Generate and write the missing files replacing the `{{SCREAMING_SNAKE_CASE}}` placeholders using the templates in `.agentic-pdlc/templates/`.
 6. Offer to run the `gh` commands for labels (`spec:approved`, `pr:in-review`, `pr:approved`, `architecture-violation`).
 7. **`PROJECT_PAT` secret (required for board automation):**
@@ -98,9 +102,9 @@ If `AGENTS.md` and `docs/pdlc.md` are present, you are in **Execution Mode**.
 
 ### 0. [FIRST] Issue Type Identification
 
-**Run before anything else — before `stage:exploration`, before reading code.**
+**Run before anything else — before reading code.**
 
-Reading the issue title and body for type inference is exempt from the `stage:exploration` requirement: it is metadata already present in the request, not code reading or skill invocation.
+Reading the issue title and body for type inference is exempt from the initial label requirement: it is metadata already present in the request, not code reading or skill invocation.
 
 1. Check if issue already has a `type:*` label (`type:us`, `type:task`, `type:bug`, `type:spike`) → if yes, skip to Section 0.1.
 2. Read issue title + body (metadata only — no code reading at this step).
@@ -116,10 +120,10 @@ Reading the issue title and body for type inference is exempt from the `stage:ex
 
 | Type | Flow |
 |---|---|
-| `type:us` | Full flow: exploration → brainstorming → Gate 1 → detailing → approval |
-| `type:task` | Skip brainstorming: exploration → detailing → approval |
-| `type:bug` | Skip brainstorming: exploration → detailing → approval |
-| `type:spike` | Skip brainstorming: exploration → detailing → conclusion comment (never reaches Development) |
+| `type:us` | 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) |
 
 ### 0.1 Board Labels — Mandatory at Every State Transition
 
@@ -127,11 +131,10 @@ These label commands are non-negotiable. They run **before** the activity they a
 
 | When | Command |
 |---|---|
-| Before reading any code / invoking any skill | `gh issue edit <N> --add-label "stage:exploration"` |
-| Before presenting architecture approaches | `gh issue edit <N> --add-label "stage:brainstorming" --remove-label "stage:exploration"` |
+| Before reading any code / invoking any skill | `gh issue edit <N> --add-label "stage:brainstorming"` |
 | Before writing the technical spec | `gh issue edit <N> --add-label "stage:detailing" --remove-label "stage:brainstorming"` |
 
-No investigation, no skill invocation, no code reading happens before `stage:exploration` is applied. No architecture presentation starts before `stage:brainstorming` is set (and `stage:exploration` removed). No spec writing starts before `stage:detailing` is set (and `stage:brainstorming` removed).
+No investigation, no skill invocation, no code reading happens before `stage:brainstorming` is applied. No spec writing starts before `stage:detailing` is set (and `stage:brainstorming` removed).
 
 ### 0.1 PR Stage Gate — Non-Negotiable
 
@@ -147,7 +150,7 @@ git checkout -b hotfix/<N>-<description>
 ```
 
 ### 1. Daily Upstream Loop
-Your job is to move issues from "💡 Idea - don't move manually to Exploration" to "📐 Detail Solution".
+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).

package/adapters/hooks/pdlc-stage-gate.sh

@@ -26,8 +26,8 @@ fi
 
 LABELS=$(gh issue view "$ISSUE_NUM" --json labels --jq '[.labels[].name] | join(" ")' 2>/dev/null || echo "")
 
-if echo "$LABELS" | grep -qw "stage:approval"; then
-  echo "✅ PDLC: Issue #$ISSUE_NUM approved — gate passed."
+if echo "$LABELS" | grep -qw "spec:approved"; then
+  echo "✅ PDLC: Issue #$ISSUE_NUM spec approved by PM — gate passed."
   exit 0
 fi
 
@@ -39,6 +39,6 @@ fi
 STAGE=$(echo "$LABELS" | tr ' ' '\n' | grep "^stage:" | head -1 || echo "none")
 echo "❌ PDLC Stage Gate: Issue #$ISSUE_NUM is not approved."
 echo "   Current stage: $STAGE"
-echo "   Required: stage:approval or stage:development label on the issue."
+echo "   Required: spec:approved (set by human PM) or stage:development label on the issue."
 echo "   Emergency bypass: rename branch to hotfix/<issue-number>-<description>."
 exit 1

package/bin/cli.js

@@ -227,6 +227,16 @@ async function runSetup() {
     }
   }
 
+  const defaultLabels = [
+    'bug', 'documentation', 'duplicate', 'enhancement',
+    'good first issue', 'help wanted', 'invalid', 'question', 'wontfix'
+  ];
+  for (const label of defaultLabels) {
+    try {
+      execFileSync('gh', ['label', 'delete', label, '--repo', repo, '--yes'], { stdio: 'ignore' });
+    } catch (_) {}
+  }
+
   // Project V2
   console.log(`\n${cyan}${i18n.creating_project}${reset}`);
   let ownerId, projectId, projectNumber;
@@ -240,13 +250,13 @@ async function runSetup() {
     }
 
     const projectCreateRaw = execFileSync('gh', ['api', 'graphql', '-f', 'query=mutation($owner: ID!, $title: String!) { createProjectV2(input: {ownerId: $owner, title: $title}) { projectV2 { id number } } }', '-f', `owner=${ownerId}`, '-f', `title=${boardName}`], { stdio: ['ignore', 'pipe', 'pipe'] }).toString().trim();
-    const projectCreateResponse = JSON.parse(projectCreateRaw);
-    if (projectCreateResponse.errors) {
+    const projectCreateResponse = projectCreateRaw ? JSON.parse(projectCreateRaw) : null;
+    if (projectCreateResponse?.errors) {
       throw new Error(projectCreateResponse.errors.map(e => e.message).join('; '));
     }
-    const projectCreateData = projectCreateResponse.data.createProjectV2.projectV2;
-    projectId = projectCreateData.id;
-    projectNumber = projectCreateData.number;
+    const projectCreateData = projectCreateResponse?.data?.createProjectV2?.projectV2;
+    projectId = projectCreateData?.id;
+    projectNumber = projectCreateData?.number;
 
     console.log(`  ${i18n.project_ok}${projectId})`);
 
@@ -280,7 +290,7 @@ async function runSetup() {
 
       if (statusFieldId) {
         const columns = [
-          { name: "💡 Idea", description: "Backlog — every new issue lands here", color: "GRAY" },
+          { name: "💡 Idea - No move to Exploration directly", description: "Just tell your agent to work on issue #XX", color: "GRAY" },
           { name: "🔍 Exploration", description: "AI is analyzing code and context", color: "PURPLE" },
           { name: "🧠 Brainstorming", description: "AI proposed approaches and trade-offs", color: "PINK" },
           { name: "📐 Detail Solution", description: "AI is writing the technical spec", color: "BLUE" },
@@ -314,7 +324,8 @@ async function runSetup() {
 
         const updateOutput = execFileSync('gh', ['api', 'graphql', '--input', '-'], { input: queryPayload }).toString().trim();
         const jsonResponse = updateOutput ? JSON.parse(updateOutput) : null;
-        const returnedOptions = jsonResponse?.data?.updateProjectV2Field?.projectV2Field?.options || [];
+        const returnedOptions = jsonResponse?.data?.updateProjectV2Field?.projectV2Field?.options ||
+                                jsonResponse?.data?.updateProjectV2SingleSelectField?.projectV2SingleSelectField?.options || [];
 
         for (const opt of returnedOptions) {
           optionMap[opt.name] = opt.id;

package/docs/flow.md

@@ -5,8 +5,7 @@ This document describes the full lifecycle of a card on the agentic-pdlc board
 ```mermaid
 stateDiagram-v2
     direction LR
-    Idea --> Exploration : stage:exploration
-    Exploration --> Brainstorming : stage:brainstorming
+    Idea --> Brainstorming : stage:brainstorming
     Brainstorming --> Detailing : Gate 1 (PM)
     Detailing --> Approval : stage:approval
     Approval --> Development : Gate 2 (spec:approved)
@@ -23,7 +22,7 @@ stateDiagram-v2
 |------|---------------|
 | **PM** (human) | Selects issues for the sprint, approves brainstorm (Gate 1), approves spec (Gate 2) |
 | **TL / Reviewer** (human) | Co-approves spec for technical decisions (Gate 2), reviews and approves the PR (Gate 3) |
-| **Claude** | Exploration, brainstorming, spec writing — acts on PM instruction via chat or via upstream label |
+| **Claude** | Brainstorming (context reading + approaches), spec writing — acts on PM instruction via chat or via upstream label |
 | **Implementation Agent** | Implementation, running tests, opening the PR |
 | **Workflow** | All label swaps and card movements — the source of truth for board state |
 
@@ -38,33 +37,22 @@ Issue exists in the backlog with no `stage:` label.
 
 ---
 
-### 🔍 Exploration
-
-**Trigger (two equivalent paths):**
-- 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 `stage:exploration` → moves card to Exploration.
-
-**Who works:** Claude reads relevant code and context.
-
----
-
 ### 🧠 Brainstorming
 
-**Trigger:** Claude, after exploration.
+**Trigger:** PM tells Claude to work on the issue (in chat) or applies `stage:brainstorming` directly.
 
 **Actions:**
-- Claude posts a comment on the issue with findings and 2–3 proposed approaches
-- Claude swaps `stage:exploration` → `stage:brainstorming`
+- Claude applies `stage:brainstorming` immediately
+- Claude reads relevant code and context
+- Claude posts a single comment with: (1) brief problem summary, (2) 2–3 proposed approaches with trade-offs
 
-**Workflow:** `project-automation.yml` moves card to Brainstorming.
+**Workflow:** `project-automation.yml` detects `stage:brainstorming` → moves card to Brainstorming.
 
 **⏸ Human gate (Gate 1 — PM):** PM reads the brainstorming comment and selects an approach. This can be done:
 - By commenting on the issue (e.g., "Option A", "Go with B", "approved", "lgtm")
 - By telling Claude in chat
 
-**Note on implicit approval:** If Claude presented multiple options, selecting one (e.g., "Option A") counts as implicit approval. The `upstream-gate.yml` detects option-selection patterns in addition to explicit approval words.
+**Note on implicit approval:** Selecting one option (e.g., "Option A") counts as implicit approval. The `upstream-gate.yml` detects option-selection patterns in addition to explicit approval words.
 
 ---
 
@@ -141,7 +129,6 @@ Issue exists in the backlog with no `stage:` label.
 
 | Label | Added by | Removed by |
 |-------|----------|------------|
-| `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` |

package/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 | AI is analyzing code and context | Label `stage:exploration` |
-| 🧠 Brainstorming | AI proposed approaches and trade-offs | 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 | AI is writing the technical spec | Label `stage:detailing` |
 | ✅ Approval | Your turn, awaiting `spec:approved` label | Label `spec:approved` |
 | ⚙️ Development | AI implementing the spec | Label `stage:development` |
@@ -32,7 +31,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}}` |
@@ -65,7 +63,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 |
@@ -73,15 +70,15 @@ REPO         = {{REPO_OWNER}}/{{REPO_NAME}}
 | `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: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.
@@ -93,13 +90,24 @@ 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:us` | 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).
 
+## 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
 
 An issue is truly done when:

package/package.json

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

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

@@ -75,7 +75,7 @@ jobs:
             console.log(`Issue #${number} → Development`);
 
       - name: Comment on issue to trigger agent and prevent race conditions
-        if: ${{ !contains('{{IMPLEMENTATION_AGENT_LABEL}}', '{{') }}
+        if: ${{ !contains('{{IMPLEMENTATION_AGENT_LABEL}}', '{{') && vars.JULES_ENABLED == 'true' }}
         uses: actions/github-script@v7
         with:
           github-token: ${{ secrets.GITHUB_TOKEN }}
@@ -118,7 +118,7 @@ jobs:
       contents: read
     steps:
       - name: Comment on issue to trigger agent
-        if: ${{ !contains('{{IMPLEMENTATION_AGENT_LABEL}}', '{{') }}
+        if: ${{ !contains('{{IMPLEMENTATION_AGENT_LABEL}}', '{{') && vars.JULES_ENABLED == 'true' }}
         uses: actions/github-script@v7
         with:
           github-token: ${{ secrets.GITHUB_TOKEN }}

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

@@ -38,3 +38,17 @@ jobs:
         if: ${{ !contains('{{TEST_COMMAND}}', '{{') }}
         run: |
           {{TEST_COMMAND}}
+
+  ci-status:
+    name: Sentinel / CI
+    needs: [validate]
+    if: always()
+    runs-on: ubuntu-latest
+    steps:
+      - name: Check validate result
+        run: |
+          result="${{ needs.validate.result }}"
+          if [[ "$result" != "success" && "$result" != "skipped" ]]; then
+            echo "CI failed: validate=$result"
+            exit 1
+          fi

package/templates/.github/workflows/pdlc-health-check.yml

@@ -8,7 +8,6 @@ on:
 env:
   PROJECT_ID: "{{PROJECT_ID}}"
   STATUS_FIELD_ID: "{{STATUS_FIELD_ID}}"
-  STATUS_EXPLORATION: "{{ID_EXPLORATION}}"
   STATUS_BRAINSTORMING: "{{ID_BRAINSTORMING}}"
   STATUS_DETAILING: "{{ID_DETAILING}}"
   STATUS_APPROVAL: "{{ID_APPROVAL}}"
@@ -35,7 +34,6 @@ jobs:
             const projectId = process.env.PROJECT_ID;
             const statusFieldId = process.env.STATUS_FIELD_ID;
             const envVars = {
-              'STATUS_EXPLORATION': process.env.STATUS_EXPLORATION,
               'STATUS_BRAINSTORMING': process.env.STATUS_BRAINSTORMING,
               'STATUS_DETAILING': process.env.STATUS_DETAILING,
               'STATUS_APPROVAL': process.env.STATUS_APPROVAL,

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}}"
@@ -40,10 +39,7 @@ jobs:
             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') {
@@ -302,3 +298,25 @@ jobs:
             } 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@v7
+        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',
+              'agent:working', '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,6 +13,8 @@ jobs:
   qa:
     name: AC Coverage Verification (GitHub Models)
     runs-on: ubuntu-latest
+    env:
+      PROJECT_PAT: ${{ secrets.PROJECT_PAT }}
     steps:
       - uses: actions/checkout@v4
         with:
@@ -59,7 +61,7 @@ jobs:
             --max-time 30 || echo "API_ERROR")
 
           if [ "$RESPONSE" = "API_ERROR" ]; then
-            gh pr edit "$PR_NUMBER" --add-label "infra:qa-broken"
+            GH_TOKEN="$PROJECT_PAT" 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
           fi
@@ -68,12 +70,12 @@ jobs:
           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_TOKEN="$PROJECT_PAT" gh api "repos/${GITHUB_REPOSITORY}/issues/${PR_NUMBER}/labels" --method POST -f 'labels[]=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_TOKEN="$PROJECT_PAT" gh api "repos/${GITHUB_REPOSITORY}/issues/${PR_NUMBER}/labels" --method POST -f 'labels[]=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_TOKEN="$PROJECT_PAT" 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."
           fi

package/templates/AGENTS.md

@@ -30,7 +30,7 @@ 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"`).
+1. **Initial State**: When beginning work on a new issue, your very first action must be to apply the `stage:brainstorming` label using the GitHub CLI (`gh issue edit <N> --add-label "stage:brainstorming"`).
 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.
@@ -64,6 +64,25 @@ When detailing a solution in an issue body, you must **always** include both the
 - `path/to/file.ts` — 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`, `stage:development`, or manually add
+`stage:approval` — these represent final human approval or the result of it.
+`stage:approval` is only set by system automation after you provide a complete
+spec for human review. Adding them manually triggers irreversible automation
+(Jules dispatch, board move).
+
+Each stage transition requires a fresh explicit signal from the user in the same
+session where the transition happens. These rules have no exceptions.
+
 ## Pipeline Updates
 
 To add or configure optional agents (Jules, QA Agent, Sentinel) at any time:
@@ -80,7 +99,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 for stage:brainstorming as the initial label when starting work. 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}}` |
@@ -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 |
@@ -81,15 +78,15 @@ REPO         = {{REPO_OWNER}}/{{REPO_NAME}}
 | `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: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,13 +98,24 @@ 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:us` | 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).
 
+## 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
 
 An issue is truly done when: