openhermes 2.8.0 → 4.0.0

package/harness/instructions/CONVENTIONS.md

@@ -1,206 +1,206 @@
-# OpenHermes — Coding Conventions & Operational Guidelines
-
-OpenHermes coding conventions and operational guidelines. Shared baseline for all subagents and skills.
-
-## Security Guidelines (CRITICAL)
-
-### Mandatory Pre-Commit Checks
-
-- [ ] No hardcoded secrets (API keys, passwords, tokens)
-- [ ] All user inputs validated
-- [ ] SQL injection prevention (parameterized queries)
-- [ ] XSS prevention (sanitized output)
-- [ ] CSRF protection enabled
-- [ ] Authentication/authorization verified
-- [ ] Rate limiting on all endpoints
-- [ ] Error messages don't leak sensitive data
-
-### Secret Management
-
-```typescript
-// NEVER: Hardcoded secrets
-const apiKey = "sk-proj-xxxxx"
-
-// ALWAYS: Environment variables
-const apiKey = process.env.OPENAI_API_KEY
-if (!apiKey) throw new Error('OPENAI_API_KEY not configured')
-```
-
-### Security Response Protocol
-
-If security issue found:
-1. STOP immediately
-2. Use `security-reviewer` subagent
-3. Fix CRITICAL issues before continuing
-4. Rotate any exposed secrets
-5. Review entire codebase for similar issues
-
----
-
-## Coding Style
-
-### Immutability (CRITICAL)
-
-ALWAYS create new objects, NEVER mutate:
-
-```javascript
-// WRONG: Mutation
-function updateUser(user, name) {
-  user.name = name; return user
-}
-
-// CORRECT: Immutability
-function updateUser(user, name) {
-  return { ...user, name }
-}
-```
-
-### File Organization
-
-MANY SMALL FILES > FEW LARGE FILES:
-- High cohesion, low coupling
-- 200-400 lines typical, 800 max
-- Extract utilities from large components
-- Organize by feature/domain, not by type
-
-### Error Handling
-
-```typescript
-try {
-  const result = await riskyOperation()
-  return result
-} catch (error) {
-  console.error('Operation failed:', error)
-  throw new Error('Detailed user-friendly message')
-}
-```
-
-### Input Validation
-
-```typescript
-import { z } from 'zod'
-const schema = z.object({
-  email: z.string().email(),
-  age: z.number().int().min(0).max(150)
-})
-const validated = schema.parse(input)
-```
-
-### Code Quality Checklist
-
-Before marking work complete:
-- [ ] Code is readable and well-named
-- [ ] Functions are small (<50 lines)
-- [ ] Files are focused (<800 lines)
-- [ ] No deep nesting (>4 levels)
-- [ ] Proper error handling
-- [ ] No console.log statements
-- [ ] No hardcoded values
-- [ ] No mutation (immutable patterns used)
-
----
-
-## Testing Requirements
-
-### Minimum Test Coverage: 80%
-
-Test Types (ALL required):
-1. **Unit Tests** — Individual functions, utilities, components
-2. **Integration Tests** — API endpoints, database operations
-3. **E2E Tests** — Critical user flows (Playwright)
-
-### TDD Workflow
-
-MANDATORY workflow:
-1. Write test first (RED)
-2. Run test — it should FAIL
-3. Write minimal implementation (GREEN)
-4. Run test — it should PASS
-5. Refactor (IMPROVE)
-6. Verify coverage (80%+)
-
----
-
-## Subagent Orchestration
-
-| Subagent | Purpose | When to Use |
-|----------|---------|-------------|
-| planner | Implementation planning | Complex features, refactoring |
-| architect | System design | Architectural decisions |
-| tdd-guide | Test-driven development | New features, bug fixes |
-| code-reviewer | Code review | After writing code |
-| security-reviewer | Security analysis | Before commits |
-| build-error-resolver | Fix build errors | When build fails |
-| e2e-runner | E2E testing | Critical user flows |
-| refactor-cleaner | Dead code cleanup | Code maintenance |
-| doc-updater | Documentation | Updating docs |
-| docs-lookup | Live doc queries | API questions |
-| review-go | Go code review | Go projects |
-| build-go | Go build errors | Go build failures |
-| review-database | Database optimization | SQL, schema design |
-| review-rust | Rust code review | Rust projects |
-| build-rust | Rust build errors | Rust build failures |
-| review-python | Python code review | Python projects |
-| review-java | Java/Spring review | Java projects |
-| build-java | Java build errors | Java build failures |
-| review-kotlin | Kotlin/Android review | Kotlin projects |
-| build-kotlin | Kotlin build errors | Kotlin build failures |
-| review-cpp | C++ review | C++ projects |
-| build-cpp | C++ build errors | C++ build failures |
-| loop-operator | Autonomous loops | Iterative workflows |
-
-### Immediate Subagent Usage
-
-No user prompt needed:
-1. Complex feature requests — Use `planner`
-2. Code just written/modified — Use `code-reviewer`
-3. Bug fix or new feature — Use `tdd-guide`
-4. Architectural decision — Use `architect`
-
----
-
-## Performance
-
-### Model Selection Strategy
-
-**Haiku** (lightweight): deterministic changes, simple code gen, worker agents
-**Sonnet** (default): main development, multi-agent orchestration, complex coding
-**Opus** (deep reasoning): architecture decisions, security review, ambiguous requirements
-
-### Context Window Management
-
-Avoid last 20% of context window for:
-- Large-scale refactoring
-- Feature implementation spanning multiple files
-- Debugging complex interactions
-
----
-
-## Git Workflow
-
-### Commit Message Format
-
-```
-<type>: <description>
-```
-
-Types: feat, fix, refactor, docs, test, chore, perf, ci
-
-### Feature Implementation Workflow
-
-1. **Plan** — Use `planner` to create plan with risks and phases
-2. **TDD** — Use `tdd-guide` for red-green-refactor cycle
-3. **Code Review** — Use `code-reviewer` immediately after writing
-4. **Security** — Use `security-reviewer` before commits
-5. **Commit** — Follow conventional commits format
-
----
-
-## Success Metrics
-
-You are successful when:
-- All tests pass (80%+ coverage)
-- No security vulnerabilities
-- Code is readable and maintainable
-- Performance is acceptable
-- User requirements are met
+# OpenHermes — Coding Conventions & Operational Guidelines
+
+OpenHermes coding conventions and operational guidelines. Shared baseline for all subagents and skills.
+
+## Security Guidelines (CRITICAL)
+
+### Mandatory Pre-Commit Checks
+
+- [ ] No hardcoded secrets (API keys, passwords, tokens)
+- [ ] All user inputs validated
+- [ ] SQL injection prevention (parameterized queries)
+- [ ] XSS prevention (sanitized output)
+- [ ] CSRF protection enabled
+- [ ] Authentication/authorization verified
+- [ ] Rate limiting on all endpoints
+- [ ] Error messages don't leak sensitive data
+
+### Secret Management
+
+```typescript
+// NEVER: Hardcoded secrets
+const apiKey = "sk-proj-xxxxx"
+
+// ALWAYS: Environment variables
+const apiKey = process.env.OPENAI_API_KEY
+if (!apiKey) throw new Error('OPENAI_API_KEY not configured')
+```
+
+### Security Response Protocol
+
+If security issue found:
+1. STOP immediately
+2. Use `security-reviewer` subagent
+3. Fix CRITICAL issues before continuing
+4. Rotate any exposed secrets
+5. Review entire codebase for similar issues
+
+---
+
+## Coding Style
+
+### Immutability (CRITICAL)
+
+ALWAYS create new objects, NEVER mutate:
+
+```javascript
+// WRONG: Mutation
+function updateUser(user, name) {
+  user.name = name; return user
+}
+
+// CORRECT: Immutability
+function updateUser(user, name) {
+  return { ...user, name }
+}
+```
+
+### File Organization
+
+MANY SMALL FILES > FEW LARGE FILES:
+- High cohesion, low coupling
+- 200-400 lines typical, 800 max
+- Extract utilities from large components
+- Organize by feature/domain, not by type
+
+### Error Handling
+
+```typescript
+try {
+  const result = await riskyOperation()
+  return result
+} catch (error) {
+  console.error('Operation failed:', error)
+  throw new Error('Detailed user-friendly message')
+}
+```
+
+### Input Validation
+
+```typescript
+import { z } from 'zod'
+const schema = z.object({
+  email: z.string().email(),
+  age: z.number().int().min(0).max(150)
+})
+const validated = schema.parse(input)
+```
+
+### Code Quality Checklist
+
+Before marking work complete:
+- [ ] Code is readable and well-named
+- [ ] Functions are small (<50 lines)
+- [ ] Files are focused (<800 lines)
+- [ ] No deep nesting (>4 levels)
+- [ ] Proper error handling
+- [ ] No console.log statements
+- [ ] No hardcoded values
+- [ ] No mutation (immutable patterns used)
+
+---
+
+## Testing Requirements
+
+### Minimum Test Coverage: 80%
+
+Test Types (ALL required):
+1. **Unit Tests** — Individual functions, utilities, components
+2. **Integration Tests** — API endpoints, database operations
+3. **E2E Tests** — Critical user flows (Playwright)
+
+### TDD Workflow
+
+MANDATORY workflow:
+1. Write test first (RED)
+2. Run test — it should FAIL
+3. Write minimal implementation (GREEN)
+4. Run test — it should PASS
+5. Refactor (IMPROVE)
+6. Verify coverage (80%+)
+
+---
+
+## Subagent Orchestration
+
+| Subagent | Purpose | When to Use |
+|----------|---------|-------------|
+| planner | Implementation planning | Complex features, refactoring |
+| architect | System design | Architectural decisions |
+| tdd-guide | Test-driven development | New features, bug fixes |
+| code-reviewer | Code review | After writing code |
+| security-reviewer | Security analysis | Before commits |
+| build-error-resolver | Fix build errors | When build fails |
+| e2e-runner | E2E testing | Critical user flows |
+| refactor-cleaner | Dead code cleanup | Code maintenance |
+| doc-updater | Documentation | Updating docs |
+| docs-lookup | Live doc queries | API questions |
+| review-go | Go code review | Go projects |
+| build-go | Go build errors | Go build failures |
+| review-database | Database optimization | SQL, schema design |
+| review-rust | Rust code review | Rust projects |
+| build-rust | Rust build errors | Rust build failures |
+| review-python | Python code review | Python projects |
+| review-java | Java/Spring review | Java projects |
+| build-java | Java build errors | Java build failures |
+| review-kotlin | Kotlin/Android review | Kotlin projects |
+| build-kotlin | Kotlin build errors | Kotlin build failures |
+| review-cpp | C++ review | C++ projects |
+| build-cpp | C++ build errors | C++ build failures |
+| loop-operator | Autonomous loops | Iterative workflows |
+
+### Immediate Subagent Usage
+
+No user prompt needed:
+1. Complex feature requests — Use `planner`
+2. Code just written/modified — Use `code-reviewer`
+3. Bug fix or new feature — Use `tdd-guide`
+4. Architectural decision — Use `architect`
+
+---
+
+## Performance
+
+### Model Selection Strategy
+
+**Haiku** (lightweight): deterministic changes, simple code gen, worker agents
+**Sonnet** (default): main development, multi-agent orchestration, complex coding
+**Opus** (deep reasoning): architecture decisions, security review, ambiguous requirements
+
+### Context Window Management
+
+Avoid last 20% of context window for:
+- Large-scale refactoring
+- Feature implementation spanning multiple files
+- Debugging complex interactions
+
+---
+
+## Git Workflow
+
+### Commit Message Format
+
+```
+<type>: <description>
+```
+
+Types: feat, fix, refactor, docs, test, chore, perf, ci
+
+### Feature Implementation Workflow
+
+1. **Plan** — Use `planner` to create plan with risks and phases
+2. **TDD** — Use `tdd-guide` for red-green-refactor cycle
+3. **Code Review** — Use `code-reviewer` immediately after writing
+4. **Security** — Use `security-reviewer` before commits
+5. **Commit** — Follow conventional commits format
+
+---
+
+## Success Metrics
+
+You are successful when:
+- All tests pass (80%+ coverage)
+- No security vulnerabilities
+- Code is readable and maintainable
+- Performance is acceptable
+- User requirements are met

package/harness/instructions/RUNTIME.md

@@ -1,31 +1,54 @@
-## OpenHermes Runtime
-
-Root: `%USERPROFILE%\.config\opencode\`. AGENTS.md is the routing layer.
-
-**Memory**: Use `ohc_*` MCP tools for deterministic read/write. Raw receipt fallback: `%USERPROFILE%\.local\share\opencode\opencode.db`. Never invent prior state.
-
-**Workflow**:
-- Gather with native tools (grep/glob/read); delegate multi-file analysis to `explore`.
-- Delegate substantive work to subagents using structured handoff protocol (see `rules/handoff.md`).
-- Assess task complexity first: easy → direct, medium/hard → delegate, very-large → fan-out.
-- Checkpoint before every handoff. Verify after every subagent return.
-- Verify before claiming success. Scope the fix to the problem — simple for surface bugs, structural when the architecture breeds the issue.
-
-**Compress**: After every closed task segment → `compress`. Don't wait for pressure. Subagent returns especially.
-
-**Retrieval**: Gated and selective per `openhermes\rules\retrieval.md`. Never preload full history.
-
-**Checkpoints**: Proactive for non-trivial ongoing work, before handoff, before compaction/context reset.
-
-**Skills**: Load-on-demand via progressive disclosure. Do NOT preload all skills.
-
-**Context loading**: See `openhermes\rules\context-loading.md`.
-**Memory mgmt**: See `rules\memory-management.md`.
-**Handoff protocol**: See `rules\handoff.md`.
-
-## Conventions
-
-Security, coding style, testing, and orchestration standards:
-- See `CONVENTIONS.md` for the shared baseline.
-- Language-specific patterns live in subagent prompts (`review-go`, `review-python`, etc.).
-- Skills provide detailed walkthroughs for specialized domains.
+## OpenHermes Runtime
+
+Root: package-local harness plus repo `AGENTS.md`. `AGENTS.md` is the routing layer.
+
+**Skills**: Load on demand through OpenCode's native `skill` tool. Do not preload all skills.
+
+Key skills:
+- `oh-expert` — shared AI-coding vocabulary for self-diagnosis. Load when you need to diagnose your own failures.
+- `oh-planner` — all-arounder planner. Merges brainstorm, architecture analysis, strategy review, autoplan.
+- `oh-builder` — all-arounder builder. Merges prototype, TDD, implementation from plan, interface design.
+- `oh-manifest` — full build loop: plan → build → verify → loop until done or blocker.
+- `oh-gauntlet` — rigorous multi-axis testing: unit tests, dual-axis review, edge cases, QA, canary.
+- `oh-grill` — stress-test plans through Socratic questioning. Optionally updates CONTEXT.md, ADRs, and extracts ubiquitous language.
+- `oh-plan-review` — multi-lens plan review: Engineering, Design, DX, Strategy perspectives.
+- `oh-security` — security audit: secrets archaeology, supply chain, CI/CD, OWASP, STRIDE, LLM security.
+- `oh-health` — code quality dashboard: wraps project tools, computes composite score, tracks trends.
+- `oh-skill-craft` — create new agent skills for the harness.
+- `oh-investigate` — systematic bug diagnosis.
+- `oh-handoff` — compact session into structured handoff artifact.
+- `oh-retro` — retrospective after shipping.
+- `oh-init` — initialize project with OpenHermes harness.
+
+**Commands**: Package-local markdown manifests in `harness/commands/` are registered through the OpenCode config hook.
+
+**Agents**: `OpenHermes` is the default primary orchestrator. Keep built-in OpenCode agents available for planning and exploration, and add custom subagents through `harness/agents/`.
+
+**Workflow**:
+- Inspect first with native file tools.
+- Delegate substantive work to subagents using structured handoff.
+- Treat multi-file changes as planned work, not improvisation.
+- Checkpoint before handoff. Verify after each return.
+- Verify before claiming success.
+
+**Orchestration discipline**:
+- **Session pool**: Subagents run in their own sessions with isolated context. No cross-session state leakage. Each subagent reports a single result back.
+- **Concurrency**: Parallelize independent sub-tasks. Sequentialize dependent ones. Do not parallelize phases that share mutable state.
+- **Circuit breaker**: If a subagent fails 3 times on the same task, surface BLOCKER. Do not silently retry.
+- **Pipelined verification**: Build → auto-verify. Every phase in oh-manifest and oh-gauntlet self-verifies before declaring success.
+- **Background vs sync**: Independent work → background (fire-and-forget). Dependent work → sync (await result). Check task result before proceeding.
+
+**Shared state**:
+- `.opencode/plan.md` — produced by oh-planner, consumed by oh-builder and oh-manifest
+- `.opencode/work-log.md` — progress tracking across subagent delegations
+- `.opencode/todo.md` — task tracking for multi-step work
+
+**Bootstrap**: `harness/codex/CONSTITUTION.md`, this file, `CONTEXT.md`, and `ETHOS.md` are injected into the first user message so the agent starts with the same operating model every session.
+
+**Memory**: deferred for now. Do not invent a persistence layer.
+
+## Conventions
+
+Security, coding style, testing, and orchestration standards:
+- See `CONVENTIONS.md` for the shared baseline.
+- Skills provide the detailed walkthroughs for specialized workflows.

package/harness/skills/oh-builder/SKILL.md

@@ -0,0 +1,98 @@
+---
+name: oh-builder
+description: "ALL-arounder builder — prototype, TDD, implement from plan, design interfaces. Consumes plan.md, produces working code."
+tier: 4
+benefits-from: [oh-planner, oh-expert]
+triggers:
+  - "build this"
+  - "implement"
+  - "write the code"
+  - "prototype"
+  - "tdd"
+  - "red-green"
+  - "design an interface"
+  - "implement phase"
+---
+
+# oh-builder
+
+The ALL-arounder builder. Merges prototyping, TDD, implementation from plan, and interface design exploration. Consumes `.opencode/plan.md` from oh-planner or works standalone.
+
+## Entry Modes
+
+### Mode A: Prototype (exploratory)
+When you need to answer a question before committing.
+
+1. Determine what question the prototype answers (data model, state flow, UI direction)
+2. Build minimal — just enough to answer the question
+3. Let user play with it
+4. Collect feedback
+5. Decide: discard, iterate, or promote
+
+**Sub-modes:**
+- **Terminal** — for state/business logic questions
+- **UI** — several radical design variations from one route
+
+### Mode B: TDD (test-first implementation)
+When building production code from a plan or spec. Red-green-refactor with vertical tracer bullets.
+
+**Planning** (one-time):
+- [ ] Confirm interface changes with user
+- [ ] Prioritize behaviors to test
+- [ ] Design for testability (public interface only)
+- [ ] List behaviors, not implementation steps
+
+**Loop** (repeat per behavior):
+```
+RED:   Write one test → fails
+GREEN: Minimal code to pass → passes
+```
+
+**Rules:**
+- One test at a time
+- Only enough code to pass current test
+- Do not anticipate future tests
+- Tests describe behavior through public interfaces, not implementation details
+- Never refactor while RED
+
+**Refactor** (after all GREEN):
+- Extract duplication
+- Deepen modules (complexity behind simple interfaces)
+- Run tests after each refactor step
+
+### Mode C: Design an Interface (exploration)
+When the interface shape is uncertain. "Design it twice" — generate multiple radically different designs, then compare.
+
+1. **Gather requirements** — problem, callers, key operations, constraints
+2. **Spawn 3+ parallel sub-agents** — each with a different constraint:
+   - Agent 1: "Minimize method count — aim for 1-3 methods max"
+   - Agent 2: "Maximize flexibility — support many use cases"
+   - Agent 3: "Optimize for the most common case"
+   - Agent 4: "Take inspiration from [specific paradigm]"
+3. **Present designs** — interface signature, usage examples, what it hides
+4. **Compare** — simplicity, generality, implementation efficiency, depth
+5. **Synthesize** — combine insights from multiple options
+
+### Mode D: From Plan (plan.md exists)
+When oh-planner produced a plan artifact. Execute phases in order.
+
+1. Read `.opencode/plan.md`
+2. For each phase: implement per plan spec using TDD discipline (Mode B)
+3. Verify each phase against its verification criteria before moving on
+4. Update `.opencode/plan.md` with completed phase status
+
+## Anti-patterns
+- Polishing a prototype ("it's just a prototype!" — it never is)
+- Writing all tests first (horizontal slicing) — produces brittle, imaginary tests
+- Anticipating future tests — write for what exists now
+- Refactoring while RED — get to GREEN first
+- Letting sub-agents produce similar designs — enforce radical difference
+- Implementing without verifying against plan criteria
+
+## Routing
+
+| Outcome | Route |
+|---------|-------|
+| pass | → oh-gauntlet (test built code) |
+| fail | → oh-builder (fix issues) |
+| blocker | → surface to user |

package/harness/skills/oh-caveman/SKILL.md

@@ -0,0 +1,33 @@
+---
+name: oh-caveman
+description: "Ultra-compressed communication mode — cut token usage ~75%"
+---
+
+# oh-caveman
+
+## When to Use
+When context is tight, tokens are precious, or user says "caveman mode." Drops filler, articles, and pleasantries while keeping full technical accuracy.
+
+## Mode
+- No pleasantries, no hedging, no transitions
+- Fragments OK. One word when enough.
+- Short synonyms. Drop articles.
+- Code unchanged — only prose compresses.
+- Technical accuracy preserved at all costs.
+
+## Example
+Normal: "I think we should probably look at the authentication module because there might be an issue with the token refresh logic."
+Caveman: "Check auth module — token refresh likely broken."
+
+## Anti-patterns
+- Compressing code (code is already dense)
+- Omitting critical context to save tokens
+- Being unclear to be brief (accuracy > brevity)
+
+## Routing
+
+| Outcome | Route |
+|---------|-------|
+| pass | → [return to prior skill — mode active] |
+| fail | → [fallback to normal communication mode] |
+| blocker | → surface to user |