Spectra Propose

• Option 1: Use the plan file
• Option 2: Use conversation context

• plan_title (H1 heading) → use as requirement description
• plan_context (Context section) → use as proposal Why/Motivation content
• plan_stages (numbered implementation stages) → use for artifact creation
• plan_files (all file paths mentioned) → use for Impact section

Classify the change type

Based on the requirement, classify the change into one of three types:

This determines the proposal template format in step 5.

Scan existing specs for relevance

Before creating the change, check if any existing specs overlap:

1. Use the Glob tool to list all files matching docs/openspec/specs/*/spec.md
2. Extract directory names as the spec identifier list
3. Compare against the user's description to identify related specs (max 5 candidates)
4. For each candidate (max 3), read the first 10 lines to retrieve the Purpose section
5. If related specs are found, display them as an informational summary

IMPORTANT:

• If related specs are found, display them but do NOT stop or ask for confirmation — continue to the next step
• If no related specs are found, silently proceed without mentioning the scan

Create the change directory

spectra new change "<name>" --agent claude

If a change with that name already exists, suggest continuing the existing change instead of creating a new one.

Write the proposal

Get instructions:

spectra instructions proposal --change "<name>" --json

Write the proposal file using the template from instructions, with the following format based on change type:

Feature

## Why

<!-- Why this functionality is needed -->

## What Changes

<!-- What will be different -->

## Non-Goals (optional)

<!-- Scope exclusions and rejected approaches. Required when design.md is skipped. -->

## Capabilities

### New Capabilities

- `<capability-name>`: <brief description>

### Modified Capabilities

(none)

## Impact

- Affected specs: <new or modified capabilities>
- Affected code: <list of affected files>

Bug Fix

## Problem

<!-- Current broken behavior -->

## Root Cause

<!-- Why it happens -->

## Proposed Solution

<!-- How to fix -->

## Non-Goals (optional)

<!-- Scope exclusions and rejected approaches. Required when design.md is skipped. -->

## Success Criteria

<!-- Expected behavior after fix, verifiable conditions -->

## Impact

- Affected code: <list of affected files>

Refactor / Enhancement

## Summary

<!-- One sentence description -->

## Motivation

<!-- Why this is needed -->

## Proposed Solution

<!-- How to do it -->

## Non-Goals (optional)

<!-- Scope exclusions and rejected approaches. Required when design.md is skipped. -->

## Alternatives Considered (optional)

<!-- Other approaches considered and why not -->

## Impact

- Affected specs: <affected capabilities>
- Affected code: <list of affected files>

Get the artifact build order

spectra status --change "<name>" --json

Parse the JSON to get:

• applyRequires: array of artifact IDs needed before implementation
• artifacts: list of all artifacts with their status and dependencies

Create remaining artifacts in sequence

Loop through artifacts in dependency order (skip proposal since it's already done):

a. For each artifact that is ready (dependencies satisfied):

• Check if the artifact is optional: If the artifact is NOT in the dependency chain of any applyRequires artifact (i.e., removing it would not block reaching apply), it is optional. Get its instructions and read the instruction field. If the instruction contains conditional criteria (e.g., "create only if any apply"), evaluate whether any criteria apply to this change based on the proposal content. If none apply, skip the artifact and show: "⊘ Skipped <artifact-id> (not needed for this change)". Then continue to the next artifact.
• Get instructions:

  spectra instructions <artifact-id> --change "<name>" --json
  

• The instructions JSON includes:
  • context: Project background (constraints for you - do NOT include in output)
  • rules: Artifact-specific rules (constraints for you - do NOT include in output)
  • template: The structure to use for your output file
  • instruction: Schema-specific guidance
  • outputPath: Where to write the artifact
  • dependencies: Completed artifacts to read for context
  • locale: The language to write the artifact in (e.g., "Japanese (日本語)"). If present, you MUST write the artifact content in this language. Exception: spec files (specs/*/.md) MUST always be written in English regardless of locale, because they use normative language (SHALL/MUST).
• Read any completed dependency files for context
• Create the artifact file using template as the structure
• Apply context and rules as constraints - but do NOT copy them into the file
• Show brief progress: "✓ Created <artifact-id>"

b. Continue until all applyRequires artifacts are complete

• After creating each artifact, re-run spectra status --change "<name>" --json
• Check if every artifact ID in applyRequires has status: "done"
• Stop when all applyRequires artifacts are done

c. If an artifact requires user input (unclear context):

• Use AskUserQuestion tool to clarify
• Then continue with creation

Inline Self-Review (before CLI analysis)

After creating all artifacts, scan them manually. Fix issues inline, then proceed to the CLI analyzer.

Check 1: No Placeholders

These patterns are artifact failures — fix each one before proceeding:

• "TBD", "TODO", "FIXME", "implement later", "details to follow"
• Vague instructions: "Add appropriate error handling", "Handle edge cases", "Write tests for the above"
• Delegation by reference: "Similar to Task N" without repeating specifics
• Steps describing WHAT without HOW: "Implement the authentication flow" (what flow? what steps?)
• Empty template sections left unfilled
• Weasel quantities: "some", "various", "several" when a specific number or list is needed

Check 2: Internal Consistency

• Does every capability in the proposal have a corresponding spec?
• Does the design reference only capabilities from the proposal?
• Do tasks cover all design decisions, and nothing outside proposal scope?
• Are file paths consistent across proposal Impact, design, and tasks?

Check 3: Scope Check

• More than 15 pending tasks → consider decomposing into multiple changes
• Any single task would take more than 1 hour → split it
• Touches more than 3 unrelated subsystems → consider splitting

Check 4: Ambiguity Check

• Are success/failure conditions testable and specific?
• Are boundary conditions defined (empty input, max limits, error cases)?
• Could "the system" refer to multiple components? Be explicit.