[Feature]: Clarify custom checklist ownership and lifecycle

[mnriem]

Problem Statement

The published documentation describes /speckit.checklist as a quality gate and "unit tests for requirements," and tells users to review generated checklists before proceeding. The command templates reinforce that custom checklists capture user-supplied focus areas, risks, audiences, and must-have criteria that the standard workflow cannot infer.

However, neither the published documentation nor the executable command documentation explicitly defines who owns the checkbox state, what [x] means, or when items should be marked complete.

This is especially ambiguous because two checklist lifecycles share the same checklists/ directory and checkbox format:

• checklists/requirements.md, created and automatically evaluated by /speckit.specify and re-evaluated by /speckit.clarify.
• Custom checklists created by /speckit.checklist, which encode reviewer-supplied requirements-quality insights. /speckit.implement treats these as opaque gates by counting checkbox state rather than interpreting or resolving their criteria.

As a result, users can reasonably conclude that the implementation agent should check off custom checklist items, even though /speckit.checklist does not instruct the agent to evaluate them and /speckit.implement is only intended to read their status.

Proposed Solution

Make the existing implicit contract explicit across the published and executable documentation:

• Explain that custom checklists are reviewer-owned requirements-quality review artifacts. An agent may assist with evaluation when explicitly asked, but implementation must not silently self-approve them.
• Define [x] as "the reviewer determined this requirements-quality criterion is satisfied," not "the implementation work is complete."
• State that /speckit.implement treats checklist files as read-only gates and must not modify their markers.
• Distinguish the agent-maintained checklists/requirements.md lifecycle from custom checklists generated by /speckit.checklist.
• Apply consistent wording in docs/quickstart.md, docs/reference/agentic-sdd.md, templates/commands/checklist.md, templates/checklist-template.md, and templates/commands/implement.md.

Alternatives Considered

Rely on the existing "custom checklist" and "review the generated checklist" wording as a nudge. That communicates some design intent, but it does not define ownership or state transitions and is weakened by the agent-maintained checklist using the same directory and syntax.

Separating checklist types into different directories or adding ownership metadata could make the distinction machine-readable, but that would be a larger behavioral change. This issue proposes documenting the current contract first.

Component

Documentation

AI Agent (if applicable)

All agents

Use Cases

1. A reviewer creates a security, accessibility, compliance, or domain-specific checklist from insights unavailable to the standard workflow.
2. A user needs to know whether unchecked items should be resolved manually, through /speckit.clarify, or by asking an agent to assist.
3. An implementation agent encounters custom checklist files and must preserve their review state.
4. A user needs to distinguish custom review checklists from the automatically maintained requirements.md checklist.

Acceptance Criteria

• Published documentation distinguishes agent-maintained and custom checklist lifecycles.
• Documentation defines custom checklist ownership and checkbox semantics.
• The checklist command and canonical checklist template communicate the same ownership model.
• The implement command explicitly treats checklist markers as read-only.
• Documentation explains that checked custom criteria concern requirements quality, not implementation completion.
• Guidance is consistent across all supported agents.

Additional Context

Raised from discussion: #2387 (reply in thread)

Follow-up clarification: #2387 (comment)

Filed on behalf of @mnriem by GitHub Copilot (model: GPT-5.6 Sol).