# Specifications Directory

This directory contains specifications for the augint-library project, following Spec-Driven Development (SDD) patterns optimized for AI collaboration.

## When to Write Specifications

### ✅ **USE SDD FOR:**
- **Complex Features**: Multi-step algorithms, business logic
- **Public APIs**: Library interfaces that external users will consume
- **Protocol Design**: When defining contracts between components
- **Ambiguous Requirements**: When implementation approach isn't obvious
- **Team Collaboration**: When multiple developers (including AI) need clarity

### ❌ **SKIP SDD FOR:**
- **Simple Utilities**: Straightforward helper functions
- **Obvious Implementations**: Standard CRUD operations, basic getters/setters
- **Internal Helpers**: Private functions with clear, single responsibilities
- **Quick Fixes**: Bug fixes with obvious solutions

## Directory Structure

```
specs/
├── README.md              # This file - how to write specs
├── interfaces/            # Python Protocol definitions  
│   └── example.py         # Example protocol specifications
└── features/              # Feature specifications
    ├── template.md        # Template for new feature specs
    └── example-feature.md # Complete example workflow
```

## Workflow

### 1. **Feature Planning**
```bash
# Create GitHub issue with specifications
gh issue create --title "feat: add data processor" --label enhancement

# Create feature branch
git checkout -b feat/issue-26-data-processor
```

### 2. **Write Protocol (if needed)**
- Define Python Protocols in `specs/interfaces/`
- Include type hints and documentation
- Focus on interface contracts, not implementation

### 3. **Write Feature Specification**
- Use `specs/features/template.md` as starting point
- Define behavior, not implementation details
- Include test scenarios and acceptance criteria

### 4. **Implement with TDD**
- Write failing tests first (based on specifications)
- Implement minimal code to pass tests
- Refactor with test safety net

### 5. **Validate Against Specifications**
- Ensure implementation matches protocol definitions
- Verify all acceptance criteria are met
- Update specifications if requirements change

## AI Collaboration Guidelines

### For AI Assistants (Claude, etc.)
1. **Always read existing specifications** before implementing
2. **Ask for specifications** if requirements are unclear
3. **Follow protocols exactly** as defined in `specs/interfaces/`
4. **Implement TDD workflow** - failing test first, always
5. **Update specifications** if implementation reveals new requirements

### For Developers
1. **Provide clear requirements** when asking AI to implement features
2. **Review specifications** before approving AI implementations  
3. **Keep specs up-to-date** as the project evolves
4. **Use issue templates** to guide specification creation

## Examples

See `specs/interfaces/example.py` and `specs/features/example-feature.md` for complete examples of the specification → implementation workflow.

## Benefits

- **Faster AI Implementation**: Clear contracts reduce back-and-forth
- **Better Test Coverage**: Specifications drive comprehensive test scenarios
- **Consistent APIs**: Protocol definitions ensure interface consistency
- **Easier Maintenance**: Specifications serve as living documentation
- **Team Alignment**: Shared understanding of requirements and behavior
