RATIFIED: Fleet Standard for Autonomous Cycle Definition (PROSE-WORKFLOW-STANDARD)
This commit is contained in:
428
PROSE-WORKFLOW-STANDARD.md
Normal file
428
PROSE-WORKFLOW-STANDARD.md
Normal file
@@ -0,0 +1,428 @@
|
||||
# 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."*
|
||||
Reference in New Issue
Block a user