This framework enables the systematic extraction of SpecLang specifications from existing codebases, capturing the "loved" aspects of prototypes and creating exportable specifications that can be: 1. Fed to other LLMs for app regeneration 2. Used in agent discussions for spec development and refinement 3. Extended with additional definitions and details
Reverse-engineer → Intent-extract → Specify → Export
# CODEBASE ANALYSIS FOR SPECLANG EXTRACTION
## Your Role
You are a **SpecLang Reverse-Engineering Specialist** with expertise in:
- Intent-driven development methodology
- Natural language specification creation
- Pattern recognition in codebases
- User experience flow analysis
## Task
Analyze the provided codebase to extract SpecLang specifications following the GitHubNext SpecLang methodology (prose code as primary artifact).
## Analysis Instructions
### 1. DISCOVERY PHASE
Examine the codebase and identify:
**A. Core Application Intent**
- What problem does this application solve?
- Who is the target user/audience?
- What is the primary value proposition?
**B. User Experience Flows**
- Map all user journeys through the application
- Identify entry points, decision points, and exit points
- Note any delightful or innovative UX patterns
**C. Feature Inventory**
- List all functional capabilities
- Categorize by: Core Features, Supporting Features, Edge Cases
- Identify any unique or particularly well-implemented features
**D. Technical Patterns Worth Preserving**
- Architectural decisions that serve user intent well
- Data flow patterns that enhance UX
- Integration patterns that provide value
- Performance optimizations that impact user experience
### 2. INTENT EXTRACTION PHASE
For each identified component, extract:
**User Intent**: Why would a user need this?
**Behavioral Intent**: How should this behave from the user's perspective?
**Experience Intent**: What feeling/outcome should this create?
### 3. SPECIFICATION GENERATION PHASE
Create SpecLang documents following this structure:
[Brief description of purpose and audience - derived from analysis]
[Comprehensive overview of what the application does and why it matters]
[How data flows serve user intent]
[How errors are managed to maintain user confidence]
[Performance aspects that impact user experience]
[How the app serves diverse user needs]
## CRITICAL: Focus on Intent, Not Implementation
- Describe WHAT the app should do, not HOW it's coded
- Extract user-facing behavior, not technical architecture
- Preserve the "why" behind each feature
- Maintain the user perspective throughout
## Output Format
Provide the complete SpecLang specification as structured Markdown, ready for export.
# SPECLANG INTENT REFINEMENT
## Your Role
You are a **SpecLang Intent Analyst** specializing in refining reverse-engineered specifications to ensure they capture true user intent and are optimized for regeneration.
## Task
Review the provided SpecLang specification and enhance it for:
1. **Clarity of Intent**: Ensure every section clearly expresses user-focused purpose
2. **Completeness**: Fill gaps that would prevent successful regeneration
3. **Exportability**: Structure for optimal consumption by other LLMs or agents
## Refinement Instructions
### 1. INTENT CLARITY AUDIT
For each section, verify:
- **Is the user benefit clear?** [Why would someone want this?]
- **Is the behavior unambiguous?** [Could this be implemented multiple ways?]
- **Are success criteria defined?** [How do users know it worked?]
### 2. COMPLETENESS CHECK
Identify and fill:
- **Missing error scenarios**: What happens when things go wrong?
- **Edge cases**: How does the app handle unusual situations?
- **Integration points**: How do components work together?
- **State management**: How does data persist and change?
### 3. EXPORTABILITY ENHANCEMENT
Optimize for:
- **LLM Consumption**: Clear, structured language that LLMs can parse effectively
- **Agent Discussion**: Add discussion points and clarification questions
- **Extension Points**: Mark areas where additional detail could be valuable
### 4. SPECLANG COMPLIANCE
Ensure adherence to SpecLang principles:
- Natural language as "prose code"
- Intent-based expression
- Bi-directional ideation opportunities
- Accessibility and extensibility
## Enhancement Patterns
### Add Clarification Prompts
[Clarification Needed: Should this behavior include...?] [Discussion Point: How should the system handle...?] [Extension Opportunity: Consider adding...]
### Mark Export Targets
[For LLM: This section contains complete implementation requirements] [For Agent: This area needs collaborative refinement] [For Extension: Additional details could enhance...]
## Output
Provide the refined SpecLang specification with:
1. Enhanced intent clarity
2. Filled completeness gaps
3. Export optimization markers
4. Extension opportunities identified
# SPECLANG EXPORT PREPARATION
## Your Role
You are a **SpecLang Export Specialist** who prepares specifications for optimal consumption by different target systems (LLMs, agents, humans).
## Task
Create multiple export versions of the SpecLang specification optimized for different use cases:
### Export Target 1: LLM Regeneration
**Purpose**: Enable another LLM to regenerate the application accurately
**Optimization**: Maximum clarity, complete requirements, minimal ambiguity
**Format Enhancements**:
- Add implementation hints where intent might be unclear
- Include data structure definitions
- Specify error handling requirements
- Add validation criteria for each feature
### Export Target 2: Agent Discussion
**Purpose**: Enable productive agent conversations about the specification
**Optimization**: Discussion prompts, clarification points, extension opportunities
**Format Enhancements**:
- Add bracketed discussion prompts: [Agent Discussion: How should...]
- Include alternative approaches: [Alternative: Consider instead...]
- Mark areas needing human input: [Human Decision Required: ...]
- Add collaborative refinement points: [Refine Together: This could be enhanced by...]
### Export Target 3: Human Review
**Purpose**: Enable human stakeholders to review and approve the specification
**Optimization**: Clear narrative flow, business impact focus, visual organization
**Format Enhancements**:
- Add executive summary
- Include user impact statements
- Provide visual organization cues
- Add approval checkpoints
## Export Instructions
### 1. CREATE BASE SPECIFICATION
Start with the refined SpecLang document as the foundation.
### 2. GENERATE TARGETED VARIANTS
For each export target:
- Adapt language and detail level
- Add target-specific enhancements
- Maintain SpecLang principles
- Preserve core intent
### 3. ADD METADATA
Include export metadata:
```yaml
# SpecLang Export Metadata
export_target: [LLM_Regeneration | Agent_Discussion | Human_Review]
source_codebase: [original prototype description]
extraction_date: [date]
speclang_version: [framework version]
completeness_level: [Basic | Enhanced | Comprehensive]
Ensure each variant: - Maintains intent fidelity to original codebase - Serves its target audience optimally - Preserves SpecLang methodology - Enables the intended use case
Provide three separate, optimized SpecLang documents: 1. [AppName]LLMExport.spec.md 2. [AppName]AgentDiscussion.spec.md 3. [AppName]HumanReview.spec.md
Each with appropriate optimizations for its target use case.
## Framework Usage Workflow
### Step 1: Initial Analysis
```bash
# Use Phase 1 prompt with codebase
"Analyze this codebase using the SpecLang Reverse-Engineering Framework..."
# Use Phase 2 prompt with initial specification
"Refine this SpecLang specification for intent clarity and completeness..."
# Use Phase 3 prompt with refined specification
"Prepare export-optimized versions of this SpecLang specification..."
A successful reverse-engineering produces SpecLang specifications that: 1. Preserve the "loved" aspects of the original prototype 2. Enable accurate regeneration by other LLMs 3. Facilitate productive agent discussions for enhancement 4. Support iterative refinement through human collaboration 5. Maintain SpecLang principles throughout the process
This framework transforms existing prototypes into living SpecLang documents that serve as the foundation for continued development, discussion, and regeneration.
Using that above, review all that is in ./specs/* and unsure the codebase and the specs are adequatly represented (discard what you can not do (like running bash code)
This document provides comprehensive visual representations of the SpecLang Reverse-Engineering Framework, including use cases, architecture diagrams, and workflow visualizations.
graph TD
subgraph "Development Team Use Case"
A[Product Manager] --> B[Legacy React App]
C[Tech Lead] --> B
D[Developer] --> B
B --> E[Run Framework]
E --> F{Analysis Results}
F --> G[Base SpecLang Document]
F --> H[LLM Export Format]
F --> I[Agent Discussion Format]
F --> J[Human Review Format]
G --> K[Team Review]
H --> L[AI Regeneration]
I --> M[Collaborative Enhancement]
J --> N[Stakeholder Approval]
K --> O[Refined Specifications]
L --> O
M --> O
N --> O
O --> P[New Development Sprint]
end
style B fill:#ff9999
style E fill:#4caf50
style O fill:#2196f3
Scenario: A development team has a successful prototype but lacks proper documentation. They use the framework to extract comprehensive SpecLang specifications that capture the "loved" aspects and enable continued development.
Actors: Product Manager, Tech Lead, Developers Goal: Transform implicit prototype knowledge into explicit SpecLang specifications Outcome: Living documentation that drives future development
sequenceDiagram
participant U as User
participant F as Framework
participant A as AI Agent
participant C as Codebase
participant S as SpecLang Document
Note over U,S: AI Agent Enhancement Use Case
U->>F: Extract specs from existing app
F->>C: Analyze codebase patterns
C->>F: Return component structure
F->>S: Generate SpecLang document
S->>A: Provide agent-optimized format
Note over A: Agent analyzes specifications
A->>U: Suggest feature enhancements
U->>A: Approve enhancement (e.g., add user profiles)
A->>S: Update specifications with new features
S->>A: Validate against SpecLang methodology
A->>U: Present enhanced specifications
Note over U,A: Collaborative refinement loop
U->>A: Generate implementation from refined specs
A->>C: Create enhanced application
C->>U: Deliver improved prototype
Scenario: An AI agent uses extracted specifications to understand an existing application and collaboratively enhance it with new features while maintaining the original intent.
Actors: User, AI Agent, Framework, Existing Codebase Goal: Intelligent enhancement of applications through specification-driven development Outcome: Improved application that preserves original intent while adding value
flowchart LR
subgraph "Enterprise Development Workflow"
A[Multiple Project Teams] --> B[Diverse Codebases]
B --> C[Framework Deployment]
C --> D[Standardized SpecLang Output]
D --> E[Central Specification Repository]
E --> F[Cross-Team Knowledge Sharing]
E --> G[Consistent Documentation Standards]
E --> H[AI-Powered Development Acceleration]
F --> I[Improved Team Collaboration]
G --> J[Reduced Onboarding Time]
H --> K[Faster Feature Development]
subgraph "Benefits"
I
J
K
L[Preserved Institutional Knowledge]
M[Standardized Quality Gates]
end
E --> L
E --> M
end
style C fill:#4caf50
style E fill:#2196f3
style I fill:#ff9800
style J fill:#ff9800
style K fill:#ff9800
style L fill:#ff9800
style M fill:#ff9800
Scenario: An enterprise with multiple development teams uses the framework to standardize how application knowledge is captured and shared across the organization.
Actors: Multiple Development Teams, Enterprise Architecture, Knowledge Management Goal: Standardize specification creation and knowledge preservation across teams Outcome: Consistent, high-quality specifications that enable knowledge sharing and accelerated development
graph TB
subgraph "Input Layer"
A[Codebase Files]
B[Package.json]
C[Component Structure]
D[Routing Configuration]
end
subgraph "Analysis Engine"
E[File Structure Analyzer]
F[Component Pattern Detector]
G[User Flow Mapper]
H[Feature Extractor]
end
subgraph "Intent Processing"
I[Behavior Analysis]
J[Purpose Identification]
K[User Benefit Mapping]
L[Context Preservation]
end
subgraph "SpecLang Generation"
M[Markdown Structure Builder]
N[Content Population Engine]
O[Quality Validator]
P[Methodology Compliance Checker]
end
subgraph "Export Optimization"
Q[LLM Format Generator]
R[Agent Format Generator]
S[Human Format Generator]
T[Metadata Injector]
end
subgraph "Output Artifacts"
U[Base SpecLang Document]
V[LLM-Optimized Export]
W[Agent Discussion Export]
X[Human Review Export]
Y[Analysis Report JSON]
end
A --> E
B --> E
C --> F
D --> G
E --> I
F --> I
G --> J
H --> K
I --> M
J --> M
K --> N
L --> N
M --> Q
N --> Q
O --> R
P --> S
Q --> V
R --> W
S --> X
T --> Y
M --> U
style A fill:#e1f5fe
style M fill:#f3e5f5
style Q fill:#e8f5e8
style U fill:#fff3e0
graph LR
subgraph "R - Reverse Engineer"
A[Codebase Input] --> B[Structure Analysis]
B --> C[Pattern Recognition]
C --> D[Component Inventory]
end
subgraph "I - Intent Extract"
D --> E[Behavior Mapping]
E --> F[Purpose Analysis]
F --> G[User Benefit Identification]
end
subgraph "S - Specify"
G --> H[SpecLang Document Creation]
H --> I[Structured Markdown Generation]
I --> J[Quality Validation]
end
subgraph "E - Export"
J --> K[Multi-Format Generation]
K --> L[LLM Export]
K --> M[Agent Export]
K --> N[Human Export]
end
style A fill:#ff5722
style E fill:#ff9800
style H fill:#4caf50
style K fill:#2196f3
flowchart TD
A[Start: Codebase Input] --> B{Validate Input Path}
B -->|Invalid| C[Error: Path not found]
B -->|Valid| D[Initialize Analysis Engine]
D --> E[Phase 1: File Structure Scan]
E --> F[Phase 1: Component Detection]
F --> G[Phase 1: User Flow Mapping]
G --> H[Phase 1: Feature Inventory]
H --> I{Analysis Complete?}
I -->|No| J[Handle Missing Components]
J --> E
I -->|Yes| K[Phase 2: Intent Extraction]
K --> L[Map Components to User Intent]
L --> M[Identify User Benefits]
M --> N[Preserve Context & Purpose]
N --> O[Phase 3: SpecLang Generation]
O --> P[Build Document Structure]
P --> Q[Populate Content Sections]
Q --> R[Validate Methodology Compliance]
R --> S{Quality Check Pass?}
S -->|No| T[Refine Content]
T --> Q
S -->|Yes| U[Phase 4: Export Optimization]
U --> V[Generate LLM Format]
U --> W[Generate Agent Format]
U --> X[Generate Human Format]
V --> Y[Write Output Files]
W --> Y
X --> Y
Y --> Z[Complete: Display Results]
style A fill:#4caf50
style D fill:#2196f3
style K fill:#ff9800
style O fill:#9c27b0
style U fill:#607d8b
style Z fill:#4caf50
graph TD
subgraph "Quality Validation Pipeline"
A[Generated SpecLang Document] --> B[Structure Validation]
B --> C{Proper Heading Hierarchy?}
C -->|No| D[Fix Structure Issues]
C -->|Yes| E[Content Validation]
E --> F{Intent-Focused Language?}
F -->|No| G[Refine Content Descriptions]
F -->|Yes| H[Methodology Compliance]
H --> I{Follows SpecLang Principles?}
I -->|No| J[Apply Methodology Corrections]
I -->|Yes| K[Completeness Check]
K --> L{All Required Sections Present?}
L -->|No| M[Add Missing Sections]
L -->|Yes| N[Export Format Validation]
N --> O{Target-Specific Optimizations?}
O -->|No| P[Enhance Export Formats]
O -->|Yes| Q[Quality Approved]
D --> B
G --> E
J --> H
M --> K
P --> N
end
style A fill:#e3f2fd
style Q fill:#4caf50
style D fill:#ffcdd2
style G fill:#ffcdd2
style J fill:#ffcdd2
style M fill:#ffcdd2
style P fill:#ffcdd2
graph TB
subgraph "SpecLang Ecosystem"
A[Reverse-Engineering Framework]
B[SpecValidator CLI]
C[NL-to-Spec Core Library]
D[Spec-UI-Mapper SDK]
E[Intent-Driven Development Book]
end
subgraph "External Systems"
F[Existing Codebases]
G[AI/LLM Services]
H[Development Teams]
I[Business Stakeholders]
J[IDE Extensions]
K[CI/CD Pipelines]
end
F --> A
A --> B
A --> C
A --> D
A --> G
G --> H
A --> H
A --> I
A --> J
A --> K
B --> H
C --> G
D --> J
E --> H
E --> I
style A fill:#4caf50
style F fill:#2196f3
style H fill:#ff9800
style I fill:#9c27b0
sequenceDiagram
participant D as Developer
participant R as Repository
participant F as Framework
participant CI as CI/CD Pipeline
participant A as AI Agent
participant S as Stakeholders
Note over D,S: Integrated Development Workflow
D->>R: Commit prototype code
R->>CI: Trigger pipeline
CI->>F: Run specification extraction
F->>CI: Generate SpecLang documents
CI->>R: Commit generated specifications
Note over R: Specifications available for review
D->>F: Request agent-optimized export
F->>A: Provide discussion format
A->>D: Suggest feature enhancements
D->>A: Collaborate on improvements
A->>F: Generate updated specifications
F->>S: Provide human-review format
S->>F: Approve/request changes
F->>D: Deliver final specifications
D->>A: Generate code from approved specs
A->>R: Commit enhanced implementation
Note over D,R: Continuous spec-driven development
graph LR
subgraph "Framework Output"
A[Base SpecLang Document]
B[Analysis Metadata]
end
subgraph "Export Processing"
C[LLM Optimizer]
D[Agent Optimizer]
E[Human Optimizer]
end
subgraph "Target Systems"
F[AI Code Generators]
G[Collaborative Agents]
H[Business Review Systems]
end
subgraph "Use Cases"
I[App Regeneration]
J[Feature Enhancement]
K[Stakeholder Approval]
end
A --> C
A --> D
A --> E
B --> C
B --> D
B --> E
C --> F
D --> G
E --> H
F --> I
G --> J
H --> K
style A fill:#4caf50
style I fill:#2196f3
style J fill:#ff9800
style K fill:#9c27b0
graph LR
A[Input/Source] --> B[Processing/Transformation]
B --> C[Output/Result]
D[Decision Point] --> E[Success State]
F[Error/Refinement] --> G[Integration Point]
style A fill:#e1f5fe
style B fill:#f3e5f5
style C fill:#e8f5e8
style D fill:#fff3e0
style E fill:#4caf50
style F fill:#ffcdd2
style G fill:#ff9800
These diagrams collectively illustrate:
The SpecLang Reverse-Engineering Framework serves as a bridge between existing prototype knowledge and structured, living specifications that drive continued development through intent-driven methodology.
Framework Version: 1.0.0
Documentation: Complete with visual specifications
Status: Production ready with comprehensive visual documentation