@ultrakit/ultrakit 0.0.0

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

@@ -0,0 +1,93 @@
+---
+purpose: Project roadmap with phases, milestones, and bead organization
+updated: 2024-12-21
+---
+
+# Roadmap
+
+## Overview
+
+<!-- High-level project breakdown -->
+
+| Phase     | Goal                | Status        | Beads |
+| --------- | ------------------- | ------------- | ----- |
+| [Phase 1] | [One-sentence goal] | [Not Started] | [#]   |
+| [Phase 2] | [One-sentence goal] | [Not Started] | [#]   |
+| [Phase 3] | [One-sentence goal] | [Not Started] | [#]   |
+
+## Phase 1: [Name]
+
+**Goal:** [Outcome-shaped description]
+
+**Success Criteria:**
+
+- [ ] [Criterion 1]
+- [ ] [Criterion 2]
+- [ ] [Criterion 3]
+
+**Beads:**
+| ID | Title | Type | Status | Depends On |
+|----|-------|------|--------|------------|
+| br-xxx | [Title] | task | open | - |
+| br-xxx | [Title] | task | open | br-xxx |
+
+**Out of Scope:**
+
+- [What's explicitly deferred to later phases]
+
+---
+
+## Phase 2: [Name]
+
+**Goal:** [Outcome-shaped description]
+
+**Success Criteria:**
+
+- [ ] [Criterion 1]
+- [ ] [Criterion 2]
+
+**Beads:**
+| ID | Title | Type | Status | Depends On |
+|----|-------|------|--------|------------|
+| br-xxx | [Title] | feature | open | Phase 1 |
+
+**Dependencies:**
+
+- Requires Phase 1 completion
+
+---
+
+## Phase 3: [Name]
+
+**Goal:** [Outcome-shaped description]
+
+**Success Criteria:**
+
+- [ ] [Criterion 1]
+
+**Beads:**
+| ID | Title | Type | Status | Depends On |
+|----|-------|------|--------|------------|
+| br-xxx | [Title] | epic | open | Phase 2 |
+
+---
+
+## 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/_templates/state.md

@@ -0,0 +1,89 @@
+---
+purpose: Current project state, active decisions, blockers, and position tracking
+updated: 2024-12-21
+---
+
+# State
+
+## Current Position
+
+<!-- Where are we right now? What just happened? -->
+
+**Active Bead:** br-xxx - [Title]
+**Status:** [In Progress / Blocked / Review]
+**Started:** [Date]
+**Phase:** [Phase name from roadmap.md]
+
+## Recent Completed Work
+
+<!-- Last 3-5 completed beads -->
+
+| Bead   | Title   | Completed | Summary            |
+| ------ | ------- | --------- | ------------------ |
+| br-xxx | [Title] | [Date]    | [One-line summary] |
+| br-xxx | [Title] | [Date]    | [One-line summary] |
+
+## Active Decisions
+
+<!-- Decisions made that affect current and future work -->
+
+| Date   | Decision           | Rationale | Impact            |
+| ------ | ------------------ | --------- | ----------------- |
+| [Date] | [What was decided] | [Why]     | [What it affects] |
+
+## Blockers
+
+<!-- What's preventing progress? -->
+
+| Bead   | Blocker                  | Since  | Owner               |
+| ------ | ------------------------ | ------ | ------------------- |
+| br-xxx | [Description of blocker] | [Date] | [Who's responsible] |
+
+## Open Questions
+
+<!-- Questions that need answers before proceeding -->
+
+| Question   | Context            | Blocking | Priority       |
+| ---------- | ------------------ | -------- | -------------- |
+| [Question] | [Where it came up] | [Yes/No] | [High/Med/Low] |
+
+## Context Notes
+
+<!-- Important context that doesn't fit elsewhere -->
+
+### Technical
+
+- [Technical decision or constraint]
+- [Pattern or convention established]
+
+### Product
+
+- [Product decision or direction]
+- [User feedback or requirement]
+
+### Process
+
+- [Workflow change or improvement]
+- [Team agreement or process]
+
+## Next Actions
+
+<!-- Immediate next steps -->
+
+1. [ ] [Action item with owner if applicable]
+2. [ ] [Action item]
+3. [ ] [Action item]
+
+## Session Handoff
+
+<!-- For multi-session work, what's the state for the next session? -->
+
+**Last Session:** [Date]
+**Next Session Priority:** [What's most important to do next]
+**Known Issues:** [Any issues to be aware of]
+**Context Links:** [Relevant files, PRs, docs]
+
+---
+
+_Update this file at the end of each significant session or when state changes._
+_This file is the "you are here" marker for the project._

package/dist/template/.opencode/memory/_templates/tasks.md

@@ -0,0 +1,198 @@
+# Implementation Tasks
+
+**Bead:** [bead-id]
+**Spec:** [link to spec]
+**Date:** [YYYY-MM-DD]
+
+---
+
+## Task Metadata
+
+Each task can have these optional fields in YAML frontmatter:
+
+```yaml
+---
+id: "1.1" # Task identifier
+depends_on: [] # Task IDs that must complete first
+parallel: true # Can run concurrently with other parallel tasks
+conflicts_with: [] # Task IDs that modify same files (cannot parallelize)
+files: [] # Files this task will modify
+estimated_minutes: 30 # Time estimate for planning
+---
+```
+
+---
+
+## 1. Setup
+
+### 1.1 [Prerequisite task]
+
+```yaml
+depends_on: []
+parallel: false
+files: ["package.json", "tsconfig.json"]
+```
+
+- [ ] [Task description]
+
+### 1.2 [Environment or config task]
+
+```yaml
+depends_on: ["1.1"]
+parallel: false
+files: [".env.example"]
+```
+
+- [ ] [Task description]
+
+---
+
+## 2. Core Implementation
+
+### 2.1 [Primary implementation task]
+
+```yaml
+depends_on: ["1.1", "1.2"]
+parallel: true
+conflicts_with: []
+files: ["src/feature/index.ts"]
+```
+
+- [ ] [Task description]
+
+### 2.2 [Secondary implementation task]
+
+```yaml
+depends_on: ["1.1", "1.2"]
+parallel: true
+conflicts_with: []
+files: ["src/feature/utils.ts"]
+```
+
+- [ ] [Task description]
+
+### 2.3 [Integration task]
+
+```yaml
+depends_on: ["2.1", "2.2"]
+parallel: false
+conflicts_with: []
+files: ["src/feature/index.ts", "src/feature/utils.ts"]
+```
+
+- [ ] [Task description]
+
+---
+
+## 3. Testing
+
+### 3.1 [Unit test task]
+
+```yaml
+depends_on: ["2.1"]
+parallel: true
+files: ["tests/feature.test.ts"]
+```
+
+- [ ] [Task description]
+
+### 3.2 [Integration test task]
+
+```yaml
+depends_on: ["2.3"]
+parallel: true
+files: ["tests/integration/feature.test.ts"]
+```
+
+- [ ] [Task description]
+
+### 3.3 [Edge case verification]
+
+```yaml
+depends_on: ["3.1", "3.2"]
+parallel: false
+files: []
+```
+
+- [ ] [Task description]
+
+---
+
+## 4. Documentation
+
+### 4.1 [Code comments / JSDoc]
+
+```yaml
+depends_on: ["2.3"]
+parallel: true
+files: ["src/feature/*.ts"]
+```
+
+- [ ] [Task description]
+
+### 4.2 [README updates]
+
+```yaml
+depends_on: ["2.3"]
+parallel: true
+files: ["README.md"]
+```
+
+- [ ] [Task description]
+
+---
+
+## 5. Verification
+
+### 5.1 All tests pass
+
+```yaml
+depends_on: ["3.1", "3.2", "3.3"]
+parallel: false
+```
+
+- [ ] `[test command]`
+
+### 5.2 Lint clean
+
+```yaml
+depends_on: ["2.3", "4.1"]
+parallel: true
+```
+
+- [ ] `[lint command]`
+
+### 5.3 Build succeeds
+
+```yaml
+depends_on: ["5.1", "5.2"]
+parallel: false
+```
+
+- [ ] `[build command]`
+
+---
+
+## Dependency Graph
+
+Visualize task flow (auto-generated from above):
+
+```
+1.1 ──┬──> 2.1 ──┬──> 2.3 ──┬──> 3.2 ──┬──> 5.1 ──> 5.3
+     │         │         │         │
+1.2 ──┘   2.2 ──┘    3.1 ──┘    5.2 ──┘
+                      │
+                 4.1 ──┘
+                 4.2
+```
+
+**Legend:**
+
+- `──>` = depends_on (sequential)
+- Tasks at same level with `parallel: true` = can run concurrently
+
+---
+
+## Notes
+
+<!-- Implementation notes, gotchas, or decisions made during task creation -->

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

@@ -0,0 +1,85 @@
+---
+purpose: Tech stack, constraints, and integrations for AI context injection
+updated: 2026-02-01
+---
+
+# Tech Stack
+
+This file is automatically injected into ALL AI prompts via `opencode.json` instructions[].
+
+## Framework & Language
+
+- **Framework:** [e.g., Next.js 15, React 19]
+- **Language:** TypeScript (strict mode)
+- **Runtime:** [e.g., Node.js 22, Bun 1.x]
+
+## Styling & UI
+
+- **CSS:** [e.g., Tailwind CSS v4]
+- **Components:** [e.g., shadcn/ui, Radix Primitives]
+- **Design System:** [e.g., Custom tokens in tailwind.config.ts]
+
+## Data & State
+
+- **Database:** [e.g., PostgreSQL via Supabase]
+- **ORM:** [e.g., Drizzle, Prisma]
+- **State Management:** [e.g., Zustand, React Query]
+- **API Style:** [e.g., REST, tRPC, GraphQL]
+
+## Testing
+
+- **Unit Tests:** [e.g., Vitest]
+- **E2E Tests:** [e.g., Playwright]
+- **Coverage Target:** [e.g., 80%]
+
+## Key Constraints
+
+- [Constraint 1: e.g., Must work offline]
+- [Constraint 2: e.g., WCAG 2.1 AA compliance required]
+- [Constraint 3: e.g., Bundle size < 500KB]
+
+## Active Integrations
+
+- [Service 1: e.g., Stripe for payments]
+- [Service 2: e.g., Resend for email]
+- [Service 3: e.g., Sentry for error tracking]
+
+## Context Budget Guidelines
+
+**Quality Degradation Rule:** Target ~50% context per plan execution for consistent quality.
+
+| Task Complexity | Max Tasks/Plan | Typical Context Usage |
+| --------------- | -------------- | --------------------- |
+| Simple (CRUD)   | 3              | ~30-45%               |
+| Complex (auth)  | 2              | ~40-50%               |
+| Very complex    | 1-2            | ~30-50%               |
+
+**Split Signals:**
+
+- More than 3 tasks → Create child plans
+- Multiple subsystems → Separate plans
+- > 5 file modifications per task → Split
+- Discovery + implementation → Split
+
+## Verification Commands
+
+**Always run before claiming complete:**
+
+```bash
+# Type checking
+[typecheck command, e.g., npm run typecheck]
+
+# Linting
+[lint command, e.g., npm run lint]
+
+# Testing
+[test command, e.g., npm test]
+
+# Building
+[build command, e.g., npm run build]
+```
+
+---
+
+_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/_templates/user.md

@@ -0,0 +1,26 @@
+---
+purpose: User identity, preferences, communication style
+updated: 2024-12-21
+---
+
+# User Profile
+
+## Identity
+
+<!-- Name, role, git contributor identity -->
+
+## Communication Preferences
+
+<!-- Concise vs detailed, tone preferences -->
+
+## Workflow Preferences
+
+<!-- Preferred tools, testing habits, review style -->
+
+## Technical Preferences
+
+<!-- Languages, frameworks, patterns they favor -->
+
+## Things to Remember
+
+<!-- Personal quirks, pet peeves, preferences learned -->

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

@@ -0,0 +1,67 @@
+---
+purpose: Footguns, edge cases, and warnings discovered during development
+updated: 2026-02-12
+---
+
+# 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

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

@@ -0,0 +1,92 @@
+---
+purpose: Project vision, success criteria, and core principles
+updated: 2026-02-12
+---
+
+# UltraKit
+
+## Vision
+
+A project scaffolding tool that generates OpenCode-ready project templates.
+
+UltraKit (`uk`) enables developers to bootstrap AI-assisted development environments with all essential configurations, skills, commands, and integrations pre-configured and validated.
+
+## Success Criteria
+
+- [ ] Users can `uk init` and get a working OpenCode project in under 60 seconds
+- [ ] Generated projects include all essential files (AGENTS.md, skills, commands, memory)
+- [ ] 100% of generated templates pass validation (typecheck, lint)
+- [ ] Templates are customizable through CLI prompts or config
+- [ ] Integration with beads for task tracking works out-of-the-box
+
+## Target Users
+
+### Primary
+
+- **Solo developers** setting up AI-assisted workflows for personal projects
+- **Teams** standardizing their OpenCode configuration across multiple projects
+
+### User Needs
+
+- Quick setup without manual configuration
+- Consistent, validated project structures
+- Customizable templates for different use cases
+- Integrated task tracking from day one
+
+## Core Principles
+
+1. **Convention over configuration** - Sensible defaults, minimal setup required
+2. **Minimal but complete** - Include only essential files, no bloat
+3. **Extensible** - Easy to add custom skills, commands, and templates
+4. **Validated by default** - All generated projects pass typecheck and lint
+5. **Git-backed** - All state and tracking integrated with git workflow
+
+## Tech Stack
+
+- **Runtime:** Node.js >= 20.19.0
+- **Language:** TypeScript (ESNext, strict mode)
+- **Build:** tsdown + rsync for template bundling
+- **CLI Framework:** cac
+- **UI Prompts:** @clack/prompts
+- **Validation:** zod
+- **Task Tracking:** beads_rust (br)
+
+## Current Phase
+
+**Scale** - Core complete, adding advanced features.
+
+See [roadmap.md](./roadmap.md) for phase details and [state.md](./state.md) for current position.
+
+## Architecture
+
+```
+src/
+├── index.ts          # CLI entry point
+├── commands/         # CLI commands (init, etc.)
+├── utils/            # Shared utilities
+└── validation/       # Validation scripts
+
+dist/
+├── index.js          # Built CLI
+└── template/         # Bundled .opencode/ template
+
+.opencode/
+├── agent/            # Agent definitions
+├── command/          # OpenCode commands
+├── skill/            # Reusable skills
+├── tool/             # Custom tools
+└── memory/           # Project memory
+```
+
+## Key Files
+
+| File          | Purpose                     |
+| ------------- | --------------------------- |
+| AGENTS.md     | Project rules for AI agents |
+| package.json  | Dependencies and scripts    |
+| build.ts      | Build configuration         |
+| tsconfig.json | TypeScript configuration    |
+
+---
+
+_Update this file when vision, success criteria, or principles change._