AI helps write code, but a team still needs to understand what changed, whether the result meets the requirements, and who can accept it. As agents handle more tasks, those connections matter more. Preparing changes may get faster while review and coordination remain manual work.
CodeGraph digital employees organize work around familiar team roles, from investigating a user problem to implementation, security review and release. Each role has a task, permissions, an expected result and its own verdict. The team can see who received the work, which checks ran and what is still missing for acceptance.
Codex or another compatible agent performs the actions of these roles. CodeGraph connects them to requirements, code and evidence. People set the goal, access and decisions that need approval before delegation. A handoff assigns the next owner. Automated execution starts through the configured execution workflow, and its progress appears in the run status.
Why divide work between roles?
A developer looks at a task through the code change. An architect checks component boundaries, a security reviewer checks threats and data, and QA checks observable behavior. Separating these questions helps reveal gaps that the author of a change might miss.
CodeGraph keeps implementation results separate from reviewer verdicts. An orchestration report shows task readiness and links to the original checks. The team can distinguish a prepared change from verified acceptance and return to the evidence behind a decision. A manager can understand progress without reconstructing the entire conversation. An engineer can continue from a known revision and saved results.
Example: change an access rule
Consider a teaching example: only an administrator should be able to change a service limit. Сергей defines the allowed roles and denial behavior. Анна connects the work to acceptance criteria. Дмитрий prepares the change and tests, while Рита examines affected dependencies.
Вера investigates ways to bypass authorization. Лена checks both permitted and denied calls. Борис updates the instructions, and Иван connects the results to the requirement. If the task includes a release, Глеб checks the environment and rollback procedure. Ева reconciles resource use before closure.
Лена records the result of the permitted call, and Вера records the authorization-bypass check. CodeGraph links both results to the change. The task status shows completed checks and each role’s current work. Each participant receives a specific review question and keeps the result linked to the change.
What the team receives
- Product: a connection between the user outcome, requirements and acceptance.
- Development: a bounded task, change context and a clear handoff.
- Reviewers: their own responsibility and evidence for the exact revision.
- Management: completed results, open questions and resource use within one task.
Start with the scenario guide to choose the first task. The analysis capability map explains which code questions you can investigate; the FAQ covers connections and application boundaries.
Choose a first task
Start with a task whose result your team can check: a known defect, a change to one rule, or a question about a specific part of the code. Specify the repository, revision and expected outcome. This lets you see how roles use shared context and hand work from definition to review.
| Team task | What to provide | What to check in the result |
|---|---|---|
| Fix a known defect | Current behavior, expected outcome and affected code. | The change, a reproduction test and reviewer verdicts for the same revision. |
| Understand code before changing it | A question, starting component and investigation scope. | An explanation linked to code, dependencies and conclusions about the affected area. |
| Prepare a release | The changes, target environment and acceptance criteria. | A readiness report linked to checks, open questions and a rollback plan. |
After the first task, review how much context you had to reconstruct manually, how easily you can find the basis for each conclusion and whether the next owner is clear. Use those observations to choose the team’s next tasks.
Mental model
A normal delivery has four layers:
- a product requirement in OpenSpec and its linked story or service task;
- a task capsule defining scope, acceptance criteria, owner, and handoffs;
- role evidence for implementation, review, security, QA, docs, traceability, runtime, and cost;
- an authoritative closure decision after all required evidence is present.
In an installed client, use the role skills shipped in the CodeGraph plugin and the
connections provisioned for that role. The development repository has its own AGENTS.md
and local role procedures. The customer’s access profiles define permissions in their workspace.
Accountable roles
| Role | Accountable outcome |
|---|---|
| Кира / Product Owner | Problem, user outcome, discovery readiness, scope decision. |
| Сергей / Industrial BA | Requirements, constraints, technical assignment, acceptance traceability. |
| Анна / Product Delivery | Plan, task capsule, handoff orchestration, release-readiness report. |
| Дмитрий / Implementation | Bounded code or configuration change and focused test evidence. |
| Рита / Structural Review | Architecture fit, changed symbols, blast radius, regression risk. |
| Вера / AppSec | Security, privacy, secrets, DLP, and publication boundary. |
| Лена / QA | Acceptance checks, regressions, and live or headless validation. |
| Борис / Documentation Memory | Documentation, catalog, bootstrap routing, and memory readiness. |
| Иван / Traceability | Links between requirements, stories, tasks, tests, evidence, and projections. |
| Олег / Support | Grounded answers, known issues, troubleshooting, and operator caveats. |
| Марина / AI Workforce Governance | Role skills, prompts, subagents, approvals, rollout, and drift. |
| Глеб / DevOps and SRE | Runtime, CI, deployment, release engineering, rollback, and publication. |
| Ева / Financial Control | Token, time, cost reconciliation, and financial closure evidence. |
Each role records the results of checks within its responsibilities. The summary report links to those results and the underlying evidence.
Delivery flow
Product requirements live in openspec/changes/<change-id>/; accepted contracts move to
openspec/specs/. The team links each task to its requirements and checks the result against acceptance criteria.
The usual flow is:
- Кира and Сергей make the intended outcome and acceptance boundary explicit.
- Анна creates or continues the task capsule and assigns the required checks and responsible roles.
- Дмитрий implements the smallest tests-first increment.
- Рита, Вера, and Лена review the exact revision and its observed behavior.
- Борис and Иван synchronize documentation and traceability.
- Олег and Глеб cover support and runtime readiness when those surfaces are in scope.
- Ева reconciles final resource use; Анна reports readiness without replacing lane verdicts.
A lightweight service task can stand on its own, with an optional grouping case and no product story. Product delivery links the task to OpenSpec, a story, a case and acceptance criteria. Its owner, scope, acceptance criteria, handoffs, and required evidence remain explicit. The server prepares a provisional resource estimate when work starts. Ева reconciles actual resource use before closure.
For example, a documentation correction can use a named service task. Record the affected pages, expected wording and example behavior, source revision, editorial review, and checks. If publication is in scope, add deployment and live-page evidence. The server uses the full set of required results to decide whether to close the task.
Status and evidence
Open the task status to see completed checks, role verdicts and remaining questions. Each result is linked to the checked revision, so the team can trace a conclusion to the tests, security report or document behind the decision.
The server checks that the required results are present before closing a task. If a report or dashboard is waiting for synchronization, retrieve the current status from the server. Human approval defines the permitted scope of changes; requirements, check results and resource use remain linked to that task.
Interfaces and scope
Use the interface that matches the task:
- MCP for agent automation and typed governed actions;
- CLI for local analysis and bounded operator workflows;
- REST or the dashboard for authenticated application operations;
- ACP for compatible IDE and agent-client sessions.
Tool presence depends on the active runtime profile and invocation policy. Discover tools through
the running client, pass native structured arguments, and keep project_key, namespace, task, and
story scope explicit where required by the discovered schema. A working call confirms runtime availability.
Verify one delivery
The server field final_status_allowed must permit the final status for the same task and revision.
Before reporting completion, reopen the authoritative status for the same task and revision. Check that every active acceptance criterion has an explicit result, required lane verdicts refer to the current revision, and the final-status decision has no unresolved blocker. The handoff history shows ownership changes, the run status shows execution progress, and the closure packet records acceptance.
While the runner is active, report the completed work and its current execution stage. If projection synchronization is pending, retrieve the status from the server. The report then shows the team what has been done and the next step.
Access and next steps
The task scope and access profile define shell, repository, deployment and publication permissions. Operators manage credentials, environment access and the scope of changes agreed with the user.
Start with the quick start, use the MCP operator guide for runtime discovery, and consult the scenario guide to choose a supported workflow.