fx-alfred 1.19.0

Alfred — Agent Runbook: workflow routing, SOP checklists, and document management for AI agents

Alfred

Agent Runbook

Workflow routing, SOP checklists, and document management for AI agents and humans.

---

What is Alfred?

Alfred is a CLI-based agent runbook (af) that manages SOPs, workflows, and structured documents across three layers (PKG, USR, PRJ). It provides:

• NEW in v1.19.0 — Project-root auto-discovery: every command now resolves the nearest ancestor directory whose rules/ contains Alfred documents, so af works from any project subdirectory without --root (explicit --root still wins). af plan no longer silently drops steps: section extraction and step rendering are now fence-aware (bash comments and numbered lines inside code blocks are body content, not boundaries or steps) — 10 bundled/user SOPs were affected. af validate warns on unknown document TYPE codes instead of silently skipping type-specific checks (--json gains an additive warnings field). All --json output is now uniformly indented UTF-8 (CJK content renders as written instead of \uXXXX escapes). CI now tests Python 3.10/3.12/3.14 with pyright and format gates.
• v1.18.0 — af issue lint <body-file> Phase 1 MVP — pre-creation lint for GitHub issue bodies; detects TBD-after-PR-review anti-patterns (5 canonical phrases, case-insensitive substring match) with --json output and - stdin support. Plus PKG SOP additions: Two-Worker TDD Dispatch (PRP-1507) opt-in cross-validation pattern (new <test-writer-worker-agent> parameter in COR-1622, dispatch contract in COR-1619, Worker-assignment rule in COR-1500); COR-1620 Primitive 5 Status-Communication Contract forbidding silent wake-and-yield; COR-1501 §Quality Criteria author-side write-time targets; COR-1617/COR-1618 reconciled on loop-start triggers.
• v1.17.1 — PRJ-layer documentation: FXA-1623 review thread watchdog, FXA-2285 pre-merge bot sweep gate, review-loop refinements (COR-1602/1612/1615).
• v1.17.0 — PR Review Thread Verification (COR-1623) audits unresolved GitHub PR review threads against exact source content at the PR head SHA; Review GitHub Issue Quality (COR-1506) scores blueprint-ready issues with a weighted implementation-readiness rubric.
• v1.16.0 — Build Weighted Decision Matrix (COR-1802) codifies rubric design and calibration; COR-1200 gained retrospective scoring; COR-1617 added Phase 11 Retrospective; COR-1622 added resilience parameters.
• v1.15.0 — COR-1501 aligned with iterwheel intake conventions (label taxonomy completed, Applies to: scoped, portability note); COR-1617 §Phase 7 closing-token prescription tightened (bare Closes #N required, verify via closingIssuesReferences); §Phase 10/11 advances on mergeable not merged.
• v1.14.0 — Multi-Agent Workflow Loop (COR-1617 cluster) — umbrella SOP for consensus-driven multi-agent task execution with consent gates, worker dispatch, and loop primitives. Ships COR-1617/1618/1619/1620/1621/1622. Also: COR-1612 §Scoping bot reviews via PR body; COR-1615 pointer; new .github/ISSUE_TEMPLATE/blueprint.md for iterwheel intake.
• v1.13.0 — Per-user document bookmarking: af star <ID>, af unstar <ID>, af starred. Bookmark any doc directly by ACID; persists in ~/.alfred/preferences.yaml; documents are not modified.
• v1.12.0 — Contract-First Delivery Workflow (COR-1616) — project-neutral reviewed-delivery loop (contract → plan review → TDD/BDD/E2E → impl review → identity-correct PR → PR review loop → close out), promoted from Babs BAB-1503. Also: pytest test-marker governance gate, skills-absorption round 5 (COR-1207, COR-1208, FXA-2248).
• v1.10.0 — Agent-editable helpers and skill documents: af agent call/run, af skill list/read, and af plan --with-skills
• v1.9.1 — GitHub App PR Review Bot Loop (COR-1615) for Codex Connector / Copilot PR review loops; v1.9.0 added Council Review (COR-1613) and Diagnose Feedback Loop (COR-1503)
• Workflow Routing — af guide tells AI agents which SOP to follow for any task
• Workflow Checklists — af plan generates step-by-step checklists from SOPs. With --task "<description>" auto-composes the SOP set from tags; --todo flattens into a unified checklist; --graph renders ASCII + Mermaid flowcharts with intra-SOP loops and gates; --with-skills recommends matching skill docs
• Agent Helpers & Skills — af agent runs explicitly gated local Python helpers/scripts, while af skill discovers and reads reusable REF/SOP skill documents without executing code
• Document Validation — af validate enforces metadata format, status values, and section structure; warns on unknown TYPE codes
• Document Formatting — af fmt normalizes metadata order, whitespace, and table alignment to canonical style
• File Path Lookup — af where prints the absolute filesystem path of any document by identifier
• Document Lifecycle — Create, read, update, search, and index documents with consistent naming
• Tags Metadata — Optional Tags: field, exposed via Document.tags and filterable with af list --tag
• Issue Body Linting — af issue lint <body-file> flags TBD-after-PR-review anti-patterns before issue creation (Phase 1 MVP — 5 canonical phrases; --json machine output; - reads stdin)
• JSON Output — --json flag on guide/plan/search/validate for machine-readable output
• Spec-driven Updates — --spec FILE on create/update for batch metadata and section changes

Alfred is designed to be used by both AI agents (Claude Code, Codex, Gemini) and humans.

Quick Start

pip install fx-alfred
cd my-project
af guide          # see workflow routing (PKG → USR → PRJ)
af list           # list all documents
af validate --root .  # validate all documents
af read COR-1000  # read a specific document

Features

Workflow Routing (af guide)

Scans three layers for routing documents and outputs a complete workflow guide:

af guide --root /path/to/project

═══ PKG: COR-1103 Workflow Routing ═══
  Intent-based router: ALWAYS → PRIMARY ROUTE → OVERLAYS
  Golden rules from all COR SOPs

═══ USR: ALF-2207 Workflow Routing USR ═══
  Cross-project user preferences

═══ PRJ: FXA-2125 Workflow Routing PRJ ═══
  Project-specific decision tree

Workflow Checklists (af plan)

Generate step-by-step checklists from SOPs — optimized for LLM consumption:

af plan COR-1102 COR-1602 COR-1500            # phased checklist from named SOPs
af plan --human COR-1102                       # human-readable format
af plan --task "implement FXA-XXXX PRP"        # auto-compose SOPs from tags (COR-1202)
af plan --task "..." --todo --graph            # flat TODO + ASCII + Mermaid graph
af plan --task "..." --with-skills             # append matching skill docs
af plan --task "..." --graph --graph-format=ascii    # ASCII only (terminal)
af plan --task "..." --graph --graph-format=mermaid  # Mermaid only (GitHub / Obsidian)
af setup                                       # suggested prompts for agent config

Auto-compose matches the task description against Task tags: SOP metadata (deterministic, no LLM), includes any SOP with Always included: true as a baseline (e.g., COR-1103 routing), and topologically orders the result via Workflow input/Workflow output edges with layer+ASCII tiebreaks.

--todo flattens all phases into one continuously-numbered checklist with [SOP-ID] provenance, ⚠️ gate markers, and 🔁 loop-start / 🔁 back to N.M (max K) markers driven by Workflow loops: SOP metadata.

--graph emits both an ASCII box-and-arrow diagram (Unicode-width aware, terminal-friendly) and a fenced Mermaid block (pasteable into GitHub / Obsidian). Use --graph-format={ascii,mermaid,both} to pick one.

--graph-layout={nested,flat} (v1.7.0+, ASCII-only) chooses the DAG shape. The default nested layout draws each SOP as an outer phase-box containing inner step-boxes with ▼ connectors. Intra-SOP loops render as a 🔁 → N.M max K annotation line inside the phase box. Cross-SOP loops — declared via Workflow loops: [{from: N, to: "PREFIX-ACID.step", ...}] metadata — render as a right-side vertical track (◄───┐ ... ───┘ max N) that spans phase boundaries. flat restores the v1.6.x layout (one phase-box per SOP, steps listed inside, intra-SOP loops only) for downstream tooling pinned on the legacy shape.

See COR-1202 (Compose Session Plan) for the canonical usage procedure.

Agent Helpers and Skills

Run explicit local helper code only after opting in:

ALFRED_AGENT_TOOLS=1 af agent call collect_review_pack --arg root=. --json
ALFRED_AGENT_TOOLS=1 af agent run scripts/check_release.py --json

af agent call loads public functions from <project-root>/.alfred/agent_helpers.py first, then ~/.alfred/agent_helpers.py. The exact ALFRED_AGENT_TOOLS=1 gate is checked before importing helper code.

Discover reusable skill documents without executing code:

af skill list
af skill list --task "release fx-alfred to pypi" --json
af skill read skill-release-to-pypi

A skill is a REF or SOP document with explicit Tags: skill metadata. af plan --task "..." --with-skills appends matched skills to the plan; JSON output adds recommended_skills and uses schema version 3.

See FXA-2237 for the full usage reference.

Testing

The pytest suite uses strict registered markers:

pytest --tb=short
pytest -m "not slow" --tb=short
pytest --cov=src/fx_alfred --cov-report=term-missing --cov-fail-under=95

Markers:

• unit — narrow module or pure-function tests
• cli — af command surface and Click command wiring
• integration — filesystem, packaging, subprocess, or cross-module behavior
• docs — document, rule, template, or documentation behavior
• slow — intentionally slower tests for local loop exclusion

Unknown markers fail because pytest runs with --strict-markers.

Document Validation (af validate)

Enforces document health across all layers (H1 format, required metadata, status values, Change History, SOP sections, layer rules). Unknown TYPE codes emit a warning — type-specific checks are skipped but never silently:

af validate --root /path/to/project   # --root optional: nearest project root is auto-discovered

Checks:

• H1 format (# TYP-ACID: Title)
• Per-type required metadata fields (Applies to, Last updated, Last reviewed, Status)
• Status values against allowed set per document type
• Change History table structure
• SOP required sections (What Is It?, Why, When to Use, When NOT to Use, Steps)

207 documents checked, 0 issues found.

Document Management

# Create
af create sop --prefix FXA --area 21 --title "My SOP"
af create prp --prefix FXA --area 21 --title "My Proposal"
af create sop --prefix FXA --area 21 --title "My SOP" --spec fields.yaml  # from spec file

# Read
af read COR-1000                    # by PREFIX-ACID
af read 1000                        # by ACID only

# Update
af update FXA-2107 --status "Active"
af update FXA-2107 --history "Done" --by "Claude"
af update FXA-2107 --title "New Title" -y
af update FXA-2107 --spec patch.yaml  # batch update via spec file

# Format
af fmt                              # show diff for all PRJ documents
af fmt FXA-2107                     # show diff for one document
af fmt --write                      # apply canonical formatting in-place
af fmt --check                      # CI check: exit 1 if any changes needed

# Search
af search "validation"              # search content across all docs
af search "validation" --json       # JSON output

# List & Filter
af list --type SOP                  # filter by type
af list --tag release               # filter by tag
af list --prefix FXA --json         # filter + JSON output

# Star (per-user bookmarks, ~/.alfred/preferences.yaml)
af star COR-1202                    # bookmark a doc (PREFIX-ACID, prefix-case-insensitive, or ACID-only)
af star 1202                        # ACID-only when unambiguous
af starred                          # list bookmarks; (missing) marks deleted docs
af starred --json                   # {schema_version, starred_docs, missing}
af unstar COR-1202                  # remove bookmark (works on stale entries too)

# Other
af guide --json                     # routing guide as JSON
af validate --json                  # validation results as JSON
af status                           # document counts by type/layer
af index                            # regenerate project index
af changelog                        # view version history

# Where (file path lookup)
af where FXA-2107                   # print absolute path
af where FXA-2107 --json            # JSON: {doc_id, path, source, filename}
vi $(af where FXA-2107)             # composable with shell tools

Three-Layer Document Model

graph TD
    AF["af CLI"] --> PKG
    AF --> USR
    AF --> PRJ

    subgraph PKG ["📦 PKG (read-only)"]
        direction LR
        P1["COR-* SOPs"]
        P2["Templates"]
        P3["Bundled with fx-alfred"]
    end

    subgraph USR ["👤 USR (~/.alfred/)"]
        direction LR
        U1["Personal preferences"]
        U2["Cross-project rules"]
        U3["Routing: ALF-2207"]
    end

    subgraph PRJ ["📁 PRJ (./rules/)"]
        direction LR
        R1["Project SOPs & CHGs"]
        R2["PRPs & ADRs"]
        R3["Routing: FXA-2125"]
    end

    style PKG fill:#1a1a2e,stroke:#e94560,color:#fff
    style USR fill:#1a1a2e,stroke:#0f3460,color:#fff
    style PRJ fill:#1a1a2e,stroke:#16213e,color:#fff

Layer	Location	Writable	Scope
PKG	Bundled in package	No	Universal COR documents
USR	~/.alfred/	Yes	Personal, cross-project
PRJ	./rules/	Yes	Project-specific

Document Types

Type	Purpose	Example
SOP	Standard Operating Procedure	How to create a document
PRP	Proposal	Design for a new feature
CHG	Change Request	Modify existing system
ADR	Architecture Decision Record	Record a decision
REF	Reference	Glossary, index, contract
PLN	Plan	Execution schedule
INC	Incident	Bug report, outage record

Document Format

<PREFIX>-<ACID>-<TYP>-<Title-With-Hyphens>.md

FXA-2134-PRP-AF-Plan-Command-Workflow-Checklist.md
COR-1103-SOP-Workflow-Routing.md

For AI Agents

Session Start

af guide --root /path/to/project    # 1. See routing + decision tree
af plan COR-1102 COR-1602 COR-1500 # 2. Generate workflow checklist

First Time Setup

af setup                            # See suggested prompts for your agent config

Decision Tree (COR-1103)

graph TD
    START["What are you doing?"] --> Q1{"Pure document\nmanagement?"}
    START --> Q2{"Something\nbroken?"}
    START --> Q3{"New capability\nthat doesn't exist?"}
    START --> Q4{"Change existing\nsystem?"}
    START --> Q5{"Record a\ndecision?"}
    START --> Q6{"Track/discuss\na topic?"}

    Q1 -->|New SOP| COR1000["COR-1000"]
    Q1 -->|New doc| COR1001["COR-1001"]
    Q1 -->|Update| COR1300["COR-1300"]

    Q2 -->|Bug| INC["INC"]
    Q2 -->|Fix + change| INC2["INC + CHG"]

    Q3 --> PRP["PRP (COR-1102)"]
    PRP --> REV["Review (COR-1602)"]
    REV --> CHG1["CHG (COR-1101)"]
    CHG1 --> TDD1["TDD (COR-1500)"]

    Q4 -->|Standard| CHG2["CHG, no review"]
    Q4 -->|Normal| CHG3["CHG → Review → TDD"]
    Q4 -->|Emergency| CHG4["CHG → Execute → Post-approval"]

    Q5 --> ADR["ADR (COR-1100)"]
    Q6 --> DT["COR-1201\nD new / D list"]

    style START fill:#0f3460,stroke:#e94560,color:#fff
    style PRP fill:#16213e,stroke:#0f3460,color:#fff
    style REV fill:#1a1a2e,stroke:#e94560,color:#fff
    style TDD1 fill:#16213e,stroke:#0f3460,color:#fff

Key SOPs

SOP	What it does
COR-1103	Workflow routing — which SOP to follow for any task
COR-1202	Compose Session Plan — af plan --task … --todo --graph for full session workflow
COR-1102	Create Proposal (PRP lifecycle)
COR-1101	Submit Change Request (CHG)
COR-1500	TDD Development Workflow
COR-1506	Review GitHub Issue Quality — weighted rubric for blueprint-ready issue implementability
COR-1602	Multi-Model Parallel Review
COR-1612	Respond to PR review comments on GitHub
COR-1615	GitHub App PR Review Bot Loop — trigger/poll/match-head loop for Codex Connector, Copilot, and other GitHub App reviewers
COR-1616	Contract-First Delivery Workflow — project-neutral reviewed delivery loop (contract → plan review → TDD/BDD/E2E → impl review → identity-correct PR → PR review loop → close out)
COR-1617	Multi-Agent Workflow Loop — consensus-driven task execution with consent gates, worker dispatch, and structured loop primitives
COR-1623	PR Review Thread Verification — audit unresolved PR review threads against exact source content at the PR head SHA
COR-1802	Build Weighted Decision Matrix — design, calibrate, and validate weighted scoring rubrics
COR-1608	PRP Review Scoring rubric
COR-1611	Reviewer Calibration Guide
COR-1613	Council Review — multi-reviewer decision mechanism (14 voting rules)
COR-1503	Diagnose Feedback Loop — disciplined bug/perf diagnosis

Review Scoring

Alfred includes a standardized review scoring framework:

• COR-1608 — PRP scoring (6 weighted dimensions + OQ hard gate)
• COR-1609 — CHG scoring (5 dimensions)
• COR-1610 — Code scoring (5 dimensions)
• COR-1611 — Shared reviewer calibration guide

Pass threshold: >= 9.0/10. All deductions must cite specific lines.

Commands Reference

af guide [--root DIR] [--json]
af plan [SOP_ID ...] [--root DIR] [--task TEXT] [--with-skills] [--todo] [--graph] [--graph-format ascii|mermaid|both] [--human] [--json]
af agent call HELPER_NAME [--arg key=value ...] [--json]
af agent run SCRIPT_PATH [--json]
af skill list [--task TEXT] [--layer PKG|USR|PRJ|all] [--json]
af skill read ID_OR_NAME [--json]
af list [--type TYPE] [--prefix PREFIX] [--source SOURCE] [--tag TAG] [--json]
af read IDENTIFIER [--json]
af create TYPE --prefix P --acid N|--area N --title T [--layer project|user] [--subdir DIR] [--spec FILE] [--dry-run]
af update IDENTIFIER [--status STATUS] [--field KEY VALUE] [--history TEXT] [--by NAME] [--title TITLE] [-y|--yes] [--dry-run] [--spec FILE]
af fmt [DOC_IDS...] [--write] [--check]
af where IDENTIFIER [--json]
af search PATTERN [--json]
af validate [--root DIR] [--json]
af setup
af status [--json]
af index
af changelog

Install / Upgrade

pip install fx-alfred              # install
pipx install fx-alfred             # install (isolated)
pipx upgrade fx-alfred             # upgrade

Changelog

See CHANGELOG.md or run af changelog.

License

MIT