diff --git a/.claude/commands/dev/incremental-feature-build.md b/.claude/commands/dev/incremental-feature-build.md new file mode 100644 index 0000000..cec7bbe --- /dev/null +++ b/.claude/commands/dev/incremental-feature-build.md @@ -0,0 +1,446 @@ +# Incremental Feature Build Command + +Systematic approach for building complex features incrementally, preventing premature completion and ensuring comprehensive functionality through structured feature tracking. + +## Instructions + +Build a feature incrementally using the structured approach for: **$ARGUMENTS** + +This command implements best practices for long-running agent tasks, preventing the tendency to one-shot applications or prematurely consider projects complete. + +> **Note:** `$ARGUMENTS` is automatically replaced with the text following the command invocation. +> Example: `/dev:incremental-feature-build user authentication system` sets `$ARGUMENTS` to "user authentication system" + +--- + +## Phase 1: Feature Requirements Expansion + +### 1.1 Create Feature Tracking Directory + +```bash +# Create tracking directory with error handling +mkdir -p .feature-tracking || { echo "ERROR: Cannot create .feature-tracking directory. Check permissions."; exit 1; } +``` + +If directory creation fails, verify: +- You have write permissions in the current directory +- Sufficient disk space is available +- No file named `.feature-tracking` already exists + +### 1.2 Generate Comprehensive Feature List + +Analyze the user's request and expand it into a comprehensive list of granular features. Each feature should be a discrete, testable unit of functionality. + +**Create file: `.feature-tracking/features.json`** + +```json +{ + "project": "$ARGUMENTS", + "created": "YYYY-MM-DD", + "version": "1.0.0", + "summary": { + "total": 0, + "passing": 0, + "failing": 0 + }, + "features": [] +} +``` + +### 1.3 Feature Schema + +Each feature MUST follow this exact JSON schema: + +```json +{ + "id": "FEAT-001", + "category": "functional|ui|integration|performance|security|accessibility", + "priority": "critical|high|medium|low", + "description": "Clear, actionable description of the feature", + "steps": [ + "Step 1: Specific action to verify", + "Step 2: Expected behavior check", + "Step 3: Edge case validation" + ], + "dependencies": ["FEAT-000"], + "passes": false, + "implementedAt": null, + "commitHash": null +} +``` + +> **Note:** This command uses a simple boolean `passes` field since features are implemented sequentially. +> The parallel command (`/dev:parallel-feature-build`) uses a multi-state `status` field to track +> concurrent work: `pending`, `in_progress`, `passed`, `blocked`. + +### 1.4 Feature Categories + +Generate features across ALL relevant categories: + +| Category | Description | Examples | +|----------|-------------|----------| +| `functional` | Core business logic | User can submit form, data saves correctly | +| `ui` | User interface elements | Button displays, modal opens, responsive layout | +| `integration` | System connections | API calls work, database syncs, auth flows | +| `performance` | Speed and efficiency | Page loads under 3s, lazy loading works | +| `security` | Protection measures | Input sanitized, auth required, CSRF protection | +| `accessibility` | Inclusive design | Screen reader support, keyboard navigation | + +### 1.5 Feature Generation Guidelines + +When expanding the user's request: + +1. **Use Hierarchical Organization**: Group features into epics/modules for manageability + - Small projects: 10-30 features + - Medium projects: 30-60 features + - Large projects: 60-100 features (consider using `/dev:parallel-feature-build` instead) +2. **Be Specific**: Each feature should be independently verifiable +3. **Include Edge Cases**: Error states, empty states, boundary conditions +4. **Cover All Paths**: Happy path AND unhappy paths +5. **Think Like a User**: What would they expect at each step? + +**Feature Grouping Example:** +```json +{ + "epics": [ + { + "id": "EPIC-01", + "name": "User Authentication", + "features": ["FEAT-001", "FEAT-002", "FEAT-003"] + } + ] +} +``` + +--- + +## Phase 2: Initialize Progress Tracking + +### 2.1 Create Progress File + +**Create file: `.feature-tracking/PROGRESS.md`** + +```markdown +# Feature Implementation Progress + +## Project: $ARGUMENTS +## Started: YYYY-MM-DD + +--- + +## Current Status + +- **Features Total**: X +- **Implemented**: 0 +- **Remaining**: X + +--- + +## Session Log + +### Session 1 - YYYY-MM-DD + +**Focus**: Initial setup and first features + +**Completed**: +- (none yet) + +**Notes**: +- (session notes here) + +**Commit**: (hash when committed) + +--- + +## Implementation Order + +Based on dependencies, implement in this order: + +1. [ ] FEAT-001 - Description +2. [ ] FEAT-002 - Description +... + +--- + +## Blocked/Issues + +(Track any blockers here) +``` + +### 2.2 Git Initialization Check + +Ensure git is initialized and create initial tracking commit: + +```bash +git add .feature-tracking/ +git commit -m "feat: initialize feature tracking for $ARGUMENTS + +- Created features.json with X features to implement +- All features marked as failing (passes: false) +- Created progress tracking file" +``` + +--- + +## Phase 3: Incremental Implementation + +### CRITICAL RULES + +**You MUST follow these rules without exception:** + +1. **ONE FEATURE AT A TIME**: Never work on multiple features simultaneously +2. **NO TEST REMOVAL**: It is **UNACCEPTABLE** to remove or edit features from features.json because this could lead to missing or buggy functionality +3. **ONLY CHANGE STATUS**: The only modification allowed to features.json is changing `passes` from `false` to `true` and updating `implementedAt` and `commitHash` +4. **COMMIT AFTER EACH**: Create a git commit after each feature is implemented +5. **CLEAN STATE**: Each commit must leave the codebase in a working state + +### 3.1 Feature Implementation Loop + +For each feature, follow this exact workflow: + +#### Step A: Select Next Feature + +1. Read `.feature-tracking/features.json` +2. Find the first feature where `passes: false` +3. Check dependencies are satisfied (all dependent features pass) +4. Announce: "Now implementing FEAT-XXX: [description]" + +#### Step B: Implement Feature + +1. Write the necessary code +2. Ensure existing functionality still works +3. Test the specific feature manually or with tests +4. Verify all steps in the feature definition + +#### Step C: Update Tracking (JSON Only) + +Edit `.feature-tracking/features.json`: +- Change `"passes": false` to `"passes": true` +- Set `"implementedAt": "YYYY-MM-DD HH:MM"` +- Update summary counts + +```json +{ + "id": "FEAT-001", + "passes": true, + "implementedAt": "2024-01-15 14:30", + "commitHash": "(to be filled)" +} +``` + +#### Step D: Commit Progress + +```bash +git add . +git commit -m "feat(FEAT-XXX): [brief description] + +Implemented: [feature description] + +Verification: +- [step 1 verified] +- [step 2 verified] +- [step 3 verified] + +Progress: X/Y features complete" +``` + +#### Step E: Update Progress File + +Add to `.feature-tracking/PROGRESS.md`: + +```markdown +### FEAT-XXX - [Description] +- **Status**: PASSED +- **Implemented**: YYYY-MM-DD HH:MM +- **Commit**: [hash] +- **Notes**: [any implementation notes] +``` + +#### Step F: Update Commit Hash + +Edit features.json to add the commit hash from Step D. + +### 3.2 Continue Until Complete + +Repeat the implementation loop until ALL features show `passes: true`. + +--- + +## Phase 4: Recovery Protocols + +### 4.1 If Implementation Fails + +If a feature cannot be implemented correctly: + +1. **DO NOT** mark it as passing +2. **DO NOT** remove the feature +3. **DO** use git to revert changes: `git restore [files]` +4. **DO** document the blocker in PROGRESS.md +5. **DO** move to the next non-blocked feature + +### 4.2 If Code Breaks + +If implementing a feature breaks existing functionality: + +1. Run `git diff` to see changes +2. Run `git stash` to save work +3. Verify baseline still works +4. Run `git stash pop` and fix carefully +5. Or `git restore .` to fully reset working directory + +### 4.3 Revert Bad Commits + +If a commit introduced bugs: + +```bash +git log --oneline -10 # Find the bad commit +git revert [hash] # Create revert commit +``` + +--- + +## Phase 5: Completion Verification + +### 5.1 Final Checklist + +Before declaring the project complete: + +```bash +# Generate completion report - count remaining incomplete features +cat .feature-tracking/features.json | jq '[.features[] | select(.passes == false)] | length' +# Must return 0 + +# Or list any incomplete features for review +cat .feature-tracking/features.json | jq '.features[] | select(.passes == false) | {id, description}' +``` + +**Must return 0** - all features must pass. + +### 5.2 Summary Generation + +Create final summary in PROGRESS.md: + +```markdown +## Project Complete + +- **Total Features**: X +- **All Passing**: Yes +- **Total Commits**: Y +- **Duration**: Z days/hours + +### Feature Breakdown by Category + +| Category | Count | Status | +|----------|-------|--------| +| functional | X | All Pass | +| ui | X | All Pass | +| integration | X | All Pass | +| ... | ... | ... | +``` + +### 5.3 Final Commit + +```bash +git add . +git commit -m "feat: complete $ARGUMENTS implementation + +All X features implemented and verified: +- functional: X/X passing +- ui: X/X passing +- integration: X/X passing +- [other categories] + +See .feature-tracking/features.json for full details" +``` + +--- + +## Example Feature Expansion + +For a request like "Build a todo app", expand to features like: + +```json +{ + "features": [ + { + "id": "FEAT-001", + "category": "ui", + "priority": "critical", + "description": "App displays main todo list container on page load", + "steps": [ + "Navigate to app URL", + "Verify todo container element exists", + "Check container is visible and centered" + ], + "dependencies": [], + "passes": false + }, + { + "id": "FEAT-002", + "category": "functional", + "priority": "critical", + "description": "User can add a new todo item", + "steps": [ + "Locate input field for new todo", + "Type 'Buy groceries' and press Enter", + "Verify new todo appears in list", + "Verify input field is cleared" + ], + "dependencies": ["FEAT-001"], + "passes": false + }, + { + "id": "FEAT-003", + "category": "functional", + "priority": "critical", + "description": "User can mark todo as complete", + "steps": [ + "Click checkbox next to existing todo", + "Verify checkbox shows checked state", + "Verify todo text shows strikethrough style" + ], + "dependencies": ["FEAT-002"], + "passes": false + } + ] +} +``` + +--- + +## Usage Examples + +### Start New Feature Build +``` +/dev:incremental-feature-build user authentication system with OAuth +``` + +### Resume Existing Build +``` +/dev:incremental-feature-build (continuing from features.json) +``` + +### View Progress +```bash +cat .feature-tracking/PROGRESS.md +cat .feature-tracking/features.json | jq '.summary' +``` + +--- + +## Key Principles + +1. **JSON Over Markdown**: Use JSON for feature tracking because models are less likely to inappropriately modify structured data +2. **Atomic Progress**: Each commit represents one verified feature +3. **Git as Safety Net**: Commit frequently to enable easy rollbacks +4. **No Shortcuts**: Every feature must be individually verified +5. **Clean States Only**: Never leave the codebase in a broken state + +--- + +## Related Commands + +- `/dev:code-review` - Review implemented code quality +- `/test:generate-test-cases` - Generate automated tests for features +- `/orchestration:status` - Check overall task progress +- `/dev:debug-error` - Debug failing features diff --git a/.claude/commands/dev/parallel-feature-build.md b/.claude/commands/dev/parallel-feature-build.md new file mode 100644 index 0000000..07a03cb --- /dev/null +++ b/.claude/commands/dev/parallel-feature-build.md @@ -0,0 +1,620 @@ +# Parallel Feature Build Command + +Orchestrated parallel implementation of complex features using multiple agents, with dependency-aware batching and synchronized progress tracking. + +## Instructions + +Build features in parallel using agent orchestration for: **$ARGUMENTS** + +This command extends the incremental approach with parallel execution capabilities, launching multiple agents to work on independent features simultaneously while maintaining strict tracking and clean merge protocols. + +> **Note:** `$ARGUMENTS` is automatically replaced with the text following the command invocation. +> Example: `/dev:parallel-feature-build e-commerce checkout` sets `$ARGUMENTS` to "e-commerce checkout" + +--- + +## Phase 1: Feature Requirements & Dependency Analysis + +### 1.1 Create Feature Tracking Directory + +```bash +# Create tracking directories with error handling +mkdir -p .feature-tracking/{agents,batches,merges} || { echo "ERROR: Cannot create directories. Check permissions."; exit 1; } +``` + +If directory creation fails, verify: +- You have write permissions in the current directory +- Sufficient disk space is available + +### 1.2 Generate Comprehensive Feature List + +Same as incremental approach - expand user request into granular features. + +**Create file: `.feature-tracking/features.json`** + +```json +{ + "project": "$ARGUMENTS", + "created": "YYYY-MM-DD", + "version": "1.0.0", + "mode": "parallel", + "summary": { + "total": 0, + "passing": 0, + "failing": 0, + "in_progress": 0 + }, + "agents": { + "max_parallel": 4, + "active": [] + }, + "features": [] +} +``` + +### 1.3 Enhanced Feature Schema for Parallel Execution + +```json +{ + "id": "FEAT-001", + "category": "functional|ui|integration|performance|security|accessibility", + "priority": "critical|high|medium|low", + "description": "Clear, actionable description", + "steps": ["Step 1", "Step 2", "Step 3"], + "dependencies": ["FEAT-000"], + "dependents": ["FEAT-002", "FEAT-003"], + "status": "pending|in_progress|passed|blocked", + "assignedAgent": null, + "branch": null, + "batch": null, + "implementedAt": null, + "mergedAt": null, + "commitHash": null +} +``` + +### 1.4 Build Dependency Graph + +**Create file: `.feature-tracking/dependency-graph.json`** + +```json +{ + "generated": "YYYY-MM-DD HH:MM", + "criticalPath": ["FEAT-001", "FEAT-005", "FEAT-012"], + "criticalPathLength": 3, + "batches": [ + { + "batch": 1, + "features": ["FEAT-001", "FEAT-002", "FEAT-003"], + "parallel": true, + "blockedBy": [] + }, + { + "batch": 2, + "features": ["FEAT-004", "FEAT-005"], + "parallel": true, + "blockedBy": [1] + } + ], + "isolatedFeatures": ["FEAT-010", "FEAT-011"], + "graph": { + "FEAT-001": { "in": [], "out": ["FEAT-004", "FEAT-005"] }, + "FEAT-002": { "in": [], "out": ["FEAT-006"] } + } +} +``` + +### 1.5 Dependency Analysis Rules + +1. **No Dependencies**: Can start immediately in Batch 1 +2. **Single Dependency**: Waits for that feature only +3. **Multiple Dependencies**: Waits for ALL dependencies +4. **Circular Detection**: FAIL if cycles found - must restructure + +#### Circular Dependency Detection + +Before proceeding, verify no cycles exist in the dependency graph: + +```bash +# Using jq to detect cycles (simplified check) +# This finds features that depend on features that depend back on them +cat .feature-tracking/features.json | jq ' + .features as $all | + [.features[] | + select(.dependencies[] as $dep | + $all[] | select(.id == $dep) | .dependencies[] == .id + ) + ] | if length > 0 then + "CIRCULAR DEPENDENCY DETECTED: \(.[].id)" + else + "No cycles detected" + end +' +``` + +**If cycles are detected:** +1. Identify the circular chain (A → B → A) +2. Break the cycle by splitting one feature into sub-features +3. Or merge dependent features into a single feature +4. Re-run dependency analysis + +--- + +## Phase 2: Parallel Execution Planning + +### 2.1 Calculate Optimal Batches + +Use topological sort to determine execution order: + +``` +Batch 1: All features with no dependencies (run in parallel) +Batch 2: Features depending only on Batch 1 (run in parallel after Batch 1) +Batch 3: Features depending on Batch 1 or 2 (run in parallel after Batch 2) +...continue until all features assigned +``` + +### 2.2 Agent Assignment Strategy + +**Create file: `.feature-tracking/agent-assignments.json`** + +```json +{ + "strategy": "round-robin|load-balanced|priority-based", + "maxAgents": 4, + "assignments": [ + { + "agentId": "agent-1", + "features": ["FEAT-001", "FEAT-004"], + "branch": "feature/agent-1-batch", + "status": "idle|working|waiting" + } + ] +} +``` + +### 2.3 Create Main Feature Branch + +Before launching agents, create the integration branch where all features will be merged: + +```bash +# Create and switch to the main feature branch +git checkout -b feature/$PROJECT_NAME-main + +# Push to establish remote tracking +git push -u origin feature/$PROJECT_NAME-main + +# Record in coordination files +echo "feature/$PROJECT_NAME-main" > .feature-tracking/main-branch.txt +``` + +**Important:** All agent branches will merge INTO this branch, not directly to main/master. + +### 2.4 Create Master Coordination Document + +**Create file: `.feature-tracking/COORDINATION.md`** + +```markdown +# Parallel Feature Build Coordination + +## Project: $ARGUMENTS +## Mode: Parallel Execution +## Max Agents: 4 + +--- + +## Execution Batches + +### Batch 1 (No Dependencies) - PARALLEL +| Feature | Agent | Branch | Status | +|---------|-------|--------|--------| +| FEAT-001 | agent-1 | feat/agent-1-b1 | pending | +| FEAT-002 | agent-2 | feat/agent-2-b1 | pending | +| FEAT-003 | agent-3 | feat/agent-3-b1 | pending | + +### Batch 2 (Depends on Batch 1) - PARALLEL after Batch 1 +| Feature | Agent | Branch | Status | +|---------|-------|--------|--------| + +--- + +## Merge Queue + +| Order | Feature | From Branch | Status | +|-------|---------|-------------|--------| + +--- + +## Active Agents + +| Agent ID | Current Feature | Branch | Started | +|----------|-----------------|--------|---------| +``` + +--- + +## Phase 3: Agent Orchestration + +### 3.1 Launch Parallel Agents + +For each feature in the current batch, use the Task tool to spawn an agent: + +```markdown +**Agent Instructions for FEAT-XXX:** + +You are implementing feature FEAT-XXX for project: $ARGUMENTS + +**Your Feature:** +- ID: FEAT-XXX +- Description: [description] +- Verification Steps: + 1. [step 1] + 2. [step 2] + 3. [step 3] + +**Your Branch:** feat/agent-X-FEAT-XXX + +**CRITICAL RULES:** +1. Work ONLY on your assigned feature +2. Create atomic, focused commits +3. Do NOT modify features.json directly +4. Write progress to: .feature-tracking/agents/agent-X-progress.md +5. When complete, update: .feature-tracking/agents/agent-X-status.json + +**Workflow:** +1. Create and checkout your branch: `git checkout -b feat/agent-X-FEAT-XXX` +2. Implement the feature +3. Test all verification steps +4. Commit with message: `feat(FEAT-XXX): [description]` +5. Update your status file to "completed" +6. Push branch: `git push origin feat/agent-X-FEAT-XXX` + +**Status File Format (.feature-tracking/agents/agent-X-status.json):** +```json +{ + "agentId": "agent-X", + "featureId": "FEAT-XXX", + "status": "completed", + "branch": "feat/agent-X-FEAT-XXX", + "commitHash": "[hash]", + "completedAt": "YYYY-MM-DD HH:MM", + "notes": "Any implementation notes" +} +``` + +Report back when complete. +``` + +### 3.2 Agent Progress Files + +Each agent writes to: `.feature-tracking/agents/agent-X-progress.md` + +```markdown +# Agent X Progress + +## Assigned Feature: FEAT-XXX +## Branch: feat/agent-X-FEAT-XXX + +### Implementation Log + +**[HH:MM]** Started implementation +- Created component structure +- Added basic functionality + +**[HH:MM]** Testing verification steps +- Step 1: PASS +- Step 2: PASS +- Step 3: PASS + +**[HH:MM]** Implementation complete +- Committed: [hash] +- Ready for merge +``` + +### 3.3 Monitor Agent Completion + +Poll agent status files until all agents in batch complete: + +```bash +# Check all agent statuses with polling interval +check_agents_complete() { + local all_complete=true + for f in .feature-tracking/agents/agent-*-status.json; do + if [ -f "$f" ]; then + status=$(cat "$f" | jq -r '.status') + if [ "$status" != "completed" ]; then + all_complete=false + echo "Agent $(basename $f): $status" + fi + else + all_complete=false + fi + done + $all_complete +} + +# Poll with 30-second intervals until all agents complete +while ! check_agents_complete; do + echo "Waiting for agents to complete..." + sleep 30 +done +echo "All agents complete!" +``` + +**Alternative: File watching** (if available) +```bash +# Use inotifywait for real-time monitoring (Linux) +inotifywait -m -e modify .feature-tracking/agents/*.json +``` + +--- + +## Phase 4: Merge Coordination + +### 4.1 Merge Order Protocol + +After all agents in a batch complete: + +1. **Sort by Feature ID** for deterministic merge order +2. **Merge sequentially** to main feature branch +3. **Verify after each merge** that codebase still works + +### 4.2 Merge Workflow + +```bash +# Read the main feature branch name (created in Phase 2.3) +MAIN_BRANCH=$(cat .feature-tracking/main-branch.txt) + +# For each completed feature branch +git checkout "$MAIN_BRANCH" +git merge --no-ff feat/agent-X-FEAT-XXX -m "merge(FEAT-XXX): [description] + +Implemented by: agent-X +Verification: All steps passed +Batch: X of Y" + +# Test that merge didn't break anything +[run tests or verification] + +# If merge conflicts: +# 1. Resolve conflicts +# 2. Run full test suite +# 3. Commit resolution +``` + +### 4.3 Update Master Tracking + +After successful merge, update `.feature-tracking/features.json` using file locking to prevent race conditions: + +```bash +# Acquire lock before updating shared tracking file +LOCKFILE=".feature-tracking/.features.lock" + +acquire_lock() { + while ! mkdir "$LOCKFILE" 2>/dev/null; do + echo "Waiting for lock..." + sleep 1 + done +} + +release_lock() { + rmdir "$LOCKFILE" +} + +# Usage +acquire_lock +# Update features.json here +release_lock +``` + +**Update the feature entry:** +```json +{ + "id": "FEAT-XXX", + "status": "passed", + "assignedAgent": "agent-X", + "branch": "feat/agent-X-FEAT-XXX", + "implementedAt": "YYYY-MM-DD HH:MM", + "mergedAt": "YYYY-MM-DD HH:MM", + "commitHash": "[merge-commit-hash]" +} +``` + +### 4.4 Conflict Resolution Protocol + +If merge conflicts occur: + +1. **Identify conflicting files** +2. **Analyze which agent's changes take precedence** +3. **Resolve favoring the more complete implementation** +4. **Document resolution** in merge commit message +5. **Re-verify affected features** + +--- + +## Phase 5: Batch Progression + +### 5.1 Batch Completion Check + +```bash +# Verify all features in batch are merged +cat .feature-tracking/features.json | jq '[.features[] | select(.batch == 1 and .status != "passed")] | length' +# Must return 0 +``` + +### 5.2 Advance to Next Batch + +1. Update COORDINATION.md with batch completion status +2. Identify next batch of features +3. Assign to agents (may reuse same agents) +4. Launch new parallel execution round + +### 5.3 Continue Until All Batches Complete + +``` +While batches remain: + 1. Launch agents for current batch (parallel) + 2. Wait for all agents to complete + 3. Merge all branches sequentially + 4. Verify merged codebase + 5. Advance to next batch +``` + +--- + +## Phase 6: Recovery & Error Handling + +### 6.1 Agent Failure Protocol + +If an agent fails to complete: + +1. **Check agent progress file** for last known state +2. **Salvage work if possible**: `git cherry-pick` good commits +3. **Reassign feature** to different agent or handle sequentially +4. **Do NOT block other agents** in same batch + +### 6.2 Merge Failure Protocol + +If merge cannot be resolved: + +1. **Abort merge**: `git merge --abort` +2. **Identify conflicting features** +3. **Re-implement one feature** to avoid conflict +4. **Or execute features sequentially** instead of parallel + +### 6.3 Rollback Batch + +If entire batch must be reverted: + +```bash +# Find commit before batch started +git log --oneline | grep "Batch X start" + +# Revert all batch commits +git revert [batch-commits] + +# Retry batch with adjusted approach +``` + +--- + +## Phase 7: Completion & Reporting + +### 7.1 Final Verification + +```bash +# All features must be passed +cat .feature-tracking/features.json | jq '[.features[] | select(.status != "passed")] | length' +# Must return 0 +``` + +### 7.2 Generate Performance Report + +**Create file: `.feature-tracking/PERFORMANCE-REPORT.md`** + +```markdown +# Parallel Execution Performance Report + +## Summary +- **Total Features**: X +- **Total Batches**: Y +- **Max Parallelism**: 4 agents +- **Total Duration**: Z hours + +## Batch Breakdown + +| Batch | Features | Duration | Parallelism | +|-------|----------|----------|-------------| +| 1 | 4 | 30min | 4x | +| 2 | 3 | 25min | 3x | +| 3 | 2 | 20min | 2x | + +## Efficiency Metrics + +- **Sequential Estimate**: X hours +- **Parallel Actual**: Y hours +- **Speedup Factor**: X/Y +- **Agent Utilization**: Z% + +## Merge Statistics + +- **Clean Merges**: X +- **Conflicts Resolved**: Y +- **Re-implementations**: Z +``` + +### 7.3 Final Commit + +```bash +git add . +git commit -m "feat: complete parallel build of $ARGUMENTS + +Execution Summary: +- Total features: X +- Batches: Y +- Max parallel agents: 4 +- Speedup: Zx over sequential + +All features verified and merged successfully. +See .feature-tracking/PERFORMANCE-REPORT.md for details" +``` + +--- + +## Usage Examples + +### Start Parallel Feature Build + +``` +/dev:parallel-feature-build e-commerce checkout system +``` + +### With Agent Limit + +``` +/dev:parallel-feature-build --agents 2 user dashboard +``` + +### Monitor Progress + +```bash +# View coordination status +cat .feature-tracking/COORDINATION.md + +# Check agent statuses +ls .feature-tracking/agents/ + +# View dependency graph +cat .feature-tracking/dependency-graph.json | jq '.batches' +``` + +--- + +## Comparison: Sequential vs Parallel + +| Aspect | Sequential | Parallel | +|--------|------------|----------| +| Speed | Slower | Faster (up to Nx) | +| Complexity | Simple | Complex coordination | +| Merge Risk | None | Potential conflicts | +| Best For | Small projects | Large feature sets | +| Agent Count | 1 | 2-4+ | + +--- + +## Key Principles + +1. **Independence First**: Only parallelize truly independent features +2. **Conservative Batching**: When in doubt, add to later batch +3. **Merge Early, Merge Often**: Don't let branches diverge too long +4. **Agent Isolation**: Each agent owns their branch exclusively +5. **Deterministic Merge Order**: Same order every time for reproducibility +6. **Fail Safe**: Any failure falls back to sequential execution + +--- + +## Related Commands + +- `/dev:incremental-feature-build` - Sequential single-agent approach +- `/orchestration:start` - General task orchestration +- `/orchestration:status` - Check orchestration progress +- `/dev:code-review` - Review merged code quality diff --git a/.feature-tracking/examples/CHECKLIST-incremental-feature-cmd.md b/.feature-tracking/examples/CHECKLIST-incremental-feature-cmd.md new file mode 100644 index 0000000..3c37626 --- /dev/null +++ b/.feature-tracking/examples/CHECKLIST-incremental-feature-cmd.md @@ -0,0 +1,43 @@ +# Incremental Feature Build Command - Implementation Checklist + +## Overview +Creating a comprehensive Claude Code command based on best practices for long-running agents that prevents premature completion and ensures incremental progress. + +## Tasks + +- [x] Review existing command structure and patterns +- [x] Create this checklist +- [x] Create the command file at `.claude/commands/dev/incremental-feature-build.md` +- [x] Include feature list initialization phase +- [x] Include JSON-based feature tracking +- [x] Include incremental progress workflow +- [x] Include git commit and progress tracking +- [x] Include recovery mechanisms +- [x] Commit changes + +## Key Concepts to Include (from best practices) + +1. **Feature List Generation** + - Comprehensive feature requirements file + - Features marked as "failing" initially + - JSON format for tracking (less likely to be modified) + +2. **Incremental Progress** + - Work on one feature at a time + - Strict instructions against removing/editing tests + - Clear outline of full functionality + +3. **Environment Cleanliness** + - Commit progress with descriptive messages + - Write progress summaries + - Use git for reverting bad changes + - Recovery of working states + +## Command Structure + +- Title and description +- Usage examples +- Step-by-step instructions +- JSON schema for feature tracking +- Git workflow integration +- Progress file management diff --git a/.feature-tracking/examples/CHECKLIST-parallel-feature-cmd.md b/.feature-tracking/examples/CHECKLIST-parallel-feature-cmd.md new file mode 100644 index 0000000..7eadf20 --- /dev/null +++ b/.feature-tracking/examples/CHECKLIST-parallel-feature-cmd.md @@ -0,0 +1,37 @@ +# Parallel Feature Build Command - Implementation Checklist + +## Overview +Creating a variation of the incremental feature build command that leverages agents for parallel implementation of independent features. + +## Tasks + +- [x] Create this checklist +- [x] Create the command file at `.claude/commands/dev/parallel-feature-build.md` +- [x] Include dependency graph generation +- [x] Include parallel batch identification +- [x] Include agent orchestration workflow +- [x] Include merge/conflict resolution protocols +- [x] Include synchronized progress tracking +- [x] Commit changes + +## Key Differences from Sequential Version + +1. **Dependency Graph Analysis** + - Build directed acyclic graph (DAG) of feature dependencies + - Identify independent feature batches + - Calculate critical path + +2. **Parallel Execution** + - Launch multiple agents for independent features + - Each agent works on isolated branch + - Coordinate via shared tracking files + +3. **Merge Strategy** + - Sequential merge of completed features + - Conflict detection and resolution + - Verification after each merge + +4. **Synchronized Tracking** + - Lock-based updates to features.json + - Agent-specific progress files + - Master coordination document