@hiai-gg/hiai-opencode 0.1.0

package/src/features/builtin-commands/templates/start-work.ts

@@ -0,0 +1,128 @@
+export const START_WORK_TEMPLATE = `You are starting a Bob work session.
+
+## ARGUMENTS
+
+- \`/start-work [plan-name] [--worktree <path>]\`
+  - \`plan-name\` (optional): name or partial match of the plan to start
+  - \`--worktree <path>\` (optional): absolute path to an existing git worktree to work in
+    - If specified and valid: hook pre-sets worktree_path in boulder.json
+    - If specified but invalid: you must run \`git worktree add <path> <branch>\` first
+    - If omitted: work directly in the current project directory (no worktree)
+
+## WHAT TO DO
+
+1. **Find available plans**: Search for Strategist-generated plan files at \`.bob/plans/\`
+
+2. **Check for active boulder state**: Read \`.bob/boulder.json\` if it exists
+
+3. **Decision logic**:
+   - If \`.bob/boulder.json\` exists AND plan is NOT complete (has unchecked boxes):
+     - **APPEND** current session to session_ids
+     - Continue work on existing plan
+   - If no active plan OR plan is complete:
+     - List available plan files
+     - If ONE plan: auto-select it
+     - If MULTIPLE plans: show list with timestamps, ask user to select
+
+4. **Worktree Setup** (ONLY when \`--worktree\` was explicitly specified and \`worktree_path\` not already set in boulder.json):
+   1. \`git worktree list --porcelain\` - see available worktrees
+   2. Create: \`git worktree add <absolute-path> <branch-or-HEAD>\`
+   3. Update boulder.json to add \`"worktree_path": "<absolute-path>"\`
+   4. All work happens inside that worktree directory
+
+5. **Create/Update boulder.json**:
+   \`\`\`json
+   {
+     "active_plan": "/absolute/path/to/plan.md",
+     "started_at": "ISO_TIMESTAMP",
+     "session_ids": ["session_id_1", "session_id_2"],
+     "plan_name": "plan-name",
+     "worktree_path": "/absolute/path/to/git/worktree"
+   }
+   \`\`\`
+
+6. **Read the plan file** and start executing tasks according to guard workflow
+
+## OUTPUT FORMAT
+
+When listing plans for selection:
+\`\`\`
+Available Work Plans
+
+Current Time: {ISO timestamp}
+Session ID: {current session id}
+
+1. [plan-name-1.md] - Modified: {date} - Progress: 3/10 tasks
+2. [plan-name-2.md] - Modified: {date} - Progress: 0/5 tasks
+
+Which plan would you like to work on? (Enter number or plan name)
+\`\`\`
+
+When resuming existing work:
+\`\`\`
+Resuming Work Session
+
+Active Plan: {plan-name}
+Progress: {completed}/{total} tasks
+Sessions: {count} (appending current session)
+Worktree: {worktree_path}
+
+Reading plan and continuing from last incomplete task...
+\`\`\`
+
+When auto-selecting single plan:
+\`\`\`
+Starting Work Session
+
+Plan: {plan-name}
+Session ID: {session_id}
+Started: {timestamp}
+Worktree: {worktree_path}
+
+Reading plan and beginning execution...
+\`\`\`
+
+## CRITICAL
+
+- The session_id is injected by the hook - use it directly
+- Always update boulder.json BEFORE starting work
+- If worktree_path is set in boulder.json, all work happens inside that worktree directory
+- Read the FULL plan file before delegating any tasks
+- Follow guard delegation protocols (7-section format)
+
+## TASK BREAKDOWN (MANDATORY)
+
+After reading the plan file, you MUST decompose every plan task into granular, implementation-level sub-steps and register ALL of them as task/todo items BEFORE starting any work.
+
+**How to break down**:
+- Each plan checkbox item (e.g., \`- [ ] Add user authentication\`) must be split into concrete, actionable sub-tasks
+- Sub-tasks should be specific enough that each one touches a clear set of files/functions
+- Include: file to modify, what to change, expected behavior, and how to verify
+- Do NOT leave any task vague - "implement feature X" is NOT acceptable; "add validateToken() to src/auth/middleware.ts that checks JWT expiry and returns 401" IS acceptable
+
+**Example breakdown**:
+Plan task: \`- [ ] Add rate limiting to API\`
+→ Todo items:
+  1. Create \`src/middleware/rate-limiter.ts\` with sliding window algorithm (max 100 req/min per IP)
+  2. Add RateLimiter middleware to \`src/app.ts\` router chain, before auth middleware
+  3. Add rate limit headers (X-RateLimit-Limit, X-RateLimit-Remaining) to response in \`rate-limiter.ts\`
+  4. Add test: verify 429 response after exceeding limit in \`src/middleware/rate-limiter.test.ts\`
+  5. Add test: verify headers are present on normal responses
+
+Register these as task/todo items so progress is tracked and visible throughout the session.
+
+## WORKTREE COMPLETION
+
+When working in a worktree (\`worktree_path\` is set in boulder.json) and ALL plan tasks are complete:
+1. Commit all remaining changes in the worktree
+2. **Sync .bob state back**: Copy \`.bob/\` from the worktree to the main repo before removal.
+   This is CRITICAL when \`.bob/\` is gitignored - state written during worktree execution would otherwise be lost.
+   \`\`\`bash
+   cp -r <worktree-path>/.bob/* <main-repo>/.bob/ 2>/dev/null || true
+   \`\`\`
+3. Switch to the main working directory (the original repo, NOT the worktree)
+4. Merge the worktree branch into the current branch: \`git merge <worktree-branch>\`
+5. If merge succeeds, clean up: \`git worktree remove <worktree-path>\`
+6. Remove the boulder.json state
+
+This is the DEFAULT behavior when \`--worktree\` was used. Skip merge only if the user explicitly instructs otherwise (e.g., asks to create a PR instead).`

package/src/features/builtin-commands/templates/stop-continuation.ts

@@ -0,0 +1,13 @@
+export const STOP_CONTINUATION_TEMPLATE = `Stop all continuation mechanisms for the current session.
+
+This command will:
+1. Stop the todo-continuation-enforcer from automatically continuing incomplete tasks
+2. Cancel any active Ralph Loop
+3. Clear the boulder state for the current project
+
+After running this command:
+- The session will not auto-continue when idle
+- You can manually continue work when ready
+- The stop state is per-session and clears when the session ends
+
+Use this when you need to pause automated continuation and take manual control.`

package/src/features/builtin-commands/types.ts

@@ -0,0 +1,9 @@
+import type { CommandDefinition } from "../claude-code-command-loader"
+
+export type BuiltinCommandName = "init-deep" | "ralph-loop" | "cancel-ralph" | "ulw-loop" | "refactor" | "start-work" | "stop-continuation" | "handoff" | "remove-ai-slops"
+
+export interface BuiltinCommandConfig {
+  disabled_commands?: BuiltinCommandName[]
+}
+
+export type BuiltinCommands = Record<string, CommandDefinition>

package/src/features/builtin-skills/index.ts

@@ -0,0 +1,2 @@
+export * from "./types"
+export { createBuiltinSkills, type CreateBuiltinSkillsOptions } from "./skills"

package/src/features/builtin-skills/materialize.ts

@@ -0,0 +1,338 @@
+import {
+  cpSync,
+  existsSync,
+  mkdirSync,
+  readdirSync,
+  readFileSync,
+  rmSync,
+  writeFileSync,
+} from "node:fs"
+import { join } from "node:path"
+
+import type { BuiltinSkill } from "./types"
+import { getOpenCodeConfigDir } from "../../shared/opencode-config-dir"
+
+const GENERATED_MARKER = "<!-- Generated by hiai-opencode builtin skill materializer. -->"
+const MANAGED_SKILL_METADATA = ".hiai-skill.json"
+const LEGACY_MANAGED_DIR_MARKER = ".hiai-plugin-skill"
+
+type ManagedSkillOrigin = "builtin" | "plugin"
+
+interface ManagedSkillMetadata {
+  name: string
+  origin: ManagedSkillOrigin
+  generatedBy: "hiai-opencode"
+  assembledPath: string
+  sourcePath: string
+}
+
+interface SkillRegistryEntry {
+  name: string
+  origin: ManagedSkillOrigin
+  sourcePath: string
+  assembledPath: string
+}
+
+function escapeYamlString(value: string): string {
+  return `"${value.replace(/\\/g, "\\\\").replace(/"/g, '\\"')}"`
+}
+
+function buildSkillFrontmatter(skill: BuiltinSkill): string {
+  const lines = [
+    "---",
+    `name: ${escapeYamlString(skill.name)}`,
+    `description: ${escapeYamlString(skill.description)}`,
+  ]
+
+  if (skill.model) lines.push(`model: ${escapeYamlString(skill.model)}`)
+  if (skill.agent) lines.push(`agent: ${escapeYamlString(skill.agent)}`)
+  if (skill.argumentHint) {
+    lines.push(`argument-hint: ${escapeYamlString(skill.argumentHint)}`)
+  }
+  if (skill.subtask) lines.push("subtask: true")
+
+  lines.push("---", "", GENERATED_MARKER, "", skill.template.trim(), "")
+  return lines.join("\n")
+}
+
+function shouldWriteSkillFile(skillFilePath: string): boolean {
+  if (!existsSync(skillFilePath)) return true
+
+  try {
+    const existing = readFileSync(skillFilePath, "utf-8")
+    return existing.includes(GENERATED_MARKER)
+  } catch {
+    return false
+  }
+}
+
+function getSkillLayout() {
+  const configDir = getOpenCodeConfigDir({ binary: "opencode" })
+  const assembledSkillsDir = join(configDir, "skills")
+  const sourceRootDir = join(configDir, ".hiai", "skills")
+  const builtinSourceDir = join(sourceRootDir, "builtin")
+  const pluginSourceDir = join(sourceRootDir, "plugin")
+
+  mkdirSync(assembledSkillsDir, { recursive: true })
+  mkdirSync(builtinSourceDir, { recursive: true })
+  mkdirSync(pluginSourceDir, { recursive: true })
+
+  return {
+    configDir,
+    assembledSkillsDir,
+    sourceRootDir,
+    builtinSourceDir,
+    pluginSourceDir,
+  }
+}
+
+function writeManagedSkillMetadata(
+  targetDir: string,
+  metadata: ManagedSkillMetadata,
+): void {
+  writeFileSync(
+    join(targetDir, MANAGED_SKILL_METADATA),
+    `${JSON.stringify(metadata, null, 2)}\n`,
+    "utf-8",
+  )
+}
+
+function readManagedSkillMetadata(targetDir: string): ManagedSkillMetadata | null {
+  const metadataPath = join(targetDir, MANAGED_SKILL_METADATA)
+  if (!existsSync(metadataPath)) {
+    return null
+  }
+
+  try {
+    return JSON.parse(readFileSync(metadataPath, "utf-8")) as ManagedSkillMetadata
+  } catch {
+    return null
+  }
+}
+
+function isLegacyManagedSkillDir(targetDir: string, origin: ManagedSkillOrigin): boolean {
+  if (origin === "plugin" && existsSync(join(targetDir, LEGACY_MANAGED_DIR_MARKER))) {
+    return true
+  }
+
+  if (origin === "builtin") {
+    const skillFilePath = join(targetDir, "SKILL.md")
+    if (!existsSync(skillFilePath)) {
+      return false
+    }
+
+    try {
+      return readFileSync(skillFilePath, "utf-8").includes(GENERATED_MARKER)
+    } catch {
+      return false
+    }
+  }
+
+  return false
+}
+
+function shouldSyncManagedSkillDir(targetDir: string, origin: ManagedSkillOrigin): boolean {
+  if (!existsSync(targetDir)) return true
+
+  const metadata = readManagedSkillMetadata(targetDir)
+  if (metadata?.generatedBy === "hiai-opencode" && metadata.origin === origin) {
+    return true
+  }
+
+  return isLegacyManagedSkillDir(targetDir, origin)
+}
+
+function shouldCleanupManagedSkillDir(targetDir: string, origin: ManagedSkillOrigin): boolean {
+  const metadata = readManagedSkillMetadata(targetDir)
+  if (metadata?.generatedBy === "hiai-opencode" && metadata.origin === origin) {
+    return true
+  }
+
+  return isLegacyManagedSkillDir(targetDir, origin)
+}
+
+function cleanupRemovedManagedSkillDirs(
+  rootDir: string,
+  origin: ManagedSkillOrigin,
+  expectedSkillNames: Set<string>,
+): void {
+  if (!existsSync(rootDir)) {
+    return
+  }
+
+  for (const entry of readdirSync(rootDir, { withFileTypes: true })) {
+    if (!entry.isDirectory()) continue
+    if (expectedSkillNames.has(entry.name)) continue
+
+    const targetDir = join(rootDir, entry.name)
+    if (shouldCleanupManagedSkillDir(targetDir, origin)) {
+      rmSync(targetDir, { recursive: true, force: true })
+    }
+  }
+}
+
+function writeSkillRegistry(configDir: string, entries: SkillRegistryEntry[]): void {
+  const registryDir = join(configDir, ".hiai")
+  const assembledSkillsDir = join(configDir, "skills")
+
+  mkdirSync(registryDir, { recursive: true })
+  mkdirSync(assembledSkillsDir, { recursive: true })
+
+  const sortedEntries = [...entries].sort((left, right) => left.name.localeCompare(right.name))
+  const payload = {
+    generatedBy: "hiai-opencode",
+    generatedAt: new Date().toISOString(),
+    summary: {
+      total: sortedEntries.length,
+      builtin: sortedEntries.filter((entry) => entry.origin === "builtin").length,
+      plugin: sortedEntries.filter((entry) => entry.origin === "plugin").length,
+    },
+    layout: {
+      assembledSkillsDir,
+      builtinSourceDir: join(registryDir, "skills", "builtin"),
+      pluginSourceDir: join(registryDir, "skills", "plugin"),
+    },
+    entries: sortedEntries,
+  }
+
+  writeFileSync(
+    join(registryDir, "skill-registry.json"),
+    `${JSON.stringify(payload, null, 2)}\n`,
+    "utf-8",
+  )
+
+  const readme = [
+    "# Hiai Skill Layout",
+    "",
+    "This directory tree is intentionally split into two layers:",
+    "",
+    "- `.opencode/.hiai/skills/plugin` contains mirrored plugin skill source directories.",
+    "- `.opencode/.hiai/skills/builtin` contains generated built-in skill source directories.",
+    "- `.opencode/skills` is the assembled working view that OpenCode indexes.",
+    "",
+    "See `.opencode/.hiai/skill-registry.json` for the exact origin of every assembled skill.",
+    "",
+  ].join("\n")
+
+  writeFileSync(join(assembledSkillsDir, "README.md"), readme, "utf-8")
+}
+
+export function materializeBuiltinSkills(skills: BuiltinSkill[]): void {
+  const { assembledSkillsDir, builtinSourceDir } = getSkillLayout()
+  const expectedSkillNames = new Set(skills.map((skill) => skill.name))
+
+  for (const skill of skills) {
+    const sourceSkillDir = join(builtinSourceDir, skill.name)
+    const sourceSkillFilePath = join(sourceSkillDir, "SKILL.md")
+    const assembledSkillDir = join(assembledSkillsDir, skill.name)
+    const assembledSkillFilePath = join(assembledSkillDir, "SKILL.md")
+    const content = buildSkillFrontmatter(skill)
+
+    mkdirSync(sourceSkillDir, { recursive: true })
+    mkdirSync(assembledSkillDir, { recursive: true })
+
+    if (!shouldWriteSkillFile(sourceSkillFilePath) || !shouldWriteSkillFile(assembledSkillFilePath)) {
+      continue
+    }
+
+    writeFileSync(sourceSkillFilePath, content, "utf-8")
+    writeFileSync(assembledSkillFilePath, content, "utf-8")
+
+    writeManagedSkillMetadata(sourceSkillDir, {
+      name: skill.name,
+      origin: "builtin",
+      generatedBy: "hiai-opencode",
+      sourcePath: sourceSkillDir,
+      assembledPath: assembledSkillDir,
+    })
+    writeManagedSkillMetadata(assembledSkillDir, {
+      name: skill.name,
+      origin: "builtin",
+      generatedBy: "hiai-opencode",
+      sourcePath: sourceSkillDir,
+      assembledPath: assembledSkillDir,
+    })
+  }
+
+  cleanupRemovedManagedSkillDirs(builtinSourceDir, "builtin", expectedSkillNames)
+  cleanupRemovedManagedSkillDirs(assembledSkillsDir, "builtin", expectedSkillNames)
+}
+
+export function materializePluginSkillDirectories(pluginRootDir: string): void {
+  const sourceSkillsDir = join(pluginRootDir, "skills")
+  if (!existsSync(sourceSkillsDir)) {
+    return
+  }
+
+  const { assembledSkillsDir, pluginSourceDir, configDir } = getSkillLayout()
+  const registryEntries: SkillRegistryEntry[] = []
+  const expectedSkillNames = new Set<string>()
+
+  for (const entry of readdirSync(sourceSkillsDir, { withFileTypes: true })) {
+    if (!entry.isDirectory()) continue
+    if (entry.name === "tmp") continue
+
+    expectedSkillNames.add(entry.name)
+
+    const sourceDir = join(sourceSkillsDir, entry.name)
+    const mirroredSourceDir = join(pluginSourceDir, entry.name)
+    const assembledDir = join(assembledSkillsDir, entry.name)
+
+    if (
+      !shouldSyncManagedSkillDir(mirroredSourceDir, "plugin") ||
+      !shouldSyncManagedSkillDir(assembledDir, "plugin")
+    ) {
+      continue
+    }
+
+    rmSync(mirroredSourceDir, { recursive: true, force: true })
+    rmSync(assembledDir, { recursive: true, force: true })
+
+    cpSync(sourceDir, mirroredSourceDir, { recursive: true, force: true })
+    cpSync(sourceDir, assembledDir, { recursive: true, force: true })
+
+    writeManagedSkillMetadata(mirroredSourceDir, {
+      name: entry.name,
+      origin: "plugin",
+      generatedBy: "hiai-opencode",
+      sourcePath: sourceDir,
+      assembledPath: assembledDir,
+    })
+    writeManagedSkillMetadata(assembledDir, {
+      name: entry.name,
+      origin: "plugin",
+      generatedBy: "hiai-opencode",
+      sourcePath: sourceDir,
+      assembledPath: assembledDir,
+    })
+
+    registryEntries.push({
+      name: entry.name,
+      origin: "plugin",
+      sourcePath: sourceDir,
+      assembledPath: assembledDir,
+    })
+  }
+
+  cleanupRemovedManagedSkillDirs(pluginSourceDir, "plugin", expectedSkillNames)
+  cleanupRemovedManagedSkillDirs(assembledSkillsDir, "plugin", expectedSkillNames)
+
+  for (const builtinEntry of readdirSync(assembledSkillsDir, { withFileTypes: true })) {
+    if (!builtinEntry.isDirectory()) continue
+
+    const assembledDir = join(assembledSkillsDir, builtinEntry.name)
+    const metadata = readManagedSkillMetadata(assembledDir)
+    if (metadata?.generatedBy !== "hiai-opencode" || metadata.origin !== "builtin") {
+      continue
+    }
+
+    registryEntries.push({
+      name: metadata.name,
+      origin: "builtin",
+      sourcePath: metadata.sourcePath,
+      assembledPath: metadata.assembledPath,
+    })
+  }
+
+  writeSkillRegistry(configDir, registryEntries)
+}

package/src/features/builtin-skills/skills/ai-slop-remover.ts

@@ -0,0 +1,145 @@
+import type { BuiltinSkill } from "../types"
+
+export const aiSlopRemoverSkill: BuiltinSkill = {
+	name: "ai-slop-remover",
+	description:
+		"Removes AI-generated code smells from a SINGLE file while preserving functionality. For multiple files, call in PARALLEL per file.",
+	template: `You are an expert code refactorer specializing in removing AI-generated "slop" patterns while STRICTLY preserving functionality.
+
+**INPUT**: Exactly ONE file path. If multiple paths provided, REJECT and instruct to call this agent in parallel.
+
+---
+
+## DETECTION CRITERIA (Specific)
+
+### 1. Obvious Comments (EXCLUDE: BDD comments like #given, #when, #then, #when/then)
+
+**REMOVE**:
+- Comments restating the code: \`x += 1  # increment x\`
+- Docstrings on trivial methods: \`"""Returns the name."""\` for \`def get_name(): return self.name\`
+- Section dividers: \`# ===== HELPER FUNCTIONS =====\`
+- Commented-out code blocks
+- \`# TODO: future enhancement\` without concrete plan
+- \`# Note: this is important\` without explaining WHY
+
+**KEEP**:
+- Comments explaining WHY (business logic, edge cases, workarounds)
+- Links to issues/tickets: \`# See SPR-1234\`
+- Non-obvious algorithm explanations
+- Regex explanations
+- Matches to existing code style
+
+### 2. Over-Defensive Code
+
+**REMOVE**:
+- Null checks for values that CANNOT be None (e.g., Django request in view)
+- \`if x is not None and x.attr is not None:\` when x is guaranteed
+- Try-except around code that can't raise (e.g., dict literal access)
+- \`isinstance()\` checks for statically typed parameters
+- Default values for required parameters: \`def foo(x: str = "")\` when empty string is invalid
+- Backward-compat shims: \`_old_name = new_name  # deprecated\`
+- \`# removed\` or \`# deleted\` comments for removed code
+- Re-exports of unused items
+- Verbose, duplicated, or redundant code / test cases
+
+**KEEP**:
+- Validation at system boundaries (user input, external API responses)
+- Error handling for I/O operations
+- Null checks for nullable DB fields
+- assertions in test code to matching type expectations
+
+### 3. Spaghetti Nesting (2+ levels deep)
+
+**REFACTOR**:
+- Nested if-else chains -> early returns / guard clauses
+- \`if x: if y: if z:\` -> \`if not x: return\` / \`if not y: return\`
+- Nested loops with conditionals -> extract to helper OR use comprehensions
+- Complex ternary \`a if b else (c if d else e)\` -> explicit if-else
+
+---
+
+## PROCESS
+
+### Step 1: Read & Analyze
+Read the file. Identify ALL slop instances with line numbers.
+
+### Step 2: Deep Consideration (CRITICAL)
+For EACH identified issue, think:
+- **Functionality Impact**: Will removing this change behavior? If ANY doubt, SKIP.
+- **Test Coverage**: Are there tests that might break? If uncertain, SKIP.
+- **Context Dependency**: Is this "slop" actually necessary for this specific codebase? (e.g., defensive code for known flaky external API)
+- **Readability Trade-off**: Will removal make code LESS readable? If yes, SKIP.
+
+**RULE**: When in doubt, DO NOT CHANGE. False negatives are better than breaking code.
+
+### Step 3: Execute Changes
+Make changes using Edit tool. One logical change at a time.
+
+### Step 4: Detailed Report
+
+**OUTPUT FORMAT**:
+
+\`\`\`
+## AI Slop Removed: {filename}
+
+### Analysis Summary
+- Total issues found: N
+- Issues fixed: M
+- Issues skipped (safety): K
+
+### Changes Made
+
+#### Change 1: [Category] Line X-Y
+**Before**: [original code snippet]
+**After**: [modified code snippet]
+**Why this is slop**: [Explain why this pattern is problematic]
+**Why safe to remove**: [Explain why functionality is preserved]
+**Impact**: None - purely cosmetic improvement
+
+---
+
+### Skipped Issues (Preserved for Safety)
+
+#### Skipped 1: Line X
+**Reason**: [Why you chose not to change this]
+
+### Summary
+- Removed N obvious comments
+- Simplified M defensive patterns
+- Flattened K nested structures
+- Preserved L patterns that looked like slop but serve purpose
+\`\`\`
+
+---
+
+## SAFETY RULES
+
+1. **NEVER remove error handling for I/O, network, or file operations**
+2. **NEVER simplify validation for user input or external data**
+3. **NEVER change public API signatures**
+4. **NEVER remove type hints (even redundant-looking ones)**
+5. **If a pattern appears in multiple places, it might be intentional - ASK before bulk removal**
+6. **Preserve all BDD test comments (#given, #when, #then)**
+
+When finished, your report should be detailed enough that a reviewer can understand EXACTLY what changed and feel confident the changes are safe.
+
+---
+
+## WHEN NO SLOP FOUND
+
+If the file is clean, report:
+
+\`\`\`
+## AI Slop Analysis: {filename}
+
+### Result: No AI Slop Detected
+
+This file is clean. Here's why:
+
+**Comments**: N comments found, all explain WHY not WHAT
+**Defensive Code**: Null checks present are appropriate (e.g., checks external API response)
+**Code Structure**: Maximum nesting depth acceptable, early returns used appropriately
+
+**Conclusion**: This code appears to be human-written or well-reviewed AI code. No changes needed.
+\`\`\``,
+}