# CLAUDE.md - augint-library

## Project Overview
**Python Package Template** for creating reusable libraries published to PyPI.

## 📚 Additional Context
For detailed technical guides and patterns, see [LINKS.md](./LINKS.md) which provides AI-optimized documentation navigation. Load only the specific guides you need for your current task.

## AI Commands (Library-Specific)
Available commands: see `.claude/commands/` for library-specific AI commands.

## Quick Commands
See `make help` for all available development commands.

## Development Workflow

### Enterprise Git Workflow (Required for all development)

**NEVER work directly on dev or main branches.** Always follow the issue-driven workflow.

#### Required Enterprise Workflow:
1. **Pick Issue**: `/ai-pick-issue` - Find or select issues to work on
2. **Start Work**: `/ai-start-work 1` - Create proper branch and setup
3. **TDD Development**: Write tests first (90%+ coverage required)
4. **Ship Work**: `/ai-ship` - Run quality checks, commit, and create PR

#### Branch Naming Convention:
```
feat/issue-123-description    # New features
fix/issue-456-description     # Bug fixes
docs/issue-789-description    # Documentation
refactor/issue-012-description # Code refactoring
test/issue-345-description    # Test additions
chore/issue-678-description   # Maintenance tasks
```

#### Conventional Commit Standards:
Every commit must follow conventional commit format:
```bash
feat(core): add new validation protocol

Implements validation protocol for data integrity.
- Protocol-based design for extensibility
- 95% test coverage
- Performance benchmarks included

Closes #123

🤖 Generated with [Claude Code](https://claude.ai/code)

Co-Authored-By: Claude <noreply@anthropic.com>
```

### Pre-commit Requirements
**Pre-commit hooks are MANDATORY** for library quality:
```bash
make pre-commit    # Runs all quality checks
# Includes:
# - Ruff formatting and linting
# - Type checking with mypy
# - Security scanning with bandit
# - Test execution with coverage check
```

## Library-Specific Standards

### Coverage Requirements
- **Minimum**: 90% coverage enforced
- **Target**: 95%+ for core functionality
- **Exclusions**: Only for defensive code paths

### Decision Framework
**USE SPEC-DRIVEN DEVELOPMENT FOR:**
- Complex features with multiple paths
- Public APIs consumed externally
- Protocol/contract design
- Ambiguous requirements

**SKIP FOR:**
- Simple utilities with obvious implementations
- Bug fixes with clear solutions
- Documentation updates

## Branch Protection (Fixed)

### Required Status Checks
- ✅ `Enforce commit standards`
- ✅ `Security scanning`  
- ✅ `Run pytest CI/CD tests`

### Auto-Merge Checklist
- [ ] Allow auto-merge enabled in settings
- [ ] Merge strategy configured in .env (MERGE_STRATEGY)
- [ ] Branch protection with required checks
- [ ] Status check names match pipeline jobs

### Merge Strategy Configuration
The project's merge strategy is configured via `MERGE_STRATEGY` in `.env`:
- **Current setting**: Check `.env` file
- **Options**: `squash` (default), `rebase`, or `merge`
- **To change**:
  1. Update `MERGE_STRATEGY` in `.env`
  2. Run: `gh repo edit --disable-[old]-merge --enable-[new]-merge`
- **Scripts**: The `/ai-ship` command reads this setting automatically

## Security Overrides

### Bandit
```python
password = get_password()  # nosec B105: from secure env
```

### Safety/pip-audit  
```toml
# Pin with documented reasoning
some-package==1.2.3  # CVE-2023-1234 false positive
```

### License Exceptions
```toml
[tool.license-compliance]
exceptions = [
    {
        package = "mysqlclient",
        license = "GPL-2.0+",
        justification = "Internal dev tools only",
        approved_by = "legal-team",
        expires = "2025-12-31"
    }
]
```

## Library Publishing

### Version Management
- Semantic versioning enforced
- Changelog auto-generated from commits
- PyPI release on main branch tags

### Pre-release Checklist
- [ ] All tests passing
- [ ] Coverage > 90%
- [ ] Security scans clean
- [ ] Documentation updated
- [ ] CHANGELOG.md current
