Reposition Ward as the operations layer for unattended coding agents #974

New issue

Closed

opened 2026-07-10 08:49:45 +00:00 by coilysiren · 1 comment

coilysiren commented

2026-07-10 08:49:45 +00:00

Owner

The problem

Proposed change

Body

Summary

Rebrand Ward around the product category and user outcome it actually provides:

Ward is the operations layer for unattended coding agents.

The current headline language describes Ward as a “guarded execution layer for coding agents.” That is accurate as an architectural description, but it explains an implementation mechanism rather than the user’s problem.

Ward’s public positioning should immediately communicate that it operates coding-agent work after the user walks away: dispatch, isolation, supervision, observability, recovery, governance, and delivery of a durable outcome.

Problem

The existing messaging introduces Ward through command gating and guarded execution. The stronger agent-operations value appears only after the reader has already had to understand internal concepts.

“Guarded execution layer” does not communicate:

Why someone would install Ward instead of invoking a harness directly
That Ward is designed for unattended work
That it supervises the complete run lifecycle
That failures remain observable and recoverable
That the desired output is a PR, landed change, or explicit blocked outcome
Why reservations, reapers, review, directors, and forge integration belong together

The product currently reads as a secure agent launcher. Its actual value is closer to a turnkey operational system around otherwise ephemeral harness sessions.

Positioning decision

The canonical one-line description is:

Ward is the operations layer for unattended coding agents.

The supporting promise is:

Give Ward an issue. It launches the selected coding harness in an isolated environment, supervises the run, preserves work through failure, and carries the result to a pull request or an explicit blocked outcome.

Where appropriate, Ward can additionally be described as open source and self-hosted, but those attributes should not displace the primary category statement.

Intended audience

Lead with the user who:

Runs Claude Code, Codex, Goose, OpenCode, or similar harnesses frequently
Wants to dispatch work and walk away
Trusts the model’s ability but not an ephemeral harness session as a durable operational unit
Has experienced stranded worktrees, silent failures, duplicate runs, unclear completion, or terminal babysitting
Wants agent reliability without building their own DevEx, observability, and recovery system
Prefers an inspectable, locally controlled system over an opaque managed service

Do not make a particular forge, model family, or organization size part of the primary persona.

Messaging hierarchy

First level: category

Ward is the operations layer for unattended coding agents.

Second level: outcome

Give Ward an issue. Get a governed, observable, recoverable path to a durable result.

Third level: operational responsibilities

Ward handles:

Task dispatch and reservation
Isolated execution
Harness lifecycle and goal continuation
Status, logs, artifacts, and provenance
Failure detection and work preservation
Cleanup and reaping
Review and landing policy
Forge-side outcome recording

Fourth level: architecture

Terms such as “guarded execution layer,” cli-guard, ward-kdl, broker, reaper, substrate, and director belong in architecture and operator documentation after the product promise is established.

“Guarded execution layer” does not need to disappear entirely. It should be demoted from product identity to an explanation of how part of Ward works.

Required changes

README

Rewrite the opening viewport of README.md so it contains:

The canonical one-line description
The issue-to-outcome supporting promise
A minimal invocation example
A short explanation of why Ward exists instead of invoking a harness directly

Suggested opening:

# Ward

**Ward is the operations layer for unattended coding agents.**

Give Ward an issue. It launches Claude Code, Codex, Goose, or OpenCode in an
isolated environment, supervises the run, preserves work through failure, and
carries the result to a pull request or an explicit blocked outcome.

```console
warded owner/repo#123


Adjust the exact harness list to match the live supported roster.

### CLI copy

Update public-facing `Usage` and `Description` text in:

- The root command
- `ward agent`
- The `warded` entry surface
- Empty-command help and role orientation
- Version or package metadata where applicable

The first description shown by `ward --help` and `ward agent --help` should establish agent operations before explaining implementation details.

Do not make the contributor command gate disappear from the CLI. Present it as one Ward capability rather than the headline product category.

### Documentation

Update the positioning and introductory copy in at least:

- `README.md`
- `AGENTS.md`
- `docs/README.md`
- `docs/FEATURES.md`
- `docs/architecture.md`
- `docs/agent.md`
- `docs/agent-lifecycle.md`
- `docs/first-run.md`

Review other durable guides for opening language that still presents “guarded execution layer” as the product identity.

Architecture documentation should explain the distinction explicitly:

- Ward’s product category is agent operations.
- Guarded execution is one mechanism within that system.
- `cli-guard` and ward-kdl remain architectural components.

### Distribution metadata

Update user-visible metadata where maintained:

- Forgejo repository description
- GitHub mirror description
- Homebrew formula description
- Release descriptions or templates
- Issue templates that explain Ward
- Package metadata embedded in generated artifacts

External repository descriptions may require a manual maintainer action; document the exact replacement text in the implementation PR.

## Terminology

Use these terms consistently:

- **Operations layer** — Ward’s category
- **Unattended coding agents** — the operating mode Ward makes dependable
- **Run** — one managed unit of agent work
- **Durable outcome** — PR, landed change, preserved salvage, or explicit blocker
- **Harness** — Claude Code, Codex, Goose, OpenCode, or another agent runtime
- **Guarded execution** — an implementation property, not the headline category

“Unattended” must not imply unaccountable or guaranteed success. It means the operator can walk away without losing operational truth.

Ward guarantees that a run becomes inspectable and recoverable, not that every model completes every task.

## Product pillars

Use the following framework when longer copy needs to explain the product:

- **DevEx:** one-command dispatch and useful defaults
- **Observability:** truthful status, logs, activity, artifacts, and provenance
- **Reliability:** isolation, persistence, recovery, cleanup, and idempotency
- **Governance:** credentials, permissions, reservations, audit, review, and landing policy
- **Workflow closure:** the run produces a durable result or an explicit blocker

Avoid presenting observability or policy as isolated feature lists. They exist to make unattended delegation trustworthy.

## Non-goals

This issue does not:

- Rename the `ward`, `ward agent`, or `warded` commands
- Remove the contributor command gate
- Deprecate agent roles or operational features
- Change runtime behavior
- Promise support for an unsupported forge or harness
- Turn Ward into a hosted service
- Claim that Ward improves model intelligence
- Guarantee successful task completion
- Replace detailed architecture documentation with marketing copy

## Acceptance criteria

- The first substantive sentence in `README.md` is the canonical positioning line.
- A new reader can understand the issue-to-durable-outcome promise without scrolling past the opening section.
- `ward --help` and `ward agent --help` lead with agent operations rather than guarded-execution internals.
- “Guarded execution layer” is no longer used as Ward’s primary public identity.
- Contributor gating remains accurately documented.
- Public copy distinguishes model intelligence from operational reliability.
- “Unattended” is defined without implying silent or ungoverned execution.
- Forge and harness claims match live support.
- Repository and package descriptions use consistent language.
- Generated documentation and CLI-copy tests are updated.
- Existing documentation drift tests pass.

## Suggested repository description

> The operations layer for unattended coding agents: isolated runs, supervision, recovery, review, and durable delivery.

Alternatives considered

Before filing

I searched existing issues and this is not a duplicate.
This stays within ward's scope (the dev-verb gate / agent driver), not a personal-infra or downstream-repo verb.

### The problem // ### Proposed change **Body** ## Summary Rebrand Ward around the product category and user outcome it actually provides: > **Ward is the operations layer for unattended coding agents.** The current headline language describes Ward as a “guarded execution layer for coding agents.” That is accurate as an architectural description, but it explains an implementation mechanism rather than the user’s problem. Ward’s public positioning should immediately communicate that it operates coding-agent work after the user walks away: dispatch, isolation, supervision, observability, recovery, governance, and delivery of a durable outcome. ## Problem The existing messaging introduces Ward through command gating and guarded execution. The stronger agent-operations value appears only after the reader has already had to understand internal concepts. “Guarded execution layer” does not communicate: * Why someone would install Ward instead of invoking a harness directly * That Ward is designed for unattended work * That it supervises the complete run lifecycle * That failures remain observable and recoverable * That the desired output is a PR, landed change, or explicit blocked outcome * Why reservations, reapers, review, directors, and forge integration belong together The product currently reads as a secure agent launcher. Its actual value is closer to a turnkey operational system around otherwise ephemeral harness sessions. ## Positioning decision The canonical one-line description is: > **Ward is the operations layer for unattended coding agents.** The supporting promise is: > Give Ward an issue. It launches the selected coding harness in an isolated environment, supervises the run, preserves work through failure, and carries the result to a pull request or an explicit blocked outcome. Where appropriate, Ward can additionally be described as open source and self-hosted, but those attributes should not displace the primary category statement. ## Intended audience Lead with the user who: * Runs Claude Code, Codex, Goose, OpenCode, or similar harnesses frequently * Wants to dispatch work and walk away * Trusts the model’s ability but not an ephemeral harness session as a durable operational unit * Has experienced stranded worktrees, silent failures, duplicate runs, unclear completion, or terminal babysitting * Wants agent reliability without building their own DevEx, observability, and recovery system * Prefers an inspectable, locally controlled system over an opaque managed service Do not make a particular forge, model family, or organization size part of the primary persona. ## Messaging hierarchy ### First level: category > Ward is the operations layer for unattended coding agents. ### Second level: outcome > Give Ward an issue. Get a governed, observable, recoverable path to a durable result. ### Third level: operational responsibilities Ward handles: * Task dispatch and reservation * Isolated execution * Harness lifecycle and goal continuation * Status, logs, artifacts, and provenance * Failure detection and work preservation * Cleanup and reaping * Review and landing policy * Forge-side outcome recording ### Fourth level: architecture Terms such as “guarded execution layer,” `cli-guard`, ward-kdl, broker, reaper, substrate, and director belong in architecture and operator documentation after the product promise is established. “Guarded execution layer” does not need to disappear entirely. It should be demoted from product identity to an explanation of how part of Ward works. ## Required changes ### README Rewrite the opening viewport of `README.md` so it contains: 1. The canonical one-line description 2. The issue-to-outcome supporting promise 3. A minimal invocation example 4. A short explanation of why Ward exists instead of invoking a harness directly Suggested opening: ````markdown # Ward **Ward is the operations layer for unattended coding agents.** Give Ward an issue. It launches Claude Code, Codex, Goose, or OpenCode in an isolated environment, supervises the run, preserves work through failure, and carries the result to a pull request or an explicit blocked outcome. ```console warded owner/repo#123 ```` ``` Adjust the exact harness list to match the live supported roster. ### CLI copy Update public-facing `Usage` and `Description` text in: - The root command - `ward agent` - The `warded` entry surface - Empty-command help and role orientation - Version or package metadata where applicable The first description shown by `ward --help` and `ward agent --help` should establish agent operations before explaining implementation details. Do not make the contributor command gate disappear from the CLI. Present it as one Ward capability rather than the headline product category. ### Documentation Update the positioning and introductory copy in at least: - `README.md` - `AGENTS.md` - `docs/README.md` - `docs/FEATURES.md` - `docs/architecture.md` - `docs/agent.md` - `docs/agent-lifecycle.md` - `docs/first-run.md` Review other durable guides for opening language that still presents “guarded execution layer” as the product identity. Architecture documentation should explain the distinction explicitly: - Ward’s product category is agent operations. - Guarded execution is one mechanism within that system. - `cli-guard` and ward-kdl remain architectural components. ### Distribution metadata Update user-visible metadata where maintained: - Forgejo repository description - GitHub mirror description - Homebrew formula description - Release descriptions or templates - Issue templates that explain Ward - Package metadata embedded in generated artifacts External repository descriptions may require a manual maintainer action; document the exact replacement text in the implementation PR. ## Terminology Use these terms consistently: - **Operations layer** — Ward’s category - **Unattended coding agents** — the operating mode Ward makes dependable - **Run** — one managed unit of agent work - **Durable outcome** — PR, landed change, preserved salvage, or explicit blocker - **Harness** — Claude Code, Codex, Goose, OpenCode, or another agent runtime - **Guarded execution** — an implementation property, not the headline category “Unattended” must not imply unaccountable or guaranteed success. It means the operator can walk away without losing operational truth. Ward guarantees that a run becomes inspectable and recoverable, not that every model completes every task. ## Product pillars Use the following framework when longer copy needs to explain the product: - **DevEx:** one-command dispatch and useful defaults - **Observability:** truthful status, logs, activity, artifacts, and provenance - **Reliability:** isolation, persistence, recovery, cleanup, and idempotency - **Governance:** credentials, permissions, reservations, audit, review, and landing policy - **Workflow closure:** the run produces a durable result or an explicit blocker Avoid presenting observability or policy as isolated feature lists. They exist to make unattended delegation trustworthy. ## Non-goals This issue does not: - Rename the `ward`, `ward agent`, or `warded` commands - Remove the contributor command gate - Deprecate agent roles or operational features - Change runtime behavior - Promise support for an unsupported forge or harness - Turn Ward into a hosted service - Claim that Ward improves model intelligence - Guarantee successful task completion - Replace detailed architecture documentation with marketing copy ## Acceptance criteria - The first substantive sentence in `README.md` is the canonical positioning line. - A new reader can understand the issue-to-durable-outcome promise without scrolling past the opening section. - `ward --help` and `ward agent --help` lead with agent operations rather than guarded-execution internals. - “Guarded execution layer” is no longer used as Ward’s primary public identity. - Contributor gating remains accurately documented. - Public copy distinguishes model intelligence from operational reliability. - “Unattended” is defined without implying silent or ungoverned execution. - Forge and harness claims match live support. - Repository and package descriptions use consistent language. - Generated documentation and CLI-copy tests are updated. - Existing documentation drift tests pass. ## Suggested repository description > The operations layer for unattended coding agents: isolated runs, supervision, recovery, review, and durable delivery. ``` ### Alternatives considered // ### Before filing - [x] I searched existing issues and this is not a duplicate. - [x] This stays within ward's scope (the dev-verb gate / agent driver), not a personal-infra or downstream-repo verb.