Workflow Skills
Spec in. Named pipeline. Reviewed pull request out. Any coding agent. GitHub and Azure DevOps.
A spec-driven pipeline: the spec is source of truth, gates are named, and the agent cannot skip them.
Dispatches use bounded subagent contracts and indexed plan slices: an 18 KB fixed preamble, a 4 KB matched MEMORY slice, and a configurable 32 KB total context budget.
A machine-readable acceptance-criteria ledger links evidence, tasks, files, tests, findings, and sabotage outcomes. Standard Step 5 derives its score from that ledger, so agents cannot author or override it.
Portable Node helpers write {workflow-id}.state.json first, render .state.md, and publish derived run.json, run.md, step handoff JSON, plans-index, and progress artifacts for reliable resume and inspection.
Per-step JSONL telemetry captures lifecycle, gate, skip, revision, and timing evidence. Aggregate and report commands summarize audit counts and median elapsed time by pipeline and step.
Choose step or phase gates, with phase mode capped at five blocking decisions. Adaptive polling uses observed check and thread state while preserving fail-closed verification and review convergence.
Authoring requires Definition of Ready, Validation & Observation Notes, and Negative & Failing Test Scenarios. Interview audits failing tests. Implement is red-then-green. Uncovered negative scenarios cap verify at 8.
Consult local MEMORY files, an external spec-memo vault, or both. enableMemoryFiles and enableSpecMemoIntegration choose the backends. ws-spec-memo is setup; runtime vault ops use ws-memo.
Human-facing *.spec.md under the specs directory is the contract of record. Plans are run artifacts. Write a spec, plan, implement, verify, review, test, open a PR, and close threads. One orchestrator owns the sequence so the agent does not skip gates.
Standard is thorough (steps 0–9). Lite is fast (steps 0–5). Both share project config. Batch mode classifies each spec and picks the right speed.
Standard Step 5 scores the work 0–10. Below defaults.minVerifyScore (default 9) it re-implements flagged tasks and re-scores (max 3 rounds). It never auto-approves a weak score.
Auth, fetch to spec, create PR, list and resolve threads, check status, merge. Switch providers.scm. The contract is tested in CI.
Prior-work sweep before plan/code; design-intent git history; repo-wide defect-class fixes; regression sabotage when mutation is unset; CI triage via extended check-pr-status; tracker close-loop via comment-issue.
Product files commit after verify (standard) or after implement (lite). Review diffs committed work vs the base branch. Review fixes get a second commit. Plan files wait until ship.
Skills are markdown plus scripts. No IDE lock-in. Paths come from config.json. Your config, memory, and changelog stay local when you update.
/ws-preview runs your preview.dryRunCommand in-repo (no packaged reviewer). Configure with /ws-configure-project --section preview — it can infer the recipe from harness docs and scripts.
How Workflow Skills eliminates LLM hallucinations, fake passes, and regression drift.
ac-ledger.json mechanically links each spec requirement to concrete tasks, touched files, tests, commits, and sabotage checks. LLMs cannot fake completion without recorded evidence.
Standard Step 5 computes an objective score from the ledger: score = 10 × (implemented / total), capped at 8 if any negative scenario remains uncovered. Agents cannot author or override this score.
Before advancing to Step N, validate_state.cjs --pre-advance N verifies all required prerequisites exist on disk and match state hashes. Missing artifacts halt the pipeline immediately.
ws-self-learning inspects project MEMORY.md and external spec-memo vaults before planning or editing, turning previous coding mistakes into hard rules that subagents must respect.
Start from a spec. Derive the plan. Implement against acceptance criteria. Ship a reviewed PR.
Transforms free-text user intent, issue description, or context into a canonical *.spec.md with crisp section hierarchy, mandatory acceptance criteria, Definition of Ready, Validation & Observation Notes, and Negative & Failing Test Scenarios. Authoring validation fails closed. New runs also ask a feature-branch strategy gate (stay on current, or create feat/{slug} from HEAD or from baseBranch).
Generates a detailed technical implementation plan (step-01-*.plan.md), mapping proposed file modifications, domain schema bindings, and verification strategies.
Audits the plan against actual project code structure, surfaces design trade-offs, and resolves ambiguities interactively with structured user-gate choices.
Breaks down the refined plan into an atomic Directed Acyclic Graph (*.exec.dag.json), establishing strict dependencies, touch boundaries, and test obligations.
Executes DAG tasks sequentially using subagent isolation. Enforces surgical diff hygiene, memory trap consulting before edits, and action-first execution. Product files stay uncommitted until after Step 05 verification.
Evaluates code changes against spec acceptance criteria, calculating an objective completeness score (0–10) and generating a verification report. Advance requires score ≥ defaults.minVerifyScore (default 9, range 1–10); below the bar the orchestrator runs scoreAndRefine (re-implement flagged tasks and re-verify) until that bar. After a passing score, the orchestrator commits workflow-touched product files so local review can diff committed work vs the base branch.
Reviews the committed diff vs baseBranch (git diff {base}...HEAD). Runs a two-phase code review (Security/Bugs & Senior Standards) with automatic fix sub-cycles, then a second product commit for review fixes if any.
Runs pre-PR automated test suites (unit, integration/E2E, coverage) plus an optional mutation-testing gate (kill/survive score vs threshold) when configured in project config. Optional defaults.testingModel selects a dedicated test-executor model for this step after modelsPreset / stepModels overrides (falls back to executionModel).
Commits configured plan-dir delivery artifacts (product code is already committed after verify and after review-fix), pushes the feature branch, and opens a Pull Request via the configured SCM provider (GitHub CLI / Azure DevOps).
For each Act-round or standalone batch, runs a gate-only fixPrPlan with reviewer-class model resolution, then validates and applies it in fixPrExec with execution-class resolution. Both roles stay inside outer Step 9; convergence continues until zero unresolved threads remain.
Drafts a canonical *.spec.md with Definition of Ready, Validation & Observation Notes, and Negative & Failing Test Scenarios (authoring validation fails closed), then evaluates complexity against dagThresholds in project config to validate Lite eligibility.
Generates concise, focused implementation plan without requiring deep multi-round interview overhead.
Executes code changes sequentially in place, bypassing complex JSON DAG file generation for rapid feature delivery. Then commits workflow-touched product files before local review.
Reviews the committed diff vs the base branch, verifying quality standards and auto-fixing issues, then a second product commit for review fixes if any.
Pushes the feature branch and opens the pull request (product already committed). GitHub or Azure DevOps, same intents.
Runs the same gate-only plan before execute order for each incoming PR-comment batch, inline on the current session model, until all threads are resolved.
Scans specs/ directory or `{plansDir}/specs/` to index all pending feature specifications and verify structural formatting.
Evaluates spec complexity (file count, layer depth, estimated tasks). Automatically routes simple specs to ws-spec-to-pr-lite and complex specs to full ws-spec-to-pr.
Dispatches worker FSM pipelines one spec at a time, persisting multi-spec execution status under {plansDir}/ws-spec-multi/ to allow resumption across sessions.
If a worker spec fails, pauses execution with clear user-gate choices (Resume, Skip, Abort). On success, ships individual PRs and updates project changelog.
Top-level Finite State Machines that coordinate multi-step workflows, manage subagent lifecycles, and maintain state persistence.
Brainstorming, spec formatting, architectural plan generation, plan auditing, and DAG task graph building.
Isolated coding step workers that execute individual tasks, apply targeted refactoring, and resolve implementation issues.
Spec compliance scoring (advance at ≥ defaults.minVerifyScore (default 9), scoreAndRefine until then), multi-pass code reviews, adversarial AI fraud detection, secrets scanning, install diagnose, and test verification.
Branch management, git commits, PR creation across GitHub / Azure DevOps with a shared intent contract, Local spec register, and goal loops for PR thread fixing.
Scope control standards, surgical code diff guidelines, anti-regression memory, action-first response rules, and changelog updates.
Every delivery run starts from a spec. One thorough path. One fast path. Same project config.
Thorough delivery (steps 0–9)
Plan, interview, implement, verify at ≥ minVerifyScore (default 9), commit, review, test, open a PR, and close threads.
defaults.minVerifyScore (default 9) or scoreAndRefine), product commit, local code review, review-fix commit (Steps 4–6)testingModel), shipping & ws-goal-fix-pr (Steps 7–9)Fast delivery (steps 0–5)
Plan, implement, commit, review, ship. Same GitHub or Azure PR ops as standard. No interview, DAG, or test step.
Many specs, one queue
Classifies each spec and runs standard or lite. Skips work that already shipped. Pauses with clear choices if a spec fails.
{plansDir}/ws-spec-multi/Discover every shipped skill. Search by name, layer, or full vs lite.
Flexible installation presets powered by bin/skill-dependencies.json dependency graph.
f
Full package — selects every installable top-level skill and initializes the ws-shared/ config/docs hub.
ws-shared/ config & docs hubw
Workflows package — 44 skills (orchestrators, pipeline, providers, harness, promoted utilities) plus the ws-shared/ hub.
ws-spec-to-pr, ws-spec-to-pr-lite, ws-spec-write, ws-classify-complexity, ws-plan-write, ws-plan-interview, ws-plan-to-tasks, ws-implement-tasks, … (+36)
e
Extra package — 7 optional authoring/review skills. Does not install workflow orchestrators or hub by default.
ws-write-a-skill, ws-show-harness, ws-preview, ws-activity-report, ws-fable-domain, ws-plan-update, ws-run-benchmark
Canonical installation form: npx --yes github:jpolvora/workflow-skills.
Preserves consumer-owned files under .agents/skills/ws-shared/.
Launch the interactive visual installer to select skills and packages.
npx --yes github:jpolvora/workflow-skills
Refresh managed skills listed in ws-shared/installed-skills.json while preserving local config.
npx --yes github:jpolvora/workflow-skills update
npx --yes github:jpolvora/workflow-skills update --include-new
Verify current local installed version against latest remote release.
npx --yes github:jpolvora/workflow-skills --check
npx --yes github:jpolvora/workflow-skills --version
Execute CLI directly via shell pipeline (requires Node.js).
curl -fsSL https://raw.githubusercontent.com/jpolvora/workflow-skills/main/install-skills.sh | bash -s --
Copy-paste integration recipes for Cursor, OpenCode, Claude Code, and Antigravity.
---
description: Spec-driven harness and workflow skills router
globs: .agents/**/*, **/*.spec.md
---
# Workflow Skills Harness
Read .agents/skills/ws-shared/AGENTS.md for project configuration and task routing.
Follow ws-spec-to-pr for standard pipeline, or ws-spec-to-pr-lite for low-complexity changes.{
"$schema": "https://opencode.ai/schema.json",
"instructions": [
".agents/skills/ws-shared/AGENTS.md"
],
"skills": {
"local": ".agents/skills",
"global": "~/.agents/skills"
}
}# Claude Code Spec-Driven Instructions
At session start, read .agents/skills/ws-shared/AGENTS.md.
Use `npx --yes github:jpolvora/workflow-skills` to update or install skills.
All changes require a spec file under .agents/specs/*.spec.md.# Antigravity / Gemini CLI Instructions
Load project settings from .agents/skills/ws-shared/config.json.
When running multi-spec batches, invoke ws-spec-multi.
Adhere to surgical code hygiene and verify ledger scoring.# Install global skills once
npx --yes github:jpolvora/workflow-skills --global
# Configure current project (in your coding agent)
/ws-configure-project
# Verify harness integrity (in your coding agent)
/ws-check-harnessNot in the current package. Shipped capabilities are on Features.
ws-{family}-{verb})us-235)Spec-driven delivery, orchestrators, quality gates, and agent harness compatibility.
Workflow Skills is a portable, spec-driven skill pack for coding agents. You install it once. The agent then runs a named pipeline from a feature spec to a reviewed pull request instead of inventing a process each time.
The spec is the contract of record. Plans are run artifacts. Standard delivery is ten steps. Lite is six. Skills are LLM-agnostic: any coding agent that can load SKILL.md can run the pipeline. Verify must hit ≥ defaults.minVerifyScore (default 9) from the AC ledger before review. GitHub and Azure DevOps expose the same PR operations. Your project config and memory stay local when skills update.
Yes. Delivery is spec-driven:
*.spec.md under the specs directory (local draft, GitHub issue, or Azure DevOps work item).defaults.minVerifyScore (default 9).This upstream repo uses the same model. Extra skills (direct problem-solving, doctor, preview) sit beside the pipeline; they do not replace the spec contract.
Pick by how much process you want:
ws-spec-to-pr): ten steps. Plan interview, task graph, verify at ≥ minVerifyScore (default 9), commit, review, tests, PR, thread fixes.ws-spec-to-pr-lite): six steps. Plan, implement, commit, review, PR. No interview, DAG, or test step.Product files are committed before local code review, not first at ship:
defaults.minVerifyScore, default 9), then Step 6 reviews git diff {base}...HEAD. Review fixes get a second product commit.status: completed), then optional push/PR. Plan files stay uncommitted until close. Shipping uses shipStatus, not workflow completion.Only workflow-touched created/updated/deleted product paths are staged. Never git add -A. Review fails closed if those files are still uncommitted.
Standard Step 5 (ws-plan-verify) advances only at overall score ≥ defaults.minVerifyScore (default 9, range 1–10).
scoreAndRefine (re-implement flagged tasks, then re-verify) until ≥ defaults.minVerifyScore.autoMode.defaults.minVerifyScore and the scoreAndRefine flag is on. Choosing Second Pass reviews the full Pass 1 diff for overengineering and unused workflow-introduced files, tests, methods, and classes.Lite has no Step 5 verify gate. Product commit on standard runs only after score ≥ defaults.minVerifyScore (default 9). Uncovered Negative & Failing Test Scenarios cap the derived score at 8.
Authoring a spec requires Definition of Ready, Validation & Observation Notes, and Negative & Failing Test Scenarios. validate_spec.cjs --mode=authoring fails closed if those sections are missing or placeholder.
Interview audits failing-test coverage. Implement-tasks is red-then-green. Verify treats uncovered negative scenarios as a known defect and caps the score at 8.
ws-spec-multi is a sequential smart multi-spec batch orchestrator. A blank scan lists only pending and unfinished specifications under {specsDir}, runs ws-classify-complexity on each selected spec to dynamically select between Standard or Lite pipeline execution, and processes them one by one.
It maintains state persistence under {plansDir}/ws-spec-multi/ (allowing safe session pauses/resumes), skips specs with already-merged PRs, and presents structured user-gate choices if a spec encounters an issue.
No! Workflow Skills maintains a strict separation between managed skill files and consumer-owned project data.
Files located under .agents/skills/ws-shared/ — including config.json, STACK.md, MEMORY.md, memory entries, and CHANGELOG.md — are strictly preserved during all updates and uninstalls. Only managed SKILL.md definitions and skill scripts are updated from canonical upstream releases.
Yes. Dual routing is controlled by enableMemoryFiles and enableSpecMemoIntegration. Default is local MEMORY files on and spec-memo off unless you opt in.
ws-spec-memo is the harness setup/bridge (wizard, import, config.json flags, hybrid fallback). Runtime vault ops (search, upsert, bootstrap, canvas) use ws-memo from the spec-memo package. When both backends are on, consult the vault first, then local MEMORY.
Workflow Skills includes multiple layers of automated defense:
ws-plan-verify: Spec compliance score 0–10. Standard Step 5 advances only at ≥ defaults.minVerifyScore (default 9); below the bar runs scoreAndRefine until that bar (max 3 rounds).ws-senior-developer: Delivery gate enforcing surgical diff footprints, anti-reinvention checks, and pre-ship verification proof.ws-fable-judge: Adversarial audit engine performing diff-grounded verification to detect 4 classic AI code frauds (weakened unit tests, false verification claims, unauthorized side effects, and scope creep).ws-secrets-leak-review: Pre-PR scanner checking diffs for hardcoded API tokens, private keys, passwords, and sensitive credentials.ws-doctor: Read-only install/runtime diagnose of path errors, script recipes, config switches, and missing skill references.Yes. Skills are markdown plus scripts. Any coding agent that can load SKILL.md can run the pipeline. There is no required host or IDE, and shipped skill bodies do not couple to a vendor UI.
GitHub and Azure DevOps share the same PR operations. Config, memory, and changelog stay in your repo when skills update.
You can run ws-configure-project or edit .agents/skills/ws-shared/config.json directly. Key configurable options include:
plans.dir: Target folder for workflow plans and execution artifacts (default: .agents/plans).providers.scm: Active SCM provider (github via gh CLI, azure-devops via ADO PAT). Both implement the same required intents in scm-provider-contract.md (parity checked in npm run test). Hybrid: providers.active: local with scm: github.rules.stackFile: Path to project technology stack guidance (default: .agents/skills/ws-shared/STACK.md).verification.*: Build, test, format, and optional mutation commands.preview.dryRunCommand: Local pipeline review dry-run for /ws-preview (set via /ws-configure-project --section preview, which can infer from AGENTS/README/MEMORY/rules/scripts; empty until configured).defaults.testingModel: Optional test-executor model for standard Step 7 (falls back to executionModel).ws-preview does not ship a reviewer backend. It runs whatever command you set in preview.dryRunCommand from the consumer repo root, and never publishes PR threads.
Recommended setup: /ws-configure-project --section preview. The wizard infers candidates from AGENTS.md, README.md, MEMORY, rules.*, package.json scripts, and local skills, then asks you to accept, edit, or leave empty. You can also edit .agents/skills/ws-shared/config.json directly (see config.json.example).
Yes. Both SCM providers implement the same required intents: validate-auth, fetch-to-spec, create-pr, list-threads, sweep-prior-work, check-pr-status, resolve-thread, comment-issue, and merge-pr.
The contract lives in .agents/skills/ws-shared/scm-provider-contract.md. Host CLI recipes stay inside each provider. An extra intent on one side without the other (and without an allowlist row) fails npm run test via test/test-provider-parity.js.
The local spec provider is not an SCM implementer. It registers specs and delegates PR intents to providers.scm.
Yes! To author a new skill, use our meta-skill ws-write-a-skill. It guides you through defining standard YAML frontmatter (name, description, version), applying progressive disclosure principles, and structuring helper scripts.
Lasting skill improvements can be submitted via Pull Request to the canonical upstream repository: jpolvora/workflow-skills. When that clone and a global ~/.agents/skills install both exist, edit only the clone; see README § This clone vs a global install.
ws-doctor is a read-only install/runtime diagnose: path errors, tool/script recipes, config switches, and missing references across installed ws-* skills. Use it after install/update or when a skill recipe fails.
ws-check-harness is the meta-harness integrity audit (routing, links, portability, integrity digests).
On a new ws-spec-to-pr / lite start (not resume), bootstrap asks how to isolate the run: stay on the current branch, create feat/{slug} from HEAD, or create it from baseBranch (after fetch). Resume skips this gate and checks out state.branch.
The gate never rewrites config.project.workingBranch. It will not git reset, delete branches, or overwrite an existing feature branch.
Optional model preference for standard Step 7 (testing). modelsPreset / stepModels overrides apply first. When set, the orchestrator prefers that model for the test executor subagent. Empty or omitted falls back to defaults.executionModel, then the active session model. Lite has no Testing step and does not read testingModel.
Lasting skill changes ship here. Consumer installs stay managed copies.
Skills live in .agents/skills/<name>/SKILL.md with standard YAML frontmatter (name, description, version).
If this clone and a global install (~/.agents/skills) both exist, edit only .agents/skills/ws-* in the clone. Do not edit the global copies from this repo. There is no IDE toggle that hides the duplicate; agents follow AGENTS.md § Global vs local ws-*.
Agents: see AGENTS.md for the full routing contract.
Humans: see README.md for install and contribution guidelines.