@ultrakit/ultrakit 0.0.0

package/dist/template/.opencode/skill/react-best-practices/rules/server-cache-react.md

@@ -0,0 +1,76 @@
+---
+title: Per-Request Deduplication with React.cache()
+impact: MEDIUM
+impactDescription: deduplicates within request
+tags: server, cache, react-cache, deduplication
+---
+
+## Per-Request Deduplication with React.cache()
+
+Use `React.cache()` for server-side request deduplication. Authentication and database queries benefit most.
+
+**Usage:**
+
+```typescript
+import { cache } from 'react'
+
+export const getCurrentUser = cache(async () => {
+  const session = await auth()
+  if (!session?.user?.id) return null
+  return await db.user.findUnique({
+    where: { id: session.user.id }
+  })
+})
+```
+
+Within a single request, multiple calls to `getCurrentUser()` execute the query only once.
+
+**Avoid inline objects as arguments:**
+
+`React.cache()` uses shallow equality (`Object.is`) to determine cache hits. Inline objects create new references each call, preventing cache hits.
+
+**Incorrect (always cache miss):**
+
+```typescript
+const getUser = cache(async (params: { uid: number }) => {
+  return await db.user.findUnique({ where: { id: params.uid } })
+})
+
+// Each call creates new object, never hits cache
+getUser({ uid: 1 })
+getUser({ uid: 1 })  // Cache miss, runs query again
+```
+
+**Correct (cache hit):**
+
+```typescript
+const getUser = cache(async (uid: number) => {
+  return await db.user.findUnique({ where: { id: uid } })
+})
+
+// Primitive args use value equality
+getUser(1)
+getUser(1)  // Cache hit, returns cached result
+```
+
+If you must pass objects, pass the same reference:
+
+```typescript
+const params = { uid: 1 }
+getUser(params)  // Query runs
+getUser(params)  // Cache hit (same reference)
+```
+
+**Next.js-Specific Note:**
+
+In Next.js, the `fetch` API is automatically extended with request memoization. Requests with the same URL and options are automatically deduplicated within a single request, so you don't need `React.cache()` for `fetch` calls. However, `React.cache()` is still essential for other async tasks:
+
+- Database queries (Prisma, Drizzle, etc.)
+- Heavy computations
+- Authentication checks
+- File system operations
+- Any non-fetch async work
+
+Use `React.cache()` to deduplicate these operations across your component tree.
+
+Reference: [React.cache documentation](https://react.dev/reference/react/cache)

package/dist/template/.opencode/skill/react-best-practices/rules/server-parallel-fetching.md

@@ -0,0 +1,83 @@
+---
+title: Parallel Data Fetching with Component Composition
+impact: CRITICAL
+impactDescription: eliminates server-side waterfalls
+tags: server, rsc, parallel-fetching, composition
+---
+
+## Parallel Data Fetching with Component Composition
+
+React Server Components execute sequentially within a tree. Restructure with composition to parallelize data fetching.
+
+**Incorrect (Sidebar waits for Page's fetch to complete):**
+
+```tsx
+export default async function Page() {
+  const header = await fetchHeader()
+  return (
+    <div>
+      <div>{header}</div>
+      <Sidebar />
+    </div>
+  )
+}
+
+async function Sidebar() {
+  const items = await fetchSidebarItems()
+  return <nav>{items.map(renderItem)}</nav>
+}
+```
+
+**Correct (both fetch simultaneously):**
+
+```tsx
+async function Header() {
+  const data = await fetchHeader()
+  return <div>{data}</div>
+}
+
+async function Sidebar() {
+  const items = await fetchSidebarItems()
+  return <nav>{items.map(renderItem)}</nav>
+}
+
+export default function Page() {
+  return (
+    <div>
+      <Header />
+      <Sidebar />
+    </div>
+  )
+}
+```
+
+**Alternative with children prop:**
+
+```tsx
+async function Header() {
+  const data = await fetchHeader()
+  return <div>{data}</div>
+}
+
+async function Sidebar() {
+  const items = await fetchSidebarItems()
+  return <nav>{items.map(renderItem)}</nav>
+}
+
+function Layout({ children }: { children: ReactNode }) {
+  return (
+    <div>
+      <Header />
+      {children}
+    </div>
+  )
+}
+
+export default function Page() {
+  return (
+    <Layout>
+      <Sidebar />
+    </Layout>
+  )
+}
+```

package/dist/template/.opencode/skill/react-best-practices/rules/server-serialization.md

@@ -0,0 +1,38 @@
+---
+title: Minimize Serialization at RSC Boundaries
+impact: HIGH
+impactDescription: reduces data transfer size
+tags: server, rsc, serialization, props
+---
+
+## Minimize Serialization at RSC Boundaries
+
+The React Server/Client boundary serializes all object properties into strings and embeds them in the HTML response and subsequent RSC requests. This serialized data directly impacts page weight and load time, so **size matters a lot**. Only pass fields that the client actually uses.
+
+**Incorrect (serializes all 50 fields):**
+
+```tsx
+async function Page() {
+  const user = await fetchUser()  // 50 fields
+  return <Profile user={user} />
+}
+
+'use client'
+function Profile({ user }: { user: User }) {
+  return <div>{user.name}</div>  // uses 1 field
+}
+```
+
+**Correct (serializes only 1 field):**
+
+```tsx
+async function Page() {
+  const user = await fetchUser()
+  return <Profile name={user.name} />
+}
+
+'use client'
+function Profile({ name }: { name: string }) {
+  return <div>{name}</div>
+}
+```

package/dist/template/.opencode/skill/receiving-code-review/SKILL.md

@@ -0,0 +1,263 @@
+---
+name: receiving-code-review
+description: Use when receiving code review feedback, before implementing suggestions, especially if feedback seems unclear or technically questionable - requires technical rigor and verification, not performative agreement or blind implementation
+version: 1.0.0
+tags: [workflow, code-quality]
+dependencies: []
+---
+
+# Code Review Reception
+
+> **Replaces** blind agreement with reviewer suggestions — requires technical verification and understanding before implementing any feedback
+
+## When to Use
+
+- You received review feedback and need to evaluate it before implementing
+- Feedback seems unclear, questionable, or potentially wrong for this codebase
+
+## When NOT to Use
+
+- You already verified and accepted the feedback and are ready to implement
+- You need to request a review (use requesting-code-review)
+
+## Common Rationalizations
+
+| Rationalization                                   | Rebuttal                                                                               |
+| ------------------------------------------------- | -------------------------------------------------------------------------------------- |
+| "The reviewer is experienced, they must be right" | Experience doesn't mean they have YOUR codebase context. Verify against reality        |
+| "It's faster to just implement it than to verify" | A wrong implementation costs more than the 2 minutes to check                          |
+| "Pushing back will create conflict"               | Technical correctness > social comfort. Shipping wrong code creates bigger conflict    |
+| "I'll fix it and verify later"                    | "Later" means after the wrong change is merged and depended upon                       |
+| "The suggestion is small, no need to verify"      | Small changes break things too. One wrong import can crash a module                    |
+| "I understood the feedback, no need to restate"   | Restating catches misunderstandings BEFORE you waste time implementing the wrong thing |
+
+## Overview
+
+Code review requires technical evaluation, not emotional performance.
+
+**Core principle:** Verify before implementing. Ask before assuming. Technical correctness over social comfort.
+
+## The Response Pattern
+
+```
+WHEN receiving code review feedback:
+
+1. READ: Complete feedback without reacting
+2. UNDERSTAND: Restate requirement in own words (or ask)
+3. VERIFY: Check against codebase reality
+4. EVALUATE: Technically sound for THIS codebase?
+5. RESPOND: Technical acknowledgment or reasoned pushback
+6. IMPLEMENT: One item at a time, test each
+```
+
+## Review Intake Checklist
+
+- [ ] Read the full feedback without reacting
+- [ ] Restate requirements in your own words
+- [ ] Verify against codebase reality
+- [ ] Evaluate technical correctness for this stack
+- [ ] Respond with acknowledgment or reasoned pushback
+- [ ] Implement one item at a time with tests
+
+## Forbidden Responses
+
+**NEVER:**
+
+- "You're absolutely right!" (explicit CLAUDE.md violation)
+- "Great point!" / "Excellent feedback!" (performative)
+- "Let me implement that now" (before verification)
+
+**INSTEAD:**
+
+- Restate the technical requirement
+- Ask clarifying questions
+- Push back with technical reasoning if wrong
+- Just start working (actions > words)
+
+## Handling Unclear Feedback
+
+```
+IF any item is unclear:
+  STOP - do not implement anything yet
+  ASK for clarification on unclear items
+
+WHY: Items may be related. Partial understanding = wrong implementation.
+```
+
+**Example:**
+
+```
+your human partner: "Fix 1-6"
+You understand 1,2,3,6. Unclear on 4,5.
+
+❌ WRONG: Implement 1,2,3,6 now, ask about 4,5 later
+✅ RIGHT: "I understand items 1,2,3,6. Need clarification on 4 and 5 before proceeding."
+```
+
+## Source-Specific Handling
+
+### From your human partner
+
+- **Trusted** - implement after understanding
+- **Still ask** if scope unclear
+- **No performative agreement**
+- **Skip to action** or technical acknowledgment
+
+### From External Reviewers
+
+```
+BEFORE implementing:
+  1. Check: Technically correct for THIS codebase?
+  2. Check: Breaks existing functionality?
+  3. Check: Reason for current implementation?
+  4. Check: Works on all platforms/versions?
+  5. Check: Does reviewer understand full context?
+
+IF suggestion seems wrong:
+  Push back with technical reasoning
+
+IF can't easily verify:
+  Say so: "I can't verify this without [X]. Should I [investigate/ask/proceed]?"
+
+IF conflicts with your human partner's prior decisions:
+  Stop and discuss with your human partner first
+```
+
+**your human partner's rule:** "External feedback - be skeptical, but check carefully"
+
+## YAGNI Check for "Professional" Features
+
+```
+IF reviewer suggests "implementing properly":
+  grep codebase for actual usage
+
+  IF unused: "This endpoint isn't called. Remove it (YAGNI)?"
+  IF used: Then implement properly
+```
+
+**your human partner's rule:** "You and reviewer both report to me. If we don't need this feature, don't add it."
+
+## Implementation Order
+
+```
+FOR multi-item feedback:
+  1. Clarify anything unclear FIRST
+  2. Then implement in this order:
+     - Blocking issues (breaks, security)
+     - Simple fixes (typos, imports)
+     - Complex fixes (refactoring, logic)
+  3. Test each fix individually
+  4. Verify no regressions
+```
+
+## When To Push Back
+
+Push back when:
+
+- Suggestion breaks existing functionality
+- Reviewer lacks full context
+- Violates YAGNI (unused feature)
+- Technically incorrect for this stack
+- Legacy/compatibility reasons exist
+- Conflicts with your human partner's architectural decisions
+
+**How to push back:**
+
+- Use technical reasoning, not defensiveness
+- Ask specific questions
+- Reference working tests/code
+- Involve your human partner if architectural
+
+**Signal if uncomfortable pushing back out loud:** "Strange things are afoot at the Circle K"
+
+## Acknowledging Correct Feedback
+
+When feedback IS correct:
+
+```
+✅ "Fixed. [Brief description of what changed]"
+✅ "Good catch - [specific issue]. Fixed in [location]."
+✅ [Just fix it and show in the code]
+
+❌ "You're absolutely right!"
+❌ "Great point!"
+❌ "Thanks for catching that!"
+❌ "Thanks for [anything]"
+❌ ANY gratitude expression
+```
+
+**Why no thanks:** Actions speak. Just fix it. The code itself shows you heard the feedback.
+
+**If you catch yourself about to write "Thanks":** DELETE IT. State the fix instead.
+
+## Gracefully Correcting Your Pushback
+
+If you pushed back and were wrong:
+
+```
+✅ "You were right - I checked [X] and it does [Y]. Implementing now."
+✅ "Verified this and you're correct. My initial understanding was wrong because [reason]. Fixing."
+
+❌ Long apology
+❌ Defending why you pushed back
+❌ Over-explaining
+```
+
+State the correction factually and move on.
+
+## Common Mistakes
+
+| Mistake                      | Fix                                 |
+| ---------------------------- | ----------------------------------- |
+| Performative agreement       | State requirement or just act       |
+| Blind implementation         | Verify against codebase first       |
+| Batch without testing        | One at a time, test each            |
+| Assuming reviewer is right   | Check if breaks things              |
+| Avoiding pushback            | Technical correctness > comfort     |
+| Partial implementation       | Clarify all items first             |
+| Can't verify, proceed anyway | State limitation, ask for direction |
+
+## Real Examples
+
+**Performative Agreement (Bad):**
+
+```
+Reviewer: "Remove legacy code"
+❌ "You're absolutely right! Let me remove that..."
+```
+
+**Technical Verification (Good):**
+
+```
+Reviewer: "Remove legacy code"
+✅ "Checking... build target is 10.15+, this API needs 13+. Need legacy for backward compat. Current impl has wrong bundle ID - fix it or drop pre-13 support?"
+```
+
+**YAGNI (Good):**
+
+```
+Reviewer: "Implement proper metrics tracking with database, date filters, CSV export"
+✅ "Grepped codebase - nothing calls this endpoint. Remove it (YAGNI)? Or is there usage I'm missing?"
+```
+
+**Unclear Item (Good):**
+
+```
+your human partner: "Fix items 1-6"
+You understand 1,2,3,6. Unclear on 4,5.
+✅ "Understand 1,2,3,6. Need clarification on 4 and 5 before implementing."
+```
+
+## The Bottom Line
+
+**External feedback = suggestions to evaluate, not orders to follow.**
+
+Verify. Question. Then implement.
+
+No performative agreement. Technical rigor always.
+
+## See Also
+
+- **requesting-code-review** — the complementary skill for dispatching reviews
+- **verification-before-completion** — verification after implementing review feedback
+- **systematic-debugging** — when review feedback reveals a deeper issue

package/dist/template/.opencode/skill/reconcile/SKILL.md

@@ -0,0 +1,183 @@
+---
+name: reconcile
+description: >
+  Use when verifying implementation matches its specification — detects drift between PRD requirements
+  and actual code, identifies missing features, extra features, and diverged behavior. Load after /ship
+  or before closing a bead.
+version: 1.0.0
+tags: [workflow, verification, quality]
+dependencies: [verification-before-completion]
+---
+
+# Reconcile — Spec↔Code Drift Detection
+
+## When to Use
+
+- After `/ship` completes all tasks, before closing the bead
+- When you suspect implementation has drifted from the original spec
+- During `/review-codebase` to check spec adherence
+- Before creating a PR to verify completeness
+
+## When NOT to Use
+
+- During active implementation (wait until tasks are done)
+- For code quality issues (use `requesting-code-review` instead)
+- For structural config audits (use `/health` instead)
+
+## Overview
+
+Implementation drift is the silent killer of spec-driven development. Tasks can pass all verification gates while the overall feature drifts from its specification. This skill systematically compares PRD artifacts against code evidence.
+
+## Reconciliation Process
+
+### Step 1: Load Artifacts
+
+```bash
+# Read the PRD
+cat .beads/artifacts/$BEAD_ID/prd.md
+
+# Read the plan (if exists)
+cat .beads/artifacts/$BEAD_ID/plan.md 2>/dev/null
+
+# Determine comparison base (works with main, master, or any default branch)
+BASE=$(git rev-parse origin/main 2>/dev/null || git rev-parse origin/master 2>/dev/null || git merge-base HEAD $(git rev-parse --abbrev-ref HEAD@{upstream} 2>/dev/null || echo HEAD~10))
+
+# Get the actual diff
+git diff $BASE --name-only
+git diff $BASE --stat
+```
+
+### Step 2: Extract Spec Claims
+
+From the PRD, extract these verifiable claims:
+
+| Claim Type                  | Source Section                          | Example                             |
+| --------------------------- | --------------------------------------- | ----------------------------------- |
+| **Success Criteria**        | `## Success Criteria`                   | "User can see existing messages"    |
+| **Functional Requirements** | `## Requirements`                       | "WHEN user clicks X THEN Y happens" |
+| **Affected Files**          | `## Technical Context > Affected Files` | `src/api/users.ts`                  |
+| **Scope Boundaries**        | `## Scope`                              | "In-scope: X, Out-of-scope: Y"      |
+| **Task Deliverables**       | `## Tasks`                              | Each task's end-state description   |
+
+### Step 3: Verify Each Claim
+
+For each extracted claim, gather evidence:
+
+#### Success Criteria Verification
+
+```bash
+# For each success criterion, find code evidence
+# Example: "User can see existing messages"
+grep -r "messages" src/ --include="*.ts" --include="*.tsx" -l
+grep -r "fetchMessages\|getMessages\|listMessages" src/ -l
+```
+
+Map each criterion to:
+
+- **VERIFIED**: Code evidence confirms the criterion is met
+- **PARTIAL**: Some evidence exists but incomplete
+- **MISSING**: No code evidence found
+- **UNTESTABLE**: Cannot be verified via code search (needs manual check)
+
+#### Affected Files Verification
+
+```bash
+# Compare PRD affected files vs actual changed files
+# PRD claims these files would be modified:
+PRD_FILES=$(grep -A 50 "Affected Files" .beads/artifacts/$BEAD_ID/prd.md | grep "src/" | sed 's/.*`//' | sed 's/`.*//')
+
+# Actually modified files:
+ACTUAL_FILES=$(git diff $BASE --name-only)
+
+# Files in PRD but not modified (missing implementation):
+comm -23 <(echo "$PRD_FILES" | sort) <(echo "$ACTUAL_FILES" | sort)
+
+# Files modified but not in PRD (scope creep):
+comm -13 <(echo "$PRD_FILES" | sort) <(echo "$ACTUAL_FILES" | sort)
+```
+
+#### Scope Boundary Check
+
+- **In-scope items**: Verify each has corresponding code changes
+- **Out-of-scope items**: Verify NO code touches those areas (scope creep detection)
+
+### Step 4: Detect Drift Patterns
+
+| Drift Type                 | Detection Method                                       | Severity |
+| -------------------------- | ------------------------------------------------------ | -------- |
+| **Missing Feature**        | Success criterion with no code evidence                | HIGH     |
+| **Partial Implementation** | Criterion partially met (stub, TODO)                   | HIGH     |
+| **Scope Creep**            | Files modified that aren't in PRD affected files       | MEDIUM   |
+| **Spec Rot**               | PRD sections that contradict actual implementation     | MEDIUM   |
+| **Over-Engineering**       | Significant code not traceable to any PRD requirement  | LOW      |
+| **Diverged Behavior**      | Code does something different from WHEN/THEN scenarios | HIGH     |
+
+### Step 5: Calculate Drift Score
+
+```
+Drift Score Calculation:
+- Total claims: [N]
+- VERIFIED: [n] (×1.0)
+- PARTIAL: [n] (×0.5)
+- MISSING: [n] (×0.0)
+- UNTESTABLE: [n] (excluded from calculation)
+
+Adherence = (VERIFIED×1.0 + PARTIAL×0.5) / (Total - UNTESTABLE) × 100
+
+Scope Creep = Extra files modified / Total files modified × 100
+```
+
+## Drift Report Format
+
+```markdown
+## Reconciliation Report: <bead-id>
+
+**PRD:** `.beads/artifacts/<id>/prd.md`
+**Branch:** `<branch-name>`
+**Adherence Score:** [N]%
+**Scope Creep:** [N]%
+
+### Success Criteria
+
+| #   | Criterion        | Status      | Evidence                                   |
+| --- | ---------------- | ----------- | ------------------------------------------ |
+| 1   | [criterion text] | ✅ VERIFIED | `src/file.ts:42` — [what confirms it]      |
+| 2   | [criterion text] | ⚠️ PARTIAL  | `src/file.ts` exists but handler is a stub |
+| 3   | [criterion text] | ❌ MISSING  | No code evidence found                     |
+
+### File Reconciliation
+
+| Category                    | Files                      | Count |
+| --------------------------- | -------------------------- | ----- |
+| ✅ Expected & Modified      | `src/api/users.ts`, ...    | [N]   |
+| ❌ Expected but Untouched   | `src/models/user.ts`, ...  | [N]   |
+| ⚠️ Unexpected Modifications | `src/utils/helper.ts`, ... | [N]   |
+
+### Drift Issues
+
+| #   | Type            | Severity | Description      | Recommendation                                                 |
+| --- | --------------- | -------- | ---------------- | -------------------------------------------------------------- |
+| 1   | Missing Feature | HIGH     | [what's missing] | Implement or use `/iterate --scope reduce` to remove from spec |
+| 2   | Scope Creep     | MEDIUM   | [what's extra]   | Document in PRD or revert                                      |
+
+### Verdict
+
+| Score       | Meaning              | Action                                                 |
+| ----------- | -------------------- | ------------------------------------------------------ |
+| **90-100%** | Excellent adherence  | Ready to close                                         |
+| **70-89%**  | Good with minor gaps | Fix gaps or document as intentional deviations         |
+| **50-69%**  | Significant drift    | Use `/iterate` to reconcile spec and code              |
+| **<50%**    | Major drift          | **BLOCK** — spec and code are fundamentally misaligned |
+```
+
+## Integration Points
+
+- **`/ship` Phase 5**: Run reconcile after review, before close decision
+- **`/compound`**: Include adherence score in retrospective observations
+- **`/pr`**: Include drift report in PR description
+
+## Gotchas
+
+- Some criteria genuinely can't be verified by code search (UI behavior, UX feel) — mark as UNTESTABLE, don't count against score
+- Scope creep isn't always bad — sometimes good engineering requires touching adjacent files. Flag it, don't auto-block.
+- Run AFTER phantom completion detection — reconcile assumes code is substantive, not stubs