{"id":29806288,"url":"https://github.com/papaoloba/spec-based-claude-code","last_synced_at":"2025-10-09T18:23:23.563Z","repository":{"id":306925221,"uuid":"1023670957","full_name":"papaoloba/spec-based-claude-code","owner":"papaoloba","description":"Implementation of a Spec-Driven Development workflow in Claude Code using custom slash commands","archived":false,"fork":false,"pushed_at":"2025-07-22T23:24:00.000Z","size":92,"stargazers_count":31,"open_issues_count":0,"forks_count":3,"subscribers_count":0,"default_branch":"main","last_synced_at":"2025-07-28T14:16:33.609Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":null,"language":"TypeScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":null,"status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/papaoloba.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":null,"code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null}},"created_at":"2025-07-21T14:09:21.000Z","updated_at":"2025-07-27T21:40:30.000Z","dependencies_parsed_at":"2025-07-28T14:16:38.468Z","dependency_job_id":null,"html_url":"https://github.com/papaoloba/spec-based-claude-code","commit_stats":null,"previous_names":["papaoloba/spec-based-claude-code"],"tags_count":null,"template":false,"template_full_name":null,"purl":"pkg:github/papaoloba/spec-based-claude-code","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/papaoloba%2Fspec-based-claude-code","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/papaoloba%2Fspec-based-claude-code/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/papaoloba%2Fspec-based-claude-code/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/papaoloba%2Fspec-based-claude-code/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/papaoloba","download_url":"https://codeload.github.com/papaoloba/spec-based-claude-code/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/papaoloba%2Fspec-based-claude-code/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":279001940,"owners_count":26083226,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","status":"online","status_checked_at":"2025-10-09T02:00:07.460Z","response_time":59,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":[],"created_at":"2025-07-28T14:05:56.414Z","updated_at":"2025-10-09T18:23:23.555Z","avatar_url":"https://github.com/papaoloba.png","language":"TypeScript","readme":"# Claude Code Spec-Driven Development Implementation Guide\n\n## Table of Contents\n1. [Overview](#overview)\n2. [Benefits](#benefits)\n3. [Prerequisites](#prerequisites)\n4. [Quick Start](#quick-start)\n5. [Installation](#installation)\n6. [Command Reference](#command-reference)\n7. [Workflow Example](#workflow-example)\n8. [Templates](#templates)\n9. [Best Practices](#best-practices)\n10. [Troubleshooting](#troubleshooting)\n11. [Advanced Usage](#advanced-usage)\n\n## Overview\n\nThis guide implements a spec-driven development workflow in Claude Code using custom slash commands. The workflow enforces a structured approach where specifications are created, reviewed, and approved before implementation begins.\n\n### Core Concept\n\nEach feature is developed through four sequential phases:\n\n1. **Requirements** - Define WHAT needs to be built\n2. **Design** - Determine HOW it will be built  \n3. **Tasks** - Plan WHEN and in what order\n4. **Implementation** - Execute the plan with progress tracking\n\n### File Structure\n\n```\n/spec/\n├── 001-user-authentication/\n│   ├── requirements.md\n│   ├── design.md\n│   └── tasks.md\n├── 002-payment-integration/\n│   ├── requirements.md\n│   ├── design.md\n│   └── tasks.md\n└── .current-spec  # Stores the full spec directory name, e.g. 001-user-authentication\n```\n\n## Benefits\n\n- **🎯 Catch problems early** - Identify and resolve requirement ambiguities before coding\n- **🎮 Maintain control** - Review and approve each phase before proceeding\n- **🔄 Iterate safely** - Modify specifications without losing conversation context\n- **🧠 Keep AI focused** - Separate planning from coding for better results\n- **👥 Enable collaboration** - Living documentation for team reviews\n- **📚 Build knowledge** - Document decisions and preserve context\n\n## Prerequisites\n\n- Claude Code installed and configured\n- Git repository initialized\n- Basic understanding of markdown\n\n## Quick Start\n\n```bash\n# 1. Set up the spec workflow (see Installation)\nmkdir -p .claude/commands/spec\nmkdir -p spec\n\n# 2. Create your first spec\n/spec:new user-authentication\n\n# 3. Follow the workflow\n/spec:requirements      # Create requirements\n/spec:approve requirements  # Mark as approved\n/spec:design           # Create design\n/spec:approve design   # Mark as approved  \n/spec:tasks            # Create task list\n/spec:approve tasks    # Mark as approved\n/spec:implement        # Start coding\n```\n\n## Installation\n\n### Step 1: Create Directory Structure\n\n```bash\n# Create directories for spec commands\nmkdir -p .claude/commands/spec\nmkdir -p spec\n\n# Create a file to track current spec\necho \"\" \u003e spec/.current-spec\n```\n\n### Step 2: Create Spec Commands\n\n#### `/spec:new` - Initialize New Specification\n\nCreate `.claude/commands/spec/new.md`:\n\n```markdown\n---\nallowed-tools: Bash(mkdir:*), Bash(echo:*), Bash(date:*), Bash(ls:*)\ndescription: Create a new feature specification\nargument-hint: \u003cfeature-name\u003e\n---\n\n## Current Spec Status\n\n!`ls -la spec/ 2\u003e/dev/null | grep \"^d\" | wc -l | xargs -I {} echo \"Total specs: {}\"`\n\n## Your Task\n\nCreate a new specification directory for the feature: $ARGUMENTS\n\n1. Determine the next ID number (format: 001, 002, etc.)\n2. Create directory: `spec/[ID]-$ARGUMENTS/`\n3. Update `spec/.current-spec` with the new spec directory name ([ID]-$ARGUMENTS)\n4. Create a README.md in the new directory with:\n   - Feature name\n   - Creation date\n   - Initial status checklist\n5. Inform the user about next steps\n\nUse the Bash tool to create directories and files as needed.\n```\n\n#### `/spec:requirements` - Generate Requirements Template\n\nCreate `.claude/commands/spec/requirements.md`:\n\n```markdown\n---\nallowed-tools: Bash(cat:*), Bash(test:*), Bash(touch:*), Write\ndescription: Create or review requirements specification\n---\n\n## Context\n\nCurrent spec: !`cat spec/.current-spec 2\u003e/dev/null || echo \"No active spec\"`\nSpec directory contents: !`ls -la spec/$(cat spec/.current-spec 2\u003e/dev/null)/ 2\u003e/dev/null || echo \"Spec not found\"`\n\n## Your Task\n\nFor the current active specification:\n\n1. Check if requirements.md exists\n2. If not, create a comprehensive requirements.md with:\n   - Feature overview\n   - User stories with acceptance criteria\n   - Functional requirements (P0, P1, P2)\n   - Non-functional requirements\n   - Constraints and assumptions\n   - Out of scope items\n   - Success metrics\n3. If it exists, display current content and suggest improvements\n4. Remind user to use `/spec:approve requirements` when ready\n\nUse the Write tool to create/update the requirements.md file.\n```\n\n#### `/spec:design` - Generate Design Document\n\nCreate `.claude/commands/spec/design.md`:\n\n```markdown\n---\nallowed-tools: Bash(cat:*), Bash(test:*), Bash(ls:*), Write\ndescription: Create technical design specification\n---\n\n## Context\n\nCurrent spec: !`cat spec/.current-spec 2\u003e/dev/null`\nRequirements approved: !`test -f spec/$(cat spec/.current-spec)/.requirements-approved \u0026\u0026 echo \"Yes\" || echo \"No\"`\nCurrent directory: !`ls -la spec/$(cat spec/.current-spec)/ 2\u003e/dev/null`\n\n## Your Task\n\n1. Verify requirements are approved (look for .requirements-approved file)\n2. If not approved, inform user to complete requirements first\n3. If approved, create/update design.md with:\n   - Architecture overview (with diagrams)\n   - Technology stack decisions\n   - Data model and schema\n   - API design\n   - Security considerations\n   - Performance considerations\n   - Deployment architecture\n   - Technical risks and mitigations\n4. Use ASCII art or mermaid diagrams where helpful\n\nUse the Write tool to create the design document.\n```\n\n#### `/spec:tasks` - Generate Task List\n\nCreate `.claude/commands/spec/tasks.md`:\n\n```markdown\n---\nallowed-tools: Bash(cat:*), Bash(test:*), Write\ndescription: Create implementation task list\n---\n\n## Context\n\nCurrent spec: !`cat spec/.current-spec 2\u003e/dev/null`\nDesign approved: !`test -f spec/$(cat spec/.current-spec)/.design-approved \u0026\u0026 echo \"Yes\" || echo \"No\"`\n\n## Your Task\n\n1. Verify design is approved\n2. Create tasks.md with:\n   - Overview with time estimates\n   - Phase breakdown (Foundation, Core, Testing, Deployment)\n   - Detailed task list with checkboxes\n   - Task dependencies\n   - Risk mitigation tasks\n3. Each task should be specific and actionable\n4. Use markdown checkboxes: `- [ ] Task description`\n\nOrganize tasks to enable incremental development and testing.\n```\n\n#### `/spec:approve` - Approve Specification Phase\n\nCreate `.claude/commands/spec/approve.md`:\n\n```markdown\n---\nallowed-tools: Bash(touch:*), Bash(test:*), Bash(cat:*)\ndescription: Approve a specification phase\nargument-hint: requirements|design|tasks\n---\n\n## Context\n\nCurrent spec: !`cat spec/.current-spec 2\u003e/dev/null`\nSpec directory: !`ls -la spec/$(cat spec/.current-spec)/ 2\u003e/dev/null`\n\n## Your Task\n\nFor the phase \"$ARGUMENTS\":\n\n1. Verify the phase file exists (requirements.md, design.md, or tasks.md)\n2. Create approval marker file: `.${ARGUMENTS}-approved`\n3. Inform user about next steps:\n   - After requirements → design phase\n   - After design → tasks phase\n   - After tasks → implementation\n4. If invalid phase name, show valid options\n\nUse touch command to create approval markers.\n```\n\n#### `/spec:status` - Show Specification Status\n\nCreate `.claude/commands/spec/status.md`:\n\n```markdown\n---\nallowed-tools: Bash(ls:*), Bash(cat:*), Bash(grep:*), Bash(test:*), Bash(find:*)\ndescription: Show all specifications and their status\n---\n\n## Gather Status Information\n\nAll specs: !`ls -d spec/*/ 2\u003e/dev/null | sort`\nCurrent spec: !`cat spec/.current-spec 2\u003e/dev/null || echo \"None\"`\n\nFor each spec directory, check:\n!`for dir in spec/*/; do\n    if [ -d \"$dir\" ]; then\n        echo \"=== $dir ===\"\n        ls -la \"$dir\" | grep -E \"(requirements|design|tasks)\\.md|\\..*-approved\"\n        if [ -f \"$dir/tasks.md\" ]; then\n            echo \"Task progress:\"\n            grep \"^- \\[\" \"$dir/tasks.md\" | head -5\n            echo \"Total tasks: $(grep -c \"^- \\[\" \"$dir/tasks.md\" 2\u003e/dev/null || echo 0)\"\n            echo \"Completed: $(grep -c \"^- \\[x\\]\" \"$dir/tasks.md\" 2\u003e/dev/null || echo 0)\"\n        fi\n        echo \"\"\n    fi\ndone`\n\n## Your Task\n\nPresent a clear status report showing:\n1. All specifications with their IDs and names\n2. Current active spec (highlighted)\n3. Phase completion status for each spec\n4. Task progress percentage if applicable\n5. Recommended next action for active spec\n```\n\n#### `/spec:implement` - Start Implementation Session\n\nCreate `.claude/commands/spec/implement.md`:\n\n```markdown\n---\nallowed-tools: Bash(cat:*), Bash(test:*), Bash(grep:*), Write\ndescription: Start implementation from approved tasks\nargument-hint: [phase-number]\n---\n\n## Context\n\nCurrent spec: !`cat spec/.current-spec 2\u003e/dev/null`\nTasks approved: !`test -f spec/$(cat spec/.current-spec)/.tasks-approved \u0026\u0026 echo \"Yes\" || echo \"No\"`\n\n## Current Tasks\n\n!`if [ -f \"spec/$(cat spec/.current-spec)/tasks.md\" ]; then\n    echo \"=== Phase Overview ===\"\n    grep \"^## Phase\" \"spec/$(cat spec/.current-spec)/tasks.md\"\n    echo \"\"\n    echo \"=== Incomplete Tasks ===\"\n    grep \"^- \\[ \\]\" \"spec/$(cat spec/.current-spec)/tasks.md\" | head -20\nfi`\n\n## Your Task\n\n1. Verify all phases are approved\n2. If phase number provided ($ARGUMENTS), focus on that phase\n3. Display current incomplete tasks\n4. Create an implementation session log\n5. Guide user to:\n   - Work on tasks sequentially\n   - Update task checkboxes as completed\n   - Commit changes regularly\n6. Remind about using Write tool to update tasks.md\n\nStart implementing based on the task list!\n```\n\n#### `/spec:switch` - Switch Active Specification\n\nCreate `.claude/commands/spec/switch.md`:\n\n```markdown\n---\nallowed-tools: Bash(ls:*), Bash(echo:*), Bash(test:*)\ndescription: Switch to a different specification\nargument-hint: \u003cspec-id\u003e\n---\n\n## Available Specifications\n\n!`ls -d spec/*/ 2\u003e/dev/null | sort`\n\n## Your Task\n\nSwitch the active specification to: $ARGUMENTS\n\n1. Verify the spec directory exists\n2. Update spec/.current-spec with the new spec directory name ([ID]-$ARGUMENTS)\n3. Show the status of the newly active spec\n4. Display next recommended action\n\nIf no argument provided, list all available specs.\n```\n\n### Step 3: Create Helper Commands (Optional)\n\n#### `/spec:update-task` - Update Task Status\n\nCreate `.claude/commands/spec/update-task.md`:\n\n```markdown\n---\nallowed-tools: Bash(cat:*), Bash(grep:*), Write\ndescription: Mark a task as complete\nargument-hint: \u003ctask-description-or-number\u003e\n---\n\n## Current Tasks\n\n!`cat spec/$(cat spec/.current-spec)/tasks.md | grep -n \"^- \\[\" | head -20`\n\n## Your Task\n\nUpdate the task status for: \"$ARGUMENTS\"\n\n1. Find the matching task in tasks.md\n2. Change `- [ ]` to `- [x]` for that task\n3. Show updated progress statistics\n4. Suggest next task to work on\n\nUse the Write tool to update the file.\n```\n\n#### `/spec:review` - Review Current Phase\n\nCreate `.claude/commands/spec/review.md`:\n\n```markdown\n---\nallowed-tools: Bash(cat:*), Bash(test:*)\ndescription: Review current specification phase\n---\n\n## Current Spec Status\n\n!`current=$(cat spec/.current-spec 2\u003e/dev/null)\nif [ -n \"$current\" ]; then\n    echo \"Active spec: $current\"\n    echo \"Files present:\"\n    ls -la \"spec/$current/\" | grep -E \"(requirements|design|tasks)\\.md\"\n    echo \"\"\n    echo \"Approval status:\"\n    ls -la \"spec/$current/\" | grep \"approved\"\nfi`\n\n## Your Task\n\n1. Identify which phase is currently active (not yet approved)\n2. Display the content of that phase's document\n3. Provide a review checklist:\n   - Does it meet all criteria?\n   - Is it complete and clear?\n   - Any missing elements?\n4. Remind user how to approve when ready\n```\n\n## Command Reference\n\n### Core Commands\n\n| Command | Description | Usage |\n|---------|-------------|--------|\n| `/spec:new` | Create a new specification | `/spec:new user-authentication` |\n| `/spec:requirements` | Generate requirements template | `/spec:requirements` |\n| `/spec:design` | Generate design template | `/spec:design` |\n| `/spec:tasks` | Generate task list template | `/spec:tasks` |\n| `/spec:approve` | Approve a specification phase | `/spec:approve requirements` |\n| `/spec:implement` | Start implementation phase | `/spec:implement [phase]` |\n| `/spec:status` | Show all specs and progress | `/spec:status` |\n| `/spec:switch` | Switch active specification | `/spec:switch 001-user-auth` |\n| `/spec:update-task` | Mark task as complete | `/spec:update-task \"Create user model\"` |\n| `/spec:review` | Review current phase | `/spec:review` |\n\n### Command Flow\n\n```mermaid\ngraph LR\n    A[\"/spec:new\"] --\u003e B[\"/spec:requirements\"]\n    B --\u003e C[\"/spec:approve requirements\"]\n    C --\u003e D[\"/spec:design\"]\n    D --\u003e E[\"/spec:approve design\"]\n    E --\u003e F[\"/spec:tasks\"]\n    F --\u003e G[\"/spec:approve tasks\"]\n    G --\u003e H[\"/spec:implement\"]\n```\n\n## Workflow Example\n\n### Complete Feature Development Flow\n\n```bash\n# Day 1: Specification\n/spec:new user-authentication\n# Creates: spec/001-user-authentication/\n\n/spec:requirements\n# Claude creates requirements.md template\n# You edit and refine the requirements\n\n/spec:approve requirements\n# Creates .requirements-approved marker\n\n# Day 2: Design\n/spec:design  \n# Claude creates design.md based on requirements\n# You review and adjust the technical design\n\n/spec:approve design\n# Creates .design-approved marker\n\n# Day 3: Planning\n/spec:tasks\n# Claude creates detailed task breakdown\n# You review and adjust time estimates\n\n/spec:approve tasks\n# Creates .tasks-approved marker\n\n# Day 4-10: Implementation\n/spec:implement 1  # Focus on Phase 1\n# Work through tasks, updating checkboxes\n\n/spec:update-task \"Initialize project repository\"\n# Claude marks task as complete\n\n/spec:status  # Check overall progress\n# See all specs and completion percentages\n```\n\n## Templates\n\n### Requirements Template Structure\n\n```markdown\n# Requirements Specification\n\n## Feature Overview\n[High-level description of the feature]\n\n## User Stories\n\n### Story 1: [User can authenticate]\n**As a** registered user  \n**I want** to log in with my credentials  \n**So that** I can access my personal dashboard\n\n**Acceptance Criteria:**\n- [ ] User can enter email and password\n- [ ] System validates credentials\n- [ ] Successful login redirects to dashboard\n- [ ] Failed login shows error message\n\n## Functional Requirements\n\n### Must Have (P0)\n- **REQ-001**: System must support email/password authentication\n- **REQ-002**: Passwords must be hashed using bcrypt\n\n### Should Have (P1)\n- **REQ-003**: Support \"Remember me\" functionality\n- **REQ-004**: Implement password reset via email\n\n### Nice to Have (P2)\n- **REQ-005**: Support OAuth providers (Google, GitHub)\n\n## Non-Functional Requirements\n\n### Performance\n- Login response time \u003c 500ms\n- Support 1000 concurrent users\n\n### Security\n- Passwords minimum 8 characters\n- Session timeout after 30 minutes\n- HTTPS only\n\n## Constraints and Assumptions\n\n### Technical Constraints\n- Must use existing user database\n- Compatible with React frontend\n\n### Assumptions\n- Users have valid email addresses\n- Email service is available\n\n## Out of Scope\n- Two-factor authentication\n- Biometric authentication\n\n## Success Metrics\n- Login success rate \u003e 95%\n- Password reset completion \u003e 80%\n```\n\n### Design Template Structure\n\n```markdown\n# Technical Design Specification\n\n## Architecture Overview\n\n### System Context\n\n```mermaid\ngraph TD\n    A[Browser] --\u003e B[API Gateway]\n    B --\u003e C[Auth Service]\n    C --\u003e D[PostgreSQL]\n```\n\n## Technology Stack\n\n### Frontend\n- **Framework**: React 18\n- **State Management**: Context API\n- **Styling**: TailwindCSS\n- **Form Handling**: React Hook Form\n\n### Backend\n- **Runtime**: Node.js 20\n- **Framework**: Express.js\n- **Authentication**: JWT + bcrypt\n- **Database**: PostgreSQL 15\n\n## Data Model\n\n### Users Table\n```sql\nCREATE TABLE users (\n    id UUID PRIMARY KEY DEFAULT gen_random_uuid(),\n    email VARCHAR(255) UNIQUE NOT NULL,\n    password_hash VARCHAR(255) NOT NULL,\n    created_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP,\n    last_login TIMESTAMP\n);\n```\n\n### Sessions Table\n```sql\nCREATE TABLE sessions (\n    id UUID PRIMARY KEY DEFAULT gen_random_uuid(),\n    user_id UUID REFERENCES users(id),\n    token_hash VARCHAR(255) NOT NULL,\n    expires_at TIMESTAMP NOT NULL,\n    created_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP\n);\n```\n\n## API Design\n\n### POST /api/auth/login\n**Request**:\n```json\n{\n  \"email\": \"user@example.com\",\n  \"password\": \"securepassword\"\n}\n```\n\n**Response (200)**:\n```json\n{\n  \"token\": \"eyJhbGciOiJIUzI1NiIs...\",\n  \"user\": {\n    \"id\": \"123e4567-e89b-12d3-a456-426614174000\",\n    \"email\": \"user@example.com\"\n  }\n}\n```\n\n### POST /api/auth/logout\n**Headers**: `Authorization: Bearer \u003ctoken\u003e`\n\n**Response (200)**:\n```json\n{\n  \"message\": \"Logged out successfully\"\n}\n```\n\n## Security Considerations\n\n### Password Storage\n- Bcrypt with cost factor 12\n- Never store plain text passwords\n\n### JWT Configuration\n- HS256 algorithm\n- 15-minute access token expiry\n- Secure, httpOnly cookies\n\n### Rate Limiting\n- 5 login attempts per IP per minute\n- Exponential backoff for failed attempts\n\n## Error Handling\n\n### Standard Error Response\n```json\n{\n  \"error\": {\n    \"code\": \"AUTH_INVALID_CREDENTIALS\",\n    \"message\": \"Invalid email or password\",\n    \"timestamp\": \"2024-01-20T10:30:00Z\"\n  }\n}\n```\n\n## Technical Risks\n\n| Risk | Impact | Probability | Mitigation |\n|------|--------|-------------|------------|\n| Database connection failure | High | Low | Connection pooling, retry logic |\n| JWT secret exposure | Critical | Low | Environment variables, key rotation |\n| Brute force attacks | Medium | Medium | Rate limiting, account lockout |\n```\n\n### Tasks Template Structure\n\n```markdown\n# Implementation Tasks\n\n## Phase 1: Foundation Setup\n\n### Development Environment\n- [ ] Initialize Node.js project with TypeScript\n- [ ] Set up ESLint and Prettier\n- [ ] Configure Jest for testing\n- [ ] Create docker-compose for PostgreSQL\n\n### Project Structure\n- [ ] Create src/ directory structure\n- [ ] Set up environment variables\n- [ ] Configure build scripts\n- [ ] Initialize Git repository\n\n## Phase 2: Backend Implementation\n\n### Database Layer\n- [ ] Create database migrations for users table\n- [ ] Create database migrations for sessions table\n- [ ] Implement database connection module\n- [ ] Create user repository layer\n\n### Authentication Logic\n- [ ] Implement password hashing utilities\n- [ ] Create JWT token generation/validation\n- [ ] Build login endpoint\n- [ ] Build logout endpoint\n- [ ] Add session management\n\n### Middleware\n- [ ] Create authentication middleware\n- [ ] Implement rate limiting\n- [ ] Add request validation\n- [ ] Set up error handling\n\n## Phase 3: Frontend Integration\n\n### Components\n- [ ] Create login form component\n- [ ] Add form validation\n- [ ] Implement error displays\n- [ ] Create loading states\n\n### State Management\n- [ ] Set up auth context\n- [ ] Implement login action\n- [ ] Handle token storage\n- [ ] Add logout functionality\n\n## Phase 4: Testing \u0026 Documentation\n\n### Testing\n- [ ] Write unit tests for auth utilities\n- [ ] Test API endpoints\n- [ ] Create integration tests\n- [ ] Manual testing checklist\n\n### Documentation\n- [ ] API documentation\n- [ ] Setup instructions\n- [ ] Security guidelines\n- [ ] Deployment notes\n\n## Dependencies\n\n```mermaid\ngraph TD\n    A[Environment Setup] --\u003e B[Database Layer]\n    B --\u003e C[Auth Logic]\n    C --\u003e D[API Endpoints]\n    D --\u003e E[Frontend Components]\n    E --\u003e F[Integration Tests]\n    F --\u003e G[Documentation]\n```\n\n## Definition of Done\n\nEach task is considered complete when:\n- Code is written and functional\n- Unit tests pass\n- Code review completed\n- Documentation updated\n```\n\n## Best Practices\n\n### 1. Phase Discipline\n- ✅ Complete phases sequentially\n- ✅ Review thoroughly before approval\n- ✅ Keep approval markers in version control\n- ❌ Don't skip phases\n- ❌ Don't implement without approved specs\n\n### 2. Documentation Standards\n- ✅ Use clear, specific language\n- ✅ Include concrete examples\n- ✅ Add diagrams where helpful\n- ❌ Avoid vague requirements\n- ❌ Don't over-engineer early phases\n\n### 3. Task Management\n- ✅ Update task status immediately\n- ✅ Keep tasks small and specific\n- ✅ Include time estimates\n- ✅ Group related tasks\n- ❌ Don't batch status updates\n\n### 4. Command Usage\n- ✅ Use commands in sequence\n- ✅ Review output before proceeding\n- ✅ Keep spec/.current-spec updated\n- ❌ Don't modify approval files manually\n\n### 5. Version Control\n```bash\n# Good commit messages\ngit commit -m \"spec(001): complete requirements phase\"\ngit commit -m \"spec(001): add security requirements\"\ngit commit -m \"impl(001): complete user model (tasks 3-5)\"\n\n# Include spec files in commits\ngit add spec/001-user-authentication/\ngit commit -m \"spec(001): approve design phase\"\n\n# Branch naming\ngit checkout -b feature/001-user-authentication\ngit checkout -b spec/001-requirements\n```\n\n## Troubleshooting\n\n### Common Issues and Solutions\n\n#### \"No active spec\" Error\n```bash\n# Check current spec\ncat spec/.current-spec\n\n# If empty, set it manually\necho \"001-user-authentication\" \u003e spec/.current-spec  # Use the full directory name\n\n# Or use switch command\n/spec:switch 001-user-authentication\n```\n\n#### Phase Not Approved\n```bash\n# Check approval status\nls -la spec/001-user-authentication/.*-approved\n\n# Approve if ready\n/spec:approve requirements\n```\n\n#### Tasks Not Updating\n```bash\n# Ensure you're using Write tool in Claude\n# When updating tasks, be specific:\n/spec:update-task \"exact task description\"\n\n# Or manually edit and have Claude read\nvi spec/001-user-authentication/tasks.md\n```\n\n#### Command Not Found\n```bash\n# Check command exists\nls .claude/commands/spec/\n\n# Ensure .md extension\nls .claude/commands/spec/new.md\n\n# Commands should appear in\n/help\n```\n\n## Advanced Usage\n\n### Creating Project Templates\n\nCreate reusable templates for common project types:\n\n```bash\n# Create template directory\nmkdir -p .claude/templates/web-api\n\n# Add template files\ncp spec/001-user-authentication/requirements.md .claude/templates/web-api/\ncp spec/001-user-authentication/design.md .claude/templates/web-api/\n```\n\n### Automated Status Reports\n\nCreate a status report command:\n\n```markdown\n# .claude/commands/spec/report.md\n---\nallowed-tools: Bash(find:*), Bash(grep:*), Bash(date:*)\ndescription: Generate comprehensive spec report\n---\n\nGenerate a markdown report showing:\n- All specifications and their status\n- Task completion percentages\n- Timeline adherence\n- Blocked items\n- Next actions for each spec\n```\n\n### Integration with Issue Trackers\n\nLink specs to GitHub issues:\n\n```markdown\n# In your spec files, reference issues\n## Related Issues\n- Implements: #123\n- Fixes: #124, #125\n- Related to: #126\n```\n\n### Multi-Phase Implementation\n\nFor large features, split implementation:\n\n```bash\n/spec:implement 1  # Complete Phase 1\n# Commit and test\n\n/spec:implement 2  # Move to Phase 2\n# Continue iteratively\n```\n\n### Spec Archival\n\nWhen specs are complete:\n\n```bash\n# Create archive directory\nmkdir -p spec/archive/2024\n\n# Move completed specs\nmv spec/001-user-authentication spec/archive/2024/\n\n# Update current spec if needed\necho \"\" \u003e spec/.current-spec\n```\n\n## Tips for Success\n\n1. **Start Small**: First spec should be a simple feature\n2. **Be Specific**: Vague requirements lead to rework\n3. **Review Often**: Check `/spec:status` regularly\n4. **Commit Frequently**: Keep specs in version control\n5. **Iterate**: Specs can evolve, but track changes\n6. **Team Alignment**: Share specs for review before approval\n7. **Learn and Adapt**: Refine templates based on experience\n\n## Conclusion\n\nThis spec-driven workflow brings professional software development practices to AI-assisted coding. By separating planning from implementation and leveraging Claude Code's custom commands, you maintain control while maximizing productivity.\n\n### Key Takeaways\n\n1. **Structure enables creativity** - Clear specs let Claude focus on quality implementation\n2. **Commands enforce discipline** - Slash commands guide the workflow naturally\n3. **Documentation is automation** - Well-written specs reduce ambiguity\n4. **Progress tracking builds confidence** - Always know where you are\n\n### Next Steps\n\n1. Install the commands in your project\n2. Create your first spec with `/spec:new`\n3. Follow the workflow for one complete feature\n4. Refine templates based on your needs\n5. Share with your team\n\n---\n\n*Happy spec-driven development with Claude Code!*","funding_links":[],"categories":["Custom Commands \u0026 Frameworks","🧠 Workflow Systems \u0026 Spec-Driven Development"],"sub_categories":[],"project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fpapaoloba%2Fspec-based-claude-code","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fpapaoloba%2Fspec-based-claude-code","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fpapaoloba%2Fspec-based-claude-code/lists"}