Overview

PuaSE is a global orchestration agent designed to handle work that is hard to solve in a single pass: multi-step tasks, cross-domain requests, and jobs that benefit from specialized collaborators.

Its role is straightforward: figure out what is actually being asked, assess how mature the codebase is, and route the work to the right expert agents.

What PuaSE focuses on

At the center of PuaSE is orchestration rather than implementation. It is built around a few key abilities:

<table> <thead> <tr> <th>Capability</th> <th>What it does</th> </tr> </thead> <tbody> <tr> <td>Implicit requirement analysis</td> <td>Uses a five-step method: capture explicit requirements → infer hidden needs → identify constraints → break the work into tasks → set priorities</td> </tr> <tr> <td>Codebase maturity assessment</td> <td>Quickly judges whether a project is in an early, growing, or mature stage, then adjusts strategy accordingly</td> </tr> <tr> <td>Architecture before code</td> <td>No coding before the architecture is understood; no modification before dependencies are mapped clearly</td> </tr> <tr> <td>Expert delegation</td> <td>Hands work to specialized agents such as architect, code-reviewer, cpp-developer, documenter, explore, general, java-developer, mysql-dba, oracle-dba, python-developer, security-expert, and quality-inspector</td> </tr> <tr> <td>Result synthesis</td> <td>Combines outputs from multiple agents in dependency order, with conflict detection and arbitration</td> </tr> <tr> <td>Failure handling</td> <td>Retries model failures automatically with exponential backoff, falls back to self-execution when an agent times out, detects delegation loops, and protects the critical path</td> </tr> </tbody> </table>

The overall idea is simple: let one coordinator understand the full task, then let specialists handle the parts they are best suited for.

Repository layout

The project is organized around one top-level orchestrator and a set of sub-agents:

├── PuaSE.md                 # 全局编排 Agent（主入口）
├── AGENTS.md                # 仓库规则与约定
├── subagent/                # 子 Agent 定义
│   ├── architect.md         # 架构分析
│   ├── code-reviewer.md     # 代码审查
│   ├── documenter.md        # 文档编写
│   ├── developer/
│   │   ├── cpp-developer.md     # C/C++ 开发
│   │   ├── java-developer.md    # Java 开发
│   │   └── python-developer.md  # Python 开发
│   ├── dba/
│   │   ├── mysql-dba.md        # MySQL 数据库管理
│   │   └── oracle-dba.md       # Oracle 数据库管理
│   ├── quality-inspector.md # 质量巡检
│   └── security/
│       └── security-expert.md # 安全审计
├── .gitignore
└── README.md

Agent roles

Each agent has a clearly scoped responsibility:

<table> <thead> <tr> <th>Agent</th> <th>Responsibility</th> </tr> </thead> <tbody> <tr> <td>PuaSE</td> <td>Global orchestration — requirement analysis, maturity evaluation, and expert delegation</td> </tr> <tr> <td>architect</td> <td>Architecture analysis — directory structure, module dependencies, data flow, and design patterns</td> </tr> <tr> <td>code-reviewer</td> <td>Code review — plan alignment, code quality, and architectural compliance</td> </tr> <tr> <td>java-developer</td> <td>Java development — implementation, compilation, and test validation</td> </tr> <tr> <td>python-developer</td> <td>Python development — implementation, syntax checking, and test validation</td> </tr> <tr> <td>cpp-developer</td> <td>C/C++ development — implementation, compilation, and test validation</td> </tr> <tr> <td>mysql-dba</td> <td>MySQL administration — installation, configuration, tuning, backup and recovery, and high availability</td> </tr> <tr> <td>oracle-dba</td> <td>Oracle administration — installation, configuration, tuning, backup and recovery, and high availability</td> </tr> <tr> <td>security-expert</td> <td>Security auditing — 17 security dimensions covering OWASP Top 10, CWE, memory safety, and more</td> </tr> <tr> <td>documenter</td> <td>Documentation — README files, API docs, design docs, and usage guides</td> </tr> <tr> <td>quality-inspector</td> <td>Quality inspection — reviews deliverables from architect, all developers (developer/*), all DBAs (dba/*), and documenter; rejects work that does not meet standards and sends it back for rework</td> </tr> </tbody> </table>

Installation

1. Install OpenCode

Choose the method that matches your platform:

YOLO（推荐，macOS / Linux）

curl -fsSL https://opencode.ai/install | bash

macOS / Linux（Homebrew，自动更新）

brew install anomalyco/tap/opencode

macOS / Linux（Homebrew 官方仓库，更新较慢）

brew install opencode

Arch Linux

sudo pacman -S opencode   # 稳定版
paru -S opencode-bin      # AUR 最新版

Windows

scoop install opencode           # Scoop
choco install opencode           # Chocolatey

任意平台（npm）

npm i -g opencode-ai@latest

Before installing, make sure any legacy version earlier than 0.1.x has been removed.

To verify the installation:

opencode --version

2. Install the PuaSE agent

Place the agent configuration into OpenCode’s agent directory.

macOS / Linux

# 推荐：创建符号链接（同步更新，自动生效）
ln -sf "$PWD" "$HOME/.config/opencode/agents/PuaSE"

# 或手动复制（如需独立副本）
cp -r . "$HOME/.config/opencode/agents/PuaSE/"

Windows（PowerShell）

# 推荐：创建目录联结（同步更新，自动生效）
New-Item -ItemType Junction -Path "$env:USERPROFILE\.config\opencode\agents\PuaSE" -Target "$pwd"

# 或手动复制（如需独立副本）
Copy-Item -Recurse -Path ".\*" -Destination "$env:USERPROFILE\.config\opencode\agents\PuaSE\"

A symbolic link or junction is the preferred option because updates to the working directory are reflected automatically.

3. Configure opencode.json

Find or create opencode.json under the OpenCode config directory (~/.config/opencode/) and add the PuaSE registration entry:

{
  "agent": {
    "PuaSE": {
      "description": "全局编排 Agent，解析隐含需求、评估代码库成熟度、委派给专家 Agent。适用于复杂多步骤任务、跨领域问题、需要多人协作的场景。",
      "prompt": "C:\\Users\\<用户名>\\.config\\opencode\\agents\\PuaSE\\PuaSE.md",
      "permission": {
        "*": "allow"
      }
    }
  }
}

Replace the prompt value with the real path on your system. For macOS or Linux, an example path would be:

"/home/<用户名>/.config/opencode/agents/PuaSE/PuaSE.md"

If you are using a symbolic link or a directory junction, the path can point to the linked target location.

Field meanings:

<table> <thead> <tr> <th>Field</th> <th>Meaning</th> </tr> </thead> <tbody> <tr> <td>PuaSE</td> <td>The agent name used inside OpenCode as @PuaSE</td> </tr> <tr> <td>description</td> <td>The agent description used by OpenCode for task matching</td> </tr> <tr> <td>prompt</td> <td>Path to the PuaSE.md configuration file, including YAML frontmatter and workflow definition</td> </tr> <tr> <td>permission</td> <td>Permission settings; "*": "allow" means all operations are allowed</td> </tr> </tbody> </table>

Restart OpenCode after saving the configuration.

4. Verify the setup

Start an OpenCode session in any project directory:

opencode

PuaSE should now be available as the global orchestrator. To test it, enter:

帮我分析这个项目的架构

If it responds by starting an architecture analysis task, the installation is working.

Quick usage examples

PuaSE routes requests according to intent. Typical examples include:

• 帮我分析这个项目的架构 → delegates to the architect agent
• 开发一个新的 Java 功能 → delegates to java-developer
• 修复 Java 代码中的 bug → delegates to java-developer
• 写一个 Python 脚本 → delegates to python-developer
• 编写 C/C++ 程序 → delegates to cpp-developer
• 配置和优化 MySQL 数据库 → delegates to mysql-dba
• 配置和优化 Oracle 数据库 → delegates to oracle-dba
• 重构整个模块 → architecture analysis → refactoring → code review
• 审计代码安全 → delegates to security-expert
• 多步骤质量巡检 → each sub-agent deliverable is checked by quality-inspector
• 给这个项目写文档 → delegates to documenter to create or update documentation

This makes PuaSE most useful when the task is larger than a single coding prompt: when architecture, implementation, review, security, database work, and documentation may all need to happen in a controlled order.

License

MIT