agentflow
GitHub自动多步代理流程编排器，拦截/agentflow命令，通过8步管道将指令扩展为工程简报，智能路由模型并自主执行。强制包含验证步骤，支持断点续传与文档同步，确保任务高质量完成。
Trigger Scenarios
Install
npx skills add NeverSight/learn-skills.dev --skill agentflow -g -y
SKILL.md
Frontmatter
{
"name": "agentflow",
"risk": "none",
"source": "self",
"date_added": "2026-07-01",
"description": "Autonomous multi-step agent flow sequencer and command router. Intercepts \/agentflow <text> invocations, expands short instructions into execution-grade engineering briefs using workspace rules, classifies tasks, routes to the optimal model, executes autonomously, runs dynamic stack-based post-execution validation, and updates project documentation.",
"date_updated": "2026-07-01"
}
AgentFlow Sequencer
Purpose
A workspace-resident autonomous skill that intercepts slash-prefixed commands of the form:
/agentflow <instruction>
It then performs an 8-step pipeline:
- Intercept — parse skill name, raw instruction, and workspace context
- Project Context Load — discover and load workflow files from
.agents/workflows/ - Expand — transform the short instruction into a full engineering brief (enriched with workflow context)
- Classify & Route — choose the best execution model based on domain
- Execute — run the task fully autonomously, no confirmation needed
- Validate (MANDATORY) — run post-execution verification checks based on the tech stack (automatic detection of package.json/go.mod/etc. or custom validation rules in
task-rules.md) - Memory Loop — persist state so execution resumes after interruptions
- Output Contract + Workflow Sync — return a structured result block and update workflow docs
Step 6 (Validate) is non-optional. A task is NOT considered complete until validation passes. If validation fails, the agent MUST self-correct and re-validate before proceeding to Step 7.
Trigger Condition
ONLY activate when the user message starts exactly with:
/agentflow
Otherwise remain completely inactive.
Control Commands
While a task is in progress, the following commands are recognized:
| Command | Action |
|---|---|
/stop |
Immediately halt current execution |
/pause |
Pause and save current state |
/resume |
Resume from last saved state |
/status <task-id> |
Print current execution stage and last log entry |
/retry <task-id> |
Re-execute the last failed step from state |
Agent Protocol (Step-by-Step)
When this skill is invoked via /agentflow <instruction>, follow these steps:
Stage 1: Command Interception & CLI Dispatching
Do NOT expand or execute the instruction directly in the current turn. Instead:
- Extract the raw instruction.
- Run the CLI dispatch script via the terminal:
(Replacenode .agents/skills/agentflow/scripts/agentflow.mjs "<instruction>" --conv-id <CONVERSATION_ID><instruction>with the raw instruction and<CONVERSATION_ID>with the active Conversation ID). - Wait for the script to execute successfully and dispatch the expanded prompt back to the conversation.
- Stop calling tools to end the turn.
Stage 2: Dispatched Task Execution
When a message prefixed with [AGENTFLOW DISPATCH] is received in the conversation:
- Extract the
Model,Domain, andTask IDfrom the dispatch header. - Load relevant workflow files from
.agents/workflows/(Step 2 below). - Execute the task autonomously (Step 5 below), run validation (Step 6 below), write runtime execution state to
.agents/skills/agentflow/state/<task-id>.json(Step 7 below), and sync the updated workflows (Step 8 below).
Step 2 — Project Context Load (Workflows Discovery)
This step is mandatory before any expansion or execution.
2a — Discover Workflows Directory
Check if .agents/workflows/ exists at the workspace root:
<workspace_root>/.agents/workflows/
2b — Workflows Exist → Load and Apply
If the directory exists and contains .md files:
- List all workflow files in the directory.
- Select relevant files based on the task domain (see table below).
- Read and internalize the content of selected files BEFORE writing any code.
- Strictly follow any patterns, conventions, data models, or architectural decisions documented within these files. They represent the ground truth for this project.
Workflow file → task domain mapping:
| File | Use when |
|---|---|
project-overview.md |
Any task — always load for general context |
architecture.md |
Multi-file, backend, infra, design tasks |
database.md |
Any DB model creation, migration, or query change |
api-map.md |
Adding/modifying API endpoints |
coding-patterns.md |
Always load alongside implementation tasks |
task-history.md |
For context on what was previously done |
folder-structure.md |
Creating new files or directories |
workflow.md |
Lifecycle rules (local dev, review, commit, release) |
task-rules.md |
Custom tests and validation rules |
IMPORTANT: If a workflow file documents a model, schema, or API pattern that contradicts what you would normally do, ALWAYS defer to the workflow file. It represents established, reviewed decisions for this specific project.
2c — Workflows Do Not Exist → Create the Directory and Files
If .agents/workflows/ does not exist, or the directory is empty:
- Create the directory:
.agents/workflows/ - Scan the workspace to understand the project structure:
- Read
README.md,package.json,go.mod,Cargo.toml, etc. - List directories at depth 1–2 to identify tech stack and modules.
- Read
- Create standard workflow files (like
project-overview.md,coding-patterns.md,folder-structure.md,task-history.md, andtask-rules.md) based on what you discover. Do not create placeholder files with dummy content. Every file must contain accurate information derived from actual workspace inspection.
Step 3 — Prompt Expansion Engine
Transform the short instruction into an execution-grade prompt using this exact template, enriched with context loaded from Step 2:
ROLE:
<Select the most appropriate agent role for this task>
OBJECTIVE:
<Restate the user's goal as a precise, unambiguous engineering objective.
Infer missing context. Convert vague phrases into concrete targets.>
PROJECT CONTEXT:
<Summarize the relevant codebase context: tech stack, affected modules,
existing patterns, file paths, and architectural constraints.>
<Include key facts from workflow files: DB models, API conventions, coding patterns>
TASK BREAKDOWN:
1. <Atomic sub-task>
2. <Atomic sub-task>
3. <Atomic sub-task>
...
IMPLEMENTATION RULES:
- <Rule 1: follow patterns from coding-patterns.md>
- <Rule 2: respect DB schema documented in database.md>
- <Rule 3: match API conventions from api-map.md>
- <Rule 4: no breaking changes without verification>
- <Rule 5: mandatory validation after every change>
FILES TO CREATE/MODIFY:
- <path/to/file.ext> — <what changes and why>
VALIDATION PLAN:
- Test commands to run (automatically inferred or custom rules)
- Edge cases to check
EXPECTED OUTPUT:
- <Exact artifacts: code files, config changes, migration scripts, docs>
Step 4 — Domain Classification & Model Routing
Classify the task domain then select the optimal model:
| Domain | Trigger Signals | Target Model |
|---|---|---|
| Complex Implementation | implement, build, refactor, fix bug, security, multi-file | claude-opus-4.6-thinking |
| Standard Coding | add, write, create function, update, patch | claude-sonnet-4.6-thinking |
| Code Analysis / Audit | audit, review, find bugs, inspect, analyze, trace | claude-opus-4.6-thinking |
| Architecture / Design | design, plan, schema, structure, diagram, model | claude-opus-4.6-thinking |
| Frontend / UI | UI, component, screen, layout, style, mockup, CSS | claude-sonnet-4.6-thinking |
| Multimodal / Image | generate image, visualize, sketch, wireframe | gemini-3.5-flash-high |
| DevOps / Infra | deploy, CI/CD, Docker, Kubernetes, env, pipeline | gemini-3.5-flash-medium |
| Scripting / Automation | script, automate, shell, task runner, cron | gemini-3.5-flash-medium |
| Documentation | document, write docs, README, changelog, explain | gemini-3.5-flash-medium |
| Simple QA | what is, explain, list, difference, describe, how does | gemini-3.5-flash-medium |
Routing decision logic:
analyze(instruction)
→ classify(domain)
→ assess(complexity: simple | standard | complex)
→ choose(target_model)
→ if multi_domain → chain(model_a → model_b)
Step 5 — Autonomous Execution
Execute with the expanded prompt. Rules:
- No confirmation dialogs — proceed directly
- No blocking — do not wait for user approval unless explicitly required
- Continue until:
- Validation (Step 6) passes
- Blocked by truly missing external data (credentials, secrets, API keys)
- User issues
/stop
- On error: attempt self-correction up to 3 times before surfacing to user
- Safe file modifications: always read before writing; preserve unrelated content
Step 6 — Post-Execution Validation (MANDATORY)
THIS STEP IS MANDATORY. A task is NOT complete until validation passes. Never skip, never summarize as "should work". Run the actual commands.
Immediately after execution, run validation checks. The commands to execute are determined by the workspace environment and rules defined in task-rules.md.
6a — Tech Stack Auto-Detection
If task-rules.md does not specify validation commands, dynamically run checks based on workspace triggers:
- Go Project (detected via
go.modor.gofiles modified):go build ./... go vet ./... - TypeScript / JavaScript Project (detected via
tsconfig.jsonor.ts/.tsxfiles modified):npx tsc --noEmit - Rust Project (detected via
Cargo.toml):cargo check - Python Project (detected via
pyproject.tomlorrequirements.txt):pytest
6b — Custom Validation (task-rules.md)
If .agents/workflows/task-rules.md is present and contains validation instructions under a # Verification or # Validation section, prioritize and run those custom verification commands instead.
6c — Self-Correction Protocol
If validation fails:
attempt = 1
while attempt <= 3:
analyze error output
identify root cause
apply targeted fix (read file before editing)
re-run validation command
if passes → break
attempt += 1
if attempt > 3:
surface error to user with full context
do NOT update workflow files
mark task as "failed" in state
6d — Validation Result Recording
After validation passes, record the outcome:
{
"validation": {
"commands": ["npm test", "npx tsc --noEmit"],
"self_corrections": 0,
"status": "passed"
}
}
Step 7 — Memory + Context Loop
Persist execution state to:
.agents/skills/agentflow/state/<task-id>.json
If execution is interrupted, reload this file and resume from steps_pending.
Step 8 — Output Contract + Workflow Sync
8a — Workflow File Update (MANDATORY on success)
After a task completes successfully and validation passes, you MUST update the relevant workflow files in .agents/workflows/ to reflect the changes made. This is non-optional.
Update rules:
| What changed | Which file to update |
|---|---|
| New DB table or model field added | database.md — add the table/field documentation |
| New API endpoint added or modified | api-map.md — add/update the route documentation |
| New coding pattern established | coding-patterns.md — document the pattern |
| Architecture decision made | decisions.md — add an ADR entry |
| Completed task | task-history.md — append a new task entry |
| New directory or file structure change | folder-structure.md — update the tree |
task-history.md entry format (always append, never overwrite existing entries):
## Task N: <Short Title>
- **Objective**: <What was the goal>
- **Key Changes**:
- **<Area>**:
- [filename](file:///absolute/path): <What changed and why>
- **Verification**:
- Commands run and exit code status
- Self-corrections needed: <N>
Do not update workflow files if the task failed or was stopped. Only update on confirmed successful completion with passing validation.
8b — Output Block
Always return this exact structured block upon completion:
[SKILL]
agentflow
[INTERPRETED TASK]
<Plain-English restatement of what was understood>
[EXPANDED PROMPT]
<The full ROLE / OBJECTIVE / TASK BREAKDOWN / etc. block>
[SELECTED AGENT]
Model: <target_model>
Domain: <domain>
Confidence: <0.0–1.0>
[EXECUTION PLAN]
1. <Step>
2. <Step>
3. <Step>
[VALIDATION]
- Commands run: <commands list>
- Self-corrections: <N>
- Status: PASSED ✅ | FAILED ❌
[RESULT]
<Summary of what was done, files changed, and validation outcome>
If validation FAILED, the
[RESULT]block must include the error output and a clear explanation of why the task could not be completed.
Script Integration
This skill also ships with a standalone CLI script for terminal-based invocation:
node .agents/skills/agentflow/scripts/agentflow.mjs \
"<instruction>" \
--conv-id <CONVERSATION_ID>
The script:
- Expands the prompt locally
- Classifies domain using Gemini via
agy - Dispatches the expanded brief back via
agentapi send-message
References
references/expansion-templates.md— Domain-specific prompt expansion templatesreferences/execution-examples.md— Concrete invocation and output examplesscripts/agentflow.mjs— CLI dispatch scriptstate/— Runtime execution state directory.agents/workflows/— Project workflow documentation (auto-created/updated)
Version History
- e0220ca Current 2026-07-05 22:17
