@ultrakit/ultrakit 0.0.0

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

@@ -0,0 +1,298 @@
+---
+description: Create a bead with specification, claim it, and prepare workspace
+argument-hint: "<description> [--type epic|feature|task|bug] [--spec-only]"
+agent: build
+---
+
+# Create: $ARGUMENTS
+
+Create a bead, write its specification (PRD), claim it, set up the workspace, and convert to executable tasks — ready for `/ship`.
+
+> **Workflow:** **`/create`** → `/ship <id>`
+>
+> Use `--spec-only` to create the specification without claiming or setting up workspace.
+
+## Load Skills
+
+```typescript
+skill({ name: "beads" });
+skill({ name: "memory-grounding" });
+skill({ name: "workspace-setup" });
+skill({ name: "prd" }); // PRD template guidance
+skill({ name: "prd-task" }); // PRD → executable tasks (Phase 8)
+```
+
+## Parse Arguments
+
+| Argument        | Default       | Description                               |
+| --------------- | ------------- | ----------------------------------------- |
+| `<description>` | required      | What to build/fix (quoted string)         |
+| `--type`        | auto-detected | Override: epic, feature, task, bug        |
+| `--spec-only`   | false         | Create spec without claiming or workspace |
+
+## Determine Input Type
+
+| Input Type  | Detection            | Action                        |
+| ----------- | -------------------- | ----------------------------- |
+| Quoted text | `"description here"` | Create PRD from description   |
+| Short form  | Simple string        | Ask for more detail if needed |
+| `--type`    | Flag provided        | Use provided type             |
+
+## Before You Create
+
+- **Be certain**: Only create beads you're confident have clear scope
+- **Don't over-spec**: If the description is vague, ask clarifying questions first
+- **Check duplicates**: Always run Phase 1 duplicate check
+- **No implementation**: This command creates specs and workspace — don't write implementation code
+- **Verify PRD**: Before saving, verify all sections are filled (no placeholders)
+- **Flag uncertainty**: Use `[NEEDS CLARIFICATION]` markers for unknowns — never guess silently
+
+## Available Tools
+
+| Tool      | Use When                                     |
+| --------- | -------------------------------------------- |
+| `explore` | Finding patterns in codebase, affected files |
+| `scout`   | External research, best practices            |
+| `br`      | Creating and managing beads                  |
+
+## Phase 1: Duplicate Check
+
+### Memory Search
+
+Follow the [memory-grounding](../skill/memory-grounding/SKILL.md) skill protocol. Focus on: duplicate bead detection, prior decisions.
+
+### Bead List Check
+
+```bash
+br list --status=open --status=in_progress
+```
+
+If a matching bead exists, stop and tell the user to use `/ship <id>` instead.
+
+## Phase 2: Classify Type
+
+If `--type` was provided, use it directly. Otherwise, suggest a type based on the description and ask the user to confirm:
+
+- **epic**: Multi-session, cross-domain (redesign, migrate, overhaul)
+- **feature**: New capability, scoped (add, implement, build, integrate)
+- **bug**: Something broken (fix, error, crash, not working)
+- **task**: Tactical change, clear scope (everything else)
+
+## Phase 3: Choose Research Depth
+
+Ask user before spawning agents:
+
+```typescript
+question({
+  questions: [
+    {
+      header: "Research Depth",
+      question: "How much codebase research do you need?",
+      options: [
+        {
+          label: "Deep (Recommended for complex work)",
+          description: "3-5 agents: patterns, tests, deps, best practices (~2 min)",
+        },
+        {
+          label: "Standard",
+          description: "2 agents: patterns + tests (~1 min)",
+        },
+        {
+          label: "Minimal",
+          description: "1 agent: quick file scan (~30 sec)",
+        },
+        {
+          label: "Skip",
+          description: "I know the codebase, use existing knowledge",
+        },
+      ],
+    },
+  ],
+});
+```
+
+## Phase 4: Gather Context
+
+Based on research depth choice, spawn agents:
+
+**If Deep:**
+
+- 3x `explore` (patterns, tests, deps)
+- 1x `scout` (feature/epic)
+- 1x `review` (epic)
+
+**If Standard:**
+
+- 2x `explore` (patterns, tests)
+- 1x `scout` (feature/epic only)
+
+**If Minimal:**
+
+- 1x `explore` (patterns)
+
+**If Skip:**
+
+- No agents, use existing AGENTS.md context
+
+**While agents run**, ask clarifying questions if the description lacks scope or expected outcome. For bugs, also ask for reproduction steps and expected vs actual behavior.
+
+## Phase 5: Create Bead
+
+Extract bead title and description from `$ARGUMENTS` before creating the bead.
+
+- If user provided a single line, use it for both title and description.
+- If user provided multiple lines, use first line as title and full text as description.
+
+```bash
+BEAD_ID=$(br create --title "$TITLE" --description "$DESCRIPTION" --type $BEAD_TYPE --json | jq -r '.id')
+mkdir -p ".beads/artifacts/$BEAD_ID"
+```
+
+## Phase 6: Determine PRD Rigor
+
+Not every change needs a full spec. Assess complexity to choose the right PRD level:
+
+| Signal | Lite PRD | Full PRD |
+| --- | --- | --- |
+| Type | `bug`, `task` | `feature`, `epic` |
+| Files affected | 1-3 | 4+ |
+| Scope | Clear, single-concern | Cross-cutting, multi-system |
+| Research depth | Skip or Minimal | Standard or Deep |
+| Description | "Fix X in Y" | "Implement X with Y and Z" |
+
+**Auto-detect:** If type is `bug` or `task` AND research was Skip/Minimal AND description is a single sentence → default to Lite.
+
+### Lite PRD Format
+
+For simple, well-scoped work (bugs, small tasks):
+
+```markdown
+# [Title]
+
+## Problem
+[1-2 sentences: what's wrong or what's needed]
+
+## Solution
+[1-2 sentences: what to do]
+
+## Affected Files
+- `src/path/to/file.ts`
+
+## Tasks
+- [ ] [Task description] → Verify: `[command]`
+
+## Success Criteria
+- Verify: `npm run typecheck && npm run lint`
+- Verify: `[specific test or check]`
+```
+
+### Full PRD Format
+
+For features and complex work, use the full template:
+
+Read the PRD template from `.opencode/memory/_templates/prd.md` and write it to `.beads/artifacts/$BEAD_ID/prd.md`.
+
+## Phase 7: Write PRD
+
+Copy and fill the PRD template (lite or full) using context from Phase 4.
+
+**If Lite PRD:** Fill the lite format directly. No template file needed.
+
+**If Full PRD:** Read the template and fill all required sections:
+
+| Section           | Source                                                     | Required          |
+| ----------------- | ---------------------------------------------------------- | ----------------- |
+| Problem Statement | User description + clarifying questions                    | Always            |
+| Scope (In/Out)    | User input + codebase exploration                          | Always            |
+| Proposed Solution | Codebase patterns + user intent                            | Always            |
+| Success Criteria  | User verification + test commands (must include `Verify:`) | Always            |
+| Technical Context | Explore agent findings                                     | Always            |
+| Affected Files    | Explore agent findings (real paths from Phase 4)           | Always            |
+| Tasks             | Derived from scope + solution                              | Always            |
+| Risks             | Codebase exploration                                       | Feature/epic only |
+| Open Questions    | Unresolved items from Phase 4                              | If any exist      |
+
+### Task Format
+
+Tasks must follow the `prd-task` skill format:
+
+- Title with `[category]` tag
+- One-sentence **end state** description (not step-by-step)
+- Metadata block: `depends_on`, `parallel`, `conflicts_with`, `files`
+- At least one verification command per task
+
+## Phase 8: Validate PRD
+
+Before saving, verify:
+
+- [ ] No placeholder text remains (e.g., "[Clear description", "[List what's allowed]")
+- [ ] Success criteria include `Verify:` commands
+- [ ] Technical context references actual `src/` paths from exploration
+- [ ] Affected files list real paths
+- [ ] Tasks have `[category]` headings
+- [ ] Each task has verification
+- [ ] No implementation code in the PRD
+- [ ] No unresolved `[NEEDS CLARIFICATION]` markers remain (convert to Open Questions or resolve)
+
+If any check fails, fix it — don't ask the user.
+
+## Phase 9: Claim and Prepare Workspace
+
+**If `--spec-only` was passed, skip to Phase 12 (Report).**
+
+### Workspace Check
+
+```bash
+git status --porcelain
+git branch --show-current
+br list --status=in_progress
+```
+
+- If uncommitted changes: ask user to stash, commit, or continue
+- If other tasks in progress: warn before claiming another
+
+### Claim Bead
+
+```bash
+br update $BEAD_ID --status in_progress
+```
+
+### Create Branch
+
+### Workspace Setup
+
+Follow the [workspace-setup](../skill/workspace-setup/SKILL.md) skill protocol.
+
+Additionally offer a "Create worktree" option:
+
+```typescript
+skill({ name: "using-git-worktrees" });
+```
+
+## Phase 10: Convert PRD to Tasks
+
+Use `prd-task` skill to convert PRD markdown → executable JSON (`prd.json`).
+
+## Phase 11: Report
+
+Output:
+
+1. Bead ID and type
+2. PRD location (`.beads/artifacts/$BEAD_ID/prd.md`)
+3. Summary: task count, success criteria count, affected files count
+4. Branch name and workspace (if claimed)
+5. Next step: `/ship $BEAD_ID` (or `/plan $BEAD_ID` for complex work)
+
+```bash
+br comments add $BEAD_ID "Created prd.md with [N] tasks, [M] success criteria"
+```
+
+---
+
+## Related Commands
+
+| Need               | Command      |
+| ------------------ | ------------ |
+| Research first     | `/research`  |
+| Plan after spec    | `/plan <id>` |
+| Implement and ship | `/ship <id>` |

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

@@ -0,0 +1,299 @@
+---
+description: Organize, deduplicate, and curate knowledge in project memory
+argument-hint: "[--scope recent|all] [--auto-merge]"
+agent: build
+---
+
+# Curate: $ARGUMENTS
+
+Organize accumulated knowledge. Surface conflicts, merge duplicates, archive stale observations.
+
+> **Workflow:** `/ship` → `/compound` → **`/curate`** → `/pr`
+>
+> Run periodically (weekly or after major work) to keep memory sharp. Inspired by ByteRover's structured curation pipeline.
+
+## Load Skills
+
+```typescript
+skill({ name: "memory-system" });
+skill({ name: "verification-before-completion" });
+```
+
+## Parse Arguments
+
+| Argument       | Default  | Description                                      |
+| -------------- | -------- | ------------------------------------------------ |
+| `--scope`      | `recent` | `recent` = last 30 days, `all` = entire memory   |
+| `--auto-merge` | false    | Auto-merge exact duplicates without confirmation |
+
+## Phase 1: Inventory
+
+Take stock of current memory state:
+
+```typescript
+memory_admin({ operation: "status" });
+memory_admin({ operation: "capture-stats" });
+```
+
+Report:
+
+```
+## Memory Inventory
+
+| Metric | Count |
+|--------|-------|
+| Total observations | [N] |
+| Recent (30 days) | [N] |
+| By type | pattern: N, decision: N, bugfix: N, ... |
+| Confidence distribution | high: N, medium: N, low: N |
+```
+
+## Phase 2: Domain Detection
+
+Analyze observations to extract semantic domains — groups of related knowledge.
+
+```typescript
+// Get memory status for inventory
+memory_admin({ operation: "status" });
+
+// Search by common concept categories to build domain map
+const domains = [];
+for (const concept of ["build", "test", "memory", "git", "agent", "auth", "ui", "config"]) {
+  const results = memory_search({ query: concept, limit: 20 });
+  // Group results by concept affinity
+}
+```
+
+Categorize observations into domains based on their `concepts` and `title` fields:
+
+| Domain         | Example Concepts                   | Observation Count |
+| -------------- | ---------------------------------- | ----------------- |
+| `build_system` | build, tsdown, rsync, dist         | [N]               |
+| `testing`      | vitest, test, TDD, coverage        | [N]               |
+| `memory`       | observation, FTS5, sqlite, handoff | [N]               |
+| `git_workflow` | commit, branch, push, PR           | [N]               |
+| `agent_system` | subagent, delegation, skills       | [N]               |
+
+**Domain naming rules:**
+
+- snake_case, 1-3 words
+- Semantically meaningful (not just "misc")
+- Maximum 10 domains (merge small groups)
+
+## Phase 3: Conflict & Duplicate Detection
+
+### 3a. Exact Duplicates
+
+```typescript
+memory_admin({ operation: "lint" });
+```
+
+Flag observations with identical or near-identical titles and narratives. Present for merge:
+
+```
+### Duplicates Found
+
+| Obs A | Obs B | Similarity | Recommended Action |
+|-------|-------|------------|-------------------|
+| #12 "Use JWT for auth" | #45 "JWT chosen for auth" | 95% title match | MERGE → keep #45 (newer) |
+| #8 "Build copies .opencode/" | #33 "Build copies .opencode/" | 100% title match | MERGE → keep #33 (newer) |
+```
+
+### 3b. Contradictions
+
+Search for observations where:
+
+- Same concepts but different decisions
+- Same file paths but conflicting patterns
+- Confidence downgrade without supersedes link
+
+```
+### Contradictions Found
+
+| Obs A | Obs B | Conflict | Recommended Action |
+|-------|-------|----------|-------------------|
+| #5 "Always use X pattern" | #29 "Avoid X pattern" | Opposite recommendations | RESOLVE — ask user which is current |
+```
+
+### 3c. Stale Observations
+
+Flag observations where:
+
+- Referenced files no longer exist
+- Referenced patterns no longer appear in codebase
+- Over 90 days old with no related recent activity
+
+```
+### Stale Observations
+
+| Obs | Age | Reason | Recommended Action |
+|-----|-----|--------|-------------------|
+| #3 "src/old-file.ts pattern" | 120 days | File deleted | ARCHIVE |
+| #7 "Use moment.js for dates" | 95 days | Dependency removed | ARCHIVE |
+```
+
+## Phase 4: Present Curation Plan
+
+Compile all findings into a review table:
+
+```
+## Curation Plan
+
+### Actions Required
+
+| # | Observation | Action | Reason |
+|---|------------|--------|--------|
+| 1 | #12 + #45 | MERGE | Duplicate — keep newer |
+| 2 | #5 vs #29 | RESOLVE | Contradicting patterns |
+| 3 | #3 | ARCHIVE | Referenced file deleted |
+| 4 | #7 | ARCHIVE | Dependency removed |
+| 5 | #18 | UPDATE | Low confidence → verify |
+```
+
+```typescript
+question({
+  questions: [
+    {
+      header: "Curation Plan",
+      question: "Review the curation plan. Proceed with all actions?",
+      options: [
+        { label: "Execute all (Recommended)", description: "Apply all actions above" },
+        { label: "Let me cherry-pick", description: "I'll approve individually" },
+        { label: "Skip curation", description: "No changes to memory" },
+      ],
+    },
+  ],
+});
+```
+
+## Phase 5: Execute Curation
+
+For each approved action:
+
+### MERGE (duplicates)
+
+```typescript
+// Read both observations
+const older = memory_get({ ids: "<older-id>" });
+const newer = memory_get({ ids: "<newer-id>" });
+
+// Union-merge: combine comma-separated lists, deduplicate (case-insensitive), existing items first
+// Example: older.facts="auth, jwt" + newer.facts="jwt, session" → "auth, jwt, session"
+
+// Create merged observation (newer as base, merge fields from older)
+observation({
+  type: newer.type,
+  title: newer.title,
+  narrative: newer.narrative,
+  // Manually combine comma-separated fields: keep all unique items from both
+  facts: "[combined unique facts from older + newer]",
+  concepts: "[combined unique concepts from older + newer]",
+  files_modified: "[combined unique file paths from older + newer]",
+  confidence: newer.confidence, // Newer confidence wins
+  supersedes: "<older-id>",
+  subtitle: "Merged from #<older-id> + #<newer-id>",
+});
+```
+
+**Union merge rule:** Combine comma-separated lists, deduplicate (case-insensitive), existing items first.
+
+### RESOLVE (contradictions)
+
+Present the conflicting observations side-by-side:
+
+```
+### Contradiction: #5 vs #29
+
+**#5 (older, high confidence):**
+> Always use X pattern for Y components
+
+**#29 (newer, medium confidence):**
+> Avoid X pattern — causes Z issues
+
+Which is the current truth?
+```
+
+```typescript
+question({
+  questions: [
+    {
+      header: "Resolve Conflict",
+      question: "Which observation reflects the current codebase reality?",
+      options: [
+        { label: "#5 (older) is correct", description: "Archive #29, keep #5" },
+        { label: "#29 (newer) is correct", description: "Supersede #5 with #29" },
+        { label: "Both partially correct", description: "I'll write a reconciled version" },
+      ],
+    },
+  ],
+});
+```
+
+### ARCHIVE (stale)
+
+```typescript
+// Verify staleness by checking codebase
+// If file doesn't exist or pattern not found:
+observation({
+  type: "warning",
+  title: "Archived: [original title]",
+  narrative: "Archived during curation — [reason]. Original observation #<id>.",
+  supersedes: "<stale-id>",
+  confidence: "low",
+});
+```
+
+### UPDATE (low confidence → verify)
+
+```typescript
+// Search codebase for evidence
+// If evidence found → upgrade confidence
+// If evidence not found → archive
+```
+
+## Phase 6: Compile Knowledge Index
+
+After curation, regenerate the knowledge index:
+
+```typescript
+memory_admin({ operation: "compile" });
+memory_admin({ operation: "index" });
+```
+
+## Phase 7: Report
+
+```
+## Curation Summary
+
+**Scope:** [recent / all]
+**Observations reviewed:** [N]
+**Domains identified:** [N]
+
+| Action | Count | Details |
+|--------|-------|---------|
+| Merged | [N] | [list merged pairs] |
+| Resolved | [N] | [list resolved conflicts] |
+| Archived | [N] | [list archived observations] |
+| Updated | [N] | [list confidence changes] |
+| No change | [N] | |
+
+**Memory health:** [Healthy / Needs attention: describe]
+**Next recommended:** /pr or continue work
+```
+
+## When Nothing to Curate
+
+If all observations are clean, well-organized, and non-conflicting:
+
+> "Memory is clean. No duplicates, contradictions, or stale observations found. [N] observations across [M] domains."
+
+Don't force curation. Quality memory means less curation needed.
+
+## Related Commands
+
+| Need                    | Command                        |
+| ----------------------- | ------------------------------ |
+| Extract learnings first | `/compound`                    |
+| Full chain              | `/lfg`                         |
+| Check memory health     | `/health`                      |
+| Search memory           | Use `memory-search()` directly |