create-agentic-pdlc 2.4.0 → 3.0.0

package/.agentic-pdlc/hooks/pdlc-stage-gate.sh

@@ -1,39 +1,66 @@
 #!/bin/bash
-# PDLC Stage Gate — blocks gh pr create without stage:approval on linked issue.
+# PDLC Stage Gate — blocks gh pr create and file edits without spec:approved 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 "")
+FILE_PATH=$(echo "$INPUT" | node -e "const d=JSON.parse(require('fs').readFileSync(0)); console.log(d.file_path || '')" 2>/dev/null || echo "")
 
-if ! echo "$COMMAND" | grep -q "gh pr create"; then
+IS_PR_CREATE=false
+IS_FILE_EDIT=false
+
+if echo "$COMMAND" | grep -q "gh pr create"; then
+  IS_PR_CREATE=true
+elif [ -n "$FILE_PATH" ]; then
+  IS_FILE_EDIT=true
+fi
+
+if [ "$IS_PR_CREATE" != "true" ] && [ "$IS_FILE_EDIT" != "true" ]; 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
+  if [ "$IS_FILE_EDIT" = "true" ]; then
+    exit 0
+  fi
   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 "")
+LABELS=$(gh issue view "$ISSUE_NUM" --json labels --jq '[.labels[].name] | join(" ")' 2>/dev/null)
+if [ $? -ne 0 ] || [ -z "$LABELS" ]; then
+  echo "❌ PDLC Stage Gate: Could not fetch labels for issue #$ISSUE_NUM."
+  echo "   Missing condition: spec:approved"
+  echo "   Next step: verify gh auth and issue number, then have PM add spec:approved."
+  exit 1
+fi
 
-if echo "$LABELS" | grep -qw "stage:approval"; then
-  echo "✅ PDLC: Issue #$ISSUE_NUM approved — gate passed."
+if echo "$LABELS" | grep -qw "spec:approved"; then
   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 label on the issue."
-echo "   Emergency bypass: rename branch to hotfix/<issue-number>-<description>."
+
+if [ "$IS_PR_CREATE" = "true" ]; then
+  echo "❌ PDLC Stage Gate: PR creation blocked — issue #$ISSUE_NUM missing spec:approved."
+  echo "   Current stage: $STAGE"
+  echo "   Missing condition: spec:approved (set by PM after reviewing spec in issue body)"
+  echo "   Next step: complete spec → stage:approval → wait for PM to add spec:approved."
+  echo "   Emergency bypass: rename branch to hotfix/<issue-number>-<description>."
+else
+  echo "❌ PDLC Stage Gate: File edit blocked — issue #$ISSUE_NUM missing spec:approved."
+  echo "   Current stage: $STAGE"
+  echo "   Missing condition: spec:approved (set by PM after reviewing spec in issue body)"
+  echo "   Next step: complete spec → stage:approval → wait for PM to add spec:approved."
+  echo "   Emergency bypass: rename branch to hotfix/<issue-number>-<description>."
+fi
 exit 1

package/.claude/settings.json

@@ -9,6 +9,24 @@
             "command": "bash .agentic-pdlc/hooks/pdlc-stage-gate.sh"
           }
         ]
+      },
+      {
+        "matcher": "Edit",
+        "hooks": [
+          {
+            "type": "command",
+            "command": "bash .agentic-pdlc/hooks/pdlc-stage-gate.sh"
+          }
+        ]
+      },
+      {
+        "matcher": "Write",
+        "hooks": [
+          {
+            "type": "command",
+            "command": "bash .agentic-pdlc/hooks/pdlc-stage-gate.sh"
+          }
+        ]
       }
     ]
   }

package/.coderabbit.yaml

@@ -0,0 +1,35 @@
+language: "en-US"
+reviews:
+  profile: "chill"
+  request_changes_workflow: false
+  high_level_summary: true
+  poem: false
+  auto_review:
+    enabled: true
+    drafts: false
+    base_branches:
+      - main
+  path_instructions:
+    - path: ".github/workflows/**"
+      instructions: >
+        Pay close attention to GitHub Actions syntax correctness, trigger
+        semantics (push/pull_request/workflow_run events and their filters),
+        expression syntax (${{ }}), and shell quoting in run steps.
+        Flag any logic that could cause silent failures or unintended trigger
+        behavior.
+  review_status: true
+  auto_apply_labels: true
+  labeling_instructions:
+    - label: "architecture-violation"
+      instructions: >
+        Apply when the PR introduces runtime behavior that violates documented
+        architectural invariants: code that bypasses the PDLC stage gate at runtime,
+        application code that programmatically sets or removes labels reserved for
+        automation (stage:*, spec:approved, qa:*) outside of their designated
+        automation workflows, business logic added directly to templates instead of
+        the CLI, or behavior that directly contradicts invariants in AGENTS.md or
+        CLAUDE.md. Do NOT apply for configuration changes to tools (e.g., updating
+        .coderabbit.yaml, GitHub Actions workflows, or CI config files) — those are
+        infrastructure, not invariant violations.
+chat:
+  auto_reply: true

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

@@ -80,42 +80,6 @@ jobs:
             await moveItem(node_id, targetStatusId);
             console.log(`Issue #${number} moved to ${stageName}`);
 
-  # human-approved on issue → qa:approved on linked open PRs
-  handle-human-approved:
-    name: human-approved → qa:approved on linked PRs
-    if: github.event_name == 'issues' && github.event.action == 'labeled' && github.event.label.name == 'human-approved'
-    runs-on: ubuntu-latest
-    permissions:
-      issues: write
-      pull-requests: write
-    steps:
-      - name: Add qa:approved to linked open PRs
-        uses: actions/github-script@v8
-        with:
-          github-token: ${{ secrets.GITHUB_TOKEN }}
-          script: |
-            const { owner, repo } = context.repo;
-            const issueNumber = context.payload.issue.number;
-            const pattern = new RegExp(`(?:Closes?|Fixes?|Resolves?)\\s+#${issueNumber}\\b`, 'i');
-
-            const prs = await github.paginate(github.rest.pulls.list, {
-              owner, repo, state: 'open', per_page: 100
-            });
-
-            const linked = prs.filter(pr => pattern.test(pr.body ?? ''));
-
-            if (linked.length === 0) {
-              console.log(`No open PRs linking issue #${issueNumber}. Exiting.`);
-              return;
-            }
-
-            for (const pr of linked) {
-              await github.rest.issues.addLabels({
-                owner, repo, issue_number: pr.number, labels: ['qa:approved']
-              }).catch(() => {});
-              console.log(`PR #${pr.number} → qa:approved`);
-            }
-
   # OPTIONAL: Uncomment to enable architecture-violation → Idea
   # move-violation-to-board:
   #   name: architecture-violation → 💡 Idea
@@ -144,15 +108,15 @@ jobs:
   #             });
   #           console.log(`Issue #${number} moved to Idea`);
 
-  # PR Opened → Move linked issue to Testing (Variant B — QA Agent enabled)
+  # PR Opened → Move linked issue to Code Review / PR
   move-card-on-pr-open:
-    name: Open PR → Testing
+    name: Open PR → Code Review / PR
     if: github.event_name == 'pull_request' && (github.event.action == 'opened' || github.event.action == 'reopened')
     runs-on: ubuntu-latest
     env:
       PROJECT_TOKEN: ${{ secrets.PROJECT_TOKEN }}
     steps:
-      - name: Move linked issue to Testing
+      - name: Move linked issue to Code Review / PR
         if: ${{ env.PROJECT_TOKEN != '' && env.PROJECT_ID != '{{PROJECT_ID}}' }}
         uses: actions/github-script@v8
         with:
@@ -164,7 +128,6 @@ jobs:
             const { data: pr } = await github.rest.pulls.get({ owner, repo, pull_number: prNumber });
             const body = pr.body ?? '';
 
-            // Extract issues linked via "Closes #N", "Fixes #N", "Resolves #N"
             const linkedIssues = [...body.matchAll(/(?:Closes?|Fixes?|Resolves?)\s+#(\d+)/gi)]
               .map(m => parseInt(m[1]));
 
@@ -181,11 +144,11 @@ jobs:
                   }
                 }`, {
                   p: process.env.PROJECT_ID, i: item.id, f: process.env.STATUS_FIELD_ID,
-                  v: { singleSelectOptionId: process.env.STATUS_TESTING }
+                  v: { singleSelectOptionId: process.env.STATUS_CODE_REVIEW_PR }
                 });
             };
 
-            const stageLabelsToRemove = ['stage:development', 'stage:brainstorming', 'stage:detailing', 'jules'];
+            const stageLabelsToRemove = ['stage:development', 'stage:brainstorming', 'stage:detailing', 'stage:testing', 'jules'];
 
             if (linkedIssues.length > 0) {
               for (const n of linkedIssues) {
@@ -194,25 +157,24 @@ jobs:
                 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)`);
+                console.log(`Issue #${n} → Code Review / PR`);
               }
             } else {
               await moveItem(pr.node_id);
-              console.log(`PR #${prNumber} → Testing (no linked issue)`);
+              console.log(`PR #${prNumber} → Code Review / PR (no linked issue)`);
             }
 
             await github.rest.issues.addLabels({ owner, repo, issue_number: prNumber, labels: ['pr:in-review'] }).catch(() => {});
 
-  # QA Approved → Move linked issue to Code Review / PR
-  move-card-on-qa-pass:
-    name: qa:approved → Code Review / PR
-    if: github.event_name == 'pull_request' && github.event.action == 'labeled' && github.event.label.name == 'qa:approved'
+  # Review Approved → Move linked issue to Code Review / PR + swap PR labels
+  move-card-on-review-approved:
+    name: Approved PR → Code Review / PR
+    if: github.event_name == 'pull_request_review' && github.event.review.state == 'approved'
     runs-on: ubuntu-latest
     env:
       PROJECT_TOKEN: ${{ secrets.PROJECT_TOKEN }}
     steps:
-      - name: Move linked issue to Code Review / PR
+      - name: Move linked issue to Code Review and swap PR labels
         if: ${{ env.PROJECT_TOKEN != '' && env.PROJECT_ID != '{{PROJECT_ID}}' }}
         uses: actions/github-script@v8
         with:
@@ -258,22 +220,6 @@ jobs:
               console.log(`PR #${prNumber} → Code Review / PR (no linked issue)`);
             }
 
-  # Review Approved → Add Label
-  move-card-on-review-approved:
-    name: Approved PR → Add Label
-    if: github.event_name == 'pull_request_review' && github.event.review.state == 'approved'
-    runs-on: ubuntu-latest
-    env:
-      PROJECT_TOKEN: ${{ secrets.PROJECT_TOKEN }}
-    steps:
-      - name: Swap PR labels
-        if: ${{ env.PROJECT_TOKEN != '' && env.PROJECT_ID != '{{PROJECT_ID}}' }}
-        uses: actions/github-script@v8
-        with:
-          github-token: ${{ env.PROJECT_TOKEN }}
-          script: |
-            const prNumber = context.payload.pull_request.number;
-            const { owner, repo } = context.repo;
             try { await github.rest.issues.removeLabel({ owner, repo, issue_number: prNumber, name: 'pr:in-review' }); } catch {}
             await github.rest.issues.addLabels({ owner, repo, issue_number: prNumber, labels: ['pr:approved'] }).catch(() => {});
 
@@ -339,7 +285,7 @@ jobs:
             const toRemove = [
               'stage:brainstorming', 'stage:detailing',
               'stage:approval', 'stage:development', 'stage:testing',
-              'qa:needs-work', 'pr:in-review', 'jules'
+              'pr:in-review', 'jules'
             ];
             for (const label of toRemove) {
               await github.rest.issues.removeLabel({ owner, repo, issue_number, name: label }).catch(() => {});

package/CLAUDE.md

@@ -1,6 +1,6 @@
 # agentic-pdlc
 
-**What it is:** npm CLI (`npx create-agentic-pdlc`) that installs a PDLC workflow for AI agent projects. Stack: Markdown + GitHub Actions YAML only — never complex Node/Python/Bash scripts.
+**What it is:** npm CLI (`npx create-agentic-pdlc`) that installs a PDLC workflow for AI agent projects.
 
 **Workflow:** `stage:brainstorming` → `stage:detailing` → `spec:approved` → `stage:development` → PR → merge. Labels move the board automatically.
 

package/README.md

@@ -1,57 +1,54 @@
-# 🤖 Agentic PDLC Framework
+# 🤖 Agentic PDLC
 
-> Do your AI agents build features that don't match the spec?
-> Do you find bugs and architecture violations only at the end of the lifecycle?
-> Are you the one manually moving cards across your board — every single time?
+> Does your AI agent add code you didn't ask for?
+> Does it skip the spec and jump straight to a PR?
+> Does it ignore the rules in your CLAUDE.md?
 
-**Agentic PDLC** gives your agents a shared rulebook, a self-moving board, and a CI that won't let broken code reach production. One `npx` command to set up.
+**Agentic PDLC** gives your agent a brake it can't ignore — a hook that makes it write the spec first, keep changes small, and stop at each gate. One `npx` to install.
 
 <div align="center">
-  <img src=".github/assets/agentic-pdlc-flow.svg" alt="Agentic PDLC Architecture Flow" width="100%">
+  <img src=".github/assets/agentic-pdlc-flow.svg" alt="Agentic PDLC: Upstream idea-to-spec, gated by spec:approved, into Downstream spec-to-production" width="100%">
 </div>
 
-Solo devs and small teams hit the same wall: one agent writes the spec, another implements it differently, a third reviews without knowing either. Agentic PDLC gives all of them a shared brief, automates the board, and puts a CI guard between your agents and production.
+---
+
+## Two modes — pick yours
+
+**`lite` (default) — the brake**
+Your agent writes the spec, waits for your approval, then implements it. It won't add code you didn't ask for. It won't open a PR before the spec is approved. It won't skip your `CLAUDE.md` rules — because the gate is a hook, not text the agent can ignore. Value on your first PR.
+
+**`--agentic` — see your whole pipeline**
+Everything in `lite`, plus a self-moving kanban board that shows your full product lifecycle, from **Idea → Production**. It makes transparent what needs your attention/approval, what's been done by the agent, and what's ready to merge. It supports as many agents as you need.
 
 ---
 
 ## ⚡ Why it works
 
-- 🗺️ **A transparent lifecycle** — Every feature travels a Kanban board from Idea to Production. You always know where things are.
-- 🤖 **A board that moves itself** — When you approve a spec, the card moves. When an agent opens a PR, the card moves. You just approve or reject.
-- 🧠 **Agents that agree with each other** — One briefing (`AGENTS.md`), read by every agent. Claude, Jules, Gemini — all pulling in the same direction, without you copy-pasting context between tabs.
-- 🛡️ **Code that can't silently break production** — A CI auditor checks every PR for architecture violations before anything reaches your main branch. *(Maturity Model — coming soon)*
+- 🛑 **A brake the agent can't ignore** — the gate is a hook, not text in CLAUDE.md. Text gets ignored; a hook does not.
+- 📋 **Spec before code** — the agent can't open a PR until the spec is approved, with acceptance criteria, edge cases, and files to change.
+- 🗺️ **See your whole pipeline** *(`--agentic` only)* — a board tracks every task from idea to production, and the gate between spec and code stays yours. You approve before anything ships.
 
 ---
 
 ## 🚀 Quick Start
 
-Run this in the root of your project:
-
 ```bash
 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.
+Installs `lite` by default — your AGENTS.md, CLAUDE.md, and the gate hook. Your AI assistant finishes the setup with you; no YAML to edit.
 
-**Already set up? Add or reconfigure optional agents at any time:**
+**Want the full board and pipeline view?**
 
 ```bash
-npx create-agentic-pdlc --update
+npx create-agentic-pdlc --agentic
 ```
 
-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
-
-The framework splits work into two phases:
-
-### 1. You + AI: Idea → Spec
-Use conversational AI (e.g., **Claude Code**, **Gemini CLI**) as your brainstorming partner. Together, you flesh out user stories, acceptance criteria, and technical specifications until they are solid.
+**Already set up? Add or change things any time:**
 
-### 2. Your agents: Spec → Production
-Once you approve the spec, autonomous implementation agents (e.g., **Jules**, **Sweep**, **Copilot Workspace**) pick up the task. The board moves automatically; the CI auditor guards the main branch.
+```bash
+npx create-agentic-pdlc --update
+```
 
 ---
 
@@ -71,11 +68,15 @@ One shared brief (`AGENTS.md`). Every agent reads it.
 
 ## 📦 What you get
 
-After setup, your project has:
+**`lite` (default)**
+- **`AGENTS.md`** — the shared brief every agent reads; your rules, once
+- **`CLAUDE.md`** — keep-changes-small rule + the stage gates
+- **`.agentic-pdlc/hooks/pdlc-stage-gate.sh`** — the hook; the agent can't open a PR until the spec is approved
 
-- **`AGENTS.md`** — The shared brief every agent reads. Your rules, once.
-- **`docs/pdlc.md`** — Your pipeline map: board columns, IDs, and who does what.
-- **`.github/workflows/`** — Three automations: board moves itself, agent wakes on spec approval, CI audits every PR.
+**`--agentic` (opt-in)**
+Everything in lite, plus:
+- **`docs/pdlc.md`** — your pipeline map: board columns and who does what
+- **`.github/workflows/`** — board automation: moves cards on spec approval, PR open, and CI pass
 
 ---
 

package/adapters/claude-code/skill.md

@@ -22,12 +22,14 @@ Specifically, check for:
 
 If any of these files are missing, you are in **Setup Mode**. Do not proceed with feature requests until setup is complete.
 
+**Lite profile note:** If `cli-context.json` contains `"profile": "lite"`, the only mandatory artifacts are `AGENTS.md` and `CLAUDE.md` — `docs/pdlc.md` and the workflow files are not installed in the lite profile. Skip checks for those files.
+
 1. **Language Detection:** Analyze the user's previous prompts and preferred language. Conduct this entire Setup Mode and ask all your interactive questions in that same language.
 2. Acknowledge that the framework is not yet set up.
 3. **Pre-filled Context:** Before asking any questions, read the following files if they exist:
-   - `.agentic-pdlc/cli-context.json` — written by the CLI. Contains `projectName`, `repoOwner`, `repoName`, `projectNumber`, `isOrg`, `boardUrl`, and `patAutoSet` (boolean). Use these values directly and skip the corresponding questions. Honor `patAutoSet` in Step 7 and `boardUrl` in Step 10.
-   - `.agentic-pdlc/templates/docs/pdlc.md` — the CLI pre-fills PROJECT_ID, STATUS_FIELD_ID, REPO_OWNER, REPO_NAME, and all 9 column option IDs. If none of the values still contain `{{...}}` placeholders, skip the entire Board IDs question group.
-   - `.agentic-pdlc/templates/.github/workflows/project-automation.yml` — the CLI also pre-fills all ID placeholders here. When writing the workflow file, the remaining `{{...}}` placeholders are only non-ID ones (project name, commands, etc.).
+   - `.agentic-pdlc/cli-context.json` — written by the CLI. Contains `projectName`, `repoOwner`, `repoName`, `projectNumber`, `isOrg`, `boardUrl`, `patAutoSet` (boolean), and `profile` (`"lite"` or `"full"`). Use these values directly and skip the corresponding questions. Honor `patAutoSet` in Step 7 and `boardUrl` in Step 10.
+   - `.agentic-pdlc/templates/docs/pdlc.md` — **only present in the `full` profile.** If absent (lite install), skip the Board IDs question group entirely and skip all steps that reference this file. If present, the CLI pre-fills PROJECT_ID, STATUS_FIELD_ID, REPO_OWNER, REPO_NAME, and all 9 column option IDs; if none still contain `{{...}}` placeholders, skip the Board IDs question group.
+   - `.agentic-pdlc/templates/.github/workflows/project-automation.yml` — **only present in the `full` profile.** If absent, skip. If present, the CLI also pre-fills all ID placeholders here; remaining `{{...}}` placeholders are non-ID ones (project name, commands, etc.).
 4. Interactively ask the user only for the **missing values**, **one group at a time**:
    - **Project basics:** Project Name (skip if present in `cli-context.json`), Description, Technical Stack/Structure. **Do not ask for GitHub Username** — use `repoOwner` from `cli-context.json` directly for CODEOWNERS.
    - **Commands:** In the user's detected language, ask for each command with its purpose and concrete examples:
@@ -53,6 +55,8 @@ If any of these files are missing, you are in **Setup Mode**. Do not proceed wit
      - Jules (`@google-labs-jules`): use `jules` — this is the native label the Jules GitHub App watches. **Do NOT use `agent:jules`** — Jules does not watch that label and the trigger will silently fail.
      - Other agents: use the handle without `@`, lowercase (e.g. `@my-agent` → `my-agent`).
 5. Generate and write the missing files replacing the `{{SCREAMING_SNAKE_CASE}}` placeholders using the templates in `.agentic-pdlc/templates/`.
+   - **CLAUDE.md:** If `.agentic-pdlc/templates/CLAUDE.md` exists and `CLAUDE.md` does not yet exist at the project root, write it — replacing only `{{PROJECT_NAME}}` with the project name. Skip if CLAUDE.md already exists (never downgrade).
+   - **Lite profile:** If `cli-context.json` has `"profile": "lite"`, skip steps that reference `docs/pdlc.md`, `project-automation.yml`, `agent-trigger.yml`, and `pdlc-health-check.yml` — these are not installed in lite.
 6. Offer to run the `gh` commands for labels (`spec:approved`, `pr:in-review`, `pr:approved`, `architecture-violation`).
 7. **`PROJECT_PAT` secret (required for board automation):**