Skip to content

Relationship Between OpenSpec and Agent

This document describes the relationship and architecture between the OpenSpec workflow and the agents (Agent / Manager / Worker) in Ithyno.

Agent Role and Relationship

Instead of humans manually dragging cards to advance phases, Ithyno uses an agent-driven architecture where the board displays the results of agent actions.

Board as a State Monitor

Users cannot manually drag cards between columns to change their internal phase (e.g., from coding to review). Phase transitions are written automatically by the Manager agent as it completes each step, and these updates are pushed to the Kanban board via WebSockets in real time.

Separation of Instruction Layer (OpenSpec) and State Management (Agent)

Ithyno separates the instructions given to agents from the resulting states (statuses) generated by agent execution.

  • Instruction Layer (OpenSpec Commands)
  • The layer used to instruct agents on what actions to perform. Commands (instructions) such as /opsx:propose, /opsx:apply, /opsx:archive, and /ithy-opsx:merge are issued by the user or the system.
  • Agent State Management (Execution Status)
  • The internal progress state (phase) determined as a result of the agent executing those instructions.
  • Correspondence between instructions and states:
    • Execution of propose command ───→ proposed state
    • Execution of apply command ───→ coded state
    • Result of review execution ───→ reviewed state
    • Result of verify execution ───→ done state

Separation of Interactive Escalations (needs-human)

When an agent encounters ambiguous requirements, it escalates to the needs-human state. * Ithyno (UI): The Kanban card simply displays a badge indicating the waiting status. There are no interactive dialogs or input forms on the board. * PTY (Terminal): Interactive Q&A and conversations with the agent are handled entirely inside the terminal session (e.g., Claude Code PTY). Once the user responds and the agent completes its run, it writes the phase update back to the filesystem, automatically updating the Kanban board.

Agent Startup and Dispatching (dispatch / dispatch-multi)

When a user clicks the "Start" button on the Kanban board or executes a command in the terminal, a dispatch process runs under the hood to spawn and manage agents. There are two dispatching mechanisms: dispatch for single changes and dispatch-multi for processing multiple changes in parallel.

Dispatching Mechanisms

  • Single Dispatch (/ithy-opsx:dispatch <change-id>):
  • Triggered when a user clicks "Start" on a single card in the Kanban board (or runs it from the terminal). Spawns the agent (Manager / Worker) for the specified change ID.
  • Multi-Dispatch (/ithy-opsx:dispatch-multi <id1> <id2> ...):
  • Triggered when a user inputs and executes the command directly in the PTY terminal.
  • Manages and executes agents in a concurrency pool governed by the concurrency limit (maxParallel: defaults to 10) defined in agents.yaml.

Code and Review Feedback Loop

During the agent execution cycle, a feedback loop runs between the Code Worker and the Review Worker to ensure implementation quality: * Code to Review: Once the Code Worker finishes the code implementation, the state transitions to coded, which automatically triggers the Review Worker. * Rejection (needs-rework): If the review detects issues (spec violations, bugs, etc.) and returns a needs-rework verdict, the review findings are piped back to the Code Worker, which restarts the implementation process (forming a loop). * Approval (pass): Only when the review verdict becomes pass is the phase updated to reviewed, allowing the process to advance to verification by the Verify Worker. * Preventing Infinite Loops (maxReworkRounds): If the loop reaches the maximum rework rounds limit defined in agents.yaml (maxReworkRounds: defaults to 5), the automated process halts to avoid an infinite loop and escalates to the needs-human state (or terminates).

Agent Dispatch and State Synchronization Flow

The execution cycle of worker agents (Code / Review / Verify), the resulting states (coded / reviewed / done), and how they map to the two UI layouts (Phase Board / Agent Board) are illustrated below:

graph TD
    %% UI & CLI interactions
    subgraph UI ["User Action (Ithyno UI)"]
        style UI fill:#f9f9f9,stroke:#cccccc
        UI_StartSingle["Start Button<br>(Single Card Select)"]
    end

    subgraph CLI ["Terminal Action (CLI)"]
        style CLI fill:#f5f5f5,stroke:#9e9e9e
        Term_Input["Direct Command Input"]
    end

    %% PTY Command Injection
    subgraph PtyCommand ["PTY Command Execution (Instruction Layer)"]
        style PtyCommand fill:#e1f5fe,stroke:#01579b
        Cmd_Single["/ithy-opsx:dispatch &lt;change-id&gt;"]
        Cmd_Multi["/ithy-opsx:dispatch-multi &lt;id1&gt; &lt;id2&gt; ..."]
    end

    %% Orchestrator & Agents
    subgraph AgentSystem ["Agent Execution Management (Orchestration & Workers)"]
        style AgentSystem fill:#efebe9,stroke:#3e2723
        Orchestrator["Orchestrator (Manager Loop)"]
        Pool["Concurrency Pool<br>(maxParallel control)"]

        subgraph Workers ["Worker Agent Execution Cycle"]
            Worker_Code["Worker in charge of Code<br>(Source Code Implementation)"]
            Worker_Review["Worker in charge of Review<br>(Diff Review)"]
            Worker_Verify["Worker in charge of Verify<br>(Test & Build Verification)"]
        end
    end

    %% Visualizers
    subgraph Visualizers ["Overview"]
        style Visualizers fill:#f1f8e9,stroke:#33691e

        subgraph PhaseBoard ["Phase Board"]
            Col_Todo["TODO"]
            Col_Inprogress["IN-PROGRESS (PROCESS)"]
            Col_Done["DONE"]
        end

        subgraph AgentBoard ["Agent Board"]
            Lane_Proposed["PROPOSE"]
            Lane_Coded["CODE"]
            Lane_Reviewed["REVIEW"]
            Lane_Verify["VERIFY"]
            Lane_Done["DONE"]
        end
    end

    %% Connections
    UI_StartSingle --> |Inject command| Cmd_Single
    Term_Input --> |Execute command| Cmd_Multi

    Cmd_Single --> Orchestrator
    Cmd_Multi --> Orchestrator

    Orchestrator --> |Control concurrency| Pool
    Pool --> |Spawn| Worker_Code

    %% Code <-> Review Loop
    Worker_Code --> |Coding complete: phase: coded| Worker_Review
    Worker_Review -.-> |needs-rework - Review findings loop| Worker_Code
    Worker_Review --> |pass: phase: reviewed| Worker_Verify
    Worker_Verify --> |Verification pass: phase: done| Lane_Done

    %% Mapping to Agent Board
    Worker_Code -.-> |Reflected| Lane_Coded
    Worker_Review -.-> |Reflected| Lane_Reviewed
    Worker_Verify -.-> |Reflected| Lane_Verify

    %% Agent Board to Phase Board mapping
    Lane_Proposed --> Col_Todo
    Lane_Coded --> Col_Inprogress
    Lane_Reviewed --> Col_Inprogress
    Lane_Verify --> Col_Inprogress
    Lane_Done --> Col_Done