ezra-environment/PROSE-WORKFLOW-STANDARD.md

# PROSE-WORKFLOW-STANDARD.md
## Fleet Standard for Autonomous Cycle Definition

**Status:** RATIFIED — April 6, 2026  
**Authors:** Ezra (bridge) + Timmy (engine)  
**Authority:** Alexander Whitestone  
**Applies to:** All wizard houses, all repeatable work  

---

## The One Rule

> **If your lane involves repeatable work, express it as a workflow.**

No more 200-word prompts. No more heroic one-off sessions. Define the cycle once. Run it infinitely.

---

## The Sovereign Cycle

Every autonomous 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 |

---

## Two Formats, One Standard

The fleet supports **two equivalent representations**. Use whichever matches your executor.

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

For agents running through Hermes `delegate_task`. Contracts are readable, enforceable intent.

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

#### Required Sections

```markdown
---
name: wizard-health-check
kind: service
services: [disk, gateway, gitea, memory]
---

requires:
- runbook: path to the health check definition
- thresholds: critical vs warning limits per check
- owner: the wizard house responsible for action

ensures:
- report: a structured markdown report of all checks
- alerts: Telegram notifications for any critical findings
- checkpoint: cycle state saved to SQLite

strategies:
- when a check fails: run remediation once, then alert
- when multiple checks fail: prioritize disk and security
- when all checks pass: still commit a null report for traceability

execution:
  call disk_check
    task: Verify disk usage is below threshold
    runbook: "{{runbook}}"
    threshold: "{{thresholds.disk}}"

  call gateway_check
    task: Verify all gateway processes are alive
    owner: "{{owner}}"

  call report_assemble
    task: Compile checks into markdown report
    checks: "$results"
```

#### Frontmatter Schema

| Key | Type | Required | Description |
|-----|------|----------|-------------|
| `name` | string | ✅ | Canonical workflow identifier |
| `kind` | string | ✅ | `service`, `cycle`, `review`, `triage` |
| `services` | list | optional | Named sub-services this workflow coordinates |
| `version` | string | optional | Semver for tracking changes |
| `owner` | string | optional | Wizard house DRI |

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

For agents running the native Hermes workflow engine. Cycles are machine-executable with state persistence.

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

#### Required Schema

```yaml
name: wizard-health-check
kind: cycle
version: "1.0.0"
owner: ezra

cycle:
  wake:
    load: [runbook, thresholds, owner]
    verify: [runbook_exists]

  assess:
    condition: runbook_valid
    on_fail: report_and_sleep

  act:
    steps:
      - id: disk_check
        tool: terminal
        command: "python3 health_check.py --runbook {{runbook}} --threshold {{thresholds.disk}}"
        
      - id: gateway_check
        tool: terminal
        command: "python3 gateway_check.py --owner {{owner}}"
        parallel: false

      - id: report_assemble
        tool: file
        depends_on: [disk_check, gateway_check]
        template: "reports/health-check.md.j2"

  commit:
    - save_file: "reports/{{timestamp}}-health-check.md"
    - send_telegram: "{{owner}}-alerts"
    - write_checkpoint: "wizard-health-check"

  report:
    format: markdown
    fields: [summary, critical_count, warning_count, remediation_taken]

  sleep:
    interval: "1h"
    checkpoint_path: "~/.hermes/prose-workflows/checkpoints/wizard-health-check.json"
```

#### YAML Schema

| Key | Type | Required | Description |
|-----|------|----------|-------------|
| `name` | string | ✅ | Matches `.prose` name for equivalence |
| `kind` | string | ✅ | `cycle`, `service`, `review`, `triage` |
| `cycle.wake` | dict | ✅ | Precondition checks and input loading |
| `cycle.assess` | dict | ✅ | Go/no-go gate |
| `cycle.act` | dict | ✅ | Steps to execute |
| `cycle.commit` | list | ✅ | Persistence actions |
| `cycle.report` | dict | ✅ | Output specification |
| `cycle.sleep` | dict | ✅ | Checkpoint + scheduling |

---

## 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 |

**Both formats must produce the same observable behavior:** same inputs consumed, same artifacts committed, same report generated.

---

## Fleet Example Library

### Example 1: PR Review Workflow

**`ezra-pr-review.prose`** (bridge format)
```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"
```

**`ezra-pr-review.yaml`** (engine format)
```yaml
name: ezra-pr-review
kind: review
owner: ezra

cycle:
  wake:
    load: [pr_url, repo]
    verify: [pr_url_accessible]

  assess:
    condition: pr_open

  act:
    steps:
      - id: security_review
        tool: delegate
        goal: "Review PR for security issues"
        context:
          pr_url: "{{pr_url}}"
          repo: "{{repo}}"

      - id: performance_review
        tool: delegate
        goal: "Review PR for performance issues"
        context:
          pr_url: "{{pr_url}}"
          repo: "{{repo}}"
        parallel: true

      - id: maintainability_review
        tool: delegate
        goal: "Review PR for maintainability issues"
        context:
          pr_url: "{{pr_url}}"
          repo: "{{repo}}"
        parallel: true

      - id: report_unify
        tool: file
        depends_on: [security_review, performance_review, maintainability_review]
        action: post_pr_comment
        target: "{{pr_url}}"

  commit:
    - post_comment: "{{pr_url}}"
    - save_file: "reviews/{{repo}}-{{pr_number}}.md"

  report:
    format: markdown
    fields: [severity_counts, top_issues, recommendation]

  sleep:
    interval: "on_demand"
```

### Example 2: Health Check Workflow

**`wizard-health-check.yaml`** (engine format)
```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()'"
      - id: memory
        tool: terminal
        command: "free -h"

  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"
```

### Example 3: Issue Triage Workflow

**`fleet-triage.prose`** (bridge format)
```markdown
---
name: fleet-triage
kind: triage
services: [scan, rank, assign, notify]
owner: ezra
---

requires:
- repo: target repository
- board: project board name
- assignees: list of available agents

ensures:
- stale issues: closed or pinged
- unassigned issues: assigned to best-fit agent
- duplicates: marked and linked
- report: posted to Telegram with today's actions

strategies:
- when an issue is >30 days old with no activity: close as stale
- when an issue matches an existing open issue: mark duplicate
- when agent capacity is known: assign to least-loaded producer

execution:
  call scan_issues
    task: Scan all open issues in repo
    repo: "{{repo}}"

  call rank_issues
    task: Rank issues by priority and staleness
    issues: "$results.scan_issues"

  call assign_issues
    task: Assign unassigned issues to best-fit agents
    ranked: "$results.rank_issues"
    assignees: "{{assignees}}"

  call notify
    task: Post triage summary to Telegram
    actions: "$results"
```

---

## Naming Conventions

1. **Workflow files:** `<wizard>-<verb>.md` or `<wizard>-<verb>.yaml`
   - Good: `ezra-pr-review.md`, `bezalel-health-check.yaml`
   - Bad: `workflow1.md`, `new_workflow.yaml`

2. **Checkpoints:** `~/.hermes/prose-workflows/checkpoints/<name>.json`

3. **Reports:** `~/.hermes/prose-workflows/reports/<timestamp>-<name>.md`

4. **Issue references:** Every workflow execution must reference a Gitea issue or epic in its report.

---

## Adoption Rules

1. **New repeatable work:** Must be defined as a workflow before execution.
2. **Existing epics:** Convert to workflows during next review cycle.
3. **One-shot tasks:** Don't workflow-ify exploration or research. Use your judgment.
4. **Both formats accepted:** No format wars. `.prose` ↔ `.yaml` are equivalent.
5. **Commit the proof:** A workflow without a committed artifact didn't run.

---

## Toolchain Reference

| Tool | Path | Purpose |
|------|------|---------|
| Ezra's bridge | `~/.hermes/skills/devops/open-prose-bridge/scripts/prose2hermes.py` | `.prose` → Hermes Python |
| Timmy's engine | `~/.hermes/bin/prose-workflow-engine.py` | `.yaml` → native cycle executor |
| Workflow directory | `~/.hermes/prose-workflows/` | Standard home for all definitions |
| Checkpoint directory | `~/.hermes/prose-workflows/checkpoints/` | Cycle state persistence |
| Report directory | `~/.hermes/prose-workflows/reports/` | Human-readable execution logs |

---

## Ratification

This standard is **active immediately**. All wizard houses are directed to:

1. Read this document.
2. Convert their highest-frequency repeatable task to a workflow (either format).
3. Execute it within 24 hours.
4. Post proof to their epic or Gitea issue.

**No more prompt engineering. No more heroic sessions. Just defined cycles, infinite execution.**

---

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