Project Toolkit Structure

The AI toolkit automatically creates a docs/ directory in your project when you first interact with it. This page explains what each file does and why it exists.

The docs/ Directory

Each project has a docs/ directory that contains all project-specific configuration for the agent system:

your-project/

├── docs/

├── project.json← Project configuration

├── CONVENTIONS.md← Coding conventions

├── prds/← Product requirements

├── prd-feature-name.json

├── skills/← Project-specific skills

└── session-locks.json← Multi-session coordination

├── src/

└── ...

project.json

This is the main configuration file that tells agents about your project:

{
  "name": "My SaaS App",
  "description": "A multi-tenant SaaS application",
  
  // Path configuration
  "codeRoot": ".",           // Root of source code (default: ".")
  "toolkitPath": "docs/",    // Where toolkit files live (default: "docs/")
  
  // Tech stack info for context-aware code generation
  "stack": {
    "frontend": "react",
    "backend": "node",
    "database": "postgres",
    "hosting": "vercel"
  },
  
  // Development server configuration
  "devServer": {
    "startCommand": "npm run dev",
    "port": 3000,            // Set to null if no dev server needed
    "readyPattern": "Ready"
  },
  
  // Environment-specific overrides
  "environments": {
    "local": { "baseUrl": "http://localhost:3000" },
    "staging": { "baseUrl": "https://staging.myapp.com" }
  },
  
  // Features that enable specific behaviors
  "features": {
    "authentication": true,
    "multiTenant": true,
    "api": true,
    "email": true
  },
  
  // Authentication configuration for E2E testing
  "authentication": {
    "provider": "supabase",   // supabase | nextauth | custom
    "method": "email-password",
    "loginUrl": "/login",
    "headless": {
      "enabled": true,
      "method": "cli",          // api | cli
      "command": "pnpm cli auth:test-token --email $TEST_EMAIL",
      "responseFormat": "json", // json | text | env
      "tokenPath": "accessToken",
      "refreshTokenPath": "refreshToken",
      "sessionStorage": "localStorage"  // cookies | localStorage | both
    },
    "acquisition": {            // Human-readable auth flow description
      "description": "Use CLI to get a test token, inject into localStorage",
      "steps": [
        "1. Ensure SUPABASE_SERVICE_ROLE_KEY is set in .env.local",
        "2. Run: pnpm cli auth:test-token --email $TEST_EMAIL",
        "3. Parse JSON output for accessToken and refreshToken",
        "4. Inject tokens into browser localStorage"
      ],
      "fallbackToUI": true,
      "notes": "CLI command requires the service role key. Token expires after 1 hour."
    },
    "credentials": {
      "email": "test@example.com",
      "password": "env:TEST_PASSWORD"  // Use env: prefix for secrets
    }
  },

  // Post-change workflow for verification
  "postChangeWorkflow": {
    "strategy": "auto",       // auto | rebuild-then-launch-app | ensure-electron-running
    "skip": ["*.md", "*.txt", "docs/**"],  // Skip verification for these patterns
    "rebuild": {
      "command": "npm run build",
      "timeout": 120000
    }
  },
  
  // Quality gates that must pass before commits
  "qualityGates": {
    "lint": "npm run lint",
    "typecheck": "npm run typecheck",
    "test": "npm run test"
  },
  
  // Controls which automated Playwright invocations are enabled (all default to true)
  "testVerifySettings": {
    "adHocUIVerify_Analysis": true,       // Ad-hoc: Playwright analysis probe after changes
    "adHocUIVerify_StoryTest": true,      // Ad-hoc: write/run Playwright tests for tasks
    "prdUIVerify_Analysis": true,         // PRD: per-story Playwright verification
    "prdUIVerify_StoryTest": true,        // PRD: write/run per-story Playwright tests
    "prdUIVerify_PRDCompletionTest": true // PRD: deferred UI tests at completion
  },
  
  // Git workflow configuration
  "git": {
    "defaultBranch": "main",
    "autoCommit": true,      // Set to false for manual commit control
    "agentWorkflow": {
      "workBranch": "main",        // Where agents work
      "pushTo": "main",            // Where to push changes
      "createPrTo": "main",        // PR target branch
      "requiresHumanApproval": []  // Branches that block auto-merge
    }
  },
  
  // Integration-specific configurations
  "integrations": {
    "stripe": true,
    "resend": true
  },
  
  // Agent behavior configuration
  "agents": {
    "multiSession": false    // Deprecated — coordination is now always-on
  },
  
  // Planning considerations passed through to PRDs
  "planning": {
    "considerations": {
      // Project-level guidance for the Planner agent
    }
  }
}

Path Configuration

codeRoot and toolkitPath tell agents where to find your source code and toolkit files.

Stack Info

Tells agents which frameworks and languages you use, so they generate appropriate code patterns.

Dev Server

Configure how to start your dev server. Set port: null for projects without a dev server (CLI tools, libraries).

Environments

Define environment-specific settings like base URLs for local, staging, and production testing.

Features

Boolean flags that unlock specific agent behaviors and enable project-specific skill generation.

Authentication

Configure how E2E tests authenticate. See the Authentication page for details.

Quality Gates

Commands that agents must run and pass before committing changes. Ensures code quality is maintained.

Git Configuration

Control commit behavior with autoCommit and agentWorkflow. See Git Configuration below.

Integrations

Third-party services your project uses. Agents can generate integration-specific code patterns.

Planning Considerations

The planning.considerations object passes project-level guidance through to PRDs. Planner uses this for consistent architectural decisions across features.

Multi-Platform Apps

Projects with multiple deployment targets (web app, Electron desktop, mobile) use the apps[] array to configure each platform independently:

{
  "name": "My Cross-Platform App",
  
  // Multiple app targets
  "apps": [
    {
      "name": "web",
      "type": "web",
      "devServer": {
        "startCommand": "npm run dev",
        "port": 3000,
        "readyPattern": "Ready"
      },
      "baseUrl": "http://localhost:3000"
    },
    {
      "name": "desktop",
      "type": "electron",
      "devServer": {
        "startCommand": "npm run electron:dev",
        "port": null,  // Electron doesn't use a port
        "readyPattern": "Electron ready"
      },
      "electron": {
        "executablePath": "dist/MyApp-darwin-arm64/MyApp.app",
        "devLaunchArgs": [".", "--no-sandbox"]
      },
      // Architecture detection for verification strategy
      "webContent": "bundled",  // bundled | remote | hybrid
      "remoteUrl": null         // Only for remote/hybrid apps
    }
  ]
}

Web App Entry

Standard web apps use type: "web". E2E tests run via Playwright against the dev server URL.

Electron App Entry

Desktop apps use type: "electron". The electron.executablePath points to the built app, while devLaunchArgs configures development mode. See the Electron Desktop Testing section for details.

Desktop Architecture Detection

The webContent field tells agents how the app loads its UI: bundled (file:// protocol), remote (loads from URL), or hybrid (shell + remote content). This enables architecture-aware verification strategy selection.

When to Use apps[] vs Top-Level devServer

• Single platform: Use top-level devServer config (simpler)

• Multiple platforms: Use apps[] array for independent configuration

• Agents automatically detect which target to use based on the test being run

Git Configuration

Control how agents handle git commits with the git configuration block:

{
  "git": {
    "defaultBranch": "main",
    "autoCommit": true,
    "agentWorkflow": {
      "workBranch": "main",
      "pushTo": "main",
      "createPrTo": "main",
      "requiresHumanApproval": ["production"]
    }
  }
}

agentWorkflow

Defines where agents push code and create PRs. This replaces the deprecated trunkMode and autoPush settings.

  • workBranch— Where agents create feature branches from
  • pushTo— Where to push changes (same as workBranch for trunk-based)
  • createPrTo— Target branch for PRs
  • requiresHumanApproval— Branches where agents can create PRs but cannot auto-merge

Protected Branch Behavior

For branches in requiresHumanApproval:

  • • Direct push — BLOCKED (agents cannot push directly)
  • • Create PR — ALLOWED (agents can create PRs for review)
  • • Auto-merge — BLOCKED (human must approve and merge)

autoCommit: true (default)

Agents create commits after completing each story or unit of work. This is the standard mode for fully autonomous operation.

autoCommit: false

Agents stage changes but do not commit. Use this when you want to:

  • • Review all changes before committing
  • • Combine multiple agent work sessions into a single commit
  • • Use your own commit message format
  • • Run additional validation before committing

Identity Lock Protection

When agents commit, they verify the git identity matches the configured user to prevent accidental commits under the wrong identity. This is especially important in multi-machine setups where git config may differ between machines.

CONVENTIONS.md

A markdown file describing your team's coding conventions. Agents read this to understand how to write code that fits your codebase:

Example conventions to document:

  • File naming patterns (PascalCase for components, kebab-case for routes)
  • Component structure and patterns (functional vs class components)
  • State management approach (React Query, Zustand, etc.)
  • Styling conventions (Tailwind classes, CSS-in-JS, design tokens)
  • Testing patterns (what to test, naming conventions)
  • Error handling approaches
  • API design patterns (REST conventions, error responses)
💬

Refine Conventions Collaboratively with @toolkit

You don't have to write CONVENTIONS.md alone! Ask @toolkit to analyze your codebase and help you refine conventions together. The more specific your conventions, the more consistent agent-generated code will be.

Example prompts:

@toolkit review my CONVENTIONS.md and suggest improvements based on my codebase

@toolkit add error handling conventions based on how we handle errors in src/

@toolkit document our component patterns from the existing components

PRDs (Product Requirements)

PRDs are JSON files in docs/prds/ that define features as a series of user stories:

{
  "project": "My SaaS App",
  "branchName": "feature/dark-mode",
  "description": "Add dark mode support",
  "userStories": [
    {
      "id": "US-001",
      "title": "Theme toggle component",
      "description": "User can toggle theme",
      "acceptanceCriteria": [
        "Toggle button in header",
        "Persists preference to localStorage"
      ],
      "priority": 1,
      "passes": false  // ← Agents update this!
    }
  ]
}
✓

passes: true/false — Agents update this as they complete each story, giving you progress visibility.

→

Priority order — Stories are implemented in priority order, so dependencies are respected.

Session Locks

The session-locks.json file prevents conflicts when multiple agent sessions work on the same project:

How Session Locks Work

• When an agent starts working on a PRD, it acquires a lock

• Other agents see the lock and either wait or work on different PRDs

• When work is complete (PR merged or abandoned), the lock is released

• This enables parallel work without merge conflicts

Bootstrapping

When you add a new project, the agent uses a streamlined quick intake flow that gets you from zero to building in minutes:

1. Quick Intake

Provide your project name and context — paste text descriptions, images, or specs directly. The agent extracts requirements from whatever you give it.

2. Optional GitHub Clone

If you have an existing repo, provide the GitHub URL and the agent clones it before detection. Otherwise, start fresh or use a scaffold.

GitHub URL (optional): https://github.com/org/my-project

3. Stack Detection + Setup

The agent auto-detects your tech stack and generates project.json and CONVENTIONS.md. Agent system setup is assumed by default.

4. Automatic PRD Kickoff

After setup, the agent immediately transitions to PRD creation — defining your first feature scope with architecture options. No separate step needed.

You can also explicitly trigger bootstrap using the project-bootstrap skill:

@planner add a new project