Advanced Agent Workflows

Level 1 - Copy-paste (beginner):
  Ask question in chat -> copy code -> paste into editor
  AI knows nothing about your project
  Every session starts from zero

Level 2 - Context-aware (intermediate):
  AI reads your files -> makes changes in-place
  You have CLAUDE.md giving project context
  Agent uses Grep/Read to orient itself

Level 3 - Agentic (advanced):
  AI reads, writes, runs tests, fixes failures, iterates
  CLAUDE.md + test suite = AI safety net
  Multiple subagents work in parallel

Level 4 - Autonomous (expert):
  You describe a feature -> AI builds it completely
  Reviews and merges via PR -> AI is a team member
  CI/CD verifies AI work before it reaches production

> I need to build these 4 independent features simultaneously.
  Spawn 4 parallel subagents, one for each:

  Agent 1 - "Email notifications":
  Create app/services/EmailService.php using PHP mail().
  Send notifications for: task assigned, task due, leave approved.

  Agent 2 - "CSV export":
  Add CSV export to TaskController and AttendanceController.
  Use fputcsv(), stream download, no temp file.

  Agent 3 - "Dark mode":
  Add dark mode toggle in header.php.
  Store preference in localStorage.
  CSS in assets/css/dark.css using prefers-color-scheme media query.

  Agent 4 - "Activity log":
  Create activity_log table + ActivityLogger service.
  Log all create/update/delete across all models.

  All agents work independently (different files).
  Report when all 4 are done.

> Build the PaymentService class:
  - processPayment(int $amount, string $token): array
  - refund(string $paymentId, int $amount): bool
  - getStatus(string $paymentId): string

  After building it:
  1. Run the existing PaymentServiceTest.php
  2. If any tests fail, read the error, fix the code
  3. Run tests again
  4. Repeat until all tests pass
  5. Report: "All X tests pass" or tell me what you could not fix

> Implement the complete user registration flow.
  After implementing:
  1. Run: php -l on all changed files (check for syntax errors)
  2. If syntax errors exist, fix them
  3. Run: composer test --filter=RegistrationTest
  4. If tests fail, fix the code
  5. Loop until: php -l passes on all files AND all registration tests pass
  6. Then show me a summary of what was built

# ProjectName - CLAUDE.md

## Architecture (read before every task)
[2-3 sentences: what the app does, main layers, key patterns]

## Directory map
- /app/models/    - Database models (PDO, one class per table)
- /app/services/  - Business logic (no DB access, uses models)
- /app/controllers/ - HTTP handlers (use services, return view/json)
- /views/         - PHP templates (no logic except loops/conditionals)
- /api/           - REST endpoints (JSON only)
- /tests/         - PHPUnit tests (mirror /app/ structure)

## Critical files
- config/app.php     - all constants and env config
- app/Core/DB.php    - singleton PDO connection (use DB::get() not new PDO)
- app/Core/Auth.php  - Auth::user() returns current user or null
- app/Core/Router.php - how routes are defined

## Must-follow conventions
- Method names: camelCase. Class names: PascalCase. Files: PascalCase.php
- All DB queries: prepared statements (no string interpolation)
- Models return null on not found, false on failure, array/object on success
- Controllers never contain SQL
- All output: htmlspecialchars() or use the esc() helper
- No die()/exit() - throw exceptions instead

## Tool preferences
- Use Grep tool, not bash grep
- Use Glob tool, not bash find
- Read files with offset+limit when function is known
- Pipe bash output: | tail -30
- Show changes as diffs, not full rewrites

## Testing
- Run: composer test
- Test files: tests/[Area]/[ClassName]Test.php
- After any code change: run tests and report results

## Known non-obvious things
- [List anything that would surprise a new developer]
- [E.g. "The users table uses tenant_id for multi-tenancy"]
- [E.g. "All times are stored as UTC, displayed as IST"]

Morning (15 min, no AI):
  - Review git log from yesterday
  - Write today's task list in plain English
  - Group by feature area
  - Identify dependencies: what must be done before what?

Per-task session (AI-first):
  1. New session: claude (from project root)
  2. First message: task description + relevant file paths
  3. Let agent work autonomously
  4. Guide tool calls if agent goes broad
  5. Review diff, test manually
  6. Commit with: git add -p (patch mode - review each hunk)

For complex features (multi-file):
  1. Start with: "Plan the implementation.
     List files to create/modify. No code yet."
  2. Review the plan
  3. Approve or adjust: "Looks good. Start with the model."
  4. Build layer by layer

End of day (10 min):
  - git status: any uncommitted changes?
  - Run full test suite: composer test
  - Write tomorrow's task list while context is fresh
  - Close all sessions (fresh context tomorrow)

Weekly:
  - Review AI-generated code added this week
  - Update CLAUDE.md with anything new you learned
  - Archive any obsolete CLAUDE.md sections