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

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

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)

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

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)

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)

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