@hung319/opencode-hive 1.3.1

package/skills/agents-md-mastery/SKILL.md

@@ -0,0 +1,252 @@
+---
+name: agents-md-mastery
+description: "Use when bootstrapping, updating, or reviewing AGENTS.md — teaches what makes effective agent memory, how to structure sections, signal vs noise filtering, and when to prune stale entries"
+---
+
+# AGENTS.md Mastery
+
+## Overview
+
+**AGENTS.md is pseudo-memory loaded at session start.** Every line shapes agent behavior for the entire session. Quality beats quantity. Write for agents, not humans.
+
+Unlike code comments or READMEs, AGENTS.md entries persist across all agent sessions. A bad entry misleads agents hundreds of times. A missing entry causes the same mistake repeatedly.
+
+**Core principle:** Optimize for agent comprehension and behavioral change, not human readability.
+
+## The Iron Law
+
+```
+EVERY ENTRY MUST CHANGE AGENT BEHAVIOR
+```
+
+If an entry doesn't:
+- Prevent a specific mistake
+- Enable a capability the agent would otherwise miss
+- Override a default assumption that breaks in this codebase
+
+...then it doesn't belong in AGENTS.md.
+
+**Test:** Would a fresh agent session make a mistake without this entry? If no → noise.
+
+## When to Use
+
+| Trigger | Action |
+|---------|--------|
+| New project bootstrap | Write initial AGENTS.md with build/test/style basics |
+| Feature completion | Sync new learnings via `hive_agents_md` tool |
+| Periodic review | Audit for stale/redundant entries (quarterly) |
+| Quality issues | Agent repeating mistakes? Check if AGENTS.md has the fix |
+
+## What Makes Good Agent Memory
+
+### Signal Entries (Keep)
+
+✅ **Project-specific conventions:**
+- "We use Zustand, not Redux — never add Redux"
+- "Auth lives in `/lib/auth` — never create auth elsewhere"
+- "Run `bun test` not `npm test` (we don't use npm)"
+
+✅ **Non-obvious patterns:**
+- "Use `.js` extension for local imports (ESM requirement)"
+- "Worktrees don't share `node_modules` — run `bun install` in each"
+- "SandboxConfig is in `dockerSandboxService.ts`, NOT `types.ts`"
+
+✅ **Gotchas that break builds:**
+- "Never use `ensureDirSync` — doesn't exist. Use `ensureDir` (sync despite name)"
+- "Import from `../utils/paths.js` not `./paths` (ESM strict)"
+
+### Noise Entries (Remove)
+
+❌ **Agent already knows:**
+- "This project uses TypeScript" (agent detects from files)
+- "We follow semantic versioning" (universal convention)
+- "Use descriptive variable names" (generic advice)
+
+❌ **Irrelevant metadata:**
+- "Created on January 2024"
+- "Originally written by X"
+- "License: MIT" (in LICENSE file already)
+
+❌ **Describes what code does:**
+- "FeatureService manages features" (agent can read code)
+- "The system uses git worktrees" (observable from commands)
+
+### Rule of Thumb
+
+**Signal:** Changes how agent acts  
+**Noise:** Documents what agent observes
+
+## Section Structure for Fast Comprehension
+
+Agents read AGENTS.md top-to-bottom once at session start. Put high-value info first:
+
+```markdown
+# Project Name
+
+## Build & Test Commands
+# ← Agents need this IMMEDIATELY
+bun run build
+bun run test
+bun run release:check
+
+## Code Style
+# ← Prevents syntax/import errors
+- Semicolons: Yes
+- Quotes: Single
+- Imports: Use `.js` extension
+
+## Architecture
+# ← Key directories, where things live
+packages/
+├── hive-core/      # Shared logic
+└── opencode-hive/  # Plugin
+
+## Important Patterns
+# ← How to do common tasks correctly
+Use `readText` from paths.ts, not fs.readFileSync
+
+## Gotchas & Anti-Patterns
+# ← Things that break or mislead
+NEVER use `ensureDirSync` — doesn't exist
+```
+
+**Keep total under 500 lines.** Beyond that, agents lose focus and miss critical entries.
+
+## The Sync Workflow
+
+After completing a feature, sync learnings to AGENTS.md:
+
+1. **Trigger sync:**
+   ```typescript
+   hive_agents_md({ action: 'sync', feature: 'feature-name' })
+   ```
+
+2. **Review each proposal:**
+   - Read the proposed change
+   - Ask: "Does this change agent behavior?"
+   - Check: Is this already obvious from code/files?
+
+3. **Accept signal, reject noise:**
+   - ❌ "TypeScript is used" → Agent detects this
+   - ✅ "Use `.js` extension for imports" → Prevents build failures
+
+4. **Apply approved changes:**
+   ```typescript
+   hive_agents_md({ action: 'apply' })
+   ```
+
+**Warning:** Don't auto-approve all proposals. One bad entry pollutes all future sessions.
+
+## When to Prune
+
+Remove entries when they become:
+
+**Outdated:**
+- "We use Redux" → Project migrated to Zustand
+- "Node 16 compatibility required" → Now on Node 22
+
+**Redundant:**
+- "Use single quotes" + "Strings use single quotes" → Keep one
+- Near-duplicates in different sections
+
+**Too generic:**
+- "Write clear code" → Applies to any project
+- "Test your changes" → Universal advice
+
+**Describing code:**
+- "TaskService manages tasks" → Agent can read `TaskService` class
+- "Worktrees are in `.hive/.worktrees/`" → Observable from filesystem
+
+**Proven unnecessary:**
+- Entry added 6 months ago, but agents haven't hit that issue since
+
+## Red Flags
+
+| Warning Sign | Why It's Bad | Fix |
+|-------------|-------------|-----|
+| AGENTS.md > 800 lines | Agents lose focus, miss critical info | Prune aggressively |
+| Describes what code does | Agent can read code | Remove descriptions |
+| Missing build/test commands | First thing agents need | Add at top |
+| No gotchas section | Agents repeat past mistakes | Document failure modes |
+| Generic best practices | Doesn't change behavior | Remove or make specific |
+| Outdated patterns | Misleads agents | Prune during sync |
+
+## Anti-Patterns
+
+| Anti-Pattern | Better Approach |
+|-------------|----------------|
+| "Document everything" | Document only what changes behavior |
+| "Keep for historical record" | Version control is history |
+| "Might be useful someday" | Add when proven necessary |
+| "Explains the system" | Agents read code for that |
+| "Comprehensive reference" | AGENTS.md is a filter, not docs |
+
+## Good Examples
+
+**Build Commands (High value, agents need immediately):**
+```markdown
+## Build & Test Commands
+bun run build              # Build all packages
+bun run test               # Run all tests
+bun run release:check      # Full CI check
+```
+
+**Project-Specific Convention (Prevents mistakes):**
+```markdown
+## Code Style
+- Imports: Use `.js` extension for local imports (ESM requirement)
+- Paths: Import from `../utils/paths.js` never `./paths`
+```
+
+**Non-Obvious Gotcha (Prevents build failure):**
+```markdown
+## Important Patterns
+Use `ensureDir` from paths.ts — sync despite name
+NEVER use `ensureDirSync` (doesn't exist)
+```
+
+## Bad Examples
+
+**Generic advice (agent already knows):**
+```markdown
+## Best Practices
+- Use meaningful variable names
+- Write unit tests
+- Follow DRY principle
+```
+
+**Describes code (agent can read it):**
+```markdown
+## Architecture
+The FeatureService class manages features. It has methods
+for create, read, update, and delete operations.
+```
+
+**Irrelevant metadata:**
+```markdown
+## Project History
+Created in January 2024 by the platform team.
+Originally built for internal use.
+```
+
+## Verification
+
+Before finalizing AGENTS.md updates:
+
+- [ ] Every entry answers: "What mistake does this prevent?"
+- [ ] No generic advice that applies to all projects
+- [ ] Build/test commands are first
+- [ ] Gotchas section exists and is populated
+- [ ] Total length under 500 lines (800 absolute max)
+- [ ] No entries describing what code does
+- [ ] Fresh agent session would benefit from each entry
+
+## Summary
+
+AGENTS.md is **behavioral memory**, not documentation:
+- Write for agents, optimize for behavior change
+- Signal = prevents mistakes, Noise = describes observables
+- Sync after features, prune quarterly
+- Test: Would agent make a mistake without this entry?
+
+**Quality > quantity. Every line counts.**

package/skills/brainstorming/SKILL.md

@@ -0,0 +1,53 @@
+---
+name: brainstorming
+description: "Use before any creative work - creating features, building components, adding functionality, or modifying behavior. Explores user intent, requirements and design before implementation."
+---
+
+# Brainstorming Ideas Into Designs
+
+## Overview
+
+Help turn ideas into fully formed designs and specs through natural collaborative dialogue.
+
+Start by understanding the current project context, then ask questions one at a time to refine the idea. Once you understand what you're building, present the design in small sections (200-300 words), checking after each section whether it looks right so far.
+
+## The Process
+
+**Understanding the idea:**
+- Check out the current project state first (files, docs, recent commits)
+- Ask questions one at a time to refine the idea
+- Prefer multiple choice questions when possible, but open-ended is fine too
+- Only one question per message - if a topic needs more exploration, break it into multiple questions
+- Focus on understanding: purpose, constraints, success criteria
+
+**Exploring approaches:**
+- Propose 2-3 different approaches with trade-offs
+- Present options conversationally with your recommendation and reasoning
+- Lead with your recommended option and explain why
+
+**Presenting the design:**
+- Once you believe you understand what you're building, present the design
+- Break it into sections of 200-300 words
+- Ask after each section whether it looks right so far
+- Cover: architecture, components, data flow, error handling, testing
+- Be ready to go back and clarify if something doesn't make sense
+
+## After the Design
+
+**Documentation:**
+- Write the validated design to `docs/plans/YYYY-MM-DD-<topic>-design.md`
+- Commit the design document to git
+
+**Implementation (if continuing):**
+- Ask: "Ready to set up for implementation?"
+- Use `hive_skill:writing-plans` to create detailed implementation plan
+
+## Key Principles
+
+- **One question at a time** - Don't overwhelm with multiple questions
+- **Multiple choice preferred** - Easier to answer than open-ended when possible
+- **YAGNI ruthlessly** - Remove unnecessary features from all designs
+- **Explore alternatives** - Always propose 2-3 approaches before settling
+- **Incremental validation** - Present design in sections, validate each
+- **Be flexible** - Go back and clarify when something doesn't make sense
+- **Challenge assumptions** - Surface fragile assumptions, ask what changes if they fail, offer lean fallback options

package/skills/code-reviewer/SKILL.md

@@ -0,0 +1,208 @@
+---
+name: code-reviewer
+description: Use when reviewing implementation changes against an approved plan or task (especially before merging or between Hive tasks) to catch missing requirements, YAGNI, dead code, and risky patterns
+---
+
+# Code Reviewer
+
+## Overview
+
+This skill teaches a reviewer to evaluate implementation changes for:
+- Adherence to the approved plan/task (did we build what we said?)
+- Correctness (does it work, including edge cases?)
+- Simplicity (YAGNI, dead code, over-abstraction)
+- Risk (security, performance, maintainability)
+
+**Core principle:** The best change is the smallest correct change that satisfies the plan.
+
+## Iron Laws
+
+- Review against the task/plan first. Code quality comes second.
+- Bias toward deletion and simplification. Every extra line is a liability.
+- Prefer changes that leverage existing patterns and dependencies.
+- Be specific: cite file paths and (when available) line numbers.
+- Do not invent requirements. If the plan/task is ambiguous, mark it and request clarification.
+
+## What Inputs You Need
+
+Minimum:
+- The task intent (1-3 sentences)
+- The plan/task requirements (or a link/path to plan section)
+- The code changes (diff or list of changed files)
+
+If available (recommended):
+- Acceptance criteria / verification steps from the plan
+- Test output or proof the change was verified
+- Any relevant context files (design decisions, constraints)
+
+## Review Process (In Order)
+
+### 1) Identify Scope
+
+1. List all files changed.
+2. For each file, state why it changed (what requirement it serves).
+3. Flag any changes that do not map to the task/plan.
+
+**Rule:** If you cannot map a change to a requirement, treat it as suspicious until justified.
+
+### 2) Plan/Task Adherence (Non-Negotiable)
+
+Create a simple checklist:
+- What the task says must happen
+- Evidence in code/tests that it happens
+
+Flag as issues:
+- Missing requirements (implemented behavior does not match intent)
+- Partial implementation with no follow-up task (TODO-driven shipping)
+- Behavior changes that are not in the plan/task
+
+### 3) Correctness Layer
+
+Review for:
+- Edge cases and error paths
+- Incorrect assumptions about inputs/types
+- Inconsistent behavior across platforms/environments
+- Broken invariants (e.g., state can become invalid)
+
+Prefer "fail fast, fail loud": invalid states should become clear errors, not silent fallbacks.
+
+### 4) Simplicity / YAGNI Layer
+
+Be ruthless and concrete:
+- Remove dead branches, unused flags/options, unreachable code
+- Remove speculative TODOs and "reserved for future" scaffolding
+- Remove comments that restate the code or narrate obvious steps
+- Inline one-off abstractions (helpers/classes/interfaces used once)
+- Replace cleverness with obvious code
+- Reduce nesting with guard clauses / early returns
+
+Prefer clarity over brevity:
+- Avoid nested ternary operators; use `if/else` or `switch` when branches matter
+- Avoid dense one-liners that hide intent or make debugging harder
+
+### 4b) De-Slop Pass (AI Artifacts / Style Drift)
+
+Scan the diff (not just the final code) for AI-generated slop introduced in this branch:
+- Extra comments that a human would not add, or that do not match the file's tone
+- Defensive checks or try/catch blocks that are abnormal for that area of the codebase
+  - Especially swallowed errors ("ignore and continue") and silent fallbacks
+  - Especially redundant validation in trusted internal codepaths
+- TypeScript escape hatches used to dodge type errors (`as any`, `as unknown as X`) without necessity
+- Style drift: naming, error handling patterns, logging style, and structure inconsistent with nearby code
+
+Default stance:
+- Prefer deletion over justification.
+- If validation is needed, do it at boundaries; keep internals trusting parsed inputs.
+- If a cast is truly unavoidable, localize it and keep the justification to a single short note.
+
+When recommending simplifications, do not accidentally change behavior. If the current behavior is unclear, request clarification or ask for a test that pins it down.
+
+**Default stance:** Do not add extensibility points without an explicit current requirement.
+
+### 5) Risk Layer (Security / Performance / Maintainability)
+
+Only report what you are confident about.
+
+Security checks (examples):
+- No secrets in code/logs
+- No injection vectors (shell/SQL/HTML) introduced
+- Authz/authn checks preserved
+- Sensitive data not leaked
+
+Performance checks (examples):
+- Avoid unnecessary repeated work (N+1 queries, repeated parsing, repeated filesystem hits)
+- Avoid obvious hot-path allocations or large sync operations
+
+Maintainability checks:
+- Clear naming and intent
+- Consistent error handling
+- API boundaries not blurred
+- Consistent with local file patterns (imports, export style, function style)
+
+### 6) Make One Primary Recommendation
+
+Provide one clear path to reach approval.
+Mention alternatives only when they have materially different trade-offs.
+
+### 7) Signal the Investment
+
+Tag the required follow-up effort using:
+- Quick (<1h)
+- Short (1-4h)
+- Medium (1-2d)
+- Large (3d+)
+
+## Confidence Filter
+
+Only report findings you believe are >=80% likely to be correct.
+If you are unsure, explicitly label it as "Uncertain" and explain what evidence would confirm it.
+
+## Output Format (Use This Exactly)
+
+---
+
+**Files Reviewed:** [list]
+
+**Plan/Task Reference:** [task name + link/path to plan section if known]
+
+**Overall Assessment:** [APPROVE | REQUEST_CHANGES | NEEDS_DISCUSSION]
+
+**Bottom Line:** 2-3 sentences describing whether it matches the task/plan and what must change.
+
+### Critical Issues
+- None | [file:line] - [issue] (why it blocks approval) + (recommended fix)
+
+### Major Issues
+- None | [file:line] - [issue] + (recommended fix)
+
+### Minor Issues
+- None | [file:line] - [issue] + (suggested fix)
+
+### YAGNI / Dead Code
+- None | [file:line] - [what to remove/simplify] + (why it is unnecessary)
+
+### Positive Observations
+- [at least one concrete good thing]
+
+### Action Plan
+1. [highest priority change]
+2. [next]
+3. [next]
+
+### Effort Estimate
+[Quick | Short | Medium | Large]
+
+---
+
+## Common Review Smells (Fast Scan)
+
+Task/plan adherence:
+- Adds features not mentioned in the plan/task
+- Leaves TODOs as the mechanism for correctness
+- Introduces new configuration modes/flags "for future"
+
+YAGNI / dead code:
+- Options/config that are parsed but not used
+- Branches that do the same thing on both sides
+- Comments like "reserved for future" or "we might need this"
+
+AI slop / inconsistency:
+- Commentary that restates code, narrates obvious steps, or adds process noise
+- try/catch that swallows errors or returns defaults without a requirement
+- `as any` used to silence type errors instead of fixing types
+- New helpers/abstractions with a single call site
+
+Correctness:
+- Silent fallbacks to defaults on error when the task expects a hard failure
+- Unhandled error paths, missing cleanup, missing returns
+
+Maintainability:
+- Abstractions used once
+- Unclear naming, "utility" grab-bags
+
+## When to Escalate
+
+Use NEEDS_DISCUSSION (instead of REQUEST_CHANGES) when:
+- The plan/task is ambiguous and multiple implementations could be correct
+- The change implies a product/architecture decision not documented
+- Fixing issues requires changing scope, dependencies, or public API