699b2d7769
* ci(security): run deterministic eval tests in affected-area CI (Task 04) The build-check job validated build + suite structure but never ran the tests, and its summary referenced a `test:ci` script that did not exist. Make affected-area CI meaningful: - Add `test:ci` to evals/framework running the offline, deterministic Vitest allowlist (7 files / 112 tests) — no model, network, or paid execution. - Add a required "Run deterministic tests" step to build-check; a failure fails the job and the existing PR summary gate (which keys on build-check.result) fails closed. - Correct the summary note to state test:ci runs the deterministic allowlist and that model/network agent suites are excluded on PRs. The broader deterministic suite has 3 pre-existing failing files (framework-confidence, logger, test-runner; confirmed failing before this work) which are intentionally out of the allowlist and tracked separately. Validated locally: build, validate:suites:all, and test:ci all exit 0. * ci(security): least privilege permissions + pin actions to SHAs (Task 05) Harden all 9 GitHub Actions workflows: Least privilege: - Add explicit top-level `permissions: contents: read` to installer-checks, validate-test-suites, and opencode (opencode's job keeps the writes it needs; the top level now defaults to read). - Every workflow now declares an explicit top-level permissions block. - Write scopes retained only where justified (releases, doc/registry commits, follow-up PRs, and sync-docs' issues.create). Immutable action pinning: - Pin every `uses:` to a full 40-char commit SHA with a version comment, including first-party actions/* (checkout, github-script, setup-node, upload-artifact) and third-party (oven-sh/setup-bun). - Replace the two mutable refs that could change under us at any push: ludeeus/action-shellcheck@master and sst/opencode/github@latest. Record all SHAs, versions, and permission justifications in docs/maintenance/repository-recovery/action-pin-inventory.md. Verified: all 9 workflows parse as valid YAML; no floating tag/branch refs remain; every workflow has a top-level permissions block. * docs(security): add SECURITY.md and private-reporting checklist (Task 06) - Add root SECURITY.md: supported versions (0.7.x), private reporting via GitHub's "Report a vulnerability", best-effort response expectations, coordinated disclosure, and no-secret guidance. - Add private-vulnerability-reporting checklist that separates repository file work (this PR) from GitHub settings changes that require their own approval (Task 07: enabling private vulnerability reporting). No external links to validate; the reporting path uses the repo Security tab. SECURITY.md documents the private reporting path ahead of Task 07 enabling it. * ci(security): add dependency governance and ownership controls (Task 08) - .github/dependabot.yml: weekly grouped github-actions updates (keeps the Task 05 SHA pins current). Scoped to actions only — the primary lockfile is bun.lock and Dependabot's npm ecosystem would desync it; npm dependency risk is covered by dependency-review below. - .github/workflows/dependency-review.yml: runs on PRs with contents: read, SHA-pinned actions, fail-on-severity: high to block newly introduced high-severity vulnerabilities (exceptions documented inline). - .github/CODEOWNERS: default owner @darrenhinde with explicit ownership of security-sensitive paths (workflows, dependabot, CODEOWNERS, SECURITY.md, scripts/validation). Verified: dependabot.yml and dependency-review.yml are valid YAML; dependency-review actions are SHA-pinned with contents: read; CODEOWNERS owner is the repository owner. * docs(security): record GitHub security settings evidence (Task 07) Enable private vulnerability reporting and record read-back evidence. Settings changed (each approved immediately before, verified by read-back): - Private vulnerability reporting: enabled=false -> enabled=true. The Security tab now offers "Report a vulnerability", making the path documented in SECURITY.md live. - Dependency Graph / Dependabot alerts: 404 -> 204. This was an undocumented prerequisite of Task 08's dependency-review.yml, which failed with "Dependency graph is not enabled"; the Dependency Review check on PR #336 went fail -> pass after enabling it. No other repository setting was modified; secret scanning and push protection are unchanged, and dependabot_security_updates remains disabled (out of scope, would need its own approval). Both changes are reversible via the corresponding DELETE calls. Marks Part B of the private-vulnerability-reporting checklist complete. |
||
|---|---|---|
| .. | ||
| agents | ||
| contributing | ||
| features | ||
| getting-started | ||
| github | ||
| guides | ||
| images | ||
| maintenance | ||
| model-providers/oss | ||
| planning | ||
| README.md | ||
OpenAgents Control Documentation
Welcome to the OpenAgents Control documentation! This directory contains all documentation organized by topic.
📚 Documentation Index
Getting Started
- Installation Guide - Complete installation guide with collision handling
- Collision Handling - Quick reference for install script collision strategies
Features
- System Builder - Build complete AI systems tailored to your domain
- Quick Start - Get started with the system builder
- Complete Guide - Detailed documentation and examples
- Agent System Blueprint - Architecture patterns and how to extend the system
Contributing
- Contributing Guide - How to contribute to the project
- Code of Conduct - Community guidelines
GitHub
- GitHub Settings - Repository settings checklist
🚀 Quick Links
For New Users
- Start with the main README in the repository root
- Follow the Installation Guide
- Use
opencode --agent OpenAgentto start building - Read the OpenAgent Guide to understand the workflow
For Contributors
- Read the Contributing Guide
- Review the Code of Conduct
- Check out good first issues
For Advanced Users
- Study the Agent System Blueprint
- Try the System Builder
- Create custom agents and commands
📖 Documentation Structure
docs/
├── README.md # This file
├── getting-started/
│ ├── installation.md # Installation guide
│ └── collision-handling.md # Collision handling reference
├── features/
│ ├── system-builder/
│ │ ├── README.md # System builder quick start
│ │ └── guide.md # System builder complete guide
│ └── agent-system-blueprint.md # Architecture patterns
├── contributing/
│ ├── CODE_OF_CONDUCT.md # Community guidelines
│ └── CONTRIBUTING.md # Contribution guide
└── github/
└── GITHUB_SETTINGS.md # Repository settings
🔍 Finding What You Need
I want to...
...install OpenAgents Control → Installation Guide
...understand collision handling → Collision Handling
...build a custom AI system → System Builder
...understand the architecture → Agent System Blueprint
...contribute to the project → Contributing Guide
...report a bug or request a feature → GitHub Issues
💡 Additional Resources
- Main README: ../README.md - Complete overview and quick start
- CHANGELOG: ../CHANGELOG.md - Version history and updates
- GitHub Repository: https://github.com/darrenhinde/OpenAgentsControl
- OpenCode CLI Docs: https://opencode.ai/docs
- Component Registry: ../registry.json
📌 Current Version
v0.6.0 (January 28, 2026)
Latest updates:
- ExternalScout subagent for fetching live library documentation (18+ libraries)
- Enhanced ContextScout with multi-model optimization
- Complete command and agent documentation
- Simplified agent architecture (OpenAgent + OpenCoder)
🤝 Community
- Issues: Report bugs or request features
- Discussions: Ask questions and share ideas
- Pull Requests: Contribute code
📝 License
This project is licensed under the MIT License. See LICENSE for details.
Need help? Check the Contributing Guide or open an issue.