Agent Workflow

Agent Workflow Skill

A portable, fully local multi-agent role workflow for Claude Code. Turn a solo project into a "virtual team": different roles divide the work, each keeps its own memory, leaves traces for the others, and captures knowledge. All state lives in local Markdown files inside the project — no server needed.

The protocol is split in two layers:

• templates/CLAUDE.md — the always-on rules (roles, identity rule, trigger route table, Step 1-5 summary, Ask mode, check-off rule, norms)
• templates/protocol/*.md — on-demand SOPs the route table points to (memory protocol, note mode, blockers, exec-review loop, handoff, INDEX governance, deliverables layout). Claude reads the relevant SOP right before executing it.

Subcommands

Decide what to do based on the user-supplied arguments ($ARGUMENTS):

init — initialize the workflow (first use)

Scaffold the workflow in the current project root:

1. Confirm the project root (current working directory). Set ROOT = absolute path of the project root.
2. Create directories and state files:

   ROOT="$(pwd)"
   mkdir -p "$ROOT/.workflow/shared" "$ROOT/.workflow/protocol" "$ROOT/.workflow/tools"
   mkdir -p "$ROOT/.workflow/agents"/{main,planner,executor,reviewer}
   

3. Copy this skill's templates/ contents into place:
   • templates/CLAUDE.md → <ROOT>/CLAUDE.md If <ROOT>/CLAUDE.md already exists: do not overwrite! Instead write the protocol to <ROOT>/.workflow/WORKFLOW.md, and tell the user to add a line @.workflow/WORKFLOW.md at the top of their CLAUDE.md to include it, or merge manually.
   • templates/protocol/*.md → <ROOT>/.workflow/protocol/ (all seven SOP files; the route table in CLAUDE.md references them by this path)
   • templates/tools/index_check.py → <ROOT>/.workflow/tools/index_check.py
   • templates/shared/*.md → <ROOT>/.workflow/shared/
   • templates/agents/<role>/ROLE.md → <ROOT>/.workflow/agents/<role>/ROLE.md (one each for main/planner/executor/reviewer)
   • templates/INDEX.template.md → <ROOT>/.workflow/agents/<role>/INDEX.md for each role, replacing <AGENT_NAME> with the role name and <DATE> with today's date
   • Create an empty MEMORY.md placeholder and a notes/ dir in each agent dir
4. Have the user fill the placeholders: ask for the project's one-line goal and write it to the top of shared/project_brief.md.
5. Verify: list the .workflow/ tree, confirm all files are present, and run the INDEX checker on one role to prove the tooling works:

   python3 "$ROOT/.workflow/tools/index_check.py" --root "$ROOT/.workflow/agents/executor"
   

   It must end with RESULT: PASS.
6. Tell the user the next steps:
   • Edit .workflow/shared/project_brief.md (goal), roadmap.md (phase framework), todos.md (tasks)
   • Then start each message with "you are " to trigger the protocol
   • Add new roles with /agent-workflow add-agent <name>
   • Deliverable directories (report/, presentation/, docs/) are created on first need per .workflow/protocol/deliverables_layout.md; init does not create them

add-agent <name> — add a custom role

1. mkdir -p "<ROOT>/.workflow/agents/<name>/notes"
2. Copy templates/ROLE.template.md → <ROOT>/.workflow/agents/<name>/ROLE.md, replacing the placeholder <AGENT_NAME> with <name>
3. Copy templates/INDEX.template.md → <ROOT>/.workflow/agents/<name>/INDEX.md (same placeholder replacement, plus <DATE>)
4. Create an empty MEMORY.md
5. Ask the user for the role's one-line responsibility and whether it is a Note Producer; fill them into ROLE.md
6. Remind: if the role participates in phase work, have planner register its responsibility in roadmap.md

status — show current workflow state

Read and summarize: current phase (todos.md), each agent's last activity (activity_log.md), unresolved blockers (and whether any resolved blocker # line is newer than planner's last MEMORY — a pending backfill), a summary of each agent's MEMORY, and — for every agent tree that has an INDEX.md — the last line of index_check.py --root <tree>. Read-only, changes nothing.

no args / other — explain usage

Briefly explain what this workflow is, which roles and modes exist, and how to init.

Important Notes

• This skill only handles scaffolding and structure management. The day-to-day Step 1-5 execution protocol is auto-applied once init installs it into the project's CLAUDE.md (or .workflow/WORKFLOW.md); you don't need to call this skill each time.
• The full protocol is templates/CLAUDE.md plus templates/protocol/*.md — together they are the authoritative definition of this workflow. When you change a rule, change it in the template, not only in an installed copy.
• Everything is local; never introduce SSH / remote dependencies.