clawgo/spec.md

Project Scope (spec.md)

Overview

• What is being built: spec-driven coding support for ClawGo.
• Why this change is needed: coding tasks need a durable project scope, task plan, and verification gate instead of ad hoc reasoning scattered across chat turns.
• Desired outcome: ClawGo should guide non-trivial coding work through spec.md, tasks.md, and checklist.md, expose that workflow in workspace policy, make active project docs visible to the agent during execution, and keep tasks.md progress moving automatically during coding turns. Completed tasks should also be reopenable when later debugging or regression work shows the task is not actually done.

In Scope

• Add a built-in spec-coding skill.
• Provide a scaffold script for spec.md, tasks.md, and checklist.md.
• Update workspace agent policy to prefer this workflow for non-trivial coding work.
• Load current-project spec docs into agent context when present.
• Document the workflow in the repo README.

Out of Scope

• A dedicated planner UI for spec documents.
• Automatic task execution directly from tasks.md.
• Complex state synchronization beyond markdown documents.

Decisions

• Use plain markdown files named exactly spec.md, tasks.md, and checklist.md.
• Default location is the current project root, not the long-term workspace directory.
• Expose the workflow primarily through workspace policy + built-in skill, not a new core planner service.
• Load project docs into the system prompt with truncation to keep context bounded.
• Only activate this workflow automatically for coding-oriented tasks, not for general chat or non-coding work.
• Treat workspace/skills/spec-coding/ as template storage only; project-specific docs must live in the target coding project.

Tradeoffs

• Loading project docs into prompt improves continuity but increases token usage when the files exist.
• Root-level markdown files are simple and transparent, but they do add repo-visible artifacts.
• A skill + prompt workflow is faster to adopt than introducing a new runtime subsystem, but it depends on agent discipline.

Risks / Open Questions

• tasks.md can grow large; prompt truncation mitigates this but may eventually need smarter summarization.
• Some users may prefer a nested path such as .clawgo/specs/; current default stays simple unless explicitly requested.