create-agentic-pdlc 2.2.1 → 2.4.0

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

@@ -19,7 +19,7 @@ jobs:
       STATUS_FIELD_ID: "PVTSSF_lAHODpFFL84BXg7hzhStRHI"
       STATUS_CODE_REVIEW_PR: "86ca9720"
     steps:
-      - uses: actions/checkout@v4
+      - uses: actions/checkout@v5.0.1
         with:
           fetch-depth: 0
 
@@ -34,7 +34,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 // ""')
@@ -53,39 +53,50 @@ jobs:
             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)
+          # Serialize prompt as JSON string and call GitHub Models API (3 attempts, 20s backoff)
           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")
+          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 marks this check as failed; qa-gate.yml enforces the merge block via infra:qa-broken label
+            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")')
           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_TOKEN" 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_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:** AC coverage insufficient. ${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
 
       - name: Move board card to Code Review on qa:approved
         if: ${{ env.PROJECT_TOKEN != '' && env.PROJECT_ID != '{{PROJECT_ID}}' }}
-        uses: actions/github-script@v7
+        uses: actions/github-script@v8
         with:
           github-token: ${{ env.PROJECT_TOKEN }}
           script: |

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

@@ -27,14 +27,55 @@ 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: `echo "No tests/build needed."`
-7. Run typecheck: `echo "No typecheck needed."`
-8. Create a Pull Request with `Closes #N` in the body — automation moves the board.
+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: `echo "No tests/build needed."`
+8. Run typecheck: `echo "No typecheck needed."`
+9. Create a Pull Request with `Closes #N` in the body — automation moves the board.
+
+## Spec Format
+
+When writing or rewriting an issue body during detailing, include ALL sections below. Omitting any section blocks `stage:approval`.
+
+```
+## 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]
+
+## Out of Scope
+- [item] — reason
+
+## 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` — what changes
+```
 
 ## What NOT to do
 
@@ -50,3 +91,4 @@ Always start from the current `main` HEAD. Never work over stale snapshots.
 - **Lint/Types:** `echo "No tests/build needed."`
 - **Typecheck:** `echo "No typecheck needed."`
 - **Build:** `echo "No tests/build needed."`
+- **Canonical secret name:** `PROJECT_TOKEN` (not `PROJECT_PAT`) — use this in all workflow files, both live and templates

package/CLAUDE.md

@@ -1,9 +1,59 @@
+# 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.
+
+**Spec 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.
+
+## 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
@@ -61,7 +63,7 @@ npx create-agentic-pdlc
 The CLI will:
 1. Ask you which AI Agent you use (Claude Code, Cursor, etc.).
 2. Copy the system instructions pointing to our interactive Setup Mode.
-3. Automatically download the base templates to `.agentic-pdlc/templates/`.
+3. Automatically install the base templates into your project.
 
 Once the CLI finishes, it will instruct you to open your AI agent and run the **Setup Mode**. Your AI agent will then ask you the required project variables interactively and generate `AGENTS.md`, `docs/pdlc.md`, and the GitHub Actions for you!
 
@@ -167,6 +169,7 @@ The issue appears in your GitHub notifications automatically — zero extra setu
    ```bash
    cp .agentic-pdlc/templates/.github/workflows/agentic-metrics.yml .github/workflows/agentic-metrics.yml
    ```
+   > If the file is missing, re-run `npx create-agentic-pdlc` to update your installed templates.
 
 2. Commit and push. The first pulse runs next Sunday, or trigger it manually:
    ```bash

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,28 +102,28 @@ 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.
+1. Check if issue already has a `type:*` label (`type:feature`, `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).
 3. Classify using these rules:
    - `type:task` — operational change, config, rename, docs update, non-functional (no user-facing behavior change)
    - `type:bug` — something broken that should work
    - `type:spike` — research/evaluation spike, never reaches Development
-   - `type:us` — new feature, behavioral change, anything product-facing
+   - `type:feature` — new feature, behavioral change, anything product-facing
 4. Confidence ≥ 85% → add inferred label: `gh issue edit <N> --add-label "type:<inferred>"`
-5. Confidence < 85% → default to `type:us`: `gh issue edit <N> --add-label "type:us"`
+5. Confidence < 85% → default to `type:feature`: `gh issue edit <N> --add-label "type:feature"`
 
 **Type drives the PDLC flow:**
 
 | 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: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) |
 
 ### 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,25 +150,46 @@ 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).
 - 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:
+Once approved, detail the solution directly into the GitHub Issue body. Always rewrite the full issue body — never append only ACs to existing text. Include ALL sections below. Omitting any section blocks `stage:approval`. Use this format:
 
 ```
-**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]
+
+## Out of Scope
+- [item] — reason
+
+## 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` — what changes
 ```
 
 ### 3. Handoff

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

@@ -26,19 +26,14 @@ 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
+if echo "$LABELS" | grep -qw "spec:approved" || echo "$LABELS" | grep -qw "stage:approval" || echo "$LABELS" | grep -qw "stage:development" || echo "$LABELS" | grep -qw "stage:testing" || echo "$LABELS" | grep -qw "human-approved"; then
   echo "✅ PDLC: Issue #$ISSUE_NUM approved — gate passed."
   exit 0
 fi
 
-if echo "$LABELS" | grep -qw "stage:development"; then
-  echo "✅ PDLC: Issue #$ISSUE_NUM in development (spec already approved) — gate passed."
-  exit 0
-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: stage:approval OR spec:approved OR stage:development OR stage:testing OR human-approved label on the issue."
 echo "   Emergency bypass: rename branch to hotfix/<issue-number>-<description>."
 exit 1

package/bin/cli.js

@@ -41,10 +41,10 @@ const i18n = {
   invalid_repo: t('❌ Invalid repository URL. Expected format: https://github.com/OWNER/REPO', '❌ URL de repositório inválida. Formato esperado: https://github.com/OWNER/REPO', '❌ URL de repositorio inválida. Formato esperado: https://github.com/OWNER/REPO'),
   ask_org: t('Does this repository belong to a personal User account (e.g., github.com/rafaeltcosta86) or an Organization (e.g., github.com/google-labs)? (user/org): ', 'Esse repositório pertence a um Usuário pessoal (ex: github.com/rafaeltcosta86) ou a uma Organização (ex: github.com/google-labs)? (user/org): ', '¿Este repositorio pertenece a un Usuario personal (ej: github.com/rafaeltcosta86) o a una Organización (ej: github.com/google-labs)? (user/org): '),
   starting_setup: t('Starting automated repository setup...', 'Iniciando o setup automatizado do repositório...', 'Iniciando la configuración automatizada del repositorio...'),
-  creating_labels: t('[1/2] Creating repository labels...', '[1/2] Criando labels no repositório...', '[1/2] Creando etiquetas (labels) en el repositorio...'),
+  creating_labels: t('[1/3] Creating repository labels...', '[1/3] Criando labels no repositório...', '[1/3] Creando etiquetas (labels) en el repositorio...'),
   label_ok: t('✅ Label created: ', '✅ Label criada: ', '✅ Etiqueta creada: '),
   label_warn: t('⚠️ Failed to create label (might already exist): ', '⚠️ Falha ao criar label (talvez já exista): ', '⚠️ Fallo al crear etiqueta (quizás ya exista): '),
-  creating_project: t('[2/2] Creating Project V2 Board...', '[2/2] Criando Project V2 Board...', '[2/2] Creando Project V2 Board...'),
+  creating_project: t('[2/3] Creating Project V2 Board...', '[2/3] Criando Project V2 Board...', '[2/3] Creando Project V2 Board...'),
   project_ok: t('✅ Project created (ID: ', '✅ Projeto criado (ID: ', '✅ Proyecto creado (ID: '),
   project_err: t('❌ Failed to create project. Error: ', '❌ Falha ao criar o projeto. Erro: ', '❌ Fallo al crear el proyecto. Error: '),
   link_project_ok: t('✅ Project linked to repository.', '✅ Projeto vinculado ao repositório.', '✅ Proyecto vinculado al repositorio.'),
@@ -72,6 +72,9 @@ const i18n = {
   update_qa_ask: t('  Activate? Uses GITHUB_TOKEN — no extra secrets needed. (Y/n): ', '  Ativar? Usa GITHUB_TOKEN — nenhum secret extra necessário. (S/n): ', '  ¿Activar? Usa GITHUB_TOKEN — sin secrets adicionales. (S/n): '),
   update_sentinel_header: t('— Sentinel (architecture audit via Gemini Code Assist) —', '— Sentinel (auditoria de arquitetura via Gemini Code Assist) —', '— Sentinel (auditoría de arquitectura via Gemini Code Assist) —'),
   update_sentinel_ask: t('  Activate? Requires Gemini Code Assist CI job. (Y/n): ', '  Ativar? Requer CI job do Gemini Code Assist. (S/n): ', '  ¿Activar? Requiere CI job de Gemini Code Assist. (S/n): '),
+  configuring_protection: t('[3/3] Configuring branch protection...', '[3/3] Configurando proteção de branch...', '[3/3] Configurando protección de rama...'),
+  protection_ok: t('✅ Branch protection set — required checks: PDLC Stage Gate, QA Gate.', '✅ Proteção de branch configurada — checks obrigatórios: PDLC Stage Gate, QA Gate.', '✅ Protección de rama configurada — checks requeridos: PDLC Stage Gate, QA Gate.'),
+  protection_warn: t('⚠️  Branch protection could not be set automatically.\n     Set required checks manually: Settings → Branches → main → Required status checks.\n     Required: "PDLC Stage Gate" and "QA Gate"', '⚠️  Proteção de branch não pôde ser configurada automaticamente.\n     Configure manualmente: Settings → Branches → main → Required status checks.\n     Obrigatórios: "PDLC Stage Gate" e "QA Gate"', '⚠️  No se pudo configurar la protección de rama automáticamente.\n     Configúralo en: Settings → Branches → main → Required status checks.\n     Requeridos: "PDLC Stage Gate" y "QA Gate"'),
 };
 
 const cyan = '\x1b[36m';
@@ -227,6 +230,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 +253,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 +293,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 +327,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;
@@ -344,6 +358,24 @@ async function runSetup() {
     console.log(`\n${yellow}ℹ️  Org repo detected — PROJECT_PAT will require manual setup for security.${reset}`);
   }
 
+  // Branch protection — require PDLC Stage Gate + QA Gate on default branch
+  console.log(`\n${cyan}${i18n.configuring_protection}${reset}`);
+  try {
+    const defaultBranch = execFileSync('gh', ['api', `repos/${repo}`, '--jq', '.default_branch'],
+      { stdio: ['ignore', 'pipe', 'ignore'], encoding: 'utf8' }).trim() || 'main';
+    const protectionPayload = JSON.stringify({
+      required_status_checks: { strict: false, contexts: ['PDLC Stage Gate', 'QA Gate'] },
+      enforce_admins: false,
+      required_pull_request_reviews: null,
+      restrictions: null
+    });
+    execFileSync('gh', ['api', `repos/${repo}/branches/${defaultBranch}/protection`, '--method', 'PUT', '--input', '-'],
+      { input: protectionPayload, stdio: ['pipe', 'ignore', 'pipe'] });
+    console.log(`  ${green}${i18n.protection_ok}${reset}`);
+  } catch (_) {
+    console.log(`  ${yellow}${i18n.protection_warn}${reset}`);
+  }
+
   console.log(`\n${yellow}${i18n.scaffolding}${reset}`);
 
   // We copy the templates folder so the agent has the real text logic to replace and rename

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` |