clawgo/workspace/skills/spec-coding/SKILL.md

name, description

name	description
spec-coding	Drive non-trivial coding work through spec.md, tasks.md, and checklist.md in the current project root. Use for feature delivery, multi-file refactors, architectural changes, or any implementation that needs scope control and explicit verification.

Spec Coding

Use this skill for non-trivial coding work. The goal is to keep implementation aligned with a living spec, an explicit task breakdown, and a final verification gate.

Important:

• The files inside workspace/skills/spec-coding/ are templates and workflow instructions only.
• Real project state must live in the coding target project itself.
• Do not treat the skill directory as shared runtime state across projects.
• Do not turn this on for small tweaks or lightweight edits unless the user explicitly asks for spec-driven workflow.

Files

Maintain these files in the current coding project root by default:

• spec.md
• tasks.md
• checklist.md

If the user explicitly asks for a different location, follow that instead. Do not create these files for non-coding tasks unless the user explicitly wants the workflow.

Intent

• spec.md is the north-star document. It explains what is being built, why it matters, what is in scope, what is out of scope, and which decisions / tradeoffs were made.
• tasks.md is the live implementation plan. It breaks the spec into modules, tasks, and ordered execution steps. Update it as work progresses.
• checklist.md is the completion gate. Only mark the project done after walking this file and confirming implementation, behavior, and validation are complete.

Workflow

1) Bootstrap

If any of the three files are missing, scaffold them first.

Use:

skill_exec(spec="spec-coding", script="scripts/init.sh")

Optional target directory:

skill_exec(spec="spec-coding", script="scripts/init.sh", args=["/path/to/project"])

2) Write / refine the spec

Before substantial code changes:

• summarize the problem
• define desired outcome
• define in-scope / out-of-scope
• capture decisions and tradeoffs
• note risks / open questions

Keep it concrete and engineering-oriented.

3) Expand into tasks

Break the spec into:

• modules or workstreams
• sub-tasks
• ordered implementation steps

Update statuses as you progress. The task plan is expected to evolve.

4) Implement against the plan

As work changes:

• update spec.md when scope or key decisions shift
• update tasks.md as tasks are completed / deferred / added
• do not wait until the end to synchronize the docs

5) Verify before close-out

When implementation is done:

• walk checklist.md
• verify code changes
• verify tests / validation
• verify no obvious scope gaps remain

Do not declare completion until the checklist has been reviewed.

Quality bar

• Prefer concise, structured markdown over long prose.
• Keep docs useful for resuming work in a later session.
• Avoid fake precision; if something is undecided, mark it explicitly.
• For small one-file edits, skip this workflow by default.
• For anything multi-step or multi-file, this workflow should be visible in the repo.