module-spec-generator

name	module-spec-generator
version	1.0.0
description	Generates module specifications following amplihack's brick philosophy template. Use when creating new modules or documenting existing ones to ensure they follow the brick & studs pattern. Analyzes code to extract: purpose, public contract, dependencies, test requirements.

Module Spec Generator Skill

Purpose

This skill automatically generates comprehensive module specifications from code analysis, ensuring adherence to amplihack's brick philosophy and enabling effective module regeneration without breaking system connections.

When to Use This Skill

• Creating new modules: Generate specs before implementation to clarify requirements
• Documenting existing modules: Extract specifications from working code for future reference
• Module reviews: Verify specs accurately represent implemented contracts
• Refactoring decisions: Use specs to understand module boundaries and dependencies
• Knowledge preservation: Document expert patterns and design decisions

Core Philosophy: Bricks & Studs

Brick = Self-contained module with ONE clear responsibility Stud = Public contract (functions, API, data models) others connect to Regeneratable = Can be rebuilt from specification without breaking connections

A good spec enables rebuilding ANY module independently while preserving its connection points.

Specification Template

Every module specification includes these sections:

1. Module Overview

# [Module Name] Specification

## Purpose
One-sentence description of the module's core responsibility.

## Scope
What this module handles | What it explicitly does NOT handle

## Philosophy Alignment
How this module embodies brick principles and simplicity.

2. Public Contract (The "Studs")

## Public Interface

### Functions
- `function_name(param: Type) -> ReturnType`
  Brief description of what it does.

### Classes/Data Models
- `ClassName`
  - Fields: list with types
  - Key methods: list

### Constants/Enums
Important module-level constants and their purposes.

3. Dependencies

## Dependencies

### External Dependencies
- `library_name` (version): What it's used for

### Internal Dependencies
- `module_path`: How this module depends on it

### NO External Dependencies (Best Case)
Pure Python, standard library only.

4. Module Structure

## Module Structure

module_name/ ├── init.py # Public interface via all ├── core.py # Main implementation ├── models.py # Data models (if needed) ├── utils.py # Internal utilities ├── tests/ │ ├── init.py │ ├── test_core.py # Main functionality tests │ ├── test_models.py # Data model tests (if needed) │ └── fixtures/ │ └── sample_data.json └── examples/ └── basic_usage.py # Usage examples

5. Test Requirements

## Test Requirements

### Unit Tests
- Test 1: Purpose and what it verifies
- Test 2: ...

### Integration Tests (if applicable)
- Test 1: ...

### Coverage Goal
Target test coverage percentage (typically 85%+)

6. Example Usage

## Example Usage

```python
from module_name import PublicFunction, DataModel

# Usage example 1
result = PublicFunction(input_data)

# Usage example 2
model = DataModel(field1="value", field2=123)

## Step-by-Step Analysis Process

### Step 1: Understand the Module
1. Read all module files (focus on `__init__.py` and core implementations)
2. Identify the single core responsibility
3. Note architectural patterns used (classes, functions, mixins, etc.)

### Step 2: Extract Public Contract
1. List all exports in `__all__` or equivalent
2. Document function signatures with full type hints
3. Identify data structures (classes, NamedTuple, dataclass)
4. Extract constants and their meanings
5. Include docstrings for each public item

### Step 3: Map Dependencies
1. Scan imports at module level
2. Categorize:
   - Standard library (good - include version constraints)
   - External packages (list version requirements)
   - Internal modules (note the module path)
3. Identify circular dependencies (red flag)

### Step 4: Analyze Module Structure
1. Map file organization
2. Identify what goes in each file
3. Note test fixtures and examples

### Step 5: Identify Test Requirements
1. What behaviors MUST be tested
2. What edge cases exist
3. What integration points need coverage
4. Suggest coverage target

### Step 6: Generate Spec Document
1. Create Specs/[module-name].md
2. Fill in all sections using analysis
3. Include example code
4. Verify spec allows module regeneration

## Usage Examples

### Example 1: Generate Spec for New Module

User: I'm creating a new authentication module. Generate a spec that ensures it follows brick philosophy.

Claude:

1. Interviews user about module purpose, public functions, dependencies
2. Analyzes similar modules in codebase
3. Generates comprehensive spec with:
   • Clear single responsibility
   • Public contract defining studs
   • Test requirements
   • Example implementations
4. Saves to Specs/authentication.md

### Example 2: Document Existing Module

User: Generate a spec for the existing caching module.

Claude:

1. Analyzes .claude/tools/amplihack/caching/ directory
2. Extracts all exports
3. Documents public functions with signatures
4. Maps dependencies
5. Identifies test requirements
6. Creates Specs/caching.md
7. Offers to verify spec matches implementation

### Example 3: Verify Module Spec Accuracy

User: Check if the existing session management spec accurately describes the implementation.

Claude:

1. Reads Specs/session-management.md
2. Analyzes actual code in .claude/tools/amplihack/session/
3. Compares:
   • Public contract (functions, signatures)
   • Dependencies listed
   • Test coverage
4. Reports discrepancies
5. Suggests spec updates if needed

## Analysis Checklist

### Code Analysis
- [ ] Read all Python files in module
- [ ] Identify `__all__` or equivalent public interface
- [ ] Extract all public function signatures
- [ ] Document all public classes with fields and methods
- [ ] List module-level constants
- [ ] Map all imports (external and internal)

### Philosophy Verification
- [ ] Single clear responsibility
- [ ] No unnecessary abstractions
- [ ] Public interface clear and minimal
- [ ] Dependencies are justified
- [ ] No external dependencies (if possible)
- [ ] Patterns align with amplihack principles

### Specification Quality
- [ ] Spec is complete and precise
- [ ] Code examples are accurate and working
- [ ] Test requirements are realistic
- [ ] Module structure is clear
- [ ] Someone could rebuild module from spec
- [ ] Regeneration preserves all connections

## Template for Module Specs

```markdown
# [Module Name] Specification

## Purpose
[Single sentence describing core responsibility]

## Scope
**Handles**: [What this module does]
**Does NOT handle**: [What is explicitly out of scope]

## Philosophy Alignment
- ✅ Ruthless Simplicity: [How it embodies this]
- ✅ Single Responsibility: [Core job]
- ✅ No External Dependencies: [True/False with reason]
- ✅ Regeneratable: [Yes, module can be rebuilt from this spec]

## Public Interface (The "Studs")

### Functions
```python
def primary_function(param: Type) -> ReturnType:
    """Brief description.

    Args:
        param: Description with constraints

    Returns:
        Description of return value
    """

Classes

class DataModel:
    """Brief description of responsibility.

    Attributes:
        field1 (Type): Description
        field2 (Type): Description
    """

Constants

• CONSTANT_NAME: Description and usage

Dependencies

External

None - pure Python standard library

Internal

• .models: Data structures
• .utils: Shared utilities

Module Structure

module_name/
├── __init__.py       # Exports via __all__
├── core.py          # Implementation
├── models.py        # Data models
├── utils.py         # Utilities
├── tests/
│   └── test_core.py
└── examples/
    └── usage.py

Test Requirements

Core Functionality Tests

• ✅ Test primary_function with valid input
• ✅ Test error handling with invalid input
• ✅ Test edge cases

Contract Verification

• ✅ All exported items in all work
• ✅ Type hints match actual behavior
• ✅ Return values match documentation

Coverage Target

85%+ line coverage

Example Usage

from module_name import primary_function, DataModel

# Basic usage
result = primary_function(input_data)

# Data model usage
model = DataModel(field1="value", field2=123)
print(model.field1)

Regeneration Notes

This module can be rebuilt from this specification while maintaining:

• ✅ Public contract (all "studs" preserved)
• ✅ Dependencies (same external/internal deps)
• ✅ Test interface (same test requirements)
• ✅ Module structure (same file organization)

## Output Location

Specifications are saved to: `Specs/[module-name].md`

This keeps all module specifications in a central, discoverable location.

## Integration with Builder Agent

After spec generation, the Builder Agent can:
1. Read the specification
2. Implement the module exactly as specified
3. Verify implementation matches spec
4. Run tests defined in spec
5. Regenerate modules when requirements change

## Quality Checks

After generating a spec, verify:

1. **Can someone rebuild the module from this spec?**
   - Yes = spec is complete
   - No = add missing details

2. **Does every exported function have a clear purpose?**
   - Yes = public interface is clear
   - No = combine or clarify functions

3. **Are all dependencies justified?**
   - Yes = move forward
   - No = remove or replace with simpler approach

4. **Would this prevent breaking other modules?**
   - Yes = studs are well-defined
   - No = clarify connection points

## Common Pitfalls to Avoid

- **Over-specification**: Don't specify implementation details
- **Under-documentation**: Document WHY, not just WHAT
- **Ambiguous contracts**: Be precise about inputs/outputs
- **Unclear dependencies**: Explicitly list all external/internal deps
- **Missing examples**: Always include working code examples
- **Ignored test requirements**: Tests define contract completeness

## Success Criteria

A good module spec:
- [ ] Single, clear responsibility
- [ ] Complete public interface documentation
- [ ] Explicit dependency list
- [ ] Realistic test requirements
- [ ] Working code examples
- [ ] Someone can rebuild module from it
- [ ] Regeneration preserves all connections
- [ ] Follows brick philosophy
- [ ] No future-proofing or speculation
- [ ] Regeneratable without breaking system