---
name: "OPSX: Export Spec"
description: Export a feature as a compact, portable spec for AI-assisted reimplementation on a sandboxed machine
category: Workflow
tags: [workflow, portability, experimental]
---

Export a feature as a portable spec for AI-assisted reimplementation.

Instead of retyping code, you retype a compact spec. The AI on the sandbox generates the code.

---

**Input**: The argument after `/opsx:export-spec` is a change name (active or archived), or a description of the feature. If omitted, prompt for selection.

**Steps**

1. **Identify the source feature**

   Same selection logic as `/opsx:extract-feature`:
   - Check active changes and archive for the change name
   - If not found, prompt with **AskUserQuestion tool**
   - Read all artifacts: `proposal.md`, `design.md`, `tasks.md`, specs

2. **Analyze dependency chain (cumulative mode)**

   Features often build on each other. Before generating the spec, determine
   what the target feature depends on.

   a. Read all archived change proposals in `openspec/changes/archive/` (sorted by date).
   b. Build a dependency graph: what does the target require? What's superseded?
   c. Ask the user:
      > "This feature depends on earlier changes. How should I scope the spec?"
      > 1. **Cumulative** — include all foundation (recommended for fresh codebase)
      > 2. **Delta only** — just this change (target already has foundation)
      > 3. **Custom** — pick which dependencies to include

   d. In cumulative mode: merge into one coherent spec, skip superseded components.
   e. In delta mode: add an "Assumes" section listing what must already exist.

3. **Read the actual implementation**

   Read all source files created or modified by this feature (and dependencies if cumulative).
   The spec must reflect what was actually built, not just what was planned.

4. **Determine the target context**

   Use **AskUserQuestion tool** to ask:
   > "Tell me about the target codebase:
   > 1. Project name / root namespace
   > 2. Existing stack (ASP.NET Core? Blazor? MudBlazor?)
   > 3. Does it already have any of these? (controllers, DI setup, chat endpoint)
   > 4. Does the target have OpenSpec? GitHub Copilot? Claude Code?"

   This shapes what the spec assumes vs what it must specify.

5. **Generate the portable spec**

   Create a single markdown document that is:
   - **Compact**: Target ~30-50 lines for a medium feature
   - **Precise**: Unambiguous enough for an AI to implement correctly
   - **Self-contained**: No references to external files or repos
   - **Stack-aware**: Uses the right terminology for the target stack

   Structure:

   ```markdown
   # Feature: <Name>
   ## Target: <project name> (<stack>)

   ## Packages
   <list with versions>

   ## Architecture
   <2-3 sentence overview>

   ## Components
   ### <Component>: <path hint>
   - <What it does>
   - <Key behavior>
   - <Interface/contract>

   ## Contracts
   <API shapes, model definitions — things that MUST be exact>

   ## Wiring
   <DI registration, middleware order, config keys — dependency order>

   ## Behavior
   <Non-obvious requirements>
   ```

   **Compression strategies:**
   - Use bullet points, not prose
   - Specify contracts precisely (field names, types, API shapes)
   - Let the AI infer standard patterns
   - Only specify non-obvious behavior
   - Omit anything the AI would do by default

6. **Estimate typing effort**

   Count characters in the spec. Compare to the code recipe equivalent.
   Show the compression ratio.

7. **Optionally generate an OpenSpec-compatible version**

   If the target has OpenSpec, also generate:
   - A `proposal.md` (minimal — 5-10 lines)
   - A `tasks.md` (implementation steps)

   Save as: `openspec/exports/<change-name>-openspec.md`

8. **Write the output**

   Save to: `openspec/exports/<change-name>-spec.md`
   Display the full content for review.

**Guardrails**
- Prioritize precision over brevity — ambiguity wastes more time than length
- Always include exact field names, types, and API shapes
- Include non-obvious gotchas (like /v1 base URL requirements)
- Mental test: could an AI implement this correctly without seeing the original code?
- If too complex for ~50 lines, split into multiple specs by component
- Always show the compression ratio
- Must be readable when printed in monospace — no wide tables or long lines
- In cumulative mode, the spec must read as one coherent feature, not a list of changes
- Skip superseded components — always describe the latest version
- In delta mode, add an "Assumes" section so the target AI knows what must exist
- In the output header, note which changes were included and which were skipped

ARGUMENTS:  based on the above