wta-using-wta

name	wta-using-wta
description	Operate WTA, the role-gated workflow controller for teams collaborating with humans and AI coding agents. Use when the user wants to set up a new WTA project, configure the SSH/VPS pair, register an identity, or follow the Blue-Green role lifecycle from intent through release.
license	MIT

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 agent 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 (author the strict Markdown yourself from the schema in docs/contract-format.md and the examples/; 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>.

Read-only orientation commands

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

• wta next (or bare wta) — the front door. Prints the active identity, current boundary, the next valid gate, and a few suggested commands. Start here.
• 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 (add --all to see every command).
• wta board — the task and intent table.

Setting up a new WTA project (orchestrator)

1. Create the local config in an empty directory:

   wta init --project <name> --ssh-host <vps-host>
   

   This writes local config and identity scaffolding. Most setup commands are dry-run/plan by default and apply only with --apply.

2. Bootstrap the VPS:

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

3. Bootstrap the team:

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

4. Add a release target (defaults to push mode):

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

   For a protected-branch (pr-mode) production target, attach it with wta project attach --remote <url> --branch main --as production.

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>             # push-mode: applies by default
# or for a protected branch (pr-mode); dry-run by default:
wta release pr --remote <target>               # preview the plan
wta release pr --remote <target> --apply       # push PR branch + record

release pr --apply pushes a PR branch named wta/<project>/<short-commit> (override with --pr-branch) based on the target branch head, writes a release_record (mode pr) to artifact.git, and prints gh pr create instructions; it does not open or merge the PR itself.

Observability

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

Workspace root

The workspace root is a generated cockpit, not a place to edit. WTA regenerates README.md (identity, boundary, next gate, board snapshot) plus product and active symlinks into the managed checkouts on every boundary-changing command — never hand-edit them. Run wta workspace tidy [--apply] to archive any unmanaged root entries into a dated folder, and wta workspace gc to clean stale local worktrees.

Where to go next

After running the orchestrator setup above and rendering generated context (wta agent 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.

Read also

• reference.md — full role × stage × command map, worktree layout, identity commands, and read-only orientation surfaces. Use when you need the lifecycle on one page.