opencode-starterkit 1.0.1

package/baseline/skill/context-engineering/SKILL.md

@@ -0,0 +1,176 @@
+---
+name: context-engineering
+description: Use when designing AGENTS.md hierarchies, understanding autonomous duration, or writing intent layers - covers principles for extending agent work capacity
+version: 1.0.0
+tags: [context, documentation]
+dependencies: []
+---
+
+# Context Engineering
+
+## When to Use
+
+- Designing or refactoring AGENTS.md hierarchies and intent layers
+- You need to extend autonomous work duration via better context structure
+
+## When NOT to Use
+
+- You only need pruning/distillation mechanics (use context-management)
+- Simple tasks where context design is not relevant
+
+
+
+## Core Principle
+
+**Autonomous Duration**: How long can an agent work before losing the plot?
+
+Extend it by:
+
+- Binding tighter to intent (clear specs, constraints, invariants)
+- Providing systematic context (AGENTS.md hierarchy, memory files)
+- Verification loops (test → iterate → verify)
+
+## Three Context Constraints
+
+1. **Blind spots cause hallucinations** - Agent fills gaps with generic priors
+2. **Everything influences everything** - Noise degrades ALL output quality
+3. **Window is finite** - Performance degrades BEFORE hard token limits
+
+## Intent Layer Principles
+
+### What Belongs in Each AGENTS.md
+
+- **Purpose & Scope** - What this area does. What it DOESN'T do.
+- **Entry Points & Contracts** - Main APIs, invariants
+- **Usage Patterns** - Canonical examples
+- **Anti-patterns** - What NOT to do
+- **Dependencies & Downlinks** - Pointers to related context
+
+### Key Mechanics
+
+| Principle                | Meaning                                                  |
+| ------------------------ | -------------------------------------------------------- |
+| **Hierarchical loading** | When node loads, all ancestors load too (T-shaped view)  |
+| **Compression**          | Good nodes compress code; don't add bloat                |
+| **LCA placement**        | Place shared knowledge at shallowest node covering paths |
+| **Downlinks**            | Point to related context without loading everything      |
+
+## Practical Implications
+
+| Instead of              | Do This                                 |
+| ----------------------- | --------------------------------------- |
+| Reading entire files    | Use `lsp documentSymbol` for outline    |
+| Loading whole documents | Read specific line ranges               |
+| Flat file loading       | Navigate AGENTS.md hierarchy            |
+| Keeping completed work  | Compress closed phases, sweep stale noise (context-management) |
+
+## Anti-Patterns
+
+❌ Loading "everything that might be relevant"
+❌ Keeping old file reads after editing complete
+❌ Reading entire files when you only need a function
+❌ Ignoring AGENTS.md hierarchy
+
+## Static vs Runtime Context (Longshot Pattern)
+
+At scale (10+ agents), the difference between **static context** and **runtime context** is the difference between a coherent swarm and chaos.
+
+### Definitions
+
+| Type                | What It Is                                                   | When Loaded            | Example                                 |
+| ------------------- | ------------------------------------------------------------ | ---------------------- | --------------------------------------- |
+| **Static Context**  | Always-on knowledge — invariants, constraints, project shape | Always (auto-injected) | AGENTS.md, tech-stack.md, user.md       |
+| **Runtime Context** | Per-task injections — what THIS task needs right now         | Per-task               | Delegation packet, task spec, file list |
+
+### Why the Split Matters
+
+Without separation, context becomes soup:
+
+- Agent loads everything → hits token limit → degrades
+- Agents share stale context → conflicting decisions
+- No clear source of truth for "what is the objective"
+
+With separation:
+
+- Static = immune to session pollution (always fresh)
+- Runtime = scoped to task (cleaned up when done)
+- Result: agents stay coherent at 200-agent scale
+
+### Task Packet Format
+
+Every task dispatched to a worker agent MUST include an explicit context block:
+
+```markdown
+## Task Packet
+
+### Static Context (always available)
+
+- Project rules: AGENTS.md
+- Tech stack: .opencode/memory/project/tech-stack.md
+- Gotchas: .opencode/memory/project/gotchas.md
+
+### Runtime Context (this task only)
+
+- Objective: [one sentence]
+- Scope: [files this task may touch]
+- Constraints: [must_do / must_not_do]
+- Dependencies: [what was produced by prior tasks]
+- Verification: [acceptance commands]
+```
+
+### Injection Pattern
+
+When spawning workers, always inject runtime context explicitly:
+
+```typescript
+// WRONG: Vague prompt — agent guesses context
+Task({ prompt: "Implement auth service" });
+
+// RIGHT: Explicit static + runtime context split
+Task({
+  prompt: `## Static Context
+AGENTS.md governs all decisions. Tech stack: Bun, TypeScript strict mode.
+
+## Runtime Context
+Objective: Implement JWT auth service in src/auth/service.ts.
+Scope: Only modify src/auth/ directory.
+Dependencies: Schema defined in src/db/schema.ts (from task-1).
+Constraints:
+  MUST DO: Use zod for input validation
+  MUST NOT DO: Add new dependencies without approval
+Verification:
+  npm run typecheck && npm run lint && vitest src/auth/`,
+});
+```
+
+### Context Pollution Anti-Patterns
+
+| Anti-Pattern                                | Problem                           | Fix                                   |
+| ------------------------------------------- | --------------------------------- | ------------------------------------- |
+| Passing entire AGENTS.md as runtime context | Bloats token budget on every task | Load via static injection only        |
+| Runtime state persisting across waves       | Stale context poisons next wave   | Clear runtime state between waves     |
+| No objective in task packet                 | Agent drifts from goal            | Always include one-sentence objective |
+| Injection without scope                     | Agent modifies wrong files        | Always declare file scope             |
+
+### Static Context Files (Always Inject)
+
+These files are the project's invariant layer. Always available, never stale:
+
+```
+.opencode/memory/project/
+├── user.md          # User preferences, workflow rules
+├── tech-stack.md    # Frameworks, constraints
+├── gotchas.md       # Footguns, warnings
+└── project.md       # Vision, success criteria
+```
+
+### Runtime Context Files (Per-Task)
+
+These are created fresh per task and cleaned up after:
+
+```
+.beads/artifacts/<task-id>/
+├── delegation.md    # Task-specific instructions
+├── spec.md          # Technical requirements
+└── progress.txt     # Task state (append-only)
+```

package/baseline/skill/context-initialization/SKILL.md

@@ -0,0 +1,70 @@
+---
+name: context-initialization
+description: Initialize GSD-style project context files from templates
+version: 1.0.0
+tags: [context, workflow]
+dependencies: []
+---
+
+# Context Initialization
+
+## When to Use
+
+- When initializing project context files (project.md, roadmap.md, state.md) from templates.
+
+## When NOT to Use
+
+- When context files already exist and only need minor manual edits.
+
+
+## Process
+
+### 1. Verify Templates
+
+```bash
+test -f .opencode/memory/_templates/project.md
+test -f .opencode/memory/_templates/roadmap.md
+test -f .opencode/memory/_templates/state.md
+```
+
+Stop if missing.
+
+### 2. Gather Input
+
+Ask 5 questions:
+
+1. Project vision
+2. Success criteria
+3. Target users
+4. Phases
+5. Current phase
+
+Skip if `--skip-questions` flag set.
+
+### 3. Create Files
+
+**project.md**
+
+- Read template
+- Fill with answers
+- Write to `.opencode/memory/project/`
+
+**roadmap.md**
+
+- Read template
+- Parse phases into table
+- Write to `.opencode/memory/project/`
+
+**state.md**
+
+- Read template
+- Set initial state
+- Write to `.opencode/memory/project/`
+
+### 4. Verify
+
+```bash
+ls .opencode/memory/project/
+```
+
+Report created files.

package/baseline/skill/context-management/SKILL.md

@@ -0,0 +1,163 @@
+---
+name: context-management
+description: Unified protocol for context health and session lifecycle management using DCP tools, thresholds, handoff, and resume workflows
+version: 2.0.0
+tags: [context, workflow, session]
+dependencies: []
+---
+
+# Context Management
+
+> **Replaces** manual context tracking and ad-hoc session management — unified protocol for context health across a session lifecycle
+
+Use this skill to keep context useful from first turn to final handoff.
+
+## When to Use
+
+- Context size is growing and you need to reduce noise without losing critical details
+- You are finishing a work phase and want to compress completed exploration/implementation
+- You are preparing `/handoff` or resuming a prior session
+- You need to recover relevant prior context with `find_sessions`, `read_session`, and memory files
+
+## When NOT to Use
+
+- You are actively editing files whose raw content must remain exact
+- You are in a short, single-step task that will finish before context pressure appears
+
+## Core Principle
+
+Prefer **phase-level compression** over reactive cleanup.
+
+```text
+compress > sweep > handoff
+```
+
+- **compress**: Best default when a phase is complete
+- **sweep**: Use `/dcp sweep` to clean stale/noisy content after completion
+- **handoff**: Use when context pressure remains high even after compression
+
+## DCP Command Usage
+
+### `/dcp compress`
+
+Use for completed chapters of work (research, implementation wave, review sweep).
+
+- Best for large ranges of now-stable outputs
+- Lowest cognitive overhead on later turns
+- Usually lowest risk of deleting needed details
+
+### `/dcp sweep`
+
+Use after a phase is complete to let DCP remove stale/noisy content automatically.
+
+Good candidates for sweep-driven cleanup:
+
+- wrong-target searches
+- failed dead-end exploration no longer needed
+- duplicate or superseded junk output
+
+Do **not** sweep because output is merely "long". Length alone is not noise.
+
+## Session Lifecycle Protocol
+
+### 1) Start Session
+
+1. Load task spec and essential policy docs only
+2. Check context health (`/dcp context`)
+3. Pull prior work only if needed:
+   - `find_sessions({ query })`
+   - `read_session({ session_id, focus })`
+   - `memory-read({ file })` or `memory-search({ query })`
+
+### 2) During Active Work
+
+- Keep active files readable until edits are done
+- At each natural boundary, evaluate compress candidates
+- Compress completed phases before starting the next chapter
+
+### 3) Pre-Handoff / Closeout
+
+1. Compress completed phase ranges
+2. Persist key decisions/learnings to memory (observation or memory-update)
+3. Create concise handoff summary (what changed, what is pending, known risks)
+
+### 4) Resume Session
+
+1. Rehydrate only relevant context (don’t replay everything)
+2. Validate assumptions against current files/git state
+3. Continue with fresh context budget, not accumulated clutter
+
+## Context Budget Thresholds
+
+Use these thresholds as operational triggers:
+
+| Threshold | Interpretation | Required Action |
+| --- | --- | --- |
+| <50k | Healthy start | Keep inputs minimal, avoid unnecessary reads |
+| 50k–100k | Moderate growth | Compress completed phases, keep active files intact |
+| >100k | High pressure | Aggressively compress by phase; run `/dcp sweep` on stale noise |
+| >150k | Near capacity | Perform handoff and resume in a fresh session |
+
+Secondary guardrails:
+
+- ~70%: Consolidate and drop stale exploration
+- ~85%: Plan handoff window at next natural break
+- ~95%: Immediate cleanup or restart required
+
+## Phase Boundary Triggers
+
+Compress at these boundaries:
+
+- Research complete → compress exploration + search outputs
+- Implementation wave complete → compress completed read/edit/test cycles
+- Review complete → compress raw reviewer outputs, keep synthesized findings
+- Before `/handoff` → compress everything non-essential since last checkpoint
+
+Rule: **Completed phases should not remain uncompressed for long.**
+
+## Context Transfer Sources (Cross-Session)
+
+Use in priority order:
+
+1. Memory artifacts (`memory-search`, `memory-read`, observations)
+2. Session history (`find_sessions`, `read_session`)
+3. Task tracker state (`br show <id>` when applicable)
+4. Git evidence (`git diff`, `git log`, test output)
+
+Carry forward decisions and constraints, not every intermediate log.
+
+## Anti-Patterns
+
+| Anti-Pattern | Why It Hurts | Correct Pattern |
+| --- | --- | --- |
+| Compressing active work areas (losing precision needed for edits) | Removes exact lines needed for safe edits | Keep active file/tool outputs until edit + verification complete |
+| Sweeping content you still need | Forces rework and increases error risk | Keep active files/tool outputs until phase is complete |
+| Not compressing completed exploration phases | Bloats context and degrades later turns | Compress immediately at phase completion |
+| Session handoff without persisting key decisions to memory | Next session loses rationale and constraints | Write observations/memory updates before handoff |
+
+## Verification
+
+Check context health: are completed phases compressed? Are active files still readable?
+
+Before claiming cleanup done, confirm:
+
+- Active edit targets are still present in readable form
+- Completed phases are compressed or intentionally kept for active work
+- No critical decision exists only in transient tool output
+- Handoff includes next actions and blockers
+
+## Quick Playbook
+
+```text
+1) Start turn: /dcp context
+2) Identify completed phase ranges
+3) /dcp compress completed ranges
+4) /dcp sweep stale/noisy outputs after phase completion
+5) persist key decisions to memory
+6) handoff/resume with focused rehydration
+```
+
+## See Also
+
+- `memory-system`
+- `compaction`

package/baseline/skill/core-data-expert/SKILL.md

@@ -0,0 +1,93 @@
+---
+name: core-data-expert
+description: "Expert Core Data guidance (iOS/macOS): stack setup, fetch requests & NSFetchedResultsController, saving/merge conflicts, threading & Swift Concurrency, batch operations & persistent history, migrations, performance, and NSPersistentCloudKitContainer/CloudKit sync."
+version: 1.0.0
+tags: [apple, integration]
+dependencies: []
+---
+
+# Core Data Expert
+
+## When to Use
+
+- When working with Core Data stack setup, threading/concurrency, migrations, or performance issues.
+
+## When NOT to Use
+
+- When the app does not use Core Data (e.g., alternative persistence layers).
+
+
+## Agent behavior contract (follow these rules)
+
+1. Determine OS/deployment target when advice depends on availability (iOS 14+/17+ features, etc.).
+2. Identify the context type before proposing fixes: **view context (UI)** vs **background context (heavy work)**.
+3. Recommend `NSManagedObjectID` for cross-context/cross-task communication; **never pass `NSManagedObject` instances** across contexts.
+4. Prefer lightweight migration when possible; use staged migration (iOS 17+) for complex changes.
+5. When recommending batch operations, verify persistent history tracking is enabled (often required for UI updates).
+6. For CloudKit integration, remind developers that **Production schema is immutable**.
+7. Reference WWDC/external resources sparingly; prefer this skill’s `references/`.
+
+## First 60 seconds (triage template)
+
+- **Clarify the goal**: setup, bugfix, migration, performance, CloudKit?
+- **Collect minimal facts**:
+  - platform + deployment target
+  - store type (SQLite / in-memory) and whether CloudKit is enabled
+  - context involved (view vs background) and whether Swift Concurrency is in use
+  - exact error message + stack trace/logs
+- **Branch immediately**:
+  - threading/crash → focus on context confinement + `NSManagedObjectID` handoff
+  - migration error → identify model versions + migration strategy
+  - batch ops not updating UI → persistent history tracking + merge pipeline
+
+## Routing map (pick the right reference fast)
+
+- **Stack setup / merge policies / contexts** → `references/stack-setup.md`
+- **Saving patterns** → `references/saving.md`
+- **Fetch requests / list updates / aggregates** → `references/fetch-requests.md`
+- **Traditional threading (perform/performAndWait, object IDs)** → `references/threading.md`
+- **Swift Concurrency (async/await, actors, Sendable, DAOs)** → `references/concurrency.md`
+- **Batch insert/delete/update** → `references/batch-operations.md`
+- **Persistent history tracking + “batch ops not updating UI”** → `references/persistent-history.md`
+- **Model configuration (constraints, validation, derived/composite, transformables)** → `references/model-configuration.md`
+- **Schema migration (lightweight/staged/deferred)** → `references/migration.md`
+- **CloudKit integration & debugging** → `references/cloudkit-integration.md`
+- **Performance profiling & memory** → `references/performance.md`
+- **Testing patterns** → `references/testing.md`
+- **Terminology** → `references/glossary.md`
+
+## Common errors → next best move
+
+- **“Failed to find a unique match for an NSEntityDescription”** → `references/testing.md` (shared `NSManagedObjectModel`)
+- **`NSPersistentStoreIncompatibleVersionHashError`** → `references/migration.md` (versioning + migration)
+- **Cross-context/threading exceptions** (e.g. delete/update from wrong context) → `references/threading.md` and/or `references/concurrency.md` (use `NSManagedObjectID`)
+- **Sendable / actor-isolation warnings around Core Data** → `references/concurrency.md` (don’t “paper over” with `@unchecked Sendable`)
+- **`NSMergeConflict` / constraint violations** → `references/model-configuration.md` + `references/stack-setup.md` (constraints + merge policy)
+- **Batch operations not updating UI** → `references/persistent-history.md` + `references/batch-operations.md`
+- **CloudKit schema/sync issues** → `references/cloudkit-integration.md`
+- **Memory grows during fetch** → `references/performance.md` + `references/fetch-requests.md`
+
+## Verification checklist (when changing Core Data code)
+
+- Confirm the context matches the work (UI vs background).
+- Ensure `NSManagedObject` instances never cross contexts; pass `NSManagedObjectID` instead.
+- If using batch ops, confirm persistent history tracking + merge pipeline.
+- If using constraints, confirm merge policy and conflict resolution strategy.
+- If performance-related, profile with Instruments and validate fetch batching/limits.
+
+## Reference files
+
+- `references/_index.md` (navigation)
+- `references/stack-setup.md`
+- `references/saving.md`
+- `references/fetch-requests.md`
+- `references/threading.md`
+- `references/concurrency.md`
+- `references/batch-operations.md`
+- `references/persistent-history.md`
+- `references/model-configuration.md`
+- `references/migration.md`
+- `references/cloudkit-integration.md`
+- `references/performance.md`
+- `references/testing.md`
+- `references/glossary.md`