module-spec-generator

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.

• 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

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.

Every module specification includes these sections:

1. Module Overview

```

# [Module Name] Specification

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

What this module handles | What it explicitly does NOT handle

How this module embodies brick principles and simplicity.

```

2. Public Contract (The "Studs")

```

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

```

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_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

```

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

````

```python

from module_name import PublicFunction, DataModel

# Usage example 1

result = PublicFunction(input_data)

# Usage example 2

model = DataModel(field1="value", field2=123)

````

```

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)

1. 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

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

1. 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

1. Reports discrepancies
2. Suggests spec updates if needed

````

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

```markdown

# [Module Name] Specification

[Single sentence describing core responsibility]

Handles: [What this module does]

Does NOT handle: [What is explicitly out of scope]

• ✅ 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]

Functions

```python

def primary_function(param: Type) -> ReturnType:

"""Brief description.

Args:

param: Description with constraints

Returns:

Description of return value

"""

````

Classes

```python

class DataModel:

"""Brief description of responsibility.

Attributes:

field1 (Type): Description

field2 (Type): Description

"""

```

Constants

• CONSTANT_NAME: Description and usage

External

None - pure Python standard library

Internal

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

```

module_name/

├── __init__.py # Exports via __all__

├── core.py # Implementation

├── models.py # Data models

├── utils.py # Utilities

├── tests/

│ └── test_core.py

└── examples/

└── usage.py

```

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

```python

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)

```

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)

```

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

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

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

After generating a spec, verify:

1. Can someone rebuild the module from this spec?

- Yes = spec is complete

- No = add missing details

1. Does every exported function have a clear purpose?

- Yes = public interface is clear

- No = combine or clarify functions

1. Are all dependencies justified?

- Yes = move forward

- No = remove or replace with simpler approach

1. Would this prevent breaking other modules?

- Yes = studs are well-defined

- No = clarify connection points

• 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

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

```