AgenticCode/.claude/commands/opsx/export-spec.md

name, description, category, tags

name	description	category	tags
OPSX: Export Spec	Export a feature as a compact, portable spec for AI-assisted reimplementation on a sandboxed machine	Workflow	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:

   # 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