create-agentic-pdlc 1.1.1 → 2.0.0

package/README.md

@@ -3,20 +3,24 @@
 [![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
 [![PRs Welcome](https://img.shields.io/badge/PRs-welcome-brightgreen.svg?style=flat-square)](http://makeapullrequest.com)
 
-> **Supercharge your solo development with a fully automated, AI-native Product Development Life Cycle (PDLC).**
+> **Stop fighting your AI agents. Give them structure.**
 
-Building software with AI agents is the future, but raw context windows aren't enough. Without structure, agents lose track, write inconsistent code, and break invariants. 
+**Agentic PDLC** is a lightweight, zero-dependency boilerplate that transforms chaotic AI coding into a deterministic, automated software assembly line.
 
-The **Agentic PDLC Framework** is a lightweight, universal boilerplate that standardizes how your AI assistants (Claude, Cursor, Copilot, etc.) interpret tasks, respect your project's rules, and collaborate seamlessly from an idea to production.
+It standardizes how your AI assistants (Claude, Cursor, Copilot, Jules) interpret tasks, respect invariants, and collaborate seamlessly from an idea to production.
+
+<div align="center">
+  <img src=".github/assets/agentic-pdlc-flow.svg" alt="Agentic PDLC Architecture Flow" width="100%">
+</div>
 
 ---
 
-## 🌟 Why use this framework?
+## ⚡ Why you need this
 
-- 🧠 **Contextual Perfection**: Gives every AI agent a single "source of truth" to abide by (`AGENTS.md`), preventing hallucinated dependencies or broken architectural rules.
-- 🔄 **Automated Handoffs**: Built-in GitHub Actions automate the flow between brainstorming an idea and having an autonomous agent implement it.
-- ⚡ **Multi-Assistant Support**: Works flawlessly whether you use Claude Code in the terminal, Cursor as your IDE, or autonomous sweeper agents.
-- 🛠️ **Setup in Seconds**: Our interactive "Setup Mode" can scaffold your entire product context dynamically!
+- 🧠 **One Contract to Rule Them All**: `AGENTS.md` is your single source of truth. Stop repeating yourself; let every AI read the same invariants.
+- 🤖 **Automated Handoffs**: Move cards across your GitHub board with labels. Brainstorm with Claude upstream, let Jules code downstream.
+- 🚀 **Interactive Setup**: Run one `npx` command and let your favorite AI assistant scaffold the framework into your project interactively.
+- 📈 **Maturity Model**: A clear path from structured (Level 1) to semi-autonomous (Level 3) development. [Read the Agentic Maturity Model](docs/maturity-model.md).
 
 ---
 

package/SETUP.md

@@ -41,7 +41,7 @@ Note down the `PROJECT_ID` and the `STATUS_FIELD_ID` for future steps.
 ```bash
 REPO="owner/repo"
 gh label create "spec:approved"          --repo $REPO --color "0e8a16" --description "Spec approved — agent can implement"
-gh label create "pr:review"              --repo $REPO --color "e4e669" --description "PR awaiting code review"
+gh label create "pr:in-review"           --repo $REPO --color "e4e669" --description "PR awaiting code review"
 gh label create "pr:approved"            --repo $REPO --color "0e8a16" --description "PR approved, ready for merge"
 gh label create "architecture-violation" --repo $REPO --color "d93f0b" --description "Invariant violation detected by CI"
 ```
@@ -122,13 +122,52 @@ For each known idea or feature, create an issue using the convention:
 gh issue create \
   --repo owner/repo \
   --title "👤 US: [short description]" \
-  --body "Initial idea issue. Spec to be detailed."
+  --body "**As** [user],
+**I want** [action],
+**so that** [benefit].
+
+---
+
+Initial idea issue. Spec to be detailed."
 ```
 
 Move the issues to the `Idea` column on the board matching your setup.
 
 ---
 
+## (Optional) Architecture Violation Integration
+
+If your project uses an automated architecture auditing tool (e.g., a CI job that creates issues with an `architecture-violation` label), the Setup Mode can automatically add a GitHub Actions job to `project-automation.yml` that moves these issues to the `Idea` column.
+
+If you skipped this during setup but want to add it later, you can append the following job to `.github/workflows/project-automation.yml` under the `jobs` section:
+
+```yaml
+  move-violation-to-board:
+    name: architecture-violation → 💡 Idea
+    if: github.event_name == 'issues' && github.event.label.name == 'architecture-violation'
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/github-script@v7
+        with:
+          github-token: ${{ secrets.PROJECT_TOKEN }}
+          script: |
+            const issueNodeId = context.payload.issue.node_id;
+            const addResult = await github.graphql(`
+              mutation($p: ID!, $c: ID!) {
+                addProjectV2ItemById(input: {projectId: $p, contentId: $c}) { item { id } }
+              }`, { p: process.env.PROJECT_ID, c: issueNodeId });
+            const itemId = addResult.addProjectV2ItemById.item.id;
+            await github.graphql(`
+              mutation($p: ID!, $i: ID!, $f: ID!, $v: ProjectV2FieldValue!) {
+                updateProjectV2ItemFieldValue(input: {projectId: $p, itemId: $i, fieldId: $f, value: $v}) {
+                  projectV2Item { id }
+                }
+              }`, { p: process.env.PROJECT_ID, i: itemId, f: process.env.STATUS_FIELD_ID,
+                    v: { singleSelectOptionId: process.env.STATUS_IDEA } });
+```
+
+---
+
 ## Final Verification Checklist
 
 - [ ] Board has 10 columns fully configured

package/adapters/claude-code/skill.md

@@ -13,19 +13,22 @@ If the user invokes you in a new project, you must first check if the PDLC artif
 Specifically, check for:
 - `AGENTS.md`
 - `docs/pdlc.md`
+- `.github/CODEOWNERS`
 - `.github/workflows/project-automation.yml`
 - `.github/workflows/agent-trigger.yml`
+- `.github/workflows/pdlc-health-check.yml`
 
 If any of these files are missing, you are in **Setup Mode**. Do not proceed with feature requests until setup is complete.
 1. Acknowledge that the framework is not yet set up.
 2. Interactively ask the user for required values **one group at a time**:
-   - **Project basics:** Project Name, Description, Technical Stack (Structure).
+   - **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, Pull Request, 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, Exploration, Brainstorming, Detail Solution, Approval, Development, Testing, Code Review / PR, Merge, 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, replace `{{OPTIONAL_ARCHITECTURE_VIOLATION_JOB}}` in `project-automation.yml` with the job definition (available in the framework documentation). If no, ask if they would like help implementing one, reminding them that it significantly improves their agentic development process. If they decline, remove the placeholder.
    - **Implementation agent handle:** e.g., `@google-labs-jules`, or "none".
 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:review`, `pr:approved`, `architecture-violation`).
+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`.
 6. Conclude Setup Mode.
 
@@ -44,6 +47,24 @@ When asked to work on a feature, you will:
 
 ### 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:
+
+```
+**As** [user],
+**I want** [action],
+**so that** [benefit].
+
+---
+
+## Acceptance Criteria
+...
+```
 
 ### 3. Handoff
 Do not write code for downstream features! Your goal is to refine the Spec, so the human Tech Lead can label the issue `spec:approved`. This label triggers the downstream agent via `agent-trigger.yml`.
+
+### 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 to write the technical spec: Run `gh issue edit <N> --add-label "stage:detailing"`

package/docs/flow.md

@@ -0,0 +1,160 @@
+# PDLC Flow: From Idea to Production
+
+This document describes the full lifecycle of a card on the agentic-pdlc board — who acts at each stage, what triggers each transition, which labels are added or removed, and where human gates are required.
+
+---
+
+## Roles
+
+| Role | Responsibility |
+|------|---------------|
+| **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 |
+| **Implementation Agent** | Implementation, running tests, opening the PR |
+| **Workflow** | All label swaps and card movements — the source of truth for board state |
+
+> **Principle:** Every board transition must be triggered by a GitHub event (label, PR, review) processed by a workflow. Agents must never be responsible for moving cards.
+
+---
+
+## Step-by-Step Flow
+
+### 💡 Idea
+Issue exists in the backlog with no `upstream:` label.
+
+---
+
+### 🔍 Exploration
+
+**Trigger (two equivalent paths):**
+- PM tells Claude directly in chat → Claude adds `upstream:exploration` to the issue, OR
+- PM adds `upstream:exploration` directly to the issue
+
+**Workflow:** `project-automation.yml` detects `upstream:exploration` → moves card to Exploration.
+
+**Who works:** Claude reads relevant code and context.
+
+---
+
+### 🧠 Brainstorming
+
+**Trigger:** Claude, after exploration.
+
+**Actions:**
+- Claude posts a comment on the issue with findings and 2–3 proposed approaches
+- Claude swaps `upstream:exploration` → `upstream:brainstorming`
+
+**Workflow:** `project-automation.yml` 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.
+
+---
+
+### 📐 Detail Solution ← Gate 1
+
+**Trigger:** `upstream-gate.yml` detects PM approval comment on a `upstream:brainstorming` issue → swaps `upstream:brainstorming` → `upstream:detailing` via `PROJECT_TOKEN`.
+
+**Who works:** Claude rewrites the issue body with:
+1. User story (`As… I want… So that…`)
+2. Acceptance Criteria (AC1, AC2, …)
+3. Files to modify
+
+**After spec is written:** Claude swaps `upstream:detailing` → `upstream:approval`.
+
+**Workflow:** `project-automation.yml` moves card to Approval.
+
+---
+
+### ✅ Approval
+
+**⏸ Human gate (Gate 2 — PM + TL):** Both PM (business decisions) and TL (technical decisions) review the spec. When both are satisfied, PM adds label `spec:approved`.
+
+**Workflow:** `agent-trigger.yml` detects `spec:approved` →
+1. Removes `upstream:approval`
+2. Adds `upstream:development`
+3. Adds specific agent label (e.g., `jules`)
+4. Posts a structured comment with implementation instructions for the Agent
+
+**Workflow:** `project-automation.yml` moves card to Development.
+
+---
+
+### ⚙️ Development
+
+**Who works:** Implementation Agent implements the spec strictly within the Acceptance Criteria.
+
+**When done:** Agent adds `upstream:testing` before running tests.
+
+**Workflow:** `project-automation.yml` moves card to Testing.
+
+---
+
+### 🧪 Testing
+
+**Who works:** Agent runs the test suite (`vitest run` + `typecheck`).
+
+**When tests pass:** Agent opens a PR with `Closes #N` in the body.
+
+**Workflow:** `project-automation.yml` detects PR opened → moves linked issue to Code Review, adds `pr:in-review` label to the PR.
+
+---
+
+### 👁 Code Review ← Gate 3
+
+**⏸ Human gate (Gate 3 — TL / PM):** Reviewer reads the PR, verifies ACs, checks for regressions.
+
+**Trigger:** Reviewer approves the PR via GitHub's native review interface (no label needed).
+
+**Workflow:** `project-automation.yml` detects `pull_request_review: approved` → moves card to Production upon merge. Adds `pr:approved` label to the PR.
+
+---
+
+### 🚀 Production
+
+**Who acts:** PM or TL merges the PR.
+
+**Workflow:** `project-automation.yml` detects PR merged → moves card to Production.
+
+> **Note:** There is no separate "Merge" column. Review and merge happen in tight sequence in practice, and a transient column adds no visibility value.
+
+---
+
+## Label Reference
+
+| Label | Added by | Removed by |
+|-------|----------|------------|
+| `upstream:exploration` | PM (human) or Claude | Claude |
+| `upstream:brainstorming` | Claude | `upstream-gate.yml` |
+| `upstream:detailing` | `upstream-gate.yml` | Claude |
+| `upstream:approval` | Claude | `agent-trigger.yml` |
+| `upstream:development` | `agent-trigger.yml` | Impl. Agent |
+| `upstream:testing` | Impl. Agent | `project-automation.yml` (on PR open) |
+| `spec:approved` | PM (human) | — |
+| `agent_label` (e.g. `jules`, `sweep`) | `agent-trigger.yml` | — |
+| `pr:in-review` | `project-automation.yml` | `project-automation.yml` |
+| `pr:approved` | `project-automation.yml` | — |
+
+---
+
+## Human Gates Summary
+
+| Gate | Who | Trigger | What they decide |
+|------|-----|---------|-----------------|
+| **Gate 1** | PM | Comment on brainstorming issue | Which approach to pursue |
+| **Gate 2** | PM + TL | Add `spec:approved` label | Whether the spec is correct and complete |
+| **Gate 3** | TL / PM | GitHub PR review approval | Whether the implementation meets the ACs |
+
+---
+
+## Known Risk: Autonomous Agents and Informal Comments
+
+Implementation agents often monitor issue comments and can act on informal instructions (e.g., "@agent fix this") — bypassing Gates 1 and 2. This behavior is controlled by the agent's platform and cannot be prevented via GitHub Actions.
+
+**Mitigation:** The effective code quality gate is Gate 3 (PR review + mandatory CI). Never comment directly on issues to instruct the agent outside the `spec:approved` flow.
+
+See [issue #11](https://github.com/rafaeltcosta86/agentic-pdlc/issues/11) for full context.

package/docs/pdlc.md

@@ -4,20 +4,20 @@
 
 | Column | Meaning | Who moves the card |
 |---|---|---|
-| 💡 Idea | Backlog — every new issue lands here | Claude Code / Manual |
-| 🔍 Exploration | Claude is analyzing code and context | Claude Code |
-| 🧠 Brainstorming | Claude proposed approaches, awaiting PM gate | Claude Code |
-| 📐 Detail Solution | Claude is writing the technical spec | Claude Code |
-| ✅ Approval | Spec ready, awaiting `spec:approved` label | Claude Code |
-| ⚙️ Development | Agent implementing the spec | Jules / Implementation Agent |
+| 💡 Idea | Backlog — every new issue lands here | Manual |
+| 🔍 Exploration | Claude is analyzing code and context | Label `stage:exploration` |
+| 🧠 Brainstorming | Claude proposed approaches, awaiting PM gate | 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` |
 | 🧪 Testing | CI pipeline running | GitHub Actions |
-| 👁 Code Review | PR opened, awaiting human review | GitHub Actions |
-| 🔀 Pull Request | PR approved, awaiting merge | GitHub Actions |
+| 👁 Code Review / PR | PR opened, awaiting human review | GitHub Actions |
+| 🔀 Merge | PR approved, awaiting merge | GitHub Actions |
 | 🚀 Production | Merged | GitHub Actions |
 
 <!--
 Adapt columns as needed. The functional baseline is:
-💡 Idea → ⚙️ Development → 👁 Code Review → 🚀 Production
+💡 Idea → ⚙️ Development → 👁 Code Review / PR → 🚀 Production
 -->
 
 ## Board Identifiers (GitHub Projects)
@@ -39,8 +39,8 @@ REPO         = {{REPO_OWNER}}/{{REPO_NAME}}
 | ✅ Approval | `{{ID_APPROVAL}}` |
 | ⚙️ Development | `{{ID_DEVELOPMENT}}` |
 | 🧪 Testing | `{{ID_TESTING}}` |
-| 👁 Code Review | `{{ID_CODE_REVIEW}}` |
-| 🔀 Pull Request | `{{ID_PULL_REQUEST}}` |
+| 👁 Code Review / PR | `{{ID_CODE_REVIEW_PR}}` |
+| 🔀 Merge | `{{ID_MERGE}}` |
 | 🚀 Production | `{{ID_PRODUCTION}}` |
 
 ## Agent × Phase Mapping
@@ -49,7 +49,7 @@ REPO         = {{REPO_OWNER}}/{{REPO_NAME}}
 |---|---|
 | 💡 → 📐 (upstream) | Claude (or ideation agent) in conversational session |
 | ⚙️ → 🔀 (downstream) | {{IMPLEMENTATION_AGENT}} (e.g. Jules `@google-labs-jules`) |
-| 👁 Code Review | Human (you) |
+| 👁 Code Review / PR | Human (you) |
 | Automatic transitions | GitHub Actions |
 
 ## Issue Title Conventions
@@ -67,8 +67,12 @@ 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 |
 | `spec:approved` | Issue | Green | Gate 2 — agent is cleared to implement |
-| `pr:review` | PR | Yellow | Awaiting code review |
+| `pr:in-review` | PR | Yellow | Awaiting code review |
 | `pr:approved` | PR | Green | Code review approved |
 
 ## Approval Gates

package/docs/spikes/04-upstream-flow-gap-analysis.md

@@ -0,0 +1,39 @@
+# Spike: Upstream Flow Gap Analysis
+
+This document analyzes the three gaps identified in the upstream flow of the Agentic PDLC framework and proposes solutions to ensure future projects receive these behaviors out of the box.
+
+## 1. Sprint start → cards move to Exploration automatically
+
+**Analysis:**
+Currently, when a PM selects issues for a sprint and tells the upstream agent to begin, the cards do not move automatically unless the agent explicitly runs a `gh issue edit` command.
+- `AGENTS.md` does not instruct the upstream agent to add `stage:exploration` (or equivalent) as its first action upon starting.
+- `project-automation.yml` does respond to the label `stage:exploration` and moves the card to the Exploration column.
+- The label naming convention (`stage:exploration`, `stage:brainstorming`, `stage:detailing`) is established in the workflow but not explicitly documented as a mandatory first step for the agent.
+
+**Solution (Gap):**
+- **Fix:** Update `AGENTS.md` and `adapters/claude-code/skill.md` to explicitly instruct the agent: *"When beginning work on a new issue, your first action must be to apply the `stage:exploration` label using the GitHub CLI."*
+
+## 2. Brainstorm gate — agent observes comments for PM approval
+
+**Analysis:**
+After the agent posts an exploration/brainstorming comment on the issue, it needs PM feedback (approval or requested changes) to proceed to Solution Detail.
+- There is no mechanism (webhook or workflow) for the upstream agent to automatically detect PM approval in an issue comment.
+- In current practice, the PM must manually notify the agent in the chat (e.g., "The brainstorm for #123 is approved").
+- This is a known limitation of current agent interfaces (which require explicit chat prompts to resume execution) and is not documented in the framework.
+
+**Solution (Gap):**
+- **Fix:** Acknowledge this limitation in the framework documentation. Update `SETUP.md` and/or a new `docs/workflow-guide.md` to establish the pattern: *"To pass Gate 1 (Brainstorming), the PM must review the issue comments and explicitly tell the agent in the chat to proceed to detailing for that specific issue."*
+
+## 3. spec:approved → implementation agent picks up the card
+
+**Analysis:**
+Cards in the "Approval" column wait for the PM to add the `spec:approved` label to signal the handoff to the implementation agent.
+- `agent-trigger.yml` correctly fires on the `spec:approved` label and comments on the issue to notify the implementation agent (e.g., Jules).
+- However, when `spec:approved` is added, `project-automation.yml` currently tries to move the card to `STATUS_APPROVAL` — which is the column it is already in.
+- The intent is for the card to move to "Development" when the handoff occurs.
+
+**Solution (Gap):**
+- **Fix:** Update `project-automation.yml`. In the `move-card-on-label` job, change the target status for `spec:approved` from `STATUS_APPROVAL` to `STATUS_DEVELOPMENT`.
+
+---
+*This analysis addresses the questions raised in Issue #4.*

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "create-agentic-pdlc",
-  "version": "1.1.1",
+  "version": "2.0.0",
   "description": "Scaffold the Agentic PDLC framework effortlessly",
   "type": "commonjs",
   "bin": {

package/templates/.github/CODEOWNERS

@@ -0,0 +1,5 @@
+# This file prevents autonomous agents from modifying core security, automation, and instruction rules
+# without explicit approval from the repository owner.
+
+.github/ @{{GITHUB_USERNAME}}
+AGENTS.md @{{GITHUB_USERNAME}}

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

@@ -12,8 +12,41 @@ jobs:
     # Runs only when spec:approved is added
     if: github.event.label.name == 'spec:approved'
     runs-on: ubuntu-latest
+    permissions:
+      issues: write
+      pull-requests: write
+      contents: read
+    env:
+      PROJECT_TOKEN: ${{ secrets.PROJECT_TOKEN }}
     steps:
-      - name: Comment on issue to trigger agent
+      - name: Update Labels
+        if: ${{ env.PROJECT_TOKEN != '' }}
+        uses: actions/github-script@v7
+        with:
+          github-token: ${{ env.PROJECT_TOKEN }}
+          script: |
+            const { owner, repo } = context.repo;
+            const issue_number = context.payload.issue.number;
+            
+            try {
+              await github.rest.issues.removeLabel({
+                owner,
+                repo,
+                issue_number,
+                name: 'upstream:approval'
+              });
+            } catch (error) {
+              console.log('Label upstream:approval not found or could not be removed');
+            }
+            
+            await github.rest.issues.addLabels({
+              owner,
+              repo,
+              issue_number,
+              labels: ['upstream:development', '{{IMPLEMENTATION_AGENT_LABEL}}', 'agent:working']
+            });
+
+      - name: Comment on issue to trigger agent and prevent race conditions
         uses: actions/github-script@v7
         with:
           github-token: ${{ secrets.GITHUB_TOKEN }}
@@ -22,6 +55,8 @@ jobs:
             const issueTitle = context.payload.issue.title;
 
             const body = [
+              `🤖 **Agentic PDLC Orchestrator:** I have dispatched the implementation agent. Please wait for the Pull Request and avoid making concurrent commits on this task to prevent race conditions.`,
+              '',
               `{{AGENT_HANDLE}} The spec for this issue has been approved. Please implement it exactly as described in the body above.`,
               '',
               '**Mandatory steps before you begin:**',
@@ -48,6 +83,10 @@ jobs:
     # Runs when architecture-violation is added (Sentinel flow)
     if: github.event.label.name == 'architecture-violation'
     runs-on: ubuntu-latest
+    permissions:
+      issues: write
+      pull-requests: write
+      contents: read
     steps:
       - name: Comment on issue to trigger agent
         uses: actions/github-script@v7

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

@@ -22,6 +22,9 @@ jobs:
       - name: Run Linters
         run: {{LINT_COMMAND}}
 
+      - name: Typecheck
+        run: {{TYPECHECK_COMMAND}}
+
       - name: Build
         run: {{BUILD_COMMAND}}
 

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

@@ -0,0 +1,123 @@
+name: PDLC Health Check (Drift Detection)
+
+on:
+  workflow_dispatch:
+  schedule:
+    - cron: '0 8 * * 1' # Every Monday at 8am
+
+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}}"
+  STATUS_DEVELOPMENT: "{{ID_DEVELOPMENT}}"
+  STATUS_TESTING: "{{ID_TESTING}}"
+  STATUS_CODE_REVIEW_PR: "{{ID_CODE_REVIEW_PR}}"
+  STATUS_PRODUCTION: "{{ID_PRODUCTION}}"
+
+jobs:
+  check-drift:
+    name: Detect Project Board Drift
+    runs-on: ubuntu-latest
+    env:
+      PROJECT_TOKEN: ${{ secrets.PROJECT_TOKEN }}
+    permissions:
+      issues: write
+    steps:
+      - name: Validate Board Configuration
+        if: ${{ env.PROJECT_TOKEN != '' && env.PROJECT_ID != '{{PROJECT_ID}}' }}
+        uses: actions/github-script@v7
+        with:
+          github-token: ${{ env.PROJECT_TOKEN }}
+          script: |
+            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,
+              'STATUS_DEVELOPMENT': process.env.STATUS_DEVELOPMENT,
+              'STATUS_TESTING': process.env.STATUS_TESTING,
+              'STATUS_CODE_REVIEW_PR': process.env.STATUS_CODE_REVIEW_PR,
+              'STATUS_PRODUCTION': process.env.STATUS_PRODUCTION
+            };
+
+            const query = `
+              query($projectId: ID!) {
+                node(id: $projectId) {
+                  ... on ProjectV2 {
+                    title
+                    fields(first: 20) {
+                      nodes {
+                        ... on ProjectV2SingleSelectField {
+                          id
+                          name
+                          options {
+                            id
+                            name
+                          }
+                        }
+                      }
+                    }
+                  }
+                }
+              }
+            `;
+
+            let result;
+            try {
+              result = await github.graphql(query, { projectId });
+            } catch (error) {
+              console.log("❌ Error fetching project. Verify your PROJECT_ID.");
+              console.log(error);
+              return;
+            }
+
+            const project = result.node;
+            if (!project) {
+              console.log("❌ Project not found.");
+              return;
+            }
+
+            const statusField = project.fields.nodes.find(f => f.id === statusFieldId);
+            if (!statusField) {
+              console.log("❌ Status field not found.");
+              return;
+            }
+
+            const validOptions = statusField.options;
+            const validOptionIds = validOptions.map(o => o.id);
+
+            let hasDrift = false;
+            let missingVars = [];
+
+            for (const [varName, id] of Object.entries(envVars)) {
+              if (id && !id.startsWith('{{') && !validOptionIds.includes(id)) {
+                hasDrift = true;
+                missingVars.push(varName);
+              }
+            }
+
+            if (hasDrift) {
+              console.log("🚨 Drift detected! The following mapped columns no longer exist: " + missingVars.join(", "));
+              
+              let table = "| Column Name | New ID |\n|---|---|\n";
+              validOptions.forEach(opt => {
+                table += `| ${opt.name} | \`${opt.id}\` |\n`;
+              });
+
+              const body = `🚨 **Agentic PDLC Drift Detected**\n\nThe following columns mapped in your \`.github/workflows/project-automation.yml\` no longer exist in your project board:\n\n**${missingVars.join(", ")}**\n\n### How to fix it:\nHere is the list of current columns in your board with their valid IDs. Please update the \`env\` block in your \`.github/workflows/project-automation.yml\` and \`.github/workflows/pdlc-health-check.yml\`.\n\n${table}`;
+
+              await github.rest.issues.create({
+                owner: context.repo.owner,
+                repo: context.repo.repo,
+                title: '🚨 Agentic PDLC Drift Detected in Project Board',
+                body: body,
+                labels: ['bug']
+              });
+            } else {
+              console.log("✅ No drift detected. Board configuration is healthy.");
+            }