@ultrakit/ultrakit 0.0.0 → 0.0.2

package/dist/template/{.opencode → opencode}/memory/README.md

@@ -15,6 +15,11 @@ memory/
 │   ├── user.md        # User preferences, identity
 │   ├── tech-stack.md  # Framework, dependencies, constraints
 │   └── gotchas.md     # Footguns, edge cases, warnings
+├── compiled/          # Curated markdown fallback when SQLite/FTS is unavailable
+│   ├── architecture.md
+│   ├── decisions.md
+│   ├── gotchas.md
+│   └── workflows.md
 ├── knowledge/         # PARA-organized reference (curated)
 │   ├── projects/      # Active work with deadlines
 │   ├── areas/         # Ongoing responsibilities
@@ -30,9 +35,10 @@ memory/
 
 | Layer               | Location      | Purpose                 | Access                             |
 | ------------------- | ------------- | ----------------------- | ---------------------------------- |
-| **Knowledge Graph** | SQLite + FTS5 | Searchable observations | `memory-search()`, `observation()` |
-| **Daily Notes**     | `daily/`      | Chronological narrative | Manual review                      |
-| **Tacit Knowledge** | `project/`    | Always-present context  | Auto-injected                      |
+| **Knowledge Graph** | SQLite + FTS5 | Searchable observations              | `memory-search()`, `observation()` |
+| **Compiled Memory** | `compiled/`   | Durable curated markdown fallback    | Read files directly                |
+| **Daily Notes**     | `daily/`      | Chronological narrative              | Manual review                      |
+| **Tacit Knowledge** | `project/`    | Always-present context               | Auto-injected                      |
 
 ## SQLite Memory Tools
 
@@ -63,9 +69,10 @@ memory/
 
 ### Session Start
 
-1. `memory-search()` - Find relevant context
-2. Read `project/` files (auto-injected)
-3. Check `daily/` for recent sessions if needed
+1. `memory-search()` - Find relevant context when SQLite/FTS is available
+2. If memory tooling fails, read `compiled/` files directly as the durable fallback
+3. Read `project/` files (auto-injected)
+4. Check `daily/` for recent sessions if needed
 
 ### During Work
 
@@ -83,6 +90,7 @@ memory/
 **Three-layer memory beats single-layer:**
 
 - SQLite for searchability (Knowledge Graph)
+- Compiled markdown for graceful fallback when SQLite/FTS is unavailable
 - Daily notes for context (Chronological)
 - Project files for presence (Tacit Knowledge)
 

package/dist/template/{.opencode/memory/project → opencode/memory/_templates}/gotchas.md

@@ -1,6 +1,6 @@
 ---
 purpose: Footguns, edge cases, and warnings discovered during development
-updated: 2026-02-12
+updated: 2026-05-08
 ---
 
 # Gotchas
@@ -65,3 +65,7 @@ The edit tool (`str_replace`) is the #1 source of failures in LLM coding. Models
 
 - Only leader agents (build, plan) should modify beads state
 - Subagents read with `br show <id>`, report findings back
+
+---
+
+_Update this file when you discover new footguns, edge cases, or surprising behaviors._

package/dist/template/opencode/memory/compiled/architecture.md

@@ -0,0 +1,44 @@
+---
+purpose: Curated architecture summary that works without SQLite memory
+updated: 2026-05-09
+---
+
+# Compiled Architecture
+
+## Project Structure
+
+- `src/` — CLI source code (entry: `src/index.ts`)
+- `src/commands/` — CLI command handlers (init, upgrade, patch, agent, command, config, doctor, status)
+- `src/utils/` — Shared utilities (manifest, patch, schemas, license)
+- `src/tui/` — Interactive dashboard (ink-based terminal UI)
+- `template/opencode/` — Package template source copied into user `.opencode/`
+- `dist/` — Built output + package template bundle
+
+## Key Design Decisions
+
+- **ESM modules** — all source uses `import`/`export`, CJS `require()` is forbidden
+- **zod validation** — all CLI options validated at runtime with zod schemas
+- **Template manifest** — `init` and `upgrade` track installed files via `.template-manifest.json` for drift detection
+- **Preserve user data** — `PRESERVE_USER_DIRS` (memory/project, context) and `PRESERVE_USER_FILES` (.env, opencode.json) protect user content during reinit/upgrade
+
+## Module Boundaries
+
+- `init.ts` owns project initialization and force-reinit
+- `upgrade.ts` owns incremental upgrades with file-level preservation
+- `patch.ts` owns user modification tracking (diff-based)
+- `manifest.ts` owns file hash generation and modification status checks
+- `schemas.ts` owns zod schemas for all CLI options
+
+## Data Flow
+
+```
+User → uk init → manifest.ts (hash all template files) → .template-manifest.json
+User → uk upgrade → manifest.ts (compare hashes) → patch.ts (preserve user mods) → updated files
+User → uk doctor → validation/docs-drift.ts → report drift issues
+```
+
+## How to Maintain
+
+- Keep entries concise and source-backed
+- Prefer links to code paths over copied code
+- Refresh after major structural changes or after `memory-admin compile` succeeds

package/dist/template/opencode/memory/compiled/decisions.md

@@ -0,0 +1,36 @@
+---
+purpose: Curated durable decisions independent of SQLite observation storage
+updated: 2026-05-09
+---
+
+# Compiled Decisions
+
+- **Decision:** Use ESM modules throughout (no CJS `require()`)
+  - **Context:** Node.js >= 20.19.0 required; ESM is the standard
+  - **Tradeoff:** CJS dynamic `require("node:fs")` breaks in ESM — must use top-level imports
+  - **Date:** 2026-05-09
+
+- **Decision:** Memory plugin uses graceful degradation for SQLite unavailability
+  - **Context:** `node:sqlite` may not be available (Node < 22.5 or built without SQLite)
+  - **Tradeoff:** Tools return "unavailable" messages instead of crashing; compiled/ markdown files serve as fallback
+  - **Date:** 2026-05-09
+
+- **Decision:** Pin plugin versions in `opencode.json` (no `@latest`)
+  - **Context:** Unpinned `@latest` refs cause non-reproducible installs
+  - **Tradeoff:** Manual version bumps required when updating plugins
+  - **Date:** 2026-05-09
+
+- **Decision:** Align `.version` with `package.json` version
+  - **Context:** Single version scheme avoids drift between template version and package version
+  - **Tradeoff:** Template version must be updated when package version changes
+  - **Date:** 2026-05-09
+
+- **Decision:** EXA_API_KEY is OPTIONAL, not REQUIRED
+  - **Context:** Exa is not part of the default or recommended runtime path per research-tool-routing skill
+  - **Tradeoff:** Users who want Exa must explicitly configure it
+  - **Date:** 2026-05-09
+
+- **Decision:** `/explore` command renamed to `/ideate` to avoid collision with `@explore` agent
+  - **Context:** The `/explore` slash command and `@explore` subagent had a naming collision
+  - **Tradeoff:** Users must use `/ideate` for ideation workflow; `/explore` no longer exists as a command
+  - **Date:** 2026-05-09

package/dist/template/opencode/memory/compiled/gotchas.md

@@ -0,0 +1,36 @@
+---
+purpose: Curated high-signal footguns independent of SQLite memory tools
+updated: 2026-05-09
+---
+
+# Compiled Gotchas
+
+- **Gotcha:** `require("node:fs")` in ESM throws `MODULE_NOT_FOUND`
+  - **Symptom:** Runtime crash in `patch.ts` when calling `rmSync` via `require()`
+  - **Avoidance:** Use top-level `import { rmSync } from "node:fs"` instead of dynamic `require()`
+  - **Source:** `ultrakit/src/utils/patch.ts`
+
+- **Gotcha:** `require("node:sqlite")` throws when SQLite is unavailable
+  - **Symptom:** All memory tools crash with `MODULE_NOT_FOUND`; no fallback message
+  - **Avoidance:** Use `isSQLiteAvailable()` guard before DB operations; return helpful "unavailable" message
+  - **Source:** `ultrakit/template/opencode/plugin/lib/db/schema.ts`
+
+- **Gotcha:** `init --force` overwrites agent/command/skill/tool dirs
+  - **Symptom:** User customizations lost on reinit
+  - **Avoidance:** `PRESERVE_USER_FILES` includes `opencode.json`; `PRESERVE_USER_DIRS` protects `memory/project` and `context`
+  - **Source:** `ultrakit/src/commands/init.ts`
+
+- **Gotcha:** Manifest generated before user files restored
+  - **Symptom:** Preserved files aren't in `.template-manifest.json`, so upgrade treats them as "unknown"
+  - **Avoidance:** This is actually correct behavior (preserved files are user-owned, not template-managed), but the ordering is fragile — don't reorder `generateManifest()` before `restoreUserFiles()`
+  - **Source:** `ultrakit/src/utils/manifest.ts`
+
+- **Gotcha:** Duplicate `agent` command registration in `index.ts`
+  - **Symptom:** Second registration overwrites first; `create` and `remove` actions lost if first registration wins
+  - **Avoidance:** Only register each command once
+  - **Source:** `ultrakit/src/index.ts`
+
+- **Gotcha:** `opencode.json` has no `limit` field for default model
+  - **Symptom:** DCP can't determine context window size for `opencode/big-pickle`
+  - **Avoidance:** Add `limit: { context: 200000, output: 16384 }` to the model definition
+  - **Source:** `ultrakit/template/opencode/opencode.json`

package/dist/template/opencode/memory/compiled/workflows.md

@@ -0,0 +1,35 @@
+---
+purpose: Curated workflow notes independent of SQLite memory tools
+updated: 2026-05-09
+---
+
+# Compiled Workflows
+
+## Baseline Loop
+
+1. Ground in project files and bead state.
+2. Make the smallest scoped change that satisfies the task.
+3. Run fresh verification before claiming success.
+4. Capture durable learnings in compiled memory or observations when available.
+
+## SQLite Degradation Workflow
+
+When `node:sqlite` is unavailable (Node < 22.5 or built without SQLite):
+
+1. Memory tools (`observation`, `memory-search`, etc.) return "unavailable" messages with guidance
+2. LTM injection is skipped silently (one-time warning logged)
+3. Context management (`messages.transform`) still works — it uses pure token estimation, not SQLite
+4. Compiled markdown files (`memory/compiled/*.md`) serve as persistent fallback context
+5. `opencode.json` `instructions[]` still injects `memory/project/*.md` and `context/git-context.md`
+
+## Init → Upgrade Cycle
+
+1. `uk init` — copies template, generates manifest, restores preserved user files
+2. `uk upgrade` — compares manifest hashes, preserves user-modified files, updates unmodified files
+3. Manifest ordering: `generateManifest()` runs BEFORE `restoreUserFiles()` — preserved files are not in the manifest
+
+## Validation Workflow
+
+1. `uk doctor` — runs drift checks from `validation/docs-drift.ts`
+2. Checks: slash commands, CLI docs, plugin README, stale references, template package, gitignore, agent/command counts, research tool routing
+3. Future checks needed: instruction path validity, agent key sync, @latest plugin refs, dcp model limits, .env required keys

package/dist/template/opencode/memory/project/gotchas.md

@@ -0,0 +1,71 @@
+---
+purpose: Footguns, edge cases, and warnings discovered during development
+updated: 2026-05-08
+---
+
+# Gotchas
+
+Track unexpected behaviors, edge cases, and warnings here. Update when you hit something surprising.
+
+## LLM Coding (Harness Problem)
+
+The edit tool (`str_replace`) is the #1 source of failures in LLM coding. Models fail at reproducing content with exact whitespace/encoding, not at understanding tasks.
+
+### Edit Tool Failures
+
+- **Whitespace mismatch** — Tabs vs spaces, trailing spaces, line endings (CRLF vs LF)
+- **Content changed** — File modified since last read
+- **Multiple matches** — Same string appears twice, edit fails
+- **Stale context** — Editing from memory instead of fresh read
+
+### Mitigation Strategies
+
+1. **Always read fresh** before editing — no assumptions
+2. **Use LSP tools** to locate symbols precisely (goToDefinition, findReferences)
+3. **Include unique context** — 2-3 lines before/after for uniqueness
+4. **Prefer smaller files** — <400 lines reduces edit complexity
+5. **Verify after edit** — read back to confirm success
+
+### File Size Guidance
+
+| Size          | Strategy                                   |
+| ------------- | ------------------------------------------ |
+| < 100 lines   | Full rewrite often easier than str_replace |
+| 100-400 lines | Structured edit with good context          |
+| > 400 lines   | Strongly prefer structured edits           |
+
+**Use the `structured-edit` skill for reliable edits.**
+
+### Context Hygiene
+
+- Compress completed work phases before moving on
+- Use `/dcp sweep` after a closed phase to remove stale noise
+- Token budget: <50k start → 50-100k mid → >150k restart session
+- Subagent outputs can leak tokens — compress completed phases and sweep stale subagent noise
+
+## OpenCode Config
+
+- **`compaction` key invalid**: Not in official schema at opencode.ai/config.json. Remove if present.
+- **`experimental` key invalid**: Not in schema. Remove if present.
+- **`tools` key invalid**: Not in schema. Remove if present.
+- **`formatter` valid but undocumented**: Works but missing from schema (schema incomplete).
+
+## Memory System
+
+- Subagents (explore, scout, review) should NOT write to memory - only leader agents
+- Use `observation: false` and `memory-update: false` in agent configs to enforce
+
+## Build System
+
+- `dist/` is generated - never edit directly
+- Build copies `.opencode/` to `dist/template/` via rsync
+- Run `npm run build` to regenerate
+
+## Beads
+
+- Only leader agents (build, plan) should modify beads state
+- Subagents read with `br show <id>`, report findings back
+
+---
+
+_Update this file when you discover new footguns, edge cases, or surprising behaviors._

package/dist/template/opencode/memory/project/project.md

@@ -0,0 +1,46 @@
+---
+purpose: Project vision, goals, and success criteria (loaded into all AI contexts)
+updated: 2026-05-09
+---
+
+# Project Vision
+
+This starter file is intentionally generic. Update it after initialization so agents understand the actual project direction.
+
+## The Goal
+
+Describe the project in one or two sentences: what it does, who it serves, and why it exists.
+
+## Success Criteria
+
+1. Define the first observable outcome that means the project is working
+2. Define the second observable outcome that matters to users
+3. Define the quality or reliability bar for shipping changes
+4. Define the documentation, deployment, or maintainability expectation
+
+## Target Users
+
+- **Primary:** Describe the main user or customer
+- **Secondary:** Describe other stakeholders, maintainers, or contributors
+
+## Core Principles
+
+1. State the most important product or engineering principle
+2. State the data, safety, or preservation principle agents must respect
+3. State the simplicity, performance, accessibility, or maintainability principle
+
+## Current Phase
+
+- **Status:** Replace with discovery, planning, implementation, stabilization, or maintenance
+- **Milestone:** Replace with the current milestone
+- **Next Milestone:** Replace with the next milestone
+
+## Key Links
+
+- **Repository:** Replace with repository URL
+- **Docs:** Replace with docs, roadmap, or design links
+
+---
+
+_Update this file when project direction or phase changes._
+_AI uses this to maintain context across sessions and make decisions aligned with project goals._

package/dist/template/opencode/memory/project/roadmap.md

@@ -0,0 +1,88 @@
+---
+purpose: Project roadmap with phases, milestones, and bead organization
+updated: 2026-05-09
+---
+
+# Roadmap
+
+## Overview
+
+| Phase                | Goal                                               | Status      | Beads |
+| -------------------- | -------------------------------------------------- | ----------- | ----- |
+| Phase 1: Foundation  | Understand codebase, verify toolchain, fill config | In Progress | -     |
+| Phase 2: Enhancement | Identify and implement CLI improvements            | Not Started | -     |
+| Phase 3: Polish      | Documentation, testing, release prep               | Not Started | -     |
+
+## Phase 1: Foundation
+
+**Goal:** Establish solid understanding of this project and verify the development toolchain.
+
+**Success Criteria:**
+
+- [x] AGENTS.md created at project root with validated commands
+- [x] tech-stack.md filled with detected toolchain
+- [ ] user.md filled with developer persona and preferences
+- [ ] Project verification commands pass (typecheck, lint, tests, build where applicable)
+- [ ] Source code structure mapped
+- [ ] Key user and maintenance flows understood
+
+**Out of Scope:**
+
+- Code changes or feature additions (Phase 2)
+- Publishing or release work (Phase 3)
+
+---
+
+## Phase 2: Enhancement
+
+**Goal:** Identify and implement improvements based on discovery findings.
+
+**Success Criteria:**
+
+- [ ] Concrete improvement list documented from codebase review
+- [ ] At least one command flow improved or extended
+- [ ] Project configuration reviewed for correctness
+- [ ] Tests added for any new behavior
+
+**Dependencies:**
+
+- Requires Phase 1 completion
+
+---
+
+## Phase 3: Polish
+
+**Goal:** Prepare for release — documentation, testing completeness, and final validation.
+
+**Success Criteria:**
+
+- [ ] README and AGENTS.md documentation up to date
+- [ ] Full governance validation passes (`npm run validate:governance`)
+- [ ] Build pipeline verified end-to-end
+- [ ] Release checklist completed
+
+**Dependencies:**
+
+- Requires Phase 2 completion
+
+---
+
+## Legend
+
+**Status:**
+
+- `Not Started` - No work begun
+- `In Progress` - Active development
+- `Complete` - All beads closed
+
+**Type:**
+
+- `task` - Tactical, single-session work
+- `feature` - New capability, multi-session
+- `epic` - Cross-domain, significant scope
+- `bug` - Fix for broken behavior
+
+---
+
+_Update this file when phases complete or roadmap changes._
+_Use `/plan` command to create detailed plans for active phases._

package/dist/template/opencode/memory/project/state.md

@@ -0,0 +1,69 @@
+---
+purpose: Current project state, active decisions, blockers, and position tracking
+updated: 2026-05-09
+---
+
+# State
+
+## Current Position
+
+**Active Bead:** None (initial setup)
+**Status:** In Progress
+**Started:** 2026-05-09
+**Phase:** Phase 1: Foundation (from roadmap.md)
+
+## Recent Completed Work
+
+| Step            | Description                                                              | Completed  |
+| --------------- | ------------------------------------------------------------------------ | ---------- |
+| `/init`         | Created AGENTS.md (63 lines), filled tech-stack.md                       | 2026-05-09 |
+| `/init-context` | Filled project.md, created roadmap.md + state.md                         | 2026-05-09 |
+| Brainstorming   | Established: UltraKit dev, full-stack persona, CLI-only, Discovery phase | 2026-05-09 |
+
+## Active Decisions
+
+| Date       | Decision                                               | Rationale                                                          | Impact                  |
+| ---------- | ------------------------------------------------------ | ------------------------------------------------------------------ | ----------------------- |
+| 2026-05-09 | Project is UltraKit development, not a new application | opencodekit-template/ is the source; Project2 is the dev workspace | All context files       |
+| 2026-05-09 | CLI-only tech stack (no web, no DB)                    | uk is a pure Node.js CLI tool; matching actual codebase            | tech-stack.md, pipeline |
+| 2026-05-09 | Discovery phase first                                  | Need to understand codebase before making changes                  | Roadmap Phase 1         |
+
+## Blockers
+
+None.
+
+## Open Questions
+
+| Question                           | Context                    | Blocking | Priority |
+| ---------------------------------- | -------------------------- | -------- | -------- |
+| What specific CLI improvements?    | Phase 2 planning           | No       | Medium   |
+| Should template bundle be updated? | .opencode/ template review | No       | Low      |
+
+## Context Notes
+
+### Technical
+
+- Source lives in `opencodekit-template/src/` (commands/, utils/, validation/, tui/)
+- Build: tsdown bundles + copies .opencode/ → dist/template/
+- PRESERVE_USER_DIRS: memory/project/ and context/ survive reinit
+- All verification commands run from opencodekit-template/ directory
+
+### Process
+
+- Use `/plan` to create detailed implementation plans per phase
+- Use `/review-codebase` for deep codebase analysis (next step)
+- Beads task tracking available via `.beads/`
+
+## Next Actions
+
+1. [ ] `/init-user` — Fill user.md with full-stack builder persona
+2. [ ] `/review-codebase` — Deep analysis of opencodekit-template/src/ structure and patterns
+3. [ ] Verify all init/upgrade/patch/agent/command flows work end-to-end
+4. [ ] Document any gaps or improvement opportunities found
+
+## Session Handoff
+
+**Last Session:** 2026-05-09
+**Next Session Priority:** Complete `/init-user`, then run `/review-codebase` for deep analysis
+**Known Issues:** None
+**Context Links:** AGENTS.md, .opencode/memory/project/tech-stack.md, .opencode/memory/project/project.md

package/dist/template/opencode/memory/project/tech-stack.md

@@ -0,0 +1,68 @@
+---
+purpose: Tech stack, constraints, and integrations for AI context injection
+updated: 2026-05-09
+---
+
+# Tech Stack
+
+This file is automatically injected into ALL AI prompts via `opencode.json` instructions[].
+
+## Framework & Language
+
+- **Framework:** None (pure Node.js CLI)
+- **Language:** TypeScript (strict mode, ESM)
+- **Runtime:** Node.js >= 20.19.0 (running v25.9.0)
+
+## CLI & UX
+
+- **CLI Framework:** cac (minimal, composable)
+- **Prompts/UI:** @clack/prompts (interactive, spinners, TUI dashboard)
+- **Colors:** picocolors
+
+## Build & Dev
+
+- **Bundler:** tsdown (TypeScript → ESM, bundles .opencode/ template)
+- **Dev Runner:** tsx (fast TS execution)
+- **Package Manager:** npm 11.13.0
+
+## Testing
+
+- **Unit Tests:** Vitest (colocated in src/\*_/_.test.ts, 9 tests, 2 files)
+- **E2E Tests:** None
+- **Coverage Target:** Not set
+
+## Quality
+
+- **Linting:** oxlint (zero-config, 92 files, 0 warnings)
+- **Formatting:** oxfmt
+- **Type Checking:** tsgo --noEmit
+- **Validation:** zod (CLI options, config shapes)
+
+## Key Constraints
+
+- Node.js >= 20.19.0 (engines.node)
+- CLI-only — no web UI, no database, no API server
+- Template bundle (.opencode/) shipped inside dist/
+- `PRESERVE_USER_DIRS` protects memory/project/ and context/ during reinit
+
+## Active Integrations
+
+- OpenCode agent runtime (reads .opencode/ config)
+- Beads task tracking (beads_rust, optional)
+- NPM registry (published as @ultrakit/ultrakit)
+
+## Verification Commands
+
+**Always run before claiming complete (from the generated project or package root):**
+
+```bash
+npm run typecheck    # tsgo --noEmit
+npm run lint         # oxlint .
+npm test             # vitest run
+npm run build        # tsdown + template copy
+```
+
+---
+
+_Update this file when tech stack or constraints change._
+_AI will capture architecture, conventions, and gotchas via the `observation` tool as it works._

package/dist/template/opencode/memory/project/user.md

@@ -0,0 +1,41 @@
+---
+purpose: User identity, preferences, communication style
+updated: 2026-05-09
+---
+
+# User Profile
+
+This starter file is intentionally generic. Update it after initialization so agents can adapt to the real user or team.
+
+## Identity
+
+- **Name:** Replace with the primary user or team name
+- **Role:** Replace with the user's role and responsibility for this project
+- **Git:** Replace with repository or author details if useful
+
+## Communication Preferences
+
+- **Style:** Describe preferred level of detail and explanation
+- **Tone:** Describe preferred collaboration style
+- **Format:** Describe preferred response structure, citations, and examples
+
+## Workflow Preferences
+
+- **Git commits:** Describe whether agents should commit automatically or ask first
+- **Testing:** Describe expected verification before completion
+- **Exploration:** Describe how much codebase reading is expected before edits
+- **Incremental:** Describe preference for small changes vs. larger batches
+
+## Technical Preferences
+
+- **Primary stack:** Replace with project language/framework preferences
+- **CLI/tools:** Replace with preferred command-line and developer tools
+- **Validation:** Replace with preferred validation or schema tools
+- **Testing:** Replace with preferred test framework and coverage expectations
+- **Linting/formatting:** Replace with preferred quality tools
+
+## Things to Remember
+
+- Add project-specific constraints here
+- Add user-specific style or process preferences here
+- Add any recurring gotchas agents should preserve across sessions