Initial commit

2025-11-30 08:44:27 +08:00
commit d97a70be33
36 changed files with 17033 additions and 0 deletions
--- a/commands/project-init.md
+++ b/commands/project-init.md
@@ -0,0 +1,426 @@
+# /sdd:project-init
+
+## Meta
+- Version: 2.0
+- Category: project-management
+- Complexity: medium
+- Purpose: Initialize story-driven development system with folder structure and template documents
+
+## Definition
+**Purpose**: Create the complete folder structure and template documents required for story-driven development workflow.
+
+**Syntax**: `/sdd:project-init`
+
+## Parameters
+None
+
+## INSTRUCTION: Initialize Project Structure
+
+### INPUTS
+- Project root directory (current working directory)
+- User responses for technology stack and preferences (gathered interactively)
+
+### PROCESS
+
+#### Phase 1: Directory Structure Creation
+1. **CREATE** `/docs/project-context/` directory
+   - Root directory for all project documentation
+   - Contains technical specifications and standards
+
+2. **CREATE** `/docs/stories/` directory with subdirectories:
+   - `/docs/stories/development/` - Active implementation work
+   - `/docs/stories/review/` - Code review stage
+   - `/docs/stories/qa/` - Quality assurance testing
+   - `/docs/stories/completed/` - Finished and shipped stories
+   - `/docs/stories/backlog/` - Planned but not started
+   - `/docs/stories/templates/` - Story and documentation templates
+
+3. **ADD** `.gitkeep` file to each empty directory:
+   - ENSURES directories are tracked in git
+   - PREVENTS empty directories from being ignored
+   - FORMAT: Empty file named `.gitkeep`
+
+#### Phase 2: Technical Stack Documentation
+1. **ASK** user about complete technical stack:
+
+   **Frontend**:
+   - Framework: (React, Vue, Svelte, Angular, Laravel Blade, Next.js, Nuxt.js, etc.)
+   - State management: (Redux, Zustand, Vuex, Pinia, Livewire, Alpine.js, etc.)
+   - Language: (TypeScript, JavaScript, PHP templating, etc.)
+   - Styling: (Tailwind CSS, CSS Modules, Styled Components, SCSS, etc.)
+   - Build tool: (Vite, Webpack, Rollup, esbuild, Parcel, Laravel Mix, etc.)
+
+   **Backend**:
+   - Runtime: (Node.js, Deno, Bun, PHP, Python, Go, Java, .NET, etc.)
+   - Framework: (Express, Fastify, Laravel, Symfony, Django, FastAPI, etc.)
+   - Language: (TypeScript, JavaScript, PHP, Python, Go, Java, C#, etc.)
+
+   **Database**:
+   - Primary database: (PostgreSQL, MySQL, MongoDB, SQLite, Redis, etc.)
+   - ORM/Query builder: (Prisma, TypeORM, Eloquent, Django ORM, etc.)
+   - Caching: (Redis, Memcached, database cache, etc.)
+
+   **Testing**:
+   - Unit testing: (Jest, Vitest, Pest, PHPUnit, Pytest, JUnit, etc.)
+   - Integration testing: (Same as unit or separate framework)
+   - Browser/E2E testing: (Playwright, Cypress, Selenium, Laravel Dusk, etc.)
+   - Test runner commands: (npm test, vendor/bin/pest, pytest, etc.)
+
+   **Development Tools**:
+   - Package manager: (npm, yarn, pnpm, composer, pip, go mod, etc.)
+   - Code formatting: (Prettier, ESLint, PHP CS Fixer, Black, etc.)
+   - Linting: (ESLint, PHPStan, pylint, golangci-lint, etc.)
+   - Git hooks: (husky, pre-commit, etc.)
+
+   **Deployment & Hosting**:
+   - Hosting platform: (Vercel, Netlify, AWS, Railway, Heroku, etc.)
+   - Container platform: (Docker, Podman, none, etc.)
+   - CI/CD: (GitHub Actions, GitLab CI, Jenkins, none, etc.)
+
+   **Key Libraries**:
+   - Authentication: (Auth0, Firebase Auth, Laravel Sanctum, etc.)
+   - HTTP client: (Axios, Fetch, Guzzle, Requests, etc.)
+   - Validation: (Zod, Joi, Laravel Validation, Pydantic, etc.)
+   - Other important libraries: [User provides list]
+
+2. **CREATE** `/docs/project-context/technical-stack.md`:
+   - POPULATE with user's technology choices
+   - INCLUDE version numbers if available
+   - ADD links to documentation
+   - NOTE any specific configuration requirements
+
+#### Phase 3: Development Process Documentation
+1. **CREATE** `/docs/project-context/development-process.md`:
+   - DEFINE three-stage workflow (Development → Review → QA)
+   - SPECIFY entry/exit criteria for each stage
+   - DOCUMENT required activities per stage
+   - ESTABLISH quality gates and checkpoints
+   - OUTLINE story movement rules
+
+2. **INCLUDE** sections:
+   - Stage Definitions
+   - Stage Requirements
+   - Testing Strategy
+   - Review Process
+   - Quality Gates
+
+#### Phase 4: Coding Standards Documentation
+1. **ASK** user about comprehensive coding standards:
+   - Naming conventions (camelCase, snake_case, PascalCase patterns)
+   - Function/method organization (length limits, complexity)
+   - Class/module structure (single responsibility patterns)
+   - Comment and documentation standards
+   - Framework-specific patterns
+   - File organization preferences
+   - Testing standards
+   - Quality requirements
+   - Git workflow conventions
+
+2. **CREATE** `/docs/project-context/coding-standards.md`:
+   - DOCUMENT language-specific standards
+   - DEFINE framework-specific patterns
+   - SPECIFY file organization rules
+   - ESTABLISH testing standards
+   - SET quality requirements
+   - OUTLINE git workflow
+
+#### Phase 5: Project Glossary
+1. **CREATE** `/docs/project-context/project-glossary.md`:
+   - PROVIDE template for domain-specific terminology
+   - INCLUDE sections for:
+     * Domain Terms (business-specific vocabulary)
+     * Technical Terms (framework-specific terminology)
+     * Process Terms (development workflow vocabulary)
+   - ENCOURAGE user to populate over time
+
+#### Phase 6: Project Brief Template
+1. **CREATE** `/docs/project-context/project-brief.md`:
+   - PROVIDE comprehensive project overview template
+   - INCLUDE sections:
+     * Project Overview (name, description, objectives)
+     * Timeline (start date, target completion, milestones)
+     * Story Planning (total stories, prioritization)
+     * Success Metrics
+   - PROMPT user to fill with actual project details
+
+#### Phase 7: Story Template Creation
+1. **CREATE** `/docs/stories/templates/story-template.md`:
+   - COMPREHENSIVE story template with sections:
+     * Story Header (ID, title, status, priority)
+     * Description and Context
+     * Success Criteria and Acceptance Tests
+     * Technical Implementation Notes
+     * Implementation Checklist
+     * Test Cases (unit, integration, browser)
+     * Rollback Plans
+     * Lessons Learned
+   - REFERENCE project's technical stack from `technical-stack.md`
+   - ALIGN with coding standards from `coding-standards.md`
+   - MATCH process requirements from `development-process.md`
+
+#### Phase 8: Completion Summary and Next Steps
+1. **DISPLAY** creation summary:
+   ```
+   ✅ Project Structure Initialized
+   ═══════════════════════════════════
+
+   📁 Directories Created:
+   - /docs/project-context/
+   - /docs/stories/development/
+   - /docs/stories/review/
+   - /docs/stories/qa/
+   - /docs/stories/completed/
+   - /docs/stories/backlog/
+   - /docs/stories/templates/
+
+   📄 Documents Created:
+   - /docs/project-context/technical-stack.md
+   - /docs/project-context/development-process.md
+   - /docs/project-context/coding-standards.md
+   - /docs/project-context/project-glossary.md
+   - /docs/project-context/project-brief.md
+   - /docs/stories/templates/story-template.md
+
+   🔧 Configuration Status:
+   - Technical stack: Configured with [user's stack]
+   - Coding standards: Customized
+   - Development process: Defined
+   ```
+
+2. **SUGGEST** next steps:
+   - Fill out `project-brief.md` with actual project details
+   - Customize `coding-standards.md` with team-specific patterns
+   - Update `development-process.md` with workflow preferences
+   - Populate `project-glossary.md` with domain terms
+   - Create first story: `/sdd:story-new`
+   - Begin development: `/sdd:story-start`
+
+3. **PROVIDE** quick start guide:
+   - How to create a story
+   - How to move story through workflow
+   - How to check project status
+   - Where to find documentation
+
+### OUTPUTS
+**Directories**:
+- `/docs/project-context/` - Project documentation root
+- `/docs/stories/development/` - Active stories
+- `/docs/stories/review/` - Stories in review
+- `/docs/stories/qa/` - Stories in QA
+- `/docs/stories/completed/` - Finished stories
+- `/docs/stories/backlog/` - Planned stories
+- `/docs/stories/templates/` - Templates
+
+**Files**:
+- `/docs/project-context/technical-stack.md` - Technology choices
+- `/docs/project-context/development-process.md` - Workflow definitions
+- `/docs/project-context/coding-standards.md` - Quality standards
+- `/docs/project-context/project-glossary.md` - Terminology reference
+- `/docs/project-context/project-brief.md` - Project overview
+- `/docs/stories/templates/story-template.md` - Story template
+
+### RULES
+- MUST create all directories before creating files
+- MUST add `.gitkeep` to all empty directories
+- MUST gather user input for technology stack
+- MUST customize templates based on user's stack
+- SHOULD reference actual technology choices in templates
+- NEVER overwrite existing files without user confirmation
+- ALWAYS provide next steps after initialization
+
+## File Structure
+
+### Directory Hierarchy
+```
+/docs/project-context/
+├── technical-stack.md              # Technology choices and versions
+├── development-process.md           # Workflow and quality gates
+├── coding-standards.md              # Code quality standards
+├── project-glossary.md              # Domain terminology
+└── project-brief.md                 # Project overview and goals
+
+/docs/stories/
+├── /development/                    # Active implementation
+│   └── .gitkeep
+├── /review/                         # Code review stage
+│   └── .gitkeep
+├── /qa/                            # Quality assurance
+│   └── .gitkeep
+├── /completed/                      # Finished stories
+│   └── .gitkeep
+├── /backlog/                        # Planned stories
+│   └── .gitkeep
+└── /templates/                      # Templates
+    ├── .gitkeep
+    └── story-template.md           # Story template
+```
+
+## Examples
+
+### Example 1: First-Time Setup
+```bash
+INPUT:
+/sdd:project-init
+
+INTERACTION:
+→ Asks about frontend framework
+→ Asks about backend framework
+→ Asks about database
+→ Asks about testing framework
+→ Asks about deployment platform
+
+OUTPUT:
+✅ Project Structure Initialized
+═══════════════════════════════════
+
+📁 Directories Created:
+- /docs/project-context/
+- /docs/stories/development/
+- /docs/stories/review/
+- /docs/stories/qa/
+- /docs/stories/completed/
+- /docs/stories/backlog/
+- /docs/stories/templates/
+
+📄 Documents Created:
+- /docs/project-context/technical-stack.md (Laravel TALL stack)
+- /docs/project-context/development-process.md
+- /docs/project-context/coding-standards.md
+- /docs/project-context/project-glossary.md
+- /docs/project-context/project-brief.md
+- /docs/stories/templates/story-template.md
+
+🔧 Configuration Status:
+- Technical stack: Laravel 12, Livewire 3, Alpine.js, Tailwind CSS
+- Testing: Pest PHP, Playwright
+- Deployment: Laravel Herd (local), Forge (production)
+
+💡 NEXT STEPS:
+1. Fill out /docs/project-context/project-brief.md with your project details
+2. Run /sdd:project-brief to create comprehensive project plan
+3. Create your first story with /sdd:story-new
+4. Begin development with /sdd:story-start
+
+📚 QUICK START:
+- Create story: /sdd:story-new
+- View status: /sdd:project-status
+- Start work: /sdd:story-start [id]
+- Documentation: See /docs/project-context/ directory
+```
+
+### Example 2: Already Initialized
+```bash
+INPUT:
+/sdd:project-init
+
+OUTPUT:
+⚠️  Project Already Initialized
+
+The following directories already exist:
+- /docs/project-context/
+- /docs/stories/
+
+Would you like to:
+1. Skip initialization (directories exist)
+2. Add missing directories/files only
+3. Recreate all templates (keeps existing config)
+4. Abort
+
+Choose an option [1-4]:
+```
+
+### Example 3: Partial Initialization
+```bash
+INPUT:
+/sdd:project-init
+
+DETECTION:
+→ Found /docs/project-context/ but missing /docs/stories/
+
+OUTPUT:
+ℹ️  Partial Project Structure Detected
+
+Found: /docs/project-context/
+Missing: /docs/stories/ and subdirectories
+
+Creating missing directories...
+
+✅ Completed Missing Structure
+═══════════════════════════════════
+
+📁 Created:
+- /docs/stories/development/
+- /docs/stories/review/
+- /docs/stories/qa/
+- /docs/stories/completed/
+- /docs/stories/backlog/
+- /docs/stories/templates/
+
+Existing configuration preserved.
+
+💡 NEXT STEPS:
+- Create first story: /sdd:story-new
+- View project status: /sdd:project-status
+```
+
+## Edge Cases
+
+### Existing Project Structure
+- DETECT existing directories and files
+- OFFER options:
+  * Skip initialization completely
+  * Add missing directories/files only
+  * Recreate templates (preserve config)
+  * Abort operation
+- NEVER overwrite without confirmation
+
+### Partial Initialization
+- IDENTIFY which components exist
+- CREATE only missing components
+- PRESERVE existing configuration
+- LOG what was added vs what existed
+
+### Permission Issues
+- CHECK write permissions before creating
+- REPORT specific permission errors
+- SUGGEST running with appropriate permissions
+- PROVIDE manual creation instructions if needed
+
+### Git Not Initialized
+- DETECT if .git directory exists
+- SUGGEST initializing git if missing
+- NOTE that .gitkeep files require git
+- CONTINUE with initialization regardless
+
+## Error Handling
+- **Permission denied**: Report specific directory/file, suggest fixes
+- **Disk space full**: Report error, suggest cleanup
+- **Invalid path**: Verify working directory is project root
+- **User cancels**: Clean up partial creation, exit gracefully
+
+## Performance Considerations
+- Directory creation is fast (< 100ms typically)
+- File creation with templates (< 500ms typically)
+- Interactive prompts allow user to control pace
+- No heavy processing or external dependencies
+
+## Security Considerations
+- Verify write permissions before operations
+- Sanitize all file paths
+- Don't create files outside project root
+- Don't overwrite without explicit confirmation
+
+## Related Commands
+- `/sdd:project-brief` - Create comprehensive project plan after init
+- `/sdd:story-new` - Create first story after initialization
+- `/sdd:project-status` - View current project state
+- `/sdd:project-context-update` - Update context documents later
+
+## Constraints
+- ⚠️ MUST NOT overwrite existing files without confirmation
+- ✅ MUST create all directories before files
+- ✅ MUST add `.gitkeep` to empty directories
+- 📋 MUST gather user input for technology stack
+- 🔧 SHOULD customize templates based on stack
+- 💾 MUST verify write permissions
+- ⚡ SHOULD complete initialization in < 5 seconds (excluding user input)