spectra-propose-plus

name	spectra-propose-plus
description	Create a Spectra change proposal with sub-agent quality gates
license	MIT
compatibility	Requires spectra CLI.
metadata	{"author":"spectra","version":"1.0","generatedBy":"Spectra"}

Create a complete Spectra change proposal — from requirement to validated artifacts — in a single workflow.

Input: The argument after $spectra-propose is the requirement description. Examples:

• $spectra-propose add dark mode
• $spectra-propose fix the login page crash
• $spectra-propose improve search performance

If no argument is provided, the workflow will extract requirements from conversation context or ask.

Prerequisites: This skill requires the spectra CLI. If any spectra command fails with "command not found" or similar, report the error and STOP.

Steps

1. Determine the requirement source

   a. Argument provided (e.g., "add dark mode") → use it as the requirement description, skip to deriving the change name below.

   b. Plan file available:

   • Check if the conversation context mentions a plan file path (plan mode system messages include the path like <name>.md)
   • If found, check if the file exists at ``
   • If a plan file is found, use the AskUserQuestion tool to ask:
     • Option 1: Use the plan file
     • Option 2: Use conversation context
   • If conversation context has no relevant discussion, mention this when presenting the choice
   • If the user picks the plan file → read it and extract:
     • 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
   • If the user picks conversation context → fall through to (c)

   c. Conversation context → attempt to extract requirements from conversation history

   • If context is insufficient, use the AskUserQuestion tool to ask what they want to build

   From the resolved description, derive a kebab-case change name (e.g., "add dark mode" → add-dark-mode). Do not keep archive-style date prefixes in active change names. If the source name starts with YYYY-MM-DD-, strip that date prefix before running spectra new change; archived change names and directories are historical references, not active names to reuse.

   IMPORTANT: Do NOT proceed without understanding what the user wants to build.

2. Classify the change type

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

   Type	When to use
   Feature	New functionality, new capabilities
   Bug Fix	Fixing existing behavior, resolving errors
   Refactor	Architecture improvements, performance optimization, UI adjustments

   This determines the proposal template format in step 5.

3. 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 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

4. Create the change directory

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

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

5. Write the proposal

   IMPORTANT — file path rules for the ## Impact section:

   • All file paths SHALL be written relative to the project root (e.g., src/lib/foo.ts, src-tauri/crates/core/src/bar.rs, docs/specs/specs/auth/spec.md).
   • Do NOT use relative fragments (e.g., parser/mod.rs, core/mod.rs) — preflight rejects them as non-anchored paths.
   • Do NOT wrap shell commands in backticks inside artifact text (e.g., `git mv a.rs b.rs`) — preflight's backtick extractor will otherwise mis-parse the command as a file reference.
   • When referring to a file without naming its concrete path, use descriptive prose (e.g., "Parser 入口檔") rather than a backticked path fragment.

   Get instructions:

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

   Generate the proposal content based on change type (see formats below), then write it via CLI:

   spectra new artifact proposal --change "<name>" --stdin <<'ARTIFACT_EOF'
   <proposal content>
   ARTIFACT_EOF
   

   If the command fails with a validation error, fix the content and retry.

   Use 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:
     - New: <paths to be created, relative to project root>
     - Modified: <paths that already exist>
     - Removed: <paths to be deleted>
   

   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:
     - Modified: <paths that already exist>
     - New: <paths to be created, relative to project root>
     - Removed: <paths to be deleted>
   

   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:
     - Modified: <paths that already exist>
     - New: <paths to be created, relative to project root>
     - Removed: <paths to be deleted>
   

6. 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

7. 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 (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

   • Generate the artifact content using template as the structure

   • Apply context and rules as constraints - but do NOT copy them into the file

   • Write the artifact via CLI (the CLI handles directory creation and format validation):

     For design or tasks:

     spectra new artifact <artifact-id> --change "<name>" --stdin <<'ARTIFACT_EOF'
     <content>
     ARTIFACT_EOF
     

     For specs (one command per capability):

     spectra new artifact spec <capability-name> --change "<name>" --stdin <<'ARTIFACT_EOF'
     <delta spec content>
     ARTIFACT_EOF
     

     If the command fails with a validation error, fix the content and retry.

   • Show brief progress: "✓ Created "

   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

   Artifact language for propose-plus

   All change artifacts produced by spectra-propose-plus (proposal.md, design.md, tasks.md, and any other non-spec artifact under openspec/changes/<change>/) MUST be written in Traditional Chinese, regardless of whether the CLI provides a locale field.

   This applies to artifacts generated in step 5 (proposal) and step 7 (remaining artifacts), and to any artifacts modified during the review loop fix actions.

   Exception — spec files stay in English:

   • openspec/changes/<change>/specs/<capability>/spec.md (delta spec)
   • openspec/specs/<capability>/spec.md (master spec)

   Spec files MUST always be written in English because they use normative SHALL/MUST wording, and delta specs are later merged into master specs — mixing languages would cause merge conflicts and semantic drift. This is consistent with the existing locale rule documented above for spec files.

   Keep the following verbatim (do not translate) even inside Chinese prose:

   • Shell commands and CLI flags
   • File paths (absolute or repo-relative)
   • Code identifiers (function names, variable names, type names)
   • Schema field names (e.g., applyRequires, outputPath, dependencies)
   • Artifact IDs and capability slugs
   • Quoted source text from existing artifacts

   If the user explicitly requests another language later, follow the latest user instruction.

   The goal is predictable Chinese-facing artifacts for propose-plus while preserving exact technical references and keeping spec deltas compatible with master specs.

8. Sub-Agent Review/Rating/Fix Loop

Run this review/rating/fix loop once per change, after the normal workflow has completed its required artifact or task work.

Entry conditions

• For spectra-propose-plus, start this loop only after proposal, design, specs, and tasks artifacts required for apply are complete.
• For spectra-apply-plus, start this loop only after all implementation tasks are complete and tasks.md 全 [x].
• Do not run this loop per artifact or per task; the granularity is per-change.

Round limit and pass condition

• Run max 6 rounds.
• A round passes only when quality_score > 9 and critical_gap == false.
• If round 6 still does not meet the pass condition, write decision: aborted, print the unresolved findings, and end the plus workflow.
• If a round passes, write decision: passed, stop the loop, and continue to the normal final validation or completion summary.

Fresh sub-agent calls

• Each round MUST spawn TWO fresh reviewer sub-agents in parallel (single message, two tool calls):
  • Reviewer A — Adherence: checks that the artifacts (and for apply-plus, the implementation diff) match the prior artifacts. For propose-plus: proposal ↔ design ↔ spec ↔ tasks internal consistency, scope coverage, and acceptance criteria completeness. For apply-plus: implementation matches design.md Implementation Contract, tasks.md task descriptions, and spec.md requirements; implementation-notes.md deviations are justified.
  • Reviewer B — Quality: scans for bugs, regressions, missing tests, security sharp edges, and risks NOT directly named in the artifacts. For propose-plus: missing risks, unstated assumptions, scope gaps. For apply-plus: logic bugs, error-handling gaps at real boundaries, untested edge cases from spec ##### Example: blocks.
• Both reviewers receive identical context (artifact paths and, for apply-plus, the changed-file list) and return findings independently. Do not pass Reviewer A output into Reviewer B or vice versa.
• After both reviewers complete, the main agent aggregates findings (deduplicate identical issues by location + summary) and applies the confidence filter (see below) before passing the filtered set to the rater.
• Each round MUST spawn a separate fresh sub-agent for the rater role.
• The reviewer roles and the rater are independent sub-agent calls; do not perform any of them inline in the main agent context.
• Do not reuse a sub-agent across rounds, and do not pass prior sub-agent state into the next round.
• The rater receives the filtered, aggregated reviewer findings as input, then independently returns quality_score, critical_gap, and rationale.

Reviewer output requirements

• Both reviewers MUST classify each finding into Critical, Warning, or Suggestion.
• Every finding MUST include the following fields:
  • severity: one of Critical, Warning, Suggestion (before filtering)
  • confidence: integer 0–100, using the rubric below
  • location: artifact + section, or file path + line range
  • summary: one-line description of the issue
  • recommendation: concrete action to resolve
• Every finding names the artifact, section, source path, or changed file it applies to.
• Scope errors at proposal level (e.g., the proposal targets the wrong capability) may set decision: aborted instead of continuing fixes.

Confidence scoring rubric (per finding)

• 0 — Not confident at all. False positive or pre-existing issue. SHOULD NOT be reported.
• 25 — Somewhat confident. Could be a real issue but the reviewer was unable to verify against artifacts or code.
• 50 — Moderately confident. Verified to be real, but minor / unlikely to hit in practice / outside the changed scope.
• 75 — Highly confident. Verified to be real and will hit in practice. Use this when judgment-based impact assessment supports the finding but no direct artifact citation exists.
• 100 — Certain. Evidence directly confirms the issue, OR the finding cites a specific artifact clause (a SHALL in spec.md, an Implementation Contract item in design.md, a task description line in tasks.md, a non-goal in proposal.md) that the artifact set or implementation provably does not satisfy.
• Direct artifact-requirement violations MUST score 100. If a reviewer can name the exact SHALL / contract item / task line being violated, the finding is objectively verifiable and SHALL NOT be downgraded below 100. This invariant guarantees the confidence filter never demotes an artifact violation to Suggestion.

Confidence filter (applied by main agent before rater)

• Drop any finding with confidence < 50. These do not appear in the round file.
• Downgrade findings with confidence ∈ [50, 80) to Suggestion regardless of original severity. They appear in the round file under Suggestion for visibility but do NOT count as Critical.
• Only findings with confidence ≥ 80 may be classified as Critical or Warning in the final round file.
• critical_gap is true only when at least one finding survives filtering with severity == Critical AND confidence ≥ 80.
• The filter exists to keep the review loop signal-to-noise high; the rater sees only the filtered set.

Common false positives — do NOT flag The following SHOULD NOT be reported, or if reported MUST be scored ≤ 25:

• Pre-existing issues on lines not modified by this change (apply-plus) or content not introduced by this proposal (propose-plus).
• Issues a linter, typechecker, formatter, or compiler would catch (missing imports, type errors, formatting, broken syntax). CI will fail separately; the review loop is not the right channel.
• Pedantic style nitpicks that a senior engineer would not call out in review.
• "Missing test coverage" complaints unless tasks.md or design.md explicitly required the test, or a spec ##### Example: block is not exercised.
• Issues already documented as intentional in design.md, implementation-notes.md, the proposal's Non-Goals section, or ## Alternatives Considered.
• Intentional behavior changes that align with the proposal's ## What Changes or ## Proposed Solution.
• Suggestions to add abstractions, configurability, or defensive error handling that the spec/contract did not require — these conflict with Simplicity First.
• Suggestions to refactor unrelated code touched only incidentally — these conflict with Surgical Changes.

Failure handling

• If a reviewer or the rater returns no response or malformed output, retry once with a fresh sub-agent invocation for the same role.
• If both parallel reviewers fail in the same round, treat it as a single role failure (the reviewer role); retry once.
• If the same role fails two consecutive times in a single round, abort the entire plus workflow.
• On abort from sub-agent failure, write the current round file with decision: aborted and include the failure note in ## Decision.
• Do not mark a malformed or failed round as passed, and do not continue to the next round after two consecutive failures.

Rater output requirements

• The rater writes quality_score as a number from 0 to 10.
• The rater writes critical_gap as true or false.
• The rater writes one concise rationale paragraph.
• The rater must not override missing reviewer evidence by optimism alone.
• The rater SHALL only consider findings that survived the confidence filter; do not re-introduce filtered-out findings.

Round file path

• Create the reviews directory if needed: openspec/changes/<change>/reviews/.
• For spectra-propose-plus, write openspec/changes/<change>/reviews/propose-r<N>.md.
• For spectra-apply-plus, write openspec/changes/<change>/reviews/apply-r<N>.md.
• Use <N> as the 1-based round number.
• The generic path pattern is openspec/changes/<change>/reviews/<skill>-r<N>.md.

Round file schema

• # Propose Plus Review — Round <N> or # Apply Plus Review — Round <N>
• ## Reviewer Findings — list aggregated, post-filter findings grouped under Critical / Warning / Suggestion. Each entry MUST include severity, confidence, location, summary, recommendation, and which reviewer raised it (A or B; A+B if both raised it independently).
• ## Rating — quality_score, critical_gap, rationale paragraph.
• ## Fix Actions
• ## Decision — value MUST be exactly one of passed, next_round, or aborted.

Fix actions

• If the decision is next_round, fix the concrete findings before starting the next round.
• Record modified files and the reason for each fix in ## Fix Actions.
• Re-run relevant CLI checks or tests before the next round when fixes affect generated artifacts or implementation code.
• If no fixes are needed because the round passed, write None; pass condition met.

Round file language

• The Round file (openspec/changes/<change>/reviews/<skill>-r<N>.md) prose content — Reviewer Findings, Rater rationale, Fix Actions descriptions, and the ## Decision explanation — MUST be written in Traditional Chinese.
• Keep the following verbatim (do not translate):
  • Section headings: # Propose Plus Review — Round <N>, # Apply Plus Review — Round <N>, ## Reviewer Findings, ## Rating, ## Fix Actions, ## Decision.
  • The decision value: one of passed, next_round, aborted.
  • Field names and their values: quality_score (number 0–10), critical_gap (true / false), severity, confidence, location, summary, recommendation.
  • Direct quotations from spec delta, master spec, or any other English-language artifact.
  • CLI commands, file paths, code identifiers, artifact IDs, capability slugs.
• This rule applies to both spectra-propose-plus and spectra-apply-plus round files because they share this review-loop template.
• If the user explicitly requests another language later, follow the latest user instruction.

10. Validation

    spectra validate "<name>"
    

    If validation fails, fix errors and re-validate.

11. Finish the plus proposal workflow

    Show summary:

    • Change name and location
    • List of artifacts created
    • Validation result
    • Final plus review decision

    Do not move the change out of openspec/changes/.

    The plus proposal workflow ends with the active change still available for implementation.

    If the user wants to temporarily set the change aside, they can do that manually after this workflow ends.

    Inform the user:

    • The change remains active.
    • The plus quality gate has completed or aborted with a recorded round file.
    • Running $spectra-apply <change-name> or $spectra-apply-plus <change-name> later can start implementation.

    If you are currently in Codex Plan Mode, also remind the user to switch the session to normal mode before running an apply workflow. This is only a reminder: do NOT try to use ExitPlanMode or EnterPlanMode, do NOT ask whether to switch modes, and do NOT invoke apply.

    The propose-plus workflow ENDS here.

    Do NOT invoke $spectra-apply.

    Do NOT call AskUserQuestion to ask whether to apply.

    Do NOT run any command that parks the change.

    This behavior is identical across Auto Mode, interactive mode, and any other agent mode.

    The end state is explicit: artifacts exist, validation has run, review records exist, and the change remains active. Artifact Creation Guidelines

• Follow the instruction field from spectra instructions for each artifact type
• Read dependency artifacts for context before creating new ones
• Use template as the structure for your output file - fill in its sections
• IMPORTANT: context and rules are constraints for YOU, not content for the file
  • Do NOT copy <context>, <rules>, <project_context> blocks into the artifact
  • These guide what you write, but should never appear in the output
• Parallel task markers ([P]): When creating the tasks artifact, first read .spectra.yaml. If parallel_tasks: true is set, add [P] markers to tasks that can be executed in parallel. Format: - [ ] [P] Task description. A task qualifies for [P] if it targets different files from other pending tasks AND has no dependency on incomplete tasks in the same group. When parallel_tasks is not enabled, do NOT add [P] markers.

Guardrails

• Create all artifacts needed for implementation. Optional artifacts (those not in the applyRequires dependency chain) may be skipped if their inclusion criteria don't apply.
• Always read dependency artifacts before creating a new one
• If context is critically unclear, ask the user - but prefer making reasonable decisions to keep momentum
• If a change with that name already exists, suggest continuing that change instead
• Verify each artifact file exists after writing before proceeding to next
• NEVER write application code or implement features during this workflow
• NEVER skip the artifact workflow to write code directly
• NEVER reinterpret requirements by ignoring the proposal file
• NEVER invoke $spectra-apply — this workflow ends after artifact creation. The user decides when to start implementation
• If AskUserQuestion tool is not available, ask the same questions as plain text and wait for the user's response