gh-macroman5-claude-code-workflow-plugins/.claude/commands/init-project.md

---
description: Initialize new project with comprehensive documentation (overview, specs, tech stack, architecture)
argument-hint: "[project-description] [--file FILE] [--minimal] [--no-sync] [--no-arch]"
allowed-tools: Read, Write, Bash, Skill, Glob
model: claude-sonnet-4-5-20250929
---

# Init Project: Bootstrap Project Foundation

## Introduction

Transform a project idea into complete foundational documentation including project overview, technical specifications, technology stack selection, and system architecture design.

**Purpose**: Create the documentation foundation before writing any code - ensures alignment, reduces rework, and provides clear technical direction.

**Output Structure:**
```
./project-management/
├── PROJECT-OVERVIEW.md      # Vision, goals, features, success criteria
├── SPECIFICATIONS.md        # Functional/non-functional requirements, API contracts, data models
├── TECH-STACK.md           # Technology selections with rationale and trade-offs
├── ARCHITECTURE.md         # System design with mermaid diagrams
└── .meta/
    └── last-sync.json      # Tracking metadata for document sync
```

**Integration**: Generated documents serve as input for `/lazy plan` when creating user stories.

---

## When to Use

**Use `/lazy init-project` when:**
- Starting a brand new greenfield project
- Need structured project documentation before coding
- Want technology stack guidance and architecture design
- Transitioning from idea to implementation
- Building POC/MVP and need technical foundation

**Skip this command when:**
- Project already has established documentation
- Working on existing codebase
- Only need single user story (use `/lazy plan` directly)
- Quick prototype without formal planning

---

## Usage Examples

```bash
# From project description
/lazy init-project "Build a real-time task management platform with AI prioritization"

# From enhanced prompt file (recommended)
/lazy init-project --file enhanced_prompt.md

# Minimal mode (skip architecture, faster)
/lazy init-project "E-commerce marketplace" --minimal

# Skip architecture generation
/lazy init-project "API service" --no-arch

# Disable auto-sync tracking
/lazy init-project "Chat app" --no-sync
```

---

## Requirements

### Prerequisites
- Working directory is project root
- Git repository initialized (recommended)
- PROJECT-OVERVIEW.md should not already exist (will be overwritten)

### Input Requirements
- **Project description** (required): Either inline text or file path via `--file`
- **Sufficient detail**: Mention key features, tech preferences, scale expectations
- **Clear goals**: What problem does this solve?

### Optional Flags
- `--file FILE`: Read project description from file (STT enhanced prompt recommended)
- `--minimal`: Generate only PROJECT-OVERVIEW.md and SPECIFICATIONS.md (skip tech stack and architecture)
- `--no-arch`: Generate overview, specs, and tech stack but skip architecture diagrams
- `--no-sync`: Skip creating `.meta/last-sync.json` tracking file

---

## Execution

### Step 1: Parse Arguments and Load Project Description

**Parse flags:**
```python
args = parse_arguments("$ARGUMENTS")

# Extract flags
file_path = args.get("--file")
minimal_mode = "--minimal" in args
skip_arch = "--no-arch" in args
disable_sync = "--no-sync" in args

# Get project description
if file_path:
    # Read from file
    project_description = read_file(file_path)
    if not project_description:
        return error(f"File not found or empty: {file_path}")
else:
    # Use inline description
    project_description = remove_flags(args)
    if not project_description.strip():
        return error("No project description provided. Use inline text or --file FILE")
```

**Validation:**
- Project description must be non-empty
- If `--file` used, file must exist and be readable
- Minimum 50 characters for meaningful planning (warn if less)

---

### Step 2: Create Project Management Directory

**Setup directory structure:**
```bash
# Create base directory
mkdir -p ./project-management/.meta

# Check if PROJECT-OVERVIEW.md exists
if [ -f "./project-management/PROJECT-OVERVIEW.md" ]; then
    echo "Warning: PROJECT-OVERVIEW.md already exists and will be overwritten"
fi
```

**Output location**: Always `./project-management/` relative to current working directory.

---

### Step 3: Invoke Project Planner Skill

**Generate overview and specifications:**

```python
# Invoke project-planner skill
result = Skill(
    command="project-planner",
    context={
        "description": project_description,
        "output_dir": "./project-management/"
    }
)

# Skill generates:
# - PROJECT-OVERVIEW.md (vision, goals, features, constraints)
# - SPECIFICATIONS.md (requirements, API contracts, data models)

# Verify both files were created
assert exists("./project-management/PROJECT-OVERVIEW.md"), "PROJECT-OVERVIEW.md not created"
assert exists("./project-management/SPECIFICATIONS.md"), "SPECIFICATIONS.md not created"
```

**What project-planner does:**
1. Extracts project context (name, features, goals, constraints)
2. Generates PROJECT-OVERVIEW.md with vision and high-level features
3. Generates SPECIFICATIONS.md with detailed technical requirements
4. Validates completeness of both documents

**Expected output:**
- `PROJECT-OVERVIEW.md`: 2-3KB, executive summary format
- `SPECIFICATIONS.md`: 8-15KB, comprehensive technical details

---

### Step 4: Invoke Tech Stack Architect Skill (unless --minimal or --no-arch)

**Generate technology stack selection:**

```python
# Skip if minimal mode or no-arch flag
if not minimal_mode:
    # Read PROJECT-OVERVIEW.md for context
    overview_content = read_file("./project-management/PROJECT-OVERVIEW.md")

    # Invoke tech-stack-architect skill
    result = Skill(
        command="tech-stack-architect",
        context={
            "project_overview": overview_content,
            "specifications": read_file("./project-management/SPECIFICATIONS.md"),
            "output_dir": "./project-management/",
            "skip_architecture": skip_arch  # Only generate TECH-STACK.md if true
        }
    )

    # Skill generates:
    # - TECH-STACK.md (frontend, backend, database, DevOps choices with rationale)
    # - ARCHITECTURE.md (system design with mermaid diagrams) [unless skip_arch]

    # Verify tech stack file created
    assert exists("./project-management/TECH-STACK.md"), "TECH-STACK.md not created"

    if not skip_arch:
        assert exists("./project-management/ARCHITECTURE.md"), "ARCHITECTURE.md not created"
```

**What tech-stack-architect does:**
1. Reads PROJECT-OVERVIEW.md for requirements and constraints
2. Analyzes technology needs across 4 categories: Frontend, Backend, Database, DevOps
3. Generates TECH-STACK.md with choices, rationale, alternatives, trade-offs
4. Designs system architecture with component diagrams
5. Generates ARCHITECTURE.md with mermaid diagrams for structure, data flow, deployment

**Expected output:**
- `TECH-STACK.md`: 5-8KB, table-based technology selections
- `ARCHITECTURE.md`: 10-15KB, system design with 3-5 mermaid diagrams

---

### Step 5: Create Tracking Metadata (unless --no-sync)

**Generate sync tracking file:**

```python
if not disable_sync:
    metadata = {
        "initialized_at": datetime.now().isoformat(),
        "documents": {
            "PROJECT-OVERVIEW.md": {
                "created": datetime.now().isoformat(),
                "size_bytes": file_size("./project-management/PROJECT-OVERVIEW.md"),
                "checksum": sha256("./project-management/PROJECT-OVERVIEW.md")
            },
            "SPECIFICATIONS.md": {
                "created": datetime.now().isoformat(),
                "size_bytes": file_size("./project-management/SPECIFICATIONS.md"),
                "checksum": sha256("./project-management/SPECIFICATIONS.md")
            },
            "TECH-STACK.md": {
                "created": datetime.now().isoformat(),
                "size_bytes": file_size("./project-management/TECH-STACK.md"),
                "checksum": sha256("./project-management/TECH-STACK.md")
            } if not minimal_mode else None,
            "ARCHITECTURE.md": {
                "created": datetime.now().isoformat(),
                "size_bytes": file_size("./project-management/ARCHITECTURE.md"),
                "checksum": sha256("./project-management/ARCHITECTURE.md")
            } if not minimal_mode and not skip_arch else None
        },
        "flags": {
            "minimal": minimal_mode,
            "skip_architecture": skip_arch
        }
    }

    # Write metadata
    write_json("./project-management/.meta/last-sync.json", metadata)
```

**Purpose of tracking:**
- Detect manual changes to generated files
- Support future re-sync or update operations
- Track generation history

---

### Step 6: Git Add (if in repository)

**Stage generated files:**

```bash
# Check if in git repo
if git rev-parse --git-dir > /dev/null 2>&1; then
    # Add all generated files
    git add ./project-management/PROJECT-OVERVIEW.md
    git add ./project-management/SPECIFICATIONS.md

    if [ "$minimal_mode" = false ]; then
        git add ./project-management/TECH-STACK.md
        [ "$skip_arch" = false ] && git add ./project-management/ARCHITECTURE.md
    fi

    [ "$disable_sync" = false ] && git add ./project-management/.meta/last-sync.json

    echo "✓ Files staged for commit (git add)"
    echo "Note: Review files before committing"
else
    echo "Not a git repository - skipping git add"
fi
```

**Important**: Files are staged but NOT committed. User should review before committing.

---

### Step 7: Output Summary

**Display comprehensive summary:**

```markdown
## Project Initialization Complete

**Project Name**: {extracted from PROJECT-OVERVIEW.md}

**Documents Generated**:

1. ✅ **PROJECT-OVERVIEW.md** ({size}KB)
   - Vision and goals defined
   - {N} key features identified
   - {N} success criteria established
   - Constraints and scope documented

2. ✅ **SPECIFICATIONS.md** ({size}KB)
   - {N} functional requirements detailed
   - Non-functional requirements defined
   - {N} API endpoints documented (if applicable)
   - {N} data models specified
   - Development phases outlined

{if not minimal_mode:}
3. ✅ **TECH-STACK.md** ({size}KB)
   - Frontend stack selected: {tech}
   - Backend stack selected: {tech}
   - Database choices: {tech}
   - DevOps infrastructure: {tech}
   - Trade-offs and migration path documented

{if not skip_arch:}
4. ✅ **ARCHITECTURE.md** ({size}KB)
   - System architecture designed
   - {N} component diagrams included
   - Data flow documented
   - Security architecture defined
   - Scalability strategy outlined

{if not disable_sync:}
5. ✅ **Tracking metadata** (.meta/last-sync.json)
   - Document checksums recorded
   - Sync tracking enabled

**Location**: `./project-management/`

**Next Steps**:

1. **Review Documentation** (~15-20 minutes)
   - Read PROJECT-OVERVIEW.md for accuracy
   - Verify SPECIFICATIONS.md completeness
   - Check TECH-STACK.md technology choices
   - Review ARCHITECTURE.md diagrams

2. **Customize** (Optional)
   - Refine goals and success criteria
   - Add missing requirements
   - Adjust technology choices if needed
   - Enhance architecture diagrams

3. **Commit Initial Docs**
   ```bash
   git commit -m "docs: initialize project documentation

   - Add PROJECT-OVERVIEW.md with vision and goals
   - Add SPECIFICATIONS.md with technical requirements
   - Add TECH-STACK.md with technology selections
   - Add ARCHITECTURE.md with system design

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

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

4. **Start Planning User Stories**
   ```bash
   # Create first user story from specifications
   /lazy plan "Implement user authentication system"

   # Or plan from specific requirement
   /lazy plan --file ./project-management/SPECIFICATIONS.md --section "Authentication"
   ```

5. **Begin Implementation**
   ```bash
   # After creating user story
   /lazy code @US-1.1.md
   ```

**Estimated Time to Review/Customize**: 15-30 minutes

**Documentation Size**: {total}KB across {N} files

---

## Tips for Success

**Review Phase:**
- Don't skip the review - these docs guide all future development
- Check if technology choices match team skills
- Verify success criteria are measurable
- Ensure API contracts match business requirements

**Customization:**
- Feel free to edit generated docs manually
- Add project-specific constraints or requirements
- Refine architecture based on team preferences
- Update specs as you learn more

**Next Phase:**
- Use generated docs as input to `/lazy plan`
- Reference TECH-STACK.md during implementation
- Keep ARCHITECTURE.md updated as system evolves
- Revisit SUCCESS CRITERIA monthly
```

---

## Validation

### Success Criteria

**Documents Generated:**
- ✅ PROJECT-OVERVIEW.md exists and is non-empty (>1KB)
- ✅ SPECIFICATIONS.md exists and is comprehensive (>5KB)
- ✅ TECH-STACK.md exists (unless --minimal) and has 4 categories
- ✅ ARCHITECTURE.md exists (unless --minimal or --no-arch) and has mermaid diagrams
- ✅ .meta/last-sync.json exists (unless --no-sync) with checksums

**Content Quality:**
- ✅ PROJECT-OVERVIEW.md has vision, goals, features, success criteria, constraints
- ✅ SPECIFICATIONS.md has functional requirements, API contracts, data models
- ✅ TECH-STACK.md has rationale and alternatives for each technology
- ✅ ARCHITECTURE.md has C4 diagram, component details, data flow diagrams

**Git Integration:**
- ✅ Files staged for commit (if in git repo)
- ✅ No automatic commit created (user reviews first)

### Error Conditions

**Handle gracefully:**
- Empty or insufficient project description → Return error with guidance
- File not found (--file flag) → Clear error message with path
- PROJECT-OVERVIEW.md already exists → Warn but continue (overwrite)
- Skill execution failure → Display error and suggest manual creation
- Not in git repo → Skip git operations, warn user

---

## Examples in Action

### Example 1: Full Initialization (Recommended)

```bash
$ /lazy init-project "Build a real-time task management platform with AI-powered prioritization, team collaboration, and GitHub integration. Target 1000 users, 99.9% uptime. Python backend, React frontend."

Initializing project...

Step 1/5: Generating project overview and specifications...
✓ PROJECT-OVERVIEW.md created (2.8KB)
✓ SPECIFICATIONS.md created (11.4KB)

Step 2/5: Designing technology stack...
✓ TECH-STACK.md created (6.2KB)
  - Frontend: React 18 + Zustand + Tailwind
  - Backend: FastAPI + SQLAlchemy
  - Database: PostgreSQL + Redis
  - DevOps: AWS ECS + GitHub Actions

Step 3/5: Architecting system design...
✓ ARCHITECTURE.md created (13.7KB)
  - Component architecture with mermaid diagrams
  - Authentication flow documented
  - Scalability strategy defined

Step 4/5: Creating tracking metadata...
✓ .meta/last-sync.json created

Step 5/5: Staging files for git...
✓ 5 files staged (git add)

## Project Initialization Complete

Project: TaskFlow Pro - Modern task management with AI

Documents Generated:
1. ✅ PROJECT-OVERVIEW.md (2.8KB)
2. ✅ SPECIFICATIONS.md (11.4KB) - 12 API endpoints, 6 data models
3. ✅ TECH-STACK.md (6.2KB) - Full stack defined
4. ✅ ARCHITECTURE.md (13.7KB) - 5 mermaid diagrams

Next Steps:
1. Review docs (15-20 min)
2. Commit: git commit -m "docs: initialize project"
3. Create first story: /lazy plan "User authentication"

Complete! Ready for user story planning.
```

### Example 2: Minimal Mode (Fast)

```bash
$ /lazy init-project "E-commerce marketplace with product catalog and checkout" --minimal

Initializing project (minimal mode)...

Step 1/2: Generating project overview and specifications...
✓ PROJECT-OVERVIEW.md created (1.9KB)
✓ SPECIFICATIONS.md created (8.3KB)

Step 2/2: Staging files...
✓ 2 files staged (git add)

## Project Initialization Complete (Minimal)

Project: E-Commerce Marketplace

Documents Generated:
1. ✅ PROJECT-OVERVIEW.md (1.9KB)
2. ✅ SPECIFICATIONS.md (8.3KB)

Skipped (minimal mode):
- TECH-STACK.md (technology selection)
- ARCHITECTURE.md (system design)

Note: Use full mode if you need tech stack guidance and architecture diagrams.

Next Steps:
1. Review specs
2. Manually define tech stack (or run: /lazy init-project --no-minimal)
3. Create stories: /lazy plan "Product catalog"
```

### Example 3: From Enhanced Prompt File

```bash
$ /lazy init-project --file enhanced_prompt.md

Reading project description from: enhanced_prompt.md

Initializing project...

Step 1/5: Generating project overview and specifications...
✓ PROJECT-OVERVIEW.md created (3.2KB)
✓ SPECIFICATIONS.md created (14.8KB)
  - Extracted 15 functional requirements
  - Defined 8 API contracts
  - Specified 9 data models

Step 2/5: Designing technology stack...
✓ TECH-STACK.md created (7.1KB)

Step 3/5: Architecting system design...
✓ ARCHITECTURE.md created (16.4KB)

...

Complete! High-quality docs generated from enhanced prompt.
```

---

## Integration with Other Commands

### With `/lazy plan`

```bash
# Initialize project foundation
/lazy init-project "Project description"

# Create first user story (references SPECIFICATIONS.md automatically)
/lazy plan "Implement authentication"
# → project-manager uses SPECIFICATIONS.md for context
# → Generates US-1.1.md aligned with project specs
```

### With `/lazy code`

```bash
# During implementation
/lazy code @US-1.1.md
# → context-packer loads TECH-STACK.md and ARCHITECTURE.md
# → Implementation follows defined architecture patterns
# → Technology choices match TECH-STACK.md
```

### With `/lazy review`

```bash
# During story review
/lazy review US-1.1
# → reviewer-story agent checks alignment with SPECIFICATIONS.md
# → Validates implementation matches ARCHITECTURE.md
# → Ensures success criteria from PROJECT-OVERVIEW.md are met
```

---

## Environment Variables

```bash
# Skip architecture generation by default
export LAZYDEV_INIT_SKIP_ARCH=1

# Minimal mode by default
export LAZYDEV_INIT_MINIMAL=1

# Disable sync tracking
export LAZYDEV_INIT_NO_SYNC=1

# Custom output directory
export LAZYDEV_PROJECT_DIR="./docs/project"
```

---

## Troubleshooting

### Issue: "Insufficient project description"

**Problem**: Description too vague or short.

**Solution**:
```bash
# Provide more detail
/lazy init-project "Build task manager with:
- Real-time collaboration
- AI prioritization
- GitHub/Jira integration
- Target: 10k users, 99.9% uptime
- Stack preference: Python + React"

# Or use enhanced prompt file
/lazy init-project --file enhanced_prompt.md
```

### Issue: "PROJECT-OVERVIEW.md already exists"

**Problem**: Running init-project in directory that's already initialized.

**Solution**:
```bash
# Review existing docs first
ls -la ./project-management/

# If you want to regenerate (will overwrite)
/lazy init-project "New description"

# Or work with existing docs
/lazy plan "First feature"
```

### Issue: "Skill execution failed"

**Problem**: project-planner or tech-stack-architect skill error.

**Solution**:
```bash
# Check skill files exist
ls .claude/skills/project-planner/SKILL.md
ls .claude/skills/tech-stack-architect/SKILL.md

# Try minimal mode (skips tech-stack-architect)
/lazy init-project "Description" --minimal

# Manual fallback: create docs manually using templates
# See .claude/skills/project-planner/SKILL.md for templates
```

### Issue: "No technology preferences detected"

**Problem**: TECH-STACK.md has generic choices that don't match needs.

**Solution**:
```bash
# Be specific about tech preferences in description
/lazy init-project "API service using FastAPI, PostgreSQL, deployed on AWS ECS with GitHub Actions CI/CD"

# Or edit TECH-STACK.md manually after generation
# File is meant to be customized
```

---

## Key Principles

1. **Documentation-First**: Create foundation before writing code
2. **Smart Defaults**: Skills generate opinionated but reasonable choices
3. **Customizable**: All generated docs are meant to be refined
4. **Integration**: Docs feed into planning and implementation commands
5. **Version Control**: Track docs alongside code
6. **Living Documents**: Update as project evolves
7. **No Lock-In**: Skip sections with flags, edit freely

---

## Related Commands

- `/lazy plan` - Create user stories from initialized project
- `/lazy code` - Implement features following architecture
- `/lazy review` - Validate against project specifications
- `/lazy docs` - Generate additional documentation

---

## Skills Used

- `project-planner` - Generates PROJECT-OVERVIEW.md and SPECIFICATIONS.md
- `tech-stack-architect` - Generates TECH-STACK.md and ARCHITECTURE.md
- `output-style-selector` (automatic) - Formats output optimally

---

**Version:** 1.0.0
**Status:** Production-Ready
**Philosophy:** Document first, build second. Clear foundation, faster development.