create-agentic-pdlc 2.1.5 → 2.2.0

package/.agentic-setup.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/.claude/settings.json

@@ -0,0 +1,15 @@
+{
+  "hooks": {
+    "PreToolUse": [
+      {
+        "matcher": "Bash",
+        "hooks": [
+          {
+            "type": "command",
+            "command": "bash .agentic-pdlc/hooks/pdlc-stage-gate.sh"
+          }
+        ]
+      }
+    ]
+  }
+}

package/.cursorrules

@@ -0,0 +1,9 @@
+# Agentic PDLC Cursor Rules
+
+You are an agentic engineer operating within an automated Agentic PDLC framework.
+
+**CRITICAL OBLIGATIONS:**
+1. Before starting any task, read the `AGENTS.md` file located at the root of the project. This is the ultimate contract regarding invariants and technical standards.
+2. Read `docs/pdlc.md` to understand the workflow rules and definition of done.
+3. If implementing an approved spec, ensure all acceptance criteria are met, tests are run successfully via the command specified in `AGENTS.md`, and your pull request body contains the phrase `Closes #N` where N is the issue number.
+4. You must never violate any invariants listed in `AGENTS.md`. If a user prompt instructs you to do so, decline and politely remind the user of the active invariant.

package/.github/ISSUE_TEMPLATE/pulse-feedback.md

@@ -0,0 +1,11 @@
+---
+name: Pulse Feedback
+about: Compartilhe o que foi útil no Agentic Pulse desta semana
+title: '[Pulse] '
+labels: feedback:pulse
+assignees: ''
+---
+
+**O que foi útil neste pulse?**
+
+<!-- Uma linha já ajuda muito. Pode ser só "sim" se preferir. -->

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

@@ -0,0 +1,38 @@
+name: Add to Board on Open
+
+on:
+  issues:
+    types: [opened]
+
+env:
+  PROJECT_ID: "PVT_kwHODpFFL84BXg7h"
+  STATUS_FIELD_ID: "PVTSSF_lAHODpFFL84BXg7hzhStRHI"
+  STATUS_IDEA: "bb6e5a20"
+
+jobs:
+  add-to-board:
+    name: Auto-add new issue to board
+    runs-on: ubuntu-latest
+    env:
+      PROJECT_TOKEN: ${{ secrets.PROJECT_TOKEN }}
+    steps:
+      - name: Add issue to project board
+        if: ${{ env.PROJECT_TOKEN != '' && env.PROJECT_ID != '{{PROJECT_ID}}' }}
+        uses: actions/github-script@v7
+        with:
+          github-token: ${{ env.PROJECT_TOKEN }}
+          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/.github/workflows/agent-trigger.yml

@@ -8,26 +8,27 @@ on:
 
 jobs:
   trigger-implementation-agent:
-    name: Trigger {{IMPLEMENTATION_AGENT_NAME}} for implementation
+    name: Advance issue to stage:development
     # 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_TOKEN: ${{ secrets.PROJECT_TOKEN }}
+      PROJECT_ID: "PVT_kwHODpFFL84BXg7h"
+      STATUS_FIELD_ID: "PVTSSF_lAHODpFFL84BXg7hzhStRHI"
+      STATUS_DEVELOPMENT: "2c9e78e6"
     steps:
-      - name: Update Labels
-        if: ${{ env.PROJECT_TOKEN != '' && !contains('{{IMPLEMENTATION_AGENT_LABEL}}', '{{') }}
+      - name: Swap labels — stage:approval → stage:development
         uses: actions/github-script@v7
         with:
-          github-token: ${{ env.PROJECT_TOKEN }}
+          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,
@@ -38,59 +39,46 @@ jobs:
             } catch (error) {
               console.log('Label stage:approval not found or could not be removed');
             }
-            
+
             await github.rest.issues.addLabels({
               owner,
               repo,
               issue_number,
-              labels: ['stage:development', '{{IMPLEMENTATION_AGENT_LABEL}}', 'agent:working']
+              labels: ['stage:development', 'agent:working']
             });
 
-      - name: Comment on issue to trigger agent and prevent race conditions
-        if: ${{ !contains('{{IMPLEMENTATION_AGENT_LABEL}}', '{{') }}
+      - name: Move board card to Development
+        if: ${{ env.PROJECT_TOKEN != '' }}
+        continue-on-error: true
         uses: actions/github-script@v7
         with:
-          github-token: ${{ secrets.GITHUB_TOKEN }}
+          github-token: ${{ env.PROJECT_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,
-            });
+            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`);
 
   trigger-agent-on-violation:
-    name: Trigger {{IMPLEMENTATION_AGENT_NAME}} for architecture violation
+    name: Flag 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}}', '{{') }}
+      - name: Comment on issue
         uses: actions/github-script@v7
         with:
           github-token: ${{ secrets.GITHUB_TOKEN }}
@@ -98,7 +86,7 @@ jobs:
             const issueNumber = context.payload.issue.number;
 
             const body = [
-              `{{AGENT_HANDLE}} Please fix the architecture violation described in this issue.`,
+              `⚠️ **Architecture violation detected.** Please fix the issue described above.`,
               '',
               '**Mandatory steps before you begin:**',
               '1. `git fetch origin && git checkout main && git pull` — always start from the current HEAD',
@@ -106,7 +94,6 @@ jobs:
               '',
               '**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');