AGENTS.md opens by pointing agents at a private workspace chain (agentic-os-kai) and never addresses the adopter-agent 'set this up for me' path

coilyco-ops commented

2026-07-01 22:43:16 +00:00

Member

Why

Persona vibe-coder / angle agent-legibility. This persona's actual move is pasting the repo URL into their harness and saying "set this up for me" — so the surface under test is what the delegated agent finds. Its entry point, AGENTS.md, opens with:

Workspace conventions load globally via ~/.claude/CLAUDE.md -> agentic-os-kai/AGENTS.md. This file covers only what's specific to this repo.

An external adopter's agent has neither that CLAUDE.md chain nor agentic-os-kai/ — the first sentence of the agent-facing doc references a private workspace it cannot resolve, and declares that the global conventions (which the rest of the doc assumes) live there.

From there, everything in AGENTS.md addresses an agent contributing to ward itself: dogfood commands (ward exec build in ward's own tree), release workflow, skip-CI marker rules, cross-repo pins. Nothing addresses the delegated-adopter agent whose task is "install ward and configure it for my user's repo" — no pointer to install → author .ward/ward.yaml → ward lint → ward install-hooks. The one line aimed downstream ("Downstream config schema: .ward/ward.yaml. Schema lives here.") points at nothing (see #436).

The result: the persona that bounces fastest delegates setup, and their agent lands on a doc written for a different audience that starts by citing files only Kai's machines have. The agent either improvises (unguided config authoring, cf. #436's silent-pass risk) or reports failure — this persona never files feedback, they just leave.

Deliverable

State the audience split at the top of AGENTS.md: a short "agent setting up ward for a downstream repo" section (or a link to the first-run guide proposed in #467) before the contributor-facing material, and either remove the private-workspace loading note or mark it explicitly as internal-fleet-only so an external agent knows to skip it.

Done condition

An agent given only the repo URL and the task "set up ward for this user's repo" finds, from AGENTS.md, an ordered adopter path (install → config → lint → hooks) without needing any agentic-os-kai/~/.claude context, and can tell which sections of AGENTS.md do not apply to it.

Severity: major-friction · persona: vibe-coder · angle: agent-legibility
Filed by Claude Code during a cold-read release pressure test (run 31).

## Why Persona `vibe-coder` / angle `agent-legibility`. This persona's actual move is pasting the repo URL into their harness and saying "set this up for me" — so the surface under test is what the **delegated agent** finds. Its entry point, `AGENTS.md`, opens with: > Workspace conventions load globally via `~/.claude/CLAUDE.md` -> `agentic-os-kai/AGENTS.md`. This file covers only what's specific to this repo. An external adopter's agent has neither that `CLAUDE.md` chain nor `agentic-os-kai/` — the first sentence of the agent-facing doc references a private workspace it cannot resolve, and declares that the *global* conventions (which the rest of the doc assumes) live there. From there, everything in AGENTS.md addresses an agent **contributing to ward itself**: dogfood commands (`ward exec build` in ward's own tree), release workflow, skip-CI marker rules, cross-repo pins. Nothing addresses the delegated-adopter agent whose task is "install ward and configure it for my user's repo" — no pointer to install → author `.ward/ward.yaml` → `ward lint` → `ward install-hooks`. The one line aimed downstream ("Downstream config schema: `.ward/ward.yaml`. Schema lives here.") points at nothing (see #436). The result: the persona that bounces fastest delegates setup, and their agent lands on a doc written for a different audience that starts by citing files only Kai's machines have. The agent either improvises (unguided config authoring, cf. #436's silent-pass risk) or reports failure — this persona never files feedback, they just leave. ## Deliverable State the audience split at the top of AGENTS.md: a short "agent setting up ward for a downstream repo" section (or a link to the first-run guide proposed in #467) before the contributor-facing material, and either remove the private-workspace loading note or mark it explicitly as internal-fleet-only so an external agent knows to skip it. ## Done condition An agent given only the repo URL and the task "set up ward for this user's repo" finds, from AGENTS.md, an ordered adopter path (install → config → lint → hooks) without needing any `agentic-os-kai`/`~/.claude` context, and can tell which sections of AGENTS.md do not apply to it. --- **Severity: major-friction** · persona: vibe-coder · angle: agent-legibility Filed by Claude Code during a cold-read release pressure test (run 31).

coilyco-ops added the

pressure-test

label

2026-07-01 22:43:16 +00:00

coilyco-ops referenced this issue

2026-07-01 22:43:18 +00:00

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

coilyco-ops added this to the ward launch milestone

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

coilyco-ops added the

headless

P1

labels

2026-07-01 23:30:21 +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

coilyco-ops commented

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

Author

Member

🔒 Reserved by ward agent --driver claude — container engineer-claude-ward-476 on host kais-macbook-pro-2.local is carrying this issue (reserved 2026-07-02T07:09:55Z). 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-476` on host `kais-macbook-pro-2.local` is carrying this issue (reserved 2026-07-02T07:09:55Z). 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

2026-07-02 07:10:55 +00:00

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

coilysiren referenced this issue from a commit

2026-07-02 07:12:51 +00:00

docs(agents): add adopter-agent setup path to AGENTS.md

coilysiren closed this issue

2026-07-02 07:12:51 +00:00

coilysiren commented

2026-07-02 07:13:23 +00:00

Owner

WARD-OUTCOME: done - AGENTS.md now opens with an audience split plus a forge-agnostic adopter setup path (install -> ward setup -> ward doctor -> ward install-hooks).

Retrospective: this one was smaller than the issue implied. The private-workspace loading line the issue quotes was already gone from AGENTS.md by the time I got here - line 3 already declared the file self-contained - so the real gap was just the missing adopter path, not the removal. The satisfying part was that ward already ships every piece the adopter needs (ward setup, ward doctor, ward install-hooks, docs/setup.md, docs/ward-yaml.md); the work was mostly pointing the delegated agent at them in the right order and being explicit that doctor is the validator since there is no ward lint verb - an easy thing to get subtly wrong.

One thing that fought back a little: the issue leans on docs/first-run.md as "the adopter path", but that guide is really about the Forgejo-locked container driver, not the forge-agnostic verb gate an external repo actually adopts. I deliberately routed the adopter to setup/doctor/hooks and marked the container driver as explicitly not part of adoption, so I did not create the misleading link the done-condition warned against.

Confidence is high - it is a docs-only change, pre-commit (including dead-cross-links) passes, and every link and intra-file anchor resolves. Possible follow-up: #467 proposed a dedicated adopter first-run guide; if that lands, the inline steps here could collapse into a link to it. Also worth a glance is whether README's "Who it's for" should mirror this same adopter-vs-contributor framing for humans.

WARD-OUTCOME: done - AGENTS.md now opens with an audience split plus a forge-agnostic adopter setup path (install -> ward setup -> ward doctor -> ward install-hooks). Retrospective: this one was smaller than the issue implied. The private-workspace loading line the issue quotes was already gone from AGENTS.md by the time I got here - line 3 already declared the file self-contained - so the real gap was just the missing adopter path, not the removal. The satisfying part was that ward already ships every piece the adopter needs (`ward setup`, `ward doctor`, `ward install-hooks`, docs/setup.md, docs/ward-yaml.md); the work was mostly pointing the delegated agent at them in the right order and being explicit that `doctor` is the validator since there is no `ward lint` verb - an easy thing to get subtly wrong. One thing that fought back a little: the issue leans on docs/first-run.md as "the adopter path", but that guide is really about the Forgejo-locked container driver, not the forge-agnostic verb gate an external repo actually adopts. I deliberately routed the adopter to setup/doctor/hooks and marked the container driver as explicitly *not* part of adoption, so I did not create the misleading link the done-condition warned against. Confidence is high - it is a docs-only change, pre-commit (including dead-cross-links) passes, and every link and intra-file anchor resolves. Possible follow-up: #467 proposed a dedicated adopter first-run guide; if that lands, the inline steps here could collapse into a link to it. Also worth a glance is whether README's "Who it's for" should mirror this same adopter-vs-contributor framing for humans.

coilysiren referenced this issue

2026-07-02 07:33:03 +00:00

Salvage should post back to the carried issue that spawned the run, and must not salvage runs whose work already landed #518

coilysiren referenced this issue

2026-07-14 15:27:09 +00:00

director should emit colorized, space buffered, visually distinct messages about the categories of actions its performing on startup #1283

Rows
Columns

AGENTS.md opens by pointing agents at a private workspace chain (agentic-os-kai) and never addresses the adopter-agent 'set this up for me' path #476

Why

Deliverable

Done condition