Roles

A role is an agent identity: a name, a CLAUDE.md with instructions, a permission tier, and a workspace layout. Roles define what each agent does and what it's allowed to do.

How Roles Work

When you run initech init and select agents, each one gets:

A workspace directory (<project>/<role>/)
A CLAUDE.md file tailored to the role (identity, responsibilities, constraints, workflow)
A permission tier (supervised or autonomous)
A src/ git submodule for roles that need source access

The role name is used everywhere: TUI pane name, directory name, messaging target (initech send eng1). One name, no aliasing.

Built-in Roles

initech ships with 11 role templates organized into tiers:

Coordinator tier

Role	Function	Permission
super	Work coordinator and dispatcher. Assigns tasks to agents, monitors progress, manages the bead lifecycle. The only role that communicates with all other agents.	Supervised

Spec tier

Role	Function	Permission
pm	Product manager. Defines requirements, acceptance criteria, and user stories. Reviews eng work for requirement survival.	Autonomous
pmm	Product marketing. Owns external positioning, website copy, blog posts, changelogs, and translations.	Autonomous
arch	Architect. Owns system shape: domain model, API contracts, security architecture, design decisions.	Autonomous
sec	Security. Threat modeling, vulnerability triage, risk scoring. Thinks like an attacker.	Autonomous

Implementation tier

Role	Function	Permission
eng1, eng2	Engineers. Implement features, fix bugs, write tests. Parallel instances with isolated git worktrees so they don't conflict on file changes.	Autonomous

Validation tier

Role	Function	Permission
qa1, qa2	Quality assurance. Validate features via behavioral testing. Issue PASS/FAIL verdicts. Can block releases.	Autonomous

Ship tier

Role	Function	Permission
shipper	Release management. Builds, packages, distributes. Handles goreleaser, Homebrew formulas, CI workflows.	Supervised

Support tier

Role	Function	Permission
writer	Technical writer. User-facing docs, setup guides, tutorials.	Autonomous
ops	Operations. Tests software as an end user. Validates install, launch, and use flows on real hardware.	Autonomous
growth	Growth engineer. Analytics instrumentation, event taxonomy, funnel analysis, experiments.	Autonomous

Permission Model

Two tiers control how much autonomy each agent has:

Tier	Flag	Roles	Rationale
Supervised	(none)	super, shipper	High-blast-radius actions. The operator wants visibility into what these agents do: dispatching all work, releasing software.
Autonomous	--dangerously-skip-permissions	All others	Implementation and analysis work. Stopping for permission prompts on every file read kills throughput.

You can override the default permission tier per role using role_overrides in initech.yaml. Set claude_args: [] to make any role supervised, or add --dangerously-skip-permissions to make a normally supervised role autonomous.

Workspace Structure

Each agent gets its own directory under the project root:

myproject/
  super/
    CLAUDE.md          # Role instructions
    .claude/           # Claude Code session state

  eng1/
    CLAUDE.md          # Role instructions
    src/               # Git submodule (isolated worktree)
    .claude/           # Claude Code session state

  qa1/
    CLAUDE.md
    src/               # Git submodule (read-only convention)

  shipper/
    CLAUDE.md
    src/               # Git submodule
    playbooks/         # Operational runbooks

  pm/
    CLAUDE.md          # No src/ (doesn't write code)

Engineers, QA, and shippers each get their own src/ directory as a git submodule. This gives each agent an isolated working tree so they don't conflict on file changes. QA follows a read-only convention on their copy.

Roles that don't write code (pm, pmm, arch, sec) don't get a src/ submodule.

Customizing Roles

Editing CLAUDE.md

The CLAUDE.md in each agent's workspace is the role's operating system. After initech init generates it from a template, you own it. Edit freely to add project-specific instructions, constraints, or workflow details.

A good CLAUDE.md answers: who is this agent, what does it own, what can't it do, and how does it communicate? An agent with no prior context should read its CLAUDE.md and start working correctly.

Per-role command overrides

Use role_overrides in initech.yaml to customize what command each agent runs:

role_overrides:
    # Give super no extra flags (supervised)
    super:
        claude_args: []

    # Run a Codex agent for growth
    growth:
        command: ["codex", "resume", "--last", "--full-auto"]
        agent_type: codex

    # Run OpenCode for a specific role
    writer:
        command: ["opencode"]
        agent_type: opencode

See the configuration reference for all available override fields.

Running non-Claude agents

initech is not limited to Claude Code. The agent_type field in role overrides tells the TUI how to handle input injection and readiness detection for different agent runtimes:

agent_type	Runtime	Input method
claude-code	Claude Code (default)	Bracketed paste
codex	OpenAI Codex CLI	Typed injection + Enter
opencode	OpenCode	Typed injection + Enter
generic	Any CLI agent	Conservative typed input

You can mix agent types in the same session. Run Claude Code for eng and QA, Codex for growth, and a custom agent for ops. All agents communicate through the same initech send / initech peek protocol regardless of their runtime.

Custom role names

Any name works. The 11 built-in names get tailored CLAUDE.md templates on init. A custom name (e.g., designer, intern, devops) gets a generic template that you customize after init.

roles:
    - super
    - eng1
    - designer    # Custom name, generic template
    - intern      # Custom name, generic template

TUI

Communication

Last updated: April 2026