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.

2026-01-30 17:18:05 +00:00

14 KiB

Raw Blame History

Changelog

All notable changes to this project will be documented in this file.

[Unreleased]

[0.7.0] - 2026-01-29

Changes

feat: add ExternalScout and optimize ContextScout with research-backed patterns (#128)

Documentation

Updated README.md and QUICK_START.md for v0.6.0 accuracy
- Updated version from 0.1.0-alpha.1 to 0.6.0
- Simplified agent architecture (OpenAgent + OpenCoder)
- Completed commands list with /analyze-patterns, /commit-openagents, /build-context-system
- Highlighted ExternalScout with 18+ supported libraries
- Updated installation profiles to mention new agents

[0.6.0] - 2026-01-28

Added

ExternalScout Subagent: New subagent for fetching live, version-specific documentation for external libraries via Context7 API
- Supports 18+ libraries: Drizzle, Better Auth, Next.js, TanStack, Cloudflare Workers, AWS Lambda, and more
- Lazy-loads query patterns for specific libraries only
- Filters and formats results by relevance
- Fallback to official docs via webfetch
- Added to registry with skill:context7 dependency
Context7 Skill: Registered in system for external documentation fetching
- Path: .opencode/skill/context7/SKILLS.MD
- Library registry: .opencode/skill/context7/library-registry.md
- Navigation guide: .opencode/skill/context7/navigation.md

Changed

ContextScout v5.1.0: Optimized with research-backed prompt engineering patterns
- Critical rules moved to first 15% of prompt (position sensitivity)
- Added 3-tier execution priority system
- 20% token reduction via visual operators (→, |, @refs)
- Simplified XML structure (4% XML vs 40%) for multi-model compatibility (Claude, Gemini, GPT-4)
- Added external library detection and ExternalScout recommendation
- Added dependency: subagent:externalscout
- 100% behavior preservation
ExternalScout v2.0.0: Optimized with research-backed prompt engineering patterns
- 42% token reduction via visual operators and inline mappings
- Critical rules moved to first 15% of prompt
- Added 3-tier execution priority system
- Added references to prompt engineering docs and context system
- Enhanced workflow structure with checkpoints
- Added dependencies: context:prompt-engineering, context:context-system
- 100% behavior preservation
Registry Updates:
- Updated ContextScout description to mention multi-model optimization
- Updated ExternalScout description to mention token reduction
- Added version numbers to both subagents
- Added "optimized" tag to both subagents

Documentation

Added .tmp/contextscout-optimization-analysis.md - Detailed optimization metrics
Added .tmp/contextscout-simplification-analysis.md - Multi-model compatibility analysis
Added .tmp/externalscout-optimization-analysis.md - Token reduction analysis

Backup

Created .opencode/agent/subagents/core/contextscout-v4-backup.md - Original v4.0.0
Created .opencode/agent/subagents/core/externalscout-v1-backup.md - Original v1.0.0

[0.5.5] - 2026-01-27

Changes

fix(registry): add component-planning context and remove repo-specific contexts from user profiles (#125)

[0.5.4] - 2026-01-25

Changes

docs: fix agent name casing in documentation (#117)

[0.5.3] - 2026-01-18

Changes

fix: make admin bypass work properly for bot PRs (#113)

[0.5.2] - 2026-01-13

Changes

docs(core): refine project intelligence system and deprecate legacy context (#93)

[0.5.0] - 2025-12-18

Changes

refactor(evals): consolidate documentation and enhance test infrastructure (#56)

Added

Explicit Context File Validation: New expectedContextFiles field in test YAML files allows explicit specification of which context files the agent must read
- Overrides auto-detection when specified
- Uses flexible pattern matching (includes() or endsWith())
- Supports partial paths (e.g., standards/code.md) or full paths
- See evals/agents/shared/tests/EXPLICIT_CONTEXT_FILES.md for detailed guide
- Example test: evals/agents/shared/tests/golden/02-context-loading-explicit.yaml

Changed

Context Loading Evaluator: Now accepts optional BehaviorExpectation config to support explicit file validation
- Shows detection mode in evidence: "Explicit (from YAML test)" or "Auto-detect (from user message)"
- Backward compatible - existing tests work unchanged

Documentation

Added evals/agents/shared/tests/EXPLICIT_CONTEXT_FILES.md - Complete feature guide
Added evals/PATTERN_MATCHING_GUIDE.md - Pattern matching reference
Updated evals/CREATING_TESTS.md - Added expectedContextFiles documentation
Updated evals/README.md - Added new feature section

The format is based on Keep a Changelog, and this project adheres to Semantic Versioning.

[0.5.0] - 2025-12-10

Added

Category-Based Agent Organization: Agents now organized by domain in subdirectories
- core/ - Core system agents (openagent, opencoder)
- meta/ - Meta-level agents (system-builder)
- development/ - Development specialists (frontend-specialist, backend-specialist, devops-specialist, codebase-agent)
- content/ - Content creation agents (copywriter, technical-writer)
- data/ - Data and analysis agents (data-analyst)
- product/ - Product management agents (directory created, ready for agents)
- learning/ - Education and coaching agents (directory created, ready for agents)
Category Metadata Files: Each category has 0-category.json documenting common subagents, tools, and context
Subagent Organization: 13 subagents organized into 4 categories (code, core, system-builder, utils)
Local Registry Fallback: Install script now supports local registry.json for development/testing
Enhanced Registry Validation: Added checks for duplicate IDs and category consistency
Comprehensive Test Suite: 15 automated validation tests for category system
Audit Tools: Scripts to verify migration completeness and system integrity

Changed

Agent File Structure: Agents moved from flat structure to category-based organization
- Example: .opencode/agent/openagent.md → .opencode/agent/core/openagent.md
- Example: .opencode/agent/opencoder.md → .opencode/agent/core/opencoder.md
Registry Schema: Updated to include category-based paths for all agents
Eval Framework: Enhanced with path resolution supporting both agent IDs and category paths
- --agent=openagent resolves to core/openagent (backward compatible)
- --agent=core/openagent works directly (new format)
Documentation: Updated all docs to reference category-based structure
Install Script: Enhanced with local registry fallback for offline/development use

Fixed

Frontend Specialist: Renamed frontend-design-agent.md to frontend-specialist.md for consistency
Eval Directory Structure: Archived legacy flat eval structure to _archive/ for clarity
Registry Validation: Fixed validation script to handle category-based paths correctly

Developer Experience

Backward Compatibility: Agent IDs like openagent still work via path resolution
Local Testing: No need to push to GitHub to test registry changes
Clear Organization: Agents grouped by domain make discovery easier
Validation Tools: Automated tests ensure system integrity

Migration Notes

Agent Paths: Update references from flat to category-based paths
- Old: .opencode/agent/openagent.md
- New: .opencode/agent/core/openagent.md
Eval Framework: Both formats work due to path resolution
- --agent=openagent (backward compatible)
- --agent=core/openagent (new format)
No Breaking Changes: Path resolution maintains backward compatibility

Technical Details

Files Modified: 14+ files updated for category structure
Agents Organized: 23 total agents (10 category agents, 13 subagents)
Test Coverage: 15/15 validation tests passing (100%)
Audit Status: 8/8 checks passing (100%)

[0.3.1] - 2025-12-09

Fixed

CI: Check only commit title for skip patterns (#46)

[0.0.2] - 2025-11-29

Added

New ExecutionBalanceEvaluator in evals/framework to assess read vs execution ordering and ratio
Contributor guide: docs/contributing/ADDING_EVALUATOR.md describing evaluator design principles
Test cases under evals/agents/openagent/tests/10-execution-balance/ (positive & negative scenarios)

Changed

Framework README updated with section documenting ExecutionBalanceEvaluator and violation codes

[0.5.1] - 2025-12-31

Fixed

Install Script Non-Interactive Bug: Fixed critical bug where curl | bash -s <profile> would fail with "Installation cancelled by user" when existing files were present
- Root cause: Collision handling prompted for user input even in non-interactive mode
- Solution: Auto-detect non-interactive mode and use "skip" strategy by default

Added

Installer CI Workflow: New .github/workflows/installer-checks.yml runs on install.sh changes
- ShellCheck static analysis
- Bash syntax validation
- Non-interactive mode tests
- End-to-end installation tests
- Profile smoke tests on Ubuntu and macOS
Non-Interactive Tests: New scripts/tests/test-non-interactive.sh validates piped execution
E2E Installation Tests: New scripts/tests/test-e2e-install.sh validates full installation workflow

Changed

Updated scripts/tests/README.md with new test documentation

[0.5.0] - 2025-12-18

Added

Explicit Context File Validation: New expectedContextFiles field in test YAML files
- Overrides auto-detection when specified
- Uses flexible pattern matching (includes() or endsWith())
- Supports partial paths (e.g., standards/code.md) or full paths

Changed

Context Loading Evaluator: Now accepts optional BehaviorExpectation config
- Shows detection mode in evidence: "Explicit (from YAML test)" or "Auto-detect (from user message)"
- Backward compatible - existing tests work unchanged

Documentation

Added evals/agents/shared/tests/EXPLICIT_CONTEXT_FILES.md - Complete feature guide
Added evals/PATTERN_MATCHING_GUIDE.md - Pattern matching reference
Updated evals/CREATING_TESTS.md and evals/README.md

[0.4.0] - 2025-12-10

Added

Category-Based Agent Organization: Agents now organized by domain in subdirectories
- core/ - Core system agents (openagent, opencoder)
- meta/ - Meta-level agents (system-builder)
- development/ - Development specialists (frontend-specialist, backend-specialist, devops-specialist, codebase-agent)
- content/ - Content creation agents (copywriter, technical-writer)
- data/ - Data and analysis agents (data-analyst)
- product/ - Product management agents (directory created, ready for agents)
- learning/ - Education and coaching agents (directory created, ready for agents)
Category Metadata Files: Each category has 0-category.json documenting common subagents, tools, and context
Subagent Organization: 13 subagents organized into 4 categories (code, core, system-builder, utils)
Local Registry Fallback: Install script now supports local registry.json for development/testing
Enhanced Registry Validation: Added checks for duplicate IDs and category consistency
Comprehensive Test Suite: 15 automated validation tests for category system
Audit Tools: Scripts to verify migration completeness and system integrity

Changed

Agent File Structure: Agents moved from flat structure to category-based organization
- Example: .opencode/agent/openagent.md → .opencode/agent/core/openagent.md
- Example: .opencode/agent/opencoder.md → .opencode/agent/core/opencoder.md
Registry Schema: Updated to include category-based paths for all agents
Eval Framework: Enhanced with path resolution supporting both agent IDs and category paths
- --agent=openagent resolves to core/openagent (backward compatible)
- --agent=core/openagent works directly (new format)
Documentation: Updated all docs to reference category-based structure
Install Script: Enhanced with local registry fallback for offline/development use

Fixed

Frontend Specialist: Renamed frontend-design-agent.md to frontend-specialist.md for consistency
Eval Directory Structure: Archived legacy flat eval structure to _archive/ for clarity
Registry Validation: Fixed validation script to handle category-based paths correctly

Developer Experience

Backward Compatibility: Agent IDs like openagent still work via path resolution
Local Testing: No need to push to GitHub to test registry changes
Clear Organization: Agents grouped by domain make discovery easier
Validation Tools: Automated tests ensure system integrity

Migration Notes

Agent Paths: Update references from flat to category-based paths
- Old: .opencode/agent/openagent.md
- New: .opencode/agent/core/openagent.md
Eval Framework: Both formats work due to path resolution
- --agent=openagent (backward compatible)
- --agent=core/openagent (new format)
No Breaking Changes: Path resolution maintains backward compatibility

Technical Details

Files Modified: 14+ files updated for category structure
Agents Organized: 23 total agents (10 category agents, 13 subagents)
Test Coverage: 15/15 validation tests passing (100%)
Audit Status: 8/8 checks passing (100%)

[0.3.1] - 2025-12-09

Fixed

CI: Check only commit title for skip patterns (#46)

[0.0.2] - 2025-11-29

Added

New ExecutionBalanceEvaluator in evals/framework to assess read vs execution ordering and ratio
Contributor guide: docs/contributing/ADDING_EVALUATOR.md describing evaluator design principles
Test cases under evals/agents/openagent/tests/10-execution-balance/ (positive & negative scenarios)

Changed

Framework README updated with section documenting ExecutionBalanceEvaluator and violation codes

Version Format

v0.X.Y
│ │ │
│ │ └─ Patch version (bug fixes, minor changes)
│ └─── Minor version (new features, non-breaking changes)
└───── Major version (breaking changes, major milestones)

Version History

0.5.1 - Install script bug fix, CI improvements for installer
0.5.0 - Explicit context file validation in evals
0.4.0 - Category-based agent organization system
0.3.1 - CI improvements
0.0.2 - Execution balance evaluator

14 KiB Raw Blame History

Changelog

[Unreleased]

[0.7.0] - 2026-01-29

Changes

Documentation

[0.6.0] - 2026-01-28

Added

Changed

Documentation

Backup

[0.5.5] - 2026-01-27

Changes

[0.5.4] - 2026-01-25

Changes

[0.5.3] - 2026-01-18

Changes

[0.5.2] - 2026-01-13

Changes

[0.5.0] - 2025-12-18

Changes

Added

Changed

Documentation

[0.5.0] - 2025-12-10

Added

Changed

Fixed

Developer Experience

Migration Notes

Technical Details

[0.3.1] - 2025-12-09

Fixed

[0.0.2] - 2025-11-29

Added

Changed

[0.5.1] - 2025-12-31

Fixed

Added

Changed

[0.5.0] - 2025-12-18

Added

Changed

Documentation

[0.4.0] - 2025-12-10

Added

Changed

Fixed

Developer Experience

Migration Notes

Technical Details

[0.3.1] - 2025-12-09

Fixed

[0.0.2] - 2025-11-29

Added

Changed

Version Format

Version History

14 KiB

Raw Blame History