create-agentic-pdlc 1.1.1 → 2.0.0

package/templates/.github/workflows/project-automation.yml

@@ -5,8 +5,8 @@ on:
     types: [opened, reopened, closed]
   pull_request_review:
     types: [submitted]
-  issue_comment:
-    types: [created]
+  issues:
+    types: [labeled]
 
 env:
   PROJECT_ID: "{{PROJECT_ID}}"
@@ -15,45 +15,52 @@ env:
   STATUS_BRAINSTORMING: "{{ID_BRAINSTORMING}}"
   STATUS_DETAILING: "{{ID_DETAILING}}"
   STATUS_APPROVAL: "{{ID_APPROVAL}}"
-  STATUS_CODE_REVIEW: "{{ID_CODE_REVIEW}}"
-  STATUS_PULL_REQUEST: "{{ID_PULL_REQUEST}}"
-  STATUS_PRODUCAO: "{{ID_PRODUCAO}}"
+  STATUS_DEVELOPMENT: "{{ID_DEVELOPMENT}}"
+  STATUS_TESTING: "{{ID_TESTING}}"
+  STATUS_CODE_REVIEW_PR: "{{ID_CODE_REVIEW_PR}}"
+  STATUS_PRODUCTION: "{{ID_PRODUCTION}}"
 
 jobs:
-  # Issue Comment → Move Upstream
-  move-card-on-comment:
-    name: Upstream Comment Marker → Move Card
-    if: github.event_name == 'issue_comment' && github.event.action == 'created'
+  # Issue Labeled → Move Upstream
+  move-card-on-label:
+    name: Upstream Label → Move Card
+    if: github.event_name == 'issues' && github.event.action == 'labeled'
     runs-on: ubuntu-latest
     env:
       PROJECT_TOKEN: ${{ secrets.PROJECT_TOKEN }}
     steps:
-      - name: Detect Marker and Move Issue
+      - name: Detect Label and Move Issue
         if: ${{ env.PROJECT_TOKEN != '' }}
         uses: actions/github-script@v7
         with:
           github-token: ${{ env.PROJECT_TOKEN }}
           script: |
-            const body = context.payload.comment.body;
+            const labelName = context.payload.label.name;
             let targetStatusId = null;
             let stageName = null;
 
-            if (body.includes('<!-- PDLC:stage:exploration -->')) {
+            if (labelName === 'upstream:exploration') {
               targetStatusId = process.env.STATUS_EXPLORATION;
               stageName = 'Exploration';
-            } else if (body.includes('<!-- PDLC:stage:brainstorming -->')) {
+            } else if (labelName === 'upstream:brainstorming') {
               targetStatusId = process.env.STATUS_BRAINSTORMING;
               stageName = 'Brainstorming';
-            } else if (body.includes('<!-- PDLC:stage:detailing -->')) {
+            } else if (labelName === 'upstream:detailing') {
               targetStatusId = process.env.STATUS_DETAILING;
               stageName = 'Detailing';
-            } else if (body.includes('<!-- PDLC:stage:approval -->')) {
+            } else if (labelName === 'upstream:approval') {
               targetStatusId = process.env.STATUS_APPROVAL;
               stageName = 'Approval';
+            } else if (labelName === 'upstream:development') {
+              targetStatusId = process.env.STATUS_DEVELOPMENT;
+              stageName = 'Development';
+            } else if (labelName === 'upstream:testing') {
+              targetStatusId = process.env.STATUS_TESTING;
+              stageName = 'Testing';
             }
 
             if (!targetStatusId) {
-              console.log('No upstream PDLC marker found. Skipping.');
+              console.log('No upstream PDLC label found. Skipping.');
               return;
             }
 
@@ -79,16 +86,17 @@ jobs:
             await moveItem(node_id, targetStatusId);
             console.log(`Issue #${number} moved to ${stageName}`);
 
+{{OPTIONAL_ARCHITECTURE_VIOLATION_JOB}}
 
-  # PR Opened → Move linked issue to Code Review
+  # PR Opened → Move linked issue to Code Review / PR
   move-card-on-pr-open:
-    name: Open PR → Code Review
+    name: Open PR → Code Review / PR
     if: github.event_name == 'pull_request' && (github.event.action == 'opened' || github.event.action == 'reopened')
     runs-on: ubuntu-latest
     env:
       PROJECT_TOKEN: ${{ secrets.PROJECT_TOKEN }}
     steps:
-      - name: Move linked issue to Code Review
+      - name: Move linked issue to Code Review / PR
         if: ${{ env.PROJECT_TOKEN != '' }}
         uses: actions/github-script@v7
         with:
@@ -117,7 +125,7 @@ jobs:
                   }
                 }`, {
                   p: process.env.PROJECT_ID, i: item.id, f: process.env.STATUS_FIELD_ID,
-                  v: { singleSelectOptionId: process.env.STATUS_CODE_REVIEW }
+                  v: { singleSelectOptionId: process.env.STATUS_CODE_REVIEW_PR }
                 });
             };
 
@@ -125,24 +133,24 @@ jobs:
               for (const n of linkedIssues) {
                 const { data: issue } = await github.rest.issues.get({ owner, repo, issue_number: n });
                 await moveItem(issue.node_id);
-                console.log(`Issue #${n} → Code Review`);
+                console.log(`Issue #${n} → Code Review / PR`);
               }
             } else {
               await moveItem(pr.node_id);
-              console.log(`PR #${prNumber} → Code Review (no linked issue)`);
+              console.log(`PR #${prNumber} → Code Review / PR (no linked issue)`);
             }
 
-            await github.rest.issues.addLabels({ owner, repo, issue_number: prNumber, labels: ['pr:review'] }).catch(() => {});
+            await github.rest.issues.addLabels({ owner, repo, issue_number: prNumber, labels: ['pr:in-review'] }).catch(() => {});
 
-  # Review Approved → Pull Request
+  # Review Approved → Add Label
   move-card-on-review-approved:
-    name: Approved PR → Pull Request
+    name: Approved PR → Add Label
     if: github.event_name == 'pull_request_review' && github.event.review.state == 'approved'
     runs-on: ubuntu-latest
     env:
       PROJECT_TOKEN: ${{ secrets.PROJECT_TOKEN }}
     steps:
-      - name: Move issue to Pull Request
+      - name: Swap PR labels
         if: ${{ env.PROJECT_TOKEN != '' }}
         uses: actions/github-script@v7
         with:
@@ -150,34 +158,7 @@ jobs:
           script: |
             const prNumber = context.payload.pull_request.number;
             const { owner, repo } = context.repo;
-            const { data: pr } = await github.rest.pulls.get({ owner, repo, pull_number: prNumber });
-            const body = pr.body ?? '';
-            const linkedIssues = [...body.matchAll(/(?:Closes?|Fixes?|Resolves?)\s+#(\d+)/gi)].map(m => parseInt(m[1]));
-
-            const moveItem = async (nodeId) => {
-              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_PULL_REQUEST } });
-            };
-
-            if (linkedIssues.length > 0) {
-              for (const n of linkedIssues) {
-                const { data: issue } = await github.rest.issues.get({ owner, repo, issue_number: n });
-                await moveItem(issue.node_id);
-              }
-            } else {
-              await moveItem(pr.node_id);
-            }
-
-            try { await github.rest.issues.removeLabel({ owner, repo, issue_number: prNumber, name: 'pr:review' }); } catch {}
+            try { await github.rest.issues.removeLabel({ owner, repo, issue_number: prNumber, name: 'pr:in-review' }); } catch {}
             await github.rest.issues.addLabels({ owner, repo, issue_number: prNumber, labels: ['pr:approved'] }).catch(() => {});
 
   # PR Merged → Production
@@ -211,7 +192,7 @@ jobs:
                     projectV2Item { id }
                   }
                 }`, { p: process.env.PROJECT_ID, i: item.id, f: process.env.STATUS_FIELD_ID,
-                      v: { singleSelectOptionId: process.env.STATUS_PRODUCAO } });
+                      v: { singleSelectOptionId: process.env.STATUS_PRODUCTION } });
             };
 
             if (linkedIssues.length > 0) {

package/templates/.github/workflows/upstream-gate.yml

@@ -0,0 +1,54 @@
+name: Upstream Gate 1
+
+on:
+  issue_comment:
+    types: [created]
+
+jobs:
+  evaluate-gate:
+    name: Evaluate Brainstorming Approval
+    if: ${{ !github.event.issue.pull_request && contains(github.event.issue.labels.*.name, 'upstream:brainstorming') }}
+    runs-on: ubuntu-latest
+    env:
+      PROJECT_TOKEN: ${{ secrets.PROJECT_TOKEN }}
+    steps:
+      - name: Check for approval and swap label
+        if: ${{ env.PROJECT_TOKEN != '' }}
+        uses: actions/github-script@v7
+        with:
+          github-token: ${{ env.PROJECT_TOKEN }}
+          script: |
+            const comment = context.payload.comment.body.toLowerCase();
+            const isApproved = 
+              comment.includes('approved') || 
+              comment.includes('lgtm') || 
+              /option\s+[a-z0-9]/i.test(comment) ||
+              /go\s+with\s+[a-z0-9]/i.test(comment) ||
+              /proceed/i.test(comment);
+
+            if (isApproved) {
+              const { owner, repo } = context.repo;
+              const issue_number = context.payload.issue.number;
+
+              console.log('Approval detected, swapping labels...');
+
+              try {
+                await github.rest.issues.removeLabel({
+                  owner,
+                  repo,
+                  issue_number,
+                  name: 'upstream:brainstorming'
+                });
+              } catch (e) {
+                console.log('Could not remove upstream:brainstorming label');
+              }
+
+              await github.rest.issues.addLabels({
+                owner,
+                repo,
+                issue_number,
+                labels: ['upstream:detailing']
+              });
+            } else {
+              console.log('No approval pattern detected in the comment.');
+            }

package/templates/AGENTS.md

@@ -35,7 +35,33 @@ Always start from the current `main` HEAD. Never work over stale snapshots.
 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. Create a Pull Request with `Closes #N` in the body — automation moves the board.
+6. Run typecheck (if applicable): `{{TYPECHECK_COMMAND}}`
+7. Create a Pull Request with `Closes #N` in the body — automation moves the board.
+
+### Spec format (Upstream Agents)
+
+When detailing a solution in an issue body, you must **always** include both the user story and the acceptance criteria. Never append only the ACs to an existing text; rewrite the full issue body in this standard format:
+
+```
+**As** [user],
+**I want** [action],
+**so that** [benefit].
+
+---
+
+## Acceptance Criteria
+
+**AC1 — ...**
+- Given ...
+- When ...
+- Then ...
+
+**AC2 — ...**
+...
+
+## Files to modify
+- `path/to/file.ts` — what changes
+```
 
 ## What NOT to do
 
@@ -49,5 +75,6 @@ Always start from the current `main` HEAD. Never work over stale snapshots.
 
 - **Tests:** `{{TEST_COMMAND}}`
 - **Lint/Types:** `{{LINT_COMMAND}}`
+- **Typecheck:** `{{TYPECHECK_COMMAND}}`
 - **Build:** `{{BUILD_COMMAND}}`
 {{EXTRA_PATTERNS}}

package/templates/docs/pdlc.md

@@ -4,20 +4,20 @@
 
 | Column | Meaning | Who moves the card |
 |---|---|---|
-| 💡 Idea | Backlog — every new issue lands here | Claude Code / Manual |
-| 🔍 Exploration | Claude is analyzing code and context | Claude Code |
-| 🧠 Brainstorming | Claude proposed approaches, awaiting PM gate | Claude Code |
-| 📐 Detail Solution | Claude is writing the technical spec | Claude Code |
-| ✅ Approval | Spec ready, awaiting `spec:approved` label | Claude Code |
-| ⚙️ Development | Agent implementing the spec | Jules / Implementation Agent |
+| 💡 Idea | Backlog — every new issue lands here | Manual |
+| 🔍 Exploration | Claude is analyzing code and context | Label `stage:exploration` |
+| 🧠 Brainstorming | Claude proposed approaches, awaiting PM gate | Label `stage:brainstorming` |
+| 📐 Detail Solution | Claude is writing the technical spec | Label `stage:detailing` |
+| ✅ Approval | Spec ready, awaiting `spec:approved` label | Label `spec:approved` |
+| ⚙️ Development | Agent implementing the spec | Label `stage:development` |
 | 🧪 Testing | CI pipeline running | GitHub Actions |
-| 👁 Code Review | PR opened, awaiting human review | GitHub Actions |
-| 🔀 Pull Request | PR approved, awaiting merge | GitHub Actions |
+| 👁 Code Review / PR | PR opened, awaiting human review | GitHub Actions |
+| 🔀 Merge | PR approved, awaiting merge | GitHub Actions |
 | 🚀 Production | Merged | GitHub Actions |
 
 <!--
 Adapt columns as needed. The functional baseline is:
-💡 Idea → ⚙️ Development → 👁 Code Review → 🚀 Production
+💡 Idea → ⚙️ Development → 👁 Code Review / PR → 🚀 Production
 -->
 
 ## Board Identifiers (GitHub Projects)
@@ -39,8 +39,8 @@ REPO         = {{REPO_OWNER}}/{{REPO_NAME}}
 | ✅ Approval | `{{ID_APPROVAL}}` |
 | ⚙️ Development | `{{ID_DEVELOPMENT}}` |
 | 🧪 Testing | `{{ID_TESTING}}` |
-| 👁 Code Review | `{{ID_CODE_REVIEW}}` |
-| 🔀 Pull Request | `{{ID_PULL_REQUEST}}` |
+| 👁 Code Review / PR | `{{ID_CODE_REVIEW_PR}}` |
+| 🔀 Merge | `{{ID_MERGE}}` |
 | 🚀 Production | `{{ID_PRODUCTION}}` |
 
 ## Agent × Phase Mapping
@@ -49,7 +49,7 @@ REPO         = {{REPO_OWNER}}/{{REPO_NAME}}
 |---|---|
 | 💡 → 📐 (upstream) | Claude (or ideation agent) in conversational session |
 | ⚙️ → 🔀 (downstream) | {{IMPLEMENTATION_AGENT}} (e.g. Jules `@google-labs-jules`) |
-| 👁 Code Review | Human (you) |
+| 👁 Code Review / PR | Human (you) |
 | Automatic transitions | GitHub Actions |
 
 ## Issue Title Conventions
@@ -67,8 +67,12 @@ REPO         = {{REPO_OWNER}}/{{REPO_NAME}}
 
 | Label | Entity | Color | Meaning |
 |---|---|---|---|
+| `stage:exploration` | Issue | Purple | Issue is being evaluated |
+| `stage:brainstorming` | Issue | Pink | Proposed approaches awaiting PM gate |
+| `stage:detailing` | Issue | Blue | Technical spec is being written |
+| `stage:development` | Issue | Orange | Agent is implementing the spec |
 | `spec:approved` | Issue | Green | Gate 2 — agent is cleared to implement |
-| `pr:review` | PR | Yellow | Awaiting code review |
+| `pr:in-review` | PR | Yellow | Awaiting code review |
 | `pr:approved` | PR | Green | Code review approved |
 
 ## Approval Gates