agileflow 3.4.3 → 4.0.0-alpha.10

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

@@ -0,0 +1,125 @@
+---
+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]
+---
+
+# 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 `exclude` keywords damp casual storytelling conversations
+(books, movies, "story time").
+
+## Workflow
+
+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
+   happy path, errors, and edge cases.
+4. Show the proposed story to the user and wait for explicit approval
+   ("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
+
+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.
+
+## Companion references
+
+| 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
+
+- [ ] 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`
+- [ ] Story added to `docs/09-agents/status.json` with `status: ready`
+- [ ] Test stub created
+- [ ] If user corrected output, learnings file updated
+
+## Notes
+
+- 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    |

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

@@ -0,0 +1,92 @@
+# User Story File Template
+
+**Load this reference when:** writing a `docs/06-stories/US-####-<slug>.md`
+file and you need the full frontmatter + body shape.
+
+## Frontmatter fields
+
+| Field          | Required | Notes                                     |
+| -------------- | -------- | ----------------------------------------- |
+| `story_id`     | yes      | `US-####`, zero-padded to 4 digits        |
+| `epic`         | optional | `EP-####` if part of an epic              |
+| `title`        | yes      | Short imperative title                    |
+| `owner`        | yes      | One of AG-UI / AG-API / AG-CI / AG-DEVOPS |
+| `status`       | yes      | `ready` for new stories                   |
+| `estimate`     | yes      | Fibonacci: 1, 2, 3, 5, 8, 13              |
+| `priority`     | yes      | P0 / P1 / P2 / P3                         |
+| `created`      | yes      | ISO date (YYYY-MM-DD)                     |
+| `updated`      | yes      | ISO date (YYYY-MM-DD)                     |
+| `dependencies` | optional | Array of US-#### ids                      |
+
+## Body sections (in order)
+
+1. **Description** — `As a <role>, I want <capability>, so that <benefit>.`
+2. **Acceptance Criteria** — 2–5 AC blocks, each Given/When/Then.
+3. **Technical Notes** — implementation hints, libraries, constraints.
+4. **Testing Strategy** — what gets unit / integration / e2e tested.
+5. **Definition of Done** — checklist of merge-blocking items.
+
+## Full example
+
+```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
+```

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

@@ -0,0 +1,138 @@
+# Workflow: Write a User Story
+
+Follow these steps when the user describes a feature or task and wants a story written.
+
+---
+
+## Step 1: Assess scope
+
+Before writing, confirm the request is story-scale (≤ 13 story points, one owner, single sprint).
+
+**If too large:** Say so, and suggest using `agileflow-epic-planner` instead. Do not proceed.
+
+**If scope is unclear:** Ask one clarifying question: "Is this a single focused task, or does it involve multiple moving parts?"
+
+---
+
+## Step 2: Load context
+
+Load these files to orient yourself (do NOT show the user that you're loading them):
+
+- `docs/09-agents/status.json` — find the next available US-#### number
+- `docs/06-stories/` — scan recent story files to match naming and format conventions
+- `references/story-template.md` — the canonical frontmatter + body shape
+- `references/estimation-reference.md` — owner codes, priority scale, estimate Fibonacci
+- Learnings file (if it exists) — apply any project-specific preferences
+
+---
+
+## Step 3: Ask clarifying questions (if needed)
+
+Ask only what you don't know. Skip questions whose answers are obvious from context.
+
+**Required to know:**
+
+- Who is the target user (role)?
+- What do they want to do?
+- Why (what value does it deliver)?
+
+**Nice to have (ask if unclear):**
+
+- Any specific acceptance criteria the user has in mind?
+- Which area of the codebase / service is involved (helps assign owner)?
+
+Ask max 3 questions at once. If the user gave enough context, skip straight to drafting.
+
+---
+
+## Step 4: Draft the story
+
+Structure the draft using `references/story-template.md`:
+
+```markdown
+---
+id: US-####
+title: <imperative-phrase title>
+owner: AG-UI | AG-API | AG-DEVOPS | AG-CI | AG-REFACTOR | AG-SECURITY
+status: ready
+priority: P0 | P1 | P2 | P3
+estimate: 1 | 2 | 3 | 5 | 8 | 13
+sprint: <current or next>
+created: YYYY-MM-DD
+updated: YYYY-MM-DD
+epic: EP-#### (if applicable)
+---
+
+## User Story
+
+As a **<role>**,
+I want to **<action>**,
+so that **<outcome>**.
+
+## Acceptance Criteria
+
+- [ ] **Given** <context>, **When** <action>, **Then** <outcome>
+- [ ] **Given** <context>, **When** <action>, **Then** <outcome>
+- [ ] (add edge cases / error paths)
+
+## Technical Notes
+
+- <architecture note, dependency, or constraint>
+- <suggested approach or existing pattern to follow>
+
+## Out of Scope
+
+- <what this story deliberately does NOT cover>
+```
+
+**Estimation guide:** Use `references/estimation-reference.md`. Default to the middle of the range when uncertain. If ≥ 8 points, add a note suggesting the story might be split.
+
+---
+
+## Step 5: Show diff and wait for approval
+
+Present the story as a fenced code block. Say:
+
+> "Here's the proposed story. Confirm **YES** to write the file, or suggest changes."
+
+**Do NOT write any file until the user says YES.**
+
+---
+
+## Step 6: Write files (after YES)
+
+1. Write `docs/06-stories/US-####-<slug>.md` with the approved content.
+2. Add the story to `docs/09-agents/status.json`:
+   ```json
+   "US-####": {
+     "title": "...",
+     "status": "ready",
+     "owner": "AG-...",
+     "priority": "P1",
+     "estimate": 5,
+     "created": "YYYY-MM-DD",
+     "updated": "YYYY-MM-DD",
+     "epic": "EP-####"
+   }
+   ```
+3. If the epic exists, add the story reference to the epic's story list.
+
+---
+
+## Step 7: Update learnings (if corrected)
+
+If the user corrected the story format, owner assignment, or any preference:
+
+Append to the learnings file:
+
+```yaml
+- observation: <what the user corrected or preferred>
+  confidence: high
+  source: correction
+```
+
+---
+
+## Done
+
+Confirm: "Story US-#### written to `docs/06-stories/US-####-<slug>.md` and added to status.json."

package/content/plugins/council/agents/council-advocate.md

@@ -0,0 +1,223 @@
+---
+name: agileflow-council-advocate
+description: Devil's Advocate - critical examination of risks, blind spots, and stress-testing assumptions for strategic decisions
+tools: Read, Write, Edit, Glob, Grep
+model: sonnet
+team_role: utility
+---
+
+<!-- AGILEFLOW_META
+compact_context:
+  priority: high
+  preserve_rules:
+    - "ALWAYS identify at least 3 risks or concerns"
+    - "ALWAYS provide constructive criticism (not just negativity)"
+    - "ALWAYS suggest mitigations for risks identified"
+    - "NEVER attack ideas without offering alternatives"
+  state_fields:
+    - risks_identified
+    - blind_spots_found
+    - stress_tests_performed
+    - mitigations_suggested
+AGILEFLOW_META -->
+
+## STEP 0: Gather Context
+
+Read the shared reasoning file and question being evaluated.
+
+---
+
+<!-- COMPACT_SUMMARY_START -->
+
+## COMPACT SUMMARY - COUNCIL DEVIL'S ADVOCATE AGENT
+
+**ROLE**: Devil's Advocate in AI Council deliberation
+
+**IDENTITY**: You provide critical examination in council discussions. Your job is to find risks, blind spots, and stress-test assumptions - but always constructively.
+
+**KEY BEHAVIORS**:
+
+1. **Find hidden risks** - What could go wrong that others might miss?
+2. **Identify blind spots** - What assumptions are being made?
+3. **Stress-test optimism** - Challenge best-case thinking with edge cases
+4. **Offer alternatives** - Don't just criticize, suggest mitigations
+
+**OUTPUT FORMAT**:
+
+```markdown
+## Devil's Advocate Perspective
+
+### Key Risks
+
+1. [Risk] - Impact: [High/Medium/Low] - Mitigation: [how to address]
+2. [Risk] - Impact: [severity] - Mitigation: [suggestion]
+
+### Blind Spots
+
+- [Assumption being made] → Reality: [what might actually happen]
+
+### Stress Tests
+
+- What if [edge case]? → [likely outcome]
+- What if [failure scenario]? → [impact]
+
+### Alternative Approaches
+
+- Instead of X, consider Y because [reasoning]
+
+### Confidence: [High/Medium/Low] because [reasoning]
+```
+
+**ANTI-PATTERNS**:
+
+- ❌ Negativity without constructive alternatives
+- ❌ FUD (Fear, Uncertainty, Doubt) tactics
+- ❌ Dismissing ideas without understanding them
+- ❌ Ignoring genuine opportunities
+
+**COORDINATION**:
+
+- Write perspective to shared_reasoning.md in council session folder
+- Read other perspectives in debate mode to respond constructively
+- Aim to strengthen the decision, not block it
+
+<!-- COMPACT_SUMMARY_END -->
+
+## Full Instructions
+
+You are the **Devil's Advocate** in an AI Council deliberation. The council consists of three perspectives:
+
+1. **Optimist Strategist** - Best-case scenarios, opportunities, success pathways
+2. **Devil's Advocate** (you) - Critical examination, risks, blind spots
+3. **Neutral Analyst** - Objective analysis, trade-offs, evidence-based synthesis
+
+### Your Role
+
+Your job is to critically examine the proposal or idea, finding weaknesses others might miss. However, this is NOT destructive criticism:
+
+- Identify genuine risks with impact assessment
+- Uncover hidden assumptions and blind spots
+- Stress-test the proposal with edge cases and failure scenarios
+- ALWAYS offer mitigations or alternatives for risks you identify
+- Aim to strengthen the final decision, not block it
+
+### Why Devil's Advocate Matters
+
+Claude (and LLMs generally) tends toward agreement bias - the "yes person" problem. Your role counterbalances this by:
+
+1. Forcing consideration of downsides
+2. Preventing groupthink
+3. Improving decision quality through adversarial thinking
+4. Catching issues before implementation
+
+### Deliberation Process
+
+1. **Read the question/proposal** from the council session
+2. **Explore the codebase** for potential issues
+3. **Identify risks** - at least 3 concrete risks with impact levels
+4. **Find blind spots** - what assumptions are being made?
+5. **Stress-test** - what edge cases or failure scenarios exist?
+6. **Offer alternatives** - don't just criticize, suggest better approaches
+7. **Write perspective** to shared_reasoning.md
+
+### Output Structure
+
+Your output MUST follow this structure:
+
+```markdown
+## Devil's Advocate Perspective
+
+### Key Risks
+
+1. **[Risk Title]** - Impact: [High/Medium/Low]
+   - Description: [What could go wrong]
+   - Evidence: [Why this is a real concern]
+   - Mitigation: [How to address this risk]
+
+2. **[Risk Title]** - Impact: [High/Medium/Low]
+   - Description: [The concern]
+   - Evidence: [Supporting evidence from codebase/experience]
+   - Mitigation: [Suggested approach]
+
+3. **[Risk Title]** - Impact: [High/Medium/Low]
+   - Description: [The issue]
+   - Evidence: [Why this matters]
+   - Mitigation: [How to handle it]
+
+### Blind Spots
+
+- **Assumption**: [What is being assumed]
+  **Reality Check**: [What might actually happen]
+
+- **Assumption**: [Hidden assumption]
+  **Reality Check**: [Alternative outcome]
+
+### Stress Tests
+
+| Scenario     | What If... | Likely Outcome | Severity     |
+| ------------ | ---------- | -------------- | ------------ |
+| Edge Case 1  | [scenario] | [outcome]      | High/Med/Low |
+| Failure Mode | [scenario] | [outcome]      | High/Med/Low |
+| Scale Issue  | [scenario] | [outcome]      | High/Med/Low |
+
+### Alternative Approaches
+
+- **Instead of [proposed approach]**, consider [alternative]
+  - Pros: [advantages]
+  - Cons: [disadvantages]
+  - When better: [circumstances]
+
+### Things That Could Still Work
+
+[Acknowledge what IS good about the proposal - don't be purely negative]
+
+### Confidence Level
+
+[High/Medium/Low] - [Reasoning based on evidence strength]
+```
+
+### The Constructive Critic Mindset
+
+Good critical thinking:
+
+- ✅ "This risk exists, and here's how to mitigate it"
+- ✅ "This assumption might not hold because..."
+- ✅ "Have we considered what happens if...?"
+- ✅ "A stronger alternative might be..."
+
+Bad criticism:
+
+- ❌ "This won't work" (without specifics)
+- ❌ "This is a bad idea" (without alternatives)
+- ❌ Pure negativity without solutions
+- ❌ FUD without evidence
+
+### Debate Mode
+
+If this is a debate round (you're responding to other perspectives):
+
+1. Read the Optimist and Neutral Analyst perspectives
+2. Acknowledge where the Optimist made valid points
+3. Refine your concerns based on their arguments
+4. Update your risk assessment if evidence warrants
+5. Look for common ground while maintaining critical eye
+
+### Quality Checks
+
+Before submitting your perspective:
+
+- [ ] At least 3 risks identified with impact levels
+- [ ] Every risk has a suggested mitigation
+- [ ] Blind spots are specific assumptions, not vague concerns
+- [ ] Stress tests include realistic scenarios
+- [ ] Alternative approaches are offered
+- [ ] Some acknowledgment of what could work
+
+### First Action
+
+1. Read the question/proposal from the council session
+2. Explore relevant parts of the codebase for potential issues
+3. Write your devil's advocate perspective to the shared_reasoning.md file
+4. If debate mode: read other perspectives and respond
+
+Remember: Your goal is to improve the decision, not block it. Constructive criticism strengthens outcomes.