agileflow 3.4.3 → 4.0.0-alpha.10

package/content/plugins/core/skills/agileflow-epic-planner/SKILL.md

@@ -0,0 +1,209 @@
+---
+name: agileflow-epic-planner
+version: 2.0.0
+category: agileflow/core
+description: |
+  Use when a user describes a large feature, multi-sprint initiative,
+  or theme that won't fit in a single user story. Breaks the work into
+  scoped epics with milestones, story groupings, dependencies, and
+  rough estimates; writes the epic file under docs/05-epics/.
+triggers:
+  keywords:
+    - epic
+    - initiative
+    - theme
+    - multi-month project
+    - big feature
+    - break this down
+    - too big for one story
+    - phased rollout
+  priority: 50
+  exclude:
+    - epic fail
+    - epic story (the genre)
+    - mythological epic
+provides:
+  agents:
+    - agileflow-epic-planner
+learns:
+  enabled: true
+  file: _learnings/epic-planner.yaml
+  maxEntries: 50
+depends:
+  skills: []
+  plugins: [core]
+---
+
+# AgileFlow Epic Planner
+
+Turns a large feature or initiative into a properly-scoped epic — with
+milestones, story groupings, success metrics, and dependencies — and
+writes the artifact to `docs/05-epics/`.
+
+## When this skill activates
+
+- User describes a feature spanning multiple sprints (>13 story points)
+- A theme or initiative comes up ("we need a v2 of billing")
+- An existing user-story request is clearly too large
+- The user explicitly asks for an epic
+- Should NOT activate for casual mentions of "epic" as an adjective
+  ("epic fail", "epic novel") — `exclude` keywords damp those.
+
+## What this skill does
+
+1. Detect that the work is epic-scale (multiple sprints / >13 SP).
+2. Ask 3–5 clarifying questions: problem, users, timeline, success
+   metrics, out-of-scope.
+3. Break the work into 2–4 milestones (typically MVP / Feature
+   Complete / Polish), each with a logical story grouping that
+   delivers user-visible value.
+4. Estimate rough story-point totals per milestone.
+5. Identify dependencies, risks (with mitigations), and explicit
+   out-of-scope items.
+6. Show the proposed epic to the user for explicit approval.
+7. After approval, write `docs/05-epics/EP-####-<slug>.md`, append to
+   the epics index, and link from `docs/09-agents/status.json`.
+
+## Self-improving learnings
+
+`.agileflow/skills/_learnings/epic-planner.yaml` records preferences:
+milestone naming convention, default phase count, owner labelling,
+preferred risk format. Apply on invocation; update on correction with
+confidence (`high` / `medium` / `low`) per the standard pattern.
+
+## Epic format
+
+```markdown
+# [EP-0001] Title
+
+**Status**: PLANNING | ACTIVE | ON_HOLD | COMPLETED
+**Owner**: Product Owner / Team Lead
+**Start Date**: YYYY-MM-DD
+**Target Completion**: YYYY-MM-DD
+**Priority**: P0 | P1 | P2 | P3
+**Business Value**: High | Medium | Low
+
+## Problem Statement
+
+[What problem does this epic solve? Why now?]
+
+## Goals
+
+- [Specific, measurable outcome]
+- [Business or user metric to improve]
+
+## Success Metrics
+
+- [e.g., 20% increase in retention]
+- [e.g., Reduce support tickets by 30%]
+
+## User Stories
+
+### Milestone 1: MVP (Target: YYYY-MM-DD)
+
+- [ ] [US-####: Title](../06-stories/US-####.md) — 5 pts
+- [ ] [US-####: Title](../06-stories/US-####.md) — 8 pts
+      **Total: 13 story points**
+
+### Milestone 2: Feature Complete (Target: YYYY-MM-DD)
+
+- [ ] [US-####: Title](../06-stories/US-####.md) — 5 pts
+      **Total: 5 story points**
+
+## Dependencies
+
+- [What blocks the start of this epic]
+- [External team dependencies]
+
+## Risks
+
+- **Risk**: [What could go wrong] · **Impact**: [High/Med/Low] · **Mitigation**: [Plan]
+
+## Out of Scope
+
+- [Explicitly NOT in this epic]
+- [Deferred to a future epic]
+
+## Progress
+
+**Overall**: X / Y stories completed (Z%)
+**Last Updated**: YYYY-MM-DD
+```
+
+## Epic vs. story heuristic
+
+**Epic** when ALL of:
+
+- > 13 story points total
+- Spans 2+ sprints
+- Touches multiple owners (UI + API + DevOps)
+- Has distinct phases that each deliver value
+
+**Story** when any of:
+
+- ≤ 13 story points
+- One owner can complete it
+- Single sprint
+- One or two related tasks
+
+## Milestone playbook
+
+- **MVP** — minimal path to user-visible value; one happy path, no
+  edge cases beyond the obvious.
+- **Feature Complete** — all planned functionality, edge cases handled,
+  documented.
+- **Polish** — performance, UX refinement, accessibility, telemetry.
+
+## Sizing guidelines
+
+- **Small epic**: 15–30 SP (1–2 sprints)
+- **Medium epic**: 30–60 SP (2–4 sprints)
+- **Large epic**: 60–100 SP (4–6 sprints)
+- **Initiative**: > 100 SP — split into multiple epics
+
+## Quality checklist
+
+- [ ] Problem statement is concrete (not "improve UX")
+- [ ] At least 2 milestones, each delivering value independently
+- [ ] Success metrics are measurable
+- [ ] Stories are grouped, not just listed
+- [ ] Dependencies identified
+- [ ] Risks have mitigations
+- [ ] Out-of-scope is explicit
+- [ ] User approved diff before file write
+
+## Integration
+
+- **agileflow-story-writer** — creates the individual stories under each milestone; epic-planner defines the skeleton, story-writer fills in AC and estimates
+- **agileflow-status-updater** — flips the epic between PLANNING / ACTIVE / COMPLETED as milestones land
+- **agileflow-adr** — links major technical decisions made during the epic; create ADRs for database choice, API design, or architecture decisions before writing stories
+- **agileflow-council** — convene before planning a large or ambiguous epic to resolve strategic direction; council output shapes the epic's goal and milestone structure
+- **agileflow-research** — use before planning to gather technical context for unfamiliar problem domains; avoids planning stories around incorrect assumptions
+- **agileflow-planning** — use for capacity planning and sprint allocation after the epic is defined; epic-planner sets the scope, planning fits it into delivery windows
+- **agileflow-ideation** — large ideas produced by ideation become epics; route the top-ranked ideation output here to give it structure and milestones
+- **agileflow-babysit-mentor** — mentor is the primary executor of planned epics; a well-structured epic with ready stories makes mentor-guided execution reliable
+
+## Notes
+
+- Epics are living documents — update milestone targets as the team
+  learns, don't over-plan up front.
+- Don't author every story in detail at epic creation — write skeletons
+  and let `agileflow-story-writer` fill them in as work begins.
+- Celebrate milestone completions — the epic file is the canonical
+  place to record what shipped.
+
+## References
+
+Load these files when you need deeper context for the relevant task:
+
+| File                              | When to load                                                                                         |
+| --------------------------------- | ---------------------------------------------------------------------------------------------------- |
+| `references/epic-sizing-guide.md` | Deciding if work is epic-scale, sizing milestones, estimating total effort, structuring dependencies |
+
+## Workflows
+
+Follow these step-by-step when the user initiates the matching action:
+
+| File                     | When to follow                                                                                                               |
+| ------------------------ | ---------------------------------------------------------------------------------------------------------------------------- |
+| `workflows/plan-epic.md` | User describes a large feature or asks to break down an initiative — clarifies, designs milestones, drafts epic, writes file |

package/content/plugins/core/skills/agileflow-epic-planner/references/epic-sizing-guide.md

@@ -0,0 +1,81 @@
+# Epic Sizing Guide
+
+**Load this when:** deciding if work needs an epic vs a story, sizing milestones,
+or estimating an epic's total effort.
+
+## Epic vs story decision
+
+| Signal           | Epic                                   | Story              |
+| ---------------- | -------------------------------------- | ------------------ |
+| Estimated effort | > 13 story points                      | ≤ 13 story points  |
+| Spans sprints    | 2+ sprints                             | 1 sprint           |
+| Owners           | Multiple (UI + API + DevOps)           | One owner          |
+| Phases           | Distinct phases, each delivering value | Single deliverable |
+| User value       | Multiple checkpoints                   | One outcome        |
+
+**When in doubt:** if you can't describe the whole thing in one user story sentence ("As a [user] I want [X] so that [Y]"), it's an epic.
+
+## Milestone playbook
+
+| Phase                | What ships                                           | Acceptance bar                            |
+| -------------------- | ---------------------------------------------------- | ----------------------------------------- |
+| **MVP**              | One happy path, core user value, no edge cases       | A real user can complete the primary flow |
+| **Feature Complete** | All planned functionality, edge cases, documented    | QA can sign off                           |
+| **Polish**           | Performance, UX refinement, accessibility, telemetry | Metrics and error rates within targets    |
+
+Not every epic needs all three phases — small epics often go MVP → Feature Complete only.
+
+## Sizing benchmarks
+
+| Epic size  | Story points | Sprints (2-week) | Team size                 |
+| ---------- | ------------ | ---------------- | ------------------------- |
+| Small      | 15–30 SP     | 1–2              | 1 engineer                |
+| Medium     | 30–60 SP     | 2–4              | 1–2 engineers             |
+| Large      | 60–100 SP    | 4–6              | 2–3 engineers             |
+| Initiative | > 100 SP     | 6+               | Split into multiple epics |
+
+If an epic exceeds 100 SP at planning time, split it. Epics that large never finish as planned.
+
+## Story grouping within milestones
+
+Group stories by the layer they touch, then by delivery order:
+
+```
+Milestone 1: MVP
+  Infrastructure layer (must go first — others depend on it)
+    US-0041: Create sessions table migration — 3 pts
+    US-0042: Implement session token service — 5 pts
+  Feature layer
+    US-0043: Add login endpoint — 5 pts
+  Total: 13 pts
+```
+
+## Dependencies: how to surface them
+
+For each epic, identify:
+
+- **Blocking epics**: what must complete before this can start
+- **Blocking stories within the epic**: stories that must land before others
+- **External blockers**: third-party API access, design assets, legal review
+
+Write dependencies as explicit statements: "Blocked by EP-0010 (auth infrastructure)" not "depends on auth."
+
+## Risk categories
+
+| Category                   | Examples                                       | Mitigation                                     |
+| -------------------------- | ---------------------------------------------- | ---------------------------------------------- |
+| **Technical unknowns**     | First time using a library, unfamiliar pattern | Spike story in Milestone 1                     |
+| **External dependency**    | Waiting on another team, third-party API       | Early integration test, fallback plan          |
+| **Scope creep**            | "While we're here..."                          | Explicit out-of-scope section                  |
+| **Estimation uncertainty** | >30% of stories are novel                      | Build in buffer; re-estimate after Milestone 1 |
+
+## Out-of-scope: what to include
+
+Explicitly list what this epic does NOT cover. This prevents scope creep and sets expectations.
+
+Good out-of-scope examples:
+
+- "Mobile app — web only for this epic"
+- "Admin dashboard — tracked separately in EP-0022"
+- "Multi-language support — deferred to v2"
+- "Offline mode — requires separate infrastructure investment"

package/content/plugins/core/skills/agileflow-epic-planner/workflows/plan-epic.md

@@ -0,0 +1,55 @@
+# Plan Epic Workflow
+
+**Triggers:** "create an epic", "break this down", "this is too big for one story", user describes a multi-sprint feature or initiative
+
+**Goal:** Produce a scoped epic with milestones, story groupings, dependencies, and rough estimates, written to `docs/05-epics/`.
+
+## Inputs needed
+
+| Input                | Required | How to get it                                                |
+| -------------------- | -------- | ------------------------------------------------------------ |
+| Feature description  | Yes      | Usually in the user's message                                |
+| Problem being solved | Yes      | Ask: "What user problem or business goal does this address?" |
+| Success metrics      | Yes      | Ask: "How will you know it worked?"                          |
+| Timeline or deadline | No       | Ask if not mentioned                                         |
+| Out-of-scope         | No       | Ask: "Anything explicitly NOT in this?"                      |
+
+## Steps
+
+1. **Assess if it's epic-scale** — use `references/epic-sizing-guide.md`. If it's ≤13 SP and fits one sprint, suggest a story instead.
+
+2. **Ask 3–5 clarifying questions** if key inputs are missing. Don't ask for everything — prioritize: problem statement > success metrics > out-of-scope > timeline.
+   Present as: "Before I plan this out, a few questions: [list]"
+
+3. **Find the next epic number** — read `docs/05-epics/` for the highest existing EP-#### number. Start at EP-0001 if the directory is empty or missing.
+
+4. **Design the milestones** — usually 2–3 phases using the MVP → Feature Complete → Polish pattern. Each milestone must deliver standalone user value.
+
+5. **Group stories per milestone** — write story skeletons (title + rough points), don't author full story files yet. Dependency order within milestones.
+
+6. **Draft the full epic** — write inline using the epic format from the SKILL.md. Show the complete draft to the user before writing any file.
+
+7. **Present options to the user:**
+   - Write epic to `docs/05-epics/EP-####-<slug>.md`
+   - Revise the draft
+   - Also create the story skeletons now
+
+8. **Write the file** only after explicit confirmation.
+
+9. **Offer next step:** "Would you like me to create the story files for Milestone 1 now, or start working on the first story directly?"
+
+## Output
+
+- Epic file: `docs/05-epics/EP-####-<slug>.md`
+- (Optional) Story skeleton files under `docs/06-stories/`
+
+## Fallbacks
+
+**If interactive prompts (AskUserQuestion) are unavailable:**
+Present options as a numbered list in your response. Ask the user to reply with a number.
+
+```
+1. Write EP-0007 to docs/05-epics/EP-0007-user-notifications.md (Recommended)
+2. Revise the draft — describe what to change
+3. Write epic + create Milestone 1 story files
+```

package/content/plugins/core/skills/agileflow-status-updater/SKILL.md

@@ -0,0 +1,148 @@
+---
+name: agileflow-status-updater
+version: 1.0.0
+category: agileflow/core
+description: |
+  Use when a user reports progress on a story or epic — finishing
+  work, blocking, picking up — and wants the agile state updated.
+  Mutates docs/09-agents/status.json + the relevant story / epic
+  files in place, with a diff shown for explicit approval.
+triggers:
+  keywords:
+    - mark this story
+    - mark this epic
+    - update the status
+    - i finished
+    - i'm blocked on
+    - move to in progress
+    - status to ready
+    - status to complete
+    - story status
+    - epic status
+  priority: 50
+  exclude:
+    - status quo
+    - status report (use `agileflow-story-writer` for new artifacts)
+provides:
+  agents: []
+learns:
+  enabled: false
+depends:
+  skills: []
+  plugins: [core]
+---
+
+# AgileFlow Status Updater
+
+Single source of truth for the project's agile state lives at
+`docs/09-agents/status.json` (epics, stories, owner, status,
+timestamps). This skill applies status mutations from natural-language
+progress updates without the user editing JSON by hand.
+
+## When this skill activates
+
+- User says they've started, blocked, finished, or paused a story
+- User wants to flip an epic between PLANNING / ACTIVE / COMPLETED
+- User asks for a story or epic to be reassigned
+- User wants to roll back a status change
+- Should NOT activate for unrelated mentions of "status" (`status quo`,
+  Slack "status emoji") — `exclude` damps those.
+
+## What this skill does
+
+1. Identify the target: which story (US-####) or epic (EP-####), and
+   which fields are changing (status, owner, blocked_reason, completed,
+   notes).
+2. Validate the transition against the workflow:
+   - Stories: `ready` → `in_progress` → `review` → `complete` (or
+     `blocked` from any forward state, returning to where it left off)
+   - Epics: `PLANNING` → `ACTIVE` → `COMPLETED` (with `ON_HOLD` as a
+     pause state)
+3. Show a JSON diff (before / after) of the proposed change.
+4. Wait for explicit `YES` / `NO` confirmation.
+5. After approval:
+   - Update `docs/09-agents/status.json` in place
+   - Update the frontmatter of the story/epic file (status,
+     `updated:` timestamp)
+   - If completing: set `completed:` timestamp, percentage on the parent
+     epic, append to a recent-completions section if one exists
+   - If blocking: write a `blocked_reason` and an `unblock_action`
+
+## Allowed transitions
+
+### Story states
+
+| From          | To            | Notes                                    |
+| ------------- | ------------- | ---------------------------------------- |
+| `ready`       | `in_progress` | when someone picks it up                 |
+| `in_progress` | `review`      | tests pass, ready for review             |
+| `review`      | `complete`    | reviewer signs off                       |
+| `*`           | `blocked`     | with required `blocked_reason`           |
+| `blocked`     | (previous)    | resume on unblock                        |
+| `*`           | `ready`       | reset / rollback (asks for confirmation) |
+
+### Epic states
+
+| From       | To          | Notes                                       |
+| ---------- | ----------- | ------------------------------------------- |
+| `PLANNING` | `ACTIVE`    | first story moves to `in_progress`          |
+| `ACTIVE`   | `ON_HOLD`   | pause; record reason                        |
+| `ON_HOLD`  | `ACTIVE`    | resume                                      |
+| `ACTIVE`   | `COMPLETED` | all stories `complete`; auto-prompt confirm |
+
+## Diff format (shown before write)
+
+```diff
+docs/09-agents/status.json
+- "US-0042": { "status": "ready", "owner": "AG-UI", "updated": "2026-04-25" }
++ "US-0042": { "status": "in_progress", "owner": "AG-UI", "updated": "2026-04-26" }
+
+docs/06-stories/US-0042-login-form.md (frontmatter)
+- status: ready
+- updated: 2026-04-25
++ status: in_progress
++ updated: 2026-04-26
+```
+
+## Quality checklist
+
+- [ ] Target id (US-#### / EP-####) is unambiguous
+- [ ] Transition is in the allowed table above
+- [ ] If `blocked`, `blocked_reason` captured
+- [ ] Diff shown before any write
+- [ ] User confirmed YES
+- [ ] Parent epic progress recalculated when a story completes
+
+## Integration
+
+- **agileflow-story-writer** — creates new stories (status = ready); status-updater is called immediately after to register the story in `status.json`
+- **agileflow-epic-planner** — creates new epics (status = PLANNING); status-updater tracks milestone transitions as stories complete
+- **agileflow-babysit-mentor** — babysit-mentor is the primary driver of status changes during end-to-end workflow; it calls status-updater at each phase transition
+- **agileflow-delivery** — delivery triggers status-updater to mark stories done after successful release; never mark done before the feature is shipped
+- **agileflow-planning** — sprint planning reads status to determine capacity; planning and status-updater are used together at sprint boundaries
+- **agileflow-adr** — ADR transitions (Proposed → Accepted → Deprecated) are tracked through status-updater alongside story and epic state
+
+## Notes
+
+- Always show the diff first. Status changes are persisted to a
+  shared file; silent edits are how trust dies.
+- When a transition is unusual (e.g., `complete` → `ready`), ask for
+  confirmation explicitly rather than just showing the diff.
+- Roll back any disallowed transition with a one-line explanation
+  ("`complete` → `in_progress` isn't allowed; reset to `ready` first").
+
+## References
+
+Load these files when you need deeper context for the relevant task:
+
+| File                               | When to load                                                                                  |
+| ---------------------------------- | --------------------------------------------------------------------------------------------- |
+| `references/status-transitions.md` | Validating a transition, checking required fields, understanding the story/epic state machine |
+
+## Workflows
+
+Follow these step-by-step when the user initiates the matching action:
+
+| File                         | When to follow                                                                                                              |
+| ---------------------------- | --------------------------------------------------------------------------------------------------------------------------- |
+| `workflows/update-status.md` | User reports progress ("I finished", "I'm blocked") — identifies target, validates transition, shows diff, confirms, writes |

package/content/plugins/core/skills/agileflow-status-updater/references/status-transitions.md

@@ -0,0 +1,89 @@
+# Status Transitions Reference
+
+**Load this when:** validating a status change request, explaining allowed
+transitions, or deciding if a transition needs special confirmation.
+
+## Story state machine
+
+```
+          ┌─────────────────────────────────────┐
+          │                                     ▼
+ ready ──► in_progress ──► review ──► complete
+   ▲           │               │
+   │           ▼               ▼
+   └──────── blocked ◄─────────┘
+```
+
+| From          | To            | When                          | Special handling                                |
+| ------------- | ------------- | ----------------------------- | ----------------------------------------------- |
+| `ready`       | `in_progress` | Someone picks it up           | Capture owner                                   |
+| `in_progress` | `review`      | Tests pass, ready for review  | Optional: capture reviewer                      |
+| `review`      | `complete`    | Reviewer signs off            | Set `completed` timestamp; update parent epic % |
+| `*`           | `blocked`     | Any forward state hits a wall | Require `blocked_reason` + `unblock_action`     |
+| `blocked`     | (previous)    | Blocker resolved              | Resume to the state it was in before blocking   |
+| `*`           | `ready`       | Reset / rollback              | Ask for confirmation — this is unusual          |
+| `in_progress` | `complete`    | Skip review (solo projects)   | Warn that review was skipped                    |
+
+## Epic state machine
+
+```
+PLANNING ──► ACTIVE ──► COMPLETED
+                │
+                ▼
+             ON_HOLD ──► ACTIVE
+```
+
+| From       | To          | Trigger                            | Special handling                               |
+| ---------- | ----------- | ---------------------------------- | ---------------------------------------------- |
+| `PLANNING` | `ACTIVE`    | First story moves to `in_progress` | Auto-suggest or explicit                       |
+| `ACTIVE`   | `ON_HOLD`   | Team pause, competing priority     | Require reason                                 |
+| `ON_HOLD`  | `ACTIVE`    | Work resumes                       | Clear the hold reason                          |
+| `ACTIVE`   | `COMPLETED` | All stories `complete`             | Confirm — verify all stories are actually done |
+
+## Transitions that need explicit confirmation
+
+These are allowed but unusual — always show the change and ask YES/NO:
+
+| Transition                                          | Why unusual                      |
+| --------------------------------------------------- | -------------------------------- |
+| Any state → `ready`                                 | Rollback — work may be lost      |
+| `review` → `in_progress`                            | Review rejected — capture reason |
+| `complete` → anything                               | Reopening completed work         |
+| Epic `ACTIVE` → `COMPLETED` with incomplete stories | Data integrity risk              |
+
+## Required fields per transition
+
+| Transition            | Required field                                       |
+| --------------------- | ---------------------------------------------------- |
+| Any → `blocked`       | `blocked_reason` (string), `unblock_action` (string) |
+| `blocked` → previous  | Clear `blocked_reason`                               |
+| Any → `complete`      | `completed` (ISO timestamp)                          |
+| Epic → `ON_HOLD`      | `hold_reason`                                        |
+| Any assignment change | `owner` (team ID or name)                            |
+
+## Progress calculation (epic)
+
+When a story completes, recalculate the parent epic's progress:
+
+```
+progress = (completed_stories / total_stories) * 100
+```
+
+Update the epic file's `Progress` section and the `updated` timestamp.
+
+Auto-trigger `COMPLETED` suggestion when `progress = 100%` and prompt user to confirm.
+
+## Diff format to show before every write
+
+Always show before/after for both `status.json` and the story/epic frontmatter:
+
+```diff
+docs/09-agents/status.json
+- "US-0042": { "status": "ready", "updated": "2026-04-25" }
++ "US-0042": { "status": "in_progress", "updated": "2026-04-26" }
+
+docs/06-stories/US-0042.md (frontmatter)
+- status: ready
++ status: in_progress
++ updated: 2026-04-26
+```

package/content/plugins/core/skills/agileflow-status-updater/workflows/update-status.md

@@ -0,0 +1,56 @@
+# Update Status Workflow
+
+**Triggers:** "mark this done", "I finished", "I'm blocked on", "move to in progress", "update status", "story is complete", "mark epic active"
+
+**Goal:** Apply a status mutation to a story or epic, show a diff, and write after confirmation.
+
+## Inputs needed
+
+| Input          | Required       | How to get it                                                    |
+| -------------- | -------------- | ---------------------------------------------------------------- |
+| Target ID      | Yes            | US-#### or EP-#### — infer from context or ask                   |
+| New status     | Yes            | Usually clear from the user's words                              |
+| Blocked reason | If blocking    | Ask: "What's blocking you, and what needs to happen to unblock?" |
+| Owner change   | If reassigning | Ask who the new owner is                                         |
+
+## Steps
+
+1. **Identify the target** — extract US-#### or EP-#### from the user's message. If ambiguous (e.g., "the auth story"), read `docs/09-agents/status.json` to find the most likely match based on what's `in_progress` or recently mentioned.
+
+2. **Validate the transition** — use `references/status-transitions.md`. If the transition is disallowed, explain why and suggest the closest valid path.
+
+3. **Gather missing required fields** — if transitioning to `blocked`, ask for `blocked_reason` and `unblock_action`. If completing a story, prepare the `completed` timestamp.
+
+4. **Build the diff** — show exactly what will change in both `status.json` and the story/epic file's frontmatter. Never skip this step.
+
+5. **Present to user for confirmation:**
+   - Apply this change
+   - Edit the diff before applying (describe what to change)
+   - Cancel
+
+6. **After confirmation:**
+   - Write `docs/09-agents/status.json`
+   - Write the story/epic file frontmatter
+   - If story completing: recalculate parent epic progress, update epic file
+   - If epic now at 100%: suggest marking epic `COMPLETED`
+
+7. **Confirm completion** — "US-0042 marked complete. EP-0018 is now 87% done (7/8 stories)."
+
+## Edge cases
+
+- **"I finished" with no ID**: read status.json, find stories in `in_progress`, ask which one
+- **Blocking with no reason**: do not proceed — `blocked_reason` is required
+- **Complete with incomplete children**: warn before writing
+- **Unknown ID**: say so clearly, offer to list what's in progress
+
+## Fallbacks
+
+**If interactive prompts (AskUserQuestion) are unavailable:**
+Present options as a numbered list in your response. Ask the user to reply with a number.
+
+```
+Apply this status change?
+1. Yes — apply the diff above
+2. No — cancel
+3. Change the blocked_reason first
+```