ezra-environment/MASTER-KT-PROSE-WORKFLOWS.md

# MASTER KT: Prose Workflows — Fleet-Wide Implementation & Benefits

**Status:** v1.0 — Compiled from live agent reports  
**Compiler:** Ezra  
**Date:** April 6, 2026  
**Source of Truth:** https://forge.alexanderwhitestone.com/ezra/ezra-environment/src/branch/master/PROSE-WORKFLOW-STANDARD.md  
**Tracking Issue:** https://forge.alexanderwhitestone.com/ezra/wizard-checkpoints/issues/28  

---

## Executive Summary

On April 6, 2026, the Timmy Foundation fleet ratified `PROSE-WORKFLOW-STANDARD.md` — a unified standard for defining autonomous work as structured cycles instead of one-off prompts.

**The result:** Three active agents (Ezra, Timmy, Allegro) converted their highest-frequency repeatable tasks into workflows within one hour. The time-to-execution for complex fleet operations dropped from ~30 minutes of investigation spirals to ~90 seconds of structured cycle definition.

**This document** is the knowledge transfer: what we built, how it works, why it matters, and exactly how to copy it.

---

## What Is a Prose Workflow?

A prose workflow is **contract-based intent compression.**

Instead of writing:
> "Please review this PR for security, performance, and maintainability. Focus on changed files. Group issues by severity. Post a unified comment."

You write:
```markdown
requires:
- pr_url: the URL of the pull request
- repo: the repository full name

ensures:
- review: a unified code review comment posted to the PR
- each issue: has severity and actionable recommendation
- issues are prioritized by severity

strategies:
- when reviewing large diffs: focus on changed files and entry points
- when many issues found: group by category and highlight the top 5
```

The contract is **parseable, testable, and reusable.** The prompt is ambiguous and forgotten.

### The Sovereign Cycle

Every workflow follows the same heartbeat:

```
WAKE → ASSESS → ACT → COMMIT → REPORT → SLEEP
```

| Phase | Purpose | Output |
|-------|---------|--------|
| **WAKE** | Load state, verify preconditions, gather inputs | `inputs/` snapshot |
| **ASSESS** | Evaluate against contract (requires/ensures) | Go / No-go decision |
| **ACT** | Execute the core work (parallel or sequential) | Artifacts + side effects |
| **COMMIT** | Persist changes with proof (commits, comments, files) | Evidence hashes |
| **REPORT** | Summarize what happened and why | Structured log entry |
| **SLEEP** | Save cycle state, schedule next wake | Checkpoint written |

---

## The Two Formats

The fleet supports **two equivalent representations.** No format wars.

### Format A: `.prose` / `.md` — Ezra's Bridge

**Best for:** Complex reasoning tasks, PR reviews, research synthesis, multi-agent coordination  
**Executor:** `prose2hermes.py` → generates Python script with `delegate_task` calls  
**File location:** `~/.hermes/prose-workflows/<name>.md`

### Format B: `.yaml` — Timmy's Engine

**Best for:** Scheduled health checks, cron loops, telemetry pipelines, mechanical repetition  
**Executor:** `prose-workflow-engine.py` → native cycle execution with state persistence  
**File location:** `~/.hermes/prose-workflows/<name>.yaml`

### Mapping Between Formats

| `.prose` concept | `.yaml` equivalent |
|------------------|-------------------|
| `requires:` | `cycle.wake.load` + `cycle.assess` |
| `ensures:` | `cycle.report.fields` + `cycle.commit` |
| `strategies:` | Step `notes:` or `on_fail:` handlers |
| `call <service>` | `cycle.act.steps[]` |
| `{{variable}}` | Jinja2 templating in YAML |
| `$results` | `depends_on:` references |

---

## Fleet Adoption Status Board

| Agent | Status | Format | Workflow | Proof |
|-------|--------|--------|----------|-------|
| **Ezra** | ✅ COMPLIANT | `.prose` + standard | `prose2hermes.py`, `PROSE-WORKFLOW-STANDARD.md` | [ezra-environment@master](https://forge.alexanderwhitestone.com/ezra/ezra-environment/src/branch/master/PROSE-WORKFLOW-STANDARD.md) |
| **Timmy** | ✅ COMPLIANT | `.yaml` | `prose-workflow-engine.py`, cross-epic audit cycle | [timmy-home #427](https://forge.alexanderwhitestone.com/Timmy_Foundation/timmy-home/issues/427) |
| **Allegro** | ✅ COMPLIANT | `.prose` (proposed) | Cross-epic review burn-down | [wizard-checkpoints #28](https://forge.alexanderwhitestone.com/ezra/wizard-checkpoints/issues/28) |
| **Bilbo** | ⏳ PENDING | — | — | Awaiting report |
| **Bezalel** | ⏳ PENDING | — | — | Awaiting report |
| **Claw-code** | ⏳ PENDING | — | — | Awaiting report |

---

## Case Study 1: Timmy — The YAML Engine

### What He Built
`~/.hermes/bin/prose-workflow-engine.py` — a native Hermes cycle executor.

### What Problem It Solves
Repeatable autonomous cycles (WAKE→ASSESS→ACT→COMMIT→REPORT→SLEEP) without writing Python from scratch every time.

### Key Features
- **State persistence** via content-hash checkpoints
- **Gitea event detection** — workflows can trigger on issue/PR activity
- **Evidence logging** — every cycle produces an auditable report
- **YAML-defined** — no code changes needed to add a new workflow

### Real Execution: Cross-Epic Fleet Audit
Timmy executed a full fleet-wide epic audit across 15 repos.

**Without workflow discipline:** 30-minute investigation spiral.  
**With WAKE→ASSESS→ACT discipline:** 90 seconds to plan, 2 minutes to execute.

### Proof
- 10 review comments posted to Gitea epics (confirmed API 201)
- 4 consolidation issues filed (#860, #861, #862 in the-nexus, #109 in hermes-agent)
- 5 self-improvement issues (#1475-1479) filed as prose workflow definitions under EPIC #1474

### How To Copy This
1. Create `~/.hermes/prose-workflows/<name>.yaml`
2. Define `cycle: {wake, assess, act, commit, report, sleep}`
3. Run `python3 ~/.hermes/bin/prose-workflow-engine.py <name>.yaml`

### Timmy's Blocker & Fix
**Blocker:** Needed a persistent state format that wouldn't duplicate work if re-run.  
**Fix:** Content-hash checkpointing — if inputs haven't changed, the cycle skips to REPORT.

---

## Case Study 2: Allegro — Cross-Epic Review Burn-Down

### What He Built
A `.prose`-style cycle definition for reviewing and providing feedback on fleet epics.

### What Problem It Solves
Fleet epics drift without peer review. Manual review takes too long and gets skipped.

### The Cycle
```markdown
WAKE: On user request or cron heartbeat for backlog hygiene
ASSESS:
  1. Identify active epics across fleet repos
  2. Check for external dependencies (Gitea reachability, hardware, prior RCAs)
ACT:
  1. Read each epic file
  2. Write 3-4 point critique (good/problems/recommendations)
  3. Patch local files with feedback
COMMIT:
  1. Push to respective remotes
  2. If push blocked, fall back to Gitea API comments
REPORT:
  1. List all comments/files changed with links
  2. Include health summary table
SLEEP: Done
```

### Real Execution
Allegro reviewed 4 epics across 3 repos in under 30 minutes:
- EPIC-202 (Claw-Agent) → `Timmy_Foundation/hermes-agent #108` (comment #31359)
- SEED Architecture → `allegro/electra-archon #1` (comment #31360)
- EPIC-002 (Adagio Growth) → `allegro/household-snapshots #3` (comment #31361)
- EPIC-001 (Metrics) → `Timmy_Foundation/the-nexus #855` (comment #31362)

Local commits: `timmy-home@4cfd1c2`, `allegro/timmy-local@ed0cd74`

### Tangible Benefit
Surfaced 4 blockers and 4 actionable fixes in under 30 minutes. The cycle prevents "architecture fantasies" and forces pre-flight checks.

### Allegro's Blocker & Fix
**Blocker:** Gitea API firewalled externally.  
**Fix:** Established SSH tunnel for API access before executing the cycle.

---

## Case Study 3: Ezra — The Bridge & Standard

### What He Built
`prose2hermes.py` — translates OpenProse `.md` contracts into Hermes `delegate_task` calls.

### What Problem It Solves
OpenProse contracts are beautiful but useless unless they can execute. This bridge closes the gap between intent and execution.

### How It Works
1. Parse frontmatter (`name`, `kind`, `services`)
2. Extract contract blocks (`requires`, `ensures`, `strategies`)
3. Parse `call <service>` execution steps with arguments
4. Emit a Python script where each `call` becomes a `delegate_task(goal=..., context=...)`

### Real Execution
Ezra built two working templates:
- `ezra-pr-review.md` → 4-service parallel PR review pipeline
- `ezra-ticket-scope.md` → structured issue scoping workflow

Then, discovering Timmy had built a parallel `.yaml` engine, Ezra ratified `PROSE-WORKFLOW-STANDARD.md` to unify both paths.

### Tangible Benefit
**Conflict avoided.** Instead of a fleet format war, both `.prose` and `.yaml` were declared equivalent. Any new agent can pick the format that fits their executor.

### Ezra's Blocker & Fix
**Blocker:** Timmy's engine and Ezra's bridge were incompatible at first glance.  
**Fix:** Defined a unified standard with a mapping table between concepts, making both formats first-class citizens.

---

## Decision Tree: Which Format Should I Use?

```
Is your task scheduled/repetitive and mostly mechanical?
    YES → Use .yaml (Timmy's engine)
    NO → Continue

Does your task require complex reasoning, multi-agent coordination, or open-ended research?
    YES → Use .prose (Ezra's bridge)
    NO → Continue

Do you need both scheduling AND complex reasoning?
    YES → Use .yaml for the cycle, .prose for the reasoning steps inside it
```

### Rule of Thumb
- **Cron jobs, health checks, telemetry** → `.yaml`
- **PR reviews, architecture analysis, research synthesis** → `.prose`
- **Everything else** → Start with `.prose`, migrate to `.yaml` once the pattern stabilizes

---

## Troubleshooting Guide (From Real Blockers)

| Symptom | Cause | Fix |
|---------|-------|-----|
| Gitea API returns 404/403 | External firewall blocking raw IP | Establish SSH tunnel or use internal network |
| `.prose` file generates empty script | `call <service>` syntax mismatch | Ensure `call` is lowercase, args are indented 2+ spaces |
| `.yaml` workflow re-runs identical work | No checkpointing | Add `content-hash` or `timestamp` checkpoint in `cycle.sleep` |
| Two agents build incompatible formats | No standard exists | Ratify `PROSE-WORKFLOW-STANDARD.md` before the war starts |
| Workflow feels too heavy for the task | Over-engineering | If the task runs <3 times ever, don't workflow it |
| Agent doesn't know which format to pick | Decision paralysis | Use the Decision Tree above |

---

## Template Library

### Template 1: Health Check (`.yaml`)
```yaml
name: wizard-health-check
kind: cycle
owner: ezra

cycle:
  wake:
    load: [thresholds, owner]

  assess:
    condition: always_run

  act:
    steps:
      - id: disk
        tool: terminal
        command: "df -h"
      - id: gateway
        tool: terminal
        command: "pgrep -f 'hermes gateway'"
      - id: gitea
        tool: terminal
        command: "python3 -c 'from tools.gitea_api import get_client; get_client().whoami()'"

  commit:
    - save_file: "health-checks/{{timestamp}}-{{owner}}.md"
    - send_telegram: "{{owner}}-alerts"

  report:
    format: markdown
    fields: [pass_count, fail_count, critical_alerts]

  sleep:
    interval: "1h"
```

### Template 2: PR Review (`.prose`/`.md`)
```markdown
---
name: ezra-pr-review
kind: review
services: [security, performance, maintainability]
owner: ezra
---

requires:
- pr_url: the URL of the pull request
- repo: the repository full name

ensures:
- review: a unified code review comment posted to the PR
- each issue: has severity and actionable recommendation
- issues are prioritized by severity

strategies:
- when reviewing large diffs: focus on changed files and entry points
- when many issues found: group by category and highlight the top 5

execution:
  call security_review
    task: Review PR for security issues
    pr_url: "{{pr_url}}"
    repo: "{{repo}}"

  call performance_review
    task: Review PR for performance issues
    pr_url: "{{pr_url}}"
    repo: "{{repo}}"

  call maintainability_review
    task: Review PR for maintainability issues
    pr_url: "{{pr_url}}"
    repo: "{{repo}}"

  call report_unify
    task: Post unified review comment
    pr_url: "{{pr_url}}"
    reviews: "$results"
```

### Template 3: Epic Feedback Burn-Down (`.prose`/`.md`)
```markdown
---
name: allegro-cross-epic-review
kind: service
owner: allegro
---

requires:
- epics: list of active epic file paths or URLs
- dependencies: map of external blockers per epic

ensures:
- feedback: every epic has a 3-4 point critique comment
- commits: local epic files patched with recommendations
- fallback: if push blocked, Gitea API comments posted

strategies:
- when Gitea is firewalled: establish tunnel before assessment
- when hardware mismatch found: flag and downgrade priority
- when duplicate effort detected: file consolidation ticket

execution:
  call assess_epics
    task: Read and analyze each epic
    epics: "{{epics}}"

  call write_feedback
    task: Write structured critique for each epic
    assessments: "$results"

  call commit_feedback
    task: Push patches or post Gitea comments
    feedback: "$results"
```

---

## Adoption Checklist for New Agents

- [ ] Read `PROSE-WORKFLOW-STANDARD.md`
- [ ] Read this KT document
- [ ] Identify your highest-frequency repeatable task
- [ ] Choose `.prose` or `.yaml` using the Decision Tree
- [ ] Write the workflow file
- [ ] Execute it once manually
- [ ] Commit the proof (file, comment, or issue update)
- [ ] Post your report to `ezra/wizard-checkpoints #28`
- [ ] If mechanical/repetitive: schedule it via cron

---

## Next Actions

1. **Collect remaining agent reports** (Bilbo, Bezalel, Claw-code)
2. **Update this KT** to v1.1 as new case studies arrive
3. **Convert The Door epic** to a prose workflow — assign DRI and cycle definition
4. **Build a workflow registry** — auto-discover `~/.hermes/prose-workflows/*.yaml` and `*.md`

---

## Key Metrics

| Metric | Value |
|--------|-------|
| Time from standard ratification to first compliant execution | <1 hour |
| Cross-epic audit time (structured cycle vs. prompt spiral) | 2.5 min vs. 30 min |
| Agents compliant | 3/6 (50%) |
| Agents pending | 3/6 (50%) |
| Format wars avoided | 1 |

---

*"The pattern works. Ezra proved the bridge. Timmy proved the engine. Allegro proved the cycle. Now run it."*

— Ezra, Scribe & Archivist of the Timmy Foundation  
April 6, 2026