ai-core-framework 0.1.0

package/core/skills/planning-groom-ticket/SKILL.md

@@ -0,0 +1,442 @@
+---
+name: planning-groom-ticket
+description: Use when the user asks to run /groom-ticket, refine a DRAFT ticket, validate acceptance criteria, estimate effort, document risks, or move a ticket to GROOMED/BLOCKED.
+command: /groom-ticket
+display_name: "Groom Ticket"
+version: 1.0.0
+owner_agent: tech-lead
+requires_agents:
+  - tech-lead           # Main executor
+consults_agents:
+  - business-analyst    # If AC needs refinement
+  - developer           # Optional: sanity check on estimate
+model_preference: opus
+args:
+  - name: ticket_id
+    required: true
+    format: "TICKET-XXX"
+    description: "Ticket ID to groom"
+preconditions:
+  - ticket_exists: "project/tickets/${ticket_id}.json"
+  - ticket_status: DRAFT
+  - has_user_story: true
+  - has_acceptance_criteria: true (min 3 scenarios)
+postconditions:
+  - ticket_status: GROOMED | BLOCKED
+  - has_estimate: true (1, 2, 3, 5, or 8 points)
+  - has_technical_approach: true
+  - has_risks_documented: true
+---
+
+# /groom-ticket
+
+> Technical grooming: Tech Lead analyzes ticket, estimates, flags risks.
+> Gate: DRAFT → GROOMED transition.
+
+## 🎯 Purpose
+
+After BA creates a DRAFT ticket, Tech Lead must:
+1. Validate feasibility
+2. Propose technical approach (WHAT + HOW at high level)
+3. Identify risks, unknowns, dependencies
+4. Estimate story points
+5. Decide: transition to GROOMED, send back to BA, or split ticket
+
+## 🚦 Trigger
+
+**Manual**:
+```
+/groom-ticket TICKET-042
+```
+
+**Batch** (multiple):
+```
+/groom-ticket TICKET-042 TICKET-043 TICKET-044
+```
+
+**Auto**: Config option to auto-trigger after `/analyze-requirements` (default: false, prefer human invocation).
+
+## 📋 Preconditions (STRICT)
+
+### 1. Ticket exists
+```bash
+test -f "project/tickets/${TICKET_ID}.json" || ABORT "Ticket not found"
+```
+
+### 2. Ticket status = DRAFT
+Grooming applies only to DRAFT tickets.
+- If GROOMED → suggest `/estimate-task` for re-estimate
+- If READY/IN_PROGRESS/DONE → ABORT
+
+### 3. Has User Story + AC
+Ticket JSON must have:
+- `user_story` object (as_a, i_want, so_that)
+- `acceptance_criteria` array with ≥3 scenarios
+
+If missing → ABORT, send back to BA:
+```
+❌ TICKET-042 missing required fields. 
+→ Send to BA: /analyze-requirements (refine)
+```
+
+### 4. Tech Lead agent enabled
+Check config.
+
+## 🔄 Execution Flow
+
+```
+┌──────────────────────────────────────────────────────────┐
+│ STEP 1: Load ticket context                              │
+│   - Read ticket JSON                                     │
+│   - Read user story + AC                                 │
+│   - Note priority, type                                  │
+├──────────────────────────────────────────────────────────┤
+│ STEP 2: Explore codebase for context                     │
+│   - Grep related features (by keywords from ticket)      │
+│   - Read related ADRs in docs/runtime/adr/                       │
+│   - Read related modules/files                           │
+│   - Look for similar completed tickets (anchor estimate) │
+├──────────────────────────────────────────────────────────┤
+│ STEP 3: Feasibility assessment                           │
+│   Verdict: FEASIBLE | FEASIBLE_WITH_CAVEATS | NOT_FEASIBLE│
+│                                                          │
+│   If NOT_FEASIBLE: document reasons, HANDOFF → BA        │
+│     for requirement revision. Transition → BLOCKED.      │
+├──────────────────────────────────────────────────────────┤
+│ STEP 4: Propose technical approach                       │
+│   - 2-3 paragraphs                                       │
+│   - Reference existing patterns                          │
+│   - Identify key technical decisions                     │
+│   - Flag decisions needing ADR                           │
+├──────────────────────────────────────────────────────────┤
+│ STEP 5: Identify dependencies                            │
+│   - Internal: other tickets blocking this                │
+│   - External: 3rd party services, APIs                   │
+│   - Data: schema changes, migrations                     │
+│   - Infrastructure: new services, config                 │
+├──────────────────────────────────────────────────────────┤
+│ STEP 6: Risk assessment                                  │
+│   For each risk:                                         │
+│   - Description                                          │
+│   - Probability: LOW | MEDIUM | HIGH                     │
+│   - Impact: LOW | MEDIUM | HIGH                          │
+│   - Mitigation strategy                                  │
+│                                                          │
+│   Overall risk level: LOW | MEDIUM | HIGH                │
+├──────────────────────────────────────────────────────────┤
+│ STEP 7: Estimate (Fibonacci)                             │
+│   Method:                                                │
+│   1. Find similar past ticket(s) as anchor               │
+│   2. Identify complexity factors                         │
+│   3. Add buffer for unknowns                             │
+│   4. Pick: 1, 2, 3, 5, or 8 points                       │
+│   5. Self-challenge: "$100 bet this fits?"               │
+│                                                          │
+│   If result > 8: SUGGEST SPLIT, don't estimate higher    │
+├──────────────────────────────────────────────────────────┤
+│ STEP 8: Split decision (if > 8 points)                   │
+│   - Propose 2-3 sub-tickets                              │
+│   - Each with own AC subset                              │
+│   - Sequenced (dependencies)                             │
+│   - HANDOFF → BA to execute split                        │
+├──────────────────────────────────────────────────────────┤
+│ STEP 9: Open questions for BA                            │
+│   List any AC ambiguity discovered.                      │
+│   - If critical: don't transition, wait for BA answer   │
+│   - If minor: note in ticket, can clarify later          │
+├──────────────────────────────────────────────────────────┤
+│ STEP 10: Update ticket JSON                              │
+│   - Add `estimate` object                                │
+│   - Add `technical_approach` field                       │
+│   - Add `risks` array                                    │
+│   - Add `dependencies` details                           │
+│   - Add grooming comment                                 │
+│   - Transition state: DRAFT → GROOMED                    │
+│   - Update state_history                                 │
+├──────────────────────────────────────────────────────────┤
+│ STEP 11: ADR check                                       │
+│   If technical approach involves decision needing ADR:   │
+│   - Suggest /create-adr                                  │
+│   - Block transition to GROOMED until ADR exists         │
+├──────────────────────────────────────────────────────────┤
+│ STEP 12: Output + HANDOFF                                │
+│   - Print grooming report                                │
+│   - HANDOFF → scrum-master for DoR check (/mark-ready)   │
+│   - Or HANDOFF → BA if questions unresolved              │
+└──────────────────────────────────────────────────────────┘
+```
+
+## 🔒 Hard Rules
+
+### RULE GR-001: Evidence-based estimate
+**MUST NOT** estimate from gut. Must reference:
+- At least 1 similar past ticket (if exists)
+- Specific complexity factors
+- Unknowns buffer justification
+
+### RULE GR-002: No estimate > 8
+If analysis → > 8 points, **MUST** propose split. Do not estimate 13 or 21 for sprint work.
+
+### RULE GR-003: Risks documented
+**MUST** identify ≥1 risk (unless truly trivial). Empty risks array on non-trivial ticket = incomplete grooming.
+
+### RULE GR-004: No implementation code
+Grooming = WHAT + HOW-at-high-level. **MUST NOT** write code snippets, only pseudo/approach.
+
+### RULE GR-005: ADR trigger check
+If approach requires:
+- New framework/library
+- Database schema major change
+- Breaking API change
+- Security model change
+- New external service integration
+
+**MUST** flag need for ADR. Block grooming completion until ADR created (or tracked as separate ticket).
+
+### RULE GR-006: Unclear AC sends back
+If AC genuinely ambiguous (not just Tech Lead preference), **MUST** HANDOFF → BA for refinement. Do not "fill in the gaps" unilaterally.
+
+### RULE GR-007: Dependencies explicit
+**MUST** list all dependencies. If none, explicitly state "No dependencies".
+
+### RULE GR-008: Respect BA's WHAT
+**MUST NOT** change user story or AC. Only technical layer. If disagreement with BA's approach → escalate, don't rewrite.
+
+### RULE GR-009: Schema validation
+After update, **MUST** run `scripts/validate-state.sh`. If fails, retry.
+
+### RULE GR-010: State transition logged
+Every state change logged in `state_history` with:
+- Timestamp
+- From/to states
+- Agent name
+- Reason
+
+## 📥 Input Examples
+
+```
+/groom-ticket TICKET-042
+/groom-ticket TICKET-042 TICKET-043 TICKET-044   # Batch
+/groom-ticket TICKET-042 --skip-ci-check         # Option flags
+```
+
+## 📤 Output Format (Success)
+
+```markdown
+## 🔍 Grooming Report: TICKET-042
+
+**Title**: Password Reset via Email
+**Type**: Feature | **Priority**: MUST
+
+### Technical Feasibility
+✅ FEASIBLE
+
+### Proposed Technical Approach
+
+Implement stateless password reset flow using JWT tokens sent via email:
+
+1. **Endpoint**: `POST /auth/request-reset` accepts email, validates format, generates secure token, sends email. Returns 202 always (prevent email enumeration).
+
+2. **Token**: `crypto.randomBytes(32)` hashed with bcrypt before DB storage. TTL 24h. Table: `password_reset_tokens`.
+
+3. **Email**: Use existing SendGrid integration (ADR-0007). Template: HTML with link `/auth/reset?token=XXX`.
+
+4. **Reset endpoint**: `POST /auth/reset-password` validates token, updates password (bcrypt), invalidates token, notifies user via email.
+
+**Reference**: Similar to TICKET-031 (email verification flow).
+
+### Key Technical Decisions
+- ✓ Token storage: DB (not JWT stateless) - need revocability
+- ⚠️ Rate limiting: middleware-level (new pattern) - **ADR needed**
+- ✓ Email service: SendGrid (existing, per ADR-0007)
+
+### Dependencies
+- **Internal**: None blocking
+- **External**: SendGrid API credentials (verified active)
+- **Data**: New table `password_reset_tokens` (migration needed)
+- **Infrastructure**: Redis for rate limiting (already deployed)
+
+### Risks
+
+| # | Risk | Probability | Impact | Mitigation |
+|---|------|-------------|--------|------------|
+| 1 | Rate limit bypass via email case variation | MEDIUM | HIGH | Normalize email to lowercase before rate check |
+| 2 | Token prediction if RNG weak | LOW | HIGH | Use `crypto.randomBytes(32)`, not `Math.random` |
+| 3 | Email not delivered (spam filter) | MEDIUM | MEDIUM | Add SPF/DKIM, fallback to resend |
+| 4 | Concurrent resets (race condition) | LOW | LOW | DB unique constraint on active token |
+
+**Overall risk level**: MEDIUM (rate limit bypass is realistic attack)
+
+### Estimate
+
+**5 story points**
+
+Reasoning:
+- Anchor: TICKET-031 (email verification) was 3 points
+- Complexity: password reset has extra flow (2 endpoints vs 1)
+- New: rate limiting middleware (+1 point, includes tests)
+- Unknowns: first SendGrid template integration in this project (+1 buffer)
+
+Self-challenge: "Bet $100 this fits 5 points?" → Yes, assuming rate limit approach decided quickly.
+
+### Split Recommendation
+
+N/A - within 8 points.
+
+### Open Questions for BA
+
+- [ ] Token expiration: Spec says 24h. Confirm OK? (Industry: 15min-24h)
+- [ ] Rate limit: 5 req/hour/email OK? Or per-IP?
+- [ ] Email copy: Use existing template or design new?
+- [ ] Notification on successful reset: email yes/no?
+
+### ADR Required
+
+⚠️ **Yes** - Rate limiting strategy is a new pattern. Suggest:
+- `/create-adr "Rate limiting middleware for auth endpoints"`
+
+Block transition to GROOMED until ADR created OR explicit decision to defer.
+
+### Ticket Update
+
+**State**: DRAFT → GROOMED ✅ (assuming questions minor)
+**Updated**: `project/tickets/TICKET-042.json`
+
+Added fields:
+- `estimate`: `{ story_points: 5, estimated_by: "tech-lead-agent", estimated_at: "..." }`
+- `technical_approach`: (see above)
+- `risks`: (4 risks documented)
+- `dependencies`: (detailed)
+
+### Next Steps
+
+1. **BA**: Answer 4 open questions (can be async)
+2. **Tech Lead**: Create ADR for rate limiting
+3. **SM**: Run `/mark-ready TICKET-042` when above done
+
+---
+HANDOFF → business-analyst
+Action needed: Answer 4 open questions above.
+```
+
+## 📤 Output Format (Send Back to BA)
+
+```markdown
+## ⚠️ Grooming Blocked: TICKET-042
+
+**Reason**: AC scenarios too ambiguous to estimate
+
+### Issues
+
+**Scenario 2** ("Edge: email does not exist"):
+- ❓ What does "generic message" mean exactly? Copy text?
+- ❓ Should system log attempt for security monitoring?
+- ❓ Response time: should be same as success (prevent timing attack)?
+
+**Scenario 3** ("Error: link expired"):
+- ❓ What's the exact expiration time? AC says "25 hours ago" but doesn't define TTL.
+- ❓ After expiration, allow N more attempts or lock?
+
+### Cannot estimate until these resolved.
+
+### State
+
+Ticket remains: DRAFT (not transitioned)
+
+---
+HANDOFF → business-analyst
+Action needed: /analyze-requirements to refine AC, then re-invoke /groom-ticket
+```
+
+## 📤 Output Format (Suggest Split)
+
+```markdown
+## ⚠️ Ticket Too Large: TICKET-042
+
+**Proposed estimate**: 13 points (exceeds max 8)
+
+### Recommendation: Split into 3 tickets
+
+**TICKET-042a**: Password reset core flow
+- Scenarios: 1, 3 (happy path + expired)
+- Estimate: 5 points
+- Deliverable: Working reset WITHOUT rate limiting
+
+**TICKET-042b**: Rate limiting for auth endpoints
+- Scenarios: 4 (rate limit scenario)
+- Estimate: 3 points  
+- Deliverable: Middleware + applied to reset + login
+- Depends on: 042a
+
+**TICKET-042c**: Security hardening
+- Scenarios: 2 (email enumeration prevention)
+- Estimate: 3 points
+- Deliverable: Timing-safe responses, audit logging
+- Depends on: 042a
+
+**Total**: 11 points across 3 tickets (vs unmanageable 13 as one)
+
+### Rationale
+
+Splitting allows:
+- Parallel work (042a and 042b can overlap after 042a MVP)
+- Smaller PRs = easier review
+- Incremental deployment
+- Clearer testing scope
+
+### Next Step
+
+HANDOFF → business-analyst
+Action needed: Review split, approve, then:
+1. `/split-ticket TICKET-042` (creates 042a/b/c)
+2. `/groom-ticket TICKET-042a` (estimate sub-tickets)
+3. `/groom-ticket TICKET-042b`
+4. `/groom-ticket TICKET-042c`
+
+### Original Ticket
+
+State: DRAFT → BLOCKED (pending split)
+```
+
+## 🚨 Failure Modes
+
+| Scenario | Action |
+|----------|--------|
+| Ticket not found | ABORT with clear error |
+| Wrong ticket state | Suggest correct command |
+| Missing user story / AC | HANDOFF → BA, don't groom |
+| AC ambiguous | HANDOFF → BA with specific questions |
+| Ticket too big (>8 points) | Propose split, don't estimate |
+| ADR needed but not created | Block transition, suggest /create-adr |
+| No similar past tickets for anchor | Flag uncertainty, add buffer, proceed |
+| Schema validation fails after update | Retry 3x, then escalate |
+
+## 🔗 Related Commands
+
+- **Before**: `/analyze-requirements` (must be done first)
+- **After**: `/mark-ready` (DoR check) or `/create-adr` (if needed)
+- **Alternative**: `/split-ticket` (if too big)
+- **Related**: `/estimate-task` (re-estimate existing GROOMED ticket)
+
+## 📊 Metrics Tracked
+
+Log to `project/metrics/groom-ticket.jsonl`:
+
+```json
+{
+  "timestamp": "...",
+  "ticket_id": "TICKET-042",
+  "duration_seconds": 180,
+  "estimate": 5,
+  "risks_identified": 4,
+  "open_questions": 4,
+  "feasibility": "FEASIBLE",
+  "adr_needed": true,
+  "split_suggested": false,
+  "transitioned_to": "GROOMED"
+}
+```
+
+---
+**Last updated**: 2026-04-18
+**Maintainer**: Tech Lead agent

package/core/skills/planning-mark-ready/SKILL.md

@@ -0,0 +1,111 @@
+---
+name: planning-mark-ready
+description: Use when the user asks to run /mark-ready, validate a GROOMED ticket against Definition of Ready, resolve readiness gaps, or move a ticket to READY/BLOCKED.
+command: /mark-ready
+display_name: "Mark Ticket Ready"
+version: 1.0.0
+status: READY
+owner_agent: scrum-master
+requires_agents:
+  - scrum-master
+consults_agents:
+  - business-analyst
+  - tech-lead
+model_preference: sonnet
+args:
+  - name: ticket_id
+    required: true
+    format: "TICKET-XXX"
+    description: "GROOMED ticket to verify against Definition of Ready"
+preconditions:
+  - ticket_exists: "project/tickets/${ticket_id}.json"
+  - ticket_status: GROOMED
+  - has_estimate: true
+  - has_acceptance_criteria: true
+  - dependencies_resolved_or_planned: true
+postconditions:
+  - ticket_status: READY | GROOMED | BLOCKED
+  - dor_checklist_recorded: true
+  - state_history_updated: true
+---
+
+# /mark-ready
+
+> Scrum Master gate for `GROOMED` → `READY`. Enforces Definition of Ready before sprint work can start.
+
+## 🎯 Purpose
+
+Verify that a groomed ticket is truly ready for implementation. This prevents developers from starting work with unclear scope, unresolved dependencies, missing designs, or untestable acceptance criteria.
+
+## 🚦 Trigger
+
+Manual only:
+
+- `/mark-ready TICKET-042`
+- `/mark-ready TICKET-042 --sprint=SPRINT-007`
+
+## 📋 Preconditions, STRICT
+
+1. Ticket exists in `project/tickets/`.
+2. Ticket status is exactly `GROOMED`.
+3. Ticket has user story, acceptance criteria, estimate, technical approach, risks, and dependencies.
+4. Ticket estimate is one of `1, 2, 3, 5, 8`.
+5. No unresolved blocking dependency unless a dated unblock plan exists.
+6. Scrum Master agent is invoking this command.
+
+If any precondition fails, ABORT and keep the ticket in `GROOMED` or move to `BLOCKED` only if the blocker is explicit.
+
+## 🔄 Execution Flow
+
+1. Load ticket JSON and `core/rules/07-definition-of-ready.md`.
+2. Validate INVEST criteria.
+3. Validate acceptance criteria are testable and include happy path, edge case, and error case.
+4. Validate estimation evidence from grooming.
+5. Validate dependencies, design assets, data/API impacts, security/compliance needs, and test strategy.
+6. Record a `dor_checklist` object with each item as `PASS`, `FAIL`, or `N/A` plus evidence.
+7. If all mandatory items pass, update status to `READY` and append state history.
+8. If mandatory items fail, leave status as `GROOMED`, add comments, and HANDOFF to BA or Tech Lead.
+9. If external dependency blocks readiness, set status to `BLOCKED` with blocker metadata.
+10. Run `/validate-state` or `bash scripts/validate-state.sh`.
+11. Output readiness decision and next command.
+
+## 🔒 Hard Rules
+
+### RULE MR-001: No partial readiness
+A ticket either passes DoR or it does not. Do not mark `READY` with pending mandatory items.
+
+### RULE MR-002: Scrum Master owns the gate
+Developer, BA, and Tech Lead may provide evidence, but only Scrum Master marks `READY`.
+
+### RULE MR-003: Evidence required
+Each DoR checklist item MUST reference ticket fields, linked docs, comments, or explicit `N/A` rationale.
+
+### RULE MR-004: No estimate above 8
+If estimate is greater than 8, ABORT and HANDOFF to BA/Tech Lead to split.
+
+### RULE MR-005: Blockers must be explicit
+If readiness fails because of dependency, record `blocked_reason`, `blocked_by`, `blocked_at`, `expected_unblock`, and `escalation`.
+
+### RULE MR-006: State history mandatory
+Every successful transition MUST append state history with `from_state`, `to_state`, `at`, `by_agent`, `by_command`, and `reason`.
+
+## 📤 Outputs
+
+Success:
+
+- Ticket marked `READY`
+- DoR checklist recorded
+- State history appended
+- Suggested next command: `/plan-sprint` or `/implement-task TICKET-XXX`
+
+Failure:
+
+- Ticket remains `GROOMED` or moves to `BLOCKED`
+- Failed DoR items listed
+- Specific handoff to BA, Tech Lead, or stakeholder
+
+## 🔗 Related Commands
+
+- Before: `/groom-ticket`
+- After: `/plan-sprint`, `/implement-task`
+- Utility: `/validate-state`

package/core/skills/planning-plan-refactor/SKILL.md

@@ -0,0 +1,66 @@
+---
+name: planning-plan-refactor
+description: Use when the user asks to run /plan-refactor, plan a refactor for a module or architecture area, assess refactor scope, or propose a ticket breakdown for cleanup work.
+command: /plan-refactor
+display_name: "Plan Refactor"
+version: 1.0.0
+status: READY
+owner_agent: tech-lead
+consults_agents:
+  - developer
+  - qa-tester
+  - scrum-master
+model_preference: opus
+args:
+  - name: scope
+    required: true
+    description: "Module, area, or refactor goal"
+preconditions:
+  - codebase_context_available: true
+postconditions:
+  - refactor_plan_created: true
+  - ticket_breakdown_proposed: true
+---
+
+# /plan-refactor
+
+> Creates a project-specific refactor plan in `docs/runtime/refactor/` and breaks it into executable tickets.
+
+## 🎯 Purpose
+
+Plan large refactors without putting project-specific design into `core/`.
+
+## 🔄 Execution Flow
+
+1. Load `config/project-structure.yaml`.
+2. Inspect affected code areas and docs.
+3. Identify current problem, target state, constraints, and risks.
+4. Determine whether ADR is required.
+5. Create `docs/runtime/refactor/<slug>-refactor-plan.md` from `core/templates/technical/refactor-plan-template.md`.
+6. Propose ticket breakdown for `project/tickets/`.
+7. Propose backlog entries for `project/backlog/backlog.json`.
+8. Define testing, rollout, and rollback plan.
+9. HANDOFF to BA for ticket creation or Tech Lead for ADR.
+
+## 🔒 Hard Rules
+
+- MUST NOT modify production code during planning.
+- MUST keep plan in `docs/runtime/refactor/`, not `core/`.
+- MUST create characterization test ticket before risky behavior-preserving refactors.
+- MUST require ADR for architectural decisions.
+- MUST split work into tickets of 8 points or less.
+
+## 📤 Outputs
+
+- Refactor plan path
+- ADR requirement
+- Ticket breakdown
+- Risk matrix
+- Verification strategy
+
+## 🔗 Related Commands
+
+- `/discover-codebase`
+- `/create-adr`
+- `/analyze-requirements`
+- `/groom-ticket`