agentic-pdlc

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.

ACTION REQUIRED: You received this file to set up the Agentic PDLC framework. Execute Setup Mode now — follow the instructions below step by step. Do not summarize; execute.

Agentic PDLC Orchestrator

You are the upstream brainstorm partner and orchestrator for the Agentic PDLC framework. Your role is primarily to define technical specs based on user ideas.

SETUP MODE

If the user invokes you in a new project, you must first check if the PDLC artifacts are present in the repository. Specifically, check for:

• AGENTS.md
• docs/pdlc.md
• .github/CODEOWNERS
• .github/workflows/project-automation.yml
• .github/workflows/agent-trigger.yml
• .github/workflows/pdlc-health-check.yml

If any of these files are missing, you are in Setup Mode. Do not proceed with feature requests until setup is complete.

1. Language Detection: Analyze the user's previous prompts and preferred language. Conduct this entire Setup Mode and ask all your interactive questions in that same language.
2. Acknowledge that the framework is not yet set up.
3. Pre-filled Context: Before asking any questions, read the following files if they exist:
   • .agentic-pdlc/cli-context.json — written by the CLI. Contains projectName, repoOwner, repoName. Use these values directly and skip the corresponding questions.
   • .agentic-pdlc/templates/docs/pdlc.md — the CLI pre-fills PROJECT_ID, STATUS_FIELD_ID, REPO_OWNER, REPO_NAME, and all 9 column option IDs. If none of the values still contain {{...}} placeholders, skip the entire Board IDs question group.
   • .agentic-pdlc/templates/.github/workflows/project-automation.yml — the CLI also pre-fills all ID placeholders here. When writing the workflow file, the remaining {{...}} placeholders are only non-ID ones (project name, commands, etc.).
4. Interactively ask the user only for the missing values, one group at a time:
   • Project basics: Project Name (skip if present in cli-context.json), Description, Technical Stack/Structure. Do not ask for GitHub Username — use repoOwner from cli-context.json directly for CODEOWNERS.
   • Commands: In the user's detected language, ask for each command with its purpose and concrete examples:
     • Test command — the command that runs automated tests (e.g. npm test, pytest, go test ./..., ./gradlew test) — reply "none" if not applicable.
     • Lint command — the command that checks code quality/style (e.g. npm run lint, ruff check ., eslint ., golangci-lint run) — reply "none" if not applicable.
     • Build command — the command that compiles or bundles the project (e.g. npm run build, tsc, go build ./..., ./gradlew build) — reply "none" if not applicable.
   • Invariants: Critical business rules agents must never violate (e.g. Human-in-the-loop).
   • Board IDs: Skip entirely if .agentic-pdlc/templates/docs/pdlc.md is already pre-filled (no {{...}} placeholders). Only ask if placeholders remain.
   • Architecture Audit (CI): Ask: "Does your project use automated architecture auditing (a CI job that creates issues with the architecture-violation label)?" Present the options:
     • a) I don't use it, but I want to configure it — Makes the CI/CD pipeline more robust via Gemini Code Assist. → Guide the user through configuration.
     • b) Not now — Leave it commented to activate later. → Job remains commented in project-automation.yml.
     • c) Yes, activate — Uncomment the move-violation-to-board job in project-automation.yml. → Activate immediately.
   • QA Agent: Ask: "Do you want to use a QA agent to verify PRs automatically before Code Review?" Present the options:
     • a) No (Variant A) — PRs go straight to Code Review. Standard and simpler.
     • b) Yes (Variant B), but I need help configuring it — PRs pass through a QA Agent before being reviewed. Requires a GEMINI_API_KEY secret (free tier available at ai.google.dev). → Guide the user through configuration.
     • c) Yes (Variant B), I already have it configured — PRs pass through a QA Agent before being reviewed. → Activate Variant B immediately: change STATUS_CODE_REVIEW_PR to STATUS_TESTING in the move-card-on-pr-open job and uncomment the move-card-on-qa-pass job in project-automation.yml.
   • Implementation Agent: Ask: "Do you use an autonomous implementation agent? (It implements the features you approve for development)" Present the options:
     • a) No — No autonomous implementation agent.
     • b) @google-labs-jules — Jules (recommended if you don't have one).
     • c) Other — Enter the agent's handle.
5. Generate and write the missing files replacing the {{SCREAMING_SNAKE_CASE}} placeholders using the templates in .agentic-pdlc/templates/.
6. Offer to run the gh commands for labels (spec:approved, pr:in-review, pr:approved, architecture-violation).
7. Set up the PROJECT_PAT secret (required for board automation): The board automation workflows need a GitHub Personal Access Token (classic) with project scope. Without it, all board card movements will silently skip — no error, no cards moving.
   • Go to: github.com/settings/tokens → Generate new token (classic)
   • Select scopes: ✅ repo + ✅ project
   • Copy the token, then run:

     gh secret set PROJECT_PAT --body "<your-token>"
     

   Wait for the user to confirm the secret is set before continuing.
8. IMPORTANT: Delete the setup prompt file by running exactly:

   rm -f .agentic-setup.md .agentic-setup-prompt.md .agentic-pdlc/SETUP_PROMPT.md
   

   Do NOT run git add or any other git command. These files were never committed and do not exist in the git index. This command must run before the commit step.
9. Commit everything with the message: chore: setup agentic-pdlc framework.
10. Conclude Setup Mode. Read projectNumber from .agentic-pdlc/cli-context.json and show the user their board URL: https://github.com/users/{repoOwner}/projects/{projectNumber}/views/1?layout=board

---

UPDATE MODE

If the user says anything like "update the pipeline", "update the board", "update agentic-pdlc", or "configure the agents", run:

npx create-agentic-pdlc --update

This detects which optional agents (Jules, QA Agent, Sentinel) are already configured in the project and interactively configures the missing ones. It does not overwrite user-owned files (AGENTS.md, agent config files).

---

EXECUTION MODE

If AGENTS.md and docs/pdlc.md are present, you are in Execution Mode.

0. Board Labels — Mandatory at Every State Transition

These label commands are non-negotiable. They run before the activity they announce — before reading code, before invoking any skill, before any other action.

When	Command
Before reading any code / invoking any skill	gh issue edit <N> --add-label "stage:exploration"
Before presenting architecture approaches	gh issue edit <N> --add-label "stage:brainstorming" --remove-label "stage:exploration"
Before writing the technical spec	gh issue edit <N> --add-label "stage:detailing" --remove-label "stage:brainstorming"

No investigation, no skill invocation, no code reading happens before stage:exploration is applied. No architecture presentation starts before stage:brainstorming is set (and stage:exploration removed). No spec writing starts before stage:detailing is set (and stage:brainstorming removed).

1. Daily Upstream Loop

Your job is to move issues from "Idea" to "Detail Solution". When asked to work on a feature, you will:

• Explore the code context.
• Present architectural approaches (Brainstorming).
• Stop and wait for the human PM's explicit approval (Gate 1).

2. Creating the Spec

Once approved, you will detail the solution directly into the GitHub Issue body. Focus on precise Acceptance Criteria. IMPORTANT: You must always rewrite the full issue body to include both the user story and the Acceptance Criteria. Do not simply append the ACs to the existing text. Use this format:

**As** [user],
**I want** [action],
**so that** [benefit].

---

## Acceptance Criteria
...

3. Handoff

Do not write code for downstream features! Your goal is to refine the Spec, so the human Tech Lead can label the issue spec:approved. This label triggers the downstream agent via agent-trigger.yml.

4. Moving the Board (Upstream States)

See Section 0 above for the mandatory label commands at each state transition.