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

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

@@ -32,8 +32,6 @@ depends:
   plugins: [core]
 ---
 
-<!-- {{PERSONALIZATION_BLOCK}} -->
-
 # AgileFlow Status Updater
 
 Single source of truth for the project's agile state lives at
@@ -74,23 +72,23 @@ progress updates without the user editing JSON by hand.
 
 ### 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) |
+| 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 |
+| 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)
 
@@ -117,10 +115,12 @@ docs/06-stories/US-0042-login-form.md (frontmatter)
 
 ## Integration
 
-- **agileflow-story-writer** — creates new stories (status = ready)
-- **agileflow-epic-planner** — creates new epics (status = PLANNING)
-- **agileflow-babysit-mentor** — drives status changes during the
-  end-to-end workflow
+- **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
 
@@ -130,3 +130,19 @@ docs/06-stories/US-0042-login-form.md (frontmatter)
   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
+```

package/content/plugins/core/skills/agileflow-story-writer/SKILL.md

@@ -33,8 +33,6 @@ depends:
   plugins: [core]
 ---
 
-<!-- {{PERSONALIZATION_BLOCK}} -->
-
 # AgileFlow Story Writer
 
 Converts user feature descriptions into properly-formatted user stories
@@ -46,23 +44,25 @@ and Fibonacci estimates.
 - User describes how a feature should behave (`"as a user, I want..."`)
 - Discussing features to build or tasks to implement
 - Requesting a new user story or asking to format an idea as one
-- The skill should NOT activate for casual conversation about
-  storytelling, books, or movies — the `exclude` keywords damp those.
 
-## What this skill does
+The `exclude` keywords damp casual storytelling conversations
+(books, movies, "story time").
+
+## Workflow
 
-1. Extract the user story components (who / what / why) from the
-   description.
-2. Determine metadata: owner, priority (P0–P3), estimate (Fibonacci),
-   epic linkage.
+1. Extract `who / what / why` from the user's description.
+2. Determine metadata: owner, priority, estimate, epic linkage.
+   See **`estimation-reference.md`** for the canonical scales.
 3. Generate 2–5 acceptance criteria in Given/When/Then format covering
-   the happy path, errors, and edge cases.
+   happy path, errors, and edge cases.
 4. Show the proposed story to the user and wait for explicit approval
-   before writing the file ("diff first; YES/NO").
-5. After approval, write `docs/06-stories/US-####-<slug>.md`, update the
-   `docs/06-stories/README.md` index, append to
-   `docs/09-agents/status.json` with `status: ready`, and create a test
-   stub at `docs/07-testing/test-cases/US-####.md`.
+   ("diff first; YES/NO"). If the description is vague, ask 1–2
+   clarifying questions before generating.
+5. After approval, write `docs/06-stories/US-####-<slug>.md` using the
+   template in **`story-template.md`**, then:
+   - Update `docs/06-stories/README.md` index
+   - Append to `docs/09-agents/status.json` with `status: ready`
+   - Create test stub at `docs/07-testing/test-cases/US-####.md`
 
 ## Self-improving learnings
 
@@ -77,94 +77,12 @@ The skill maintains preferences in
    patterns, `low` for observations — and append the signal to the
    learnings file. Continue with the corrected approach.
 
-## Story file format
-
-```markdown
----
-story_id: US-0042
-epic: EP-0001
-title: User Login Form
-owner: AG-UI
-status: ready
-estimate: 5
-priority: P1
-created: 2026-04-26
-updated: 2026-04-26
-dependencies: [US-0040]
----
-
-## Description
-
-As a user,
-I want to log in with my email and password,
-So that I can access my account and personalized features.
-
-## Acceptance Criteria
-
-### AC1: Successful Login
-**Given** a registered user with valid credentials
-**When** user enters email and password
-**Then** user is redirected to dashboard with welcome message
-
-### AC2: Invalid Credentials
-**Given** user enters incorrect password
-**When** user submits login form
-**Then** error message "Invalid email or password" is displayed
-
-### AC3: Input Validation
-**Given** user submits empty email field
-**When** user clicks "Login" button
-**Then** validation error "Email is required" is shown
-
-## Technical Notes
-
-- Use JWT authentication with 24h expiration
-- Store tokens in httpOnly cookies
-- Implement rate limiting (5 attempts per 15 minutes)
-- Hash passwords with bcrypt
-
-## Testing Strategy
-
-- Unit tests for form validation logic
-- Integration tests for authentication flow
-- E2E test for full login journey
-- Test stub: docs/07-testing/test-cases/US-0042.md
-
-## Definition of Done
+## Companion references
 
-- [ ] Code implemented and reviewed
-- [ ] Tests written and passing
-- [ ] Documentation updated
-- [ ] Deployed to staging
-- [ ] Acceptance criteria validated
-```
-
-## Owner determination
-
-- **AG-UI** — Frontend components, styling, user interactions, accessibility
-- **AG-API** — Backend services, APIs, data models, business logic
-- **AG-CI** — CI/CD pipelines, testing infrastructure, quality gates
-- **AG-DEVOPS** — Infrastructure, deployment, monitoring, automation
-
-If the work spans multiple owners, pick the **primary** owner and note
-others under Technical Notes.
-
-## Story-point estimation (Fibonacci)
-
-- **1** — Trivial (text update, typo, config tweak)
-- **2** — Simple (add form field, new button, basic validation)
-- **3** — Small (basic CRUD endpoint, simple component)
-- **5** — Medium (authentication flow, data model)
-- **8** — Large (payment integration, complex UI workflow)
-- **13** — Very large — **suggest splitting** into multiple stories or
-  promoting to an epic
-
-## Priority guidelines
-
-- **P0 (Critical)** — Blocking users, security, data loss, prod outage
-- **P1 (High)** — Major features, important fixes, user-facing improvements
-- **P2 (Medium)** — Nice-to-have, minor improvements, enhancements
-- **P3 (Low)** — Tech debt, cleanup, future enhancements, optimizations
+| File                      | Load when                                                           |
+| ------------------------- | ------------------------------------------------------------------- |
+| `story-template.md`       | Writing the story file — full frontmatter + body shape with example |
+| `estimation-reference.md` | Assigning owner / estimate / priority — canonical scales            |
 
 ## Quality checklist
 
@@ -173,28 +91,35 @@ others under Technical Notes.
 - [ ] At least 2 acceptance criteria with Given/When/Then
 - [ ] Owner reflects the primary work area
 - [ ] Priority reflects urgency and impact (P0–P3)
-- [ ] Estimate is in Fibonacci sequence (1,2,3,5,8,13)
+- [ ] Estimate is in Fibonacci sequence (1, 2, 3, 5, 8, 13)
 - [ ] File name matches pattern: `US-####-descriptive-name.md`
-- [ ] Technical notes capture implementation details
-- [ ] Definition of Done is comprehensive
 - [ ] Story added to `docs/09-agents/status.json` with `status: ready`
 - [ ] Test stub created
 - [ ] If user corrected output, learnings file updated
 
-## Integration
-
-- **agileflow-epic-planner** — stories are part of epics
-- **agileflow-sprint-planner** — stories are selected for sprints
-- **agileflow-acceptance-criteria** — strengthen AC sections
-- **agileflow-adr** — reference architectural decisions in technical notes
-
 ## Notes
 
-- If the user description is vague, ask 1–2 clarifying questions before
-  generating the story.
 - Use the next available story number based on existing files in
   `docs/06-stories/` (zero-pad to 4 digits: `US-0042`).
 - If the estimate would exceed 13 points, suggest splitting before
   writing the file.
 - Always show the proposed story diff and wait for explicit `YES` /
   `NO` before writing.
+
+## Integration
+
+- **agileflow-ideation** — ideation produces feature ideas; story-writer gives them the AC and structure needed to enter the backlog
+- **agileflow-epic-planner** — when a story grows beyond one sprint of effort, suggest splitting via epic-planner before writing individual stories
+- **agileflow-status-updater** — after writing a story, flip its status to `ready` in `status.json` via status-updater
+- **agileflow-adr** — if writing a story reveals a technology or architecture decision, spawn adr to document it before implementation begins
+- **agileflow-planning** — use for estimation guidance, sprint capacity checks, or INVEST criteria validation before finalising a story
+- **agileflow-babysit-mentor** — babysit-mentor is the primary consumer of stories produced here; a well-written story is the input that makes mentor-guided execution reliable
+- **agileflow-council** — convene before writing a story if the scope or approach is genuinely ambiguous and a multi-perspective input would sharpen the AC
+
+## Workflows
+
+Follow these step-by-step when the user initiates the matching action:
+
+| File                       | When to follow                                                                             |
+| -------------------------- | ------------------------------------------------------------------------------------------ |
+| `workflows/write-story.md` | User wants a new story written — scope check, clarifying questions, draft, approval, write |

package/content/plugins/core/skills/agileflow-story-writer/references/estimation-reference.md

@@ -0,0 +1,36 @@
+# Owner, Estimate, and Priority Reference
+
+**Load this reference when:** assigning `owner`, `estimate`, or `priority`
+to a new story and you need the canonical scales.
+
+## Owner
+
+Pick the **primary** owner. If work spans multiple owners, note the
+others under "Technical Notes".
+
+| Owner         | Scope                                                          |
+| ------------- | -------------------------------------------------------------- |
+| **AG-UI**     | Frontend components, styling, user interactions, accessibility |
+| **AG-API**    | Backend services, APIs, data models, business logic            |
+| **AG-CI**     | CI/CD pipelines, testing infrastructure, quality gates         |
+| **AG-DEVOPS** | Infrastructure, deployment, monitoring, automation             |
+
+## Estimate (Fibonacci)
+
+| Points | Meaning    | Example                                                             |
+| ------ | ---------- | ------------------------------------------------------------------- |
+| **1**  | Trivial    | Text update, typo, config tweak                                     |
+| **2**  | Simple     | Add form field, new button, basic validation                        |
+| **3**  | Small      | Basic CRUD endpoint, simple component                               |
+| **5**  | Medium     | Auth flow, data model, multi-step form                              |
+| **8**  | Large      | Payment integration, complex UI workflow                            |
+| **13** | Very large | **Suggest splitting** into multiple stories or promoting to an epic |
+
+## Priority
+
+| Level             | When to use                                               |
+| ----------------- | --------------------------------------------------------- |
+| **P0 — Critical** | Blocking users, security, data loss, prod outage          |
+| **P1 — High**     | Major features, important fixes, user-facing improvements |
+| **P2 — Medium**   | Nice-to-have, minor improvements, enhancements            |
+| **P3 — Low**      | Tech debt, cleanup, future enhancements, optimizations    |