ai-core-framework 0.1.0

package/core/skills/release-rollback/SKILL.md

@@ -0,0 +1,62 @@
+---
+name: release-rollback
+description: Use when the user asks to run /rollback, plan or execute a release rollback, validate rollback prerequisites, record rollback evidence, or verify rollback completion.
+command: /rollback
+display_name: "Rollback Release"
+version: 1.0.0
+status: READY
+owner_agent: scrum-master
+consults_agents:
+  - tech-lead
+  - qa-tester
+model_preference: opus
+args:
+  - name: version
+    required: true
+    format: "vMAJOR.MINOR.PATCH"
+preconditions:
+  - release_exists: true
+  - rollback_plan_exists: true
+postconditions:
+  - rollback_record_created: true
+  - verification_completed: true
+---
+
+# /rollback
+
+> Coordinates reverting a release when production health is unacceptable.
+
+## 🎯 Purpose
+
+Restore service safely, preserve audit trail, and start follow-up remediation.
+
+## 🔄 Execution Flow
+
+1. Confirm rollback trigger and incident severity.
+2. Load release record and rollback plan.
+3. Get Tech Lead confirmation for technical risk.
+4. Notify stakeholders and freeze related deploys.
+5. Execute documented rollback steps.
+6. Verify service health and core flows.
+7. Record rollback result in `project/releases/`.
+8. Create follow-up bug/ticket and incident notes.
+
+## 🔒 Hard Rules
+
+- MUST NOT rollback without known target version or backup plan.
+- MUST verify after rollback.
+- MUST document data migration impact.
+- MUST create follow-up RCA work.
+
+## 📤 Outputs
+
+- Rolled back version
+- Current production version
+- Verification result
+- Incident/follow-up links
+
+## 🔗 Related Commands
+
+- `/release`
+- `/hotfix`
+- `/report-bug`

package/core/skills/review-create-pr/SKILL.md

@@ -0,0 +1,418 @@
+---
+name: review-create-pr
+description: Use when the user asks to run /create-pr, prepare or open a pull request, perform pre-PR checks, link a ticket to a PR, or move a ticket into review.
+command: /create-pr
+display_name: "Create Pull Request"
+version: 1.0.0
+owner_agent: developer
+model_preference: sonnet
+args:
+  - name: draft
+    required: false
+    type: boolean
+    default: false
+    description: "Create as draft PR (not ready for review)"
+  - name: skip-self-review
+    required: false
+    type: boolean
+    default: false
+    description: "Skip self-review step (not recommended)"
+preconditions:
+  - on_feature_branch: true
+  - ticket_exists_for_branch: true
+  - ticket_status: IN_PROGRESS
+  - all_tests_passing: true
+  - diff_coverage_met: "≥80%"
+  - lint_passing: true
+  - no_uncommitted_changes: true
+  - branch_pushed: true
+postconditions:
+  - pr_created: true
+  - ticket_status: IN_REVIEW
+  - pr_linked_to_ticket: true
+  - reviewer_assigned: "tech-lead"
+---
+
+# /create-pr
+
+> Create a Pull Request with quality gates, template filled, reviewer assigned.
+> **Gate**: IN_PROGRESS → IN_REVIEW transition.
+
+## 🎯 Purpose
+
+Developer has finished implementing the ticket and must create a PR. This command:
+1. Run all quality gates (tests, coverage, lint)
+2. Do self-review
+3. Generate PR title + description from template
+4. Push branch if not already pushed
+5. Create PR via GitHub CLI or web
+6. Assign reviewer (Tech Lead)
+7. Update ticket state → IN_REVIEW
+
+## 🚦 Trigger
+
+**Manual** (primary):
+```
+/create-pr
+```
+
+**With options**:
+```
+/create-pr --draft                # Draft PR (WIP)
+/create-pr --skip-self-review     # Skip self-review (only with justification)
+```
+
+**Auto**: No. Developer MUST explicitly invoke it after self-review.
+
+## 📋 Preconditions (STRICT)
+
+### 1. On feature branch
+```bash
+current_branch=$(git rev-parse --abbrev-ref HEAD)
+# Must match: ^(feature|bugfix|hotfix|chore|refactor)/TICKET-\d+-[a-z0-9-]+$
+if ! echo "$current_branch" | grep -qE '^(feature|bugfix|hotfix|chore|refactor)/TICKET-[0-9]+-[a-z0-9-]+$'; then
+  ABORT "Not on valid feature branch. Current: $current_branch"
+fi
+```
+
+### 2. Ticket exists for branch
+Extract TICKET-XXX from branch name, verify:
+```bash
+TICKET_ID=$(echo "$current_branch" | grep -oE 'TICKET-[0-9]+')
+test -f "project/tickets/${TICKET_ID}.json" || ABORT
+```
+
+### 3. Ticket in IN_PROGRESS
+Read ticket.status. Must be `IN_PROGRESS`. Else:
+- DRAFT/GROOMED/READY → ABORT, use `/implement-task` first
+- IN_REVIEW → ABORT, PR likely already exists
+- DONE → ABORT
+
+### 4. No uncommitted changes
+```bash
+git status --porcelain | grep -q . && ABORT "Uncommitted changes. Commit or stash first."
+```
+
+### 5. All tests passing
+```bash
+# Run full test suite
+pnpm test || ABORT "Tests failing. Fix before PR."
+```
+
+### 6. Diff coverage ≥ 80%
+```bash
+# Check coverage on diff vs develop
+pnpm run coverage:diff --threshold=80 || ABORT "Diff coverage < 80%"
+```
+
+### 7. Linter passing
+```bash
+pnpm run lint || ABORT "Lint errors. Fix before PR."
+```
+
+### 8. Branch pushed to remote
+```bash
+git fetch origin
+if ! git branch -r --contains HEAD | grep -q "origin/$current_branch"; then
+  # Push if not
+  git push -u origin "$current_branch" || ABORT "Failed to push"
+fi
+```
+
+### 9. Branch up-to-date with develop
+```bash
+git fetch origin develop
+behind=$(git rev-list --count HEAD..origin/develop)
+if [ "$behind" -gt 0 ]; then
+  WARN "Branch $behind commits behind develop. Consider rebasing."
+  # Not fatal, but notify
+fi
+```
+
+## 🔄 Execution Flow
+
+```
+┌──────────────────────────────────────────────────────────┐
+│ STEP 1: Validate preconditions (above)                   │
+│   Any fail → ABORT with specific error                   │
+├──────────────────────────────────────────────────────────┤
+│ STEP 2: Load context                                     │
+│   - Ticket JSON                                          │
+│   - AC scenarios                                         │
+│   - Grooming notes (technical approach)                  │
+│   - Commit history since branch creation                 │
+│   - Diff stats (files changed, +/- lines)                │
+├──────────────────────────────────────────────────────────┤
+│ STEP 3: Self-review (unless --skip-self-review)          │
+│                                                          │
+│   3.1 Read own diff top-to-bottom                        │
+│   3.2 Checklist:                                         │
+│     - [ ] Every AC scenario has test                     │
+│     - [ ] No TODO/FIXME without ticket                   │
+│     - [ ] No console.log / print debug                   │
+│     - [ ] No commented-out code                          │
+│     - [ ] No hardcoded secrets                           │
+│     - [ ] No unrelated changes (scope creep)             │
+│     - [ ] Commits follow conventional format             │
+│     - [ ] Docs updated if API changed                    │
+│                                                          │
+│   3.3 If issues found: FIX, commit, re-run               │
+├──────────────────────────────────────────────────────────┤
+│ STEP 4: Generate PR title                                │
+│   Format: "<type>(TICKET-XXX): <short description>"      │
+│   Max: 72 chars                                          │
+│   Examples:                                              │
+│     feat(TICKET-042): add password reset via email       │
+│     fix(TICKET-089): handle + character in email login   │
+├──────────────────────────────────────────────────────────┤
+│ STEP 5: Generate PR description                          │
+│   Use template: templates/pr/pull-request-template.md    │
+│   Auto-fill sections:                                    │
+│     - Summary (from ticket)                              │
+│     - Changes (from diff)                                │
+│     - How to test (from AC)                              │
+│     - Checklist (self-review)                            │
+│     - Screenshots (prompt if UI changes detected)        │
+├──────────────────────────────────────────────────────────┤
+│ STEP 6: Determine reviewers                              │
+│   - Primary: tech-lead (mandatory)                       │
+│   - Secondary: suggest from codeowners (if file)         │
+│   - Label: "needs-review"                                │
+├──────────────────────────────────────────────────────────┤
+│ STEP 7: Create PR via GitHub CLI                         │
+│   gh pr create \                                         │
+│     --base develop \                                     │
+│     --head <current_branch> \                            │
+│     --title "<title>" \                                  │
+│     --body-file <generated-body.md> \                    │
+│     --reviewer <tech-lead> \                             │
+│     --label "TICKET-XXX" \                               │
+│     [--draft if --draft flag]                            │
+│                                                          │
+│   Capture PR URL from output.                            │
+├──────────────────────────────────────────────────────────┤
+│ STEP 8: Update ticket                                    │
+│   - state: IN_PROGRESS → IN_REVIEW                       │
+│   - pr_url: <captured URL>                               │
+│   - state_history append                                 │
+│   - updated_at timestamp                                 │
+├──────────────────────────────────────────────────────────┤
+│ STEP 9: Notify                                           │
+│   - Output PR URL                                        │
+│   - Suggest reviewer action: /techlead-review PR-XXX     │
+│   - (Optional) Slack notification via webhook            │
+├──────────────────────────────────────────────────────────┤
+│ STEP 10: Log metrics                                     │
+│   project/metrics/create-pr.jsonl                 │
+└──────────────────────────────────────────────────────────┘
+```
+
+## 🔒 Hard Rules
+
+### RULE PR-001: All preconditions must pass
+**MUST NOT** bypass preconditions with flags like `--skip-tests`. Exception: `--draft` allowed with failing tests (WIP), but NOT allowed for ready PRs.
+
+### RULE PR-002: Ticket MUST be IN_PROGRESS
+PR creation transitions ticket to IN_REVIEW. If ticket not IN_PROGRESS, something wrong with workflow.
+
+### RULE PR-003: Self-review mandatory by default
+`--skip-self-review` requires justification in PR body:
+```
+> ⚠️ Self-review skipped: [reason]
+```
+Tech Lead can reject PR if justification weak.
+
+### RULE PR-004: Branch must match ticket
+Regex check: branch name contains `TICKET-XXX` matching ticket file. No mismatch allowed.
+
+### RULE PR-005: PR against develop (not main)
+Base branch **MUST** be `develop`. Exception: hotfix branches target `main`.
+
+### RULE PR-006: One PR per ticket
+If PR already exists for this ticket → ABORT. Don't create duplicate.
+
+Check:
+```bash
+existing_pr=$(gh pr list --head "$current_branch" --json number --jq '.[0].number')
+[ -n "$existing_pr" ] && ABORT "PR #$existing_pr already exists"
+```
+
+### RULE PR-007: Reviewer auto-assigned
+**MUST** assign tech-lead as reviewer. No PR without reviewer (dead PR).
+
+If tech-lead = PR author (self), escalate:
+- Suggest another tech-lead in team
+- Or escalate human
+
+### RULE PR-008: Labels required
+**MUST** apply labels:
+- `TICKET-XXX` (for tracking)
+- `needs-review` (initial state)
+- Type label: `feature`, `bugfix`, `hotfix`, `refactor`, `chore`
+- Size label: `size/S` (< 100 lines), `size/M` (100-500), `size/L` (500+)
+
+### RULE PR-009: Description from template
+**MUST** use PR template. No freestyle descriptions.
+
+### RULE PR-010: Link ticket bidirectionally
+- PR description references ticket ID
+- Ticket JSON has `pr_url` field
+- Commit body has `Closes: TICKET-XXX`
+
+## 📥 Input Examples
+
+```
+/create-pr                             # Standard PR, ready for review
+/create-pr --draft                     # WIP PR (CI runs, but not ready for review)
+/create-pr --skip-self-review          # Risky, requires justification
+```
+
+## 📤 Output Format (Success)
+
+```markdown
+## ✅ PR Created: #123
+
+**Title**: feat(TICKET-042): add password reset via email
+**URL**: https://github.com/org/repo/pull/123
+**Branch**: feature/TICKET-042-password-reset → develop
+**Reviewer**: @tech-lead
+
+### Quality Gates
+| Check | Status |
+|-------|--------|
+| Tests | ✅ 47 passed, 0 failed |
+| Coverage (diff) | ✅ 87% (target: 80%) |
+| Coverage (overall) | ✅ 73% (+1.2%) |
+| Lint | ✅ 0 errors, 2 warnings |
+| Type check | ✅ Pass |
+| Security scan | ✅ No high-severity issues |
+
+### Self-Review Checklist
+- [x] Every AC scenario has test (4/4 scenarios)
+- [x] No TODO/FIXME without ticket
+- [x] No debug statements
+- [x] No commented-out code
+- [x] No hardcoded secrets
+- [x] Scope matches ticket (no creep)
+- [x] Commits conventional format
+- [x] API docs updated
+
+### PR Stats
+- **Files changed**: 12 (+8, ~4)
+- **Lines**: +234, -45
+- **Commits**: 7 (atomic, TDD pattern)
+
+### Commits (verified TDD flow)
+1. `test(TICKET-042): add failing tests for happy path`
+2. `feat(TICKET-042): implement password reset endpoint`
+3. `test(TICKET-042): add edge case tests for invalid email`
+4. `feat(TICKET-042): handle invalid email cases`
+5. `test(TICKET-042): add rate limiting tests`
+6. `feat(TICKET-042): add rate limiting middleware`
+7. `docs(TICKET-042): update API docs`
+
+### Ticket Updated
+- **State**: IN_PROGRESS → IN_REVIEW ✅
+- **PR URL**: saved to ticket
+
+### Next Steps
+1. **Tech Lead**: `/techlead-review PR-123`
+2. **Developer**: Respond to review comments promptly
+3. **After approval**: `/merge-pr PR-123`
+
+---
+HANDOFF → tech-lead
+PR ready for review.
+```
+
+## 📤 Output Format (Failure)
+
+```markdown
+## ❌ Cannot create PR
+
+**Reason**: Diff coverage below threshold
+
+### Details
+- Current diff coverage: **62%**
+- Required: **80%**
+- Uncovered lines: 45
+
+### Uncovered files:
+- `src/auth/reset-password.ts:23-45` (error handling branch)
+- `src/auth/reset-password.ts:78-82` (email validation)
+- `src/email/send.ts:12-18` (retry logic)
+
+### Action Required
+Add tests covering the uncovered branches. Then retry:
+```
+/write-unit-tests  # for guidance
+# Manually add tests for the above files
+pnpm test --coverage  # verify
+/create-pr  # retry
+```
+
+### Ticket State
+Unchanged: IN_PROGRESS (no transition).
+```
+
+## 📤 Output Format (Duplicate PR)
+
+```markdown
+## ⚠️ PR Already Exists
+
+An open PR exists for this branch:
+- **PR #123**: https://github.com/org/repo/pull/123
+- **Status**: Open, awaiting review
+
+### Options
+1. Update existing PR: `git push` (current commits will update it)
+2. Close old PR and create new: `gh pr close 123 && /create-pr`
+3. Check PR state: `gh pr view 123`
+
+### No action taken.
+```
+
+## 🚨 Failure Modes
+
+| Precondition | Error | Recovery |
+|--------------|-------|----------|
+| Wrong branch | Not on feature/TICKET-* | Checkout correct branch |
+| No ticket | TICKET not found | `/analyze-requirements` first |
+| Wrong status | Ticket not IN_PROGRESS | Check /implement-task workflow |
+| Tests failing | Test count failed | Fix tests, commit, retry |
+| Low coverage | Diff coverage < 80% | Add tests |
+| Lint errors | Lint failed | Fix lint, commit, retry |
+| Uncommitted | Dirty working dir | Commit or stash |
+| Not pushed | Branch not on remote | Auto-push |
+| Behind develop | Branch stale | WARN, offer rebase |
+| Existing PR | Duplicate | Use existing or close |
+
+## 🔗 Related Commands
+
+- **Before**: `/implement-task` (must complete implementation)
+- **After**: `/techlead-review` (reviewer's next step)
+- **If blocked**: `/check-coverage`, `/run-tests`, `/write-unit-tests`
+- **Emergency close**: `gh pr close <num>` (manual)
+
+## 📊 Metrics Tracked
+
+```json
+{
+  "timestamp": "2026-04-18T14:30:00Z",
+  "ticket_id": "TICKET-042",
+  "pr_number": 123,
+  "files_changed": 12,
+  "lines_added": 234,
+  "lines_removed": 45,
+  "commits_count": 7,
+  "coverage_diff": 87.0,
+  "lint_warnings": 2,
+  "tdd_compliant": true,
+  "self_review_skipped": false,
+  "duration_seconds": 38
+}
+```
+
+---
+**Last updated**: 2026-04-18
+**Maintainer**: Developer agent