From Spec to Delivery

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 of record — canonical *.spec.md under the specs directory (local draft, GitHub issue, or Azure DevOps work item).
• Plans are runs — workflow copies and state live under the plans directory. A plan is not a second spec.
• Acceptance criteria gate code — standard verify derives its 0–10 score from an AC ledger. Agents cannot author or override that score. Advance only at score ≥ defaults.minVerifyScore (default 9).

This upstream repo uses the same model. Extra skills (direct problem-solving, doctor, preview, human runbook) sit beside the pipeline; they do not replace the spec contract. ws-spec-translate-to-human writes a numbered implementation and UI-test runbook next to the spec. The pipeline still runs if that file is absent.

Pick by how much process you want:

• Standard (ws-spec-to-pr): ten steps. Plan interview, task graph, verify at ≥ minVerifyScore (default 9), commit, review, tests, PR, thread fixes.
• Lite (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:

• Standard: after Step 5 verify (score ≥ defaults.minVerifyScore, default 9), then Step 6 reviews git diff {base}...HEAD. Review fixes get a second product commit.
• Lite: after Step 2 implement, then Step 3 review; second commit after review fixes if any.
• Ship (Step 8 / lite Step 4): close implementation first (plan-dir G2-delivery, MEMORY, changelog, 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).

• Score below the bar: the orchestrator runs scoreAndRefine (re-implement flagged tasks, then re-verify) until ≥ defaults.minVerifyScore.
• Max 3 rounds per Step 5 visit; then Pause (fail closed). Resume continues. Never auto-approve below the bar, including in autoMode.
• Optional polish (Accept As-Is) only when the score is already ≥ 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 per-run {plansDir}/{runId}/ directories (legacy flat {plansDir}/ws-spec-multi/*.state.md files still resume), allowing safe session pauses/resumes. It 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.

Project .ws/config.json, STACK.md, and installed-skills.json stay put on update and uninstall. MEMORY.md, memory/, and CHANGELOG.md follow rules.memoryDir and rules.changelogFile (repo root by default) and are never overwritten from upstream. Update replaces managed skill files only.

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 .ws/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: .ws/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 .ws/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, close-issue, and merge-pr.

The contract lives in {skillsRoot}/ws-shared/runtime/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.

Closes #{id} stays in the PR body. GitHub auto-closes that issue only when the PR base is the repository default branch. After a merge with zero active threads, ship dispatches close-issue on any base. comment-issue stays a comment. Local specs (id: null) skip the close with exit 0.

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.

Yes. Pass preset=<name> (or --preset <name>) on the ws-spec-to-pr / ws-spec-to-pr-lite invocation and that run resolves subagent models from the named bundle instead of defaults.modelsPreset — no config.json edit needed.

Unknown names warn in telemetry and the Init banner and fall back to the configured preset. The resolved preset persists in workflow state and survives resume without re-passing the flag. The orchestrator session itself always stays on the active model.

ws-goal-fix-pr acts as an orchestrator: its session owns the wait/fetch convergence loop inline, while every Act round batch runs in a freshly dispatched worker. Each worker runs one ordered pair — reviewer-model fixPrPlan writes the complete gate before any mutation, then execution-model fixPrExec validates and applies it.

Hosts without subagent dispatch use documented Tier 3 inline execution with identical gate and learning contracts. Resolve and push stay forbidden until both substeps have evidence.

Specialized subagents project canonical .agents/skills/ws-* definitions into native host agent formats, such as .cursor/agents/ws-step-*.md. Each compiled subagent embeds domain instructions, behavioral rules, and JSON schemas directly into its prompt with disable-model-invocation: true, eliminating the prompt token tax of reading SKILL.md on boot.

Canonical skills remain the single source of truth: compile_host_subagents.cjs signs generated files with @generated hashes to prevent clobbering human-authored agents and detects drift via --check. If specialized subagents are disabled or unsupported, the orchestrator automatically falls back to generic subagent prompts or inline execution.

Three things:

• Node 22+ — the only required runtime. Install, update, skills, and scripts all run on npx/Node. No Python, no shell toolchain.
• A coding agent that can load SKILL.md — any host works; there is no required IDE.
• Your SCM CLI — gh for GitHub or an ADO PAT for Azure DevOps, only if you want issue/PR operations. Local-spec runs need neither.

After install, ask your agent to run ws-check-harness once, then /ws-configure-project to fill .ws/config.json (or use the desktop GUI via npm run config:gui on Windows).

Five steps, in order:

• 1. Install — npx --yes github:jpolvora/workflow-skills install --full --yes in your repo.
• 2. Configure — /ws-configure-project (interview) so builds, tests, and the SCM provider match your repo.
• 3. Write a spec — describe the feature; the agent drafts a testable *.spec.md with acceptance criteria.
• 4. Run the pipeline — ws-spec-to-pr-lite for a fast first run, ws-spec-to-pr for the full gated path.
• 5. Review the PR — code is committed before review and shipped only after close; fix-PR rounds converge review threads.

Unsure which pipeline fits? ws-classify-complexity recommends lite vs standard from your spec.

• Project-local (.agents/skills/) — best for teams and CI: the skills travel with the repo and every run uses the same version.
• Global (~/.agents/skills) — best for solo work across many repos: install once, use everywhere. Global runs still read and write project config from the open repo, never from the global hub.
• Hybrid — both installed: project-local skill bodies win, global fills gaps, and project .ws/config.json always wins over global defaults.

Global installs can also project into companion host targets (Claude Code, Codex, Gemini/Antigravity) via --targets. ws-version shows which scope a session actually loaded.

The pipeline fails closed and tells you how to resume — it never auto-approves a weak state:

• Below the verify bar — scoreAndRefine re-implements and re-scores up to 3 rounds, then Pauses with the deficiencies listed.
• Review loops — fix → re-review runs max 3 rounds, then Pause.
• Resume — re-invoke the orchestrator on the same slug; atomic state plus telemetry.jsonl restore the exact step. ws-monitor shows which step and gate a run is waiting on.

Genuine blockers (missing credentials, ambiguous scope, failing base branch) surface through a user-gate choice instead of a guess.

Two read-only views, no interference with the run:

• ws-monitor --watch --until-terminal — polls until the run leaves active state, tracks a stall stopwatch, follows the session transcript, and can file an anonymized defect issue when something hangs.
• ws-kanvas (npm run kanvas) — a six-column board of spec and workflow state with drag-and-drop moves.

In autoMode the orchestrator chains steps 0→9 without yielding at internal checkpoints; mid-step progress survives host turn ends via checkpoint / turn-boundary pause records.

• index.PRD — the project spec board. Specs are tracked as pending on write/import and flipped to done with a Done-log row when delivery evidence (commit or PR URL) exists.
• Status subfolders — opt in with plans.statusSubfolders to file specs under pending/, completed/, archived/; sync moves shipped specs automatically and a close verifier fails if a done row still points at pending/.
• ws-spec-manager — one front door for create/list/update/sync/organize/archive/validate/import/run, so agents stop guessing which skill owns the task.

Before the ship phase opens a PR, the close step files a documentation trio so docs reflect shipped code:

• ws-wiki sync — living feature wiki pages for the shipped behavior (warn-skips when no wiki is configured).
• ws-spec-index sync — flips the spec row to done and files the spec into completed/.
• Changelog entry — append-only record of prompt, done, and result.

Governed by defaults.requirePreShipDocSync (default true; omitted or invalid also means true). Set false to restore the previous offered-wiki behavior.