create-agentic-pdlc 2.2.1 → 2.3.0

package/.agentic-pdlc/SETUP_PROMPT.md

@@ -25,10 +25,10 @@ If any of these files are missing, you are in **Setup Mode**. Do not proceed wit
    - **Project basics:** Project Name, Description, Technical Stack (Structure), and GitHub Username (for CODEOWNERS security).
    - **Commands:** Test command, Lint command, Build command.
    - **Invariants:** Critical business rules agents must never violate (e.g. Human-in-the-loop).
-   - **Board IDs:** PROJECT_ID, STATUS_FIELD_ID, column option IDs (provide standard PDLC options: Idea, Exploration, Brainstorming, Detail Solution, Approval, Development, Testing, Code Review / PR, Production). Allow user to answer "skip", which means you leave the placeholders intact.
+   - **Board IDs:** PROJECT_ID, STATUS_FIELD_ID, column option IDs (provide standard PDLC options: Idea, Brainstorming, Detail Solution, Approval, Development, Testing, Code Review / PR, Production). Allow user to answer "skip", which means you leave the placeholders intact.
    - **Architecture Violation:** Ask "Does your project use an automated architecture auditing tool (e.g., a CI job that creates issues with an `architecture-violation` label)?". If yes, uncomment the `move-violation-to-board` job inside `project-automation.yml`. If no, ask if they would like help implementing one, reminding them that it significantly improves their agentic development process. If they decline, you can leave the job commented out.
    - **QA Agent (Variant B):** Ask "Do you plan to use an AI QA Agent (e.g. QAWolf or a secondary script) to verify your PRs before Code Review?". If yes, explain you will adopt Variant B: you will change `STATUS_CODE_REVIEW_PR` to `STATUS_TESTING` inside the `move-card-on-pr-open` job in `project-automation.yml` and uncomment the `move-card-on-qa-pass` job. If no, leave the workflow as Variant A (default) and delete the optional `.github/workflows/qa-agent.yml` template.
-   - **Implementation agent handle:** e.g., `@google-labs-jules`, or "none".
+   - **Implementation agent handle:** e.g., `@google-labs-jules`, or "none". When replacing `{{IMPLEMENTATION_AGENT_LABEL}}` in `agent-trigger.yml`: for Jules use `jules` (the native label the Jules GitHub App watches — **not** `agent:jules`); for other agents use the handle without `@`, lowercase.
 3. Generate and write the missing files replacing the `{{SCREAMING_SNAKE_CASE}}` placeholders using the templates logic you know (usually they reside in standard Agentic PDLC templates).
 4. Offer to run the `gh` commands for labels (`spec:approved`, `pr:in-review`, `pr:approved`, `architecture-violation`).
 5. Commit everything with the message: `chore: setup agentic-pdlc framework`.
@@ -68,6 +68,5 @@ Do not write code for downstream features! Your goal is to refine the Spec, so t
 
 ### 4. Moving the Board (Upstream States)
 As you actively work with the user advancing the feature, you MUST use the GitHub CLI to update internal state labels. This triggers GitHub Actions behind the scenes.
-- Starting context evaluation: Run `gh issue edit <N> --add-label "stage:exploration"`
-- Presenting architecture/approaches: Run `gh issue edit <N> --add-label "stage:brainstorming"`
+- Starting work on an issue (before reading code): Run `gh issue edit <N> --add-label "stage:brainstorming"`
 - Starting to write the technical spec: Run `gh issue edit <N> --add-label "stage:detailing"`

package/.agentic-pdlc/metrics/raw/2026-W18.jsonl

@@ -0,0 +1,2 @@
+{"issueNumber": 5, "stage": "stage:exploration", "durationDays": 3.0}
+{"issueNumber": 5, "stage": "stage:detailing", "durationDays": 1.5}

package/.agentic-pdlc/metrics/raw/2026-W21.jsonl

@@ -0,0 +1,68 @@
+{"issueNumber":66,"stage":"stage:development","durationDays":5}
+{"issueNumber":66,"stage":"stage:approval","durationDays":0}
+{"issueNumber":67,"stage":"stage:brainstorming","durationDays":0}
+{"issueNumber":67,"stage":"stage:detailing","durationDays":0}
+{"issueNumber":67,"stage":"stage:approval","durationDays":0}
+{"issueNumber":74,"stage":"stage:detailing","durationDays":0}
+{"issueNumber":74,"stage":"stage:approval","durationDays":0}
+{"issueNumber":75,"stage":"stage:detailing","durationDays":0}
+{"issueNumber":75,"stage":"stage:approval","durationDays":0}
+{"issueNumber":76,"stage":"stage:detailing","durationDays":0}
+{"issueNumber":76,"stage":"stage:approval","durationDays":0}
+{"issueNumber":78,"stage":"stage:detailing","durationDays":0}
+{"issueNumber":78,"stage":"stage:approval","durationDays":0}
+{"issueNumber":80,"stage":"stage:detailing","durationDays":0}
+{"issueNumber":80,"stage":"stage:approval","durationDays":0}
+{"issueNumber":80,"stage":"stage:development","durationDays":3.1}
+{"issueNumber":84,"stage":"stage:brainstorming","durationDays":0}
+{"issueNumber":84,"stage":"stage:detailing","durationDays":0}
+{"issueNumber":84,"stage":"stage:approval","durationDays":0}
+{"issueNumber":84,"stage":"stage:development","durationDays":0}
+{"issueNumber":85,"stage":"stage:brainstorming","durationDays":0}
+{"issueNumber":85,"stage":"stage:detailing","durationDays":0}
+{"issueNumber":85,"stage":"stage:approval","durationDays":0}
+{"issueNumber":85,"stage":"stage:approval","durationDays":0}
+{"issueNumber":87,"stage":"stage:approval","durationDays":0}
+{"issueNumber":87,"stage":"stage:development","durationDays":0}
+{"issueNumber":87,"stage":"stage:brainstorming","durationDays":0}
+{"issueNumber":87,"stage":"stage:detailing","durationDays":0}
+{"issueNumber":87,"stage":"stage:approval","durationDays":0}
+{"issueNumber":88,"stage":"stage:brainstorming","durationDays":0}
+{"issueNumber":88,"stage":"stage:detailing","durationDays":0}
+{"issueNumber":88,"stage":"stage:approval","durationDays":0}
+{"issueNumber":88,"stage":"stage:development","durationDays":0}
+{"issueNumber":89,"stage":"stage:brainstorming","durationDays":0}
+{"issueNumber":90,"stage":"stage:brainstorming","durationDays":0}
+{"issueNumber":90,"stage":"stage:detailing","durationDays":0}
+{"issueNumber":90,"stage":"stage:approval","durationDays":0}
+{"issueNumber":90,"stage":"stage:approval","durationDays":0}
+{"issueNumber":91,"stage":"stage:brainstorming","durationDays":0}
+{"issueNumber":91,"stage":"stage:detailing","durationDays":0}
+{"issueNumber":91,"stage":"stage:approval","durationDays":0}
+{"issueNumber":91,"stage":"stage:development","durationDays":0}
+{"issueNumber":92,"stage":"stage:brainstorming","durationDays":0}
+{"issueNumber":92,"stage":"stage:detailing","durationDays":0}
+{"issueNumber":92,"stage":"stage:approval","durationDays":0}
+{"issueNumber":92,"stage":"stage:development","durationDays":0}
+{"issueNumber":93,"stage":"stage:brainstorming","durationDays":0}
+{"issueNumber":93,"stage":"stage:detailing","durationDays":0}
+{"issueNumber":93,"stage":"stage:approval","durationDays":0}
+{"issueNumber":93,"stage":"stage:development","durationDays":0}
+{"issueNumber":94,"stage":"stage:brainstorming","durationDays":0}
+{"issueNumber":94,"stage":"stage:detailing","durationDays":0}
+{"issueNumber":94,"stage":"stage:approval","durationDays":0}
+{"issueNumber":96,"stage":"stage:brainstorming","durationDays":0}
+{"issueNumber":96,"stage":"stage:detailing","durationDays":0}
+{"issueNumber":96,"stage":"stage:approval","durationDays":0}
+{"issueNumber":96,"stage":"stage:development","durationDays":0}
+{"issueNumber":97,"stage":"stage:brainstorming","durationDays":0}
+{"issueNumber":97,"stage":"stage:detailing","durationDays":0}
+{"issueNumber":97,"stage":"stage:approval","durationDays":0}
+{"issueNumber":109,"stage":"stage:brainstorming","durationDays":0}
+{"issueNumber":109,"stage":"stage:detailing","durationDays":0}
+{"issueNumber":109,"stage":"stage:approval","durationDays":0}
+{"issueNumber":109,"stage":"stage:development","durationDays":0}
+{"issueNumber":113,"stage":"stage:brainstorming","durationDays":0}
+{"issueNumber":113,"stage":"stage:detailing","durationDays":0}
+{"issueNumber":113,"stage":"stage:approval","durationDays":0}
+{"issueNumber":113,"stage":"stage:development","durationDays":0}

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

@@ -25,7 +25,7 @@ jobs:
             const { owner, repo } = context.repo;
             const since = new Date(Date.now() - 7 * 24 * 60 * 60 * 1000).toISOString();
             const STAGE_LABELS = new Set([
-              'stage:exploration', 'stage:brainstorming', 'stage:detailing',
+              'stage:brainstorming', 'stage:detailing',
               'stage:approval', 'stage:development', 'stage:testing'
             ]);
 
@@ -297,7 +297,6 @@ jobs:
               const records = fs.readFileSync(jsonlPath, 'utf8').trim().split('\n').filter(Boolean).map(JSON.parse);
               if (records.length > 0) {
                 const STAGES = [
-                  ['stage:exploration',   'Exploration'],
                   ['stage:brainstorming', 'Brainstorming'],
                   ['stage:detailing',     'Detailing'],
                   ['stage:approval',      'Approval'],
@@ -394,19 +393,27 @@ jobs:
               console.log(`Created label ${LABEL}`);
             }
 
-            // Close previous pulse issues
+            // Close previous pulse issues; upsert if same week already exists
             const prev = await github.rest.issues.listForRepo({
               owner, repo, labels: LABEL, state: 'open', per_page: 20
             });
+            let existingIssue = null;
             for (const issue of prev.data) {
-              if (issue.title !== title) {
+              if (issue.title === title) {
+                existingIssue = issue;
+                console.log(`Found existing pulse for ${title}: #${issue.number} — will update body`);
+              } else {
                 await github.rest.issues.update({ owner, repo, issue_number: issue.number, state: 'closed' });
                 console.log(`Closed previous pulse: #${issue.number}`);
               }
             }
 
-            // Create new pulse issue
-            const created = await github.rest.issues.create({
-              owner, repo, title, body, labels: [LABEL]
-            });
-            console.log(`✅ Created pulse issue: #${created.data.number} — ${title}`);
+            if (existingIssue) {
+              await github.rest.issues.update({ owner, repo, issue_number: existingIssue.number, body });
+              console.log(`✅ Updated pulse issue: #${existingIssue.number} — ${title}`);
+            } else {
+              const created = await github.rest.issues.create({
+                owner, repo, title, body, labels: [LABEL]
+              });
+              console.log(`✅ Created pulse issue: #${created.data.number} — ${title}`);
+            }

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

@@ -12,7 +12,6 @@ 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') {

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

@@ -64,7 +64,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
@@ -73,13 +73,13 @@ 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/.agentic-pdlc/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,12 +64,35 @@ 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.
+
 ## What NOT to do
 
 - Never commit directly to `main`.
 - Never open a PR without passing the tests.
 - Never implement beyond the immediate scope of the issue.
 - Never create future-proofing abstractions for hypothetical features.
+- 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.
 {{EXTRA_DONT}}
 
 ## Project Standards

package/.agentic-pdlc/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 |
@@ -78,15 +75,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.
@@ -98,13 +95,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/.agentic-setup-prompt.md

@@ -25,10 +25,10 @@ If any of these files are missing, you are in **Setup Mode**. Do not proceed wit
    - **Project basics:** Project Name, Description, Technical Stack (Structure), and GitHub Username (for CODEOWNERS security).
    - **Commands:** Test command, Lint command, Build command.
    - **Invariants:** Critical business rules agents must never violate (e.g. Human-in-the-loop).
-   - **Board IDs:** PROJECT_ID, STATUS_FIELD_ID, column option IDs (provide standard PDLC options: Idea, Exploration, Brainstorming, Detail Solution, Approval, Development, Testing, Code Review / PR, Production). Allow user to answer "skip", which means you leave the placeholders intact.
+   - **Board IDs:** PROJECT_ID, STATUS_FIELD_ID, column option IDs (provide standard PDLC options: Idea, Brainstorming, Detail Solution, Approval, Development, Testing, Code Review / PR, Production). Allow user to answer "skip", which means you leave the placeholders intact.
    - **Architecture Violation:** Ask "Does your project use an automated architecture auditing tool (e.g., a CI job that creates issues with an `architecture-violation` label)?". If yes, uncomment the `move-violation-to-board` job inside `project-automation.yml`. If no, ask if they would like help implementing one, reminding them that it significantly improves their agentic development process. If they decline, you can leave the job commented out.
    - **QA Agent (Variant B):** Ask "Do you plan to use an AI QA Agent (e.g. QAWolf or a secondary script) to verify your PRs before Code Review?". If yes, explain you will adopt Variant B: you will change `STATUS_CODE_REVIEW_PR` to `STATUS_TESTING` inside the `move-card-on-pr-open` job in `project-automation.yml` and uncomment the `move-card-on-qa-pass` job. If no, leave the workflow as Variant A (default) and delete the optional `.github/workflows/qa-agent.yml` template.
-   - **Implementation agent handle:** e.g., `@google-labs-jules`, or "none".
+   - **Implementation agent handle:** e.g., `@google-labs-jules`, or "none". When replacing `{{IMPLEMENTATION_AGENT_LABEL}}` in `agent-trigger.yml`: for Jules use `jules` (the native label the Jules GitHub App watches — **not** `agent:jules`); for other agents use the handle without `@`, lowercase.
 3. Generate and write the missing files replacing the `{{SCREAMING_SNAKE_CASE}}` placeholders using the templates logic you know (usually they reside in standard Agentic PDLC templates).
 4. Offer to run the `gh` commands for labels (`spec:approved`, `pr:in-review`, `pr:approved`, `architecture-violation`).
 5. Commit everything with the message: `chore: setup agentic-pdlc framework`.
@@ -68,6 +68,5 @@ Do not write code for downstream features! Your goal is to refine the Spec, so t
 
 ### 4. Moving the Board (Upstream States)
 As you actively work with the user advancing the feature, you MUST use the GitHub CLI to update internal state labels. This triggers GitHub Actions behind the scenes.
-- Starting context evaluation: Run `gh issue edit <N> --add-label "stage:exploration"`
-- Presenting architecture/approaches: Run `gh issue edit <N> --add-label "stage:brainstorming"`
+- Starting work on an issue (before reading code): Run `gh issue edit <N> --add-label "stage:brainstorming"`
 - Starting to write the technical spec: Run `gh issue edit <N> --add-label "stage:detailing"`

package/.agentic-setup.md

@@ -25,10 +25,10 @@ If any of these files are missing, you are in **Setup Mode**. Do not proceed wit
    - **Project basics:** Project Name, Description, Technical Stack (Structure), and GitHub Username (for CODEOWNERS security).
    - **Commands:** Test command, Lint command, Build command.
    - **Invariants:** Critical business rules agents must never violate (e.g. Human-in-the-loop).
-   - **Board IDs:** PROJECT_ID, STATUS_FIELD_ID, column option IDs (provide standard PDLC options: Idea, Exploration, Brainstorming, Detail Solution, Approval, Development, Testing, Code Review / PR, Production). Allow user to answer "skip", which means you leave the placeholders intact.
+   - **Board IDs:** PROJECT_ID, STATUS_FIELD_ID, column option IDs (provide standard PDLC options: Idea, Brainstorming, Detail Solution, Approval, Development, Testing, Code Review / PR, Production). Allow user to answer "skip", which means you leave the placeholders intact.
    - **Architecture Violation:** Ask "Does your project use an automated architecture auditing tool (e.g., a CI job that creates issues with an `architecture-violation` label)?". If yes, uncomment the `move-violation-to-board` job inside `project-automation.yml`. If no, ask if they would like help implementing one, reminding them that it significantly improves their agentic development process. If they decline, you can leave the job commented out.
    - **QA Agent (Variant B):** Ask "Do you plan to use an AI QA Agent (e.g. QAWolf or a secondary script) to verify your PRs before Code Review?". If yes, explain you will adopt Variant B: you will change `STATUS_CODE_REVIEW_PR` to `STATUS_TESTING` inside the `move-card-on-pr-open` job in `project-automation.yml` and uncomment the `move-card-on-qa-pass` job. If no, leave the workflow as Variant A (default) and delete the optional `.github/workflows/qa-agent.yml` template.
-   - **Implementation agent handle:** e.g., `@google-labs-jules`, or "none".
+   - **Implementation agent handle:** e.g., `@google-labs-jules`, or "none". When replacing `{{IMPLEMENTATION_AGENT_LABEL}}` in `agent-trigger.yml`: for Jules use `jules` (the native label the Jules GitHub App watches — **not** `agent:jules`); for other agents use the handle without `@`, lowercase.
 3. Generate and write the missing files replacing the `{{SCREAMING_SNAKE_CASE}}` placeholders using the templates logic you know (usually they reside in standard Agentic PDLC templates).
 4. Offer to run the `gh` commands for labels (`spec:approved`, `pr:in-review`, `pr:approved`, `architecture-violation`).
 5. Commit everything with the message: `chore: setup agentic-pdlc framework`.
@@ -68,6 +68,5 @@ Do not write code for downstream features! Your goal is to refine the Spec, so t
 
 ### 4. Moving the Board (Upstream States)
 As you actively work with the user advancing the feature, you MUST use the GitHub CLI to update internal state labels. This triggers GitHub Actions behind the scenes.
-- Starting context evaluation: Run `gh issue edit <N> --add-label "stage:exploration"`
-- Presenting architecture/approaches: Run `gh issue edit <N> --add-label "stage:brainstorming"`
+- Starting work on an issue (before reading code): Run `gh issue edit <N> --add-label "stage:brainstorming"`
 - Starting to write the technical spec: Run `gh issue edit <N> --add-label "stage:detailing"`

package/.github/workflows/agentic-metrics.yml

@@ -25,7 +25,7 @@ jobs:
             const { owner, repo } = context.repo;
             const since = new Date(Date.now() - 7 * 24 * 60 * 60 * 1000).toISOString();
             const STAGE_LABELS = new Set([
-              'stage:exploration', 'stage:brainstorming', 'stage:detailing',
+              'stage:brainstorming', 'stage:detailing',
               'stage:approval', 'stage:development', 'stage:testing'
             ]);
 
@@ -297,7 +297,6 @@ jobs:
               const records = fs.readFileSync(jsonlPath, 'utf8').trim().split('\n').filter(Boolean).map(JSON.parse);
               if (records.length > 0) {
                 const STAGES = [
-                  ['stage:exploration',   'Exploration'],
                   ['stage:brainstorming', 'Brainstorming'],
                   ['stage:detailing',     'Detailing'],
                   ['stage:approval',      'Approval'],
@@ -311,11 +310,14 @@ jobs:
                 }
                 const avg = arr => arr.reduce((a, b) => a + b, 0) / arr.length;
 
-                let maxStage = null, maxDays = 0;
+                let maxStage = null, maxDays = -1;
                 const rows = [];
                 for (const [stage, label] of STAGES) {
                   const days = byStage[stage];
-                  if (!days) continue;
+                  if (!days) {
+                    rows.push(`| **${label}** | — | — |`);
+                    continue;
+                  }
                   const a = round1(avg(days));
                   rows.push(`| **${label}** | ${a}d | ${days.length} |`);
                   if (a > maxDays) { maxStage = label; maxDays = a; }
@@ -394,19 +396,27 @@ jobs:
               console.log(`Created label ${LABEL}`);
             }
 
-            // Close previous pulse issues
+            // Close previous pulse issues; upsert if same week already exists
             const prev = await github.rest.issues.listForRepo({
               owner, repo, labels: LABEL, state: 'open', per_page: 20
             });
+            let existingIssue = null;
             for (const issue of prev.data) {
-              if (issue.title !== title) {
+              if (issue.title === title) {
+                existingIssue = issue;
+                console.log(`Found existing pulse for ${title}: #${issue.number} — will update body`);
+              } else {
                 await github.rest.issues.update({ owner, repo, issue_number: issue.number, state: 'closed' });
                 console.log(`Closed previous pulse: #${issue.number}`);
               }
             }
 
-            // Create new pulse issue
-            const created = await github.rest.issues.create({
-              owner, repo, title, body, labels: [LABEL]
-            });
-            console.log(`✅ Created pulse issue: #${created.data.number} — ${title}`);
+            if (existingIssue) {
+              await github.rest.issues.update({ owner, repo, issue_number: existingIssue.number, body });
+              console.log(`✅ Updated pulse issue: #${existingIssue.number} — ${title}`);
+            } else {
+              const created = await github.rest.issues.create({
+                owner, repo, title, body, labels: [LABEL]
+              });
+              console.log(`✅ Created pulse issue: #${created.data.number} — ${title}`);
+            }

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

@@ -8,7 +8,6 @@ on:
 env:
   PROJECT_ID: "PVT_kwHODpFFL84BXg7h"
   STATUS_FIELD_ID: "PVTSSF_lAHODpFFL84BXg7hzhStRHI"
-  STATUS_EXPLORATION: "96ac537d"
   STATUS_BRAINSTORMING: "8eb07c5b"
   STATUS_DETAILING: "9f6ce70e"
   STATUS_APPROVAL: "31bf4610"
@@ -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/.github/workflows/project-automation.yml

@@ -6,13 +6,12 @@ on:
   pull_request_review:
     types: [submitted]
   issues:
-    types: [labeled]
+    types: [labeled, closed]
 
 env:
   PROJECT_ID: "PVT_kwHODpFFL84BXg7h"
   STATUS_FIELD_ID: "PVTSSF_lAHODpFFL84BXg7hzhStRHI"
   STATUS_IDEA: "bb6e5a20"
-  STATUS_EXPLORATION: "96ac537d"
   STATUS_BRAINSTORMING: "8eb07c5b"
   STATUS_DETAILING: "9f6ce70e"
   STATUS_APPROVAL: "31bf4610"
@@ -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') {
@@ -156,11 +152,17 @@ jobs:
                 });
             };
 
+            const stageLabelsToRemove = ['stage:development', 'stage:brainstorming', 'stage:detailing', 'stage:approval', 'jules', 'agent:working'];
+
             if (linkedIssues.length > 0) {
               for (const n of linkedIssues) {
                 const { data: issue } = await github.rest.issues.get({ owner, repo, issue_number: n });
                 await moveItem(issue.node_id);
-                console.log(`Issue #${n} → Testing`);
+                for (const label of stageLabelsToRemove) {
+                  await github.rest.issues.removeLabel({ owner, repo, issue_number: n, name: label }).catch(() => {});
+                }
+                await github.rest.issues.addLabels({ owner, repo, issue_number: n, labels: ['stage:testing'] }).catch(() => {});
+                console.log(`Issue #${n} → Testing (labels updated)`);
               }
             } else {
               await moveItem(pr.node_id);
@@ -282,3 +284,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/.github/workflows/qa-agent.yml

@@ -64,7 +64,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_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
           fi
@@ -73,13 +73,13 @@ 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_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."
           fi
 

package/AGENTS.md

@@ -27,7 +27,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.