opencode-overclock 0.3.0 → 0.5.0

package/skills/to-spec/SKILL.md

@@ -0,0 +1,69 @@
+---
+name: to-spec
+description: Synthesizes conversation context and requirements into a structured specification without reopening interviews. Use when requirements have been discussed and agreed upon, and you need to document the formal spec.
+pack: core
+license: MIT
+attribution: Adapted from mattpocock/skills (MIT License)
+references:
+  - SPEC-TEMPLATE.md
+---
+
+# To Spec: Requirements Synthesis
+
+Transform agreed conversation context, architecture boundaries, and requirements into a clear, testable specification.
+
+## Core Rule: No Renewed Interview
+
+Do **NOT** reopen the interview loop. The time for grilling was during requirements elicitation (`grilling`). Now is the time for **synthesis**: consolidate what has already been agreed upon into an actionable document.
+
+- Only pause to confirm testing seams if multiple viable seams exist.
+- Do not ask open-ended questions about things already discussed.
+
+## When to Use
+
+- Requirements have been gathered and agreed upon (e.g. following a grilling session).
+- Drafting `SPEC.md` or updating an existing project specification.
+- Translating high-level feature requests into concrete acceptance criteria and seams.
+
+## When NOT to Use
+
+- Requirements are still vague or contradictory (use `grilling` first).
+- Decomposing an already completed spec into executable tasks (use `to-tickets` instead).
+
+---
+
+## Synthesis Process
+
+### 1. Survey Codebase Context & Conventions
+
+Inspect existing code to ground the spec:
+
+- Check existing ubiquitous language (`CONTEXT.md`).
+- Respect any relevant Architecture Decision Records (`docs/adr/`).
+- Identify established test patterns and libraries in the repository.
+
+### 2. Identify the Public Testing Seams
+
+Determine the cleanest boundaries at which automated tests will verify the feature:
+
+- **Prefer existing seams:** Use existing module interfaces or API endpoints rather than creating artificial test-only hooks.
+- **Prefer high seams:** Test through the public interface of the module or service.
+- **Fewer seams is better:** The ideal number of external test seams across a feature is one or two.
+
+Check with the user that the selected test seams match expectations before finalizing the document.
+
+### 3. Draft the Specification
+
+Write `SPEC.md` (or the project's designated spec location) using the structured format in [SPEC-TEMPLATE.md](SPEC-TEMPLATE.md):
+
+- **Problem Statement & Solution:** User-perspective framing.
+- **Ubiquitous Language:** Canonical names and entities.
+- **User Stories:** Extensive, numbered list with verifiable acceptance criteria.
+- **Public Seams & Interfaces:** Explicit signatures, types, and invariants.
+- **3-Tier Boundaries:** Always Do / Ask First / Never Do.
+- **Out of Scope:** Concrete non-goals preventing scope creep.
+- **Verification Strategy:** Automated commands that prove completion.
+
+### 4. Present for Confirmation
+
+Present the synthesized specification to the human architect for approval. Once confirmed, proceed to task decomposition via `to-tickets`.

package/skills/to-spec/SPEC-TEMPLATE.md

@@ -0,0 +1,50 @@
+# Specification Template
+
+```markdown
+# Specification: [Feature Name]
+
+## 1. Problem Statement
+
+The problem that the user or system is facing, stated from the user's perspective. What friction, limitation, or deficiency currently exists?
+
+## 2. Proposed Solution
+
+The high-level solution and intended user experience. How does this resolve the problem statement?
+
+## 3. Ubiquitous Language & Entities
+
+Key terms defined precisely (referencing `CONTEXT.md` where established).
+
+- **[Entity 1]:** [Definition]
+- **[Entity 2]:** [Definition]
+
+## 4. User Stories & Acceptance Criteria
+
+Numbered list of user stories covering all functional aspects:
+
+1. **As a** [actor], **I want** [capability], **so that** [outcome/benefit].
+   - **Given:** [initial state]
+   - **When:** [action taken]
+   - **Then:** [expected verifiable outcome]
+
+## 5. Public Seams & Interfaces
+
+Explicit declarations of public types, API endpoints, function signatures, or CLI contracts:
+
+- Prefer existing high-level seams over creating new low-level seams.
+- Document inputs, outputs, errors, and invariants.
+
+## 6. 3-Tier Boundaries
+
+- **Always Do:** Non-negotiables (invariants, validations, mandatory logging).
+- **Ask First:** Irreversible actions requiring explicit human confirmation.
+- **Never Do:** Prohibited patterns or anti-patterns.
+
+## 7. Out of Scope (Non-Goals)
+
+Explicit list of items intentionally excluded from this increment.
+
+## 8. Verification Strategy
+
+How the feature will be proven before merging (unit tests, integration smoke tests, automated reproduction commands).
+```

package/skills/to-tickets/SKILL.md

@@ -0,0 +1,74 @@
+---
+name: to-tickets
+description: Decomposes a specification or plan into a directed acyclic graph (DAG) of independently verifiable, tracer-bullet tasks. Use when planning implementation steps from a spec or readying work for execution.
+pack: core
+license: MIT
+attribution: Adapted from mattpocock/skills (MIT License)
+references:
+  - TICKET-TEMPLATE.md
+---
+
+# To Tickets: Task Decomposition & Dependency Planning
+
+Decompose a specification, feature plan, or design into an executable dependency DAG of **tracer-bullet tasks**.
+
+## Core Principles
+
+### 1. Vertical Tracer Bullets vs Horizontal Layers
+
+- **Anti-pattern (Horizontal Slicing):** "Task 1: Build all database tables; Task 2: Build all API routes; Task 3: Build UI." Slices cannot be tested end-to-end, defer integration risks to the end, and leave software broken between steps.
+- **Tracer Bullet (Vertical Slicing):** Each task cuts a narrow but COMPLETE path through schema, logic, interface, and tests. Each completed task delivers working, verifiable software at that seam.
+
+### 2. Context-Sized Increments
+
+- Size each increment so it can be implemented, verified, and reasoned about within a single, fresh context window.
+- Thin increments (~50-150 lines of focused diff) minimize regression risk and make rollbacks trivial.
+
+### 3. Explicit Blocking Edges & The Ready Frontier
+
+- Every task explicitly declares its prerequisite blockers: `Blocked By: [Task IDs]`.
+- Tasks with no blockers form the **Ready Frontier** and can be worked on immediately or in parallel.
+- Maintain an accurate DAG so tasks are never started before their true foundations exist.
+
+### 4. The Wide-Refactor Exception: Expand-and-Contract
+
+A **wide refactor** (e.g. renaming a ubiquitous column, changing a core function signature used across hundreds of files) cannot be landed in a single vertical slice without breaking the entire test suite.
+
+Do NOT force wide refactors into single tracer bullets. Sequence them as **Expand-and-Contract**:
+
+1. **Expand:** Introduce the new interface or column alongside the old one. Both exist simultaneously; existing tests remain green.
+2. **Migrate:** Migrate callers in bounded batches (by directory or module). Each batch is an independent task blocked by Expand, keeping CI green at every step.
+3. **Contract:** Once all callers use the new interface, delete the old implementation and remove deprecation warnings. Blocked by all migration batches.
+4. _(Optional)_ When intermediate batches cannot stay green in isolation, execute on a dedicated integration branch with a final integrate-and-verify gate.
+
+---
+
+## The Decomposition Process
+
+### 1. Prefactoring First
+
+Look for opportunities to refactor existing code before adding new logic:
+
+> _"Make the change easy, then make the easy change."_ (Kent Beck)
+> If prefactoring is needed, make it Task 1 on the frontier.
+
+### 2. Draft Tasks with Public Seams
+
+For each task, define:
+
+- **Title:** Concise imperative action.
+- **Blocked By:** Explicit prerequisites.
+- **Seam:** File path to the automated test suite or verification assertion that will prove completion.
+- **Acceptance Criteria:** Verifiable conditions satisfying requirements.
+
+### 3. Output Location
+
+By default, output the plan to `tasks/plan.md` in the workspace using the format in [TICKET-TEMPLATE.md](TICKET-TEMPLATE.md). If integrated with an external issue tracker (GitHub, Linear), format each task as an issue and link blocking dependencies.
+
+### 4. Confirm with Human Architect
+
+Present the task breakdown to the user. Confirm:
+
+- Granularity: Are any tasks too large or too trivial?
+- Blocking Edges: Are dependencies minimal and strictly gating?
+- Once confirmed, proceed to execution via `/build` or the `tdd` skill.

package/skills/to-tickets/TICKET-TEMPLATE.md

@@ -0,0 +1,41 @@
+# Ticket & Plan Templates
+
+## Single Task Format (Markdown)
+
+```markdown
+### [TASK-NN]: [Concise Title in Imperative Mood]
+
+- **Blocked By:** [TASK-XX, TASK-YY | None (Can start immediately)]
+- **Seam:** [File path to test file, e.g. tests/unit/auth-token.test.ts]
+- **Deliverable:** The end-to-end behavior this task makes work from the caller's perspective.
+- **Acceptance Criteria:**
+  - [ ] Automated test at seam fails before implementation (Red).
+  - [ ] Implementation passes test without skips or suppressions (Green).
+  - [ ] Linters and typechecks pass clean.
+```
+
+---
+
+## Tasks Plan Document (`tasks/plan.md`)
+
+```markdown
+# Implementation Plan: [Feature Name]
+
+## Frontier (Ready to Execute)
+
+Tasks whose dependencies are completely satisfied.
+
+- [ ] **Task 1: [Title]**
+  - **Blocked By:** None
+  - **Seam:** `test/feature-core.test.ts`
+  - **Scope:** [Description of vertical slice]
+
+## Sequence (Blocked)
+
+Tasks waiting on prerequisite tasks.
+
+- [ ] **Task 2: [Title]**
+  - **Blocked By:** Task 1
+  - **Seam:** `test/feature-api.test.ts`
+  - **Scope:** [Description of vertical slice]
+```

package/src/bridge.ts

@@ -0,0 +1 @@
+export { createHybridPlugin, type HybridPlugin, type HybridPluginDefinition } from "./core/bridge.ts"

package/src/buddy/companion.ts

@@ -1,4 +1,74 @@
-import { SPECIES, type Companion, type CompanionStats, type Rarity } from "./types.ts"
+import type { SpriteState } from "./sprites.ts"
+
+export const SPECIES = [
+  "cat",
+  "dog",
+  "bunny",
+  "owl",
+  "bat",
+  "penguin",
+  "duck",
+  "ghost",
+  "slime",
+] as const
+export type Species = (typeof SPECIES)[number]
+
+export type Rarity = "common" | "uncommon" | "rare" | "legendary"
+
+export interface CompanionStats {
+  patience: number
+  chaos: number
+  wisdom: number
+  snark: number
+}
+
+export interface Companion {
+  species: Species
+  rarity: Rarity
+  name: string
+  stats: CompanionStats
+  hatchedAt: number
+}
+
+export type ReactionKind = "done" | "error" | "permission" | "question" | "pet"
+
+/** Speech-bubble line + which face the sprite pulls while it shows. */
+export interface Reaction {
+  text: string
+  state: SpriteState
+}
+
+// Lines render into the sprite's 12-col effect row -- keep every line <= 12 chars.
+const POOLS: Record<ReactionKind, { lines: string[]; state: SpriteState }> = {
+  done: { lines: ["cooked", "ate that", "big W", "say less", "we ball"], state: "idle" },
+  error: { lines: ["bruh", "ur cooked", "skill issue", "aint no way", "big L"], state: "alarmed" },
+  permission: { lines: ["let me cook", "valid?", "we good?", "bet?", "vibe check"], state: "curious" },
+  question: { lines: ["wym?", "the move?", "u tell me", "spill", "hbu?"], state: "curious" },
+  pet: { lines: ["pookie!", "w rizz", "ur valid", "slay", "ily"], state: "pet" },
+}
+
+/** Pure: pick a random line for a reaction kind. */
+export function pickReaction(kind: ReactionKind, rng: () => number = Math.random): Reaction {
+  const pool = POOLS[kind]
+  return { text: pool.lines[Math.floor(rng() * pool.lines.length)]!, state: pool.state }
+}
+
+export interface ReactionGate {
+  /** True + arms the cooldown if enough time has passed since the last fire. */
+  tryFire(now?: number): boolean
+}
+
+/** Debounce for event-driven reactions -- keeps a busy session from spamming the bubble. */
+export function createReactionGate(cooldownMs = 8000): ReactionGate {
+  let last = -Infinity
+  return {
+    tryFire(now: number = Date.now()): boolean {
+      if (now - last < cooldownMs) return false
+      last = now
+      return true
+    },
+  }
+}
 
 const RARITY_WEIGHTS: { rarity: Rarity; weight: number }[] = [
   { rarity: "common", weight: 60 },
@@ -55,16 +125,45 @@ function rollStat(rng: () => number): number {
 }
 
 /**
- * Companions persist in TUI kv and outlive the sprite sheet, so an install that
- * hatched a species we have since retired would look it up and find no art. Move
- * it onto a species we still draw, keeping the identity that isn't the drawing:
- * same name, rarity, stats and hatch date. Returns undefined when nothing to do.
+ * Move companion onto an active species if its hatched species was retired.
  */
 export function migrateSpecies(c: Companion, rng: () => number = Math.random): Companion | undefined {
   if ((SPECIES as readonly string[]).includes(c.species)) return undefined
   return { ...c, species: pick(rng, SPECIES) }
 }
 
+/** Short character descriptions for each species based on their idle fidget. */
+export const SPECIES_DESCRIPTIONS: Record<Species, string> = {
+  cat: "tail flick",
+  dog: "ear perk",
+  bunny: "ear wiggle",
+  owl: "feather ruffle",
+  bat: "wing beat",
+  penguin: "waddle",
+  duck: "ripples",
+  ghost: "float",
+  slime: "squash",
+}
+
+/** Pure: formatted description for dialog options. */
+export function speciesDescription(species: Species, isCurrent = false): string {
+  const desc = SPECIES_DESCRIPTIONS[species] ?? species
+  return isCurrent ? `${desc} (current)` : desc
+}
+
+/** Move companion to a new species, preserving name, stats, and hatchedAt. */
+export function switchSpecies(c: Companion, species: Species): Companion {
+  if (!(SPECIES as readonly string[]).includes(species)) return c
+  return { ...c, species }
+}
+
+/** Pure: get the next species in the SPECIES rotation. */
+export function cycleSpecies(current: Species): Species {
+  const idx = SPECIES.indexOf(current)
+  if (idx === -1) return SPECIES[0]
+  return SPECIES[(idx + 1) % SPECIES.length]!
+}
+
 /** One-line card for the /oc-buddy toast. */
 export function describeCompanion(c: Companion): string {
   const s = c.stats

package/src/buddy/sprites.ts

@@ -1,4 +1,4 @@
-import type { Species } from "./types.ts"
+import type { Species } from "./companion.ts"
 
 /**
  * Every frame is padded to exactly SPRITE_WIDTH columns so animation never
@@ -35,8 +35,8 @@ interface SpeciesArt {
   /**
    * Which of the two poses a tick shows. Per-species on purpose: alternating
    * every tick reads as a strobe, and it makes every species move alike. A cat
-   * flicks its tail rarely, a dog wags nonstop, a dragon's wingbeat is slow and
-   * held at the top, a ghost never quite lands.
+   * flicks its tail rarely, a dog wags nonstop, a bat's wingbeat flutters rapidly,
+   * a ghost never quite lands.
    */
   beat: (t: number) => 0 | 1
 }
@@ -148,7 +148,7 @@ export function withBubble(frame: string, bubble: string | undefined): string {
 /** Pure: render one frame. `tick` drives idle fidget + blink; other states are static. */
 export function spriteFrame(species: Species, state: SpriteState, tick: number): string {
   const art = ART[species]
-  const t = ((tick % 1000) + 1000) % 1000
+  const t = Math.max(0, tick)
   const body = art.idle[art.beat(t)]!
   const rest = art.idle[0]!