create-agentic-pdlc 2.2.0 → 2.3.0

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

@@ -6,13 +6,12 @@ on:
   pull_request_review:
     types: [submitted]
   issues:
-    types: [labeled, edited]
+    types: [labeled, edited, closed]
 
 env:
   PROJECT_ID: "{{PROJECT_ID}}"
   STATUS_FIELD_ID: "{{STATUS_FIELD_ID}}"
   STATUS_IDEA: "{{ID_IDEA}}"
-  STATUS_EXPLORATION: "{{ID_EXPLORATION}}"
   STATUS_BRAINSTORMING: "{{ID_BRAINSTORMING}}"
   STATUS_DETAILING: "{{ID_DETAILING}}"
   STATUS_APPROVAL: "{{ID_APPROVAL}}"
@@ -40,10 +39,7 @@ jobs:
             let targetStatusId = null;
             let stageName = null;
 
-            if (labelName === 'stage:exploration') {
-              targetStatusId = process.env.STATUS_EXPLORATION;
-              stageName = 'Exploration';
-            } else if (labelName === 'stage:brainstorming') {
+            if (labelName === 'stage:brainstorming') {
               targetStatusId = process.env.STATUS_BRAINSTORMING;
               stageName = 'Brainstorming';
             } else if (labelName === 'stage:detailing') {
@@ -302,3 +298,25 @@ jobs:
             } else {
               await moveItem(pr.node_id);
             }
+
+  cleanup-labels-on-close:
+    name: Issue closed → strip stage/agent labels
+    if: github.event_name == 'issues' && github.event.action == 'closed'
+    runs-on: ubuntu-latest
+    steps:
+      - name: Remove transient labels
+        uses: actions/github-script@v7
+        with:
+          github-token: ${{ secrets.GITHUB_TOKEN }}
+          script: |
+            const { owner, repo } = context.repo;
+            const issue_number = context.payload.issue.number;
+            const toRemove = [
+              'stage:brainstorming', 'stage:detailing',
+              'stage:approval', 'stage:development', 'stage:testing',
+              'agent:working', 'qa:needs-work', 'pr:in-review', 'jules'
+            ];
+            for (const label of toRemove) {
+              await github.rest.issues.removeLabel({ owner, repo, issue_number, name: label }).catch(() => {});
+            }
+            console.log(`Issue #${issue_number} labels cleaned up`);

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

@@ -13,6 +13,8 @@ jobs:
   qa:
     name: AC Coverage Verification (GitHub Models)
     runs-on: ubuntu-latest
+    env:
+      PROJECT_PAT: ${{ secrets.PROJECT_PAT }}
     steps:
       - uses: actions/checkout@v4
         with:
@@ -59,7 +61,7 @@ jobs:
             --max-time 30 || echo "API_ERROR")
 
           if [ "$RESPONSE" = "API_ERROR" ]; then
-            gh pr edit "$PR_NUMBER" --add-label "infra:qa-broken"
+            GH_TOKEN="$PROJECT_PAT" gh api "repos/${GITHUB_REPOSITORY}/issues/${PR_NUMBER}/labels" --method POST -f 'labels[]=infra:qa-broken'
             gh pr comment "$PR_NUMBER" --body "🤖 **QA Agent:** Could not reach GitHub Models API. Manual review required."
             exit 0
           fi
@@ -68,12 +70,12 @@ jobs:
           EXPLANATION=$(echo "$RESPONSE" | python3 -c 'import json,sys; d=json.load(sys.stdin); t=d.get("choices",[{}])[0].get("message",{}).get("content","").strip(); lines=t.split("\n",1); print(lines[1].strip() if len(lines)>1 else "")')
 
           if echo "$VERDICT" | grep -q "^PASS"; then
-            gh pr edit "$PR_NUMBER" --add-label "qa:approved"
+            GH_TOKEN="$PROJECT_PAT" gh api "repos/${GITHUB_REPOSITORY}/issues/${PR_NUMBER}/labels" --method POST -f 'labels[]=qa:approved'
             gh pr comment "$PR_NUMBER" --body "🤖 **QA Agent:** AC coverage verified. ${EXPLANATION}"
           elif echo "$VERDICT" | grep -q "^FAIL"; then
-            gh pr edit "$PR_NUMBER" --add-label "qa:needs-work"
+            GH_TOKEN="$PROJECT_PAT" gh api "repos/${GITHUB_REPOSITORY}/issues/${PR_NUMBER}/labels" --method POST -f 'labels[]=qa:needs-work'
             gh pr comment "$PR_NUMBER" --body "🤖 **QA Agent:** AC coverage insufficient. ${EXPLANATION}"
           else
-            gh pr edit "$PR_NUMBER" --add-label "infra:qa-broken"
+            GH_TOKEN="$PROJECT_PAT" gh api "repos/${GITHUB_REPOSITORY}/issues/${PR_NUMBER}/labels" --method POST -f 'labels[]=infra:qa-broken'
             gh pr comment "$PR_NUMBER" --body "🤖 **QA Agent:** Could not parse GitHub Models response. Manual review required."
           fi

package/templates/AGENTS.md

@@ -30,7 +30,7 @@ Always start from the current `main` HEAD. Never work over stale snapshots.
 ## Mandatory Workflow
 
 0. **Identity**: Always prefix your GitHub comments with `🤖 **Agent:** ` to distinguish yourself.
-1. **Initial State**: When beginning work on a new issue, your very first action must be to apply the `stage:exploration` label using the GitHub CLI (`gh issue edit <N> --add-label "stage:exploration"`).
+1. **Initial State**: When beginning work on a new issue, your very first action must be to apply the `stage:brainstorming` label using the GitHub CLI (`gh issue edit <N> --add-label "stage:brainstorming"`).
 2. Read the issue entirely — understand its type (US/BUG/TASK/SPIKE) and the Acceptance Criteria.
 3. Read `docs/pdlc.md` — understand the PDLC and the Definition of Done in this project.
 4. Read all files mentioned in the issue's technical context.
@@ -64,6 +64,25 @@ When detailing a solution in an issue body, you must **always** include both the
 - `path/to/file.ts` — what changes
 ```
 
+## Stage Transition Rules (non-negotiable)
+
+MUST apply `stage:brainstorming` label immediately on starting work — before reading
+any code, before invoking any skill. Then read context and present problem summary
++ 2–3 solution options in a single message.
+
+MUST NOT add `stage:detailing` label until the user has explicitly selected
+an approach in the current conversation turn. Work done in a prior
+planning session does NOT count as confirmation.
+
+MUST NOT add `spec:approved`, `stage:development`, or manually add
+`stage:approval` — these represent final human approval or the result of it.
+`stage:approval` is only set by system automation after you provide a complete
+spec for human review. Adding them manually triggers irreversible automation
+(Jules dispatch, board move).
+
+Each stage transition requires a fresh explicit signal from the user in the same
+session where the transition happens. These rules have no exceptions.
+
 ## Pipeline Updates
 
 To add or configure optional agents (Jules, QA Agent, Sentinel) at any time:
@@ -80,7 +99,11 @@ Run this when the user says anything like "update the pipeline", "update the boa
 - Never open a PR without passing the tests.
 - Never implement beyond the immediate scope of the issue.
 - Never create future-proofing abstractions for hypothetical features.
-- Never add or remove `stage:*` or `qa:*` labels manually. These are owned by GitHub Actions automation and the PM only.
+- The agent MUST NOT apply these labels under any circumstances (PM only):
+  - `spec:approved`: triggers Jules dispatch + board move to Development.
+  - `qa:approved`: triggers board move to Code Review.
+  - `qa:needs-work`: signals the PR requires changes and halts the flow.
+- Never add or remove stage:* labels manually, except for stage:brainstorming as the initial label when starting work. All other stage transitions are owned by GitHub Actions automation and the PM.
 {{EXTRA_DONT}}
 
 ## Project Standards

package/templates/docs/pdlc.md

@@ -4,9 +4,8 @@
 
 | Column | Meaning | Who moves the card |
 |---|---|---|
-| 💡 Idea — don't move manually to Exploration | Backlog — tell agent: "work on issue #XX" | Don't move manually |
-| 🔍 Exploration | Claude is analyzing code and context | Label `stage:exploration` |
-| 🧠 Brainstorming | Claude proposed approaches, awaiting PM gate | Label `stage:brainstorming` |
+| 💡 Idea | Backlog — tell agent: "work on issue #XX" | Don't move manually |
+| 🧠 Brainstorming | AI reading context, proposing approaches and trade-offs | Label `stage:brainstorming` |
 | 📐 Detail Solution | Claude is writing the technical spec | Label `stage:detailing` |
 | ✅ Approval | Spec ready, awaiting `spec:approved` label | Label `spec:approved` |
 | ⚙️ Development | Agent implementing the spec | Label `stage:development` |
@@ -37,7 +36,6 @@ REPO         = {{REPO_OWNER}}/{{REPO_NAME}}
 | Column | Option ID |
 |---|---|
 | 💡 Idea | `{{ID_IDEA}}` |
-| 🔍 Exploration | `{{ID_EXPLORATION}}` |
 | 🧠 Brainstorming | `{{ID_BRAINSTORMING}}` |
 | 📐 Detail Solution | `{{ID_DETAIL}}` |
 | ✅ Approval | `{{ID_APPROVAL}}` |
@@ -70,7 +68,6 @@ REPO         = {{REPO_OWNER}}/{{REPO_NAME}}
 
 | Label | Entity | Color | Meaning |
 |---|---|---|---|
-| `stage:exploration` | Issue | Purple | Issue is being evaluated |
 | `stage:brainstorming` | Issue | Pink | Proposed approaches awaiting PM gate |
 | `stage:detailing` | Issue | Blue | Technical spec is being written |
 | `stage:development` | Issue | Orange | Agent is implementing the spec |
@@ -81,15 +78,15 @@ REPO         = {{REPO_OWNER}}/{{REPO_NAME}}
 | `qa:needs-work` | PR | Red | QA Agent failed — PR needs changes |
 | `infra:qa-broken` | PR | Orange | QA Agent error — manual review required |
 | `type:us` | Issue | Blue | New feature or behavioral change — full flow |
-| `type:task` | Issue | Yellow | Operational/non-functional change — skips brainstorming |
-| `type:bug` | Issue | Red | Something broken — skips brainstorming |
+| `type:task` | Issue | Yellow | Operational/non-functional change — full flow |
+| `type:bug` | Issue | Red | Something broken — full flow |
 | `type:spike` | Issue | Gray | Research/evaluation — never reaches Development |
 
 ## Approval Gates
 
 **Gate 1 — PM/Ideation (Brainstorming):**
-You comment on the issue approving one of the approaches proposed by the ideation agent.
-Format: *"Approved — proceed with option X."*
+Agent presents problem summary + 2–3 solution options in a single message. You select an approach.
+Format: *"Option X"* or *"Go with B"* or *"Approved — proceed with option X."*
 
 **Gate 2 — Tech Lead (Spec):**
 You add the `spec:approved` label to the issue after reviewing the technical spec in the body.
@@ -101,13 +98,24 @@ The `type:*` label is the authoritative signal — set automatically by the agen
 
 | Label | Flow |
 |---|---|
-| `type:us` | Full flow — exploration → brainstorming → Gate 1 → detailing → approval |
-| `type:task` | Skips brainstorming — exploration → detailing → approval |
-| `type:bug` | Skips brainstorming — exploration → detailing → approval |
-| `type:spike` | Skips brainstorming — exploration → detailing → conclusion comment (never reaches Development) |
+| `type:us` | brainstorming → Gate 1 → detailing → approval |
+| `type:task` | brainstorming → Gate 1 → detailing → approval |
+| `type:bug` | brainstorming → Gate 1 → detailing → approval |
+| `type:spike` | brainstorming → Gate 1 → detailing → conclusion comment (never reaches Development) |
 
 If no `type:*` label present and agent confidence < 85%, defaults to `type:us` (safe fallback — never skips gates by omission).
 
+## Bypass Mechanism
+
+Agents MUST NOT skip any stage. The ONLY authorized bypasses are:
+
+| Mechanism | Who authorizes | What it bypasses |
+|---|---|---|
+| `human-approved` label on issue | PM (human) only | All stage gates |
+| Branch prefix `hotfix/` | PM (human) only | PR gate only |
+
+Agents MUST NOT self-authorize a bypass. Stop and ask the PM explicitly.
+
 ## Definition of Done
 
 An issue is truly done when: