Omair Saleh
2fb612b1df
- Static site: /manifesto, /live, /hire pages - Ship-log Pi extension: calvana_ship, calvana_oops, calvana_deploy tools - Docker + nginx deploy to calvana.quikcue.com - Terminal-ish dark aesthetic, mobile responsive - Auto-updating /live page from extension state
65 lines
3.4 KiB
Markdown
65 lines
3.4 KiB
Markdown
# 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.
|