specai-living-documents

Files (3)

• SKILL.md
• _design.md · templates/
• _spec.md · templates/

SKILL.md (first lines)

# Living documents

Full and Mini use the same six documents. Give each fact one owner:

- `prd.md`: problem, desired outcome, scope and exclusions. Do not copy design.
- `spec.md`: behavior, invariants and the delta to project specs.
- `designs.md`: chosen approach and why; record only material alternatives.
- `plan.md`: execution order and material decisions, blockers or changes of
  direction. Do not copy the task list or keep a command diary.
- `tasks.md`: the only task list. Each task names exact files, intended change,
  dependencies, parallelizability, criterion IDs, one focused command and
  expected result, and status. Add steps only when the command needs them.
- `verify.md`: global Given/When/Then criteria, type, seam, exact check,
  current-HEAD evidence, failures/correctives and manual HTD. Derive coverage
  from criterion IDs in `tasks.md`; do not repeat it in a matrix.

The compact task and verification forms are preferred for new features. The
validators continue accepting historical forms; do not rewrite archives.

After a task's focused test or direct check passes, update `tasks` to mark its
state `completed` and commit that task's code and documentation together. Record
a plan entry only for a decision, blocker, corrective batch, or outcome needed
to resume or understand the work. Use the three states defined by
`specai-writing-plans`. While the next eligible task is being implemented,
documentation for the previous task may be updated in parallel; serialize
shared-document writes and commits, and stage only the completed task's changes.

Do not run code review per task. Update `verify` at the single global gate,
not after every task-local check. A failure preserves its criterion and
evidence and adds a traceable corrective task. The manual HTD is completed in
verify after global PASS; plan references it but does not duplicate it.

Keep execution notes factual and brief. Do not duplicate PRD, spec, design,
task, or verification content in the plan.

From ArceApps-dev/specai, MIT.

More from ArceApps-dev/specai