feat(skills): follow-ups — track a story's loose ends as linked tickets (#67)

.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",

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 <idea | path/to/brief.pdf | URL>`) 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.

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)

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.

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.

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",

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"

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",

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 <owner/name> --title <t> --body-file - --label <type>`, referencing the source in the body (`Follow-up of #<n>` / 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: `<keys>`"** 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.

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.

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 <owner/name> --title <t> --body-file - --label <type>`, referencing the source in the body (`Follow-up of #<n>` / 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: `<keys>`"** 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.