How Spektacular Works

Before Spektacular drafts a single section, it interviews you. Rather than working through a fixed script, the agent asks open questions about what you’re building, adapting each one to what you’ve already said, a technique called Flipped Interaction, drawn from prompt-engineering research on shifting conversational control to the agent.

Agent: What are you building, and who runs into the problem it solves?
You:   A CLI users can point at a local repo to check for
       outdated dependencies.
Agent: Should it just report outdated packages, or offer to
       upgrade them too?
You:   Report only, for now, upgrading is a separate feature.
Agent: Got it, I have enough to draft an Overview. One more
       thing: does this touch the docs site too, or is it
       CLI-only for now?

The interview stops once no further question would change the draft, not once every possible detail has been asked about.

In a project with more than one registered repo, the interview already knows the full roster, so a feature that reads as focused on one repo still gets asked about impact on the others, shaped by what each one actually is:

Agent: This project also has a "docs" repo registered
       (role: documentation). Does exposing this as a new
       CLI flag mean the docs site needs a new page or
       section too?
You:   Yes, it should get its own reference page.

From there, each section, Requirements, Constraints, Acceptance Criteria, and the rest, is drafted from what the interview established and presented back for you to confirm or correct, rather than asked from a blank prompt. Rejecting a draft opens a short follow-up conversation to understand why before anything changes, since a single correction can turn out to need more than one change. The spec itself stays plain markdown, no special syntax, just structured sections.

Specs don’t only start this way: during any open-ended discussion, the agent watches for the moment it produces something spec-worthy (a scoped decision, a multi-requirement feature) and proactively offers to capture it, calibrated by the spec_trigger_threshold config key. It always proposes before starting, never begins unilaterally.

Plan turns the spec into a detailed implementation plan. It loads your project knowledge base, explores the codebase, and surfaces clarifying questions before writing anything. The conventions, gotchas, decisions, and architecture it draws from the knowledge base are woven directly into the plan, so the output reflects how your project works rather than a generic approach. The plan, plus supporting research and context documents, are written to .spektacular/plans/.

Once the documents are written, the agent offers to walk through the plan conversationally: the approach and reasoning, how the work breaks into phases, and what was deliberately left out, before you commit to it. You can interrupt with questions or changes at any point; edits land directly in plan.md. Reading the documents yourself remains just as valid; the walkthrough is optional.

Implement drives the coding agent through each phase of the plan and verifies the output against your acceptance criteria, so you know the implementation matches the spec.

Before it starts, Spektacular checks the plan’s phases against the spec’s Requirements and Acceptance Criteria checklist: any gap must be either filled in or explicitly accepted as a descope. After implementation finishes, it checks the spec’s checklist against what was actually built, and writes a changelog record of what shipped, why, and how it differed from the plan to .spektacular/changelog/.