> ## Documentation Index
> Fetch the complete documentation index at: https://docs.weventures.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# AI-Assisted Build Workflow

> Master the Claude Code and Codex workflow for maximum productivity

<Note>
  We rely on **Claude Code (planning)** and **Codex (review/iteration)**. You are the **supervisor** - you write prompts, drive structure, check outputs, run code, read logs, and iterate.
</Note>

## Core Planning Ritual

Inside Claude Code, establish your project foundation with these driver documents:

<Steps>
  <Step title="Create claude.md">
    Project summary, constraints, target users, KPIs, and explicit tech stack
  </Step>

  <Step title="Create plan.md">
    Phased implementation plan with tiny milestones and explicit tasks
  </Step>

  <Step title="Create agents.md">
    Define tools, repos, APIs, and roles for each agent
  </Step>

  <Step title="Use Magic Keys">
    Apply depth when needed: `ultrathink`, `think deeply`, `think`
  </Step>
</Steps>

## Driver Documents

### claude.md Template

```markdown theme={null}
# Project: [Name]

## Summary
[2-3 sentences describing the project]

## Tech Stack (BE EXPLICIT)
- Frontend: Next.js 14 + shadcn/ui + Tailwind
- Backend: Supabase + Edge Functions
- AI: LangChain + LangGraph
- Deployment: Vercel

## Constraints
- Use battle-tested OSS libraries wherever possible
- Avoid custom logic unless necessary
- Plan phases so each can be implemented & tested independently

## Target Users
[Who will use this and why]

## Success Metrics
- [KPI 1]
- [KPI 2]
```

### plan.md Structure

```markdown theme={null}
# Implementation Plan

## Phase 0: Foundation (Day 1)
- [ ] Scaffold project with Next.js
- [ ] Configure environments (.env.local)
- [ ] Set up CI/CD pipeline
- [ ] Initialize Sentry

## Phase 1: Core Features (Days 2-3)
- [ ] Auth flow with Supabase
- [ ] Database schema and migrations
- [ ] Seed data
- [ ] Basic UI shell

## Phase 2: Business Logic (Days 4-5)
- [ ] [Feature specific tasks]

## Phase 3: Polish (Day 6)
- [ ] E2E tests
- [ ] Performance optimization
- [ ] Documentation
```

### agents.md Roles

```markdown theme={null}
# Agent Responsibilities

## Claude Code (CC)
- Planning & code generation
- Architecture decisions
- Complex implementations

## Codex
- Code review
- Refactoring suggestions
- Test generation
- Security audits

## Runner
- Execute commands
- Capture logs
- Test execution

## Docs Agent
- Fetch library examples
- API documentation
- Best practices
```

## Prompt Power-Ups

<Tabs>
  <Tab title="Architecture">
    ```text theme={null}
    ultrathink this architecture for edge cases,
    rate limits, and fallbacks
    ```
  </Tab>

  <Tab title="Data Modeling">
    ```text theme={null}
    think deeply about data modeling with
    Postgres for multi-tenant isolation
    ```
  </Tab>

  <Tab title="Testing">
    ```text theme={null}
    Draft unit tests and Playwright specs
    for the new authentication flow
    ```
  </Tab>

  <Tab title="Refactoring">
    ```text theme={null}
    Refactor to remove custom helpers
    in favor of library lodash methods
    ```
  </Tab>
</Tabs>

## From Plan to Code

<Steps>
  <Step title="Repository Setup">
    ```bash theme={null}
    # Create or clone repo
    git clone [repo-url]
    cd [repo-name]
    pnpm i
    ```
  </Step>

  <Step title="Branch Strategy">
    ```bash theme={null}
    # Feature branches
    git checkout -b feat/user-auth

    # Fix branches
    git checkout -b fix/login-error
    ```
  </Step>

  <Step title="Development Loop">
    ```bash theme={null}
    # Start dev server
    pnpm dev

    # Run tests continuously
    pnpm test --watch
    ```
  </Step>

  <Step title="Tight Iteration">
    Feed exact errors/logs to CC/Codex:

    ```text theme={null}
    Getting this TypeScript error:
    [paste exact error]

    Here's the current code:
    [paste relevant code]
    ```
  </Step>
</Steps>

## Effective Prompting

### Good Prompts

<Accordion title="Specific Implementation">
  ```text theme={null}
  Using Next.js 14 app router and Supabase,
  create a protected dashboard route that:
  1. Checks authentication in middleware
  2. Fetches user profile with RLS
  3. Displays data in shadcn DataTable
  Include error boundaries and loading states.
  ```
</Accordion>

<Accordion title="Debug with Context">
  ```text theme={null}
  This Supabase query returns null:
  [paste query]

  RLS policies:
  [paste policies]

  Auth context:
  [paste session info]

  What's wrong and how do I fix it?
  ```
</Accordion>

<Accordion title="Test Generation">
  ```text theme={null}
  Generate Playwright e2e tests for:
  - Login flow with valid credentials
  - Login with invalid credentials
  - Password reset flow
  - Session timeout handling

  Use our existing test helpers from tests/utils.ts
  ```
</Accordion>

### Prompt Templates

<CodeGroup>
  ```text Architecture theme={null}
  I need to architect a [feature] that:
  - Requirement 1
  - Requirement 2

  Current stack:
  - [List your stack]

  Constraints:
  - [Any limitations]

  Provide:
  1. Component structure
  2. Data flow
  3. Error handling strategy
  ```

  ```text Debugging theme={null}
  Error: [paste error]

  Context:
  - File: [filename]
  - Line: [line number]
  - Trigger: [what causes it]

  Relevant code:
  [paste code]

  Previous attempts:
  - [what you tried]

  What's the root cause and solution?
  ```

  ```text Review Request theme={null}
  Review this implementation for:
  - Security vulnerabilities
  - Performance issues
  - Best practice violations
  - Missing edge cases

  Code:
  [paste diff or code]

  Suggest specific improvements.
  ```
</CodeGroup>

## Working with Codex

After Claude Code generates, use Codex for review:

<Steps>
  <Step title="Share Diff">
    ```bash theme={null}
    git diff > changes.diff
    # Paste diff to Codex
    ```
  </Step>

  <Step title="Request Review">
    ```text theme={null}
    Review this diff for:
    - Security issues
    - Performance problems
    - Missing error handling
    - Test coverage gaps
    ```
  </Step>

  <Step title="Iterate">
    Apply suggestions and re-run review until clean
  </Step>
</Steps>

## Common Workflows

<Tabs>
  <Tab title="New Feature">
    1. Update `plan.md` with feature requirements
    2. Ask CC to generate implementation plan
    3. Generate code incrementally
    4. Test each piece locally
    5. Codex review → refactor
    6. Write tests
    7. Commit with conventional message
  </Tab>

  <Tab title="Bug Fix">
    1. Reproduce bug locally
    2. Capture exact error and context
    3. Ask CC for root cause analysis
    4. Generate fix
    5. Verify fix resolves issue
    6. Add regression test
    7. Codex security review
  </Tab>

  <Tab title="Refactor">
    1. Identify code to refactor
    2. Ask Codex for improvement suggestions
    3. Generate refactored version with CC
    4. Ensure tests still pass
    5. Check performance impact
    6. Update documentation
  </Tab>
</Tabs>

## Best Practices

<Warning>
  **Always specify your tech stack explicitly** - don't let AI guess what libraries you're using
</Warning>

<Info>
  **Use battle-tested libraries** - explicitly tell AI to prefer proven OSS over custom implementations
</Info>

<Tip>
  **Small, atomic prompts** work better than large, complex ones. Break down big tasks.
</Tip>

## Troubleshooting

<Accordion title="AI generates wrong library usage">
  Always specify exact versions and import styles:

  ```text theme={null}
  Using Next.js 14 with app router (not pages),
  Supabase JS client v2 (not v1),
  shadcn/ui components from @/components/ui
  ```
</Accordion>

<Accordion title="Generated code doesn't match style">
  Provide examples from your codebase:

  ```text theme={null}
  Follow this pattern from our codebase:
  [paste existing code example]
  ```
</Accordion>

<Accordion title="Complex logic gets confused">
  Break into smaller steps:

  ```text theme={null}
  Step 1: Just create the database schema
  Step 2: Now add the RLS policies
  Step 3: Create the API route
  ```
</Accordion>