create-agentic-pdlc 2.3.0 → 3.0.0

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

@@ -31,7 +31,7 @@ jobs:
     steps:
       - name: Detect Label and Move Issue
         if: ${{ env.PROJECT_TOKEN != '' && env.PROJECT_ID != '{{PROJECT_ID}}' }}
-        uses: actions/github-script@v7
+        uses: actions/github-script@v8
         with:
           github-token: ${{ env.PROJECT_TOKEN }}
           script: |
@@ -51,9 +51,6 @@ jobs:
             } else if (labelName === 'stage:development') {
               targetStatusId = process.env.STATUS_DEVELOPMENT;
               stageName = 'Development';
-            } else if (labelName === 'stage:testing') {
-              targetStatusId = process.env.STATUS_TESTING;
-              stageName = 'Testing';
             }
 
             if (!targetStatusId) {
@@ -91,7 +88,7 @@ jobs:
   #   steps:
   #     - name: Move issue to Idea
   #       if: ${{ env.PROJECT_TOKEN != '' && env.PROJECT_ID != '{{PROJECT_ID}}' }}
-  #       uses: actions/github-script@v7
+  #       uses: actions/github-script@v8
   #       with:
   #         github-token: ${{ env.PROJECT_TOKEN }}
   #         script: |
@@ -111,17 +108,17 @@ 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@v7
+        uses: actions/github-script@v8
         with:
           github-token: ${{ env.PROJECT_TOKEN }}
           script: |
@@ -131,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]));
 
@@ -148,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', 'stage:approval', 'jules', 'agent:working'];
+            const stageLabelsToRemove = ['stage:development', 'stage:brainstorming', 'stage:detailing', 'stage:testing', 'jules'];
 
             if (linkedIssues.length > 0) {
               for (const n of linkedIssues) {
@@ -161,27 +157,26 @@ 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@v7
+        uses: actions/github-script@v8
         with:
           github-token: ${{ env.PROJECT_TOKEN }}
           script: |
@@ -215,6 +210,9 @@ jobs:
               for (const n of linkedIssues) {
                 const { data: issue } = await github.rest.issues.get({ owner, repo, issue_number: n });
                 await moveItem(issue.node_id);
+                if (issue.labels?.some(l => l.name === 'stage:testing')) {
+                  await github.rest.issues.removeLabel({ owner, repo, issue_number: n, name: 'stage:testing' }).catch(() => {});
+                }
                 console.log(`Issue #${n} → Code Review / PR`);
               }
             } else {
@@ -222,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@v7
-        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(() => {});
 
@@ -251,7 +233,7 @@ jobs:
     steps:
       - name: Move issue to Production
         if: ${{ env.PROJECT_TOKEN != '' && env.PROJECT_ID != '{{PROJECT_ID}}' }}
-        uses: actions/github-script@v7
+        uses: actions/github-script@v8
         with:
           github-token: ${{ env.PROJECT_TOKEN }}
           script: |
@@ -279,6 +261,9 @@ jobs:
               for (const n of linkedIssues) {
                 const { data: issue } = await github.rest.issues.get({ owner, repo, issue_number: n });
                 await moveItem(issue.node_id);
+                if (issue.labels?.some(l => l.name === 'stage:approval')) {
+                  await github.rest.issues.removeLabel({ owner, repo, issue_number: n, name: 'stage:approval' }).catch(() => {});
+                }
                 console.log(`Issue #${n} → Production`);
               }
             } else {
@@ -291,7 +276,7 @@ jobs:
     runs-on: ubuntu-latest
     steps:
       - name: Remove transient labels
-        uses: actions/github-script@v7
+        uses: actions/github-script@v8
         with:
           github-token: ${{ secrets.GITHUB_TOKEN }}
           script: |
@@ -300,7 +285,7 @@ jobs:
             const toRemove = [
               'stage:brainstorming', 'stage:detailing',
               'stage:approval', 'stage:development', 'stage:testing',
-              'agent:working', '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/AGENTS.md

@@ -27,14 +27,55 @@ 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: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.
-5. Implement the **minimum viable change** that satisfies the ACs — do not refactor beyond scope.
-6. Run tests: `echo "No tests/build needed."`
-7. Run typecheck: `echo "No typecheck needed."`
-8. Create a Pull Request with `Closes #N` in the body — automation moves the board.
+1. **Stage Check**: Before applying any label or taking any action, run `gh issue view <N> --json labels,title` to determine the issue's current stage. State: *"Issue #N — [title] — is currently at `<stage>`. Requesting confirmation to advance to `<next>`."* Wait for an explicit stage-advancement signal in this conversation turn. A prioritization signal ("work on X", "tackle X next") does **not** count as confirmation — only an explicit signal counts (e.g. "start brainstorming", "yes advance", "go"). **Exceptions — skip this step and proceed directly**:
+   - `spec:approved` → begin implementation (gate already passed)
+   - `stage:development` or `stage:testing` → issue is owned by automation; do not intervene unless explicitly asked to fix a specific problem
+   - `stage:approval` → spec already written; wait for PM to add `spec:approved` before doing anything
+2. **Initial State**: Apply the `stage:brainstorming` label using the GitHub CLI (`gh issue edit <N> --add-label "stage:brainstorming"`). **Exception — pre-spec'd issue**: if the issue body already contains all required spec sections (`## Problem`, `## Solution`, `## Acceptance Criteria`, `## Edge Cases`, `## Out of Scope`, `## Files to Modify`) — all present and non-empty — apply `stage:approval` directly in a single call instead, skipping `stage:brainstorming` and `stage:detailing`.
+3. Read the issue entirely — understand its type (US/BUG/TASK/SPIKE) and the Acceptance Criteria.
+4. Read `docs/pdlc.md` — understand the PDLC and the Definition of Done in this project.
+5. Read all files mentioned in the issue's technical context.
+6. Implement the **minimum viable change** that satisfies the ACs — do not refactor beyond scope.
+7. Run tests: `echo "No tests/build needed."`
+8. Run typecheck: `echo "No typecheck needed."`
+9. Create a Pull Request with `Closes #N` in the body — automation moves the board.
+
+## Spec Format
+
+When writing or rewriting an issue body during detailing, include ALL sections below. Omitting any section blocks `stage:approval`.
+
+```
+## Problem
+[1-3 sentences. What fails. Who affected. Measured impact.]
+
+## Sprint Goal / Success Metrics
+| Metric | Baseline | Target | When |
+|--------|----------|--------|------|
+
+## Solution
+[Behavioral description of what is built. No implementation details.]
+
+## Acceptance Criteria
+**AC1 — [name]**
+- Given [precondition]
+- When [action]
+- Then [outcome]
+
+## Edge Cases
+- EC1: [condition] → [expected behavior]
+
+## Out of Scope
+- [item] — reason
+
+## Non-Functional Requirements
+- Performance: [metric with number]
+- Security: [constraint]
+- Reliability: [constraint]
+> For pure docs/markdown issues with zero runtime behavior, include the NFRs section and state "N/A".
+
+## Files to Modify
+- `path/to/file` — what changes
+```
 
 ## What NOT to do
 
@@ -50,3 +91,4 @@ Always start from the current `main` HEAD. Never work over stale snapshots.
 - **Lint/Types:** `echo "No tests/build needed."`
 - **Typecheck:** `echo "No typecheck needed."`
 - **Build:** `echo "No tests/build needed."`
+- **Canonical secret name:** `PROJECT_TOKEN` (not `PROJECT_PAT`) — use this in all workflow files, both live and templates

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.
 
@@ -33,6 +33,8 @@ The PreToolUse hook will block `gh pr create` automatically if this rule is viol
 
 **Detailing is fully autonomous.** Write the complete spec, add it to the issue, advance to `stage:approval` — no confirmation needed. Then **stop and wait** for human to add `spec:approved` before any implementation.
 
+**Spec destination: the issue body.** Write spec content to the issue body using `gh issue edit <N> --body "..."` — not to a file. A file is acceptable as optional reference only. Automation checks the issue body for `## Acceptance Criteria` and `## Files to Modify` to advance the stage; content that exists only in a file is invisible to it.
+
 ## Stage Transition Rules (non-negotiable)
 
 MUST apply `stage:brainstorming` label immediately on starting work — before

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/SETUP.md

@@ -63,7 +63,7 @@ npx create-agentic-pdlc
 The CLI will:
 1. Ask you which AI Agent you use (Claude Code, Cursor, etc.).
 2. Copy the system instructions pointing to our interactive Setup Mode.
-3. Automatically download the base templates to `.agentic-pdlc/templates/`.
+3. Automatically install the base templates into your project.
 
 Once the CLI finishes, it will instruct you to open your AI agent and run the **Setup Mode**. Your AI agent will then ask you the required project variables interactively and generate `AGENTS.md`, `docs/pdlc.md`, and the GitHub Actions for you!
 
@@ -169,6 +169,7 @@ The issue appears in your GitHub notifications automatically — zero extra setu
    ```bash
    cp .agentic-pdlc/templates/.github/workflows/agentic-metrics.yml .github/workflows/agentic-metrics.yml
    ```
+   > If the file is missing, re-run `npx create-agentic-pdlc` to update your installed templates.
 
 2. Commit and push. The first pulse runs next Sunday, or trigger it manually:
    ```bash

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):**
 
@@ -106,21 +110,21 @@ If `AGENTS.md` and `docs/pdlc.md` are present, you are in **Execution Mode**.
 
 Reading the issue title and body for type inference is exempt from the initial label 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.
+1. Check if issue already has a `type:*` label (`type:feature`, `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
+   - `type:feature` — 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"`
+5. Confidence < 85% → default to `type:feature`: `gh issue edit <N> --add-label "type:feature"`
 
 **Type drives the PDLC flow:**
 
 | Type | Flow |
 |---|---|
-| `type:us` | brainstorming → Gate 1 → detailing → approval |
+| `type:feature` | 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) |
@@ -157,18 +161,39 @@ When asked to work on a feature, you will:
 - Stop and wait for the human PM's explicit approval (Gate 1).
 
 ### 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:
+Once approved, detail the solution directly into the GitHub Issue body. Always rewrite the full issue body — never append only ACs to existing text. Include ALL sections below. Omitting any section blocks `stage:approval`. Use this format:
 
 ```
-**As** [user],
-**I want** [action],
-**so that** [benefit].
+## Problem
+[1-3 sentences. What fails. Who affected. Measured impact.]
 
----
+## Sprint Goal / Success Metrics
+| Metric | Baseline | Target | When |
+|--------|----------|--------|------|
+
+## Solution
+[Behavioral description of what is built. No implementation details.]
 
 ## Acceptance Criteria
-...
+**AC1 — [name]**
+- Given [precondition]
+- When [action]
+- Then [outcome]
+
+## Edge Cases
+- EC1: [condition] → [expected behavior]
+
+## Out of Scope
+- [item] — reason
+
+## Non-Functional Requirements
+- Performance: [metric with number]
+- Security: [constraint]
+- Reliability: [constraint]
+> For pure docs/markdown issues with zero runtime behavior, include the NFRs section and state "N/A".
+
+## Files to Modify
+- `path/to/file` — what changes
 ```
 
 ### 3. Handoff

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

@@ -26,19 +26,14 @@ fi
 
 LABELS=$(gh issue view "$ISSUE_NUM" --json labels --jq '[.labels[].name] | join(" ")' 2>/dev/null || echo "")
 
-if echo "$LABELS" | grep -qw "spec:approved"; then
-  echo "✅ PDLC: Issue #$ISSUE_NUM spec approved by PM — 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."
+if echo "$LABELS" | grep -qw "spec:approved" || echo "$LABELS" | grep -qw "stage:approval" || echo "$LABELS" | grep -qw "stage:development" || echo "$LABELS" | grep -qw "stage:testing" || echo "$LABELS" | grep -qw "human-approved"; then
+  echo "✅ PDLC: Issue #$ISSUE_NUM 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: spec:approved (set by human PM) or stage:development label on the issue."
+echo "   Required: stage:approval OR spec:approved OR stage:development OR stage:testing OR human-approved label on the issue."
 echo "   Emergency bypass: rename branch to hotfix/<issue-number>-<description>."
 exit 1