agency-agents Deep Dive: Separate Development, Verification, and Operations by Role

In one sentence

agency-agents is an open source collection of role definitions, workflows, and deliverable expectations for development, design, testing, marketing, and operations, with installation paths for supported coding tools.

Repository: msitarzewski/agency-agents

A developer, a designer, and an operator read the same feature differently. They look for implementation details, user journeys, and failure handling. A solo builder often has to explain each perspective to an agent repeatedly. agency-agents is worth exploring when you want a documented starting point for what each role should inspect and deliver.

Our earlier Superpowers deep dive connected stages of development, while Everything Claude Code introduced skills, rules, and hooks for configuring the working environment. With agency-agents, focus on who reviews an outcome and from which perspective. It also connects to the requirements work in mattpocock/skills, but role responsibilities and deliverables are the starting point here.

We suggest trying a small feature where two roles meet. A booking screen and its storage API, or a completed contact form reviewed as a user journey, make useful candidates. Follow what each role sees in the same requirement and what it passes to the next person. Begin with a small set of roles so those handoffs are easy to read.

What can you do with it?

The repository contains role documents across engineering, design, product, project management, testing, security, support, and other domains. Each file includes a name and description, mission, standards, workflow, and example deliverables. You can read a document as reference, adapt it to team guidance, or install it into a supported coding tool.

Frontend Developer covers UI implementation, accessibility, performance, and API integration. Backend Architect covers data structures, API contracts, error responses, and reliability. Applying these perspectives to the same feature helps separate visible UI states from server guarantees. Read the actual responsibilities inside the file to decide whether the role fits the work.

In testing, Evidence Collector and Reality Checker are useful documents to compare. The former connects specifications to reproducible evidence, while the latter cross-checks previous assessments and examines complete user journeys. Their language and judgment criteria differ, so compare each document with your team's acceptance rules before installing it.

There are perspectives outside development too. Paid Media Auditor covers account structure, measurement, budgets, and creative. Tracking & Measurement Specialist covers event design, conversion measurement, duplicate counting, and consent signals. Real data connections need separate preparation, but the documents can also help organize questions and required inputs before access is available.

These files are instructions for a model. References to experience, memory, and success metrics inside a persona do not establish a person's credentials or measured results. The host tool and surrounding configuration determine available tools, persistence between sessions, and concurrent execution. Understanding that scope makes it easier to choose the execution environment you need.

When browsing the official roster, choose a task and a handoff artifact together. A screen change accompanied by error states and API input conditions is easier to review than a broad request to build a screen. Keep decisions that require a human owner alongside the proposed output.

Installation and a first conversation

The README offers a desktop app, script-based installation, and use of individual documents as reference. For a terminal-based start, obtain a local copy of the repository and follow the official installation instructions from its root directory. The model and coding tool are separate prerequisites.

Claude Code can use the original Markdown role files without conversion. The following full-install command appears in the Claude Code integration instructions. Review the installer and compare existing role filenames first to identify overlap.

./scripts/install.sh --tool claude-code

If you need a smaller selection, the README also supports installing chosen divisions. Its example below selects engineering and security. Choose the full or selective path according to the work. Claude Code installation copies role files into the user directory at ~/.claude/agents/.

./scripts/install.sh --tool claude-code --division engineering,security

For other tools, the conversion script prepares the integration files before installation. The README includes this selective Cursor example for frontend development and UI design. Read the corresponding integration section because installation locations and role-loading behavior vary by host.

./scripts/convert.sh
./scripts/install.sh --tool cursor --agent frontend-developer,ui-designer

The README also includes a team listing and an OpenCode dry-run example. The second command targets OpenCode; it is an optional example for inspecting a target and scope, rather than a required follow-up to a Claude Code installation.

./scripts/install.sh --list teams
./scripts/install.sh --tool opencode --division engineering --dry-run

The Claude Code integration document demonstrates requesting a role by name. For a first session, ask Frontend Developer to inspect a small UI task. The following illustrative conversation applies that approach to booking. Establish whether the installed role is available and whether its answer stays within the requested task.

Use the Frontend Developer role to inspect the booking screen.
Follow the existing components and design rules.
Describe available, fully booked, and request-failure states.
Before editing, list the related files and conditions needed from the API.

If the result expands too far, examine whether it is applying every responsibility in the role document to this one task. A small screen change may not need a new design system or framework migration. Project requirements define the stack, scope, and decisions to leave alone. Adapting general role guidance to the current repository is part of the first session.

Scenario 1: Align a booking screen with its API contract

Suppose users need to view available slots, choose one, and submit a booking. Frontend Developer can examine UI states, input, and accessibility. Backend Architect can examine time data, request shape, and failures. The official README's startup MVP scenario also combines frontend and backend roles. For a small feature, begin with the contract where their work meets.

Ask the screen role to identify the states a user passes through. Loading slots, finding none available, and submitting a request call for different feedback. The Frontend Developer document covers API integration, state management, error feedback, and accessibility. Here is an illustrative request applying that perspective to booking.

Describe the states and actions for choosing a booking slot.
Follow the existing UI structure and keyboard interaction patterns.
Separate loading, empty results, selection, and submission failure.
List the API inputs and responses required for each state.
Leave server-side policy decisions unresolved where necessary.

Next, pass the same requirement and the UI questions to the server role. The Backend Architect document covers API contracts, consistent errors, retries, and idempotency. That perspective can help examine a slot becoming unavailable or a repeated request using the product's existing data model.

Use Backend Architect to review the booking request contract.
Use the UI state outline and the existing API and data structure as evidence.
Propose conditions for slot identifiers, unavailable slots, and duplicate requests.
Separate the smallest feasible change from additional product decisions.
Return response examples and verification conditions for the frontend role.

The useful output is a set of conditions to agree on. If the screen proposes sending a time string while the server expects a slot identifier, resolve the discrepancy first. If the API returns an unavailable-slot error and the UI has no corresponding state, connect them. The person combining the outputs needs to read these boundaries.

Time zones and duplicate requests can introduce product-policy decisions. A specialized role name does not authorize the agent to invent policy. Follow existing product documents and leave missing conditions as questions. Then trace agreed conditions into requests, responses, and tests.

Define file ownership before implementation too. If both roles freely modify the API and components, it becomes harder to track why a change happened. Agree on inputs and responses, then retain file scope and verification with each task. The host tool and team process determine how workspaces and concurrent work are managed.

One person can use both roles sequentially. Inspect screen states, review the output from the server perspective, and return to the agreed contract. Look at the information passed between roles. A first pilot can concentrate on following the contract end to end before exploring parallel execution.

The benefit is a more concrete set of review questions. The screen role explains visible states; the server role explains the conditions that support them. When both connect to the same requirement, a reviewer can identify mismatched assumptions before implementation. Read how the questions change when the perspective changes.

Scenario 2: Review completion using reproducible evidence

Once the booking screen exists, the question moves from whether a screen appears to whether a user can finish a booking. Evidence Collector connects requirements to actual results and distinguishes visual evidence from behavioral evidence. A screenshot of completed inputs does not establish that the booking was saved, making this perspective useful even for small web features.

Begin by defining the requirements and test environment. The Evidence Collector document asks for reproducible findings, explicit untested scope, and no added requirements. Apply that to a normal booking, an unavailable-slot response, and retrying after failure.

Use Evidence Collector to compare the approved booking requirements with the build.
Use only the test environment and synthetic inputs.
Connect visual states to images and submission outcomes to responses,
persistence results, or other evidence that establishes the behavior.
For each issue, include reproduction steps, expected behavior,
actual behavior, and evidence location.
Separate unavailable tests from reproducible product defects.

Compare the document's example commands with your repository before using them. Some testing roles assume particular script names, paths, and local ports. Establish whether those files exist and connect the procedure to the team's actual test tools. Installing a role file does not prepare every script or environment shown in its examples.

Read each claim against appropriate evidence. An image of an unavailable slot helps review the feedback presented to a user. Server rejection needs behavioral evidence such as a response and storage outcome. Conversely, a failed-request log does not show that the user could read an error message. Keeping both types of evidence reveals gaps more clearly.

The Reality Checker document proposes a role that cross-checks previous review against implementation and considers complete journeys and readiness. It includes conservative verdict language and example criteria. Define the team's final decision around approved requirements and execution evidence, rather than adopting a fixed score or number of revision cycles.

Use Reality Checker to examine the booking review evidence again.
Connect the journey from screen entry through selection to the final outcome.
Identify claims in the earlier report that lack sufficient support.
Separate additional checks needed from defects already reproduced.
List outstanding items for the team's release approval process.

If you use both review roles, give each a distinct responsibility. The first can reproduce behavior and organize evidence; the second can map that evidence to requirements and remaining scope. This creates clearer questions than asking for the same review twice. A model responding under a different role name does not by itself establish fully independent verification.

When reports disagree, compare evidence before preferring the stricter tone. One reviewer may lack access to the environment, or they may have inspected different versions. Establish that both reviewed the same change and requirements. A defect should produce a reproducible correction request; missing evidence should produce a specific additional check.

These role documents provide a starting format for review. A team that reports completion inconsistently can use reproduction steps, outcomes, and evidence locations to make handoffs clearer. In the first pilot, ask whether the next person can reproduce a finding, rather than counting how many issues a role reports.

Scenario 3: Separate an advertising audit from measurement investigation

When taking over an advertising account, reported conversions may differ from actual inquiries. That discrepancy makes budget changes hard to justify. The official README's account-takeover scenario separates auditing, measurement, strategy, creative, and reporting. A smaller team can begin by comparing Paid Media Auditor with Tracking & Measurement Specialist.

The Paid Media Auditor document organizes work across account structure, measurement, bidding and budget, targeting, creative, and landing pages. Choose the relevant scope and provide read-only inputs. This can help determine which evidence is needed before considering any live account changes.

Use Paid Media Auditor to prepare a review plan for a newly inherited account.
Limit the scope to campaign structure, conversion settings, and landing pages.
Use only the anonymized reports and configuration descriptions provided.
Separate observations, possible explanations, and additional data needed.
Do not change budgets or settings. Prioritize the items to inspect first.

If the output points toward a conversion-counting issue, narrow the next question for the measurement role. The Tracking & Measurement Specialist document covers tag management, GA4 events, advertising conversions, browser/server deduplication, and consent verification. Distinguish an environment with connected tools from one where the role can only read supplied reports.

Use Tracking & Measurement Specialist to investigate conversion-count differences.
I will provide a measurement plan, test events, and anonymized aggregate reports.
First align the meanings of form submission, qualified inquiry, and ad conversion.
Propose an investigation order for duplicate events, missing events,
and differences in reporting periods.
Exclude account writes and access to real customer records from this task.

Begin with definitions. A button click, a saved form, and an inquiry accepted by a sales team are different events. Reporting windows and classification rules can also differ between platforms. Use the role's review framework while narrowing the actual cause through the supplied configuration and test evidence.

Where tags and events are available, trace how a single synthetic submission is recorded. If browser and server events coexist, examine their deduplication method. Inspect what changes with consent state as appropriate to the approved scope. These questions follow the document's measurement and debugging remit; conditions still need to reflect the organization's data policy and actual service settings.

Treat the role document's target metrics and performance language as persona guidance. They do not establish expected gains for the current account. Account size, inputs, and operating history affect the judgment, and improvement claims require execution and measurement. A first output should make candidate problems, evidence needs, and proposed decisions clear.

Connecting an API or MCP service requires separate decisions about permissions, query scope, and data destinations. A tool name in a role file does not grant access. Keep credentials in the connection environment and remove account identifiers and customer information from shared reports. Retain only the configuration and aggregates necessary for review.

Having development and operations perspectives in one collection is useful to explore. You can review a booking's successful submission and then examine how it becomes an inquiry in reporting. Keep each review's evidence and approval scope visible so the next person understands its basis. As you add roles, design their inputs and handoffs too.

Read the handoffs in the official example

The repository's Nexus Spatial Discovery Exercise is an official example of several roles examining a product opportunity. It combines market, technical architecture, brand, customer support, UX, and execution perspectives. Read the individual outputs and synthesis to see what information moves between roles.

Treat it as a product discovery exercise. Its market sizes and competitive assessments require their own verification before becoming business evidence. The useful reading focus here is how different conclusions are assembled. Look for whether conflicting assumptions are surfaced or left for another decision.

A small team does not need to reproduce the same roster. Start with a role examining the user's problem and another examining implementation feasibility. Define the input each needs, collect conflicting conditions, and name the decision owner. The example is useful for understanding connections between outputs at whatever scale fits the work.

The README also includes startup MVP, enterprise feature, and advertising takeover combinations. Choose the closest bottleneck and retain only the relevant roles. Compare Superpowers when you need a more explicit development sequence, or ECC when you need rules and verification attached to the environment. Thinking about roles, procedures, and execution separately helps identify overlapping instructions.

Which teams should consider it?

Strengths: agency-agents is worth exploring for builders moving between development, design, testing, and operations, or teams organizing several reviewers' perspectives. The documents provide a starting point for specific missions and deliverables, with selective installation. Role-specific examples are especially useful when deciding what to pass to the next person.

Operating effort: Someone needs to read the documents and adapt them to the existing stack and team policy. General responsibilities, example commands, and target metrics may need adjustment for the task. More roles bring more model calls and outputs to review, along with potentially conflicting proposals. Start with two roles and one handoff artifact.

Execution environment: The collection and the host tool serve different responsibilities. File access, command execution, service connections, persistent memory, and concurrency are controlled by the tool and environment. When moving between hosts, inspect conversion output and installation locations, then establish available behavior. Also consider how roles installed in a shared user directory affect other projects.

License and responsibility: agency-agents is MIT licensed. Review the license conditions when modifying or redistributing it and the separate terms for host tools and model services. Specialized role names do not transfer organizational approval responsibilities. Connect code and account changes to the review process of their existing owners.

Sources and further reading

Wrapping up

The Hypemarc Builder Community will keep sharing the AI tools and open source projects we explore. We'll continue gathering useful resources to share with fellow builders.

Open chat: AI Builders
Adoption advice and inquiries: Contact form
Get the next post: Blog RSS · AI resource library