feat: Context path configuration and documentation reorganization #143
+2,150
−1,118
Conversation
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
- 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
- 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)
- 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
- 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.
- 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).
- 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)
- 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.
- 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.
Minor enhancement to First-Time User Checklist step 2 for extra clarity.
- 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
- 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
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.
- 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
- 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.
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.
This suggestion is invalid because no changes were made to the code.
Suggestions cannot be applied while the pull request is closed.
Suggestions cannot be applied while viewing a subset of changes.
Only one suggestion per line can be applied in a batch.
Add this suggestion to a batch that can be applied as a single commit.
Applying suggestions on deleted lines is not supported.
You must change the existing code in this line in order to create a valid suggestion.
Outdated suggestions cannot be applied.
This suggestion has been applied or marked resolved.
Suggestions cannot be applied from pending reviews.
Suggestions cannot be applied on multi-line comments.
Suggestions cannot be applied while the pull request is queued to merge.
Suggestion cannot be applied right now. Please check back later.
Summary
This PR introduces configurable context paths and reorganizes documentation into the context system, improving flexibility and maintainability.
Key Changes
🎯 Context Path Configuration
paths.jsonconfiguration for custom context directories@referenceloading in agent frontmatter.context,.ai/context).opencode/context/📝 Documentation Reorganization
NPM_PUBLISHING_GUIDE.md→guides/npm-publishing.md(context system)guides/github-issues-workflow.mdfor issue management/add-contextcommand for interactive context setup🔧 Agent Updates
opencoder.mdto support configurable context rootcontextscout.mdto use paths.json configurationBenefits
✅ Flexibility - Projects can choose their own context directory structure
✅ Consistency - Centralized path configuration via paths.json
✅ Discoverability - Documentation now in context system (ContextScout can find it)
✅ Backward Compatible - Existing setups continue to work
✅ Team-Ready - Easier to customize for different project structures
Testing
Files Changed
Modified:
.opencode/agent/core/opencoder.md.opencode/agent/subagents/core/contextscout.md.opencode/context/openagents-repo/navigation.mdREADME.mdAdded:
.opencode/command/add-context.md.opencode/context/core/config/paths.json.opencode/context/core/system/context-paths.md.opencode/context/openagents-repo/guides/github-issues-workflow.md.opencode/context/openagents-repo/guides/npm-publishing.mdRemoved:
NPM_PUBLISHING_GUIDE.md(moved to context system)Related Issues
Closes #[issue-number] (if applicable)
Ready to merge ✅