Agency: Building a Near-Autonomous AI Programming Agent Workflow

This article introduces the srid/agency project, an innovative solution that packages AI programming agent workflows into an APM package, enabling a fully automated pipeline from research to PR via commands like /do and /talk.

Agency is a near-autonomous workflow framework designed for coding agents, distributed as an APM package. It defines a set of standardized commands and processes that enable AI agents to independently complete complex development tasks under human supervision. The core philosophy of the project is to encode best practices into automatically executable processes while retaining human intervention capabilities at key decision points. This "hands-off but controllable" model represents a new paradigm for AI-assisted development.

Agency is built around two main commands:

This is Agency's flagship feature. After executing the /do command, the AI agent will automatically complete the following full process:

1. Research: Analyze requirements and explore implementation solutions
2. Architecture Evaluation (Hickey): Evaluate structural simplicity using Rich Hickey's "Simple Made Easy" framework
3. Module Decomposition Review (Lowy): Check if module boundaries encapsulate axes of change based on Juval Lowy's framework
4. Branch Creation: Create feature branches in version control
5. Code Implementation: Write code based on research conclusions
6. Quality Check (Code Police): Three-stage quality gate—rule checking, fact verification, and elegance review
7. CI Validation: Run continuous integration processes
8. PR Generation (Forge PR): Write PR titles and descriptions that developers actually want to read

The entire process requires no human intervention until the final PR review stage.

Unlike /do, /talk is a pure conversation mode. The agent can discuss ideas, explore solutions, and read code, but is not allowed to modify files. This is suitable for scenarios such as requirement clarification, architecture discussion, and code review, allowing developers to think thoroughly before starting to code.

A key design decision of Agency is to decompose complex tasks into specialized sub-agents instead of executing them serially in a single conversation loop. This architecture brings significant advantages:

Based on Rich Hickey's famous talk "Simple Made Easy" as the theoretical foundation, the hickey sub-agent is specifically responsible for identifying accidental complexity in code. It checks:

• Whether there is unnecessary coupling (complecting)
• Whether module responsibilities are clearly separated
• Whether there are simpler alternatives

Importantly, hickey runs as an independent sub-agent and can execute in parallel with lowy, without needing to wait serially in the main conversation loop.

The lowy sub-agent is based on Juval Lowy's "Righting Software" framework (inherited from Parnas' 1972 modularity standards) and checks whether module boundaries encapsulate axes of change rather than just functions. The core question is: When requirements change, which modules need to be modified? Ideally, changes should be isolated within the smallest possible range of modules.