create-agentic-pdlc 2.4.0 → 3.1.0

package/docs/superpowers/plans/2026-06-05-archive-card-on-issue-close.md

@@ -0,0 +1,105 @@
+# Archive Board Card on Issue Close Implementation Plan
+
+> **For agentic workers:** REQUIRED SUB-SKILL: Use superpowers:subagent-driven-development (recommended) or superpowers:executing-plans to implement this plan task-by-task. Steps use checkbox (`- [ ]`) syntax for tracking.
+
+**Goal:** Archive the GitHub Project board card when an issue is closed, preventing stale cards from accumulating in active columns.
+
+**Architecture:** Single new job appended to `project-automation.yml` template. Triggers on the already-present `issues: closed` event. Uses `addProjectV2ItemById` (idempotent) then `archiveProjectV2Item` — handles both issues closed without a PR and issues closed via PR merge safely.
+
+**Tech Stack:** GitHub Actions, `actions/github-script@v8`, GitHub GraphQL API (`addProjectV2ItemById`, `archiveProjectV2Item`).
+
+---
+
+## File Map
+
+| Action | Path | Responsibility |
+|---|---|---|
+| Modify | `templates/.github/workflows/project-automation.yml` | Add `move-card-on-issue-close` job at end of file |
+
+No unit tests — YAML workflow template; correctness verified by grep and manual inspection.
+
+---
+
+### Task 1: Add `move-card-on-issue-close` job
+
+**Files:**
+- Modify: `templates/.github/workflows/project-automation.yml` (append after `cleanup-labels-on-close`)
+
+- [ ] **Step 1: Verify the insertion point**
+
+Run:
+```bash
+tail -5 templates/.github/workflows/project-automation.yml
+```
+
+Expected: last line is `console.log(\`Issue #\${issue_number} labels cleaned up\`);` followed by closing braces. The file ends after `cleanup-labels-on-close`.
+
+- [ ] **Step 2: Append the new job**
+
+At the end of `templates/.github/workflows/project-automation.yml`, add:
+
+```yaml
+
+  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;
+            } catch (e) {
+              console.log(`Could not add issue to project: ${e.message}`);
+              return;
+            }
+            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`);
+```
+
+- [ ] **Step 3: Verify job was added and file is syntactically correct**
+
+Run:
+```bash
+grep -n "move-card-on-issue-close\|archiveProjectV2Item" templates/.github/workflows/project-automation.yml
+```
+
+Expected: two matches — the job name line and the mutation name.
+
+Run:
+```bash
+python3 -c "import yaml, sys; yaml.safe_load(open('templates/.github/workflows/project-automation.yml'))" 2>&1
+```
+
+Expected: no output (valid YAML).
+
+- [ ] **Step 4: Verify guard condition matches existing pattern**
+
+Run:
+```bash
+grep "PROJECT_TOKEN != ''" templates/.github/workflows/project-automation.yml
+```
+
+Expected: multiple lines including the new job — confirms guard is consistent with other jobs.
+
+- [ ] **Step 5: Commit**
+
+```bash
+git add templates/.github/workflows/project-automation.yml
+git commit -m "feat(templates): archive board card when issue is closed"
+```

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

@@ -0,0 +1,336 @@
+# PROJECT_ID as Actions Variable Implementation Plan
+
+> **For agentic workers:** REQUIRED SUB-SKILL: Use superpowers:subagent-driven-development (recommended) or superpowers:executing-plans to implement this plan task-by-task. Steps use checkbox (`- [ ]`) syntax for tracking.
+
+**Goal:** Replace hardcoded `PROJECT_ID: "PVT_xxx"` in installed YAML files with `${{ vars.PROJECT_ID }}`, and have the installer set the value via the GitHub Actions Variables REST API.
+
+**Architecture:** Three workflow templates swap their `PROJECT_ID` env value and guard condition. `bin/cli.js` gains a `setActionsVariable(repo, name, value, execFn)` helper (dependency-injected `execFn` for testability) called after board creation in both the `runFullSetup` and `runUpgradeToAgentic` flows.
+
+**Tech Stack:** Node.js 22, `node:test` + `node:assert/strict`, `gh` CLI (`execFileSync`), GitHub Actions Variables REST API (`PATCH`/`POST /repos/{owner}/{repo}/actions/variables`).
+
+---
+
+## File Map
+
+| Action | Path | Responsibility |
+|---|---|---|
+| Modify | `templates/.github/workflows/project-automation.yml` | Remove `{{PROJECT_ID}}` placeholder, source from `vars` |
+| Modify | `templates/.github/workflows/add-to-board.yml` | Same |
+| Modify | `templates/.github/workflows/agent-trigger.yml` | Same |
+| Modify | `bin/cli.js` | Add helper, wire call sites, export helper |
+| Modify | `tests/cli.test.js` | Tests for `setActionsVariable` logic |
+
+---
+
+### Task 1: Update workflow templates
+
+**Files:**
+- Modify: `templates/.github/workflows/project-automation.yml`
+- Modify: `templates/.github/workflows/add-to-board.yml`
+- Modify: `templates/.github/workflows/agent-trigger.yml`
+
+No tests for template content — correctness is verified by the installer integration.
+
+- [ ] **Step 1: Replace `PROJECT_ID` env value in all three templates**
+
+In each of the three files, find every line matching:
+```yaml
+PROJECT_ID: "{{PROJECT_ID}}"
+```
+Replace with:
+```yaml
+PROJECT_ID: ${{ vars.PROJECT_ID }}
+```
+
+`project-automation.yml` line 12, `add-to-board.yml` line 8, `agent-trigger.yml` line 21.
+
+- [ ] **Step 2: Replace guard conditions in all three templates**
+
+In each of the three files, find every line matching:
+```yaml
+env.PROJECT_ID != '{{PROJECT_ID}}'
+```
+Replace with:
+```yaml
+env.PROJECT_ID != ''
+```
+
+Do a full-file search in each — there are multiple occurrences per file (every job that conditionally runs).
+
+- [ ] **Step 3: Verify no `{{PROJECT_ID}}` remains in workflow files**
+
+Run:
+```bash
+grep -rn "{{PROJECT_ID}}" templates/.github/workflows/
+```
+
+Expected: no output. If any lines appear, fix them before proceeding.
+
+- [ ] **Step 4: Commit**
+
+```bash
+git add templates/.github/workflows/project-automation.yml \
+        templates/.github/workflows/add-to-board.yml \
+        templates/.github/workflows/agent-trigger.yml
+git commit -m "feat(templates): source PROJECT_ID from vars instead of hardcoded placeholder"
+```
+
+---
+
+### Task 2: Remove `{{PROJECT_ID}}` YAML substitution from `scaffoldFullTemplates`
+
+**Files:**
+- Modify: `bin/cli.js:345`
+
+- [ ] **Step 1: Delete the single PROJECT_ID substitution line**
+
+In `bin/cli.js`, find and remove exactly this line (currently line 345):
+```javascript
+    if (projectId)     wfContent = wfContent.replace(/\{\{PROJECT_ID\}\}/g,      () => projectId);
+```
+
+The block around it (lines 342–356) substitutes `STATUS_FIELD_ID` and all `ID_*` column options into `project-automation.yml`. Keep all those lines. Only the `PROJECT_ID` line is removed.
+
+- [ ] **Step 2: Verify other substitutions are intact**
+
+Run:
+```bash
+grep -n "wfContent.replace" bin/cli.js
+```
+
+Expected output must include lines for `STATUS_FIELD_ID`, `ID_IDEA`, `ID_BRAINSTORMING`, `ID_DETAILING`, `ID_APPROVAL`, `ID_DEVELOPMENT`, `ID_TESTING`, `ID_CODE_REVIEW_PR`, `ID_PRODUCTION`. Must NOT include `PROJECT_ID`.
+
+- [ ] **Step 3: Commit**
+
+```bash
+git add bin/cli.js
+git commit -m "fix(cli): remove PROJECT_ID hardcoding from scaffoldFullTemplates"
+```
+
+---
+
+### Task 3: Add `setActionsVariable` helper (TDD)
+
+**Files:**
+- Modify: `bin/cli.js` (add function before `scaffoldFullTemplates`, ~line 283)
+- Modify: `tests/cli.test.js` (add describe block)
+- Modify: `bin/cli.js:793` (add to `module.exports`)
+
+- [ ] **Step 1: Write failing tests**
+
+Add to `tests/cli.test.js`:
+
+```javascript
+const { describe, it, mock } = require('node:test');
+
+// ... existing imports and tests above ...
+
+describe('setActionsVariable', () => {
+  it('calls PATCH first', () => {
+    const calls = [];
+    const execFn = (cmd, args) => { 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')));
+  });
+
+  it('falls back to POST on 404', () => {
+    const calls = [];
+    let callCount = 0;
+    const execFn = (cmd, args) => {
+      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[1].includes('POST'));
+  });
+
+  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/
+    );
+  });
+});
+```
+
+- [ ] **Step 2: Run tests to verify they fail**
+
+```bash
+npm test
+```
+
+Expected: 3 new test failures — `setActionsVariable` is not exported yet.
+
+- [ ] **Step 3: Add `setActionsVariable` to `bin/cli.js`**
+
+Insert this function before `scaffoldFullTemplates` (~line 283):
+
+```javascript
+function setActionsVariable(repo, name, value, execFn = execFileSync) {
+  try {
+    execFn('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() || '') + (err.message || '');
+    if (msg.includes('404') || msg.includes('Not Found')) {
+      execFn('gh', [
+        'api', `repos/${repo}/actions/variables`,
+        '--method', 'POST',
+        '-f', `name=${name}`,
+        '-f', `value=${value}`
+      ], { stdio: ['ignore', 'pipe', 'pipe'] });
+    } else {
+      throw err;
+    }
+  }
+}
+```
+
+- [ ] **Step 4: Export the function**
+
+In `bin/cli.js` at line 793, update:
+```javascript
+if (typeof module !== 'undefined') module.exports = { resolveMode };
+```
+to:
+```javascript
+if (typeof module !== 'undefined') module.exports = { resolveMode, setActionsVariable };
+```
+
+- [ ] **Step 5: Run tests to verify they pass**
+
+```bash
+npm test
+```
+
+Expected: all tests pass including the 3 new `setActionsVariable` tests.
+
+- [ ] **Step 6: Commit**
+
+```bash
+git add bin/cli.js tests/cli.test.js
+git commit -m "feat(cli): add setActionsVariable helper with PATCH→POST fallback"
+```
+
+---
+
+### Task 4: Wire `setActionsVariable` into the create flow (`runFullSetup`)
+
+**Files:**
+- Modify: `bin/cli.js` (~line 554)
+
+- [ ] **Step 1: Add the call site after the PROJECT_PAT block**
+
+In `bin/cli.js`, locate the end of the `PROJECT_PAT` block in `runFullSetup` (the `} else if (projectId && isOrg)` line at ~554). Add after it:
+
+```javascript
+  // Set PROJECT_ID as GitHub Actions Variable
+  if (projectId) {
+    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 manually: repo Settings → Secrets and variables → Variables → PROJECT_ID = ${projectId}${reset}`);
+    }
+  }
+```
+
+Insert this block between line 554 (`} else if (projectId && isOrg) { ... }`) and line 556 (`await setBranchProtection(...)`).
+
+- [ ] **Step 2: Verify placement**
+
+```bash
+grep -n "vars.PROJECT_ID\|setBranchProtection\|isOrg\)" bin/cli.js | head -20
+```
+
+The `vars.PROJECT_ID` console log should appear between the `isOrg` block and `setBranchProtection`.
+
+- [ ] **Step 3: Commit**
+
+```bash
+git add bin/cli.js
+git commit -m "feat(cli): set vars.PROJECT_ID as Actions Variable in create flow"
+```
+
+---
+
+### Task 5: Wire `setActionsVariable` into the upgrade flow (`runUpgradeToAgentic`)
+
+**Files:**
+- Modify: `bin/cli.js` (~line 1006)
+
+- [ ] **Step 1: Add the call site after the PROJECT_PAT block in the upgrade flow**
+
+In `bin/cli.js`, locate the end of the `PROJECT_PAT` block in `runUpgradeToAgentic` (the closing `}` of `if (projectId && !isOrg)` at ~line 1006). Add after it:
+
+```javascript
+  // Set PROJECT_ID as GitHub Actions Variable
+  if (projectId) {
+    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 manually: repo Settings → Secrets and variables → Variables → PROJECT_ID = ${projectId}${reset}`);
+    }
+  }
+```
+
+Insert between line ~1006 (`}` closing the `PROJECT_PAT` block) and line ~1008 (`console.log scaffolding`).
+
+- [ ] **Step 2: Verify no `{{PROJECT_ID}}` placeholder survives install**
+
+```bash
+grep -rn "{{PROJECT_ID}}" templates/
+```
+
+Expected: only `templates/full/docs/pdlc.md` (the documentation file). No workflow YAML files.
+
+- [ ] **Step 3: Run full test suite**
+
+```bash
+npm test
+```
+
+Expected: all tests pass.
+
+- [ ] **Step 4: Commit**
+
+```bash
+git add bin/cli.js
+git commit -m "feat(cli): set vars.PROJECT_ID as Actions Variable in upgrade flow"
+```
+
+---
+
+## Self-Review Checklist
+
+- Acceptance Criteria 1 (new install sets `vars.PROJECT_ID`): Task 4 ✓
+- Acceptance Criteria 2 (`resolve-ids` works without YAML modification): Task 1 ✓
+- Acceptance Criteria 3 (`--update` sets variable): Task 5 ✓
+- Acceptance Criteria 4 (403 warning, non-fatal): Tasks 3, 4, 5 ✓
+- Edge case — PATCH first, POST on 404: Task 3 ✓
+- Edge case — `vars.PROJECT_ID` unset resolves to `''`, guard works: Task 1 ✓
+- No `{{PROJECT_ID}}` in any YAML after install: Tasks 1 + 2 ✓
+- All other ID substitutions preserved: Task 2 Step 2 ✓

package/docs/superpowers/specs/2026-06-04-spec-format-issue-template-design.md

@@ -0,0 +1,46 @@
+# Design: ship spec-format issue template (lite)
+
+**Issue:** #157
+**Date:** 2026-06-04
+**Status:** approved
+
+## Problem
+
+`npx create-agentic-pdlc` copies templates to `.agentic-pdlc/templates/` — a path GitHub ignores entirely. Users who open "New Issue" after setup see a blank text box instead of the spec format template.
+
+## Decision
+
+Copy `templates/.github/ISSUE_TEMPLATE/` directly to `targetDir/.github/ISSUE_TEMPLATE/` during `runSetup()` in `bin/cli.js`. No agent involvement — templates have no `{{PLACEHOLDER}}` substitution, so the CLI can write them directly.
+
+## Change
+
+**File:** `bin/cli.js`
+
+After the existing `copyDirSync(sourceTemplates, targetTemplates)` block (around line 386):
+
+```js
+// i18n string (add to i18n object)
+issue_templates_copied: t(
+  '✅ Issue templates copied to .github/ISSUE_TEMPLATE/',
+  '✅ Issue templates copiados para .github/ISSUE_TEMPLATE/',
+  '✅ Issue templates copiados a .github/ISSUE_TEMPLATE/'
+),
+
+// Copy block (add inside runSetup(), after template copy)
+const sourceIssueTemplates = path.join(sourceDir, 'templates', '.github', 'ISSUE_TEMPLATE');
+const targetIssueTemplates = path.join(targetDir, '.github', 'ISSUE_TEMPLATE');
+if (fs.existsSync(sourceIssueTemplates)) {
+  copyDirSync(sourceIssueTemplates, targetIssueTemplates);
+  console.log(i18n.issue_templates_copied);
+}
+```
+
+## Edge Cases
+
+- `.github/ISSUE_TEMPLATE/` already exists → `copyDirSync` overwrites. Correct — boilerplate, not user customizations.
+- Source dir missing (corrupt install) → guarded by `if (fs.existsSync(...))`, skips silently.
+
+## Out of Scope
+
+- Changes to template content — existing `feature.md`, `bug.md`, `task.md` already have all required sections.
+- Changes to `adapters/claude-code/skill.md` — agent setup not involved.

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,13 +1,13 @@
 {
   "name": "create-agentic-pdlc",
-  "version": "2.4.0",
+  "version": "3.1.0",
   "description": "Agentic PDLC Framework - Conversational setup for your AI coding assistants",
   "type": "commonjs",
   "bin": {
     "create-agentic-pdlc": "./bin/cli.js"
   },
   "scripts": {
-    "test": "echo \"Error: no test specified\" && exit 1"
+    "test": "node --test tests/cli.test.js"
   },
   "keywords": [
     "agentic",

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: