How vxcozy/workflow-orchestration works
What this project is (type + purpose)
This repo is not an application runtime (no src/, no services, no code modules). It’s a portable “skill” package for AI coding agents (AgentSkills-compatible), intended to be installed into an agent environment (e.g., Claude Code, Cursor, Copilot) to enforce a disciplined workflow: planning, delegation, verification, and self-improvement loops.
• The host agent runtime (external)
• This skill package (static assets + instructions)
• The user’s project workspace where tasks and outputs are created
• Optional supporting artifacts created during use (tasks/todo.md, lessons, etc.)
Treat it like a plugin / policy module rather than a service.
Architecture cues from the file tree
Top-level contents:
• SKILL.md — the *core entrypoint* (what gets loaded/executed by the agent runtime)
• docs/ — Diataxis docs for onboarding and usage patterns
• references/ — canonical formats/templates and detailed reference behavior
• README.md, LICENSE, .gitignore
• No executables, no language build files, no dependencies → this is documentation-driven orchestration.
What to capture from the README (behavioral architecture)
Key functional “subsystems” described:
• Plan Mode (create and follow a plan; often tasks/todo.md)
• Subagent Delegation (offload to subagents to keep main context clean)
• Verification (prove completeness before done)
• Self-Improvement (capture corrections/lessons; feed back into future runs)
• Autonomous Fixing (reduce user burden)
• Activation modes: direct invocation (/workflow-orchestration) or automatic triggers (3+ steps, bugfixes, refactors)
These are best represented as a state machine / workflow loop layered over the host agent.
User
• provides goal, constraints, reviews verification results
Agent Runtime (external) (e.g., Claude Code / Cursor / Copilot / Gemini CLI)
• executes instructions, manages context, may spawn subagents
• *owns* the execution environment; this repo plugs into it
Workflow Orchestration Skill (this repo)
• SKILL.md (primary “controller” instruction set)
• Docs (Diataxis): tutorial/howto/explanation (human learning + correct usage)
• References/Templates: reference spec, task templates, lessons format (standardized artifacts)
Workspace Artifacts (in the user’s project)
• tasks/todo.md plan/progress tracker (explicitly mentioned)
• optional “lessons” file(s) based on references/lessons-format.md
• any code changes produced by executing the plan (outside this repo)
Subagents (optional, spawned by agent runtime)
• handle focused subtasks; return results to main agent
• Orchestration Policy (from SKILL.md)
• Planning/Task Tracking Format (from references/task-templates.md)
• Verification Checklist/Method (from references/REFERENCE.md)
• Learning Capture Format (from references/lessons-format.md)
• User → Agent Runtime: task request / feedback
• Agent Runtime → Skill (SKILL.md): loads skill content; uses it to decide behavior
• Skill → Agent Runtime: prescribes phases (Plan → Execute → Verify → Learn)
• Agent Runtime ↔ Workspace: reads/writes tasks/todo.md, edits code, runs checks
• Agent Runtime → Subagents: delegates subtasks
• Subagents → Agent Runtime: returns findings/patches/summaries
• Verification results → User: proof-of-done, test outputs, checklist completion
• Lessons learned → Workspace Artifacts: persistent learning notes/templates for future tasks
Architectural pattern
This is essentially:
• Plugin/Skill architecture (static skill instructions loaded by a host)
• Workflow/state-machine overlay on agent execution
• Artifact-driven process control (plans, checklists, lessons are first-class objects)
Call out that the “business logic” is procedural guidance, not code.
Relevant technologies / standards
• AgentSkills-compatible skill package
• Diataxis documentation model (docs/tutorial.md, docs/howto.md, docs/explanation.md, and references/REFERENCE.md)
• Invocation modes: /workflow-orchestration and automatic activation conditions
• Artifacts: tasks/todo.md, “lessons” format, templates