create-agentic-pdlc 2.4.0 → 3.1.0

package/README.md

@@ -1,57 +1,54 @@
-# 🤖 Agentic PDLC Framework
+# 🤖 Agentic PDLC
 
-> Do your AI agents build features that don't match the spec?
-> Do you find bugs and architecture violations only at the end of the lifecycle?
-> Are you the one manually moving cards across your board — every single time?
+> Does your AI agent add code you didn't ask for?
+> Does it skip the spec and jump straight to a PR?
+> Does it ignore the rules in your CLAUDE.md?
 
-**Agentic PDLC** gives your agents a shared rulebook, a self-moving board, and a CI that won't let broken code reach production. One `npx` command to set up.
+**Agentic PDLC** gives your agent a brake it can't ignore — a hook that makes it write the spec first, keep changes small, and stop at each gate. One `npx` to install.
 
 <div align="center">
-  <img src=".github/assets/agentic-pdlc-flow.svg" alt="Agentic PDLC Architecture Flow" width="100%">
+  <img src=".github/assets/agentic-pdlc-flow.svg" alt="Agentic PDLC: Upstream idea-to-spec, gated by spec:approved, into Downstream spec-to-production" width="100%">
 </div>
 
-Solo devs and small teams hit the same wall: one agent writes the spec, another implements it differently, a third reviews without knowing either. Agentic PDLC gives all of them a shared brief, automates the board, and puts a CI guard between your agents and production.
+---
+
+## Two modes — pick yours
+
+**`lite` (default) — the brake**
+Your agent writes the spec, waits for your approval, then implements it. It won't add code you didn't ask for. It won't open a PR before the spec is approved. It won't skip your `CLAUDE.md` rules — because the gate is a hook, not text the agent can ignore. Value on your first PR.
+
+**`--agentic` — see your whole pipeline**
+Everything in `lite`, plus a self-moving kanban board that shows your full product lifecycle, from **Idea → Production**. It makes transparent what needs your attention/approval, what's been done by the agent, and what's ready to merge. It supports as many agents as you need.
 
 ---
 
 ## ⚡ Why it works
 
-- 🗺️ **A transparent lifecycle** — Every feature travels a Kanban board from Idea to Production. You always know where things are.
-- 🤖 **A board that moves itself** — When you approve a spec, the card moves. When an agent opens a PR, the card moves. You just approve or reject.
-- 🧠 **Agents that agree with each other** — One briefing (`AGENTS.md`), read by every agent. Claude, Jules, Gemini — all pulling in the same direction, without you copy-pasting context between tabs.
-- 🛡️ **Code that can't silently break production** — A CI auditor checks every PR for architecture violations before anything reaches your main branch. *(Maturity Model — coming soon)*
+- 🛑 **A brake the agent can't ignore** — the gate is a hook, not text in CLAUDE.md. Text gets ignored; a hook does not.
+- 📋 **Spec before code** — the agent can't open a PR until the spec is approved, with acceptance criteria, edge cases, and files to change.
+- 🗺️ **See your whole pipeline** *(`--agentic` only)* — a board tracks every task from idea to production, and the gate between spec and code stays yours. You approve before anything ships.
 
 ---
 
 ## 🚀 Quick Start
 
-Run this in the root of your project:
-
 ```bash
 npx create-agentic-pdlc
 ```
 
-The CLI sets up your GitHub board, labels, and workflows, then hands over to your AI assistant to finish the configuration interactively. No YAML editing. No manual config.
+Installs `lite` by default — your AGENTS.md, CLAUDE.md, and the gate hook. Your AI assistant finishes the setup with you; no YAML to edit.
 
-**Already set up? Add or reconfigure optional agents at any time:**
+**Want the full board and pipeline view?**
 
 ```bash
-npx create-agentic-pdlc --update
+npx create-agentic-pdlc --agentic
 ```
 
-Detects what is already configured (Jules, QA Agent, Sentinel) and interactively sets up what is missing. Your existing board IDs and customizations are never touched.
-
----
-
-## 🏗️ How It Works
-
-The framework splits work into two phases:
-
-### 1. You + AI: Idea → Spec
-Use conversational AI (e.g., **Claude Code**, **Gemini CLI**) as your brainstorming partner. Together, you flesh out user stories, acceptance criteria, and technical specifications until they are solid.
+**Already set up? Add or change things any time:**
 
-### 2. Your agents: Spec → Production
-Once you approve the spec, autonomous implementation agents (e.g., **Jules**, **Sweep**, **Copilot Workspace**) pick up the task. The board moves automatically; the CI auditor guards the main branch.
+```bash
+npx create-agentic-pdlc --update
+```
 
 ---
 
@@ -71,11 +68,15 @@ One shared brief (`AGENTS.md`). Every agent reads it.
 
 ## 📦 What you get
 
-After setup, your project has:
+**`lite` (default)**
+- **`AGENTS.md`** — the shared brief every agent reads; your rules, once
+- **`CLAUDE.md`** — keep-changes-small rule + the stage gates
+- **`.agentic-pdlc/hooks/pdlc-stage-gate.sh`** — the hook; the agent can't open a PR until the spec is approved
 
-- **`AGENTS.md`** — The shared brief every agent reads. Your rules, once.
-- **`docs/pdlc.md`** — Your pipeline map: board columns, IDs, and who does what.
-- **`.github/workflows/`** — Three automations: board moves itself, agent wakes on spec approval, CI audits every PR.
+**`--agentic` (opt-in)**
+Everything in lite, plus:
+- **`docs/pdlc.md`** — your pipeline map: board columns and who does what
+- **`.github/workflows/`** — board automation: moves cards on spec approval, PR open, and CI pass
 
 ---
 

package/adapters/claude-code/skill.md

@@ -22,12 +22,14 @@ Specifically, check for:
 
 If any of these files are missing, you are in **Setup Mode**. Do not proceed with feature requests until setup is complete.
 
+**Lite profile note:** If `cli-context.json` contains `"profile": "lite"`, the only mandatory artifacts are `AGENTS.md` and `CLAUDE.md` — `docs/pdlc.md` and the workflow files are not installed in the lite profile. Skip checks for those files.
+
 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`, `projectNumber`, `isOrg`, `boardUrl`, and `patAutoSet` (boolean). Use these values directly and skip the corresponding questions. Honor `patAutoSet` in Step 7 and `boardUrl` in Step 10.
-   - `.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.).
+   - `.agentic-pdlc/cli-context.json` — written by the CLI. Contains `projectName`, `repoOwner`, `repoName`, `projectNumber`, `isOrg`, `boardUrl`, `patAutoSet` (boolean), and `profile` (`"lite"` or `"full"`). Use these values directly and skip the corresponding questions. Honor `patAutoSet` in Step 7 and `boardUrl` in Step 10.
+   - `.agentic-pdlc/templates/docs/pdlc.md` — **only present in the `full` profile.** If absent (lite install), skip the Board IDs question group entirely and skip all steps that reference this file. If present, the CLI pre-fills PROJECT_ID, STATUS_FIELD_ID, REPO_OWNER, REPO_NAME, and all 9 column option IDs; if none still contain `{{...}}` placeholders, skip the Board IDs question group.
+   - `.agentic-pdlc/templates/.github/workflows/project-automation.yml` — **only present in the `full` profile.** If absent, skip. If present, the CLI also pre-fills all ID placeholders here; remaining `{{...}}` placeholders are 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:
@@ -53,23 +55,25 @@ If any of these files are missing, you are in **Setup Mode**. Do not proceed wit
      - Jules (`@google-labs-jules`): use `jules` — this is the native label the Jules GitHub App watches. **Do NOT use `agent:jules`** — Jules does not watch that label and the trigger will silently fail.
      - Other agents: use the handle without `@`, lowercase (e.g. `@my-agent` → `my-agent`).
 5. Generate and write the missing files replacing the `{{SCREAMING_SNAKE_CASE}}` placeholders using the templates in `.agentic-pdlc/templates/`.
+   - **CLAUDE.md:** If `.agentic-pdlc/templates/CLAUDE.md` exists and `CLAUDE.md` does not yet exist at the project root, write it — replacing only `{{PROJECT_NAME}}` with the project name. Skip if CLAUDE.md already exists (never downgrade).
+   - **Lite profile:** If `cli-context.json` has `"profile": "lite"`, skip steps that reference `docs/pdlc.md`, `project-automation.yml`, `agent-trigger.yml`, and `pdlc-health-check.yml` — these are not installed in lite.
 6. Offer to run the `gh` commands for labels (`spec:approved`, `pr:in-review`, `pr:approved`, `architecture-violation`).
-7. **`PROJECT_PAT` secret (required for board automation):**
+7. **`PROJECT_TOKEN` secret (required for board automation):**
 
    Read `patAutoSet` from `.agentic-pdlc/cli-context.json`:
 
-   **If `patAutoSet === true`:** The CLI already configured this secret automatically. Print `✅ PROJECT_PAT is configured.` and continue to Step 8 — do not ask the user anything.
+   **If `patAutoSet === true`:** The CLI already configured this secret automatically. Print `✅ PROJECT_TOKEN is configured.` and continue to Step 8 — do not ask the user anything.
 
    **If `patAutoSet === false` (org repo):** Show the block below and wait for the user to reply "done" or "secret set" before continuing:
 
-   > Your repo is in an organization. For security, `PROJECT_PAT` must be a dedicated PAT (not your personal OAuth token). Without it, all board card movements in CI will silently skip — no error surfaced.
+   > Your repo is in an organization. For security, `PROJECT_TOKEN` must be a dedicated PAT (not your personal OAuth token). Without it, all board card movements in CI will silently skip — no error surfaced.
    >
    > 1. Open: **github.com/settings/tokens** → *Generate new token (classic)*
-   > 2. Name: `PROJECT_PAT — <repo-name>`
+   > 2. Name: `PROJECT_TOKEN — <repo-name>`
    > 3. Select scopes: ✅ `repo` + ✅ `project`
    > 4. Copy the token, then run:
    >    ```
-   >    gh secret set PROJECT_PAT --body "<your-token>" --repo <owner>/<repo>
+   >    gh secret set PROJECT_TOKEN --body "<your-token>" --repo <owner>/<repo>
    >    ```
    > 5. Reply **"done"** when finished.
 8. **IMPORTANT:** Delete the setup prompt file by running exactly: