bf02ad0d5c
* refactor: Rename repository to OpenAgents Control Update all project references from "OpenAgents" to "OpenAgents Control": - Updated core config files (package.json, registry.json) - Updated documentation (README.md, docs/) - Updated scripts (install.sh, update.sh, test scripts) - Updated agent and command files - Updated integrations and packages - Updated all GitHub URLs to use OpenAgentsControl Naming convention: - Display name: "OpenAgents Control" - Repository URL: OpenAgentsControl * feat: Enable subagent-to-subagent delegation (ContextScout integration) Allow coding-related subagents to call ContextScout for context discovery: - CoderAgent: Can now discover coding standards on-demand - TestEngineer: Can now discover test coverage and TDD guidelines - CodeReviewer: Can now discover code review and security patterns - BuildAgent: Can now discover build validation standards - DocWriter: Can now discover documentation formatting guidelines Changes per subagent: - Added `task: true` to tools section - Added permission allowlist for ContextScout only (deny all other delegation) - Added Context Discovery workflow section with when-to-call guidance This enables subagents to be self-sufficient for finding relevant standards instead of relying on orchestrator to provide all context files. Benefits: - Subagents can discover what they need when context isn't explicit - Maintains security (only ContextScout allowed via task tool) - Follows existing patterns (uses task tool like main agents) * fix: Set OPENCODE_BRANCH in CI tests to use PR branch for downloads - Add OPENCODE_BRANCH environment variable to E2E tests - Add OPENCODE_BRANCH environment variable to profile smoke tests - Ensures tests download files from the PR branch instead of main - Fixes E2E test failures after repository rename to OpenAgentsControl
97 lines
2.8 KiB
Markdown
97 lines
2.8 KiB
Markdown
# Building CLIs in OpenAgents Control: Compact Guide
|
|
|
|
**Category**: guide
|
|
**Purpose**: Rapidly build, register, and deploy CLI tools for OpenAgents Control skills
|
|
**Framework**: FAB (Features, Advantages, Benefits)
|
|
|
|
---
|
|
|
|
## 🚀 Quick Start
|
|
|
|
**Don't start from scratch.** Use the standard pattern to build robust CLIs in minutes.
|
|
|
|
1. **Create**: `mkdir -p .opencode/skill/{name}/scripts`
|
|
2. **Implement**: Create `skill-cli.ts` (TypeScript) and `router.sh` (Bash)
|
|
3. **Register**: Add to `registry.json`
|
|
4. **Run**: `bash .opencode/skill/{name}/router.sh help`
|
|
|
|
---
|
|
|
|
## 🏗️ Core Architecture
|
|
|
|
| Component | File | Purpose |
|
|
|-----------|------|---------|
|
|
| **Logic** | `scripts/skill-cli.ts` | Type-safe implementation using `ts-node`. Handles args, logic, and output. |
|
|
| **Router** | `router.sh` | Universal entry point. Routes commands to the TS script. |
|
|
| **Docs** | `SKILL.md` | User guide, examples, and integration details. |
|
|
| **Config** | `registry.json` | Makes the skill discoverable and installable via `install.sh`. |
|
|
|
|
---
|
|
|
|
## ⚡ Implementation Patterns
|
|
|
|
### 1. The Router (`router.sh`)
|
|
**Why**: Provides a consistent, dependency-free entry point for all environments.
|
|
|
|
```bash
|
|
#!/bin/bash
|
|
SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
|
|
|
|
case "$1" in
|
|
help|--help|-h)
|
|
echo "Usage: bash router.sh <command>"
|
|
;;
|
|
*)
|
|
# Route to TypeScript implementation
|
|
npx ts-node "$SCRIPT_DIR/scripts/skill-cli.ts" "$@"
|
|
;;
|
|
esac
|
|
```
|
|
|
|
### 2. The CLI Logic (`skill-cli.ts`)
|
|
**Why**: Type safety, async/await support, and rich ecosystem access.
|
|
|
|
```typescript
|
|
#!/usr/bin/env ts-node
|
|
|
|
async function main() {
|
|
const [command, ...args] = process.argv.slice(2);
|
|
|
|
switch (command) {
|
|
case 'action':
|
|
await handleAction(args);
|
|
break;
|
|
default:
|
|
console.log("Unknown command");
|
|
process.exit(1);
|
|
}
|
|
}
|
|
|
|
main().catch(console.error);
|
|
```
|
|
|
|
---
|
|
|
|
## ✅ Quality Checklist
|
|
|
|
Before shipping, verify your CLI delivers value:
|
|
|
|
- [ ] **Help Command**: Does `router.sh help` provide clear, actionable usage info?
|
|
- [ ] **Error Handling**: Do invalid inputs return helpful error messages (not stack traces)?
|
|
- [ ] **Performance**: Does it start in < 1s? (Avoid heavy imports at top level)
|
|
- [ ] **Idempotency**: Can commands be run multiple times safely?
|
|
- [ ] **Registry**: Is it added to `registry.json` with correct paths?
|
|
|
|
---
|
|
|
|
## 🧠 Copywriting Principles for CLI Output
|
|
|
|
Apply `content-creation` principles to your CLI output:
|
|
|
|
1. **Clarity**: Use **Active Voice**. "Created file" (Good) vs "File has been created" (Bad).
|
|
2. **Specificity**: "Processed 5 files" (Good) vs "Processing complete" (Bad).
|
|
3. **Action**: Tell the user what to do next. "Run `npm test` to verify."
|
|
|
|
---
|
|
|
|
**Reference**: See `.opencode/context/openagents-repo/guides/adding-skill.md` for the full, detailed walkthrough.
|