# Agent Workflow

> Set up and run a multi-agent role workflow in a local project. Splits a project into Agent roles (main / planner / executor / reviewer + your own), each with its own responsibilities, memory (MEMORY), activity log (activity_log), blockers, knowledge notes and a per-directory INDEX. Supports Ask mode, Exec-Review auto loop, Note knowledge capture, a blockers protocol, cross-agent handoff records, planner-only verified check-off, and a deliverables layout rule. Use this skill when the user wants to initialize the workflow, add an agent role, check workflow status, or asks how the workflow is used. Pure local files, no SSH.

- Skill: `cifang-kasit/agent-workflow` (Agent Skill, multi-file: 21 files)
- Install (CLI): `npx skillmds@latest add cifang-kasit/agent-workflow`
- Raw SKILL.md: https://api.skillmd.com/api/skills/cifang-kasit/agent-workflow/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: AI & ML
- Author: cifang-Kasit (https://skillmd.com/u/cifang-kasit)
- Updated: 2026-09-22
- Page: https://skillmd.com/skills/cifang-kasit/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:
   ```bash
   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:
   ```bash
   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 <agent>" 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.