create-agentic-pdlc 3.0.0 → 3.1.0

package/docs/superpowers/specs/2026-06-05-project-id-actions-variable-design.md

@@ -0,0 +1,114 @@
+# Design: Set PROJECT_ID as Actions Variable During Install
+
+**Issue:** #179
+**Date:** 2026-06-05
+**Status:** Approved
+
+## Problem
+
+The `create-agentic-pdlc` installer embeds the GitHub Project ID (`PVT_xxx`) directly into workflow YAML files by replacing `{{PROJECT_ID}}` placeholders during `scaffoldFullTemplates`. This means new repo installs get workflows with a hardcoded value in source-controlled files — brittle, hard to rotate, and inconsistent with how GitHub recommends storing non-secret configuration.
+
+The fix: set `vars.PROJECT_ID` as a GitHub Actions Variable via the REST API during install, and have workflow templates source it from `vars` at runtime.
+
+## Approach: env block sourced from `vars`
+
+Keep the `PROJECT_ID:` entry in the workflow-level `env` block — just change its value from a hardcoded placeholder to `${{ vars.PROJECT_ID }}`. All `process.env.PROJECT_ID` references inside `actions/github-script` bodies remain unchanged. Minimal diff, maximum behavioral parity.
+
+Rejected alternatives:
+- **Inline `vars` everywhere**: larger diff, all script bodies change, no benefit.
+- **Set vars + keep YAML hardcode**: adds complexity, defeats the goal.
+
+## Changes
+
+### 1. Templates — 3 workflow files
+
+Files: `templates/.github/workflows/project-automation.yml`, `add-to-board.yml`, `agent-trigger.yml`
+
+Every occurrence of:
+
+| Before | After |
+|---|---|
+| `PROJECT_ID: "{{PROJECT_ID}}"` | `PROJECT_ID: ${{ vars.PROJECT_ID }}` |
+| `env.PROJECT_ID != '{{PROJECT_ID}}'` | `env.PROJECT_ID != ''` |
+
+Guard correctness: when `vars.PROJECT_ID` is unset, `${{ vars.PROJECT_ID }}` resolves to `''` at workflow startup → `env.PROJECT_ID != ''` suppresses execution cleanly. Verified: `vars.*` in workflow-level `env` block resolves before jobs run.
+
+`pdlc.md` keeps `{{PROJECT_ID}}` substitution — it is a documentation file, not a YAML workflow.
+
+### 2. `bin/cli.js` — new helper `setActionsVariable`
+
+```javascript
+function setActionsVariable(repo, name, value) {
+  try {
+    execFileSync('gh', ['api', `repos/${repo}/actions/variables/${name}`,
+      '--method', 'PATCH', '-f', `name=${name}`, '-f', `value=${value}`],
+      { stdio: ['ignore', 'pipe', 'pipe'] });
+  } catch (err) {
+    const msg = err.stderr?.toString() || '';
+    if (msg.includes('404') || msg.includes('Not Found')) {
+      execFileSync('gh', ['api', `repos/${repo}/actions/variables`,
+        '--method', 'POST', '-f', `name=${name}`, '-f', `value=${value}`],
+        { stdio: ['ignore', 'pipe', 'pipe'] });
+    } else {
+      throw err; // 403 bubbles up → caller emits user-visible warning
+    }
+  }
+}
+```
+
+Uses `gh api` via `execFileSync` — consistent with all other API calls in `cli.js`. PATCH on existing variable, POST on 404, throws on 403 so the caller can warn the user.
+
+**Token scope requirement:** fine-grained PAT needs `variables:write`; classic PAT needs `repo` scope. `GITHUB_TOKEN` (workflow-issued) will return 403 — cannot set repo variables. The installer already calls `gh auth token` for `PROJECT_PAT`; the same authenticated session is used here.
+
+### 3. `bin/cli.js` — `scaffoldFullTemplates` (line 345)
+
+Remove the single line that substitutes `{{PROJECT_ID}}` in `project-automation.yml`:
+
+```javascript
+// REMOVE this line:
+if (projectId) wfContent = wfContent.replace(/\{\{PROJECT_ID\}\}/g, () => projectId);
+```
+
+All other substitutions on lines 346–355 (`STATUS_FIELD_ID`, `ID_BRAINSTORMING`, `ID_DETAILING`, etc.) are preserved unchanged.
+
+### 4. Create flow — call site
+
+Inside the existing `if (projectId)` block (after `PROJECT_PAT` secret is set, ~line 541):
+
+```javascript
+try {
+  setActionsVariable(repo, 'PROJECT_ID', projectId);
+  console.log(`${green}✅ vars.PROJECT_ID set as Actions Variable.${reset}`);
+} catch (_) {
+  console.log(`${yellow}⚠️  Could not set vars.PROJECT_ID — token may lack variables:write scope.\n   Set it manually: repo Settings → Secrets and variables → Variables → PROJECT_ID = ${projectId}${reset}`);
+}
+```
+
+Non-fatal. Install continues regardless.
+
+### 5. `--update` flow — same call site
+
+The `--update` command is a **lite → full upgrade** — it exits early if the profile is already `full` (line 865). For lite → full, a new board is created via `createProjectV2` (line 920), producing a fresh `projectId`. Call `setActionsVariable` in the same `if (projectId)` block after board creation. Identical error handling to the create flow.
+
+No "find existing project" query is needed. `projectId` is always available from the mutation result in both flows.
+
+## Acceptance Criteria
+
+- `npx create-agentic-pdlc` → `vars.PROJECT_ID` set as GitHub Actions Variable on the target repo
+- No `PVT_xxx` value appears in any installed YAML file
+- `resolve-ids` job resolves column IDs without any YAML modification
+- `--update` (lite → full) → `vars.PROJECT_ID` set with the newly created board ID
+- If token lacks scope → installer prints actionable warning with manual steps; install does not abort
+
+## Out of Scope
+
+- Migrating existing full installs (board already set up, YAML already hardcoded)
+- Changing how `PROJECT_ID` is resolved during install (GraphQL flow unchanged)
+- `--update` on an already-full install (exits early before any board logic runs)
+
+## Files to Modify
+
+- `templates/.github/workflows/project-automation.yml`
+- `templates/.github/workflows/add-to-board.yml`
+- `templates/.github/workflows/agent-trigger.yml`
+- `bin/cli.js` — `setActionsVariable` helper, `scaffoldFullTemplates` line 345, create flow call site, update flow call site

package/package.json

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

package/scripts/derive-column.js

@@ -0,0 +1,20 @@
+// Single source of truth for label → board column classification.
+// Used by the event dispatcher (project-automation.yml) and the reconciliation cron (board-reconciliation.yml).
+// pr:* beats stage:* — a live PR is higher-confidence signal than a stage label that may not have been cleaned up.
+const LABEL_PRIORITY = [
+  { label: 'pr:in-review',        column: 'code_review_pr' },
+  { label: 'pr:approved',         column: 'code_review_pr' },
+  { label: 'stage:development',   column: 'development' },
+  { label: 'stage:approval',      column: 'approval' },
+  { label: 'stage:detailing',     column: 'detailing' },
+  { label: 'stage:brainstorming', column: 'brainstorming' },
+];
+
+function classifyItem(labelNames) {
+  for (const { label, column } of LABEL_PRIORITY) {
+    if (labelNames.includes(label)) return column;
+  }
+  return null;
+}
+
+module.exports = { classifyItem, LABEL_PRIORITY };

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

@@ -5,7 +5,7 @@ on:
     types: [opened]
 
 env:
-  PROJECT_ID: "{{PROJECT_ID}}"
+  PROJECT_ID: ${{ vars.PROJECT_ID }}
   STATUS_FIELD_ID: "{{STATUS_FIELD_ID}}"
   STATUS_IDEA: "{{ID_IDEA}}"
 
@@ -17,7 +17,7 @@ jobs:
       PROJECT_TOKEN: ${{ secrets.PROJECT_TOKEN }}
     steps:
       - name: Add issue to project board
-        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/agent-trigger.yml

@@ -18,7 +18,7 @@ jobs:
       contents: read
     env:
       PROJECT_TOKEN: ${{ secrets.PROJECT_TOKEN }}
-      PROJECT_ID: "{{PROJECT_ID}}"
+      PROJECT_ID: ${{ vars.PROJECT_ID }}
       STATUS_FIELD_ID: "{{STATUS_FIELD_ID}}"
       STATUS_DEVELOPMENT: "{{ID_DEVELOPMENT}}"
     steps:
@@ -62,7 +62,7 @@ jobs:
             });
 
       - name: Move board card to Development
-        if: ${{ env.PROJECT_TOKEN != '' && env.PROJECT_ID != '{{PROJECT_ID}}' }}
+        if: ${{ env.PROJECT_TOKEN != '' && env.PROJECT_ID != '' }}
         continue-on-error: true
         uses: actions/github-script@v8
         with:

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/tests/cli.test.js

@@ -1,5 +1,9 @@
 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');
 
@@ -30,3 +34,85 @@ describe('buildFullClaudeContent', () => {
     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 });
+    }
+  });
+});