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/component-planning
|
||||||
- context:core/workflows/external-libraries
|
- context:core/workflows/external-libraries
|
||||||
|
|
||||||
|
# Context Configuration
|
||||||
|
context:
|
||||||
|
- "@.opencode/context/core/config/paths.json"
|
||||||
|
|
||||||
tools:
|
tools:
|
||||||
task: true
|
task: true
|
||||||
read: 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,
|
quality, and alignment with established patterns. Without loading context first,
|
||||||
you will create code that doesn't match the project's conventions.
|
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:
|
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
|
- Language-specific patterns if available
|
||||||
|
|
||||||
WHY THIS MATTERS:
|
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!)
|
- `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)
|
- `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 (via TaskManager)
|
||||||
- `CoderAgent` - Complex multi-component implementations
|
|
||||||
- `TestEngineer` - Testing after implementation
|
- `TestEngineer` - Testing after implementation
|
||||||
- `DocWriter` - Documentation generation
|
- `DocWriter` - Documentation generation
|
||||||
|
|
||||||
|
|
@ -146,16 +155,13 @@ Code Standards
|
||||||
|
|
||||||
<delegation_rules>
|
<delegation_rules>
|
||||||
<delegate_when>
|
<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">
|
<condition id="complex_task" trigger="multi_component_implementation" action="delegate_to_coder_agent">
|
||||||
For complex, multi-component implementations delegate to CoderAgent
|
For complex, multi-component implementations delegate to CoderAgent
|
||||||
</condition>
|
</condition>
|
||||||
</delegate_when>
|
</delegate_when>
|
||||||
|
|
||||||
<execute_directly_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>
|
</execute_directly_when>
|
||||||
</delegation_rules>
|
</delegation_rules>
|
||||||
|
|
||||||
|
|
@ -167,13 +173,14 @@ Code Standards
|
||||||
Goal: Understand what's needed. Nothing written to disk.
|
Goal: Understand what's needed. Nothing written to disk.
|
||||||
|
|
||||||
1. Call `ContextScout` to discover relevant project context files.
|
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.
|
- Capture the returned file paths — you will persist these in Stage 3.
|
||||||
2. **For external packages/libraries**:
|
2. **For external packages/libraries**:
|
||||||
a. Check for install scripts FIRST: `ls scripts/install/ scripts/setup/ bin/install*`
|
a. Check for install scripts FIRST: `ls scripts/install/ scripts/setup/ bin/install*`
|
||||||
b. If scripts exist: Read and understand them before fetching docs.
|
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.
|
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.
|
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.*
|
*Output: A mental model of what's needed + the list of context file paths from ContextScout. Nothing persisted yet.*
|
||||||
</stage>
|
</stage>
|
||||||
|
|
@ -211,8 +218,8 @@ Code Standards
|
||||||
Goal: Create the session and persist everything discovered so far.
|
Goal: Create the session and persist everything discovered so far.
|
||||||
|
|
||||||
1. Create session directory: `.tmp/sessions/{YYYY-MM-DD}-{task-slug}/`
|
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).
|
2. Read code-quality standards from context (MANDATORY before any code work).
|
||||||
3. Read `.opencode/context/core/workflows/component-planning.md`.
|
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:
|
4. Write `context.md` in the session directory. This is the single source of truth for all downstream agents:
|
||||||
|
|
||||||
```markdown
|
```markdown
|
||||||
|
|
@ -227,8 +234,7 @@ Code Standards
|
||||||
|
|
||||||
## Context Files (Standards to Follow)
|
## Context Files (Standards to Follow)
|
||||||
{Paths discovered by ContextScout in Stage 1 — these are the standards}
|
{Paths discovered by ContextScout in Stage 1 — these are the standards}
|
||||||
- .opencode/context/core/standards/code-quality.md
|
- {discovered context file paths}
|
||||||
- {other discovered paths}
|
|
||||||
|
|
||||||
## Reference Files (Source Material to Look At)
|
## Reference Files (Source Material to Look At)
|
||||||
{Project files relevant to this task — NOT standards}
|
{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
|
version: 6.0.0
|
||||||
author: darrenhinde
|
author: darrenhinde
|
||||||
|
|
||||||
|
# Context Configuration
|
||||||
|
context:
|
||||||
|
- "@.opencode/context/core/config/paths.json"
|
||||||
|
|
||||||
# Agent Configuration
|
# Agent Configuration
|
||||||
mode: subagent
|
mode: subagent
|
||||||
temperature: 0.1
|
temperature: 0.1
|
||||||
|
|
@ -56,14 +60,14 @@ tags:
|
||||||
|
|
||||||
# ContextScout
|
# 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: This section must be in first 15% -->
|
||||||
<critical_rules priority="absolute" enforcement="strict">
|
<critical_rules priority="absolute" enforcement="strict">
|
||||||
<rule id="context_root">
|
<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>
|
||||||
<rule id="read_only">
|
<rule id="read_only">
|
||||||
Read-only agent. NEVER use write, edit, bash, task, or any tool besides read, grep, glob.
|
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
|
## Implementation
|
||||||
|
|
||||||
### Delegation
|
### Delegation
|
||||||
- Delegates to: **opencoder** (primary) or **openimplementer** (fallback)
|
- Delegates to: **opencoder** (primary)
|
||||||
- Uses context search capabilities for pattern matching
|
- Uses context search capabilities for pattern matching
|
||||||
- Returns structured pattern analysis results
|
- Returns structured pattern analysis results
|
||||||
|
|
||||||
|
|
@ -186,7 +186,7 @@ Formatted for documentation + sharing:
|
||||||
"type": "command",
|
"type": "command",
|
||||||
"category": "analysis",
|
"category": "analysis",
|
||||||
"description": "Analyze codebase for patterns and similar implementations",
|
"description": "Analyze codebase for patterns and similar implementations",
|
||||||
"delegates_to": ["opencoder", "openimplementer"],
|
"delegates_to": ["opencoder"],
|
||||||
"parameters": ["pattern", "language", "depth", "output"]
|
"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:**
|
**Scopes for this repo:**
|
||||||
- `evals` - Evaluation framework changes
|
- `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/meta` - Meta agents (system-builder, repo-manager)
|
||||||
- `agents/content` - Content category agents (copywriter, technical-writer)
|
- `agents/content` - Content category agents (copywriter, technical-writer)
|
||||||
- `agents/data` - Data category agents (data-analyst)
|
- `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
|
- Error handling patterns
|
||||||
- Language-specific guidelines (JavaScript, Python, Go, Rust)
|
- 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
|
### react-patterns.md
|
||||||
Modern React patterns, hooks usage, and component design principles.
|
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
|
- API versioning strategies
|
||||||
- Authentication and authorization
|
- Authentication and authorization
|
||||||
|
|
||||||
**Used by**: opencoder, openimplementer
|
**Used by**: opencoder
|
||||||
|
|
||||||
## Usage
|
## Usage
|
||||||
|
|
||||||
|
|
|
||||||
|
|
@ -2,7 +2,7 @@
|
||||||
|
|
||||||
**Category**: development
|
**Category**: development
|
||||||
**Purpose**: REST API design principles, GraphQL patterns, and API versioning strategies
|
**Purpose**: REST API design principles, GraphQL patterns, and API versioning strategies
|
||||||
**Used by**: opencoder, openimplementer
|
**Used by**: opencoder
|
||||||
|
|
||||||
---
|
---
|
||||||
|
|
||||||
|
|
|
||||||
|
|
@ -2,7 +2,7 @@
|
||||||
|
|
||||||
**Category**: development
|
**Category**: development
|
||||||
**Purpose**: Core coding standards and best practices for writing clean, maintainable code
|
**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
|
**Category**: development
|
||||||
**Purpose**: REST API design principles, GraphQL patterns, and API versioning strategies
|
**Purpose**: REST API design principles, GraphQL patterns, and API versioning strategies
|
||||||
**Used by**: opencoder, openimplementer
|
**Used by**: opencoder
|
||||||
|
|
||||||
---
|
---
|
||||||
|
|
||||||
|
|
|
||||||
|
|
@ -2,7 +2,7 @@
|
||||||
|
|
||||||
**Category**: development
|
**Category**: development
|
||||||
**Purpose**: Core coding standards and best practices for writing clean, maintainable code
|
**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:
|
Agents:
|
||||||
- `frontend-specialist.md` - React, Vue, modern CSS
|
- `frontend-specialist.md` - React, Vue, modern CSS
|
||||||
- `devops-specialist.md` - CI/CD, deployment, infrastructure
|
- `devops-specialist.md` - CI/CD, deployment, infrastructure
|
||||||
- `openimplementer.md` - Lightweight implementation (1-4 files, <60 min)
|
|
||||||
|
|
||||||
**When to use**: Building applications, dev tasks
|
**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)
|
**Purpose**: Essential system agents (always available)
|
||||||
|
|
||||||
**Agents**:
|
**Agents**:
|
||||||
- openagent, opencoder, openimplementer, system-builder
|
|
||||||
|
|
||||||
**When to use**: System-level tasks, orchestration, coding (simple or complex)
|
**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
|
├── 0-category.json # Category metadata
|
||||||
├── openagent.md
|
├── openagent.md
|
||||||
├── opencoder.md
|
├── opencoder.md
|
||||||
└── openimplementer.md
|
|
||||||
|
|
||||||
.opencode/agent/subagents/development/
|
.opencode/agent/subagents/development/
|
||||||
├── 0-category.json # Subagent category metadata
|
├── 0-category.json # Subagent category metadata
|
||||||
|
|
@ -351,7 +349,6 @@ Loads: `.opencode/context/development/react-patterns.md`
|
||||||
├── core/
|
├── core/
|
||||||
│ ├── openagent.md
|
│ ├── openagent.md
|
||||||
│ ├── opencoder.md
|
│ ├── opencoder.md
|
||||||
│ └── openimplementer.md
|
|
||||||
├── subagents/
|
├── subagents/
|
||||||
│ ├── development/
|
│ ├── development/
|
||||||
│ │ ├── frontend-specialist.md
|
│ │ ├── frontend-specialist.md
|
||||||
|
|
@ -384,7 +381,6 @@ core/
|
||||||
├── 0-category.json
|
├── 0-category.json
|
||||||
├── openagent.md
|
├── openagent.md
|
||||||
├── opencoder.md
|
├── opencoder.md
|
||||||
└── openimplementer.md
|
|
||||||
```
|
```
|
||||||
|
|
||||||
### Development Subagents
|
### Development Subagents
|
||||||
|
|
@ -414,7 +410,6 @@ evals/agents/core/
|
||||||
│ ├── config/config.yaml
|
│ ├── config/config.yaml
|
||||||
│ └── tests/smoke-test.yaml
|
│ └── tests/smoke-test.yaml
|
||||||
├── opencoder/
|
├── opencoder/
|
||||||
└── openimplementer/
|
|
||||||
```
|
```
|
||||||
|
|
||||||
---
|
---
|
||||||
|
|
|
||||||
|
|
@ -163,7 +163,7 @@ ERROR: Missing dependency: subagent:nonexistent
|
||||||
**Specialist Subagents** (8 in Developer profile):
|
**Specialist Subagents** (8 in Developer profile):
|
||||||
- frontend-specialist: React, Vue, CSS architecture
|
- frontend-specialist: React, Vue, CSS architecture
|
||||||
- devops-specialist: CI/CD, infrastructure, deployment
|
- devops-specialist: CI/CD, infrastructure, deployment
|
||||||
- openimplementer: Lightweight implementation (1-4 files, <60 min)
|
|
||||||
- task-manager: Feature breakdown and planning
|
- task-manager: Feature breakdown and planning
|
||||||
- documentation: Create and update docs
|
- documentation: Create and update docs
|
||||||
- coder-agent: Execute coding subtasks
|
- 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**:
|
**Include**:
|
||||||
- Core agents (openagent, opencoder)
|
- Core agents (openagent, opencoder)
|
||||||
- Development specialist subagents (frontend, devops)
|
- Development specialist subagents (frontend, devops)
|
||||||
- OpenImplementer (openimplementer - lightweight implementation agent)
|
|
||||||
- All code subagents (tester, reviewer, coder-agent, build-agent)
|
- All code subagents (tester, reviewer, coder-agent, build-agent)
|
||||||
- Dev commands (commit, test, validate-repo, analyze-patterns)
|
- Dev commands (commit, test, validate-repo, analyze-patterns)
|
||||||
- Dev context (standards/code, standards/tests, workflows/*)
|
- 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)
|
- Content specialists (copywriter, technical-writer)
|
||||||
- Data specialists (data-analyst)
|
- Data specialists (data-analyst)
|
||||||
- Image tools (gemini, image-specialist)
|
- Image tools (gemini, image-specialist)
|
||||||
- Notification tools (telegram, notify)
|
- Notification tools (notify)
|
||||||
|
|
||||||
**Exclude**:
|
**Exclude**:
|
||||||
- Development specialists
|
- Development specialists
|
||||||
|
|
@ -330,7 +329,7 @@ Add profile validation to CI:
|
||||||
| data | ❌ | ❌ | ✅ | ✅ | ✅ |
|
| data | ❌ | ❌ | ✅ | ✅ | ✅ |
|
||||||
| meta | ❌ | ❌ | ❌ | ❌ | ✅ |
|
| 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/openagent.md
|
||||||
.opencode/agent/core/opencoder.md
|
.opencode/agent/core/opencoder.md
|
||||||
```
|
|
||||||
|
|
||||||
### Meta Agents
|
|
||||||
|
|
||||||
```
|
|
||||||
.opencode/agent/meta/system-builder.md
|
.opencode/agent/meta/system-builder.md
|
||||||
```
|
```
|
||||||
|
|
||||||
|
|
@ -133,7 +128,9 @@ README.md # Main documentation
|
||||||
```
|
```
|
||||||
.opencode/agent/development/frontend-specialist.md
|
.opencode/agent/development/frontend-specialist.md
|
||||||
.opencode/agent/development/devops-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
|
### Content Agents
|
||||||
|
|
|
||||||
|
|
@ -2,7 +2,7 @@
|
||||||
|
|
||||||
**Purpose**: Context files specific to the OpenAgents Control repository
|
**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 |
|
| **Concepts** | 2 files | Core ideas and principles |
|
||||||
| **Examples** | 1 file | Working code samples |
|
| **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 |
|
| **Lookup** | 4 files | Quick reference tables |
|
||||||
| **Errors** | 1 file | Common issues + solutions |
|
| **Errors** | 1 file | Common issues + solutions |
|
||||||
|
|
||||||
|
|
@ -46,6 +46,8 @@
|
||||||
| `guides/adding-agent.md` | How to add new agents | ⭐⭐⭐⭐ |
|
| `guides/adding-agent.md` | How to add new agents | ⭐⭐⭐⭐ |
|
||||||
| `guides/testing-agent.md` | How to test agents | ⭐⭐⭐⭐ |
|
| `guides/testing-agent.md` | How to test agents | ⭐⭐⭐⭐ |
|
||||||
| `guides/external-libraries-workflow.md` | How to handle external library dependencies | ⭐⭐⭐⭐ |
|
| `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/updating-registry.md` | How to update registry | ⭐⭐⭐ |
|
||||||
| `guides/debugging.md` | How to debug issues | ⭐⭐⭐ |
|
| `guides/debugging.md` | How to debug issues | ⭐⭐⭐ |
|
||||||
| `guides/resolving-installer-wildcard-failures.md` | Fix wildcard context install failures | ⭐⭐⭐ |
|
| `guides/resolving-installer-wildcard-failures.md` | Fix wildcard context install failures | ⭐⭐⭐ |
|
||||||
|
|
@ -105,6 +107,12 @@
|
||||||
4. Load `examples/subagent-prompt-structure.md` (if subagent)
|
4. Load `examples/subagent-prompt-structure.md` (if subagent)
|
||||||
5. Load `guides/testing-agent.md` (validate)
|
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:
|
### For Debugging:
|
||||||
1. Load `guides/debugging.md` (general approach)
|
1. Load `guides/debugging.md` (general approach)
|
||||||
2. Load specific error file from `errors/`
|
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": [
|
"components": [
|
||||||
"agent:openagent",
|
"agent:openagent",
|
||||||
"agent:opencoder",
|
"agent:opencoder",
|
||||||
"agent:openimplementer",
|
|
||||||
"agent:system-builder",
|
"agent:system-builder",
|
||||||
"agent:repo-manager",
|
"agent:repo-manager",
|
||||||
"agent:eval-runner",
|
"agent:eval-runner",
|
||||||
|
|
|
||||||
|
|
@ -1,10 +1,9 @@
|
||||||
{
|
{
|
||||||
"name": "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",
|
"badge": "RECOMMENDED",
|
||||||
"components": [
|
"components": [
|
||||||
"agent:openagent",
|
"agent:openagent",
|
||||||
"agent:openimplementer",
|
|
||||||
"agent:opencoder",
|
"agent:opencoder",
|
||||||
"subagent:task-manager",
|
"subagent:task-manager",
|
||||||
"subagent:frontend-specialist",
|
"subagent:frontend-specialist",
|
||||||
|
|
|
||||||
|
|
@ -4,7 +4,6 @@
|
||||||
"components": [
|
"components": [
|
||||||
"agent:openagent",
|
"agent:openagent",
|
||||||
"agent:opencoder",
|
"agent:opencoder",
|
||||||
"agent:openimplementer",
|
|
||||||
"agent:eval-runner",
|
"agent:eval-runner",
|
||||||
"agent:copywriter",
|
"agent:copywriter",
|
||||||
"agent:technical-writer",
|
"agent:technical-writer",
|
||||||
|
|
|
||||||
|
|
@ -12,7 +12,7 @@ All notable changes to this project will be documented in this file.
|
||||||
### Documentation
|
### Documentation
|
||||||
- Updated README.md and QUICK_START.md for v0.6.0 accuracy
|
- Updated README.md and QUICK_START.md for v0.6.0 accuracy
|
||||||
- Updated version from 0.1.0-alpha.1 to 0.6.0
|
- 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
|
- Completed commands list with /analyze-patterns, /commit-openagents, /build-context-system
|
||||||
- Highlighted ExternalScout with 18+ supported libraries
|
- Highlighted ExternalScout with 18+ supported libraries
|
||||||
- Updated installation profiles to mention new agents
|
- 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:
|
Latest updates:
|
||||||
- ExternalScout subagent for fetching live library documentation (18+ libraries)
|
- ExternalScout subagent for fetching live library documentation (18+ libraries)
|
||||||
- OpenImplementer agent for lightweight implementation tasks
|
|
||||||
- Enhanced ContextScout with multi-model optimization
|
- Enhanced ContextScout with multi-model optimization
|
||||||
- Complete command and agent documentation
|
- Complete command and agent documentation
|
||||||
|
- Simplified agent architecture (OpenAgent + OpenCoder)
|
||||||
|
|
||||||
## 🤝 Community
|
## 🤝 Community
|
||||||
|
|
||||||
|
|
|
||||||
56
package.json
56
package.json
|
|
@ -1,11 +1,41 @@
|
||||||
{
|
{
|
||||||
"name": "opencode-agents",
|
"name": "@nextsystems/oac",
|
||||||
"version": "0.7.0",
|
"version": "0.7.0",
|
||||||
"description": "OpenCode agent evaluation framework and test suites",
|
"description": "AI agent framework for plan-first development workflows with approval-based execution. Multi-language support for TypeScript, Python, Go, Rust and more.",
|
||||||
"private": true,
|
|
||||||
"workspaces": [
|
"workspaces": [
|
||||||
"evals/framework"
|
"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": {
|
"scripts": {
|
||||||
"test": "npm run test:all",
|
"test": "npm run test:all",
|
||||||
"test:all": "cd evals/framework && npm run eval:sdk",
|
"test:all": "cd evals/framework && npm run eval:sdk",
|
||||||
|
|
@ -55,10 +85,18 @@
|
||||||
},
|
},
|
||||||
"keywords": [
|
"keywords": [
|
||||||
"opencode",
|
"opencode",
|
||||||
"agents",
|
"openagents",
|
||||||
"evaluation",
|
"ai-agents",
|
||||||
"testing",
|
"code-generation",
|
||||||
"ai"
|
"development-workflow",
|
||||||
|
"plan-first",
|
||||||
|
"context-aware",
|
||||||
|
"typescript",
|
||||||
|
"python",
|
||||||
|
"go",
|
||||||
|
"rust",
|
||||||
|
"cli",
|
||||||
|
"automation"
|
||||||
],
|
],
|
||||||
"author": "Darren Hinde",
|
"author": "Darren Hinde",
|
||||||
"license": "MIT",
|
"license": "MIT",
|
||||||
|
|
@ -66,6 +104,10 @@
|
||||||
"type": "git",
|
"type": "git",
|
||||||
"url": "https://github.com/darrenhinde/OpenAgentsControl.git"
|
"url": "https://github.com/darrenhinde/OpenAgentsControl.git"
|
||||||
},
|
},
|
||||||
|
"bugs": {
|
||||||
|
"url": "https://github.com/darrenhinde/OpenAgentsControl/issues"
|
||||||
|
},
|
||||||
|
"homepage": "https://github.com/darrenhinde/OpenAgentsControl#readme",
|
||||||
"devDependencies": {
|
"devDependencies": {
|
||||||
"glob": "^13.0.0"
|
"glob": "^13.0.0"
|
||||||
}
|
}
|
||||||
|
|
|
||||||
|
|
@ -40,24 +40,6 @@
|
||||||
],
|
],
|
||||||
"category": "core"
|
"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",
|
"id": "openagent",
|
||||||
"name": "OpenAgent",
|
"name": "OpenAgent",
|
||||||
|
|
@ -671,37 +653,6 @@
|
||||||
}
|
}
|
||||||
],
|
],
|
||||||
"plugins": [
|
"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",
|
"id": "notify",
|
||||||
"name": "Generic Notifier",
|
"name": "Generic Notifier",
|
||||||
|
|
@ -2822,11 +2773,10 @@
|
||||||
},
|
},
|
||||||
"developer": {
|
"developer": {
|
||||||
"name": "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",
|
"badge": "RECOMMENDED",
|
||||||
"components": [
|
"components": [
|
||||||
"agent:openagent",
|
"agent:openagent",
|
||||||
"agent:openimplementer",
|
|
||||||
"agent:opencoder",
|
"agent:opencoder",
|
||||||
"subagent:task-manager",
|
"subagent:task-manager",
|
||||||
"subagent:frontend-specialist",
|
"subagent:frontend-specialist",
|
||||||
|
|
@ -2876,8 +2826,6 @@
|
||||||
"tool:env",
|
"tool:env",
|
||||||
"tool:gemini",
|
"tool:gemini",
|
||||||
"plugin:notify",
|
"plugin:notify",
|
||||||
"plugin:telegram-bot",
|
|
||||||
"plugin:telegram-notify",
|
|
||||||
"context:essential-patterns",
|
"context:essential-patterns",
|
||||||
"context:project-context",
|
"context:project-context",
|
||||||
"context:quick-start",
|
"context:quick-start",
|
||||||
|
|
@ -2894,7 +2842,6 @@
|
||||||
"description": "Everything included - all agents, subagents, tools, and plugins for maximum functionality.",
|
"description": "Everything included - all agents, subagents, tools, and plugins for maximum functionality.",
|
||||||
"components": [
|
"components": [
|
||||||
"agent:openagent",
|
"agent:openagent",
|
||||||
"agent:openimplementer",
|
|
||||||
"agent:opencoder",
|
"agent:opencoder",
|
||||||
"agent:eval-runner",
|
"agent:eval-runner",
|
||||||
"agent:copywriter",
|
"agent:copywriter",
|
||||||
|
|
@ -2923,8 +2870,6 @@
|
||||||
"tool:env",
|
"tool:env",
|
||||||
"tool:gemini",
|
"tool:gemini",
|
||||||
"plugin:notify",
|
"plugin:notify",
|
||||||
"plugin:telegram-bot",
|
|
||||||
"plugin:telegram-notify",
|
|
||||||
"context:essential-patterns",
|
"context:essential-patterns",
|
||||||
"context:project-context",
|
"context:project-context",
|
||||||
"context:quick-start",
|
"context:quick-start",
|
||||||
|
|
@ -2941,7 +2886,6 @@
|
||||||
"description": "Full installation plus System Builder for creating custom AI architectures. For power users and contributors.",
|
"description": "Full installation plus System Builder for creating custom AI architectures. For power users and contributors.",
|
||||||
"components": [
|
"components": [
|
||||||
"agent:openagent",
|
"agent:openagent",
|
||||||
"agent:openimplementer",
|
|
||||||
"agent:opencoder",
|
"agent:opencoder",
|
||||||
"agent:system-builder",
|
"agent:system-builder",
|
||||||
"agent:repo-manager",
|
"agent:repo-manager",
|
||||||
|
|
@ -2979,8 +2923,6 @@
|
||||||
"tool:env",
|
"tool:env",
|
||||||
"tool:gemini",
|
"tool:gemini",
|
||||||
"plugin:notify",
|
"plugin:notify",
|
||||||
"plugin:telegram-bot",
|
|
||||||
"plugin:telegram-notify",
|
|
||||||
"context:essential-patterns",
|
"context:essential-patterns",
|
||||||
"context:project-context",
|
"context:project-context",
|
||||||
"context:quick-start",
|
"context:quick-start",
|
||||||
|
|
|
||||||
Loading…
Reference in a new issue