Move agent role definitions into an embedded role KDL file type

coilyco-ops commented

2026-07-10 00:54:34 +00:00

Member

Problem

PR #906 moves in the right direction by resolving role rows from definitions plus fleet overlays, but its source of truth is still hard-coded Go (builtInAgentRoleDefinitions). Kai wants the implementation to rely on a special-purpose agent role KDL file type, embedded into ward at compile time.

Goal

Introduce a ward-owned role-definition KDL asset that describes the shipped startup role presets. Ward embeds that file at compile time and parses it into the role definition model used by ward agent roster and any launch planning that consumes role metadata.

Do

Add a dedicated role-definition KDL file type, separate from ward-kdl.fleet.kdl, ward-kdl.defaults.kdl, topology KDL, and edge guardfiles.
Define a minimal schema for shipped role presets:
- role name
- tagline
- semantic capabilities (read, project-management, engineering, ops, admin)
- invocation modes/help text
- posture (detached, attached, no-code, code-landing)
- default harness/overlay hook fields where needed
Embed the role KDL into ward at compile time.
Replace Go literal role definitions with parsed embedded role KDL defaults.
Keep selected fleet config as an operator overlay layer over those embedded role defaults.
Regenerate docs/agent-roster.md from the resolved role definitions.
Update docs to explain that role definitions are ward-owned embedded KDL product defaults, while fleet KDL remains operator config.

Acceptance

builtInAgentRoleDefinitions() or equivalent Go literal source of role truth is removed or reduced to parser fallback/test fixtures.
A test proves the embedded role KDL parses and produces the shipped engineer/director/advisor/qa roster.
A test proves fleet overlays still affect the effective role metadata without replacing the embedded role defaults.
ward exec test passes, or the issue comment names the exact failing check.

Closes this issue when merged.

## Problem PR #906 moves in the right direction by resolving role rows from definitions plus fleet overlays, but its source of truth is still hard-coded Go (`builtInAgentRoleDefinitions`). Kai wants the implementation to rely on a special-purpose agent role KDL file type, embedded into ward at compile time. ## Goal Introduce a ward-owned role-definition KDL asset that describes the shipped startup role presets. Ward embeds that file at compile time and parses it into the role definition model used by `ward agent roster` and any launch planning that consumes role metadata. ## Do - Add a dedicated role-definition KDL file type, separate from `ward-kdl.fleet.kdl`, `ward-kdl.defaults.kdl`, topology KDL, and edge guardfiles. - Define a minimal schema for shipped role presets: - role name - tagline - semantic capabilities (`read`, `project-management`, `engineering`, `ops`, `admin`) - invocation modes/help text - posture (`detached`, `attached`, `no-code`, `code-landing`) - default harness/overlay hook fields where needed - Embed the role KDL into ward at compile time. - Replace Go literal role definitions with parsed embedded role KDL defaults. - Keep selected fleet config as an operator overlay layer over those embedded role defaults. - Regenerate `docs/agent-roster.md` from the resolved role definitions. - Update docs to explain that role definitions are ward-owned embedded KDL product defaults, while fleet KDL remains operator config. ## Acceptance - `builtInAgentRoleDefinitions()` or equivalent Go literal source of role truth is removed or reduced to parser fallback/test fixtures. - A test proves the embedded role KDL parses and produces the shipped engineer/director/advisor/qa roster. - A test proves fleet overlays still affect the effective role metadata without replacing the embedded role defaults. - `ward exec test` passes, or the issue comment names the exact failing check. Closes this issue when merged.

coilyco-ops added the

headless

P1

labels

2026-07-10 00:54:41 +00:00

coilyco-ops commented

2026-07-10 00:54:45 +00:00

Author

Member

WARD-DISPATCH: failed ❌

failure details

This forwarded dispatch failed after the issue was already reserved.

Attempted harness: codex
Attempted run: ward agent engineer coilyco-flight-deck/ward#911 --harness codex --ward-version v0.543.0
Container: engineer-codex-ward-911
Container created: no running engineer was observed.
Host log: /Users/kai/.ward/agent-logs/dispatch/20260710T005441Z-director-codex-zv98-coilyco-flight-deck-ward-911.log
Failure: ward agent engineer --harness codex: global engineer limit is reached: 10 running (limit 10); wait for a run to finish or run ward agent reap for stale engineers

Retry: choose another harness if the first one is down, or rerun with --force if the reservation is stale.

— Codex, via ward agent

WARD-DISPATCH: failed ❌ <details><summary>failure details</summary> This forwarded dispatch failed after the issue was already reserved. Attempted harness: `codex` Attempted run: `ward agent engineer coilyco-flight-deck/ward#911 --harness codex --ward-version v0.543.0` Container: `engineer-codex-ward-911` Container created: no running engineer was observed. Host log: `/Users/kai/.ward/agent-logs/dispatch/20260710T005441Z-director-codex-zv98-coilyco-flight-deck-ward-911.log` Failure: `ward agent engineer --harness codex: global engineer limit is reached: 10 running (limit 10); wait for a run to finish or run `ward agent reap` for stale engineers` Retry: choose another harness if the first one is down, or rerun with `--force` if the reservation is stale. </details>  — Codex, via `ward agent`

coilyco-ops commented

2026-07-10 17:18:33 +00:00

Author

Member

WARD-RESERVATION: held 🔒

reservation details

Holder: container engineer-codex-ward-911 on host kais-macbook-pro-2.local.

Reserved by ward agent --harness codex (reserved 2026-07-10T17:18:32Z). Concurrent ward agent runs are blocked until it finishes or the reservation goes stale (1h TTL). --force overrides.

Do not comment on or edit this issue to steer the run while it is reserved. The engineer seeded the body once at launch and never re-reads it, so a comment or edit reaches only human readers, never the running engineer. A correction goes to a new issue, dispatched fresh. That is the only channel that reaches a run in flight. Where the forge supports it, ward locks this conversation to make that a road-block rather than a convention (ward#494).

run seed context — what this run is carrying (ward#609)

Resolved: coilyco-flight-deck/ward#911 · branch issue-911 · harness codex · workflow pull-requests-and-merge
Run: engineer-codex-ward-911 · ward v0.584.0 · dispatched 2026-07-10T17:18:32Z
Comment thread: 1 included in the pre-flight read, 0 stripped (ward's own automated comments).
- included: @coilyco-ops (2026-07-10T00:54:45Z)

Static container doctrine and seed boilerplate are identical every run and omitted here (they ride ward v0.584.0).

— Codex, via ward agent

WARD-RESERVATION: held 🔒 <details><summary>reservation details</summary> Holder: container `engineer-codex-ward-911` on host `kais-macbook-pro-2.local`. Reserved by `ward agent --harness codex` (reserved 2026-07-10T17:18:32Z). Concurrent `ward agent` runs are blocked until it finishes or the reservation goes stale (1h TTL). `--force` overrides. **Do not comment on or edit this issue to steer the run while it is reserved.** The engineer seeded the body once at launch and never re-reads it, so a comment or edit reaches only human readers, never the running engineer. A correction goes to a **new issue, dispatched fresh**. That is the only channel that reaches a run in flight. Where the forge supports it, ward locks this conversation to make that a road-block rather than a convention (ward#494). <details><summary>run seed context — what this run is carrying (ward#609)</summary> - **Resolved:** `coilyco-flight-deck/ward#911` · branch `issue-911` · harness `codex` · workflow `pull-requests-and-merge` - **Run:** `engineer-codex-ward-911` · ward `v0.584.0` · dispatched `2026-07-10T17:18:32Z` - **Comment thread:** 1 included in the pre-flight read, 0 stripped (ward's own automated comments). - included: @coilyco-ops (2026-07-10T00:54:45Z) Static container doctrine and seed boilerplate are identical every run and omitted here (they ride ward v0.584.0). </details> </details>  — Codex, via `ward agent`

coilyco-ops referenced this issue from a pull request that will close it,

2026-07-10 17:34:56 +00:00

feat(agent): embed role definitions in KDL #1056

coilyco-ops commented

2026-07-10 17:36:34 +00:00

Author

Member

WARD-OUTCOME: merge-ready

details

workflow: pull-requests-and-merge; review summary: skipped (review gate skipped by ~/.ward/config.yaml default)
summary: embedded role definitions now come from ward-owned KDL defaults, with fleet overlays applied at resolve time.
felt: mechanical and low-risk.
confidence: high.
surprises: the repo test suite needed roster tests to self-seed a bundle fixture, otherwise the bare suite depended on a global config ref.
follow-ups: merge PR #1056 once the director lane clears it.

WARD-OUTCOME: merge-ready <details><summary>details</summary> workflow: pull-requests-and-merge; review summary: skipped (review gate skipped by ~/.ward/config.yaml default) summary: embedded role definitions now come from ward-owned KDL defaults, with fleet overlays applied at resolve time. felt: mechanical and low-risk. confidence: high. surprises: the repo test suite needed roster tests to self-seed a bundle fixture, otherwise the bare suite depended on a global config ref. follow-ups: merge PR #1056 once the director lane clears it. </details>

coilyco-ops commented

2026-07-10 18:11:55 +00:00

Author

Member

WARD-DISPATCH: failed ❌

failure details

This forwarded dispatch failed after the issue was already reserved.

Attempted harness: codex
Attempted run: ward agent engineer coilyco-flight-deck/ward#911 --harness codex --ward-version v0.584.0 --details Conflict-repair assignment from the director merge queue. Existing PR #1056 is blocked by file conflicts on branch issue-911. Start from that existing branch, update it against current main, resolve only the conflicts needed to make PR #1056 mergeable, run the repo allowed validation, and push the same branch. Do not open a replacement PR and do not broaden the feature scope.
Container: engineer-codex-ward-911
Container created: no running engineer was observed.
Host log: /Users/kai/.ward/agent-logs/dispatch/20260710T181147Z-director-codex-cz57-coilyco-flight-deck-ward-911.log
Failure: ward agent engineer --harness codex: issue coilyco-flight-deck/ward#911 is already reserved remotely (by @coilyco-ops at 2026-07-10T17:18:33Z); wait for it to finish or pass --force to override

Retry: choose another harness if the first one is down, or rerun with --force if the reservation is stale.

— Codex, via ward agent

WARD-DISPATCH: failed ❌ <details><summary>failure details</summary> This forwarded dispatch failed after the issue was already reserved. Attempted harness: `codex` Attempted run: `ward agent engineer coilyco-flight-deck/ward#911 --harness codex --ward-version v0.584.0 --details Conflict-repair assignment from the director merge queue. Existing PR #1056 is blocked by file conflicts on branch issue-911. Start from that existing branch, update it against current main, resolve only the conflicts needed to make PR #1056 mergeable, run the repo allowed validation, and push the same branch. Do not open a replacement PR and do not broaden the feature scope.` Container: `engineer-codex-ward-911` Container created: no running engineer was observed. Host log: `/Users/kai/.ward/agent-logs/dispatch/20260710T181147Z-director-codex-cz57-coilyco-flight-deck-ward-911.log` Failure: `ward agent engineer --harness codex: issue coilyco-flight-deck/ward#911 is already reserved remotely (by @coilyco-ops at 2026-07-10T17:18:33Z); wait for it to finish or pass --force to override` Retry: choose another harness if the first one is down, or rerun with `--force` if the reservation is stale. </details>  — Codex, via `ward agent`

coilyco-ops commented

2026-07-10 19:30:45 +00:00

Author

Member

Post-mortem (director surface): PR #1056 for this issue was closed. It reintroduced .ward/ward-kdl/ specgen bundle files, which ward#1009 deleted and forbids restoring. This issue stays open. When the ward open-PR queue is under the backpressure threshold (6), re-cut a clean fix off current main that touches CONSUMER CODE ONLY and never restores .ward/ward-kdl/.

Post-mortem (director surface): PR #1056 for this issue was closed. It reintroduced `.ward/ward-kdl/` specgen bundle files, which ward#1009 deleted and forbids restoring. This issue stays open. When the ward open-PR queue is under the backpressure threshold (6), re-cut a clean fix off current main that touches CONSUMER CODE ONLY and never restores `.ward/ward-kdl/`.

coilyco-ops commented

2026-07-10 23:19:49 +00:00

Author

Member

WARD-RESERVATION: held 🔒

reservation details

Holder: container engineer-codex-ward-911 on host KAI-DESKTOP-TOWER.

Reserved by ward agent --harness codex (reserved 2026-07-10T23:19:50Z). Concurrent ward agent runs are blocked until it finishes or the reservation goes stale (1h TTL). --force overrides.

Do not comment on or edit this issue to steer the run while it is reserved. The engineer seeded the body once at launch and never re-reads it, so a comment or edit reaches only human readers, never the running engineer. A correction goes to a new issue, dispatched fresh. That is the only channel that reaches a run in flight. Where the forge supports it, ward locks this conversation to make that a road-block rather than a convention (ward#494).

run seed context — what this run is carrying (ward#609)

Resolved: coilyco-flight-deck/ward#911 · branch issue-911 · harness codex · workflow pull-requests-and-merge
Run: engineer-codex-ward-911 · ward v0.605.0 · dispatched 2026-07-10T23:19:50Z
Comment thread: 4 included in the pre-flight read, 1 stripped (ward's own automated comments).
- included: @coilyco-ops (2026-07-10T00:54:45Z), @coilyco-ops (2026-07-10T17:36:34Z), @coilyco-ops (2026-07-10T18:11:55Z), @coilyco-ops (2026-07-10T19:30:45Z)
- stripped: @coilyco-ops (2026-07-10T17:18:33Z)

Static container doctrine and seed boilerplate are identical every run and omitted here (they ride ward v0.605.0).

— Codex, via ward agent

WARD-RESERVATION: held 🔒 <details><summary>reservation details</summary> Holder: container `engineer-codex-ward-911` on host `KAI-DESKTOP-TOWER`. Reserved by `ward agent --harness codex` (reserved 2026-07-10T23:19:50Z). Concurrent `ward agent` runs are blocked until it finishes or the reservation goes stale (1h TTL). `--force` overrides. **Do not comment on or edit this issue to steer the run while it is reserved.** The engineer seeded the body once at launch and never re-reads it, so a comment or edit reaches only human readers, never the running engineer. A correction goes to a **new issue, dispatched fresh**. That is the only channel that reaches a run in flight. Where the forge supports it, ward locks this conversation to make that a road-block rather than a convention (ward#494). <details><summary>run seed context — what this run is carrying (ward#609)</summary> - **Resolved:** `coilyco-flight-deck/ward#911` · branch `issue-911` · harness `codex` · workflow `pull-requests-and-merge` - **Run:** `engineer-codex-ward-911` · ward `v0.605.0` · dispatched `2026-07-10T23:19:50Z` - **Comment thread:** 4 included in the pre-flight read, 1 stripped (ward's own automated comments). - included: @coilyco-ops (2026-07-10T00:54:45Z), @coilyco-ops (2026-07-10T17:36:34Z), @coilyco-ops (2026-07-10T18:11:55Z), @coilyco-ops (2026-07-10T19:30:45Z) - stripped: @coilyco-ops (2026-07-10T17:18:33Z) Static container doctrine and seed boilerplate are identical every run and omitted here (they ride ward v0.605.0). </details> </details>  — Codex, via `ward agent`

coilyco-ops referenced this issue from a pull request that will close it,

2026-07-10 23:27:28 +00:00

feat(agent): embed role definitions in KDL #1102

coilyco-ops commented

2026-07-10 23:32:52 +00:00

Author

Member

WARD-OUTCOME: submitted

details

workflow: pull-request-and-merge; review summary: skipped (in-container review gate intentionally skipped because the temporary ward default pending brokered QA)
summary: embedded role definitions now come from ward-owned KDL defaults, with fleet overlays applied at resolve time.
felt: mechanical and low-risk.
confidence: high.
surprises: current main needed a small compatibility-shim cleanup after the rebase so golangci-lint stayed green.
follow-ups: merge PR #1102.

WARD-OUTCOME: submitted <details><summary>details</summary> workflow: pull-request-and-merge; review summary: skipped (in-container review gate intentionally skipped because the temporary ward default pending brokered QA) summary: embedded role definitions now come from ward-owned KDL defaults, with fleet overlays applied at resolve time. felt: mechanical and low-risk. confidence: high. surprises: current main needed a small compatibility-shim cleanup after the rebase so golangci-lint stayed green. follow-ups: merge PR #1102. </details>

coilyco-ops commented

2026-07-10 23:49:11 +00:00

Author

Member

WARD-DISPATCH: failed ❌

failure details

This forwarded dispatch failed after the issue was already reserved.

Attempted harness: codex
Attempted run: ward agent engineer coilyco-flight-deck/ward#911 --harness codex --ward-version v0.605.0
Container: engineer-codex-ward-911
Container created: no running engineer was observed.
Host log: C:\Users\firem\.ward\agent-logs\dispatch\20260710T234900Z-director-codex-yq57-coilyco-flight-deck-ward-911.log
Failure: ward agent engineer --harness codex: issue coilyco-flight-deck/ward#911 is already reserved remotely (by @coilyco-ops at 2026-07-10T23:19:49Z); wait for it to finish or pass --force to override

Retry: choose another harness if the first one is down, or rerun with --force if the reservation is stale.

— Codex, via ward agent

WARD-DISPATCH: failed ❌ <details><summary>failure details</summary> This forwarded dispatch failed after the issue was already reserved. Attempted harness: `codex` Attempted run: `ward agent engineer coilyco-flight-deck/ward#911 --harness codex --ward-version v0.605.0` Container: `engineer-codex-ward-911` Container created: no running engineer was observed. Host log: `C:\Users\firem\.ward\agent-logs\dispatch\20260710T234900Z-director-codex-yq57-coilyco-flight-deck-ward-911.log` Failure: `ward agent engineer --harness codex: issue coilyco-flight-deck/ward#911 is already reserved remotely (by @coilyco-ops at 2026-07-10T23:19:49Z); wait for it to finish or pass --force to override` Retry: choose another harness if the first one is down, or rerun with `--force` if the reservation is stale. </details>  — Codex, via `ward agent`

coilysiren commented

2026-07-10 23:49:47 +00:00

Owner

see also https://forgejo.coilysiren.me/coilyco-flight-deck/agentic-os/issues/465

coilysiren referenced this issue from coilyco-flight-deck/agentic-os

2026-07-10 23:49:59 +00:00

Define advisor role in the agentic os personal config, remove it from the ward product config #465

coilyco-ops commented

2026-07-11 02:30:05 +00:00

Author

Member

WARD-RESERVATION: held 🔒

reservation details

Holder: container engineer-codex-ward-911 on host KAI-DESKTOP-TOWER.

Reserved by ward agent --harness codex (reserved 2026-07-11T02:30:05Z). Concurrent ward agent runs are blocked until it finishes or the reservation goes stale (1h TTL). --force overrides.

Do not comment on or edit this issue to steer the run while it is reserved. The engineer seeded the body once at launch and never re-reads it, so a comment or edit reaches only human readers, never the running engineer. A correction goes to a new issue, dispatched fresh. That is the only channel that reaches a run in flight. Where the forge supports it, ward locks this conversation to make that a road-block rather than a convention (ward#494).

run seed context — what this run is carrying (ward#609)

Resolved: coilyco-flight-deck/ward#911 · branch issue-911 · harness codex · workflow pull-requests-and-merge
Run: engineer-codex-ward-911 · ward v0.605.0 · dispatched 2026-07-11T02:30:05Z
Comment thread: 7 included in the pre-flight read, 2 stripped (ward's own automated comments).
- included: @coilyco-ops (2026-07-10T00:54:45Z), @coilyco-ops (2026-07-10T17:36:34Z), @coilyco-ops (2026-07-10T18:11:55Z), @coilyco-ops (2026-07-10T19:30:45Z), @coilyco-ops (2026-07-10T23:32:52Z), @coilyco-ops (2026-07-10T23:49:11Z), @coilysiren (2026-07-10T23:49:47Z)
- stripped: @coilyco-ops (2026-07-10T17:18:33Z), @coilyco-ops (2026-07-10T23:19:49Z)

Static container doctrine and seed boilerplate are identical every run and omitted here (they ride ward v0.605.0).

— Codex, via ward agent

WARD-RESERVATION: held 🔒 <details><summary>reservation details</summary> Holder: container `engineer-codex-ward-911` on host `KAI-DESKTOP-TOWER`. Reserved by `ward agent --harness codex` (reserved 2026-07-11T02:30:05Z). Concurrent `ward agent` runs are blocked until it finishes or the reservation goes stale (1h TTL). `--force` overrides. **Do not comment on or edit this issue to steer the run while it is reserved.** The engineer seeded the body once at launch and never re-reads it, so a comment or edit reaches only human readers, never the running engineer. A correction goes to a **new issue, dispatched fresh**. That is the only channel that reaches a run in flight. Where the forge supports it, ward locks this conversation to make that a road-block rather than a convention (ward#494). <details><summary>run seed context — what this run is carrying (ward#609)</summary> - **Resolved:** `coilyco-flight-deck/ward#911` · branch `issue-911` · harness `codex` · workflow `pull-requests-and-merge` - **Run:** `engineer-codex-ward-911` · ward `v0.605.0` · dispatched `2026-07-11T02:30:05Z` - **Comment thread:** 7 included in the pre-flight read, 2 stripped (ward's own automated comments). - included: @coilyco-ops (2026-07-10T00:54:45Z), @coilyco-ops (2026-07-10T17:36:34Z), @coilyco-ops (2026-07-10T18:11:55Z), @coilyco-ops (2026-07-10T19:30:45Z), @coilyco-ops (2026-07-10T23:32:52Z), @coilyco-ops (2026-07-10T23:49:11Z), @coilysiren (2026-07-10T23:49:47Z) - stripped: @coilyco-ops (2026-07-10T17:18:33Z), @coilyco-ops (2026-07-10T23:19:49Z) Static container doctrine and seed boilerplate are identical every run and omitted here (they ride ward v0.605.0). </details> </details>  — Codex, via `ward agent`

coilyco-ops commented

2026-07-11 02:47:11 +00:00

Author

Member

WARD-OUTCOME: submitted

details

workflow: pull-request-and-merge; review summary: skipped (in-container review gate intentionally skipped because the temporary ward default pending brokered QA)
summary: embedded role definitions now come from ward-owned KDL defaults, with fleet overlays applied at resolve time.
felt: mechanical and low-risk.
confidence: high.
surprises: merged current main forward and trimmed docs to stay under the layout cap.
follow-ups: watch PR #1102 until the merge queue clears it.

WARD-OUTCOME: submitted <details><summary>details</summary> workflow: pull-request-and-merge; review summary: skipped (in-container review gate intentionally skipped because the temporary ward default pending brokered QA) summary: embedded role definitions now come from ward-owned KDL defaults, with fleet overlays applied at resolve time. felt: mechanical and low-risk. confidence: high. surprises: merged current main forward and trimmed docs to stay under the layout cap. follow-ups: watch PR #1102 until the merge queue clears it. </details>

coilyco-ops closed this issue

2026-07-11 02:48:25 +00:00

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

Move agent role definitions into an embedded role KDL file type #911

Problem

Goal

Do

Acceptance