create-agentic-pdlc 1.0.0

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

@@ -0,0 +1,77 @@
+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
+    steps:
+      - name: Comment on issue to trigger agent
+        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 = [
+              `{{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
+    steps:
+      - name: Comment on issue to trigger agent
+        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,
+            });

package/.github/workflows/ci.yml

@@ -0,0 +1,29 @@
+name: Sentinel / CI
+
+on:
+  pull_request:
+    branches: [ main ]
+  push:
+    branches: [ main ]
+
+jobs:
+  validate:
+    name: Run tests and linters
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Setup environment
+        run: echo "Replace this with your language/toolchain setup (e.g., actions/setup-node)"
+        
+      - name: Install dependencies
+        run: echo "Replace this with your package manager install command"
+
+      - name: Run Linters
+        run: echo "No tests/build needed."
+
+      - name: Build
+        run: echo "No tests/build needed."
+
+      - name: Run Tests
+        run: echo "No tests/build needed."

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

@@ -0,0 +1,150 @@
+name: PDLC Board Automation
+
+on:
+  pull_request:
+    types: [opened, reopened, closed]
+  pull_request_review:
+    types: [submitted]
+
+env:
+  PROJECT_ID: "{{PROJECT_ID}}"
+  STATUS_FIELD_ID: "{{STATUS_FIELD_ID}}"
+  STATUS_CODE_REVIEW: "{{ID_CODE_REVIEW}}"
+  STATUS_PULL_REQUEST: "{{ID_PULL_REQUEST}}"
+  STATUS_PRODUCAO: "{{ID_PRODUCAO}}"
+
+jobs:
+  # PR Opened → Move linked issue to Code Review
+  move-card-on-pr-open:
+    name: Open PR → Code Review
+    if: github.event_name == 'pull_request' && (github.event.action == 'opened' || github.event.action == 'reopened')
+    runs-on: ubuntu-latest
+    steps:
+      - name: Move linked issue to Code Review
+        uses: actions/github-script@v7
+        with:
+          github-token: ${{ secrets.PROJECT_TOKEN }}
+          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 ?? '';
+
+            // Extract issues linked via "Closes #N", "Fixes #N", "Resolves #N"
+            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_CODE_REVIEW }
+                });
+            };
+
+            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);
+                console.log(`Issue #${n} → Code Review`);
+              }
+            } else {
+              await moveItem(pr.node_id);
+              console.log(`PR #${prNumber} → Code Review (no linked issue)`);
+            }
+
+            await github.rest.issues.addLabels({ owner, repo, issue_number: prNumber, labels: ['pr:review'] }).catch(() => {});
+
+  # Review Approved → Pull Request
+  move-card-on-review-approved:
+    name: Approved PR → Pull Request
+    if: github.event_name == 'pull_request_review' && github.event.review.state == 'approved'
+    runs-on: ubuntu-latest
+    steps:
+      - name: Move issue to Pull Request
+        uses: actions/github-script@v7
+        with:
+          github-token: ${{ secrets.PROJECT_TOKEN }}
+          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 {}
+            await github.rest.issues.addLabels({ owner, repo, issue_number: prNumber, labels: ['pr:approved'] }).catch(() => {});
+
+  # PR Merged → Production
+  move-card-on-pr-merge:
+    name: Merged PR → Production
+    if: github.event_name == 'pull_request' && github.event.action == 'closed' && github.event.pull_request.merged == true
+    runs-on: ubuntu-latest
+    steps:
+      - name: Move issue to Production
+        uses: actions/github-script@v7
+        with:
+          github-token: ${{ secrets.PROJECT_TOKEN }}
+          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_PRODUCAO } });
+            };
+
+            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);
+                console.log(`Issue #${n} → Production`);
+              }
+            } else {
+              await moveItem(pr.node_id);
+            }

package/AGENTS.md

@@ -0,0 +1,48 @@
+# agentic-pdlc — AI Agent Instructions
+
+This template is the contract between the project and any external AI agent 
+(Claude Code, Cursor, Copilot, Jules, Codex, Sweep, etc.). Read this before committing any change.
+
+## Project Overview
+
+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.
+
+**Structure:**
+Markdown documentation and GitHub Actions YAMLs.
+
+## Before Any Change
+
+```bash
+git fetch origin && git checkout main && git pull
+```
+
+Always start from the current `main` HEAD. Never work over stale snapshots.
+
+## Invariants / Non-negotiable business rules
+
+1. **Keep it Lightweight & Universal**: Never introduce complex scripts (Node, Python, Bash) if a simple Markdown instruction or standard GitHub Action step suffices. The framework must remain easy for solo developers to adopt regardless of their tech stack.
+2. **Template Purity**: Never remove `{{SCREAMING_SNAKE_CASE}}` placeholders from the files inside the `templates/` folder. They must remain intact for the Setup Mode replacement logic to work.
+3. **No Placeholders in Root**: Conversely, files in the root (like `README.md` or `SETUP.md`) are for human readers on GitHub. Never leave unreplaced template variables in root documents.
+
+## Mandatory Workflow
+
+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.
+
+## What NOT to do
+
+- Never commit directly to `main`.
+- Never open a PR without passing the tests.
+- Never implement beyond the immediate scope of the issue.
+- Never create future-proofing abstractions for hypothetical features.
+
+
+## Project Standards
+
+- **Tests:** `echo "No tests/build needed."`
+- **Lint/Types:** `echo "No tests/build needed."`
+- **Build:** `echo "No tests/build needed."`

package/CONTRIBUTING.md

@@ -0,0 +1,18 @@
+# Contributing to Agentic PDLC
+
+First of all, thank you for considering contributing! We want to make the Agentic PDLC framework as seamless as possible across an ever-expanding multitude of AI coding environments.
+
+## How to Contribute
+
+We welcome discussions, issues, and Pull Requests that directly help refine the interactions between developers and implementation agents. You can contribute by:
+
+- **Reporting issues:** Let us know if a workflow or AI adapter is hallucinating or missing instructions.
+- **Improving templates:** Fix grammatical errors or propose enhancements that make agent context more robust without polluting the prompt window.
+- **Adding new adapters:** The AI space moves fast. If a new powerful AI agent emerges that requires specific adapter mechanisms, we'd love to see support for it. Keep it lean and ensure it leverages the universal `AGENTS.md`.
+
+## Submitting Pull Requests
+
+1. Fork the repository.
+2. Create a specific branch for your changes.
+3. Make your commits clear and atomic. 
+4. Open a Pull Request pointing to `main`. Ensure your PR description spells out exactly why the change improves the agentic experience.

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Rafael Costa
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,84 @@
+# 🤖 Agentic PDLC Framework
+
+[![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).**
+
+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. 
+
+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.
+
+---
+
+## 🌟 Why use this framework?
+
+- 🧠 **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!
+
+---
+
+## 🏗️ How It Works: The Two Scopes
+
+The Agentic PDLC bridges the gap between high-level human ideas and deterministic AI execution. It splits the workflow into two clear phases:
+
+### 🌊 1. Upstream (Idea → Spec)
+You use conversational AI (e.g., **Claude Code**, **Cursor Chat**) as your brainstorming partner. Together, you flesh out user stories, acceptance criteria, and technical specifications until they are rock solid.
+
+### 🏭 2. Downstream (Spec → Production)
+Once the spec is approved, autonomous implementation agents (e.g., **Jules**, **Sweep**, **Copilot Workspace**) pick up the task via an automated GitHub Project board flow. They execute the deterministic specs while being strictly governed by your project's invariants.
+
+---
+
+## 🤝 Universal Multi-Assistant Support
+
+The framework relies on a universal source of truth (`AGENTS.md`), but uses elegant adapters to teach specific AI platforms how to read them.
+
+| AI Assistant | Instruction File | How it Integrates |
+|:---|:---|:---|
+| **Claude Code** | `CLAUDE.md` + Claude Skill | Uses `adapters/claude-code/skill.md` *(Includes Auto-Setup Mode)* |
+| **Cursor** | `.cursor/rules/*.md` | Uses `adapters/cursor/rules.md` |
+| **GitHub Copilot** | `.github/copilot-instructions.md` | Uses `templates/.github/copilot-instructions.md` |
+| **Codex / Antigravity** | `AGENTS.md` | Reads the contract natively |
+
+*No matter which AI you pair with, they will all share the exact same context.*
+
+---
+
+## 📂 Expected Structure
+
+Once initialized in your project, the framework provides the following layout:
+
+```text
+your-project/
+├── AGENTS.md                          ← The universal contract mapping rules to any AI.
+├── docs/
+│   └── pdlc.md                        ← The PDLC pipeline defining board columns and IDs.
+└── .github/
+    └── workflows/
+        ├── project-automation.yml     ← Automates GitHub Project card movement.
+        ├── agent-trigger.yml          ← Wakes up your agent upon `spec:approved`.
+        └── ci.yml                     ← The Sentinel enforcing invariants and tests.
+```
+
+---
+
+## 🚀 Quick Start
+
+Ready to build at the speed of thought? Scaffold the entire framework interactively without copy-pasting code!
+
+Simply run our installer in the root of your project:
+
+```bash
+npx create-agentic-pdlc
+```
+
+> **💡 How it works:** The CLI acts as a bridge. It asks which AI assistant you prefer (e.g., Claude Code, Cursor), drops the required system instructions into your workspace, and hands control over to your AI. Your AI will then chat with you to customize your framework!
+
+---
+
+## ❤️ Contributing
+
+We welcome improvements from other solo-founders and AI-engineers! Please check our **[Contributing Guidelines](CONTRIBUTING.md)** on how to submit PRs, add new AI platform adapters, or improve the documentation.

package/SETUP.md

@@ -0,0 +1,142 @@
+# Setup Guide — Agentic PDLC Framework
+
+Step-by-step guide to applying the framework to a new project.
+Estimated time: 2-3 hours (including GitHub Projects setup).
+
+---
+
+## Prerequisites
+
+- Target repository on GitHub (Public or GitHub Pro for branch protection)
+- `gh` CLI installed and authenticated
+- GitHub Projects enabled on your account/organization
+- Implementation agent connected to the repository (e.g., Jules: github.com/google-labs/jules)
+
+---
+
+## Step 1 — Create the GitHub Project Board
+
+```bash
+# Create the project
+gh api graphql -f query='
+mutation($owner: ID!, $title: String!) {
+  createProjectV2(input: {ownerId: $owner, title: $title}) {
+    projectV2 { id }
+  }
+}' -f owner="YOUR_USER_NODE_ID" -f title="PDLC — Project Name"
+```
+
+To get your user node ID:
+```bash
+gh api graphql -f query='{ viewer { id } }' --jq '.data.viewer.id'
+```
+
+After creation, **add the 10 columns** via the GitHub Projects UI or API.
+Note down the `PROJECT_ID` and the `STATUS_FIELD_ID` for future steps.
+
+---
+
+## Step 2 — Create the Repository Labels
+
+```bash
+REPO="owner/repo"
+gh label create "spec:approved"          --repo $REPO --color "0e8a16" --description "Spec approved — agent can implement"
+gh label create "pr:review"              --repo $REPO --color "e4e669" --description "PR awaiting code review"
+gh label create "pr:approved"            --repo $REPO --color "0e8a16" --description "PR approved, ready for merge"
+gh label create "architecture-violation" --repo $REPO --color "d93f0b" --description "Invariant violation detected by CI"
+```
+
+---
+
+## Step 3 — Scaffold the Framework Files
+
+Instead of manually copying templates around, you can interactively inject the framework into your project using our open-source NPM tool.
+
+Run the following command in the root of your project:
+
+```bash
+npx create-agentic-pdlc
+```
+
+The CLI will:
+1. Ask you which AI Agent you use (Claude Code, Cursor, etc.).
+2. Copy the system instructions pointing to our interactive Setup Mode.
+3. Automatically download the base templates to `.agentic-pdlc/templates/`.
+
+Once the CLI finishes, it will instruct you to open your AI agent and run the **Setup Mode**. Your AI agent will then ask you the required project variables interactively and generate `AGENTS.md`, `docs/pdlc.md`, and the GitHub Actions for you!
+
+---
+
+## Step 4 — Configure GitHub Secrets
+
+In the target repository: Settings → Secrets → Actions
+
+| Secret | Description |
+|---|---|
+| `PROJECT_TOKEN` | GitHub PAT with `repo` + `project` scopes |
+
+---
+
+## Step 5 — Activate Branch Protection on `main`
+
+Requires a public repository or GitHub Pro:
+
+```bash
+gh api repos/OWNER/REPO/branches/main/protection \
+  --method PUT \
+  --input - <<'EOF'
+{
+  "required_status_checks": {
+    "strict": true,
+    "checks": [{"context": "Sentinel / CI"}]
+  },
+  "enforce_admins": false,
+  "required_pull_request_reviews": {
+    "required_approving_review_count": 1,
+    "dismiss_stale_reviews": true
+  },
+  "restrictions": null,
+  "allow_force_pushes": false,
+  "allow_deletions": false
+}
+EOF
+```
+
+---
+
+## Step 6 — Commit Artifacts
+
+```bash
+git add AGENTS.md docs/pdlc.md .github/workflows/
+git commit -m "chore: setup agentic-pdlc framework"
+git push
+```
+
+---
+
+## Step 7 — Populate the Initial Backlog
+
+For each known idea or feature, create an issue using the convention:
+
+```bash
+gh issue create \
+  --repo owner/repo \
+  --title "👤 US: [short description]" \
+  --body "Initial idea issue. Spec to be detailed."
+```
+
+Move the issues to the `Idea` column on the board matching your setup.
+
+---
+
+## Final Verification Checklist
+
+- [ ] Board has 10 columns fully configured
+- [ ] Labels created in the repository
+- [ ] `AGENTS.md` is present at the root, completely devoid of placeholders
+- [ ] `docs/pdlc.md` has the correct IDs
+- [ ] `project-automation.yml` is active (test with a dummy PR)
+- [ ] `agent-trigger.yml` is active (test by adding `spec:approved` to an issue)
+- [ ] `ci.yml` correctly runs tests and linters
+- [ ] Branch protection active on `main`
+- [ ] Implementation agent correctly connected to the repo

package/adapters/claude-code/claude-md-snippet.md

@@ -0,0 +1,5 @@
+Add the following snippet to the `CLAUDE.md` file in the root of your target repository:
+
+```markdown
+Run the `agentic-pdlc` skill to act as my upstream brainstorm and spec writing partner. If this repository is fresh, running the skill will automatically prompt the Setup Mode to populate `AGENTS.md`, `docs/pdlc.md`, and the automated `.github/workflows/`.
+```

package/adapters/claude-code/skill.md

@@ -0,0 +1,49 @@
+---
+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/workflows/project-automation.yml`
+- `.github/workflows/agent-trigger.yml`
+
+If any of these files are missing, you are in **Setup Mode**. Do not proceed with feature requests until setup is complete.
+1. Acknowledge that the framework is not yet set up.
+2. Interactively ask the user for required values **one group at a time**:
+   - **Project basics:** Project Name, Description, Technical Stack (Structure).
+   - **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, Pull Request, Production). Allow user to answer "skip", which means you leave the placeholders intact.
+   - **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:review`, `pr:approved`, `architecture-violation`).
+5. Commit everything with the message: `chore: setup agentic-pdlc framework`.
+6. 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.
+
+### 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`.

package/adapters/cursor/rules.md

@@ -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/bin/cli.js

@@ -0,0 +1,100 @@
+#!/usr/bin/env node
+
+const fs = require('fs');
+const path = require('path');
+const readline = require('readline');
+
+// The directory where CLI is executed
+const targetDir = process.cwd();
+// The directory where this script sits (globally/locally in node_modules)
+const sourceDir = path.join(__dirname, '..');
+
+const rl = readline.createInterface({
+  input: process.stdin,
+  output: process.stdout
+});
+
+const cyan = '\x1b[36m';
+const reset = '\x1b[0m';
+const green = '\x1b[32m';
+const yellow = '\x1b[33m';
+
+console.log(`${cyan}================================================================${reset}`);
+console.log(`${cyan}🤖 Welcome to Agentic PDLC Boilerplate Bootstrap! 🤖${reset}`);
+console.log(`${cyan}================================================================${reset}\n`);
+
+// Helper function to recursively copy directories
+function copyDirSync(src, dest) {
+  if (!fs.existsSync(dest)) fs.mkdirSync(dest, { recursive: true });
+  const entries = fs.readdirSync(src, { withFileTypes: true });
+
+  for (let entry of entries) {
+    const srcPath = path.join(src, entry.name);
+    const destPath = path.join(dest, entry.name);
+    if (entry.isDirectory()) {
+      copyDirSync(srcPath, destPath);
+    } else {
+      fs.copyFileSync(srcPath, destPath);
+    }
+  }
+}
+
+rl.question('Which AI Agent do you use to bootstrap? (claude / cursor): ', (answer) => {
+  const agent = answer.trim().toLowerCase();
+  
+  console.log(`\n${yellow}Scaffolding Agentic PDLC into your project...${reset}`);
+
+  // We copy the templates folder so the agent has the real text logic to replace and rename
+  const sourceTemplates = path.join(sourceDir, 'templates');
+  const targetTemplates = path.join(targetDir, '.agentic-pdlc', 'templates');
+  
+  if (fs.existsSync(sourceTemplates)) {
+    copyDirSync(sourceTemplates, targetTemplates);
+    console.log(`✅ Templates copied to .agentic-pdlc/templates/`);
+  }
+
+  // Handle the specific setup instructions target
+  const claudeSetupSrc = path.join(sourceDir, 'adapters', 'claude-code', 'skill.md');
+  const cursorSetupSrc = path.join(sourceDir, 'adapters', 'cursor', 'rules.md');
+
+  if (agent === 'claude') {
+    if (fs.existsSync(claudeSetupSrc)) {
+      const dest = path.join(targetDir, '.claude.md');
+      fs.copyFileSync(claudeSetupSrc, dest);
+      console.log(`✅ Setup agent profile written to .claude.md`);
+      console.log(`\n${green}🎉 Done! To start the conversational setup:${reset}`);
+      console.log(`${cyan}\t1. Type 'claude'${reset}`);
+      console.log(`${cyan}\t2. It should automatically detect Setup Mode and prompt you.${reset}`);
+      console.log(`\nNote: The agent expects templates in .agentic-pdlc/templates.\n`);
+    } else {
+      console.error(`❌ Could not find claude instruction file at ${claudeSetupSrc}`);
+    }
+  } else if (agent === 'cursor') {
+    if (fs.existsSync(cursorSetupSrc)) {
+      // Create .cursorrules which has the general invariants
+      const dest = path.join(targetDir, '.cursorrules');
+      fs.copyFileSync(cursorSetupSrc, dest);
+      
+      // Also copy skill.md as a setup prompt for cursor composer
+      const setupPromptDest = path.join(targetDir, '.agentic-pdlc', 'SETUP_PROMPT.md');
+      if (fs.existsSync(claudeSetupSrc)) fs.copyFileSync(claudeSetupSrc, setupPromptDest);
+
+      console.log(`✅ Default cursor rules written to .cursorrules`);
+      console.log(`✅ Framework Setup Instructions written to .agentic-pdlc/SETUP_PROMPT.md`);
+      console.log(`\n${green}🎉 Done! To start the conversational setup:${reset}`);
+      console.log(`${cyan}\t1. Open Cursor${reset}`);
+      console.log(`${cyan}\t2. Open Composer (Cmd+I or Cmd+L) and type: "@.agentic-pdlc/SETUP_PROMPT.md execute Setup Mode"${reset}\n`);
+    } else {
+      console.error(`❌ Could not find cursor instruction file at ${cursorSetupSrc}`);
+    }
+  } else {
+    // Generic fallback mapping
+    const dest = path.join(targetDir, '.agentic-setup-prompt.md');
+    fs.copyFileSync(claudeSetupSrc, dest);
+    console.log(`✅ Agent generic setup instructions written to .agentic-setup-prompt.md`);
+    console.log(`\n${green}🎉 Done! To start the conversational setup:${reset}`);
+    console.log(`${cyan}Provide the .agentic-setup-prompt.md file to your AI agent and ask it to execute Setup Mode!${reset}\n`);
+  }
+
+  rl.close();
+});

package/docs/pdlc.md

@@ -0,0 +1,98 @@
+# PDLC — agentic-pdlc
+
+## Board Columns
+
+| 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 |
+| 🧪 Testing | CI pipeline running | GitHub Actions |
+| 👁 Code Review | PR opened, awaiting human review | GitHub Actions |
+| 🔀 Pull Request | PR approved, awaiting merge | GitHub Actions |
+| 🚀 Production | Merged | GitHub Actions |
+
+<!--
+Adapt columns as needed. The functional baseline is:
+💡 Idea → ⚙️ Development → 👁 Code Review → 🚀 Production
+-->
+
+## Board Identifiers (GitHub Projects)
+
+```
+PROJECT_ID   = {{PROJECT_ID}}
+STATUS_FIELD = {{STATUS_FIELD_ID}}
+REPO         = {{REPO_OWNER}}/{{REPO_NAME}}
+```
+
+## Column Option IDs
+
+| Column | Option ID |
+|---|---|
+| 💡 Idea | `{{ID_IDEA}}` |
+| 🔍 Exploration | `{{ID_EXPLORATION}}` |
+| 🧠 Brainstorming | `{{ID_BRAINSTORMING}}` |
+| 📐 Detail Solution | `{{ID_DETAIL}}` |
+| ✅ Approval | `{{ID_APPROVAL}}` |
+| ⚙️ Development | `{{ID_DEVELOPMENT}}` |
+| 🧪 Testing | `{{ID_TESTING}}` |
+| 👁 Code Review | `{{ID_CODE_REVIEW}}` |
+| 🔀 Pull Request | `{{ID_PULL_REQUEST}}` |
+| 🚀 Production | `{{ID_PRODUCTION}}` |
+
+## Agent × Phase Mapping
+
+| Phase | Responsible |
+|---|---|
+| 💡 → 📐 (upstream) | Claude (or ideation agent) in conversational session |
+| ⚙️ → 🔀 (downstream) | {{IMPLEMENTATION_AGENT}} (e.g. Jules `@google-labs-jules`) |
+| 👁 Code Review | Human (you) |
+| Automatic transitions | GitHub Actions |
+
+## Issue Title Conventions
+
+```
+[icon] [PREFIX]: [short description, imperative tense]
+
+👤 US:     user story
+🐛 BUG:    bug
+🔧 TASK:   operational task
+🔬 SPIKE:  exploration/evaluation spike
+```
+
+## Labels
+
+| Label | Entity | Color | Meaning |
+|---|---|---|---|
+| `spec:approved` | Issue | Green | Gate 2 — agent is cleared to implement |
+| `pr:review` | PR | Yellow | Awaiting code review |
+| `pr:approved` | PR | Green | Code review approved |
+
+## Approval Gates
+
+**Gate 1 — PM/Ideation (Brainstorming):**
+You comment on the issue approving one of the approaches proposed by the ideation agent.
+Format: *"Approved — proceed with option X."*
+
+**Gate 2 — Tech Lead (Spec):**
+You add the `spec:approved` label to the issue after reviewing the technical spec in the body.
+This triggers the implementation agent via `agent-trigger.yml`.
+
+## Shortcuts by Type
+
+- **BUG** — Skips Brainstorming; enters Detail Solution with diagnostics + fix.
+- **TASK** — Skips Brainstorming; enters Detail Solution with operational steps.
+- **SPIKE** — Never reaches Development; delivery is a concluding comment.
+- **US** — Full flow observing both gates.
+
+## Definition of Done
+
+An issue is truly done when:
+- [ ] All Acceptance Criteria described in the body are implemented
+- [ ] Tests passing: `echo "No tests/build needed."`
+- [ ] No invariant violations (CI green)
+- [ ] Associated PR explicitly contains `Closes #N`
+- [ ] Basic manual smoke test executed after deploy (when applicable)

package/package.json

@@ -0,0 +1,26 @@
+{
+  "name": "create-agentic-pdlc",
+  "version": "1.0.0",
+  "description": "Scaffold the Agentic PDLC framework effortlessly",
+  "type": "commonjs",
+  "bin": {
+    "create-agentic-pdlc": "./bin/cli.js"
+  },
+  "scripts": {
+    "test": "echo \"Error: no test specified\" && exit 1"
+  },
+  "keywords": [
+    "agentic",
+    "pdlc",
+    "claude",
+    "cursor",
+    "copilot",
+    "framework"
+  ],
+  "author": "Rafael Costa",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/rafaeltcosta86/agentic-pdlc.git"
+  }
+}

package/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/templates/.github/workflows/agent-trigger.yml

@@ -0,0 +1,77 @@
+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
+    steps:
+      - name: Comment on issue to trigger agent
+        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 = [
+              `{{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
+    steps:
+      - name: Comment on issue to trigger agent
+        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,
+            });

package/templates/.github/workflows/ci.yml

@@ -0,0 +1,29 @@
+name: Sentinel / CI
+
+on:
+  pull_request:
+    branches: [ main ]
+  push:
+    branches: [ main ]
+
+jobs:
+  validate:
+    name: Run tests and linters
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Setup environment
+        run: echo "Replace this with your language/toolchain setup (e.g., actions/setup-node)"
+        
+      - name: Install dependencies
+        run: echo "Replace this with your package manager install command"
+
+      - name: Run Linters
+        run: {{LINT_COMMAND}}
+
+      - name: Build
+        run: {{BUILD_COMMAND}}
+
+      - name: Run Tests
+        run: {{TEST_COMMAND}}

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

@@ -0,0 +1,150 @@
+name: PDLC Board Automation
+
+on:
+  pull_request:
+    types: [opened, reopened, closed]
+  pull_request_review:
+    types: [submitted]
+
+env:
+  PROJECT_ID: "{{PROJECT_ID}}"
+  STATUS_FIELD_ID: "{{STATUS_FIELD_ID}}"
+  STATUS_CODE_REVIEW: "{{ID_CODE_REVIEW}}"
+  STATUS_PULL_REQUEST: "{{ID_PULL_REQUEST}}"
+  STATUS_PRODUCAO: "{{ID_PRODUCAO}}"
+
+jobs:
+  # PR Opened → Move linked issue to Code Review
+  move-card-on-pr-open:
+    name: Open PR → Code Review
+    if: github.event_name == 'pull_request' && (github.event.action == 'opened' || github.event.action == 'reopened')
+    runs-on: ubuntu-latest
+    steps:
+      - name: Move linked issue to Code Review
+        uses: actions/github-script@v7
+        with:
+          github-token: ${{ secrets.PROJECT_TOKEN }}
+          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 ?? '';
+
+            // Extract issues linked via "Closes #N", "Fixes #N", "Resolves #N"
+            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_CODE_REVIEW }
+                });
+            };
+
+            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);
+                console.log(`Issue #${n} → Code Review`);
+              }
+            } else {
+              await moveItem(pr.node_id);
+              console.log(`PR #${prNumber} → Code Review (no linked issue)`);
+            }
+
+            await github.rest.issues.addLabels({ owner, repo, issue_number: prNumber, labels: ['pr:review'] }).catch(() => {});
+
+  # Review Approved → Pull Request
+  move-card-on-review-approved:
+    name: Approved PR → Pull Request
+    if: github.event_name == 'pull_request_review' && github.event.review.state == 'approved'
+    runs-on: ubuntu-latest
+    steps:
+      - name: Move issue to Pull Request
+        uses: actions/github-script@v7
+        with:
+          github-token: ${{ secrets.PROJECT_TOKEN }}
+          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 {}
+            await github.rest.issues.addLabels({ owner, repo, issue_number: prNumber, labels: ['pr:approved'] }).catch(() => {});
+
+  # PR Merged → Production
+  move-card-on-pr-merge:
+    name: Merged PR → Production
+    if: github.event_name == 'pull_request' && github.event.action == 'closed' && github.event.pull_request.merged == true
+    runs-on: ubuntu-latest
+    steps:
+      - name: Move issue to Production
+        uses: actions/github-script@v7
+        with:
+          github-token: ${{ secrets.PROJECT_TOKEN }}
+          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_PRODUCAO } });
+            };
+
+            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);
+                console.log(`Issue #${n} → Production`);
+              }
+            } else {
+              await moveItem(pr.node_id);
+            }

package/templates/AGENTS.md

@@ -0,0 +1,52 @@
+# {{PROJECT_NAME}} — AI Agent Instructions
+
+This template is the contract between the project and any external AI agent 
+(Claude Code, Cursor, Copilot, Jules, Codex, Sweep, etc.). Read this before committing any change.
+
+## Project Overview
+
+{{PROJECT_DESCRIPTION}}
+
+**Structure:**
+{{PROJECT_STRUCTURE}}
+
+## Before Any Change
+
+```bash
+git fetch origin && git checkout main && git pull
+```
+
+Always start from the current `main` HEAD. Never work over stale snapshots.
+
+## Invariants / Non-negotiable business rules
+
+{{INVARIANTS}}
+<!-- Examples:
+1. **Human-in-the-Loop** — No external side-effect actions without explicit human approval.
+2. **Immutable Audit-Log** — It's strictly forbidden to UPDATE/DELETE on audit_log; INSERT only.
+3. **Credential Isolation** — Decryption occurs only in a specific service.
+-->
+
+## Mandatory Workflow
+
+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. Create a Pull Request with `Closes #N` in the body — automation moves the board.
+
+## What NOT to do
+
+- Never commit directly to `main`.
+- Never open a PR without passing the tests.
+- Never implement beyond the immediate scope of the issue.
+- Never create future-proofing abstractions for hypothetical features.
+{{EXTRA_DONT}}
+
+## Project Standards
+
+- **Tests:** `{{TEST_COMMAND}}`
+- **Lint/Types:** `{{LINT_COMMAND}}`
+- **Build:** `{{BUILD_COMMAND}}`
+{{EXTRA_PATTERNS}}

package/templates/docs/pdlc.md

@@ -0,0 +1,98 @@
+# PDLC — {{PROJECT_NAME}}
+
+## Board Columns
+
+| 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 |
+| 🧪 Testing | CI pipeline running | GitHub Actions |
+| 👁 Code Review | PR opened, awaiting human review | GitHub Actions |
+| 🔀 Pull Request | PR approved, awaiting merge | GitHub Actions |
+| 🚀 Production | Merged | GitHub Actions |
+
+<!--
+Adapt columns as needed. The functional baseline is:
+💡 Idea → ⚙️ Development → 👁 Code Review → 🚀 Production
+-->
+
+## Board Identifiers (GitHub Projects)
+
+```
+PROJECT_ID   = {{PROJECT_ID}}
+STATUS_FIELD = {{STATUS_FIELD_ID}}
+REPO         = {{REPO_OWNER}}/{{REPO_NAME}}
+```
+
+## Column Option IDs
+
+| Column | Option ID |
+|---|---|
+| 💡 Idea | `{{ID_IDEA}}` |
+| 🔍 Exploration | `{{ID_EXPLORATION}}` |
+| 🧠 Brainstorming | `{{ID_BRAINSTORMING}}` |
+| 📐 Detail Solution | `{{ID_DETAIL}}` |
+| ✅ Approval | `{{ID_APPROVAL}}` |
+| ⚙️ Development | `{{ID_DEVELOPMENT}}` |
+| 🧪 Testing | `{{ID_TESTING}}` |
+| 👁 Code Review | `{{ID_CODE_REVIEW}}` |
+| 🔀 Pull Request | `{{ID_PULL_REQUEST}}` |
+| 🚀 Production | `{{ID_PRODUCTION}}` |
+
+## Agent × Phase Mapping
+
+| Phase | Responsible |
+|---|---|
+| 💡 → 📐 (upstream) | Claude (or ideation agent) in conversational session |
+| ⚙️ → 🔀 (downstream) | {{IMPLEMENTATION_AGENT}} (e.g. Jules `@google-labs-jules`) |
+| 👁 Code Review | Human (you) |
+| Automatic transitions | GitHub Actions |
+
+## Issue Title Conventions
+
+```
+[icon] [PREFIX]: [short description, imperative tense]
+
+👤 US:     user story
+🐛 BUG:    bug
+🔧 TASK:   operational task
+🔬 SPIKE:  exploration/evaluation spike
+```
+
+## Labels
+
+| Label | Entity | Color | Meaning |
+|---|---|---|---|
+| `spec:approved` | Issue | Green | Gate 2 — agent is cleared to implement |
+| `pr:review` | PR | Yellow | Awaiting code review |
+| `pr:approved` | PR | Green | Code review approved |
+
+## Approval Gates
+
+**Gate 1 — PM/Ideation (Brainstorming):**
+You comment on the issue approving one of the approaches proposed by the ideation agent.
+Format: *"Approved — proceed with option X."*
+
+**Gate 2 — Tech Lead (Spec):**
+You add the `spec:approved` label to the issue after reviewing the technical spec in the body.
+This triggers the implementation agent via `agent-trigger.yml`.
+
+## Shortcuts by Type
+
+- **BUG** — Skips Brainstorming; enters Detail Solution with diagnostics + fix.
+- **TASK** — Skips Brainstorming; enters Detail Solution with operational steps.
+- **SPIKE** — Never reaches Development; delivery is a concluding comment.
+- **US** — Full flow observing both gates.
+
+## Definition of Done
+
+An issue is truly done when:
+- [ ] All Acceptance Criteria described in the body are implemented
+- [ ] Tests passing: `{{TEST_COMMAND}}`
+- [ ] No invariant violations (CI green)
+- [ ] Associated PR explicitly contains `Closes #N`
+- [ ] Basic manual smoke test executed after deploy (when applicable)