Workflow Modes

Writ’s workflow scales from a solo developer pressing enter through prompts to an enterprise fleet of 500 agents committing autonomously. The scaling happens in the automation layer between agents and git, not in the user’s interface. One agent or 500, the user checks in with writ status, promotes work with writ finish, and pushes with git push.

Two modes control how completed work becomes git commits.

User Mode (Default)

The user runs writ finish manually. Maximum control.

agents complete work → user runs writ status → user runs writ finish → git commit

# .writ/config.toml
[workflow]
commit_mode = "user"

This is the default because it’s the safest starting point. The user reviews everything. Good for solo developers, small teams, and learning writ.

The Three Command Interface

From the user’s perspective, the entire workflow is three commands:

writ status                  # What's happening?
writ finish                  # Promote completed work to git
git push                     # Standard git from here

writ status shows a fleet overview: how many agents are active, which specs are complete, what’s ready to commit. It adapts automatically to scale, expanding details for small projects and collapsing to summaries for large ones.

writ finish is interactive. It shows all completed specs, lets you select which to include, and offers commit strategies:

• Single commit (default): All specs as one git commit. Clean and simple.
• Per spec commits: Each spec becomes its own git commit. Good when git bisect and per feature rollback matter.
• Grouped commits: Writ auto detects logical groupings by file overlap. Good for large scale where coherence matters more than granularity.

Live Monitoring

writ status --watch

Refreshes every 5 seconds. Shows agents completing specs in real time. Keyboard shortcuts let you jump to finish or diff without leaving the view.

Auto Mode

Fully autonomous. Orchestrator commits directly. No human in the loop.

agents complete work → orchestrator runs writ finish --auto → git commit

# .writ/config.toml
[workflow]
commit_mode = "auto"

[workflow.auto]
verify_command = "cargo test --quiet"    # must exit 0 to commit
max_specs_per_commit = 10                # prevent mega-commits
branch = "writ/auto"                     # commit to a branch, not main
notify = "log"                           # log | stdout | none

Safety Rails

Auto mode is powerful and dangerous. The configuration includes guardrails:

Test verification: The verify_command must exit 0 before a commit proceeds. If tests fail, the commit is blocked and the spec goes into a blocked state.

Branch targeting: Auto commits go to a designated branch (writ/auto), not directly to main. The human merges when ready. This is the strongest safety rail. Agents commit freely, but the human controls what reaches main.

Max specs per commit: Prevents runaway mega-commits. If more than N specs are completed, they’re committed in batches.

When to Use Auto

• CI pipelines where completed work should commit immediately
• Overnight batch runs with trusted agents
• Environments with strong test suites that catch regressions

The Agent’s Perspective

Agents follow the same workflow regardless of mode:

writ context                                          # understand project state, find unclaimed specs
writ spec claim auth                                  # claim a spec (or auto-claim on first seal)
# ... do work ...
writ seal -s "added auth endpoint" --spec auth        # checkpoint (captures only this spec's changes)
# ... more work ...
writ spec done auth -s "JWT auth complete"            # mark task complete

Agents seal checkpoints and mark tasks complete. They do not run writ finish or git commit. The workflow mode determines what happens after spec done, and that’s not the agent’s concern. Multiple agents can work in the same directory simultaneously. Spec-scoped sealing keeps each agent’s changes separate.

Choosing a Mode

Configuration

Set the mode during writ init or directly in config. See Configuration for the full reference.

# During init:
# Default workflow mode:
#   (1) user      You run `writ finish` manually (recommended)
#   (2) auto      Fully autonomous (CI/pipelines)

Global config applies to all projects. Override per project in .writ/config.toml.