create-agentic-pdlc 2.3.0 → 3.0.0

package/docs/superpowers/specs/2026-05-29-agentic-pulse-rework-taxonomy-design.md

@@ -0,0 +1,122 @@
+# Agentic Pulse — Rework Taxonomy with Review-Actor Attribution and Stage Correlation
+
+**Date:** 2026-05-29
+**Issue:** [#142](https://github.com/rafaeltcosta86/agentic-pdlc/issues/142)
+**Status:** stage:approval — awaiting spec:approved
+
+## Problem
+
+Current rework signal detects extra commit sessions but cannot distinguish cause. All rework produces the same generic recommendation: "incomplete specs or requirement changes."
+
+Three distinct causes exist, each pointing to a different fix:
+
+| Cause | Root stage | Fix |
+|---|---|---|
+| Code reviewer caught a defect | stage:development — DoD too weak | Tighten implementation checklist |
+| QA agent caught a functional gap | stage:detailing — spec incomplete | Add acceptance criteria |
+| Self-correction (pre-review) | Unknown | Not auto-determinable |
+
+## Design Decision
+
+**Option C selected:** Review-Actor Taxonomy + Stage Correlation
+- Auto-only (zero user friction)
+- Actors are configurable — not locked to any specific bot
+- Stage correlation provides upstream attribution when N≥3 data points available
+
+## Architecture
+
+### Files Changed
+
+- `.github/workflows/agentic-metrics.yml`
+- `templates/.github/workflows/agentic-metrics.yml` (mirror)
+
+No new files. No new dependencies.
+
+### Configuration
+
+```yaml
+env:
+  AGENTIC_PULSE_REVIEWERS: |
+    code_reviewer=gemini-code-assist[bot]
+    qa_agent=github-actions[bot]
+```
+
+Format: `role=login1,login2` per line. If absent/empty → taxonomy skipped, existing behavior unchanged.
+
+## Detection Logic
+
+### Review-Actor Rework Detection
+
+For each merged PR in the week window (up to 10 — consistent with existing rework block):
+
+1. Get commit timestamps (reuse existing fetch)
+2. If single commit session: skip
+3. `GET /repos/{owner}/{repo}/pulls/{pr}/reviews`
+4. For each review where `reviewer.login` is in the actor map:
+   - Record first review timestamp for that role
+   - Count commits with `timestamp > first_review_at`
+   - If count > 0: mark as `{role}`-triggered rework
+5. If multi-session but no configured actor review found before them: `self_correction`
+6. For reviewer-triggered PRs: extract `Closes #N` → store `{ pr_number, issue_number, role }` for stage correlation
+
+A PR can count in multiple role buckets if multiple roles triggered rework. Total rework % = unique PRs with any rework / total PRs. Role breakdown counts per role (sum can exceed total %).
+
+### Stage Correlation
+
+Load `stage:detailing` durations from `weekKey.jsonl` → `Map<issueNumber, durationDays>`
+
+Group:
+- `reviewer_rework_group`: issues linked to reviewer-triggered rework PRs with known detailing time
+- `clean_group`: issues linked to PRs with zero reviewer-triggered rework (single session OR only self-correction) with known detailing time
+
+Emit correlation signal only if both groups have N≥3. Otherwise skip.
+
+## Output Format
+
+### Rework signal (taxonomy active)
+
+```
+🟡 **Rework rate: 60%** — 6 de 10 PRs tiveram commits extras
+   ↳ Code reviewer: **4 PRs** → revisar DoD em stage:development
+   ↳ QA Agent: **1 PR** → spec com lacunas funcionais em stage:detailing
+   ↳ Self-correction: **1 PR** (causa não determinada automaticamente)
+```
+
+### Stage correlation signal (when N≥3 both groups)
+
+```
+💡 **Stage correlation:** PRs com reviewer rework tiveram Detailing médio de 0.2d vs 0.8d (N=4 vs N=6)
+   → Specs rápidas correlacionam com mais rework de review
+```
+
+### Signal levels
+
+| Condition | Level |
+|---|---|
+| `code_reviewer` rework ≥ 80% of total | 🔴 |
+| `code_reviewer` rework ≥ 50% of total | 🟡 |
+| `qa_agent` rework > 0 | 🟡 |
+| Stage correlation present | 🔵 (informational) |
+
+## Recommendations
+
+| Trigger | Recommendation |
+|---|---|
+| `code_reviewer` dominant | Revisar Definition of Done em stage:development. Considere checklist de qualidade antes de abrir PR. |
+| `qa_agent` > 0 | Spec tem lacunas funcionais. Revisar critérios de aceitação em stage:detailing. |
+| Stage correlation fires (rework detailing < clean detailing) | Specs rápidas correlacionam com mais rework. Invista mais tempo em stage:detailing. |
+| All self-correction | Configure AGENTIC_PULSE_REVIEWERS para attribution mais precisa. |
+
+## Backward Compatibility
+
+- `AGENTIC_PULSE_REVIEWERS` absent → taxonomy skipped, no regression
+- JSONL absent → correlation skipped, taxonomy still runs
+- N < 3 either group → correlation skipped
+- `listReviews` API error → catch, skip PR, continue
+
+## Out of Scope
+
+- Manual rework classification
+- Self-correction cause detection
+- Changes to Stage Residence Time collection
+- Changes to any other signal

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/package.json

@@ -1,13 +1,13 @@
 {
   "name": "create-agentic-pdlc",
-  "version": "2.3.0",
+  "version": "3.0.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/templates/.github/ISSUE_TEMPLATE/bug.md

@@ -0,0 +1,53 @@
+---
+name: Bug
+about: Broken behavior with root cause and fix criteria
+title: 'bug: '
+labels: type:bug
+assignees: ''
+---
+
+## Problem
+
+<!-- What fails. Who affected. Measured impact. -->
+
+## Root Cause
+
+<!-- Why it fails. Link to code/config if known. -->
+
+## Reproduction Steps
+
+1. 
+2. 
+3. 
+
+**Expected:** 
+**Actual:** 
+
+## Acceptance Criteria
+
+<!-- agent fills during detailing -->
+
+**AC1 — [name]**
+- Given 
+- When 
+- Then 
+
+## Edge Cases
+
+<!-- agent fills during detailing -->
+- EC1: [condition] → [expected behavior]
+
+## Out of Scope
+
+<!-- agent fills during detailing -->
+- 
+
+## Non-Functional Requirements
+
+<!-- agent fills during detailing — omit if pure docs/markdown -->
+- Reliability: idempotent — safe to re-run
+
+## Files to Modify
+
+<!-- agent fills during detailing -->
+- `path/to/file` — what changes

package/templates/.github/ISSUE_TEMPLATE/feature.md

@@ -0,0 +1,54 @@
+---
+name: Feature
+about: New capability with spec scaffold for detailing agent
+title: 'feat: '
+labels: type:feature
+assignees: ''
+---
+
+## Problem
+
+<!-- What fails or is missing. Who affected. Measured impact. -->
+
+## Sprint Goal / Success Metrics
+
+<!-- agent fills during detailing -->
+
+| Metric | Baseline | Target | When |
+|--------|----------|--------|------|
+|  |  |  |  |
+
+## Solution
+
+<!-- agent fills during detailing — behavioral description, no implementation details -->
+
+## Acceptance Criteria
+
+<!-- agent fills during detailing -->
+
+**AC1 — [name]**
+- Given 
+- When 
+- Then 
+
+## Edge Cases
+
+<!-- agent fills during detailing -->
+- EC1: [condition] → [expected behavior]
+
+## Out of Scope
+
+<!-- agent fills during detailing -->
+- 
+
+## Non-Functional Requirements
+
+<!-- agent fills during detailing — omit if pure docs/markdown -->
+- Performance: 
+- Security: 
+- Reliability: 
+
+## Files to Modify
+
+<!-- agent fills during detailing -->
+- `path/to/file` — what changes

package/templates/.github/ISSUE_TEMPLATE/task.md

@@ -0,0 +1,33 @@
+---
+name: Task
+about: Defined work unit with clear done criteria
+title: 'task: '
+labels: type:task
+assignees: ''
+---
+
+## Objective
+
+<!-- What must be done and why. -->
+
+## Steps
+
+<!-- agent fills during detailing -->
+1. 
+2. 
+
+## Acceptance Criteria
+
+<!-- agent fills during detailing -->
+- [ ] 
+- [ ] 
+
+## Out of Scope
+
+<!-- agent fills during detailing -->
+- 
+
+## Files to Modify
+
+<!-- agent fills during detailing -->
+- `path/to/file` — what changes

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

@@ -14,13 +14,13 @@ jobs:
     name: Auto-add new issue to board
     runs-on: ubuntu-latest
     env:
-      PROJECT_PAT: ${{ secrets.PROJECT_PAT }}
+      PROJECT_TOKEN: ${{ secrets.PROJECT_TOKEN }}
     steps:
       - name: Add issue to project board
-        if: ${{ env.PROJECT_PAT != '' && env.PROJECT_ID != '{{PROJECT_ID}}' }}
-        uses: actions/github-script@v7
+        if: ${{ env.PROJECT_TOKEN != '' && env.PROJECT_ID != '{{PROJECT_ID}}' }}
+        uses: actions/github-script@v8
         with:
-          github-token: ${{ env.PROJECT_PAT }}
+          github-token: ${{ env.PROJECT_TOKEN }}
           script: |
             const nodeId = context.payload.issue.node_id;
             const number = context.payload.issue.number;

package/templates/.github/workflows/agent-trigger.yml

@@ -17,13 +17,13 @@ jobs:
       pull-requests: write
       contents: read
     env:
-      PROJECT_PAT: ${{ secrets.PROJECT_PAT }}
+      PROJECT_TOKEN: ${{ secrets.PROJECT_TOKEN }}
       PROJECT_ID: "{{PROJECT_ID}}"
       STATUS_FIELD_ID: "{{STATUS_FIELD_ID}}"
       STATUS_DEVELOPMENT: "{{ID_DEVELOPMENT}}"
     steps:
-      - name: Update Labels
-        uses: actions/github-script@v7
+      - name: Update stage labels
+        uses: actions/github-script@v8
         with:
           github-token: ${{ secrets.GITHUB_TOKEN }}
           script: |
@@ -41,23 +41,32 @@ jobs:
               console.log('Label stage:approval not found or could not be removed');
             }
 
-            const agentLabel = '{{IMPLEMENTATION_AGENT_LABEL}}';
-            const labelsToAdd = ['stage:development'];
-            if (!agentLabel.includes('{{')) labelsToAdd.push(agentLabel, 'agent:working');
-
             await github.rest.issues.addLabels({
               owner,
               repo,
               issue_number,
-              labels: labelsToAdd
+              labels: ['stage:development']
+            });
+
+      - name: Add agent label via PAT
+        if: ${{ env.PROJECT_TOKEN != '' && !contains('{{IMPLEMENTATION_AGENT_LABEL}}', '{{') }}
+        uses: actions/github-script@v8
+        with:
+          github-token: ${{ env.PROJECT_TOKEN }}
+          script: |
+            await github.rest.issues.addLabels({
+              owner: context.repo.owner,
+              repo: context.repo.repo,
+              issue_number: context.payload.issue.number,
+              labels: ['{{IMPLEMENTATION_AGENT_LABEL}}']
             });
 
       - name: Move board card to Development
-        if: ${{ env.PROJECT_PAT != '' && env.PROJECT_ID != '{{PROJECT_ID}}' }}
+        if: ${{ env.PROJECT_TOKEN != '' && env.PROJECT_ID != '{{PROJECT_ID}}' }}
         continue-on-error: true
-        uses: actions/github-script@v7
+        uses: actions/github-script@v8
         with:
-          github-token: ${{ env.PROJECT_PAT }}
+          github-token: ${{ env.PROJECT_TOKEN }}
           script: |
             const nodeId = context.payload.issue.node_id;
             const number = context.payload.issue.number;
@@ -76,7 +85,7 @@ jobs:
 
       - name: Comment on issue to trigger agent and prevent race conditions
         if: ${{ !contains('{{IMPLEMENTATION_AGENT_LABEL}}', '{{') && vars.JULES_ENABLED == 'true' }}
-        uses: actions/github-script@v7
+        uses: actions/github-script@v8
         with:
           github-token: ${{ secrets.GITHUB_TOKEN }}
           script: |
@@ -119,7 +128,7 @@ jobs:
     steps:
       - name: Comment on issue to trigger agent
         if: ${{ !contains('{{IMPLEMENTATION_AGENT_LABEL}}', '{{') && vars.JULES_ENABLED == 'true' }}
-        uses: actions/github-script@v7
+        uses: actions/github-script@v8
         with:
           github-token: ${{ secrets.GITHUB_TOKEN }}
           script: |