agileflow 4.0.0-alpha.2 → 4.0.0-alpha.21

package/content/plugins/core/skills/agileflow-adr/references/madr-format-guide.md

@@ -0,0 +1,86 @@
+# MADR Format Guide
+
+**Load this when:** writing an ADR, reviewing an existing one,
+or explaining the MADR format to a user.
+
+## What MADR is
+
+MADR (Markdown Any Decision Records) — a lightweight, structured format
+for capturing decisions. The key insight: decisions without context rot
+into mystery. MADR forces you to record the WHY, not just the WHAT.
+
+## Required sections
+
+| Section                           | Purpose                     | What to write                                                                                                                |
+| --------------------------------- | --------------------------- | ---------------------------------------------------------------------------------------------------------------------------- |
+| **Context and Problem Statement** | Why this decision is needed | The situation + the friction. "We need to pick a queue backend because we're hitting rate limits on synchronous processing." |
+| **Decision Drivers**              | What matters most           | 3-5 bullets: performance, cost, team expertise, operational simplicity, compliance                                           |
+| **Considered Options**            | What was evaluated          | At least 2. "Status quo / do nothing" counts as an option.                                                                   |
+| **Decision Outcome**              | What was chosen and why     | Tie directly back to the drivers. Name the option.                                                                           |
+
+## Optional but recommended
+
+| Section                      | When to include                                              |
+| ---------------------------- | ------------------------------------------------------------ |
+| **Positive Consequences**    | Non-obvious upsides worth documenting                        |
+| **Negative Consequences**    | Downsides + mitigations (being honest here builds trust)     |
+| **Pros and Cons per option** | When options were close and you want the reasoning preserved |
+| **Links**                    | Related ADRs, external benchmarks, issue trackers            |
+
+## Status lifecycle
+
+```
+Proposed → Accepted → (years later) → Deprecated | Superseded
+```
+
+- **Proposed**: under active discussion
+- **Accepted**: decision made, do not change — write a new ADR to override
+- **Deprecated**: no longer relevant (tech removed, requirements changed)
+- **Superseded by ADR-XXXX**: replaced — always link forward
+
+## Common mistakes
+
+| Mistake                      | Problem                                    | Fix                                                    |
+| ---------------------------- | ------------------------------------------ | ------------------------------------------------------ |
+| Single option considered     | Looks like rationalization                 | Add "status quo" or "do nothing" as an explicit option |
+| Vague problem statement      | Future reader has no context               | Name the constraint that forced the decision           |
+| No negative consequences     | Untrustworthy — every choice has tradeoffs | Document downsides + mitigation plan                   |
+| Missing decision drivers     | Options can't be evaluated                 | List what matters — performance, cost, DX, compliance  |
+| ADR updated after acceptance | History lost                               | Create a new ADR, set old to Superseded                |
+
+## Numbering and naming
+
+```
+docs/03-decisions/ADR-0001-use-postgresql.md
+docs/03-decisions/ADR-0002-rest-over-graphql.md
+docs/03-decisions/ADR-0015-switch-to-edge-functions.md
+```
+
+- Always 4-digit zero-padded
+- Slug: lowercase, hyphens, describes the decision (not "database-decision")
+- Never reuse a number even after a superseded ADR is "deleted"
+
+## Size guidelines
+
+- **Micro ADR** (< 20 lines): small, clear decisions — OK to skip Pros/Cons per option
+- **Standard ADR** (20-60 lines): most decisions
+- **Extended ADR** (60-100 lines): architecture pivots, platform migrations
+- **Never > 100 lines**: if it's longer, the problem statement is too broad — split it
+
+## Cross-linking
+
+When an ADR supersedes another:
+
+```markdown
+## Status
+
+Accepted — supersedes [ADR-0003](ADR-0003-use-mongodb.md)
+```
+
+When an ADR is superseded:
+
+```markdown
+## Status
+
+Superseded by [ADR-0015](ADR-0015-switch-to-postgresql.md) (2026-03)
+```

package/content/plugins/core/skills/agileflow-adr/workflows/write-adr.md

@@ -0,0 +1,57 @@
+# Write ADR Workflow
+
+**Triggers:** "record this decision", "write an ADR", "which should we use", "trade-off between X and Y", user compares two technical options
+
+**Goal:** Capture a technical or architectural decision as a formal ADR in `docs/03-decisions/`.
+
+## Inputs needed
+
+| Input              | Required | How to get it                                                             |
+| ------------------ | -------- | ------------------------------------------------------------------------- |
+| Decision topic     | Yes      | Usually clear from context; ask if ambiguous                              |
+| Options considered | Yes      | At least 2 — ask if only 1 given ("what did you consider instead?")       |
+| Decision drivers   | Yes      | Ask: "What matters most — performance, cost, simplicity, team expertise?" |
+| Chosen option      | Yes      | May already be decided, or may still be open                              |
+| Status             | Yes      | `Proposed` if still debating, `Accepted` if decided                       |
+
+## Steps
+
+1. **Detect scope** — is this a real architecture decision or a casual question?
+   - Real: compares libraries, frameworks, infra, patterns with real tradeoffs
+   - Casual: "which is better, tabs or spaces?" → skip the ADR, just answer
+
+2. **Gather missing pieces** — ask 1-3 targeted questions if inputs are incomplete.
+   Present as: "To write this ADR I need a couple things: [questions]"
+   Don't ask for everything at once — prioritize the most critical gaps.
+
+3. **Find the next ADR number** — read `docs/03-decisions/` to find the highest existing number.
+   If the directory doesn't exist, create it and start at 0001.
+
+4. **Draft the ADR** — write it inline using the MADR format from `references/madr-format-guide.md`.
+   Show the full draft to the user before writing any file.
+
+5. **Present options to the user:**
+   - Write this ADR to `docs/03-decisions/ADR-####-<slug>.md`
+   - Revise the draft (describe what to change)
+   - Change status to Proposed (if they want to discuss first)
+
+6. **Write the file** only after explicit confirmation.
+
+7. **Link** — if this supersedes an existing ADR, update the old file's Status line.
+
+## Output
+
+File written to: `docs/03-decisions/ADR-####-<slug>.md`
+
+Confirm to user: "ADR-#### written. Future decisions that change this approach should supersede it with a new ADR."
+
+## 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 ADR-0007 to docs/03-decisions/ADR-0007-use-redis-for-queuing.md
+2. Revise the draft first
+3. Save as Proposed (not Accepted) for further discussion
+```

package/content/plugins/core/skills/agileflow-babysit-mentor/SKILL.md

@@ -5,9 +5,9 @@ category: agileflow/core
 description: |
   Use when the user wants end-to-end guidance through a story or
   feature — from picking the right task to commit. Acts as a mentor
-  that plans, delegates to domain experts, tracks tasks, runs audits,
-  and ends every response with a smart AskUserQuestion so the user is
-  always in control.
+  that plans, delegates to domain experts, tracks progress, runs
+  audits, and keeps the user in control with explicit next-step
+  choices.
 triggers:
   keywords:
     - help me ship this
@@ -33,8 +33,6 @@ depends:
   plugins: [core]
 ---
 
-<!-- {{PERSONALIZATION_BLOCK}} -->
-
 # AgileFlow Babysit Mentor
 
 The mentor pattern: pick the most impactful ready story, plan the
@@ -53,16 +51,16 @@ every decision point. This skill is the v4 successor to v3's
 
 ## Core operating rules (always apply)
 
-1. **Always end every response with a smart `AskUserQuestion`** —
+1. **Always end every response with a concrete next step or choice** —
    specific, contextual options with one marked `(Recommended)`. Never
    `Continue?` / `What next?`.
-2. **Use plan mode for non-trivial implementation** — call
-   `EnterPlanMode`, explore 3–5 files, write a plan, `ExitPlanMode`.
-   Skip for typos and one-liners.
-3. **Delegate complex work to domain experts** via the `Task` tool
-   (e.g., `agileflow-database`, `agileflow-api`, `agileflow-ui`).
-4. **Track progress with `TaskCreate` / `TaskUpdate`** for any task
-   with 3+ steps. Mark complete as soon as each step lands.
+2. **Use the IDE's planning workflow for non-trivial implementation**
+   when one exists. Otherwise write a short plan in the response,
+   explore the relevant files, and keep the plan visible.
+3. **Delegate complex work to domain experts or subagents** when the
+   current IDE supports that shape of delegation.
+4. **Track progress visibly for any task with 3+ steps.** Keep a task
+   list or checklist and mark each step complete as soon as it lands.
 5. **Suggest a logic audit after every implementation** — present
    `Run logic audit` as `(Recommended)` after tests pass.
 6. **Suggest a flow audit when implementation touches user flows** —
@@ -76,7 +74,7 @@ every decision point. This skill is the v4 successor to v3's
 1. Read `docs/09-agents/status.json` and the active session state.
 2. Surface the most impactful **ready** stories (priority + epic
    completion proximity + dependency unblockers).
-3. Present them via `AskUserQuestion` with the recommended pick.
+3. Present them as a short decision prompt with the recommended pick.
 
 ### Phase 2 — Plan
 
@@ -93,14 +91,15 @@ Step N: Verify flow integrity
 ### Phase 3 — Execute
 
 - Implement directly OR spawn domain experts for parallelizable work.
-- Update `TaskUpdate` as each step completes.
+- Update the visible checklist as each step completes.
 
 ### Phase 4 — Verify & commit
 
 After tests pass, present (in this order):
-- `Run logic audit (Recommended)` — `/agileflow:code:logic` on the
-  modified files
-- `Run flow audit` — `/agileflow:code:flows` if user flows changed
+
+- `Run logic audit (Recommended)` — run the logic audit on the modified
+  files
+- `Run flow audit` — run the flow audit if user flows changed
 - `Commit: 'feat: ...'`
 
 After audits land, the commit option becomes `(Recommended)`.
@@ -119,26 +118,94 @@ After audits land, the commit option becomes `(Recommended)`.
 
 - [ ] Picked from `ready` stories, not arbitrary
 - [ ] Used plan mode if scope warranted
-- [ ] Tracked tasks with `TaskCreate`/`TaskUpdate` for ≥3 steps
+- [ ] Tracked tasks visibly for ≥3 steps
 - [ ] Tests run after implementation
 - [ ] Logic audit suggested
 - [ ] Flow audit suggested for user-facing changes
-- [ ] Every response ended with smart `AskUserQuestion`
+- [ ] Every response ended with a concrete next step or choice
 
 ## Integration
 
-- **agileflow-story-writer** — when a discovered task isn't already a
-  story, propose creating one before starting work
-- **agileflow-status-updater** — flip story status as work progresses
-- **agileflow-epic-planner** — when scope creeps past one story, propose
-  splitting into an epic
+Use the skill that best matches the phase of work. When in doubt, the trigger keywords in each skill's `SKILL.md` are the canonical guide.
+
+### Task & story management
+
+- **agileflow-story-writer** — when a task isn't yet a proper story, propose creating one before starting work; handles AC, estimation, and story formatting
+- **agileflow-status-updater** — flip story status as work progresses (ready → in-progress → done → blocked); call whenever state changes
+- **agileflow-epic-planner** — when scope creeps past one story or a theme emerges, propose splitting into an epic with sequenced stories
+- **agileflow-adr** — surface when implementation involves a meaningful technology or architecture trade-off that deserves a recorded decision
+- **agileflow-planning** — use for impact analysis, velocity tracking, RPI scoring, metrics dashboards, or sprint planning; ideal when the user asks about prioritisation
+
+### Strategy & ideation
+
+- **agileflow-council** — convene for architectural or strategic decisions with significant trade-offs; brings multiple perspectives (optimist, advocate, contrarian, technical) instead of a single opinion
+- **agileflow-ideation** — use when the user wants to explore what to build next, validate a product direction, discover feature opportunities, or generate a product brief before writing stories
+- **agileflow-retention** — suggest when stories involve engagement, habit-forming features, onboarding flows, or growth mechanics; applies behavioural psychology patterns
+
+### Research
+
+- **agileflow-research** — activate before coding begins when the story requires external knowledge: unfamiliar libraries, API integrations, architectural patterns, or comparative analysis; pairs with `research:ask` for stuck moments
+
+### Implementation
+
+- **agileflow-engineering** — delegate hands-on coding: API endpoints, DB schema, UI components, mobile, security hardening, and general feature implementation
+- **agileflow-database** — delegate schema design, index selection, migration planning, or query-optimisation work; covers relational and NoSQL
+- **agileflow-migration** — use when the story involves upgrading a framework, library, or data schema; plans zero-downtime migrations and generates rollback scripts
+- **agileflow-refactor** — suggest when existing code needs cleanup before or after a feature lands; applies safe refactoring patterns without changing observable behaviour
+- **agileflow-debug** — hand off immediately when the user reports a bug or unexpected behaviour; applies structured debugging methodology
+- **agileflow-performance** — suggest when a feature is slow, memory-heavy, bundle-size-constrained, or Core Web Vitals need improvement
+- **agileflow-accessibility** — suggest for any user-facing change; invoke before commit when the story touches UI; covers WCAG, ARIA, keyboard navigation, and screen reader compatibility
+
+### Testing
+
+- **agileflow-test-writer** — spawn after implementation to generate test suites from acceptance criteria; covers unit, integration, and E2E patterns
+
+### Verification & audits
+
+- **agileflow-audit** — broad multi-dimensional sweep (logic, security, accessibility, legal, test coverage, architecture, performance, completeness, API quality, SEO); offer after implementation when no specific audit is targeted
+- **agileflow-pr-reviewer** — invoke before opening a PR to catch logic correctness, security vulnerabilities, and style issues; required for stories touching 5+ source files
+- **agileflow-delivery** — use when the user is ready to ship: CI checks, changelog generation, dependency audit, release notes, and sprint finalisation
+
+### Documentation & discoverability
+
+- **agileflow-docs** — generate or sync API docs, README files, learning content, or skill recommendations after implementation; required when public APIs or exports change
+- **agileflow-seo** — suggest for any story touching public-facing pages or content discoverability; covers technical SEO, Core Web Vitals, structured data, and content quality
+
+### Advertising & growth
+
+- **agileflow-ads** — use when stories involve advertising campaigns (Google, Meta, LinkedIn, TikTok); covers tracking, creative, budget allocation, and audit
 
 ## Notes
 
 - Mentor mode is opt-in. Don't impose it on simple requests
   ("rename this variable") where direct execution is faster.
-- The user is always in control. Smart `AskUserQuestion` with a
-  recommended path is the principle, not the exception.
+- The user is always in control. A specific recommended choice is the
+  principle, not the exception.
 - When in doubt, ASK rather than guess. The cost of a clarifying
   question is one round-trip; the cost of redoing the wrong work is
   much more.
+
+## Customization
+
+Set `plugins.core.settings.babysit.mode` in `agileflow.config.json` to
+control how much interaction the mentor uses:
+
+- `full` - use the richest interaction pattern the IDE supports
+- `light` - keep the guidance concise and avoid repeated interruptions
+- `minimal` - stick to direct execution and short plain-text checklists
+
+## References
+
+Load these files when you need deeper context for the relevant task:
+
+| File                                  | When to load                                                                                         |
+| ------------------------------------- | ---------------------------------------------------------------------------------------------------- |
+| `references/mentor-decision-guide.md` | Calibrating interaction depth, choosing which expert to delegate to, deciding when to suggest audits |
+
+## Workflows
+
+Follow these step-by-step when the user initiates the matching action:
+
+| File                          | When to follow                                                                    |
+| ----------------------------- | --------------------------------------------------------------------------------- |
+| `workflows/mentor-session.md` | User wants end-to-end guidance — story selection through commit, full mentor loop |

package/content/plugins/core/skills/agileflow-babysit-mentor/references/mentor-decision-guide.md

@@ -0,0 +1,81 @@
+# Mentor Decision Guide
+
+**Load this when:** deciding how deeply to guide the user, choosing between
+doing work directly vs delegating, or calibrating the level of interaction.
+
+## When to use mentor mode vs just answering
+
+| Request type                   | Approach                                               |
+| ------------------------------ | ------------------------------------------------------ |
+| "Help me ship US-0042"         | Full mentor mode — plan, delegate, track, verify       |
+| "Walk me through this feature" | Full mentor mode                                       |
+| "What should I work on?"       | Story selection + mentor mode for chosen story         |
+| "Fix this bug in auth.js"      | Do it directly, no mentor overhead                     |
+| "Rename this function"         | Do it directly                                         |
+| "Is this approach correct?"    | Answer the question, offer to proceed with mentor mode |
+
+## Calibrating interaction depth by scale
+
+| Project scale             | Planning depth                    | Delegation    | Audits                  |
+| ------------------------- | --------------------------------- | ------------- | ----------------------- |
+| Micro (solo, < 5 stories) | Skip plan mode for most tasks     | 2 experts max | Logic only              |
+| Small (1 sprint)          | Light planning, skip for familiar | 3 experts max | Logic + flow            |
+| Medium (2–4 sprints)      | Plan mode for non-trivial         | 4 experts     | Logic + flow + security |
+| Large (4+ sprints)        | Always plan mode                  | 5 experts     | All relevant audits     |
+| Enterprise (team)         | Plan + council for arch decisions | Full panel    | Strict gates            |
+
+User preferences override this — if configured as `light` or `minimal`, respect that.
+
+## Choosing the right expert to delegate to
+
+| Work involves...                     | Delegate to                      |
+| ------------------------------------ | -------------------------------- |
+| Database schema, migrations, queries | `agileflow-database`             |
+| API endpoints, business logic        | `agileflow-api`                  |
+| UI components, styling               | `agileflow-ui`                   |
+| Test strategy, coverage              | `agileflow-testing`              |
+| Security, auth                       | `agileflow-security`             |
+| 2+ domains                           | `agileflow-orchestrator`         |
+| Architecture decision                | Council first, then implementors |
+
+## When to suggest audits
+
+After any implementation, present audits in this order:
+
+1. **Logic audit** — always, after tests pass (`Recommended`)
+2. **Flow audit** — when user-facing flows changed (forms, navigation, auth, CRUD)
+3. **Security audit** — when auth, APIs, user input, or sensitive data touched
+4. **Performance audit** — when DB queries, rendering, or large data touched
+5. **Accessibility audit** — when UI components changed
+6. **Legal audit** — when data collection, consent, or compliance code changed
+
+`auditAll` mode: suggest all of the above after every implementation regardless of context.
+
+## Decision points that require user input (always ask)
+
+- Which story to work on (never pick silently)
+- Plan approval before implementation
+- Commit message and timing
+- Whether to fix P0/P1 audit findings now or defer
+
+## Decision points to handle autonomously (don't ask)
+
+- Reading files to understand context
+- Spawning experts after plan approval
+- Checking git status
+- Running tests after implementation
+
+## Next-step option quality bar
+
+**Bad options:**
+
+- "Continue" / "Keep going"
+- "What would you like to do?"
+- "Proceed with implementation?"
+
+**Good options:**
+
+- "Run npm test on the 3 changed files (Recommended)"
+- "Commit: 'feat: add OAuth login flow'"
+- "Run logic audit on auth.js, session.js (Recommended)"
+- "Continue to US-0044 (EP-0018 is 85% complete)"

package/content/plugins/core/skills/agileflow-babysit-mentor/workflows/mentor-session.md

@@ -0,0 +1,79 @@
+# Mentor Session Workflow
+
+**Triggers:** "help me ship", "walk me through", "what should I work on", "mentor mode", "babysit", "guide me through this story"
+
+**Goal:** Guide the user from story selection through commit, keeping them in control at every decision point.
+
+## Inputs needed
+
+| Input            | Required | How to get it                                      |
+| ---------------- | -------- | -------------------------------------------------- |
+| Project context  | Yes      | Read `docs/09-agents/status.json`                  |
+| Story to work on | Yes      | Present options from ready stories; user picks     |
+| User preferences | Auto     | Read from `agileflow.config.json` babysit settings |
+
+## Steps
+
+### Phase 1: Context
+
+1. Read `docs/09-agents/status.json` — find all `ready` stories.
+2. Check for stories claimed by other sessions if multi-session support is available.
+3. **Present story options to the user** — ranked by: epic proximity (80%+ complete epics first), dependency-unblocking value, priority. Mark the recommended pick.
+   Show: story ID, title, epic it belongs to, estimated points.
+4. After user picks: claim the story if claiming is supported.
+
+### Phase 2: Plan
+
+For non-trivial stories (>1 file, any new pattern):
+
+1. Enter plan mode.
+2. Read 3–5 relevant files — existing patterns, affected modules, tests.
+3. Write the plan: implementation steps, files to change, testing approach.
+4. **Every plan for user-facing features must include:**
+   ```
+   Step N+1: Run tests
+   Step N+2: Verify flow integrity — confirm user journeys work end-to-end
+   Step N+3: Commit
+   ```
+5. Exit plan mode and present to user for approval.
+
+For trivial stories (typo, config change, one-liner): skip plan mode, implement directly.
+
+### Phase 3: Execute
+
+1. After plan approval, start immediately — do not ask "ready to proceed?"
+2. Implement directly OR spawn domain experts (see `references/mentor-decision-guide.md` for routing).
+3. Track progress visibly for 3+ step tasks — check off each step as it completes.
+4. Run tests after implementation.
+
+### Phase 4: Verify and commit
+
+After tests pass, present options in this order:
+
+- `🔍 Run logic audit on [N] modified files (Recommended)` — catches edge cases tests miss
+- `🔄 Run flow audit` — if user-facing flows were touched
+- `Commit: '[type]: [summary]'` — skip audits
+
+After audits: `Commit: '[type]: [summary]' (Recommended)`
+
+After commit:
+
+- Update story status to `complete`
+- Release story claim
+- Present options: next story in the same epic, different story, or stop
+
+## Fallbacks
+
+**If interactive prompts (AskUserQuestion) are unavailable:**
+Present each decision point as a numbered list. Ask the user to reply with a number.
+
+```
+Which story would you like to work on?
+1. US-0042: Add OAuth login (EP-0018 — 85% complete) — 8 pts (Recommended)
+2. US-0051: Add rate limiting to API — 5 pts
+3. US-0038: Fix password reset email — 3 pts
+```
+
+**If agent spawning (Task tool) is unavailable:**
+Implement each domain inline and sequentially rather than in parallel.
+State which domain you're working on as you go: "Working on the database layer now..."

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

@@ -34,8 +34,6 @@ depends:
   plugins: [core]
 ---
 
-<!-- {{PERSONALIZATION_BLOCK}} -->
-
 # AgileFlow Epic Planner
 
 Turns a large feature or initiative into a properly-scoped epic — with
@@ -86,39 +84,48 @@ confidence (`high` / `medium` / `low`) per the standard pattern.
 **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**
+      **Total: 13 story points**
 
 ### Milestone 2: Feature Complete (Target: YYYY-MM-DD)
+
 - [ ] [US-####: Title](../06-stories/US-####.md) — 5 pts
-**Total: 5 story points**
+      **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
 ```
@@ -126,12 +133,14 @@ confidence (`high` / `medium` / `low`) per the standard pattern.
 ## 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
@@ -165,9 +174,14 @@ confidence (`high` / `medium` / `low`) per the standard pattern.
 
 ## Integration
 
-- **agileflow-story-writer** — creates the individual stories under each milestone
-- **agileflow-status-updater** — flips the epic between PLANNING / ACTIVE / COMPLETED
-- **agileflow-adr** — links major technical decisions made during the epic
+- **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
 
@@ -177,3 +191,19 @@ confidence (`high` / `medium` / `low`) per the standard pattern.
   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 |