diff --git a/.claude-plugin/plugin.json b/.claude-plugin/plugin.json index 2790c96..736b938 100644 --- a/.claude-plugin/plugin.json +++ b/.claude-plugin/plugin.json @@ -1,6 +1,6 @@ { "name": "fullstack-dev-kit", - "version": "0.19.9", + "version": "0.19.10", "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 2fbc95c..c95f3be 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -8,6 +8,7 @@ a release is only "live" for users once that is bumped and published. ## [Unreleased] ### Added +- **`follow-ups` skill — close the loop (#67).** When a story finishes, the loose ends it surfaced (out-of-scope notes in the PR, deferred `pr-review`/`fix-pr` findings, deliberate TODOs) can now be **tracked**, not just described: `follow-ups` proposes them as work items linked to the source story and creates them in the tracker **after approval** (Jira / Linear / GitHub / Azure adapters, reusing the `plan-backlog` creation path). Wired as an offered final step (step 8) in `coding-agent` and the portable `work-story` playbook — never forced, never fabricated. Full loop: idea → backlog → ticket → PR → **follow-ups tracked**. Kit → **0.19.10**. - **`/plan-backlog` command + `backlog-planner` agent (Claude Code orchestration for #64).** Phase 2 on top of the `plan-backlog` skill: a slash command (`/plan-backlog `) delegates to a context-isolated `backlog-planner` orchestrator that reads the source, learns the tracker's conventions, drafts the backlog, **prints it and waits for approval** (two-step gate, same as `/work-story`), then creates the items and hands off to `work-story`. Portable hosts (Codex/Cursor/Copilot) keep invoking the `plan-backlog` skill directly. Kit → **0.19.9**. - **`plan-backlog` skill (product-owner, upstream of the workflow).** Turns an idea or description — in any form (chat text, PDF, Word, an artifact, a Confluence page) — into a well-formed backlog (epics, INVEST user stories with Given/When/Then acceptance criteria, sub-tasks, dependencies) and **creates it in the configured tracker after approval**. Discovery-first: it learns the team's native hierarchy and conventions from the tracker rather than imposing one, and maps a neutral model onto Jira / Linear / GitHub Issues / Azure DevOps via adapters (same pattern as `issue-fetch`). Never creates anything before an explicit approval gate. Created stories hand off to `work-story`, closing the loop idea → backlog → ticket → PR. Design: #64. Kit → **0.19.8**. - **Real-world PHP validation for the stack matrix (#50).** A `Stacks` CI job runs the PHP profile's own install/test/coverage commands against `samples/php/` (PCOV driver) and enforces the ≥95% per-file line bar via `scripts/check-clover.mjs`, so a stale profile command fails CI. `php.md` updated from "iteration zero" to "verified in CI" (E2E still iteration zero). Tooling/samples/docs + a shipped `php.md` fix — no version bump; rides the next release. diff --git a/README.md b/README.md index f9ca39f..a22ea27 100644 --- a/README.md +++ b/README.md @@ -29,7 +29,8 @@ Give the `coding-agent` a user story ID from your tracker and it orchestrates th ├─ security-reviewer → authorization / secrets / input / exposure pass (gate) ├─ pr-review → pr-fixer → self-review, then fix the blocking findings ├─ create-pr → branch + commit + PR with verification evidence - └─ issue-update → comment PR link on the ticket + move it to review + ├─ issue-update → comment PR link on the ticket + move it to review + └─ follow-ups → offer to track leftover loose ends as linked tickets ``` ### From idea to backlog (product owners) diff --git a/agents/coding-agent.md b/agents/coding-agent.md index aca9e0e..f2aad20 100644 --- a/agents/coding-agent.md +++ b/agents/coding-agent.md @@ -12,6 +12,7 @@ skills: - pr-review - fix-pr - issue-update + - follow-ups --- You are the story orchestrator. Your input is an issue key from the team's tracker; your output is a pull request that satisfies the story's acceptance criteria with verified quality gates, and a tracker ticket that reflects it. @@ -73,6 +74,9 @@ Apply the gates that fit the project (detect its setup each run; see `instructio ### 7. Update the ticket - Run `issue-update`: comment a **product-facing summary** on the ticket (what was delivered and the decisions taken, in plain language for the product owner — no technical jargon; the technical evidence lives in the PR) plus the PR link, and transition the ticket to the team's review status. The story is not done until the tracker reflects it. +### 8. Track follow-ups (offer — never force) +- If the story left **loose ends** (out-of-scope notes in the PR, deferred `pr-review`/`fix-pr` findings, deliberate TODOs), run `follow-ups`: **offer** to create them as tracked work items linked to this story. It's approval-gated — present the list and create nothing until the user approves; the user may edit or skip. If there are no genuine loose ends, say so and skip. Never fabricate follow-ups to look thorough. + ## Reporting At every step, state plainly what passed, what failed (with output), and what was skipped. Never report a gate as passed without having run it. diff --git a/codex/skills/work-story/SKILL.md b/codex/skills/work-story/SKILL.md index 05005e7..59b0ec6 100644 --- a/codex/skills/work-story/SKILL.md +++ b/codex/skills/work-story/SKILL.md @@ -68,6 +68,12 @@ Run **`issue-update`**: comment a product-facing summary (plain language) plus t and transition the ticket to the team's review status. The story isn't done until the tracker reflects it. +## 8. Track follow-ups (offer — never force) +If the story left **loose ends** (out-of-scope notes in the PR, deferred `pr-review`/`fix-pr` +findings, deliberate TODOs), run **`follow-ups`**: offer to create them as tracked work items +linked to this story. Approval-gated — present the list, create nothing until approved; the +user may edit or skip. No genuine loose ends → say so and skip. Never fabricate follow-ups. + ## Reporting At every step, state plainly what passed, what failed (with output), and what was skipped. Never report a gate as passed without having run it. diff --git a/plugins/fullstack-dev-kit/.codex-plugin/plugin.json b/plugins/fullstack-dev-kit/.codex-plugin/plugin.json index 70904a7..6cf2bd2 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.9", + "version": "0.19.10", "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 dc4f1a4..03f0061 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.9", + "version": "0.19.10", "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 8126167..9c3bfca 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.9", + "version": "0.19.10", "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/follow-ups/SKILL.md b/plugins/fullstack-dev-kit/skills/follow-ups/SKILL.md new file mode 100644 index 0000000..849fed8 --- /dev/null +++ b/plugins/fullstack-dev-kit/skills/follow-ups/SKILL.md @@ -0,0 +1,60 @@ +--- +name: follow-ups +description: Turn the loose ends a finished story leaves — out-of-scope notes, deferred review findings, deliberate TODOs — into tracked follow-up work items in the team's tracker, linked to the source story, after approval. Supports Jira, Linear, GitHub Issues, and Azure DevOps via adapters. Use at the end of a story, or when the user asks to track follow-ups. +--- + +# Follow-ups + +Close the loop: when a story finishes, the loose ends it surfaced should be **tracked**, not just described in the PR body. This skill turns them into real work items in the configured tracker, **linked back to the source story** — created only after approval. It's the tracking counterpart to the "Out of scope / follow-ups" section `create-pr` already writes. + +## Preconditions + +- `.claude/dev-kit.json` exists with a `tracker` block (otherwise run `dev-kit-setup` first). +- The adapter's backend is authenticated (MCP connector authorized, or `gh`/`az` logged in) — otherwise tell the user how to authenticate and stop. +- The **source story key** (the item just delivered) is known, for linking. If unknown, ask once. + +## 1. Gather the loose ends — only real ones + +Collect follow-ups from the story just finished, from where they were already surfaced: +- the **"Out of scope / follow-ups"** list in the `create-pr` PR body, +- **deferred review findings** from `fix-pr` / `pr-review` (the "defer to a tracked issue" bucket), +- deliberate **TODOs / known gaps** the implementation left. + +**Never invent follow-ups.** If there are none, say so and stop — don't pad a backlog to look thorough. + +## 2. Propose — WAIT FOR APPROVAL + +For each loose end, propose a work item: +- **Type**: default **Task**; use a **User Story** when it's a user-facing increment (ask if unsure). +- **Title** + a one-line description + **why** (the context from the story that produced it). +- **Link** to the source story (and its epic/parent when there is one) for traceability. +- A sizing hint or label when the team uses them (discover, don't assume). + +Present the full list and **wait for explicit approval**; the user may edit or drop items. **Create nothing until approved.** + +## 3. Create — via the tracker's write adapter + +Create each approved item and link it to the source story. Verify writes by read-back where the CLI can silently no-op. + +### Jira (`type: "jira"`) — Atlassian MCP +`createJiraIssue` for each item (project, type, summary, description, labels); link to the source with `createIssueLink` ("Relates to", or a sub-task under the story when appropriate). + +### Linear (`type: "linear"`) — Linear MCP +Create the issue under the team; relate it to the source (relation or sub-issue); set labels/estimate. + +### GitHub Issues (`type: "github"`) — `gh` +`gh issue create --repo --title --body-file - --label `, referencing the source in the body (`Follow-up of #` / a task-list link). **Verify by read-back** (`gh issue view --json labels`) and apply labels via REST on a miss (classic-Projects orgs can silently no-op). + +### Azure DevOps (`type: "azure"`) — `az boards` / MCP +`az boards work-item create --type "Task|User Story" ...`; link to the source with `az boards work-item relation add` (Related / Parent). + +## 4. Report + +List each created item with its key/URL, and record them where the story lives — add a **"Follow-ups tracked: ``"** line to the PR and/or the tracker comment so the trail is visible. On partial failure, report exactly what was created and what wasn't. + +## Guardrails + +- **Never create anything before approval.** +- **Only genuine loose ends** from the work — no fabricated backlog. +- **Always link** to the source story for traceability. +- Watch for secrets/PII in the source material; don't copy them into tickets. diff --git a/plugins/fullstack-dev-kit/skills/work-story/SKILL.md b/plugins/fullstack-dev-kit/skills/work-story/SKILL.md index 05005e7..59b0ec6 100644 --- a/plugins/fullstack-dev-kit/skills/work-story/SKILL.md +++ b/plugins/fullstack-dev-kit/skills/work-story/SKILL.md @@ -68,6 +68,12 @@ Run **`issue-update`**: comment a product-facing summary (plain language) plus t and transition the ticket to the team's review status. The story isn't done until the tracker reflects it. +## 8. Track follow-ups (offer — never force) +If the story left **loose ends** (out-of-scope notes in the PR, deferred `pr-review`/`fix-pr` +findings, deliberate TODOs), run **`follow-ups`**: offer to create them as tracked work items +linked to this story. Approval-gated — present the list, create nothing until approved; the +user may edit or skip. No genuine loose ends → say so and skip. Never fabricate follow-ups. + ## Reporting At every step, state plainly what passed, what failed (with output), and what was skipped. Never report a gate as passed without having run it. diff --git a/skills/follow-ups/SKILL.md b/skills/follow-ups/SKILL.md new file mode 100644 index 0000000..849fed8 --- /dev/null +++ b/skills/follow-ups/SKILL.md @@ -0,0 +1,60 @@ +--- +name: follow-ups +description: Turn the loose ends a finished story leaves — out-of-scope notes, deferred review findings, deliberate TODOs — into tracked follow-up work items in the team's tracker, linked to the source story, after approval. Supports Jira, Linear, GitHub Issues, and Azure DevOps via adapters. Use at the end of a story, or when the user asks to track follow-ups. +--- + +# Follow-ups + +Close the loop: when a story finishes, the loose ends it surfaced should be **tracked**, not just described in the PR body. This skill turns them into real work items in the configured tracker, **linked back to the source story** — created only after approval. It's the tracking counterpart to the "Out of scope / follow-ups" section `create-pr` already writes. + +## Preconditions + +- `.claude/dev-kit.json` exists with a `tracker` block (otherwise run `dev-kit-setup` first). +- The adapter's backend is authenticated (MCP connector authorized, or `gh`/`az` logged in) — otherwise tell the user how to authenticate and stop. +- The **source story key** (the item just delivered) is known, for linking. If unknown, ask once. + +## 1. Gather the loose ends — only real ones + +Collect follow-ups from the story just finished, from where they were already surfaced: +- the **"Out of scope / follow-ups"** list in the `create-pr` PR body, +- **deferred review findings** from `fix-pr` / `pr-review` (the "defer to a tracked issue" bucket), +- deliberate **TODOs / known gaps** the implementation left. + +**Never invent follow-ups.** If there are none, say so and stop — don't pad a backlog to look thorough. + +## 2. Propose — WAIT FOR APPROVAL + +For each loose end, propose a work item: +- **Type**: default **Task**; use a **User Story** when it's a user-facing increment (ask if unsure). +- **Title** + a one-line description + **why** (the context from the story that produced it). +- **Link** to the source story (and its epic/parent when there is one) for traceability. +- A sizing hint or label when the team uses them (discover, don't assume). + +Present the full list and **wait for explicit approval**; the user may edit or drop items. **Create nothing until approved.** + +## 3. Create — via the tracker's write adapter + +Create each approved item and link it to the source story. Verify writes by read-back where the CLI can silently no-op. + +### Jira (`type: "jira"`) — Atlassian MCP +`createJiraIssue` for each item (project, type, summary, description, labels); link to the source with `createIssueLink` ("Relates to", or a sub-task under the story when appropriate). + +### Linear (`type: "linear"`) — Linear MCP +Create the issue under the team; relate it to the source (relation or sub-issue); set labels/estimate. + +### GitHub Issues (`type: "github"`) — `gh` +`gh issue create --repo --title --body-file - --label `, referencing the source in the body (`Follow-up of #` / a task-list link). **Verify by read-back** (`gh issue view --json labels`) and apply labels via REST on a miss (classic-Projects orgs can silently no-op). + +### Azure DevOps (`type: "azure"`) — `az boards` / MCP +`az boards work-item create --type "Task|User Story" ...`; link to the source with `az boards work-item relation add` (Related / Parent). + +## 4. Report + +List each created item with its key/URL, and record them where the story lives — add a **"Follow-ups tracked: ``"** line to the PR and/or the tracker comment so the trail is visible. On partial failure, report exactly what was created and what wasn't. + +## Guardrails + +- **Never create anything before approval.** +- **Only genuine loose ends** from the work — no fabricated backlog. +- **Always link** to the source story for traceability. +- Watch for secrets/PII in the source material; don't copy them into tickets.