tannhatcms/jarvis/ams-agent-workflows

Reusable Agent Workflow Patterns

One-off agent sessions don't scale; workflows do. The reusable patterns are: subagents (scoped workers with briefs), hooks (event-triggered automations), slash commands (parameterized task templates), and session management (state that survives across runs).

Overview

Think of workflows as the operating system layer above individual agent sessions. Subagents let a coordinator delegate bounded work without context contamination. Hooks automate responses to events — a file changes, a check runs. Slash commands turn repeated task shapes into invokable templates with arguments. Session management — persistent notes, handoffs, resumable state — makes long work survive interruptions. Together they turn "ask the agent" into a reliable production practice.

When to use

• The same agent task recurs: research briefs, code reviews, weekly reports.
• Coordinating multiple agents on one objective without tangling their contexts.
• Automating routine responses: lint-on-save, test-on-commit, summarize-on-arrival.
• Long projects that span many sessions and must resume cleanly.

Core concepts

• Subagents: child agents spawned with a scoped brief — goal, boundaries, output contract.

Isolation keeps their context clean; the brief keeps their work useful.

• Hooks: event → action mappings. File saved → run formatter; task completed → update the

log. Keep hooks fast, idempotent, and observable.

• Slash commands: named, parameterized task templates (/review <pr>, /brief <topic>). They

encode the task shape — steps, output format, quality bar — so every invocation is consistent.

• Session management: durable state across sessions — decision logs, progress trackers,

handoff notes. The workflow remembers so the agent doesn't have to.

• Composition: commands that spawn subagents, hooks that trigger commands, sessions that chain.

Design the pieces to combine.

• Idempotency: workflow steps safe to rerun. Hooks fire twice, sessions resume mid-way —

design for it.

Practical workflow

1. Identify the recurring task; write down its steps, inputs, outputs, and quality bar as observed

in manual runs.

1. Encode it as a slash command: parameterized template with the steps and output contract baked in.
2. Where the task has parallelizable parts, have the command spawn subagents with scoped briefs

instead of doing everything inline.

1. Add hooks for the trigger events: what should happen automatically, with what guardrails.
2. Set up session state: a progress file or log the workflow updates, so interruptions resume

instead of restart.

1. Run it three times manually via the command; fix the rough edges; then trust the automation.

Workflow anatomy:
COMMAND:  /weekly-brief <topic> — steps, output format, sources to check
SUBAGENTS: researcher (sources) + analyst (synthesis) — scoped briefs
HOOK:      on Friday 09:00 → run /weekly-brief automatically
SESSION:   briefs/ log — what was covered, open threads

Common pitfalls

• Automating before stabilizing: encoding a flaky manual process into a workflow. Stabilize by

hand first, then automate.

• Vague subagent briefs: "look into this." Subagents need the same rigor as any delegation —

goal, scope, output contract.

• Hook sprawl: dozens of overlapping triggers firing unpredictably. Keep hooks few, logged, and

individually disableable.

• Non-idempotent steps: reruns that duplicate work or corrupt state. Make every step safe to

repeat.

• No session state: long workflows that restart from zero on interruption. Persist progress;

resume, don't redo.

• Over-composition: commands calling commands calling subagents until no one can trace what

happened. Keep the call depth shallow and logged.