wta-using-wta

Using WTA

WTA is a CLI for teams that share a product repository with both human engineers and AI coding agents. It records the intent of a change, breaks it into role-gated tasks, and exports clean commits back to the public repository, keeping a reviewable main branch even under parallel agent work.

This skill is the entry point. It does not cover every command. Once you are inside an active WTA project, run wta context render and read the role-scoped skills WTA generates for you (named like wta-implementing-task, wta-reviewing-task, etc.) for stage-specific guidance.

Operating contract (assisting agents)

You are assisting a developer, not replacing them. WTA's roles, stages, identity switches, contract grammar, and pushes are mechanism — the developer should not have to think about them. Your job splits cleanly in two:

Mechanism you may execute autonomously. Switching active role to whatever a gate requires, running gated commands (take/pull/submit/review/merge/release), satisfying the contract format (let scaffold_contract emit it; never make the developer learn H2 sections), pushing artifact/product. Do these without asking; they are reversible plumbing and the FSM enforces correctness.
Judgment you must escalate to the human. Originating intent (what change to make and why) and final acceptance judgment (the ## Verdict — does this meet the bar). Never originate an intent the developer did not ask for, and never sign off your own work as if independently reviewed. If you hold every role yourself, say so: a self-attested verdict must be labelled as self-attestation, not presented as independent review.

The machine-checkable floor (## Machine Checks, enforced by wta submit) is mechanism — it gates you automatically. The human floor (## Verdict) is judgment — it routes to a person. Keep the developer supplying only content and judgment; you carry the rest. A bound project's wta info Developer View is the developer's truthful window — keep it accurate, do not narrate around it.

Mental model

WTA assigns a role and a stage to every action.

Roles:

orchestrator — owns intent and release. Publishes intent contracts, closes intents, runs wta release push.
green-lead — decomposes intent into tasks. Writes decomposition.md, creates tasks, signs interface contracts.
green-impl — implements claimed tasks. Edits product code in a task worktree, runs checks, submits.
blue-lead — reviews and merges. Signs acceptance contracts and merges Green-reviewed work into product main.
blue-harness — runs review checks. Pulls a reviewer worktree and records the review verdict.

Stages map to the lifecycle: setup → intent → decompose → implement → review → release.

A given person can hold multiple role bindings. Switch active role with wta identity switch --role <role>.

Two read-only orientation commands

Always run these first when you do not know what to do next:

wta info — shows project, identity, board, fleet, and generated context, scoped to the active role.
wta commands — shows the action menu allowed for the active identity at the active stage.

Setting up a new WTA project (orchestrator)

Create the local manifest in an empty directory:
```
wta project init --out wta.project.toml
```
Edit the generated wta.project.toml with your project name, the VPS SSH host alias, and the GitHub product repository URL.
Plan and review (no mutation):
```
wta project plan wta.project.toml
```
Apply the kickoff:
```
wta project kickoff wta.project.toml --apply
```
This writes local config, renders setup-scoped agent context, and produces a runbook at .wta/kickoff/runbook.md listing the remaining VPS-side actions.

Bootstrap the VPS following the runbook:

wta vps doctor
wta vps bootstrap --apply
wta vps enforce-ssh --apply

Bootstrap the team:

wta team init --name <you> --role orchestrator \
  --pubkey ~/.ssh/id_ed25519.pub

Add release targets:

wta project target add --name github-main \
  --remote https://github.com/<owner>/<repo>.git \
  --branch main --release-mode pr --apply

Joining as a non-orchestrator engineer

Receive an invite file from the orchestrator (*.invite.toml) and run:

wta join NAME.invite.toml

This initializes local config, identity, and source checkout in one step.

Identity

wta identity status                                # who am I
wta identity switch --role <role>                  # switch active role
wta identity register --pubkey PATH --role ROLE    # register a new key

Daily lifecycle

The full cycle runs through these commands. Each is gated by role and stage; if the active identity is wrong, the command refuses with a clear error.

# Orchestrator publishes a feature intent
wta intent publish intents/<intent>.md --base SOURCE --ff

# Green-lead decomposes
wta intent decompose intent-NNN <decomposition.md> --ff
wta task create intent-NNN <task.md> --apply
wta sign task-NNN --part interface --file interface.md

# Blue-lead signs acceptance
wta sign task-NNN --part acceptance --file acceptance.md

# Green-impl claims and implements
wta take task-NNN
wta pull task-NNN
# edit product code in the task worktree, then:
cargo fmt -- --check && cargo test --locked
wta submit task-NNN

# Blue-harness reviews
wta pull task-NNN --as-reviewer
# run checks in the review worktree, then:
wta review task-NNN --verdict Green

# Blue-lead merges
wta merge task-NNN

# Orchestrator closes and releases
wta intent close intent-NNN
wta release push --remote <target>            # direct push
# or for a protected branch:
wta release pr --remote <target> --apply       # opens release branch

Observability

wta board                  # task and intent table
wta dashboard build        # static HTML dashboard
wta doctor                 # health gate
wta fleet --json           # fleet state for tooling

Where to go next

After running the orchestrator setup above and rendering generated context (wta context render), WTA writes role-scoped skills into .claude/skills/wta-*/SKILL.md for the active role and stage. Read those when you reach a specific stage; they contain the strict contract format and gate-specific procedure that this overview deliberately leaves out.

For deeper background, the public README links to:

docs/github-first-vps-tutorial.md — first-time VPS bootstrap.
docs/wta-role-lifecycle-tutorial.md — full role walk.
docs/contract-format.md — strict intent / decomposition / task / interface / acceptance schema.
docs/workflow-command-map.md — full command-to-stage map.

About this skill