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 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: ```sh 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: ```sh wta vps doctor wta vps bootstrap --apply wta vps enforce-ssh --apply ``` 3. Bootstrap the team: ```sh wta team init --name <you> --role orchestrator \ --pubkey ~/.ssh/id_ed25519.pub ``` 4. Add a release target (defaults to `push` mode): ```sh 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: ```sh wta join NAME.invite.toml ``` This initializes local config, identity, and source checkout in one step. ## Identity ```sh 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. ```sh # 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 ```sh 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](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.