Proposal Creation Guide

Guardrails

• Favor straightforward, minimal implementations first and add complexity

only when it is requested or clearly required.

• Keep changes tightly scoped to the requested outcome.
• Refer to spectr/AGENTS.md and spectr/project.md (located inside the

spectr/ directory—run ls spectr) if you need additional Spectr conventions or clarifications.

• Identify any vague or ambiguous details and ask the necessary follow-up

questions before editing files.

Note: You are not implementing yet, you are fully planning and creating the change proposal using spectr.

Steps

1. Review spectr/project.md, read spectr/specs/ and

spectr/changes/ directories, and inspect related code or docs (e.g., via rg/ls) to ground the proposal in current behaviour; note any gaps that require clarification.

1. Choose a unique verb-led change-id and scaffold proposal.md,

tasks.md, and design.md (when needed) under spectr/changes/<id>/.

1. Map the change into concrete capabilities or requirements, breaking

multi-scope efforts into distinct spec deltas with clear relationships and sequencing.

1. Capture architectural reasoning in design.md when the solution spans

multiple systems, introduces new patterns, or demands trade-off discussion before committing to specs.

1. Draft spec deltas in spectr/changes/<id>/specs/<capability>/spec.md

(one folder per capability) using ## ADDED|MODIFIED|REMOVED Requirements with at least one #### Scenario: per requirement and cross-reference related capabilities when relevant.

1. Draft tasks.md as an ordered list of small, verifiable work items that

deliver user-visible progress, include validation (tests, tooling), and highlight dependencies or parallelizable work. Note: After running spectr accept, both tasks.md (human-readable) and tasks.jsonc (machine-readable) will coexist—the former preserves formatting and context, while the latter becomes the runtime source of truth.

1. Validate with spectr validate <id> and resolve every issue before

sharing the proposal.

Reference

• Read delta specs directly at

spectr/changes/<id>/specs/<capability>/spec.md when validation fails.

• Read existing specs at spectr/specs/<capability>/spec.md to understand

current state.

• Search existing requirements with `rg -n "Requirement:|Scenario:"

spectr/specs` before writing new ones.

• Explore the codebase with rg <keyword>, ls, or direct file reads so

proposals align with current implementation realities.