Agentic Workflow Guide

Design, review, and improve agent workflows based on proven principles.

この SKILL の基本姿勢は、agent を増やすことではなく、必要最小の primitive で解くこと。 context が膨らんだときも、まずは split / compact / reference 化を考え、いきなり multi-agent にしない。

Primitive First

Do not start with multi-agent by default.

Single focused slash task -> Prompt
Always-on or file-scoped guidance -> Instruction
Reusable workflow with bundled assets -> Skill
Persona, tool restrictions, delegation, or handoffs -> Agent
Deterministic enforcement -> Hook

If the ask does not require an Agent, stop and use the simpler primitive.

この primitive 選択表が SSOT。skill-creator-plus / skill-finder などの判定表は「そのスキルを使うべきか」の即時ゲートとして扱い、基準がずれたらここに合わせる。

Selection details: references/customization-decision.md

When to Use

Action	Triggers
Create	New `.agent.md`, `.instructions.md`, `.prompt.md`, `AGENTS.md`, or workflow architecture
Review	Orchestrator not delegating, design principle check, context overflow
Update	Adding Handoffs, improving delegation, tool configuration
Debug	Agent not found, subagent not working, picker visibility, access control
Decide	Determining whether multi-agent is justified or a simpler primitive is enough

Core Principles

Simplicity First: より単純な primitive で解けるなら agent 化しない
SSOT / SRP: 情報源と責務の分割を守る
Fail Fast: エラーは早く止める
Feedback Loop: 各段で検証できるようにする
Context Discipline: context が膨らんだら compact / split / retrieve を検討する

Principle details: references/design-principles.md

Pattern Selection

Prompt Chaining: 順序のある段階処理
Routing: 入力タイプで分岐する処理
Parallelization: 独立タスクを並列で進める処理
Orchestrator-Workers: 動的に subtasks を分解する処理
Evaluator-Optimizer: 品質基準を満たすまで反復する処理

Every loop needs explicit stop conditions.

Pattern details: references/workflow-patterns/overview.md

Design Workflow

Extract from conversation Repeated behavior, tool preferences, workflow shape, and obvious specialization を先に拾う。
Choose primitive + scope Prompt / instruction / skill / agent / hook と workspace / profile を決める。
Clarify only the gaps 挙動を変える曖昧さだけ聞く。
Check escalation agent や multi-agent が本当に必要か確認する。
Choose pattern complexity が上がるなら pattern を明示して設計する。
Review before expanding split / compact / reference 化で済まないかを見る。
Implement and iterate 最初から完成形を狙わず、弱い箇所を見つけて詰める。

Rule Placement

汎用的な workflow 設計原則は、この SKILL と references/ を SSOT にする。
repo local の .instructions.md には workspace 固有の差分だけを残す。差分が無い generic instruction は merge back して削除候補にする。
IR は原則 in-memory で扱う。validator、script、deterministic handoff が必要な場合だけ中間 file を materialize し、不要になったら片付ける。
scheduler / service / config など決定論的な state mutation は、AI/UI loop ではなく direct script / API で現状確認 -> 最小変更 -> live read-back まで行う。LLM は scope と整合対象の判断に限定する。
For model allocation, trace actual producer/reviewer responsibilities, verify live availability and applicable pricing, and show current-to-proposed assignments with quality/cost tradeoffs before mutation; use scheduled runtime bindings. Try the cheapest capable model first when a human can check the result quickly; after a stronger model completes a task once, capture its steps and checks as a prompt or skill, route repeats to the cheaper model, and fall back when the steps fail.

Escalation Rules

L0: Single Prompt
L1: Prompt + Instructions
L2: Single Agent
L3: Multi-Agent

Prefer the lowest level that solves the problem cleanly.

Quick signals:

Prompt > 50 lines
Steps > 5
"missed" / "overlooked" errorsが続く
Multiple responsibilities in one agent
Context > 70%

Threshold details: references/splitting-criteria.md

Entry Boundary Smells

Instruction Elevation Smell

always-loaded entry において、強い命令語が直下の catalog、reference list、workflow map、rule inventory を会話の優先レイヤーへ昇格させる状態。

Always-Loaded Entry Budget

always-loaded entry は会話境界と最小 guardrail のみを持つ。catalog、詳細手順、広い参照一覧は docs、README、task-specific assets へ退避する。

Runtime Boundary Rule

Review assets improve design quality and detect structural problems. Default conversational behavior is controlled by always-loaded entries.

Casual Input Safety Check

Lightweight inputs such as greetings, short Q&A, and numeric-only replies should not be force-routed into task intake unless the task context is explicit.

Review Gates

Primitive choice is simpler than agent if possible
Placement is appropriate and always-loaded entry files stay thin
New additions are proposed only after delete / merge / split / move options are checked
Single responsibility per agent is preserved
Errors can be detected and stopped early
Verify actual producer-to-consumer dataflow, not only fixtures injected into a validator; cover empty results and meaningful state transitions. Repeating unchanged input proves idempotency, not the full lifecycle.
Deterministic parts are offloaded to scripts / IR / hooks, and state changes are confirmed by reading authoritative live state back (not LLM/UI loops)

Full checklist: references/review-checklist.md

Reference Map

Core references: primitive decision, design principles, workflow patterns, splitting criteria, review checklist, and context management.

For scheduled workflows, use scheduled runtime bindings. For delegated evidence and append-only current-state extraction, see orchestrator-workers and IR architecture.

agent Quick Fix

When an orchestrator promises delegation but works directly, make the delegation requirement explicit and verifiable. See agent-guide.md.

Tools Reference

Use references/agent-template.md for tool mapping and stable agent scaffold details.

agentic-workflow-guide