SpecWorkflow

English | 中文

SpecWorkflow is a shareable workflow skill pack for DeepSeek Harness and other Agent Skills-compatible tools. It gives an agent a disciplined path from a rough request to requirements, an implementation spec, code execution, delivery review, repair planning, bug diagnosis, and source-backed research.

It is intentionally not a heavy process for every request. Small, concrete edits can stay direct; ambiguous, cross-module, product-facing, data, permission, API, or release-sensitive work gets promoted into the full workflow.

dsh plugin --profile web add specworkflow
dsh web

npx specworkflow install codex

Install globally with -g:

npx specworkflow install -g codex

Replace codex with another preset when needed:

Unknown plain names are rejected so a typo does not create the wrong folder. For unsupported agents, pass an explicit project-level skills path:

npx specworkflow install .my-agent/skills

With -g, relative explicit paths are resolved from your home directory.

Typical feature work:

Use to-grill to clarify this request, then move to to-spec when the requirement is ready.

Simple edits should stay simple:

Make the table font larger.

SpecWorkflow should route that kind of request to direct implementation instead of forcing the full five-stage path.

SpecWorkflow does not start by writing a spec. It starts by deciding whether the request deserves one. Small, obvious work such as copy edits, style tweaks, or a missing guard should stay direct.

The full route is for work with product meaning, data semantics, permission boundaries, cross-module impact, release risk, or enough ambiguity that guessing would be expensive. Once a request enters the route, keep its artifacts under one .spec-workflow/<feature-slug>/ folder so every later pass has the same source of context.

to-grill -> to-spec -> spec-do -> do-review -> fix-review -> spec-do repair -> do-review

to-grill turns a vague request into something solid. It should inspect the repo before asking questions, separate facts the code can answer from decisions only the user can make, and decide whether the work should be direct, deferred, or promoted into a spec. When it hands off, it leaves a requirements conclusion that the next stage can actually use.

to-spec turns that conclusion into an implementation contract. A useful spec names the scope, the non-goals, the affected modules, the data and permission rules, the user-visible behavior, and the evidence that will prove the work is done. If the task is changing an existing spec, it records the amendment and its impact instead of pretending the work starts from a blank page.

spec-do is the first stage that should touch production code. It checks the branch and dirty worktree, consumes the commit policy already chosen for a Goal run, and works from the approved spec, tickets, amendment, or repair plan. In staged execution it asks about commit permission before editing. Temporary evidence can live under .spec-workflow, but durable tests belong in the project's own test tree. Business logic should be wired for real, not mocked away just to make a validation run pass.

When implementation claims to be finished, do-review decides whether that claim holds. It compares the original request, spec, code diff, tests, and evidence, then looks for missed requirements, regressions, edge cases, and acceptance gaps. Review is not a quiet repair pass and not a place to expand scope; its job is a clear ship / no-ship judgment.

If the review finds must-fix issues, fix-review turns them into a focused repair plan. It cares about root cause, priority, verification, and whether the repair should be split into tickets. That plan goes back to spec-do, and the repair returns to do-review. The loop stays short: repair what blocks delivery, then review again.

deep-research and bugs-fix sit beside the main route rather than inside it. Reach for deep-research when the answer depends on primary sources, official docs, API behavior, standards, or external facts. Start with bugs-fix when the problem is already a failure, regression, exception, or performance issue; reproduce first, then diagnose the root cause.

Choose Goal Mode at the end of to-spec, after requirements, testing, optional tickets, branch handling, and the finished spec are settled. The final choice shows the exact spec version, completion target, repair limit, execution backend, and whether commits are allowed. An earlier request to "run autonomously" is recorded as a preference; it does not start execution.

The Goal round limit defaults to 3, with 5, 10, and Custom alternatives. It caps automatic repair cycles for the current spec; the run finishes early when the goal is met. Choose the limit before the final execution-mode choice. Host continuation limits and token budgets are separate.

Choosing the mode authorizes the run. Starting it requires a separate, real host action. On a host exposing goal tools, the agent must create or reuse the matching goal and read back its state. If the host needs a composer command or UI action, the workflow reports that it is waiting for activation. Writing Goal mode: enabled in a spec does not activate the host.

After verified activation, implementation, review, repair planning, and repair execution continue without repeating settled questions. The agent fixes in-scope defects and chooses technical details itself. A new product decision, scope change, unresolved ownership, unavailable required validation, or exhausted limit records a blocker before requesting input. Each new spec or amendment gets its own final choice.

Persistent goals are not a universal Agent feature. A host without a verified goal or loop can offer explicitly labeled session-only execution: continue within the current invocation, with no promise of automatic continuation after the host ends the turn. Auto-approval and permission-bypass flags do not turn it into a persistent goal. Host-specific entries and verification requirements are bundled in the runtime adapters.

The bundled coverage catalog contains 30 named tools/products, including every host represented by the installer presets. It records startup steps, execution surfaces, lifecycle limits, and primary sources. Entries with insufficient evidence are marked as such rather than assigned a guessed Goal command.

For a new Agent, unavailable entry, changed version, or conflicting result, the built-in discovery procedure inspects local tools/help and current official docs or source. It saves the current host's findings under .spec-workflow/<feature-slug>/research/agent-runtime.md and verifies real activation before implementation. The installed skill is not rewritten automatically, and discovering a mechanism does not authorize installing a plugin, changing permissions, or launching cloud work.

Each of the seven skills carries the bilingual presentation and reading contract. Questions, progress, report headings and delivery conclusions follow the user's chosen language; they are not duplicated in both languages by default. Programming terms, actual command/API identifiers, paths and literal evidence keep their real spelling.

Language instructions keep their scope: requesting an English report in a Chinese conversation changes the report, not ordinary questions/progress. Only an explicit all-output switch changes everything. Child-agent prompts and recovery messages carry and reuse this resolved policy.

Later stages understand Chinese, English and mixed legacy labels while preserving the separate ticket, review and Goal-state domains. Translation does not grant authorization or reset repair counts. Skill-menu metadata has static strings rather than automatic locale selection, so it uses paired bilingual labels.

SpecWorkflow keeps workflow files under .spec-workflow so project code and agent evidence stay separate.

.spec-workflow/<feature-slug>/
  requirements.md
  spec.md
  issues/
  amendments/
  implementation/
  review/
  repair-spec.md
  repair-issues/
  verification/
  debug/
  bugs/
  research/

Project tests still belong in the project's real test directories, not under .spec-workflow.

After installing into DSH:

dsh --profile web --dump-config

The composed config should include:

# == specworkflow
- id: specworkflow
  name: specworkflow

You can also ask the agent which SpecWorkflow skills are available and when to use to-grill.

dsh plugin --profile web remove specworkflow

Replace web with the profile you installed into.

MIT. See LICENSE.