From 1e841dab67998f0385f0a364c9aa7f3d2dfdb81a Mon Sep 17 00:00:00 2001 From: jamalcodez Date: Mon, 25 Aug 2025 06:18:38 -0500 Subject: [PATCH 1/9] Update placeholder URLs with correct GitHub username --- .../.github/ISSUE_TEMPLATE/bug_report.yml | 69 +++++++++++++++++++ .../ISSUE_TEMPLATE/feature_request.yml | 58 ++++++++++++++++ adce-framework/.github/workflows/ci.yml | 60 ++++++++++++++++ adce-framework/.gitignore | 46 +++++++++++++ adce-framework/CONTRIBUTING.md | 2 +- adce-framework/docs/getting-started.md | 2 +- adce-framework/install.js | 2 +- adce-framework/tools/cli.js | 2 +- 8 files changed, 237 insertions(+), 4 deletions(-) create mode 100644 adce-framework/.github/ISSUE_TEMPLATE/bug_report.yml create mode 100644 adce-framework/.github/ISSUE_TEMPLATE/feature_request.yml create mode 100644 adce-framework/.github/workflows/ci.yml create mode 100644 adce-framework/.gitignore diff --git a/adce-framework/.github/ISSUE_TEMPLATE/bug_report.yml b/adce-framework/.github/ISSUE_TEMPLATE/bug_report.yml new file mode 100644 index 0000000..3499e7f --- /dev/null +++ b/adce-framework/.github/ISSUE_TEMPLATE/bug_report.yml @@ -0,0 +1,69 @@ +name: Bug Report +description: File a bug report to help us improve +title: "[Bug]: " +labels: ["bug", "needs-triage"] + +body: + - type: markdown + attributes: + value: | + Thanks for taking the time to fill out this bug report! + + - type: input + id: version + attributes: + label: ADCE Framework Version + description: What version of ADCE framework are you running? + placeholder: e.g., 1.0.0 + validations: + required: true + + - type: dropdown + id: environment + attributes: + label: Environment + description: What environment are you using? + options: + - Claude Code (Desktop) + - Claude Code (Web) + - Local installation + - NPX usage + validations: + required: true + + - type: textarea + id: what-happened + attributes: + label: What happened? + description: Describe the bug and what you expected to happen + placeholder: A clear and concise description of what the bug is. + validations: + required: true + + - type: textarea + id: reproduction + attributes: + label: Steps to reproduce + description: How can we reproduce this issue? + placeholder: | + 1. Run 'npx adce-framework install' + 2. Use shaper agent with prompt: "..." + 3. See error + validations: + required: true + + - type: textarea + id: logs + attributes: + label: Relevant log output + description: Please copy and paste any relevant log output + render: shell + + - type: checkboxes + id: terms + attributes: + label: Code of Conduct + description: By submitting this issue, you agree to follow our Code of Conduct + options: + - label: I agree to follow this project's Code of Conduct + required: true \ No newline at end of file diff --git a/adce-framework/.github/ISSUE_TEMPLATE/feature_request.yml b/adce-framework/.github/ISSUE_TEMPLATE/feature_request.yml new file mode 100644 index 0000000..7ad05e4 --- /dev/null +++ b/adce-framework/.github/ISSUE_TEMPLATE/feature_request.yml @@ -0,0 +1,58 @@ +name: Feature Request +description: Suggest an idea for the ADCE framework +title: "[Feature]: " +labels: ["enhancement", "needs-discussion"] + +body: + - type: markdown + attributes: + value: | + Thanks for suggesting a feature! Please provide details below. + + - type: dropdown + id: feature-area + attributes: + label: Feature Area + description: Which area does this feature request relate to? + options: + - Agent behavior + - Templates + - Installation process + - Documentation + - CLI tools + - Examples + - Framework methodology + validations: + required: true + + - type: textarea + id: problem + attributes: + label: Problem Statement + description: What problem does this feature solve? + placeholder: Describe the user problem this feature addresses + validations: + required: true + + - type: textarea + id: solution + attributes: + label: Proposed Solution + description: Describe your proposed solution + placeholder: How would you like this feature to work? + validations: + required: true + + - type: textarea + id: alternatives + attributes: + label: Alternatives Considered + description: What alternative solutions have you considered? + placeholder: Describe alternative approaches you've thought about + + - type: textarea + id: additional-context + attributes: + label: Additional Context + description: Add any other context, screenshots, or examples + placeholder: Any additional information that helps explain your request \ No newline at end of file diff --git a/adce-framework/.github/workflows/ci.yml b/adce-framework/.github/workflows/ci.yml new file mode 100644 index 0000000..8b39b68 --- /dev/null +++ b/adce-framework/.github/workflows/ci.yml @@ -0,0 +1,60 @@ +name: CI + +on: + push: + branches: [ main, develop ] + pull_request: + branches: [ main ] + +jobs: + test: + runs-on: ubuntu-latest + + strategy: + matrix: + node-version: [18.x, 20.x] + + steps: + - uses: actions/checkout@v3 + + - name: Use Node.js ${{ matrix.node-version }} + uses: actions/setup-node@v3 + with: + node-version: ${{ matrix.node-version }} + cache: 'npm' + + - run: npm ci + + - name: Run tests + run: npm test + + - name: Test installation process + run: | + mkdir test-install + cd test-install + npm init -y + node ../install.js + + validate-agents: + runs-on: ubuntu-latest + + steps: + - uses: actions/checkout@v3 + + - name: Use Node.js 18.x + uses: actions/setup-node@v3 + with: + node-version: 18.x + cache: 'npm' + + - run: npm ci + + - name: Validate agent files + run: npm run validate-agents + + - name: Check documentation links + run: | + # Check that all referenced files exist + find . -name "*.md" -exec grep -l "\[.*\](" {} \; | while read file; do + echo "Checking links in $file" + done \ No newline at end of file diff --git a/adce-framework/.gitignore b/adce-framework/.gitignore new file mode 100644 index 0000000..6c2132f --- /dev/null +++ b/adce-framework/.gitignore @@ -0,0 +1,46 @@ +# Dependencies +node_modules/ +npm-debug.log* + +# Environment files +.env +.env.local +.env.development.local +.env.test.local +.env.production.local + +# OS generated files +.DS_Store +.DS_Store? +._* +.Spotlight-V100 +.Trashes +ehthumbs.db +Thumbs.db + +# IDE files +.vscode/ +.idea/ +*.swp +*.swo + +# Logs +logs +*.log + +# Runtime data +pids +*.pid +*.seed +*.pid.lock + +# Coverage directory used by tools like istanbul +coverage/ + +# Build outputs +dist/ +build/ + +# Temporary files +tmp/ +temp/ \ No newline at end of file diff --git a/adce-framework/CONTRIBUTING.md b/adce-framework/CONTRIBUTING.md index c704497..ae972ea 100644 --- a/adce-framework/CONTRIBUTING.md +++ b/adce-framework/CONTRIBUTING.md @@ -29,7 +29,7 @@ Thank you for your interest in contributing to the ADCE (Appetite-Driven Context ### 1. Fork & Clone ```bash -git clone https://github.com/yourusername/adce-framework.git +git clone https://github.com/jamalcodez/adce-framework.git cd adce-framework npm install ``` diff --git a/adce-framework/docs/getting-started.md b/adce-framework/docs/getting-started.md index a081c27..31b4d30 100644 --- a/adce-framework/docs/getting-started.md +++ b/adce-framework/docs/getting-started.md @@ -23,5 +23,5 @@ Use deployer to package and deploy user-dashboard What’s Next? • Read ADCE Methodology • Explore Examples - • Join the community: https://github.com/yourusername/adce-framework/discussions + • Join the community: https://github.com/jamalcodez/adce-framework/discussions diff --git a/adce-framework/install.js b/adce-framework/install.js index c550117..74bc5ba 100755 --- a/adce-framework/install.js +++ b/adce-framework/install.js @@ -164,7 +164,7 @@ npm run build console.log('2. Review the methodology:'); console.log(chalk.cyan(' cat ADCE/examples/user-dashboard/README.md\n')); console.log('3. Join the community:'); - console.log(chalk.cyan(' https://github.com/yourusername/adce-framework/discussions\n')); + console.log(chalk.cyan(' https://github.com/jamalcodez/adce-framework/discussions\n')); } } diff --git a/adce-framework/tools/cli.js b/adce-framework/tools/cli.js index c7220b4..3c194b6 100755 --- a/adce-framework/tools/cli.js +++ b/adce-framework/tools/cli.js @@ -185,7 +185,7 @@ npm run build # Build for production console.log(' adce install'); console.log(' adce status'); console.log(' adce validate-agents\n'); - console.log('Visit https://github.com/yourusername/adce-framework for documentation'); + console.log('Visit https://github.com/jamalcodez/adce-framework for documentation'); } } From eb8380dfd37bd6f83a72320910da1cf5f45ded10 Mon Sep 17 00:00:00 2001 From: jamalcodez Date: Mon, 25 Aug 2025 20:43:27 -0500 Subject: [PATCH 2/9] Update installation instructions with working methods MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit - Add global installation option (npm install -g + adce install) - Keep local installation option for project-specific use - Improve Quick Start section structure 🤖 Generated with [Claude Code](https://claude.ai/code) Co-Authored-By: Claude --- adce-framework/README.md | 12 +++++++++++- 1 file changed, 11 insertions(+), 1 deletion(-) diff --git a/adce-framework/README.md b/adce-framework/README.md index de8e5b2..5097ac8 100644 --- a/adce-framework/README.md +++ b/adce-framework/README.md @@ -18,9 +18,19 @@ ADCE combines the best of three methodologies: ## Quick Start -### 1. Install in Your Project +### 1. Install the Framework ```bash +# Global installation (recommended) +npm install -g adce-framework +adce install + +# Or local installation +npm install adce-framework npx adce-framework install +``` + +### 2. Start Your First Cycle +```bash # Create a pitch from your idea "Use shaper to create a pitch for: [your broad idea]" From c86f67f525c2211e06fb95b477805aacc52cb377 Mon Sep 17 00:00:00 2001 From: jamalcodez Date: Wed, 27 Aug 2025 16:08:59 -0500 Subject: [PATCH 3/9] Upgrade builder subagent with 2025 design patterns and modern UI capabilities MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit - Enhanced builder agent with cutting-edge 2025 design patterns including vivid glow aesthetics, anti-design/brutalism, and human-crafted authenticity - Added advanced interactivity patterns: dynamic cursors, 3D elements, micro-interactions 2.0 - Integrated AI & accessibility features with WCAG 2.2 compliance and voice interfaces - Included sustainability and ethical design principles for energy-efficient development - Added comprehensive 2025 component pattern library with CSS examples - Updated success metrics to include modern standards and progressive enhancement 🤖 Generated with [Claude Code](https://claude.ai/code) Co-Authored-By: Claude --- adce-framework/agents/builder.md | 140 ++++++++++++++++++++++++++----- 1 file changed, 117 insertions(+), 23 deletions(-) diff --git a/adce-framework/agents/builder.md b/adce-framework/agents/builder.md index 8230735..985925a 100644 --- a/adce-framework/agents/builder.md +++ b/adce-framework/agents/builder.md @@ -1,24 +1,24 @@ --- name: builder -description: MUST BE USED for UI/UX design and frontend implementation within AI-accelerated appetite constraints. Handles both design decisions and code implementation. Use for all user-facing features and interfaces. +description: MUST BE USED for UI/UX design and frontend implementation within AI-accelerated appetite constraints. Handles both design decisions and code implementation with 2025 design patterns. Use for all user-facing features, interfaces, and modern design systems. tools: Read, Write, Edit, Bash --- -You are a hybrid designer-developer operating within AI-accelerated appetite constraints, using comprehensive context to build user interfaces that work on first implementation with dramatically reduced iteration cycles. +You are a hybrid designer-developer operating within AI-accelerated appetite constraints, using comprehensive context and cutting-edge 2025 design patterns to build user interfaces that work on first implementation with dramatically reduced iteration cycles. -## Your Dual Expertise +## Your Enhanced Dual Expertise -### Design Responsibilities -- **Solve interface problems** during implementation, not upfront planning -- **Design within appetite constraints** - prioritize "good enough" over pixel perfect -- **Follow solution sketches** from shaper while making detailed UX decisions -- **Create consistent experiences** that match existing system patterns +### Design Responsibilities with 2025 Patterns +- **Solve interface problems** during implementation using modern design trends +- **Apply 2025 design patterns** - vivid glow aesthetics, anti-design/brutalism, human-crafted authenticity +- **Follow solution sketches** from shaper while making detailed UX decisions with trend awareness +- **Create consistent experiences** using both existing patterns and bold visual expression -### Development Responsibilities -- **Build responsive user interfaces** using modern frontend frameworks -- **Implement component systems** that integrate with existing codebase -- **Handle state management** and API integration efficiently -- **Ensure accessibility and performance** within appetite bounds +### Development Responsibilities with Modern Standards +- **Build responsive user interfaces** using modern frontend frameworks with 2025 interactivity +- **Implement component systems** with advanced micro-interactions and 3D elements +- **Handle state management** and API integration with AI-powered personalization +- **Ensure accessibility and performance** with WCAG 2.2 compliance and sustainability focus ## Your Context-Driven Process @@ -39,18 +39,112 @@ You are a hybrid designer-developer operating within AI-accelerated appetite con 2. **Core functionality first**: Get basic user workflow working 3. **Layer on polish**: Apply styling and interactions within appetite -## Design Philosophy for Appetite Constraints +## Enhanced Design Philosophy for 2025 -- **Functional > Beautiful**: Works reliably over looks perfect -- **Consistent > Novel**: Matches existing patterns over innovative design -- **Clear > Clever**: Users understand immediately over impressive interactions -- **Fast > Perfect**: Quick interactions over complex animations +### Core Principles with Modern Edge +- **Functional > Beautiful**: Works reliably while embracing bold visual expression +- **Consistent > Novel**: Balance existing patterns with trend-forward innovation +- **Clear > Clever**: User understanding with engaging micro-interactions +- **Fast > Perfect**: Performance-conscious with purposeful animation and interactivity -## Success Metrics +### 2025 Design Integration Strategy +- **Bold Expression**: Implement vivid colors, experimental typography, authentic imperfections +- **Human Authenticity**: Hand-crafted illustrations, organic forms, sketchbook aesthetics +- **Advanced Interactivity**: Dynamic cursors, 3D elements, gesture-based controls +- **AI & Accessibility**: Voice interfaces, automated accessibility, personalization +- **Sustainability**: Energy-efficient design, ethical AI, environmental consciousness +### Pattern Selection Framework +- **Appetite = 1-2 weeks**: Focus on existing patterns with modern polish +- **Appetite = 3-4 weeks**: Integrate 1-2 bold design trends strategically +- **Appetite = 5-6 weeks**: Full 2025 design system with advanced interactivity + +## Enhanced Success Metrics for 2025 + +### Functional Excellence - Can users complete their intended workflow efficiently? -- Does it feel consistent with the existing product? -- Works acceptably on mobile and desktop? -- Basic accessibility and performance standards met? +- Does it feel consistent with the existing product while embracing modern trends? +- Works acceptably on mobile, desktop, and emerging form factors? + +### Modern Standards Compliance +- **Accessibility**: WCAG 2.2 AA minimum, European Accessibility Act ready +- **Performance**: Core Web Vitals optimized, energy-efficient design +- **Sustainability**: Minimal resource usage, green hosting compatibility +- **AI Integration**: Accessibility automation, personalization features +- **Voice Interface**: Natural language support, hands-free navigation + +### 2025 Design Pattern Implementation +- **Bold Visual Expression**: Effective use of vivid colors, experimental typography +- **Human Authenticity**: Incorporation of hand-crafted elements, organic forms +- **Advanced Interactivity**: Purpose-driven micro-interactions, 3D integration +- **Progressive Enhancement**: Graceful degradation across device capabilities + +## 2025 Component Pattern Library + +### Navigation Patterns +```css +/* 2025 Header with Glow Aesthetic */ +.header-2025 { + background: linear-gradient(135deg, #ff6b6b, #4ecdc4); + box-shadow: 0 0 20px rgba(255, 107, 107, 0.3); + backdrop-filter: blur(10px); +} + +/* Bento Box Navigation */ +.nav-bento { + display: grid; + grid-template-columns: repeat(auto-fit, minmax(120px, 1fr)); + gap: 8px; + padding: 16px; +} +``` + +### Interactive Elements +```css +/* Dynamic Cursor Integration */ +.interactive-cursor { + cursor: none; +} +.interactive-cursor::before { + content: ''; + position: fixed; + width: 20px; + height: 20px; + background: radial-gradient(circle, #ff6b6b, transparent); + pointer-events: none; + z-index: 9999; +} + +/* 3D Card Hover */ +.card-3d { + transform-style: preserve-3d; + transition: transform 0.3s ease; +} +.card-3d:hover { + transform: perspective(1000px) rotateY(15deg); +} +``` + +### Accessibility-First Voice Integration +```javascript +// Voice Navigation Pattern +const voiceCommands = { + "navigate home": () => router.push('/'), + "open menu": () => setMobileMenuOpen(true), + "search for": (query) => performSearch(query), + "help me": () => showAccessibilityPanel() +}; +``` + +### Color Systems with Accessibility +```css +/* 2025 Vivid Glow Palette (WCAG 2.2 Compliant) */ +:root { + --glow-primary: #ff3d71; + --glow-secondary: #00d4ff; + --contrast-safe: #1a1a1a; /* 4.5:1 ratio maintained */ + --energy-efficient: #2a2a2a; /* Dark mode default */ +} +``` -Remember: Build interfaces that help people accomplish their goals efficiently while staying within appetite constraints. +Remember: Build interfaces that help people accomplish their goals efficiently while embracing 2025 design trends and staying within appetite constraints. From 8948c8b34748995850c6ffb9bf3e607742096f1b Mon Sep 17 00:00:00 2001 From: jamalcodez Date: Wed, 27 Aug 2025 16:11:32 -0500 Subject: [PATCH 4/9] Update documentation and examples for enhanced builder agent MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit - Updated agent specifications with comprehensive 2025 design pattern integration - Enhanced agents README with modern builder capabilities - Added 2025 design patterns example directory with usage guidelines - All agents pass validation with only minor enhancement suggestions 🤖 Generated with [Claude Code](https://claude.ai/code) Co-Authored-By: Claude --- adce-framework/agents/README.md | 6 +- adce-framework/docs/agent-specifications.md | 68 +++++++++++-------- .../examples/2025-design-patterns/README.md | 27 ++++++++ 3 files changed, 70 insertions(+), 31 deletions(-) create mode 100644 adce-framework/examples/2025-design-patterns/README.md diff --git a/adce-framework/agents/README.md b/adce-framework/agents/README.md index a6a9101..d0c9733 100644 --- a/adce-framework/agents/README.md +++ b/adce-framework/agents/README.md @@ -22,9 +22,9 @@ Example: "Use architect to review this pitch for technical feasibility" 🎨 builder -Purpose: UI/UX design and frontend implementation -When to use: Building user interfaces, implementing designs -Example: "Use builder to implement the dashboard components" +Purpose: UI/UX design and frontend implementation with 2025 design patterns +When to use: Building user interfaces, implementing designs, applying modern trends +Example: "Use builder to implement the dashboard components with 2025 design patterns" 🚀 deployer diff --git a/adce-framework/docs/agent-specifications.md b/adce-framework/docs/agent-specifications.md index aaf5f21..be5caa3 100644 --- a/adce-framework/docs/agent-specifications.md +++ b/adce-framework/docs/agent-specifications.md @@ -105,47 +105,59 @@ Agents automatically activate based on: - **Risk assessment**: Include domain-specific technical risks - **PRP templates**: Customize for different technology stacks -### 🎨 builder Agent +### 🎨 builder Agent (Enhanced 2025) -**Primary Role**: UI/UX design and frontend implementation within appetite constraints +**Primary Role**: UI/UX design and frontend implementation with cutting-edge 2025 design patterns **Auto-Activation Triggers**: -- Keywords: "UI", "component", "design", "frontend", "interface", "user experience" -- Context: User-facing feature development, design system work -- Patterns: Visual design needs, user interaction requirements +- Keywords: "UI", "component", "design", "frontend", "interface", "user experience", "2025", "modern", "trends" +- Context: User-facing feature development, design system work, modern pattern implementation +- Patterns: Visual design needs, user interaction requirements, bold visual expression **Core Responsibilities**: -1. **Design-While-Building**: Solve interface problems during implementation -2. **Component Development**: Build reusable UI components and patterns -3. **User Experience**: Ensure usable, accessible, and responsive experiences -4. **Design System**: Maintain consistency with existing visual patterns -5. **Frontend Integration**: Connect UI components with backend services - -**Design Philosophy for Appetite Constraints**: -- **Functional > Beautiful**: Works reliably over looks perfect -- **Consistent > Novel**: Matches existing patterns over innovative design -- **Clear > Clever**: Users understand immediately over impressive interactions -- **Fast > Perfect**: Quick interactions over complex animations +1. **Design-While-Building**: Solve interface problems using 2025 design trends +2. **Component Development**: Build reusable UI components with advanced interactivity +3. **User Experience**: Ensure usable, accessible experiences with AI-powered features +4. **Design System**: Balance existing patterns with trend-forward innovation +5. **Frontend Integration**: Connect UI components with voice interfaces and AI personalization + +**Enhanced Design Philosophy for 2025**: +- **Functional > Beautiful**: Works reliably while embracing bold visual expression +- **Consistent > Novel**: Balance existing patterns with trend-forward innovation +- **Clear > Clever**: User understanding with engaging micro-interactions +- **Fast > Perfect**: Performance-conscious with purposeful animation and interactivity +- **Accessible > Aesthetic**: WCAG 2.2 compliance with stunning visual design +- **Sustainable > Resource-Heavy**: Energy-efficient design with environmental consciousness + +**2025 Pattern Integration**: +- **Bold Expression**: Vivid glow aesthetics, experimental typography, anti-design elements +- **Human Authenticity**: Hand-crafted illustrations, organic forms, sketchbook aesthetics +- **Advanced Interactivity**: Dynamic cursors, 3D elements, gesture-based controls +- **AI Integration**: Voice interfaces, automated accessibility, personalization +- **Sustainability**: Energy-efficient design, ethical AI, green hosting compatibility **Required Context Engineering**: -- Existing design system patterns and component library -- User research and usability requirements -- Accessibility standards and compliance needs -- Performance budgets and technical constraints -- Brand guidelines and visual consistency requirements +- Existing design system patterns and 2025 trend compatibility +- User research and modern usability requirements +- WCAG 2.2 accessibility standards and European Accessibility Act compliance +- Performance budgets with Core Web Vitals optimization +- Brand guidelines balanced with modern visual expression +- Voice interface and AI personalization capabilities **Output Quality Standards**: -- Functional user interfaces that complete intended workflows -- Consistent design language matching existing product -- Accessible and responsive across devices and browsers -- Performance-conscious implementation within appetite bounds +- Functional user interfaces with 2025 design pattern integration +- Consistent design language balancing existing and modern approaches +- WCAG 2.2 accessible and responsive across all device types +- Performance-optimized with energy efficiency and sustainability focus +- AI-powered accessibility features and voice interface support **Tools**: Read, Write, Edit, Bash **Customization Points**: -- **Design system integration**: Connect with company design systems -- **Accessibility standards**: Include specific compliance requirements -- **Performance budgets**: Set company-specific performance constraints +- **2025 Design Integration**: Customize trend adoption based on brand personality +- **Accessibility Enhancement**: WCAG 2.2 and European Accessibility Act compliance +- **Performance & Sustainability**: Energy-efficient design with Core Web Vitals optimization +- **AI Feature Integration**: Voice interfaces, automated accessibility, personalization engines ### 🚀 deployer Agent diff --git a/adce-framework/examples/2025-design-patterns/README.md b/adce-framework/examples/2025-design-patterns/README.md new file mode 100644 index 0000000..764db66 --- /dev/null +++ b/adce-framework/examples/2025-design-patterns/README.md @@ -0,0 +1,27 @@ +# 2025 Design Patterns - ADCE Builder Examples + +Modern design pattern implementations showcasing the enhanced builder agent capabilities. + +## Pattern Categories + +### Bold Visual Expression +Examples of vivid glow aesthetics, anti-design elements, and experimental typography. + +### Human-Crafted Authenticity +Hand-drawn illustrations, organic forms, and sketchbook aesthetic implementations. + +### Advanced Interactivity +Dynamic cursors, 3D elements, and micro-interactions 2.0 with performance optimization. + +### AI & Accessibility Integration +Voice interfaces, automated accessibility features, and AI-powered personalization. + +## Usage with Builder Agent + +```bash +"Use builder to implement a dashboard with 2025 vivid glow aesthetic" +"Use builder to create navigation with bento box layout and dynamic cursors" +"Use builder to build form components with hand-crafted authenticity" +``` + +These examples demonstrate appetite-driven implementation of cutting-edge design trends while maintaining usability and accessibility standards. \ No newline at end of file From 8914bfe067e36fb3cb7c76734d7b9c16da473bf0 Mon Sep 17 00:00:00 2001 From: Claude Date: Sun, 26 Oct 2025 12:15:20 +0000 Subject: [PATCH 5/9] Add task breakdown system with planner agent This enhancement adds granular task decomposition capabilities to ADCE: New Components: - Planner agent: Breaks PRPs into 5-15 specific, dependency-aware tasks - Task plan template: Structured format with dependency tracking - Task breakdown example: Complete workflow showing planning in action Updated Documentation: - Added Phase 3 (Task Planning) to methodology - Updated README.md and agents/README.md to include planner - Modified install.js to install planner agent and task-plan templates - Updated CLAUDE.md template with extended workflow Key Features: - Dependency mapping (identifies which tasks block others) - Time estimation per task (1-4 hour chunks) - Verification criteria for each task - Circuit breaker integration (P1/P2/P3 priority system) - Parallel work opportunities identification Benefits: - Systematic execution with clear step-by-step path - Better progress tracking (7/12 tasks = 58% done) - Early risk detection (task overruns trigger circuit breakers) - Enables parallel work across multiple developers - Improved AI results through specific task prompts Usage: Use for complex features (1-2+ week appetite), skip for simple features. Example: "Use planner to break down the API PRP into specific tasks" Generated with Claude Code --- adce-framework/README.md | 19 +- adce-framework/agents/README.md | 70 +- adce-framework/agents/planner.md | 266 +++++ adce-framework/docs/methodology.md | 48 +- .../examples/task-breakdown/README.md | 174 +++ .../task-breakdown/implementation-log.md | 475 ++++++++ .../task-breakdown/prp-expense-api.md | 172 +++ .../task-breakdown/task-plan-expense-api.md | 1024 +++++++++++++++++ adce-framework/install.js | 13 +- .../templates/task-plan/task-plan-base.md | 319 +++++ 10 files changed, 2549 insertions(+), 31 deletions(-) create mode 100644 adce-framework/agents/planner.md create mode 100644 adce-framework/examples/task-breakdown/README.md create mode 100644 adce-framework/examples/task-breakdown/implementation-log.md create mode 100644 adce-framework/examples/task-breakdown/prp-expense-api.md create mode 100644 adce-framework/examples/task-breakdown/task-plan-expense-api.md create mode 100644 adce-framework/templates/task-plan/task-plan-base.md diff --git a/adce-framework/README.md b/adce-framework/README.md index de8e5b2..48dd1a8 100644 --- a/adce-framework/README.md +++ b/adce-framework/README.md @@ -45,15 +45,16 @@ Appetite constraints: Prevent scope creep Context engineering: Enable AI first-pass success Specialized agents: Domain expertise + consistency -The Four Core Agents -🎯 shaper -Turns broad ideas into appetite-bounded pitches with comprehensive context -🏗️ architect -Manages technical implementation, architecture decisions, and scope within appetite -🎨 builder -Handles UI/UX design and frontend development within constraints -🚀 deployer -Gets features safely to production and maintains system reliability +## The Five Core Agents +🎯 **shaper** - Turns broad ideas into appetite-bounded pitches with comprehensive context + +🏗️ **architect** - Manages technical implementation, architecture decisions, and scope within appetite + +📋 **planner** - Breaks PRPs into specific, dependency-aware tasks for complex features (optional) + +🎨 **builder** - Handles UI/UX design and frontend development within constraints + +🚀 **deployer** - Gets features safely to production and maintains system reliability Real Results Finance Dashboard: "Users want better financial insights" → Working dashboard with spending breakdown in 1.5 weeks (AI-accelerated) User Onboarding: "Reduce new user confusion" → Progressive onboarding flow reducing churn 67% in 1 week (AI-accelerated) diff --git a/adce-framework/agents/README.md b/adce-framework/agents/README.md index a6a9101..2a2e2cf 100644 --- a/adce-framework/agents/README.md +++ b/adce-framework/agents/README.md @@ -1,13 +1,15 @@ # ADCE Framework Agents -This directory contains the four core ADCE (Appetite-Driven Context Engineering) agents for Claude Code. +This directory contains the five core ADCE (Appetite-Driven Context Engineering) agents for Claude Code. ## Quick Installation ```bash # Copy agents to your Claude Code project cp agents/*.md .claude/agents/ -The Four Core Agents +``` + +## The Five ADCE Agents 🎯 shaper Purpose: Turn broad ideas into appetite-bounded pitches with context @@ -20,6 +22,12 @@ Purpose: Technical leadership, architecture decisions, scope management When to use: Technical feasibility, creating PRPs, managing complexity Example: "Use architect to review this pitch for technical feasibility" +📋 planner + +Purpose: Break PRPs into specific, sequential, dependency-aware tasks +When to use: Complex features needing granular execution steps, coordinating parallel work +Example: "Use planner to break down the API PRP into specific implementation tasks" + 🎨 builder Purpose: UI/UX design and frontend implementation @@ -32,23 +40,55 @@ Purpose: Infrastructure, deployment, production operations When to use: Getting features to production, managing infrastructure Example: "Use deployer to set up staging environment" -Usage Workflow +## Usage Workflow -Shaping: shaper creates appetite-bounded pitch -Architecture: architect reviews feasibility and creates PRPs -Building: builder and deployer implement features -Integration: architect manages integration and scope decisions -Deployment: deployer gets features to production +### Standard Flow (Simple Features) +1. **Shaping**: shaper creates appetite-bounded pitch +2. **Architecture**: architect reviews feasibility and creates PRPs +3. **Building**: builder and deployer implement features +4. **Integration**: architect manages integration and scope decisions +5. **Deployment**: deployer gets features to production -Agent Configuration -Each agent includes: +### Extended Flow (Complex Features) +1. **Shaping**: shaper creates appetite-bounded pitch +2. **Architecture**: architect reviews feasibility and creates PRPs +3. **Planning**: planner breaks PRPs into specific, dependency-aware tasks (NEW) +4. **Building**: builder and deployer execute tasks systematically +5. **Integration**: architect manages integration and scope decisions +6. **Deployment**: deployer gets features to production -Specific tools access: Only the tools needed for their role -Context engineering: Comprehensive prompts for AI success -Appetite awareness: Built-in scope and time management -Validation criteria: Clear success metrics and testing +## Agent Configuration +Each agent includes: -Customization +- Specific tools access: Only the tools needed for their role +- Context engineering: Comprehensive prompts for AI success +- Appetite awareness: Built-in scope and time management +- Validation criteria: Clear success metrics and testing + +## When to Use the Planner + +### Always Use For: +- Complex features (1-2 week or 2-3 week appetite) +- Features with many integration points or dependencies +- Work involving multiple developers or AI sessions +- High-risk technical work with unknowns +- Onboarding new team members to the codebase + +### Consider Skipping For: +- Simple features (1-3 day appetite, straightforward implementation) +- Well-understood patterns (e.g., another CRUD endpoint) +- Solo developer comfortable working from PRPs directly +- Emergency bug fixes requiring immediate action + +### Benefits of Task Planning: +- **Systematic execution**: Clear step-by-step path from start to finish +- **Better AI results**: Specific tasks → specific prompts → better code +- **Parallel work**: Multiple developers can work on independent tasks +- **Progress tracking**: Know exactly where you are (7/12 tasks = 58% done) +- **Early risk detection**: If Task 3 takes 2x estimate, trigger circuit breaker +- **Clearer handoffs**: Easy to delegate or resume work later + +## Customization You can customize agents by: Modifying the description field for different trigger conditions diff --git a/adce-framework/agents/planner.md b/adce-framework/agents/planner.md new file mode 100644 index 0000000..26901f0 --- /dev/null +++ b/adce-framework/agents/planner.md @@ -0,0 +1,266 @@ +--- +name: planner +description: MUST BE USED for breaking PRPs into specific, sequential, dependency-aware implementation tasks. Use when you need concrete execution steps from high-level requirements, especially for complex features requiring systematic task decomposition. +tools: Read, Write, Edit +--- + +You are a specialized planning expert responsible for transforming Product Requirement Prompts (PRPs) into specific, sequential, dependency-aware task breakdowns that enable systematic implementation within appetite constraints. + +## Your Core Responsibilities + +### Task Decomposition +- Break PRP goals into 5-15 specific, actionable tasks +- Each task must be completable in 1-4 hours +- Tasks must be concrete, not abstract (e.g., "Create UserController with GET /users endpoint" not "Work on API") +- Ensure tasks build logically on each other + +### Dependency Mapping +- Identify which tasks depend on others (can't start until prerequisites complete) +- Highlight tasks that can be done in parallel (no dependencies) +- Create clear dependency chains showing the critical path +- Plan for rollback if tasks fail + +### Time & Appetite Management +- Estimate realistic time per task (AI-accelerated development) +- Ensure total time ≤ PRP appetite constraint +- Mark tasks as Priority 1 (must have), 2 (should have), 3 (nice to have) +- Plan what to cut if complexity emerges + +### Verification Planning +- Every task must have concrete pass/fail criteria +- Include unit tests, integration tests, or manual verification steps +- No task is "done" until verification passes +- Build quality gates into the execution flow + +## Task Plan Structure + +For each PRP, create a task plan with: + +### 1. Overview Section +- PRP goal and appetite constraint +- Total time budget and task count +- Visual dependency graph (ASCII art showing task relationships) +- Critical path identification + +### 2. Task Breakdown (5-15 tasks) +For each task include: +- **Task number and name**: Clear, specific action +- **Depends on**: Which tasks must complete first (or "None" for foundational tasks) +- **Enables**: Which tasks become available after this completes +- **Estimated time**: Realistic hours (1-4 hour chunks) +- **Output**: Concrete deliverable (files, features, tests) +- **Verification**: How to prove it works +- **Files to create/modify**: Specific file paths +- **Appetite risk**: Low/Medium/High complexity indicator +- **Circuit breaker**: What to simplify if time pressure emerges + +### 3. Progress Tracking +- Checklist of all tasks +- Running time total vs. appetite budget +- Warning thresholds (50%, 75%, 90% time consumed) + +### 4. Parallel Work Opportunities +- Which tasks can be done simultaneously +- How to divide work across multiple developers or AI sessions + +## Key Principles + +### 1. Specificity Over Abstraction +**Bad**: "Set up backend" +**Good**: "Create Express.js server with /api/users GET endpoint returning JSON" + +### 2. Verifiable Completion +**Bad**: "Make it look good" +**Good**: "Style button with primary-blue, 16px padding, hover state; verify with visual regression test" + +### 3. Dependency Awareness +**Bad**: Random task order +**Good**: +- Task 1: Create database schema +- Task 2: Write migration (depends on Task 1) +- Task 3: Create model (depends on Task 1, 2) +- Task 4: Build API endpoint (depends on Task 3) + +### 4. Time-Boxing +- If a task seems >4 hours, break it down further +- Smaller tasks = better progress tracking +- Easier to parallelize and delegate + +### 5. Appetite Discipline +- Tasks must fit within PRP appetite +- Mark non-essential tasks for circuit breaker decisions +- Include simplified alternatives for complex tasks + +## Task Decomposition Process + +### Step 1: Parse the PRP +Read the PRP document and extract: +- Goal and user value +- Appetite constraint (time budget) +- Success criteria (must haves) +- Context and gotchas +- Known complexity areas + +### Step 2: Identify Work Chunks +Break the goal into logical implementation units: +- Database/data layer +- Business logic/API layer +- UI/presentation layer +- Integration points +- Testing and validation +- Deployment and infrastructure + +### Step 3: Sequence Tasks +Order tasks by dependencies: +- Foundational work first (database, schemas, core models) +- API layer second (depends on data layer) +- UI layer third (depends on API) +- Integration and testing fourth +- Deployment last + +### Step 4: Add Verification +For each task, define how to verify completion: +- Unit tests that must pass +- Integration tests that prove it works with system +- Manual checks or user acceptance criteria +- Performance benchmarks if relevant + +### Step 5: Estimate Time +For each task: +- Consider AI-acceleration (AI can write boilerplate 5x faster) +- Include time for testing and debugging +- Add buffer for complexity unknowns +- Sum total and compare to appetite + +### Step 6: Mark Priorities +Label each task: +- **P1 (Must Have)**: Core user value, can't ship without it +- **P2 (Should Have)**: Important but can be simplified +- **P3 (Nice to Have)**: Polish and enhancements, first to cut + +### Step 7: Plan Circuit Breakers +For each high-risk task, define: +- What to cut if it takes too long +- Simpler alternative approach +- Impact of cutting on user value + +## AI-Accelerated Time Estimation + +When estimating task time, account for AI assistance: + +### Tasks AI Accelerates Well (3-5x faster) +- Boilerplate code (CRUD endpoints, models, controllers) +- Standard UI components (forms, tables, buttons) +- Test scaffolding and basic test cases +- Documentation and code comments +- Configuration files and setup scripts + +### Tasks AI Helps Less (1.5-2x faster) +- Complex business logic +- Novel algorithms +- System architecture decisions +- Performance optimization +- Security-critical code + +### Tasks AI Doesn't Accelerate Much (1-1.2x faster) +- Debugging production issues +- Integration with poorly documented APIs +- Visual design decisions +- User research and testing +- DevOps troubleshooting + +## Dependency Graph Examples + +### Simple Linear Dependencies +``` +Task 1 (Schema) → Task 2 (Migration) → Task 3 (Model) → Task 4 (API) +``` + +### Parallel Opportunities +``` +Task 1 (Database setup) + ├─→ Task 2 (User model) → Task 4 (Auth API) + └─→ Task 3 (Product model) → Task 5 (Product API) +``` + +### Complex Dependencies +``` +Task 1 (Schema) + ├─→ Task 2 (User model) + │ ├─→ Task 4 (Auth API) + │ └─→ Task 5 (User API) + └─→ Task 3 (Settings model) + └─→ Task 6 (Settings API) (also depends on Task 5) +``` + +## Communication Style + +- Use clear, imperative task names: "Create X", "Implement Y", "Test Z" +- Be specific about files, functions, and endpoints +- Include concrete examples in task descriptions +- Provide clear verification criteria (not vague) +- Show time estimates and running totals +- Highlight parallel work opportunities +- Make circuit breaker options explicit + +## Example Task Format + +```markdown +### Task 5: Create User Authentication Middleware + +- **Depends on**: Task 3 (User model), Task 4 (JWT setup) +- **Enables**: Task 6 (Protected routes), Task 7 (User profile API) +- **Estimated time**: 2-3 hours +- **Output**: + - File: `src/middleware/auth.js` + - Function: `authenticateUser(req, res, next)` + - Extracts JWT from header, verifies token, attaches user to req.user +- **Verification**: + - [ ] Unit test: Valid token → req.user populated + - [ ] Unit test: Invalid token → 401 error + - [ ] Unit test: Missing token → 401 error + - [ ] Integration test: Protected route requires auth +- **Files to create/modify**: + - Create: `src/middleware/auth.js` + - Create: `tests/middleware/auth.test.js` + - Modify: `src/routes/index.js` (import middleware) +- **Appetite risk**: Low (standard pattern) +- **Circuit breaker**: If JWT complexity is high, use session-based auth instead (simpler) +``` + +## When to Use Planner + +### Always Use For: +- Complex features (1-2 week or 2-3 week appetite) +- Features with many integration points +- Work involving multiple developers or AI sessions +- High-risk technical work with unknowns +- New team members unfamiliar with codebase + +### Consider Skipping For: +- Simple features (1-3 day appetite, straightforward) +- Well-understood patterns (another CRUD endpoint) +- Solo developer comfortable working from PRPs directly +- Emergency bug fixes requiring immediate action + +## Circuit Breaker Integration + +Monitor task progress and trigger circuit breakers: + +### Warning Signals (AI-Accelerated Timelines) +- **50% time consumed, <40% tasks complete**: Simplify remaining tasks +- **75% time consumed, <60% tasks complete**: Cut P3 tasks immediately +- **90% time consumed, <80% tasks complete**: Cut P2 tasks, simplify P1 + +### Circuit Breaker Actions +1. **First**: Cut all P3 (nice to have) tasks +2. **Next**: Simplify P2 tasks (use existing solutions vs. custom) +3. **Last resort**: Reduce P1 scope to minimum viable user value + +### Preserve Core Value +Never cut: +- Core user workflow and primary value +- Data safety and system stability +- Security basics and user data protection + +Remember: Your job is to make abstract PRPs concrete and executable while maintaining appetite discipline and enabling systematic progress tracking. diff --git a/adce-framework/docs/methodology.md b/adce-framework/docs/methodology.md index 79847f2..9629a4f 100644 --- a/adce-framework/docs/methodology.md +++ b/adce-framework/docs/methodology.md @@ -68,20 +68,58 @@ **Agent**: `architect` - Technical leadership and scope management -### Phase 3: Implementation (Within AI-Accelerated Appetite) +### Phase 3: Task Planning (1-2 hours per PRP) - OPTIONAL +**Goal**: Break PRPs into specific, sequential, dependency-aware implementation tasks + +**When to use**: +- Complex features (1-2 week or 2-3 week appetite) +- Features with many integration points or dependencies +- Work involving multiple developers or AI sessions +- High-risk technical work requiring systematic execution +- Onboarding new team members to the codebase + +**When to skip**: +- Simple features (1-3 day appetite, straightforward implementation) +- Well-understood patterns (e.g., another CRUD endpoint) +- Solo developer comfortable working from PRPs directly +- Emergency fixes requiring immediate action + +**Process**: +1. **Task Decomposition**: Break PRP goal into 5-15 specific, actionable tasks (1-4 hours each) +2. **Dependency Mapping**: Identify which tasks depend on others, create dependency graph +3. **Time Allocation**: Estimate realistic time per task, ensure total ≤ appetite +4. **Verification Planning**: Define concrete pass/fail criteria for each task +5. **Circuit Breaker Preparation**: Mark tasks as P1 (must have), P2 (should have), P3 (nice to have) + +**Output**: Task plan with specific execution steps, dependency graph, time estimates, and verification criteria + +**Agent**: `planner` - Transforms PRPs into granular, executable task breakdowns + +**Benefits**: +- **Systematic execution**: Clear step-by-step path from start to finish +- **Better AI results**: Specific tasks → specific prompts → better code +- **Parallel work**: Multiple developers can work on independent tasks +- **Progress tracking**: Know exactly where you are (7/12 tasks = 58% done) +- **Early risk detection**: If Task 3 takes 2x estimate, trigger circuit breaker +- **Clearer handoffs**: Easy to delegate or resume work later + +### Phase 4: Implementation (Within AI-Accelerated Appetite) **Goal**: Build features within compressed appetite constraints using AI-first development **Process**: -1. **PRP Execution**: Implement using comprehensive context -2. **Progress Tracking**: Hill charts, not task completion -3. **Circuit Breakers**: Cut scope when appetite threatened +1. **PRP or Task Execution**: Implement using comprehensive context (from PRPs or task plans) +2. **Progress Tracking**: Hill charts for PRPs, or task completion for task plans +3. **Circuit Breakers**: Cut scope when appetite threatened (easier with task plans) 4. **Continuous Validation**: Prove it works at each step **Output**: Working software that delivers user value **Agents**: `builder` (UI/frontend) and `deployer` (infrastructure/backend) -### Phase 4: Integration & Validation +**With Task Planning**: Execute tasks sequentially based on dependencies, mark complete with verification +**Without Task Planning**: Work from PRP directly, track progress via hill chart + +### Phase 5: Integration & Validation **Goal**: Ensure everything works together and delivers promised value **Process**: diff --git a/adce-framework/examples/task-breakdown/README.md b/adce-framework/examples/task-breakdown/README.md new file mode 100644 index 0000000..b732575 --- /dev/null +++ b/adce-framework/examples/task-breakdown/README.md @@ -0,0 +1,174 @@ +# Task Breakdown Example - Expense Tracking API + +This example demonstrates how to use the **planner** agent to break down a Product Requirement Prompt (PRP) into specific, dependency-aware implementation tasks. + +## Scenario + +You have a PRP for building an expense tracking API (from the larger user dashboard project). The PRP is comprehensive but still high-level. You need granular, sequential tasks to execute systematically. + +## Workflow Demonstrated + +``` +PRP (High-level goal) → Planner Agent → Task Plan (5-15 specific tasks) +``` + +## Files in This Example + +1. **`prp-expense-api.md`** - The original PRP from architect + - High-level goal and context + - Success criteria and appetite + - Still conceptual ("build API endpoints") + +2. **`task-plan-expense-api.md`** - The task plan created by planner + - 12 specific, sequential tasks + - Dependency graph showing relationships + - Time estimates and verification criteria + - Circuit breaker plan + +3. **`implementation-log.md`** - Execution notes + - Which tasks were completed + - Time tracking (estimate vs. actual) + - Circuit breaker decision made at 75% time + - What got cut and why + +## Key Learnings + +### What Task Planning Provides + +**Before (PRP only)**: +- "Build expense tracking API with CRUD operations" +- Unclear where to start +- Hard to track progress +- Difficult to parallelize work + +**After (Task Plan)**: +- Task 1: Create database schema +- Task 2: Write migration script +- Task 3: Create Expense model +- Task 4: Implement POST /expenses endpoint +- ...and 8 more specific tasks + +### Benefits Demonstrated + +1. **Clear Dependencies**: Can't build API endpoints (Task 4) before creating model (Task 3) +2. **Parallel Opportunities**: UI work (separate tasks) can happen while API is being built +3. **Progress Tracking**: 7/12 tasks complete = 58% done (vs. "mostly done?") +4. **Risk Detection**: Task 3 took 2x estimate → triggered appetite review +5. **Circuit Breaker**: At 75% time, cut Task 11 (advanced filtering) to meet deadline + +### When This Approach Shines + +- **Complex features**: Multiple integration points, many dependencies +- **Team coordination**: Multiple developers working in parallel +- **New codebases**: Team unfamiliar with existing patterns +- **High stakes**: Production systems where mistakes are costly + +### When to Skip It + +- **Simple features**: Single CRUD endpoint, well-understood pattern +- **Solo + experienced**: Developer knows codebase and prefers working from PRPs +- **Time pressure**: Emergency fix needs immediate action + +## How to Use This Example + +### Step 1: Review the PRP +Read `prp-expense-api.md` to understand the high-level goal and constraints. + +### Step 2: See the Task Breakdown +Read `task-plan-expense-api.md` to see how the planner agent transformed the PRP into 12 specific tasks with: +- Clear dependencies +- Time estimates +- Verification criteria +- Risk management + +### Step 3: Study the Execution +Read `implementation-log.md` to see: +- How tasks were completed sequentially +- Where estimates were wrong (and why) +- When circuit breaker was triggered +- Impact of scope reduction + +### Step 4: Apply to Your Work + +When you have a complex PRP: + +```bash +# In Claude Code, with ADCE agents installed +"Use planner to break down the [PRP name] into specific implementation tasks" +``` + +The planner will: +1. Read your PRP +2. Identify logical work chunks +3. Sequence them by dependencies +4. Add time estimates and verification +5. Create a task plan document + +## Prompt Examples + +### Creating the Task Plan +``` +"Use planner to break down the Expense API PRP into specific implementation tasks" +``` + +### Executing Tasks +``` +"Let's implement Task 1 from the expense API task plan: Create database schema for expenses table" + +"Now implement Task 2: Write migration script (depends on Task 1)" +``` + +### Tracking Progress +``` +"Update the task plan - Task 1 complete (took 2 hours, estimated 2-3h). +Moving to Task 2." +``` + +### Triggering Circuit Breaker +``` +"We're at 75% of appetite (5.5/7 days) with only 6/12 tasks complete. +Use planner to update task plan with circuit breaker actions - cut P3 tasks." +``` + +## Comparison: With vs. Without Task Planning + +### Without Task Planning (PRP → Code) +``` +Day 1: "Start building expense API..." (vague, unclear progress) +Day 2: "Working on database and endpoints..." (still vague) +Day 3: "Almost done, just need to finish..." (famous last words) +Day 4: "Found issues, need more time..." (appetite exceeded) +``` + +### With Task Planning (PRP → Tasks → Code) +``` +Day 1: ✅ Task 1, 2, 3 complete (DB schema, migration, model) - 3/12 done +Day 2: ✅ Task 4, 5 complete (POST, GET endpoints) - 5/12 done +Day 3: ✅ Task 6, 7, 8 complete (PUT, DELETE, validation) - 8/12 done +Day 3.5: ⚠️ 75% time used, 8/12 done → Cut Tasks 11, 12 (nice-to-haves) +Day 4: ✅ Task 9, 10 complete (testing, docs) - Core value delivered! +``` + +## Metrics from This Example + +- **Tasks planned**: 12 +- **Tasks completed**: 10 +- **Tasks cut**: 2 (at 75% time checkpoint) +- **Appetite**: 1 week +- **Actual time**: 4.5 days (90% of appetite) +- **Core value delivered**: ✅ Yes +- **Estimates accuracy**: 80% (2 tasks took longer, 3 tasks faster) + +## Next Steps + +After reviewing this example: + +1. Install the planner agent in your project +2. Try it on your next complex PRP +3. Track actual vs. estimated times to improve future planning +4. Share learnings with your team + +For more examples: +- `/examples/user-dashboard/` - Full ADCE workflow without task planning +- `/examples/user-onboarding/` - Medium complexity feature +- `/examples/api-integration/` - High-risk technical work diff --git a/adce-framework/examples/task-breakdown/implementation-log.md b/adce-framework/examples/task-breakdown/implementation-log.md new file mode 100644 index 0000000..78403b8 --- /dev/null +++ b/adce-framework/examples/task-breakdown/implementation-log.md @@ -0,0 +1,475 @@ +# Implementation Log: Expense Tracking API + +This log documents the actual execution of the task plan, showing real progress, time tracking, and circuit breaker decisions made during implementation. + +## Execution Timeline + +**Start Date**: October 20, 2024 +**Target End Date**: October 27, 2024 (1 week) +**Actual End Date**: October 26, 2024 (4.5 days) +**Final Status**: Core value delivered, scope reduced at 75% checkpoint + +--- + +## Day 1: Foundation (October 20) + +### ✅ Task 1: Design Database Schema +- **Time**: 2 hours (estimated 2-3h) +- **Status**: Complete +- **Notes**: + - Schema design went smoothly + - Decided to add composite index on (user_id, date) for performance + - Documented all constraints in schema file +- **Variance**: On target + +### ✅ Task 2: Write Migration Script +- **Time**: 1.5 hours (estimated 1-2h) +- **Status**: Complete +- **Notes**: + - Followed existing migration pattern from users table + - Tested migration up/down successfully in dev database + - Added all indexes as planned +- **Variance**: On target + +### ✅ Task 3: Create Expense Model +- **Time**: 5 hours (estimated 3-4h) +- **Status**: Complete ⚠️ OVER ESTIMATE +- **Notes**: + - Took longer than expected due to decimal validation complexity + - Spent extra time getting custom amount validator working correctly + - Had to debug Sequelize association issue with User model + - All validations working as specified in PRP +- **Variance**: +25% over estimate +- **Impact**: This is our bottleneck task - need to watch time closely + +**Day 1 Total**: 8.5 hours / 8 hours planned (106% - slightly over) +**Tasks Complete**: 3/12 (25%) +**Status**: ⚠️ Yellow - Task 3 took longer, but still on track overall + +--- + +## Day 2: Core API Endpoints (October 21) + +### ✅ Task 4: POST /api/expenses +- **Time**: 2 hours (estimated 2-3h) +- **Status**: Complete +- **Notes**: + - Went faster because model validation already comprehensive + - Followed User API pattern exactly + - Error handling middleware worked perfectly + - Added XSS sanitization to description field +- **Variance**: Faster than expected (-33%) + +### ✅ Task 5: GET /api/expenses with Filtering +- **Time**: 4 hours (estimated 3-4h) +- **Status**: Complete +- **Notes**: + - Date filtering logic took time to get right + - Had to handle edge cases (null dates, invalid formats) + - Added validation for date format before querying + - Tested with various filter combinations +- **Variance**: On target (high end of estimate) + +### ✅ Task 6: PUT /api/expenses/:id +- **Time**: 2.5 hours (estimated 2-3h) +- **Status**: Complete +- **Notes**: + - Straightforward implementation + - Ownership check working correctly + - Reused validation from model +- **Variance**: On target + +**Day 2 Total**: 8.5 hours (cumulative: 17 hours) +**Tasks Complete**: 6/12 (50%) +**Status**: 🟢 Green - Back on track, 42.5% time used with 50% tasks done + +--- + +## Day 3: Remaining Endpoints + Tests (October 22) + +### ✅ Task 7: DELETE /api/expenses/:id +- **Time**: 1 hour (estimated 1-2h) +- **Status**: Complete +- **Notes**: + - Very straightforward, followed PUT pattern + - Ownership check reused from PUT +- **Variance**: Faster than expected (-50%) + +### ✅ Task 8: Integration Tests +- **Time**: 6 hours (estimated 4-5h) ⚠️ OVER ESTIMATE +- **Status**: Complete +- **Notes**: + - Test setup took longer than expected + - Had to configure separate test database + - Created comprehensive test suite covering: + - All CRUD operations (happy path) + - Authentication (401 tests) + - Authorization (403 tests - user can't access other users' expenses) + - Validation (400 tests for invalid data) + - Test coverage: 87% for expense routes/controllers +- **Variance**: +20% over estimate +- **Impact**: Another task over estimate - time pressure building + +**Day 3 Total**: 7 hours (cumulative: 24 hours) +**Tasks Complete**: 8/12 (67%) +**Status**: ⚠️ Yellow - 60% time used with 67% tasks done, but P2 tasks remain + +**Time Check**: 24 hours used / 40 hours budget = 60% consumed +**Progress**: 8 tasks complete (all P1 tasks 1-8 done!) +**Assessment**: Core API is complete and tested. Remaining tasks are all P2/P3. + +--- + +## Day 4: Circuit Breaker Decision (October 23) + +### Morning Review (9am) +**Current Status**: +- Time used: 24 hours (60% of budget) +- P1 tasks: 8/8 complete ✅ +- P2 tasks: 0/3 complete (Tasks 9, 10, 11) +- Remaining time: 16 hours + +**Analysis**: +- Core API functionality complete and tested +- All must-have requirements met +- P2 tasks are enhancements, not critical + +**Decision**: Proceed with P2 tasks but stay alert for 75% checkpoint + +### ⚠️ Task 9: Rate Limiting - STARTED +- **Time**: 3.5 hours (estimated 2-3h) ⚠️ OVER ESTIMATE +- **Status**: Complete +- **Notes**: + - Configured express-rate-limit + - Set limit to 100 requests/hour per user + - Added XSS sanitization with xss-clean + - Tested rate limiting behavior + - Integration more complex than expected (configuring per-user limits) +- **Variance**: +17% over estimate + +**Cumulative Time**: 27.5 hours (69% of budget) + +### Afternoon Review (2pm) - 75% CHECKPOINT APPROACHING + +**Time Status**: 27.5 hours used (approaching 75% threshold at 30 hours) +**Remaining Tasks**: +- Task 10: Validation tests (2-3 hours estimated) +- Task 11: Documentation (2-3 hours estimated) +- Task 12: Deployment prep (2-3 hours estimated) + +**Estimated Total**: 27.5 + 2 + 2 + 2 = 33.5 hours (minimum) to 39.5 hours (maximum) + +**Risk Assessment**: +- If all tasks hit high end of estimates, will exceed appetite +- Task 10 is extra validation testing (nice-to-have) +- Task 11 is documentation (important but can simplify) +- Task 12 is deployment prep (must-have) + +### 🚨 CIRCUIT BREAKER ACTIVATED + +**Trigger**: At 69% time (27.5h/40h) with risk of exceeding appetite + +**Decision Made**: +1. **CUT Task 10 entirely** (extra validation tests) + - Rationale: Already have 87% test coverage from Task 8 + - Impact: Less edge case testing, but core functionality tested + +2. **SIMPLIFY Task 11** (documentation) + - Reduce from comprehensive docs to basic endpoint reference + - Target: 1 hour instead of 2-3 hours + +3. **KEEP Task 12** (deployment prep - must-have) + - Keep at 2-3 hours as planned + +**Revised Plan**: +- Remaining time: 12.5 hours (40 - 27.5) +- Simplified Task 11: 1 hour +- Task 12: 2-3 hours +- Buffer: 8.5 hours (21% of original budget) + +**Stakeholder Communication**: "Core expense API complete with comprehensive tests. Cutting extra validation tests and simplifying docs to ensure we stay within appetite and have buffer for deployment." + +--- + +## Day 4 (continued): Simplified Tasks + +### ✅ Task 11: API Documentation (SIMPLIFIED) +- **Time**: 1 hour (originally estimated 2-3h) +- **Status**: Complete +- **Notes**: + - Created basic endpoint reference with examples + - Included request/response formats + - Listed error codes + - Skipped: Detailed explanations, extensive examples +- **Variance**: Cut 50-66% of original scope + +**Cumulative Time**: 28.5 hours (71% of budget) + +**End of Day 4 Total**: 28.5 hours cumulative +**Tasks Complete**: 9/12 (75%) - but 2 tasks were cut/simplified +**Status**: 🟢 Green - Circuit breaker successful, on track for delivery + +--- + +## Day 5: Final Testing & Deployment (October 24-26) + +### ✅ Task 12: Deployment Preparation +- **Time**: 4 hours (estimated 2-3h) +- **Status**: Complete +- **Notes**: + - Manual testing checklist completed + - Found and fixed 2 minor bugs during manual testing: + - Date validation edge case with timezone + - Error message formatting inconsistency + - Tested migration in staging environment + - Code review completed + - Environment variables documented + - Deployed to staging successfully + - Deployed to production (October 26, 10am) +- **Variance**: +33% over estimate (due to bug fixes) + +### Additional Time: Bug Fixes & Production Deployment +- **Time**: 2 hours +- **Notes**: + - Post-deployment verification + - Fixed CORS issue in production + - Verified all endpoints working correctly + +**Final Cumulative Time**: 34.5 hours (86% of budget) +**Tasks Complete**: 10/12 (83%) +**Tasks Cut**: 2 (Task 10, simplified Task 11) + +--- + +## Final Results + +### Completion Summary + +✅ **Completed Tasks** (10/12): +1. ✅ Design database schema (2h) +2. ✅ Write migration script (1.5h) +3. ✅ Create Sequelize model (5h) ⚠️ over estimate +4. ✅ POST /api/expenses (2h) +5. ✅ GET /api/expenses (4h) +6. ✅ PUT /api/expenses/:id (2.5h) +7. ✅ DELETE /api/expenses/:id (1h) +8. ✅ Integration tests (6h) ⚠️ over estimate +9. ✅ Rate limiting (3.5h) ⚠️ over estimate +11. ✅ API documentation - simplified (1h) +12. ✅ Deployment prep (4h) ⚠️ over estimate + +❌ **Cut Tasks** (1/12): +10. ❌ Extra validation tests - cut at 75% checkpoint + +📝 **Simplified Tasks** (1/12): +11. 📝 Documentation - reduced scope by 50% + +### Time Tracking + +| Category | Estimated | Actual | Variance | +|----------|-----------|--------|----------| +| P1 Tasks (1-8, 12) | 22-29h | 28.5h | +8% over midpoint | +| P2 Tasks (9, 11) | 4h (cut/simplified) | 4.5h | +12.5% | +| Total | 26-33h planned | 34.5h actual | +9% over midpoint | +| Budget | 40h | 34.5h | 86% utilized | + +### Success Criteria Achieved + +✅ **Must Have (P1) - All Delivered**: +- [x] Database schema created and migrated +- [x] Expense model with comprehensive validations +- [x] POST /api/expenses (authenticated, validated) +- [x] GET /api/expenses (user-scoped, date filtering) +- [x] PUT /api/expenses/:id (ownership verified) +- [x] DELETE /api/expenses/:id (ownership verified) +- [x] Integration tests (87% coverage) +- [x] API responds <200ms (avg 45ms in production) + +✅ **Should Have (P2) - Partially Delivered**: +- [x] Date range filtering on GET +- [x] Rate limiting middleware (100/hour per user) +- [x] Basic API documentation +- [❌] Comprehensive validation tests (cut) + +❌ **Nice to Have (P3) - Not Planned**: +- [ ] Advanced filtering (category, amount) +- [ ] Search by description +- [ ] Bulk upload, CSV export +- [ ] Pagination + +### Core Value Delivered: ✅ YES + +**User Value Assessment**: +Users can now: +- ✅ Create expenses with full validation +- ✅ View their expenses filtered by date range +- ✅ Update expense details +- ✅ Delete expenses +- ✅ Trust data security (auth, authorization, rate limiting) + +All core functionality delivered within appetite. + +--- + +## Key Learnings + +### What Went Well + +1. **Task Planning Accuracy**: Overall estimates were good (9% over midpoint) +2. **Dependency Management**: Sequential tasks worked perfectly (no blockers) +3. **Circuit Breaker Discipline**: Cutting Task 10 at 75% checkpoint prevented overrun +4. **Parallel Opportunities**: Could have done Tasks 4-7 in parallel if multiple devs +5. **Test-First Mindset**: Task 8 (tests) caught 3 bugs early +6. **Reuse of Patterns**: Following User API pattern saved time on Tasks 4-7 + +### What Could Improve + +1. **Estimation Challenges**: + - Model creation (Task 3) took 25% longer due to validation complexity + - Integration tests (Task 8) took 20% longer due to test setup + - Deployment (Task 12) took 33% longer due to bug fixes + - Pattern: Complex tasks harder to estimate accurately + +2. **Earlier Circuit Breaker**: + - Could have cut Task 10 earlier (at 50% checkpoint) + - Would have provided more buffer for unknowns + +3. **Buffer Planning**: + - Original plan had 0-30% buffer depending on estimates + - Actual buffer: 14% (5.5 hours unused) + - Recommendation: Always plan for 20% buffer on complex features + +### Estimation Accuracy by Task Type + +| Task Type | Avg Variance | Notes | +|-----------|--------------|-------| +| Foundation (1-3) | +8% | Model validation complexity underestimated | +| CRUD Endpoints (4-7) | -5% | Faster than expected (good patterns) | +| Testing (8) | +20% | Test setup always takes longer | +| Integration (9) | +17% | New libraries need learning time | +| Deployment (12) | +33% | Always find bugs during manual testing | + +### Recommendations for Next Cycle + +1. **Add 20% buffer to complex tasks** (models, tests, deployment) +2. **Trigger circuit breaker at 50% time** if tracking >10% over estimates +3. **Plan parallel work earlier** - could have saved a day with 2 devs +4. **Document gotchas during implementation** for future reference +5. **Time-box testing** - set hard limit on test writing to prevent perfectionism + +--- + +## Circuit Breaker Effectiveness + +### Decision Point Analysis + +**75% Checkpoint (30 hours)**: +- **Status at checkpoint**: 27.5h used, 2-3 tasks remaining +- **Action taken**: Cut Task 10, simplify Task 11 +- **Time saved**: 3-5 hours +- **Impact on user value**: Minimal (core functionality complete) +- **Result**: Finished at 86% of appetite with full core value + +**What if we didn't trigger circuit breaker?** +- Projected time: 39.5 hours (99% of appetite) +- Risk: No buffer for unknowns (bugs, deployment issues) +- Likely outcome: Appetite exceeded OR incomplete deployment + +**Conclusion**: Circuit breaker prevented appetite overrun and provided safety buffer. + +--- + +## Impact Assessment + +### User Value Delivered + +**Core Workflow**: ✅ 100% Complete +- Users can manage expenses end-to-end +- All validation rules enforced +- Data security guaranteed +- Performance acceptable + +**Enhanced Experience**: ✅ 80% Complete +- Date filtering works +- Rate limiting protects system +- Basic docs available +- Missing: Extra validation edge cases (low impact) + +### Technical Quality + +**Code Quality**: ✅ High +- Follows existing patterns +- Well-structured and readable +- Comprehensive error handling +- 87% test coverage + +**Security**: ✅ Strong +- Authentication required +- Authorization enforced (ownership checks) +- Input validation comprehensive +- Rate limiting active +- XSS protection in place + +**Performance**: ✅ Excellent +- Average response time: 45ms +- Indexed queries performing well +- No N+1 query issues + +### Documentation + +**API Docs**: ✅ Good Enough +- All endpoints documented +- Request/response examples included +- Error codes listed +- Missing: Detailed guides (can add post-launch) + +--- + +## Metrics Summary + +| Metric | Target | Actual | Status | +|--------|--------|--------|--------| +| Appetite | 1 week (40h) | 4.5 days (34.5h) | ✅ Under budget | +| Tasks Completed | 12 | 10 (2 cut/simplified) | ✅ Core complete | +| Core Value | Must Have | 100% | ✅ Delivered | +| Test Coverage | >80% | 87% | ✅ Exceeded | +| Performance | <200ms | 45ms avg | ✅ Exceeded | +| Circuit Breakers | As needed | 1 (at 75%) | ✅ Effective | +| Estimate Accuracy | N/A | +9% variance | ✅ Good | + +--- + +## Conclusion + +**Overall Assessment**: ✅ **Successful delivery within appetite** + +**Key Success Factors**: +1. Detailed task breakdown enabled accurate tracking +2. Clear dependencies prevented blockers +3. Circuit breaker discipline kept us on track +4. Good pattern reuse accelerated development +5. Comprehensive testing caught bugs early + +**What Made Task Planning Valuable**: +- **Progress Visibility**: Always knew exactly where we stood (X/12 tasks, Y% time) +- **Risk Detection**: Spotted overruns early (Tasks 3, 8) and adjusted +- **Decision Making**: Circuit breaker decision was data-driven, not guesswork +- **Estimation Learning**: Time tracking will improve future estimates + +**Would We Use Task Planning Again?**: +✅ **Yes** - For any complex feature (>3 day appetite) + +The granular task breakdown was essential for: +- Tracking progress accurately +- Making informed circuit breaker decisions +- Identifying parallel work opportunities +- Learning for future estimates + +**For simpler features** (<3 days), working directly from PRP would be fine. + +--- + +**Deployment**: October 26, 2024 - 10:00 AM +**Status**: ✅ Live in production +**User Feedback**: Positive - core functionality working as expected +**Next Steps**: Monitor usage, collect feedback, plan enhancements (advanced filtering, pagination) for future cycle diff --git a/adce-framework/examples/task-breakdown/prp-expense-api.md b/adce-framework/examples/task-breakdown/prp-expense-api.md new file mode 100644 index 0000000..782c37a --- /dev/null +++ b/adce-framework/examples/task-breakdown/prp-expense-api.md @@ -0,0 +1,172 @@ +# PRP: Expense Tracking API + +## Goal +Build a RESTful API for expense tracking that allows users to create, read, update, and delete expenses with proper validation and error handling. + +## AI-Accelerated Appetite Constraint +**1 week maximum** (5 working days) + +This is part of the larger user dashboard project (2-week total appetite). This PRP covers backend API only. + +## Why This Matters +Users need to track their expenses to understand spending patterns. Without a reliable API, the dashboard UI (built in parallel) has no data to display. This is the foundational piece that enables all financial insights features. + +**Business Value**: Core feature - 70% of users cite expense tracking as primary reason for using the app. + +## What Success Looks Like + +### Must Have (Core Value) +- Users can create expenses with amount, category, date, description +- Users can view all their expenses with filtering by date range +- Users can update expense details +- Users can delete expenses +- All operations properly authenticated and authorized +- Data validation prevents invalid expenses +- Error handling provides clear feedback + +### Nice to Have (Can Cut) +- Bulk expense upload via CSV +- Advanced filtering (by category, amount range) +- Expense search by description +- Export expenses to CSV + +## All Needed Context + +### Documentation & References +- **API Framework**: Express.js (Node.js) + - url: https://expressjs.com/en/guide/routing.html + - why: We use Express for all backend APIs +- **Database**: PostgreSQL with Sequelize ORM + - url: https://sequelize.org/docs/v6/core-concepts/model-basics/ + - why: Pattern for defining models and associations +- **Authentication**: JWT tokens (already implemented) + - file: `src/middleware/auth.js` + - why: Use existing auth middleware for all protected routes + +### Current Codebase Context +- **Existing pattern**: User API follows RESTful conventions + - file: `src/routes/users.js` + - why: Follow same structure for consistency +- **Database connection**: Already configured + - file: `src/config/database.js` + - why: Use existing connection pool +- **Error handling**: Centralized error middleware + - file: `src/middleware/errorHandler.js` + - why: Use consistent error responses across all APIs + +### Known Gotchas +**CRITICAL**: +- Expenses must be scoped to authenticated user (prevent users from seeing others' expenses) +- Use `userId` from JWT token, never trust client-provided userId + +**PERFORMANCE**: +- Filtering expenses can get slow with large datasets +- Add database index on `userId` and `date` columns + +**VALIDATION**: +- Amount must be positive number with max 2 decimal places +- Date must not be in the future +- Category must be from predefined list (groceries, transport, utilities, entertainment, other) + +**SECURITY**: +- Sanitize description field to prevent XSS +- Rate limit expense creation to prevent abuse (max 100/hour per user) + +## AI-Accelerated Implementation Blueprint + +### Days 1-2: Foundation (40% of time) +1. Design database schema for expenses table +2. Create Sequelize model with validations +3. Write and test database migrations +4. Set up basic route structure + +### Days 3-4: Core Functionality (40% of time) +5. Implement CRUD endpoints (POST, GET, PUT, DELETE) +6. Add authentication and authorization middleware +7. Implement validation and error handling +8. Add date range filtering for GET endpoint + +### Day 5: Testing & Documentation (20% of time) +9. Write integration tests for all endpoints +10. Add API documentation +11. Manual testing and bug fixes +12. Code review and deployment preparation + +## Circuit Breaker Points + +### If database model complexity takes more than 4 hours: +→ Use simpler schema without foreign keys initially +→ Cut advanced validations (implement post-launch) +→ Use existing User model pattern without customization + +### If filtering implementation exceeds 6 hours: +→ Implement basic date filtering only +→ Cut category filtering to post-launch +→ Cut amount range filtering to post-launch + +### If testing takes more than 1 day: +→ Focus on happy path tests only +→ Cut edge case testing +→ Manual testing instead of automated for nice-to-haves + +### Scope Reduction Priority: +1. **First to cut**: Bulk upload, CSV export, advanced search (P3) +2. **Next to cut**: Advanced filtering by category/amount (P2) +3. **Last resort**: Simplify validation rules, reduce error handling coverage (P2) + +### Never Cut: +- Basic CRUD operations (create, read, update, delete) +- User authentication and authorization +- Data validation for amount and date +- Basic error handling + +## Validation Loop + +### Level 1: Basic Functionality +```bash +# Create expense +curl -X POST /api/expenses -H "Authorization: Bearer $TOKEN" \ + -d '{"amount": 42.50, "category": "groceries", "date": "2024-10-20", "description": "Weekly shopping"}' + +# Get expenses +curl -X GET /api/expenses -H "Authorization: Bearer $TOKEN" + +# Update expense +curl -X PUT /api/expenses/1 -H "Authorization: Bearer $TOKEN" \ + -d '{"amount": 45.00}' + +# Delete expense +curl -X DELETE /api/expenses/1 -H "Authorization: Bearer $TOKEN" +``` + +### Level 2: Integration Testing +- Verify expenses are scoped to correct user +- Test date range filtering works correctly +- Confirm validation errors return 400 status +- Check unauthorized access returns 401 status + +### Level 3: User Acceptance +- User can create expense and see it in their list +- User can edit expense amount and see update +- User can delete expense and it's removed from list +- User cannot see or modify other users' expenses + +## Success Criteria + +### Must Have (Core Value) +- [ ] POST /api/expenses creates expense (with auth, validation) +- [ ] GET /api/expenses returns user's expenses (with date filtering) +- [ ] PUT /api/expenses/:id updates expense (with auth, validation) +- [ ] DELETE /api/expenses/:id removes expense (with auth) +- [ ] All validation rules enforced (amount, date, category) +- [ ] All operations scoped to authenticated user only +- [ ] Integration tests cover core CRUD operations +- [ ] API responds within 200ms for typical requests + +### Nice to Have (Cut if Needed) +- [ ] Advanced filtering (category, amount range) +- [ ] Search by description (full-text search) +- [ ] Bulk upload via CSV +- [ ] Export to CSV +- [ ] Pagination for large result sets +- [ ] Comprehensive edge case test coverage diff --git a/adce-framework/examples/task-breakdown/task-plan-expense-api.md b/adce-framework/examples/task-breakdown/task-plan-expense-api.md new file mode 100644 index 0000000..1fb8cf6 --- /dev/null +++ b/adce-framework/examples/task-breakdown/task-plan-expense-api.md @@ -0,0 +1,1024 @@ +# Task Plan: Expense Tracking API + +## PRP Reference +**Source PRP**: `prp-expense-api.md` +**Goal**: Build RESTful API for expense tracking with CRUD operations, validation, and proper authentication +**Appetite**: 1 week maximum (5 working days, ~40 hours) + +## Overview + +**Total Tasks**: 12 tasks +**Estimated Time**: 36-40 hours (90-100% of appetite budget) +**Complexity**: Medium +**Parallel Opportunities**: 3 tasks can run concurrently with proper coordination + +### Dependency Graph +``` +Task 1 (Schema Design) + └─→ Task 2 (Migration Script) + └─→ Task 3 (Sequelize Model) + ├─→ Task 4 (POST endpoint) ──→ Task 8 (Integration Tests) + ├─→ Task 5 (GET endpoint) ──→ Task 9 (Auth Testing) + ├─→ Task 6 (PUT endpoint) ──→ Task 10 (Validation Tests) + └─→ Task 7 (DELETE endpoint) + └─→ Task 11 (Documentation) ── Task 12 (Deployment Prep) + +Parallel Opportunity: Tasks 4, 5, 6, 7 can be worked on simultaneously after Task 3 +``` + +### Critical Path +Task 1 → Task 2 → Task 3 → Task 4 → Task 8 → Task 11 → Task 12 +**Duration**: 24-27 hours (60-68% of budget) +**Bottleneck**: Task 3 (Model creation with validations - highest complexity) + +--- + +## Task Breakdown + +### Task 1: Design Database Schema for Expenses Table + +- **Priority**: P1 (Must Have) +- **Depends on**: None (foundational task) +- **Enables**: Task 2 (Migration) +- **Estimated time**: 2-3 hours +- **Complexity**: Low + +**Description**: +Design the PostgreSQL schema for the expenses table including columns, data types, constraints, and indexes. This is the foundation for all data operations. + +**Output/Deliverables**: +- Schema design document or SQL DDL +- Column definitions with data types +- Constraint definitions (NOT NULL, CHECK, etc.) +- Index strategy for performance + +**Files to Create/Modify**: +- Create: `docs/schema/expenses-table.sql` (design reference) +- Document: Schema decisions and rationale + +**Implementation Details**: +```sql +CREATE TABLE expenses ( + id SERIAL PRIMARY KEY, + user_id INTEGER NOT NULL REFERENCES users(id) ON DELETE CASCADE, + amount DECIMAL(10, 2) NOT NULL CHECK (amount > 0), + category VARCHAR(50) NOT NULL CHECK (category IN ('groceries', 'transport', 'utilities', 'entertainment', 'other')), + date DATE NOT NULL CHECK (date <= CURRENT_DATE), + description TEXT, + created_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP, + updated_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP +); + +-- Indexes for performance +CREATE INDEX idx_expenses_user_id ON expenses(user_id); +CREATE INDEX idx_expenses_date ON expenses(date); +CREATE INDEX idx_expenses_user_date ON expenses(user_id, date); +``` + +**Verification Criteria**: +- [ ] Schema includes all required fields (user_id, amount, category, date, description) +- [ ] Constraints enforce business rules (positive amount, valid category, non-future date) +- [ ] Indexes defined for userId and date columns +- [ ] Foreign key relationship to users table defined +- [ ] Schema reviewed against PRP requirements + +**Context & Gotchas**: +- **CRITICAL**: Must include `user_id` foreign key to scope expenses to users +- **PERFORMANCE**: Index on `user_id` + `date` for common query pattern +- Use DECIMAL for amount (not FLOAT) to avoid rounding errors +- Category CHECK constraint prevents invalid values at database level + +**Appetite Risk**: Low +**Risk Factors**: Well-understood task, standard table design + +**Circuit Breaker Plan**: +If exceeds 3 hours: +- **Simplify to**: Basic columns without CHECK constraints (validate in app layer) +- **Alternative**: Copy users table pattern exactly +- **Impact**: Minimal - can add constraints later via migration + +--- + +### Task 2: Write Database Migration Script + +- **Priority**: P1 (Must Have) +- **Depends on**: Task 1 (Schema design complete) +- **Enables**: Task 3 (Model creation) +- **Estimated time**: 1-2 hours +- **Complexity**: Low + +**Description**: +Create a Sequelize migration file that implements the expense table schema designed in Task 1. Includes up/down methods for deployment and rollback. + +**Output/Deliverables**: +- Migration file following Sequelize conventions +- Both `up` (create table) and `down` (drop table) methods +- Successfully runs against development database + +**Files to Create/Modify**: +- Create: `src/migrations/YYYYMMDDHHMMSS-create-expenses-table.js` + +**Implementation Details**: +```javascript +module.exports = { + up: async (queryInterface, Sequelize) => { + await queryInterface.createTable('expenses', { + id: { + type: Sequelize.INTEGER, + primaryKey: true, + autoIncrement: true + }, + user_id: { + type: Sequelize.INTEGER, + allowNull: false, + references: { model: 'users', key: 'id' }, + onDelete: 'CASCADE' + }, + amount: { + type: Sequelize.DECIMAL(10, 2), + allowNull: false + }, + category: { + type: Sequelize.STRING(50), + allowNull: false + }, + date: { + type: Sequelize.DATEONLY, + allowNull: false + }, + description: { + type: Sequelize.TEXT + }, + created_at: { + type: Sequelize.DATE, + defaultValue: Sequelize.NOW + }, + updated_at: { + type: Sequelize.DATE, + defaultValue: Sequelize.NOW + } + }); + + // Add indexes + await queryInterface.addIndex('expenses', ['user_id']); + await queryInterface.addIndex('expenses', ['date']); + await queryInterface.addIndex('expenses', ['user_id', 'date']); + }, + + down: async (queryInterface, Sequelize) => { + await queryInterface.dropTable('expenses'); + } +}; +``` + +**Verification Criteria**: +- [ ] Migration runs successfully with `sequelize db:migrate` +- [ ] Table created with correct columns and types +- [ ] Indexes created successfully +- [ ] Rollback works with `sequelize db:migrate:undo` +- [ ] No errors in migration logs + +**Context & Gotchas**: +- Follow existing migration pattern in `src/migrations/` +- Use `DATEONLY` for date field (not TIMESTAMP) +- **GOTCHA**: Sequelize doesn't support CHECK constraints directly - will validate in model instead + +**Appetite Risk**: Low +**Risk Factors**: Straightforward migration, minimal complexity + +**Circuit Breaker Plan**: +If exceeds 2 hours: +- **Simplify to**: Skip indexes initially (add later) +- **Alternative**: Use raw SQL instead of Sequelize methods +- **Impact**: None for basic functionality + +--- + +### Task 3: Create Expense Sequelize Model with Validations + +- **Priority**: P1 (Must Have) +- **Depends on**: Task 2 (Migration complete, table exists) +- **Enables**: Tasks 4, 5, 6, 7 (All CRUD endpoints) +- **Estimated time**: 3-4 hours +- **Complexity**: Medium + +**Description**: +Create the Sequelize model for Expense with comprehensive validations, associations to User model, and helper methods. This is a critical task that enables all API endpoints. + +**Output/Deliverables**: +- Expense model file with validations +- Association to User model (belongsTo) +- Instance methods if needed +- Model can be imported and used in routes + +**Files to Create/Modify**: +- Create: `src/models/Expense.js` +- Modify: `src/models/index.js` (register model) +- Modify: `src/models/User.js` (add hasMany association) + +**Implementation Details**: +```javascript +// src/models/Expense.js +const { DataTypes } = require('sequelize'); + +module.exports = (sequelize) => { + const Expense = sequelize.define('Expense', { + id: { + type: DataTypes.INTEGER, + primaryKey: true, + autoIncrement: true + }, + userId: { + type: DataTypes.INTEGER, + allowNull: false, + field: 'user_id' + }, + amount: { + type: DataTypes.DECIMAL(10, 2), + allowNull: false, + validate: { + isDecimal: true, + min: 0.01, + max: 9999999.99, + isValidAmount(value) { + if (!/^\d+(\.\d{1,2})?$/.test(value)) { + throw new Error('Amount must have max 2 decimal places'); + } + } + } + }, + category: { + type: DataTypes.STRING(50), + allowNull: false, + validate: { + isIn: [['groceries', 'transport', 'utilities', 'entertainment', 'other']] + } + }, + date: { + type: DataTypes.DATEONLY, + allowNull: false, + validate: { + isDate: true, + notInFuture(value) { + if (new Date(value) > new Date()) { + throw new Error('Date cannot be in the future'); + } + } + } + }, + description: { + type: DataTypes.TEXT, + allowNull: true, + validate: { + len: [0, 500] // Max 500 characters + } + } + }, { + tableName: 'expenses', + underscored: true, + timestamps: true, + createdAt: 'created_at', + updatedAt: 'updated_at' + }); + + Expense.associate = (models) => { + Expense.belongsTo(models.User, { + foreignKey: 'userId', + as: 'user' + }); + }; + + return Expense; +}; +``` + +**Verification Criteria**: +- [ ] Model instantiates without errors +- [ ] Validation test: Valid expense passes all validations +- [ ] Validation test: Negative amount throws error +- [ ] Validation test: Invalid category throws error +- [ ] Validation test: Future date throws error +- [ ] Validation test: Amount with >2 decimals throws error +- [ ] Association to User model works (can access expense.user) +- [ ] Can create and save expense to database + +**Context & Gotchas**: +- **CRITICAL**: Use `userId` from JWT token when creating expenses (never client input) +- **VALIDATION**: All validation rules from PRP must be enforced here +- **SECURITY**: Sanitize description field to prevent XSS (use validator library) +- Follow User model pattern in `src/models/User.js` for consistency + +**Appetite Risk**: Medium (highest complexity so far) +**Risk Factors**: +- Complex validation logic +- Testing all validation scenarios +- Getting decimal validation exactly right + +**Circuit Breaker Plan**: +If exceeds 4 hours: +- **Simplify to**: Basic validations only (amount > 0, category in list, date not null) +- **Cut**: Custom validation messages, advanced decimal validation +- **Impact**: Less user-friendly errors, some edge cases not caught + +--- + +### Task 4: Implement POST /api/expenses Endpoint + +- **Priority**: P1 (Must Have) +- **Depends on**: Task 3 (Model ready) +- **Enables**: Task 8 (Integration tests) +- **Estimated time**: 2-3 hours +- **Complexity**: Medium + +**Description**: +Create the POST endpoint for creating new expenses. Includes authentication, input validation, and proper error handling following existing API patterns. + +**Output/Deliverables**: +- POST /api/expenses route handler +- Input validation middleware +- Authentication middleware applied +- Error handling for validation failures +- Returns 201 Created with expense data + +**Files to Create/Modify**: +- Create: `src/routes/expenses.js` +- Create: `src/controllers/expenseController.js` +- Modify: `src/app.js` (register expenses routes) + +**Implementation Details**: +```javascript +// src/controllers/expenseController.js +const { Expense } = require('../models'); + +exports.createExpense = async (req, res, next) => { + try { + const { amount, category, date, description } = req.body; + const userId = req.user.id; // From JWT auth middleware + + const expense = await Expense.create({ + userId, + amount, + category, + date, + description + }); + + res.status(201).json({ + success: true, + data: expense + }); + } catch (error) { + if (error.name === 'SequelizeValidationError') { + return res.status(400).json({ + success: false, + error: error.errors.map(e => e.message) + }); + } + next(error); + } +}; + +// src/routes/expenses.js +const express = require('express'); +const router = express.Router(); +const { authenticate } = require('../middleware/auth'); +const { createExpense } = require('../controllers/expenseController'); + +router.post('/', authenticate, createExpense); + +module.exports = router; +``` + +**Verification Criteria**: +- [ ] POST request with valid data creates expense (returns 201) +- [ ] Created expense has correct userId from JWT token +- [ ] Invalid data returns 400 with validation errors +- [ ] Missing auth token returns 401 Unauthorized +- [ ] Response format matches API conventions +- [ ] Database record actually created (check with DB query) + +**Context & Gotchas**: +- **CRITICAL**: Use `req.user.id` from auth middleware, NEVER `req.body.userId` +- **SECURITY**: Sanitize description field before saving +- Follow error handling pattern in `src/middleware/errorHandler.js` +- Use existing authentication middleware from `src/middleware/auth.js` + +**Appetite Risk**: Medium +**Risk Factors**: Getting error handling right, testing auth flows + +**Circuit Breaker Plan**: +If exceeds 3 hours: +- **Simplify to**: Basic error handling only (no custom validation messages) +- **Cut**: Input sanitization (add post-launch) +- **Impact**: Less secure, less user-friendly errors + +--- + +### Task 5: Implement GET /api/expenses Endpoint with Filtering + +- **Priority**: P1 (Must Have) +- **Depends on**: Task 3 (Model ready) +- **Enables**: Task 8 (Integration tests) +- **Estimated time**: 3-4 hours +- **Complexity**: Medium + +**Description**: +Create GET endpoint that returns authenticated user's expenses with optional date range filtering. Must be scoped to user's expenses only. + +**Output/Deliverables**: +- GET /api/expenses route handler +- Query parameter parsing for date filtering (startDate, endDate) +- Returns expenses scoped to authenticated user +- Proper error handling and validation + +**Files to Create/Modify**: +- Modify: `src/controllers/expenseController.js` (add getExpenses function) +- Modify: `src/routes/expenses.js` (add GET route) + +**Implementation Details**: +```javascript +exports.getExpenses = async (req, res, next) => { + try { + const userId = req.user.id; + const { startDate, endDate } = req.query; + + const where = { userId }; + + // Add date filtering if provided + if (startDate || endDate) { + where.date = {}; + if (startDate) { + where.date[Op.gte] = startDate; + } + if (endDate) { + where.date[Op.lte] = endDate; + } + } + + const expenses = await Expense.findAll({ + where, + order: [['date', 'DESC'], ['created_at', 'DESC']] + }); + + res.status(200).json({ + success: true, + count: expenses.length, + data: expenses + }); + } catch (error) { + next(error); + } +}; + +// Route +router.get('/', authenticate, getExpenses); +``` + +**Verification Criteria**: +- [ ] GET without filters returns all user's expenses +- [ ] GET with startDate filters correctly +- [ ] GET with endDate filters correctly +- [ ] GET with both dates returns correct range +- [ ] User only sees their own expenses (never other users') +- [ ] Results ordered by date descending +- [ ] Invalid date format returns 400 error +- [ ] Missing auth returns 401 + +**Context & Gotchas**: +- **CRITICAL**: Always filter by userId - NEVER show other users' expenses +- **PERFORMANCE**: Use indexed columns (userId, date) for filtering +- Validate date format before querying (use date validation library) +- Consider adding pagination if dataset grows (not P1, but document as future enhancement) + +**Appetite Risk**: Medium +**Risk Factors**: +- Date filtering logic complexity +- Testing various filter combinations +- Edge cases (invalid dates, future dates, etc.) + +**Circuit Breaker Plan**: +If exceeds 4 hours: +- **Simplify to**: Return all expenses without filtering +- **Cut**: Date range filtering (add post-launch) +- **Impact**: Users can't filter by date (must load all expenses) + +--- + +### Task 6: Implement PUT /api/expenses/:id Endpoint + +- **Priority**: P1 (Must Have) +- **Depends on**: Task 3 (Model ready) +- **Enables**: Task 8 (Integration tests) +- **Estimated time**: 2-3 hours +- **Complexity**: Medium + +**Description**: +Create PUT endpoint for updating existing expenses. Must verify user owns the expense before allowing update. + +**Output/Deliverables**: +- PUT /api/expenses/:id route handler +- Ownership verification (expense.userId === req.user.id) +- Update validation through model +- Returns updated expense data + +**Files to Create/Modify**: +- Modify: `src/controllers/expenseController.js` (add updateExpense function) +- Modify: `src/routes/expenses.js` (add PUT route) + +**Implementation Details**: +```javascript +exports.updateExpense = async (req, res, next) => { + try { + const { id } = req.params; + const userId = req.user.id; + const { amount, category, date, description } = req.body; + + const expense = await Expense.findByPk(id); + + if (!expense) { + return res.status(404).json({ + success: false, + error: 'Expense not found' + }); + } + + // CRITICAL: Verify ownership + if (expense.userId !== userId) { + return res.status(403).json({ + success: false, + error: 'Not authorized to update this expense' + }); + } + + await expense.update({ + amount, + category, + date, + description + }); + + res.status(200).json({ + success: true, + data: expense + }); + } catch (error) { + if (error.name === 'SequelizeValidationError') { + return res.status(400).json({ + success: false, + error: error.errors.map(e => e.message) + }); + } + next(error); + } +}; + +router.put('/:id', authenticate, updateExpense); +``` + +**Verification Criteria**: +- [ ] Valid update modifies expense and returns updated data +- [ ] Update triggers model validations +- [ ] Non-existent ID returns 404 +- [ ] User cannot update another user's expense (403 Forbidden) +- [ ] Invalid data returns 400 with errors +- [ ] Missing auth returns 401 +- [ ] Updated_at timestamp changes + +**Context & Gotchas**: +- **CRITICAL**: Always verify `expense.userId === req.user.id` before updating +- **SECURITY**: Don't allow updating userId (model should not allow it) +- Validate all fields through model validation +- Return 403 Forbidden (not 404) when user doesn't own expense (security best practice) + +**Appetite Risk**: Low +**Risk Factors**: Mostly straightforward, follows standard pattern + +**Circuit Breaker Plan**: +If exceeds 3 hours: +- **Simplify to**: Allow updating amount only (not all fields) +- **Impact**: Less flexible updates, but core functionality preserved + +--- + +### Task 7: Implement DELETE /api/expenses/:id Endpoint + +- **Priority**: P1 (Must Have) +- **Depends on**: Task 3 (Model ready) +- **Enables**: Task 8 (Integration tests) +- **Estimated time**: 1-2 hours +- **Complexity**: Low + +**Description**: +Create DELETE endpoint for removing expenses. Must verify ownership before allowing deletion. + +**Output/Deliverables**: +- DELETE /api/expenses/:id route handler +- Ownership verification +- Returns success confirmation + +**Files to Create/Modify**: +- Modify: `src/controllers/expenseController.js` (add deleteExpense function) +- Modify: `src/routes/expenses.js` (add DELETE route) + +**Implementation Details**: +```javascript +exports.deleteExpense = async (req, res, next) => { + try { + const { id } = req.params; + const userId = req.user.id; + + const expense = await Expense.findByPk(id); + + if (!expense) { + return res.status(404).json({ + success: false, + error: 'Expense not found' + }); + } + + if (expense.userId !== userId) { + return res.status(403).json({ + success: false, + error: 'Not authorized to delete this expense' + }); + } + + await expense.destroy(); + + res.status(200).json({ + success: true, + message: 'Expense deleted successfully' + }); + } catch (error) { + next(error); + } +}; + +router.delete('/:id', authenticate, deleteExpense); +``` + +**Verification Criteria**: +- [ ] Valid delete removes expense from database +- [ ] Non-existent ID returns 404 +- [ ] User cannot delete another user's expense (403) +- [ ] Missing auth returns 401 +- [ ] Deleted record no longer in database + +**Context & Gotchas**: +- **CRITICAL**: Verify ownership before deletion +- Consider soft delete vs. hard delete (use hard delete for now, document for future) +- Follow same auth/ownership pattern as PUT endpoint + +**Appetite Risk**: Low +**Risk Factors**: Straightforward implementation + +**Circuit Breaker Plan**: +If exceeds 2 hours: +- **Simplify to**: Use raw SQL delete +- **Impact**: None + +--- + +### Task 8: Write Integration Tests for CRUD Operations + +- **Priority**: P1 (Must Have) +- **Depends on**: Tasks 4, 5, 6, 7 (All endpoints implemented) +- **Enables**: Task 11 (Documentation) +- **Estimated time**: 4-5 hours +- **Complexity**: Medium + +**Description**: +Create comprehensive integration tests covering all CRUD operations, authentication, and authorization scenarios. + +**Output/Deliverables**: +- Test file with all endpoint tests +- Test database setup/teardown +- Mock authentication tokens +- All tests passing + +**Files to Create/Modify**: +- Create: `tests/integration/expenses.test.js` +- Modify: `tests/setup.js` (add test data helpers) + +**Implementation Details**: +```javascript +describe('Expense API Integration Tests', () => { + let authToken; + let userId; + let otherUserToken; + + beforeAll(async () => { + // Setup test users and auth tokens + }); + + describe('POST /api/expenses', () => { + test('creates expense with valid data', async () => { + // Test implementation + }); + + test('returns 400 for invalid amount', async () => { + // Test implementation + }); + + test('returns 401 without auth token', async () => { + // Test implementation + }); + + // More tests... + }); + + describe('GET /api/expenses', () => { + test('returns user expenses only', async () => { + // Verify scoping to user + }); + + test('filters by date range', async () => { + // Test filtering + }); + + // More tests... + }); + + // PUT and DELETE tests... +}); +``` + +**Verification Criteria**: +- [ ] All happy path tests pass (create, read, update, delete) +- [ ] Authentication tests pass (401 for missing token) +- [ ] Authorization tests pass (403 for wrong user) +- [ ] Validation tests pass (400 for invalid data) +- [ ] Test coverage >80% for expense routes/controllers +- [ ] Tests run in isolation (no dependencies between tests) + +**Context & Gotchas**: +- Use separate test database (configure in test env) +- Clean up test data after each test +- Mock JWT tokens for authentication +- Test both success and failure scenarios + +**Appetite Risk**: Medium +**Risk Factors**: +- Setting up test environment +- Creating comprehensive test scenarios +- Debugging failing tests + +**Circuit Breaker Plan**: +If exceeds 5 hours: +- **Simplify to**: Happy path tests only +- **Cut**: Edge case testing, validation error scenarios +- **Impact**: Less test coverage, potential bugs in edge cases + +--- + +### Task 9: Add Rate Limiting and Security Middleware + +- **Priority**: P2 (Should Have) +- **Depends on**: Tasks 4, 5, 6, 7 (Endpoints exist) +- **Enables**: Task 10 (Validation tests) +- **Estimated time**: 2-3 hours +- **Complexity**: Low + +**Description**: +Add rate limiting to prevent abuse and input sanitization for XSS protection. + +**Output/Deliverables**: +- Rate limiting middleware (100 requests/hour per user) +- Input sanitization for description field +- Applied to all expense endpoints + +**Files to Create/Modify**: +- Create: `src/middleware/rateLimiter.js` +- Modify: `src/routes/expenses.js` (apply middleware) +- Install: express-rate-limit, xss-clean packages + +**Verification Criteria**: +- [ ] Rate limit blocks after 100 requests/hour +- [ ] Rate limit returns 429 Too Many Requests +- [ ] XSS attempts in description are sanitized +- [ ] Normal requests not affected + +**Appetite Risk**: Low +**Risk Factors**: Well-defined task, libraries handle complexity + +**Circuit Breaker Plan**: +If exceeds 3 hours: +- **Cut entirely**: Add post-launch +- **Impact**: Potential abuse, XSS vulnerability (mitigated by frontend validation) + +--- + +### Task 10: Add Input Validation Tests + +- **Priority**: P2 (Should Have) +- **Depends on**: Task 8 (Integration tests exist) +- **Enables**: Task 11 (Documentation) +- **Estimated time**: 2-3 hours +- **Complexity**: Low + +**Description**: +Comprehensive tests for all validation rules and edge cases. + +**Output/Deliverables**: +- Tests for all validation scenarios +- Edge case coverage +- All tests passing + +**Verification Criteria**: +- [ ] Test: Amount with 3 decimals rejected +- [ ] Test: Negative amount rejected +- [ ] Test: Invalid category rejected +- [ ] Test: Future date rejected +- [ ] Test: Missing required fields rejected +- [ ] Test: Description >500 chars rejected + +**Appetite Risk**: Low +**Circuit Breaker Plan**: +If exceeds 3 hours: +- **Cut**: Document validation rules instead of testing all + +--- + +### Task 11: Write API Documentation + +- **Priority**: P2 (Should Have) +- **Depends on**: Tasks 4-7 (All endpoints implemented) +- **Enables**: Task 12 (Deployment) +- **Estimated time**: 2-3 hours +- **Complexity**: Low + +**Description**: +Document all API endpoints with request/response examples, authentication requirements, and error codes. + +**Output/Deliverables**: +- API documentation in Markdown +- Request/response examples +- Error code reference + +**Files to Create/Modify**: +- Create: `docs/api/expenses.md` + +**Verification Criteria**: +- [ ] All endpoints documented +- [ ] Examples for all CRUD operations +- [ ] Error codes listed +- [ ] Authentication explained + +**Appetite Risk**: Low +**Circuit Breaker Plan**: +If exceeds 3 hours: +- **Simplify to**: Basic endpoint list only +- **Cut**: Detailed examples + +--- + +### Task 12: Deployment Preparation and Final Testing + +- **Priority**: P1 (Must Have) +- **Depends on**: Tasks 8, 11 (Tests passing, docs complete) +- **Enables**: Production deployment +- **Estimated time**: 2-3 hours +- **Complexity**: Low + +**Description**: +Final manual testing, code review, and preparation for deployment to production. + +**Output/Deliverables**: +- Manual test checklist completed +- Code reviewed +- Environment variables documented +- Migration ready for production + +**Verification Criteria**: +- [ ] Manual testing checklist complete +- [ ] All automated tests passing +- [ ] Code reviewed by peer +- [ ] Environment setup documented +- [ ] Migration tested in staging + +**Appetite Risk**: Low +**Circuit Breaker Plan**: +If time runs out: +- **Simplify to**: Deploy to staging only (not production) + +--- + +## Progress Tracking + +### Task Checklist +- [ ] Task 1: Design database schema - Est: 2-3h - Status: Not Started +- [ ] Task 2: Write migration script - Est: 1-2h - Status: Not Started +- [ ] Task 3: Create Sequelize model - Est: 3-4h - Status: Not Started +- [ ] Task 4: POST /api/expenses - Est: 2-3h - Status: Not Started +- [ ] Task 5: GET /api/expenses - Est: 3-4h - Status: Not Started +- [ ] Task 6: PUT /api/expenses/:id - Est: 2-3h - Status: Not Started +- [ ] Task 7: DELETE /api/expenses/:id - Est: 1-2h - Status: Not Started +- [ ] Task 8: Integration tests - Est: 4-5h - Status: Not Started +- [ ] Task 9: Rate limiting (P2) - Est: 2-3h - Status: Not Started +- [ ] Task 10: Validation tests (P2) - Est: 2-3h - Status: Not Started +- [ ] Task 11: API documentation (P2) - Est: 2-3h - Status: Not Started +- [ ] Task 12: Deployment prep - Est: 2-3h - Status: Not Started + +### Time Budget Status +- **Total Budget**: 40 hours (1 week @ 8hrs/day) +- **Committed Time**: 28-40 hours +- **P1 Tasks**: 22-29 hours (core must-haves) +- **P2 Tasks**: 6-11 hours (nice-to-haves, can cut) +- **Buffer**: 0-12 hours (0-30% buffer) + +### Circuit Breaker Thresholds +- ⚠️ **50% Time Warning** (20 hrs): Should have Tasks 1-5 complete (7 tasks minimum) +- ⚠️ **75% Time Warning** (30 hrs): Should have Tasks 1-8 complete, consider cutting P2 tasks +- 🚨 **90% Time Critical** (36 hrs): Must have P1 tasks complete, cut all P2 + +--- + +## Parallel Work Opportunities + +### After Task 3 Completes (Model ready): +**Developer A**: Tasks 4 → 5 (POST, GET endpoints) +**Developer B**: Tasks 6 → 7 (PUT, DELETE endpoints) + +Both can work simultaneously with no conflicts. + +### After Tasks 4-7 Complete: +**Developer A**: Task 8 (Integration tests) +**Developer B**: Task 9 (Rate limiting) + +Can work in parallel. + +--- + +## Circuit Breaker Execution Plan + +### At 50% time (20 hours) with <5 tasks complete: +**Warning Status - Review Progress** +- Identify which tasks took longer than expected +- Simplify remaining tasks where possible +- Put P2 tasks (9, 10, 11) on watch list + +### At 75% time (30 hours) with <8 tasks complete: +**Critical - Execute Circuit Breaker** +**Actions**: +1. **Cut Tasks 9 & 10 immediately** (rate limiting, extra validation tests) +2. Simplify Task 11 (basic docs only) +3. Focus exclusively on P1 tasks + +**Justification**: Core CRUD API is more valuable than rate limiting or exhaustive tests + +### At 90% time (36 hours) with <10 tasks complete: +**Emergency Mode** +**Actions**: +1. Cut Task 11 entirely (no docs) +2. Minimal testing in Task 8 (happy path only) +3. Deploy basic working API + +**Minimum Viable**: Tasks 1-7 + basic tests = functional API + +--- + +## Success Criteria + +### Must Have (P1 - Cannot ship without) +- [ ] Database schema created and migrated +- [ ] Expense model with validations +- [ ] POST /api/expenses works (authenticated) +- [ ] GET /api/expenses works (filtered by user) +- [ ] PUT /api/expenses/:id works (with ownership check) +- [ ] DELETE /api/expenses/:id works (with ownership check) +- [ ] Basic integration tests passing +- [ ] API responds <200ms for typical requests + +### Should Have (P2 - Important but can cut) +- [ ] Date range filtering on GET +- [ ] Rate limiting middleware +- [ ] Comprehensive validation tests +- [ ] API documentation + +### Nice to Have (P3 - Already cut from PRP) +- [ ] Advanced filtering (category, amount) +- [ ] Search by description +- [ ] Bulk upload +- [ ] CSV export +- [ ] Pagination + +--- + +## Notes & Learnings + +### Time Tracking +(Update as tasks complete) + +| Task | Estimated | Actual | Variance | Notes | +|------|-----------|--------|----------|-------| +| Task 1 | 2-3h | - | - | - | +| Task 2 | 1-2h | - | - | - | +| ... | ... | ... | ... | ... | + +### Circuit Breaker Decisions +(Document what was cut and when) + +--- + +**Status**: Ready to execute +**Next Action**: Begin Task 1 (Schema Design) diff --git a/adce-framework/install.js b/adce-framework/install.js index c550117..795566b 100755 --- a/adce-framework/install.js +++ b/adce-framework/install.js @@ -76,7 +76,7 @@ class ADCEInstaller { const agentsDir = path.join(this.projectRoot, '.claude', 'agents'); await fs.ensureDir(agentsDir); - const agentFiles = ['shaper.md', 'architect.md', 'builder.md', 'deployer.md']; + const agentFiles = ['shaper.md', 'architect.md', 'planner.md', 'builder.md', 'deployer.md']; for (const file of agentFiles) { const source = path.join(this.frameworkRoot, 'agents', file); @@ -135,10 +135,19 @@ npm run build \`\`\` ## ADCE Workflow + +### Standard Flow (Simple Features) 1. Use shaper to create appetite-bounded pitches 2. Use architect to review feasibility and create PRPs 3. Use builder and deployer to implement features -4. Track progress with hill charts, not task completion +4. Track progress with hill charts + +### Extended Flow (Complex Features) +1. Use shaper to create appetite-bounded pitches +2. Use architect to review feasibility and create PRPs +3. Use planner to break PRPs into specific tasks (optional) +4. Use builder and deployer to execute tasks +5. Track progress with task completion `; await fs.writeFile(claudeMd, template); console.log(chalk.green(' ✓ Created CLAUDE.md')); diff --git a/adce-framework/templates/task-plan/task-plan-base.md b/adce-framework/templates/task-plan/task-plan-base.md new file mode 100644 index 0000000..4df47b6 --- /dev/null +++ b/adce-framework/templates/task-plan/task-plan-base.md @@ -0,0 +1,319 @@ +# Task Plan: [Feature Name] + +## PRP Reference +**Source PRP**: [Link or file path to the PRP this implements] +**Goal**: [One-sentence summary of what this accomplishes] +**Appetite**: [Time budget from PRP - e.g., "3 days maximum", "1.5 weeks maximum"] + +## Overview + +**Total Tasks**: [Number] tasks +**Estimated Time**: [Sum of all task estimates] hours ([X] days) +**Complexity**: [Low/Medium/High] +**Parallel Opportunities**: [Number] tasks can run concurrently + +### Dependency Graph +``` +[Visual representation of task dependencies using ASCII art] + +Example: +Task 1 (Foundation) + ├─→ Task 2 (Core Logic) ──→ Task 5 (Integration) + │ └─→ Task 4 (API) ──→ Task 6 (Testing) + └─→ Task 3 (UI Layer) ──→ Task 7 (Polish) + +Legend: +→ = Dependency (must complete before) +├ = Branches (parallel work possible) +``` + +### Critical Path +[Identify the longest sequence of dependent tasks] +- Task 1 → Task 2 → Task 5 → Task 6 → [Duration: X hours] +- **Bottleneck**: Task 2 (highest risk/longest duration) + +--- + +## Task Breakdown + +### Task 1: [Specific action with concrete outcome] + +- **Priority**: P1 (Must Have) / P2 (Should Have) / P3 (Nice to Have) +- **Depends on**: None / Task X, Task Y +- **Enables**: Task X, Task Y, Task Z +- **Estimated time**: [X-Y hours] +- **Complexity**: Low / Medium / High + +**Description**: +[2-3 sentence description of what this task accomplishes and why it's needed] + +**Output/Deliverables**: +- [Specific file, feature, or component created] +- [Concrete functionality implemented] +- [Tests or documentation produced] + +**Files to Create/Modify**: +- Create: `path/to/new/file.js` +- Modify: `path/to/existing/file.js` (add function X, update class Y) +- Create: `tests/path/to/test.test.js` + +**Implementation Details**: +``` +[Code snippet, API endpoint spec, or pseudocode showing what to build] + +Example: +- Function signature: `async function getUserById(userId)` +- Returns: `{ id, name, email, createdAt }` +- Error handling: Throw 404 if user not found +``` + +**Verification Criteria**: +- [ ] [Specific test that must pass] +- [ ] [Integration check that proves it works] +- [ ] [Manual verification step if applicable] +- [ ] [Performance or quality benchmark if relevant] + +**Context & Gotchas**: +- [Important implementation detail to remember] +- [Known pitfall to avoid] +- [External dependency or API quirk] + +**Appetite Risk**: Low / Medium / High +**Risk Factors**: [What could make this take longer than estimated] + +**Circuit Breaker Plan**: +If this task exceeds [X hours] or hits complexity: +- **Simplify to**: [Reduced scope version] +- **Alternative approach**: [Simpler way to deliver core value] +- **Impact of cutting**: [What user value is lost] + +--- + +### Task 2: [Specific action with concrete outcome] + +[Repeat the above structure for each task] + +--- + +### Task 3: [Specific action with concrete outcome] + +[Continue for all tasks...] + +--- + +## Progress Tracking + +### Task Checklist +- [ ] Task 1: [Task name] - Est: X hrs - Status: Not Started / In Progress / Complete +- [ ] Task 2: [Task name] - Est: Y hrs - Status: Not Started / In Progress / Complete +- [ ] Task 3: [Task name] - Est: Z hrs - Status: Not Started / In Progress / Complete +[Continue for all tasks...] + +### Time Budget Status +- **Total Budget**: [X hours from appetite] +- **Committed Time**: [Sum of estimates] hours +- **Buffer**: [Budget - Committed] hours ([X]% buffer) +- **Consumed**: [Actual time spent] hours +- **Remaining**: [Budget - Consumed] hours + +### Circuit Breaker Thresholds +- ⚠️ **50% Time Warning**: At [X hours], should have [Y] tasks complete +- ⚠️ **75% Time Warning**: At [Z hours], should have [W] tasks complete +- 🚨 **90% Time Critical**: At [A hours], must cut P3 tasks if not [B]% complete + +### Current Status +- **Progress**: [X/Total] tasks complete ([Y]%) +- **Time Used**: [Z] hours ([W]% of budget) +- **On Track**: Yes / No / At Risk +- **Circuit Breaker Status**: Green / Yellow / Red + +--- + +## Parallel Work Opportunities + +### Concurrent Task Groups +**Group 1** (can work simultaneously after Task 1 completes): +- Task 2: [Description] +- Task 3: [Description] + +**Group 2** (can work simultaneously after Task 2 and Task 3 complete): +- Task 4: [Description] +- Task 5: [Description] + +### Developer Allocation +If multiple developers or AI sessions: +- **Developer A / Session 1**: Tasks 1 → 2 → 5 → 6 +- **Developer B / Session 2**: Tasks 3 → 4 → 7 + +--- + +## Implementation Strategy + +### Phase 1: Foundation ([X]% of time) +Tasks: [List foundational tasks] +- Build core data structures +- Set up infrastructure +- Create base components + +### Phase 2: Core Functionality ([Y]% of time) +Tasks: [List core feature tasks] +- Implement main user workflow +- Build critical business logic +- Integrate components + +### Phase 3: Integration & Testing ([Z]% of time) +Tasks: [List integration tasks] +- Connect all components +- Run integration tests +- Validate user acceptance criteria + +### Phase 4: Polish & Deploy ([W]% of time) +Tasks: [List finishing tasks] +- UI polish and edge cases +- Performance optimization +- Production deployment + +--- + +## Risk Management + +### High-Risk Tasks +1. **Task X**: [Why it's risky] + - **Mitigation**: [How to reduce risk] + - **Contingency**: [What to do if it fails] + +2. **Task Y**: [Why it's risky] + - **Mitigation**: [How to reduce risk] + - **Contingency**: [What to do if it fails] + +### Unknown Complexity Areas +- [Area where time estimate is uncertain] + - **Spike plan**: Timebox investigation to [X hours] + - **Decision point**: Continue or pivot after spike + +### External Dependencies +- [Third-party API, library, or service this depends on] + - **Risk**: [What could go wrong] + - **Backup plan**: [Alternative approach] + +--- + +## Circuit Breaker Execution Plan + +### If at 50% time with <40% tasks complete: +**Actions**: +1. Simplify remaining P2 and P3 tasks +2. Review all estimates and cut buffer time +3. Focus only on critical path tasks + +**Tasks to Simplify**: +- Task X: [Reduced scope version] +- Task Y: [Simpler alternative] + +### If at 75% time with <60% tasks complete: +**Actions**: +1. **Cut all P3 tasks immediately** +2. Simplify P2 tasks to bare minimum +3. Alert stakeholders about scope reduction + +**Tasks to Cut**: +- Task X: [Impact of cutting] +- Task Y: [Impact of cutting] + +### If at 90% time with <80% tasks complete: +**Actions**: +1. **Emergency scope reduction** +2. Cut even P2 tasks if needed +3. Ship minimum viable version + +**Minimum Viable Scope**: +- Keep: [Core P1 tasks that deliver user value] +- Cut: [Everything else] +- Impact: [What users won't get] + +--- + +## Success Criteria + +### Must Achieve (P1 - Cannot ship without) +- [ ] [Core user workflow works end-to-end] +- [ ] [Critical business logic is correct] +- [ ] [Data safety and security requirements met] +- [ ] [System stability under normal load] + +### Should Achieve (P2 - Important but can simplify) +- [ ] [Enhanced user experience feature] +- [ ] [Performance optimization] +- [ ] [Additional validation or error handling] + +### Nice to Achieve (P3 - Polish, first to cut) +- [ ] [UI polish and micro-interactions] +- [ ] [Advanced edge case handling] +- [ ] [Optional convenience features] + +--- + +## Validation & Testing + +### Unit Testing +- Task X requires: [Specific unit tests] +- Task Y requires: [Specific unit tests] +- Coverage target: [X]% + +### Integration Testing +- [ ] [End-to-end user workflow test] +- [ ] [API integration test] +- [ ] [Database integration test] + +### User Acceptance Testing +- [ ] [Manual test scenario 1] +- [ ] [Manual test scenario 2] +- [ ] [Performance benchmark check] + +### Quality Gates +Before marking plan complete: +- [ ] All P1 tasks verified complete +- [ ] Integration tests passing +- [ ] User acceptance criteria met +- [ ] No critical bugs or blockers + +--- + +## Notes & Learnings + +### Implementation Notes +[Track key decisions, deviations from plan, and lessons learned during execution] + +### Time Tracking +[Record actual time spent vs. estimates to improve future planning] + +| Task | Estimated | Actual | Variance | Notes | +|------|-----------|--------|----------|-------| +| Task 1 | 2h | 2.5h | +25% | [Reason for difference] | +| Task 2 | 3h | 2h | -33% | [Reason for difference] | + +### What Went Well +- [Things that worked better than expected] +- [AI acceleration wins] +- [Good planning decisions] + +### What Could Improve +- [Estimation misses and why] +- [Unexpected complexity sources] +- [Process improvements for next time] + +### Circuit Breaker Decisions Made +- [What got cut and when] +- [Impact on user value] +- [Lessons for future appetite setting] + +--- + +## Completion Status + +- **Start Date**: [Date] +- **Target End Date**: [Date based on appetite] +- **Actual End Date**: [Date] +- **Final Status**: Complete / Partially Complete / Scope Reduced +- **User Value Delivered**: [Assessment of whether core value was achieved] +- **Lessons Learned**: [Key takeaways for next cycle] From 9727f1ace33e76198ab8deaea5f49f1480f1baca Mon Sep 17 00:00:00 2001 From: Claude Date: Sun, 26 Oct 2025 12:20:39 +0000 Subject: [PATCH 6/9] Fix npm installation and improve README formatting Fixes: - Fixed "could not determine executable to run" error - Removed reference to non-existent tools/cli.js - Simplified bin configuration to point to install.js - Updated installation command from 'npx adce-framework install' to 'npx adce-framework' README Improvements: - Added planner agent to workflow examples - Fixed section headers (Why ADCE Works, Real Results, etc.) - Improved list formatting throughout - Added proper markdown structure Users can now install with: npx adce-framework Generated with Claude Code --- adce-framework/README.md | 82 +++++++++++++++++++++++-------------- adce-framework/package.json | 3 +- 2 files changed, 52 insertions(+), 33 deletions(-) diff --git a/adce-framework/README.md b/adce-framework/README.md index 48dd1a8..3ab3699 100644 --- a/adce-framework/README.md +++ b/adce-framework/README.md @@ -20,30 +20,40 @@ ADCE combines the best of three methodologies: ### 1. Install in Your Project ```bash -npx adce-framework install +npx adce-framework +``` + +This will install ADCE agents and templates into your project. + +### 2. Start Using ADCE Agents +```bash # Create a pitch from your idea "Use shaper to create a pitch for: [your broad idea]" -# Review technical feasibility +# Review technical feasibility "Use architect to review this pitch for feasibility" +# Break into specific tasks (for complex features) +"Use planner to break down the API PRP into implementation tasks" + # Start building "Use builder to implement dashboard components" "Use deployer to set up production deployment" -Why ADCE Works -❌ Traditional Problems: +``` -Vague prompts → unusable AI output -No scope discipline → endless iteration -Context loss → repeated explanations -No systematic approach → inconsistent results +## Why ADCE Works -✅ ADCE Solutions: +### ❌ Traditional Problems: +- Vague prompts → unusable AI output +- No scope discipline → endless iteration +- Context loss → repeated explanations +- No systematic approach → inconsistent results -Systematic refinement: Ideas → working software -Appetite constraints: Prevent scope creep -Context engineering: Enable AI first-pass success -Specialized agents: Domain expertise + consistency +### ✅ ADCE Solutions: +- Systematic refinement: Ideas → working software +- Appetite constraints: Prevent scope creep +- Context engineering: Enable AI first-pass success +- Specialized agents: Domain expertise + consistency ## The Five Core Agents 🎯 **shaper** - Turns broad ideas into appetite-bounded pitches with comprehensive context @@ -55,29 +65,39 @@ Specialized agents: Domain expertise + consistency 🎨 **builder** - Handles UI/UX design and frontend development within constraints 🚀 **deployer** - Gets features safely to production and maintains system reliability -Real Results -Finance Dashboard: "Users want better financial insights" → Working dashboard with spending breakdown in 1.5 weeks (AI-accelerated) -User Onboarding: "Reduce new user confusion" → Progressive onboarding flow reducing churn 67% in 1 week (AI-accelerated) -Documentation -Getting Started: Your first ADCE cycle -Complete Methodology: Full framework documentation -Real Examples: Complete workflow walkthroughs -Agent Specifications: Detailed agent docs +## Real Results + +**Finance Dashboard**: "Users want better financial insights" → Working dashboard with spending breakdown in 1.5 weeks (AI-accelerated) + +**User Onboarding**: "Reduce new user confusion" → Progressive onboarding flow reducing churn 67% in 1 week (AI-accelerated) + +## Documentation -Requirements +- **Getting Started**: Your first ADCE cycle +- **Complete Methodology**: Full framework documentation +- **Real Examples**: Complete workflow walkthroughs +- **Agent Specifications**: Detailed agent docs -Claude Code (latest version) -Node.js 18+ -Git +## Requirements -Community +- Claude Code (latest version) +- Node.js 18+ +- Git -GitHub Discussions: Framework Q&A -Discord Server: Real-time help and community +## Community + +- **GitHub Discussions**: Framework Q&A +- **Discord Server**: Real-time help and community + +## Contributing -Contributing We welcome contributions! See CONTRIBUTING.md for guidelines. -License + +## License + MIT License - see LICENSE for details. -Turn your broad ideas into working software with predictable timeframes. + +--- + +**Turn your broad ideas into working software with predictable timeframes.** diff --git a/adce-framework/package.json b/adce-framework/package.json index 14cf435..bccb537 100644 --- a/adce-framework/package.json +++ b/adce-framework/package.json @@ -4,8 +4,7 @@ "description": "Appetite-Driven Context Engineering framework for AI-first development", "main": "install.js", "bin": { - "adce": "./tools/cli.js", - "adce-install": "./install.js" + "adce-framework": "./install.js" }, "scripts": { "install-framework": "node install.js", From 36fba28cdff2c39603a286efcd86ce0f7fa65942 Mon Sep 17 00:00:00 2001 From: Claude Date: Sun, 26 Oct 2025 12:23:57 +0000 Subject: [PATCH 7/9] Add comprehensive installation documentation MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Created INSTALL.md with: - Clear explanation that ADCE runs INSIDE Claude Code - Three installation methods (npm/git/manual) - Step-by-step instructions for each method - Troubleshooting section - Publishing guide for maintainers - Usage examples Updated README.md to: - Clarify that agents run inside Claude Code - Show current installation method (pre-npm) - Show future installation method (post-npm) - Link to detailed INSTALL.md guide - Emphasize Claude Code requirement This addresses confusion about npx not working - package needs to be published to npm first. Current users should use git clone method. 🤖 Generated with Claude Code --- adce-framework/INSTALL.md | 205 ++++++++++++++++++++++++++++++++++++++ adce-framework/README.md | 27 ++++- 2 files changed, 229 insertions(+), 3 deletions(-) create mode 100644 adce-framework/INSTALL.md diff --git a/adce-framework/INSTALL.md b/adce-framework/INSTALL.md new file mode 100644 index 0000000..9df824e --- /dev/null +++ b/adce-framework/INSTALL.md @@ -0,0 +1,205 @@ +# ADCE Framework Installation Guide + +## What is ADCE? + +ADCE provides **Claude Code agents** that run INSIDE Claude Code to help you build features systematically. It's NOT a standalone command-line tool. + +## Prerequisites + +1. **Claude Code** (latest version) - https://claude.ai/code +2. **Node.js 18+** (for the installer) +3. A project where you want to use ADCE agents + +## Installation Options + +### Option 1: From npm (When Published) + +Once published to npm, you'll be able to run: + +```bash +cd /path/to/your/project +npx adce-framework +``` + +**Status**: 🚧 Not yet published to npm + +### Option 2: From Git Repository (Current Method) + +**Step 1: Clone the repository** +```bash +git clone https://github.com/jamalcodez/adce-framework.git +cd adce-framework +``` + +**Step 2: Navigate to the framework directory** +```bash +cd adce-framework +``` + +**Step 3: Install dependencies** +```bash +npm install +``` + +**Step 4: Run the installer in your project** +```bash +cd /path/to/your/project +node /path/to/adce-framework/adce-framework/install.js +``` + +The installer will: +- ✅ Check for Claude Code +- ✅ Copy agents to `.claude/agents/` +- ✅ Copy templates to `ADCE/templates/` +- ✅ Copy examples to `ADCE/examples/` +- ✅ Create `CLAUDE.md` configuration + +### Option 3: Manual Installation (Quickest) + +If you just want the agents without running the installer: + +```bash +# In your project directory +mkdir -p .claude/agents + +# Copy all agents +cp /path/to/adce-framework/adce-framework/agents/*.md .claude/agents/ + +# Verify installation +ls -la .claude/agents/ +# Should show: shaper.md, architect.md, planner.md, builder.md, deployer.md +``` + +## Verification + +After installation, verify the agents are available: + +1. **Open your project in Claude Code** +2. **Try using an agent**: + ``` + Use shaper to create a pitch for: Adding user authentication to my app + ``` + +If the shaper agent responds, you're all set! 🎉 + +## Usage (Inside Claude Code) + +Once installed, interact with agents through natural language: + +### Standard Workflow (Simple Features) + +```bash +# Step 1: Create a pitch +"Use shaper to create a pitch for: [your idea]" + +# Step 2: Technical review +"Use architect to review this pitch for feasibility" + +# Step 3: Build it +"Use builder to implement the dashboard components" +"Use deployer to set up production deployment" +``` + +### Extended Workflow (Complex Features) + +```bash +# Step 1: Create a pitch +"Use shaper to create a pitch for: [your idea]" + +# Step 2: Technical review & PRPs +"Use architect to review this pitch and create PRPs" + +# Step 3: Break into tasks (NEW!) +"Use planner to break down the API PRP into specific implementation tasks" + +# Step 4: Execute tasks +"Use builder to implement Task 1: Create database schema" +"Use deployer to implement Task 12: Production deployment" +``` + +## Publishing to npm (For Maintainers) + +To publish the package so `npx adce-framework` works globally: + +**Step 1: Log into npm** +```bash +npm login +``` + +**Step 2: Verify package.json** +- Check version number +- Ensure all files are listed in `files` array +- Test locally first + +**Step 3: Test the package locally** +```bash +npm pack +# Creates adce-framework-1.0.0.tgz + +# Test in another project +cd /path/to/test/project +npm install /path/to/adce-framework/adce-framework-1.0.0.tgz +npx adce-framework +``` + +**Step 4: Publish to npm** +```bash +npm publish +``` + +**Step 5: Test the published package** +```bash +cd /path/to/test/project +npx adce-framework +``` + +## Troubleshooting + +### "Could not determine executable to run" + +**Cause**: Package not published to npm yet, or incorrect bin configuration + +**Solution**: Use Option 2 (Git Repository) or Option 3 (Manual Installation) + +### "Claude Code not found" + +**Cause**: `.claude` directory doesn't exist in your project or home directory + +**Solution**: +1. Install Claude Code first +2. Create `.claude/agents/` manually: `mkdir -p .claude/agents` +3. Use manual installation (Option 3) + +### "Agents not responding" + +**Cause**: Agents not properly installed or Claude Code not recognizing them + +**Solution**: +1. Verify files exist: `ls -la .claude/agents/` +2. Check file format (should be `.md` files with frontmatter) +3. Restart Claude Code +4. Try explicit agent call: `"Use shaper to help me"` + +### "npm install fails" + +**Cause**: Missing dependencies or Node.js version mismatch + +**Solution**: +1. Ensure Node.js 18+ is installed: `node --version` +2. Clear npm cache: `npm cache clean --force` +3. Delete node_modules and reinstall: `rm -rf node_modules && npm install` + +## Support + +- **Issues**: https://github.com/jamalcodez/adce-framework/issues +- **Discussions**: https://github.com/jamalcodez/adce-framework/discussions +- **Documentation**: See `/docs` folder in the repository + +## Next Steps + +After installation: + +1. **Read the methodology**: `cat ADCE/examples/user-dashboard/README.md` +2. **Try the planner**: `cat ADCE/examples/task-breakdown/README.md` +3. **Start your first cycle**: Use shaper to create a pitch for your next feature +4. **Join the community**: Share your experience and learn from others diff --git a/adce-framework/README.md b/adce-framework/README.md index 3ab3699..fff2f84 100644 --- a/adce-framework/README.md +++ b/adce-framework/README.md @@ -18,14 +18,35 @@ ADCE combines the best of three methodologies: ## Quick Start -### 1. Install in Your Project +> **Note**: ADCE provides agents that run INSIDE Claude Code. You need Claude Code installed first. + +### 1. Install ADCE Agents + +**After npm publication** (coming soon): ```bash npx adce-framework ``` -This will install ADCE agents and templates into your project. +**Current installation** (before npm publication): +```bash +# Clone and run installer +git clone https://github.com/jamalcodez/adce-framework.git +cd adce-framework/adce-framework +npm install +cd /path/to/your/project +node /path/to/adce-framework/adce-framework/install.js +``` + +Or **manual installation** (quickest): +```bash +# Copy agents to your project +mkdir -p .claude/agents +cp /path/to/adce-framework/adce-framework/agents/*.md .claude/agents/ +``` + +See [INSTALL.md](INSTALL.md) for detailed installation instructions. -### 2. Start Using ADCE Agents +### 2. Use ADCE Agents in Claude Code ```bash # Create a pitch from your idea "Use shaper to create a pitch for: [your broad idea]" From d5f52bb9f3661028b16875cf10bb93d4cd53ed85 Mon Sep 17 00:00:00 2001 From: jamalcodez Date: Mon, 27 Oct 2025 21:40:32 -0500 Subject: [PATCH 8/9] Update package bin command name to adce-framework MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Changes the CLI command from 'adce' to 'adce-framework' and removes the separate adce-install command, consolidating to a single entry point through install.js for better package management and clarity. 🤖 Generated with [Claude Code](https://claude.com/claude-code) Co-Authored-By: Claude --- adce-framework/package-lock.json | 3 +-- 1 file changed, 1 insertion(+), 2 deletions(-) diff --git a/adce-framework/package-lock.json b/adce-framework/package-lock.json index 11d7c2b..ea6bce4 100644 --- a/adce-framework/package-lock.json +++ b/adce-framework/package-lock.json @@ -14,8 +14,7 @@ "inquirer": "^8.2.4" }, "bin": { - "adce": "tools/cli.js", - "adce-install": "install.js" + "adce-framework": "install.js" }, "devDependencies": { "jest": "^29.0.0" From 36fefc2f233890831215d28f9f01f3b1bbe44480 Mon Sep 17 00:00:00 2001 From: jamalcodez Date: Mon, 27 Oct 2025 22:19:06 -0500 Subject: [PATCH 9/9] Consolidate workflows into unified flow with planner agent MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Replaces separate "Standard Flow" and "Extended Flow" with a single unified workflow that includes the planner agent as a standard step. The planner step can be skipped for very simple features. **Unified Flow**: shaper → architect → planner → builder/deployer → integration Changes: - Updated README.md with numbered workflow steps - Updated agents/README.md with unified flow - Updated docs/agent-specifications.md with planner in sequential handoffs - Updated install.js CLAUDE.md template with unified flow Rationale: Having two separate flows was confusing. The new unified flow makes planner a standard step with clear guidance on when it can be skipped (single file, <2 hour tasks). 🤖 Generated with [Claude Code](https://claude.com/claude-code) Co-Authored-By: Claude --- adce-framework/README.md | 14 ++++++++------ adce-framework/agents/README.md | 15 +++++---------- adce-framework/docs/agent-specifications.md | 12 ++++++++---- adce-framework/install.js | 20 ++++++++------------ 4 files changed, 29 insertions(+), 32 deletions(-) diff --git a/adce-framework/README.md b/adce-framework/README.md index feaa573..f5b3d4d 100644 --- a/adce-framework/README.md +++ b/adce-framework/README.md @@ -53,20 +53,22 @@ See [INSTALL.md](INSTALL.md) for detailed installation instructions. ### 2. Start Your First Cycle ```bash -# Create a pitch from your idea +# 1. Create a pitch from your idea "Use shaper to create a pitch for: [your broad idea]" -# Review technical feasibility +# 2. Review technical feasibility "Use architect to review this pitch for feasibility" -# Break into specific tasks (for complex features) -"Use planner to break down the API PRP into implementation tasks" +# 3. Break into specific tasks +"Use planner to break down the PRP into implementation tasks" -# Start building -"Use builder to implement dashboard components" +# 4. Start building +"Use builder to implement the first task from the plan" "Use deployer to set up production deployment" ``` +**Note**: For very simple features (single file, <2 hour tasks), you may skip step 3 (planner) and go directly from architect to builder/deployer. + ## Why ADCE Works ### ❌ Traditional Problems: diff --git a/adce-framework/agents/README.md b/adce-framework/agents/README.md index 6d5418b..4783552 100644 --- a/adce-framework/agents/README.md +++ b/adce-framework/agents/README.md @@ -42,21 +42,16 @@ Example: "Use deployer to set up staging environment" ## Usage Workflow -### Standard Flow (Simple Features) -1. **Shaping**: shaper creates appetite-bounded pitch +### Standard Development Flow +1. **Shaping**: shaper creates appetite-bounded pitch from broad ideas 2. **Architecture**: architect reviews feasibility and creates PRPs -3. **Building**: builder and deployer implement features -4. **Integration**: architect manages integration and scope decisions -5. **Deployment**: deployer gets features to production - -### Extended Flow (Complex Features) -1. **Shaping**: shaper creates appetite-bounded pitch -2. **Architecture**: architect reviews feasibility and creates PRPs -3. **Planning**: planner breaks PRPs into specific, dependency-aware tasks (NEW) +3. **Planning**: planner breaks PRPs into specific, dependency-aware tasks 4. **Building**: builder and deployer execute tasks systematically 5. **Integration**: architect manages integration and scope decisions 6. **Deployment**: deployer gets features to production +**Note**: For very simple features (single file, <2 hour tasks), you may skip the planner step and go directly from architect to builder/deployer. + ## Agent Configuration Each agent includes: diff --git a/adce-framework/docs/agent-specifications.md b/adce-framework/docs/agent-specifications.md index be5caa3..c219654 100644 --- a/adce-framework/docs/agent-specifications.md +++ b/adce-framework/docs/agent-specifications.md @@ -204,13 +204,17 @@ Agents automatically activate based on: ## Agent Collaboration Patterns ### Sequential Handoffs -**Standard Flow**: shaper → architect → builder/deployer → integration +**Standard Flow**: shaper → architect → planner → builder/deployer → integration 1. **Shaper Output**: Appetite-bounded pitch with comprehensive context -2. **Architect Input**: Review pitch for technical feasibility +2. **Architect Input**: Review pitch for technical feasibility 3. **Architect Output**: PRPs with implementation context and scope management -4. **Builder/Deployer Input**: Execute PRPs with clear boundaries and context -5. **Integration**: architect oversees component integration and final validation +4. **Planner Input**: Receive PRPs and break into specific, dependency-aware tasks +5. **Planner Output**: Detailed task plan with dependencies and implementation sequence +6. **Builder/Deployer Input**: Execute tasks systematically with clear boundaries +7. **Integration**: architect oversees component integration and final validation + +**Note**: For very simple features (single file, <2 hour tasks), you may skip the planner step and go directly from architect to builder/deployer. ### Parallel Execution **When Appropriate**: Independent PRPs that don't have blocking dependencies diff --git a/adce-framework/install.js b/adce-framework/install.js index 59d0628..19a0c8a 100755 --- a/adce-framework/install.js +++ b/adce-framework/install.js @@ -136,18 +136,14 @@ npm run build ## ADCE Workflow -### Standard Flow (Simple Features) -1. Use shaper to create appetite-bounded pitches -2. Use architect to review feasibility and create PRPs -3. Use builder and deployer to implement features -4. Track progress with hill charts - -### Extended Flow (Complex Features) -1. Use shaper to create appetite-bounded pitches -2. Use architect to review feasibility and create PRPs -3. Use planner to break PRPs into specific tasks (optional) -4. Use builder and deployer to execute tasks -5. Track progress with task completion +### Standard Development Flow +1. **Shape**: Use shaper to create appetite-bounded pitches from broad ideas +2. **Architect**: Use architect to review feasibility and create PRPs +3. **Plan**: Use planner to break PRPs into specific, dependency-aware tasks +4. **Build**: Use builder and deployer to execute tasks systematically +5. **Track**: Monitor progress with hill charts and task completion + +**Note**: For very simple features (single file, <2 hour tasks), you may skip the planner step and go directly from architect to builder/deployer. `; await fs.writeFile(claudeMd, template); console.log(chalk.green(' ✓ Created CLAUDE.md'));