@ultrakit/ultrakit 0.0.0 → 0.0.2

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

@@ -1,92 +0,0 @@
----
-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._

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

@@ -1,142 +0,0 @@
----
-purpose: Project roadmap with phases, milestones, and bead organization
-updated: 2026-02-12
----
-
-# Roadmap
-
-## Overview
-
-| Phase  | Goal                                              | Status      | Beads |
-| ------ | ------------------------------------------------- | ----------- | ----- |
-| MVP    | Core `ock init` command with basic template       | Complete    | [#]   |
-| Extend | Additional commands (`/ship`, `/plan`, `/resume`) | Complete    | [#]   |
-| Polish | Error handling, docs, validation improvements     | Complete    | [#]   |
-| Scale  | Plugin system, custom templates, advanced config  | In Progress | [#]   |
-
-## Phase 1: MVP
-
-**Goal:** Users can run `ock init` to generate a working OpenCode project template.
-
-**Success Criteria:**
-
-- [x] `ock init` command creates project structure
-- [x] Generated files include AGENTS.md, skills, commands, memory
-- [x] Templates pass typecheck and lint
-- [x] Basic CLI prompts for project configuration
-
-**Beads:**
-
-| ID  | Title             | Type    | Status | Depends On |
-| --- | ----------------- | ------- | ------ | ---------- |
-| -   | Core init command | feature | closed | -          |
-| -   | Template bundling | task    | closed | -          |
-| -   | CLI prompts       | task    | closed | -          |
-
-**Out of Scope:**
-
-- Advanced customization
-- Plugin system
-- Multiple template options
-
----
-
-## Phase 2: Extend
-
-**Goal:** Add essential OpenCode commands for common workflows.
-
-**Success Criteria:**
-
-- [x] `/ship` command for deployment workflows
-- [x] `/plan` command for implementation planning
-- [x] `/resume` command for continuing work
-- [x] `/handoff` command for session handoffs
-- [x] `/status` command for project state
-
-**Beads:**
-
-| ID  | Title           | Type    | Status | Depends On |
-| --- | --------------- | ------- | ------ | ---------- |
-| -   | Ship command    | feature | closed | MVP        |
-| -   | Plan command    | feature | closed | MVP        |
-| -   | Resume command  | feature | closed | MVP        |
-| -   | Handoff command | feature | closed | MVP        |
-| -   | Status command  | feature | closed | MVP        |
-
-**Dependencies:**
-
-- Requires MVP completion
-
----
-
-## Phase 3: Polish
-
-**Goal:** Improve quality, documentation, and error handling.
-
-**Success Criteria:**
-
-- [x] Comprehensive error messages with actionable guidance
-- [x] Documentation for all commands
-- [x] Validation scripts for template integrity
-- [x] Improved CLI UX with progress indicators
-
-**Beads:**
-
-| ID  | Title               | Type | Status | Depends On |
-| --- | ------------------- | ---- | ------ | ---------- |
-| -   | Error handling      | task | closed | Extend     |
-| -   | Documentation       | task | closed | Extend     |
-| -   | Validation scripts  | task | closed | Extend     |
-| -   | CLI UX improvements | task | closed | Extend     |
-
-**Dependencies:**
-
-- Requires Extend completion
-
----
-
-## Phase 4: Scale
-
-**Goal:** Add advanced features for power users and customization.
-
-**Success Criteria:**
-
-- [ ] Plugin system for extending CLI functionality
-- [ ] Custom template support (user-defined templates)
-- [ ] Advanced configuration options
-- [ ] Template marketplace or sharing mechanism
-
-**Beads:**
-
-| ID  | Title            | Type    | Status | Depends On    |
-| --- | ---------------- | ------- | ------ | ------------- |
-| -   | Plugin system    | epic    | open   | Polish        |
-| -   | Custom templates | feature | open   | Polish        |
-| -   | Advanced config  | task    | open   | Polish        |
-| -   | Template sharing | epic    | open   | Plugin system |
-
-**Dependencies:**
-
-- Requires Polish 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

@@ -1,84 +0,0 @@
----
-purpose: Current project state, active decisions, blockers, and position tracking
-updated: 2026-02-12
----
-
-# State
-
-## Current Position
-
-**Active Bead:** (none active)
-**Status:** Ready for new work
-**Started:** 2026-02-12
-**Phase:** Scale
-
-## Recent Completed Work
-
-| Bead | Title                 | Completed | Summary                                           |
-| ---- | --------------------- | --------- | ------------------------------------------------- |
-| -    | Polish phase tasks    | 2026-02   | Error handling, docs, validation, UX improvements |
-| -    | Extend phase commands | 2026-02   | Ship, plan, resume, handoff, status commands      |
-| -    | MVP core features     | 2026-02   | Init command, template bundling, CLI prompts      |
-
-## Active Decisions
-
-| Date       | Decision          | Rationale                                  | Impact                          |
-| ---------- | ----------------- | ------------------------------------------ | ------------------------------- |
-| 2026-02-12 | Scale phase focus | Core complete, ready for advanced features | Plugin system, custom templates |
-
-## Blockers
-
-| Bead | Blocker | Since | Owner |
-| ---- | ------- | ----- | ----- |
-| -    | (none)  | -     | -     |
-
-## Open Questions
-
-| Question                         | Context                        | Blocking | Priority |
-| -------------------------------- | ------------------------------ | -------- | -------- |
-| What plugin system architecture? | Scale phase planning           | Yes      | High     |
-| How to handle custom templates?  | User-defined templates feature | Yes      | High     |
-
-## Context Notes
-
-### Technical
-
-- Node.js runtime required (>= 20.19.0)
-- TypeScript strict mode enforced
-- Build uses tsdown + rsync to bundle .opencode/ template
-- oxlint for linting (fast, modern)
-
-### Product
-
-- Target: solo developers and teams
-- Key differentiator: validated, ready-to-use templates
-- Integration with beads_rust for task tracking
-
-### Process
-
-- Run `npm run lint:fix` before commits
-- Validate with `npm run typecheck`
-- Never modify dist/ directly
-
-## Next Actions
-
-1. [ ] Define plugin system architecture
-2. [ ] Design custom template API
-3. [ ] Create Scale phase implementation plan
-4. [ ] Identify Scale phase beads
-
-## Session Handoff
-
-**Last Session:** 2026-02-12
-**Next Session Priority:** Define plugin system architecture
-**Known Issues:** None currently blocking
-**Context Links:**
-
-- AGENTS.md - Project rules
-- .opencode/skill/ - Available skills
-- .opencode/command/ - Available commands
-
----
-
-_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/project/tech-stack.md

@@ -1,53 +0,0 @@
----
-purpose: Tech stack, constraints, and integrations for AI context injection
-updated: 2026-02-24
----
-
-# Tech Stack
-
-This file is automatically injected into ALL AI prompts via `opencode.json` instructions[].
-
-## Framework & Language
-
-- **Framework:** CLI tool (cac for argument parsing)
-- **Language:** TypeScript (ESNext, strict mode, bundler moduleResolution)
-- **Runtime:** Node.js >= 20.19.0
-
-## Key Dependencies
-
-- **CLI Framework:** cac (^6.7.14) - Command-line argument parsing
-- **UI Prompts:** @clack/prompts (^0.7.0) - Interactive CLI prompts
-- **Validation:** zod (^3.25.76) - Schema validation
-- **Task Tracking:** beads-village (^1.3.3) - Git-backed task management
-- **AI SDK:** @ai-sdk/provider (^3.0.8) - AI provider integration
-
-## Build & Tools
-
-- **Build:** tsdown + rsync for template bundling
-- **Lint:** oxlint (^1.48.0) - Fast JavaScript/TypeScript linter
-- **Format:** oxfmt (^0.23.0) - Code formatter
-- **TypeCheck:** tsgo (@typescript/native-preview)
-- **Dev Runner:** tsx - TypeScript execution for development
-
-## Testing
-
-- **Unit Tests:** vitest
-- **Test Location:** src/\*_/_.test.ts (colocated)
-- **Run Single:** vitest src/commands/init.test.ts
-
-## Key Constraints
-
-- Node.js >= 20.19.0 required (engines.node in package.json)
-- pnpm for package management
-- Build copies .opencode/ to dist/template/ - don't edit dist/ directly
-- Keep .opencode/ structure minimal and focused
-
-## Active Integrations
-
-- **OpenCode AI:** @opencode-ai/plugin (^1.1.12) - OpenCode integration
-- **Beads CLI:** beads_rust (br) - Task tracking CLI
-
----
-
-_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

@@ -1,45 +0,0 @@
----
-purpose: User identity, preferences, communication style
-updated: 2025-01-06
----
-
-# User Profile
-
-## Identity
-
-- Name: Ryan Jose Brosas
-- Git email: ryanjoserbrosas@gmail.com
-
-## Communication Preferences
-
-- Style: Detailed responses preferred
-- Explanations welcome when helpful
-
-## Workflow Preferences
-
-- Git commits: Auto-commit (no ask)
-- Beads updates: Auto-commit (no ask)
-- Auto-actions: Enabled - proceed without confirmation
-
-## Technical Preferences
-
-- Runtime: Node.js
-- Language: TypeScript
-- Linter: oxlint
-
-## Editing Tool Preferences
-
-- **Primary**: `edit` tool (str_replace) and `patch` tool
-- **Secondary/Fallback**: `tilth_tilth_edit` (hash-anchored edits) — only when str_replace fails
-- **Reading/Search**: `tilth_tilth_read` and `tilth_tilth_search` are fine to use freely
-
-## Rules to Always Follow
-
-- Run `npm run lint:fix` before any commit
-- Validate changes with `npm run typecheck`
-- Don't modify dist/ directly (it's built output)
-- Ask before adding new dependencies
-- Ask before changing .opencode/ structure
-- Ask before schema changes (zod schemas, config shapes)
-- Never commit secrets or .env files
-- Never force push to main

package/dist/template/.opencode/memory/research/benchmark-framework.md

@@ -1,162 +0,0 @@
----
-purpose: Scoring rubric for evaluating template agent effectiveness
-updated: 2026-03-08
-based-on: tilth research (measurable pattern adoption improvements)
----
-
-# Agent Effectiveness Benchmark Framework
-
-## Purpose
-
-Evaluate whether skills, tools, and commands in the OpenCodeKit template actually help AI agents perform better. Based on tilth's methodology: they measured accuracy, cost/correct answer, and tool adoption rates to prove what works.
-
-## Scoring Dimensions
-
-7 dimensions, each scored 0–2. Max score: **14**.
-
-### 1. Trigger Clarity (WHEN/SKIP)
-
-Does the description clearly specify when to load AND when NOT to?
-
-| Score | Criteria                                    |
-| ----- | ------------------------------------------- |
-| 0     | Vague or missing trigger conditions         |
-| 1     | Has WHEN but not WHEN NOT (or vice versa)   |
-| 2     | Clear WHEN and WHEN NOT (SKIP) binary gates |
-
-**Why it matters:** tilth found explicit WHEN/SKIP gates are the single most effective pattern for correct tool routing. Without them, agents either over-load (waste tokens) or under-load (miss relevant skills).
-
-### 2. "Replaces X" Framing
-
-Does it explicitly state what behavior, tool, or workflow it replaces?
-
-| Score | Criteria                                       |
-| ----- | ---------------------------------------------- |
-| 0     | No replacement framing                         |
-| 1     | Implied replacement or "better than X"         |
-| 2     | Explicit "Replaces X" statement in description |
-
-**Why it matters:** tilth measured +36 percentage points adoption on Haiku when tool descriptions included "Replaces X" framing. Models route better when they know what's superseded.
-
-### 3. Concrete Examples
-
-Does it provide working code with actual tool calls, not just prose?
-
-| Score | Criteria                                                                |
-| ----- | ----------------------------------------------------------------------- |
-| 0     | No examples                                                             |
-| 1     | Prose descriptions or generic prompt templates                          |
-| 2     | Working code examples with actual tool calls / before-after comparisons |
-
-**Why it matters:** Models follow examples more reliably than instructions. Prompt templates ("Analyze this image: [attach]") score 1, not 2 — they lack tool integration.
-
-### 4. Anti-Patterns
-
-Does it show what NOT to do?
-
-| Score | Criteria                                                       |
-| ----- | -------------------------------------------------------------- |
-| 0     | No anti-patterns section                                       |
-| 1     | Brief "don't do X" mentions                                    |
-| 2     | Wrong/right comparison table or detailed anti-patterns section |
-
-**Why it matters:** Failure prevention is as valuable as success instruction. tilth's evidence-based feature removal (disabling `--map` because 62% of losing tasks used it) proves tracking what fails matters.
-
-### 5. Verification Integration
-
-Does it reference or require verification steps?
-
-| Score | Criteria                                                       |
-| ----- | -------------------------------------------------------------- |
-| 0     | No mention of verification                                     |
-| 1     | Mentions verification in passing                               |
-| 2     | Integrates verification steps into workflow (run X, confirm Y) |
-
-**Why it matters:** Skills that don't include verification produce unverified outputs. The build loop is perceive → create → **verify** → ship.
-
-### 6. Token Efficiency
-
-Is the token cost proportional to value delivered?
-
-| Score | Criteria                                                                       |
-| ----- | ------------------------------------------------------------------------------ |
-| 0     | >2500 tokens with low value density (filler, repetition, obvious instructions) |
-| 1     | Reasonable size OR moderate value density                                      |
-| 2     | <1500 tokens with high value density, OR larger with proportional density      |
-
-**Why it matters:** Every loaded skill consumes context budget. A 4000-token skill that could be 1500 tokens is actively harmful — it displaces working memory.
-
-### 7. Cross-References
-
-Does it link to related skills for next steps?
-
-| Score | Criteria                                                                     |
-| ----- | ---------------------------------------------------------------------------- |
-| 0     | No references to other skills                                                |
-| 1     | Mentions related skills in text                                              |
-| 2     | Clear "Related Skills" table or "Next Phase" with skill loading instructions |
-
-**Why it matters:** Skills that exist in isolation force agents to discover connections. Explicit connections reduce routing failures.
-
-## Score Interpretation
-
-| Range | Tier       | Meaning                                                     |
-| ----- | ---------- | ----------------------------------------------------------- |
-| 12–14 | Exemplary  | Ready to ship — high adoption, measurable value             |
-| 8–11  | Adequate   | Functional but missing patterns that would improve adoption |
-| 4–7   | Needs Work | Significant gaps — may load but produce suboptimal results  |
-| 0–3   | Poor       | Should be rewritten or merged into another skill            |
-
-## Category Assessment
-
-Beyond individual scoring, evaluate each skill's **category fit**:
-
-| Category             | Expected Traits                                                                  |
-| -------------------- | -------------------------------------------------------------------------------- |
-| Core Workflow        | Loaded frequently, high token ROI, tight integration with other core skills      |
-| Planning & Lifecycle | Clear phase transitions, handoff points between skills                           |
-| Debugging & Quality  | Real examples from actual debugging sessions, measurable impact                  |
-| Code Review          | Severity levels, actionable findings format                                      |
-| Design & UI          | Visual reference integration, component breakdown                                |
-| Agent Orchestration  | Parallelism rules, coordination protocols                                        |
-| External Integration | API examples, auth handling, error patterns                                      |
-| Platform Specific    | Version-pinned APIs, migration guidance                                          |
-| Meta Skills          | Self-referential consistency (does the skill-about-skills follow its own rules?) |
-
-## Audit Process
-
-1. **Inventory** — List all skills with token size
-2. **Sample** — Read representative skills from each category
-3. **Score** — Apply 7 dimensions to each sampled skill
-4. **Classify** — Assign tier and category
-5. **Identify** — Flag overlaps, dead weight, and upgrade candidates
-6. **Prioritize** — Rank improvements by impact (core skills first)
-
-## Effectiveness Signals (Observable)
-
-Beyond the rubric, track these runtime signals when possible:
-
-| Signal                                     | Indicates                                                    |
-| ------------------------------------------ | ------------------------------------------------------------ |
-| Skill loaded but instructions not followed | Trigger too broad OR instructions too vague                  |
-| Skill never loaded despite relevant tasks  | Trigger too narrow OR description doesn't match task framing |
-| Agent re-reads files after skill search    | Skill examples insufficient — agent needs more context       |
-| Verification skipped after skill workflow  | Skill doesn't integrate verification                         |
-| Agent loads 5+ skills simultaneously       | Skills too granular — should be merged                       |
-
-## Template-Level Metrics
-
-For the overall template (all skills + tools + commands):
-
-| Metric                        | Target | Current |
-| ----------------------------- | ------ | ------- |
-| Core skills at Exemplary tier | 100%   | (audit) |
-| No skills at Poor tier        | 0      | (audit) |
-| Average token cost per skill  | <1500  | (audit) |
-| Skills with WHEN/SKIP gates   | 100%   | (audit) |
-| Skills with anti-patterns     | >75%   | (audit) |
-| Overlap/redundancy pairs      | 0      | (audit) |
-
----
-
-_Apply this framework during effectiveness audits. Update scoring criteria as new evidence emerges._