create-agentic-pdlc 2.1.5 → 2.2.0

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

@@ -6,22 +6,123 @@ on:
 permissions:
   pull-requests: write
   contents: read
+  issues: read
+  models: read
 
 jobs:
   qa:
-    name: Run AI QA Agent
+    name: AC Coverage Verification (GitHub Models)
     runs-on: ubuntu-latest
+    env:
+      PROJECT_TOKEN: ${{ secrets.PROJECT_TOKEN }}
+      PROJECT_ID: "PVT_kwHODpFFL84BXg7h"
+      STATUS_FIELD_ID: "PVTSSF_lAHODpFFL84BXg7hzhStRHI"
+      STATUS_CODE_REVIEW_PR: "86ca9720"
     steps:
       - uses: actions/checkout@v4
-      - name: Execute QA Tests
-        run: |
-          echo "Run your QA Agent here."
-          echo "This could be QAWolf, a custom LLM script, or a secondary agent."
-          echo "If tests pass: gh pr edit $PR_URL --add-label 'qa:pass'"
-          echo "If tests fail: gh pr edit $PR_URL --add-label 'qa:fail'"
-          
-          # Example success:
-          # gh pr edit ${{ github.event.pull_request.html_url }} --add-label "qa:pass"
+        with:
+          fetch-depth: 0
+
+      - name: Verify AC Coverage via GitHub Models
         env:
           GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
-          PR_URL: ${{ github.event.pull_request.html_url }}
+        run: |
+          set -e
+
+          PR_NUMBER="${{ github.event.pull_request.number }}"
+          BASE="${{ github.event.pull_request.base.sha }}"
+          HEAD="${{ github.event.pull_request.head.sha }}"
+
+          # Get PR diff (truncated to 8000 chars to stay within context limits)
+          DIFF=$(git diff "$BASE" "$HEAD" | head -c 64000)
+
+          # Extract linked issues from PR body
+          PR_BODY=$(gh pr view "$PR_NUMBER" --json body --jq '.body // ""')
+          ISSUE_NUMS=$(echo "$PR_BODY" | grep -oiE '(Closes?|Fixes?|Resolves?)\s+#([0-9]+)' | grep -oE '[0-9]+' || true)
+
+          # Build acceptance criteria context
+          AC_CONTEXT=""
+          if [ -n "$ISSUE_NUMS" ]; then
+            for NUM in $ISSUE_NUMS; do
+              ISSUE_BODY=$(gh issue view "$NUM" --json body --jq '.body // ""' 2>/dev/null || echo "")
+              AC_CONTEXT="${AC_CONTEXT}\\n\\n--- Issue #${NUM} ---\\n${ISSUE_BODY}"
+            done
+          fi
+
+          if [ -z "$AC_CONTEXT" ]; then
+            AC_CONTEXT="No linked issue found. Evaluate if the PR description is self-contained."
+          fi
+
+          # Serialize prompt as JSON string and call GitHub Models API (30s timeout)
+          PROMPT_JSON=$(printf '%s' "You are a senior QA engineer. Review whether this PR diff satisfies the Acceptance Criteria below.\n\nACCEPTANCE CRITERIA:\n${AC_CONTEXT}\n\nPR DIFF:\n${DIFF}\n\nFirst line of your response must be exactly one word: PASS or FAIL. Second line: brief explanation (max 3 sentences)." | python3 -c 'import json,sys; print(json.dumps(sys.stdin.read()))')
+
+          RESPONSE=$(curl -sf -X POST \
+            "https://models.github.ai/inference/chat/completions" \
+            -H "Authorization: Bearer ${GITHUB_TOKEN}" \
+            -H "Content-Type: application/json" \
+            -d "{\"model\":\"gpt-4o-mini\",\"messages\":[{\"role\":\"user\",\"content\":${PROMPT_JSON}}]}" \
+            --max-time 30 || echo "API_ERROR")
+
+          if [ "$RESPONSE" = "API_ERROR" ]; then
+            gh pr edit "$PR_NUMBER" --add-label "infra:qa-broken"
+            gh pr comment "$PR_NUMBER" --body "🤖 **QA Agent:** Could not reach GitHub Models API. Manual review required."
+            exit 0
+          fi
+
+          VERDICT=$(echo "$RESPONSE" | python3 -c 'import json,sys,re; d=json.load(sys.stdin); t=d.get("choices",[{}])[0].get("message",{}).get("content","").strip(); first=t.split("\n")[0].upper() if t else ""; print("FAIL" if re.search(r"\bFAIL\b",first) else "PASS" if re.search(r"\bPASS\b",first) else "API_ERROR")')
+          EXPLANATION=$(echo "$RESPONSE" | python3 -c 'import json,sys; d=json.load(sys.stdin); t=d.get("choices",[{}])[0].get("message",{}).get("content","").strip(); lines=t.split("\n",1); print(lines[1].strip() if len(lines)>1 else "")')
+
+          if echo "$VERDICT" | grep -q "^PASS"; then
+            gh pr edit "$PR_NUMBER" --add-label "qa:approved"
+            gh 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 pr comment "$PR_NUMBER" --body "🤖 **QA Agent:** AC coverage insufficient. ${EXPLANATION}"
+          else
+            gh pr edit "$PR_NUMBER" --add-label "infra:qa-broken"
+            gh pr comment "$PR_NUMBER" --body "🤖 **QA Agent:** Could not parse GitHub Models response. Manual review required."
+          fi
+
+      - name: Move board card to Code Review on qa:approved
+        if: ${{ env.PROJECT_TOKEN != '' && env.PROJECT_ID != '{{PROJECT_ID}}' }}
+        uses: actions/github-script@v7
+        with:
+          github-token: ${{ env.PROJECT_TOKEN }}
+          script: |
+            const prNumber = context.payload.pull_request.number;
+            const { owner, repo } = context.repo;
+
+            const { data: pr } = await github.rest.pulls.get({ owner, repo, pull_number: prNumber });
+            if (!pr.labels.some(l => l.name === 'qa:approved')) {
+              console.log('qa:approved not on PR — skipping board move');
+              return;
+            }
+
+            const body = pr.body ?? '';
+            const linkedIssues = [...body.matchAll(/(?:Closes?|Fixes?|Resolves?)\s+#(\d+)/gi)]
+              .map(m => parseInt(m[1]));
+
+            const moveItem = async (nodeId) => {
+              const { addProjectV2ItemById: { item } } = await github.graphql(`
+                mutation($p: ID!, $c: ID!) {
+                  addProjectV2ItemById(input: {projectId: $p, contentId: $c}) { item { id } }
+                }`, { p: process.env.PROJECT_ID, c: nodeId });
+              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: item.id, f: process.env.STATUS_FIELD_ID,
+                     v: { singleSelectOptionId: process.env.STATUS_CODE_REVIEW_PR } });
+            };
+
+            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} → Code Review / PR`);
+              }
+            } else {
+              await moveItem(pr.node_id);
+              console.log(`PR #${prNumber} → Code Review / PR (no linked issue)`);
+            }

package/CLAUDE.md

@@ -0,0 +1,9 @@
+# PDLC Stage Gate
+
+NEVER run `gh pr create` unless one of these is true:
+- The linked issue has label `stage:approval`
+- The branch name starts with `hotfix/`
+
+Advance stages first: `exploration` → `brainstorming` → `detailing` → `approval`
+
+The PreToolUse hook will block the action automatically if this rule is violated.

package/README.md

@@ -33,6 +33,14 @@ npx create-agentic-pdlc
 
 The CLI sets up your GitHub board, labels, and workflows, then hands over to your AI assistant to finish the configuration interactively. No YAML editing. No manual config.
 
+**Already set up? Add or reconfigure optional agents at any time:**
+
+```bash
+npx create-agentic-pdlc --update
+```
+
+Detects what is already configured (Jules, QA Agent, Sentinel) and interactively sets up what is missing. Your existing board IDs and customizations are never touched.
+
 ---
 
 ## 🏗️ How It Works

package/SETUP.md

@@ -149,6 +149,34 @@ If you don't use this, you can safely delete `templates/.github/workflows/qa-age
 
 ---
 
+## (Optional) Agentic Metrics — Weekly Report
+
+Every Sunday a `📊 Agentic Pulse` issue is created automatically in your repository with agentic-specific insights no off-the-shelf tool provides:
+
+- **Orphan issues** — open 14+ days with no linked PR (forgotten or blocked work)
+- **PR merge time trend** — week-over-week comparison (flow acceleration or slowdown)
+- **Rework rate** — PRs merged without extra commit sessions (agent or human first-shot rate)
+- **Unlinked PRs** — merged without `Closes #N` (traceability gaps)
+- **Stage Residence Time** — included automatically if your team uses `stage:*` labels _(Milestone 2)_
+
+The issue appears in your GitHub notifications automatically — zero extra setup, zero extra secrets.
+
+**To activate:**
+
+1. Copy the workflow to your repository:
+   ```bash
+   cp .agentic-pdlc/templates/.github/workflows/agentic-metrics.yml .github/workflows/agentic-metrics.yml
+   ```
+
+2. Commit and push. The first pulse runs next Sunday, or trigger it manually:
+   ```bash
+   gh workflow run agentic-metrics.yml
+   ```
+
+> **No additional secrets needed.** The workflow uses the standard `GITHUB_TOKEN` and creates a `metrics:weekly` label automatically on first run.
+
+---
+
 ## Final Verification Checklist
 
 - [ ] Board has 10 columns fully configured

package/adapters/claude-code/skill.md

@@ -42,7 +42,7 @@ If any of these files are missing, you are in **Setup Mode**. Do not proceed wit
      - c) **Yes, activate** — *Uncomment the `move-violation-to-board` job in `project-automation.yml`.* → Activate immediately.
    - **QA Agent:** Ask: *"Do you want to use a QA agent to verify PRs automatically before Code Review?"* Present the options:
      - a) **No (Variant A)** — *PRs go straight to Code Review. Standard and simpler.*
-     - b) **Yes (Variant B), but I need help configuring it** — *PRs pass through a QA Agent before being reviewed. Requires a `GEMINI_API_KEY` secret (free tier available at ai.google.dev).* → Guide the user through configuration.
+     - b) **Yes (Variant B), but I need help configuring it** — *PRs pass through a QA Agent before being reviewed. Uses `GITHUB_TOKEN` — zero additional secrets.* → Guide the user through configuration.
      - c) **Yes (Variant B), I already have it configured** — *PRs pass through a QA Agent before being reviewed.* → Activate Variant B immediately: change `STATUS_CODE_REVIEW_PR` to `STATUS_TESTING` in the `move-card-on-pr-open` job and uncomment the `move-card-on-qa-pass` job in `project-automation.yml`.
    - **Implementation Agent:** Ask: *"Do you use an autonomous implementation agent? (It implements the features you approve for development)"* Present the options:
      - a) **No** — *No autonomous implementation agent.*
@@ -86,7 +86,32 @@ This detects which optional agents (Jules, QA Agent, Sentinel) are already confi
 
 If `AGENTS.md` and `docs/pdlc.md` are present, you are in **Execution Mode**. 
 
-### 0. Board Labels — Mandatory at Every State Transition
+### 0. [FIRST] Issue Type Identification
+
+**Run before anything else — before `stage:exploration`, 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.
+
+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).
+3. Classify using these rules:
+   - `type:task` — operational change, config, rename, docs update, non-functional (no user-facing behavior change)
+   - `type:bug` — something broken that should work
+   - `type:spike` — research/evaluation spike, never reaches Development
+   - `type:us` — new feature, behavioral change, anything product-facing
+4. Confidence ≥ 85% → add inferred label: `gh issue edit <N> --add-label "type:<inferred>"`
+5. Confidence < 85% → default to `type:us`: `gh issue edit <N> --add-label "type:us"`
+
+**Type drives the PDLC flow:**
+
+| Type | Flow |
+|---|---|
+| `type:us` | Full flow: exploration → brainstorming → Gate 1 → detailing → approval |
+| `type:task` | Skip brainstorming: exploration → detailing → approval |
+| `type:bug` | Skip brainstorming: exploration → detailing → approval |
+| `type:spike` | Skip brainstorming: exploration → detailing → conclusion comment (never reaches Development) |
+
+### 0.1 Board Labels — Mandatory at Every State Transition
 
 These label commands are non-negotiable. They run **before** the activity they announce — before reading code, before invoking any skill, before any other action.
 
@@ -98,8 +123,21 @@ These label commands are non-negotiable. They run **before** the activity they a
 
 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).
 
+### 0.1 PR Stage Gate — Non-Negotiable
+
+**NEVER run `gh pr create` unless the linked issue has label `stage:approval`.**
+
+The PreToolUse hook enforces this automatically and will block the command. The only bypass is a branch prefixed with `hotfix/` — which requires explicit PM instruction, never agent self-authorization.
+
+Hotfix flow (only when PM explicitly requests it):
+```bash
+gh issue edit <N> --add-label "hotfix"
+git checkout -b hotfix/<N>-<description>
+# implement → gh pr create --label hotfix
+```
+
 ### 1. Daily Upstream Loop
-Your job is to move issues from "Idea" to "Detail Solution".
+Your job is to move issues from "💡 Idea - don't move manually to Exploration" 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

@@ -0,0 +1,44 @@
+#!/bin/bash
+# PDLC Stage Gate — blocks gh pr create without stage:approval on linked issue.
+# Bypass: branch prefix hotfix/ skips all checks.
+
+INPUT=$(cat)
+COMMAND=$(echo "$INPUT" | node -e "const d=JSON.parse(require('fs').readFileSync(0)); console.log(d.command || '')" 2>/dev/null || echo "")
+
+if ! echo "$COMMAND" | grep -q "gh pr create"; then
+  exit 0
+fi
+
+BRANCH=$(git branch --show-current 2>/dev/null || echo "")
+
+if echo "$BRANCH" | grep -qE "^hotfix/"; then
+  echo "✅ PDLC: Hotfix branch — stage gate bypassed."
+  exit 0
+fi
+
+ISSUE_NUM=$(echo "$BRANCH" | grep -oE '[0-9]+' | head -1)
+
+if [ -z "$ISSUE_NUM" ]; then
+  echo "❌ PDLC Stage Gate: Cannot determine issue from branch '$BRANCH'."
+  echo "   Use: feat/<issue-number>-<description> or hotfix/<issue-number>-<description>"
+  exit 1
+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."
+  exit 0
+fi
+
+if echo "$LABELS" | grep -qw "stage:development"; then
+  echo "✅ PDLC: Issue #$ISSUE_NUM in development (spec already approved) — gate passed."
+  exit 0
+fi
+
+STAGE=$(echo "$LABELS" | tr ' ' '\n' | grep "^stage:" | head -1 || echo "none")
+echo "❌ PDLC Stage Gate: Issue #$ISSUE_NUM is not approved."
+echo "   Current stage: $STAGE"
+echo "   Required: stage:approval or stage:development label on the issue."
+echo "   Emergency bypass: rename branch to hotfix/<issue-number>-<description>."
+exit 1

package/bin/cli.js

@@ -68,8 +68,8 @@ const i18n = {
   update_jules_header: t('— Jules (autonomous implementation agent) —', '— Jules (agente de implementação autônomo) —', '— Jules (agente de implementación autónomo) —'),
   update_jules_ask: t('  Which agent? (a) @google-labs-jules  (b) Other  (c) Skip: ', '  Qual agente? (a) @google-labs-jules  (b) Outro  (c) Pular: ', '  ¿Qué agente? (a) @google-labs-jules  (b) Otro  (c) Omitir: '),
   update_jules_ask_handle: t('  Agent handle (e.g. @my-agent): ', '  Handle do agente (ex: @meu-agente): ', '  Handle del agente (ej: @mi-agente): '),
-  update_qa_header: t('— QA Agent (AC verification via Gemini — free tier) —', '— QA Agent (verificação de ACs via Gemini — free tier) —', '— QA Agent (verificación de ACs via Gemini — free tier) —'),
-  update_qa_ask: t('  Activate? Requires GEMINI_API_KEY secret. (Y/n): ', '  Ativar? Requer secret GEMINI_API_KEY. (S/n): ', '  ¿Activar? Requiere el secret GEMINI_API_KEY. (S/n): '),
+  update_qa_header: t('— QA Agent (AC verification via GitHub Models — zero secrets) —', '— QA Agent (verificação de ACs via GitHub Models — zero secrets) —', '— QA Agent (verificación de ACs via GitHub Models — zero secrets) —'),
+  update_qa_ask: t('  Activate? Uses GITHUB_TOKEN — no extra secrets needed. (Y/n): ', '  Ativar? Usa GITHUB_TOKEN — nenhum secret extra necessário. (S/n): ', '  ¿Activar? Usa GITHUB_TOKEN — sin secrets adicionales. (S/n): '),
   update_sentinel_header: t('— Sentinel (architecture audit via Gemini Code Assist) —', '— Sentinel (auditoria de arquitetura via Gemini Code Assist) —', '— Sentinel (auditoría de arquitectura via Gemini Code Assist) —'),
   update_sentinel_ask: t('  Activate? Requires Gemini Code Assist CI job. (Y/n): ', '  Ativar? Requer CI job do Gemini Code Assist. (S/n): ', '  ¿Activar? Requiere CI job de Gemini Code Assist. (S/n): '),
 };
@@ -343,6 +343,29 @@ async function runSetup() {
     // Non-fatal — agent will ask for the values instead
   }
 
+  // Install PDLC stage gate hook (all agents)
+  const hookSrc = path.join(sourceDir, 'adapters', 'hooks', 'pdlc-stage-gate.sh');
+  const hookDir = path.join(targetDir, '.agentic-pdlc', 'hooks');
+  const hookDest = path.join(hookDir, 'pdlc-stage-gate.sh');
+  if (fs.existsSync(hookSrc)) {
+    fs.mkdirSync(hookDir, { recursive: true });
+    fs.copyFileSync(hookSrc, hookDest);
+    fs.chmodSync(hookDest, '755');
+  }
+  const claudeSettingsDir = path.join(targetDir, '.claude');
+  const claudeSettingsPath = path.join(claudeSettingsDir, 'settings.json');
+  if (!fs.existsSync(claudeSettingsPath)) {
+    fs.mkdirSync(claudeSettingsDir, { recursive: true });
+    fs.writeFileSync(claudeSettingsPath, JSON.stringify({
+      hooks: {
+        PreToolUse: [{
+          matcher: 'Bash',
+          hooks: [{ type: 'command', command: 'bash .agentic-pdlc/hooks/pdlc-stage-gate.sh' }]
+        }]
+      }
+    }, null, 2) + '\n');
+  }
+
   // Handle the specific setup instructions target
   const claudeSetupSrc = path.join(sourceDir, 'adapters', 'claude-code', 'skill.md');
   const cursorSetupSrc = path.join(sourceDir, 'adapters', 'cursor', 'rules.md');
@@ -536,9 +559,9 @@ async function runUpdate() {
     if (!['n', 'no', 'não', 'nao'].includes(answer)) {
       activateQaAgent(paPath);
       results.push(t(
-        '✅  QA Agent configured — Variant B activated\n     Next: gh secret set GEMINI_API_KEY --body "<your-key>"',
-        '✅  QA Agent configurado — Variant B ativado\n     Próximo: gh secret set GEMINI_API_KEY --body "<sua-chave>"',
-        '✅  QA Agent configurado — Variant B activado\n     Siguiente: gh secret set GEMINI_API_KEY --body "<tu-clave>"'
+        '✅  QA Agent configured — Variant B activated (uses GITHUB_TOKEN, no extra secrets needed)',
+        '✅  QA Agent configurado — Variant B ativado (usa GITHUB_TOKEN, nenhum secret extra necessário)',
+        '✅  QA Agent configurado — Variant B activado (usa GITHUB_TOKEN, sin secrets adicionales)'
       ));
     } else {
       results.push(t('⏭  QA Agent — skipped', '⏭  QA Agent — pulado', '⏭  QA Agent — omitido'));

package/docs/pdlc.md

@@ -4,7 +4,7 @@
 
 | Column | Meaning | Who moves the card |
 |---|---|---|
-| 💡 Idea | Backlog — every new issue lands here | Manual |
+| 💡 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` |
 | 📐 Detail Solution | AI is writing the technical spec | Label `stage:detailing` |
@@ -72,6 +72,10 @@ REPO         = {{REPO_OWNER}}/{{REPO_NAME}}
 | `spec:approved` | Issue | Green | Gate 2 — agent is cleared to implement |
 | `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:spike` | Issue | Gray | Research/evaluation — never reaches Development |
 
 ## Approval Gates
 
@@ -85,10 +89,16 @@ This triggers the implementation agent via `agent-trigger.yml`.
 
 ## Shortcuts by Type
 
-- **BUG** — Skips Brainstorming; enters Detail Solution with diagnostics + fix.
-- **TASK** — Skips Brainstorming; enters Detail Solution with operational steps.
-- **SPIKE** — Never reaches Development; delivery is a concluding comment.
-- **US** — Full flow observing both gates.
+The `type:*` label is the authoritative signal — set automatically by the agent via type inference (see `adapters/claude-code/skill.md`). Title prefixes (`🔧 TASK:`, `👤 US:`) are hints for humans; the label drives the flow.
+
+| 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) |
+
+If no `type:*` label present and agent confidence < 85%, defaults to `type:us` (safe fallback — never skips gates by omission).
 
 ## Definition of Done
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "create-agentic-pdlc",
-  "version": "2.1.5",
+  "version": "2.2.0",
   "description": "Agentic PDLC Framework - Conversational setup for your AI coding assistants",
   "type": "commonjs",
   "bin": {

package/pr_comments.json

@@ -0,0 +1,20 @@
+{
+  "body": "![security-high](https://www.gstatic.com/codereviewagent/security-high-priority.svg) ![high](https://www.gstatic.com/codereviewagent/high-priority.svg)\n\nThe use of `execSync` with template literals containing user-provided variables (such as `${repo}`, `${repoOwner}`, `${repoName}`, and `${branchName}`) is vulnerable to command injection. If a user provides a malicious repository URL or branch name containing shell metacharacters (e.g., `; rm -rf /`), they could execute arbitrary shell commands. It is highly recommended to use `spawnSync` with an arguments array to avoid shell interpretation, or at least sanitize and quote the inputs strictly.",
+  "path": "bin/cli.js",
+  "line": 155
+}
+{
+  "body": "![medium](https://www.gstatic.com/codereviewagent/medium-priority.svg)\n\nThe required status check context `\"Sentinel / CI\"` does not match any of the workflow or job names defined in the provided templates (e.g., `PDLC Board Automation` or `Detect Project Board Drift`). This will cause pull requests to be permanently blocked as the required check will never be reported. Based on the provided templates, `\"Detect Project Board Drift\"` seems to be the intended health check job name.\n\n```suggestion\n    required_status_checks: { strict: true, checks: [{ context: \"Detect Project Board Drift\" }] },\n```",
+  "path": "bin/cli.js",
+  "line": 165
+}
+{
+  "body": "![medium](https://www.gstatic.com/codereviewagent/medium-priority.svg)\n\nParsing `updateOutput` directly can throw a `SyntaxError` if the command fails or returns an empty/invalid response. Although it's inside a `try...catch` block, checking if the output is truthy before parsing and using optional chaining provides better resilience and prevents the script from crashing on unexpected API responses.\n\n```suggestion\n        const jsonResponse = updateOutput ? JSON.parse(updateOutput) : null;\n        const returnedOptions = jsonResponse?.data?.updateProjectV2SingleSelectField?.projectV2SingleSelectField?.options || [];\n```",
+  "path": "bin/cli.js",
+  "line": 248
+}
+{
+  "body": "![medium](https://www.gstatic.com/codereviewagent/medium-priority.svg)\n\nTypo in Spanish translation: \"arquivo\" is Portuguese. In Spanish, it should be \"archivo\".\n\n```suggestion\n      console.log(`${cyan}>>> Español: \"Lea el archivo .agentic-setup.md e inicie el Setup Mode\"${reset}`);\n```",
+  "path": "bin/cli.js",
+  "line": 314
+}

package/templates/.github/workflows/add-to-board.yml

@@ -0,0 +1,38 @@
+name: Add to Board on Open
+
+on:
+  issues:
+    types: [opened]
+
+env:
+  PROJECT_ID: "{{PROJECT_ID}}"
+  STATUS_FIELD_ID: "{{STATUS_FIELD_ID}}"
+  STATUS_IDEA: "{{ID_IDEA}}"
+
+jobs:
+  add-to-board:
+    name: Auto-add new issue to board
+    runs-on: ubuntu-latest
+    env:
+      PROJECT_PAT: ${{ secrets.PROJECT_PAT }}
+    steps:
+      - name: Add issue to project board
+        if: ${{ env.PROJECT_PAT != '' && env.PROJECT_ID != '{{PROJECT_ID}}' }}
+        uses: actions/github-script@v7
+        with:
+          github-token: ${{ env.PROJECT_PAT }}
+          script: |
+            const nodeId = context.payload.issue.node_id;
+            const number = context.payload.issue.number;
+            const { addProjectV2ItemById: { item } } = await github.graphql(`
+              mutation($p: ID!, $c: ID!) {
+                addProjectV2ItemById(input: {projectId: $p, contentId: $c}) { item { id } }
+              }`, { p: process.env.PROJECT_ID, c: nodeId });
+            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: item.id, f: process.env.STATUS_FIELD_ID,
+                   v: { singleSelectOptionId: process.env.STATUS_IDEA } });
+            console.log(`Issue #${number} added to board → Idea`);

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

@@ -16,16 +16,20 @@ jobs:
       issues: write
       pull-requests: write
       contents: read
+    env:
+      PROJECT_PAT: ${{ secrets.PROJECT_PAT }}
+      PROJECT_ID: "{{PROJECT_ID}}"
+      STATUS_FIELD_ID: "{{STATUS_FIELD_ID}}"
+      STATUS_DEVELOPMENT: "{{ID_DEVELOPMENT}}"
     steps:
       - name: Update Labels
-        if: ${{ !contains('{{IMPLEMENTATION_AGENT_LABEL}}', '{{') }}
         uses: actions/github-script@v7
         with:
           github-token: ${{ secrets.GITHUB_TOKEN }}
           script: |
             const { owner, repo } = context.repo;
             const issue_number = context.payload.issue.number;
-            
+
             try {
               await github.rest.issues.removeLabel({
                 owner,
@@ -36,14 +40,40 @@ jobs:
             } catch (error) {
               console.log('Label stage:approval not found or could not be removed');
             }
-            
+
+            const agentLabel = '{{IMPLEMENTATION_AGENT_LABEL}}';
+            const labelsToAdd = ['stage:development'];
+            if (!agentLabel.includes('{{')) labelsToAdd.push(agentLabel, 'agent:working');
+
             await github.rest.issues.addLabels({
               owner,
               repo,
               issue_number,
-              labels: ['stage:development', '{{IMPLEMENTATION_AGENT_LABEL}}', 'agent:working']
+              labels: labelsToAdd
             });
 
+      - name: Move board card to Development
+        if: ${{ env.PROJECT_PAT != '' && env.PROJECT_ID != '{{PROJECT_ID}}' }}
+        continue-on-error: true
+        uses: actions/github-script@v7
+        with:
+          github-token: ${{ env.PROJECT_PAT }}
+          script: |
+            const nodeId = context.payload.issue.node_id;
+            const number = context.payload.issue.number;
+            const { addProjectV2ItemById: { item } } = await github.graphql(`
+              mutation($p: ID!, $c: ID!) {
+                addProjectV2ItemById(input: {projectId: $p, contentId: $c}) { item { id } }
+              }`, { p: process.env.PROJECT_ID, c: nodeId });
+            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: item.id, f: process.env.STATUS_FIELD_ID,
+                   v: { singleSelectOptionId: process.env.STATUS_DEVELOPMENT } });
+            console.log(`Issue #${number} → Development`);
+
       - name: Comment on issue to trigger agent and prevent race conditions
         if: ${{ !contains('{{IMPLEMENTATION_AGENT_LABEL}}', '{{') }}
         uses: actions/github-script@v7

package/templates/.github/workflows/pdlc-stage-gate.yml

@@ -0,0 +1,51 @@
+name: PDLC Stage Gate
+on:
+  pull_request:
+    types: [opened, synchronize, reopened, labeled, unlabeled]
+
+permissions:
+  pull-requests: read
+  issues: read
+
+jobs:
+  stage-gate:
+    name: PDLC Stage Gate
+    runs-on: ubuntu-latest
+    steps:
+      - name: Check stage:approval
+        env:
+          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
+        run: |
+          set -e
+          REPO="${{ github.repository }}"
+          PR_NUMBER="${{ github.event.pull_request.number }}"
+
+          PR_LABELS=$(gh pr view "$PR_NUMBER" --repo "$REPO" --json labels --jq '[.labels[].name] | join(" ")')
+          if echo "$PR_LABELS" | grep -qw "hotfix"; then
+            echo "✅ Hotfix label — stage gate bypassed."
+            exit 0
+          fi
+
+          PR_BODY=$(gh pr view "$PR_NUMBER" --repo "$REPO" --json body --jq '.body // ""')
+          ISSUE_NUMS=$(echo "$PR_BODY" | grep -oiE '(Closes?|Fixes?|Resolves?)\s+#([0-9]+)' | grep -oE '[0-9]+' || true)
+
+          if [ -z "$ISSUE_NUMS" ]; then
+            echo "❌ No linked issues in PR body."
+            echo "   Add 'Closes #N' to PR body, or add 'hotfix' label to PR for emergencies."
+            exit 1
+          fi
+
+          for NUM in $ISSUE_NUMS; do
+            LABELS=$(gh issue view "$NUM" --repo "$REPO" --json labels --jq '[.labels[].name] | join(" ")' 2>/dev/null || echo "")
+            if echo "$LABELS" | grep -qw "stage:approval" || echo "$LABELS" | grep -qw "spec:approved" || echo "$LABELS" | grep -qw "stage:development"; then
+              echo "✅ Issue #$NUM approved"
+            else
+              STAGE=$(echo "$LABELS" | tr ' ' '\n' | grep "^stage:" | head -1 || echo "none")
+              echo "❌ Issue #$NUM missing approval (current: $STAGE)"
+              echo "   Required: stage:approval OR spec:approved OR stage:development label on the issue."
+              echo "   Emergency bypass: add 'hotfix' label to this PR."
+              exit 1
+            fi
+          done
+
+          echo "✅ All linked issues approved."