AI Agent Workflow Collection

Design an evaluation plan for a product AI feature (LLM- or model-backed output): measurable success criteria, a held-out labeled eval dataset shape, per-criterion grading (code-based first, then LLM-based for nuanced judgment), and a pass threshold, then persist as AIEVALPLAN.md. Use when the task ships or changes a feature whose output is model-generated or non-deterministic (assistant reply, classification, extraction, summarization, ranking, agent action) and needs a repeatable dataset-backed eval rather than only example-based tests. Do not use when the feature has no model-backed output (use test-strategy for deterministic behavior), when judging Fhorja's own command outputs against a rubric (use verify-against-rubric), or when no active task folder exists. The code-graded tier composes with ADR-0048 (a passing deterministic gate is Layer-1 evidence); the LLM-graded tier is added signal, not a replacement.

Verify a built mobile or app runtime at runtime: run the app (device, emulator, or headless), read the captured runtime output (native logcat, iOS device log, or the Metro/JS console), classify any runtime errors against a per-stack taxonomy, and decide a PASS/FAIL runtime gate for the slice's acceptance behavior. The run's real output IS the Layer-1 runtime evidence (ADR-0048); a claimed-but-not-shown run is unverified. Capability-routed and MCP-agnostic about how the app is run; React Native/Expo (logcat plus Metro) is the first documented adapter. It verifies and routes fixes, it does not apply them. Use after an app slice is implemented to gate runtime behavior the static checks (typecheck, lint) cannot catch. Do not use to plan a screen (use implementation-plan), to write or fix code (use implement-approved-slice), to triage a failure into a fix size (use incident-triage), to verify a Godot scene (use godot-runtime-verify), or with no implemented app to run.

Persist the user's triage decisions (apply, decline, discuss) from a SWEEP snapshot into REVIEWPREFERENCES.md so future sweeps suppress declined findings and track applied fixes. Use after the user has edited the triage values in a SWEEP snapshot file produced by repo-consistency-sweep. Do not use when no sweep snapshot exists or when the user has not yet set triage values.

Atomically lock IMPLEMENTATIONPLAN.md as the approved execution baseline and stamp TASKSTATE.md with the approval signal. Symmetric counterpart to approve-proposed but for the plan itself, not for arbitrary PROPOSED artifacts. Use when IMPLEMENTATIONPLAN.md has been produced (or revised via self-critique-and-revise) and the user authorizes execution to begin. Do not use when the plan is still draft, when implementation-plan returned NOOP, when the plan contains [NEEDS CLARIFICATION:] markers, or when revisions are still pending review.

Atomically persist every file marked PROPOSED in the most recent prior assistant turn's Artifact changes block. Single-command idiom that closes the two-step latency in ADR-0001's PROPOSED-by-default contract; the user reviews proposals in Ask/Plan mode, then runs this once to write all of them. Use when the prior assistant turn ended with a Artifact changes block containing one or more files marked PROPOSED and you have read and accepted the inline content for each. Do not use when the prior turn had no Artifact changes block, every artifact is APPLIED or SKIP, you have not yet read the proposed content, or you want to approve only a subset (run the original command in Agent mode for partial approval).

Produce ATOMAUDIT.md table auditing every atom component against COMPONENTGUIDELINES.md (memo, callbacks, inline styles, press anim, touch target, a11y, reduced motion). Output is the table; fixes flow through normal slice pipeline. Use when 2-4 weeks have passed since last audit, when 5+ new atoms shipped, or when COMPONENTGUIDELINES has a new normative rule. Do not use when no atoms exist (run design-bootstrap first) or when only a single atom needs review (use design-spec-review instead). For 6 or more atoms, use atom-audit-fleet.

Orchestrator-workers variant of atom-audit. Dispatches N Haiku workers (3-5 atoms each) to audit every atom under packages/design-system/src/atoms/ in parallel against COMPONENTGUIDELINES.md rules; merges per-worker rows into ATOMAUDIT.md table. Use when atom count >= 6 (per cost-effectiveness threshold) AND COMPONENTGUIDELINES.md exists. Do not use when atom count < 6 (use atom-audit single-agent), when COMPONENTGUIDELINES.md is missing, or when only 1-2 atoms changed (use design-spec-review per-component).

Read-only board-of-record view for an autonomous-run task (ADR-0044 D7, wos/autonomous-track.md). Renders the run as the spec, the IMPLEMENTATIONPLAN waves and slices, and the TASKSTATE phases mapped to to-do / in-progress / escalated / proposed / done columns, sourced only from the Fhorja task artifacts. No external work tracker; no writes. Use when the maintainer wants a single-glance status of an autonomous run without opening every artifact. Do not use to change state (use sync-task-state), to assess a normal multi-slice task (use where-we-at), or to route the next command (use what-next).

Drive an approved, waved IMPLEMENTATIONPLAN through the autonomous delivery track. A thin code-orchestrated dispatcher over the existing fleet primitives (the Workflow tool, implement-approved-slice as single writer) bounded by two human gates and a runtime governor. Runs verifiable slices with little supervision and emits PROPOSED slice diffs only; it never merges. Use when the plan is approved (approve-plan), broken into dependency-ordered waves, and the maintainer wants the work between the two gates run hands-off in a single supervised session. Do not use when the plan is not yet approved (run approve-plan), the work is a single slice (use implement-approved-slice), the run would need to remove the human merge gate or auto-merge (never allowed; a human always performs the merge), or cross-session durable resume (restart and re-attach of a stopped run) is required (out of v1 scope; a detached single continuous background session is in scope via the opt-in background mode).

Produce a staff-grade backend system-design RFC for the active task: a 12-section design document (problem, requirements, architecture, data model and storage, API contract, caching, scaling and bottlenecks, reliability and SLOs, security, observability, rollout and migration, trade-offs) for a new service, endpoint, or backend feature, persisted as BACKENDSYSTEMDESIGN.md. Capability-routed, not stack-specific; composes with slo-define, performance-budget, api-contract-review, and release-plan rather than duplicating them. Use when a backend service or feature needs an architecture-level design before planning and slicing. Do not use to slice an already-designed change (use implementation-plan), to analyze blast radius (use impact-analysis), to review an API contract in isolation (use api-contract-review), to design the frontend surface (use frontend-system-design), or with no active task folder (run task-init first).

Return a branch name and a concise commit message (at most 2 lines) for the current task, grounded in the real git diff rather than a paraphrase of the task summary. Use when the user only needs quick branch and commit naming right before committing, full PR packaging is unnecessary, and there is a real inspectable diff (staged or unstaged changes, or a branch diff vs an integration base). Do not use when the task needs a complete PR package (use pr-package), there is no diff yet (naming a branch from a task summary alone is the failure mode this command exists to avoid; ask the user to stage at least one change first), or the diff is still too unclear to summarize safely.

Append a single observation, question, hypothesis, or concern to TASKSTATE.md as task memory without disrupting in-progress work or requiring a full state sync. Lean append-only; never restructures other artifacts. Use when something surfaces mid-work that should be remembered for later (during planning, implementation, or review), when you noticed something not actionable now but should not be lost, when you want to log a hypothesis to validate before closure, or when a small concern does not justify decision-interview or targeted-questions but deserves to be on record. Do not use when the observation is a canonical decision (use decision-interview or sync-task-state), invalidates the current direction (use direction-adjust), requires several artifact changes (use sync-task-state or state-reconcile), or when there is no active task folder yet (run task-init first).

Pull external references (URLs or topics provided by the user) from the web, summarize each with a defined freshness format, and append them to projects/ /REFERENCES.md so all current and future tasks under that project can consume them as grounded external context. Deduplicates by URL. Use when the user wants to research and persist project-level references (stack docs, API contracts, regulations, competitor pages), supplies URLs to summarize with freshness metadata, surfaces an external reference that should outlive the task, or wants to seed REFERENCES.md for a freshly bootstrapped project. Do not use when the project folder does not exist yet (run project-bootstrap first), the reference is internal to a single task, the input is a codebase observation (use capture-observation), or the input is a decision or policy choice (use decision-interview or direction-adjust).

Generate and re-sync an AI-readable code context map (a ranked, token-budgeted, layered Markdown map of files, imports, signatures, invoke edges, and typed external boundary calls: db/http/queue) for a target project (or, from a seed file, its import chain), written to a gitignored folder inside that project and regenerated on invoke. Extraction is ripgrep-based by default, with optional parser augmentation when a parser is already present; no embeddings. The map is a seed for grep, not a replacement for reading code. Opt-in; not part of default task init. Use when an assistant needs fast structural orientation before editing a codebase, when onboarding to an unfamiliar repo, or when an existing map is stale. Do not use to locate one specific behavior (use code-locate), to analyze the blast radius of a planned change (use impact-analysis), to introspect a database schema (use db-context-supabase), or without a target codebase path.

Given a behavior description, locate candidate code paths and line ranges in the active codebase that probably implement it. Output up to 10 candidates with HIGH/MEDIUM/LOW confidence, one-line rationale per candidate, and an explicit search trail; propose a SOURCEOFTRUTH.md update so the next workflow step (typically impact-analysis) runs with concrete files instead of a vague codebase pointer. Per-repo when multi-repo. Use when the first real step is "where is this code?" (file paths not yet known), SOURCEOFTRUTH.md names the codebase but not specific files, you are about to run impact-analysis and the file list is missing, the user has a clear behavior description but no path or file pointers, or a failing test or runtime symptom names a behavior but not the implementation file. Do not use when file paths are already explicit, the codebase is tiny and the layout is known, the need is general architectural understanding (use impact-analysis), or no active task folder exists yet.

Senior design-system color contrast architect enforcing WCAG 2.2 AA/AAA per design context (normal text, large text, UI components, focus indicators). Audits every documented foreground and background pair across light and dark themes BEFORE the visual choices lock, producing a pairwise contrast matrix with token-level remediation. Activates when design-bootstrap proposes color tokens without contrast pairs, when DECISIONS.md proposes a primary or accent color without confirming contrast, when foundations/color.md exists without a contrast matrix, or when a screen-spec or component-spec mentions an unvalidated pair. Do not use for a single pair (use component-spec inline), when the design system has no theme variants, when no accessibility target is locked (raise via decision-interview first), or after remediation is agreed (use implement-approved-slice).

Produce a lossy compaction summary of TASKSTATE.md when task memory has grown beyond a useful working size, preserving canonical decisions and recommended next step while dropping stale facts. Distinct from sync-task-state (incremental, append-only, never lossy) and state-reconcile (drift repair, no shrinking). Use when task memory has accumulated across multiple slices (5+ completed) and feels heavy, the resume cost is growing as the file scales, the current known facts list is full of resolved or routine entries, or before a session pause where a slim TASKSTATE will speed restart. Do not use when the task is still in early discovery (memory is small), the artifacts disagree across files (use state-reconcile first), an incremental sync would be sufficient (use sync-task-state), or no active task folder exists yet (run task-init first).

Harden the current decision set into a clean, normative source of truth with no residual ambiguity, then persist the result in DECISIONS.md and TASKSTATE.md as explicit reviewable edits (no silent intent drift). Use when key decisions are already resolved, the task has a stable contract or policy direction, and the remaining work is to harden wording and remove interpretation risk before planning or implementation. Do not use when major ambiguities remain unresolved, the task still needs decision-interview or resolve-contract-gaps, or the task is still in broad discovery.

Validate that a generic Postgres database (GCP Cloud SQL, GKE Autopilot, self-hosted, etc.) is reachable via psql or pgdump, introspect a user-scoped subset of the schema (extensions, tables, columns, indexes, foreign keys, and optionally RLS policies and functions), and persist the result as DBCONTEXT.md inside the active task folder; adds a single DB context cross-link in SOURCEOFTRUTH.md. Read-only introspection only; never destructive SQL. Opt-in, not part of default task init. Use when the active task touches a non-Supabase Postgres database (Cloud SQL, GKE Autopilot Postgres, self-hosted Postgres, RDS, etc.), when planning or implementation needs verified schema rather than assumed schema, or when an existing DBCONTEXT.md is stale. Do not use without an active task folder (run task-init first), when the task does not touch a database, when the target is Supabase (use db-context-supabase), or when the user wants to record a schema decision (use decision-interview).

Validate that a Supabase MCP server is reachable, introspect a user-scoped subset of the database (tables, columns, types, RLS policies, optionally functions and recent migrations), and persist the result as DBCONTEXT.md inside the active task folder; adds a single DB context cross-link in SOURCEOFTRUTH.md. Read-only introspection only; never destructive SQL. Opt-in, not part of default task init. Use when the active task touches Supabase data/schema/RLS, when planning or implementation needs verified schema rather than assumed schema, or when an existing DBCONTEXT.md is stale. Do not use without an active task folder (run task-init first), when the task does not touch Supabase, when the database is not Supabase, or when the user wants to record a schema decision (use decision-interview).

Ask the minimum set of high-value decision questions needed before turning the task into canonical implementation rules. Decisions that would change runtime behavior, data integrity, rollout safety, or test strategy. Use when the missing information is decision-driven (not factual), different answers would change behavior or data integrity or rollout safety or test strategy, or the task cannot safely move into planning because policy or behavior is undecided. Do not use when missing information is factual (use targeted-questions), decisions are already locked in code or docs or approved task artifacts, or the task is already in implementation with no correctness-critical ambiguity. To harden wording before planning, use contract-signoff; to reconcile contradictory rules, use resolve-contract-gaps.

Generate an outward-facing delivery artifact (executive summary, slack or email update, demo script, release note, blog post draft) from the current task's work, scoped per audience and per format. Persists as DELIVERYASSET .md inside the active task folder. Distinct from pr-package (GitHub-scoped) and team-update (team-internal). Grounds every claim in TASKSTATE.md, DECISIONS.md, IMPLEMENTATIONPLAN.md, and PRPACKAGE.md when present; never invents metrics, customer impact, or marketing claims. An opt-in mode can send the asset to a connected knowledge-base MCP after a per-post confirmation. Use when delivery requires audience-specific framing beyond a PR description or team status update (executive readout, customer-facing release note, all-hands demo script, partner email). Do not use when the audience is a code reviewer (use pr-package), for a quick team status update (use team-update), when it is a reviewer note for PRPACKAGE.md, or with no active task folder (run task-init first).

Bootstrap a design system from a Figma file using MCP tools. Extracts token variables, identifies components, creates the directory structure, and generates scaffolded foundation docs and a component inventory. Use when starting a new project with a Figma design file. Do not use when the design system docs already exist or when there is no Figma file.

Review a component or screen implementation against its spec doc for alignment on variants, states, accessibility, tokens, and visual fidelity. Distinct from review-hard (general risk) and repo-consistency-sweep (pattern matching). Activates when a slice's declared Scope touches a design-system button, icon, or component convention file (a shared atom/component under a design-system package) with no cited design-spec-review pass for that change. Use when a design system component or screen has been implemented and you want to verify it matches the documented spec. Do not use when no spec exists (write one first with component-spec or screen-spec).