agileflow 3.4.2 → 4.0.0-alpha.1

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

@@ -0,0 +1,144 @@
+---
+name: agileflow-babysit-mentor
+version: 1.0.0
+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.
+triggers:
+  keywords:
+    - help me ship this
+    - walk me through
+    - what should i work on
+    - take me through this story
+    - mentor mode
+    - babysit
+    - end-to-end
+    - guide me through
+  priority: 60
+  exclude:
+    - babysit my kid
+    - babysitting service
+provides:
+  agents: []
+learns:
+  enabled: true
+  file: _learnings/babysit-mentor.yaml
+  maxEntries: 50
+depends:
+  skills: []
+  plugins: [core]
+---
+
+<!-- {{PERSONALIZATION_BLOCK}} -->
+
+# AgileFlow Babysit Mentor
+
+The mentor pattern: pick the most impactful ready story, plan the
+implementation, delegate work to domain experts, track progress,
+verify (tests + audits), and commit — always letting the user steer at
+every decision point. This skill is the v4 successor to v3's
+`/agileflow:babysit` command.
+
+## When this skill activates
+
+- User asks "what should I work on", "walk me through", "help me ship"
+- User explicitly invokes mentor / babysit mode
+- User describes wanting end-to-end coaching on a feature
+- Should NOT activate on unrelated childcare mentions — `exclude`
+  damps `babysit my kid` etc.
+
+## Core operating rules (always apply)
+
+1. **Always end every response with a smart `AskUserQuestion`** —
+   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.
+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** —
+   plans for non-trivial features must include a "Verify flow
+   integrity" step.
+
+## Workflow phases
+
+### Phase 1 — Context & task selection
+
+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.
+
+### Phase 2 — Plan
+
+For non-trivial tasks: enter plan mode, explore, design, exit.
+Plans for user-flow features MUST include:
+
+```
+Step N: Verify flow integrity
+  - Run /agileflow:code:flows on modified paths
+  - Confirm user journeys work end-to-end
+  - Fix BROKEN / DEGRADED findings before commit
+```
+
+### Phase 3 — Execute
+
+- Implement directly OR spawn domain experts for parallelizable work.
+- Update `TaskUpdate` 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
+- `Commit: 'feat: ...'`
+
+After audits land, the commit option becomes `(Recommended)`.
+
+## Self-improving learnings
+
+`.agileflow/skills/_learnings/babysit-mentor.yaml` captures:
+
+- Story-priority preferences (e.g., "user prefers near-complete epics
+  over isolated high-priority tasks")
+- Audit cadence (e.g., "always run flow audit before commit")
+- Plan-mode threshold (which task scopes get plan mode vs direct)
+- Delegation defaults (which expert for which file pattern)
+
+## Quality checklist (per session)
+
+- [ ] Picked from `ready` stories, not arbitrary
+- [ ] Used plan mode if scope warranted
+- [ ] Tracked tasks with `TaskCreate`/`TaskUpdate` for ≥3 steps
+- [ ] Tests run after implementation
+- [ ] Logic audit suggested
+- [ ] Flow audit suggested for user-facing changes
+- [ ] Every response ended with smart `AskUserQuestion`
+
+## 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
+
+## 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.
+- 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.

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

@@ -0,0 +1,179 @@
+---
+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]
+---
+
+<!-- {{PERSONALIZATION_BLOCK}} -->
+
+# 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
+- **agileflow-status-updater** — flips the epic between PLANNING / ACTIVE / COMPLETED
+- **agileflow-adr** — links major technical decisions made during the epic
+
+## 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.

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

@@ -0,0 +1,132 @@
+---
+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]
+---
+
+<!-- {{PERSONALIZATION_BLOCK}} -->
+
+# 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)
+- **agileflow-epic-planner** — creates new epics (status = PLANNING)
+- **agileflow-babysit-mentor** — drives status changes during the
+  end-to-end workflow
+
+## 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").

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

@@ -0,0 +1,200 @@
+---
+name: agileflow-story-writer
+version: 2.0.0
+category: agileflow/core
+description: |
+  Use when a user describes a feature, requirement, or bug in natural
+  language and needs a properly-formatted user story with acceptance
+  criteria. Creates a US-#### story file in docs/06-stories/ and
+  updates the status.json index.
+triggers:
+  keywords:
+    - user story
+    - story for
+    - acceptance criteria
+    - as a user
+    - as a user, i want
+    - feature request
+    - implement this
+  priority: 50
+  exclude:
+    - story time
+    - bedtime story
+    - tell me a story
+provides:
+  agents:
+    - agileflow-story-writer
+learns:
+  enabled: true
+  file: _learnings/story-writer.yaml
+  maxEntries: 50
+depends:
+  skills: []
+  plugins: [core]
+---
+
+<!-- {{PERSONALIZATION_BLOCK}} -->
+
+# AgileFlow Story Writer
+
+Converts user feature descriptions into properly-formatted user stories
+with `Given/When/Then` acceptance criteria, owner assignment, priority,
+and Fibonacci estimates.
+
+## When this skill activates
+
+- 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
+
+1. Extract the user story components (who / what / why) from the
+   description.
+2. Determine metadata: owner, priority (P0–P3), estimate (Fibonacci),
+   epic linkage.
+3. Generate 2–5 acceptance criteria in Given/When/Then format covering
+   the 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`.
+
+## Self-improving learnings
+
+The skill maintains preferences in
+`.agileflow/skills/_learnings/story-writer.yaml`. On each invocation:
+
+1. Read the learnings file if it exists; apply preferences (priority
+   format, estimate scale, owner conventions, AC style).
+2. Follow conventions and avoid anti-patterns recorded there.
+3. On user correction (e.g. "use P0–P3 not HIGH/MEDIUM"), determine
+   confidence — `high` for explicit corrections, `medium` for approved
+   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
+
+- [ ] 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
+
+## Quality checklist
+
+- [ ] Loaded learnings file (if exists) and applied preferences
+- [ ] Story follows "As a... I want... So that..." format
+- [ ] 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)
+- [ ] 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.

package/content/plugins/council/plugin.yaml

@@ -0,0 +1,14 @@
+id: council
+name: AI Council
+description: Six-perspective strategic decision framework (optimist, contrarian, technical, revenue, etc.).
+version: 1.0.0
+enabledByDefault: false
+
+depends: []
+
+provides:
+  commands: []
+  skills: []
+  agents: []
+  hooks: []
+  templates: []

package/content/plugins/seo/plugin.yaml

@@ -0,0 +1,14 @@
+id: seo
+name: SEO
+description: Technical SEO, schema, content, GEO, images, and sitemap audits.
+version: 1.0.0
+enabledByDefault: false
+
+depends: []
+
+provides:
+  commands: []
+  skills: []
+  agents: []
+  hooks: []
+  templates: []