create-agentic-pdlc 2.1.5 → 2.2.0

package/.agentic-pdlc/SETUP_PROMPT.md

@@ -0,0 +1,73 @@
+---
+name: agentic-pdlc
+description: Orchestrates the Agentic Product Development Life Cycle (PDLC) upstream stages (Idea -> Spec) and includes an interactive Setup Mode to initialize the framework.
+---
+
+# Agentic PDLC Orchestrator
+
+You are the upstream brainstorm partner and orchestrator for the Agentic PDLC framework. Your role is primarily to define technical specs based on user ideas.
+
+## SETUP MODE
+
+If the user invokes you in a new project, you must first check if the PDLC artifacts are present in the repository.
+Specifically, check for:
+- `AGENTS.md`
+- `docs/pdlc.md`
+- `.github/CODEOWNERS`
+- `.github/workflows/project-automation.yml`
+- `.github/workflows/agent-trigger.yml`
+- `.github/workflows/pdlc-health-check.yml`
+
+If any of these files are missing, you are in **Setup Mode**. Do not proceed with feature requests until setup is complete.
+1. **Language Detection:** Analyze the user's previous prompts and preferred language. Conduct this entire Setup Mode and ask all your interactive questions in that same language.
+2. Acknowledge that the framework is not yet set up.
+3. Interactively ask the user for required values **one group at a time**:
+   - **Project basics:** Project Name, Description, Technical Stack (Structure), and GitHub Username (for CODEOWNERS security).
+   - **Commands:** Test command, Lint command, Build command.
+   - **Invariants:** Critical business rules agents must never violate (e.g. Human-in-the-loop).
+   - **Board IDs:** PROJECT_ID, STATUS_FIELD_ID, column option IDs (provide standard PDLC options: Idea, Exploration, Brainstorming, Detail Solution, Approval, Development, Testing, Code Review / PR, Production). Allow user to answer "skip", which means you leave the placeholders intact.
+   - **Architecture Violation:** Ask "Does your project use an automated architecture auditing tool (e.g., a CI job that creates issues with an `architecture-violation` label)?". If yes, uncomment the `move-violation-to-board` job inside `project-automation.yml`. If no, ask if they would like help implementing one, reminding them that it significantly improves their agentic development process. If they decline, you can leave the job commented out.
+   - **QA Agent (Variant B):** Ask "Do you plan to use an AI QA Agent (e.g. QAWolf or a secondary script) to verify your PRs before Code Review?". If yes, explain you will adopt Variant B: you will change `STATUS_CODE_REVIEW_PR` to `STATUS_TESTING` inside the `move-card-on-pr-open` job in `project-automation.yml` and uncomment the `move-card-on-qa-pass` job. If no, leave the workflow as Variant A (default) and delete the optional `.github/workflows/qa-agent.yml` template.
+   - **Implementation agent handle:** e.g., `@google-labs-jules`, or "none".
+3. Generate and write the missing files replacing the `{{SCREAMING_SNAKE_CASE}}` placeholders using the templates logic you know (usually they reside in standard Agentic PDLC templates).
+4. Offer to run the `gh` commands for labels (`spec:approved`, `pr:in-review`, `pr:approved`, `architecture-violation`).
+5. Commit everything with the message: `chore: setup agentic-pdlc framework`.
+6. **IMPORTANT:** Delete this setup prompt file (e.g., `.agentic-setup.md`, `.agentic-setup-prompt.md`, or `.agentic-pdlc/SETUP_PROMPT.md`) from the root or `.agentic-pdlc/` directory to clean up the workspace.
+7. Conclude Setup Mode.
+
+---
+
+## EXECUTION MODE
+
+If `AGENTS.md` and `docs/pdlc.md` are present, you are in **Execution Mode**. 
+
+### 1. Daily Upstream Loop
+Your job is to move issues from "Idea" to "Detail Solution".
+When asked to work on a feature, you will:
+- Explore the code context.
+- Present architectural approaches (Brainstorming).
+- Stop and wait for the human PM's explicit approval (Gate 1).
+
+### 2. Creating the Spec
+Once approved, you will detail the solution directly into the GitHub Issue body. Focus on precise Acceptance Criteria.
+**IMPORTANT:** You must always rewrite the full issue body to include both the user story and the Acceptance Criteria. Do not simply append the ACs to the existing text. Use this format:
+
+```
+**As** [user],
+**I want** [action],
+**so that** [benefit].
+
+---
+
+## Acceptance Criteria
+...
+```
+
+### 3. Handoff
+Do not write code for downstream features! Your goal is to refine the Spec, so the human Tech Lead can label the issue `spec:approved`. This label triggers the downstream agent via `agent-trigger.yml`.
+
+### 4. Moving the Board (Upstream States)
+As you actively work with the user advancing the feature, you MUST use the GitHub CLI to update internal state labels. This triggers GitHub Actions behind the scenes.
+- Starting context evaluation: Run `gh issue edit <N> --add-label "stage:exploration"`
+- Presenting architecture/approaches: Run `gh issue edit <N> --add-label "stage:brainstorming"`
+- Starting to write the technical spec: Run `gh issue edit <N> --add-label "stage:detailing"`

package/.agentic-pdlc/hooks/pdlc-stage-gate.sh

@@ -0,0 +1,39 @@
+#!/bin/bash
+# PDLC Stage Gate — blocks gh pr create without stage:approval on linked issue.
+# Bypass: branch prefix hotfix/ skips all checks.
+
+INPUT=$(cat)
+COMMAND=$(echo "$INPUT" | node -e "const d=JSON.parse(require('fs').readFileSync(0)); console.log(d.command || '')" 2>/dev/null || echo "")
+
+if ! echo "$COMMAND" | grep -q "gh pr create"; then
+  exit 0
+fi
+
+BRANCH=$(git branch --show-current 2>/dev/null || echo "")
+
+if echo "$BRANCH" | grep -qE "^hotfix/"; then
+  echo "✅ PDLC: Hotfix branch — stage gate bypassed."
+  exit 0
+fi
+
+ISSUE_NUM=$(echo "$BRANCH" | grep -oE '[0-9]+' | head -1)
+
+if [ -z "$ISSUE_NUM" ]; then
+  echo "❌ PDLC Stage Gate: Cannot determine issue from branch '$BRANCH'."
+  echo "   Use: feat/<issue-number>-<description> or hotfix/<issue-number>-<description>"
+  exit 1
+fi
+
+LABELS=$(gh issue view "$ISSUE_NUM" --json labels --jq '[.labels[].name] | join(" ")' 2>/dev/null || echo "")
+
+if echo "$LABELS" | grep -qw "stage:approval"; then
+  echo "✅ PDLC: Issue #$ISSUE_NUM approved — gate passed."
+  exit 0
+fi
+
+STAGE=$(echo "$LABELS" | tr ' ' '\n' | grep "^stage:" | head -1 || echo "none")
+echo "❌ PDLC Stage Gate: Issue #$ISSUE_NUM is not approved."
+echo "   Current stage: $STAGE"
+echo "   Required: stage:approval label on the issue."
+echo "   Emergency bypass: rename branch to hotfix/<issue-number>-<description>."
+exit 1

package/.agentic-pdlc/metrics/2026-W19.md

@@ -0,0 +1,21 @@
+# Agentic Metrics — 2026-W19
+
+> Métricas agentic-specific geradas automaticamente pelo [agentic-pdlc](https://github.com/rafaeltcosta86/agentic-pdlc).
+
+## 🔄 Stage Residence Time
+
+Tempo médio que issues passaram em cada fase do PDLC esta semana (transições completas).
+
+| Stage | Avg | N | vs semana passada |
+|---|---|---|---|
+| **Exploration** | 0d | 1 issue | — |
+| **Brainstorming** | 0d | 1 issue | — |
+| **Detailing** | 0d | 1 issue | — |
+| **Approval** | 0d | 1 issue | — |
+| **Development** | 0.3d | 1 issue | — |
+| **Testing** | 0d | 1 issue | — |
+
+> **Insight:** `Development` é o maior gargalo (0.3d avg). Issues acumulam aqui. Considere quebrar specs ou aumentar cadência de revisão nessa fase.
+
+---
+*Gerado em 2026-05-10 · [Ver histórico](.)*

package/.agentic-pdlc/metrics/raw/2026-W19.jsonl

@@ -0,0 +1,6 @@
+{"issueNumber":58,"stage":"stage:exploration","durationDays":0}
+{"issueNumber":58,"stage":"stage:brainstorming","durationDays":0}
+{"issueNumber":58,"stage":"stage:detailing","durationDays":0}
+{"issueNumber":58,"stage":"stage:approval","durationDays":0}
+{"issueNumber":58,"stage":"stage:development","durationDays":0.3}
+{"issueNumber":58,"stage":"stage:testing","durationDays":0}

package/.agentic-pdlc/metrics/raw/2026-W20.jsonl

@@ -0,0 +1 @@
+{"issueNumber":66,"stage":"stage:exploration","durationDays":0}

package/.agentic-pdlc/templates/.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/ @{{GITHUB_USERNAME}}
+AGENTS.md @{{GITHUB_USERNAME}}

package/.agentic-pdlc/templates/.github/copilot-instructions.md

@@ -0,0 +1,12 @@
+# Agentic PDLC Instructions for GitHub Copilot Workspace
+
+Hello! You are operating within the Agentic PDLC framework.
+
+Before addressing the user's prompt or executing any task in this workspace, you MUST:
+
+1. Read the `AGENTS.md` file located at the root of this repository. It contains the primary instructions, definitions of done, and absolute invariants you must respect.
+2. Read `docs/pdlc.md` to understand your role in the project lifecycle.
+
+Never violate the invariants described in those files. If a user asks you to do something that contradicts `AGENTS.md`, you must refuse and point out the conflict.
+
+Focus on delivering the absolute minimum required to satisfy the immediate technical specs. Start! 

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

@@ -0,0 +1,38 @@
+name: Add to Board on Open
+
+on:
+  issues:
+    types: [opened]
+
+env:
+  PROJECT_ID: "{{PROJECT_ID}}"
+  STATUS_FIELD_ID: "{{STATUS_FIELD_ID}}"
+  STATUS_IDEA: "{{ID_IDEA}}"
+
+jobs:
+  add-to-board:
+    name: Auto-add new issue to board
+    runs-on: ubuntu-latest
+    env:
+      PROJECT_PAT: ${{ secrets.PROJECT_PAT }}
+    steps:
+      - name: Add issue to project board
+        if: ${{ env.PROJECT_PAT != '' && env.PROJECT_ID != '{{PROJECT_ID}}' }}
+        uses: actions/github-script@v7
+        with:
+          github-token: ${{ env.PROJECT_PAT }}
+          script: |
+            const nodeId = context.payload.issue.node_id;
+            const number = context.payload.issue.number;
+            const { addProjectV2ItemById: { item } } = await github.graphql(`
+              mutation($p: ID!, $c: ID!) {
+                addProjectV2ItemById(input: {projectId: $p, contentId: $c}) { item { id } }
+              }`, { p: process.env.PROJECT_ID, c: nodeId });
+            await github.graphql(`
+              mutation($p: ID!, $i: ID!, $f: ID!, $v: ProjectV2FieldValue!) {
+                updateProjectV2ItemFieldValue(input: {projectId: $p, itemId: $i, fieldId: $f, value: $v}) {
+                  projectV2Item { id }
+                }
+              }`, { p: process.env.PROJECT_ID, i: item.id, f: process.env.STATUS_FIELD_ID,
+                   v: { singleSelectOptionId: process.env.STATUS_IDEA } });
+            console.log(`Issue #${number} added to board → Idea`);

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

@@ -0,0 +1,146 @@
+name: Trigger Implementation Agent
+
+# Triggers when spec:approved is added to an issue (Gate 2)
+# or when an architecture-violation issue is modified (Sentinel flow)
+on:
+  issues:
+    types: [labeled]
+
+jobs:
+  trigger-implementation-agent:
+    name: Trigger {{IMPLEMENTATION_AGENT_NAME}} for implementation
+    # Runs only when spec:approved is added
+    if: github.event.label.name == 'spec:approved'
+    runs-on: ubuntu-latest
+    permissions:
+      issues: write
+      pull-requests: write
+      contents: read
+    env:
+      PROJECT_PAT: ${{ secrets.PROJECT_PAT }}
+      PROJECT_ID: "{{PROJECT_ID}}"
+      STATUS_FIELD_ID: "{{STATUS_FIELD_ID}}"
+      STATUS_DEVELOPMENT: "{{ID_DEVELOPMENT}}"
+    steps:
+      - name: Update Labels
+        uses: actions/github-script@v7
+        with:
+          github-token: ${{ secrets.GITHUB_TOKEN }}
+          script: |
+            const { owner, repo } = context.repo;
+            const issue_number = context.payload.issue.number;
+
+            try {
+              await github.rest.issues.removeLabel({
+                owner,
+                repo,
+                issue_number,
+                name: 'stage:approval'
+              });
+            } catch (error) {
+              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
+            });
+
+      - name: Move board card to Development
+        if: ${{ env.PROJECT_PAT != '' && env.PROJECT_ID != '{{PROJECT_ID}}' }}
+        continue-on-error: true
+        uses: actions/github-script@v7
+        with:
+          github-token: ${{ env.PROJECT_PAT }}
+          script: |
+            const nodeId = context.payload.issue.node_id;
+            const number = context.payload.issue.number;
+            const { addProjectV2ItemById: { item } } = await github.graphql(`
+              mutation($p: ID!, $c: ID!) {
+                addProjectV2ItemById(input: {projectId: $p, contentId: $c}) { item { id } }
+              }`, { p: process.env.PROJECT_ID, c: nodeId });
+            await github.graphql(`
+              mutation($p: ID!, $i: ID!, $f: ID!, $v: ProjectV2FieldValue!) {
+                updateProjectV2ItemFieldValue(input: {projectId: $p, itemId: $i, fieldId: $f, value: $v}) {
+                  projectV2Item { id }
+                }
+              }`, { p: process.env.PROJECT_ID, i: item.id, f: process.env.STATUS_FIELD_ID,
+                   v: { singleSelectOptionId: process.env.STATUS_DEVELOPMENT } });
+            console.log(`Issue #${number} → Development`);
+
+      - name: Comment on issue to trigger agent and prevent race conditions
+        if: ${{ !contains('{{IMPLEMENTATION_AGENT_LABEL}}', '{{') }}
+        uses: actions/github-script@v7
+        with:
+          github-token: ${{ secrets.GITHUB_TOKEN }}
+          script: |
+            const issueNumber = context.payload.issue.number;
+            const issueTitle = context.payload.issue.title;
+
+            const body = [
+              `🤖 **Agentic PDLC Orchestrator:** I have dispatched the implementation agent. Please wait for the Pull Request and avoid making concurrent commits on this task to prevent race conditions.`,
+              '',
+              `{{AGENT_HANDLE}} The spec for this issue has been approved. Please implement it exactly as described in the body above.`,
+              '',
+              '**Mandatory steps before you begin:**',
+              '1. `git fetch origin && git checkout main && git pull` — always start from the current HEAD',
+              '2. Read `AGENTS.md` — mandatory rules for agents in this repository',
+              '3. Read `docs/pdlc.md` — Definition of Done and invariants reference',
+              '',
+              '**Rules:**',
+              '- Implement strictly what the Acceptance Criteria describes',
+              '- Run `{{TEST_COMMAND}}` before opening the Pull Request',
+              `- Include \`Closes #${issueNumber}\` in the PR body`,
+              '- Create a descriptive branch branching from `main`',
+            ].join('\n');
+
+            await github.rest.issues.createComment({
+              owner: context.repo.owner,
+              repo: context.repo.repo,
+              issue_number: issueNumber,
+              body,
+            });
+
+  trigger-agent-on-violation:
+    name: Trigger {{IMPLEMENTATION_AGENT_NAME}} for architecture violation
+    # Runs when architecture-violation is added (Sentinel flow)
+    if: github.event.label.name == 'architecture-violation'
+    runs-on: ubuntu-latest
+    permissions:
+      issues: write
+      pull-requests: write
+      contents: read
+    steps:
+      - name: Comment on issue to trigger agent
+        if: ${{ !contains('{{IMPLEMENTATION_AGENT_LABEL}}', '{{') }}
+        uses: actions/github-script@v7
+        with:
+          github-token: ${{ secrets.GITHUB_TOKEN }}
+          script: |
+            const issueNumber = context.payload.issue.number;
+
+            const body = [
+              `{{AGENT_HANDLE}} Please fix the architecture violation described in this issue.`,
+              '',
+              '**Mandatory steps before you begin:**',
+              '1. `git fetch origin && git checkout main && git pull` — always start from the current HEAD',
+              '2. Read `AGENTS.md` — mandatory rules for agents in this repository',
+              '',
+              '**Rules:**',
+              '- Fix only what the violation points out — do not refactor unrelated code',
+              '- Run `{{TEST_COMMAND}}` before opening the Pull Request',
+              `- Include \`Closes #${issueNumber}\` in the PR body`,
+            ].join('\n');
+
+            await github.rest.issues.createComment({
+              owner: context.repo.owner,
+              repo: context.repo.repo,
+              issue_number: issueNumber,
+              body,
+            });