ai-core-framework 0.1.0

package/core/skills/planning-analyze-requirements/SKILL.md

@@ -0,0 +1,471 @@
+---
+name: planning-analyze-requirements
+description: Use when the user asks to run /analyze-requirements, turn stakeholder requirement text into a ticket, clarify acceptance criteria, or analyze a new product request.
+command: /analyze-requirements
+display_name: "Analyze Requirements"
+version: 1.0.0
+owner_agent: business-analyst
+requires_agents:
+  - business-analyst  # Main executor
+consults_agents:
+  - tech-lead         # Optional: if technical sanity check is required
+model_preference: opus
+args:
+  - name: requirement_text
+    required: true
+    type: string
+    description: "Free text requirement from stakeholder"
+  - name: source
+    required: false
+    type: string
+    default: "user-input"
+    description: "Source: stakeholder-email | slack | figma-link | user-input | voice-transcript"
+preconditions:
+  - ai_core_initialized: true
+  - business_analyst_agent_available: true
+postconditions:
+  - ticket_created: true
+  - ticket_state: DRAFT
+  - ticket_has_user_story: true
+  - ticket_has_acceptance_criteria: true (min 3 scenarios)
+---
+
+# /analyze-requirements
+
+> Analyze stakeholder requirement and create DRAFT ticket with User Story + AC.
+> **Entry point** of the feature lifecycle.
+
+## 🎯 Purpose
+
+Turn free-text requirement (email, Slack, voice note) into a structured ticket with:
+- User Story (INVEST-compliant)
+- Acceptance Criteria (≥3 Gherkin scenarios)
+- Priority (MoSCoW)
+- Classification (feature/enhancement/bug/tech-debt)
+- Ready for grooming session
+
+## 🚦 Trigger
+
+**Manual** (primary):
+```
+/analyze-requirements "I want users to reset passwords by email"
+```
+
+**With source specification**:
+```
+/analyze-requirements --source=slack "CEO: Customers are complaining about Excel export"
+```
+
+**Auto** (experimental): Webhook from Slack/email integration (Phase 3+).
+
+## 📋 Preconditions (STRICT)
+
+Check before starting. **ABORT** if any check fails.
+
+### 1. `core/` initialized
+```bash
+test -d "project/tickets" || ABORT "Run /setup-project first"
+```
+
+### 2. BA agent available
+Check `core/agents/business-analyst.md` exists and is enabled in config.
+
+### 3. Requirement text is not empty
+If empty or < 10 chars → ABORT and ask for the actual requirement.
+
+## 🔄 Execution Flow (STRICT ORDER)
+
+```
+┌──────────────────────────────────────────────────────────┐
+│ STEP 1: Ingest requirement                               │
+│   - Parse free text                                      │
+│   - Note source (email/Slack/etc)                        │
+├──────────────────────────────────────────────────────────┤
+│ STEP 2: 5W1H Analysis                                    │
+│   Ask mentally:                                          │
+│   - WHO is the user? (persona)                           │
+│   - WHAT do they need to do? (action)                    │
+│   - WHY? (business value)                                │
+│   - WHEN? (priority/deadline)                            │
+│   - WHERE? (module/feature area)                         │
+│   - HOW to verify? (acceptance)                          │
+│                                                          │
+│   Score clarity 0-6 (one point per W/H)                 │
+│   If < 4: ABORT, ask clarifying questions                │
+├──────────────────────────────────────────────────────────┤
+│ STEP 3: Classify                                         │
+│   - Feature: new user-facing capability                  │
+│   - Enhancement: improve existing feature                │
+│   - Bug: something broken                                │
+│   - Tech-debt: refactor, cleanup                         │
+│   - Spike: research/exploration                          │
+│                                                          │
+│   If Bug: determine severity SEV-1/2/3/4                 │
+│   If SEV-1: flag as HOTFIX PATH, notify SM              │
+├──────────────────────────────────────────────────────────┤
+│ STEP 4: Assign Priority (MoSCoW)                         │
+│   - MUST: core functionality, blockers                   │
+│   - SHOULD: important but not blocking                   │
+│   - COULD: nice to have                                  │
+│   - WONT: out of scope for now                           │
+├──────────────────────────────────────────────────────────┤
+│ STEP 5: Generate User Story                              │
+│   Format: "As a <persona>,                               │
+│            I want <action>,                              │
+│            So that <business value>"                     │
+│                                                          │
+│   Validate INVEST:                                       │
+│   - Independent? (can ship alone)                        │
+│   - Negotiable? (not locked to implementation)           │
+│   - Valuable? (clear business value)                     │
+│   - Estimable? (not too vague for estimate)              │
+│   - Small? (sized right for sprint)                      │
+│   - Testable? (can verify objectively)                   │
+│                                                          │
+│   If fails INVEST: iterate or split                      │
+├──────────────────────────────────────────────────────────┤
+│ STEP 6: Generate Acceptance Criteria                     │
+│   Minimum 3 Gherkin scenarios:                           │
+│   - Happy path                                           │
+│   - Edge case                                            │
+│   - Error case                                           │
+│   (Add more if relevant: security, performance, ...)     │
+│                                                          │
+│   Each MUST be testable (QA can write test case).       │
+├──────────────────────────────────────────────────────────┤
+│ STEP 7: Check dependencies                               │
+│   - Does this relate to existing tickets?                │
+│   - Does it block/blocked by other tickets?              │
+│   - External dependencies (3rd party API)?               │
+├──────────────────────────────────────────────────────────┤
+│ STEP 8: Generate ticket ID                               │
+│   - Read project/tickets/                         │
+│   - Find highest TICKET-NNN                              │
+│   - Increment: TICKET-NNN+1                              │
+├──────────────────────────────────────────────────────────┤
+│ STEP 9: Write ticket JSON                                │
+│   Path: project/tickets/TICKET-XXX.json           │
+│   Schema: core/config/ticket.schema.json             │
+│   State: DRAFT                                           │
+│   created_by: "business-analyst-agent"                   │
+├──────────────────────────────────────────────────────────┤
+│ STEP 10: Validate schema                                 │
+│   Run scripts/validate-state.sh                          │
+│   If fails: retry with fixes                             │
+├──────────────────────────────────────────────────────────┤
+│ STEP 11: Output summary + HANDOFF                        │
+│   - Print ticket preview                                 │
+│   - HANDOFF → tech-lead for grooming                     │
+└──────────────────────────────────────────────────────────┘
+```
+
+## 🔒 Hard Rules
+
+### RULE AR-001: 5W1H gate
+If requirement does not pass 5W1H check (clarity score < 4/6) → **MUST** stop and ask. Guessing missing info is **FORBIDDEN**.
+
+### RULE AR-002: Minimum 3 AC scenarios
+**MUST** generate ≥3 AC scenarios. If only 1-2 → suspect requirement is not clear enough → request more info.
+
+### RULE AR-003: INVEST compliance
+User Story **MUST** pass INVEST. If not → **MUST** propose splitting it into multiple tickets.
+
+### RULE AR-004: No estimate
+BA agent **MUST NOT** estimate story points in this command. That belongs to Tech Lead in `/groom-ticket`.
+
+### RULE AR-005: No technical solution
+**MUST NOT** specify HOW to implement (framework, library, code structure). Only WHAT + WHY.
+
+### RULE AR-006: Bug severity
+If ticket type = bug, **MUST** assign severity:
+- SEV-1: Production down, data loss, security breach
+- SEV-2: Major feature broken, many users affected
+- SEV-3: Minor issue, workaround exists
+- SEV-4: Cosmetic, edge case
+
+### RULE AR-007: SEV-1 fast track
+SEV-1 bug **MUST** trigger hotfix notification:
+- Console output: `🚨 SEV-1 BUG DETECTED - Hotfix path activated`
+- Suggest: `/hotfix TICKET-XXX` instead of normal sprint flow
+- HANDOFF → scrum-master + tech-lead immediately
+
+### RULE AR-008: Template enforcement
+**MUST** use template `templates/requirements/user-story-template.md` format. Freestyle is **FORBIDDEN**.
+
+### RULE AR-009: No duplicate tickets
+Before creating, **MUST** search existing tickets for similar work:
+- Grep titles in `project/tickets/*.json`
+- If high similarity (>80%) → flag to user, ask if duplicate
+
+### RULE AR-010: Complete source tracking
+**MUST** capture source metadata:
+- Where requirement came from (email/Slack/meeting)
+- Who originated (stakeholder name if any)
+- Timestamp
+
+Store in ticket `labels` or dedicated field.
+
+## 📥 Input Examples
+
+### Example 1: Feature request
+```
+User: /analyze-requirements "I want users to reset passwords by email"
+```
+
+### Example 2: Bug report
+```
+User: /analyze-requirements "Login returns 500 when email contains a plus sign"
+```
+
+### Example 3: Vague (will fail 5W1H)
+```
+User: /analyze-requirements "Improve performance"
+```
+Expected response: Ask clarifying questions (what's slow, who notices, acceptance criteria).
+
+### Example 4: Complex (multi-feature)
+```
+User: /analyze-requirements "Users should be able to reset password, enable 2FA,
+      and change email. All actions require email confirmation."
+```
+Expected: Propose splitting into 3 tickets.
+
+## 📤 Output Formats
+
+### Success output
+
+```markdown
+## ✅ Analyzed: Password Reset via Email
+
+**Created**: TICKET-042
+**Type**: Feature
+**Priority**: MUST
+**Status**: DRAFT → awaiting grooming
+
+### User Story
+**As a** registered user who forgot their password,
+**I want** to reset my password by email,
+**So that** I can regain account access without contacting support.
+
+### Acceptance Criteria
+
+**Scenario 1: Happy path - successful reset**
+```gherkin
+Given User has an account with email user@example.com
+When User requests password reset and clicks the email link
+Then User can set a new password and log in successfully
+```
+
+**Scenario 2: Edge - email does not exist**
+```gherkin
+Given User enters an unregistered email
+When User submits the password reset form
+Then System displays a generic message, does not leak email existence, and does not send email
+```
+
+**Scenario 3: Error - link expired**
+```gherkin
+Given User received the password reset email 25 hours ago
+When User clicks the link
+Then System displays "Link expired" and allows requesting a new link
+```
+
+**Scenario 4: Security - rate limit**
+```gherkin
+Given User has requested reset 5 times within 1 hour
+When User makes the 6th request
+Then System rejects with message "Too many requests"
+```
+
+### Business Context
+Customer complaints: 15 support tickets/week about password issues.
+Estimated: 40% support load reduction if self-service reset works.
+
+### Dependencies
+- Blocked by: None
+- Blocks: TICKET-045 (user settings UI depends on this)
+- External: Need SendGrid API credentials
+
+### Out of Scope
+- SMS-based reset (future ticket)
+- Security questions (deprecated flow)
+- Password change while logged in (separate ticket TICKET-XXX)
+
+### Open Questions for Tech Lead
+- [ ] Token expiration: 24h OK or shorter?
+- [ ] Rate limit: 5/hour/email OK?
+- [ ] Email template: existing template system or custom?
+
+### Ticket File
+Created: `project/tickets/TICKET-042.json`
+
+---
+HANDOFF → tech-lead
+Action needed: /groom-ticket TICKET-042 (estimate + technical feasibility)
+```
+
+### Failure output (vague requirement)
+
+```markdown
+## ⚠️ Cannot analyze: requirement unclear
+
+**Input**: "Improve performance"
+
+### Missing information (5W1H analysis)
+
+| Dimension | Status | Need |
+|-----------|--------|------|
+| WHO | ❌ Unknown | Which users experience this? |
+| WHAT | ⚠️ Vague | What specific operation is slow? |
+| WHY | ❌ Unknown | Why is this important now? |
+| WHEN | ❌ Unknown | Priority? Deadline? |
+| WHERE | ❌ Unknown | Which page/feature/endpoint? |
+| HOW | ❌ Unknown | What's "fast enough"? Target p95? |
+
+### Please provide:
+1. Which part of the app is slow? (specific page, API endpoint, operation)
+2. How slow is it now? (any metric, even subjective)
+3. What's acceptable performance? (e.g., "< 2s", "feels instant")
+4. Who reported it? (user feedback, internal, monitoring?)
+5. How many users affected?
+
+### Suggested format:
+"[Users] are experiencing [slow X] when doing [Y]. 
+Current: [Z ms/s]. Target: [W ms/s]. Reported by [source]."
+
+Re-run `/analyze-requirements` with more detail.
+```
+
+### Failure output (duplicate detected)
+
+```markdown
+## ⚠️ Possible duplicate detected
+
+**Input**: "User resets password by email"
+
+### Similar existing ticket:
+- **TICKET-038**: "Password reset flow" (Status: IN_PROGRESS)
+  Similarity: 87%
+
+### Options:
+1. If it's the same: don't create new ticket. Check TICKET-038 status.
+2. If it's different: re-run with more specific scope, e.g.:
+   - "SMS-based password reset (different channel from TICKET-038)"
+   - "Password reset for SSO users (different user segment)"
+
+What would you like to do?
+```
+
+### Failure output (SEV-1 bug)
+
+```markdown
+## 🚨 SEV-1 BUG DETECTED - Hotfix Path Activated
+
+**Created**: TICKET-101 (HOTFIX)
+**Type**: Bug
+**Severity**: SEV-1 (Critical)
+**Priority**: MUST (hotfix)
+
+### Bug Summary
+Login endpoint returning 500 for all users with emails containing "+"
+
+### Impact
+- Users affected: ~30% (emails with +)
+- Symptoms: Cannot log in, no error message
+- Workaround: None
+- Data loss risk: None
+
+### Acceptance Criteria
+**Scenario 1: Fix - email with +**
+```gherkin
+Given User has email "user+tag@example.com"
+When User enters email + password
+Then User logs in successfully
+```
+
+**Scenario 2: Regression - normal email still works**
+```gherkin
+Given User has email "user@example.com"
+When User login
+Then User logs in successfully
+```
+
+**Scenario 3: Security - SQL injection still prevented**
+```gherkin
+Given Attacker tries email "admin@x.com' OR 1=1--"
+When Attempted login
+Then Login fails, no SQL injection possible
+```
+
+### 🚨 Immediate Actions Required
+
+1. **SM**: Declare incident, notify stakeholders
+2. **Tech Lead**: Start `/hotfix TICKET-101` 
+3. **Dev**: Pair with Tech Lead on fix
+
+### Ticket File
+Created: `project/tickets/TICKET-101.json`
+
+---
+HANDOFF → scrum-master + tech-lead (URGENT)
+Action needed: /hotfix TICKET-101
+```
+
+## 🚨 Failure Modes & Recovery
+
+| Scenario | Action |
+|----------|--------|
+| Requirement has < 4/6 5W1H score | ABORT, ask specific questions |
+| Cannot extract clear persona | ABORT, ask "who is this for?" |
+| No testable outcome identified | ABORT, ask "how do we know it works?" |
+| Possible duplicate (>80% similarity) | WARN, let user decide |
+| Ticket too big (>8 points estimated) | SUGGEST SPLIT, but let BA decide (Tech Lead will enforce in grooming) |
+| Contradicts existing feature | ASK for clarification, flag for stakeholder review |
+| Schema validation fails | Retry up to 3 times, then escalate to human |
+
+## 🔗 Related Commands
+
+- **Before**: None (entry point)
+- **After**: `/groom-ticket TICKET-XXX` (mandatory next step)
+- **Alternative paths**:
+  - SEV-1 bug: `/hotfix TICKET-XXX`
+  - Spike ticket: `/create-spike TICKET-XXX`
+
+## 📊 Metrics Tracked
+
+Log to `project/metrics/analyze-requirements.jsonl`:
+
+```json
+{
+  "timestamp": "2026-04-18T10:00:00Z",
+  "input_length": 142,
+  "source": "user-input",
+  "ticket_created": "TICKET-042",
+  "type": "feature",
+  "priority": "MUST",
+  "ac_scenarios_count": 4,
+  "clarity_score": 6,
+  "duration_seconds": 45,
+  "clarifications_requested": 0
+}
+```
+
+## 💡 Tips for Users
+
+**Give context**:
+- ❌ "Add export feature"
+- ✅ "Admin users need to export user list to CSV for compliance audit"
+
+**Specify persona**:
+- ❌ "Make it faster"
+- ✅ "Free-tier users experience dashboard load > 5s"
+
+**Quote stakeholders**:
+- ✅ "CEO email: 'Enterprise customers need SSO before Q3'"
+
+**Provide metrics when possible**:
+- ✅ "Page load currently p95 = 4.2s, target p95 < 2s"
+
+---
+**Last updated**: 2026-04-18
+**Maintainer**: Business Analyst agent

package/core/skills/planning-backlog-status/SKILL.md

@@ -0,0 +1,57 @@
+---
+name: planning-backlog-status
+description: Use when the user asks to run /backlog-status, summarize backlog state, inspect backlog items by status or priority, or report planning readiness.
+command: /backlog-status
+display_name: "Backlog Status"
+version: 1.0.0
+status: READY
+owner_agent: business-analyst
+consults_agents:
+  - scrum-master
+model_preference: sonnet
+args: []
+preconditions:
+  - backlog_exists: "project/backlog/backlog.json"
+postconditions:
+  - backlog_report_generated: true
+---
+
+# /backlog-status
+
+> Reports backlog health from `project/backlog/backlog.json` and linked ticket files.
+
+## 🎯 Purpose
+
+Show whether the backlog is prioritized, actionable, and aligned with ticket state.
+
+## 🔄 Execution Flow
+
+1. Load `project/backlog/backlog.json`.
+2. Load referenced `project/tickets/TICKET-XXX.json` files.
+3. Detect missing ticket references.
+4. Detect duplicate ranks or duplicate ticket IDs.
+5. Group by priority, epic, and status.
+6. Highlight tickets needing grooming, readiness, or cancellation.
+7. Recommend next commands.
+
+## 🔒 Hard Rules
+
+- Backlog ordering source of truth is `project/backlog/backlog.json`.
+- Ticket detail source of truth is `project/tickets/TICKET-XXX.json`.
+- MUST NOT duplicate full ticket content in backlog reports.
+- MUST flag backlog items pointing to missing tickets.
+
+## 📤 Outputs
+
+- Backlog item count
+- Ready versus not ready count
+- Missing or duplicate entries
+- Top priority candidates
+- Suggested next commands
+
+## 🔗 Related Commands
+
+- `/prioritize-backlog`
+- `/groom-ticket`
+- `/mark-ready`
+- `/generate-views`