PHASE 1 - REQUIREMENT RECONSTRUCTION Product Objective Create a lightweight project and task management SaaS that allows small teams to organize projects, assign work, track progress, and complete tasks securely. User Problems Teams need a central location for tasks. Managers need to assign work. Members need to know their responsibilities. Project progress needs to be visible. Target Users Admin Manager Member Core Workflow Login ↓ Dashboard ↓ Select Project ↓ Create Task ↓ Assign Member ↓ Member Updates Status ↓ Task Completed Functional Requirements Authentication User roles Project management Task management Task assignment Status management Dashboard Audit logging Non-Functional Requirements Secure authentication Server-side authorization Responsive interface Test coverage for critical workflows Maintainable TypeScript code API response target below 500ms for normal operations Confirmed Requirements React frontend Node.js backend PostgreSQL JWT authentication Three user roles Project/task CRUD Task status workflow Automated tests Assumptions Email/password authentication is sufficient for MVP. A project can contain multiple tasks. A task can have one primary assignee. Users belong to one organization in the MVP. Proposed Decisions Use REST APIs. Use UUIDs for primary identifiers. Hash passwords using a modern password-hashing algorithm. Enforce authorization on the backend. Open Questions JWT expiration period Soft delete vs permanent task deletion Audit-log retention period --- PHASE 2 - FEATURE & USER STORY ARCHITECTURE Feature 1: Authentication User Story As a user, I want to securely log in so that I can access my workspace. Main Flow Enter credentials ↓ Validate credentials ↓ Generate session/token ↓ Open dashboard Error States Invalid email Invalid password Missing credentials Disabled account Acceptance Criteria Valid credentials authenticate successfully. Invalid credentials return a safe error. Passwords are never returned by the API. Unauthorized API requests are rejected. --- Feature 2: Project Management User Story As a manager, I want to create projects so that work can be organized. Acceptance Criteria Authorized users can create projects. Project names are validated. Users cannot access unauthorized projects. Project creation is persisted in PostgreSQL. --- Feature 3: Task Management User Story As a manager, I want to create and assign tasks. Acceptance Criteria Task requires a valid title. Task belongs to an existing project. Assignee must be authorized for the project. Initial status is Todo. Invalid project IDs are rejected. --- Feature 4: Task Status Allowed states: TODO → IN_PROGRESS → DONE Acceptance Criteria Valid status transitions succeed. Invalid status values are rejected. Only authorized users can modify task status. Status changes are persisted. --- PHASE 3 - SOFTWARE SPECIFICATION Task Entity Required fields: id project_id title description assignee_id status due_date created_at updated_at Business Rules Every task belongs to exactly one project. A task cannot reference a nonexistent user. A member can update tasks assigned to them. Managers can manage project tasks. Members cannot manage other members' tasks. Admins can manage organization-level resources. Validation Task title: Required Minimum: 1 character Maximum: 200 characters Description: Optional Maximum: 5000 characters Status: TODO IN_PROGRESS DONE Example POST /api/projects/{projectId}/tasks { "title": "Create landing page", "description": "Build the initial responsive landing page", "assigneeId": "user-123", "dueDate": "2026-10-01" } Expected result: 201 Created --- PHASE 4 - ARCHITECTURE BLUEPRINT Target Architecture React + TypeScript ↓ REST API ↓ Express + TypeScript ↓ Service Layer ↓ Repository/Data Layer ↓ PostgreSQL Authentication Login ↓ Backend validates credentials ↓ Password hash verification ↓ JWT/session issued ↓ Protected API request ↓ Authentication middleware ↓ Authorization middleware Components Frontend LoginPage DashboardPage ProjectPage TaskList TaskForm TaskCard ProjectSelector Backend auth module users module projects module tasks module audit module Architecture Decision Keep the MVP as a modular monolith rather than introducing microservices. Reason The product is small, the team is one developer, and microservices would add operational complexity without a demonstrated requirement. --- PHASE 5 - DATA & API CONTRACT DESIGN Database Entities User id email password_hash name role created_at updated_at Project id name description created_by created_at updated_at Task id project_id title description assignee_id status due_date created_at updated_at AuditLog id user_id action resource_type resource_id metadata created_at Relationships User ├── creates → Project ├── assigned → Task └── performs → AuditLog Project └── contains → Task API Contracts Authentication POST /api/auth/login Input: email password Output: accessToken user --- Create Project POST /api/projects Authorization: Admin / Manager --- List Projects GET /api/projects Authorization: Authenticated user --- Create Task POST /api/projects/:projectId/tasks Authorization: Admin / Manager --- Update Task Status PATCH /api/tasks/:taskId/status Authorization: Authorized manager OR assigned member Error Contract { "error": { "code": "TASK_NOT_FOUND", "message": "Task could not be found." } } Do not expose database errors or internal stack traces to users. --- PHASE 6 - TEST-FIRST ACCEPTANCE ARCHITECTURE Authentication Tests Unit Tests Password validation Credential validation Token generation Token expiration behavior Integration Tests Login with valid credentials Login with invalid credentials Protected endpoint without authentication Protected endpoint with invalid authentication E2E Test Open login ↓ Enter valid credentials ↓ Submit ↓ Dashboard appears --- Task Tests Unit Tests Required title validation Status validation Permission validation Due-date validation Integration Tests Create task Retrieve task Update task Reject unauthorized task modification E2E Test Login ↓ Open project ↓ Create task ↓ Assign member ↓ Member opens task ↓ Member changes status ↓ Status displays DONE Security Tests Unauthorized user cannot access project. Member cannot modify another member's task. Invalid IDs cannot bypass authorization. Malicious input is safely handled. Password hashes never appear in API responses. --- PHASE 7 - AI IMPLEMENTATION TASK GENERATION TASK ID: AUTH-001 TASK NAME: Create authentication foundation OBJECTIVE: Implement the basic authentication backend. CONTEXT: The application uses Node.js, Express, TypeScript and PostgreSQL. FILES / COMPONENTS: Create or modify only verified authentication-related files after inspecting the repository. DEPENDENCIES: None. REQUIREMENTS: Login endpoint Credential validation Secure password hashing Authentication middleware IMPLEMENTATION CONSTRAINTS: Inspect repository before coding. Do not invent existing files. Do not add unnecessary dependencies. Never log passwords. ACCEPTANCE CRITERIA: Valid users can authenticate. Invalid credentials are rejected. Password hashes are never exposed. Protected endpoints reject unauthenticated requests. TEST REQUIREMENTS: Authentication unit tests Login integration tests Unauthorized-access tests SECURITY CONSIDERATIONS: Secure password handling Safe error messages Token/session security No hardcoded secrets DEFINITION OF DONE: Authentication implementation is reviewed, tests pass, security checks pass, and no unrelated files are modified. --- TASK ID: DB-001 TASK NAME: Create core database schema OBJECTIVE: Create User, Project, Task and AuditLog persistence structures. DEPENDENCIES: None. ACCEPTANCE CRITERIA: Schema can be created successfully. Foreign-key relationships are enforced. Required fields have constraints. Appropriate indexes are considered. TEST REQUIREMENTS: Migration test Constraint tests Relationship tests DEFINITION OF DONE: Migration executes successfully and database constraints behave as specified. --- TASK ID: API-001 TASK NAME: Implement project API DEPENDENCIES: AUTH-001, DB-001 ACCEPTANCE CRITERIA: Authorized users can create projects. Users can retrieve permitted projects. Unauthorized access is rejected. Validation errors are predictable. DEFINITION OF DONE: API contract is implemented, tested and reviewed. --- TASK ID: TASK-001 TASK NAME: Implement task creation DEPENDENCIES: API-001, DB-001, AUTH-001 ACCEPTANCE CRITERIA: Valid tasks are created. Invalid project IDs are rejected. Unauthorized users cannot create tasks. Assignee authorization is checked. DEFINITION OF DONE: Task creation works through the API with unit and integration coverage. --- PHASE 8 - AI CODING INSTRUCTION DESIGN AI Coding Instruction for AUTH-001 You are implementing AUTH-001. Before changing anything: 1. Inspect the repository structure. 2. Identify the existing application entry point. 3. Identify existing authentication utilities. 4. Identify the database access pattern. 5. Identify existing test conventions. 6. Do not assume any file, dependency, function, middleware, or service exists. Implement only the authentication foundation described by the approved specification. Requirements: - Implement secure credential validation. - Store only password hashes. - Implement protected-request authentication. - Follow the existing repository architecture. - Reuse existing dependencies where appropriate. - Do not introduce a framework or library without justification. - Do not modify unrelated features. Create or update tests for: - Valid login - Invalid credentials - Missing authentication - Invalid authentication - Password non-disclosure After implementation: 1. Run relevant tests. 2. Inspect failures. 3. Fix implementation defects rather than weakening tests. 4. Run relevant regression tests. 5. Report exactly what was changed. 6. Report actual test results. 7. Do not claim tests passed unless they were actually executed. --- PHASE 9 - IMPLEMENTATION ORDER & DEPENDENCY GRAPH Dependency Graph REQUIREMENTS ↓ DB-001 ↓ AUTH-001 ↓ API-001 ↓ TASK-001 ↓ FRONTEND-001 ↓ INTEGRATION-001 ↓ SECURITY-001 ↓ RELEASE-001 Parallel Work After database contracts are finalized: Authentication + Frontend shell + Test infrastructure can be developed in parallel where repository structure permits. Blocking Dependencies Task APIs depend on database schema. Protected APIs depend on authentication. Frontend task flows depend on API contracts. E2E tests depend on integrated frontend/backend behavior. High-Risk Changes Authentication Authorization Database migrations Task permission logic Deployment configuration --- PHASE 10 - AI-GENERATED CODE REVIEW Review Checklist Correctness Does implementation match requirements? Are edge cases handled? Are business rules enforced? Architecture Does code follow the approved architecture? Are responsibilities separated correctly? Did AI introduce unnecessary abstractions? Security Are permissions enforced server-side? Are inputs validated? Are secrets protected? Are sensitive errors hidden? Testing Are requirements tested? Are failure cases covered? Are tests testing behavior rather than implementation details? Review Finding Format Finding: Member authorization is checked only in the frontend. Evidence: Backend task update endpoint does not verify task ownership. Impact: A malicious user could potentially modify another user's task by calling the API directly. Severity: High Recommended Fix: Add server-side authorization before allowing the status update. --- PHASE 11 - SECURITY & TRUST BOUNDARY REVIEW Authentication Check: Password hashing Token validation Expiration Authentication middleware Credential handling Authorization Verify: Frontend restriction ≠ Security boundary The backend must independently verify permissions. Input Validation Validate: IDs Task title Description Status Dates Request body structure Injection Protection Use parameterized database queries or the selected ORM/query mechanism. Secrets Never allow: JWT_SECRET = "mysecret123" inside source code. Use environment/configuration mechanisms. Sensitive Information Do not expose: Password hashes Database errors Internal stack traces Secrets Internal infrastructure information Security Release Requirement Authentication and authorization tests must pass before production deployment. --- PHASE 12 - TEST EXECUTION & FAILURE TRIAGE Validation Loop Implement ↓ Run targeted tests ↓ Inspect failure ↓ Classify failure ↓ Fix correct layer ↓ Run targeted tests again ↓ Run regression tests Failure Classification Implementation Failure Example: Expected 403 Received 200 Action: Fix authorization implementation. Test Failure Example: Test expects obsolete behavior that conflicts with approved requirements. Action: Review requirement and test together before modifying the test. Environment Failure Example: PostgreSQL service unavailable. Action: Fix test environment rather than changing application behavior. Dependency Failure Example: Package incompatibility. Action: Investigate dependency version compatibility. Requirement Ambiguity Example: Requirement says "users can delete tasks" but does not specify which roles. Action: Stop implementation and resolve the requirement. --- PHASE 13 - INTEGRATION & REGRESSION CONTROL Integration Checklist Authentication → API Valid token accepted. Invalid token rejected. Expired token rejected. API → Database Correct data persisted. Foreign keys enforced. Transactions used where necessary. Frontend → API Request format matches contract. Response format matches contract. Error states are handled. Authorization Test: Admin → allowed Manager → allowed where specified Member → restricted where specified Unauthenticated → rejected Regression Checklist Login still works. Existing projects remain accessible. Existing tasks remain accessible. Task assignment still works. Status changes still work. Unauthorized access remains blocked. --- PHASE 14 - ENGINEERING QUALITY & PRODUCTION HARDENING Reliability Graceful API error handling Database connection handling Transaction safety where required Retry behavior only where appropriate Performance Measure: API latency Database query latency Frontend loading time The 500ms target should be measured rather than assumed. Observability Implement: Structured application logs Error logging Request correlation IDs where appropriate Basic health endpoint Deployment health checks Deployment Production should include: Environment variables Database migration process Health checks Application startup validation Rollback procedure Prototype Shortcuts Potentially acceptable temporarily: Basic dashboard analytics Limited notification system Minimal audit interface Should not be accepted as production shortcuts: Plaintext passwords Missing authorization Hardcoded secrets Unvalidated API input Untracked destructive migrations --- PHASE 15 - RELEASE READINESS & DEFINITION OF DONE Gate Requirement Evidence Status Blocking? G1 Requirements complete Approved specification Pending Yes G2 Acceptance criteria pass Test results Pending Yes G3 Unit tests pass CI output Pending Yes G4 Integration tests pass CI output Pending Yes G5 E2E workflow passes Playwright results Pending Yes G6 Security reviewed Security checklist Pending Yes G7 Regression verified Regression report Pending Yes G8 Observability configured Monitoring evidence Pending Yes G9 Deployment tested Deployment evidence Pending Yes G10 Rollback available Rollback procedure/test Pending Yes Important: The system must not declare production readiness merely because the application compiles. Actual evidence is required. --- PHASE 16 - FINAL AI-ASSISTED SOFTWARE BUILD BLUEPRINT 1. Product Specification A role-based SaaS task management application for small teams. Core capabilities: Authentication User roles Projects Tasks Assignment Status tracking Audit logging --- 2. Architecture Blueprint React ↓ REST API ↓ Express ↓ Service Layer ↓ Repository Layer ↓ PostgreSQL Supporting systems: Authentication Authorization Validation Logging Testing Docker Deployment --- 3. Feature Breakdown Feature Priority Dependency Authentication P0 None Database P0 None Authorization P0 Authentication Projects P0 Database + Auth Tasks P0 Projects + Auth Status Workflow P0 Tasks Dashboard P1 Projects + Tasks Audit Logs P1 Core APIs --- 4. Data & API Contracts Core entities: User Project Task AuditLog Core APIs: POST /api/auth/login GET /api/projects POST /api/projects GET /api/projects/:projectId/tasks POST /api/projects/:projectId/tasks PATCH /api/tasks/:taskId/status All protected endpoints require authentication and appropriate authorization. --- 5. AI CODING TASK BACKLOG Task ID Task Dependency Priority Tests DB-001 Database schema None P0 Migration/constraint AUTH-001 Authentication DB-001 P0 Unit/integration AUTH-002 Authorization AUTH-001 P0 Permission tests API-001 Project API AUTH-002 P0 Integration TASK-001 Task API API-001 P0 Integration TASK-002 Status workflow TASK-001 P0 Unit/integration UI-001 Authentication UI AUTH-001 P0 E2E UI-002 Project UI API-001 P1 Component/E2E UI-003 Task UI TASK-002 P0 E2E SEC-001 Security audit Core implementation P0 Security REL-001 Production hardening Core implementation P0 Deployment REL-002 Release validation All P0 P0 Full regression --- 6. AI CODING INSTRUCTIONS Every AI coding task should follow this pattern: Inspect → Understand → Plan → Modify → Test → Review → Report AI must: Inspect existing repository first. Identify relevant files. Confirm existing patterns. Reuse established architecture. Make the smallest reasonable change. Create/update tests. Run tests. Report actual results. Avoid unrelated refactoring. AI must not: Invent existing APIs. Invent existing files. Rewrite unrelated code. Add unnecessary dependencies. Remove tests to make CI pass. Hardcode secrets. Expand scope without approval. --- 7. TESTING BLUEPRINT Unit Testing Test: Validation Business rules Status transitions Authorization rules Integration Testing Test: Authentication Database persistence Project APIs Task APIs Permission boundaries E2E Testing Critical scenario: Login ↓ Create project ↓ Create task ↓ Assign member ↓ Member logs in ↓ Member updates task ↓ Task becomes DONE Security Testing Test: Authentication bypass Authorization bypass IDOR Injection Input validation Sensitive-data exposure Secret leakage Regression Testing Run the complete critical workflow after major changes. --- 8. CODE REVIEW CHECKLIST Before approving AI-generated code: [ ] Requirement satisfied [ ] Acceptance criteria satisfied [ ] Existing architecture respected [ ] No unnecessary dependencies [ ] Input validation implemented [ ] Authorization enforced [ ] Error handling implemented [ ] Security reviewed [ ] Tests added/updated [ ] Tests actually executed [ ] No unrelated changes [ ] No secrets committed [ ] Database changes reviewed [ ] Backward compatibility considered --- 9. SECURITY REVIEW Critical Security Requirements Passwords must be securely hashed. Authentication must be validated server-side. Authorization must be enforced server-side. Inputs must be validated. Database queries must be safely parameterized. Secrets must come from secure configuration. Sensitive errors must not reach clients. Audit events must not expose sensitive information. --- 10. INTEGRATION & REGRESSION PLAN For every merged AI-generated task: Review diff ↓ Run task tests ↓ Run dependent tests ↓ Run critical E2E tests ↓ Review API compatibility ↓ Review database impact ↓ Merge High-risk changes require additional review before merging. --- 11. PRODUCTION HARDENING PLAN Before production: Configure production secrets. Configure database backups. Test migrations. Configure health checks. Configure error monitoring. Configure structured logging. Verify API authorization. Verify database connection recovery. Test deployment. Test rollback. Verify environment configuration. Review dependency vulnerabilities. --- 12. RELEASE GATES Production release requires: Requirements + Acceptance Tests + Unit Tests + Integration Tests + E2E Tests + Security Review + Regression Tests + Observability + Deployment Validation + Rollback Plan = Release Candidate Any blocking gate without evidence means the release is not ready. --- 13. TECHNICAL RISK REGISTER Risk Impact Likelihood Mitigation Trigger Owner Authorization bug High Medium Server-side permission tests Unauthorized access succeeds Developer Migration failure High Medium Backup + migration testing Migration fails Developer AI introduces regression High Medium Small tasks + regression tests Existing test fails Developer API contract drift Medium Medium Central contracts Frontend/API mismatch Developer Secret exposure Critical Low Secret management + scanning Secret appears in code Developer Performance degradation Medium Medium API/database measurements Latency exceeds target Developer --- 14. OPEN DECISIONS 1. JWT expiration period. 2. Refresh-token strategy. 3. Soft deletion vs permanent task deletion. 4. Audit-log retention period. 5. Production hosting provider. 6. Database backup frequency. 7. Email/password only vs social authentication. These decisions should be resolved before the affected implementation tasks begin. --- 15. RECOMMENDED EXECUTION SEQUENCE 1. Finalize requirements ↓ 2. Resolve critical open questions ↓ 3. Define database schema ↓ 4. Implement authentication ↓ 5. Implement authorization ↓ 6. Implement project APIs ↓ 7. Implement task APIs ↓ 8. Implement status workflow ↓ 9. Build frontend authentication ↓ 10. Build project UI ↓ 11. Build task UI ↓ 12. Run integration testing ↓ 13. Run E2E testing ↓ 14. Security review ↓ 15. Production hardening ↓ 16. Regression validation ↓ 17. Release gate ↓ 18. Production deployment --- 16. FINAL AI-ASSISTED DEVELOPMENT WORKFLOW IDEA ↓ REQUIREMENT RECONSTRUCTION ↓ SPECIFICATION ↓ ARCHITECTURE ↓ DATA & API CONTRACTS ↓ TEST-FIRST ACCEPTANCE CRITERIA ↓ FEATURE DECOMPOSITION ↓ SMALL AI CODING TASK ↓ REPOSITORY INSPECTION ↓ AI IMPLEMENTATION ↓ CODE REVIEW ↓ UNIT TESTING ↓ INTEGRATION TESTING ↓ E2E TESTING ↓ SECURITY VALIDATION ↓ REGRESSION TESTING ↓ PRODUCTION HARDENING ↓ RELEASE GATES ↓ DEPLOYMENT ↓ MONITORING ↓ ITERATION Final Quality Principle AI-generated code ↓ Human review ↓ Automated tests ↓ Security validation ↓ Integration validation ↓ Production evidence The AI is the implementation accelerator. The specification, architecture, tests, security requirements, repository behavior, and human review remain the source of truth.