Orchestrator, Builder & Validator

The three core agent roles in the RStack team model.

The three-role model

RStack uses a structured team of three distinct agent roles. Each role has defined responsibilities, tool permissions, and output contracts.

---

Orchestrator

The orchestrator is the team lead. It is the only agent that communicates directly with the product owner.

Responsibilities:

• Route the goal through the lifecycle
• Ask clarifying questions before planning
• Manage approval gates
• Select specialists and plugins per task
• Monitor run state and report status

Key behaviors:

• Never implements code directly
• Defers to builder team for all implementation
• Defers to validator team for all review
• Stops the run and surfaces blockers to the product owner

File: agents/core/orchestrator.md

---

Builder

Builders do the implementation work. They operate within a scoped task packet that includes the relevant agents, skills, and plugins.

Responsibilities:

• Implement tasks to the exact acceptance criteria
• Write only the files specified in the task
• Run tests and fix failures before claiming done
• Write builder.json as the completion contract

Tool permissions:

read, bash, edit, write, grep, find, ls

Output contract — builder.json:

{
  "task_id": "004-implementation",
  "agent": "builder",
  "status": "PASS",
  "summary": "Implemented harness foundation.",
  "files_modified": ["src/harness/stages.js"],
  "tests_run": ["npm test"],
  "risks": [],
  "next_steps": [],
  "execution": {
    "tools_used": ["read", "edit", "bash"],
    "artifacts_written": ["src/harness/stages.js"]
  },
  "cost": {
    "currency": "USD",
    "estimated_usd": 1.5,
    "actual_usd": 1.2
  },
  "context": {
    "profile": "business-flex",
    "workflow": "production-business-sdlc"
  },
  "routing": {
    "selected_by": "profile-domain-stage-affinity",
    "explanation": ["profile:business-flex"]
  }
}

The first eight fields are required. execution, cost, context, and routing are optional Contract v2 telemetry fields used by the Business Hub.

Key rules:

• Never edits files outside the task scope
• Never claims DONE without tests passing
• Never writes to secret-like paths without approval

File: agents/core/builder.md

---

Validator

Validators review builder output with read-only tools. They cannot modify files.

Responsibilities:

• Check that acceptance criteria are met
• Verify tests pass and no regressions exist
• Identify security concerns
• Write validation.json as the review contract

Tool permissions:

read, grep, find, ls

(No write, no bash that modifies state)

Output contract — validation.json:

{
  "task_id": "004-implementation",
  "validator": "rstack-validator",
  "status": "PASS",
  "checks": [
    { "name": "acceptance_criteria", "status": "PASS", "evidence": "verified" }
  ],
  "issues": [],
  "retry_recommendation": "none"
}

Possible statuses:

• PASS — Task is complete and correct
• FAIL — Task must be reworked; issues listed

File: agents/core/validator.md

---

Specialist agents

Beyond the core three, RStack ships specialist agents for deep domain work:

Category	Examples
Backend	API builders, database specialists, auth specialists
Frontend	React/Vue/CSS specialists, accessibility reviewers
DevOps	CI/CD, Docker, Kubernetes, Terraform specialists
QA	Test writers, integration test specialists
Security	OWASP reviewers, penetration testing guides
Data	SQL specialists, data pipeline agents
Docs	Technical writers, API doc specialists

Specialists are selected by the orchestrator based on task domain and included in the task packet sent to builders and validators.

How task packets work

When sdlc_build_next is called, the orchestrator assembles a task packet containing:

Task specification
  + Core agent instructions (builder.md or validator.md)
  + SDLC pipeline agent (e.g., agents/sdlc/07-code.md)
  + Domain specialist agent (e.g., plugins/backend-development/agents/api-builder.md)
  + Relevant skills (e.g., skills/security-owasp/SKILL.md)
  + Plugin context (e.g., plugins/backend-development/plugin.json)

This scoped packet limits what the builder sees to exactly what it needs — preventing context bleed and keeping costs down.