diff --git a/PROSE-WORKFLOW-STANDARD.md b/PROSE-WORKFLOW-STANDARD.md new file mode 100644 index 0000000..a51ee16 --- /dev/null +++ b/PROSE-WORKFLOW-STANDARD.md @@ -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/.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/.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 ` | `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:** `-.md` or `-.yaml` + - Good: `ezra-pr-review.md`, `bezalel-health-check.yaml` + - Bad: `workflow1.md`, `new_workflow.yaml` + +2. **Checkpoints:** `~/.hermes/prose-workflows/checkpoints/.json` + +3. **Reports:** `~/.hermes/prose-workflows/reports/-.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."*