[Feature Request] Reverse-engineer specs from existing implementations (code-first workflow)

[alfred-openspec]

Problem

Teams adopting OpenSpec often have members who prefer implementing features manually with minimal AI assistance. After implementation, they need a way to generate specs and documentation retroactively from the existing code.

Currently, OpenSpec is optimized for a spec-first workflow. There is no native support for generating specs from already-implemented code.

User Story

"I have a specific use case: for team members who prefer to implement features manually with minimal AI assistance, is it possible to generate the specifications and documentation after the code is written? Specifically, can /opsx:verify be used to 'reverse-engineer' these artifacts then archive it?"

"In your experience, do you recommend generating specs for manual implementations, or is the tool optimized for a 'spec-first' workflow?"

— Ousama Esbel (Discord, rolling out to a 15-person team)

Context

• Team of 15 members with mixed workflows (some AI-assisted, some manual coding)
• Need to reduce rework and AI variability across different tools, rules, and prompts
• Want all work captured in specs regardless of how it was implemented

Current Workaround

Prompt your coding agent to create specs from the current codebase. However, this is manual and not part of any built-in workflow.

Design Consideration

Specs store contracts of intent and user experience. Even reverse-engineered specs should be reviewed by humans before becoming the context that agents treat as ground truth.

Related

• opsx-discovery: baseline specs for legacy code #690 (opsx-discovery: baseline specs for legacy code)
• How can I use OpenSpec in a large existing project，what is the first step I should do? #510 (Using OpenSpec in large existing projects)

[1code-async]

Task completed.

The enrichment comment has been posted on issue #724. Here's a summary of what was included:

Related issues identified: #690 (opsx-discovery with a concrete prototype from @kleysonr), #510 (bootstrapping OpenSpec in large existing projects), and #434 (advanced spec generation). The #690 prototype is the most actionable prior art.

Architecture context: The comment maps exactly where a code-first workflow would fit in the codebase — the template-driven skill system at src/core/templates/workflows/, registration in skill-generation.ts, and the structured spec format enforced by markdown-parser.ts.

Three implementation options were outlined:

• Option A (Recommended): A new opsx:discover skill as an 11th workflow module
• Option B: Extending /opsx:verify (not recommended — blurs single responsibility)
• Option C: Integrating opsx-discovery: baseline specs for legacy code #690's discovery schema (most comprehensive but depends on [Proposal/Enhancement] Hardcoded spec format prevents custom schemas from working #666)

Key blockers flagged: Issue #666 (hardcoded spec format) and context window limits for large codebases.

Comment URL: #724 (comment)

---

View full conversation

Powered by 1Code

[1code-async]

Codebase Analysis & Implementation Context

Related Issues & Potential Duplicates

This request intersects with several existing issues:

Issue	Title	Relevance
#690	opsx-discovery: baseline specs for legacy code	Direct overlap — @kleysonr built a concrete prototype with a custom discovery schema producing system-spec and domain-map artifacts. Includes working SKILL.md, schema.yaml, and templates.
#510	Using OpenSpec in large existing projects	Same core question from a different angle — how to bootstrap OpenSpec in brownfield codebases.
#434	Advanced Spec & Plan Generation	Potentially related to automated spec generation.

The community-contributed opsx-discovery prototype in #690 is the most concrete implementation proposal and could serve as a foundation here.

Current Architecture: Where This Would Fit

Skill/Workflow System — OpenSpec uses a template-driven skill architecture in src/core/templates/workflows/. Each workflow is a TypeScript function returning a SkillTemplate (defined in src/core/templates/types.ts:5-12) and a CommandTemplate. These are registered centrally in src/core/shared/skill-generation.ts:51-64. Currently there are 10 workflows:

explore → new → continue → apply → ff → sync → archive → bulk-archive → verify → onboard

A new opsx:discover (or opsx:reverse) skill would slot naturally into this system as an 11th workflow module.

Spec Format — Specs follow a strict structured format enforced by src/core/parsers/markdown-parser.ts and documented in openspec/specs/openspec-conventions/spec.md. Key constraints:

• ### Requirement: [Name] headers (used as unique identifiers for programmatic matching)
• #### Scenario: [Description] with WHEN/THEN/AND keywords
• Behavioral focus — specs capture external contracts, not implementation details
• Parser requires both ## Purpose and ## Requirements sections (markdown-parser.ts:26-36)

Any reverse-engineering workflow must produce output conforming to this format, or the generated specs won't integrate with validate, verify, archive, and sync.

Known Blocker — Issue #666 (hardcoded spec format) was flagged in #690 as a blocker. The markdown parser currently expects the exact ### Requirement: / #### Scenario: structure. Custom schemas that produce different output formats won't pass validation. This would need to be addressed if the discovery workflow uses a non-standard intermediate format.

Suggested Implementation Approach

Option A: New opsx:discover Skill (Recommended)

Create a new workflow module at src/core/templates/workflows/discover.ts following the existing pattern. The workflow would:

1. Analyze — Scan a specified directory/module using code structure analysis (similar to how onboard.ts already does codebase scanning in Phase 2 — see src/core/templates/workflows/onboard.ts:69-86 for the pattern)
2. Extract — Identify capabilities, public APIs, error handling patterns, and behavioral contracts from the code
3. Generate — Produce draft spec files in the standard ### Requirement: / #### Scenario: format
4. Review gate — Present generated specs for human review before committing (aligns with the design consideration in the issue)
5. Place — Write reviewed specs to openspec/specs/[capability]/spec.md

Registration would require adding the template functions to src/core/templates/skill-templates.ts and entries in src/core/shared/skill-generation.ts:51-64 and skill-generation.ts:69-82.

Option B: Extend /opsx:verify for Reverse Generation

The original user question asks whether /opsx:verify could be repurposed. Currently, verify (src/core/templates/workflows/verify-change.ts) operates in a check-only mode — it reads existing artifacts and validates implementation against them. It does not generate artifacts. Adding generation capability would blur its single responsibility (verification). A separate skill is cleaner.

Option C: Leverage #690's Discovery Schema

Integrate @kleysonr's custom schema from #690 as a first-class workflow. This would provide a system-spec and domain-map as intermediate artifacts, with a second phase to convert those into standard behavioral specs. This is the most comprehensive approach but depends on resolving #666 (custom schema support).

Key Files to Modify

For Option A, the minimal changeset would be:

File	Change
src/core/templates/workflows/discover.ts	New — Discovery skill template and command template
src/core/templates/skill-templates.ts	Add exports for the new templates
src/core/shared/skill-generation.ts	Register in getSkillTemplates() and getCommandTemplates() arrays
test/core/templates/	Tests for the new workflow

Design Considerations

1. Context window limits — Large codebases may exceed AI context windows during analysis. The skill should support scoping to specific directories or modules, and potentially work incrementally (one capability at a time).

2. Human review gate — The issue correctly notes that reverse-engineered specs should not automatically become ground truth. The workflow should include an explicit approval step before writing specs, similar to how onboard.ts pauses for user confirmation at key transitions.

3. Behavioral vs. implementation extraction — Per OpenSpec conventions, specs must capture behavioral contracts, not implementation details. The skill instructions should explicitly guide the AI to extract WHAT the code does (externally observable behavior) rather than HOW it does it (internal structure). Implementation details belong in design.md.

4. Existing onboard.ts pattern — The onboarding workflow already performs lightweight codebase analysis (TODO/FIXME scanning, test gap detection, type issue detection) at onboard.ts:69-86. This pattern can be extended for deeper capability extraction.

[sumitparakh]

This feature would be really helpful

[alfred-openspec]

Another concrete signal from @paranic on Discord: they would spend substantial AI tokens on high-quality reverse engineering if generation can be scoped by an explicit capability prompt, such as authentication, billing, APIs, or employee management, instead of crawling the whole repository and choosing the specs itself.

The desired outcome is a reviewed, summarized baseline that gives /opsx:propose reliable context about existing behavior. Source message