create-agentic-pdlc 2.3.0 → 2.4.0

package/.agentic-pdlc/templates/AGENTS.md

@@ -1,104 +0,0 @@
-# {{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
-
-0. **Identity**: Always prefix your GitHub comments with `🤖 **Agent:** ` to distinguish yourself.
-1. **Initial State**: When beginning work on a new issue, your very first action must be to apply the `stage:brainstorming` label using the GitHub CLI (`gh issue edit <N> --add-label "stage:brainstorming"`).
-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: `{{TEST_COMMAND}}`
-7. Run typecheck (if applicable): `{{TYPECHECK_COMMAND}}`
-8. Create a Pull Request with `Closes #N` in the body — automation moves the board.
-
-### Spec format (Upstream Agents)
-
-When detailing a solution in an issue body, you must **always** include both the user story and the acceptance criteria. Never append only the ACs to an existing text; rewrite the full issue body in this standard format:
-
-```
-**As** [user],
-**I want** [action],
-**so that** [benefit].
-
----
-
-## Acceptance Criteria
-
-**AC1 — ...**
-- Given ...
-- When ...
-- Then ...
-
-**AC2 — ...**
-...
-
-## Files to modify
-- `path/to/file.ts` — what changes
-```
-
-## Stage Transition Rules (non-negotiable)
-
-MUST apply `stage:brainstorming` label immediately on starting work — before reading
-any code, before invoking any skill. Then read context and present problem summary
-+ 2–3 solution options in a single message.
-
-MUST NOT add `stage:detailing` label until the user has explicitly selected
-an approach in the current conversation turn. Work done in a prior
-planning session does NOT count as confirmation.
-
-MUST NOT add `spec:approved`, `stage:development`, or manually add
-`stage:approval` — these represent final human approval or the result of it.
-`stage:approval` is only set by system automation after you provide a complete
-spec for human review. Adding them manually triggers irreversible automation
-(Jules dispatch, board move).
-
-Each stage transition requires a fresh explicit signal from the user in the same
-session where the transition happens. These rules have no exceptions.
-
-## 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.
-- The agent MUST NOT apply these labels under any circumstances (PM only):
-  - `spec:approved`: triggers Jules dispatch + board move to Development.
-  - `qa:approved`: triggers board move to Code Review.
-  - `qa:needs-work`: signals the PR requires changes and halts the flow.
-{{EXTRA_DONT}}
-
-## Project Standards
-
-- **Tests:** `{{TEST_COMMAND}}`
-- **Lint/Types:** `{{LINT_COMMAND}}`
-- **Typecheck:** `{{TYPECHECK_COMMAND}}`
-- **Build:** `{{BUILD_COMMAND}}`
-{{EXTRA_PATTERNS}}

package/.agentic-pdlc/templates/docs/pdlc.md

@@ -1,123 +0,0 @@
-# PDLC — {{PROJECT_NAME}}
-
-## Board Columns
-
-| Column | Meaning | Who moves the card |
-|---|---|---|
-| 💡 Idea | Backlog — tell agent: "work on issue #XX" | Don't move manually |
-| 🧠 Brainstorming | AI reading context, proposing approaches and trade-offs | Label `stage:brainstorming` |
-| 📐 Detail Solution | Claude is writing the technical spec | Label `stage:detailing` |
-| ✅ Approval | Spec ready, awaiting `spec:approved` label | Label `spec:approved` |
-| ⚙️ Development | Agent implementing the spec | Label `stage:development` |
-| 🧪 Testing | CI pipeline or AI QA Agent running (Variant B) | GitHub Actions / QA Agent |
-| 👁 Code Review / PR | PR opened (Variant A) or QA passed (Variant B) | GitHub Actions |
-| 🚀 Ready for Production | Merged | GitHub Actions |
-
-<!--
-Adapt columns as needed. The functional baseline is:
-💡 Idea → ⚙️ Development → 👁 Code Review / PR → 🚀 Ready for Production
--->
-
-## Workflow Variants (QA Agent)
-
-- **Variant A (Default):** PRs bypass the `Testing` column and land directly in `Code Review / PR`.
-- **Variant B (QA Agent Enabled):** PRs land in the `Testing` column first. An AI QA agent verifies the PR, adding `qa:pass` or `qa:fail`. Only after a `qa:pass` is the issue moved to `Code Review / PR`.
-
-## 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}}` |
-| 🧠 Brainstorming | `{{ID_BRAINSTORMING}}` |
-| 📐 Detail Solution | `{{ID_DETAIL}}` |
-| ✅ Approval | `{{ID_APPROVAL}}` |
-| ⚙️ Development | `{{ID_DEVELOPMENT}}` |
-| 🧪 Testing | `{{ID_TESTING}}` |
-| 👁 Code Review / PR | `{{ID_CODE_REVIEW_PR}}` |
-| 🚀 Ready for Production | `{{ID_READY_FOR_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 / PR | 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 |
-|---|---|---|---|
-| `stage:brainstorming` | Issue | Pink | Proposed approaches awaiting PM gate |
-| `stage:detailing` | Issue | Blue | Technical spec is being written |
-| `stage:development` | Issue | Orange | Agent is implementing the spec |
-| `spec:approved` | Issue | Green | Gate 2 — agent is cleared to implement |
-| `pr:in-review` | PR | Yellow | Awaiting code review |
-| `pr:approved` | PR | Green | Code review approved |
-| `type:us` | Issue | Blue | New feature or behavioral change — full flow |
-| `type:task` | Issue | Yellow | Operational/non-functional change — full flow |
-| `type:bug` | Issue | Red | Something broken — full flow |
-| `type:spike` | Issue | Gray | Research/evaluation — never reaches Development |
-
-## Approval Gates
-
-**Gate 1 — PM/Ideation (Brainstorming):**
-Agent presents problem summary + 2–3 solution options in a single message. You select an approach.
-Format: *"Option X"* or *"Go with B"* or *"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
-
-The `type:*` label is the authoritative signal — set automatically by the agent via type inference (see `adapters/claude-code/skill.md`). Title prefixes (`🔧 TASK:`, `👤 US:`) are hints for humans; the label drives the flow.
-
-| Label | Flow |
-|---|---|
-| `type:us` | brainstorming → Gate 1 → detailing → approval |
-| `type:task` | brainstorming → Gate 1 → detailing → approval |
-| `type:bug` | brainstorming → Gate 1 → detailing → approval |
-| `type:spike` | brainstorming → Gate 1 → detailing → conclusion comment (never reaches Development) |
-
-If no `type:*` label present and agent confidence < 85%, defaults to `type:us` (safe fallback — never skips gates by omission).
-
-## Bypass Mechanism
-
-Agents MUST NOT skip any stage. The ONLY authorized bypasses are:
-
-| Mechanism | Who authorizes | What it bypasses |
-|---|---|---|
-| `human-approved` label on issue | PM (human) only | All stage gates |
-| Branch prefix `hotfix/` | PM (human) only | PR gate only |
-
-Agents MUST NOT self-authorize a bypass. Stop and ask the PM explicitly.
-
-## 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)