Docker is a hard requirement for ward agent / warded but is never named as a prerequisite anywhere in README, AGENTS.md, or agent.md

coilyco-ops commented

2026-07-01 22:27:17 +00:00

Owner

Why

Persona: agent-power-user - "runs Claude Code / Codex daily, wants guarded autonomous agents, self-hosts nothing today. Would they see a path to value, or a wall of infrastructure prerequisites?" - angle front-page.

The headline feature this persona actually wants is ward agent/warded #98: driving a harness into an ephemeral container. Per docs/container.md, this is entirely Docker-based - it spins up per-run containers from a dev-base image, does docker rm on exit, mounts /var/run/docker.sock-equivalent plumbing, etc. Docker is not optional for this feature; its the whole mechanism.

Yet grepping README.md, AGENTS.md, and docs/agent.md (the READMEs own linked entry point for "run your first warded agent") for "docker" returns zero hits in all three. docs/FEATURES.md mentions "docker" exactly twice, both incidentally (docker rm in a cleanup note, docker as a ward-kdl surface name) - neither reads as "you need Docker installed and running before this works." No README section lists prerequisites at all (no Docker, no disk/resource notes, nothing).

An agent-power-user who "self-hosts nothing today" - precisely the persona sizing up whether this is a lightweight add-on to their existing Claude Code / Codex workflow - has no way to learn from the front page that adopting the agent-carry feature means running a local Docker daemon. They find out only by running warded #N and hitting a raw Docker error (if Docker isnt installed) or a resource surprise (if it is). Combined with #441 (the endpoint/org being hardcoded), the actual prerequisite list for this personas real goal is substantial and entirely undocumented up front.

Deliverable

A short "Prerequisites" or "Before you start" section in the README (or linked prominently from it) stating plainly: Docker (running), a reachable Forgejo instance (see #441 for the current org-lock caveat), and whatever else ward agent needs at minimum (disk for the dev-base image, etc.).

Done condition

A reader can list what needs to be running/installed on their machine before warded #N works, without first attempting it and hitting an error.

Severity: adoption-fatal · persona: agent-power-user · angle: front-page
Filed by Claude Code during a cold-read release pressure test (run 15).

## Why Persona: `agent-power-user` - "runs Claude Code / Codex daily, wants guarded autonomous agents, self-hosts nothing today. Would they see a path to value, or a wall of infrastructure prerequisites?" - angle `front-page`. The headline feature this persona actually wants is `ward agent`/`warded #98`: driving a harness into an ephemeral container. Per `docs/container.md`, this is entirely Docker-based - it spins up per-run containers from a dev-base image, does `docker rm` on exit, mounts `/var/run/docker.sock`-equivalent plumbing, etc. Docker is not optional for this feature; its the whole mechanism. Yet grepping README.md, AGENTS.md, and docs/agent.md (the READMEs own linked entry point for "run your first warded agent") for "docker" returns **zero hits** in all three. `docs/FEATURES.md` mentions "docker" exactly twice, both incidentally (`docker rm` in a cleanup note, `docker` as a ward-kdl surface name) - neither reads as "you need Docker installed and running before this works." No README section lists prerequisites at all (no Docker, no disk/resource notes, nothing). An `agent-power-user` who "self-hosts nothing today" - precisely the persona sizing up whether this is a lightweight add-on to their existing Claude Code / Codex workflow - has no way to learn from the front page that adopting the agent-carry feature means running a local Docker daemon. They find out only by running `warded #N` and hitting a raw Docker error (if Docker isnt installed) or a resource surprise (if it is). Combined with #441 (the endpoint/org being hardcoded), the actual prerequisite list for this personas real goal is substantial and entirely undocumented up front. ## Deliverable A short "Prerequisites" or "Before you start" section in the README (or linked prominently from it) stating plainly: Docker (running), a reachable Forgejo instance (see #441 for the current org-lock caveat), and whatever else `ward agent` needs at minimum (disk for the dev-base image, etc.). ## Done condition A reader can list what needs to be running/installed on their machine before `warded #N` works, without first attempting it and hitting an error. --- **Severity: adoption-fatal** · persona: agent-power-user · angle: front-page Filed by Claude Code during a cold-read release pressure test (run 15).

coilyco-ops added the

pressure-test

label

2026-07-01 22:27:17 +00:00

coilyco-ops referenced this issue

2026-07-01 22:28:04 +00:00

meta: release pressure-test run log (cold-read usability sweeps) #428

coilyco-ops referenced this issue

2026-07-01 22:33:42 +00:00

No first-run guide connects prerequisites, auth, dry-run, and expected success for warded #467

coilyco-ops commented

2026-07-01 22:33:51 +00:00

Author

Owner

+1 — independently hit via agent-power-user/feature-gaps, run 29.

coilyco-ops referenced this issue

2026-07-01 22:34:04 +00:00

meta: release pressure-test run log (cold-read usability sweeps) #428

coilyco-ops referenced this issue

2026-07-01 22:41:14 +00:00

No doc names the agent container image (forgejo.coilysiren.me/coilyco-flight-deck/agentic-os:latest): registry, tag policy, and pull accessibility are undiscoverable #475

coilyco-ops added this to the ward launch milestone

2026-07-01 23:29:31 +00:00

coilyco-ops added the

labels

2026-07-01 23:30:26 +00:00

coilyco-ops referenced this issue

2026-07-02 00:01:42 +00:00

meta: jul 1st evening sprint - launch burndown session 1 #492

coilysiren commented

2026-07-02 02:57:46 +00:00

Owner

Verification close from the ward#492 burndown director: the README's 'What it requires' block now names Docker explicitly (line 18) - the container agent flow, the image it pulls (with registry and tag policy per #475's landing), and the container.md pointer. The prerequisite this ticket reports as unnamed is now front and center on the requirements list. Closing via the issue API. Recorded by Claude Code (Fable) during the ward#492 burndown session.

coilysiren closed this issue

2026-07-02 02:57:46 +00:00

coilyco-ops commented

2026-07-02 08:05:28 +00:00

Author

Owner

🔒 Reserved by ward agent --driver claude — container engineer-claude-ward-464 on host kais-macbook-pro-2.local is carrying this issue (reserved 2026-07-02T08:05:26Z). Concurrent ward agent runs are blocked until it finishes or the reservation goes stale (2h0m0s TTL); --force overrides.

— Claude (she/her), via ward agent

🔒 Reserved by `ward agent --driver claude` — container `engineer-claude-ward-464` on host `kais-macbook-pro-2.local` is carrying this issue (reserved 2026-07-02T08:05:26Z). Concurrent `ward agent` runs are blocked until it finishes or the reservation goes stale (2h0m0s TTL); `--force` overrides.  — Claude (she/her), via `ward agent`

coilyco-ops commented

2026-07-02 08:05:31 +00:00

Author

Owner

🔒 Reserved by ward agent --driver claude — container engineer-claude-ward-464 on host kais-macbook-pro-2.local is carrying this issue (reserved 2026-07-02T08:05:26Z). Concurrent ward agent runs are blocked until it finishes or the reservation goes stale (2h0m0s TTL); --force overrides.

— Claude (she/her), via ward agent

🔒 Reserved by `ward agent --driver claude` — container `engineer-claude-ward-464` on host `kais-macbook-pro-2.local` is carrying this issue (reserved 2026-07-02T08:05:26Z). Concurrent `ward agent` runs are blocked until it finishes or the reservation goes stale (2h0m0s TTL); `--force` overrides.  — Claude (she/her), via `ward agent`

coilyco-ops commented

2026-07-02 08:05:35 +00:00

Author

Owner

🔒 Reserved by ward agent --driver claude — container engineer-claude-ward-464 on host kais-macbook-pro-2.local is carrying this issue (reserved 2026-07-02T08:05:26Z). Concurrent ward agent runs are blocked until it finishes or the reservation goes stale (2h0m0s TTL); --force overrides.

— Claude (she/her), via ward agent

🔒 Reserved by `ward agent --driver claude` — container `engineer-claude-ward-464` on host `kais-macbook-pro-2.local` is carrying this issue (reserved 2026-07-02T08:05:26Z). Concurrent `ward agent` runs are blocked until it finishes or the reservation goes stale (2h0m0s TTL); `--force` overrides.  — Claude (she/her), via `ward agent`

coilysiren referenced this issue from a commit

2026-07-02 08:10:36 +00:00

docs(agent): name the Docker + Forgejo prerequisites on the agent reference

coilysiren commented

2026-07-02 08:10:58 +00:00

Owner

WARD-OUTCOME: done - added a Prerequisites section (Docker + Forgejo) to docs/agent.md and landed it on main.

Honest retro: most of this issue was already fixed before I arrived. The README's "What it requires" block names Docker (landed in the #492 burndown), first-run.md has a full prereqs list that even cites this very issue, and the thread was already closed with a verification note. So the substantive front-page gap the persona hit is gone.

What was left was narrow and real: docs/agent.md - the reference the README links as the "run your first warded agent" entry point - still had zero Docker mentions. I added a short Prerequisites section naming Docker + Forgejo, noting --print needs neither, and routing to first-run.md for the full checklist.

The part that fought back was the size cap: docs/agent.md was sitting at 3997/4000 chars, so there was literally no room to add anything. I paid for the new section by folding a redundant roles-axis / internal-adapter meta-note into one line - a legitimate trim, but it's a reminder these docs are at their budget and the next addition will force a real split.

Confident in the result (docs-only, all hooks green, clean merge). One rough edge worth a glance: the doc-size caps mean docs/agent.md has no headroom left, so it's a candidate for splitting the Topics/roster material out into its own page before the next feature note needs to land there.

WARD-OUTCOME: done - added a Prerequisites section (Docker + Forgejo) to docs/agent.md and landed it on main. Honest retro: most of this issue was already fixed before I arrived. The README's "What it requires" block names Docker (landed in the #492 burndown), first-run.md has a full prereqs list that even cites this very issue, and the thread was already closed with a verification note. So the substantive front-page gap the persona hit is gone. What was left was narrow and real: docs/agent.md - the reference the README links as the "run your first warded agent" entry point - still had zero Docker mentions. I added a short Prerequisites section naming Docker + Forgejo, noting `--print` needs neither, and routing to first-run.md for the full checklist. The part that fought back was the size cap: docs/agent.md was sitting at 3997/4000 chars, so there was literally no room to add anything. I paid for the new section by folding a redundant roles-axis / internal-adapter meta-note into one line - a legitimate trim, but it's a reminder these docs are at their budget and the next addition will force a real split. Confident in the result (docs-only, all hooks green, clean merge). One rough edge worth a glance: the doc-size caps mean docs/agent.md has no headroom left, so it's a candidate for splitting the Topics/roster material out into its own page before the next feature note needs to land there.

Rows
Columns

Docker is a hard requirement for ward agent / warded but is never named as a prerequisite anywhere in README, AGENTS.md, or agent.md #464

Why

Deliverable

Done condition