agileflow 3.4.3 → 4.0.0-alpha.10

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

@@ -0,0 +1,211 @@
+---
+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 progress, runs
+  audits, and keeps the user in control with explicit next-step
+  choices.
+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]
+---
+
+# 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 concrete next step or choice** —
+   specific, contextual options with one marked `(Recommended)`. Never
+   `Continue?` / `What next?`.
+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** —
+   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 as a short decision prompt 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 the visible checklist as each step completes.
+
+### Phase 4 — Verify & commit
+
+After tests pass, present (in this order):
+
+- `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)`.
+
+## 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 visibly for ≥3 steps
+- [ ] Tests run after implementation
+- [ ] Logic audit suggested
+- [ ] Flow audit suggested for user-facing changes
+- [ ] Every response ended with a concrete next step or choice
+
+## Integration
+
+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. 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..."