@ultrakit/ultrakit 0.0.0

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

@@ -0,0 +1,356 @@
+---
+description: Audit .opencode/ configuration for consistency, stale references, and enforcement gaps
+argument-hint: "[--fix] [--layer <intent|knowledge|control>]"
+agent: review
+---
+
+# Health Check: $ARGUMENTS
+
+Self-audit the .opencode/ configuration for drift, inconsistencies, and enforcement gaps.
+
+## Load Skills
+
+```typescript
+skill({ name: "verification-before-completion" });
+```
+
+## Parse Arguments
+
+| Argument  | Default | Description                                         |
+| --------- | ------- | --------------------------------------------------- |
+| `--fix`   | false   | Auto-fix safe issues (stale refs, dead links)       |
+| `--layer` | all     | Focus on specific layer: intent, knowledge, control |
+
+## Overview
+
+This command runs a multi-layer health check inspired by three-layer defense:
+
+1. **Intent** (AGENTS.md) — policies and rules
+2. **Knowledge** (Skills) — procedures and workflows
+3. **Control** (Agent frontmatter, hooks) — structural enforcement
+
+A rule that exists at intent but not control is a gap. This command finds those gaps.
+
+## Phase 1: Inventory
+
+Build an inventory of all .opencode/ artifacts:
+
+```bash
+# Count artifacts
+echo "=== Skills ==="
+ls .opencode/skill/ | wc -l
+echo "=== Commands ==="
+ls .opencode/command/ | wc -l
+echo "=== Agents ==="
+ls .opencode/agent/ | wc -l
+echo "=== Tools ==="
+ls .opencode/tool/ 2>/dev/null | wc -l
+echo "=== Plugins ==="
+ls .opencode/plugin/ 2>/dev/null | wc -l
+```
+
+Report totals as a summary table.
+
+## Phase 2: Stale Reference Detection
+
+Check for references to skills, commands, or agents that don't exist:
+
+### 2a. Skill references in commands and AGENTS.md
+
+For every `skill({ name: "X" })` call found in `.opencode/command/*.md` and `AGENTS.md`:
+
+- Verify `.opencode/skill/X/SKILL.md` exists
+- Flag any that don't exist as **CRITICAL**
+
+### 2b. Command references in skills and AGENTS.md
+
+For every `/command-name` reference found in `.opencode/skill/*/SKILL.md` and `AGENTS.md`:
+
+- Verify `.opencode/command/command-name.md` exists
+- Flag missing as **IMPORTANT**
+
+### 2c. Agent references
+
+For every `agent: X` in command frontmatter:
+
+- Verify `.opencode/agent/X.md` exists (or is a built-in agent)
+- Flag missing as **CRITICAL**
+
+### 2d. Cross-references between skills
+
+For every `dependencies: [X, Y]` in skill YAML frontmatter:
+
+- Verify each dependency skill exists
+- Flag missing as **IMPORTANT**
+
+Report format:
+
+```text
+| Reference Type       | Source File           | Target        | Status  |
+|---------------------|-----------------------|---------------|---------|
+| skill()             | command/ship.md:15    | beads         | OK      |
+| skill()             | command/plan.md:22    | old-skill     | MISSING |
+| /command             | skill/X/SKILL.md:45   | /deploy       | MISSING |
+```
+
+## Phase 3: Skill Quality Audit
+
+For each skill in `.opencode/skill/*/SKILL.md`:
+
+1. **Frontmatter check:**
+   - [ ] Has `name:` field
+   - [ ] Has `description:` field
+   - [ ] `name:` matches directory name
+   - [ ] Starts with `---` on line 1
+
+2. **Content check:**
+   - [ ] Has `## When to Use` section
+   - [ ] Has `## When NOT to Use` section
+   - [ ] Under 200 lines (warn if over)
+   - [ ] Has `## Gotchas` section (advisory — new skills may not have one yet)
+
+3. **Description trigger check:**
+   - [ ] Description starts with action trigger (Use when, MUST load, Use INSTEAD OF)
+   - Flag descriptions that don't specify when to load as **MINOR**
+
+Report as a scorecard:
+
+```text
+| Skill                   | Frontmatter | Content | Trigger | Gotchas | Lines | Grade |
+|-------------------------|-------------|---------|---------|---------|-------|-------|
+| verification-before-... | OK          | OK      | OK      | NO      | 237   | B+    |
+| skill-creator           | OK          | OK      | OK      | NO      | 157   | B     |
+```
+
+Grade scale:
+
+- **A** — all checks pass including gotchas
+- **B+** — all required checks pass, missing gotchas (acceptable for newer skills)
+- **B** — missing one optional section
+- **C** — missing required section or over 200 lines
+- **D** — frontmatter issues
+- **F** — broken (missing name, missing description, invalid YAML)
+
+## Phase 4: Three-Layer Defense Audit
+
+Check the top safety rules from AGENTS.md for three-layer coverage:
+
+| Rule                           | Intent (AGENTS.md) | Knowledge (Skill) | Control (Agent/Hook) |
+| ------------------------------ | ------------------ | ----------------- | -------------------- |
+| Never force push main          | ?                  | ?                 | ?                    |
+| Never bypass hooks             | ?                  | ?                 | ?                    |
+| Never expose credentials       | ?                  | ?                 | ?                    |
+| Read before write/edit         | ?                  | ?                 | ?                    |
+| Verify before completion       | ?                  | ?                 | ?                    |
+| Never `git add .`              | ?                  | ?                 | ?                    |
+| Review agents are read-only    | ?                  | ?                 | ?                    |
+| Never fabricate tool output    | ?                  | ?                 | ?                    |
+| Ask before destructive actions | ?                  | ?                 | ?                    |
+
+For each rule:
+
+- **Intent**: grep AGENTS.md for the policy statement
+- **Knowledge**: check if any skill documents the procedure
+- **Control**: check if any agent frontmatter enforces it (tools: false, permission: deny)
+
+Flag rules with intent but no control as **IMPORTANT** gaps.
+
+## Phase 5: AI Governance Audit
+
+Audit AI-facing configuration for token efficiency, rule health, and instruction quality.
+
+### 5a. Token Budget Estimation
+
+Estimate the total token cost of context injected into each command execution:
+
+```bash
+# Base context (always injected)
+echo "=== Base Context ==="
+wc -c AGENTS.md
+wc -c .opencode/memory/project/user.md .opencode/memory/project/tech-stack.md .opencode/memory/project/project.md 2>/dev/null
+echo "=== Agent Prompts ==="
+wc -c .opencode/agent/*.md 2>/dev/null
+```
+
+For each command, estimate total context = Base + Agent prompt + Skills loaded:
+
+| Command | Base | Agent    | Skills Loaded                                          | Est. Tokens | Budget             |
+| ------- | ---- | -------- | ------------------------------------------------------ | ----------- | ------------------ |
+| `/ship` | [N]  | build.md | beads, memory-grounding, workspace-setup, verification | [total]     | [OK/HEAVY/BLOATED] |
+| `/plan` | [N]  | plan.md  | beads, memory-grounding, writing-plans                 | [total]     | [OK/HEAVY/BLOATED] |
+| ...     | ...  | ...      | ...                                                    | ...         | ...                |
+
+**Thresholds:**
+
+- **OK**: < 15k tokens total injected context
+- **HEAVY**: 15-30k tokens (warn — leaves less room for codebase context)
+- **BLOATED**: > 30k tokens (flag — likely causing quality degradation)
+
+Rough token estimate: `bytes / 4` for English text.
+
+### 5b. Rule Echo Detection
+
+Find instructions duplicated across layers:
+
+```bash
+# Find common instruction phrases across AGENTS.md and agent prompts
+# Look for exact or near-duplicate paragraphs
+grep -hF "Never" AGENTS.md .opencode/agent/*.md | sort | uniq -c | sort -rn | head -20
+grep -hF "Always" AGENTS.md .opencode/agent/*.md | sort | uniq -c | sort -rn | head -20
+grep -hF "MUST" AGENTS.md .opencode/agent/*.md | sort | uniq -c | sort -rn | head -20
+```
+
+Also check for:
+
+- Rules in AGENTS.md that are repeated verbatim in agent prompts (redundant — AGENTS.md is already injected)
+- Rules in agent prompts that contradict AGENTS.md (dangerous)
+- Rules in skills that duplicate AGENTS.md content (bloat)
+
+Report:
+
+| Rule Text (truncated)   | Found In            | Count | Issue                       |
+| ----------------------- | ------------------- | ----- | --------------------------- |
+| "Never force push main" | AGENTS.md, build.md | 2     | ECHO — remove from build.md |
+| "Stage specific files"  | AGENTS.md, ship.md  | 2     | ECHO — remove from ship.md  |
+
+### 5c. Instruction Bloat Detection
+
+Flag oversized configuration files:
+
+| File             | Lines | Tokens (est.) | Status            |
+| ---------------- | ----- | ------------- | ----------------- |
+| AGENTS.md        | [N]   | [N]           | [OK/WARN/BLOATED] |
+| [skill]/SKILL.md | [N]   | [N]           | [OK/WARN/BLOATED] |
+| [command].md     | [N]   | [N]           | [OK/WARN/BLOATED] |
+
+**Thresholds:**
+
+- Skills: WARN > 200 lines, BLOATED > 400 lines
+- Commands: WARN > 300 lines, BLOATED > 500 lines
+- AGENTS.md: WARN > 500 lines, BLOATED > 800 lines
+
+### 5d. Compression Opportunities
+
+Identify repeated boilerplate across skills and commands:
+
+````bash
+# Find common blocks across skills
+for f in .opencode/skill/*/SKILL.md; do
+  grep -c "## When to Use" "$f"
+  grep -c "## When NOT to Use" "$f"
+done
+
+# Find repeated code blocks
+grep -rh "```typescript" .opencode/command/*.md | wc -l
+grep -rh "skill({ name:" .opencode/command/*.md | sort | uniq -c | sort -rn | head -10
+````
+
+Flag opportunities:
+
+- Skills that share >50% identical content (candidates for merging or shared base)
+- Commands with identical boilerplate sections (candidates for shared template)
+- Repeated `skill({ name: "X" })` calls across commands (consider making X a dependency)
+
+### AI Governance Report
+
+```text
+## AI Governance Summary
+
+Token Budget:
+- Lightest command: [command] ([N] tokens)
+- Heaviest command: [command] ([N] tokens)
+- Commands over budget: [list]
+
+Rule Health:
+- Echo rules found: [N] (wasted tokens on duplicates)
+- Contradictions found: [N] (CRITICAL)
+- Compression opportunities: [N]
+
+Instruction Bloat:
+- Oversized skills: [N]
+- Oversized commands: [N]
+- AGENTS.md status: [OK/WARN/BLOATED]
+
+Recommendations:
+1. [Most impactful recommendation]
+2. [Second recommendation]
+3. [Third recommendation]
+```
+
+## Phase 6: Agent Tool Restriction Audit
+
+For each agent in `.opencode/agent/*.md`:
+
+1. Read the agent's YAML frontmatter
+2. Check `tools:` restrictions (which tools are disabled)
+3. Check `permission:` restrictions (which commands are denied/asked)
+4. Compare against the agent's stated role
+
+Flag:
+
+- **CRITICAL**: Write-capable agents that should be read-only (review, explore, scout)
+- **IMPORTANT**: Agents with no tool restrictions at all
+- **MINOR**: Agents with restrictions that could be tighter
+
+## Phase 7: Report
+
+Output a health report:
+
+```markdown
+## Health Report
+
+**Date:** [timestamp]
+**Configuration:** [X skills, Y commands, Z agents]
+
+### Summary
+
+| Layer   | Issues Found | Critical | Important | Minor |
+| ------- | ------------ | -------- | --------- | ----- |
+| Refs    | N            | N        | N         | N     |
+| Skills  | N            | N        | N         | N     |
+| Defense | N            | N        | N         | N     |
+| Agents  | N            | N        | N         | N     |
+| TOTAL   | N            | N        | N         | N     |
+
+### Critical Issues
+
+- [list]
+
+### Important Issues
+
+- [list]
+
+### Minor Issues
+
+- [list]
+
+### Recommendations
+
+- [prioritized list of fixes]
+```
+
+If `--fix` flag is provided, auto-fix `safe_auto` issues:
+
+- Remove stale skill references from commands (after confirmation)
+- Add missing `## Gotchas` placeholder sections to skills
+- Fix frontmatter formatting issues
+
+Record findings:
+
+```typescript
+observation({
+  type: "discovery",
+  title: "Health check: [summary]",
+  narrative: "[Key findings and gaps discovered]",
+  concepts: "health, audit, configuration",
+  confidence: "high",
+});
+```
+
+## Related Commands
+
+| Need                | Command            |
+| ------------------- | ------------------ |
+| Review code         | `/review-codebase` |
+| Check project state | `/status`          |
+| Verify a bead       | `/verify <id>`     |

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

@@ -0,0 +1,297 @@
+---
+description: Initialize project planning context (roadmap, state) with optional brownfield analysis
+argument-hint: "[--skip-questions] [--brownfield]"
+agent: build
+---
+
+# Init-Context: $ARGUMENTS
+
+Initialize project planning context files from templates.
+
+## Architecture
+
+**Auto-injected files** (always loaded into every prompt via `instructions[]`):
+- `user.md` — identity, preferences
+- `tech-stack.md` — framework, constraints
+- `project.md` — vision, success criteria, principles
+- `git-context.md` — spatial awareness
+
+**On-demand files** (created by this command, loaded via `memory-read` when needed):
+- `roadmap.md` — phases, milestones, bead planning
+- `state.md` — current position, blockers, next actions
+
+> **Warning:** Do NOT add roadmap.md or state.md to `instructions[]`. Per-prompt injection of too many files causes session OOM crashes. Use `memory-read({ file: "project/roadmap" })` or `memory-read({ file: "project/state" })` when needed.
+
+## Load Skills
+
+```typescript
+skill({ name: "context-initialization" });
+skill({ name: "brainstorming" });
+skill({ name: "verification-before-completion" });
+```
+
+## Parse Arguments
+
+```typescript
+const args = {
+  skipQuestions: $ARGUMENTS.includes("--skip-questions"),
+  brownfield: $ARGUMENTS.includes("--brownfield"),
+  focus: $ARGUMENTS.match(/--focus=(\w+)/)?.[1], // Optional: api, ui, db, etc.
+};
+```
+
+## Phase 1: Discovery
+
+### 1.1 Check Existing Context
+
+Use tilth or Read to check for existing files:
+
+```typescript
+tilth_tilth_files({ pattern: "*.md", scope: ".opencode/memory/project" });
+// Or: Read({ filePath: ".opencode/memory/project/project.md", limit: 20 });
+```
+
+**If planning context exists:**
+
+```
+Existing planning context found:
+- project.md: [exists/size] (auto-injected)
+- roadmap.md: [exists/size] (on-demand)
+- state.md: [exists/size] (on-demand)
+
+Options:
+1. Refresh - Delete and recreate from templates
+2. Update - Keep existing, only update state.md
+3. Skip - Use existing context as-is
+```
+
+Wait for user selection.
+
+### 1.2 Brownfield Codebase Analysis (if --brownfield)
+
+If `--brownfield` flag is set:
+
+```typescript
+skill({ name: "swarm-coordination" });
+
+// Agent 1: Map tech stack
+task({
+  subagent_type: "explore",
+  description: "Analyze tech stack",
+  prompt:
+    "Analyze the codebase technology stack. Write findings to .opencode/memory/project/codebase/tech-analysis.md covering: languages, frameworks, dependencies, build tools. Return file path and line count only.",
+});
+
+// Agent 2: Map architecture
+task({
+  subagent_type: "explore",
+  description: "Analyze architecture",
+  prompt:
+    "Analyze the codebase architecture. Write findings to .opencode/memory/project/codebase/arch-analysis.md covering: patterns, directory structure, entry points. Return file path and line count only.",
+});
+
+// Wait for agents and collect confirmations
+```
+
+## Phase 2: Requirements Gathering
+
+### 2.1 Brainstorming (if not --skip-questions)
+
+```typescript
+if (!args.skipQuestions) {
+  // brainstorming skill already loaded in Load Skills phase
+  // Follow brainstorming process for project vision
+  // Ask questions one at a time (as per brainstorming skill)
+  // Output: Refined vision, success criteria, target users
+}
+```
+
+### 2.2 Quick Mode (if --skip-questions)
+
+Use template defaults with placeholders for:
+
+- Project vision
+- Success criteria
+- Target users
+- Phases
+- Current phase
+
+## Phase 3: Document Creation
+
+### 3.1 Update project.md (auto-injected)
+
+This file is auto-injected into every prompt. Keep it concise.
+
+**Load template:**
+
+```typescript
+Read({ filePath: ".opencode/memory/_templates/project.md" });
+```
+
+**Fill with gathered data:**
+
+- Vision from brainstorming OR template placeholder
+- Success criteria (3-7 measurable outcomes)
+- Target users (primary/secondary)
+- Core principles (convention over config, minimal, extensible)
+- Current phase (from user input or template default)
+
+**Write using memory tools:**
+
+```typescript
+memory-update({ file: "project/project", content: filledContent, mode: "replace" });
+```
+
+### 3.2 Create roadmap.md (on-demand)
+
+This file is NOT auto-injected. Access via `memory-read({ file: "project/roadmap" })`.
+
+**Parse phases from input:**
+
+```typescript
+// Convert user-provided phases into structured roadmap
+// Example: "Discovery, MVP, Launch, Scale" → table rows
+```
+
+**Structure:**
+
+```markdown
+| Phase     | Goal   | Status   | Beads |
+| --------- | ------ | -------- | ----- |
+| [Phase 1] | [Goal] | [Status] | [#]   |
+```
+
+**Write using memory tools:**
+
+```typescript
+memory-update({ file: "project/roadmap", content: roadmapContent, mode: "replace" });
+```
+
+### 3.3 Create state.md (on-demand)
+
+This file is NOT auto-injected. Access via `memory-read({ file: "project/state" })`.
+
+**Initialize with:**
+
+- Active Bead: (blank or from bead context)
+- Status: In Progress
+- Started: [current date]
+- Phase: [from roadmap]
+- Recent Completed Work: (empty table)
+- Active Decisions: (empty table)
+- Blockers: (empty table)
+- Open Questions: (empty table)
+- Next Actions: (empty list)
+
+**Write using memory tools:**
+
+```typescript
+memory-update({ file: "project/state", content: stateContent, mode: "replace" });
+```
+
+### 3.4 Brownfield Analysis Integration (if applicable)
+
+If `--brownfield` analysis was run:
+
+```typescript
+// Append tech/arch findings to project.md Context Notes section
+// Or create separate .opencode/memory/project/codebase/ documents
+```
+
+## Phase 4: Verification & Security
+
+### 4.1 Verify Documents Created
+
+```typescript
+tilth_tilth_files({ pattern: "*.md", scope: ".opencode/memory/project" });
+// Verify each file exists and has content
+Read({ filePath: ".opencode/memory/project/project.md", limit: 5 });
+Read({ filePath: ".opencode/memory/project/roadmap.md", limit: 5 });
+Read({ filePath: ".opencode/memory/project/state.md", limit: 5 });
+```
+
+**Check:**
+
+- [ ] project.md exists and >20 lines
+- [ ] roadmap.md exists and >20 lines
+- [ ] state.md exists and >20 lines
+- [ ] All files are readable
+
+### 4.2 Secret Scan
+
+```bash
+# Scan for accidentally leaked secrets in generated docs
+grep -rE '(sk-[a-zA-Z0-9]{20,}|sk_live_[a-zA-Z0-9]+|AKIA[A-Z0-9]{16}|ghp_[a-zA-Z0-9]{36}|xoxb-[a-zA-Z0-9-]+|-----BEGIN.*PRIVATE KEY)' .opencode/memory/project/*.md 2>/dev/null && SECRETS_FOUND=true || SECRETS_FOUND=false
+```
+
+**If secrets found:** Alert user and pause before proceeding.
+
+### 4.3 Run Verification
+
+```typescript
+// verification-before-completion skill already loaded
+// Run verification checklist:
+// 1. IDENTIFY: Files created, structure valid
+// 2. RUN: Validation commands
+// 3. READ: Check file contents
+// 4. VERIFY: All success criteria met
+// 5. CLAIM: Context initialization complete
+```
+
+## Output
+
+Creates planning context in `.opencode/memory/project/`:
+
+| File         | Purpose                                  | Injection   | Access                                       |
+| ------------ | ---------------------------------------- | ----------- | -------------------------------------------- |
+| `project.md` | Vision, success criteria, principles     | Auto-injected | Updated in-place (already in `instructions[]`) |
+| `roadmap.md` | Phases, milestones, bead planning        | On-demand   | `memory-read({ file: "project/roadmap" })`   |
+| `state.md`   | Current position, blockers, next actions | On-demand   | `memory-read({ file: "project/state" })`     |
+
+**If `--brownfield`:**
+Additional files in `.opencode/memory/project/codebase/`:
+
+- `tech-analysis.md` - Stack and dependencies
+- `arch-analysis.md` - Architecture patterns
+
+## Success Criteria
+
+- [ ] All planning documents created from templates
+- [ ] Documents follow template structure
+- [ ] No secrets leaked in generated files
+- [ ] Files pass basic validation (readable, non-empty)
+- [ ] User informed of next steps and access patterns
+
+## Custom Context (Optional)
+
+Inform user about `.opencode/context/` for additional project-specific context:
+
+```
+Custom context folder available at .opencode/context/
+- Add .md files with architecture decisions, domain knowledge, team agreements
+- This folder is preserved during init --force and upgrade
+
+⚠️  Only add files to instructions[] if they are essential for EVERY prompt.
+    Per-prompt injection adds ~2-4KB each. Too many files cause session OOM.
+    Prefer memory-read() for on-demand access instead.
+```
+
+## Next Steps
+
+After init-context completes:
+
+1. **For new projects:** Use `/plan` to create first implementation plan
+2. **For brownfield:** Review codebase analysis, then `/plan`
+3. **For existing beads:** Use `/resume` to continue tracked work
+4. **For custom context:** Add `.md` files to `.opencode/context/` (on-demand via Read, not auto-injected)
+
+---
+
+## Skill Integration Summary
+
+| Skill                            | When Used                         | Purpose                        |
+| -------------------------------- | --------------------------------- | ------------------------------ |
+| `context-initialization`         | Phase 1                           | Template verification          |
+| `brainstorming`                  | Phase 2 (if not --skip-questions) | Refine vision and requirements |
+| `swarm-coordination`             | Phase 1.2 (if --brownfield)       | Parallel codebase analysis     |
+| `verification-before-completion` | Phase 4                           | Validate created files         |