agentic-workflow-guide

Agentic Workflow Guide

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

The basic stance of this SKILL is,not to increase agents, but to solve with the minimal necessary primitives. Even when context swells, first consider splitting / compacting / converting to references, and do not suddenly go multi-agent.

Primitive First

Do not start with multi-agent by default.

• Single focused slash task -> Prompt (Local harness only; prompt files are deprecated for Agent Host sessions, so prefer a Skill for new slash workflows)
• Always-on or file-scoped guidance -> Instruction
• Reusable workflow with bundled assets -> Skill
• Persona, tool restrictions, delegation, or handoffs -> Agent
• Deterministic enforcement -> Hook (Preview; events and config differ by harness)

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

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: If it can be solved with a simpler primitive, do not turn it into an agent
• SSOT / SRP: Maintain the separation of information sources and responsibilities
• Fail Fast: Stop early on errors
• Feedback Loop: Make it verifiable at each stage
• Context Discipline: If context swells, consider compacting / splitting / retrieving

Principle details: references/design-principles.md

Pattern Selection

Name the pattern explicitly when complexity rises, using the selector in references/workflow-patterns/overview.md. Every loop needs explicit stop conditions.

Design Workflow

1. Extract repeated behavior, tool preferences, and workflow shape from the conversation.
2. Choose primitive + scope (workspace / profile); ask only about ambiguities that change behavior.
3. Escalate only when split / compact / reference-ization cannot solve it, then pick a pattern.
4. Implement the smallest version and tighten the weakest parts.

Rule Placement

• For general workflow design principles, in this SKILL and references/ make it the SSOT.
• repo local の .instructions.md keep only the workspace-specific differences. Generic instructions with no differences should be merged back and made candidates for deletion.
• In principle, handle the IR in-memory. Materialize intermediate files only when a validator, script, or deterministic handoff is needed, and clean them up once they are no longer needed.
• For deterministic state mutations such as scheduler / service / config, perform current-state confirmation -> minimal change -> live read-back not via an AI/UI loop but via direct script / API. Limit the LLM to judging scope and what to align.
• For model allocation reviews, use scheduled runtime bindings.

Escalation Rules

Prefer the lowest level (L0 prompt → L1 + instructions → L2 single agent → L3 multi-agent) that solves the problem cleanly. Quick signals to split:

• Prompt > 50 lines
• Steps > 5
• "missed" / "overlooked" errors continue
• Multiple responsibilities in one agent
• Context > 70%

Threshold details: references/splitting-criteria.md

Review Gates

• Primitive choice is simpler than agent if possible
• Placement is appropriate and always-loaded entry files stay thin (entry boundary smells: review-checklist.md)
• 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.

When an orchestrator promises delegation but works directly, make the delegation requirement explicit and verifiable (agent-guide.md). Tool mapping and agent scaffold: agent-template.md.

Done Criteria

• Primitive and scope selected intentionally
• Workflow pattern selected and confirmed with user
• New or updated assets have clear Role/Workflow/Done Criteria where applicable
• Review Gates passed
• Recommendations are classified as delete / merge / split / move / add / keep where applicable
• Always-on instruction boundaries and DRY / SSOT risks are explicitly reviewed when copilot-instructions.md or AGENTS.md are in scope
• New agent / workflow assets are registered in the appropriate catalog or docs when needed
• AGENTS.md is updated only when shared guardrails or entry behavior need to change
• Long-running or ad-hoc terminals/tasks started during the workflow are closed, or remaining terminals are explicitly reported with a reason
• Distinguish configuration saved, code tested, live read verified, action authorized, and recurring cycle completed. Verify authoritative state before claiming completion or unattended readiness; pending safeguards and unobserved cycles retain their blockers and next check conditions.