workflowskill

Multi-agent workflow skills for coding agents you already use.

Give your agent a high-level goal. Get back deep research, a tech-validated task DAG, parallel workers in isolated git worktrees, reviewed merges, verification, audit, tech-debt cleanup, and an honest final report.

/swarmgoal Add dark mode toggle to settings with tests
/swarmgoal Fix auth redirect loop --mode fast
/swarmgoal --resume .swarmgoal/add-dark-mode-Ab3Kx9 --from execute

Works on Grok, Claude Code, Codex, and Cursor (with graceful fallback on unknown harnesses).

Swarmgoal

Swarmgoal synthesizes the best of three workflows:

Source	What Swarmgoal inherits
Supergoal	Deep planning, two human gates, falsifiable criteria, final audit, 3-strike recovery
GoalGraph	DAG decomposition, file ownership, parallel batches, worktree isolation
execute-plan patterns	Harness adapters, persona injection, concurrency control

The difference: Supergoal runs phases sequentially. GoalGraph skips research depth. Swarmgoal does both — research and parallel execution and audit/debt closeout — with modes, resume, and mechanical validators.

How it works

flowchart TD
    Start(["/swarmgoal goal"]) --> S0["Stage 0<br/>Bootstrap + harness detect"]
    S0 --> G1{"Gate 1<br/>Intake (full mode)"}
    G1 --> R["Stage 1<br/>Research (per mode)"]
    R --> P["Stage 2<br/>DAG plan + self-critique"]
    P --> G2{"Gate 2<br/>Plan review + pre-flight"]
    G2 -->|Revise| P
    G2 -->|Start| E["Stage 3<br/>Parallel workers<br/>review + merge"]
    E --> C["Stage 4<br/>Verify → Audit → Debt"]
    C --> Done(["SWARMGOAL_RUN_COMPLETE"])

    classDef human fill:#fef3c7,stroke:#d97706,color:#000
    classDef done fill:#d1fae5,stroke:#059669,color:#000
    class Start,G1,G2 human
    class Done done

Loading

Yellow = human gates in full mode (fast skips Gate 1). Resume with --resume <run-root> --from execute if a session drops.

Modes

Mode	When	Research	Gates	Parallel
full	Greenfield, large features	Deep + tech audit	2	Yes
fast	Brownfield fixes, scoped work	Scripts only	1 (plan)	Yes
sequential	High-risk or unknown harness	Scripts only	1 (plan)	No

Install

git clone https://github.com/robzilla1738/workflowskill.git
cd workflowskill
./install.sh

install.sh checks git and jq, symlinks swarmgoal/ into agent skill dirs, and links the swarmgoal CLI to ~/.local/bin.

Manual install:

ln -sfn "$(pwd)/swarmgoal" ~/.agents/skills/swarmgoal
ln -sfn "$(pwd)/bin/swarmgoal" ~/.local/bin/swarmgoal

Use

Open your coding agent in any project and run:

/swarmgoal Build a REST API for todos with SQLite, tests, and README
/swarmgoal Fix checkout bug --mode fast

CLI (from any repo):

swarmgoal init --check
swarmgoal validate plan .swarmgoal/<run>/plan.json
swarmgoal status .swarmgoal/<run> --json
swarmgoal resume .swarmgoal/<run> --from execute
swarmgoal test

What lands in your repo

.swarmgoal/<goal-slug>-<random>/
├── plan.json              # Machine-readable DAG (jq-mutated only)
├── ROADMAP.md             # Human-readable plan
├── STATE.md               # Live progress + resume command
├── THINKING.md            # Goals, risks, constraints
├── tech-audit.md          # Tech freshness validation (full mode)
├── harness.md             # Detected harness + concurrency
├── PROTOCOL.md            # Execution manual
├── contracts/             # Per-task worker contracts
├── reports/               # Worker reports
├── reviews/               # Batch review outputs
└── phases/                # Audit/debt fix specs

Harness support

Harness	Spawn API	Default concurrency
Grok	spawn_subagent + persona prepend	4 (max 8)
Claude Code	Agent + isolation: worktree	4 (max 5)
Codex	Task tool	4 (max 8)
Cursor	Task tool + git worktree add	4 (max 8)
Unknown	Sequential + manual worktrees	1

Parallel safety

Validators perform semantic overlap detection — src/** and src/pages/Settings.tsx in the same batch is rejected. Optional worker pre-commit hooks enforce allowed_files at commit time.

Requirements

• git — worktree isolation
• jq — plan.json mutations
• bash 4+ — scripts and validators

Development

swarmgoal test
# or
bash swarmgoal/tests/run-all.sh

CI runs the full suite on every push. See CONTRIBUTING.md and docs/ARCHITECTURE.md.

Repository layout

workflowskill/
├── bin/swarmgoal          # CLI entry point
├── install.sh
├── swarmgoal/
│   ├── SKILL.md           # Main orchestrator entry
│   ├── references/        # modes, resume, harness adapters, DAG design
│   ├── personas/          # researcher, worker, reviewer, tech-validator
│   ├── templates/         # ROADMAP, STATE, PROTOCOL, contracts
│   ├── schemas/           # plan.json + task JSON schemas
│   ├── scripts/           # validators, CLI helpers, glob-overlap lib
│   ├── subskills/         # research + execute routing
│   ├── fixtures/          # Sample plans + overlap test repo
│   └── tests/             # Full test suite (7 files)
└── docs/
    └── ARCHITECTURE.md

Related projects

• Supergoal — sequential deep planning + single /goal dispatch
• GoalGraph — parallel DAG, hands-off, less research overhead

Support

If Swarmgoal saves you time, you can buy me a coffee. ☕

Version

Current: v1.1.0. See CHANGELOG.md.

License

MIT. See LICENSE.