Skip to content

project-overview-pdr.md

Latest commit

 

History

History
606 lines (493 loc) · 18.6 KB

project-overview-pdr.md

File metadata and controls

606 lines (493 loc) · 18.6 KB

Project Overview & Product Development Requirements (PDR)

Project Name: ClaudeKit Engineer Version: 1.8.0 Last Updated: 2025-10-26 Status: Active Development Repository: https://github.com/claudekit/claudekit-engineer

Executive Summary

ClaudeKit Engineer is a comprehensive boilerplate template that revolutionizes software development by integrating AI-powered CLI coding agents (Claude Code and Open Code) into the development workflow. It provides a complete orchestration framework where specialized AI agents collaborate to handle planning, implementation, testing, code review, documentation, and project management.

Project Purpose

Vision

Enable developers to build professional software projects faster and with higher quality by leveraging AI agent orchestration, automated workflows, and intelligent project management.

Mission

Provide a production-ready template that:

  • Accelerates development velocity through AI-powered agent collaboration
  • Enforces best practices and coding standards automatically
  • Maintains comprehensive documentation that evolves with code
  • Ensures code quality through automated testing and review
  • Streamlines git workflows with professional commit standards

Value Proposition

  • 10x Faster Planning: Parallel researcher agents explore solutions simultaneously
  • Consistent Quality: Automated code review and testing on every change
  • Zero Documentation Debt: Docs update automatically with code changes
  • Professional Git History: Clean, conventional commits without AI attribution
  • Reduced Context Switching: Specialized agents handle specific concerns

Target Users

Primary Users

  1. Solo Developers: Building projects faster with AI assistance
  2. Small Development Teams: Standardizing workflows and practices
  3. Open Source Maintainers: Managing contributions and documentation
  4. Startups: Rapid prototyping and MVP development
  5. Enterprise Teams: Enforcing architectural standards

User Personas

Persona 1: Solo Full-Stack Developer

  • Needs: Fast iteration, quality code, minimal documentation overhead
  • Pain Points: Context switching, documentation maintenance, testing gaps
  • Solution: AI agents handle planning, testing, docs while dev focuses on features

Persona 2: Technical Lead

  • Needs: Enforce standards, review code, maintain architecture docs
  • Pain Points: Code review bottleneck, inconsistent patterns, outdated docs
  • Solution: Automated reviews, standardized workflows, living documentation

Persona 3: Open Source Maintainer

  • Needs: Scale contributions, maintain quality, clear documentation
  • Pain Points: Limited time, varying contribution quality, doc rot
  • Solution: Consistent review process, automated standards enforcement

Key Features & Capabilities

1. Multi-Agent Orchestration System

Agent Types:

  • Planning Agents: Research, architecture, technical decisions
  • Implementation Agents: Code generation, feature development
  • Quality Agents: Testing, code review, security analysis
  • Documentation Agents: Auto-updating docs, API references
  • Management Agents: Project tracking, progress monitoring, git operations

Orchestration Patterns:

  • Sequential Chaining: Planning → Implementation → Testing → Review → Deploy
  • Parallel Execution: Multiple researchers exploring different approaches
  • Query Fan-Out: Simultaneous investigation of technical solutions

Performance Optimization:

  • Scout Block Hook: Cross-platform hook system blocking heavy directories
    • Automatic platform detection (Windows/Unix/WSL)
    • Zero-configuration setup
    • Blocks: node_modules, pycache, .git/, dist/, build/
    • Improves AI agent response time and token efficiency

2. Comprehensive Slash Commands (50+)

Core Development:

  • /plan [task] - Research and create implementation plans
  • /cook [tasks] - Implement features with full workflow
  • /test - Run comprehensive test suites
  • /ask [question] - Expert technical consultation
  • /bootstrap - Initialize new projects end-to-end
  • /brainstorm [question] - Solution ideation and evaluation

Debugging & Fixing:

  • /debug [issues] - Deep issue analysis
  • /fix:fast [issues] - Quick bug fixes
  • /fix:hard [issues] - Complex problem solving with subagents
  • /fix:ci [url] - GitHub Actions log analysis
  • /fix:test [issues] - Test suite debugging
  • /fix:types - Type error resolution
  • /fix:logs [issue] - Log analysis and fixes
  • /fix:ui [issue] - UI/UX problem solving

Design & Content:

  • /design:fast [tasks] - Quick design creation
  • /design:good [tasks] - Immersive design development
  • /design:3d [tasks] - Interactive 3D designs with Three.js
  • /design:screenshot [image] - Design from screenshots
  • /design:video [video] - Design from video references
  • /content:fast [request] - Quick copywriting
  • /content:good [request] - High-quality content creation
  • /content:enhance [issues] - Copy improvement
  • /content:cro [issues] - Conversion optimization

Documentation:

  • /docs:init - Create initial documentation
  • /docs:update - Update existing documentation
  • /docs:summarize - Generate codebase summaries

Git Operations:

  • /git:cm - Stage and commit changes
  • /git:cp - Stage, commit, and push
  • /git:pr [branch] - Create pull requests

Project Management:

  • /watzup - Review recent changes and status
  • /journal - Development journal entries
  • /scout [prompt] [scale] - Parallel codebase exploration

3. Extensive Skills Library (20+ Skills)

Categories:

  • Authentication: better-auth integration
  • Cloud: Cloudflare (Workers, R2, Browser Rendering), Google Cloud
  • Databases: MongoDB, PostgreSQL
  • Design: Canvas-based design generation
  • Debugging: Systematic debugging, root-cause tracing, defense-in-depth
  • Development: Next.js, Turborepo, Claude Code workflows
  • Documentation: Repomix, docs-seeker
  • Documents: PDF, DOCX, PPTX, XLSX processing
  • Infrastructure: Docker containerization
  • Media: FFmpeg, ImageMagick
  • MCP: Model Context Protocol server building
  • Problem Solving: Meta-pattern recognition, collision-zone thinking
  • UI: shadcn/ui, Tailwind CSS, Remix Icon
  • Ecommerce: Shopify integrations

4. Automated Release Management

Features:

  • Semantic versioning (MAJOR.MINOR.PATCH)
  • Conventional commit enforcement
  • Automated changelog generation
  • GitHub releases with assets
  • Optional NPM publishing
  • Git hooks for commit validation

Commit Types:

  • feat: → Minor version bump
  • fix: → Patch version bump
  • BREAKING CHANGE: → Major version bump
  • docs:, refactor:, test:, ci: → Patch bump

5. Development Workflow Automation

Pre-Commit:

  • Commit message linting (conventional commits)
  • Optional test execution

Pre-Push:

  • Linting validation
  • Test suite execution
  • Build verification

CI/CD:

  • GitHub Actions integration
  • Automated releases on main branch
  • Test automation
  • Build validation

Technical Requirements

Functional Requirements

FR1: Agent Orchestration

  • Support sequential and parallel agent execution
  • Enable agent-to-agent communication via file system
  • Maintain context across agent handoffs
  • Track agent task completion

FR2: Command System

  • Parse slash commands with arguments
  • Route to appropriate agent workflows
  • Support nested commands (e.g., /fix:ci)
  • Provide command discovery and help

FR3: Documentation Management

  • Auto-generate codebase summaries with repomix
  • Keep docs synchronized with code changes
  • Maintain project roadmap and changelog
  • Update API documentation automatically

FR4: Quality Assurance

  • Run tests before commits
  • Perform code review automatically
  • Check type safety and compilation
  • Validate security best practices

FR5: Git Workflow

  • Enforce conventional commits
  • Scan for secrets before commits
  • Generate professional commit messages
  • Create clean PR descriptions

FR6: Project Bootstrapping

  • Initialize git repository
  • Gather requirements through questions
  • Research tech stacks
  • Generate project structure
  • Create initial documentation
  • Set up CI/CD

Non-Functional Requirements

NFR1: Performance

  • Command execution < 5 seconds for simple operations
  • Parallel agent spawning for independent tasks
  • Efficient file system operations
  • Optimized context loading

NFR2: Reliability

  • Handle agent failures gracefully
  • Provide rollback mechanisms
  • Validate agent outputs
  • Error recovery and retry logic

NFR3: Usability

  • Clear command syntax and documentation
  • Helpful error messages
  • Progress indicators for long operations
  • Comprehensive command help

NFR4: Maintainability

  • Modular agent definitions
  • Reusable workflow templates
  • Clear separation of concerns
  • Self-documenting code and configs

NFR5: Security

  • Secret detection before commits
  • No AI attribution in public commits
  • Secure handling of credentials
  • Security best practice enforcement

NFR6: Scalability

  • Support projects of any size
  • Handle large codebases efficiently
  • Scale agent parallelization
  • Manage complex dependency graphs

Success Metrics

Adoption Metrics

  • GitHub stars and forks
  • NPM package downloads
  • Active users and installations
  • Community engagement (issues, discussions, PRs)

Performance Metrics

  • Average time to bootstrap new project: < 10 minutes
  • Planning to implementation cycle time: 50% reduction
  • Documentation coverage: > 90%
  • Test coverage: > 80%
  • Code review time: 75% reduction

Quality Metrics

  • Conventional commit compliance: 100%
  • Zero secrets in commits: 100%
  • Automated test pass rate: > 95%
  • Documentation freshness: < 24 hours lag

Developer Experience Metrics

  • Time to first commit: < 5 minutes
  • Developer onboarding time: 50% reduction
  • Context switching overhead: 60% reduction
  • Satisfaction score: > 4.5/5.0

Technical Architecture

Core Components

1. Agent Framework

  • Agent definition files (Markdown with frontmatter)
  • Agent orchestration engine
  • Context management system
  • Communication protocol (file-based reports)

2. Command System

  • Command parser and router
  • Argument handling ($ARGUMENTS, $1, $2, etc.)
  • Command composition and nesting
  • Help and discovery system

3. Workflow Engine

  • Sequential execution support
  • Parallel task scheduling
  • Dependency resolution
  • Error handling and recovery

4. Documentation System

  • Repomix integration for codebase compaction
  • Template-based doc generation
  • Auto-update triggers
  • Version tracking

5. Quality System

  • Test runner integration
  • Code review automation
  • Type checking and linting
  • Security scanning

6. Release System

  • Semantic versioning engine
  • Changelog generation
  • GitHub release creation
  • Asset packaging

Technology Stack

Runtime:

  • Node.js >= 18.0.0
  • Bash scripting (Unix hooks)
  • PowerShell scripting (Windows hooks)
  • Cross-platform hook dispatcher (Node.js)

AI Platforms:

  • Anthropic Claude (Sonnet 4, Opus 4)
  • OpenRouter integration
  • Google Gemini (for docs-manager)
  • Grok Code (for git-manager)

Development Tools:

  • Semantic Release
  • Commitlint
  • Husky (git hooks)
  • Repomix (codebase compaction)
  • Scout Block Hook (performance optimization)

CI/CD:

  • GitHub Actions
  • Conventional Commits
  • Automated versioning

Integration Points

MCP Tools:

  • context7: Read latest documentation
  • sequential-thinking: Structured problem solving
  • SearchAPI: Google and YouTube search
  • review-website: Web content extraction
  • VidCap: Video transcript analysis

External Services:

  • GitHub (Actions, Releases, PRs)
  • Discord (notifications)
  • NPM (optional package publishing)

Use Cases

UC1: Bootstrap New Project

Actor: Developer Goal: Create new project from scratch Flow:

  1. Run /bootstrap command
  2. Answer requirement questions
  3. AI researches tech stacks
  4. Review and approve recommendations
  5. AI generates project structure
  6. AI implements initial features
  7. AI creates tests and documentation
  8. Project ready for development

Outcome: Fully functional project with tests, docs, CI/CD in < 10 minutes

UC2: Implement New Feature

Actor: Developer Goal: Add feature with full workflow Flow:

  1. Run /cook "add user authentication"
  2. Planner creates implementation plan
  3. Researcher agents explore auth solutions
  4. Developer reviews and approves plan
  5. AI implements code
  6. AI writes comprehensive tests
  7. AI performs code review
  8. AI updates documentation
  9. AI commits with conventional message

Outcome: Feature complete with tests, docs, and clean git history

UC3: Debug Production Issue

Actor: Developer Goal: Identify and fix production bug Flow:

  1. Run /fix:logs "API timeout errors"
  2. Debugger agent analyzes logs
  3. Root cause identified
  4. Fix plan created
  5. AI implements solution
  6. Tests validate fix
  7. Code review confirms quality
  8. Commit and deploy

Outcome: Bug fixed with comprehensive testing and documentation

UC4: Create Pull Request

Actor: Developer Goal: Submit code for review Flow:

  1. Run /git:pr feature/new-auth main
  2. AI analyzes all commits in branch
  3. AI generates comprehensive PR description
  4. PR created with proper context
  5. Links to related issues added

Outcome: Professional PR ready for review

UC5: Update Documentation

Actor: Project Manager Goal: Ensure docs are current Flow:

  1. Run /docs:update
  2. Docs manager scans codebase
  3. Generates fresh summary with repomix
  4. Identifies outdated sections
  5. Updates API docs, guides, architecture
  6. Validates naming conventions
  7. Creates update report

Outcome: Documentation synchronized with code

Constraints & Limitations

Technical Constraints

  • Requires Node.js >= 18.0.0
  • Depends on Claude Code or Open Code CLI
  • File-based communication has I/O overhead
  • Token limits on AI model context windows

Operational Constraints

  • Requires API keys for AI platforms
  • GitHub Actions minutes for CI/CD
  • Internet connection for MCP tools
  • Storage for repomix output files

Design Constraints

  • Agent definitions must be Markdown with frontmatter
  • Commands follow slash syntax
  • Reports use specific naming conventions
  • Conventional commits required

Risks & Mitigation

Risk 1: AI Model API Failures

Impact: High Likelihood: Medium Mitigation: Retry logic, fallback models, graceful degradation

Risk 2: Context Window Limits

Impact: Medium Likelihood: High Mitigation: Repomix for code compaction, selective context loading, chunking

Risk 3: Agent Coordination Failures

Impact: High Likelihood: Low Mitigation: Validation checks, error recovery, rollback mechanisms

Risk 4: Secret Exposure

Impact: Critical Likelihood: Low Mitigation: Pre-commit scanning, .gitignore enforcement, security reviews

Risk 5: Documentation Drift

Impact: Medium Likelihood: Medium Mitigation: Automated triggers, freshness checks, validation workflows

Future Roadmap

Phase 1: Foundation (Complete - v1.0-1.8)

  • ✅ Core agent framework
  • ✅ Slash command system
  • ✅ Automated releases
  • ✅ Skills library
  • ✅ Documentation system

Phase 2: Enhancement (Current)

  • 🔄 Additional skills (GCP, AWS, Azure)
  • 🔄 UI/UX improvements
  • 🔄 Performance optimization
  • 🔄 Enhanced error handling

Phase 3: Advanced Features (Planned)

  • 📋 Visual workflow builder
  • 📋 Custom agent creator UI
  • 📋 Team collaboration features
  • 📋 Analytics and insights dashboard
  • 📋 Multi-language support

Phase 4: Enterprise (Future)

  • 📋 Self-hosted deployment
  • 📋 Advanced security features
  • 📋 Compliance automation
  • 📋 Custom integrations
  • 📋 Enterprise support

Dependencies & Integration

Required Dependencies

  • Node.js runtime environment
  • Git version control
  • Claude Code or Open Code CLI
  • API keys for AI platforms

Optional Dependencies

  • Discord webhook for notifications
  • GitHub repository for CI/CD
  • NPM account for publishing

Integrations

  • GitHub Actions
  • Semantic Release
  • Commitlint
  • Husky
  • Repomix
  • Various MCP servers

Compliance & Standards

Coding Standards

  • YANGI (You Aren't Gonna Need It)
  • KISS (Keep It Simple, Stupid)
  • DRY (Don't Repeat Yourself)
  • Files < 500 lines
  • Comprehensive error handling
  • Security-first development

Git Standards

  • Conventional Commits
  • Clean commit history
  • No AI attribution
  • No secrets in commits
  • Professional PR descriptions

Documentation Standards

  • Markdown format
  • Up-to-date (< 24 hours)
  • Comprehensive coverage
  • Clear examples
  • Proper versioning

Testing Standards

  • Unit test coverage > 80%
  • Integration tests for workflows
  • Error scenario coverage
  • Performance validation
  • Security testing

Glossary

  • Agent: Specialized AI assistant with specific expertise and responsibilities
  • Slash Command: Shortcut that triggers agent workflows (e.g., /plan)
  • Skill: Reusable knowledge module for specific technologies or patterns
  • MCP: Model Context Protocol for AI tool integration
  • Repomix: Tool for compacting codebases into AI-friendly format
  • Sequential Chaining: Running agents one after another with dependencies
  • Parallel Execution: Running multiple agents simultaneously
  • Query Fan-Out: Spawning multiple researchers to explore different approaches
  • Conventional Commits: Structured commit message format (type(scope): description)

Appendix

Related Documentation

External Resources

Support & Community

Unresolved Questions

  1. Performance Benchmarks: Need to establish baseline metrics for agent execution times
  2. Multi-Repository Support: How to handle projects spanning multiple repositories?
  3. Custom AI Model Support: Should we support other AI platforms beyond Claude and OpenRouter?
  4. Agent Marketplace: Community-contributed agents and skills distribution mechanism?
  5. Real-Time Collaboration: How to handle multiple developers using agents simultaneously?