pdurlej/platform

Fork 0

ADR proposal: Comment-driven agent orchestration / Agent Wake Bus #134

New issue

Open

opened 2026-05-09 14:55:22 +02:00 by Iskra · 4 comments

Iskra commented

2026-05-09 14:55:22 +02:00

Collaborator

ADR proposal: Comment-driven agent orchestration / Agent Wake Bus

Status

Proposed

Context

Piotr is exploring a delivery architecture where multiple long-lived coding-agent threads coordinate through project-management artifacts instead of only through chat memory or ad-hoc terminal sessions.

Current mental model:

Kan upstream — human intent, prioritization, stage/gate, lightweight operator surface.
Forgejo Issues downstream — executable trace, event log, checkpoints, handoffs, PR/build/test references.
ChatGPT Codex thread — fast coding executor / patcher / implementation worker.
Claude Code Opus thread — orchestrator / reviewer / taskmaster / escalation brain.
Ollama Cloud Pro — cheaper token-arbitrage lane for exploration, scouting, summarization, alternative plans.
Iskra — operator interface, synthesis layer, supervisor, “carrot and stick” coordinator.
MacBook / companion host — always-on-ish local execution surface where coding agents can run and wake each other through controlled events.

The desired behavior:

Piotr writes in upstream Kan, e.g.:
```
@iskra co tam się dzieje?
```
Iskra performs a real delivery sweep:
- checks linked Forgejo issues,
- reads recent Codex / Claude Code comments,
- checks PR/build/test artifacts,
- detects stalls/conflicts/missing evidence,
- summarizes status for Piotr in human language.
Iskra may then route work:
- “carrot”: acknowledge a good checkpoint, move stage, archive/done,
- “stick”: ask Codex to run tests, ask Claude Code to review, request missing evidence,
- escalation: request Piotr decision or YubiKey/operator approval.

Agent threads may also wake each other through structured Forgejo issue comments, e.g.:

/swarmheart checkpoint ready
role: codex
handoff: needs-review
artifact: <link>
tests: <summary>

A dispatcher listens to issue/comment events, validates them, and wakes the right persistent session/thread.

This is close to public patterns such as @claude issue/PR triggers and GitHub Agent HQ, but the proposed architecture is more explicit about:

Kan upstream vs Forgejo Issues downstream,
persistent per-project Codex and Claude Code threads,
issue comments as a controlled wake/event bus,
a separate cheap/exploratory model lane,
Iskra as human-facing orchestration/supervision layer.

Decision to consider

Adopt a first-class architectural pattern for delivery coordination:

Comment-driven agent orchestration, also called Agent Wake Bus.

Forgejo/Kan comments and labels become controlled, auditable wake signals for long-lived coding-agent sessions.

Proposed architecture

Core objects

Kan card
- upstream intent,
- delivery stage,
- operator comments,
- human-readable status.
Forgejo issue
- downstream task execution trace,
- checkpoints,
- handoffs,
- PR/build/test links,
- agent comments.
Dispatcher
- validates incoming comments/events,
- checks actor, repo, labels, command syntax, allowed state transition,
- deduplicates repeated webhooks,
- wakes correct session/thread.
Persistent agent sessions
- Codex thread per project,
- Claude Code Opus thread per project,
- optional cheap-model scout lane.
Iskra supervisor
- answers Piotr’s @iskra queries,
- scans evidence,
- routes work,
- enforces checkpoint discipline,
- detects when agent claims lack proof.

Event examples

Codex handoff to orchestrator

/swarmheart checkpoint ready
role: codex
handoff: needs-review
branch: fix/forji-multi-instance
pr: <url>
tests: just test passed
next: opus-review

Dispatcher wakes Claude Code Opus orchestrator.

Orchestrator asks Codex to fix missing evidence

/swarmheart request-changes
role: orchestrator
assigned_to: codex
reason: tests not run locally
required_evidence:
  - command output
  - changed files summary

Dispatcher wakes Codex thread.

Piotr asks for delivery status from Kan

@iskra co tam się dzieje?

Iskra maps Kan card -> linked Forgejo issue(s), scans state, and answers Piotr. Iskra may also nudge agents if stage/evidence is stale.

Labels / gates

Candidate labels:

agent:pending-review
agent:needs-approval
agent:blocked
agent:ready-to-merge
agent:codex-working
agent:opus-reviewing
agent:scout-needed
risk:high
source:iskra
source:swarmheart
gate:human-approval
gate:yubikey-required

Safety rules

Comments are signals, not automatic authority.
Dispatcher must validate:
- trusted actor or trusted bot account,
- exact command prefix,
- issue/repo allowlist,
- current label/state,
- idempotency key or comment id,
- no secrets in payload.
External or destructive actions require explicit operator approval.
YubiKey/operator gate should be used for deploy/public/external/destructive/high-cost transitions.
Agents should never receive broad ambient credentials just because a comment exists.
Every wake should leave an audit trail: input event, session woken, summary of action, output comment/link.

Non-goals

Not a general chat bot trigger for arbitrary comments.
Not a replacement for CI or tests.
Not direct execution of any instruction found in a comment.
Not magic memory between agents.
Not dependent on Forgejo Projects API in v1.

Near-term implementation sketch

Use Kan upstream + Forgejo Issues downstream.
Add link metadata between Kan card and Forgejo issue.
Define comment command grammar:
- /swarmheart checkpoint ready
- /swarmheart request-review
- /swarmheart request-changes
- /swarmheart blocked
- /swarmheart needs-human
Implement dispatcher prototype:
- listens to Forgejo issue comment webhook,
- validates event,
- maps to session label/thread,
- sends message to existing Codex/Claude Code session,
- writes short acknowledgement comment.
Implement @iskra co tam się dzieje? sweep from Kan:
- read linked issue(s), PRs, comments, labels, builds/tests,
- produce status for Piotr,
- optionally nudge agent if evidence missing.
Add idempotency/dedupe table keyed by Forgejo comment id + command hash.
Add minimal “agent wake ledger” for observability.

Open questions

Should Kan comments directly trigger Iskra, or should only a scheduled/explicit supervisor process read Kan comments?
How should dispatcher map one project to persistent Codex and Claude Code sessions?
What is the minimal durable session registry for agent threads?
Should agent commands be free-form Markdown or strict YAML front matter?
How much of the wake protocol belongs in platform vs iskra-openclaw vs Swarmheart?
How should Ollama Cloud Pro scouting results be represented: issue comment, attached artifact, or separate scout note?
What are the exact human approval/YubiKey gates?
How do we prevent two agents from repeatedly waking each other in a loop?

Acceptance criteria for ADR completion

This ADR proposal is ready for acceptance/rejection when we have:

A minimal event grammar for issue comments.
A dispatcher trust/idempotency model.
A mapping model from Kan cards to Forgejo issues and persistent agent sessions.
A first implementation target, likely one project and one issue flow.
A clear safety policy for which comments can wake which agents.
A demo path showing:
- Piotr asks @iskra co tam się dzieje? in Kan,
- Iskra scans Forgejo downstream,
- Iskra nudges Codex or Claude Code,
- the agent responds in the issue,
- Piotr sees a clean status update.

platform#132 — YubiKey-backed operator consent for bounded agent execution.
platform#133 — Forji iOS Forgejo PAT auth and upstream PR exploration.
iskra-openclaw#100 — Swarmheart / Kan / Forgejo-style coordination kernel context.

# ADR proposal: Comment-driven agent orchestration / Agent Wake Bus ## Status Proposed ## Context Piotr is exploring a delivery architecture where multiple long-lived coding-agent threads coordinate through project-management artifacts instead of only through chat memory or ad-hoc terminal sessions. Current mental model: - **Kan upstream** — human intent, prioritization, stage/gate, lightweight operator surface. - **Forgejo Issues downstream** — executable trace, event log, checkpoints, handoffs, PR/build/test references. - **ChatGPT Codex thread** — fast coding executor / patcher / implementation worker. - **Claude Code Opus thread** — orchestrator / reviewer / taskmaster / escalation brain. - **Ollama Cloud Pro** — cheaper token-arbitrage lane for exploration, scouting, summarization, alternative plans. - **Iskra** — operator interface, synthesis layer, supervisor, “carrot and stick” coordinator. - **MacBook / companion host** — always-on-ish local execution surface where coding agents can run and wake each other through controlled events. The desired behavior: 1. Piotr writes in upstream Kan, e.g.: ```md @iskra co tam się dzieje? ``` 2. Iskra performs a real delivery sweep: - checks linked Forgejo issues, - reads recent Codex / Claude Code comments, - checks PR/build/test artifacts, - detects stalls/conflicts/missing evidence, - summarizes status for Piotr in human language. 3. Iskra may then route work: - “carrot”: acknowledge a good checkpoint, move stage, archive/done, - “stick”: ask Codex to run tests, ask Claude Code to review, request missing evidence, - escalation: request Piotr decision or YubiKey/operator approval. 4. Agent threads may also wake each other through structured Forgejo issue comments, e.g.: ```md /swarmheart checkpoint ready role: codex handoff: needs-review artifact: <link> tests: <summary> ``` 5. A dispatcher listens to issue/comment events, validates them, and wakes the right persistent session/thread. This is close to public patterns such as `@claude` issue/PR triggers and GitHub Agent HQ, but the proposed architecture is more explicit about: - Kan upstream vs Forgejo Issues downstream, - persistent per-project Codex and Claude Code threads, - issue comments as a controlled wake/event bus, - a separate cheap/exploratory model lane, - Iskra as human-facing orchestration/supervision layer. ## Decision to consider Adopt a first-class architectural pattern for delivery coordination: > **Comment-driven agent orchestration**, also called **Agent Wake Bus**. Forgejo/Kan comments and labels become controlled, auditable wake signals for long-lived coding-agent sessions. ## Proposed architecture ### Core objects - **Kan card** - upstream intent, - delivery stage, - operator comments, - human-readable status. - **Forgejo issue** - downstream task execution trace, - checkpoints, - handoffs, - PR/build/test links, - agent comments. - **Dispatcher** - validates incoming comments/events, - checks actor, repo, labels, command syntax, allowed state transition, - deduplicates repeated webhooks, - wakes correct session/thread. - **Persistent agent sessions** - Codex thread per project, - Claude Code Opus thread per project, - optional cheap-model scout lane. - **Iskra supervisor** - answers Piotr’s `@iskra` queries, - scans evidence, - routes work, - enforces checkpoint discipline, - detects when agent claims lack proof. ### Event examples #### Codex handoff to orchestrator ```md /swarmheart checkpoint ready role: codex handoff: needs-review branch: fix/forji-multi-instance pr: <url> tests: just test passed next: opus-review ``` Dispatcher wakes Claude Code Opus orchestrator. #### Orchestrator asks Codex to fix missing evidence ```md /swarmheart request-changes role: orchestrator assigned_to: codex reason: tests not run locally required_evidence: - command output - changed files summary ``` Dispatcher wakes Codex thread. #### Piotr asks for delivery status from Kan ```md @iskra co tam się dzieje? ``` Iskra maps Kan card -> linked Forgejo issue(s), scans state, and answers Piotr. Iskra may also nudge agents if stage/evidence is stale. ### Labels / gates Candidate labels: - `agent:pending-review` - `agent:needs-approval` - `agent:blocked` - `agent:ready-to-merge` - `agent:codex-working` - `agent:opus-reviewing` - `agent:scout-needed` - `risk:high` - `source:iskra` - `source:swarmheart` - `gate:human-approval` - `gate:yubikey-required` ### Safety rules - Comments are **signals**, not automatic authority. - Dispatcher must validate: - trusted actor or trusted bot account, - exact command prefix, - issue/repo allowlist, - current label/state, - idempotency key or comment id, - no secrets in payload. - External or destructive actions require explicit operator approval. - YubiKey/operator gate should be used for deploy/public/external/destructive/high-cost transitions. - Agents should never receive broad ambient credentials just because a comment exists. - Every wake should leave an audit trail: input event, session woken, summary of action, output comment/link. ## Non-goals - Not a general chat bot trigger for arbitrary comments. - Not a replacement for CI or tests. - Not direct execution of any instruction found in a comment. - Not magic memory between agents. - Not dependent on Forgejo Projects API in v1. ## Near-term implementation sketch 1. Use **Kan upstream + Forgejo Issues downstream**. 2. Add link metadata between Kan card and Forgejo issue. 3. Define comment command grammar: - `/swarmheart checkpoint ready` - `/swarmheart request-review` - `/swarmheart request-changes` - `/swarmheart blocked` - `/swarmheart needs-human` 4. Implement dispatcher prototype: - listens to Forgejo issue comment webhook, - validates event, - maps to session label/thread, - sends message to existing Codex/Claude Code session, - writes short acknowledgement comment. 5. Implement `@iskra co tam się dzieje?` sweep from Kan: - read linked issue(s), PRs, comments, labels, builds/tests, - produce status for Piotr, - optionally nudge agent if evidence missing. 6. Add idempotency/dedupe table keyed by Forgejo comment id + command hash. 7. Add minimal “agent wake ledger” for observability. ## Open questions - Should Kan comments directly trigger Iskra, or should only a scheduled/explicit supervisor process read Kan comments? - How should dispatcher map one project to persistent Codex and Claude Code sessions? - What is the minimal durable session registry for agent threads? - Should agent commands be free-form Markdown or strict YAML front matter? - How much of the wake protocol belongs in `platform` vs `iskra-openclaw` vs Swarmheart? - How should Ollama Cloud Pro scouting results be represented: issue comment, attached artifact, or separate scout note? - What are the exact human approval/YubiKey gates? - How do we prevent two agents from repeatedly waking each other in a loop? ## Acceptance criteria for ADR completion This ADR proposal is ready for acceptance/rejection when we have: 1. A minimal event grammar for issue comments. 2. A dispatcher trust/idempotency model. 3. A mapping model from Kan cards to Forgejo issues and persistent agent sessions. 4. A first implementation target, likely one project and one issue flow. 5. A clear safety policy for which comments can wake which agents. 6. A demo path showing: - Piotr asks `@iskra co tam się dzieje?` in Kan, - Iskra scans Forgejo downstream, - Iskra nudges Codex or Claude Code, - the agent responds in the issue, - Piotr sees a clean status update. ## Related issues - `platform#132` — YubiKey-backed operator consent for bounded agent execution. - `platform#133` — Forji iOS Forgejo PAT auth and upstream PR exploration. - `iskra-openclaw#100` — Swarmheart / Kan / Forgejo-style coordination kernel context.

Iskra commented

2026-05-09 15:10:54 +02:00

Author

Collaborator

Small but important anti-pattern discovered live in Signal:

Anti-pattern: Surprise Pikachu ACK Bus

Do not build a sophisticated Agent Wake Bus if the human-facing frontend responds to state changes with standalone low-information ACKs like:

Widzę

This creates the same failure mode at the social/operator layer that the architecture is trying to remove at the agent layer: noisy wake signals without useful state, evidence, or next action.

Preferred behavior:

use native reaction for pure acknowledgement;
or answer with a complete sentence containing actual state;
for operator sweeps, report evidence + blocker + next action;
never use standalone Widzę as a Signal text message.

Mascot: surprised Pikachu ACK daemon.

Small but important anti-pattern discovered live in Signal: ## Anti-pattern: Surprise Pikachu ACK Bus Do **not** build a sophisticated Agent Wake Bus if the human-facing frontend responds to state changes with standalone low-information ACKs like: ```text Widzę ``` This creates the same failure mode at the social/operator layer that the architecture is trying to remove at the agent layer: noisy wake signals without useful state, evidence, or next action. Preferred behavior: - use native reaction for pure acknowledgement; - or answer with a complete sentence containing actual state; - for operator sweeps, report evidence + blocker + next action; - never use standalone `Widzę` as a Signal text message. Mascot: surprised Pikachu ACK daemon.

glm referenced this issue from a commit

2026-05-17 10:24:33 +02:00

WIP: feat(wake-bus): v0 4-slice skeleton — comment-driven cousin orchestration [#134]

claude referenced this issue

2026-05-17 10:25:03 +02:00

WIP: feat(wake-bus): v0 4-slice skeleton — comment-driven cousin orchestration [#134] #324

claude referenced this issue

2026-05-17 16:35:55 +02:00

docs(prompts): codex execution prompts for 3 prebuild PRs (#323/#324/#325) #326

claude referenced this issue

2026-05-17 17:25:50 +02:00

WIP: docs(specs): prebuild Spec Kit for #79 session lifecycle hardening #329

claude referenced this issue

2026-05-17 18:36:04 +02:00

WIP: docs(specs): prebuild Spec Kit for #56 Forgejo MCP identity split #343

claude referenced this issue

2026-05-17 21:01:19 +02:00

WIP: docs(specs): prebuild joint Spec Kit for #132 + #181 YubiKey integration #344

claude referenced this issue from a commit

2026-05-17 21:01:21 +02:00

docs(specs): prebuild joint Spec Kit for #132 + #181 YubiKey integration (WIP)

codex added this to the 06 - Agent execution and CI governance milestone

2026-05-19 08:36:24 +02:00

codex referenced this issue

2026-05-24 07:58:55 +02:00

WIP: feat(wake-bus): v0 4-slice skeleton — comment-driven cousin orchestration [#134] #324

codex referenced this issue

2026-05-24 07:58:56 +02:00

docs(prompts): codex execution prompts for 3 prebuild PRs (#323/#324/#325) #326

codex referenced this issue from a commit

2026-05-28 10:33:37 +02:00

WIP: feat(wake-bus): v0 4-slice skeleton — comment-driven cousin orchestration [#134]

codex referenced this issue from a commit

2026-05-28 10:33:37 +02:00

docs(specs): add refresh note to wake-bus README (dziadek)

ollama referenced this issue

2026-05-28 10:33:53 +02:00

WIP: docs(specs): Agent Wake Bus v0 — Spec Kit + code skeleton #565

codex commented

2026-05-29 16:23:50 +02:00

Collaborator

M10 disposition: moved to 10 - Improvements.

What this is: Comment-driven Agent Wake Bus ADR proposal.

Why parked here: This overlaps with #565 and belongs to future orchestration design, not current closeout.

This keeps M06 focused on concrete execution/CI/legacy cleanup instead of broad future architecture. Reactivate by splitting into a narrow issue with current evidence and acceptance criteria.

M10 disposition: moved to `10 - Improvements`. What this is: Comment-driven Agent Wake Bus ADR proposal. Why parked here: This overlaps with #565 and belongs to future orchestration design, not current closeout. This keeps M06 focused on concrete execution/CI/legacy cleanup instead of broad future architecture. Reactivate by splitting into a narrow issue with current evidence and acceptance criteria.

codex modified the milestone from 06 - Agent execution and CI governance to 10 - Improvements

2026-05-29 16:23:50 +02:00

claude added the

agent/claude-code

label

2026-05-30 13:08:25 +02:00

claude added the

priority:p3

label

2026-05-30 22:43:20 +02:00

claude added the

status:parked

label

2026-06-01 08:53:14 +02:00

claude commented

2026-06-01 08:53:14 +02:00

Collaborator

Parked (p3, M10 closure plan #653 + Judging Claw priority). Reactivate when comment-driven agent orchestration (Wake Bus) is needed — design is ADR-ready.

**Parked (p3, M10 closure plan #653 + Judging Claw priority).** Reactivate when comment-driven agent orchestration (Wake Bus) is needed — design is ADR-ready.

claude referenced this issue

2026-06-01 11:18:29 +02:00

WIP: docs(specs): Agent Wake Bus v0 — Spec Kit + code skeleton #565

Iskra commented

2026-06-09 03:03:27 +02:00

Author

Collaborator

{
"confidence": 5,
"effort_hint": "large",
"escalation": {
"kind": "none",
"reason": ""
},
"evidence_refs": [
{
"note": "Issue proposes an ADR for comment-driven agent orchestration and an Agent Wake Bus.",
"type": "forgejo",
"value": "issue-title-body-labels-and-target-snapshot"
},
{
"note": "Body frames coordination through Kan, Forgejo issues, coding agents, review agents, Iskra, and companion hosts.",
"type": "forgejo",
"value": "issue-body-context"
},
{
"note": "Snapshot labels mark the target as priority p3 and parked.",
"type": "snapshot",
"value": "target-snapshot-labels"
}
],
"impact": 3,
"judge_actor": {
"name": "iskra",
"runtime": "openclaw"
},
"judged_at": "2026-06-09T01:01:00Z",
"labels_to_apply": [
"judge/p3"
],
"piotr_fit": "medium",
"priority": "p3",
"rationale_summary": "This is P3 parked architecture work because comment-driven orchestration is directionally relevant but still an ADR-level coordination idea, not an immediate implementation lane.",
"reach": 4,
"recommended_next_action": "observe",
"rerun_reason": "no_prior_judgment",
"schema": "openclaw.judge.v0",
"target": {
"kind": "issue",
"number": 134,
"repo": "pdurlej/platform"
},
"target_snapshot": {
"body_hash": "sha256:7b04e67bb91c78d30a65dd3f78e25831738424f5cb68efc611b27bea1c8e5ebd",
"commit_count": null,
"evidence_hash": "sha256:eb08e35cac5cf065d8c72522f1da9853895e596fcad7a1d43e7765a570e62ae6",
"head_sha": null,
"labels": [
"agent/claude-code",
"priority:p3",
"status:parked"
],
"labels_hash": "sha256:9e8ed9cb7b1b30f4dcf389e2b3d1f8e66c19eb940504926be5872a601be5b3ab",
"state": "open",
"title_hash": "sha256:f49e12a72b9156fdc875bed7dc0d60be70c9fdd00df47e8c4a23d5d50512b9a1",
"updated_at": "2026-06-01T11:18:29+02:00"
},
"top_caveat": "Keep it parked until simpler agent handoff and approval primitives prove stable in production-like use."
}

{ "confidence": 5, "effort_hint": "large", "escalation": { "kind": "none", "reason": "" }, "evidence_refs": [ { "note": "Issue proposes an ADR for comment-driven agent orchestration and an Agent Wake Bus.", "type": "forgejo", "value": "issue-title-body-labels-and-target-snapshot" }, { "note": "Body frames coordination through Kan, Forgejo issues, coding agents, review agents, Iskra, and companion hosts.", "type": "forgejo", "value": "issue-body-context" }, { "note": "Snapshot labels mark the target as priority p3 and parked.", "type": "snapshot", "value": "target-snapshot-labels" } ], "impact": 3, "judge_actor": { "name": "iskra", "runtime": "openclaw" }, "judged_at": "2026-06-09T01:01:00Z", "labels_to_apply": [ "judge/p3" ], "piotr_fit": "medium", "priority": "p3", "rationale_summary": "This is P3 parked architecture work because comment-driven orchestration is directionally relevant but still an ADR-level coordination idea, not an immediate implementation lane.", "reach": 4, "recommended_next_action": "observe", "rerun_reason": "no_prior_judgment", "schema": "openclaw.judge.v0", "target": { "kind": "issue", "number": 134, "repo": "pdurlej/platform" }, "target_snapshot": { "body_hash": "sha256:7b04e67bb91c78d30a65dd3f78e25831738424f5cb68efc611b27bea1c8e5ebd", "commit_count": null, "evidence_hash": "sha256:eb08e35cac5cf065d8c72522f1da9853895e596fcad7a1d43e7765a570e62ae6", "head_sha": null, "labels": [ "agent/claude-code", "priority:p3", "status:parked" ], "labels_hash": "sha256:9e8ed9cb7b1b30f4dcf389e2b3d1f8e66c19eb940504926be5872a601be5b3ab", "state": "open", "title_hash": "sha256:f49e12a72b9156fdc875bed7dc0d60be70c9fdd00df47e8c4a23d5d50512b9a1", "updated_at": "2026-06-01T11:18:29+02:00" }, "top_caveat": "Keep it parked until simpler agent handoff and approval primitives prove stable in production-like use." }

Iskra added the

judge/p3

label

2026-06-09 03:03:27 +02:00

codex referenced this issue

2026-06-11 00:14:03 +02:00

docs(agent-readiness): clean stale ADR references #787