Plan: Create automation structure that combines agents and workflows

[geoffjay]

TODO

[geoffjay]

🔬 Research Findings: Automation Structure Combining Agents and Workflows

Summary

The agentd project already has a mature, composable automation structure: 14 agent definitions, 12 workflow definitions, 4 room templates, and 2 ad-hoc prompt templates — all under .agentd/ and applied via agent apply .agentd/. The key gap is not the individual pieces but the lack of a higher-level "automation" abstraction that declaratively composes agents + workflows into named, multi-step pipelines. Today, the pipeline behavior lives implicitly in the conductor agent's system prompt and in GitHub label conventions, not in a portable, versionable configuration.

Key Findings

1. Current structure is three independent layers with convention-based coupling

   The .agentd/ directory has three peer subdirectories:

   .agentd/
     rooms/       → 4 templates (engineering, operations, announcements, security)
     agents/      → 14 templates (worker, planner, reviewer, conductor, research, etc.)
     workflows/   → 12 templates (issue-worker, plan-worker, pull-request-reviewer, etc.)
   

   Each workflow references an agent by name (resolved to UUID at apply-time), and the apply order is rooms → agents → workflows (crates/cli/src/commands/apply.rs:781-893). However, there is no declarative way to define "this set of agents + workflows constitutes a named automation" — e.g., "the code-review automation uses the reviewer agent + pull-request-reviewer workflow + the engineering room."

2. The pipeline is implicit, not declarative

   The autonomous development pipeline (triage → enrich → implement → review → merge → docs) exists as:

   • A state machine documented in docs/public/pipeline-state-machine.md
   • Label dispatch mappings hard-coded in the conductor agent's system prompt (.agentd/agents/conductor.yml:51-61)
   • Convention: each label maps to exactly one workflow, which dispatches to exactly one agent

   This works but is fragile — the pipeline topology is spread across 12+ YAML files and a long system prompt rather than expressed as a single, reviewable definition.

3. Workflow chaining infrastructure exists but is unused

   The DispatchResult trigger type in crates/orchestrator/src/scheduler/types.rs:96-105 enables workflow-A-completes → workflow-B-starts chaining. The EventStrategy with EventFilter::DispatchResult is fully implemented and tested in crates/orchestrator/src/scheduler/strategy.rs:382-495 with comprehensive test coverage (5 tests). However, no existing workflow YAML uses this trigger type. Issue Add workflow chaining support - dispatch_result trigger type #641 tracks wiring it into the pipeline.

4. The templates/ directory serves a different purpose

   .agentd/templates/ currently holds ad-hoc prompt templates (project-wide-plan.yml, user-interface-plan.yml) that are standalone prompts, not composable automation definitions. These are one-shot "run this prompt against the codebase" instructions, not part of the agent-workflow composition system.

5. Missing: a "pipeline" or "automation" top-level abstraction

   What does not exist today:

   • A declarative way to define "Pipeline X consists of stages [A, B, C] where A triggers B via dispatch_result and B triggers C"
   • A way to express conditional branching (reviewer approves → merge; reviewer requests changes → rework loop)
   • A way to group agents + workflows + rooms into a named, portable "automation pack" that can be applied or torn down as a unit
   • A way for the conductor to read pipeline topology from configuration rather than from its system prompt

6. The conductor agent is the de facto pipeline engine

   The conductor (.agentd/agents/conductor.yml) manages:

   • Pipeline state transitions via label mutations
   • Merge queue ordering via git-spice stack analysis
   • Conflict escalation to the engineering room
   • Stale work detection
   • Status digests

   This is currently implemented entirely as a system prompt (~260 lines of instructions), with no corresponding workflow definition. The conductor has no automated trigger — it appears to be run manually or on a schedule that isn't declared in the workflow templates.

Recommendations

1. Relabel this issue plan-agent so the planner can design a concrete "automation" or "pipeline" YAML schema that:

   • Groups related agents, workflows, and rooms into named automations
   • Declaratively specifies stage ordering and chaining (using dispatch_result)
   • Supports conditional transitions (approve → merge vs. request-changes → rework)
   • Is applied/torn down atomically via agent apply

2. Prerequisite: Issue Add workflow chaining support - dispatch_result trigger type #641 (workflow chaining) should be implemented first, since the dispatch_result trigger is the mechanism that makes multi-stage pipelines work without relying on label-polling alone.

3. Consider a pipelines/ subdirectory under .agentd/:

   # .agentd/pipelines/autonomous-dev.yml
   name: autonomous-development
   description: "End-to-end issue lifecycle automation"
   stages:
     - name: triage
       workflow: plan-worker
       triggers_on: label(needs-triage)
       on_complete: enrich
     - name: enrich
       workflow: enrichment-worker
       triggers_on: dispatch_result(triage)
       on_complete: implement
     - name: implement
       workflow: issue-worker
       triggers_on: dispatch_result(enrich)
       on_complete: review
     - name: review
       workflow: pull-request-reviewer
       triggers_on: dispatch_result(implement)
       on_complete:
         approved: merge
         changes_requested: rework
     # ...

   This would make the pipeline topology explicit, reviewable, and versionable — rather than implicit in the conductor's system prompt.

4. Create a conductor workflow — today the conductor has an agent definition but no workflow trigger. Adding a cron-triggered conductor-sync workflow (e.g., every 15 minutes) would close this gap and make the pipeline fully self-driving.

Open Questions

• Should the "automation" abstraction replace the conductor's label-dispatch logic, or complement it? The conductor currently handles nuanced decisions (merge ordering, conflict escalation) that may not fit neatly into a declarative pipeline. It may be better to keep the conductor as a stateful agent and use the pipeline YAML only for the happy-path transitions. — blocked on: architectural decision from project owner
• How should conditional branching work in the YAML schema? The reviewer can produce 3 outcomes (approve, request changes, comment-only), and the rework loop can iterate multiple times. A simple linear pipeline doesn't capture this. — blocked on: design spike for pipeline schema
• Should pipelines be first-class in the orchestrator (new DB table, API endpoints) or purely a CLI/template concept that generates individual workflows? — blocked on: scope decision (MVP vs. full feature)

References

• .agentd/agents/conductor.yml — pipeline state machine and dispatch logic in system prompt
• .agentd/workflows/ — all 12 workflow definitions showing the current label-dispatch pattern
• docs/public/pipeline-state-machine.md — documented pipeline states and transitions
• crates/orchestrator/src/scheduler/types.rs:56-113 — TriggerConfig enum including DispatchResult
• crates/orchestrator/src/scheduler/strategy.rs:373-495 — EventFilter::DispatchResult implementation
• crates/orchestrator/src/scheduler/events.rs — EventBus and SystemEvent types
• crates/cli/src/commands/apply.rs:779-893 — composite apply_directory implementation
• Add workflow chaining support - dispatch_result trigger type #641 — "Add workflow chaining support - dispatch_result trigger type"
• End-to-end PoC: run one issue through the full autonomous pipeline #647 — "End-to-end PoC: run one issue through the full autonomous pipeline"
• Add merge automation - CI verification and git spice merge commands for conductor #644 — "Add merge automation - CI verification and git spice merge commands for conductor"
• Document the autonomous pipeline architecture and state machine #646 — "Document the autonomous pipeline architecture and state machine"

[geoffjay]

🔬 Research Findings Update: Automation Structure — Current State Assessment

Summary

Since the original research (above), significant progress has been made: issue #641 (workflow chaining via dispatch_result) is now closed, two chain workflows exist, a conductor-sync cron heartbeat is deployed, and the workflow count has grown from 12 to 18. The core gap identified in the original research — no higher-level "automation" or "pipeline" abstraction — remains, but the urgency has increased: the chain workflows ship enabled: false and require manual post-deploy API patching to wire up source_workflow_id, which is a fragile deployment experience that a pipeline abstraction would eliminate.

Key Findings

1. dispatch_result chaining is implemented but requires manual wiring

   Two chain workflows now use the trigger:

   • .agentd/workflows/triage-enrich-chain.yml — triage completion → enrich
   • .agentd/workflows/review-merge-chain.yml — review completion → merge-ready

   Both ship enabled: false with source_workflow_id commented out. The documented setup requires:

   1. Deploy all workflows via agent apply
   2. Look up the upstream workflow's UUID manually
   3. Patch source_workflow_id via a curl -X PATCH call to the API
   4. Enable the workflow

   This 4-step post-deploy dance is the exact problem a pipeline abstraction would solve — it should be a single declarative definition that agent apply resolves automatically.

2. Current automation inventory (18 workflows, 14 agents, 4 rooms)

   Trigger Type	Count	Workflows
   github_issues	10	triage-worker, enrichment-worker, issue-worker, plan-worker, research-worker, docs-worker, design-worker, refactor-worker, security-worker, test-worker
   github_pull_requests	2	pull-request-reviewer, merge-worker
   cron	3	conductor-sync (*/5), security-audit, refactor-review
   dispatch_result	2	triage-enrich-chain, review-merge-chain
   github_issues (manual)	1	conductor-sync-manual

   New since original research: conductor-sync, conductor-sync-manual, design-worker, merge-worker, test-worker, triage-enrich-chain, review-merge-chain, security-audit.

3. The conductor-sync workflow closes the "no conductor trigger" gap

   The original research noted the conductor had no automated trigger. This is now solved:

   • conductor-sync.yml — cron every 5 minutes, runs a comprehensive 10-step pipeline sync
   • conductor-sync-manual.yml — label-triggered for on-demand sync via conductor-sync label

   The conductor-sync prompt is ~260 lines covering: repo sync, triage, dispatch, review nudge, promote, merge, re-dispatch rework, stale detection, status digest, and state persistence to memory. This is effectively the pipeline engine expressed as a prompt template.

4. Three implicit pipeline paths exist today

   Tracing the label-dispatch and chain-trigger paths reveals three distinct automation pipelines:

   Pipeline A: Issue Lifecycle (happy path)

   unlabelled issue → [conductor-sync] needs-triage
     → [triage-worker] triaged
     → [triage-enrich-chain] enrich-agent
     → [enrichment-worker] agent
     → [issue-worker] → creates PR with review-agent label
     → [pull-request-reviewer] → approved
     → [review-merge-chain] merge-ready
     → [merge-worker] → merged
   

   Pipeline B: Rework Loop

   PR with changes_requested → [conductor-sync] needs-rework
     → [conductor-sync] re-applies agent to linked issue
     → [issue-worker] → creates updated PR
     → [pull-request-reviewer] → re-review
   

   Pipeline C: Specialized Dispatch

   triaged issue → [conductor-sync] applies specialized label
     → plan-agent → [plan-worker]
     → docs-agent → [docs-worker]
     → research-agent → [research-worker]
     → design-agent → [design-worker]
     → refactor-agent → [refactor-worker]
     → test-agent → [test-worker]
     → security-agent → [security-worker]
   

   None of these pipelines are expressed as a single reviewable definition. They exist as emergent behavior from 18 individual workflow files and the conductor's prompt.

5. The apply_directory function has no pipeline-aware ordering

   crates/cli/src/commands/apply.rs:861 applies in directory order (rooms → agents → workflows). It has no awareness of chain dependencies — it cannot auto-wire source_workflow_id for dispatch_result workflows because the upstream workflow UUID isn't known until after creation.

Recommendations

1. Relabel this issue plan-agent to design a pipeline YAML schema. The minimum viable schema should:

   • Define named stages with explicit ordering
   • Auto-resolve source_workflow_id references by workflow name (not UUID)
   • Enable chain workflows automatically after wiring
   • Be applied atomically via agent apply .agentd/pipelines/

2. Proposed pipeline schema (building on original research suggestion, updated for current state):

   # .agentd/pipelines/issue-lifecycle.yml
   name: issue-lifecycle
   description: "End-to-end issue automation: triage → enrich → implement → review → merge"
   
   stages:
     - name: triage
       workflow: triage-worker
       entry: label(needs-triage)
   
     - name: enrich
       workflow: enrichment-worker
       after: triage                    # auto-wires dispatch_result chain
       chain_agent: conductor           # which agent runs the chain transition
   
     - name: implement
       workflow: issue-worker
       after: enrich
       chain_agent: conductor
   
     - name: review
       workflow: pull-request-reviewer
       entry: label(review-agent)       # entered via PR creation, not chain
   
     - name: merge
       workflow: merge-worker
       after: review
       chain_agent: conductor
       conditions:
         approved: true
         ci: passed
   
   on_failure:
     changes_requested: rework          # loops back
     ci_failed: notify(operations)
   
   rework:
     workflow: issue-worker
     entry: label(needs-rework)
     after_complete: review             # re-enters review stage

3. Implementation approach: The apply_directory function should:

   • Parse pipeline YAML files from .agentd/pipelines/
   • Apply stages in order, collecting created workflow UUIDs
   • Auto-patch source_workflow_id on chain workflows using the upstream workflow's UUID
   • Enable chain workflows after wiring
   • This eliminates the manual 4-step post-deploy process entirely

4. Keep the conductor-sync as the fallback engine — the pipeline abstraction should handle the happy-path linear progression, while conductor-sync continues handling edge cases (stale detection, nudges, conflict escalation) that don't fit a declarative model.

Open Questions

• Should pipelines be first-class in the orchestrator (DB table + API) or CLI-only? If CLI-only, the pipeline definition is just syntactic sugar that generates individual workflow creates + patches. If first-class, the orchestrator tracks pipeline state, which enables observability (e.g., "show me where issue Extend agent templates with room configuration #500 is in the pipeline"). — blocked on: scope decision from project owner
• How should the rework loop iteration limit work? The current system has no guard against infinite rework cycles (reviewer rejects → worker reworks → reviewer rejects again → ...). Should the pipeline schema support max_iterations: 3? — blocked on: design decision
• Should chain workflows remain separate YAML files or be generated from pipeline definitions? If generated, the current triage-enrich-chain.yml and review-merge-chain.yml become implementation details, not user-authored files. — blocked on: pipeline schema design

References

• .agentd/workflows/triage-enrich-chain.yml — dispatch_result chain with manual UUID wiring
• .agentd/workflows/review-merge-chain.yml — dispatch_result chain with manual UUID wiring
• .agentd/workflows/conductor-sync.yml — 5-minute cron pipeline heartbeat (new since original research)
• .agentd/workflows/conductor-sync-manual.yml — label-triggered manual sync
• .agentd/workflows/merge-worker.yml — new merge automation workflow
• crates/cli/src/commands/apply.rs:861 — apply_directory function (no pipeline awareness)
• crates/orchestrator/src/scheduler/types.rs — TriggerConfig including DispatchResult
• Add workflow chaining support - dispatch_result trigger type #641 — workflow chaining (now closed — prerequisite satisfied)
• Original research comment above — foundational analysis still valid