cclohmar/OpenWriterControle
1
0
Fork 0
Code Issues Pull requests Projects Releases Packages Wiki Activity Actions 1
OpenWriterControle/CHANGELOG.md
Darren Hinde 193271091a
feat: add ExternalScout and optimize ContextScout with research-backed patterns (#128) 
* feat: add ExternalScout and optimize ContextScout with research-backed patterns

## New Features

### ExternalScout Subagent (v2.0.0)
- Fetches live, version-specific documentation for external libraries via Context7 API
- Supports 18+ libraries: Drizzle, Better Auth, Next.js, TanStack, Cloudflare Workers, AWS Lambda, Vercel, Shadcn/ui, Radix UI, Tailwind CSS, Zustand, Jotai, Zod, React Hook Form, Vitest, Playwright
- Lazy-loads query patterns for specific libraries only
- Filters and formats results by relevance (Critical → High → Medium)
- Fallback to official docs via webfetch
- 42% token reduction via research-backed optimization
- Added to registry with skill:context7 dependency

### Context7 Skill
- Registered in system for external documentation fetching
- Library registry with 18+ supported libraries
- Query optimization patterns per library
- Navigation guide and README

## Optimizations

### 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) 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 Optimizations
- 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
- Added ExternalScout subagent entry
- Added Context7 skill entry
- Updated ContextScout dependencies to include ExternalScout
- Added version numbers to both subagents
- Enhanced descriptions with optimization details
- Added 'optimized' tag to both subagents

## Files Added
- .opencode/agent/subagents/core/externalscout.md
- .opencode/skill/context7/README.md
- .opencode/skill/context7/library-registry.md
- .opencode/skill/context7/navigation.md
- .opencode/agent/subagents/core/contextscout-v4-backup.md (backup)
- .opencode/agent/subagents/core/externalscout-v1-backup.md (backup)

## Files Modified
- .opencode/agent/subagents/core/contextscout.md (v4.0.0 → v5.1.0)
- registry.json (added ExternalScout, Context7, updated ContextScout)
- CHANGELOG.md (documented all changes)
- VERSION (0.5.5 → 0.6.0)
- package.json (0.5.5 → 0.6.0)

## Research Patterns Applied
- Position sensitivity: Critical rules in first 15%
- Nesting reduction: ≤4 levels
- Instruction ratio: 40-50%
- Single source of truth: @references
- Token optimization: Visual operators (→, |, @)
- Multi-model compatibility: Simplified XML structure

## Breaking Changes
None - 100% backward compatible

## Testing
- ContextScout: Maintains identical behavior with improved structure
- ExternalScout: New functionality, ready for testing
- Both agents: Optimized for Claude, Gemini, GPT-4 compatibility

Closes #[issue-number-if-applicable]

* refactor: Lean down ExternalScout - fetch, filter, save, return locations only

- Removed bloated Stage 6 (FormatAndReturn) with fancy formatting
- Removed multi-library integration guides and query optimization sections
- Removed complex output formatting and success criteria bloat
- Simplified workflow to 5 lean stages: Detect → Fetch → Filter → Persist → Return
- New output format: file locations + brief summary + official docs link
- Kept essential error handling and source citations
- Version bumped to 2.0.0
- Focus: Fast, accurate documentation retrieval without extra bloat

* feat: Add ExternalScout and optimize context system

- Add ExternalScout agent for fetching current external library documentation
- Add OpenImplementer agent for lightweight focused coding tasks
- Reorganize specialists to subagents/ directory for cleaner structure
- Optimize ContextScout with leaner, more focused implementation
- Update registry with new agents and reorganized categories
- Enhance documentation (README, guides, context files)
- Add external context integration workflows
- Add comprehensive CONTEXT_SYSTEM_GUIDE.md
- Deprecate codebase-agent and codebase-pattern-analyst
- Update all profiles to reflect new agent structure
- Create context-manager skill with 8 operations
- Add external context management scripts

BREAKING CHANGES: None (all changes backward compatible)

Fixes: Outdated training data issues for external libraries

* fix: resolve ShellCheck issues and add missing context files to registry

- Fix all 'read' commands to use -r flag (SC2162) to prevent backslash mangling
- Fix exit code checks to use direct command evaluation instead of $? (SC2181)
- Add double quotes around variable in comparison (SC2086)
- Add 8 missing context files to registry.json:
  - external-libraries.md (new workflow for external library handling)
  - visual-development.md
  - development/README.md
  - learning/README.md
  - product/README.md
  - data/README.md
  - mastra-ai/README.md
  - context-bundle-template.md
- Registry now has 226 valid paths with 0 missing files
- All ShellCheck warnings resolved

* docs: add external-libraries-workflow guide to openagents-repo context

- Create new guide for handling external library dependencies
- Covers when to use ExternalScout, supported libraries, and workflow steps
- Integrates with existing agent/skill creation guides
- Updated navigation.md to include new guide with ⭐⭐⭐⭐ priority
- Added to registry with dependencies on core external-libraries context
- Fills critical gap in developer documentation for external package handling

* fix: resolve ShellCheck SC2145 errors in context router

- Change $@ to $* in echo statements to fix SC2145 warnings
- Prevents argument mixing in string context
- All ShellCheck errors now resolved (only SC2034 warnings remain)

* fix: resolve all ShellCheck warnings in manage-external-context.sh

- Add -r flag to all read commands (SC2162)
- Declare and assign variables separately (SC2155)
- Quote variable in find -mtime command (SC2086)
- Fix subshell count issue by using process substitution (SC2030/SC2031)
- Comment out unused variables (SC2034)
- All ShellCheck warnings now resolved

* fix: remove unused variables in context router to pass ShellCheck

- Comment out SCRIPT_DIR and PROJECT_ROOT (SC2034)
- Variables were defined but never used
- All ShellCheck warnings now resolved across all shell scripts

* fix: replace bash registry validation with Python script

- Create fast Python validation script (validate-registry.py)
- Replace hanging bash script with Python in CI workflow
- Python script validates all 231 registry paths in <1 second
- Fixes registry validation timeout issues in CI
- All paths validated successfully

* chore: trigger CI re-run for workflow updates

* Revert "fix: replace bash registry validation with Python script"

This reverts commit 03843935d075f1350afb721b5235e9406005810f.

* fix: remove verbose flag and add timeout to registry validation

- Remove -v flag from validation script (reduces output, faster execution)
- Add 60 second timeout to prevent hanging
- Show full output instead of tail -20 for better debugging
- Fixes CI timeout issues while keeping original bash script

* feat: add TypeScript registry validator with full skill support

- Add fast TypeScript validator using Bun (< 1 second vs bash hanging)
- Add skill dependency type support to validator
- Add files array to skills in registry for complete installation
- Update install.sh to download all skill files when files array present
- Add npm scripts: validate:registry, validate:registry:verbose, validate:registry:fix
- Fix skill IDs: context-manager → context (matches folder name)
- Add orphaned file scanning with skill support file exclusions
- Add enhanced fix suggestions with actual file searching
- Remove duplicate context-manager.md file
- Add comprehensive README for registry validation scripts

Skills now install completely with all supporting files:
- SKILL.md (main definition)
- router.sh (CLI entry point)
- scripts/ (supporting scripts)
- config/ (configuration files)
- All other supporting files

Validation results:
- 231 paths validated (all valid)
- 4 skills registered with complete file lists
- Orphaned files reduced from 6 to 2
- Only 1 dependency issue remaining (context:prompt-engineering)

* fix: use TypeScript validator in CI instead of hanging bash script

- Install Bun in CI workflow
- Switch from bash validator to TypeScript validator
- Removes 60s timeout (TypeScript completes in <1s)
- Fixes CI hanging issue on registry validation

* chore: retrigger CI checks

Empty commit to retrigger CI after workflow fix in PR #129

* fix: use official Bun setup action in CI

- Replace manual Bun installation with oven-sh/setup-bun@v2
- Fixes PATH issue where bun wasn't available in subsequent steps
- Ensures Bun is properly installed before running TypeScript validator

* chore: retrigger CI after Bun setup fix in PR #131

Empty commit to retrigger CI once PR #131 is merged to main

* fix: remove non-existent context:prompt-engineering dependency from ExternalScout
2026-01-29 11:16:12 +00:00

14 KiB
Raw Blame History

Changelog

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

[Unreleased]

Documentation

  • Updated README.md and QUICK_START.md for v0.6.0 accuracy
    • Updated version from 0.1.0-alpha.1 to 0.6.0
    • Added OpenImplementer agent to main agents list
    • 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