🚀

specs/agent-workflow.md

@@ -0,0 +1,64 @@
+# Specification: The Chronicle (agent-workflow)
+
+## 1. Overview
+**The Chronicle** is a temporal orchestration extension for the Pi Coding Agent. It enables long-running, state-aware workflows that span multiple sessions and personas. Unlike traditional linear agents, The Chronicle manages a formal **State Machine** where each stage of a project is handled by a specialized agent persona, with the extension acting as a persistent "State Supervisor."
+
+## 2. Core Architecture
+
+### 2.1 The Supervisor Model
+The Chronicle operates as a non-working supervisor that delegates tasks to worker agents.
+- **The Ledger**: A persistent JSON file (`.pi/chronicle/sessions/<uuid>.json`) that tracks the project state, file snapshots, and transition history.
+- **State Isolation**: Each state is executed by a fresh Pi sub-agent process with a specialized system prompt, preventing "persona leakage" and ensuring clean tool contexts.
+- **Context Handover**: When transitioning, the Supervisor extracts a "Snapshot" (modified files, key discoveries, pending tasks) and injects it into the next agent's starting context.
+
+### 2.2 Workflow Definition
+Workflows are defined in JSON templates:
+```json
+{
+  "name": "Feature Implementation",
+  "states": {
+    "planning": {
+      "persona": "Software Architect",
+      "next": ["implementation"],
+      "requires_approval": true
+    },
+    "implementation": {
+      "persona": "Senior Engineer",
+      "next": ["verification", "planning"]
+    }
+  }
+}
+```
+
+## 3. Key Mechanisms
+
+### 3.1 Explicit Transitions
+To ensure reliability, transitions are **explicit**. The agent must call a tool to signal completion:
+- `workflow_transition(target_state, summary)`: Finalizes the current state, saves the snapshot, and triggers the supervisor to spawn the next agent.
+- `workflow_update_snapshot(data)`: Allows agents to "checkpoint" critical findings (e.g., "The API port is 8081, not 8080") that must persist through the entire workflow.
+
+### 3.2 Temporal Persistence
+- **Checkpointing**: Every tool call and state change is logged to the Ledger.
+- **Recovery**: If a session is interrupted (e.g., power loss, manual exit), the extension can resume exactly where it left off by reading the Ledger and re-priming the sub-agent.
+
+### 3.3 TUI Integration (The Timeline)
+A dedicated widget displays the project's journey:
+- **Breadcrumbs**: `Planning [✓] -> Implementation [●] -> Verification [ ]`.
+- **Metrics**: Displays cumulative token usage and time elapsed per state.
+- **Diff View**: Shows which files have been modified since the start of the current state.
+
+## 4. Operational Guardrails
+
+### 4.1 Anti-Looping
+If a workflow transitions between the same states more than 3 times (e.g., Planning -> Implementation -> Planning -> Implementation), the Supervisor forces a transition to a `human_intervention` state and blocks further automated moves.
+
+### 4.2 Resource Budgeting
+The Supervisor tracks the total cost and token consumption across all sub-agents. It can be configured with hard limits to prevent runaway costs in long-running workflows.
+
+### 4.3 Cleanup
+Each state can define a cleanup routine that the Supervisor executes (e.g., killing background processes) before the next agent is spawned.
+
+## 5. Integration
+The Chronicle integrates with:
+- **agent-team**: To fetch specialized personas for specific states.
+- **damage-control**: To enforce safety rules across all worker sub-agents spawned by the Supervisor.