create-saltic/CLAUDE.md

Spec-Driven Development (SDD) framework for constitutional software development - inject into any project

# CLAUDE.md

This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.

## Installation

This framework is typically injected into projects using the CLI:

```bash
# Inject framework into current project
npx create-saltic@latest

# Check framework status
npx create-saltic@latest status

# Remove framework from project
npx create-saltic@latest remove
```

## Project Overview

This is a **Spec-Driven Development (SDD) framework** that implements a structured approach to software development through specifications, plans, and tasks. The framework provides tools and templates for following a constitutional development methodology.

## Architecture

The framework consists of:

1. **Memory System** (`memory/`): Contains constitution and governance documents
2. **Scripts** (`scripts/`): Bash utilities for managing features and workflows  
3. **Templates** (`templates/`): Standardized templates for various development artifacts
4. **Commands** (`.claude/commands/`): Command definitions and workflows

## Architecture

The framework consists of:

1. **Memory System** (`memory/`): Contains constitution and governance documents
2. **Scripts** (`scripts/`): Bash utilities for managing features and workflows  
3. **Templates** (`templates/`): Standardized templates for various development artifacts
4. **Commands** (`.claude/commands/`): Command definitions and workflows

### Development Workflow
The framework follows a strict Spec-Driven Development lifecycle:

1. **Specify**: Define feature requirements and user stories
2. **Plan**: Create implementation plan and design artifacts
3. **Tasks**: Generate numbered, ordered tasks from the plan
4. **Implement**: Execute tasks following constitutional principles
5. **Validate**: Run tests and verify acceptance criteria

## Development Principles

### Constitutional Development
All features must comply with the constitution (`memory/constitution.md`):

- **Library-First**: Every feature starts as a standalone library
- **CLI Interface**: All libraries expose functionality via CLI
- **Test-First**: TDD is mandatory - tests must fail before implementation
- **Integration Testing**: Required for new libraries, contract changes, and shared schemas
- **Observability**: Structured logging and error context required
- **Versioning**: MAJOR.MINOR.BUILD format with breaking change handling
- **Context7 Documentation Integration**: Always use context7 tools for external library documentation

### Branch Naming Convention
Feature branches must follow the pattern: `<git:branchname>-<git:name>-<featurename>` (e.g., `WEC0101-BUDI-authentication`)

## File Structure

```
specs/[<git:branchname>-<git:name>-<featurename>]/
├── spec.md              # Feature specification (Phase 1)
├── plan.md              # Implementation plan (Phase 2)
├── research.md          # Research findings (Phase 0)
├── data-model.md        # Data model design (Phase 1)
├── quickstart.md        # Quickstart guide (Phase 1)
├── contracts/           # API contracts (Phase 1)
└── tasks.md             # Implementation tasks (Phase 2)
```

## Template System

The framework uses templates for consistency:
- `agent-file-template.md`: AI assistant configuration
- `plan-template.md`: Implementation plan structure
- `tasks-template.md`: Task generation template
- `spec-template.md`: Feature specification template
- `templates/codes/angular/`: Angular 20+ templates (entity, dto, presenter, repository, usecase, adapter, config) - All updated with context7 integration and modern dependency injection standards

## Common Operations

When working with features:

1. Always check current branch matches feature naming convention
2. Follow the constitutional gates in the plan template
3. **Always use context7 for planning**: Use `mcp__context7__resolve-library-id` and `mcp__context7__get-library-docs` to retrieve current documentation for external libraries
4. Document all context7-compatible library IDs in planning artifacts
5. Maintain progress tracking throughout development

## Context7 Integration

All development activities must integrate context7 tools for external library documentation:

### Mandatory Context7 Usage
- **Library Resolution**: Always use `mcp__context7__resolve-library-id` before implementing external library features
- **Documentation Retrieval**: Use `mcp__context7__get-library-docs` with specific topics and token limits
- **Reference Tracking**: Document all context7-compatible library IDs in component/service documentation
- **Planning Integration**: Context7 usage is mandatory during the planning phase (see `.claude/commands/plan.md`)

## Context7 Integration

All development activities must integrate context7 tools for external library documentation:

### Mandatory Context7 Usage
- **Library Resolution**: Always use `mcp__context7__resolve-library-id` before implementing external library features
- **Documentation Retrieval**: Use `mcp__context7__get-library-docs` with specific topics and token limits
- **Reference Tracking**: Document all context7-compatible library IDs in component/service documentation
- **Planning Integration**: Context7 usage is mandatory during the planning phase

## Error Handling

The scripts include comprehensive error checking:
- Feature branch validation
- File existence verification
- Prerequisite checking
- Constitution compliance verification
- Context7 integration verification