create-agentic-pdlc 2.2.0 → 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

@@ -25,7 +25,7 @@ If any of these files are missing, you are in **Setup Mode**. Do not proceed wit
 1. **Language Detection:** Analyze the user's previous prompts and preferred language. Conduct this entire Setup Mode and ask all your interactive questions in that same language.
 2. Acknowledge that the framework is not yet set up.
 3. **Pre-filled Context:** Before asking any questions, read the following files if they exist:
-   - `.agentic-pdlc/cli-context.json` — written by the CLI. Contains `projectName`, `repoOwner`, `repoName`. Use these values directly and skip the corresponding questions.
+   - `.agentic-pdlc/cli-context.json` — written by the CLI. Contains `projectName`, `repoOwner`, `repoName`, `projectNumber`, `isOrg`, `boardUrl`, and `patAutoSet` (boolean). Use these values directly and skip the corresponding questions. Honor `patAutoSet` in Step 7 and `boardUrl` in Step 10.
    - `.agentic-pdlc/templates/docs/pdlc.md` — the CLI pre-fills PROJECT_ID, STATUS_FIELD_ID, REPO_OWNER, REPO_NAME, and all 9 column option IDs. If none of the values still contain `{{...}}` placeholders, skip the entire Board IDs question group.
    - `.agentic-pdlc/templates/.github/workflows/project-automation.yml` — the CLI also pre-fills all ID placeholders here. When writing the workflow file, the remaining `{{...}}` placeholders are only non-ID ones (project name, commands, etc.).
 4. Interactively ask the user only for the **missing values**, **one group at a time**:
@@ -48,25 +48,39 @@ 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. **Set up the `PROJECT_PAT` secret (required for board automation):**
-   The board automation workflows need a GitHub Personal Access Token (classic) with `project` scope. Without it, all board card movements will silently skip — no error, no cards moving.
-   - Go to: **github.com/settings/tokens** → *Generate new token (classic)*
-   - Select scopes: ✅ `repo` + ✅ `project`
-   - Copy the token, then run:
-     ```
-     gh secret set PROJECT_PAT --body "<your-token>"
-     ```
-   Wait for the user to confirm the secret is set before continuing.
+7. **`PROJECT_PAT` secret (required for board automation):**
+
+   Read `patAutoSet` from `.agentic-pdlc/cli-context.json`:
+
+   **If `patAutoSet === true`:** The CLI already configured this secret automatically. Print `✅ PROJECT_PAT is configured.` and continue to Step 8 — do not ask the user anything.
+
+   **If `patAutoSet === false` (org repo):** Show the block below and wait for the user to reply "done" or "secret set" before continuing:
+
+   > Your repo is in an organization. For security, `PROJECT_PAT` must be a dedicated PAT (not your personal OAuth token). Without it, all board card movements in CI will silently skip — no error surfaced.
+   >
+   > 1. Open: **github.com/settings/tokens** → *Generate new token (classic)*
+   > 2. Name: `PROJECT_PAT — <repo-name>`
+   > 3. Select scopes: ✅ `repo` + ✅ `project`
+   > 4. Copy the token, then run:
+   >    ```
+   >    gh secret set PROJECT_PAT --body "<your-token>" --repo <owner>/<repo>
+   >    ```
+   > 5. Reply **"done"** when finished.
 8. **IMPORTANT:** Delete the setup prompt file by running exactly:
    ```
    rm -f .agentic-setup.md .agentic-setup-prompt.md .agentic-pdlc/SETUP_PROMPT.md
    ```
    **Do NOT run `git add` or any other git command.** These files were never committed and do not exist in the git index. This command must run **before** the commit step.
 9. Commit everything with the message: `chore: setup agentic-pdlc framework`.
-10. Conclude Setup Mode. Read `projectNumber` from `.agentic-pdlc/cli-context.json` and show the user their board URL:
-    `https://github.com/users/{repoOwner}/projects/{projectNumber}/views/1?layout=board`
+10. Conclude Setup Mode. Read `boardUrl` from `.agentic-pdlc/cli-context.json` and show the user exactly this (do not reconstruct the URL — `boardUrl` already includes the correct `users/` or `orgs/` path segment and `?layout=board`):
+
+    `🎉 Setup complete! Your board: <boardUrl>`
 
 ---
 
@@ -88,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).
@@ -106,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
 
@@ -117,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
 
@@ -137,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

@@ -84,6 +84,11 @@ console.log(`${cyan}============================================================
 console.log(`${cyan}${i18n.welcome}${reset}`);
 console.log(`${cyan}================================================================${reset}\n`);
 
+function buildBoardUrl(repoOwner, projectNumber, isOrg) {
+  const segment = isOrg ? 'orgs' : 'users';
+  return `https://github.com/${segment}/${repoOwner}/projects/${projectNumber}/views/1?layout=board`;
+}
+
 // Helper function to recursively copy directories
 function copyDirSync(src, dest) {
   if (!fs.existsSync(dest)) fs.mkdirSync(dest, { recursive: true });
@@ -121,6 +126,43 @@ async function runSetup() {
     process.exit(1);
   }
 
+  function getScopes() {
+    try {
+      const out = execFileSync('gh', ['api', 'user', '-i'], { stdio: ['ignore', 'pipe', 'pipe'], encoding: 'utf8' });
+      const line = out.split('\n').find(l => l.toLowerCase().startsWith('x-oauth-scopes:'));
+      return line ? line.split(':').slice(1).join(':').split(',').map(s => s.trim()) : [];
+    } catch (e) {
+      return [];
+    }
+  }
+
+  const scopesBefore = getScopes();
+  if (scopesBefore.length > 0 && !scopesBefore.includes('project')) {
+    console.log(`${yellow}⚠️  Token missing 'project' scope — required for GitHub Projects board.${reset}`);
+    console.log(`${yellow}   Refreshing token now (browser may open)...${reset}\n`);
+    try {
+      execSync('gh auth refresh -h github.com -s project', { stdio: 'inherit' });
+    } catch (e) {
+      console.log(`${red}❌ Token refresh failed. Run manually: gh auth refresh -h github.com -s project${reset}`);
+      rl.close();
+      process.exit(1);
+    }
+    const scopesAfter = getScopes();
+    if (scopesAfter.length > 0 && !scopesAfter.includes('project')) {
+      console.log(`\n${red}❌ 'project' scope still missing after refresh.${reset}`);
+      console.log(`${yellow}   Active scopes: ${scopesAfter.join(', ')}${reset}`);
+      console.log(`${yellow}   Note: gh uses OAuth tokens — visible at github.com/settings/applications, not /settings/tokens${reset}`);
+      console.log(`${yellow}   Try manually: gh auth refresh -h github.com -s project${reset}`);
+      rl.close();
+      process.exit(1);
+    }
+    if (scopesAfter.length > 0) {
+      console.log(`\n${green}✅ Token refreshed. Active scopes: ${scopesAfter.join(', ')}${reset}\n`);
+    } else {
+      console.log(`\n${green}✅ Token refreshed with 'project' scope.${reset}\n`);
+    }
+  }
+
   const agentAnswer = await askQuestion(i18n.ask_agent);
   const agent = agentAnswer.trim().toLowerCase();
   if (!['claude', 'cursor', 'copilot'].includes(agent)) {
@@ -185,26 +227,36 @@ 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;
   try {
     if (isOrg) {
-      const orgOutput = execFileSync('gh', ['api', 'graphql', '-f', 'query=query($login: String!) { organization(login: $login) { id } }', '-f', `login=${repoOwner}`, '--jq', '.data.organization.id']).toString().trim();
+      const orgOutput = execFileSync('gh', ['api', 'graphql', '-f', 'query=query($login: String!) { organization(login: $login) { id } }', '-f', `login=${repoOwner}`, '--jq', '.data.organization.id'], { stdio: ['ignore', 'pipe', 'pipe'] }).toString().trim();
       ownerId = orgOutput;
     } else {
-      const userOutput = execFileSync('gh', ['api', 'graphql', '-f', 'query={ viewer { id } }', '--jq', '.data.viewer.id']).toString().trim();
+      const userOutput = execFileSync('gh', ['api', 'graphql', '-f', 'query={ viewer { id } }', '--jq', '.data.viewer.id'], { stdio: ['ignore', 'pipe', 'pipe'] }).toString().trim();
       ownerId = userOutput;
     }
 
-    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}`]).toString().trim();
-    const projectCreateResponse = JSON.parse(projectCreateRaw);
-    if (projectCreateResponse.errors) {
+    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 = 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})`);
 
@@ -217,7 +269,14 @@ async function runSetup() {
     }
 
   } catch (err) {
-    console.log(`  ${i18n.project_err}${err.message}`);
+    const isScopeError = (err.message || '').includes("required scopes") || (err.stderr || '').toString().includes("required scopes");
+    if (isScopeError) {
+      console.log(`  ${red}❌ Token missing 'project' scope.${reset}`);
+      console.log(`  ${yellow}Fix: gh auth refresh -s project${reset}`);
+      console.log(`  ${yellow}Then re-run: npx create-agentic-pdlc${reset}`);
+    } else {
+      console.log(`  ${i18n.project_err}${err.message}`);
+    }
   }
 
   let statusFieldId;
@@ -231,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" },
@@ -265,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;
@@ -278,6 +338,23 @@ async function runSetup() {
     }
   }
 
+  // Auto-provision PROJECT_PAT for personal repos
+  let patAutoSet = false;
+  if (projectId && !isOrg) {
+    try {
+      const tokenOut = execFileSync('gh', ['auth', 'token'], { stdio: ['ignore', 'pipe', 'pipe'], encoding: 'utf8' }).trim();
+      if (tokenOut) {
+        execFileSync('gh', ['secret', 'set', 'PROJECT_PAT', '--body', tokenOut, '--repo', repo], { stdio: ['ignore', 'pipe', 'pipe'] });
+        patAutoSet = true;
+        console.log(`\n${green}✅ PROJECT_PAT secret set automatically (uses your gh OAuth token).${reset}`);
+      }
+    } catch (err) {
+      console.log(`\n${yellow}⚠️  Could not auto-set PROJECT_PAT. Agent will guide manual setup.${reset}`);
+    }
+  } else if (projectId && isOrg) {
+    console.log(`\n${yellow}ℹ️  Org repo detected — PROJECT_PAT will require manual setup for security.${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
@@ -311,7 +388,11 @@ async function runSetup() {
       }
 
       fs.writeFileSync(pdlcDest, pdlcContent);
-      console.log(`${i18n.pdlc_prefilled}`);
+      if (projectId && statusFieldId && Object.keys(optionMap).length > 0) {
+        console.log(`${i18n.pdlc_prefilled}`);
+      } else {
+        console.log(`${yellow}⚠️  pdlc.md copied — Project IDs not filled (board creation failed). Re-run after fixing token.${reset}`);
+      }
     }
 
     // Pre-fill project-automation.yml with the same IDs so the agent doesn't need to map them
@@ -338,7 +419,16 @@ async function runSetup() {
   // Write CLI context for the agent to consume in Setup Mode
   try {
     const cliContextPath = path.join(targetDir, '.agentic-pdlc', 'cli-context.json');
-    fs.writeFileSync(cliContextPath, JSON.stringify({ projectName, repoOwner, repoName, projectNumber }, null, 2));
+    const boardUrl = projectNumber ? buildBoardUrl(repoOwner, projectNumber, isOrg) : null;
+    fs.writeFileSync(cliContextPath, JSON.stringify({
+      projectName,
+      repoOwner,
+      repoName,
+      projectNumber,
+      isOrg,
+      boardUrl,
+      patAutoSet
+    }, null, 2));
   } catch (err) {
     // Non-fatal — agent will ask for the values instead
   }

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.0",
+  "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,