ai-core-framework 0.1.0

package/core/skills/review-techlead-review/SKILL.md

@@ -0,0 +1,547 @@
+---
+name: review-techlead-review
+description: Use when the user asks to run /techlead-review, review a pull request as tech lead, assess architecture/security/test risk, or post an approve/comment/changes-requested decision.
+command: /techlead-review
+display_name: "Tech Lead Review"
+version: 1.0.0
+owner_agent: tech-lead
+model_preference: opus  # Deep analysis needed
+args:
+  - name: pr_number
+    required: true
+    type: integer
+    description: "PR number to review"
+  - name: depth
+    required: false
+    type: string
+    default: "full"
+    enum: [quick, full, security-focused]
+    description: "Review depth"
+preconditions:
+  - pr_exists: true
+  - pr_open: true
+  - pr_not_own: true  # Tech lead can't review own PR
+  - ci_status: green  # Block if CI red
+  - ticket_status: IN_REVIEW
+postconditions:
+  - review_posted: true
+  - review_decision: APPROVED | CHANGES_REQUESTED | COMMENTED
+  - owasp_checklist_completed: true
+---
+
+# /techlead-review
+
+> Thorough code review by Tech Lead: architecture, security, performance, testing, maintainability.
+> **Gate**: Required approval before `/merge-pr`.
+
+## 🎯 Purpose
+
+Ensure code quality meets project standards BEFORE merge. Catch:
+- Architecture violations
+- Security issues (OWASP)
+- Performance regressions
+- Test gaps
+- Maintainability concerns
+
+And **teach** developers through review feedback.
+
+## 🚦 Trigger
+
+**Manual**:
+```
+/techlead-review 123                    # PR #123, full review
+/techlead-review 123 --depth=quick      # Quick skim for minor changes
+/techlead-review 123 --depth=security-focused   # For auth/data/payment PRs
+```
+
+**Auto-assignment**: When `/create-pr` runs, tech-lead gets notification. They then invoke this command.
+
+## 📋 Preconditions (STRICT)
+
+### 1. PR exists and open
+```bash
+gh pr view "$PR_NUMBER" --json state,author | jq -e '.state == "OPEN"' || ABORT
+```
+
+### 2. PR author != reviewer (no self-review)
+```bash
+pr_author=$(gh pr view "$PR_NUMBER" --json author --jq .author.login)
+current_user=$(gh api user --jq .login)
+[ "$pr_author" != "$current_user" ] || ABORT "Cannot review own PR (RULE TL-005)"
+```
+
+### 3. CI status green
+```bash
+ci_status=$(gh pr checks "$PR_NUMBER" --json status --jq '.[].status')
+[ "$ci_status" = "SUCCESS" ] || ABORT "CI not green. Wait or notify author."
+```
+
+### 4. Ticket in IN_REVIEW
+Read ticket (from branch name), verify status = IN_REVIEW.
+
+### 5. PR description filled
+Check PR has description using template (not empty / not default).
+
+## 🔄 Execution Flow
+
+```
+┌──────────────────────────────────────────────────────────┐
+│ STEP 1: Load context                                     │
+│   - PR metadata (title, description, author, branch)    │
+│   - Ticket JSON + AC + grooming notes                    │
+│   - ADRs referenced                                      │
+│   - Related code (imports, callers)                      │
+│   - Commit history                                       │
+├──────────────────────────────────────────────────────────┤
+│ STEP 2: Read PR description                              │
+│   - Does it follow template?                             │
+│   - Self-review checklist filled?                        │
+│   - Testing notes present?                               │
+│   - Screenshots (if UI change)?                          │
+├──────────────────────────────────────────────────────────┤
+│ STEP 3: AC Coverage Check                                │
+│   For each AC scenario in ticket:                        │
+│   - Find corresponding test                              │
+│   - Verify test actually validates scenario              │
+│   Score: N/N scenarios covered                           │
+├──────────────────────────────────────────────────────────┤
+│ STEP 4: Architecture Review                              │
+│   - Layer separation (UI/logic/data)                     │
+│   - Consistent with existing patterns                     │
+│   - ADRs followed                                        │
+│   - No premature abstraction                             │
+│   - No god classes/functions                             │
+├──────────────────────────────────────────────────────────┤
+│ STEP 5: Security Review (OWASP Top 10)                   │
+│   Go through each relevant item:                         │
+│   A01 - Access Control                                   │
+│   A02 - Cryptographic Failures                           │
+│   A03 - Injection                                        │
+│   A04 - Insecure Design                                  │
+│   A05 - Security Misconfiguration                        │
+│   A06 - Vulnerable Components                            │
+│   A07 - Identification & Auth Failures                   │
+│   A08 - Software & Data Integrity                        │
+│   A09 - Security Logging Failures                        │
+│   A10 - SSRF                                             │
+│                                                          │
+│   Mark each: ✓ Pass | ⚠ Concern | ✗ Block | N/A         │
+├──────────────────────────────────────────────────────────┤
+│ STEP 6: Performance Review                               │
+│   - Hot paths: O(N²) or worse?                           │
+│   - N+1 queries?                                         │
+│   - Unnecessary synchronous blocks?                      │
+│   - Memory leaks (subscriptions, listeners)?             │
+│   - Caching opportunities?                               │
+│   - Database indexes needed?                             │
+├──────────────────────────────────────────────────────────┤
+│ STEP 7: Testing Review                                   │
+│   - Coverage: meets 80% diff threshold?                  │
+│   - Test quality (see rules/05-testing-mandatory):       │
+│     - Descriptive names                                  │
+│     - AAA structure                                      │
+│     - Minimal mocking                                    │
+│     - Edge cases covered                                 │
+│   - Integration tests for integration points?            │
+│   - E2E for critical flows?                              │
+├──────────────────────────────────────────────────────────┤
+│ STEP 8: Maintainability Review                           │
+│   - Names clear (not `x`, `tmp`, `data`)                 │
+│   - Functions < 50 lines?                                │
+│   - Files < 500 lines?                                   │
+│   - Cyclomatic complexity < 10?                          │
+│   - DRY (no copy-paste)                                  │
+│   - Comments explain WHY (not WHAT)                      │
+│   - No magic numbers                                     │
+├──────────────────────────────────────────────────────────┤
+│ STEP 9: Documentation Review                             │
+│   - API docs updated (if endpoint changed)?              │
+│   - README updated (if setup changed)?                   │
+│   - CHANGELOG entry added?                               │
+│   - ADR created (if architecture decision)?              │
+│   - Inline docs for complex logic?                       │
+├──────────────────────────────────────────────────────────┤
+│ STEP 10: Commit Hygiene                                  │
+│   - Conventional commits format?                         │
+│   - Atomic commits?                                      │
+│   - TDD flow visible (test commits before feat)?         │
+│   - No WIP/debug commits?                                │
+│   - No secrets in history?                               │
+├──────────────────────────────────────────────────────────┤
+│ STEP 11: Compile Review                                  │
+│   - Aggregate findings                                   │
+│   - Categorize: MUST_FIX | SHOULD_FIX | NIT | PRAISE    │
+│   - Decide: APPROVED | REQUEST_CHANGES                   │
+├──────────────────────────────────────────────────────────┤
+│ STEP 12: Post Review                                     │
+│   - Inline comments on specific lines                    │
+│   - Summary comment                                      │
+│   - Approve or request changes                           │
+│   - Update ticket (add review comment)                   │
+└──────────────────────────────────────────────────────────┘
+```
+
+## 🔒 Hard Rules
+
+### RULE TR-001: OWASP checklist mandatory
+**MUST** go through ALL 10 OWASP items, even if N/A. Document "N/A" with reason.
+
+### RULE TR-002: MUST_FIX categorization strict
+Only MUST_FIX items block merge. Categorize accurately:
+- **MUST_FIX**: Security issue, bug, broken functionality, policy violation
+- **SHOULD_FIX**: Design/architecture concerns, performance issues (non-critical), testing gaps
+- **NIT**: Style preferences, minor naming, micro-optimizations
+- **PRAISE**: Positive feedback (do this!)
+
+**DO NOT** inflate issues to MUST_FIX to force rework. Be fair.
+
+### RULE TR-003: Constructive comments
+Every MUST_FIX / SHOULD_FIX **MUST** include:
+- **Problem**: What's wrong
+- **Why**: Why it matters (impact)
+- **Suggestion**: Specific fix (not just "fix this")
+
+### RULE TR-004: Teach, don't dictate
+When rejecting approach:
+- Explain tradeoffs, not just preferences
+- Reference principles (SOLID, DRY, etc.) or ADRs
+- Acknowledge valid perspectives
+- Invite discussion if uncertain
+
+### RULE TR-005: No approval without OWASP
+Even "simple" PRs require OWASP skim. Document quickly if all N/A.
+
+### RULE TR-006: Performance concerns need evidence
+If flagging performance issue, **SHOULD** provide:
+- Estimated complexity (Big O)
+- Example scenario where it matters
+- Benchmark if available
+
+Don't flag "feels slow" without basis.
+
+### RULE TR-007: Test adequacy check
+If diff coverage ≥ 80% but tests are bad quality (tautological, over-mocked), flag it. Coverage number is not sufficient.
+
+### RULE TR-008: Approve only if deployable
+Only approve if would happily deploy to production immediately. "Good enough" is NOT good enough.
+
+### RULE TR-009: Respect developer time
+- Don't re-review full PR on minor fix (spot-check only)
+- Don't change mind arbitrarily (if approved once, don't unapprove for NITs)
+- Respond to re-review requests within 4 hours SLA
+
+### RULE TR-010: Praise publicly, correct kindly
+- Use PRAISE category generously (positive reinforcement)
+- Frame corrections as learning opportunities
+- Assume positive intent from developer
+
+## 📥 Input Examples
+
+```
+/techlead-review 123                           # Full review of PR #123
+/techlead-review 123 --depth=quick             # Minor typo fix etc.
+/techlead-review 123 --depth=security-focused  # Auth/payment PRs
+```
+
+## 📤 Output Format (Approved)
+
+```markdown
+## 🔍 Code Review: PR #123 (TICKET-042)
+
+**Overall Decision**: ✅ **APPROVED**
+
+**PR**: feat(TICKET-042): add password reset via email
+**Author**: @alice
+**Files**: 12 | **+234 / -45**
+**Review depth**: Full
+**Review duration**: 45 min
+
+### Summary
+Solid implementation of password reset flow. TDD followed properly, security considerations addressed, rate limiting well-designed. A few minor NITs but nothing blocking.
+
+### AC Coverage: ✅ 4/4
+- ✅ Scenario 1 (happy path) → `reset-password.test.ts:23`
+- ✅ Scenario 2 (email not exist) → `reset-password.test.ts:67`
+- ✅ Scenario 3 (link expired) → `reset-password.test.ts:104`
+- ✅ Scenario 4 (rate limit) → `rate-limit.test.ts:15`
+
+### Architecture: ✅
+- Follows existing controller/service/repository pattern
+- Middleware pattern consistent with auth middleware
+- Rate limiter properly extracted as reusable utility
+- No layer violations
+
+### Security: ✅ (OWASP Top 10)
+- [x] **A01 Access Control**: Reset token scoped to user ID
+- [x] **A02 Crypto**: crypto.randomBytes(32), bcrypt hashing
+- [x] **A03 Injection**: Parameterized queries throughout
+- [x] **A04 Insecure Design**: Timing-safe comparison, no email enumeration
+- [x] **A05 Misconfig**: N/A (no config changes)
+- [x] **A06 Vulnerable Components**: New deps reviewed (bcrypt@5.1, express-rate-limit@7.0)
+- [x] **A07 Auth Failures**: Token single-use, short TTL (24h)
+- [x] **A08 Integrity**: Password updated atomically
+- [x] **A09 Logging**: Auth events logged to audit log
+- [x] **A10 SSRF**: N/A (no URL fetching)
+
+### Performance: ✅
+- Bcrypt work factor: 10 (acceptable balance)
+- DB query: single indexed lookup (token_hash)
+- Email send: async via queue (doesn't block request)
+- No N+1 concerns
+
+### Testing: ✅
+- Coverage: 87% diff (target 80%) ✅
+- Unit: 15 new tests (well-named, AAA structure)
+- Integration: 4 tests (real DB, real request/response)
+- Edge cases: covered (case sensitivity, boundary times)
+- No flaky tests detected
+
+### Maintainability: ✅
+- Function sizes reasonable (< 30 lines)
+- Clear naming (`generateResetToken`, not `genTkn`)
+- Constants extracted (`TOKEN_TTL_MS`, `RATE_LIMIT_MAX`)
+- Comments explain non-obvious decisions
+
+### Documentation: ✅
+- API docs: updated `docs/project/api/auth.md`
+- CHANGELOG: entry added
+- ADR-0012 created for rate limiting strategy
+
+### Commits: ✅
+TDD flow evident:
+- test commits before feat commits ✓
+- atomic, descriptive commits ✓
+- conventional format ✓
+
+### Inline Comments
+
+#### [PRAISE] `src/auth/reset-password.ts:45`
+Nice use of `timingSafeEqual` to prevent timing attacks on token comparison. Exactly what I'd want.
+
+#### [PRAISE] `tests/auth/reset-password.test.ts:89`
+Great test for case-sensitivity edge case. Would have missed that in dev.
+
+#### [NIT] `src/auth/reset-password.ts:78`
+Consider extracting magic number 3600000 to `ONE_HOUR_MS` constant. Already have `TOKEN_TTL_MS`, consistent style.
+
+(Non-blocking, address if easy)
+
+### Decision
+
+✅ **APPROVED** - Ready to merge after optional NIT (if fixing).
+
+### Next Steps
+1. **Developer**: Address NIT if easy (< 5 min)
+2. **Developer**: `/merge-pr 123`
+
+### Ticket Update
+Adding review comment to TICKET-042:
+- "Approved by tech-lead-agent on 2026-04-18"
+- No status change (still IN_REVIEW, awaiting merge)
+
+---
+HANDOFF → developer
+```
+
+## 📤 Output Format (Request Changes)
+
+```markdown
+## 🔍 Code Review: PR #123 (TICKET-042)
+
+**Overall Decision**: ⚠️ **CHANGES REQUESTED**
+
+**Blockers**: 2 MUST_FIX (1 security, 1 testing)
+**Nice to have**: 3 SHOULD_FIX + 2 NITs
+
+### Summary
+Good direction overall. Core implementation works but has a critical security issue in rate limiting and a test gap that makes me uncertain about edge case behavior. Fix the 2 blockers, then I'll re-approve.
+
+### AC Coverage: ⚠️ 3/4
+- ✅ Scenario 1 → covered
+- ✅ Scenario 2 → covered
+- ✅ Scenario 3 → covered
+- ❌ Scenario 4 (rate limit) → **test exists but doesn't actually validate rate limit trigger**
+
+### Security: ⚠️ 1 Blocker
+
+#### [MUST_FIX] [Security] `src/auth/rate-limit.ts:23`
+
+**Problem**: Rate limit counter keyed by raw email, allowing bypass via case variation.
+
+```typescript
+// Current:
+const key = `reset:${email}`;  // "User@x.com" and "user@x.com" are different keys
+```
+
+**Why it matters**: Attacker can bypass rate limit by:
+- `user@example.com`
+- `User@example.com`
+- `USER@example.com`
+- etc.
+Each would have its own 5-request budget. Effectively unlimited.
+
+**Suggestion**: Normalize email before key:
+```typescript
+const key = `reset:${email.toLowerCase().trim()}`;
+```
+
+Add test:
+```typescript
+it('should rate limit across case variations', async () => {
+  await request('user@x.com');  // 1
+  await request('User@x.com');  // 2
+  await request('USER@x.com');  // 3
+  await request('uSeR@x.com');  // 4
+  await request('user@x.com');  // 5
+  const response = await request('User@x.com');  // 6 - should be limited
+  expect(response.status).toBe(429);
+});
+```
+
+### Testing: ⚠️ 1 Blocker
+
+#### [MUST_FIX] [Testing] `tests/auth/rate-limit.test.ts:15`
+
+**Problem**: Test for Scenario 4 sets rate limit to 1 req/hour but only calls once. Never actually triggers the limit.
+
+```typescript
+// Current test:
+it('should rate limit', async () => {
+  const response = await request.post('/auth/reset');
+  expect(response.status).toBe(200);  // ❌ This is happy path, not rate limit
+});
+```
+
+**Why it matters**: Scenario 4 (rate limit) has 0 actual coverage. Could silently regress.
+
+**Suggestion**: Make request N+1 times, verify 429 on last:
+```typescript
+it('should return 429 after limit exceeded', async () => {
+  for (let i = 0; i < 5; i++) {
+    const r = await request.post('/auth/reset').send({ email: 'x@y.com' });
+    expect(r.status).toBe(200);
+  }
+  const overLimit = await request.post('/auth/reset').send({ email: 'x@y.com' });
+  expect(overLimit.status).toBe(429);
+  expect(overLimit.body.error).toBe('RATE_LIMIT_EXCEEDED');
+});
+```
+
+### Performance: ⚠️
+
+#### [SHOULD_FIX] [Performance] `src/email/send.ts:23`
+
+**Problem**: Awaiting SendGrid call synchronously in request handler.
+
+**Why it matters**: User request blocked 300-800ms waiting for external service. Bad UX.
+
+**Suggestion**: Queue the job, return 202 immediately:
+```typescript
+// Instead of:
+await sendGrid.send(email);
+return 200;
+
+// Use:
+await jobQueue.enqueue('send-reset-email', { email, token });
+return 202;  // Accepted, processing async
+```
+
+(Requires job queue infra - check ADR-0008)
+
+### Maintainability
+
+#### [SHOULD_FIX] [Maintainability] `src/auth/reset-password.ts:78`
+
+Function `validateAndResetPassword` is 67 lines, does 4 things. Consider extracting:
+- `validateResetToken(token)`
+- `updateUserPassword(userId, newPassword)`
+- `invalidateToken(token)`
+- `sendConfirmationEmail(user)`
+
+Not blocking but will pay off as feature grows.
+
+#### [SHOULD_FIX] [Maintainability] `src/auth/reset-password.ts:45`
+
+Magic number `86400000` - extract:
+```typescript
+const TOKEN_TTL_MS = 24 * 60 * 60 * 1000;
+```
+
+#### [NIT] [Style] `src/auth/reset-password.ts:92`
+Unused variable `requestId`. Remove or prefix `_requestId`.
+
+#### [NIT] [Docs] `src/auth/reset-password.ts:15`
+JSDoc missing `@throws` for `InvalidTokenError` case.
+
+### Praise
+
+#### [PRAISE] `tests/email/send.test.ts:34`
+Excellent test for email template rendering. Nice touch.
+
+### Decision
+
+⚠️ **REQUEST CHANGES**
+
+**Blockers (MUST_FIX)**:
+1. Rate limit bypass via email case
+2. Rate limit test doesn't actually test rate limit
+
+**After fixing blockers**: I'll re-review (mostly spot-check).
+
+### Next Steps
+
+1. **Developer**: Address 2 MUST_FIX items
+2. **Developer**: Consider SHOULD_FIX items (optional but recommended)
+3. **Developer**: Re-request review: comment `@tech-lead ready for re-review`
+4. **Tech Lead**: Re-review (spot-check)
+
+### Ticket Update
+Added review comment. No status change (still IN_REVIEW).
+
+---
+HANDOFF → developer
+Re-review expected within 1 iteration.
+```
+
+## 🚨 Failure Modes
+
+| Scenario | Action |
+|----------|--------|
+| PR closed / merged | ABORT, cannot review |
+| Own PR | ABORT with RULE TL-005 reference |
+| CI red | ABORT, instruct fix CI first |
+| Huge PR (>1000 lines changed) | Suggest split, but proceed with warning |
+| No tests added | MUST_FIX, coverage failed already |
+| Secrets in diff | CRITICAL: Block + immediate notification |
+| Review paralysis (too many issues) | Prioritize top 3 MUST_FIX, defer rest to follow-up |
+
+## 🔗 Related Commands
+
+- **Before**: `/create-pr` (Developer's step)
+- **Alternatives**: `/security-review` (security-focused only)
+- **After approval**: `/merge-pr` (by Tech Lead)
+- **After changes requested**: Developer fixes, re-requests, back to this command
+
+## 📊 Metrics Tracked
+
+```json
+{
+  "timestamp": "2026-04-18T15:00:00Z",
+  "pr_number": 123,
+  "ticket_id": "TICKET-042",
+  "reviewer": "tech-lead-agent",
+  "review_duration_seconds": 2700,
+  "depth": "full",
+  "decision": "CHANGES_REQUESTED",
+  "must_fix_count": 2,
+  "should_fix_count": 3,
+  "nit_count": 2,
+  "praise_count": 1,
+  "owasp_concerns": 1,
+  "iterations": 1
+}
+```
+
+---
+**Last updated**: 2026-04-18
+**Maintainer**: Tech Lead agent

package/core/skills/using-ai-core/SKILL.md

@@ -0,0 +1,72 @@
+---
+name: using-ai-core
+description: Use at the start of any AI Core project conversation. Establishes chat-first command handling, agent inference, state governance, documentation rules, and guided next-step reporting.
+---
+
+# Using AI Core
+
+AI Core is a chat-first enterprise SDLC framework. The user should interact through the AI chat window, not by running shell wrappers.
+
+## Mandatory Behavior
+
+Before responding to a project workflow request, check whether one of these applies:
+
+- The user typed a slash command such as `/analyze-requirements`.
+- The user typed a guided command such as `guide /groom-ticket TICKET-001 5`.
+- The user asked for the next workflow step, status, sprint, ticket, release, docs, review, QA, or implementation.
+- The user asked to modify production code.
+
+If any applies, use AI Core rules, commands, and state.
+
+## Chat Interface
+
+Users type:
+
+```text
+/analyze-requirements "User can reset password"
+/groom-ticket TICKET-001 5
+guide /mark-ready TICKET-001
+next TICKET-001
+```
+
+Do not ask users to type `bash core/scripts/ai-core.sh` or `AI_AGENT=...` during normal use. Those are internal tools for deterministic execution and CI.
+
+## Agent Selection
+
+Infer the agent from command metadata:
+
+- `owner_agent`
+- `requires_agents`
+
+If command metadata and user intent conflict, explain the conflict and stop.
+
+## Source Of Truth
+
+- `project/` is machine-readable runtime state.
+- `docs/` is human-readable project documentation.
+- `config/` is project configuration.
+- `core/` is portable framework code.
+
+Do not move backlog, tickets, releases, bugs, sprints, or audit records into `docs/`. Generate human-readable summaries in `project/views/` and keep longer narrative docs in `docs/`.
+
+## Guided Report
+
+After completing a workflow step, report:
+
+- completed command
+- inferred agent
+- ticket state before and after, if applicable
+- files created or updated
+- validation results
+- suggested next chat command
+
+Ask before running the next step. Do not continue automatically when the next command needs missing arguments.
+
+## Required Gates
+
+- No production code without an active `IN_PROGRESS` ticket.
+- No skipped state transitions.
+- No self-approval.
+- No DONE without fresh verification evidence.
+- No public API, setup, migration, architecture, or release-impacting change without the required docs evidence.
+

package/core/skills/verification-before-done/SKILL.md

@@ -0,0 +1,35 @@
+---
+name: verification-before-done
+description: Use before claiming a ticket, PR, release, or fix is complete. Requires fresh evidence before completion claims.
+---
+
+# Verification Before Done
+
+Do not claim work is complete without fresh verification evidence from this session.
+
+## Gate
+
+Before saying a workflow step is complete:
+
+1. Identify what proves the claim.
+2. Run or inspect the relevant verification.
+3. Read the result.
+4. Record evidence in `project/test-runs/`, `project/verifications/`, or the ticket.
+5. Only then report completion.
+
+## Required Evidence
+
+For DONE tickets:
+
+- `qa_evidence.path`
+- `qa_evidence.verified_by`
+- `qa_evidence.verified_at`
+- `dod_checklist.tests_passed = true`
+- `dod_checklist.qa_verified = true`
+
+For docs-sensitive changes:
+
+- `documentation.paths`
+- ADR path when architecture changed
+- runbook path when migration or operations changed
+

package/core/skills/writing-implementation-plan/SKILL.md

@@ -0,0 +1,45 @@
+---
+name: writing-implementation-plan
+description: Use after a ticket has a spec and is groomed or ready. Creates a detailed implementation plan before coding.
+---
+
+# Writing Implementation Plans
+
+Use this skill when creating `docs/project/plans/TICKET-XXX-<slug>-plan.md`.
+
+## Plan Requirements
+
+The plan must be specific enough for an agent to execute without guessing.
+
+Include:
+
+- goal
+- linked ticket
+- linked spec, if available
+- affected files
+- task checklist
+- test strategy
+- documentation updates
+- verification commands
+- rollback notes
+- risks and open questions
+
+## Task Quality Bar
+
+Each task should be small, verifiable, and ordered:
+
+- exact files to create or modify
+- exact tests to write or run
+- expected verification result
+- docs to update
+
+Avoid placeholders such as `TODO`, `TBD`, `add tests`, or `handle edge cases` without details.
+
+## Handoff
+
+After writing the plan:
+
+- link it from the ticket as `implementation_plan_path`
+- run state validation
+- suggest `/implement-task TICKET-XXX`
+