MoonCoder-HAPPY/SpecWorkflow

SpecWorkflow

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.

What It Does

Install

DSH

dsh plugin --profile web add specworkflow
dsh web

Other Agents

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.

Quick Start

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.

Workflow

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, dirty worktree, and auto-commit permission before implementation, then works from the approved spec, tickets, amendment, or repair plan. 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.

Goal Mode is a continuous-execution switch for one spec at a time. Once the user explicitly enables it, the agent can move through implementation, review, repair planning, repair implementation, and another review without pausing at every handoff. It is not unlimited permission: product choices, safety concerns, git decisions, validation gaps, environment problems, and scope changes still stop the run.

Directory Output

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.

Verify

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.

Uninstall

dsh plugin --profile web remove specworkflow

Replace web with the profile you installed into.

License

MIT. See LICENSE.