create-agentic-pdlc 1.2.1 → 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/.github/assets/agentic-pdlc-flow.svg

@@ -0,0 +1,255 @@
+<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 1000 450" width="100%" height="100%">
+  <defs>
+    <style>
+      :root {
+        --bg-color: transparent;
+        --card-bg: #ffffff;
+        --card-border: #e2e8f0;
+        --text-main: #0f172a;
+        --text-muted: #64748b;
+        --accent-blue: #3b82f6;
+        --accent-purple: #8b5cf6;
+        --accent-green: #10b981;
+        --glow-blue: rgba(59, 130, 246, 0.15);
+        --glow-purple: rgba(139, 92, 246, 0.15);
+      }
+
+      @media (prefers-color-scheme: dark) {
+        :root {
+          --card-bg: #0d1117;
+          --card-border: #30363d;
+          --text-main: #e6edf3;
+          --text-muted: #848d97;
+          --accent-blue: #58a6ff;
+          --accent-purple: #bc8cff;
+          --accent-green: #238636;
+          --glow-blue: rgba(88, 166, 255, 0.2);
+          --glow-purple: rgba(188, 140, 255, 0.2);
+        }
+      }
+
+      body { background-color: var(--bg-color); }
+      
+      .card { fill: var(--card-bg); stroke: var(--card-border); stroke-width: 2; rx: 16; }
+      .card-glow-left { fill: var(--glow-blue); filter: blur(40px); rx: 16; }
+      .card-glow-right { fill: var(--glow-purple); filter: blur(40px); rx: 16; }
+      
+      .text-title { fill: var(--text-main); font-family: -apple-system, BlinkMacSystemFont, "Segoe UI", Roboto, sans-serif; font-size: 26px; font-weight: 800; letter-spacing: -0.5px; }
+      .text-subtitle { fill: var(--text-muted); font-family: -apple-system, BlinkMacSystemFont, "Segoe UI", Roboto, sans-serif; font-size: 16px; font-weight: 500; }
+      .text-label { fill: var(--text-main); font-family: -apple-system, BlinkMacSystemFont, "Segoe UI", Roboto, sans-serif; font-size: 14px; font-weight: 600; }
+      
+      .icon-container { fill: var(--card-bg); stroke: var(--card-border); stroke-width: 2; rx: 12; }
+      
+      .path-line { stroke: url(#gradientLine); stroke-width: 4; stroke-linecap: round; stroke-linejoin: round; fill: none; stroke-dasharray: 8 8; animation: dashMove 15s linear infinite; }
+      .path-glow { stroke: url(#gradientLine); stroke-width: 12; stroke-linecap: round; stroke-linejoin: round; fill: none; opacity: 0.3; filter: blur(8px); }
+      .path-interaction { stroke: var(--text-muted); stroke-width: 2; stroke-linecap: round; fill: none; stroke-dasharray: 4 4; opacity: 0.5; animation: dashMove 20s linear infinite reverse; }
+
+      .badge-bg { fill: var(--card-bg); stroke: var(--accent-blue); stroke-width: 2; rx: 17; }
+      .badge-text { fill: var(--accent-blue); font-family: "JetBrains Mono", ui-monospace, SFMono-Regular, Menlo, Monaco, Consolas, monospace; font-size: 15px; font-weight: 700; }
+      
+      .pr-badge-bg { fill: var(--accent-green); rx: 8; }
+      .pr-badge-text { fill: #ffffff; font-family: -apple-system, BlinkMacSystemFont, "Segoe UI", Roboto, sans-serif; font-size: 15px; font-weight: 700; }
+
+      .pulse { animation: pulse 2s infinite; }
+      .pulse-slow { animation: pulse 4s infinite; }
+      
+      @keyframes dashMove {
+        from { stroke-dashoffset: 1000; }
+        to { stroke-dashoffset: 0; }
+      }
+      
+      @keyframes pulse {
+        0% { filter: drop-shadow(0 0 4px var(--accent-green)); }
+        50% { filter: drop-shadow(0 0 12px var(--accent-green)); }
+        100% { filter: drop-shadow(0 0 4px var(--accent-green)); }
+      }
+
+      /* Gear Animation */
+      .gear { transform-origin: 0px 0px; animation: spin 8s linear infinite; }
+      .gear-reverse { transform-origin: 0px 0px; animation: spin-reverse 8s linear infinite; }
+      @keyframes spin { 100% { transform: rotate(360deg); } }
+      @keyframes spin-reverse { 100% { transform: rotate(-360deg); } }
+
+      /* Blinking Cursor and Typing */
+      @keyframes blink { 0%, 49% { opacity: 1; } 50%, 100% { opacity: 0; } }
+      .blinking-cursor { animation: blink 1s infinite; }
+      
+      @keyframes typeEffect {
+        0%, 10% { opacity: 0; transform: translateY(5px); }
+        20%, 80% { opacity: 1; transform: translateY(0); }
+        90%, 100% { opacity: 0; transform: translateY(-5px); }
+      }
+      .code-line-1 { animation: typeEffect 6s infinite; }
+      .code-line-2 { animation: typeEffect 6s infinite 0.5s; }
+      .code-line-3 { animation: typeEffect 6s infinite 1s; }
+
+      /* Conceiving Spec:Approved Badge Animation */
+      @keyframes conceive {
+        0% { transform: translate(-300px, 0px) scale(0.5); opacity: 0; }
+        15% { transform: translate(-100px, 10px) scale(0.8); opacity: 1; }
+        30%, 70% { transform: translate(0px, 0px) scale(1); opacity: 1; filter: drop-shadow(0 0 15px var(--accent-blue)); }
+        85% { transform: translate(150px, -10px) scale(0.8); opacity: 1; }
+        100% { transform: translate(300px, -20px) scale(0.5); opacity: 0; }
+      }
+      .conceive-badge { animation: conceive 8s ease-in-out infinite; }
+      
+      /* Orb traversing from human to AIs */
+      @keyframes dataFlow {
+        0% { transform: translate(0,0); opacity: 0; }
+        10% { opacity: 1; }
+        90% { opacity: 1; }
+        100% { transform: translate(120px, 0); opacity: 0; }
+      }
+    </style>
+    
+    <linearGradient id="gradientLine" x1="0%" y1="0%" x2="100%" y2="0%">
+      <stop offset="0%" stop-color="var(--accent-blue)" />
+      <stop offset="100%" stop-color="var(--accent-purple)" />
+    </linearGradient>
+
+    <!-- 3D Human Gradients -->
+    <radialGradient id="headGrad" cx="35%" cy="35%" r="65%">
+      <stop offset="0%" stop-color="#e2e8f0" />
+      <stop offset="100%" stop-color="#475569" />
+    </radialGradient>
+    <linearGradient id="bodyGrad" x1="0%" y1="0%" x2="0%" y2="100%">
+      <stop offset="0%" stop-color="#cbd5e1" />
+      <stop offset="100%" stop-color="#334155" />
+    </linearGradient>
+  </defs>
+
+  <!-- Left Block: Upstream -->
+  <g transform="translate(50, 70)">
+    <rect class="card-glow-left" x="0" y="0" width="360" height="320" />
+    <rect class="card" x="0" y="0" width="360" height="320" />
+    
+    <text class="text-title" x="180" y="50" text-anchor="middle">🌊 Upstream</text>
+    <text class="text-subtitle" x="180" y="75" text-anchor="middle">Idea → Specification</text>
+
+    <!-- Human Icon (3D Style) -->
+    <g transform="translate(60, 110)">
+      <rect class="icon-container" x="0" y="0" width="80" height="80" />
+      
+      <!-- 3D Human Silhouette -->
+      <circle cx="40" cy="28" r="14" fill="url(#headGrad)" />
+      <path d="M40 48 C18 48, 12 70, 12 80 L68 80 C68 70, 62 48, 40 48 Z" fill="url(#bodyGrad)" />
+      
+      <text class="text-label" x="40" y="110" text-anchor="middle">Human / PM</text>
+    </g>
+
+    <!-- Interaction Animations -->
+    <!-- Human to AGENTS.md -->
+    <path class="path-interaction" d="M 100 190 Q 140 220 180 240" />
+    <!-- AIs to AGENTS.md -->
+    <path class="path-interaction" d="M 260 190 Q 220 220 180 240" />
+    <!-- Human to AIs (Collaboration) -->
+    <path class="path-interaction" d="M 140 150 L 220 150" />
+    
+    <!-- Floating Data Orb between Human and AIs -->
+    <circle cx="140" cy="150" r="4" fill="var(--accent-blue)" filter="blur(1px)">
+      <animate attributeName="cx" values="140; 220; 140" dur="4s" repeatCount="indefinite" />
+    </circle>
+
+    <!-- AI Assistants Group -->
+    <g transform="translate(220, 110)">
+      <rect class="icon-container" x="0" y="0" width="80" height="80" />
+      
+      <!-- Claude-like Asterisk/Brain -->
+      <g transform="translate(20, 20) scale(0.6)">
+        <path d="M20 5 L20 35 M5 20 L35 20 M10 10 L30 30 M10 30 L30 10" style="stroke: #d97757; stroke-width: 6; stroke-linecap: round;" />
+      </g>
+      
+      <!-- Cursor-like Pointer -->
+      <g transform="translate(45, 20) scale(0.7)">
+        <path d="M5 5 L15 35 L20 20 L35 15 Z" style="fill: var(--accent-blue); stroke: var(--accent-blue); stroke-width: 2; stroke-linejoin: round;" />
+      </g>
+      
+      <!-- Copilot-like Hexagon/Wings -->
+      <g transform="translate(32, 45) scale(0.6)">
+        <path d="M10 25 C 10 10, 30 10, 30 25 C 30 35, 20 40, 20 40 C 20 40, 10 35, 10 25 Z M 5 20 L 10 25 M 35 20 L 30 25" style="fill: none; stroke: var(--text-main); stroke-width: 4; stroke-linecap: round; stroke-linejoin: round;" />
+      </g>
+
+      <text class="text-label" x="40" y="110" text-anchor="middle">Agnostic AIs</text>
+    </g>
+
+    <!-- The Resulting Spec -->
+    <g transform="translate(100, 240)">
+      <rect x="0" y="0" width="160" height="46" rx="8" style="fill: var(--card-bg); stroke: var(--card-border); stroke-width: 2;" />
+      <path d="M25 15h15M25 23h25M25 31h20M15 15v16" style="stroke: var(--accent-blue); stroke-width: 2; stroke-linecap: round;" />
+      <text class="text-label" x="50" y="28">AGENTS.md</text>
+    </g>
+  </g>
+
+  <!-- The Bridge / Connection -->
+  <g transform="translate(410, 230)">
+    <!-- Animated Path connecting boxes -->
+    <path class="path-glow" d="M 0 0 C 60 0, 120 0, 180 0" />
+    <path class="path-line" d="M 0 0 C 60 0, 120 0, 180 0" />
+    
+    <!-- Floating Spec:Approved Badge that travels from Human to Agent -->
+    <g class="conceive-badge" transform="translate(0, -35)">
+      <rect class="badge-bg" x="0" y="0" width="160" height="34" />
+      <!-- Removed the bullet, centered text perfectly -->
+      <text class="badge-text" x="80" y="22" text-anchor="middle">spec:approved</text>
+    </g>
+  </g>
+
+  <!-- Right Block: Downstream -->
+  <g transform="translate(600, 70)">
+    <rect class="card-glow-right" x="0" y="0" width="360" height="320" />
+    <rect class="card" x="0" y="0" width="360" height="320" />
+    
+    <text class="text-title" x="180" y="50" text-anchor="middle">🏭 Downstream</text>
+    <text class="text-subtitle" x="180" y="75" text-anchor="middle">Spec → Production Code</text>
+
+    <!-- Central Auto Agent Factory Graphic -->
+    <g transform="translate(80, 110)">
+      <!-- Server / Terminal Window representing the AI Workspace -->
+      <rect x="0" y="0" width="200" height="110" rx="6" style="fill: var(--card-bg); stroke: var(--card-border); stroke-width: 3;" />
+      <!-- Terminal Header -->
+      <path d="M0 25 L200 25" style="stroke: var(--card-border); stroke-width: 3;" />
+      <circle cx="15" cy="12.5" r="4" style="fill: #ff5f56;" />
+      <circle cx="30" cy="12.5" r="4" style="fill: #ffbd2e;" />
+      <circle cx="45" cy="12.5" r="4" style="fill: #27c93f;" />
+      
+      <!-- Terminal Code Content with Animation -->
+      <path d="M20 45 L35 60 L20 75" style="stroke: var(--accent-purple); stroke-width: 3; stroke-linecap: round; stroke-linejoin: round; fill: none;" />
+      
+      <!-- Blinking Cursor -->
+      <line x1="45" y1="75" x2="55" y2="75" class="blinking-cursor" style="stroke: var(--text-main); stroke-width: 3; stroke-linecap: round;" />
+      
+      <!-- Animated Code Lines Typing -->
+      <rect class="code-line-1" x="20" y="90" width="60" height="6" rx="3" style="fill: var(--text-muted); opacity: 0.5;" />
+      <rect class="code-line-2" x="85" y="90" width="40" height="6" rx="3" style="fill: var(--accent-blue); opacity: 0.5;" />
+      <rect class="code-line-3" x="20" y="105" width="90" height="6" rx="3" style="fill: var(--text-muted); opacity: 0.5;" />
+      
+      <!-- Gears processing the code -->
+      <g transform="translate(150, 65)">
+        <g class="gear">
+          <circle cx="0" cy="0" r="16" style="fill: none; stroke: var(--text-muted); stroke-width: 4; stroke-dasharray: 6 4;" />
+          <circle cx="0" cy="0" r="6" style="fill: var(--text-muted);" />
+        </g>
+        <g class="gear-reverse" transform="translate(-18, 22) scale(0.7)">
+          <circle cx="0" cy="0" r="16" style="fill: none; stroke: var(--accent-purple); stroke-width: 4; stroke-dasharray: 6 4;" />
+          <circle cx="0" cy="0" r="6" style="fill: var(--accent-purple);" />
+        </g>
+      </g>
+    </g>
+
+    <!-- Result: Pull Request Badge -->
+    <g transform="translate(100, 240)" class="pulse">
+      <rect class="pr-badge-bg" x="0" y="0" width="160" height="46" />
+      
+      <!-- PR Icon (GitHub style) -->
+      <g transform="translate(15, 13) scale(1.2)" style="fill: none; stroke: #ffffff; stroke-width: 2; stroke-linecap: round; stroke-linejoin: round;">
+        <circle cx="4" cy="4" r="2" />
+        <circle cx="4" cy="14" r="2" />
+        <circle cx="14" cy="4" r="2" />
+        <path d="M4 6 v6" />
+        <path d="M14 6 v2 c0 2 -2 2 -2 2 h-4 c0 0 -2 0 -2 2 v2" />
+      </g>
+      
+      <text class="pr-badge-text" x="45" y="28">Pull Request</text>
+    </g>
+  </g>
+</svg>

package/.github/workflows/agent-trigger.yml

@@ -12,8 +12,41 @@ jobs:
     # 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 }}
     steps:
-      - name: Comment on issue to trigger agent
+      - name: Update Labels
+        if: ${{ env.PROJECT_TOKEN != '' }}
+        uses: actions/github-script@v7
+        with:
+          github-token: ${{ env.PROJECT_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: 'upstream:approval'
+              });
+            } catch (error) {
+              console.log('Label upstream:approval not found or could not be removed');
+            }
+            
+            await github.rest.issues.addLabels({
+              owner,
+              repo,
+              issue_number,
+              labels: ['upstream:development', '{{IMPLEMENTATION_AGENT_LABEL}}', 'agent:working']
+            });
+
+      - name: Comment on issue to trigger agent and prevent race conditions
         uses: actions/github-script@v7
         with:
           github-token: ${{ secrets.GITHUB_TOKEN }}
@@ -22,6 +55,8 @@ jobs:
             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:**',
@@ -48,6 +83,10 @@ jobs:
     # 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
         uses: actions/github-script@v7

package/.github/workflows/ci.yml

@@ -22,6 +22,9 @@ jobs:
       - name: Run Linters
         run: echo "No tests/build needed."
 
+      - name: Typecheck
+        run: echo "No typecheck needed."
+
       - name: Build
         run: echo "No tests/build needed."
 

package/.github/workflows/pdlc-health-check.yml

@@ -0,0 +1,123 @@
+name: PDLC Health Check (Drift Detection)
+
+on:
+  workflow_dispatch:
+  schedule:
+    - cron: '0 8 * * 1' # Every Monday at 8am
+
+env:
+  PROJECT_ID: "{{PROJECT_ID}}"
+  STATUS_FIELD_ID: "{{STATUS_FIELD_ID}}"
+  STATUS_EXPLORATION: "{{ID_EXPLORATION}}"
+  STATUS_BRAINSTORMING: "{{ID_BRAINSTORMING}}"
+  STATUS_DETAILING: "{{ID_DETAILING}}"
+  STATUS_APPROVAL: "{{ID_APPROVAL}}"
+  STATUS_DEVELOPMENT: "{{ID_DEVELOPMENT}}"
+  STATUS_TESTING: "{{ID_TESTING}}"
+  STATUS_CODE_REVIEW_PR: "{{ID_CODE_REVIEW_PR}}"
+  STATUS_PRODUCTION: "{{ID_PRODUCTION}}"
+
+jobs:
+  check-drift:
+    name: Detect Project Board Drift
+    runs-on: ubuntu-latest
+    env:
+      PROJECT_TOKEN: ${{ secrets.PROJECT_TOKEN }}
+    permissions:
+      issues: write
+    steps:
+      - name: Validate Board Configuration
+        if: ${{ env.PROJECT_TOKEN != '' && env.PROJECT_ID != '{{PROJECT_ID}}' }}
+        uses: actions/github-script@v7
+        with:
+          github-token: ${{ env.PROJECT_TOKEN }}
+          script: |
+            const projectId = process.env.PROJECT_ID;
+            const statusFieldId = process.env.STATUS_FIELD_ID;
+            const envVars = {
+              'STATUS_EXPLORATION': process.env.STATUS_EXPLORATION,
+              'STATUS_BRAINSTORMING': process.env.STATUS_BRAINSTORMING,
+              'STATUS_DETAILING': process.env.STATUS_DETAILING,
+              'STATUS_APPROVAL': process.env.STATUS_APPROVAL,
+              'STATUS_DEVELOPMENT': process.env.STATUS_DEVELOPMENT,
+              'STATUS_TESTING': process.env.STATUS_TESTING,
+              'STATUS_CODE_REVIEW_PR': process.env.STATUS_CODE_REVIEW_PR,
+              'STATUS_PRODUCTION': process.env.STATUS_PRODUCTION
+            };
+
+            const query = `
+              query($projectId: ID!) {
+                node(id: $projectId) {
+                  ... on ProjectV2 {
+                    title
+                    fields(first: 20) {
+                      nodes {
+                        ... on ProjectV2SingleSelectField {
+                          id
+                          name
+                          options {
+                            id
+                            name
+                          }
+                        }
+                      }
+                    }
+                  }
+                }
+              }
+            `;
+
+            let result;
+            try {
+              result = await github.graphql(query, { projectId });
+            } catch (error) {
+              console.log("❌ Error fetching project. Verify your PROJECT_ID.");
+              console.log(error);
+              return;
+            }
+
+            const project = result.node;
+            if (!project) {
+              console.log("❌ Project not found.");
+              return;
+            }
+
+            const statusField = project.fields.nodes.find(f => f.id === statusFieldId);
+            if (!statusField) {
+              console.log("❌ Status field not found.");
+              return;
+            }
+
+            const validOptions = statusField.options;
+            const validOptionIds = validOptions.map(o => o.id);
+
+            let hasDrift = false;
+            let missingVars = [];
+
+            for (const [varName, id] of Object.entries(envVars)) {
+              if (id && !id.startsWith('{{') && !validOptionIds.includes(id)) {
+                hasDrift = true;
+                missingVars.push(varName);
+              }
+            }
+
+            if (hasDrift) {
+              console.log("🚨 Drift detected! The following mapped columns no longer exist: " + missingVars.join(", "));
+              
+              let table = "| Column Name | New ID |\n|---|---|\n";
+              validOptions.forEach(opt => {
+                table += `| ${opt.name} | \`${opt.id}\` |\n`;
+              });
+
+              const body = `🚨 **Agentic PDLC Drift Detected**\n\nThe following columns mapped in your \`.github/workflows/project-automation.yml\` no longer exist in your project board:\n\n**${missingVars.join(", ")}**\n\n### How to fix it:\nHere is the list of current columns in your board with their valid IDs. Please update the \`env\` block in your \`.github/workflows/project-automation.yml\` and \`.github/workflows/pdlc-health-check.yml\`.\n\n${table}`;
+
+              await github.rest.issues.create({
+                owner: context.repo.owner,
+                repo: context.repo.repo,
+                title: '🚨 Agentic PDLC Drift Detected in Project Board',
+                body: body,
+                labels: ['bug']
+              });
+            } else {
+              console.log("✅ No drift detected. Board configuration is healthy.");
+            }

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

@@ -16,9 +16,9 @@ env:
   STATUS_DETAILING: "{{ID_DETAILING}}"
   STATUS_APPROVAL: "{{ID_APPROVAL}}"
   STATUS_DEVELOPMENT: "{{ID_DEVELOPMENT}}"
+  STATUS_TESTING: "{{ID_TESTING}}"
   STATUS_CODE_REVIEW_PR: "{{ID_CODE_REVIEW_PR}}"
-  STATUS_MERGE: "{{ID_MERGE}}"
-  STATUS_PRODUCAO: "{{ID_PRODUCAO}}"
+  STATUS_PRODUCTION: "{{ID_PRODUCTION}}"
 
 jobs:
   # Issue Labeled → Move Upstream
@@ -39,21 +39,24 @@ jobs:
             let targetStatusId = null;
             let stageName = null;
 
-            if (labelName === 'stage:exploration') {
+            if (labelName === 'upstream:exploration') {
               targetStatusId = process.env.STATUS_EXPLORATION;
               stageName = 'Exploration';
-            } else if (labelName === 'stage:brainstorming') {
+            } else if (labelName === 'upstream:brainstorming') {
               targetStatusId = process.env.STATUS_BRAINSTORMING;
               stageName = 'Brainstorming';
-            } else if (labelName === 'stage:detailing') {
+            } else if (labelName === 'upstream:detailing') {
               targetStatusId = process.env.STATUS_DETAILING;
               stageName = 'Detailing';
-            } else if (labelName === 'spec:approved') {
+            } else if (labelName === 'upstream:approval') {
               targetStatusId = process.env.STATUS_APPROVAL;
               stageName = 'Approval';
-            } else if (labelName === 'stage:development') {
+            } 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) {
@@ -83,6 +86,7 @@ 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
   move-card-on-pr-open:
@@ -136,17 +140,17 @@ jobs:
               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 → Merge
+  # Review Approved → Add Label
   move-card-on-review-approved:
-    name: Approved PR → Merge
+    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 Merge
+      - name: Swap PR labels
         if: ${{ env.PROJECT_TOKEN != '' }}
         uses: actions/github-script@v7
         with:
@@ -154,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_MERGE } });
-            };
-
-            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
@@ -215,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/AGENTS.md

@@ -27,12 +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. 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
 
@@ -46,4 +48,5 @@ Always start from the current `main` HEAD. Never work over stale snapshots.
 
 - **Tests:** `echo "No tests/build needed."`
 - **Lint/Types:** `echo "No tests/build needed."`
+- **Typecheck:** `echo "No typecheck needed."`
 - **Build:** `echo "No tests/build needed."`

package/README.md

@@ -3,20 +3,24 @@
 [![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
 [![PRs Welcome](https://img.shields.io/badge/PRs-welcome-brightgreen.svg?style=flat-square)](http://makeapullrequest.com)
 
-> **Supercharge your solo development with a fully automated, AI-native Product Development Life Cycle (PDLC).**
+> **Stop fighting your AI agents. Give them structure.**
 
-Building software with AI agents is the future, but raw context windows aren't enough. Without structure, agents lose track, write inconsistent code, and break invariants. 
+**Agentic PDLC** is a lightweight, zero-dependency boilerplate that transforms chaotic AI coding into a deterministic, automated software assembly line.
 
-The **Agentic PDLC Framework** is a lightweight, universal boilerplate that standardizes how your AI assistants (Claude, Cursor, Copilot, etc.) interpret tasks, respect your project's rules, and collaborate seamlessly from an idea to production.
+It standardizes how your AI assistants (Claude, Cursor, Copilot, Jules) interpret tasks, respect invariants, and collaborate seamlessly from an idea to production.
+
+<div align="center">
+  <img src=".github/assets/agentic-pdlc-flow.svg" alt="Agentic PDLC Architecture Flow" width="100%">
+</div>
 
 ---
 
-## 🌟 Why use this framework?
+## ⚡ Why you need this
 
-- 🧠 **Contextual Perfection**: Gives every AI agent a single "source of truth" to abide by (`AGENTS.md`), preventing hallucinated dependencies or broken architectural rules.
-- 🔄 **Automated Handoffs**: Built-in GitHub Actions automate the flow between brainstorming an idea and having an autonomous agent implement it.
-- ⚡ **Multi-Assistant Support**: Works flawlessly whether you use Claude Code in the terminal, Cursor as your IDE, or autonomous sweeper agents.
-- 🛠️ **Setup in Seconds**: Our interactive "Setup Mode" can scaffold your entire product context dynamically!
+- 🧠 **One Contract to Rule Them All**: `AGENTS.md` is your single source of truth. Stop repeating yourself; let every AI read the same invariants.
+- 🤖 **Automated Handoffs**: Move cards across your GitHub board with labels. Brainstorm with Claude upstream, let Jules code downstream.
+- 🚀 **Interactive Setup**: Run one `npx` command and let your favorite AI assistant scaffold the framework into your project interactively.
+- 📈 **Maturity Model**: A clear path from structured (Level 1) to semi-autonomous (Level 3) development. [Read the Agentic Maturity Model](docs/maturity-model.md).
 
 ---