ai-core-framework 0.1.0

package/core/templates/requirements/user-story-template.md

@@ -0,0 +1,381 @@
+<!--
+User Story Template
+Used by: business-analyst agent (via /analyze-requirements)
+Consumed by: tech-lead (via /groom-ticket), developer (via /implement-task), qa-tester
+
+Instructions:
+- Fill ALL required sections (marked with *)
+- Delete sections marked "optional" if not applicable
+- Keep language clear, specific, testable
+- Avoid implementation details (HOW) - focus on WHAT + WHY
+- INVEST compliance required (see checklist at bottom)
+-->
+
+# TICKET-XXX: [Short descriptive title] *
+
+<!-- 
+Title guidelines:
+- Max 80 chars
+- Action-oriented: "Add X", "Fix Y", "Refactor Z"
+- Specific: "Add password reset via email" > "Improve auth"
+- No implementation details: "Add password reset" > "Implement JWT-based password reset"
+-->
+
+---
+
+## 📋 Metadata *
+
+| Field | Value |
+|-------|-------|
+| **Ticket ID** | `TICKET-XXX` |
+| **Type** | `feature` \| `enhancement` \| `bug` \| `tech-debt` \| `spike` |
+| **Priority (MoSCoW)** | `MUST` \| `SHOULD` \| `COULD` \| `WONT` |
+| **Severity** (bugs only) | `SEV-1` \| `SEV-2` \| `SEV-3` \| `SEV-4` |
+| **Status** | `DRAFT` (auto at creation) |
+| **Epic** | `EPIC-XXX` (optional) |
+| **Source** | stakeholder-email \| slack \| user-interview \| support-ticket \| meeting \| other |
+| **Requested by** | [Stakeholder name or role] |
+| **Created by** | business-analyst-agent |
+| **Created at** | YYYY-MM-DD HH:MM |
+
+---
+
+## 👤 User Story *
+
+<!--
+Format: "As a <persona>, I want <action>, So that <business value>"
+
+Guidelines:
+- Persona: specific user type (not "user" - be specific: "registered user", "admin", "free-tier customer")
+- Action: what they want to DO (not how system implements it)
+- Value: WHY this matters to them or business
+-->
+
+**As a** [specific persona],  
+**I want** [specific action / capability],  
+**So that** [business / user value].
+
+### Example
+> **As a** registered user who forgot their password,  
+> **I want to** reset my password via email,  
+> **So that** I can regain access to my account without contacting support.
+
+---
+
+## 🎯 Business Context *
+
+<!--
+Why is this important? What problem does it solve?
+Include metrics/evidence when possible.
+-->
+
+### Problem statement
+<!-- 1-3 sentences describing the problem -->
+
+### Current state
+<!-- What happens now without this feature/fix? -->
+- 
+- 
+
+### Desired state
+<!-- What changes after this is done? -->
+- 
+- 
+
+### Success metrics
+<!-- How do we measure success? -->
+- **Primary metric**: [e.g., "Support tickets re: password reduce by 40%"]
+- **Secondary**: [e.g., "User reactivation rate +5%"]
+
+---
+
+## ✅ Acceptance Criteria *
+
+<!--
+MINIMUM 3 scenarios required:
+1. Happy path
+2. Edge case
+3. Error case
+Add more for security, performance, etc.
+
+Use Gherkin format (Given/When/Then).
+Each MUST be testable - QA can write a test case from this.
+-->
+
+### Scenario 1: [Happy path - descriptive name] *
+
+```gherkin
+Given [initial context / precondition]
+And [additional context if needed]
+When [user action or event]
+Then [expected outcome]
+And [additional outcomes]
+```
+
+**Example**:
+```gherkin
+Given User has an account with email "user@example.com"
+When User requests a password reset for that email
+And User clicks the link in the received email
+Then User is redirected to the new password page
+And User can enter a new password and log in successfully
+```
+
+---
+
+### Scenario 2: [Edge case - descriptive name] *
+
+```gherkin
+Given [edge context]
+When [action]
+Then [expected behavior]
+```
+
+**Example**:
+```gherkin
+Given User enters an email that is not registered in the system
+When User submit form reset password
+Then System displays message "If this email is registered, reset instructions have been sent"
+And System MUST NOT send a real email, preventing email enumeration
+```
+
+---
+
+### Scenario 3: [Error case - descriptive name] *
+
+```gherkin
+Given [error context]
+When [action]
+Then [error handling]
+```
+
+**Example**:
+```gherkin
+Given User received the reset email more than 24 hours ago
+When User click link reset
+Then System displays "This link has expired. Please request a new one"
+And System allows the user to request a new link on the same page
+```
+
+---
+
+### Scenario 4 (optional): [Security case - e.g., rate limiting]
+
+```gherkin
+Given [security context]
+When [attack vector attempt]
+Then [defense behavior]
+```
+
+**Example**:
+```gherkin
+Given User has requested a reset 5 times within 1 hour
+When User makes the 6th request
+Then System rejects it with HTTP 429 "Too many requests"
+And System displays "Please try again in X minutes"
+```
+
+---
+
+### Scenario 5 (optional): [Performance case]
+
+```gherkin
+Given [performance context]
+When [load condition]
+Then [performance expectation]
+```
+
+---
+
+## 🚫 Out of Scope
+
+<!--
+Explicitly state what is NOT included.
+Prevents scope creep and sets expectations.
+-->
+
+- [ ] [Feature not included in this ticket]
+- [ ] [Another future enhancement]
+- [ ] [Related work tracked elsewhere]
+
+**Example**:
+- [ ] SMS-based password reset (future ticket)
+- [ ] Security questions flow (deprecated, not coming back)
+- [ ] Password change while logged in (see TICKET-045)
+- [ ] Admin-initiated password reset (see TICKET-046)
+
+---
+
+## 🔗 Dependencies
+
+### Blocked by
+<!-- Tickets that must complete before this can start -->
+- [ ] TICKET-XXX: [brief description]
+
+### Blocks
+<!-- Tickets that depend on this -->
+- TICKET-YYY: [brief description]
+
+### External dependencies
+<!-- 3rd party services, credentials, infrastructure -->
+- [ ] [e.g., "SendGrid API credentials (contact DevOps)"]
+- [ ] [e.g., "Figma design approved by UX (pending)"]
+
+### Data dependencies
+<!-- New tables, migrations, data imports -->
+- [ ] [e.g., "New table `password_reset_tokens` - migration needed"]
+
+---
+
+## 🎨 Design / Mockups
+
+<!-- Delete section if not applicable -->
+
+### Figma
+<!-- Link to design files -->
+- [Design doc](link)
+- [Mockup v2](link)
+
+### Copy / Content
+<!-- Exact text, especially for user-facing strings -->
+
+| Context | Text |
+|---------|------|
+| Email subject | `Reset your password` |
+| Email body CTA | `Reset password` |
+| Success message | `Password updated successfully. Please log in with your new password.` |
+| Expired link | `This link has expired. Request a new one below.` |
+
+### i18n / l10n
+<!-- Is this translated? Which locales? -->
+- [ ] i18n keys needed: `auth.reset_password.*`
+- [ ] Locales: en (MVP), vi, ja (later sprints)
+
+---
+
+## ❓ Open Questions
+
+<!--
+Questions that need answers BEFORE implementation.
+Tech Lead will review these during grooming.
+-->
+
+### For Tech Lead
+- [ ] [Technical question]
+- [ ] [Architecture decision question]
+
+**Examples**:
+- [ ] Token expiration: 24h acceptable or should be shorter?
+- [ ] Rate limit approach: per-email or per-IP or both?
+- [ ] Email template: reuse existing framework or build new?
+
+### For Product / Stakeholder
+- [ ] [Product decision]
+
+**Examples**:
+- [ ] Should we notify user via email AFTER password successfully changed?
+- [ ] Should reset also invalidate all existing sessions?
+
+### For Design / UX
+- [ ] [Design question]
+
+---
+
+## 🧪 Test Considerations
+
+<!-- Guidance for QA test planning -->
+
+### Test types needed
+- [ ] Unit tests (developer)
+- [ ] Integration tests (developer)
+- [ ] E2E tests (if critical user flow)
+- [ ] Security tests (if touching auth/data)
+- [ ] Performance tests (if on hot path)
+- [ ] Accessibility tests (if UI change)
+- [ ] Cross-browser tests (if UI change)
+- [ ] Mobile responsive tests (if UI change)
+
+### Test data requirements
+<!-- Any special data setup? -->
+- 
+
+### Environment requirements
+<!-- Staging? Preview deploy? Specific config? -->
+- 
+
+---
+
+## ⚠️ Risks & Concerns
+
+<!--
+BA can list initial concerns. Tech Lead refines during grooming.
+-->
+
+- [ ] [Concern 1]
+- [ ] [Concern 2]
+
+**Examples**:
+- [ ] Email deliverability (spam filters for transactional emails)
+- [ ] Token enumeration if RNG not cryptographically secure
+- [ ] Locale of email content (which language to send?)
+
+---
+
+## 📊 INVEST Compliance Check
+
+<!--
+BA MUST verify this before marking ticket ready for grooming.
+If any fail, iterate on story or propose split.
+-->
+
+- [ ] **Independent**: Can be shipped alone without waiting on another ticket mid-flight
+- [ ] **Negotiable**: AC could be adjusted (not locked to specific implementation)
+- [ ] **Valuable**: Business value clearly stated
+- [ ] **Estimable**: Enough detail for Tech Lead to estimate (≤ 8 points target)
+- [ ] **Small**: Fits in one sprint (if too big, split)
+- [ ] **Testable**: Every AC scenario is verifiable
+
+---
+
+## 📝 Additional Notes
+
+<!-- Any context that doesn't fit above sections -->
+
+### Assumptions made
+<!-- What did BA assume while writing this? -->
+- 
+
+### Source material
+<!-- Quotes from stakeholder, links to interviews, etc. -->
+
+**Example**:
+> "Our customers keep calling support when they forget passwords. We've had 15 tickets this week alone. We need self-service." — CEO email, 2026-04-15
+
+---
+
+## 🔄 Change History
+
+<!-- Auto-populated on state transitions -->
+
+| Date | State | Agent / Person | Note |
+|------|-------|----------------|------|
+| YYYY-MM-DD | DRAFT | business-analyst | Ticket created |
+
+---
+
+## 🤝 Handoff
+
+**Next step**: `/groom-ticket TICKET-XXX`  
+**Assigned to**: tech-lead  
+**Expected**: Technical approach + estimate + risks within 1-2 business days
+
+---
+
+<!--
+DO NOT EDIT BELOW - auto-populated fields
+-->
+
+<!-- TEMPLATE_VERSION: 1.0.0 -->
+<!-- CREATED_BY_AGENT: business-analyst -->
+<!-- NEXT_AGENT: tech-lead -->
+<!-- SCHEMA: core/config/ticket.schema.json -->

package/core/templates/technical/ADR-template.md

@@ -0,0 +1,46 @@
+# Architecture Decision Record Template
+
+## Status
+
+Proposed | Accepted | Deprecated | Superseded
+
+## Context
+
+Describe the forces, constraints, and problem that require a decision.
+
+## Decision
+
+State the decision clearly.
+
+## Alternatives Considered
+
+| Option | Pros | Cons | Reason rejected or accepted |
+|--------|------|------|-----------------------------|
+| | | | |
+
+## Consequences
+
+### Positive
+
+- 
+
+### Negative
+
+- 
+
+### Risks
+
+- 
+
+## Implementation Notes
+
+- Owner:
+- Target ticket:
+- Migration required:
+- Rollback or mitigation:
+
+## Links
+
+- Tickets:
+- PRs:
+- Docs:

package/core/templates/technical/refactor-plan-template.md

@@ -0,0 +1,84 @@
+# Refactor Plan Template
+
+## Metadata
+
+- Plan ID:
+- Owner:
+- Status:
+- Created:
+- Related epic:
+- Related ADRs:
+
+## Problem
+
+Describe the current technical problem and why it matters now.
+
+## Goals
+
+- 
+
+## Non-Goals
+
+- 
+
+## Affected Areas
+
+| Area | Current issue | Target state | Risk |
+|------|---------------|--------------|------|
+| | | | |
+
+## Constraints
+
+- Backward compatibility:
+- Data migration:
+- Performance:
+- Security:
+- Release timing:
+
+## Proposed Approach
+
+Describe the refactor strategy and sequence.
+
+## Phases
+
+| Phase | Objective | Tickets | Exit criteria |
+|-------|-----------|---------|---------------|
+| 1 | | | |
+| 2 | | | |
+| 3 | | | |
+
+## Ticket Breakdown
+
+| Ticket | Type | Summary | Depends on |
+|--------|------|---------|------------|
+| TICKET-XXX | tech-debt | | |
+
+## Testing Strategy
+
+- Characterization tests before refactor:
+- Unit tests:
+- Integration tests:
+- E2E smoke tests:
+- Performance checks:
+
+## Rollout Plan
+
+- Feature flags:
+- Incremental deploy:
+- Monitoring:
+- Rollback:
+
+## Risks and Mitigations
+
+| Risk | Probability | Impact | Mitigation | Owner |
+|------|-------------|--------|------------|-------|
+| | | | | |
+
+## Verification Checklist
+
+- [ ] Existing behavior covered by tests
+- [ ] No public API regression
+- [ ] Performance within threshold
+- [ ] Security review complete if sensitive area
+- [ ] Docs updated
+- [ ] Follow-up tickets created

package/core/templates/technical/tech-design-template.md

@@ -0,0 +1,71 @@
+# Technical Design Template
+
+## Metadata
+
+- Ticket/epic:
+- Author:
+- Reviewers:
+- Status:
+- Date:
+
+## Summary
+
+Briefly describe the technical change.
+
+## Goals
+
+- 
+
+## Non-Goals
+
+- 
+
+## Current State
+
+Describe existing architecture, data flow, and limitations.
+
+## Proposed Design
+
+### Components
+
+| Component | Responsibility | Change |
+|-----------|----------------|--------|
+| | | |
+
+### Data Model
+
+- New fields/tables:
+- Migration plan:
+- Backward compatibility:
+
+### API Contract
+
+- Endpoint/event/command:
+- Request:
+- Response:
+- Error cases:
+
+## Testing Strategy
+
+- Unit:
+- Integration:
+- E2E:
+- Manual QA:
+
+## Security and Privacy
+
+- Auth/authz:
+- Data sensitivity:
+- Logging/audit:
+- Threats and mitigations:
+
+## Rollout Plan
+
+- Feature flag:
+- Deployment steps:
+- Monitoring:
+- Rollback:
+
+## Open Questions
+
+- 

package/core/workflows/bug-lifecycle.md

@@ -0,0 +1,56 @@
+# Bug Lifecycle Workflow
+
+> Complete path from bug discovery to triage, fix, verification, and closure.
+
+## 🎯 Purpose
+
+Make bugs reproducible, prioritized, fixed with regression coverage, and verified by QA.
+
+## 🔄 Flow
+
+1. Discovery
+   - Any agent or user reports a defect with `/report-bug`.
+   - Bug is created in `project/bugs/` with status `NEW` or `NEEDS_MORE_INFO`.
+
+2. Triage
+   - BA runs `/triage-bug` with Tech Lead and QA input.
+   - Severity, priority, owner, duplicate status, and target fix window are set.
+   - SEV-1 and SEV-2 may trigger `/hotfix`.
+
+3. Fix planning
+   - For normal bugs, create or link a `TICKET-XXX` bug ticket.
+   - Ticket follows normal state machine from `DRAFT` or `READY` depending on triage confidence.
+
+4. Development
+   - Developer reproduces the bug.
+   - Developer writes regression test first.
+   - Developer fixes with `/implement-task`.
+
+5. Review and merge
+   - Developer creates PR.
+   - Tech Lead reviews.
+   - Tech Lead merges to QA.
+
+6. Verification
+   - QA runs `/verify-fix BUG-XXX` or `/smoke-test TICKET-XXX`.
+   - Pass closes or verifies the bug.
+   - Fail sends bug/ticket back to development with evidence.
+
+## 🔒 Rules
+
+- No vague bug reports accepted as actionable.
+- Severity must be justified.
+- Regression tests are mandatory for bug fixes unless documented impossible.
+- QA owns verification.
+- SEV-1 requires immediate escalation.
+
+## 📊 Artifacts
+
+- `project/bugs/BUG-XXX.json`
+- Linked ticket in `project/tickets/`
+- Verification report
+- Regression tests
+
+## 🔗 Commands
+
+`/report-bug` → `/triage-bug` → `/implement-task` → `/create-pr` → `/techlead-review` → `/merge-pr` → `/verify-fix`