a0_software_orchestrator/README.md

# A0 Software Orchestrator

## v11 status

This package is aligned back to standard Agent Zero plugin surfaces: `plugin.yaml`, `.toggle-1`, `tools/`, `prompts/agent.system.tool.*.md`, `api/`, `extensions/`, `webui/`, and plugin-local `helpers/`.

Runtime classes use Agent Zero framework bases directly:

- Tools: `from helpers.tool import Tool, Response`
- API handlers: `from helpers.api import ApiHandler, Request, Response`
- Extensions: `from helpers.extension import Extension`

Run local package checks from the plugin root:

```bash
python execute.py --self-test
python scripts/test_all_tools.py
python scripts/security_prompt_lint.py
```

After installation under `/a0/usr/plugins/a0_software_orchestrator/` and Agent Zero restart, first runtime check:

```json
{"tool_name":"orchestrator_self_check","tool_args":{"action":"summary"}}
```

---

# A0 Software Orchestrator

Core-first software project orchestration plugin for Agent Zero.

## Overview

The A0 Software Orchestrator is a manager-agent that guides software projects from initial user dialogue to deployable, documented, and recoverable state. It enforces Plan Mode, delegates to hidden specialist subagents, tracks project state in repository artifacts, and ensures quality gates before release.

## Features (v0.1 Core)

- **Manager Agent**: `a0_software_orchestrator` – the only user-facing agent
- **9 Specialist Subagents**: codebase_explorer, requirements_analyst, solution_architect, ui_design_specialist, implementation_engineer, test_debug_engineer, runtime_devops_engineer, security_data_engineer, release_auditor
- **15 Lifecycle Skills**: software-intake through release-audit
- **Plan Mode**: planning_only → implementation_allowed → runtime_verification_allowed → deployment_preparation_allowed → release_handoff_allowed
- **Model Routing**: Per-role model preset configuration
- **Tool Governance**: External tool capability detection and fallback handling
- **Context Budgeting**: Token estimation, warning thresholds, forced compaction
- **Session Recovery**: Resume files and snapshots
- **Project Memory**: Git-based repository artifacts (`.a0/` directory)
- **Self-Test**: Structure validation, roundtrip test, health/reachability test

## Installation

This plugin is built for local use in `/a0/usr/plugins/a0_software_orchestrator/`.

## Usage

```bash
# Run self-test
python execute.py --self-test

# Initialize a new project
python execute.py --init /path/to/project
```

## External Tools

The orchestrator manages these external tools (when available):
- **Forgejo** – Git hosting
- **Coolify** – Deployment platform
- **Terminal** – Command execution (required)
- **Browser/UI smoke** – opt-in only; public/non-authenticated checks after explicit user approval; never for login or credential discovery
- **Git** – Version control
- **Docker** – Container management

## Configuration

Edit `default_config.yaml` or use the WebUI settings panel to configure:
- Model routing presets per role
- Autonomy level (low/balanced/high)
- External tool availability
- Advanced packs (security deep audit, Coolify deep handoff, etc.)

## Advanced Packs (v0.2+)

Optional features that can be enabled in config:
- Security/Data Deep Audit
- Coolify Deep Handoff
- Operations Deep Readiness
- Extended Permission Governance
- Full Evaluation Harness

## License

MIT License – See LICENSE file for details.

## Version

0.1.0 – Core-first release


## Agent Zero runtime contract (v10)

This plugin follows the Agent Zero plugin contract:

- installed under `/a0/usr/plugins/a0_software_orchestrator/`
- `plugin.yaml` is runtime manifest metadata, not a custom tool registry
- executable tools live in `tools/<tool_name>.py`
- tool prompt docs live in `prompts/agent.system.tool.<tool_name>.md`
- plugin-local Python helpers live in `helpers/` and are imported through `usr.plugins.a0_software_orchestrator.helpers...`
- tool classes import `Tool` and `Response` directly from `helpers.tool`
- no `sys.path` mutation is used for runtime loading
- plugin cache is refreshed by Agent Zero restart or the official plugin API/UI, not by WebUI login workflows

Framework/plugin diagnostics must run inside the Agent Zero framework runtime. Do not treat `/opt/venv` execution-runtime import failures as plugin loader failures.


## v10 notes

- `execute.py` now includes security prompt lint.
- `orchestrator_self_check` reports scoped `.toggle-0` leftovers under `/a0/usr/agents` and `/a0/usr/projects`.
- Browser/UI smoke remains opt-in and never performs login/auth without an explicit user-provided test account.