create-agentic-pdlc 2.0.0 → 2.0.1

package/.github/CODEOWNERS

@@ -0,0 +1,5 @@
+# This file prevents autonomous agents from modifying core security, automation, and instruction rules
+# without explicit approval from the repository owner.
+
+.github/ @rafaeltcosta86
+AGENTS.md @rafaeltcosta86

package/AGENTS.md

@@ -27,13 +27,14 @@ Always start from the current `main` HEAD. Never work over stale snapshots.
 ## Mandatory Workflow
 
 0. **Identity**: Always prefix your GitHub comments with `🤖 **Agent:** ` to distinguish yourself.
-1. Read the issue entirely — understand its type (US/BUG/TASK/SPIKE) and the Acceptance Criteria.
-2. Read `docs/pdlc.md` — understand the PDLC and the Definition of Done in this project.
-3. Read all files mentioned in the issue's technical context.
-4. Implement the **minimum viable change** that satisfies the ACs — do not refactor beyond scope.
-5. Run tests: `echo "No tests/build needed."`
-6. Run typecheck: `echo "No typecheck needed."`
-7. Create a Pull Request with `Closes #N` in the body — automation moves the board.
+1. **Initial State**: When beginning work on a new issue, your very first action must be to apply the `stage:exploration` label using the GitHub CLI (`gh issue edit <N> --add-label "stage:exploration"`).
+2. Read the issue entirely — understand its type (US/BUG/TASK/SPIKE) and the Acceptance Criteria.
+3. Read `docs/pdlc.md` — understand the PDLC and the Definition of Done in this project.
+4. Read all files mentioned in the issue's technical context.
+5. Implement the **minimum viable change** that satisfies the ACs — do not refactor beyond scope.
+6. Run tests: `echo "No tests/build needed."`
+7. Run typecheck: `echo "No typecheck needed."`
+8. Create a Pull Request with `Closes #N` in the body — automation moves the board.
 
 ## What NOT to do
 

package/bin/cli.js

@@ -63,8 +63,10 @@ rl.question('Which AI Agent will you use for the setup? (e.g. claude, cursor, co
       fs.copyFileSync(claudeSetupSrc, dest);
       console.log(`✅ Setup agent profile written to .agentic-setup.md`);
       console.log(`\n${green}🎉 Done! To start the conversational setup:${reset}`);
-      console.log(`${cyan}\t1. Type 'claude'${reset}`);
-      console.log(`${cyan}\t2. Ask Claude to "read .agentic-setup.md to enter Setup Mode."${reset}`);
+      console.log(`${cyan}\tStep 1: Open the Claude Code CLI in your terminal (type 'claude')${reset}`);
+      console.log(`${cyan}\t        [Or open your preferred IDE Agent chat, like Antigravity, Cursor, Codex, GitHub Copilot, etc]${reset}`);
+      console.log(`${cyan}\tStep 2: Paste this exact prompt:${reset}`);
+      console.log(`${yellow}\t        "read .agentic-setup.md to enter Setup Mode."${reset}`);
       console.log(`\nNote: Once setup is completed, the agent will typically delete .agentic-setup.md to keep your root clean.\n`);
     } else {
       console.error(`❌ Could not find claude instruction file at ${claudeSetupSrc}`);

package/docs/flow.md

@@ -2,6 +2,19 @@
 
 This document describes the full lifecycle of a card on the agentic-pdlc board — who acts at each stage, what triggers each transition, which labels are added or removed, and where human gates are required.
 
+```mermaid
+stateDiagram-v2
+    direction LR
+    Idea --> Exploration : stage:exploration
+    Exploration --> Brainstorming : stage:brainstorming
+    Brainstorming --> Detailing : Gate 1 (PM)
+    Detailing --> Approval : stage:approval
+    Approval --> Development : Gate 2 (spec:approved)
+    Development --> Testing : stage:testing
+    Testing --> CodeReview : PR Opened
+    CodeReview --> Production : Gate 3 (PR Merged)
+```
+
 ---
 
 ## Roles
@@ -21,17 +34,17 @@ This document describes the full lifecycle of a card on the agentic-pdlc board
 ## Step-by-Step Flow
 
 ### 💡 Idea
-Issue exists in the backlog with no `upstream:` label.
+Issue exists in the backlog with no `stage:` label.
 
 ---
 
 ### 🔍 Exploration
 
 **Trigger (two equivalent paths):**
-- PM tells Claude directly in chat → Claude adds `upstream:exploration` to the issue, OR
-- PM adds `upstream:exploration` directly to the issue
+- PM tells Claude directly in chat → Claude adds `stage:exploration` to the issue, OR
+- PM adds `stage:exploration` directly to the issue
 
-**Workflow:** `project-automation.yml` detects `upstream:exploration` → moves card to Exploration.
+**Workflow:** `project-automation.yml` detects `stage:exploration` → moves card to Exploration.
 
 **Who works:** Claude reads relevant code and context.
 
@@ -43,7 +56,7 @@ Issue exists in the backlog with no `upstream:` label.
 
 **Actions:**
 - Claude posts a comment on the issue with findings and 2–3 proposed approaches
-- Claude swaps `upstream:exploration` → `upstream:brainstorming`
+- Claude swaps `stage:exploration` → `stage:brainstorming`
 
 **Workflow:** `project-automation.yml` moves card to Brainstorming.
 
@@ -57,14 +70,14 @@ Issue exists in the backlog with no `upstream:` label.
 
 ### 📐 Detail Solution ← Gate 1
 
-**Trigger:** `upstream-gate.yml` detects PM approval comment on a `upstream:brainstorming` issue → swaps `upstream:brainstorming` → `upstream:detailing` via `PROJECT_TOKEN`.
+**Trigger:** `upstream-gate.yml` detects PM approval comment on a `stage:brainstorming` issue → swaps `stage:brainstorming` → `stage:detailing` via `PROJECT_TOKEN`.
 
 **Who works:** Claude rewrites the issue body with:
 1. User story (`As… I want… So that…`)
 2. Acceptance Criteria (AC1, AC2, …)
 3. Files to modify
 
-**After spec is written:** Claude swaps `upstream:detailing` → `upstream:approval`.
+**After spec is written:** Claude swaps `stage:detailing` → `stage:approval`.
 
 **Workflow:** `project-automation.yml` moves card to Approval.
 
@@ -75,8 +88,8 @@ Issue exists in the backlog with no `upstream:` label.
 **⏸ Human gate (Gate 2 — PM + TL):** Both PM (business decisions) and TL (technical decisions) review the spec. When both are satisfied, PM adds label `spec:approved`.
 
 **Workflow:** `agent-trigger.yml` detects `spec:approved` →
-1. Removes `upstream:approval`
-2. Adds `upstream:development`
+1. Removes `stage:approval`
+2. Adds `stage:development`
 3. Adds specific agent label (e.g., `jules`)
 4. Posts a structured comment with implementation instructions for the Agent
 
@@ -88,7 +101,7 @@ Issue exists in the backlog with no `upstream:` label.
 
 **Who works:** Implementation Agent implements the spec strictly within the Acceptance Criteria.
 
-**When done:** Agent adds `upstream:testing` before running tests.
+**When done:** Agent adds `stage:testing` before running tests.
 
 **Workflow:** `project-automation.yml` moves card to Testing.
 
@@ -128,12 +141,12 @@ Issue exists in the backlog with no `upstream:` label.
 
 | Label | Added by | Removed by |
 |-------|----------|------------|
-| `upstream:exploration` | PM (human) or Claude | Claude |
-| `upstream:brainstorming` | Claude | `upstream-gate.yml` |
-| `upstream:detailing` | `upstream-gate.yml` | Claude |
-| `upstream:approval` | Claude | `agent-trigger.yml` |
-| `upstream:development` | `agent-trigger.yml` | Impl. Agent |
-| `upstream:testing` | Impl. Agent | `project-automation.yml` (on PR open) |
+| `stage:exploration` | PM (human) or Claude | Claude |
+| `stage:brainstorming` | Claude | `upstream-gate.yml` |
+| `stage:detailing` | `upstream-gate.yml` | Claude |
+| `stage:approval` | Claude | `agent-trigger.yml` |
+| `stage:development` | `agent-trigger.yml` | Impl. Agent |
+| `stage:testing` | Impl. Agent | `project-automation.yml` (on PR open) |
 | `spec:approved` | PM (human) | — |
 | `agent_label` (e.g. `jules`, `sweep`) | `agent-trigger.yml` | — |
 | `pr:in-review` | `project-automation.yml` | `project-automation.yml` |

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "create-agentic-pdlc",
-  "version": "2.0.0",
-  "description": "Scaffold the Agentic PDLC framework effortlessly",
+  "version": "2.0.1",
+  "description": "Agentic PDLC Framework - Conversational setup for your AI coding assistants",
   "type": "commonjs",
   "bin": {
     "create-agentic-pdlc": "./bin/cli.js"

package/templates/AGENTS.md

@@ -30,13 +30,14 @@ Always start from the current `main` HEAD. Never work over stale snapshots.
 ## Mandatory Workflow
 
 0. **Identity**: Always prefix your GitHub comments with `🤖 **Agent:** ` to distinguish yourself.
-1. Read the issue entirely — understand its type (US/BUG/TASK/SPIKE) and the Acceptance Criteria.
-2. Read `docs/pdlc.md` — understand the PDLC and the Definition of Done in this project.
-3. Read all files mentioned in the issue's technical context.
-4. Implement the **minimum viable change** that satisfies the ACs — do not refactor beyond scope.
-5. Run tests: `{{TEST_COMMAND}}`
-6. Run typecheck (if applicable): `{{TYPECHECK_COMMAND}}`
-7. Create a Pull Request with `Closes #N` in the body — automation moves the board.
+1. **Initial State**: When beginning work on a new issue, your very first action must be to apply the `stage:exploration` label using the GitHub CLI (`gh issue edit <N> --add-label "stage:exploration"`).
+2. Read the issue entirely — understand its type (US/BUG/TASK/SPIKE) and the Acceptance Criteria.
+3. Read `docs/pdlc.md` — understand the PDLC and the Definition of Done in this project.
+4. Read all files mentioned in the issue's technical context.
+5. Implement the **minimum viable change** that satisfies the ACs — do not refactor beyond scope.
+6. Run tests: `{{TEST_COMMAND}}`
+7. Run typecheck (if applicable): `{{TYPECHECK_COMMAND}}`
+8. Create a Pull Request with `Closes #N` in the body — automation moves the board.
 
 ### Spec format (Upstream Agents)