Mike Swanson
75ce1c2fd5
Enhanced code review and frontend validation with intelligent triggers: Code Review Agent Enhancement: - Added Sequential Thinking MCP integration for complex issues - Triggers on 2+ rejections or 3+ critical issues - New escalation format with root cause analysis - Comprehensive solution strategies with trade-off evaluation - Educational feedback to break rejection cycles - Files: .claude/agents/code-review.md (+308 lines) - Docs: CODE_REVIEW_ST_ENHANCEMENT.md, CODE_REVIEW_ST_TESTING.md Frontend Design Skill Enhancement: - Automatic invocation for ANY UI change - Comprehensive validation checklist (200+ checkpoints) - 8 validation categories (visual, interactive, responsive, a11y, etc.) - 3 validation levels (quick, standard, comprehensive) - Integration with code review workflow - Files: .claude/skills/frontend-design/SKILL.md (+120 lines) - Docs: UI_VALIDATION_CHECKLIST.md (462 lines), AUTOMATIC_VALIDATION_ENHANCEMENT.md (587 lines) Settings Optimization: - Repaired .claude/settings.local.json (fixed m365 pattern) - Reduced permissions from 49 to 33 (33% reduction) - Removed duplicates, sorted alphabetically - Created SETTINGS_PERMISSIONS.md documentation Checkpoint Command Enhancement: - Dual checkpoint system (git + database) - Saves session context to API for cross-machine recall - Includes git metadata in database context - Files: .claude/commands/checkpoint.md (+139 lines) Decision Rationale: - Sequential Thinking MCP breaks rejection cycles by identifying root causes - Automatic frontend validation catches UI issues before code review - Dual checkpoints enable complete project memory across machines - Settings optimization improves maintainability Total: 1,200+ lines of documentation and enhancements Co-Authored-By: Claude Sonnet 4.5 <noreply@anthropic.com>
563 lines
20 KiB
Plaintext
563 lines
20 KiB
Plaintext
<project_specification>
|
|
<project_name>Auto-Claude-Plus</project_name>
|
|
|
|
<overview>
|
|
Auto-Claude-Plus is an autonomous multi-agent coding framework that plans, builds, and validates software with minimal human intervention. It combines Auto-Claude's spec pipeline and multi-agent architecture, Ralph Wiggum's iterative persistence loop for difficult tasks, and the frontend-design skill's philosophy for producing distinctive, polished UIs. The system features a three-tier memory system (project, global, infrastructure), a Re-Spec capability for refining project vision mid-stream, and intelligent error recovery that continues work on non-blocking tasks while flagging issues for review.
|
|
</overview>
|
|
|
|
<technology_stack>
|
|
<frontend>
|
|
<framework>Electron + React 18 + TypeScript</framework>
|
|
<styling>Tailwind CSS + Custom Design System</styling>
|
|
<state_management>Zustand (lightweight, scalable)</state_management>
|
|
<ui_components>Radix UI primitives (accessible, unstyled)</ui_components>
|
|
<bundler>Vite</bundler>
|
|
</frontend>
|
|
<backend>
|
|
<runtime>Python 3.12+</runtime>
|
|
<agent_sdk>Claude Agent SDK</agent_sdk>
|
|
<database>SQLite (portable, Docker-friendly)</database>
|
|
<orm>SQLAlchemy</orm>
|
|
<api>FastAPI (for internal IPC and potential future REST API)</api>
|
|
</backend>
|
|
<communication>
|
|
<api>IPC between Electron and Python backend</api>
|
|
<realtime>WebSocket for agent terminal streaming</realtime>
|
|
</communication>
|
|
<deployment>
|
|
<containerization>Docker + Docker Compose</containerization>
|
|
<platforms>Windows, macOS, Linux</platforms>
|
|
</deployment>
|
|
</technology_stack>
|
|
|
|
<prerequisites>
|
|
<environment_setup>
|
|
- Python 3.12+ with uv package manager
|
|
- Node.js 20+ with npm
|
|
- Git
|
|
- Docker (for containerized deployment)
|
|
- Claude Pro/Max subscription
|
|
- Claude Code CLI: npm install -g @anthropic-ai/claude-code
|
|
</environment_setup>
|
|
</prerequisites>
|
|
|
|
<feature_count>165</feature_count>
|
|
|
|
<security_and_access_control>
|
|
<user_roles>
|
|
<role name="owner">
|
|
<permissions>
|
|
- Full access to all features
|
|
- Manage global and infrastructure memory
|
|
- Configure deployment targets
|
|
- Access all projects
|
|
</permissions>
|
|
<protected_routes>
|
|
- All routes accessible
|
|
</protected_routes>
|
|
</role>
|
|
</user_roles>
|
|
<authentication>
|
|
<method>Local only (no auth required for single-user internal use)</method>
|
|
<session_timeout>none</session_timeout>
|
|
<password_requirements>N/A</password_requirements>
|
|
</authentication>
|
|
<sensitive_operations>
|
|
- Infrastructure memory contains server access info (stored locally only)
|
|
- Git push operations require confirmation
|
|
- Delete project requires confirmation
|
|
</sensitive_operations>
|
|
</security_and_access_control>
|
|
|
|
<core_features>
|
|
<project_management>
|
|
- Create new project with spec interview
|
|
- Open/browse existing projects
|
|
- Adopt existing codebase (import and run through spec interview)
|
|
- Project dashboard with status overview
|
|
- Project settings and configuration
|
|
- Delete project with confirmation
|
|
</project_management>
|
|
|
|
<spec_system>
|
|
- Spec interview/creation wizard
|
|
- Re-Spec feature (re-interview with existing context)
|
|
- Automatic milestone detection for large projects
|
|
- Re-Spec offered at milestones (MVP, phase completion)
|
|
- Spec validation and completeness checking
|
|
- Spec history and version tracking
|
|
- Existing work re-evaluation against new spec
|
|
</spec_system>
|
|
|
|
<kanban_board>
|
|
- Visual task board with columns (Backlog, In Progress, QA, Done, Blocked)
|
|
- Task cards with status, priority, agent assignment
|
|
- Drag-and-drop task movement
|
|
- Task filtering by status, agent, phase
|
|
- Task details panel with full context
|
|
- Phase grouping and visualization
|
|
- Dependency visualization
|
|
</kanban_board>
|
|
|
|
<agent_system>
|
|
- Planner Agent (creates implementation plan)
|
|
- Coder Agent (implements subtasks)
|
|
- QA Reviewer Agent (validates acceptance criteria)
|
|
- QA Fixer Agent (resolves issues)
|
|
- Parallel agent execution (up to 12 terminals)
|
|
- Agent terminals UI with live output streaming
|
|
- Agent status indicators (idle, working, stuck, complete)
|
|
- Subagent spawning for complex subtasks
|
|
</agent_system>
|
|
|
|
<iterative_loop>
|
|
- Single-pass validation (default mode)
|
|
- Auto-escalation for failed tasks
|
|
- Auto-escalation for detected complexity
|
|
- Manual retry trigger
|
|
- Ralph Wiggum mode (persistent iteration until completion)
|
|
- Completion promise detection
|
|
- Max iterations safety limit
|
|
- Task flagging for multi-iteration mode
|
|
</iterative_loop>
|
|
|
|
<memory_system>
|
|
<project_memory>
|
|
- Session insights (what worked, what failed)
|
|
- Codebase map (what files do what)
|
|
- Patterns discovered (coding conventions)
|
|
- Gotchas (pitfalls to avoid)
|
|
- Build progress history
|
|
</project_memory>
|
|
<global_memory>
|
|
- User preferences (coding style, UI tastes)
|
|
- Cross-project patterns
|
|
- Common solutions ("last time I built auth...")
|
|
- Technology preferences learned over time
|
|
</global_memory>
|
|
<infrastructure_memory>
|
|
- Dev server locations and access methods
|
|
- Docker server configurations
|
|
- Deployment targets (local, cloud)
|
|
- Database server connections
|
|
- API key storage locations
|
|
- Environment-specific configurations
|
|
</infrastructure_memory>
|
|
<memory_management>
|
|
- Memory items tagged by project or global
|
|
- Memory search and retrieval
|
|
- Memory editing and cleanup
|
|
- Memory import/export
|
|
</memory_management>
|
|
</memory_system>
|
|
|
|
<frontend_design_integration>
|
|
- Design philosophy applied to all frontend projects
|
|
- MVP mode (functional drafts acceptable)
|
|
- Finished mode (frontend-design criteria required)
|
|
- Opt-out via spec configuration
|
|
- Design thinking framework (purpose, tone, constraints)
|
|
- Typography, color, motion, spatial composition guidelines
|
|
- Anti-pattern detection (generic AI slop)
|
|
</frontend_design_integration>
|
|
|
|
<qa_and_testing>
|
|
- Unit test generation for each component
|
|
- E2E test generation at phase completion
|
|
- Test execution against specified infrastructure
|
|
- Test reporting with pass/fail details
|
|
- Coverage tracking
|
|
- QA loop (review -> fix -> re-review)
|
|
- Infrastructure-aware testing (dev servers, Docker)
|
|
</qa_and_testing>
|
|
|
|
<git_integration>
|
|
- Git worktree isolation for safe development
|
|
- Auto-commit per subtask completion
|
|
- Auto-push on project/phase completion
|
|
- Branch management (feature branches per spec)
|
|
- Commit message generation
|
|
- Git history visualization
|
|
- Merge conflict detection
|
|
</git_integration>
|
|
|
|
<progress_and_visibility>
|
|
- Real-time notifications (task complete, fail, blocked)
|
|
- Estimated time remaining per task/phase
|
|
- Changelog generation from completed tasks
|
|
- Build history and statistics
|
|
- Agent activity timeline
|
|
- Phase progress indicators
|
|
- Overall project completion percentage
|
|
</progress_and_visibility>
|
|
|
|
<error_handling>
|
|
- Autonomous error recovery attempts
|
|
- Task flagging for human review
|
|
- Non-blocking continuation (work on other tasks)
|
|
- Error categorization (recoverable, blocking, needs review)
|
|
- Error history and patterns
|
|
- Re-Spec suggestion for persistent issues
|
|
</error_handling>
|
|
|
|
<deployment>
|
|
- Docker containerization
|
|
- Docker Compose configuration
|
|
- Multi-machine access support
|
|
- Infrastructure memory integration
|
|
- Deployment pipeline generation
|
|
- Environment configuration management
|
|
</deployment>
|
|
|
|
<ui_ux>
|
|
- Polished, distinctive interface (non-generic)
|
|
- Dark/light theme support
|
|
- Responsive layout (desktop-first, but usable on tablet)
|
|
- Keyboard shortcuts for power users
|
|
- Settings/preferences panel
|
|
- Onboarding wizard for first-time setup
|
|
</ui_ux>
|
|
</core_features>
|
|
|
|
<database_schema>
|
|
<tables>
|
|
<projects>
|
|
- id, name, description, path, status, created_at, updated_at
|
|
- complexity (simple, medium, complex)
|
|
- current_phase, total_phases
|
|
- spec_version, last_respec_at
|
|
</projects>
|
|
<specs>
|
|
- id, project_id, version, content, created_at
|
|
- is_active, parent_spec_id (for Re-Spec tracking)
|
|
</specs>
|
|
<tasks>
|
|
- id, project_id, spec_id, phase_id, name, description
|
|
- status (backlog, in_progress, qa, done, blocked)
|
|
- priority, estimated_time, actual_time
|
|
- agent_type, iteration_count, flagged_for_review
|
|
- depends_on (JSON array of task IDs)
|
|
</tasks>
|
|
<phases>
|
|
- id, project_id, name, order, status
|
|
- depends_on (JSON array of phase IDs)
|
|
- milestone_type (none, mvp, release)
|
|
</phases>
|
|
<agent_sessions>
|
|
- id, project_id, task_id, agent_type
|
|
- started_at, ended_at, status, output_log
|
|
- iterations, completion_promise
|
|
</agent_sessions>
|
|
<memory_project>
|
|
- id, project_id, type (insight, pattern, gotcha, codebase_map)
|
|
- content, metadata, created_at
|
|
</memory_project>
|
|
<memory_global>
|
|
- id, type (preference, pattern, solution)
|
|
- content, metadata, created_at, usage_count
|
|
</memory_global>
|
|
<memory_infrastructure>
|
|
- id, name, type (server, docker, database, deployment)
|
|
- config (JSON), projects (JSON array of project IDs or null for all)
|
|
- created_at, updated_at
|
|
</memory_infrastructure>
|
|
<notifications>
|
|
- id, project_id, type, message, read, created_at
|
|
</notifications>
|
|
<settings>
|
|
- id, key, value, updated_at
|
|
</settings>
|
|
</tables>
|
|
</database_schema>
|
|
|
|
<api_endpoints_summary>
|
|
<projects>
|
|
- GET /api/projects - List all projects
|
|
- POST /api/projects - Create new project
|
|
- GET /api/projects/:id - Get project details
|
|
- PUT /api/projects/:id - Update project
|
|
- DELETE /api/projects/:id - Delete project
|
|
- POST /api/projects/:id/adopt - Adopt existing codebase
|
|
</projects>
|
|
<specs>
|
|
- GET /api/projects/:id/spec - Get current spec
|
|
- POST /api/projects/:id/spec - Create/update spec
|
|
- POST /api/projects/:id/respec - Trigger Re-Spec
|
|
- GET /api/projects/:id/spec/history - Get spec versions
|
|
</specs>
|
|
<tasks>
|
|
- GET /api/projects/:id/tasks - List tasks (with filters)
|
|
- POST /api/projects/:id/tasks - Create task
|
|
- PUT /api/tasks/:id - Update task
|
|
- PUT /api/tasks/:id/status - Update task status
|
|
- POST /api/tasks/:id/retry - Retry task
|
|
- POST /api/tasks/:id/flag - Flag for review
|
|
</tasks>
|
|
<agents>
|
|
- POST /api/agents/start - Start agent session
|
|
- POST /api/agents/:id/stop - Stop agent session
|
|
- GET /api/agents/active - List active agents
|
|
- WS /api/agents/:id/stream - Stream agent output
|
|
</agents>
|
|
<memory>
|
|
- GET /api/memory/project/:id - Get project memory
|
|
- POST /api/memory/project/:id - Add project memory
|
|
- GET /api/memory/global - Get global memory
|
|
- POST /api/memory/global - Add global memory
|
|
- GET /api/memory/infrastructure - Get infrastructure memory
|
|
- POST /api/memory/infrastructure - Add infrastructure config
|
|
- PUT /api/memory/infrastructure/:id - Update infrastructure config
|
|
</memory>
|
|
<notifications>
|
|
- GET /api/notifications - Get notifications
|
|
- PUT /api/notifications/:id/read - Mark as read
|
|
- DELETE /api/notifications/:id - Delete notification
|
|
</notifications>
|
|
<settings>
|
|
- GET /api/settings - Get all settings
|
|
- PUT /api/settings - Update settings
|
|
</settings>
|
|
</api_endpoints_summary>
|
|
|
|
<ui_layout>
|
|
<main_structure>
|
|
- Left sidebar: Project list, navigation, quick actions
|
|
- Main content area: Context-dependent (kanban, terminals, settings, etc.)
|
|
- Right panel (collapsible): Task details, agent output, memory viewer
|
|
- Top bar: Project name, phase indicator, notifications, settings
|
|
- Bottom bar: Agent status summary, progress indicator
|
|
</main_structure>
|
|
<key_screens>
|
|
- Dashboard: Project overview, recent activity, quick stats
|
|
- Kanban Board: Visual task management
|
|
- Agent Terminals: Live agent output with multiple terminals
|
|
- Spec Editor: View/edit current spec, trigger Re-Spec
|
|
- Memory Manager: Browse/edit all memory types
|
|
- Infrastructure Config: Manage servers, Docker, deployment targets
|
|
- Settings: App preferences, theme, shortcuts
|
|
- Project Creation Wizard: New project setup flow
|
|
- Re-Spec Interview: Guided re-interview with context
|
|
</key_screens>
|
|
</ui_layout>
|
|
|
|
<design_system>
|
|
<philosophy>
|
|
- Distinctive, professional interface (not generic AI slop)
|
|
- Clean but not sterile - subtle personality
|
|
- Information-dense but not overwhelming
|
|
- Emphasize clarity and readability for long coding sessions
|
|
</philosophy>
|
|
<color_palette>
|
|
- Primary: Deep blue (#1a365d) - trust, focus
|
|
- Accent: Vibrant teal (#0d9488) - action, success
|
|
- Warning: Amber (#f59e0b) - attention
|
|
- Error: Rose (#e11d48) - problems
|
|
- Background: Slate gray tones (dark mode default)
|
|
- Text: High contrast for readability
|
|
</color_palette>
|
|
<typography>
|
|
- Headings: Inter or similar geometric sans-serif
|
|
- Body: System font stack for performance
|
|
- Code: JetBrains Mono or Fira Code (monospace with ligatures)
|
|
</typography>
|
|
<motion>
|
|
- Subtle transitions (150-300ms)
|
|
- Meaningful animations (task completion, agent status changes)
|
|
- No gratuitous motion - respect user focus
|
|
</motion>
|
|
</design_system>
|
|
|
|
<implementation_steps>
|
|
<step number="1">
|
|
<title>Foundation & Infrastructure</title>
|
|
<tasks>
|
|
- Set up Electron + React + TypeScript project structure
|
|
- Configure Vite bundler and Tailwind CSS
|
|
- Set up Python backend with FastAPI
|
|
- Configure SQLite database with SQLAlchemy
|
|
- Implement IPC bridge between Electron and Python
|
|
- Create Docker configuration
|
|
</tasks>
|
|
</step>
|
|
<step number="2">
|
|
<title>Core Data Layer</title>
|
|
<tasks>
|
|
- Implement database schema and migrations
|
|
- Create Python models for all entities
|
|
- Build CRUD API endpoints for projects, specs, tasks
|
|
- Implement basic memory storage (all three types)
|
|
- Set up WebSocket for real-time updates
|
|
</tasks>
|
|
</step>
|
|
<step number="3">
|
|
<title>Spec System</title>
|
|
<tasks>
|
|
- Build spec interview wizard UI
|
|
- Implement spec creation flow
|
|
- Build Re-Spec interview with existing context
|
|
- Implement spec versioning and history
|
|
- Add milestone detection logic
|
|
- Build spec validation
|
|
</tasks>
|
|
</step>
|
|
<step number="4">
|
|
<title>Agent System</title>
|
|
<tasks>
|
|
- Integrate Claude Agent SDK
|
|
- Implement Planner Agent
|
|
- Implement Coder Agent
|
|
- Implement QA Reviewer Agent
|
|
- Implement QA Fixer Agent
|
|
- Build agent session management
|
|
- Implement parallel agent execution
|
|
</tasks>
|
|
</step>
|
|
<step number="5">
|
|
<title>Iterative Loop Integration</title>
|
|
<tasks>
|
|
- Implement single-pass validation
|
|
- Build auto-escalation detection
|
|
- Implement Ralph Wiggum mode
|
|
- Add completion promise detection
|
|
- Build task flagging system
|
|
- Implement retry logic
|
|
</tasks>
|
|
</step>
|
|
<step number="6">
|
|
<title>Kanban Board & Task Management</title>
|
|
<tasks>
|
|
- Build kanban board UI with drag-and-drop
|
|
- Implement task cards with status
|
|
- Add filtering and sorting
|
|
- Build task details panel
|
|
- Implement phase grouping
|
|
- Add dependency visualization
|
|
</tasks>
|
|
</step>
|
|
<step number="7">
|
|
<title>Agent Terminals UI</title>
|
|
<tasks>
|
|
- Build terminal component with live streaming
|
|
- Implement multi-terminal layout
|
|
- Add agent status indicators
|
|
- Build terminal history/scrollback
|
|
- Implement terminal controls (pause, clear, copy)
|
|
</tasks>
|
|
</step>
|
|
<step number="8">
|
|
<title>Memory System</title>
|
|
<tasks>
|
|
- Build memory manager UI
|
|
- Implement project memory CRUD
|
|
- Implement global memory with cross-project access
|
|
- Build infrastructure memory management
|
|
- Add memory search and tagging
|
|
- Implement memory learning/inference
|
|
</tasks>
|
|
</step>
|
|
<step number="9">
|
|
<title>Git Integration</title>
|
|
<tasks>
|
|
- Implement git worktree management
|
|
- Build auto-commit logic
|
|
- Implement auto-push on completion
|
|
- Add branch management UI
|
|
- Build commit history visualization
|
|
</tasks>
|
|
</step>
|
|
<step number="10">
|
|
<title>QA & Testing System</title>
|
|
<tasks>
|
|
- Implement unit test generation
|
|
- Build E2E test generation
|
|
- Integrate with infrastructure memory for test targets
|
|
- Build test execution and reporting
|
|
- Implement QA loop (review -> fix -> re-review)
|
|
</tasks>
|
|
</step>
|
|
<step number="11">
|
|
<title>Frontend Design Integration</title>
|
|
<tasks>
|
|
- Integrate design philosophy guidelines
|
|
- Build MVP vs Finished mode detection
|
|
- Implement design validation checks
|
|
- Add anti-pattern detection
|
|
</tasks>
|
|
</step>
|
|
<step number="12">
|
|
<title>Progress & Notifications</title>
|
|
<tasks>
|
|
- Build notification system
|
|
- Implement time estimation
|
|
- Build changelog generation
|
|
- Add progress indicators throughout UI
|
|
- Build activity timeline
|
|
</tasks>
|
|
</step>
|
|
<step number="13">
|
|
<title>Error Handling & Recovery</title>
|
|
<tasks>
|
|
- Implement autonomous recovery logic
|
|
- Build task flagging for review
|
|
- Implement non-blocking continuation
|
|
- Add error categorization
|
|
- Build Re-Spec suggestion for persistent issues
|
|
</tasks>
|
|
</step>
|
|
<step number="14">
|
|
<title>Polish & Design System</title>
|
|
<tasks>
|
|
- Apply design system throughout
|
|
- Implement dark/light themes
|
|
- Add keyboard shortcuts
|
|
- Build onboarding wizard
|
|
- Refine animations and transitions
|
|
- Ensure responsive layout
|
|
</tasks>
|
|
</step>
|
|
<step number="15">
|
|
<title>Deployment & Documentation</title>
|
|
<tasks>
|
|
- Finalize Docker configuration
|
|
- Build deployment pipeline support
|
|
- Create user documentation
|
|
- Add in-app help system
|
|
- Final testing and bug fixes
|
|
</tasks>
|
|
</step>
|
|
</implementation_steps>
|
|
|
|
<success_criteria>
|
|
<functionality>
|
|
- Can create a new project through spec interview
|
|
- Can adopt existing codebase and run through spec
|
|
- Re-Spec works with full context awareness
|
|
- Agents execute tasks autonomously
|
|
- Iterative loop handles difficult tasks
|
|
- Memory persists and informs across sessions
|
|
- Git operations work correctly (worktree, commit, push)
|
|
- QA loop validates and fixes issues
|
|
</functionality>
|
|
<user_experience>
|
|
- Kanban board is intuitive and responsive
|
|
- Agent terminals provide clear visibility
|
|
- Notifications keep user informed
|
|
- Progress is always visible
|
|
- Error states are clear and actionable
|
|
</user_experience>
|
|
<technical_quality>
|
|
- No mock data - all real persistence
|
|
- Unit tests for core functionality
|
|
- E2E tests for critical workflows
|
|
- Clean error handling throughout
|
|
- Performance acceptable with many tasks
|
|
</technical_quality>
|
|
<design_polish>
|
|
- UI follows design system consistently
|
|
- Dark mode is fully implemented
|
|
- No generic "AI slop" aesthetics
|
|
- Animations are subtle and meaningful
|
|
- Typography is readable for long sessions
|
|
</design_polish>
|
|
</success_criteria>
|
|
</project_specification> |