@ultrakit/ultrakit 0.0.0 → 0.0.2

package/README.md

@@ -1,15 +1,46 @@
 # UltraKit
 
-UltraKit is a TypeScript CLI and template for running OpenCode with an opinionated multi-agent workflow.
+UltraKit is a scaffolding and maintenance CLI for OpenCode projects. It generates and upgrades a complete OpenCode-ready project structure: agents, slash commands, skills, memory files, tools, plugins, validation scripts, and configuration.
+
+Think of it as **create-react-app for OpenCode projects** — it bootstraps the environment, validates it, and keeps it maintainable over time.
+
+## What UltraKit Is
+
+UltraKit is a **project scaffolding and maintenance CLI**. It:
+
+- Generates a validated `.opencode/` template with agents, commands, skills, tools, plugins
+- Initializes `.beads/` for multi-agent task coordination
+- Validates project configuration (docs-drift, command-doc, skill-lint)
+- Upgrades templates to latest repository state via `uk upgrade`
+- Manages project health via `uk doctor` and `uk status`
+
+## What UltraKit Is Not
+
+UltraKit is **not primarily a runtime orchestration plugin**.
+
+Runtime plugins such as Oh My OpenAgent enhance what happens during an active OpenCode coding session: background agents, model routing, specialized runtime roles, and live multi-agent execution.
+
+UltraKit operates one layer earlier and one layer longer: it creates, standardizes, upgrades, and governs the project structure those sessions run inside.
+
+## Long-Term Direction
+
+UltraKit will be developed continuously across four connected layers:
+
+1. **Personal AI dev environment** — a dogfooded setup for real daily work.
+2. **Reusable starter kit** — a reliable template for new OpenCode projects.
+3. **Packaged tool** — an installable CLI with validation, upgrades, and guided setup.
+4. **Agent operating-system layer** — a project substrate for agents, memory, workflows, skills, verification, and compounding improvements.
+
+The goal is not only to help agents code, but to help OpenCode projects remember, coordinate, verify, and improve over time.
 
 ## What This Template Includes
 
-- Beads-first lifecycle: `/create` -> `/start` -> `/ship`
-- Custom agents in `.opencode/agent/` (9 in this template)
-- Slash commands in `.opencode/command/` (14 workflows)
-- Skills in `.opencode/skill/` (large curated library)
-- Custom tools in `.opencode/tool/` (memory tools, `observation`, `swarm`, `context7`, `grepsearch`, etc.)
-- Plugins in `.opencode/plugin/` for memory, session continuity, swarm workflow enforcement, and skill MCP
+- Beads-first lifecycle: `/create` -> `/plan` (optional) -> `/ship` (or `/lfg` for the full loop)
+- Custom agents installed to `.opencode/agent/` (template source: `template/opencode/agent/`)
+- Slash commands installed to `.opencode/command/` (template source: `template/opencode/command/`)
+- Skills installed to `.opencode/skill/` (template source: `template/opencode/skill/`)
+- Custom tools installed to `.opencode/tool/` (template source: `template/opencode/tool/`)
+- Plugins installed to `.opencode/plugin/` (template source: `template/opencode/plugin/`)
 
 ## Quick Start
 
@@ -18,34 +49,62 @@ UltraKit is a TypeScript CLI and template for running OpenCode with an opinionat
 npx ultrakit init
 
 # Or in this repository during development
-pnpm install
-pnpm run src/index.ts --help
+npm install
+npm run dev -- --help
+```
+
+## Optional: Upstream Superpowers
+
+UltraKit already includes a curated workflow skill library, including many skills that overlap with the upstream [`obra/superpowers`](https://github.com/obra/superpowers) project. Superpowers is therefore **not installed by default**: its plugin adds overlapping skills and injects its own bootstrap instructions into OpenCode sessions.
+
+If you explicitly want the upstream Superpowers plugin in a newly initialized project, run:
+
+```bash
+npx ultrakit init --with-superpowers
 ```
 
+This appends the pinned OpenCode plugin spec to the generated `.opencode/opencode.json`:
+
+```txt
+superpowers@git+https://github.com/obra/superpowers.git#v5.1.0
+```
+
+For an existing project, add the same pinned entry manually to the `plugin` array in `.opencode/opencode.json`. Treat it as opt-in remote plugin code loaded by OpenCode, and update the pinned tag deliberately during maintenance.
+
 ## Core Slash Command Workflow
 
 Use these inside OpenCode:
 
-1. `/create <description>` - create bead and PRD
-2. `/start <bead-id>` - claim bead and prepare branch/workspace
-3. `/ship <bead-id>` - implement, verify, review, close
+1. `/create <description>` — create bead and PRD
+2. `/plan <bead-id>` — optionally create a detailed implementation plan
+3. `/ship <bead-id>` — implement, verify, review, close
 
 ## Available Slash Commands (Template)
 
+- `/compound`
 - `/create`
-- `/start`
-- `/ship`
+- `/cleanup`
+- `/curate`
+- `/design`
+- `/handoff`
+- `/health`
+- `/ideate`
+- `/init`
+- `/init-context`
+- `/init-deep`
+- `/init-user`
+- `/iterate`
+- `/lfg`
 - `/plan`
-- `/status`
 - `/pr`
-- `/resume`
-- `/handoff`
 - `/research`
+- `/resume`
 - `/review-codebase`
-- `/verify`
-- `/design`
+- `/ship`
+- `/status`
 - `/ui-review`
-- `/init`
+- `/ui-slop-check`
+- `/verify`
 
 ## CLI Command Surface (`uk`)
 
@@ -58,6 +117,7 @@ The packaged CLI commands are:
 - `uk doctor`
 - `uk status`
 - `uk upgrade`
+- `uk patch [action]`
 - `uk completion [shell]`
 - `uk tui`
 
@@ -67,9 +127,8 @@ See `CLI.md` for command usage details.
 
 ```text
 src/                  # CLI implementation
-.opencode/            # Agents, commands, skills, tools, plugins
+template/opencode/    # Package template source installed as user .opencode/
 .beads/               # Task tracking database and artifacts
-build.ts              # Build pipeline (bundles .opencode template)
 dist/                 # Build output (generated)
 ```
 
@@ -85,9 +144,9 @@ npm run build
 ## Documentation
 
 - `CLI.md` - `uk` command reference
-- `.opencode/README.md` - project OpenCode configuration guide
-- `.opencode/AGENTS.md` - global agent rules and operating constraints
-- `.opencode/plugin/README.md` - plugin architecture and tooling
+- `template/opencode/README.md` - packaged OpenCode configuration guide
+- `template/opencode/AGENTS.md` - packaged agent rules and operating constraints
+- `template/opencode/plugin/README.md` - plugin architecture and tooling
 
 ## Notes