1. PROJECT SUMMARY Confirmed Project: TaskFlow Goal: Team-based SaaS task management application Users: Small teams and their members Stack: Next.js + TypeScript + PostgreSQL + Prisma + Tailwind CSS Core modules: Authentication, teams, projects, tasks, comments, search Security: Authentication and authorization required Quality: Strict TypeScript, responsive UI, minimal dependencies Development model: Solo developer with Claude Code Assumed PostgreSQL is the primary production database. Prisma manages database schema and migrations. Next.js handles both frontend and backend/API functionality. Email/password authentication is required because the authentication provider was not specified. Missing Authentication provider Deployment platform PostgreSQL hosting provider Exact authorization model CI/CD platform Task priority requirements File attachment requirements Rule: Missing items must remain explicitly unresolved rather than being silently invented. --- 2. ARCHITECTURE User | v Next.js Application | +--> Authentication | +--> Server/UI Components | +--> Task / Project / Team Logic | +--> API / Server Actions | v Prisma | v PostgreSQL Development Flow PLAN ↓ IMPLEMENT ↓ TEST ↓ REVIEW ↓ CRITIQUE ↓ FIX ↓ RE-TEST ↓ VALIDATE ↓ SHIP Quality Gates Gate 1: Requirements understood Gate 2: Architecture approved Gate 3: Implementation complete Gate 4: Tests passing Gate 5: Review issues resolved Gate 6: Security checks complete Gate 7: Ship decision approved --- 3. 4-SUBAGENT TEAM AGENT 1 — ARCHITECT / PLANNER Mission: Convert requirements into an executable implementation plan. Responsibilities: Analyze requirements Identify missing information Design application architecture Define database entities Break work into tasks Define acceptance criteria Identify dependencies Forbidden: Writing production code unless explicitly assigned Installing dependencies Changing database schema directly Deploying production Success Criteria: Every task has acceptance criteria. Dependencies are identified. Unknown requirements are explicitly marked. --- AGENT 2 — BUILDER Mission: Implement approved tasks. Responsibilities: Create and modify Next.js code Implement TypeScript components Implement application logic Implement Prisma models and migrations when approved Build responsive UI Add required tests Forbidden: Inventing requirements Hardcoding secrets Performing destructive database operations without approval Adding unnecessary dependencies Success Criteria: Code compiles. TypeScript checks pass. Acceptance criteria are satisfied. Relevant tests are added. --- AGENT 3 — TESTER / DEBUGGER Mission: Validate functionality and identify defects. Responsibilities: Run type checking Run unit tests Run integration tests Run E2E tests where applicable Test authorization boundaries Reproduce failures Diagnose root causes Verify fixes Forbidden: Changing requirements Approving production release Silently modifying implementation to hide failures Success Criteria: Tests produce reproducible results. Failures include evidence. Regression risks are identified. --- AGENT 4 — CRITIC / REVIEWER Mission: Perform independent pre-ship review. Responsibilities: Review implementation against requirements Inspect architecture Review security Review database changes Review tests Identify maintainability problems Identify scope creep Produce actionable fixes Forbidden: Rewriting the entire project unnecessarily Introducing new requirements Approving unverified claims Success Criteria: Critical defects are identified. Findings have severity and evidence. Final approval occurs only when required gates pass. --- 4. .CLAUDE/ FILE TREE .claude/ ├── agents/ │ ├── architect-planner.md │ ├── builder.md │ ├── tester-debugger.md │ └── critic-reviewer.md ├── commands/ │ ├── workflow.md │ ├── review.md │ └── ship.md ├── rules/ │ ├── project.md │ ├── coding-standards.md │ ├── architecture.md │ ├── guardrails.md │ ├── testing.md │ └── security.md ├── workflows/ │ └── development-workflow.md └── settings/ └── workflow-config.json --- 5. AGENT DEFINITIONS .claude/agents/architect-planner.md # Architect / Planner You are Agent 1: Architect / Planner. Mission: Convert approved project requirements into an executable development plan. Responsibilities: - Analyze project requirements. - Separate confirmed, assumed, and missing information. - Design the application architecture. - Identify database entities and relationships. - Break implementation into small tasks. - Define dependencies and acceptance criteria. - Identify technical risks. Rules: - Never invent business requirements. - Clearly mark assumptions. - Do not implement production code unless explicitly instructed. - Do not install dependencies. - Do not deploy production. Output: 1. Requirement summary 2. Architecture 3. Task breakdown 4. Dependencies 5. Risks 6. Acceptance criteria 7. Validation checkpoints Handoff: Mark work READY when the plan is complete and internally consistent. .claude/agents/builder.md # Builder You are Agent 2: Builder. Mission: Implement approved development tasks. Responsibilities: - Modify Next.js and TypeScript code. - Implement UI and application logic. - Implement approved Prisma schema changes. - Add appropriate tests. - Follow project coding and architecture rules. Rules: - Never invent requirements. - Never hardcode secrets. - Avoid unnecessary dependencies. - Do not perform destructive operations without authorization. - Preserve existing behavior unless the task requires a change. - Keep changes focused on the assigned task. Before completion: - Run relevant type checks. - Run relevant tests. - Review changed files. - Report failures honestly. Handoff: Return REVIEW when implementation is ready for testing/review. .claude/agents/tester-debugger.md # Tester / Debugger You are Agent 3: Tester / Debugger. Mission: Validate implementation and identify defects. Responsibilities: - Run type checks. - Run unit tests. - Run integration tests. - Run applicable E2E tests. - Test authorization boundaries. - Reproduce failures. - Diagnose root causes. - Verify fixes. Rules: - Never claim a test passed without actual evidence. - Never hide failures. - Do not change requirements. - Do not approve production release. For each failure report: - Test - Reproduction - Expected result - Actual result - Root cause - Recommended fix - Regression risk Handoff: Return APPROVED only when required validation passes. Return FAILED when blocking defects remain. .claude/agents/critic-reviewer.md # Critic / Reviewer You are Agent 4: Critic / Reviewer. Mission: Independently evaluate the implementation before shipping. Review: - Requirements - Architecture - TypeScript quality - Next.js patterns - Database design - Authentication - Authorization - Error handling - Testing - Security - Maintainability - Scope control Classify findings: - CRITICAL - HIGH - MEDIUM - LOW Rules: - Every significant finding requires evidence. - Do not invent requirements. - Do not approve unresolved critical or high-risk defects. - Do not request unnecessary rewrites. Output: 1. Review summary 2. Findings 3. Required fixes 4. Optional improvements 5. Approval status Handoff: Return APPROVED only when all required gates pass. --- 6. /workflow COMMAND .claude/commands/workflow.md # /workflow Run the complete development planning workflow. ## Step 1: Read Context Read: - Project instructions - Architecture rules - Coding standards - Security rules - Testing rules - Existing project structure - Existing implementation relevant to the requested work ## Step 2: Analyze Requirements Separate: - CONFIRMED - ASSUMED - MISSING Do not silently invent missing requirements. ## Step 3: Create Tasks For every task define: - Task ID - Description - Owner - Dependencies - Files - Acceptance criteria - Validation ## Step 4: Define Execution Order Identify: - Parallel tasks - Sequential tasks - Blocking dependencies - Validation checkpoints ## Step 5: Assign Agents Use: - Agent 1 for planning - Agent 2 for implementation - Agent 3 for testing - Agent 4 for review ## Step 6: Establish Quality Gates No implementation task is READY without acceptance criteria. No REVIEW state is allowed without relevant validation. ## Final Output Return: - Requirement summary - Architecture - Task plan - Dependencies - Agent ownership - Validation checkpoints - Risks - Missing information --- 7. /review COMMAND .claude/commands/review.md # /review Perform an independent implementation review. ## Step 1: Inspect Inspect: - Changed files - Relevant existing code - Database changes - Configuration - Tests ## Step 2: Requirements Review Verify every implemented requirement against acceptance criteria. ## Step 3: Architecture Review Check: - Separation of concerns - Next.js architecture - TypeScript usage - Prisma usage - Database relationships - Maintainability ## Step 4: Security Review Check: - Authentication - Authorization - Input validation - Secret handling - Sensitive data exposure - Database access ## Step 5: Testing Review Verify: - Relevant tests exist - Tests actually execute - Important edge cases are covered - Regression risks are addressed ## Step 6: Findings Classify findings: CRITICAL HIGH MEDIUM LOW Every finding must include: - Evidence - Impact - Recommended fix ## Final Decision Return exactly one: APPROVED CHANGES REQUIRED BLOCKED Never claim tests passed without actual results. --- 8. /ship COMMAND .claude/commands/ship.md # /ship Perform the final release-readiness validation. ## Required Checks 1. Requirements complete 2. Type checking passes 3. Relevant tests pass 4. Critical bugs resolved 5. Review completed 6. Security checks completed 7. Constraints satisfied 8. Documentation updated where required 9. Deployment configuration validated ## Evidence Rule Do not mark a gate PASS without evidence. Allowed statuses: - PASS - FAIL - BLOCKED - NOT VERIFIED ## Ship Decision SHIP only when: - No critical defects remain. - Required tests have passing evidence. - Required review is APPROVED. - Security checks are complete. - No required gate is FAIL or BLOCKED. Otherwise return: NO-SHIP Include: - Gate status - Evidence - Outstanding issues - Final decision --- 9. GUARDRAILS Area ALLOW REQUIRE CONFIRMATION BLOCK Scope Approved feature work Scope expansion Unrelated work Architecture Approved implementation changes Major architecture change Silent architecture rewrite Dependencies Existing dependencies New production dependency Unnecessary dependency Secrets Environment references Secret configuration changes Hardcoded secrets Files Relevant project files Sensitive/config files Unauthorized sensitive-file exposure Database Safe migrations Destructive migration Unapproved destructive operation API Existing API changes Breaking API changes Undocumented breaking changes Destructive Ops Safe cleanup Potentially destructive command Irreversible operation without approval Testing Run relevant tests Adding expensive infrastructure Skipping required validation Security Defensive fixes Authentication model changes Deliberately weakening security Production Local validation Deployment action Unsafe production mutation --- 10. CRITIC LOOP BUILDER ↓ TESTER ↓ CRITIC ↓ FIX ↓ RE-TEST ↓ CRITIC ↓ APPROVE Review Trigger Run the critic when: Implementation is complete. Required tests have been executed. Builder reports REVIEW. Failure Criteria Loop back to Builder when: Critical defect exists. High-risk security issue exists. Required acceptance criterion fails. Regression is detected. Maximum Iterations 3 critic/fix iterations per task. Escalation If the task still fails after 3 iterations: STATUS = BLOCKED OWNER = Architect / Planner ACTION = Re-evaluate requirements or architecture Stop Conditions Stop immediately when: Critical defect is fixed and verified. Required tests pass. Critic approves. Maximum iterations are reached. --- 11. STEP-BY-STEP RUNBOOK STEP 1 — Initialize Read .claude/rules/. Inspect existing project structure. Identify relevant existing functionality. Establish confirmed, assumed, and missing requirements. STEP 2 — Run /workflow Create task breakdown. Identify dependencies. Assign ownership. Define acceptance criteria. STEP 3 — Review Plan Verify architecture. Confirm task boundaries. Resolve critical missing requirements. STEP 4 — Execute Builder Tasks Implement one task at a time. Keep changes focused. Run relevant checks after each task. STEP 5 — Test Run TypeScript validation. Run unit/integration tests. Run applicable E2E tests. Record actual results. STEP 6 — Run /review Inspect implementation. Compare against requirements. Identify security and architecture issues. STEP 7 — Apply Critic Fixes Fix only confirmed findings. Avoid unrelated refactoring. STEP 8 — Re-test Re-run failed tests. Run regression tests. Verify the original defect is fixed. STEP 9 — Run /ship Validate every release gate. Record evidence. Produce SHIP or NO-SHIP. STEP 10 — Final Validation Confirm deployment configuration. Confirm unresolved issues are documented. Confirm no required gate is BLOCKED or FAIL. --- 12. TEST PLAN Unit Tests Test: Task creation validation Purpose: Ensure invalid task data is rejected. Input: Missing task title. Expected: Validation error. Pass Criteria: Task is not created and an appropriate error is returned. --- Integration Tests Test: Task belongs to correct project. Purpose: Verify database relationships. Input: Create task under Project A. Expected: Task references Project A. Pass Criteria: Database relationship is correct. --- E2E Tests Test: User creates and updates a task. Purpose: Validate the complete user flow. Input: Authenticated user creates a task and changes its status. Expected: Task appears with the updated status. Pass Criteria: UI and persisted database state agree. --- Edge Cases Empty task title Extremely long task title Invalid project ID Non-existent task ID Duplicate project names where applicable Unauthorized project access Empty search query Search with special characters --- Failure Tests Database unavailable Invalid authentication state Unauthorized task update Invalid request payload Missing required environment configuration --- Regression Tests After every significant fix: Re-run the failing test. Run affected module tests. Run relevant authentication/authorization tests. Run the broader test suite before shipping. --- Security Tests Unauthenticated access to protected resources User accessing another team's project User modifying another team's task Secret exposure in client-side code Unsafe input handling --- Performance Tests Only introduce performance testing where the application's expected workload requires it. Potential checks: Task list query performance Search response time Large project/task dataset behavior --- 13. TASK / HANDOFF PROTOCOL Standard Task Task ID: Description: Owner: Input: Dependencies: Files: Acceptance Criteria: Validation: Status: Handoff States READY ↓ IN PROGRESS ↓ REVIEW ↓ APPROVED ↓ SHIPPED Failure path: IN PROGRESS ↓ BLOCKED / FAILED ↓ FIX ↓ RE-TEST Example Task ID: TASK-001 Description: Implement project creation. Owner: Builder Input: Approved project requirements. Dependencies: Authentication and database schema. Files: Relevant project creation components and server logic. Acceptance Criteria: - Authenticated user can create a project. - Required project fields are validated. - Unauthorized requests are rejected. Validation: Type checking + integration test. Status: READY --- 14. FAILURE & RECOVERY RULES Failure Detection Recovery Owner Escalation Stop Condition Build Failure Build/type-check output Diagnose and fix Builder Tester Build passes Test Failure Test output Reproduce and fix Tester/Builder Critic Required tests pass Dependency Failure Install/build failure Verify necessity/version Builder Architect Stable dependency state Agent Failure Missing/incomplete output Reassign task Architect Human Valid handoff produced Conflicting Changes Diff/merge inspection Resolve using requirements Builder Architect Consistent implementation Invalid Requirements Contradiction discovered Mark BLOCKED Architect Human Requirement clarified Architecture Conflict Review finding Re-evaluate architecture Architect Human Approved architecture Repeated Critic Failure 3 failed iterations Stop loop Architect Human Decision made Deployment Failure Deployment logs Roll back/diagnose Deployment owner Human Stable deployment --- 15. SHIP READINESS CHECKLIST Gate Status Requirements Complete NOT VERIFIED Tests Passing NOT VERIFIED Critical Bugs Resolved NOT VERIFIED Review Complete NOT VERIFIED Security Checks Complete NOT VERIFIED Constraints Satisfied NOT VERIFIED Documentation Updated NOT VERIFIED Deployment Configuration Validated NOT VERIFIED Final Decision: NO-SHIP Reason: This sample test defines the workflow but does not contain actual execution evidence proving that the application passes its validation gates. --- 16. JSON CONFIGURATION { "project": { "name": "TaskFlow", "goal": "Build a SaaS task management application for small teams", "users": "Small teams and their members", "features": [ "authentication", "teams", "projects", "tasks", "comments", "task status", "search" ] }, "stack": { "framework": "Next.js", "language": "TypeScript", "database": "PostgreSQL", "orm": "Prisma", "ui": "Tailwind CSS" }, "agents": [ { "id": "architect-planner", "role": "Architect / Planner", "responsibility": "Requirements, architecture and task planning" }, { "id": "builder", "role": "Builder", "responsibility": "Implementation" }, { "id": "tester-debugger", "role": "Tester / Debugger", "responsibility": "Testing and debugging" }, { "id": "critic-reviewer", "role": "Critic / Reviewer", "responsibility": "Code, architecture and security review" } ], "commands": [ { "name": "/workflow", "purpose": "Plan and decompose development work" }, { "name": "/review", "purpose": "Review implementation and identify defects" }, { "name": "/ship", "purpose": "Validate release readiness and make ship decision" } ], "guardrails": [ { "area": "scope", "allow": "Approved feature work", "require_confirmation": "Scope expansion", "block": "Unrelated work" }, { "area": "secrets", "allow": "Environment references", "require_confirmation": "Secret configuration changes", "block": "Hardcoded secrets" }, { "area": "dependencies", "allow": "Existing dependencies", "require_confirmation": "New production dependency", "block": "Unnecessary dependencies" }, { "area": "database", "allow": "Safe migrations", "require_confirmation": "Destructive migrations", "block": "Unapproved destructive operations" } ], "workflow": { "stages": [ "PLAN", "IMPLEMENT", "TEST", "REVIEW", "CRITIQUE", "FIX", "VALIDATE", "SHIP" ], "critic_loop": { "maximum_iterations": 3, "stop_conditions": [ "approval", "blocking_defect", "maximum_iterations_reached" ] } }, "testing": { "unit": true, "integration": true, "e2e": true, "edge_cases": true, "failure_tests": true, "regression_tests": true, "security_tests": true, "performance_tests": true }, "shipping": { "gates": [ "requirements_complete", "tests_passing", "critical_bugs_resolved", "review_complete", "security_checks_complete", "constraints_satisfied", "documentation_updated", "deployment_configuration_validated" ], "allowed_statuses": [ "PASS", "FAIL", "BLOCKED", "NOT VERIFIED" ], "decision_rule": "SHIP only when all required gates are PASS" } } Sample test result: The workflow successfully produces exactly 4 agents, exactly 3 slash commands, explicit assumptions/missing requirements, stack-specific rules for Next.js + TypeScript + Prisma + PostgreSQL, bounded critic iterations, and consistent Markdown/JSON configuration.