create-agentic-pdlc 2.4.0 → 3.1.0

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

@@ -6,7 +6,7 @@ on:
     - cron: '0 8 * * 1' # Every Monday at 8am
 
 env:
-  PROJECT_ID: "{{PROJECT_ID}}"
+  PROJECT_ID: ${{ vars.PROJECT_ID }}
   STATUS_FIELD_ID: "{{STATUS_FIELD_ID}}"
   STATUS_BRAINSTORMING: "{{ID_BRAINSTORMING}}"
   STATUS_DETAILING: "{{ID_DETAILING}}"
@@ -26,7 +26,7 @@ jobs:
       issues: write
     steps:
       - name: Validate Board Configuration
-        if: ${{ env.PROJECT_TOKEN != '' && env.PROJECT_ID != '{{PROJECT_ID}}' }}
+        if: ${{ env.PROJECT_TOKEN != '' && env.PROJECT_ID != '' }}
         uses: actions/github-script@v8
         with:
           github-token: ${{ env.PROJECT_TOKEN }}

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

@@ -9,7 +9,7 @@ on:
     types: [labeled, edited, closed]
 
 env:
-  PROJECT_ID: "{{PROJECT_ID}}"
+  PROJECT_ID: ${{ vars.PROJECT_ID }}
   STATUS_FIELD_ID: "{{STATUS_FIELD_ID}}"
   STATUS_IDEA: "{{ID_IDEA}}"
   STATUS_BRAINSTORMING: "{{ID_BRAINSTORMING}}"
@@ -30,7 +30,7 @@ jobs:
       PROJECT_TOKEN: ${{ secrets.PROJECT_TOKEN }}
     steps:
       - name: Detect Label and Move Issue
-        if: ${{ env.PROJECT_TOKEN != '' && env.PROJECT_ID != '{{PROJECT_ID}}' }}
+        if: ${{ env.PROJECT_TOKEN != '' && env.PROJECT_ID != '' }}
         uses: actions/github-script@v8
         with:
           github-token: ${{ env.PROJECT_TOKEN }}
@@ -91,7 +91,7 @@ jobs:
       PROJECT_TOKEN: ${{ secrets.PROJECT_TOKEN }}
     steps:
       - name: Check spec markers and swap labels
-        if: ${{ env.PROJECT_TOKEN != '' && env.PROJECT_ID != '{{PROJECT_ID}}' }}
+        if: ${{ env.PROJECT_TOKEN != '' && env.PROJECT_ID != '' }}
         uses: actions/github-script@v8
         with:
           github-token: ${{ env.PROJECT_TOKEN }}
@@ -149,7 +149,7 @@ jobs:
   #   runs-on: ubuntu-latest
   #   steps:
   #     - name: Move issue to Idea
-  #       if: ${{ env.PROJECT_TOKEN != '' && env.PROJECT_ID != '{{PROJECT_ID}}' }}
+  #       if: ${{ env.PROJECT_TOKEN != '' && env.PROJECT_ID != '' }}
   #       uses: actions/github-script@v8
   #       with:
   #         github-token: ${{ env.PROJECT_TOKEN }}
@@ -179,7 +179,7 @@ jobs:
       PROJECT_TOKEN: ${{ secrets.PROJECT_TOKEN }}
     steps:
       - name: Move linked issue to Testing
-        if: ${{ env.PROJECT_TOKEN != '' && env.PROJECT_ID != '{{PROJECT_ID}}' }}
+        if: ${{ env.PROJECT_TOKEN != '' && env.PROJECT_ID != '' }}
         uses: actions/github-script@v8
         with:
           github-token: ${{ env.PROJECT_TOKEN }}
@@ -233,7 +233,7 @@ jobs:
       PROJECT_TOKEN: ${{ secrets.PROJECT_TOKEN }}
     steps:
       - name: Move linked issue to Code Review / PR
-        if: ${{ env.PROJECT_TOKEN != '' && env.PROJECT_ID != '{{PROJECT_ID}}' }}
+        if: ${{ env.PROJECT_TOKEN != '' && env.PROJECT_ID != '' }}
         uses: actions/github-script@v8
         with:
           github-token: ${{ env.PROJECT_TOKEN }}
@@ -281,7 +281,7 @@ jobs:
       PROJECT_TOKEN: ${{ secrets.PROJECT_TOKEN }}
     steps:
       - name: Swap PR labels
-        if: ${{ env.PROJECT_TOKEN != '' && env.PROJECT_ID != '{{PROJECT_ID}}' }}
+        if: ${{ env.PROJECT_TOKEN != '' && env.PROJECT_ID != '' }}
         uses: actions/github-script@v8
         with:
           github-token: ${{ env.PROJECT_TOKEN }}
@@ -300,7 +300,7 @@ jobs:
       PROJECT_TOKEN: ${{ secrets.PROJECT_TOKEN }}
     steps:
       - name: Move issue to Production
-        if: ${{ env.PROJECT_TOKEN != '' && env.PROJECT_ID != '{{PROJECT_ID}}' }}
+        if: ${{ env.PROJECT_TOKEN != '' && env.PROJECT_ID != '' }}
         uses: actions/github-script@v8
         with:
           github-token: ${{ env.PROJECT_TOKEN }}
@@ -359,3 +359,42 @@ jobs:
               await github.rest.issues.removeLabel({ owner, repo, issue_number, name: label }).catch(() => {});
             }
             console.log(`Issue #${issue_number} labels cleaned up`);
+
+  move-card-on-issue-close:
+    name: Closed issue → Archive from board
+    if: github.event_name == 'issues' && github.event.action == 'closed'
+    runs-on: ubuntu-latest
+    env:
+      PROJECT_TOKEN: ${{ secrets.PROJECT_TOKEN }}
+    steps:
+      - name: Archive board card
+        if: ${{ env.PROJECT_TOKEN != '' && env.PROJECT_ID != '' }}
+        uses: actions/github-script@v8
+        with:
+          github-token: ${{ env.PROJECT_TOKEN }}
+          script: |
+            const nodeId = context.payload.issue.node_id;
+            let itemId;
+            try {
+              const added = await github.graphql(`
+                mutation($p: ID!, $c: ID!) {
+                  addProjectV2ItemById(input: {projectId: $p, contentId: $c}) { item { id } }
+                }`, { p: process.env.PROJECT_ID, c: nodeId });
+              itemId = added.addProjectV2ItemById.item.id;
+              if (!itemId) {
+                console.log(`Could not extract itemId from add response`);
+                return;
+              }
+            } catch (e) {
+              console.log(`Could not add issue to project: ${e.message}`);
+              return;
+            }
+            try {
+              await github.graphql(`
+                mutation($p: ID!, $i: ID!) {
+                  archiveProjectV2Item(input: {projectId: $p, itemId: $i}) { item { id } }
+                }`, { p: process.env.PROJECT_ID, i: itemId });
+              console.log(`Issue #${context.payload.issue.number} archived from board`);
+            } catch (e) {
+              console.log(`Could not archive item: ${e.message}`);
+            }

package/templates/full/CLAUDE.md

@@ -0,0 +1,30 @@
+<!-- agentic-full -->
+## Multi-Agent Pipeline
+
+This project uses automated agents beyond the spec gate:
+
+| Agent | Role | Trigger |
+|---|---|---|
+| Implementation Agent (Jules or custom) | Implements spec after `spec:approved` | `agent-trigger.yml` |
+| QA Agent | Verifies PR against ACs via GitHub Models | `project-automation.yml` Variant B |
+| Sentinel | Architecture audit via Gemini Code Assist CI | `architecture-violation` label |
+
+**QA Labels — automation-owned, never apply manually:**
+- `qa:approved` — QA Agent passed; card moves to Code Review
+- `qa:needs-work` — QA Agent found issues; PR flow halts
+- `infra:qa-broken` — QA Agent error; requires manual review
+
+**Board Automation:**
+`project-automation.yml` moves cards between board columns based on labels and PR events.
+Column Option IDs and Project IDs are documented in `docs/pdlc.md`.
+
+Read `docs/pdlc.md` for the full board layout, column IDs, and label reference.
+
+**Pipeline Updates:**
+To add or configure optional agents (Jules, QA Agent, Sentinel):
+```bash
+npx create-agentic-pdlc --update
+```
+
+Run this when asked to "update the pipeline", "configure the agents", or "update the board".
+It detects what is already configured and sets up what is missing — without touching user-owned files.

package/templates/lite/AGENTS.md

@@ -0,0 +1,121 @@
+# {{PROJECT_NAME}} — AI Agent Instructions
+
+This is the contract between the project and any external AI agent
+(Claude Code, Cursor, Copilot, Codex, Sweep, etc.). Read this before committing any change.
+
+## Project Overview
+
+{{PROJECT_DESCRIPTION}}
+
+**Structure:**
+{{PROJECT_STRUCTURE}}
+
+## Before Any Change
+
+```bash
+git fetch origin && git checkout main && git pull
+```
+
+Always start from the current `main` HEAD. Never work over stale snapshots.
+
+## Invariants / Non-negotiable business rules
+
+{{INVARIANTS}}
+<!-- Examples:
+1. **Minimum viable change** — implement exactly what the spec says; no future-proofing.
+2. **Human-in-the-Loop** — No external side-effect actions without explicit human approval.
+3. **Immutable Audit-Log** — INSERT only on audit_log; never UPDATE/DELETE.
+-->
+
+## Mandatory Workflow
+
+0. **Identity**: Always prefix your GitHub comments with `🤖 **Agent:** ` to distinguish yourself.
+1. **Stage Check**: Run `gh issue view <N> --json labels,title` to determine current stage.
+   - `spec:approved` → begin implementation (gate already passed)
+   - `stage:approval` → spec written; wait for PM to add `spec:approved`
+   - Otherwise → follow the stage gate below
+2. Apply `stage:brainstorming` before reading any code: `gh issue edit <N> --add-label "stage:brainstorming"`
+3. Read the issue entirely — understand type and Acceptance Criteria.
+4. Read all files mentioned in the issue's technical context.
+5. Present problem summary + 2–3 solution options. **Stop and wait for PM choice.**
+6. Once PM selects an approach, write the complete spec into the issue body. Advance to `stage:approval`.
+7. Wait for PM to add `spec:approved`. Then implement the **minimum viable change** that satisfies the ACs.
+8. Run tests: `{{TEST_COMMAND}}`
+9. Create a Pull Request with `Closes #N` in the body.
+
+## Spec Format
+
+**Destination: the issue body.** Write spec content using `gh issue edit <N> --body "..."` — not to a file.
+Automation checks the issue body for `## Acceptance Criteria` and `## Files to Modify`.
+
+```
+## 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
+```
+
+## Stage Gate Labels
+
+| Label | Who sets it | Meaning |
+|---|---|---|
+| `stage:brainstorming` | Agent | Brainstorming started — first action before reading code |
+| `stage:detailing` | Agent | Spec is being written |
+| `stage:approval` | Agent | Spec complete, awaiting PM review |
+| `spec:approved` | **PM only** | Gate cleared — implement |
+
+**NEVER apply `spec:approved`, `stage:development`, or `qa:*`.** These are owned by the PM and automation.
+
+## Stage Transition Rules (non-negotiable)
+
+MUST apply `stage:brainstorming` immediately on starting work — before reading any code,
+before invoking any skill.
+
+MUST NOT add `stage:detailing` until the user has explicitly selected an approach
+in the current conversation turn.
+
+MUST NOT add `spec:approved` or any approval-trigger label under any circumstances.
+
+Each stage transition requires a fresh explicit signal from the user in the same session.
+
+## What NOT to Do
+
+- Never commit directly to `main`.
+- Never open a PR without `spec:approved` on the linked issue.
+- Never implement beyond the immediate scope of the issue.
+- Never create future-proofing abstractions for hypothetical features.
+{{EXTRA_DONT}}
+
+## Project Standards
+
+- **Tests:** `{{TEST_COMMAND}}`
+- **Lint/Types:** `{{LINT_COMMAND}}`
+- **Typecheck:** `{{TYPECHECK_COMMAND}}`
+- **Build:** `{{BUILD_COMMAND}}`
+{{EXTRA_PATTERNS}}

package/templates/lite/CLAUDE.md

@@ -0,0 +1,44 @@
+# {{PROJECT_NAME}}
+
+**What it is:** {{PROJECT_DESCRIPTION}}
+
+## Non-Negotiable Invariants
+
+1. **Minimum viable change** — implement exactly what the spec says. No refactoring beyond scope, no future-proofing, no abstractions for hypothetical needs.
+2. **Spec before code** — never edit files, create branches, or commit unless the linked issue has label `spec:approved` (set by PM only) or the branch starts with `hotfix/`.
+
+## Stage Gate
+
+Three labels gate every issue:
+
+| Label | Who sets it | What it unlocks |
+|---|---|---|
+| `stage:brainstorming` | Agent (first action) | Reading code + presenting options |
+| `stage:approval` | Agent (after spec is written) | Signals spec is ready for PM review |
+| `spec:approved` | **PM only** | Clears agent to implement |
+
+**NEVER apply `spec:approved`.** The PM sets it after reviewing the spec in the issue body. Applying it triggers irreversible automation.
+
+## Workflow
+
+1. Apply `stage:brainstorming` immediately — before reading code or invoking any tool.
+2. Read the issue. Present problem summary + 2–3 solution options. **Stop and wait for PM to choose.**
+3. Once PM selects an approach, write the complete spec into the issue body (`gh issue edit <N> --body "..."`). Advance to `stage:approval`.
+4. **Stop.** Wait for PM to add `spec:approved`.
+5. After `spec:approved`: create branch, implement minimum viable change, open PR with `Closes #N`.
+
+## Hook Behavior
+
+A `PreToolUse` hook blocks `gh pr create` unless:
+- The linked issue has `spec:approved`, **or**
+- The branch name starts with `hotfix/`
+
+If blocked: check the issue labels before retrying.
+
+## What NOT to Do
+
+- Never commit to `main` directly.
+- Never open a PR without `spec:approved` on the linked issue.
+- Never implement beyond the immediate scope of the spec.
+- Never add abstractions, error handling, or features for hypothetical future needs.
+- Never apply `spec:approved`, `stage:development`, or `qa:*` — these are PM/automation only.

package/tests/cli.test.js

@@ -0,0 +1,118 @@
+const { describe, it } = require('node:test');
+const assert = require('node:assert/strict');
+const os = require('os');
+const fs = require('fs');
+const path = require('path');
+const crypto = require('crypto');
+
+const { resolveMode } = require('../bin/cli.js');
+
+describe('resolveMode', () => {
+  it('returns lite when no flags', () => {
+    assert.equal(resolveMode([]), 'lite');
+  });
+  it('returns full for --agentic', () => {
+    assert.equal(resolveMode(['--agentic']), 'full');
+  });
+  it('returns update for --update', () => {
+    assert.equal(resolveMode(['--update']), 'update');
+  });
+  it('returns upgrade for --upgrade-to-agentic', () => {
+    assert.equal(resolveMode(['--upgrade-to-agentic']), 'upgrade');
+  });
+  it('--update takes precedence over --agentic', () => {
+    assert.equal(resolveMode(['--update', '--agentic']), 'update');
+  });
+});
+
+describe('buildFullClaudeContent', () => {
+  it('concatenates lite and full with a newline separator', () => {
+    const lite = '# Lite\ncontent';
+    const full = '## Extra\nmore';
+    const result = lite + '\n' + full;
+    assert.ok(result.startsWith('# Lite'));
+    assert.ok(result.includes('## Extra'));
+  });
+});
+
+describe('setActionsVariable', () => {
+  it('calls PATCH first', () => {
+    const calls = [];
+    const execFn = (cmd, args, _opts) => { calls.push([...args]); };
+    const { setActionsVariable } = require('../bin/cli.js');
+    setActionsVariable('owner/repo', 'PROJECT_ID', 'PVT_abc', execFn);
+    assert.equal(calls.length, 1);
+    assert.ok(calls[0].includes('--method'));
+    assert.ok(calls[0].includes('PATCH'));
+    assert.ok(calls[0].some(a => a.includes('PROJECT_ID')));
+    assert.ok(calls[0].some(a => a.includes('PVT_abc')));
+  });
+
+  it('falls back to POST on 404', () => {
+    const calls = [];
+    let callCount = 0;
+    const execFn = (cmd, args, _opts) => {
+      calls.push([...args]);
+      callCount++;
+      if (callCount === 1) {
+        const err = new Error('Not Found');
+        err.stderr = Buffer.from('Not Found');
+        throw err;
+      }
+    };
+    const { setActionsVariable } = require('../bin/cli.js');
+    setActionsVariable('owner/repo', 'PROJECT_ID', 'PVT_abc', execFn);
+    assert.equal(calls.length, 2);
+    assert.ok(calls[0].includes('PATCH'));
+    assert.ok(calls[0].some(a => a.includes('PVT_abc')));
+    assert.ok(calls[1].includes('POST'));
+    assert.ok(calls[1].some(a => a.includes('PVT_abc')));
+  });
+
+  it('throws on 403', () => {
+    const execFn = () => {
+      const err = new Error('Forbidden');
+      err.stderr = Buffer.from('Forbidden');
+      throw err;
+    };
+    const { setActionsVariable } = require('../bin/cli.js');
+    assert.throws(
+      () => setActionsVariable('owner/repo', 'PROJECT_ID', 'PVT_abc', execFn),
+      /Forbidden/
+    );
+  });
+});
+
+describe('scaffoldLiteTemplates', () => {
+  it('copies CLAUDE.md and AGENTS.md but excludes .github/workflows', () => {
+    const { scaffoldLiteTemplates } = require('../bin/cli.js');
+    const src = path.join(__dirname, '..');
+    const tmp = path.join(os.tmpdir(), `pdlc-lite-${crypto.randomBytes(4).toString('hex')}`);
+    try {
+      scaffoldLiteTemplates(src, tmp);
+      const base = path.join(tmp, '.agentic-pdlc', 'templates');
+      assert.ok(fs.existsSync(path.join(base, 'CLAUDE.md')), 'CLAUDE.md should exist');
+      assert.ok(fs.existsSync(path.join(base, 'AGENTS.md')), 'AGENTS.md should exist');
+      assert.ok(!fs.existsSync(path.join(base, '.github', 'workflows')), '.github/workflows must not exist in lite');
+    } finally {
+      fs.rmSync(tmp, { recursive: true, force: true });
+    }
+  });
+});
+
+describe('scaffoldFullTemplates', () => {
+  it('copies .github/workflows with at least one yml file', () => {
+    const { scaffoldFullTemplates } = require('../bin/cli.js');
+    const src = path.join(__dirname, '..');
+    const tmp = path.join(os.tmpdir(), `pdlc-full-${crypto.randomBytes(4).toString('hex')}`);
+    try {
+      scaffoldFullTemplates(src, tmp, null, null, {}, 'owner', 'repo');
+      const wfDir = path.join(tmp, '.agentic-pdlc', 'templates', '.github', 'workflows');
+      assert.ok(fs.existsSync(wfDir), '.github/workflows should exist in full');
+      const ymls = fs.readdirSync(wfDir).filter(f => f.endsWith('.yml'));
+      assert.ok(ymls.length > 0, 'should contain at least one .yml file');
+    } finally {
+      fs.rmSync(tmp, { recursive: true, force: true });
+    }
+  });
+});