Commit graph

2 commits

Author SHA1 Message Date
Darren Hinde
9c7f1c3099
Fix/164 permission key compatibility (#171)
* fix: migrate all agents to OpenCode v1.1.1+ permission (singular) key

Resolves #164

## Changes

### Agent Files (16 files)
- Migrated all agent frontmatter from deprecated `permissions:` (plural) to `permission:` (singular)
- Updated: core agents (OpenCoder, OpenAgent, RepoManager)
- Updated: code subagents (TestEngineer, CoderAgent, BuildAgent, CodeReviewer)
- Updated: core subagents (TaskManager, DocWriter, ExternalScout, ContextScout, ContextManager, Context Retriever)
- Updated: development subagents (DevOpsSpecialist, FrontendSpecialist)
- Updated: system-builder subagents (ContextOrganizer, WorkflowDesigner)

### Context Documentation (3 files)

#### Updated: agent-frontmatter.md
- Fixed field name from `permissions:` to `permission:`
- Updated all examples to use correct singular form
- Corrected "Wrong Field Names" section to show `permissions:` as deprecated
- Updated validation checklist and valid keys list

#### Updated: agent-metadata.md
- Added clarification that `permission` replaces deprecated `permissions`
- Added comprehensive migration guide with before/after examples
- Added validation steps for migration

#### New: permission-patterns.md
- Comprehensive 400+ line permission patterns reference
- Permission evaluation order (last-matching-wins)
- Complete table of valid permission keys
- Agent type patterns (read-only, write-enabled, orchestrators)
- Security patterns (sensitive files, dangerous commands)
- Task permission patterns
- Complete working examples for each agent type
- Validation checklist

## Verification

- ✅ 0 agents using deprecated `permissions:` (plural)
- ✅ 16 agents using correct `permission:` (singular)
- ✅ All permission patterns follow last-matching-wins order
- ✅ Security denials applied consistently
- ✅ Context documentation updated and accurate

## Migration Details

Based on official OpenCode documentation (https://opencode.ai/docs/agents/):
- OpenCode v1.1.1+ uses `permission:` (singular)
- Deprecated: `permissions:` (plural)
- Granular control with last-matching-wins evaluation
- Valid actions: "allow", "ask", "deny"

All agents now comply with OpenCode v1.1.1+ standards.

* fix: correct YAML errors and restore missing permissions in agent configs

- Fix repo-manager.md duplicate permission section
- Fix externalscout.md YAML indentation error
- Remove old tools: section from devops-specialist.md
- Restore context file permissions in context-manager.md
- Restore test command permissions in tester.md
- Clean up formatting in coder-agent.md

All 20 agent files now have valid YAML frontmatter with proper permission blocks.

* fix: standardize permission key across agent files

- Updated all instances of `permissions:` to `permission:` in agent frontmatter for consistency.
- Removed deprecated `write:` and `edit:` sections from externalscout.md.
- Adjusted related documentation to reflect the singular form of permission key.

These changes ensure compliance with OpenCode v1.1.1+ standards and improve YAML structure across the repository.
2026-02-03 22:09:09 +00:00
Darren Hinde
d7a4cb8031
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