diff --git a/.claude-plugin/plugin.json b/.claude-plugin/plugin.json index 76eea5a..dccc252 100644 --- a/.claude-plugin/plugin.json +++ b/.claude-plugin/plugin.json @@ -1,6 +1,6 @@ { "name": "fullstack-dev-kit", - "version": "0.19.11", + "version": "0.19.12", "description": "Issue-to-PR workflow kit for any tech stack. Fetch a user story from your tracker (Jira, Linear, GitHub Issues, Azure DevOps) and any linked Figma designs, implement with plan approval, enforce >95% coverage and a security pass, generate e2e tests, open the PR, fix review findings, and move the ticket to review.", "license": "Apache-2.0", "homepage": "https://github.com/theam/claude-dev-kit", diff --git a/CHANGELOG.md b/CHANGELOG.md index 34e1ffd..82b83e3 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -7,6 +7,9 @@ The `version` in `.claude-plugin/plugin.json` is what reaches installed clients a release is only "live" for users once that is bumped and published. ## [Unreleased] +### Added +- **Rich review artifact for `plan-backlog` (#74).** On hosts that support artifacts (Claude Code / claude.ai), a non-trivial backlog draft is now presented as a **navigable artifact** at the review step — collapsible epics → stories with acceptance criteria, labels, sizing and dependencies, plus search/filter and a table of contents — so a large backlog is easy to scan and drill into. The in-chat draft + approval question stay the gate (the artifact is a review aid, not a substitute); portable hosts (Codex/Cursor/Copilot) keep Markdown. From @santielizondo's idea. Kit → **0.19.12**. + ### Changed - **`plan-backlog` is now guided by default (#72).** Instead of emitting a whole backlog in one shot, it elaborates progressively — **zoom-out → zoom-in** across three levels (framing → epics → stories), presenting **2–4 alternatives** and waiting for the PO's decision at each, so the definition work stays with the human. One-shot is still available via `--quick`. The mode is judged **per invocation** from repo docs + brief context (never persisted — a mature project can hold a brand-new feature), always keeping a light framing check. The guided flow runs in the main conversation (`/plan-backlog`); the `backlog-planner` subagent remains the engine for `--quick` and for discovery/creation. From early-user feedback. Kit → **0.19.11**. diff --git a/README.md b/README.md index 6593566..c554ba3 100644 --- a/README.md +++ b/README.md @@ -38,7 +38,7 @@ Give the `coding-agent` a user story ID from your tracker and it orchestrates th Before there's a ticket, **`plan-backlog`** turns an idea or brief — chat text, a PDF, a Word doc, an artifact — into a well-formed backlog (epics, INVEST user stories with acceptance criteria, sub-tasks, dependencies) and **creates it in your tracker after you approve it**. It's discovery-first (mirrors your team's existing hierarchy and conventions rather than imposing one) and speaks Jira / Linear / GitHub Issues / Azure DevOps via the same adapters. The stories it creates feed straight into `/work-story` — closing the loop **idea → backlog → ticket → PR**. -It's **guided by default** — it elaborates progressively (framing → epics → stories), offering alternatives and asking for your decision at each level, so the definition stays yours; add `--quick` for a one-shot draft. In **Claude Code**, run `/plan-backlog [--quick]`. On **Codex / Cursor / Copilot**, invoke the `plan-backlog` skill directly. +It's **guided by default** — it elaborates progressively (framing → epics → stories), offering alternatives and asking for your decision at each level, so the definition stays yours; add `--quick` for a one-shot draft. On Claude, a non-trivial backlog is shown as a **navigable artifact** for review (approval still happens in the chat). In **Claude Code**, run `/plan-backlog [--quick]`. On **Codex / Cursor / Copilot**, invoke the `plan-backlog` skill directly. **Install in one command:** diff --git a/agents/backlog-planner.md b/agents/backlog-planner.md index 8930875..df77752 100644 --- a/agents/backlog-planner.md +++ b/agents/backlog-planner.md @@ -28,7 +28,7 @@ Build the backlog draft per `plan-backlog`: the hierarchy plus each item's title **If you are running as a subagent** (your caller relays to the user): return the FULL draft as your result and stop — do not ask for approval yourself and do not create anything. Your caller shows it to the user and resumes you with the decision. Approving an unseen draft is worthless. -**If you are running in the main conversation**: present the full draft in the chat and wait for explicit approval. +**If you are running in the main conversation**: present the full draft in the chat and wait for explicit approval. On a host with artifacts, you may also render a non-trivial backlog as a navigable artifact for review (per the `plan-backlog` skill), but the in-chat draft + question stay the gate. (As a subagent you only return the draft — the caller renders any artifact and runs the gate.) ### 3. Create On approval, create the items via the tracker's write adapter: **parents before children**, link children to parents, set labels/components/points where discovered, and **verify writes by read-back** where the CLI can silently no-op (e.g. GitHub). Ground everything in the source and the user's edits — never fabricate scope or acceptance criteria. diff --git a/commands/plan-backlog.md b/commands/plan-backlog.md index 9688454..29b9943 100644 --- a/commands/plan-backlog.md +++ b/commands/plan-backlog.md @@ -20,7 +20,7 @@ The guided flow is interactive, so conduct it in the main conversation (do not h - **Framing (zoom-out):** the goal, the problem space, and framing options (MVP vs full, ways to slice it). - **Epics / themes** for the chosen framing. - **Stories** (with Given/When/Then acceptance criteria) within each epic. -3. **Approval gate:** print the full assembled draft in the conversation, then ask the user to approve, adjust, or cancel. (The per-level decisions do not replace this final gate.) +3. **Approval gate:** print a concise hierarchy summary in the conversation and ask the user to approve, adjust, or cancel. For a non-trivial backlog, also render the full draft as a **navigable artifact** (collapsible epics → stories, searchable) as the rich review surface — but the approval still happens in the chat (the artifact is not a substitute for the gate). See the `plan-backlog` skill's review step. (The per-level decisions do not replace this final gate.) 4. **Create** on approval, via the tracker adapter (you may delegate the creation writes to `backlog-planner`), then report each item's key/URL and the handoff note (each story ready for `/work-story `). ## `--quick` — one-shot draft (delegate) @@ -31,7 +31,7 @@ Delegate to the `backlog-planner` subagent in two phases: **Approval gate — two separate steps, in this exact order:** -1. **FIRST, print the draft**: write a normal assistant message containing the backlog-planner's FULL draft (hierarchy + each item's title, acceptance criteria, labels, links), verbatim. This message is a hard requirement — a selection dialog is not a substitute, and putting the draft only inside a dialog's option text does not count. +1. **FIRST, print the draft**: write a normal assistant message containing the backlog-planner's FULL draft (hierarchy + each item's title, acceptance criteria, labels, links), verbatim. This message is a hard requirement — a selection dialog is not a substitute, and putting the draft only inside a dialog's option text does not count. For a non-trivial backlog you may *additionally* render it as a navigable artifact (see the skill's review step), but the in-chat draft + question remain the gate. 2. **THEN, and only after that message is visible**, ask the user to approve, adjust, or cancel. Never collapse these two steps into one dialog. Only if the arguments contain `--auto-approve` (automated runs), skip the gate. diff --git a/plugins/fullstack-dev-kit/.codex-plugin/plugin.json b/plugins/fullstack-dev-kit/.codex-plugin/plugin.json index 6490f2b..25c5922 100644 --- a/plugins/fullstack-dev-kit/.codex-plugin/plugin.json +++ b/plugins/fullstack-dev-kit/.codex-plugin/plugin.json @@ -1,6 +1,6 @@ { "name": "fullstack-dev-kit", - "version": "0.19.11", + "version": "0.19.12", "description": "Issue-to-PR workflow for any tech stack: fetch stories from Jira/Linear/GitHub/Azure and Figma designs, plan-approval gate, adaptive quality + coverage gates, e2e generation, PR creation and review.", "author": { "name": "The Agile Monkeys", diff --git a/plugins/fullstack-dev-kit/.cursor-plugin/plugin.json b/plugins/fullstack-dev-kit/.cursor-plugin/plugin.json index ca232a0..b3712c2 100644 --- a/plugins/fullstack-dev-kit/.cursor-plugin/plugin.json +++ b/plugins/fullstack-dev-kit/.cursor-plugin/plugin.json @@ -1,6 +1,6 @@ { "name": "fullstack-dev-kit", - "version": "0.19.11", + "version": "0.19.12", "description": "Issue-to-PR workflow for any tech stack: fetch stories from Jira/Linear/GitHub/Azure and Figma designs, plan-approval gate, adaptive quality + coverage gates, e2e generation, PR creation and review.", "author": { "name": "The Agile Monkeys" diff --git a/plugins/fullstack-dev-kit/plugin.json b/plugins/fullstack-dev-kit/plugin.json index bba9799..3a8b188 100644 --- a/plugins/fullstack-dev-kit/plugin.json +++ b/plugins/fullstack-dev-kit/plugin.json @@ -1,7 +1,7 @@ { "$schema": "https://agent-plugins.org/schemas/1.0.0/plugin.schema.json", "name": "fullstack-dev-kit", - "version": "0.19.11", + "version": "0.19.12", "description": "Issue-to-PR workflow for any tech stack: fetch stories from Jira/Linear/GitHub/Azure and Figma designs, plan-approval gate, adaptive quality + coverage gates, e2e generation, PR creation and review.", "author": { "name": "The Agile Monkeys", diff --git a/plugins/fullstack-dev-kit/skills/plan-backlog/SKILL.md b/plugins/fullstack-dev-kit/skills/plan-backlog/SKILL.md index 9a6ca76..b18bea4 100644 --- a/plugins/fullstack-dev-kit/skills/plan-backlog/SKILL.md +++ b/plugins/fullstack-dev-kit/skills/plan-backlog/SKILL.md @@ -81,10 +81,12 @@ Work with a neutral backlog model and produce the whole thing at once: Recommend a shape based on discovery and **confirm it** with the user — don't force one. Then go to the approval gate (§5). -## 5. Approval gate (mandatory — create nothing yet) +## 5. Review & approval gate (mandatory — create nothing yet) Present the **full assembled draft**: the hierarchy plus each item's title, description, acceptance criteria, labels, and links. **Wait for explicit approval**; the user may edit anything. Only after approval proceed to create. (Same doctrine as `work-story`'s plan gate — never create tickets without a human OK. In guided mode the per-level decisions do not replace this final gate.) +**Rich review surface (when the host supports artifacts — e.g. Claude Code / claude.ai).** For anything beyond a couple of items, also render the draft as a **navigable artifact** so a large backlog is easy to scan and drill into — collapsible **epics → stories**, each showing its user story, Given/When/Then acceptance criteria, labels, sizing, and dependencies; with search/filter and a table-of-contents. Load the `artifact-design` skill before building it. The artifact is a *review aid, not the gate itself*: still print a concise hierarchy summary and ask for approval **in the conversation** (a page or dialog is not a substitute — the user must be able to approve in the chat). On hosts without artifacts (Codex / Cursor / Copilot), present the draft as Markdown. + ## 6. Create — via the tracker's write adapter Create **parents before children**, link children to parents, and set labels/components/points where discovered. Report each created item with its key/URL. diff --git a/skills/plan-backlog/SKILL.md b/skills/plan-backlog/SKILL.md index 9a6ca76..b18bea4 100644 --- a/skills/plan-backlog/SKILL.md +++ b/skills/plan-backlog/SKILL.md @@ -81,10 +81,12 @@ Work with a neutral backlog model and produce the whole thing at once: Recommend a shape based on discovery and **confirm it** with the user — don't force one. Then go to the approval gate (§5). -## 5. Approval gate (mandatory — create nothing yet) +## 5. Review & approval gate (mandatory — create nothing yet) Present the **full assembled draft**: the hierarchy plus each item's title, description, acceptance criteria, labels, and links. **Wait for explicit approval**; the user may edit anything. Only after approval proceed to create. (Same doctrine as `work-story`'s plan gate — never create tickets without a human OK. In guided mode the per-level decisions do not replace this final gate.) +**Rich review surface (when the host supports artifacts — e.g. Claude Code / claude.ai).** For anything beyond a couple of items, also render the draft as a **navigable artifact** so a large backlog is easy to scan and drill into — collapsible **epics → stories**, each showing its user story, Given/When/Then acceptance criteria, labels, sizing, and dependencies; with search/filter and a table-of-contents. Load the `artifact-design` skill before building it. The artifact is a *review aid, not the gate itself*: still print a concise hierarchy summary and ask for approval **in the conversation** (a page or dialog is not a substitute — the user must be able to approve in the chat). On hosts without artifacts (Codex / Cursor / Copilot), present the draft as Markdown. + ## 6. Create — via the tracker's write adapter Create **parents before children**, link children to parents, and set labels/components/points where discovered. Report each created item with its key/URL.