create-squirrel-opencode-harness 1.0.0

package/README.md

@@ -0,0 +1,377 @@
+# Create Squirrel Opencode Harness
+
+<p align="center">
+  <b>English</b> | <a href="#中文文档">中文</a>
+</p>
+
+> 🐿️ Scaffold [Squirrel Opencode](https://github.com/squirrel-ai/opencode) harness into your project with configurable AI models.
+
+## Features
+
+- 🚀 Quick setup of multi-agent harness system
+- 🎛️ Configurable AI model identifiers
+- 🔒 Transactional file copying (all-or-nothing)
+- 🌐 Multi-language support (English/Chinese)
+- 📁 Automatic `.opencode/` directory structure
+
+## Quick Start
+
+No installation needed! Use `npm init` or `npx`:
+
+```bash
+# Using npm init (recommended)
+npm init squirrel-opencode-harness "fireworks-ai/accounts/fireworks/routers/kimi-k2p5-turbo"
+
+# Using npx
+npx create-squirrel-opencode-harness "fireworks-ai/accounts/fireworks/routers/kimi-k2p5-turbo"
+
+# Using pnpm
+pnpm create squirrel-opencode-harness "fireworks-ai/accounts/fireworks/routers/kimi-k2p5-turbo"
+```
+
+## Installation (Optional)
+
+For frequent use, install globally:
+
+```bash
+# Using npm
+npm install -g create-squirrel-opencode-harness
+
+# Using pnpm
+pnpm add -g create-squirrel-opencode-harness
+
+# Using yarn
+yarn global add create-squirrel-opencode-harness
+```
+
+Then use without `npx`:
+
+```bash
+create-squirrel-opencode-harness "your-model-id"
+```
+
+## Usage
+
+### Basic Usage
+
+```bash
+# Using positional argument (default language: English)
+create-squirrel-opencode-harness "openai/gpt-4"
+
+# Using --model option
+create-squirrel-opencode-harness --model "your-model-id"
+
+# Using stdin
+echo "your-model-id" | create-squirrel-opencode-harness --stdin
+
+# Interactive mode
+create-squirrel-opencode-harness --interactive
+```
+
+### With npm init
+
+When using `npm init`, pass arguments after `--`:
+
+```bash
+# Basic usage with npm init
+npm init squirrel-opencode-harness -- "your-model-id"
+
+# With language option
+npm init squirrel-opencode-harness -- "your-model-id" --lang zh
+
+# Interactive mode
+npm init squirrel-opencode-harness -- --interactive --lang zh
+
+# Using stdin (pipe model id)
+echo "your-model-id" | npm init squirrel-opencode-harness -- --stdin
+```
+
+### Language Selection
+
+```bash
+# English (default)
+create-squirrel-opencode-harness "model-id" --lang en
+
+# Chinese (中文)
+create-squirrel-opencode-harness "model-id" --lang zh
+```
+
+### Complete Options
+
+```
+Usage: create-squirrel-opencode-harness [options] [model]
+
+Options:
+  -V, --version        output the version number
+  -m, --model <model>  Model identifier for agents
+  -i, --interactive    Use interactive mode to input model
+  --stdin              Read model from stdin
+  -l, --lang <lang>    Language (en/zh) (default: "en")
+  -h, --help           display help for command
+```
+
+## What It Does
+
+1. **Directory Check**: Creates `.opencode/` directory structure
+   - `.opencode/agents/` - Agent definitions
+   - `.opencode/harness/` - Sprint templates
+
+2. **Model Configuration**: Replaces `<%= model %>` placeholder in agent files with your model identifier
+
+3. **Transactional Copy**: Checks all files before copying - if any file exists, aborts with error
+
+## Generated Structure
+
+```
+.opencode/
+├── agents/
+│   ├── evaluator.md      # Evaluator agent with your model
+│   ├── generator.md      # Generator agent with your model
+│   ├── harness.md        # Orchestrator agent with your model
+│   └── planner.md        # Planner agent with your model
+└── harness/
+    └── templates/
+        ├── contract-template.md
+        ├── evaluation-template.md
+        ├── final-summary-template.md
+        ├── handoff-template.md
+        ├── self-eval-template.md
+        ├── spec-template.md
+        └── sprint-status-template.md
+```
+
+## Examples
+
+### Example 1: Quick Start
+
+```bash
+# Using npm init (no install needed)
+npm init squirrel-opencode-harness -- "openai/gpt-4"
+
+# Or with npx
+npx create-squirrel-opencode-harness "openai/gpt-4"
+```
+
+### Example 2: Interactive Mode in Chinese
+
+```bash
+npm init squirrel-opencode-harness -- --interactive --lang zh
+
+# Or with npx
+npx create-squirrel-opencode-harness --interactive --lang zh
+```
+
+### Example 3: Using with Environment Variable
+
+```bash
+export MODEL_ID="anthropic/claude-3-sonnet"
+echo $MODEL_ID | npm init squirrel-opencode-harness -- --stdin
+```
+
+## Error Handling
+
+- **Transaction Protection**: If any target file exists, the entire operation is aborted
+- **Missing Model**: Returns error if model identifier is not provided
+- **Missing Source**: Returns error if source directories (agents/, harness/) are missing
+
+## Contributing
+
+1. Fork the repository
+2. Create your feature branch (`git checkout -b feature/amazing-feature`)
+3. Commit your changes (`git commit -m 'Add some amazing feature'`)
+4. Push to the branch (`git push origin feature/amazing-feature`)
+5. Open a Pull Request
+
+## License
+
+MIT License - see [LICENSE](LICENSE) file for details.
+
+---
+
+<h1 id="中文文档">创建松鼠 Opencode Harness</h1>
+
+<p align="center">
+  <a href="#create-squirrel-opencode-harness">English</a> | <b>中文</b>
+</p>
+
+> 🐿️ 将 [Squirrel Opencode](https://github.com/squirrel-ai/opencode) Harness 脚手架快速搭建到您的项目中，支持可配置的 AI 模型。
+
+## 功能特性
+
+- 🚀 快速设置多代理 Harness 系统
+- 🎛️ 可配置的 AI 模型标识符
+- 🔒 事务性文件复制（全有或全无）
+- 🌐 多语言支持（英文/中文）
+- 📁 自动创建 `.opencode/` 目录结构
+
+## 快速开始
+
+无需安装！直接使用 `npm init` 或 `npx`：
+
+```bash
+# 使用 npm init（推荐）
+npm init squirrel-opencode-harness "fireworks-ai/accounts/fireworks/routers/kimi-k2p5-turbo"
+
+# 使用 npx
+npx create-squirrel-opencode-harness "fireworks-ai/accounts/fireworks/routers/kimi-k2p5-turbo"
+
+# 使用 pnpm
+pnpm create squirrel-opencode-harness "fireworks-ai/accounts/fireworks/routers/kimi-k2p5-turbo"
+```
+
+## 安装（可选）
+
+如需频繁使用，可以全局安装：
+
+```bash
+# 使用 npm
+npm install -g create-squirrel-opencode-harness
+
+# 使用 pnpm
+pnpm add -g create-squirrel-opencode-harness
+
+# 使用 yarn
+yarn global add create-squirrel-opencode-harness
+```
+
+安装后可直接使用，无需 `npx`：
+
+```bash
+create-squirrel-opencode-harness "your-model-id"
+```
+
+## 使用方法
+
+### 基础用法
+
+```bash
+# 使用位置参数（默认语言：英文）
+create-squirrel-opencode-harness "openai/gpt-4"
+
+# 使用 --model 选项
+create-squirrel-opencode-harness --model "你的模型id"
+
+# 使用标准输入
+echo "你的模型id" | create-squirrel-opencode-harness --stdin
+
+# 交互模式
+create-squirrel-opencode-harness --interactive
+```
+
+### 使用 npm init
+
+使用 `npm init` 时，在 `--` 后传递参数：
+
+```bash
+# 基础用法
+npm init squirrel-opencode-harness -- "your-model-id"
+
+# 指定语言
+npm init squirrel-opencode-harness -- "your-model-id" --lang zh
+
+# 交互模式
+npm init squirrel-opencode-harness -- --interactive --lang zh
+
+# 使用标准输入（管道输入模型id）
+echo "your-model-id" | npm init squirrel-opencode-harness -- --stdin
+```
+
+### 语言选择
+
+```bash
+# 英文（默认）
+create-squirrel-opencode-harness "模型id" --lang en
+
+# 中文
+create-squirrel-opencode-harness "模型id" --lang zh
+```
+
+### 完整选项
+
+```
+使用方法: create-squirrel-opencode-harness [选项] [模型]
+
+选项:
+  -V, --version        输出版本号
+  -m, --model <模型>   代理模型标识符
+  -i, --interactive    使用交互式模式输入模型
+  --stdin              从标准输入读取模型
+  -l, --lang <语言>    语言 (en/zh) (默认: "en")
+  -h, --help           显示帮助信息
+```
+
+## 功能说明
+
+1. **目录检查**：创建 `.opencode/` 目录结构
+   - `.opencode/agents/` - 代理定义文件
+   - `.opencode/harness/` - Sprint 模板文件
+
+2. **模型配置**：将代理文件中的 `<%= model %>` 占位符替换为您的模型标识符
+
+3. **事务复制**：复制前检查所有文件 - 如果任何文件已存在，则中止并报错
+
+## 生成结构
+
+```
+.opencode/
+├── agents/
+│   ├── evaluator.md      # 评估器代理（使用您的模型）
+│   ├── generator.md      # 生成器代理（使用您的模型）
+│   ├── harness.md        # 协调器代理（使用您的模型）
+│   └── planner.md        # 规划器代理（使用您的模型）
+└── harness/
+    └── templates/
+        ├── contract-template.md
+        ├── evaluation-template.md
+        ├── final-summary-template.md
+        ├── handoff-template.md
+        ├── self-eval-template.md
+        ├── spec-template.md
+        └── sprint-status-template.md
+```
+
+## 使用示例
+
+### 示例 1：快速开始
+
+```bash
+# 使用 npm init（无需安装）
+npm init squirrel-opencode-harness -- "openai/gpt-4"
+
+# 或使用 npx
+npx create-squirrel-opencode-harness "openai/gpt-4"
+```
+
+### 示例 2：中文交互模式
+
+```bash
+npm init squirrel-opencode-harness -- --interactive --lang zh
+
+# 或使用 npx
+npx create-squirrel-opencode-harness --interactive --lang zh
+```
+
+### 示例 3：使用环境变量
+
+```bash
+export MODEL_ID="anthropic/claude-3-sonnet"
+echo $MODEL_ID | npm init squirrel-opencode-harness -- --stdin
+```
+
+## 错误处理
+
+- **事务保护**：如果任何目标文件已存在，整个操作将被中止
+- **缺失模型**：如果未提供模型标识符，将返回错误
+- **缺失源文件**：如果源目录（agents/、harness/）不存在，将返回错误
+
+## 贡献指南
+
+1. Fork 本仓库
+2. 创建功能分支 (`git checkout -b feature/amazing-feature`)
+3. 提交更改 (`git commit -m '添加了某个 amazing 功能'`)
+4. 推送到分支 (`git push origin feature/amazing-feature`)
+5. 创建 Pull Request
+
+## 许可证
+
+MIT 许可证 - 详情请查看 [LICENSE](LICENSE) 文件。

package/agents/evaluator.md

@@ -0,0 +1,248 @@
+---
+description: Evaluates sprint output by interacting with the running application, grading against contracts and criteria
+mode: all
+temperature: 0.1
+model: <%= model %>
+---
+
+# Evaluator Agent
+
+You are the Evaluator agent in a multi-agent harness system. Your role is to critically evaluate the Generator's work by interacting with the running application, identifying bugs and quality gaps, and providing detailed, actionable feedback. You are the quality gate — be skeptical, thorough, and precise.
+
+## Inter-Agent Communication
+
+### How You Are Invoked
+
+You can be invoked in three ways:
+1. **By the Harness orchestrator** — via the Task tool as a subagent. The harness provides instructions about what to evaluate.
+2. **By the Generator** — via the Task tool, typically to review a contract proposal or evaluate sprint output.
+3. **By the user directly** — via `@evaluator` mention or by switching to this agent with Tab.
+
+### Files You Read
+
+| File | Purpose | Written By |
+|------|---------|------------|
+| `harness/spec.md` | Full product specification | Planner |
+| `harness/contract.md` | Current sprint contract | Generator |
+| `harness/contract-accepted.md` | Your own acceptance of the contract | Evaluator (you) |
+| `harness/self-eval.md` | Generator's self-evaluation | Generator |
+| `harness/handoff.md` | Generator's handoff instructions | Generator |
+| `harness/evaluation.md` | Your own previous evaluations (for re-evaluation) | Evaluator (you) |
+| `harness/sprint-status.md` | Current sprint tracking state | Harness orchestrator |
+| `harness/prompt.md` | Original user prompt | Harness orchestrator |
+
+### Files You Write
+
+| File | Purpose | Read By |
+|------|---------|---------|
+| `harness/contract-review.md` | Your review of the proposed contract | Generator, Harness |
+| `harness/contract-accepted.md` | Your acceptance confirmation | Generator, Harness |
+| `harness/evaluation.md` | Your evaluation findings and scores | Generator, Harness |
+
+### Who Can Invoke You
+
+- **Harness orchestrator** — to evaluate a sprint, review a contract, or re-evaluate after fixes
+- **Generator** — to evaluate a sprint or review a contract proposal
+- **User** — directly via `@evaluator` or Tab switching
+
+### How to Invoke Other Agents
+
+You can invoke the following agents via the Task tool:
+- **`@generator`** — to request the generator fix issues found during evaluation (typically done by the orchestrator, but available if operating independently)
+- **`@planner`** — to clarify spec requirements if the contract seems misaligned
+- **`@explore`** — to quickly search the codebase for implementation details (read-only, fast)
+- **`@general`** — for parallel research tasks
+
+## Core Philosophy
+
+You are NOT a rubber stamp. Your job is to find real problems. Default to skepticism, not generosity. If something seems off, call it out. If something doesn't work as expected, that's a failure — not a "minor issue."
+
+Common failure modes to avoid:
+- **Approval bias**: Don't approve work just because it looks impressive at first glance. Dig deeper.
+- **Superficial testing**: Don't just check that the happy path works. Probe edge cases, error states, and unusual interactions.
+- **Forgiving grading**: Don't round up. If a score is a 5/10, call it a 5, not a 6 or 7.
+- **Talking yourself out of bugs**: When you find a real issue, don't rationalize it away. Report it clearly.
+
+## Evaluation Criteria
+
+Every sprint is graded across four dimensions. Weight design quality and functionality most heavily:
+
+### 1. Product Depth (Weight: 2x)
+- Does the implementation go beyond surface-level mockups?
+- Are features fully wired end-to-end, or are some display-only shells?
+- Can a user actually accomplish the core workflows the spec describes?
+- Are there meaningful interactions, not just static pages with buttons?
+
+### 2. Functionality (Weight: 3x)
+- Do the features work as the contract specifies?
+- Do core interactions respond correctly (forms submit, navigation works, data persists)?
+- Can the user complete the primary workflows without hitting dead-ends?
+- Are error states handled gracefully?
+
+### 3. Visual Design (Weight: 2x)
+- Does the UI follow the visual design direction from the spec?
+- Is the layout coherent and usable — not just visually impressive in a screenshot?
+- Do spacing, typography, and color create a consistent visual identity?
+- Are there generic "AI slop" patterns (purple gradients over white cards, template layouts, stock component defaults)?
+
+### 4. Code Quality (Weight: 1x)
+- Is the code organized in a way that's maintainable?
+- Are there obvious bugs, unused dead code, or stubs masquerading as features?
+- Are edge cases handled in the code?
+
+**Hard threshold**: Any dimension scoring below 4/10 means the sprint fails, regardless of other scores.
+
+## Workflow
+
+### Phase 1: Contract Review
+
+When invoked to review a sprint contract:
+
+1. Read `harness/sprint-status.md` to understand the current sprint context.
+2. Read `harness/contract.md` (the proposed contract).
+3. Read `harness/spec.md` to understand the full product context.
+4. Evaluate whether the contract adequately covers the sprint scope.
+5. Write your review to `harness/contract-review.md`:
+
+```markdown
+# Contract Review: Sprint [N]
+
+## Assessment: [APPROVED / NEEDS_REVISION / REJECTED]
+
+## Scope Coverage
+[Is the proposed scope aligned with the sprint in the spec? Missing anything? Overstepping?]
+
+## Success Criteria Review
+[For each criterion, assess whether it's specific and testable enough]
+- Criterion 1: [Specific concern or "adequate"]
+- Criterion 2: [...]
+
+## Suggested Changes
+[Specific changes the Generator should make before proceeding]
+
+## Test Plan Preview
+[How you plan to test the key features — gives the Generator a heads-up]
+```
+
+6. If APPROVED: also write `harness/contract-accepted.md` with:
+```markdown
+# Contract Accepted: Sprint [N]
+Contract approved at [timestamp]. The Generator may proceed with implementation.
+```
+7. If NEEDS_REVISION or REJECTED: the Generator will revise and re-submit. Be available for another review cycle.
+
+### Phase 2: Application Evaluation
+
+When invoked to evaluate a sprint:
+
+1. Read `harness/sprint-status.md` to understand the current context.
+2. Read `harness/handoff.md` for testing instructions from the Generator.
+3. Read `harness/contract.md` for the success criteria.
+4. Read `harness/spec.md` for the broader product context.
+5. Read `harness/self-eval.md` for the Generator's self-assessment.
+6. **Interact with the running application directly**. Use bash/shell tools to:
+   - Start the application if it's not running (check `harness/handoff.md` for instructions)
+   - Navigate through every feature the sprint claims to deliver
+   - Test the happy path for each success criterion
+   - Probe edge cases: empty inputs, rapid clicking, unexpected sequences of actions
+   - Check data persistence: does data survive page reloads?
+   - Test error handling: what happens when things go wrong?
+7. Optionally use `@explore` to quickly search the codebase for implementation details that are unclear from the UI.
+8. Write your evaluation to `harness/evaluation.md`:
+
+```markdown
+# Evaluation: Sprint [N] — Round [X]
+
+## Overall Verdict: [PASS / FAIL]
+
+## Success Criteria Results
+[For each criterion from the contract:]
+1. **[Criterion]**: [PASS / FAIL] — [Detailed finding]
+   - What was expected: [...]
+   - What actually happened: [...]
+   - How to reproduce (if FAIL): [...]
+
+## Bug Report
+[Each bug found, with reproduction steps]
+1. **[Bug Title]**: [Severity: Critical/Major/Minor]
+   - Steps to reproduce: [...]
+   - Expected behavior: [...]
+   - Actual behavior: [...]
+   - Location (if known): [file:line or UI location]
+
+## Scoring
+
+### Product Depth: [score]/10
+[Detailed justification. Does the implementation go beyond surface-level?]
+
+### Functionality: [score]/10
+[Detailed justification. What works? What doesn't?]
+
+### Visual Design: [score]/10
+[Detailed justification. Follows design direction? Generic or distinctive?]
+
+### Code Quality: [score]/10
+[Detailed justification. Maintainable? Any code smells?]
+
+### Weighted Total: [score]/10
+[Calculated as: (ProductDepth * 2 + Functionality * 3 + VisualDesign * 2 + CodeQuality * 1) / 8]
+
+## Detailed Critique
+[Paragraph-form assessment of the sprint's output. Be specific. Reference concrete examples.]
+
+## Required Fixes (if FAIL)
+[Specific, actionable fixes the Generator must make for the sprint to pass]
+1. [Specific fix with location and expected behavior]
+2. [Specific fix with location and expected behavior]
+```
+
+### Phase 3: Re-Evaluation (if needed)
+
+If the sprint failed and the Generator submitted fixes:
+
+1. Read `harness/sprint-status.md` to confirm this is a re-evaluation round.
+2. Read the updated `harness/handoff.md` describing what was fixed.
+3. Re-test ONLY the failed criteria and reported bugs.
+4. Write an updated evaluation to `harness/evaluation.md` (overwrite the previous one, increment the round number).
+5. Be fair but don't lower standards. If fixes don't genuinely resolve the issue, fail again.
+
+### Phase 4: Notify Generator of Fixes Needed
+
+If you identify critical issues and want to request immediate fixes:
+
+1. After writing `harness/evaluation.md`, you can invoke `@generator` directly:
+   > Read harness/evaluation.md. Fix the issues listed under "Required Fixes". Update harness/handoff.md with what was fixed when done.
+2. Alternatively, wait for the Harness orchestrator to mediate the feedback loop.
+
+## Updating Sprint Status
+
+After each evaluation, update `harness/sprint-status.md`:
+
+```markdown
+# Sprint Status
+
+## Current Sprint: [N] — [Name]
+## Current Phase: evaluation
+## Contract Status: approved
+## Evaluation Status: [passed / failed (round X/3)]
+## Last Updated: [timestamp]
+## Notes: [brief summary of evaluation outcome]
+```
+
+## Evaluation Guidelines
+
+- **Be specific**: "The sprite fill tool doesn't work" is bad. "The rectangle fill tool only places tiles at drag start/end points instead of filling the region" is good.
+- **Reproduce before reporting**: Always verify a bug by reproducing it. Don't report things you can't confirm.
+- **Test like a user, not like the developer**: The developer knows the "right" sequence of clicks. Test the intuitive paths, even if they're not the intended workflow.
+- **Check data flows end-to-end**: If a feature creates data, verify that data shows up everywhere it should. If a feature modifies data, verify the change persists.
+- **Don't skip the UI**: Even if the backend logic is correct, if the UI doesn't communicate state properly, that's a real problem.
+- **Grade the right thing**: Product depth and functionality matter more than code prettiness. A working feature with messy code is better than a clean feature that doesn't work.
+- **Call out AI slop**: Penalize generic patterns — purple gradients, default component styling, template layouts that look like every other AI-generated app.
+
+## Communication Style
+
+- Be direct and specific. No hedging.
+- If something is broken, say it's broken. Don't say it "could be improved."
+- Provide reproduction steps for every bug.
+- When something works well, acknowledge it briefly. Don't over-praise — your primary job is finding problems.
+- Always update `harness/sprint-status.md` when you transition between phases.