/xnew

description: "Initialize a new project with comprehensive CLAUDE.md and specification framework"
tags: ["project", "setup", "initialization"]

Initialize repo with comprehensive CLAUDE.md + Specification-Driven Development

Initialize a new project with comprehensive CLAUDE.md and specification framework.

Usage

/xnew <project_name> [stack]

Examples

/xnew vibecoding-web node
/xnew ai-patterns python
/xnew microservice-api go

Parameters

• **PROJECT_NAME**: First word in arguments (default: current folder name)
• **STACK**: Technology stack (choices: `python` | `node` | `go` | `java` | `mixed`; default: `mixed`)

Execution

Perform the following steps in order:

Step 1: Safety & Idempotence

• Check for existing files before overwriting
• Create timestamped backups for any existing files (format: `filename.bak-YYYYMMDD-HHMMSS`)
• Never overwrite without backup creation

Step 2: Create Comprehensive CLAUDE.md

Generate CLAUDE.md with Specification-Driven Development methodology:

# Project: $PROJECT_NAME
# Stack: $STACK
# Generated: $(date +%Y-%m-%d)
# Development Methodology: Specification-Driven Development (SDD)

This is the single source of truth for all development standards, conventions, rules, and specifications for this project. Claude Code and other AI assistants should read this file first and follow these guidelines for all operations.

## 📚 Specification-Driven Development

This project follows Specification-Driven Development (SDD) methodology. All features MUST have specifications before implementation.

### Specification Framework
specs/
├── README.md                    # Specification guide and navigation
├── requirements.md             # EARS-formatted requirements
├── design.md                   # Technical architecture and design
├── tasks.md                    # Atomic, sequenced implementation tasks
├── mvp-summary.md             # MVP vs Advanced feature separation
├── testing-requirements.md    # Test coverage requirements
├── performance-benchmarks.md  # Performance targets and metrics
├── user-testing-strategy.md   # User validation approach
├── system-monitoring.md       # Operational monitoring strategy
├── hooks.md                   # Development lifecycle automation
├── agents.md                  # Multi-agent orchestration
├── context.md                 # Data classification and context management
└── github-actions-requirements.md  # CI/CD automation specs

### AWS Kiro EARS Requirements Pattern
All Requirements Now Follow Official EARS Syntax:

- **Event-Driven**: "When [trigger], the system shall [response]"
- **State-Driven**: "While [precondition], the system shall [response]"
- **Ubiquitous**: "The system shall [response]"
- **Optional Feature**: "Where [feature], the system shall [response]"
- **Unwanted Behavior**: "If [trigger], then the system shall [response]"

The validation tool now shows **100% EARS compliance**

### Specification Coverage Requirements
- Every feature must have corresponding specifications
- Every specification must have corresponding tests
- Minimum spec coverage: 95% of all features
- Spec-to-test mapping: Automated validation required
- **EARS compliance: 100% mandatory for all requirements**

### EARS Validation Rules
🚨 **MANDATORY COMPLIANCE**:
- All requirements MUST use exact AWS Kiro EARS syntax with brackets
- No exceptions allowed - 100% compliance required
- Validation tool enforces strict format checking
- Requirements failing EARS format are rejected automatically

**EARS Format Validation Examples**:
✅ CORRECT: "When [user clicks save], the system shall [persist data to database]"
✅ CORRECT: "While [backup is running], the system shall [display progress indicator]" 
✅ CORRECT: "The system shall [authenticate users before access]"
✅ CORRECT: "Where [admin privileges], the system shall [allow user management]"
✅ CORRECT: "If [network timeout occurs], then the system shall [retry 3 times]"

❌ INCORRECT: "User can save data" (not EARS format)
❌ INCORRECT: "System should authenticate" (missing brackets)
❌ INCORRECT: "When user saves, validate" (incomplete structure)

## 🎯 Project Goals & Context
- Primary objective: [Define main goal and success metrics]
- Technical requirements: [Core technical needs and constraints]
- Business objectives: [Business value delivered]
- User value: [What users gain from this system]
- Development methodology: Specification-Driven Development (SDD)

## 📋 Requirements Management

### Requirements Framework (AWS Kiro EARS)
requirement_structure:
  id: "REQ-XXX"
  pattern: "Event-Driven|State-Driven|Ubiquitous|Optional|Unwanted"
  requirement: "MUST follow exact EARS syntax with brackets"
  ears_format_examples:
    - "When [user submits form], the system shall [validate all fields]"
    - "While [user is authenticated], the system shall [display user dashboard]"  
    - "The system shall [encrypt all data at rest]"
    - "Where [premium feature enabled], the system shall [allow advanced analytics]"
    - "If [invalid login attempt], then the system shall [lock account after 3 failures]"
  rationale: "Why this requirement exists"
  acceptance_criteria: "Testable criteria for validation"
  priority: "MVP|ADVANCED"
  ears_compliance: "MANDATORY - 100% compliance required"

### MVP vs Advanced Features
- MVP Features: Core functionality for initial release
- Advanced Features: Enhanced capabilities for future iterations
- Decision Framework:
  - ✅ Include in MVP if: Essential for core workflow
  - ⚠️ Move to Advanced if: Complex edge cases or optimizations

## 📁 Directory Structure
project/
├── src/                        # Source code
├── tests/                     # Test suites
│   └── specs/                # Specification compliance tests
├── specs/                     # SPECIFICATIONS (CRITICAL)
│   ├── README.md            # Specification navigation guide
│   ├── requirements.md      # EARS-formatted requirements
│   ├── design.m