@ultrakit/ultrakit 0.0.0

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

@@ -0,0 +1,128 @@
+---
+description: Research a topic or bead before implementation
+argument-hint: "<topic-or-bead-id> [--quick|--thorough]"
+agent: scout
+---
+
+# Research: $ARGUMENTS
+
+Gather information before implementation. Find answers, document findings, stop when done.
+
+> Research can happen at any phase when you need external information or codebase understanding.
+
+## Load Skills
+
+```typescript
+skill({ name: "beads" });
+skill({ name: "memory-grounding" });
+// For --thorough mode:
+skill({ name: "deep-research" });
+```
+
+## Parse Arguments
+
+| Argument         | Default  | Description                         |
+| ---------------- | -------- | ----------------------------------- |
+| Topic or bead ID | required | What to research                    |
+| `--quick`        | false    | ~10 tool calls, single question     |
+| `--thorough`     | false    | ~100+ calls, comprehensive analysis |
+
+Default depth: ~30 tool calls for moderate exploration.
+
+## Determine Input Type
+
+| Input Type | Detection                   | Action                            |
+| ---------- | --------------------------- | --------------------------------- |
+| Bead ID    | Matches `br-xxx` or numeric | Research within that bead context |
+| Topic      | String                      | Standalone research               |
+
+## Before You Research
+
+- **Be certain**: Only research what you need for implementation
+- **Don't over-research**: Stop when you have enough to proceed
+- **Use source priority**: Codebase → Docs → Source → GitHub → Web
+- **Verify confidence**: Medium+ confidence required before stopping
+- **Document findings**: Write to research.md for beads, report for topics
+
+## Available Tools
+
+| Tool         | Use When                        |
+| ------------ | ------------------------------- |
+| `explore`    | Codebase patterns, LSP analysis |
+| `scout`      | External docs, best practices   |
+| `context7`   | Official API references         |
+| `opensrc`    | Package source code inspection  |
+| `codesearch` | Real-world usage examples       |
+| `grepsearch` | GitHub code search              |
+
+## Phase 1: Load Context
+
+If argument is a bead ID:
+
+```bash
+br show $ARGUMENTS
+```
+
+Read PRD if it exists and extract questions that need answering.
+
+### Memory Search (Required)
+
+Follow the [memory-grounding](../skill/memory-grounding/SKILL.md) skill protocol. Use findings to: skip already-answered questions, narrow scope to gaps only, avoid contradicting prior decisions without justification.
+
+## Phase 2: Research
+
+### Source Priority
+
+1. **Codebase patterns** — delegate to `explore` agent for LSP analysis
+2. **Official docs** — `context7` for API references
+3. **Source code** — `npx opensrc <package>` when docs are insufficient
+4. **GitHub examples** — `codesearch` / `grepsearch` for real-world patterns
+5. **Web search** — only if tiers 1-4 don't answer
+
+### Delegation
+
+| What              | Agent                        | When                                   |
+| ----------------- | ---------------------------- | -------------------------------------- |
+| Codebase analysis | `explore`                    | Internal patterns, file structure, LSP |
+| External docs     | `scout` (this agent)         | Library APIs, best practices           |
+| Multiple domains  | Parallel `explore` + `scout` | 3+ independent questions               |
+
+### Confidence Levels
+
+- **High**: Multiple authoritative sources agree, verified in codebase
+- **Medium**: Single good source, plausible but unverified
+- **Low**: Conflicting info, speculation — discard without corroboration
+
+## Phase 3: Stop When
+
+- All questions answered with medium+ confidence
+- Tool budget exhausted for depth level
+- Last 5 tool calls yielded no new insights
+- Blocked and need human input
+
+## Phase 4: Document
+
+Write findings to `.beads/artifacts/$ARGUMENTS/research.md` (if bead) or report directly (if topic):
+
+- Questions asked → answered/partial/unanswered with confidence
+- Key findings with sources (file paths, docs)
+- Recommendation based on findings
+- Open items needing resolution
+
+## Output
+
+Report:
+
+1. Depth level and tool call count
+2. Questions with answer status and confidence
+3. Key insights (bullet points)
+4. Open items remaining
+5. Next step suggestion
+
+## Related Commands
+
+| Need           | Command      |
+| -------------- | ------------ |
+| Create + start | `/create`    |
+| Plan details   | `/plan <id>` |
+| Pick up work   | `/ship <id>` |

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

@@ -0,0 +1,78 @@
+---
+description: Resume work on a bead from previous session
+argument-hint: "<bead-id>"
+agent: build
+---
+
+# Resume: $ARGUMENTS
+
+Pick up where a previous session left off. Recover context, verify state, continue.
+
+## Load Skills
+
+```typescript
+skill({ name: "beads" });
+skill({ name: "memory-grounding" });
+```
+
+## Phase 1: Verify Task
+
+```bash
+br show $ARGUMENTS
+```
+
+If not found, check `br list --status=all` — it may have been closed or the ID is wrong.
+
+## Phase 2: Git State
+
+```bash
+git branch --show-current
+git status --porcelain
+```
+
+If not on the right branch, check out the feature branch. If uncommitted changes exist, ask user what to do.
+
+## Phase 3: Find Handoff
+
+Follow the [memory-grounding](../skill/memory-grounding/SKILL.md) skill protocol. Focus on: handoff file by bead ID, session history.
+
+If a handoff exists, it tells you:
+
+- What was completed
+- Where work stopped
+- What to do next
+- Any blockers
+
+## Phase 4: Load Artifacts
+
+Read all available context:
+
+- `.beads/artifacts/$ARGUMENTS/prd.md`
+- `.beads/artifacts/$ARGUMENTS/plan.md` (if exists)
+- `.beads/artifacts/$ARGUMENTS/progress.txt` (if exists)
+- `.beads/artifacts/$ARGUMENTS/research.md` (if exists)
+
+## Phase 5: Check Staleness
+
+If handoff is more than 3 days old:
+
+```bash
+git log --oneline -10
+```
+
+Check if significant changes happened on main. If so, consider rebasing. Don't blindly follow an outdated plan — verify it still makes sense.
+
+## Phase 6: Continue
+
+```bash
+br update $ARGUMENTS --status in_progress
+```
+
+Report:
+
+1. Branch and commit
+2. Handoff age
+3. Progress (completed/remaining tasks)
+4. Next action (from handoff or PRD)
+
+Then continue with `/ship $ARGUMENTS` or `/plan $ARGUMENTS` as appropriate.

package/dist/template/.opencode/command/review-codebase.md

@@ -0,0 +1,135 @@
+---
+description: Review code for quality, security, and compliance
+argument-hint: "[path|bead-id|pr-number|'all'] [--quick|--thorough]"
+agent: review
+---
+
+# Review: $ARGUMENTS
+
+## Load Skills
+
+```typescript
+skill({ name: "beads" });
+skill({ name: "requesting-code-review" });
+skill({ name: "verification-gates" });
+```
+
+## Determine Input Type
+
+| Input Type            | Detection                    | Action                     |
+| --------------------- | ---------------------------- | -------------------------- |
+| No arguments          | Default                      | Review uncommitted changes |
+| Commit hash (40-char) | SHA pattern                  | `git show <hash>`          |
+| Branch name           | String, not matching above   | `git diff main...HEAD`     |
+| PR URL/number         | Contains "github.com" or "#" | `gh pr diff`               |
+
+## Before You Review
+
+- **Be certain**: Only flag issues you can verify with tools
+- **Don't invent problems**: If an edge case isn't specified, don't flag it
+- **Don't be a zealot about style**: Unless it violates project conventions, don't flag
+- **Review the changes**: Don't review pre-existing code that wasn't modified
+- **Investigate first**: If unsure, use explore/scout agents before flagging
+
+## Available Tools
+
+| Tool                 | Use When                                |
+| -------------------- | --------------------------------------- |
+| `explore`            | Finding patterns in codebase, prior art |
+| `scout`              | External research, best practices       |
+| `lsp`                | Finding symbol definitions, references  |
+| `tilth_tilth_search` | Finding code patterns                   |
+| `codesearch`         | Real-world usage examples               |
+
+## Phase 1: Gather Context
+
+```bash
+git status --short
+git diff --cached  # staged
+git diff           # unstaged
+```
+
+For each changed file:
+
+- Read the full file to understand context
+- Don't rely on diff alone — code that looks wrong in isolation may be correct
+
+If bead provided, read `.beads/artifacts/$ID/prd.md` to review against spec.
+
+## Phase 2: Determine Scope
+
+| Input                    | Scope                 | How to Get Code           |
+| ------------------------ | --------------------- | ------------------------- |
+| File/directory path      | That path only        | `read` or `glob` + `read` |
+| Bead ID (e.g., `br-123`) | Implementation vs PRD | `br show` then `git diff` |
+| PR number (e.g., `#45`)  | PR changes            | `gh pr diff 45`           |
+| `all` or empty           | Recent changes        | `git diff main...HEAD`    |
+
+If bead provided, read `.beads/artifacts/$ID/prd.md` to review against spec.
+
+## Phase 3: Automated Checks
+
+Follow the [verification-gates](../skill/verification-gates/SKILL.md) skill protocol.
+
+Check `package.json` scripts, `Makefile`, or `justfile` for project-specific commands first — prefer those over generic defaults.
+
+Also scan for common issues appropriate to the detected language:
+
+- Debug statements (`console.log`, `print()`, `println!`, `fmt.Println`)
+- Loose typing (`any` in TypeScript, `type: ignore` in Python)
+- `TODO|FIXME|HACK` markers
+- Hardcoded secrets patterns
+
+## Phase 4: Manual Review
+
+Review each category:
+
+| Category            | Focus                                                                   |
+| ------------------- | ----------------------------------------------------------------------- |
+| **Security**        | Auth checks, input validation, no secrets in code, injection prevention |
+| **Performance**     | N+1 queries, unbounded loops, missing pagination, hot path ops          |
+| **Maintainability** | Complexity, DRY violations, dead code, naming clarity                   |
+| **Error Handling**  | Async error handling, error context, sanitized user errors              |
+| **Testing**         | Coverage on changed code, behavior tests, edge cases                    |
+| **Type Safety**     | No unjustified `any`, null handling, explicit return types              |
+
+**Depth levels:**
+
+- `--quick`: Automated checks + skim, critical issues only
+- Default: Full automated + manual review
+- `--thorough`: Deep analysis of all categories
+
+## Phase 5: Report
+
+Group findings by severity:
+
+- **Critical** (must fix before merge): with file:line, issue, fix
+- **Important** (should fix): with file:line, issue, fix
+- **Minor** (nice to have): with file:line, suggestion
+
+Include:
+
+1. Summary metrics (files reviewed, issues by severity)
+2. Strengths (what's done well, with file:line)
+3. Verdict: Ready to merge / With fixes / No
+4. Reasoning (1-2 sentences)
+
+Record significant findings with `observation()`:
+
+```typescript
+observation({
+  type: "discovery", // or "warning", "pattern", "bugfix"
+  title: "Review: [scope] [key finding]",
+  narrative: "[What was found, severity, file:line, recommended fix]",
+  concepts: "code-review, [category]",
+  confidence: "high",
+});
+```
+
+## Related Commands
+
+| Need                | Command        |
+| ------------------- | -------------- |
+| Ship after review   | `/ship <id>`   |
+| Verify completeness | `/verify <id>` |
+| Check status        | `/status`      |