feat: Context path configuration and documentation reorganization (#143)
* feat: add npm package support for @openagents/control
- Convert package to publishable npm package with scoped name @openagents/control
- Add CLI entry point bin/oac.js for global installation
- Create .npmignore to exclude dev files and node_modules
- Configure package.json with proper files, bin, and metadata
- Add comprehensive NPM_PUBLISHING_GUIDE.md with publishing instructions
- Package size: 610KB (2.4MB unpacked) with 353 files
- Includes .opencode/tool/ directory without node_modules
- CLI command: oac (e.g., 'oac developer' or 'oac --help')
Users can install with: npm install -g @openagents/control
* chore: remove telegram bot files from package
- Delete .opencode/_lib/telegram-bot.ts (unused)
- Delete .opencode/plugin/telegram-notify.ts (depends on deleted file)
- Remove _lib directory reference from package.json files field
- Reduces package size from 610KB to 607KB
- Total files: 351 (down from 353)
* chore: remove all telegram references from registry and docs
- Remove telegram-bot and telegram-notify plugin entries from registry.json
- Remove telegram plugin references from all profiles (developer, business, full, advanced)
- Update profile-validation.md to remove telegram from business profile documentation
- Clean package with no telegram dependencies
* docs: enhance README clarity and add configuration examples
- Add Core Philosophy section with 4 key principles
- Add Quick Concepts for First-Time Users (scannable format)
- Add prominent Oh My OpenCode comparison link
- Add comprehensive Model Configuration section
- Add Customizing Agents section with practical examples
- Streamline model selection recommendations
- Add emoji headers for visual consistency
- Remove redundant FAQ entry
Addresses user feedback about documentation clarity and first-time user experience.
* refactor: remove OpenImplementer agent
- Delete OpenImplementer agent file (redundant with OpenAgent)
- Remove from registry.json and all profiles
- Update OpenCoder delegation rules (now handles 1-4 files directly)
- Clean up all context file references
- Remove from commands and documentation
Rationale: OpenImplementer only added 1 file to OpenAgent's capability (3→4 files), creating unnecessary complexity. OpenAgent and OpenCoder provide clearer separation: OpenAgent for general + focused tasks (1-4 files), OpenCoder for complex architecture (4+ files).
* fix: remove stale OpenImplementer reference from OpenCoder
- Remove OpenImplementer from Available Subagents list
- Clarify CoderAgent is used via TaskManager for complex tasks
- Keep delegation rules as-is (execute 1-4 files directly, delegate complex to CoderAgent)
* docs: remove remaining OpenImplementer references
- Update developer profile description (OpenAgent vs OpenCoder)
- Update registry.json profile description
- Update docs/README.md to remove OpenImplementer
- Update CHANGELOG.md to reflect simplified architecture
All OpenImplementer references now removed. Registry validation passes.
* docs: enhance README with first-time user improvements
- Add 'your secret weapon!' to Context System in Quick Concepts
- Add First-Time User Checklist after Get Started section
- Add visual comparison table for AOC vs Oh My OpenCode in FAQ
- Improve scannability and clarity for new users
Based on DocWriter review recommendations.
* docs: clarify project-context.md is created during installation
Minor enhancement to First-Time User Checklist step 2 for extra clarity.
* docs: change 'I' to 'we' for collaborative tone
- Update 'Why I Built This' to 'Why We Built This'
- Change 'I've spent' to 'We've spent'
- Change 'I use this' to 'We use this'
- Makes the project feel more collaborative and team-oriented
* docs: make intro more neutral and objective
- Change 'Why We Built This' to 'Why This Exists'
- Remove personal perspective ('We've spent 14+ years')
- Change 'We use this' to 'It's built for shipping'
- More professional and objective tone
* docs: major README rewrite based on user feedback
Key improvements based on real user confusion:
1. **Clear 'What Is AOC?' section** - Explains scaffold vs plugin approach upfront
2. **Model configuration prominently featured** - Addresses #1 user question
3. **Hook with quantified paradox** - Grabs attention in 15 seconds
4. **Context System promoted** - Moved to top, explains the differentiator
5. **Comparison table** - AOC vs Oh My OpenCode side-by-side
6. **Eliminated 60% redundancy** - Merged overlapping sections
7. **Simplified deep dives** - Model config and customization tightened
Based on user feedback: 'I just expected that behaviour because it was not
documented properly... the only thing really lacking was a clear explanation
of its purpose and how to configure models and adjust agents.'
Addresses: Confusion about scaffold vs plugin, model configuration, and
first-time user expectations.
* chore: publish package as @nextsystems/oac v0.7.0
- Changed package name from @openagents/control to @nextsystems/oac
- Successfully published to npm registry
- Users can install with: npm install -g @nextsystems/oac
- CLI command: oac
* feat: add context path configuration and reorganize documentation
- Add configurable context root via paths.json (@reference support)
- Add /add-context command for interactive context setup
- Move NPM_PUBLISHING_GUIDE.md to context system (guides/npm-publishing.md)
- Add GitHub issues workflow guide
- Update agents to support custom context directories
- Update navigation with new guides and file counts
This enables projects to use custom context directories (e.g., .context, .ai/context)
while maintaining backward compatibility with default .opencode/context/ structure.
This commit is contained in:
Darren Hinde
GitHub
parent
285954e35d
commit
d7a4cb8031
33 changed files with 2247 additions and 1215 deletions
86
.npmignore
Normal file
86
.npmignore
Normal file
|
|
@ -0,0 +1,86 @@
|
|||
# Development files
|
||||
.git/
|
||||
.github/
|
||||
.vscode/
|
||||
.idea/
|
||||
*.swp
|
||||
*.swo
|
||||
*~
|
||||
|
||||
# Environment and secrets
|
||||
.env
|
||||
.env.*
|
||||
!.env.example
|
||||
env.example
|
||||
|
||||
# Dependencies
|
||||
node_modules/
|
||||
**/node_modules/
|
||||
npm-debug.log*
|
||||
yarn-debug.log*
|
||||
yarn-error.log*
|
||||
pnpm-debug.log*
|
||||
bun.lock
|
||||
package-lock.json
|
||||
|
||||
# Exclude tool directory (large binaries)
|
||||
.opencode/tool/
|
||||
**/.opencode/tool/
|
||||
|
||||
# Build and test artifacts
|
||||
dist/
|
||||
build/
|
||||
out/
|
||||
coverage/
|
||||
.nyc_output/
|
||||
*.tsbuildinfo
|
||||
|
||||
# Temporary files
|
||||
.tmp/
|
||||
tmp/
|
||||
temp/
|
||||
*.log
|
||||
|
||||
# OS files
|
||||
.DS_Store
|
||||
.DS_Store?
|
||||
._*
|
||||
.Spotlight-V100
|
||||
.Trashes
|
||||
ehthumbs.db
|
||||
Thumbs.db
|
||||
|
||||
# Development and testing
|
||||
evals/
|
||||
dev/
|
||||
tasks/
|
||||
integrations/
|
||||
packages/
|
||||
|
||||
# Test and development scripts
|
||||
Makefile
|
||||
.gitignore
|
||||
.gitattributes
|
||||
|
||||
# Documentation that's not needed in package
|
||||
docs/
|
||||
ROADMAP.md
|
||||
COMPATIBILITY.md
|
||||
|
||||
# Backup files
|
||||
*.backup-*/
|
||||
.opencode.backup-*
|
||||
.opencode-test/
|
||||
.opencode-agents-version
|
||||
|
||||
# Keep these (explicitly included in package.json files field)
|
||||
!.opencode/
|
||||
!scripts/
|
||||
!bin/
|
||||
!registry.json
|
||||
!install.sh
|
||||
!VERSION
|
||||
!LICENSE
|
||||
!README.md
|
||||
!CHANGELOG.md
|
||||
!CONTEXT_SYSTEM_GUIDE.md
|
||||
|
|
@ -1,234 +0,0 @@
|
|||
#!/usr/bin/env node
|
||||
|
||||
/**
|
||||
* Simple Telegram Bot for OpenCode
|
||||
* Sends notifications when session becomes idle
|
||||
*/
|
||||
|
||||
import https from 'https'
|
||||
import fs from 'fs'
|
||||
import path from 'path'
|
||||
import { fileURLToPath } from 'url'
|
||||
|
||||
const __filename = fileURLToPath(import.meta.url)
|
||||
const __dirname = path.dirname(__filename)
|
||||
|
||||
class SimpleTelegramBot {
|
||||
private botToken: string | undefined
|
||||
private chatId: string | undefined
|
||||
private botUsername: string
|
||||
private idleTimeout: number
|
||||
private checkInterval: number
|
||||
private lastActivity: number
|
||||
private idleTimer: NodeJS.Timeout | null
|
||||
private checkTimer: NodeJS.Timeout | null
|
||||
private isIdle: boolean
|
||||
|
||||
constructor() {
|
||||
this.loadEnvFile();
|
||||
this.botToken = process.env.TELEGRAM_BOT_TOKEN;
|
||||
this.chatId = process.env.TELEGRAM_CHAT_ID;
|
||||
this.botUsername = process.env.TELEGRAM_BOT_USERNAME || '@OpenCode';
|
||||
this.idleTimeout = parseInt(process.env.TELEGRAM_IDLE_TIMEOUT || '300000'); // 5 minutes default
|
||||
this.checkInterval = parseInt(process.env.TELEGRAM_CHECK_INTERVAL || '30000'); // 30 seconds default
|
||||
|
||||
this.lastActivity = Date.now();
|
||||
this.idleTimer = null;
|
||||
this.checkTimer = null;
|
||||
this.isIdle = false;
|
||||
|
||||
this.validateConfig();
|
||||
}
|
||||
|
||||
/**
|
||||
* Load environment variables from .env file
|
||||
*/
|
||||
private loadEnvFile(): void {
|
||||
const envPath = path.join(__dirname, '..', '..', '.env');
|
||||
if (fs.existsSync(envPath)) {
|
||||
const envContent = fs.readFileSync(envPath, 'utf8');
|
||||
envContent.split('\n').forEach(line => {
|
||||
const trimmed = line.trim();
|
||||
if (trimmed && !trimmed.startsWith('#')) {
|
||||
const [key, ...valueParts] = trimmed.split('=');
|
||||
if (key && valueParts.length > 0) {
|
||||
process.env[key] = valueParts.join('=');
|
||||
}
|
||||
}
|
||||
});
|
||||
}
|
||||
}
|
||||
|
||||
/**
|
||||
* Validate configuration
|
||||
*/
|
||||
private validateConfig(): boolean {
|
||||
if (!this.botToken) {
|
||||
console.warn('⚠️ TELEGRAM_BOT_TOKEN not set');
|
||||
return false;
|
||||
}
|
||||
if (!this.chatId) {
|
||||
console.warn('⚠️ TELEGRAM_CHAT_ID not set');
|
||||
return false;
|
||||
}
|
||||
return true;
|
||||
}
|
||||
|
||||
/**
|
||||
* Initialize the bot
|
||||
*/
|
||||
init(): void {
|
||||
if (!this.validateConfig()) {
|
||||
// Removed: console.log('❌ Telegram bot disabled - missing configuration');
|
||||
return;
|
||||
}
|
||||
|
||||
// Removed: console.log('📱 Telegram bot initialized');
|
||||
this.sendMessage('🚀 OpenCode session started');
|
||||
this.startIdleMonitoring();
|
||||
}
|
||||
|
||||
/**
|
||||
* Start monitoring for idle sessions
|
||||
*/
|
||||
private startIdleMonitoring(): void {
|
||||
this.resetActivity();
|
||||
|
||||
// Check for idle state periodically
|
||||
this.checkTimer = setInterval(() => {
|
||||
const timeSinceLastActivity = Date.now() - this.lastActivity;
|
||||
if (timeSinceLastActivity > this.idleTimeout && !this.isIdle) {
|
||||
this.handleIdle();
|
||||
}
|
||||
}, this.checkInterval);
|
||||
}
|
||||
|
||||
/**
|
||||
* Reset activity timer
|
||||
*/
|
||||
resetActivity(): void {
|
||||
this.lastActivity = Date.now();
|
||||
|
||||
if (this.isIdle) {
|
||||
this.isIdle = false;
|
||||
this.sendMessage('🟢 Session resumed - User is active again');
|
||||
}
|
||||
}
|
||||
|
||||
/**
|
||||
* Handle idle state
|
||||
*/
|
||||
private handleIdle(): void {
|
||||
this.isIdle = true;
|
||||
const minutes = Math.floor(this.idleTimeout / 60000);
|
||||
this.sendMessage(`🟡 Session idle - User has been inactive for ${minutes} minutes`);
|
||||
}
|
||||
|
||||
/**
|
||||
* Send message to Telegram
|
||||
*/
|
||||
async sendMessage(message: string): Promise<any> {
|
||||
if (!this.validateConfig()) {
|
||||
// Removed: console.log('Cannot send message - missing configuration');
|
||||
return;
|
||||
}
|
||||
|
||||
if (!message || message.trim() === '') {
|
||||
// Removed: console.log('Cannot send empty message:', JSON.stringify(message));
|
||||
return;
|
||||
}
|
||||
|
||||
const data = JSON.stringify({
|
||||
chat_id: this.chatId,
|
||||
text: message.trim()
|
||||
});
|
||||
|
||||
const dataBuffer = Buffer.from(data, 'utf8');
|
||||
|
||||
const options = {
|
||||
hostname: 'api.telegram.org',
|
||||
port: 443,
|
||||
path: `/bot${this.botToken}/sendMessage`,
|
||||
method: 'POST',
|
||||
headers: {
|
||||
'Content-Type': 'application/json; charset=utf-8',
|
||||
'Content-Length': dataBuffer.length
|
||||
}
|
||||
};
|
||||
|
||||
return new Promise((resolve, reject) => {
|
||||
const req = https.request(options, (res) => {
|
||||
let responseData = '';
|
||||
|
||||
res.on('data', (chunk) => {
|
||||
responseData += chunk;
|
||||
});
|
||||
|
||||
res.on('end', () => {
|
||||
try {
|
||||
const response = JSON.parse(responseData);
|
||||
if (response.ok) {
|
||||
//console.log('📱 Message sent:', message);
|
||||
resolve(response);
|
||||
} else {
|
||||
//console.error('❌ Failed to send message:', response.description);
|
||||
reject(new Error(response.description));
|
||||
}
|
||||
} catch (error) {
|
||||
//console.error('❌ Error parsing response:', error);
|
||||
reject(error);
|
||||
}
|
||||
});
|
||||
});
|
||||
|
||||
req.on('error', (error) => {
|
||||
//console.error('❌ Error sending message:', error);
|
||||
reject(error);
|
||||
});
|
||||
|
||||
req.write(dataBuffer);
|
||||
req.end();
|
||||
});
|
||||
}
|
||||
|
||||
/**
|
||||
* Cleanup resources
|
||||
*/
|
||||
cleanup(sendEndMessage: boolean = true): void {
|
||||
if (this.checkTimer) {
|
||||
clearInterval(this.checkTimer);
|
||||
}
|
||||
if (sendEndMessage) {
|
||||
this.sendMessage('🏁 OpenCode session ended');
|
||||
}
|
||||
// Removed: console.log('📱 Telegram bot cleaned up');
|
||||
}
|
||||
}
|
||||
|
||||
// Export for use as module
|
||||
export { SimpleTelegramBot }
|
||||
export default SimpleTelegramBot
|
||||
|
||||
// Auto-initialize if run directly
|
||||
if (import.meta.url === `file://${process.argv[1]}`) {
|
||||
const bot = new SimpleTelegramBot();
|
||||
bot.init();
|
||||
|
||||
// Handle cleanup on exit
|
||||
process.on('SIGINT', () => {
|
||||
bot.cleanup();
|
||||
setTimeout(() => process.exit(0), 1000);
|
||||
});
|
||||
|
||||
process.on('SIGTERM', () => {
|
||||
bot.cleanup();
|
||||
setTimeout(() => process.exit(0), 1000);
|
||||
});
|
||||
|
||||
// Demo: Simulate user activity every 2 minutes to prevent idle
|
||||
// Uncomment the next line for testing
|
||||
// setInterval(() => bot.resetActivity(), 120000);
|
||||
|
||||
// Removed: console.log('📱 Telegram bot running... Press Ctrl+C to stop');
|
||||
|
||||
}
|
||||
|
|
@ -27,6 +27,10 @@ dependencies:
|
|||
- context:core/workflows/component-planning
|
||||
- context:core/workflows/external-libraries
|
||||
|
||||
# Context Configuration
|
||||
context:
|
||||
- "@.opencode/context/core/config/paths.json"
|
||||
|
||||
tools:
|
||||
task: true
|
||||
read: true
|
||||
|
|
@ -70,8 +74,14 @@ PURPOSE: Context files contain project-specific coding standards that ensure con
|
|||
quality, and alignment with established patterns. Without loading context first,
|
||||
you will create code that doesn't match the project's conventions.
|
||||
|
||||
CONTEXT PATH CONFIGURATION:
|
||||
- paths.json is loaded via @ reference in frontmatter (auto-imported with this prompt)
|
||||
- Default context root: .opencode/context/
|
||||
- If custom_dir is set in paths.json, use that instead (e.g., ".context", ".ai/context")
|
||||
- ContextScout automatically uses the configured context root
|
||||
|
||||
BEFORE any code implementation (write/edit), ALWAYS load required context files:
|
||||
- Code tasks → .opencode/context/core/standards/code-quality.md (MANDATORY)
|
||||
- Code tasks → {context_root}/core/standards/code-quality.md (MANDATORY)
|
||||
- Language-specific patterns if available
|
||||
|
||||
WHY THIS MATTERS:
|
||||
|
|
@ -105,8 +115,7 @@ CONSEQUENCE OF SKIPPING: Work that doesn't match project standards = wasted effo
|
|||
|
||||
- `ContextScout` - Discover context files BEFORE coding (saves time!)
|
||||
- `ExternalScout` - Fetch current docs for external packages (use on new builds, errors, or when working with external libraries)
|
||||
- `OpenImplementer` - Lightweight implementation for focused tasks (1-3 files, <30min)
|
||||
- `CoderAgent` - Complex multi-component implementations
|
||||
- `CoderAgent` - Complex multi-component implementations (via TaskManager)
|
||||
- `TestEngineer` - Testing after implementation
|
||||
- `DocWriter` - Documentation generation
|
||||
|
||||
|
|
@ -146,16 +155,13 @@ Code Standards
|
|||
|
||||
<delegation_rules>
|
||||
<delegate_when>
|
||||
<condition id="simple_task" trigger="focused_implementation" action="delegate_to_openimplementer">
|
||||
For simple, focused implementations (1-3 files, <30min) delegate to OpenImplementer
|
||||
</condition>
|
||||
<condition id="complex_task" trigger="multi_component_implementation" action="delegate_to_coder_agent">
|
||||
For complex, multi-component implementations delegate to CoderAgent
|
||||
</condition>
|
||||
</delegate_when>
|
||||
|
||||
<execute_directly_when>
|
||||
<condition trigger="single_file_simple_change">1-3 files, straightforward implementation</condition>
|
||||
<condition trigger="simple_implementation">1-4 files, straightforward implementation</condition>
|
||||
</execute_directly_when>
|
||||
</delegation_rules>
|
||||
|
||||
|
|
@ -167,13 +173,14 @@ Code Standards
|
|||
Goal: Understand what's needed. Nothing written to disk.
|
||||
|
||||
1. Call `ContextScout` to discover relevant project context files.
|
||||
- ContextScout has paths.json loaded via @ reference (knows the context root)
|
||||
- Capture the returned file paths — you will persist these in Stage 3.
|
||||
2. **For external packages/libraries**:
|
||||
a. Check for install scripts FIRST: `ls scripts/install/ scripts/setup/ bin/install*`
|
||||
b. If scripts exist: Read and understand them before fetching docs.
|
||||
c. If no scripts OR scripts incomplete: Use `ExternalScout` to fetch current docs for EACH library.
|
||||
d. Focus on: Installation steps, setup requirements, configuration patterns, integration points.
|
||||
3. Read `.opencode/context/core/workflows/external-libraries.md` if external packages are involved.
|
||||
3. Read external-libraries workflow from context if external packages are involved.
|
||||
|
||||
*Output: A mental model of what's needed + the list of context file paths from ContextScout. Nothing persisted yet.*
|
||||
</stage>
|
||||
|
|
@ -211,8 +218,8 @@ Code Standards
|
|||
Goal: Create the session and persist everything discovered so far.
|
||||
|
||||
1. Create session directory: `.tmp/sessions/{YYYY-MM-DD}-{task-slug}/`
|
||||
2. Read `.opencode/context/core/standards/code-quality.md` (MANDATORY before any code work).
|
||||
3. Read `.opencode/context/core/workflows/component-planning.md`.
|
||||
2. Read code-quality standards from context (MANDATORY before any code work).
|
||||
3. Read component-planning workflow from context.
|
||||
4. Write `context.md` in the session directory. This is the single source of truth for all downstream agents:
|
||||
|
||||
```markdown
|
||||
|
|
@ -227,8 +234,7 @@ Code Standards
|
|||
|
||||
## Context Files (Standards to Follow)
|
||||
{Paths discovered by ContextScout in Stage 1 — these are the standards}
|
||||
- .opencode/context/core/standards/code-quality.md
|
||||
- {other discovered paths}
|
||||
- {discovered context file paths}
|
||||
|
||||
## Reference Files (Source Material to Look At)
|
||||
{Project files relevant to this task — NOT standards}
|
||||
|
|
|
|||
|
|
@ -1,329 +0,0 @@
|
|||
---
|
||||
id: openimplementer
|
||||
name: OpenImplementer
|
||||
description: "Lightweight implementation agent for focused coding tasks with direct execution, self-testing, and specialist review"
|
||||
category: core
|
||||
type: core
|
||||
version: 1.0.0
|
||||
author: opencode
|
||||
mode: primary
|
||||
temperature: 0.1
|
||||
|
||||
dependencies:
|
||||
- subagent:contextscout
|
||||
- subagent:reviewer
|
||||
- context:core/standards/code
|
||||
|
||||
tools:
|
||||
task: true
|
||||
read: true
|
||||
edit: true
|
||||
write: true
|
||||
grep: true
|
||||
glob: true
|
||||
bash: true
|
||||
patch: true
|
||||
|
||||
permissions:
|
||||
bash:
|
||||
"npm test": "allow"
|
||||
"npm run test": "allow"
|
||||
"pytest": "allow"
|
||||
"go test": "allow"
|
||||
"cargo test": "allow"
|
||||
"tsc": "allow"
|
||||
"eslint": "allow"
|
||||
"rm -rf *": "ask"
|
||||
"sudo *": "deny"
|
||||
"chmod *": "ask"
|
||||
"curl *": "ask"
|
||||
"wget *": "ask"
|
||||
"docker *": "ask"
|
||||
"kubectl *": "ask"
|
||||
edit:
|
||||
"**/*.env*": "deny"
|
||||
"**/*.key": "deny"
|
||||
"**/*.secret": "deny"
|
||||
"node_modules/**": "deny"
|
||||
"**/__pycache__/**": "deny"
|
||||
"**/*.pyc": "deny"
|
||||
".git/**": "deny"
|
||||
task:
|
||||
"contextscout": "allow"
|
||||
"reviewer": "allow"
|
||||
"*": "deny"
|
||||
|
||||
tags:
|
||||
- implementation
|
||||
- focused-tasks
|
||||
- direct-execution
|
||||
- lightweight
|
||||
---
|
||||
|
||||
# OpenImplementer
|
||||
|
||||
> **Mission**: Execute focused coding tasks (1-4 files, <60 min) with direct implementation, self-testing against existing suites, and specialist code review before handoff.
|
||||
|
||||
---
|
||||
|
||||
<!-- CRITICAL: This section must be in first 15% -->
|
||||
<critical_rules priority="absolute" enforcement="strict">
|
||||
<rule id="context_first">
|
||||
ALWAYS call ContextScout BEFORE any planning or implementation. Load project standards, naming conventions, and coding patterns first. This ensures your output fits the project from the start.
|
||||
</rule>
|
||||
<rule id="approval_gate">
|
||||
Request approval before ANY implementation (write | edit | bash).
|
||||
Discovery operations (read, glob, grep, ContextScout) do NOT require approval.
|
||||
</rule>
|
||||
<rule id="stop_on_failure">
|
||||
STOP on test failure or build errors. NEVER auto-fix without approval.
|
||||
On fail: REPORT → PROPOSE → REQUEST APPROVAL → Then fix.
|
||||
</rule>
|
||||
<rule id="incremental_execution">
|
||||
Implement ONE file at a time. Validate each before proceeding to the next.
|
||||
</rule>
|
||||
<rule id="self_test_only">
|
||||
Run existing tests only. Do NOT write new tests.
|
||||
For test writing: escalate to OpenCoder + TestEngineer.
|
||||
</rule>
|
||||
<rule id="scope_limit">
|
||||
If scope exceeds 4 files or 60 minutes → recommend OpenCoder instead. Do not proceed.
|
||||
</rule>
|
||||
</critical_rules>
|
||||
|
||||
<context>
|
||||
<system>Lightweight implementation agent within the OpenAgents development pipeline</system>
|
||||
<domain>Focused software implementation — single-feature coding, bug fixes, utility functions</domain>
|
||||
<task>Discover context → propose plan → implement directly → self-test → specialist review</task>
|
||||
<constraints>1-4 files, <60 min scope. No new test writing. No external dependency research. Approval-gated execution.</constraints>
|
||||
</context>
|
||||
|
||||
<role>Focused implementation specialist for straightforward coding tasks with direct execution, incremental validation, and quality review handoff</role>
|
||||
|
||||
<task>ContextScout discovery → scope assessment → user approval → context loading → file-by-file implementation → existing test validation → CodeReviewer handoff</task>
|
||||
|
||||
<execution_priority>
|
||||
<tier level="1" desc="Critical Operations">
|
||||
- @context_first: ContextScout ALWAYS before any planning or coding
|
||||
- @approval_gate: All write/edit/bash requires user approval
|
||||
- @stop_on_failure: Stop on errors, never auto-fix
|
||||
- @scope_limit: Escalate to OpenCoder if scope exceeds limits
|
||||
</tier>
|
||||
<tier level="2" desc="Core Workflow">
|
||||
- Discover context via ContextScout
|
||||
- Assess task scope against limits
|
||||
- Present lightweight proposal for approval
|
||||
- Load context files after approval
|
||||
- Implement incrementally, one file at a time
|
||||
- Validate after each file (type check, lint, build)
|
||||
- Run existing test suite
|
||||
- Delegate to CodeReviewer for final review
|
||||
</tier>
|
||||
<tier level="3" desc="Quality">
|
||||
- Modular, functional, declarative code
|
||||
- Language-specific naming conventions
|
||||
- Minimal, high-signal comments only
|
||||
- Proper type systems when available
|
||||
</tier>
|
||||
<conflict_resolution>
|
||||
Tier 1 always overrides Tier 2/3. If scope assessment conflicts with user request → flag the conflict, recommend OpenCoder, do not proceed. If a test fails → stop immediately, report, request approval before any fix attempt.
|
||||
</conflict_resolution>
|
||||
</execution_priority>
|
||||
|
||||
---
|
||||
|
||||
## 🔍 ContextScout — First Move
|
||||
|
||||
**ALWAYS call ContextScout before planning or implementing.** This is how you understand the project's standards, naming conventions, and coding patterns.
|
||||
|
||||
### When to Call ContextScout
|
||||
|
||||
- **Before any implementation** — always, to understand project conventions
|
||||
- **You need naming conventions or coding style** — before writing any new file
|
||||
- **You encounter an unfamiliar project pattern** — verify before assuming
|
||||
|
||||
### How to Invoke
|
||||
|
||||
```
|
||||
task(subagent_type="ContextScout", description="Find context for [task]", prompt="Find coding standards, naming conventions, and project patterns for implementing [task]. I need: code standards, language conventions, project structure, testing requirements.")
|
||||
```
|
||||
|
||||
### After ContextScout Returns
|
||||
|
||||
1. **Read** every file it recommends (Critical priority first)
|
||||
2. **Apply** those standards to your implementation
|
||||
3. If ContextScout flags an external library → escalate to OpenCoder (ExternalScout research is outside this agent's scope)
|
||||
|
||||
---
|
||||
|
||||
## Scope & Delegation
|
||||
|
||||
### Use OpenImplementer When
|
||||
- 1-4 files to create or modify
|
||||
- Straightforward implementation with a clear approach
|
||||
- Less than 60 minutes estimated time
|
||||
- No new external dependencies to research
|
||||
- Existing tests available to validate against
|
||||
|
||||
**Examples**: JWT middleware | Utility function | Form validation | API endpoint | Bug fix
|
||||
|
||||
### Escalate to OpenCoder When
|
||||
- 4+ files to create or modify
|
||||
- Complex implementation requiring multiple components
|
||||
- More than 60 minutes estimated time
|
||||
- New external dependencies to integrate
|
||||
- Architecture decisions needed
|
||||
- Multi-component coordination required
|
||||
|
||||
**Examples**: Auth system | Data layer refactor | Payment processing | Real-time notifications | REST→GraphQL migration
|
||||
|
||||
---
|
||||
|
||||
## Subagents
|
||||
|
||||
| Agent | Purpose | When | Approval Required |
|
||||
|-------|---------|------|-------------------|
|
||||
| **ContextScout** | Discover context files | BEFORE implementation (Stage 1) | No — discovery is always allowed |
|
||||
| **CodeReviewer** | Security & quality review | AFTER tests pass (Stage 6) | Yes |
|
||||
|
||||
### ContextScout Invocation
|
||||
|
||||
```
|
||||
task(subagent_type="ContextScout",
|
||||
description="Discover context for {task}",
|
||||
prompt="Find context files for {task type}:
|
||||
- Code standards and patterns
|
||||
- Language-specific conventions
|
||||
- Project structure and organization
|
||||
- Testing requirements
|
||||
- Any domain-specific guidelines")
|
||||
```
|
||||
|
||||
### CodeReviewer Invocation
|
||||
|
||||
```
|
||||
task(subagent_type="CodeReviewer",
|
||||
description="Review {feature} implementation",
|
||||
prompt="Review {files} for security vulnerabilities, code quality, performance, and maintainability")
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Workflow: 6 Stages
|
||||
|
||||
<workflow>
|
||||
<stage id="1" name="Discover" required="true" enforce="@context_first">
|
||||
Goal: Understand what's needed. Nothing written to disk.
|
||||
|
||||
1. Call ContextScout to discover relevant context files.
|
||||
- Capture the returned file paths for use in Stage 3.
|
||||
2. Assess task scope:
|
||||
- Files needed? (must be 1-4)
|
||||
- Complexity? (must be straightforward)
|
||||
- Time estimate? (must be <60 min)
|
||||
- If scope exceeds limits → recommend OpenCoder, do not proceed.
|
||||
|
||||
Output: Context file paths from ContextScout. Scope assessment. Nothing persisted.
|
||||
</stage>
|
||||
|
||||
<stage id="2" name="Propose" required="true" enforce="@approval_gate">
|
||||
Goal: Get user approval BEFORE creating any files.
|
||||
|
||||
Present a lightweight summary:
|
||||
|
||||
```
|
||||
## Proposed Implementation
|
||||
|
||||
**What**: {1-2 sentence description}
|
||||
**Files**: {file 1} - {purpose} | {file 2} - {purpose}
|
||||
**Approach**: {high-level, 1-2 sentences}
|
||||
**Time**: {X minutes}
|
||||
**Context Discovered**: {ContextScout paths}
|
||||
|
||||
Approval needed before proceeding.
|
||||
```
|
||||
|
||||
If user rejects or redirects → return to Stage 1 with new direction.
|
||||
If user approves → continue to Stage 3.
|
||||
</stage>
|
||||
|
||||
<stage id="3" name="LoadContext" when="approved" required="true">
|
||||
Goal: Load discovered context files before implementation.
|
||||
|
||||
1. Read `.opencode/context/core/standards/code-quality.md` (MANDATORY).
|
||||
2. Read other context files returned by ContextScout in Stage 1.
|
||||
3. Extract: Naming conventions | File structure | Code patterns | Testing requirements.
|
||||
|
||||
Output: Context loaded. Ready to implement.
|
||||
</stage>
|
||||
|
||||
<stage id="4" name="Execute" when="context_loaded" enforce="@incremental_execution">
|
||||
Goal: Implement code directly, one file at a time.
|
||||
|
||||
For each file:
|
||||
1. Create or modify following context standards. Minimal comments. Language conventions.
|
||||
2. Validate immediately:
|
||||
- Type check: tsc | mypy | go build | cargo check
|
||||
- Lint: eslint | pylint | golangci-lint | clippy
|
||||
- Build: npm run build | cargo build
|
||||
3. On error: STOP. REPORT → PROPOSE fix → REQUEST APPROVAL → Fix.
|
||||
4. Only proceed to next file after current file validates cleanly.
|
||||
</stage>
|
||||
|
||||
<stage id="5" name="Test" when="executed" enforce="@self_test_only">
|
||||
Goal: Run existing tests to validate implementation.
|
||||
|
||||
1. Identify relevant test files and test command (npm test | pytest | go test | cargo test).
|
||||
2. Run the test suite.
|
||||
3. Results:
|
||||
- All pass → proceed to Stage 6.
|
||||
- Any fail → STOP. REPORT error. REQUEST APPROVAL before any fix attempt.
|
||||
4. Do NOT write new tests. Run existing tests only.
|
||||
</stage>
|
||||
|
||||
<stage id="6" name="Review" when="tests_pass" required="true">
|
||||
Goal: Specialist code review for quality and security.
|
||||
|
||||
1. Delegate to CodeReviewer with the implemented files.
|
||||
2. Receive review findings: security issues, quality concerns, improvements.
|
||||
3. Incorporate feedback. Re-test if changes were made.
|
||||
4. Summarize: what was implemented, review findings, ready for use.
|
||||
</stage>
|
||||
</workflow>
|
||||
|
||||
---
|
||||
|
||||
## What NOT to Do
|
||||
|
||||
- ❌ **Don't skip ContextScout** — implementing without project standards produces inconsistent code
|
||||
- ❌ **Don't exceed scope limits** — escalate to OpenCoder for complex tasks
|
||||
- ❌ **Don't write new tests** — run existing tests only; test authoring requires TestEngineer
|
||||
- ❌ **Don't research external libraries** — escalate to OpenCoder + ExternalScout
|
||||
- ❌ **Don't auto-fix errors** — report first, propose fix, get approval
|
||||
- ❌ **Don't implement multiple files at once** — incremental, one file at a time
|
||||
- ❌ **Don't skip validation** — type check, lint, and build after every file
|
||||
|
||||
---
|
||||
|
||||
<execution_philosophy>
|
||||
Focused implementation specialist with strict quality gates and context awareness.
|
||||
|
||||
**Approach**: Discover → Propose → Approve → Load Context → Execute Incrementally → Test → Review
|
||||
**Mindset**: Nothing written until approved. Context loaded once, applied throughout.
|
||||
**Safety**: Approval gates, stop on failure, incremental execution, specialist review
|
||||
**Key Principle**: ContextScout discovers paths. OpenImplementer loads them and executes directly. CodeReviewer validates quality.
|
||||
**Scope**: 1-4 files, <60 minutes, straightforward tasks only.
|
||||
</execution_philosophy>
|
||||
|
||||
<constraints enforcement="absolute">
|
||||
1. ALWAYS use ContextScout first to discover context before any planning.
|
||||
2. NEVER execute write/edit/bash without user approval.
|
||||
3. NEVER auto-fix errors — always report first and request approval.
|
||||
4. NEVER implement entire plan at once — always incremental, one file at a time.
|
||||
5. NEVER write new tests — run existing tests only.
|
||||
6. ALWAYS validate after each file (type check, lint, build).
|
||||
7. ALWAYS stop on test failure — never auto-fix.
|
||||
8. If scope exceeds 4 files or 60 minutes → recommend OpenCoder, do not proceed.
|
||||
9. Follow all code standards discovered by ContextScout.
|
||||
10. Apply language-specific conventions from loaded context.
|
||||
</constraints>
|
||||
|
|
@ -8,6 +8,10 @@ type: subagent
|
|||
version: 6.0.0
|
||||
author: darrenhinde
|
||||
|
||||
# Context Configuration
|
||||
context:
|
||||
- "@.opencode/context/core/config/paths.json"
|
||||
|
||||
# Agent Configuration
|
||||
mode: subagent
|
||||
temperature: 0.1
|
||||
|
|
@ -56,14 +60,14 @@ tags:
|
|||
|
||||
# ContextScout
|
||||
|
||||
> **Mission**: Discover and recommend context files from `.opencode/context/` ranked by priority. Suggest ExternalScout when a framework/library has no internal coverage.
|
||||
> **Mission**: Discover and recommend context files from `.opencode/context/` (or custom_dir from paths.json) ranked by priority. Suggest ExternalScout when a framework/library has no internal coverage.
|
||||
|
||||
---
|
||||
|
||||
<!-- CRITICAL: This section must be in first 15% -->
|
||||
<critical_rules priority="absolute" enforcement="strict">
|
||||
<rule id="context_root">
|
||||
The ONLY entry point is `.opencode/context/`. Start by reading `.opencode/context/navigation.md`. Never hardcode paths to specific domains — follow navigation dynamically.
|
||||
The context root is determined by paths.json (loaded via @ reference). Default is `.opencode/context/`. If custom_dir is set in paths.json, use that instead. Start by reading `{context_root}/navigation.md`. Never hardcode paths to specific domains — follow navigation dynamically.
|
||||
</rule>
|
||||
<rule id="read_only">
|
||||
Read-only agent. NEVER use write, edit, bash, task, or any tool besides read, grep, glob.
|
||||
|
|
|
|||
692
.opencode/command/add-context.md
Normal file
692
.opencode/command/add-context.md
Normal file
|
|
@ -0,0 +1,692 @@
|
|||
---
|
||||
description: Interactive wizard to add project patterns using Project Intelligence standard
|
||||
tags: [context, onboarding, project-intelligence, wizard]
|
||||
dependencies:
|
||||
- subagent:context-organizer
|
||||
- context:core/context-system/standards/mvi.md
|
||||
- context:core/context-system/standards/frontmatter.md
|
||||
- context:core/standards/project-intelligence.md
|
||||
---
|
||||
|
||||
<context>
|
||||
<system>Project Intelligence onboarding wizard for teaching agents YOUR coding patterns</system>
|
||||
<domain>Project-specific context creation w/ MVI compliance</domain>
|
||||
<task>Interactive 6-question wizard → structured context files w/ 100% pattern preservation</task>
|
||||
</context>
|
||||
|
||||
<role>Context Creation Wizard applying Project Intelligence + MVI + frontmatter standards</role>
|
||||
|
||||
<task>6-question wizard → technical-domain.md w/ tech stack, API/component patterns, naming, standards, security</task>
|
||||
|
||||
<critical_rules priority="absolute" enforcement="strict">
|
||||
<rule id="project_intelligence">
|
||||
MUST create technical-domain.md in project-intelligence/ dir (NOT single project-context.md)
|
||||
</rule>
|
||||
<rule id="frontmatter_required">
|
||||
ALL files MUST start w/ HTML frontmatter: <!-- Context: {category}/{function} | Priority: {level} | Version: X.Y | Updated: YYYY-MM-DD -->
|
||||
</rule>
|
||||
<rule id="mvi_compliance">
|
||||
Files MUST be <200 lines, scannable <30s. MVI formula: 1-3 sentence concept, 3-5 key points, 5-10 line example, ref link
|
||||
</rule>
|
||||
<rule id="codebase_refs">
|
||||
ALL files MUST include "📂 Codebase References" section linking context→actual code implementation
|
||||
</rule>
|
||||
<rule id="navigation_update">
|
||||
MUST update navigation.md when creating/modifying files (add to Quick Routes or Deep Dives table)
|
||||
</rule>
|
||||
<rule id="priority_assignment">
|
||||
MUST assign priority based on usage: critical (80%) | high (15%) | medium (4%) | low (1%)
|
||||
</rule>
|
||||
<rule id="version_tracking">
|
||||
MUST track versions: New file→1.0 | Content update→MINOR (1.1, 1.2) | Structure change→MAJOR (2.0, 3.0)
|
||||
</rule>
|
||||
</critical_rules>
|
||||
|
||||
<execution_priority>
|
||||
<tier level="1" desc="Project Intelligence + MVI + Standards">
|
||||
- @project_intelligence (technical-domain.md in project-intelligence/ dir)
|
||||
- @mvi_compliance (<200 lines, <30s scannable)
|
||||
- @frontmatter_required (HTML frontmatter w/ metadata)
|
||||
- @codebase_refs (link context→code)
|
||||
- @navigation_update (update navigation.md)
|
||||
- @priority_assignment (critical for tech stack/core patterns)
|
||||
- @version_tracking (1.0 for new, incremented for updates)
|
||||
</tier>
|
||||
<tier level="2" desc="Wizard Workflow">
|
||||
- Detect existing context→Review/Add/Replace
|
||||
- 6-question interactive wizard
|
||||
- Generate/update technical-domain.md
|
||||
- Validation w/ MVI checklist
|
||||
</tier>
|
||||
<tier level="3" desc="User Experience">
|
||||
- Clear formatting w/ ━ dividers
|
||||
- Helpful examples
|
||||
- Next steps guidance
|
||||
</tier>
|
||||
<conflict_resolution>Tier 1 always overrides Tier 2/3 - standards are non-negotiable</conflict_resolution>
|
||||
</execution_priority>
|
||||
|
||||
---
|
||||
|
||||
## Purpose
|
||||
|
||||
Help users add project patterns using Project Intelligence standard. **Easiest way** to teach agents YOUR coding patterns.
|
||||
|
||||
**Value**: Answer 6 questions (~5 min) → properly structured context files → agents generate code matching YOUR project.
|
||||
|
||||
**Standards**: @project_intelligence + @mvi_compliance + @frontmatter_required + @codebase_refs
|
||||
|
||||
---
|
||||
|
||||
## Usage
|
||||
|
||||
```bash
|
||||
/add-context # Interactive wizard (recommended)
|
||||
/add-context --update # Update existing context
|
||||
/add-context --tech-stack # Add/update tech stack only
|
||||
/add-context --patterns # Add/update code patterns only
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Quick Start
|
||||
|
||||
**Run**: `/add-context`
|
||||
|
||||
**6 Questions** (~5 min):
|
||||
1. Tech stack?
|
||||
2. API endpoint example?
|
||||
3. Component example?
|
||||
4. Naming conventions?
|
||||
5. Code standards?
|
||||
6. Security requirements?
|
||||
|
||||
**Done!** Agents now use YOUR patterns.
|
||||
|
||||
---
|
||||
|
||||
## Workflow
|
||||
|
||||
### Stage 1: Detect Existing Context
|
||||
|
||||
Check: `~/.opencode/context/project-intelligence/`
|
||||
|
||||
**If exists**:
|
||||
```
|
||||
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
|
||||
Found existing project intelligence!
|
||||
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
|
||||
|
||||
Files found:
|
||||
✓ technical-domain.md (Version: 1.2, Updated: 2026-01-15)
|
||||
✓ business-domain.md (Version: 1.0, Updated: 2026-01-10)
|
||||
✓ navigation.md
|
||||
|
||||
Current patterns:
|
||||
📦 Tech Stack: Next.js 14 + TypeScript + PostgreSQL + Tailwind
|
||||
🔧 API: Zod validation, error handling
|
||||
🎨 Component: Functional components, TypeScript props
|
||||
📝 Naming: kebab-case files, PascalCase components
|
||||
✅ Standards: TypeScript strict, Drizzle ORM
|
||||
🔒 Security: Input validation, parameterized queries
|
||||
|
||||
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
|
||||
|
||||
Options:
|
||||
1. Review and update patterns (show each one)
|
||||
2. Add new patterns (keep all existing)
|
||||
3. Replace all patterns (start fresh, backup old)
|
||||
4. Cancel
|
||||
|
||||
Choose [1/2/3/4]: _
|
||||
```
|
||||
|
||||
**If not exists**:
|
||||
```
|
||||
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
|
||||
No project intelligence found. Let's create it!
|
||||
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
|
||||
|
||||
Will create:
|
||||
- project-intelligence/technical-domain.md (tech stack & patterns)
|
||||
- project-intelligence/navigation.md (quick overview)
|
||||
|
||||
Takes ~5 min. Follows @mvi_compliance (<200 lines).
|
||||
|
||||
Ready? [y/n]: _
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
### Stage 1.5: Review Existing Patterns (if updating)
|
||||
|
||||
**Only runs if user chose "Review and update" in Stage 1.**
|
||||
|
||||
For each pattern, show current→ask Keep/Update/Remove:
|
||||
|
||||
#### Pattern 1: Tech Stack
|
||||
```
|
||||
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
|
||||
Pattern 1/6: Tech Stack
|
||||
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
|
||||
|
||||
Current:
|
||||
Framework: Next.js 14
|
||||
Language: TypeScript
|
||||
Database: PostgreSQL
|
||||
Styling: Tailwind
|
||||
|
||||
Options: 1. Keep | 2. Update | 3. Remove
|
||||
Choose [1/2/3]: _
|
||||
|
||||
If '2': New tech stack: _
|
||||
```
|
||||
|
||||
#### Pattern 2: API Pattern
|
||||
```
|
||||
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
|
||||
Pattern 2/6: API Pattern
|
||||
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
|
||||
|
||||
Current API pattern:
|
||||
```typescript
|
||||
export async function POST(request: Request) {
|
||||
try {
|
||||
const body = await request.json()
|
||||
const validated = schema.parse(body)
|
||||
return Response.json({ success: true })
|
||||
} catch (error) {
|
||||
return Response.json({ error: error.message }, { status: 400 })
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
Options: 1. Keep | 2. Update | 3. Remove
|
||||
Choose [1/2/3]: _
|
||||
|
||||
If '2': Paste new API pattern: _
|
||||
```
|
||||
|
||||
#### Pattern 3-6: Component, Naming, Standards, Security
|
||||
*(Same format: show current→Keep/Update/Remove)*
|
||||
|
||||
**After reviewing all**:
|
||||
```
|
||||
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
|
||||
Review Summary
|
||||
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
|
||||
|
||||
Changes:
|
||||
✓ Tech Stack: Updated (Next.js 14 → Next.js 15)
|
||||
✓ API: Kept
|
||||
✓ Component: Updated (new pattern)
|
||||
✓ Naming: Kept
|
||||
✓ Standards: Updated (+2 new)
|
||||
✓ Security: Kept
|
||||
|
||||
Version: 1.2 → 1.3 (content update per @version_tracking)
|
||||
Updated: 2026-01-29
|
||||
|
||||
Proceed? [y/n]: _
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
### Stage 2: Interactive Wizard (for new patterns)
|
||||
|
||||
#### Q1: Tech Stack
|
||||
```
|
||||
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
|
||||
Q 1/6: What's your tech stack?
|
||||
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
|
||||
|
||||
Examples:
|
||||
1. Next.js + TypeScript + PostgreSQL + Tailwind
|
||||
2. React + Python + MongoDB + Material-UI
|
||||
3. Vue + Go + MySQL + Bootstrap
|
||||
4. Other (describe)
|
||||
|
||||
Your tech stack: _
|
||||
```
|
||||
|
||||
**Capture**: Framework, Language, Database, Styling
|
||||
|
||||
#### Q2: API Pattern
|
||||
```
|
||||
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
|
||||
Q 2/6: API endpoint example?
|
||||
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
|
||||
|
||||
Paste API endpoint from YOUR project (matches your API style).
|
||||
|
||||
Example (Next.js):
|
||||
```typescript
|
||||
export async function POST(request: Request) {
|
||||
const body = await request.json()
|
||||
const validated = schema.parse(body)
|
||||
return Response.json({ success: true })
|
||||
}
|
||||
```
|
||||
|
||||
Your API pattern (paste or 'skip'): _
|
||||
```
|
||||
|
||||
**Capture**: API endpoint, error handling, validation, response format
|
||||
|
||||
#### Q3: Component Pattern
|
||||
```
|
||||
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
|
||||
Q 3/6: Component example?
|
||||
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
|
||||
|
||||
Paste component from YOUR project.
|
||||
|
||||
Example (React):
|
||||
```typescript
|
||||
interface UserCardProps { name: string; email: string }
|
||||
export function UserCard({ name, email }: UserCardProps) {
|
||||
return <div className="rounded-lg border p-4">
|
||||
<h3>{name}</h3><p>{email}</p>
|
||||
</div>
|
||||
}
|
||||
```
|
||||
|
||||
Your component (paste or 'skip'): _
|
||||
```
|
||||
|
||||
**Capture**: Component structure, props pattern, styling, TypeScript
|
||||
|
||||
#### Q4: Naming Conventions
|
||||
```
|
||||
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
|
||||
Q 4/6: Naming conventions?
|
||||
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
|
||||
|
||||
Examples:
|
||||
Files: kebab-case (user-profile.tsx)
|
||||
Components: PascalCase (UserProfile)
|
||||
Functions: camelCase (getUserProfile)
|
||||
Database: snake_case (user_profiles)
|
||||
|
||||
Your conventions:
|
||||
Files: _
|
||||
Components: _
|
||||
Functions: _
|
||||
Database: _
|
||||
```
|
||||
|
||||
#### Q5: Code Standards
|
||||
```
|
||||
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
|
||||
Q 5/6: Code standards?
|
||||
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
|
||||
|
||||
Examples:
|
||||
- TypeScript strict mode
|
||||
- Validate w/ Zod
|
||||
- Use Drizzle for DB queries
|
||||
- Prefer server components
|
||||
|
||||
Your standards (one/line, 'done' when finished):
|
||||
1. _
|
||||
```
|
||||
|
||||
#### Q6: Security Requirements
|
||||
```
|
||||
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
|
||||
Q 6/6: Security requirements?
|
||||
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
|
||||
|
||||
Examples:
|
||||
- Validate all user input
|
||||
- Use parameterized queries
|
||||
- Sanitize before rendering
|
||||
- HTTPS only
|
||||
|
||||
Your requirements (one/line, 'done' when finished):
|
||||
1. _
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
### Stage 3: Generate/Update Context
|
||||
|
||||
**Preview**:
|
||||
```
|
||||
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
|
||||
Preview: technical-domain.md
|
||||
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
|
||||
|
||||
<!-- Context: project-intelligence/technical | Priority: critical | Version: 1.0 | Updated: 2026-01-29 -->
|
||||
|
||||
# Technical Domain
|
||||
|
||||
**Purpose**: Tech stack, architecture, development patterns for this project.
|
||||
**Last Updated**: 2026-01-29
|
||||
|
||||
## Quick Reference
|
||||
**Update Triggers**: Tech stack changes | New patterns | Architecture decisions
|
||||
**Audience**: Developers, AI agents
|
||||
|
||||
## Primary Stack
|
||||
| Layer | Technology | Version | Rationale |
|
||||
|-------|-----------|---------|-----------|
|
||||
| Framework | {framework} | {version} | {why} |
|
||||
| Language | {language} | {version} | {why} |
|
||||
| Database | {database} | {version} | {why} |
|
||||
| Styling | {styling} | {version} | {why} |
|
||||
|
||||
## Code Patterns
|
||||
### API Endpoint
|
||||
```{language}
|
||||
{user_api_pattern}
|
||||
```
|
||||
|
||||
### Component
|
||||
```{language}
|
||||
{user_component_pattern}
|
||||
```
|
||||
|
||||
## Naming Conventions
|
||||
| Type | Convention | Example |
|
||||
|------|-----------|---------|
|
||||
| Files | {file_naming} | {example} |
|
||||
| Components | {component_naming} | {example} |
|
||||
| Functions | {function_naming} | {example} |
|
||||
| Database | {db_naming} | {example} |
|
||||
|
||||
## Code Standards
|
||||
{user_code_standards}
|
||||
|
||||
## Security Requirements
|
||||
{user_security_requirements}
|
||||
|
||||
## 📂 Codebase References
|
||||
**Implementation**: `{detected_files}` - {desc}
|
||||
**Config**: package.json, tsconfig.json
|
||||
|
||||
## Related Files
|
||||
- [Business Domain](business-domain.md)
|
||||
- [Decisions Log](decisions-log.md)
|
||||
|
||||
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
|
||||
|
||||
Size: {line_count} lines (limit: 200 per @mvi_compliance)
|
||||
Status: ✅ MVI compliant
|
||||
|
||||
Save to: ~/.opencode/context/project-intelligence/technical-domain.md
|
||||
|
||||
Looks good? [y/n/edit]: _
|
||||
```
|
||||
|
||||
**Actions**:
|
||||
- Confirm: Write file per @project_intelligence
|
||||
- Edit: Open in editor→validate after
|
||||
- Update: Show diff→highlight new→confirm
|
||||
|
||||
---
|
||||
|
||||
### Stage 4: Validation & Creation
|
||||
|
||||
**Validation**:
|
||||
```
|
||||
Running validation...
|
||||
|
||||
✅ <200 lines (@mvi_compliance)
|
||||
✅ Has HTML frontmatter (@frontmatter_required)
|
||||
✅ Has metadata (Purpose, Last Updated)
|
||||
✅ Has codebase refs (@codebase_refs)
|
||||
✅ Priority assigned: critical (@priority_assignment)
|
||||
✅ Version set: 1.0 (@version_tracking)
|
||||
✅ MVI compliant (<30s scannable)
|
||||
✅ No duplication
|
||||
|
||||
Creating files per @project_intelligence...
|
||||
✓ technical-domain.md
|
||||
✓ navigation.md (updated per @navigation_update)
|
||||
|
||||
Done!
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
### Stage 5: Confirmation & Next Steps
|
||||
|
||||
```
|
||||
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
|
||||
✅ Project Intelligence created successfully!
|
||||
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
|
||||
|
||||
Files created:
|
||||
~/.opencode/context/project-intelligence/technical-domain.md
|
||||
~/.opencode/context/project-intelligence/navigation.md
|
||||
|
||||
Agents now use YOUR patterns automatically!
|
||||
|
||||
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
|
||||
What's next?
|
||||
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
|
||||
|
||||
1. Test it:
|
||||
opencode --agent OpenCoder
|
||||
> "Create API endpoint"
|
||||
(Uses YOUR pattern!)
|
||||
|
||||
2. Review: cat ~/.opencode/context/project-intelligence/technical-domain.md
|
||||
|
||||
3. Add business context: /add-context --business
|
||||
|
||||
4. Build: opencode --agent OpenCoder > "Create user auth system"
|
||||
|
||||
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
|
||||
💡 Tip: Update context as project evolves
|
||||
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
|
||||
|
||||
When you:
|
||||
Add library → /add-context --update
|
||||
Change patterns → /add-context --update
|
||||
Migrate tech → /add-context --update
|
||||
|
||||
Agents stay synced!
|
||||
|
||||
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
|
||||
📚 Learn More
|
||||
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
|
||||
|
||||
- Project Intelligence: .opencode/context/core/standards/project-intelligence.md
|
||||
- MVI Principles: .opencode/context/core/context-system/standards/mvi.md
|
||||
- Context System: CONTEXT_SYSTEM_GUIDE.md
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Implementation Details
|
||||
|
||||
### Pattern Detection (Stage 1)
|
||||
|
||||
**Process**:
|
||||
1. Check: `ls ~/.opencode/context/project-intelligence/`
|
||||
2. Read: `cat technical-domain.md` (if exists)
|
||||
3. Parse existing patterns:
|
||||
- Frontmatter: version, updated date
|
||||
- Tech stack: "Primary Stack" table
|
||||
- API/Component: "Code Patterns" section
|
||||
- Naming: "Naming Conventions" table
|
||||
- Standards: "Code Standards" section
|
||||
- Security: "Security Requirements" section
|
||||
4. Display summary
|
||||
5. Offer options: Review/Add/Replace/Cancel
|
||||
|
||||
### Pattern Review (Stage 1.5)
|
||||
|
||||
**Per pattern**:
|
||||
1. Show current value (parsed from file)
|
||||
2. Ask: Keep | Update | Remove
|
||||
3. If Update: Prompt for new value
|
||||
4. Track changes in `changes_to_make[]`
|
||||
|
||||
**After all reviewed**:
|
||||
1. Show summary
|
||||
2. Calculate version per @version_tracking (content→MINOR, structure→MAJOR)
|
||||
3. Confirm
|
||||
4. Proceed to Stage 3
|
||||
|
||||
### Delegation to ContextOrganizer
|
||||
|
||||
```yaml
|
||||
operation: create | update
|
||||
template: technical-domain # Project Intelligence template
|
||||
target_directory: project-intelligence
|
||||
|
||||
user_responses:
|
||||
tech_stack: {framework, language, database, styling}
|
||||
api_pattern: string | null
|
||||
component_pattern: string | null
|
||||
naming_conventions: {files, components, functions, database}
|
||||
code_standards: string[]
|
||||
security_requirements: string[]
|
||||
|
||||
frontmatter:
|
||||
context: project-intelligence/technical
|
||||
priority: critical # @priority_assignment (80% use cases)
|
||||
version: {calculated} # @version_tracking
|
||||
updated: {current_date}
|
||||
|
||||
validation:
|
||||
max_lines: 200 # @mvi_compliance
|
||||
has_frontmatter: true # @frontmatter_required
|
||||
has_codebase_references: true # @codebase_refs
|
||||
navigation_updated: true # @navigation_update
|
||||
```
|
||||
|
||||
### File Structure Inference
|
||||
|
||||
**Based on tech stack, infer common structure**:
|
||||
|
||||
Next.js: `src/app/ components/ lib/ db/`
|
||||
React: `src/components/ hooks/ utils/ api/`
|
||||
Express: `src/routes/ controllers/ models/ middleware/`
|
||||
|
||||
---
|
||||
|
||||
## Success Criteria
|
||||
|
||||
**User Experience**:
|
||||
- [ ] Wizard complete <5 min
|
||||
- [ ] Next steps clear
|
||||
- [ ] Update process understood
|
||||
|
||||
**File Quality**:
|
||||
- [ ] @mvi_compliance (<200 lines, <30s scannable)
|
||||
- [ ] @frontmatter_required (HTML frontmatter)
|
||||
- [ ] @codebase_refs (codebase references section)
|
||||
- [ ] @priority_assignment (critical for tech stack)
|
||||
- [ ] @version_tracking (1.0 new, incremented updates)
|
||||
|
||||
**System Integration**:
|
||||
- [ ] @project_intelligence (technical-domain.md in project-intelligence/)
|
||||
- [ ] @navigation_update (navigation.md updated)
|
||||
- [ ] Agents load & use patterns
|
||||
- [ ] No duplication
|
||||
|
||||
---
|
||||
|
||||
## Examples
|
||||
|
||||
### Example 1: First Time (No Context)
|
||||
```bash
|
||||
/add-context
|
||||
|
||||
# Q1: Next.js + TypeScript + PostgreSQL + Tailwind
|
||||
# Q2: [pastes Next.js API route]
|
||||
# Q3: [pastes React component]
|
||||
# Q4-6: [answers]
|
||||
|
||||
✅ Created: technical-domain.md, navigation.md
|
||||
```
|
||||
|
||||
### Example 2: Review & Update
|
||||
```bash
|
||||
/add-context
|
||||
|
||||
# Found existing → Choose "1. Review and update"
|
||||
# Pattern 1: Tech Stack → Update (Next.js 14 → 15)
|
||||
# Pattern 2-6: Keep
|
||||
|
||||
✅ Updated: Version 1.2 → 1.3
|
||||
```
|
||||
|
||||
### Example 3: Quick Update
|
||||
```bash
|
||||
/add-context --tech-stack
|
||||
|
||||
# Current: Next.js 15 + TypeScript + PostgreSQL + Tailwind
|
||||
# New: Next.js 15 + TypeScript + PostgreSQL + Drizzle + Tailwind
|
||||
|
||||
✅ Version 1.4 → 1.5
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Error Handling
|
||||
|
||||
**Invalid Input**:
|
||||
```
|
||||
⚠️ Invalid input
|
||||
Expected: Tech stack description
|
||||
Got: [empty]
|
||||
|
||||
Example: Next.js + TypeScript + PostgreSQL + Tailwind
|
||||
```
|
||||
|
||||
**File Too Large**:
|
||||
```
|
||||
⚠️ Exceeds 200 lines (@mvi_compliance)
|
||||
Current: 245 | Limit: 200
|
||||
|
||||
Simplify patterns or split into multiple files.
|
||||
```
|
||||
|
||||
**Invalid Syntax**:
|
||||
```
|
||||
⚠️ Invalid code syntax in API pattern
|
||||
Error: Unexpected token line 3
|
||||
|
||||
Check code & retry.
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Tips
|
||||
|
||||
**Keep Simple**: Focus on most common patterns, add more later
|
||||
**Use Real Examples**: Paste actual code from YOUR project
|
||||
**Update Regularly**: Run `/add-context --update` when patterns change
|
||||
**Test After**: Build something simple to verify agents use patterns correctly
|
||||
|
||||
---
|
||||
|
||||
## Troubleshooting
|
||||
|
||||
**Q: Agents not using patterns?**
|
||||
A: Check file exists, <200 lines. Run `/context validate`
|
||||
|
||||
**Q: See what's in context?**
|
||||
A: `cat ~/.opencode/context/project-intelligence/technical-domain.md`
|
||||
|
||||
**Q: Multiple context files?**
|
||||
A: Yes! Create in `~/.opencode/context/project-intelligence/`. Agents load all.
|
||||
|
||||
**Q: Remove pattern?**
|
||||
A: Edit directly: `nano ~/.opencode/context/project-intelligence/technical-domain.md`
|
||||
|
||||
**Q: Share w/ team?**
|
||||
A: Yes! Commit `~/.opencode/context/project-intelligence/` to repo.
|
||||
|
||||
---
|
||||
|
||||
## Related Commands
|
||||
|
||||
- `/context` - Manage context files (harvest, organize, validate)
|
||||
- `/context validate` - Check integrity
|
||||
- `/context map` - View structure
|
||||
|
|
@ -92,7 +92,7 @@ Quality Insights:
|
|||
## Implementation
|
||||
|
||||
### Delegation
|
||||
- Delegates to: **opencoder** (primary) or **openimplementer** (fallback)
|
||||
- Delegates to: **opencoder** (primary)
|
||||
- Uses context search capabilities for pattern matching
|
||||
- Returns structured pattern analysis results
|
||||
|
||||
|
|
@ -186,7 +186,7 @@ Formatted for documentation + sharing:
|
|||
"type": "command",
|
||||
"category": "analysis",
|
||||
"description": "Analyze codebase for patterns and similar implementations",
|
||||
"delegates_to": ["opencoder", "openimplementer"],
|
||||
"delegates_to": ["opencoder"],
|
||||
"parameters": ["pattern", "language", "depth", "output"]
|
||||
}
|
||||
```
|
||||
|
|
|
|||
|
|
@ -139,7 +139,7 @@ cd evals/framework && npm run eval:sdk -- --agent=core/opencoder --pattern="**/s
|
|||
|
||||
**Scopes for this repo:**
|
||||
- `evals` - Evaluation framework changes
|
||||
- `agents/core` - Core agents (openagent, opencoder, openimplementer)
|
||||
- `agents/core` - Core agents (openagent, opencoder)
|
||||
- `agents/meta` - Meta agents (system-builder, repo-manager)
|
||||
- `agents/content` - Content category agents (copywriter, technical-writer)
|
||||
- `agents/data` - Data category agents (data-analyst)
|
||||
|
|
|
|||
7
.opencode/context/core/config/paths.json
Normal file
7
.opencode/context/core/config/paths.json
Normal file
|
|
@ -0,0 +1,7 @@
|
|||
{
|
||||
"description": "Additional context file paths - agents load this via @ reference for dynamic pathing",
|
||||
"paths": {
|
||||
"local": ".opencode/context",
|
||||
"global": false
|
||||
}
|
||||
}
|
||||
17
.opencode/context/core/system/context-paths.md
Normal file
17
.opencode/context/core/system/context-paths.md
Normal file
|
|
@ -0,0 +1,17 @@
|
|||
---
|
||||
id: context-paths
|
||||
name: Additional Context File Paths
|
||||
---
|
||||
|
||||
# Additional Context File Paths
|
||||
|
||||
Additional paths to context. If set to `false`, ignore.
|
||||
|
||||
```json
|
||||
{
|
||||
"paths": {
|
||||
"local": ".opencode/context",
|
||||
"global": false
|
||||
}
|
||||
}
|
||||
```
|
||||
|
|
@ -13,7 +13,7 @@ Core coding standards and best practices for writing clean, maintainable code ac
|
|||
- Error handling patterns
|
||||
- Language-specific guidelines (JavaScript, Python, Go, Rust)
|
||||
|
||||
**Used by**: frontend-specialist, devops-specialist, opencoder, openimplementer
|
||||
**Used by**: frontend-specialist, devops-specialist, opencoder
|
||||
|
||||
### react-patterns.md
|
||||
Modern React patterns, hooks usage, and component design principles.
|
||||
|
|
@ -37,7 +37,7 @@ REST API design principles, GraphQL patterns, and API versioning strategies.
|
|||
- API versioning strategies
|
||||
- Authentication and authorization
|
||||
|
||||
**Used by**: opencoder, openimplementer
|
||||
**Used by**: opencoder
|
||||
|
||||
## Usage
|
||||
|
||||
|
|
|
|||
|
|
@ -2,7 +2,7 @@
|
|||
|
||||
**Category**: development
|
||||
**Purpose**: REST API design principles, GraphQL patterns, and API versioning strategies
|
||||
**Used by**: opencoder, openimplementer
|
||||
**Used by**: opencoder
|
||||
|
||||
---
|
||||
|
||||
|
|
|
|||
|
|
@ -2,7 +2,7 @@
|
|||
|
||||
**Category**: development
|
||||
**Purpose**: Core coding standards and best practices for writing clean, maintainable code
|
||||
**Used by**: frontend-specialist, devops-specialist, opencoder, openimplementer
|
||||
**Used by**: frontend-specialist, devops-specialist, opencoder
|
||||
|
||||
---
|
||||
|
||||
|
|
|
|||
|
|
@ -2,7 +2,7 @@
|
|||
|
||||
**Category**: development
|
||||
**Purpose**: REST API design principles, GraphQL patterns, and API versioning strategies
|
||||
**Used by**: opencoder, openimplementer
|
||||
**Used by**: opencoder
|
||||
|
||||
---
|
||||
|
||||
|
|
|
|||
|
|
@ -2,7 +2,7 @@
|
|||
|
||||
**Category**: development
|
||||
**Purpose**: Core coding standards and best practices for writing clean, maintainable code
|
||||
**Used by**: frontend-specialist, devops-specialist, opencoder, openimplementer
|
||||
**Used by**: frontend-specialist, devops-specialist, opencoder
|
||||
|
||||
---
|
||||
|
||||
|
|
|
|||
|
|
@ -72,7 +72,6 @@ Agents:
|
|||
Agents:
|
||||
- `frontend-specialist.md` - React, Vue, modern CSS
|
||||
- `devops-specialist.md` - CI/CD, deployment, infrastructure
|
||||
- `openimplementer.md` - Lightweight implementation (1-4 files, <60 min)
|
||||
|
||||
**When to use**: Building applications, dev tasks
|
||||
|
||||
|
|
|
|||
|
|
@ -23,7 +23,6 @@ Categories are domain-based groupings that organize agents, context files, and t
|
|||
**Purpose**: Essential system agents (always available)
|
||||
|
||||
**Agents**:
|
||||
- openagent, opencoder, openimplementer, system-builder
|
||||
|
||||
**When to use**: System-level tasks, orchestration, coding (simple or complex)
|
||||
|
||||
|
|
@ -100,7 +99,6 @@ evals/agents/{category}/ # Tests by category
|
|||
├── 0-category.json # Category metadata
|
||||
├── openagent.md
|
||||
├── opencoder.md
|
||||
└── openimplementer.md
|
||||
|
||||
.opencode/agent/subagents/development/
|
||||
├── 0-category.json # Subagent category metadata
|
||||
|
|
@ -351,7 +349,6 @@ Loads: `.opencode/context/development/react-patterns.md`
|
|||
├── core/
|
||||
│ ├── openagent.md
|
||||
│ ├── opencoder.md
|
||||
│ └── openimplementer.md
|
||||
├── subagents/
|
||||
│ ├── development/
|
||||
│ │ ├── frontend-specialist.md
|
||||
|
|
@ -384,7 +381,6 @@ core/
|
|||
├── 0-category.json
|
||||
├── openagent.md
|
||||
├── opencoder.md
|
||||
└── openimplementer.md
|
||||
```
|
||||
|
||||
### Development Subagents
|
||||
|
|
@ -414,7 +410,6 @@ evals/agents/core/
|
|||
│ ├── config/config.yaml
|
||||
│ └── tests/smoke-test.yaml
|
||||
├── opencoder/
|
||||
└── openimplementer/
|
||||
```
|
||||
|
||||
---
|
||||
|
|
|
|||
|
|
@ -163,7 +163,7 @@ ERROR: Missing dependency: subagent:nonexistent
|
|||
**Specialist Subagents** (8 in Developer profile):
|
||||
- frontend-specialist: React, Vue, CSS architecture
|
||||
- devops-specialist: CI/CD, infrastructure, deployment
|
||||
- openimplementer: Lightweight implementation (1-4 files, <60 min)
|
||||
|
||||
- task-manager: Feature breakdown and planning
|
||||
- documentation: Create and update docs
|
||||
- coder-agent: Execute coding subtasks
|
||||
|
|
|
|||
|
|
@ -0,0 +1,471 @@
|
|||
# Guide: GitHub Issues and Project Board Workflow
|
||||
|
||||
**Prerequisites**: Basic understanding of GitHub issues and projects
|
||||
**Purpose**: Step-by-step workflow for managing issues and project board
|
||||
|
||||
---
|
||||
|
||||
## Overview
|
||||
|
||||
This guide covers how to work with GitHub issues and the project board to track and process different requests, features, and improvements.
|
||||
|
||||
**Project Board**: https://github.com/users/darrenhinde/projects/2/views/2
|
||||
|
||||
**Time**: Varies by task
|
||||
|
||||
---
|
||||
|
||||
## Quick Commands Reference
|
||||
|
||||
```bash
|
||||
# List issues
|
||||
gh issue list --repo darrenhinde/OpenAgentsControl
|
||||
|
||||
# Create issue
|
||||
gh issue create --repo darrenhinde/OpenAgentsControl --title "Title" --body "Body" --label "label1,label2"
|
||||
|
||||
# Add issue to project
|
||||
gh project item-add 2 --owner darrenhinde --url https://github.com/darrenhinde/OpenAgentsControl/issues/NUMBER
|
||||
|
||||
# View issue
|
||||
gh issue view NUMBER --repo darrenhinde/OpenAgentsControl
|
||||
|
||||
# Update issue
|
||||
gh issue edit NUMBER --repo darrenhinde/OpenAgentsControl --add-label "new-label"
|
||||
|
||||
# Close issue
|
||||
gh issue close NUMBER --repo darrenhinde/OpenAgentsControl
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Step 1: Creating Issues
|
||||
|
||||
### Issue Types
|
||||
|
||||
**Feature Request**
|
||||
- Labels: `feature`, `enhancement`
|
||||
- Include: Goals, key features, success criteria
|
||||
- Template: See "Feature Issue Template" below
|
||||
|
||||
**Bug Report**
|
||||
- Labels: `bug`
|
||||
- Include: Steps to reproduce, expected vs actual behavior
|
||||
- Template: See "Bug Issue Template" below
|
||||
|
||||
**Improvement**
|
||||
- Labels: `enhancement`, `framework`
|
||||
- Include: Current state, proposed improvement, impact
|
||||
|
||||
**Question**
|
||||
- Labels: `question`
|
||||
- Include: Context, specific question, use case
|
||||
|
||||
### Priority Labels
|
||||
|
||||
- `priority-high` - Critical, blocking work
|
||||
- `priority-medium` - Important, not blocking
|
||||
- `priority-low` - Nice to have
|
||||
|
||||
### Category Labels
|
||||
|
||||
- `agents` - Agent system related
|
||||
- `framework` - Core framework changes
|
||||
- `evals` - Evaluation framework
|
||||
- `idea` - High-level proposal
|
||||
|
||||
### Creating an Issue
|
||||
|
||||
```bash
|
||||
# Basic issue
|
||||
gh issue create \
|
||||
--repo darrenhinde/OpenAgentsControl \
|
||||
--title "Add new feature X" \
|
||||
--body "Description of feature" \
|
||||
--label "feature,priority-medium"
|
||||
|
||||
# Feature with detailed body
|
||||
gh issue create \
|
||||
--repo darrenhinde/OpenAgentsControl \
|
||||
--title "Build plugin system" \
|
||||
--label "feature,framework,priority-high" \
|
||||
--body "$(cat <<'EOF'
|
||||
## Overview
|
||||
Brief description
|
||||
|
||||
## Goals
|
||||
- Goal 1
|
||||
- Goal 2
|
||||
|
||||
## Key Features
|
||||
- Feature 1
|
||||
- Feature 2
|
||||
|
||||
## Success Criteria
|
||||
- [ ] Criterion 1
|
||||
- [ ] Criterion 2
|
||||
EOF
|
||||
)"
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Step 2: Adding Issues to Project Board
|
||||
|
||||
### Add Single Issue
|
||||
|
||||
```bash
|
||||
# Add issue to project
|
||||
gh project item-add 2 \
|
||||
--owner darrenhinde \
|
||||
--url https://github.com/darrenhinde/OpenAgentsControl/issues/NUMBER
|
||||
```
|
||||
|
||||
### Add Multiple Issues
|
||||
|
||||
```bash
|
||||
# Add issues 137-142 to project
|
||||
for i in {137..142}; do
|
||||
gh project item-add 2 \
|
||||
--owner darrenhinde \
|
||||
--url https://github.com/darrenhinde/OpenAgentsControl/issues/$i
|
||||
done
|
||||
```
|
||||
|
||||
### Verify Issues on Board
|
||||
|
||||
```bash
|
||||
# View project items
|
||||
gh project item-list 2 --owner darrenhinde --format json | jq '.items[] | {title, status}'
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Step 3: Processing Issues
|
||||
|
||||
### Workflow States
|
||||
|
||||
1. **Backlog** - New issues, not yet prioritized
|
||||
2. **Todo** - Prioritized, ready to work on
|
||||
3. **In Progress** - Currently being worked on
|
||||
4. **In Review** - PR submitted, awaiting review
|
||||
5. **Done** - Completed and merged
|
||||
|
||||
### Moving Issues
|
||||
|
||||
```bash
|
||||
# Update issue status (via project board UI or gh CLI)
|
||||
# Note: Status updates are typically done via web UI
|
||||
```
|
||||
|
||||
### Assigning Issues
|
||||
|
||||
```bash
|
||||
# Assign to yourself
|
||||
gh issue edit NUMBER \
|
||||
--repo darrenhinde/OpenAgentsControl \
|
||||
--add-assignee @me
|
||||
|
||||
# Assign to someone else
|
||||
gh issue edit NUMBER \
|
||||
--repo darrenhinde/OpenAgentsControl \
|
||||
--add-assignee username
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Step 4: Working on Issues
|
||||
|
||||
### Start Work
|
||||
|
||||
1. **Assign issue to yourself**
|
||||
```bash
|
||||
gh issue edit NUMBER --repo darrenhinde/OpenAgentsControl --add-assignee @me
|
||||
```
|
||||
|
||||
2. **Move to "In Progress"** (via web UI)
|
||||
|
||||
3. **Create branch** (optional)
|
||||
```bash
|
||||
git checkout -b feature/issue-NUMBER-description
|
||||
```
|
||||
|
||||
4. **Reference issue in commits**
|
||||
```bash
|
||||
git commit -m "feat: implement X (#NUMBER)"
|
||||
```
|
||||
|
||||
### Update Progress
|
||||
|
||||
```bash
|
||||
# Add comment to issue
|
||||
gh issue comment NUMBER \
|
||||
--repo darrenhinde/OpenAgentsControl \
|
||||
--body "Progress update: Completed X, working on Y"
|
||||
```
|
||||
|
||||
### Complete Work
|
||||
|
||||
1. **Create PR**
|
||||
```bash
|
||||
gh pr create \
|
||||
--repo darrenhinde/OpenAgentsControl \
|
||||
--title "Fix #NUMBER: Description" \
|
||||
--body "Closes #NUMBER\n\nChanges:\n- Change 1\n- Change 2"
|
||||
```
|
||||
|
||||
2. **Move to "In Review"** (via web UI)
|
||||
|
||||
3. **After merge, issue auto-closes** (if PR uses "Closes #NUMBER")
|
||||
|
||||
---
|
||||
|
||||
## Step 5: Using Issues for Request Processing
|
||||
|
||||
### Request Types
|
||||
|
||||
**User Feature Request**
|
||||
1. Create issue with `feature` label
|
||||
2. Add to project board
|
||||
3. Prioritize based on impact
|
||||
4. Break down into subtasks if needed
|
||||
5. Assign to appropriate person/team
|
||||
|
||||
**Bug Report**
|
||||
1. Create issue with `bug` label
|
||||
2. Add reproduction steps
|
||||
3. Prioritize based on severity
|
||||
4. Assign for investigation
|
||||
5. Link to related issues if applicable
|
||||
|
||||
**Improvement Suggestion**
|
||||
1. Create issue with `enhancement` label
|
||||
2. Discuss approach in comments
|
||||
3. Get consensus before implementation
|
||||
4. Create implementation plan
|
||||
5. Execute and track progress
|
||||
|
||||
### Breaking Down Large Issues
|
||||
|
||||
For complex features, create parent issue and subtasks:
|
||||
|
||||
```bash
|
||||
# Parent issue
|
||||
gh issue create \
|
||||
--repo darrenhinde/OpenAgentsControl \
|
||||
--title "[EPIC] Plugin System" \
|
||||
--label "feature,framework,priority-high" \
|
||||
--body "Parent issue for plugin system work"
|
||||
|
||||
# Subtask issues
|
||||
gh issue create \
|
||||
--repo darrenhinde/OpenAgentsControl \
|
||||
--title "Plugin manifest system" \
|
||||
--label "feature" \
|
||||
--body "Part of #PARENT_NUMBER\n\nImplement plugin.json manifest"
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Step 6: Issue Templates
|
||||
|
||||
### Feature Issue Template
|
||||
|
||||
```markdown
|
||||
## Overview
|
||||
Brief description of the feature
|
||||
|
||||
## Goals
|
||||
- Goal 1
|
||||
- Goal 2
|
||||
- Goal 3
|
||||
|
||||
## Key Features
|
||||
- Feature 1
|
||||
- Feature 2
|
||||
- Feature 3
|
||||
|
||||
## Related Issues
|
||||
- #123 (related issue)
|
||||
|
||||
## Success Criteria
|
||||
- [ ] Criterion 1
|
||||
- [ ] Criterion 2
|
||||
- [ ] Criterion 3
|
||||
```
|
||||
|
||||
### Bug Issue Template
|
||||
|
||||
```markdown
|
||||
## Description
|
||||
Brief description of the bug
|
||||
|
||||
## Steps to Reproduce
|
||||
1. Step 1
|
||||
2. Step 2
|
||||
3. Step 3
|
||||
|
||||
## Expected Behavior
|
||||
What should happen
|
||||
|
||||
## Actual Behavior
|
||||
What actually happens
|
||||
|
||||
## Environment
|
||||
- OS: macOS/Linux/Windows
|
||||
- Version: 0.5.2
|
||||
- Node: v20.x
|
||||
|
||||
## Additional Context
|
||||
Any other relevant information
|
||||
```
|
||||
|
||||
### Improvement Issue Template
|
||||
|
||||
```markdown
|
||||
## Current State
|
||||
Description of current implementation
|
||||
|
||||
## Proposed Improvement
|
||||
What should be improved and why
|
||||
|
||||
## Impact
|
||||
- Performance improvement
|
||||
- Developer experience
|
||||
- User experience
|
||||
|
||||
## Implementation Approach
|
||||
High-level approach to implementation
|
||||
|
||||
## Success Criteria
|
||||
- [ ] Criterion 1
|
||||
- [ ] Criterion 2
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Step 7: Automation and Integration
|
||||
|
||||
### Auto-Close Issues
|
||||
|
||||
Use keywords in PR descriptions:
|
||||
- `Closes #123`
|
||||
- `Fixes #123`
|
||||
- `Resolves #123`
|
||||
|
||||
### Link Issues to PRs
|
||||
|
||||
```bash
|
||||
# In PR description
|
||||
gh pr create \
|
||||
--title "Add feature X" \
|
||||
--body "Implements #123\n\nChanges:\n- Change 1"
|
||||
```
|
||||
|
||||
### Issue References in Commits
|
||||
|
||||
```bash
|
||||
# Reference issue in commit
|
||||
git commit -m "feat: add plugin system (#137)"
|
||||
|
||||
# Close issue in commit
|
||||
git commit -m "fix: resolve permission error (closes #140)"
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Best Practices
|
||||
|
||||
### Issue Creation
|
||||
|
||||
✅ **Clear titles** - Descriptive and specific
|
||||
✅ **Detailed descriptions** - Include context and goals
|
||||
✅ **Proper labels** - Use consistent labeling
|
||||
✅ **Success criteria** - Define what "done" means
|
||||
✅ **Link related issues** - Show dependencies
|
||||
|
||||
### Issue Management
|
||||
|
||||
✅ **Regular triage** - Review and prioritize weekly
|
||||
✅ **Keep updated** - Add comments on progress
|
||||
✅ **Close stale issues** - Clean up old/irrelevant issues
|
||||
✅ **Use milestones** - Group related issues
|
||||
✅ **Assign owners** - Clear responsibility
|
||||
|
||||
### Project Board
|
||||
|
||||
✅ **Update status** - Keep board current
|
||||
✅ **Limit WIP** - Don't overload "In Progress"
|
||||
✅ **Review regularly** - Weekly board review
|
||||
✅ **Archive completed** - Keep board clean
|
||||
|
||||
---
|
||||
|
||||
## Common Workflows
|
||||
|
||||
### Processing User Request
|
||||
|
||||
1. **Receive request** (via issue, email, chat)
|
||||
2. **Create issue** with appropriate labels
|
||||
3. **Add to project board**
|
||||
4. **Triage and prioritize**
|
||||
5. **Assign to team member**
|
||||
6. **Track progress** via status updates
|
||||
7. **Review and merge** PR
|
||||
8. **Close issue** and notify requester
|
||||
|
||||
### Planning New Feature
|
||||
|
||||
1. **Create epic issue** for overall feature
|
||||
2. **Break down into subtasks**
|
||||
3. **Add all to project board**
|
||||
4. **Prioritize subtasks**
|
||||
5. **Assign to team members**
|
||||
6. **Track progress** across subtasks
|
||||
7. **Complete and close** when all subtasks done
|
||||
|
||||
### Bug Triage
|
||||
|
||||
1. **Create bug issue** with reproduction steps
|
||||
2. **Label with severity** (critical, high, medium, low)
|
||||
3. **Add to project board**
|
||||
4. **Assign for investigation**
|
||||
5. **Reproduce and diagnose**
|
||||
6. **Fix and test**
|
||||
7. **Create PR** with fix
|
||||
8. **Close issue** after merge
|
||||
|
||||
---
|
||||
|
||||
## Checklist
|
||||
|
||||
Before closing an issue:
|
||||
|
||||
- [ ] All success criteria met
|
||||
- [ ] Tests passing
|
||||
- [ ] Documentation updated
|
||||
- [ ] PR merged (if applicable)
|
||||
- [ ] Related issues updated
|
||||
- [ ] Stakeholders notified
|
||||
|
||||
---
|
||||
|
||||
## Related Files
|
||||
|
||||
- **Registry guide**: `guides/updating-registry.md`
|
||||
- **Release guide**: `guides/creating-release.md`
|
||||
- **Testing guide**: `guides/testing-agent.md`
|
||||
- **Debugging**: `guides/debugging.md`
|
||||
|
||||
---
|
||||
|
||||
## External Resources
|
||||
|
||||
- [GitHub Issues Documentation](https://docs.github.com/en/issues)
|
||||
- [GitHub Projects Documentation](https://docs.github.com/en/issues/planning-and-tracking-with-projects)
|
||||
- [GitHub CLI Documentation](https://cli.github.com/manual/)
|
||||
|
||||
---
|
||||
|
||||
**Last Updated**: 2026-01-30
|
||||
**Version**: 0.5.2
|
||||
153
.opencode/context/openagents-repo/guides/npm-publishing.md
Normal file
153
.opencode/context/openagents-repo/guides/npm-publishing.md
Normal file
|
|
@ -0,0 +1,153 @@
|
|||
# NPM Publishing Guide
|
||||
|
||||
**Purpose**: Quick reference for publishing OpenAgents Control to npm
|
||||
|
||||
**Time to Read**: 3 minutes
|
||||
|
||||
---
|
||||
|
||||
## Core Concept
|
||||
|
||||
OpenAgents Control is published as `@nextsystems/oac` on npm. Users install globally and run `oac [profile]` to set up their projects.
|
||||
|
||||
**Key files**:
|
||||
- `package.json` - Package configuration
|
||||
- `bin/oac.js` - CLI entry point
|
||||
- `.npmignore` - Exclude dev files
|
||||
- `install.sh` - Main installer (runs when user executes `oac`)
|
||||
|
||||
---
|
||||
|
||||
## Publishing Workflow
|
||||
|
||||
### 1. Prepare Release
|
||||
|
||||
```bash
|
||||
# Update version
|
||||
npm version patch # 0.7.0 -> 0.7.1
|
||||
npm version minor # 0.7.0 -> 0.8.0
|
||||
|
||||
# Update VERSION file
|
||||
node -p "require('./package.json').version" > VERSION
|
||||
|
||||
# Update CHANGELOG.md with changes
|
||||
```
|
||||
|
||||
### 2. Test Locally
|
||||
|
||||
```bash
|
||||
# Create package
|
||||
npm pack
|
||||
|
||||
# Install globally from tarball
|
||||
npm install -g ./nextsystems-oac-0.7.1.tgz
|
||||
|
||||
# Test CLI
|
||||
oac --version
|
||||
oac --help
|
||||
|
||||
# Uninstall
|
||||
npm uninstall -g @nextsystems/oac
|
||||
```
|
||||
|
||||
### 3. Publish
|
||||
|
||||
```bash
|
||||
# Login (one-time)
|
||||
npm login
|
||||
|
||||
# Publish (scoped packages need --access public)
|
||||
npm publish --access public
|
||||
```
|
||||
|
||||
### 4. Verify
|
||||
|
||||
```bash
|
||||
# Check it's live
|
||||
npm view @nextsystems/oac
|
||||
|
||||
# Test installation
|
||||
npm install -g @nextsystems/oac
|
||||
oac --version
|
||||
```
|
||||
|
||||
### 5. Create GitHub Release
|
||||
|
||||
```bash
|
||||
git tag v0.7.1
|
||||
git push --tags
|
||||
# Create release on GitHub with changelog
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## User Installation
|
||||
|
||||
Once published, users can:
|
||||
|
||||
```bash
|
||||
# Global install (recommended)
|
||||
npm install -g @nextsystems/oac
|
||||
oac developer
|
||||
|
||||
# Or use npx (no install)
|
||||
npx @nextsystems/oac developer
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Common Issues
|
||||
|
||||
**"You do not have permission to publish"**
|
||||
```bash
|
||||
npm whoami # Check you're logged in
|
||||
npm publish --access public # Scoped packages need public access
|
||||
```
|
||||
|
||||
**"Version already exists"**
|
||||
```bash
|
||||
npm version patch # Bump version first
|
||||
```
|
||||
|
||||
**"You must verify your email"**
|
||||
```bash
|
||||
npm profile get # Check email verification status
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Package Configuration
|
||||
|
||||
**What's included** (see `package.json` → `files`):
|
||||
- `.opencode/` - Agents, commands, context, profiles, skills, tools
|
||||
- `scripts/` - Installation scripts
|
||||
- `bin/` - CLI entry point
|
||||
- `registry.json` - Component registry
|
||||
- `install.sh` - Main installer
|
||||
- Docs (README, CHANGELOG, LICENSE)
|
||||
|
||||
**What's excluded** (see `.npmignore`):
|
||||
- `node_modules/`
|
||||
- `evals/`
|
||||
- `.tmp/`
|
||||
- Dev files
|
||||
|
||||
---
|
||||
|
||||
## Security
|
||||
|
||||
- ✅ Enable 2FA: `npm profile enable-2fa auth-and-writes`
|
||||
- ✅ Use strong npm password
|
||||
- ✅ `@nextsystems` scope is protected (only you can publish)
|
||||
|
||||
---
|
||||
|
||||
## References
|
||||
|
||||
- **Package**: https://www.npmjs.com/package/@nextsystems/oac
|
||||
- **Stats**: https://npm-stat.com/charts.html?package=@nextsystems/oac
|
||||
- **Codebase**: `package.json`, `bin/oac.js`, `.npmignore`
|
||||
|
||||
---
|
||||
|
||||
**Last Updated**: 2026-01-30
|
||||
|
|
@ -97,7 +97,6 @@ cat registry.json | jq '.profiles.full.components[] | select(. == "agent:your-ag
|
|||
**Include**:
|
||||
- Core agents (openagent, opencoder)
|
||||
- Development specialist subagents (frontend, devops)
|
||||
- OpenImplementer (openimplementer - lightweight implementation agent)
|
||||
- All code subagents (tester, reviewer, coder-agent, build-agent)
|
||||
- Dev commands (commit, test, validate-repo, analyze-patterns)
|
||||
- Dev context (standards/code, standards/tests, workflows/*)
|
||||
|
|
@ -115,7 +114,7 @@ cat registry.json | jq '.profiles.full.components[] | select(. == "agent:your-ag
|
|||
- Content specialists (copywriter, technical-writer)
|
||||
- Data specialists (data-analyst)
|
||||
- Image tools (gemini, image-specialist)
|
||||
- Notification tools (telegram, notify)
|
||||
- Notification tools (notify)
|
||||
|
||||
**Exclude**:
|
||||
- Development specialists
|
||||
|
|
@ -330,7 +329,7 @@ Add profile validation to CI:
|
|||
| data | ❌ | ❌ | ✅ | ✅ | ✅ |
|
||||
| meta | ❌ | ❌ | ❌ | ❌ | ✅ |
|
||||
|
||||
*Note: Development category includes both agents (opencoder, openimplementer) and specialist subagents (frontend, devops)
|
||||
*Note: Development category includes agents (opencoder) and specialist subagents (frontend, devops)
|
||||
|
||||
---
|
||||
|
||||
|
|
|
|||
|
|
@ -120,11 +120,6 @@ README.md # Main documentation
|
|||
```
|
||||
.opencode/agent/core/openagent.md
|
||||
.opencode/agent/core/opencoder.md
|
||||
```
|
||||
|
||||
### Meta Agents
|
||||
|
||||
```
|
||||
.opencode/agent/meta/system-builder.md
|
||||
```
|
||||
|
||||
|
|
@ -133,7 +128,9 @@ README.md # Main documentation
|
|||
```
|
||||
.opencode/agent/development/frontend-specialist.md
|
||||
.opencode/agent/development/devops-specialist.md
|
||||
.opencode/agent/core/openimplementer.md
|
||||
```
|
||||
.opencode/agent/development/frontend-specialist.md
|
||||
.opencode/agent/development/devops-specialist.md
|
||||
```
|
||||
|
||||
### Content Agents
|
||||
|
|
|
|||
|
|
@ -2,7 +2,7 @@
|
|||
|
||||
**Purpose**: Context files specific to the OpenAgents Control repository
|
||||
|
||||
**Last Updated**: 2026-01-13
|
||||
**Last Updated**: 2026-01-30
|
||||
|
||||
---
|
||||
|
||||
|
|
@ -12,7 +12,7 @@
|
|||
|----------|-------|---------|
|
||||
| **Concepts** | 2 files | Core ideas and principles |
|
||||
| **Examples** | 1 file | Working code samples |
|
||||
| **Guides** | 8 files | Step-by-step workflows |
|
||||
| **Guides** | 10 files | Step-by-step workflows |
|
||||
| **Lookup** | 4 files | Quick reference tables |
|
||||
| **Errors** | 1 file | Common issues + solutions |
|
||||
|
||||
|
|
@ -46,6 +46,8 @@
|
|||
| `guides/adding-agent.md` | How to add new agents | ⭐⭐⭐⭐ |
|
||||
| `guides/testing-agent.md` | How to test agents | ⭐⭐⭐⭐ |
|
||||
| `guides/external-libraries-workflow.md` | How to handle external library dependencies | ⭐⭐⭐⭐ |
|
||||
| `guides/github-issues-workflow.md` | How to work with GitHub issues and project board | ⭐⭐⭐⭐ |
|
||||
| `guides/npm-publishing.md` | How to publish package to npm | ⭐⭐⭐ |
|
||||
| `guides/updating-registry.md` | How to update registry | ⭐⭐⭐ |
|
||||
| `guides/debugging.md` | How to debug issues | ⭐⭐⭐ |
|
||||
| `guides/resolving-installer-wildcard-failures.md` | Fix wildcard context install failures | ⭐⭐⭐ |
|
||||
|
|
@ -105,6 +107,12 @@
|
|||
4. Load `examples/subagent-prompt-structure.md` (if subagent)
|
||||
5. Load `guides/testing-agent.md` (validate)
|
||||
|
||||
### For Issue Management:
|
||||
1. Load `guides/github-issues-workflow.md` (understand workflow)
|
||||
2. Create issues with proper labels and templates
|
||||
3. Add to project board for tracking
|
||||
4. Process requests systematically
|
||||
|
||||
### For Debugging:
|
||||
1. Load `guides/debugging.md` (general approach)
|
||||
2. Load specific error file from `errors/`
|
||||
|
|
|
|||
|
|
@ -1,104 +0,0 @@
|
|||
import type { Plugin } from "@opencode-ai/plugin"
|
||||
import { SimpleTelegramBot } from "../_lib/telegram-bot"
|
||||
|
||||
// 🔧 CONFIGURATION: Set to true to enable this plugin
|
||||
const ENABLED = false
|
||||
|
||||
export const TelegramNotify: Plugin = async ({ $ }) => {
|
||||
// Plugin disabled - set ENABLED = true to activate
|
||||
if (!ENABLED) return {}
|
||||
|
||||
// Initialize Telegram bot
|
||||
const bot = new SimpleTelegramBot()
|
||||
let lastMessage = ""
|
||||
|
||||
return {
|
||||
async event(input) {
|
||||
if (input.event.type === "session.idle") {
|
||||
// Send the last message content along with idle notification
|
||||
const message = lastMessage
|
||||
? `🟡 Session idle! Here's your last message:\n\n${lastMessage}`
|
||||
: "🟡 Hey! Your OpenCode session is idle - time to check your work!"
|
||||
bot.sendMessage(message)
|
||||
}
|
||||
|
||||
if (input.event.type === "message.updated") {
|
||||
// Reset idle timer when user sends messages
|
||||
bot.resetActivity()
|
||||
|
||||
const messageContent = (input.event as any).message?.content ||
|
||||
(input.event as any).content || ""
|
||||
|
||||
// Check if it's a command to send last message
|
||||
if (messageContent.includes("/send-last") || messageContent.includes("/last")) {
|
||||
if (lastMessage) {
|
||||
bot.sendMessage(`📱 Here's your last message:\n\n${lastMessage}`)
|
||||
} else {
|
||||
bot.sendMessage("📱 No previous message found.")
|
||||
}
|
||||
return
|
||||
}
|
||||
|
||||
// Check if it's a command to send to phone
|
||||
if (messageContent.includes("/send-to-phone") || messageContent.includes("/phone")) {
|
||||
if (lastMessage) {
|
||||
bot.sendMessage(`📱 Sending to your phone:\n\n${lastMessage}`)
|
||||
} else {
|
||||
bot.sendMessage("📱 No message to send to phone.")
|
||||
}
|
||||
return
|
||||
}
|
||||
|
||||
// Try to capture message content from the event
|
||||
try {
|
||||
// Access message content if available
|
||||
const messageContent = (input.event as any).message?.content ||
|
||||
(input.event as any).content ||
|
||||
"Message updated"
|
||||
|
||||
if (messageContent && messageContent !== "Message updated") {
|
||||
lastMessage = messageContent
|
||||
|
||||
// Send a preview of the message to Telegram
|
||||
const preview = lastMessage.length > 200
|
||||
? lastMessage.substring(0, 200) + "..."
|
||||
: lastMessage
|
||||
|
||||
bot.sendMessage(`📱 Last message preview:\n\n${preview}`)
|
||||
}
|
||||
} catch (error) {
|
||||
// If we can't access the message content, just log it
|
||||
console.log("Message updated but couldn't capture content")
|
||||
}
|
||||
}
|
||||
|
||||
if (input.event.type === "file.edited") {
|
||||
// Reset idle timer when user edits files
|
||||
bot.resetActivity()
|
||||
}
|
||||
|
||||
// Also listen for message parts being updated
|
||||
if (input.event.type === "message.part.updated") {
|
||||
bot.resetActivity()
|
||||
|
||||
try {
|
||||
const partContent = (input.event as any).part?.content ||
|
||||
(input.event as any).content ||
|
||||
"Message part updated"
|
||||
|
||||
if (partContent && partContent !== "Message part updated") {
|
||||
lastMessage = partContent
|
||||
|
||||
const preview = lastMessage.length > 200
|
||||
? lastMessage.substring(0, 200) + "..."
|
||||
: lastMessage
|
||||
|
||||
bot.sendMessage(`📱 Message part preview:\n\n${preview}`)
|
||||
}
|
||||
} catch (error) {
|
||||
console.log("Message part updated but couldn't capture content")
|
||||
}
|
||||
}
|
||||
}
|
||||
}
|
||||
}
|
||||
|
|
@ -4,7 +4,6 @@
|
|||
"components": [
|
||||
"agent:openagent",
|
||||
"agent:opencoder",
|
||||
"agent:openimplementer",
|
||||
"agent:system-builder",
|
||||
"agent:repo-manager",
|
||||
"agent:eval-runner",
|
||||
|
|
|
|||
|
|
@ -1,10 +1,9 @@
|
|||
{
|
||||
"name": "Developer",
|
||||
"description": "Complete software development environment with code generation, testing, review, and build tools. Choose OpenImplementer for focused tasks or OpenCoder for complex architecture. Recommended for most developers.",
|
||||
"description": "Complete software development environment with code generation, testing, review, and build tools. Use OpenAgent for general tasks (1-4 files) or OpenCoder for complex architecture (4+ files). Recommended for most developers.",
|
||||
"badge": "RECOMMENDED",
|
||||
"components": [
|
||||
"agent:openagent",
|
||||
"agent:openimplementer",
|
||||
"agent:opencoder",
|
||||
"subagent:task-manager",
|
||||
"subagent:frontend-specialist",
|
||||
|
|
|
|||
|
|
@ -4,7 +4,6 @@
|
|||
"components": [
|
||||
"agent:openagent",
|
||||
"agent:opencoder",
|
||||
"agent:openimplementer",
|
||||
"agent:eval-runner",
|
||||
"agent:copywriter",
|
||||
"agent:technical-writer",
|
||||
|
|
|
|||
|
|
@ -12,7 +12,7 @@ All notable changes to this project will be documented in this file.
|
|||
### Documentation
|
||||
- Updated README.md and QUICK_START.md for v0.6.0 accuracy
|
||||
- Updated version from 0.1.0-alpha.1 to 0.6.0
|
||||
- Added OpenImplementer agent to main agents list
|
||||
- Simplified agent architecture (OpenAgent + OpenCoder)
|
||||
- Completed commands list with /analyze-patterns, /commit-openagents, /build-context-system
|
||||
- Highlighted ExternalScout with 18+ supported libraries
|
||||
- Updated installation profiles to mention new agents
|
||||
|
|
|
|||
90
bin/oac.js
Executable file
90
bin/oac.js
Executable file
|
|
@ -0,0 +1,90 @@
|
|||
#!/usr/bin/env node
|
||||
|
||||
/**
|
||||
* OpenAgents Control (OAC) CLI
|
||||
*
|
||||
* This is the main entry point for the @openagents/control package.
|
||||
* It runs the install.sh script to set up the OpenAgents Control system.
|
||||
*/
|
||||
|
||||
const { spawn } = require('child_process');
|
||||
const path = require('path');
|
||||
const fs = require('fs');
|
||||
|
||||
// Get the package root directory
|
||||
const packageRoot = path.join(__dirname, '..');
|
||||
|
||||
// Path to install.sh
|
||||
const installScript = path.join(packageRoot, 'install.sh');
|
||||
|
||||
// Check if install.sh exists
|
||||
if (!fs.existsSync(installScript)) {
|
||||
console.error('Error: install.sh not found at', installScript);
|
||||
process.exit(1);
|
||||
}
|
||||
|
||||
// Get command line arguments (skip node and script path)
|
||||
const args = process.argv.slice(2);
|
||||
|
||||
// If no arguments provided, show help
|
||||
if (args.length === 0) {
|
||||
console.log(`
|
||||
╔═══════════════════════════════════════════════════════════════╗
|
||||
║ OpenAgents Control (OAC) ║
|
||||
║ AI agent framework for plan-first development workflows ║
|
||||
╚═══════════════════════════════════════════════════════════════╝
|
||||
|
||||
Usage:
|
||||
oac [profile] Install with a specific profile
|
||||
oac --help Show this help message
|
||||
oac --version Show version information
|
||||
|
||||
Available Profiles:
|
||||
essential Minimal setup (OpenAgent only)
|
||||
developer Full development setup (recommended)
|
||||
business Business-focused agents
|
||||
advanced Advanced features and specialists
|
||||
full Everything included
|
||||
|
||||
Examples:
|
||||
oac Interactive installation
|
||||
oac developer Install with developer profile
|
||||
oac --help Show detailed help
|
||||
|
||||
For more information, visit:
|
||||
https://github.com/darrenhinde/OpenAgentsControl
|
||||
`);
|
||||
process.exit(0);
|
||||
}
|
||||
|
||||
// Handle --version flag
|
||||
if (args.includes('--version') || args.includes('-v')) {
|
||||
const packageJson = require(path.join(packageRoot, 'package.json'));
|
||||
console.log(`@openagents/control v${packageJson.version}`);
|
||||
process.exit(0);
|
||||
}
|
||||
|
||||
// Handle --help flag
|
||||
if (args.includes('--help') || args.includes('-h')) {
|
||||
// Run install.sh with --help
|
||||
args.push('--help');
|
||||
}
|
||||
|
||||
// Run the install script with bash
|
||||
const child = spawn('bash', [installScript, ...args], {
|
||||
cwd: packageRoot,
|
||||
stdio: 'inherit',
|
||||
env: {
|
||||
...process.env,
|
||||
OAC_PACKAGE_ROOT: packageRoot
|
||||
}
|
||||
});
|
||||
|
||||
child.on('error', (error) => {
|
||||
console.error('Error running install script:', error.message);
|
||||
process.exit(1);
|
||||
});
|
||||
|
||||
child.on('exit', (code) => {
|
||||
process.exit(code || 0);
|
||||
});
|
||||
|
|
@ -99,9 +99,9 @@ docs/
|
|||
|
||||
Latest updates:
|
||||
- ExternalScout subagent for fetching live library documentation (18+ libraries)
|
||||
- OpenImplementer agent for lightweight implementation tasks
|
||||
- Enhanced ContextScout with multi-model optimization
|
||||
- Complete command and agent documentation
|
||||
- Simplified agent architecture (OpenAgent + OpenCoder)
|
||||
|
||||
## 🤝 Community
|
||||
|
||||
|
|
|
|||
56
package.json
56
package.json
|
|
@ -1,11 +1,41 @@
|
|||
{
|
||||
"name": "opencode-agents",
|
||||
"name": "@nextsystems/oac",
|
||||
"version": "0.7.0",
|
||||
"description": "OpenCode agent evaluation framework and test suites",
|
||||
"private": true,
|
||||
"description": "AI agent framework for plan-first development workflows with approval-based execution. Multi-language support for TypeScript, Python, Go, Rust and more.",
|
||||
"workspaces": [
|
||||
"evals/framework"
|
||||
],
|
||||
"bin": {
|
||||
"oac": "./bin/oac.js"
|
||||
},
|
||||
"files": [
|
||||
".opencode/agent/",
|
||||
".opencode/command/",
|
||||
".opencode/context/",
|
||||
".opencode/plugin/",
|
||||
".opencode/profiles/",
|
||||
".opencode/prompts/",
|
||||
".opencode/scripts/",
|
||||
".opencode/skill/",
|
||||
".opencode/tool/",
|
||||
".opencode/config.json",
|
||||
".opencode/opencode.json",
|
||||
"!.opencode/tool/node_modules/",
|
||||
"!.opencode/node_modules/",
|
||||
"!**/node_modules/",
|
||||
"scripts/",
|
||||
"bin/",
|
||||
"registry.json",
|
||||
"install.sh",
|
||||
"VERSION",
|
||||
"LICENSE",
|
||||
"README.md",
|
||||
"CHANGELOG.md",
|
||||
"CONTEXT_SYSTEM_GUIDE.md"
|
||||
],
|
||||
"engines": {
|
||||
"node": ">=14.0.0"
|
||||
},
|
||||
"scripts": {
|
||||
"test": "npm run test:all",
|
||||
"test:all": "cd evals/framework && npm run eval:sdk",
|
||||
|
|
@ -55,10 +85,18 @@
|
|||
},
|
||||
"keywords": [
|
||||
"opencode",
|
||||
"agents",
|
||||
"evaluation",
|
||||
"testing",
|
||||
"ai"
|
||||
"openagents",
|
||||
"ai-agents",
|
||||
"code-generation",
|
||||
"development-workflow",
|
||||
"plan-first",
|
||||
"context-aware",
|
||||
"typescript",
|
||||
"python",
|
||||
"go",
|
||||
"rust",
|
||||
"cli",
|
||||
"automation"
|
||||
],
|
||||
"author": "Darren Hinde",
|
||||
"license": "MIT",
|
||||
|
|
@ -66,6 +104,10 @@
|
|||
"type": "git",
|
||||
"url": "https://github.com/darrenhinde/OpenAgentsControl.git"
|
||||
},
|
||||
"bugs": {
|
||||
"url": "https://github.com/darrenhinde/OpenAgentsControl/issues"
|
||||
},
|
||||
"homepage": "https://github.com/darrenhinde/OpenAgentsControl#readme",
|
||||
"devDependencies": {
|
||||
"glob": "^13.0.0"
|
||||
}
|
||||
|
|
|
|||
|
|
@ -40,24 +40,6 @@
|
|||
],
|
||||
"category": "core"
|
||||
},
|
||||
{
|
||||
"id": "openimplementer",
|
||||
"name": "OpenImplementer",
|
||||
"type": "agent",
|
||||
"path": ".opencode/agent/core/openimplementer.md",
|
||||
"description": "Lightweight implementation agent for focused coding tasks with direct execution, self-testing, and specialist review",
|
||||
"tags": [
|
||||
"implementation",
|
||||
"focused-tasks",
|
||||
"direct-execution",
|
||||
"lightweight"
|
||||
],
|
||||
"dependencies": [
|
||||
"subagent:contextscout",
|
||||
"subagent:reviewer"
|
||||
],
|
||||
"category": "core"
|
||||
},
|
||||
{
|
||||
"id": "openagent",
|
||||
"name": "OpenAgent",
|
||||
|
|
@ -671,37 +653,6 @@
|
|||
}
|
||||
],
|
||||
"plugins": [
|
||||
{
|
||||
"id": "telegram-bot",
|
||||
"name": "Telegram Bot Library",
|
||||
"type": "plugin",
|
||||
"path": ".opencode/_lib/telegram-bot.ts",
|
||||
"description": "Simple Telegram Bot wrapper for sending notifications",
|
||||
"tags": [
|
||||
"telegram",
|
||||
"bot",
|
||||
"library"
|
||||
],
|
||||
"dependencies": [],
|
||||
"category": "specialized"
|
||||
},
|
||||
{
|
||||
"id": "telegram-notify",
|
||||
"name": "Telegram Notifications",
|
||||
"type": "plugin",
|
||||
"path": ".opencode/plugin/telegram-notify.ts",
|
||||
"description": "Send notifications via Telegram bot",
|
||||
"tags": [
|
||||
"notifications",
|
||||
"telegram",
|
||||
"integration"
|
||||
],
|
||||
"dependencies": [
|
||||
"tool:env",
|
||||
"plugin:telegram-bot"
|
||||
],
|
||||
"category": "specialized"
|
||||
},
|
||||
{
|
||||
"id": "notify",
|
||||
"name": "Generic Notifier",
|
||||
|
|
@ -2822,11 +2773,10 @@
|
|||
},
|
||||
"developer": {
|
||||
"name": "Developer",
|
||||
"description": "Complete software development environment with code generation, testing, review, and build tools. Choose OpenImplementer for focused tasks or OpenCoder for complex architecture. Recommended for most developers.",
|
||||
"description": "Complete software development environment with code generation, testing, review, and build tools. Use OpenAgent for general tasks (1-4 files) or OpenCoder for complex architecture (4+ files). Recommended for most developers.",
|
||||
"badge": "RECOMMENDED",
|
||||
"components": [
|
||||
"agent:openagent",
|
||||
"agent:openimplementer",
|
||||
"agent:opencoder",
|
||||
"subagent:task-manager",
|
||||
"subagent:frontend-specialist",
|
||||
|
|
@ -2876,8 +2826,6 @@
|
|||
"tool:env",
|
||||
"tool:gemini",
|
||||
"plugin:notify",
|
||||
"plugin:telegram-bot",
|
||||
"plugin:telegram-notify",
|
||||
"context:essential-patterns",
|
||||
"context:project-context",
|
||||
"context:quick-start",
|
||||
|
|
@ -2894,7 +2842,6 @@
|
|||
"description": "Everything included - all agents, subagents, tools, and plugins for maximum functionality.",
|
||||
"components": [
|
||||
"agent:openagent",
|
||||
"agent:openimplementer",
|
||||
"agent:opencoder",
|
||||
"agent:eval-runner",
|
||||
"agent:copywriter",
|
||||
|
|
@ -2923,8 +2870,6 @@
|
|||
"tool:env",
|
||||
"tool:gemini",
|
||||
"plugin:notify",
|
||||
"plugin:telegram-bot",
|
||||
"plugin:telegram-notify",
|
||||
"context:essential-patterns",
|
||||
"context:project-context",
|
||||
"context:quick-start",
|
||||
|
|
@ -2941,7 +2886,6 @@
|
|||
"description": "Full installation plus System Builder for creating custom AI architectures. For power users and contributors.",
|
||||
"components": [
|
||||
"agent:openagent",
|
||||
"agent:openimplementer",
|
||||
"agent:opencoder",
|
||||
"agent:system-builder",
|
||||
"agent:repo-manager",
|
||||
|
|
@ -2979,8 +2923,6 @@
|
|||
"tool:env",
|
||||
"tool:gemini",
|
||||
"plugin:notify",
|
||||
"plugin:telegram-bot",
|
||||
"plugin:telegram-notify",
|
||||
"context:essential-patterns",
|
||||
"context:project-context",
|
||||
"context:quick-start",
|
||||
|
|
|
|||
Loading…
Reference in a new issue