@benjaminthomas/spec-driven-dev 1.16.4 → 1.17.0

package/README.md

@@ -190,6 +190,20 @@ changes. From a terminal: `spec-driven-dev setup --join=../soreto-specs`. Changi
 edit to `team.yml` and a commit, and anything set in your own file overrides it for you only (`doctor`
 lists those overrides). An existing setup can be converted with `spec-driven-dev team init`.
 
+**After the PR is reviewed.** When reviewers leave comments, say "address the PR comments". Each
+comment is checked against the code and sorted (fix, scope change, question, disagree, nit), and you
+choose which to act on. The changes then go through the stages again (implement → verify → review →
+checkpoint → ship) onto the same PR, never as a quick push. A comment that changes the requirements
+updates the spec and waits for your approval first. Replies go on each thread once you've seen them.
+
+**The ticket keeps up with the work.** When your AI tool can reach the tracker (a Jira/Atlassian,
+GitHub or Linear MCP server, or `gh`/`acli`), the pipeline updates the ticket: investigate comments
+with the summary, implement moves it to *In Progress*, verify comments with each acceptance criterion
+and its pass/fail, review with the blocker count, and ship moves it to *In Review* with the PR link.
+Status names come from your project's real workflow (asked once, saved in `team.yml`); it never closes
+a ticket. It asks before the first update on each ticket; say "update Jira without asking" or "stop
+updating Jira" to change that (`tracker.updates: on | ask | off`).
+
 **For scripts and CI** there's `spec-driven-dev setup` with flags (it asks nothing):
 `--yes`, `--layout=multi-repo --repos=~/Projects/frontend,~/Work/backend --workspace=~/Projects`,
 `--layout=monorepo --packages=apps/web,packages/ui`, `--specs-dir=<path>`, `--share=all|memory|none`,
@@ -787,16 +801,16 @@ skips that step rather than failing.
 
 | Skill | Stage | SKILL.md lines | Words | Supporting files |
 |---|---|---:|---:|---:|
-| `spec-setup` | 0 · configure | 308 | 3,393 | 4 |
-| `spec-investigate` | 1 · understand | 387 | 3,391 | 1 |
+| `spec-setup` | 0 · configure | 311 | 3,468 | 5 |
+| `spec-investigate` | 1 · understand | 392 | 3,429 | 1 |
 | `spec-create` | 2 · plan | 198 | 1,806 | 6 |
-| `spec-implement` | 3 · build | 327 | 2,777 | 3 |
-| `spec-verify` | 4 · prove | 163 | 1,581 | 1 |
-| `spec-review` | 5 · review | 137 | 1,318 | 1 |
+| `spec-implement` | 3 · build | 330 | 2,813 | 3 |
+| `spec-verify` | 4 · prove | 166 | 1,610 | 1 |
+| `spec-review` | 5 · review | 179 | 1,817 | 1 |
 | `spec-checkpoint` | 6 · commit | 140 | 1,168 | 0 |
-| `spec-ship` | 7 · PR | 230 | 1,412 | 0 |
+| `spec-ship` | 7 · PR | 238 | 1,494 | 0 |
 | `generative-seo` | standalone | 255 | 2,209 | 7 |
-| **Total** | | **2,145** | **19,055** | **23** |
+| **Total** | | **2,209** | **19,814** | **24** |
 
 - **8** skills: **1** setup + **6** workflow stages + **1** standalone
 - **4** tools supported natively (Claude Code, Codex CLI, Cursor, Antigravity), plus an MCP fallback

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@benjaminthomas/spec-driven-dev",
-  "version": "1.16.4",
+  "version": "1.17.0",
   "description": "Spec-driven AI development workflow (investigate → spec → implement → verify → review → ship) as Agent Skills for Claude Code, Cursor, Codex CLI and Antigravity.",
   "type": "module",
   "bin": {

package/plugin/.claude-plugin/plugin.json

@@ -1,6 +1,6 @@
 {
   "name": "ticket-to-pr",
-  "version": "1.16.4",
+  "version": "1.17.0",
   "description": "Parallel-batch spec-driven feature workflow (spec-setup, spec-investigate, spec-create, spec-implement, spec-verify, spec-review, spec-checkpoint, spec-ship) plus a portable SEO/GEO operations skill (generative-seo) for any codebase.",
   "author": {
     "name": "Benjamin Thomas",

package/plugin/skills/spec-implement/SKILL.md

@@ -86,6 +86,9 @@ This structure is produced by the `spec-create` skill. If the user doesn't have
 4. Determine the **current batch**: the first batch that has any incomplete tasks
 5. If all tasks in all batches are complete, report "All tasks complete!" and stop
 
+6. **Tracker update** (first batch only, when it came from a ticket and `tracker.updates` isn't
+   `off`): follow `tracker-updates.md` in the installed `spec-setup` skill's references folder and move the ticket to its `start` status. No comment here.
+
 This makes the skill **resumable** — if invoked on a partially completed spec, it picks up exactly where it left off.
 
 ### Step 2: Process Each Batch

package/plugin/skills/spec-investigate/SKILL.md

@@ -355,6 +355,11 @@ evidence points to — reusing existing patterns the investigation actually foun
 architecture invented on the spot. It is not permission to start building; flag any business
 decision it depends on.
 
+## Step 9b — Tracker update
+
+If the work came from a ticket and `tracker.updates` isn't `off`, follow `tracker-updates.md` in the installed `spec-setup` skill's references folder: post the
+investigation summary as a comment. Don't change the status here.
+
 ## Step 10 — Stop, hand off, don't bleed into the next stage
 
 Report completion plainly:

package/plugin/skills/spec-review/SKILL.md

@@ -8,7 +8,10 @@ description: >
   blockers. Use after spec-verify, when the user says "review this", "code review", "review the
   branch", "review PR #42", "is this ready to merge", or "/spec-review". Also works with no spec
   folder, on any branch, diff, or pull request, including a teammate's. Reports findings and offers
-  fixes; it changes code only after the user says yes, through spec-implement's fix loop.
+  fixes; it changes code only after the user says yes, through spec-implement's fix loop. Also
+  handles the reviewers' comments once the PR is open ("address the PR comments", "the PR got
+  review feedback", "changes requested on PR #42"): triages them, then runs the changes back
+  through implement → verify → review → checkpoint → ship on the same PR.
 license: MIT
 ---
 
@@ -99,6 +102,9 @@ Write `{specs_dir}/{feature}/review.md` using `references/report-template.md`. W
 | **nit** | small and optional | listed once, never blocks |
 | **question** | needs the author's intent to judge | asked, never blocks |
 
+**Tracker update.** If the work came from a ticket and `tracker.updates` isn't `off`,
+follow `tracker-updates.md` in the installed `spec-setup` skill's references folder: post the severity counts and each blocker as a comment.
+
 Then append one line to `log.md` (counts per severity) and overwrite the README's **Resume here**:
 `Stage: reviewed (B blockers, S should-fix)`, `Next: fix blockers` or `Next: spec-checkpoint`.
 
@@ -119,6 +125,42 @@ Fix the blockers and should-fix items now? (y / pick numbers / n)
 - **Someone else's PR:** never push to their branch. Offer to post the findings as PR review
   comments (`gh pr review`), and do it only after the user says yes and has seen the text.
 
+## PR feedback (after the PR is open)
+
+When reviewers comment on the PR ("address the PR comments", "changes requested on #42"), the
+changes go through the pipeline again, on the same branch and the same PR. Never push a quick fix
+straight to the PR.
+
+1. **Collect.** `gh pr view <n> --json number,url,reviewDecision,reviews,comments` plus the inline
+   threads (`gh api graphql` for `reviewThreads` with `isResolved`, `path`, `line`, `comments`).
+   Keep only unresolved threads and review bodies after the last push.
+2. **Triage each one, checked against the code** (same rule as the passes above):
+   - **fix**: a real problem in what was built. Becomes a fix item.
+   - **scope change**: asks for something the spec didn't cover, or changes a requirement.
+     Add it to `requirements.md` as a new R-id marked `(from PR review, <reviewer>)`, update the
+     affected task files, and **stop for the user's approval of the spec**, as after spec-create.
+   - **question**: answer it from the code and the spec; no change.
+   - **disagree**: you think the current code is right. Say why with evidence; the user decides.
+   - **nit**: small and optional.
+   Show the list numbered, with the reviewer and `path:line`, and ask which to act on. Never
+   dismiss a reviewer's comment silently.
+3. **Run the stages again** for the chosen items:
+   `spec-implement` (fix loop, one round, grouped by task) → `spec-verify` (the criteria the
+   changes touch, plus lint, typecheck and tests) → this skill on the changed lines only →
+   `spec-checkpoint` → `spec-ship`, which pushes to the existing PR instead of opening a new one.
+   In stop mode, pause after each stage as usual. A blocker found on the way stops it.
+4. **Reply on the PR** after the push, only on a yes and after the user has seen the text: one
+   reply per thread saying what changed and the commit (`fixed in abc1234: …`), or the answer.
+   Don't resolve threads; that's the reviewer's call. Then ask the reviewers again
+   (`gh pr edit <n> --add-reviewer …`) if the user wants.
+5. **Record.** Add a `## PR feedback, round N` section to `review.md` (each comment, its triage,
+   the outcome). Append one line to `log.md`, and overwrite **Resume here**:
+   `Stage: PR feedback round N (F fixes, S scope changes)`, `Next: <the stage it's at>`.
+6. **Tracker update** (`tracker.updates` not `off`): follow `tracker-updates.md` in the installed
+   `spec-setup` skill's references folder. Comment "review feedback round N addressed: …"
+   with the counts and the commit. If people moved the ticket back (e.g. to *In Progress*),
+   spec-ship moves it to `review` again when it pushes.
+
 ## Run-through
 
 In run-through mode (see `spec-implement`), this runs after verify passes. **Any blocker stops the

package/plugin/skills/spec-setup/SKILL.md

@@ -204,7 +204,8 @@ evidence in the description, then the common alternatives:
 `Jira, key STP (Recommended)`: "STP-123 in recent branches", `GitHub Issues`, `Linear`, `None`), then
 sharing (if specs are inside a repo), after approval (stop / run straight through), and any command
 that's a guess (e.g. typecheck). At most 4; a guessed command that doesn't fit goes in the summary as
-"I'll use X, say if that's wrong".
+"I'll use X, say if that's wrong". Don't ask about tracker updates: they default to `ask`, so the
+first update on each ticket is confirmed then. Mention it in one line of the summary.
 
 Then the open questions, as plain text (see How to ask).
 
@@ -284,6 +285,8 @@ keep every other line and comment, and confirm in one sentence. Don't re-run dis
 | "run straight through after I approve", "fewer stops" | `pipeline.after_approval: run-through` |
 | "stop after each stage" | `pipeline.after_approval: stop` |
 | "change our branch rules", "use main for PRs" (when `team.yml` exists) | edit `team.yml`, since it's a team rule, and remind them to commit it; only change `.spec-driven.yml` if they say it's just for them |
+| "stop updating Jira", "don't comment on tickets", "update Jira without asking" | `tracker.updates: off` / `on` (default `ask`), in `team.yml` when it exists; see `references/tracker-updates.md` |
+| "our statuses are To Do / Doing / Code Review" | `tracker.statuses.start` / `.review`, from the project's real transitions |
 | "add reverb-react to the workspace", "I also work on X" | check each named repo first and say what you found, per repo: **already in the workspace** (change nothing for it), **in `team-repos.yml` but not cloned here** (offer the `git clone`), **not found** (ask for its path), or **new**. For new ones: add under `repos:` and to `team-repos.yml` if new to the team, audit only that repo and add its areas to `CONTEXT.md` (Step 4), re-run `spec-driven-dev risk`, offer the pointer line for it (Step 4, item 5), then `doctor` |
 | "share the specs with the team", "keep specs local", "share only the project memory" | `context.share: all / none / memory`: show the `.gitignore` change, then run `spec-driven-dev settings --share=…` on a yes |
 

package/plugin/skills/spec-setup/references/config-template.yml

@@ -26,6 +26,8 @@ tracker:
   type: jira                    # jira | github | linear | none
   key: STP                      # ticket key prefix (jira/linear); omit for github/none
   url: https://example.atlassian.net   # site/org/repo URL, if any
+  updates: ask                  # move the ticket and post stage comments when a tracker tool is connected: ask | on | off
+  # statuses: { start: In Progress, review: In Review }   # filled from the project's real workflow on first use
 
 git:
   remote: origin

package/plugin/skills/spec-setup/references/tracker-updates.md

@@ -0,0 +1,60 @@
+# Tracker updates (status and comments)
+
+When a tracker tool is connected (a Jira/Atlassian, GitHub or Linear MCP server, or the `gh`, `acli`
+or `jira` CLI), the pipeline keeps the ticket in step with the work, so the team can see in the
+tracker that it was investigated, verified and reviewed. Every pipeline skill follows these rules.
+
+## Settings (`tracker.updates` in team.yml or .spec-driven.yml)
+
+```yaml
+tracker:
+  updates: ask        # ask (default) | on | off
+  statuses:           # this project's real status names; leave a stage out to never move it
+    start: In Progress     # when implementation starts
+    review: In Review      # when the PR is open
+```
+
+- `off`: never write to the tracker. `ask`: confirm the first write for each ticket, then go on
+  for the rest of that ticket. `on`: write without asking.
+- Never post anything when there's no ticket (no tracker, or the work started from a doc or a
+  description).
+
+## Statuses: read, never guess
+
+Workflows differ in every team. The first time a move is needed and `tracker.statuses` is unset,
+read the ticket's real transitions (Jira: `getTransitionsForJiraIssue`; Linear: the team's states;
+GitHub: labels or a Projects status field, if the team uses one), propose a mapping for `start`
+and `review`, and save it to `team.yml` (shared) on a yes. Move a ticket only along a transition
+it offers right now. Never move it backwards, never close it or mark it Done (that's for
+people, after merge), and never move a ticket assigned to someone else without asking.
+
+## When to write
+
+| Stage | Status | Comment |
+|---|---|---|
+| spec-investigate done | — | summary: root cause or approach, repos affected, top risks, open questions |
+| spec-implement starts | `start` | — |
+| spec-verify done | — | each acceptance criterion with pass/fail and one line of evidence; overall N of M pass |
+| spec-review done | — | blocker / should-fix / nit counts, and each blocker in one line |
+| spec-ship done | `review` | PR link, plus "verified N/M, review: no blockers" |
+| PR feedback round done | `review` (only if people moved it back) | "review feedback round N addressed": fixes, scope changes, commit |
+
+One comment per stage. A rerun replaces nothing: it posts a new, shorter comment saying what
+changed ("re-verified after fix: 12/12 pass").
+
+## What a comment looks like
+
+Short, factual, readable by someone who never saw the spec. Start with the stage and the result,
+then at most 8 lines. Name file paths, never paste code, secrets, tokens, customer data or env
+values. Example:
+
+> **Verified (spec-driven-dev)**: 11 of 12 acceptance criteria pass.
+> - ✓ R1 discount applies at checkout (dev store, order #1043)
+> - ✗ R4 email copy: still shows the old text (screenshot in verification-report.md)
+> Spec: `soreto-specs/STP-123/`
+
+## Failure and fallback
+
+- No tracker tool connected, or a write fails: don't retry in a loop and don't block the stage.
+  Print the comment text so the user can paste it, and say which status change didn't happen.
+- Record each write in `log.md` (`tracker: moved to In Progress`, `tracker: posted verify comment`).

package/plugin/skills/spec-ship/SKILL.md

@@ -199,10 +199,18 @@ EOF
 )"
 ```
 
+After the report, tell the user the next step: when reviewers leave comments, say "address the PR
+comments", which runs them back through the pipeline (spec-review's **PR feedback**). A push for
+a feedback round goes to the existing PR (Step 6).
+
 If this branch belongs to a spec, overwrite its README's **Resume here** (`Stage: PR open`,
 `Next: review`, the PR URL) and append one line to `log.md`. Commit that only if the user
 agrees; otherwise leave it for the next checkpoint.
 
+**Tracker update.** If the branch came from a ticket and `tracker.updates` isn't `off`,
+follow `tracker-updates.md` in the installed `spec-setup` skill's references folder: move the ticket to its `review` status and comment with the PR link and the verify and
+review results.
+
 ### Step 8: Report
 
 Display the result clearly:

package/plugin/skills/spec-verify/SKILL.md

@@ -147,6 +147,9 @@ exact structure (a summary line, then a table of criterion → source → verdic
 Update `specs/{feature}/README.md` with a short **Verification** section linking to the report
 and stating the overall status (all pass / N of M pass).
 
+**Tracker update.** If the spec came from a ticket and `tracker.updates` isn't `off`,
+follow `tracker-updates.md` in the installed `spec-setup` skill's references folder: post the per-criterion result as a comment.
+
 Then tell the user directly:
 
 ```