@ultrakit/ultrakit 0.0.0

package/dist/template/.opencode/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/dist/template/.opencode/skill/context-initialization/SKILL.md

@@ -0,0 +1,69 @@
+---
+name: context-initialization
+description: Initialize project context files from templates. Creates on-demand planning files (roadmap.md, state.md) and updates auto-injected project.md.
+version: 2.0.0
+tags: [context, workflow]
+dependencies: []
+---
+
+# Context Initialization
+
+## When to Use
+
+- When initializing project context files (project.md, roadmap.md, state.md) from templates.
+- project.md is auto-injected into every prompt; roadmap.md and state.md are on-demand.
+
+## When NOT to Use
+
+- When context files already exist and only need minor manual edits.
+
+## Process
+
+### 1. Verify Templates
+
+```typescript
+tilth_tilth_files({ pattern: "*.md", scope: ".opencode/memory/_templates" });
+// Required templates: project.md, roadmap.md, 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** (auto-injected — keep concise)
+
+- Read template via `Read({ filePath: ".opencode/memory/_templates/project.md" })`
+- Fill with answers
+- Write via `memory-update({ file: "project/project", content: ..., mode: "replace" })`
+
+**roadmap.md** (on-demand — access via `memory-read({ file: "project/roadmap" })`)
+
+- Read template
+- Parse phases into table
+- Write via `memory-update({ file: "project/roadmap", content: ..., mode: "replace" })`
+
+**state.md** (on-demand — access via `memory-read({ file: "project/state" })`)
+
+- Read template
+- Set initial state
+- Write via `memory-update({ file: "project/state", content: ..., mode: "replace" })`
+
+### 4. Verify
+
+```typescript
+tilth_tilth_files({ pattern: "*.md", scope: ".opencode/memory/project" });
+```
+
+Report created files with their injection status (auto-injected vs on-demand).

package/dist/template/.opencode/skill/context-management/SKILL.md

@@ -0,0 +1,390 @@
+---
+name: context-management
+description: Unified protocol for context health and session lifecycle management using DCP tools, thresholds, handoff, resume workflows, and post-compaction restoration.
+version: 3.0.0
+tags: [context, workflow, session]
+dependencies: []
+---
+
+# Context Management
+
+> Unified protocol for context health across start, active execution, compression, restoration, handoff, and resume.
+
+Use this skill to keep context high-signal while preserving edit safety and execution continuity.
+
+## When to Use
+
+- Context is growing and signal quality is dropping
+- A phase is complete and should be compressed
+- You are preparing `/handoff` or resuming prior work
+- You need deterministic restoration after compaction
+- You need reusable summary templates for exploration/implementation/debugging
+
+## Core Principle
+
+Prefer **phase-level context hygiene** over emergency cleanup.
+
+```text
+compress > sweep > handoff
+```
+
+- **compress**: shrink closed chapters while preserving decisions
+- **sweep**: remove stale/noisy residue from closed chapters
+- **handoff**: reset in a fresh session when compression is insufficient
+
+## DCP Command Usage
+
+### `/dcp context`
+
+Run at session start and major boundaries to detect pressure early.
+
+### `/dcp compress`
+
+Primary action for completed chapters.
+
+Use when:
+
+- exploration has stable conclusions
+- implementation wave is complete and verified
+- review output has been synthesized
+
+### `/dcp sweep`
+
+Secondary cleanup after chapter closure.
+
+Sweep candidates:
+
+- wrong-target searches
+- superseded logs
+- duplicate tool output
+- dead-end exploration replaced by synthesis
+- large terminal dumps no longer needed
+
+Do not sweep active material needed for immediate edits.
+
+## Session Lifecycle Protocol
+
+### 1) Start Session
+
+1. Load task + essential policy docs only
+2. Run `/dcp context`
+3. Rehydrate prior state only if needed:
+   - `find_sessions({ query })`
+   - `read_session({ session_id, focus })`
+   - `memory-search({ query })` / `memory-read({ file })`
+4. Verify git position before edits
+
+### 2) During Active Work
+
+- Keep active file outputs readable until edit + verification finish
+- Reclassify context at boundaries: active vs closed
+- Compress closed chapters before opening a new major chapter
+- Sweep only after synthesis exists
+
+### 3) Pre-Handoff / Closeout
+
+1. Compress closed phases
+2. Sweep stale/noisy residue
+3. Persist decisions/learnings to memory
+4. Write concise handoff (changed, pending, risks)
+
+### 4) Resume Session
+
+1. Rehydrate only relevant context
+2. Validate assumptions against files + git state
+3. Continue with fresh budget and explicit priorities
+
+## Context Budget Thresholds
+
+| Threshold | Interpretation  | Required Action                    |
+| --------- | --------------- | ---------------------------------- |
+| <50k      | Healthy start   | Keep inputs minimal                |
+| 50k-100k  | Moderate growth | Compress completed phases          |
+| >100k     | High pressure   | Aggressive compress + `/dcp sweep` |
+| >150k     | Near capacity   | Handoff + resume fresh session     |
+
+Guardrails: ~70% consolidate closed exploration, ~85% schedule handoff, ~95% immediate cleanup/restart.
+
+## Phase Boundary Triggers
+
+Compress at these boundaries:
+
+- Research complete -> compress exploration/search output
+- Implementation wave complete -> compress read/edit/test cycle output
+- Review complete -> compress raw reviewer output; keep synthesis
+- Pre-handoff -> compress non-essential context since last checkpoint
+
+Rule: **Closed phases should not remain uncompressed for long.**
+
+## Compaction Decision Tree
+
+Use this before each cleanup action.
+
+```text
+Is context pressure increasing materially?
+├── NO
+│   └── Continue work; reassess at next phase boundary
+└── YES
+    ├── Is there a completed phase with stable conclusions?
+    │   ├── YES -> /dcp compress completed range
+    │   └── NO
+    │       ├── Is growth mostly stale/noisy closed-phase output?
+    │       │   ├── YES -> /dcp sweep
+    │       │   └── NO
+    │       │       ├── Is most remaining context still active/relevant?
+    │       │       │   ├── YES -> Prepare handoff + resume fresh session
+    │       │       │   └── NO -> Reclassify content, then compress/sweep
+    │       └── If uncertain, preserve active content until closure
+```
+
+## Custom Summarization Templates
+
+Use these templates to keep summaries dense and recoverable.
+
+### A) Code Exploration Template
+
+```markdown
+## Exploration Summary: [Component/Module]
+
+### Objective
+
+- [What was investigated]
+
+### Architecture Map
+
+- Entry points: `path/to/entry.ts`
+- Core modules: `A`, `B`, `C`
+- Data flow: [input -> transform -> output]
+- Dependencies/services: [list]
+
+### Verified Findings
+
+- [Finding with evidence]
+- [Finding with evidence]
+- [Finding with evidence]
+
+### Constraints
+
+- [Technical/policy/runtime constraints]
+
+### Decisions
+
+- [Decision] -> [Rationale]
+- [Decision] -> [Rationale]
+
+### Next Step
+
+- [Immediate next action]
+```
+
+### B) Implementation Template
+
+```markdown
+## Implementation Summary: [Feature/Fix]
+
+### Scope
+
+- [What this wave covered]
+
+### Completed
+
+- [x] `path/to/file.ts` -> [change]
+- [x] `path/to/file.test.ts` -> [coverage]
+- [x] [other completed work]
+
+### Verification Evidence
+
+- Typecheck: [command + result]
+- Lint: [command + result]
+- Tests: [command + result]
+
+### Remaining
+
+- [ ] [pending item]
+- [ ] [pending item]
+
+### Key Decisions
+
+- [Decision + reason]
+- [Decision + reason]
+
+### Resume Anchor
+
+- Resume from: `path/to/file.ts` [function/region]
+```
+
+### C) Debugging Template
+
+```markdown
+## Debug Summary: [Issue]
+
+### Symptoms
+
+- Error: [exact error]
+- Trigger: [request/action]
+- Location: `path:line`
+
+### Root Cause
+
+- [causal chain with evidence]
+
+### Fix Applied
+
+- `path/to/file.ts` -> [exact fix]
+- `path/to/test.ts` -> [new/updated coverage]
+
+### Verification
+
+- [test command + result]
+- [manual check + result]
+
+### Next Step
+
+- [if unresolved, next investigation/fix]
+```
+
+## DCP Plugin Integration
+
+This project uses `@tarquinen/opencode-dcp` via `experimental.chat.system.transform`.
+
+### DCP Responsibilities (Always On)
+
+- context budget monitoring + threshold cues
+- `/dcp` command surface (`context`, `compress`, `sweep`, `stats`)
+- prunable-tools guidance + token-aware nudges
+- critical-limit warnings
+
+### Context-Management Responsibilities (This Skill)
+
+- timing policy for compress/sweep/handoff
+- summary quality and template selection
+- post-compaction restoration protocol
+- cross-session rehydration sequence
+
+### Division of Responsibility
+
+- **DCP plugin**: measures/surfaces pressure, exposes cleanup commands
+- **context-management skill**: decides when to apply commands and how to preserve continuity
+
+### Custom Prompt Overrides
+
+Custom DCP prompts are enabled (`experimental.customPrompts: true`).
+
+Override precedence:
+
+1. `.opencode/dcp-prompts/overrides/` (project)
+2. config directory overrides
+3. `~/.config/opencode/dcp-prompts/overrides/` (global)
+
+Key file: `compress-message.md` (structured compression schema). Recommended blocks: Primary Request, Key Technical Concepts, Files/Code, Errors/Fixes, Problem Solving, User Messages, Pending Tasks, Current Work, Next Step.
+
+## Post-Compaction Restoration Protocol (Critical)
+
+After any compaction (server-side or `/dcp compress`), execute all 5 steps before editing.
+
+### Step 1 — Re-read Active Files (max 5)
+
+Re-read files active before compaction.
+
+- prioritize most recent edits first
+- cap at 5 files
+- use targeted reads (`offset`/`limit`) for precision
+
+Example:
+
+```text
+read({ filePath: "src/auth.ts", offset: 30, limit: 80 })
+```
+
+Why: restores exact local code context and satisfies read-before-edit safety requirements.
+
+### Step 2 — Restore Active Skills
+
+Reload any skills active before compaction.
+
+```typescript
+skill({ name: "<active-skill>" });
+```
+
+Why: skill instructions are prompt-injected and may be dropped by compaction.
+
+### Step 3 — Reconcile Todo State
+
+Rebuild exact task status:
+
+- what was `in_progress`
+- what remains `pending`
+- what is `completed`
+
+Why: prevents duplicate work and missed subtasks.
+
+### Step 4 — Verify Git Position
+
+```bash
+git branch --show-current
+git status --short
+```
+
+Why: confirms branch correctness and re-anchors uncommitted file state.
+
+### Step 5 — Scan Memory / Session Artifacts
+
+If compaction was heavy, recover nuance using:
+
+- `memory-search({ query, limit: 3 })`
+- `memory-read({ file })`
+- `find_sessions({ query, limit })`
+- `read_session({ session_id, focus })`
+
+Why: restores rationale/constraints often missing from short summaries.
+
+### Restoration Exit Criteria
+
+Do not resume edits until active targets are re-read, required skills are reloaded, todo state is reconciled, git position is confirmed, and critical rationale is recovered when needed.
+
+## 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>`)
+4. Git evidence (`git diff`, `git log`, test output)
+
+Carry forward decisions, constraints, and next actions — not transcript bulk.
+
+## Anti-Patterns
+
+| Anti-Pattern                          | Why It Hurts                           | Correct Pattern                                |
+| ------------------------------------- | -------------------------------------- | ---------------------------------------------- |
+| Compressing active edit context       | Loses exact data needed for safe edits | Keep active outputs until edit+verify complete |
+| Sweeping still-live content           | Causes rework and precision loss       | Sweep only stale/noisy closed-phase outputs    |
+| Leaving closed phases uncompressed    | Context bloat degrades later turns     | Compress at each phase boundary                |
+| Handoff without memory persistence    | Next session loses rationale           | Persist decisions before handoff               |
+| Skipping restoration after compaction | Edit failures, skill drift, task drift | Run 5-step restoration before resuming         |
+
+## Verification
+
+Before claiming context cleanup complete, verify:
+
+- active edit targets are still readable
+- closed chapters are compressed or intentionally retained
+- no critical decision exists only in transient output
+- restoration protocol completed after compaction
+- handoff includes next actions and blockers
+
+## Quick Playbook
+
+```text
+1) /dcp context
+2) classify context: active vs closed
+3) /dcp compress on closed chapters
+4) /dcp sweep stale/noisy closed outputs
+5) if compaction happened: run 5-step restoration
+6) persist key decisions to memory
+7) handoff/resume with focused rehydration
+```
+
+## See Also
+
+- `memory-system`