@ultrakit/ultrakit 0.0.0

package/dist/template/.opencode/command/init-user.md

@@ -0,0 +1,125 @@
+---
+description: Create user profile for personalized AI interactions
+argument-hint: "[--skip-questions]"
+agent: build
+---
+
+# Init-User: $ARGUMENTS
+
+Create personalized user profile. Optional but recommended for better AI responses.
+
+> **Prerequisite:** Run `/init` first for core setup
+> **Related:** `/init-context` for project planning setup
+
+## Load Skills
+
+```typescript
+skill({ name: "memory-system" });
+```
+
+## Options
+
+| Argument           | Default | Description                         |
+| ------------------ | ------- | ----------------------------------- |
+| `--skip-questions` | false   | Infer from git config, skip prompts |
+
+## Phase 1: Gather Preferences
+
+Unless `--skip-questions`, ask in one message:
+
+1. **Identity**: "Which git contributor are you?" (show top 5 from `git shortlog -sn --all`)
+2. **Communication**: "Terse or detailed responses?"
+3. **Workflow**: "Auto-commit or ask-first?"
+4. **Rules**: "Any rules I should always follow?"
+5. **Technical**: "Preferred languages/frameworks?"
+
+If skipped, infer from `git config user.name` and `git config user.email`.
+
+## Phase 2: Create user.md
+
+From template `.opencode/memory/_templates/user.md`:
+
+```bash
+cp .opencode/memory/_templates/user.md .opencode/memory/project/user.md
+```
+
+Fill in gathered answers:
+
+```markdown
+---
+purpose: User identity, preferences, communication style
+updated: [today]
+---
+
+# User Profile
+
+## Identity
+
+- Name: [from answers]
+- Git email: [user.email]
+
+## Communication Preferences
+
+- Style: [Terse/Detailed]
+- Tone: [Professional/Casual]
+
+## Workflow Preferences
+
+- Git commits: [Auto/Ask-first]
+- Beads updates: [Auto/Ask-first]
+
+## Technical Preferences
+
+- Languages/frameworks: [Preferred languages/frameworks]
+
+## Things to Remember
+
+- [Rule 1]
+- [Rule 2]
+- [Rule 3]
+```
+
+### Persist to Memory System
+
+After writing the file, also store key preferences as a memory observation for cross-session retrieval:
+
+```typescript
+observation({
+  type: "decision",
+  title: "User profile: [name]",
+  narrative: "User preferences captured: [style], [workflow prefs], [technical prefs]. Source: /init-user command.",
+  concepts: "user-profile, preferences",
+  confidence: "high",
+  files_modified: ".opencode/memory/project/user.md",
+});
+```
+
+## Phase 3: Update opencode.json
+
+Ensure `user.md` is loaded in `instructions` (bare paths, no `file://` prefix).
+
+The default `instructions[]` includes 4 auto-injected files:
+
+```json
+{
+  "instructions": [
+    ".opencode/memory/project/user.md",
+    ".opencode/memory/project/tech-stack.md",
+    ".opencode/memory/project/project.md",
+    ".opencode/context/git-context.md"
+  ]
+}
+```
+
+> **Warning:** Do not add more files to `instructions[]` unless they are essential for every prompt. Per-prompt injection of too many files causes session OOM crashes. Use `memory-read()` for on-demand access instead.
+
+## Phase 4: Report
+
+Output:
+
+1. user.md created at `.opencode/memory/project/user.md`
+2. Preferences captured
+3. 4 files are auto-injected by default: user.md, tech-stack.md, project.md, git-context.md
+4. Additional planning files (roadmap.md, state.md) are on-demand via `/init-context`
+5. Custom context available at `.opencode/context/` (preserved during init --force and upgrade)
+6. Next step: `/init-context` if the user wants fuller project-planning memory files

package/dist/template/.opencode/command/init.md

@@ -0,0 +1,115 @@
+---
+description: Initialize core project setup (AGENTS.md + tech-stack detection only)
+argument-hint: "[--deep]"
+agent: build
+---
+
+# Init: $ARGUMENTS
+
+Core project setup. Creates AGENTS.md and detects tech stack. Run once per project.
+
+> **Next steps:** `/init-user` for personalization, `/init-context` for GSD planning workflow
+
+## Load Skills
+
+```typescript
+skill({ name: "index-knowledge" });
+```
+
+## Options
+
+| Argument | Default | Description                               |
+| -------- | ------- | ----------------------------------------- |
+| `--deep` | false   | Comprehensive research (~100+ tool calls) |
+
+## Phase 1: Detect Project
+
+Detect and validate:
+
+- Package manager and dependencies (with versions)
+- Build, test, lint, dev commands — **validate each actually works**
+- CI/CD configuration
+- Existing AI rules (`.cursor/rules/`, `.cursorrules`, `.github/copilot-instructions.md`)
+- Top-level directory structure
+
+With `--deep`: Also analyze git history, source patterns, subsystem candidates.
+
+## Phase 2: Preview Detection
+
+After detecting project, show summary and ask for confirmation:
+
+```typescript
+question({
+  questions: [
+    {
+      header: "Preview",
+      question: `Detected: ${detectedTechStack}. Create AGENTS.md?`,
+      options: [
+        { label: "Yes, create it (Recommended)" },
+        { label: "Show me what you'll write first" },
+        { label: "Cancel" },
+      ],
+    },
+  ],
+});
+```
+
+**If "Show me":** Display detected values without writing files, then ask again.
+
+## Phase 3: Create AGENTS.md
+
+Create `./AGENTS.md` — **target <60 lines** (max 150). Follow the `index-knowledge` skill format:
+
+- Tech stack with versions
+- File structure
+- Commands (validated)
+- Code example from actual codebase (5-10 lines)
+- Testing conventions
+- Boundaries (always/ask-first/never)
+- Gotchas
+
+**Principles**: Examples > explanations. Pointers > copies. If AGENTS.md exists, improve it — don't overwrite blindly.
+
+## Phase 4: Create tech-stack.md
+
+From template `.opencode/memory/_templates/tech-stack.md`:
+
+Read the template from `.opencode/memory/_templates/tech-stack.md` and write it to `.opencode/memory/project/tech-stack.md`.
+
+Fill detected values:
+
+- Framework, language, runtime
+- Styling, components, design system
+- Database, ORM, state management
+- Testing tools
+- Verification commands
+
+## Phase 5: Subsystems (--deep only)
+
+Identify candidates for nested AGENTS.md:
+
+- `packages/*/` in monorepos
+- `frontend/` vs `backend/` directories
+- Significantly different subsystem patterns
+
+Ask user before creating nested files.
+
+## Phase 6: Verify and Report
+
+Verify:
+
+- [ ] AGENTS.md is <60 lines (or justified)
+- [ ] Commands validated and work
+- [ ] Boundaries include Never rules
+- [ ] Code example from actual codebase
+- [ ] tech-stack.md created
+
+Output:
+
+1. Files created (with line counts)
+2. Tech stack detected
+3. Commands validated (yes/no)
+4. Suggested next steps:
+   - `/init-user` — Create user profile
+   - `/init-context` — Set up GSD planning workflow
+   - `/review-codebase` — Deep codebase analysis

package/dist/template/.opencode/command/iterate.md

@@ -0,0 +1,200 @@
+---
+description: Refine PRD mid-implementation when scope changes, discoveries emerge, or requirements pivot
+argument-hint: "<bead-id> [--scope expand|reduce|pivot] [--reason <text>]"
+agent: build
+---
+
+# Iterate: $ARGUMENTS
+
+Refine a bead's PRD during active implementation. Two-phase process: define what changed, then update spec artifacts and re-derive affected tasks.
+
+> **When to use:** Mid-`/ship` when you discover scope changed, requirements shifted, or a technical discovery invalidates the original plan.
+>
+> **NOT for:** Pre-implementation changes (use `/create` to rewrite the PRD) or post-implementation retrospectives (use `/compound`).
+
+## Load Skills
+
+```typescript
+skill({ name: "beads" });
+skill({ name: "memory-grounding" });
+skill({ name: "prd" });
+skill({ name: "prd-task" });
+```
+
+## Parse Arguments
+
+| Argument    | Default       | Description                        |
+| ----------- | ------------- | ---------------------------------- |
+| `<bead-id>` | required      | The bead being iterated            |
+| `--scope`   | auto-detected | Change type: expand, reduce, pivot |
+| `--reason`  | prompted      | Why the change is needed           |
+
+## Before You Iterate
+
+- **Be certain**: Only iterate if continuing with the current spec would produce wrong output
+- **Don't over-iterate**: Minor adjustments don't need a full iterate cycle — just fix inline during `/ship`
+- **Preserve progress**: Completed tasks stay completed unless explicitly invalidated
+- **Document the delta**: Every change must be traceable to a reason
+
+## Phase 1: Guards
+
+```bash
+br show $ARGUMENTS
+```
+
+Read `.beads/artifacts/$ARGUMENTS/` to check what artifacts exist.
+
+Verify:
+
+- Bead is `in_progress`
+- `prd.md` exists
+- Implementation is partially complete (at least 1 task done or in-progress)
+
+If no tasks are started yet, redirect: "Use `/create --spec-only` to rewrite the PRD instead."
+
+## Phase 2: Assess Change Type
+
+If `--scope` was not provided, determine the change type:
+
+| Type       | Signal                                                  | Example                                   |
+| ---------- | ------------------------------------------------------- | ----------------------------------------- |
+| **expand** | New requirement discovered, additional files needed     | "We also need to handle edge case X"      |
+| **reduce** | Feature is over-scoped, some tasks are unnecessary      | "We don't need the admin panel after all" |
+| **pivot**  | Fundamental approach changed, different solution needed | "REST won't work, switching to WebSocket" |
+
+Ask user to confirm:
+
+```typescript
+question({
+  questions: [
+    {
+      header: "Change Type",
+      question: "What kind of spec change is this?",
+      options: [
+        { label: "Expand", description: "Adding scope — new requirements or files" },
+        { label: "Reduce", description: "Removing scope — dropping unnecessary work" },
+        { label: "Pivot", description: "Changing approach — different solution path" },
+      ],
+    },
+  ],
+});
+```
+
+## Phase 3: Define the Delta
+
+### Step 1: Capture the change reason
+
+If `--reason` was not provided, ask:
+
+```typescript
+question({
+  questions: [
+    {
+      header: "Reason",
+      question: "What triggered this change? (Be specific — this goes into the PRD changelog)",
+      options: [],
+    },
+  ],
+});
+```
+
+### Step 2: Identify affected artifacts
+
+Read the current PRD and list:
+
+- **Tasks completed:** (preserve these unless pivot invalidates them)
+- **Tasks in-progress:** (may need modification)
+- **Tasks not started:** (may need modification, removal, or replacement)
+- **New tasks needed:** (for expand/pivot)
+
+### Step 3: Document the delta
+
+Write a change record to `.beads/artifacts/$ARGUMENTS/iterations.md`:
+
+```markdown
+## Iteration [N] — [date]
+
+**Type:** [expand | reduce | pivot]
+**Reason:** [user-provided reason]
+**Triggered by:** [discovery | user request | technical constraint | external dependency]
+
+### Impact Assessment
+
+| Area  | Before                  | After                     | Action                         |
+| ----- | ----------------------- | ------------------------- | ------------------------------ |
+| Scope | [original scope]        | [new scope]               | [expanded/reduced/pivoted]     |
+| Tasks | [N] total, [M] complete | [N'] total, [M] preserved | [added/removed/modified count] |
+| Files | [original file list]    | [updated file list]       | [new/removed files]            |
+
+### Task Changes
+
+- **Preserved:** [list of completed task titles — unchanged]
+- **Modified:** [list of tasks with what changed]
+- **Removed:** [list of tasks marked obsolete, with reason]
+- **Added:** [list of new tasks]
+```
+
+## Phase 4: Apply Changes
+
+### For Expand:
+
+1. Add new sections/requirements to `prd.md`
+2. Add new tasks at the end of the Tasks section
+3. Mark new tasks with `depends_on` referencing completed tasks if needed
+4. Re-run `prd-task` skill to regenerate `prd.json` with merged task state
+
+### For Reduce:
+
+1. Move removed scope items to "Out-of-Scope" in `prd.md` with note: `[Removed in Iteration N: reason]`
+2. Mark affected tasks by changing their heading from `### Task Title [category]` to `### ~~Task Title~~ [OBSOLETE — Iteration N]` in `prd.md` (don't delete — preserve history). The `prd-task` skill skips headings containing `OBSOLETE` or `INVALIDATED` markers.
+3. Re-run `prd-task` to regenerate `prd.json` (obsolete tasks excluded)
+
+### For Pivot:
+
+1. Archive current PRD section as `## Original Approach (Superseded)` at bottom of file
+2. Rewrite affected sections (Proposed Solution, Requirements, Tasks)
+3. Preserve completed tasks that are still valid
+4. Mark invalidated completed tasks by changing their heading to `### ~~Task Title~~ [INVALIDATED — Iteration N: reason]`
+5. Re-run `prd-task` to regenerate `prd.json`
+
+### Update plan.md (if exists):
+
+If `.beads/artifacts/$ARGUMENTS/plan.md` exists:
+
+1. Add an "## Iteration [N] Changes" section to the plan
+2. Update dependency graph if tasks changed
+3. Re-compute waves for remaining tasks
+
+## Phase 5: Validate
+
+After applying changes:
+
+- [ ] PRD has no `[NEEDS CLARIFICATION]` markers (resolve or add to Open Questions)
+- [ ] All preserved completed tasks are still valid
+- [ ] New/modified tasks have verification steps
+- [ ] `iterations.md` documents the full delta
+- [ ] `prd.json` reflects the updated task state
+
+## Phase 6: Report
+
+```bash
+br comments add $ARGUMENTS "Iteration [N]: [type] — [reason summary]. Tasks: [added/removed/modified] count"
+```
+
+Output:
+
+1. **Change type:** [expand | reduce | pivot]
+2. **Reason:** [brief summary]
+3. **Task changes:** [N] preserved, [M] modified, [K] removed, [J] added
+4. **Files affected:** [updated list]
+5. **Iteration log:** `.beads/artifacts/$ARGUMENTS/iterations.md`
+6. **Next step:** Continue `/ship $ARGUMENTS` with updated spec
+
+## Related Commands
+
+| Need                       | Command            |
+| -------------------------- | ------------------ |
+| Create initial spec        | `/create`          |
+| Continue shipping          | `/ship <id>`       |
+| Review after changes       | `/review-codebase` |
+| Post-implementation review | `/compound <id>`   |

package/dist/template/.opencode/command/lfg.md

@@ -0,0 +1,173 @@
+---
+description: Full autonomous chain - Plan → Ship → Review → Compound in one command
+argument-hint: "<bead-id> [--skip-plan]"
+agent: build
+---
+
+# LFG (Let's Fucking Go): $ARGUMENTS
+
+Full compound engineering cycle. One command, all four steps.
+
+> **When to use:** You have a bead in `in_progress` state with a PRD. You want maximum autonomous execution with minimum hand-holding.
+>
+> **Checkpoints happen** at decision points. Everything automatable is automated.
+
+## Parse Arguments
+
+| Argument      | Default  | Description                             |
+| ------------- | -------- | --------------------------------------- |
+| `<bead-id>`   | required | The bead to execute                     |
+| `--skip-plan` | false    | Skip planning if plan.md already exists |
+
+## Phase 0: Preflight
+
+```bash
+br show $BEAD_ID
+```
+
+Read `.beads/artifacts/$BEAD_ID/` to check what artifacts exist.
+
+Verify:
+
+- Bead exists and is `in_progress`
+- `prd.md` exists
+- If `plan.md` exists and `--skip-plan` not set: ask user whether to replan or use existing
+
+Report:
+
+```
+## LFG: <bead-id> — <title>
+
+Cycle: Plan → Ship → Review → Compound
+Review mode: [Standard 3-agent / Deep 5-agent]
+Plan: [create new / use existing]
+```
+
+## Step 1: PLAN
+
+Load and execute the `/plan` command for this bead:
+
+```typescript
+skill({ name: "writing-plans" });
+// Run full /plan flow including Phase 0 institutional research
+// Output: .beads/artifacts/$BEAD_ID/plan.md
+```
+
+Checkpoint if plan has major unknowns or architecture questions. Otherwise proceed automatically.
+
+## Step 2: WORK
+
+Execute the plan:
+
+```typescript
+skill({ name: "executing-plans" });
+skill({ name: "reflection-checkpoints" }); // Phase transition + mid-point checks
+// Load plan.md, execute wave-by-wave
+// Per-task commits after each task passes verification
+```
+
+Follow the [Verification Protocol](../skill/verification-before-completion/references/VERIFICATION_PROTOCOL.md):
+
+- Use **full mode** for final verification
+- Use **incremental mode** between implementation waves
+
+Checkpoint only at `checkpoint:human-verify` or `checkpoint:decision` tasks.
+
+## Step 3: REVIEW
+
+```bash
+BASE_SHA=$(git rev-parse origin/main 2>/dev/null || git merge-base HEAD origin/main)
+HEAD_SHA=$(git rev-parse HEAD)
+```
+
+Load and run the review skill:
+
+```typescript
+skill({ name: "requesting-code-review" });
+```
+
+Dispatch 5 specialized agents in parallel.
+
+Wait for all agents to return. Synthesize findings.
+
+**Auto-fix rule:**
+
+- Critical issues → fix inline, re-verify, continue
+- Important issues → fix inline, continue
+- Minor issues → add to bead comments, continue
+
+If Critical issues cannot be auto-fixed:
+
+```
+## CHECKPOINT: Review Blocker
+
+Critical issue found that requires architectural decision:
+[description]
+
+Options:
+1. [option A]
+2. [option B]
+
+Awaiting your decision before continuing.
+```
+
+## Step 4: COMPOUND
+
+Load and run the compound command:
+
+```typescript
+// Run /compound $BEAD_ID
+// Extract learnings from the full cycle
+// Store observations to memory
+// Suggest AGENTS.md updates if conventions changed
+```
+
+## Step 5: Report & Next
+
+```
+## LFG Complete: <bead-id>
+
+### Cycle Summary
+
+| Step     | Status | Notes                        |
+|----------|--------|------------------------------|
+| Plan     | ✓      | [N] waves, [M] tasks         |
+| Work     | ✓      | [N] commits, [M] files       |
+| Review   | ✓      | [N] agents, [M] fixes        |
+| Compound | ✓      | [N] observations stored      |
+
+### Learnings Captured
+[list of observation titles]
+
+### Verification
+- typecheck: pass
+- lint: pass
+- tests: pass ([N] passing)
+
+### Next Steps
+- Review the changes: `git diff origin/main`
+- Create PR: `/pr`
+- Or continue with next bead: `/lfg <next-bead-id>`
+```
+
+## Swarm Mode (sLFG)
+
+For large plans with 6+ independent tasks, run Work step in swarm mode:
+
+```typescript
+skill({ name: "swarm-coordination" });
+// Dispatch parallel worker agents per wave
+// Leader monitors and synthesizes
+```
+
+Use when: plan has 2+ independent waves with no shared file mutations.
+
+## Related Commands
+
+| Need            | Command          |
+| --------------- | ---------------- |
+| Plan only       | `/plan <id>`     |
+| Ship only       | `/ship <id>`     |
+| Review only     | `/review`        |
+| Compound only   | `/compound <id>` |
+| Create PR after | `/pr`            |