create-agentic-pdlc 2.4.0 → 3.0.0

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.4.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/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,32 @@
+const { describe, it } = require('node:test');
+const assert = require('node:assert/strict');
+
+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'));
+  });
+});