Project Name

Last Updated: [Current Month Year]

Brief one-sentence description of what this project does and who it's for.

Roles & Responsibilities

Human (You)

Reads: TECHNICAL.md or equivalent (what's done, what's next, blockers)
Role: Sets direction, provides requirements, reviews final output, approves PRs and deployments
Decides: Strategic direction, priorities, when to merge

Droid Assistant (AI in Chat)

Reads: AGENTS.md + TECHNICAL.md (or equivalent)
Role: Plans work, writes specs in tasks/pending/, reviews droid exec output, coordinates workflow
Never: Writes code directly - always delegates to droid exec
Outputs: Specs, plans, code reviews, guidance

Droid Exec (Autonomous Agent)

Reads: Task specs (tasks/pending/*.md) + AGENTS.md
Role: Executes specs autonomously with TDD (tests first), implements code following conventions
Always: Follows AGENTS.md conventions, commits with co-authorship
Outputs: Code, tests, commits

Workflow: Human directs → Droid Assistant specs → Droid Exec executes → Droid Assistant reviews → Human approves

Core Commands

# Install dependencies
npm install          # or: pip install -e . / cargo build

# Development
npm run dev          # Start dev server (localhost:8080 or specify port)

# Testing
npm test            # Run all tests
npm run test:coverage  # Coverage report (when configured)

# Linting
npm run lint        # Check code style

# Build
npm run build       # Production build

# Deploy
vercel --prod       # Deploy (or your deployment command)

Core Principles

1. TDD (Test-Driven Development)

MANDATORY: Write tests FIRST, then implementation.

# Run tests before and after changes
npm test

Coverage requirement: ≥80% for all new code.

2. Never Write Code Directly

RULE: AI agents NEVER write code directly. Always delegate to droid exec.

Why:

Droid exec follows TDD properly (writes tests first)
You writing code = no tests = bugs in production
Delegation is faster and higher quality

Your role:

✅ Write specs in tasks/pending/
✅ Review droid exec output
✅ Verify correctness
❌ Write code yourself

Example workflow:

# 1. Create spec
vim tasks/pending/feature_name.md

# 2. Commit spec FIRST
git add tasks/pending/feature_name.md
git commit -m "spec: add feature spec"

# 3. Delegate to droid exec
droid exec --auto medium -f tasks/pending/feature_name.md

# 4. Review output and commit
git add [files created by droid]
git commit -m "feat: description (via droid exec)

Co-authored-by: factory-droid[bot] <138933559+factory-droid[bot]@users.noreply.github.com>"

3. Git Workflow

Default: Work on main branch (or specify your default branch)

# Daily workflow
git checkout main
git pull

# Make changes (via droid exec)
git add [specific files]
git commit -m "type: description"
git push

# Feature branches: MAX 24 hours
git checkout -b feat/quick-feature
# Work, commit, merge same day
git checkout main
git merge feat/quick-feature --no-ff
git branch -d feat/quick-feature

Commit message format:

type(scope): description

- Detail 1
- Detail 2

Co-authored-by: factory-droid[bot] <138933559+factory-droid[bot]@users.noreply.github.com>

Types: feat, fix, refactor, docs, chore, test, spec

Project Structure

src/
├── components/         # React components (or your component structure)
├── services/          # Business logic and API clients
├── contexts/          # React context providers (or state management)
├── pages/            # Page components
└── __tests__/        # Tests mirror src/ structure

api/                  # Serverless functions (if applicable)
tasks/
├── pending/          # Not started or in progress
├── completed/        # Done (dated: YYYY-MM-DD_task_name.md)
└── templates/        # Spec templates

docs/                 # Additional documentation

File naming:

Components: PascalCase.tsx
Services: kebab-case.ts
Tests: component.test.ts or service.test.ts
Use @/* imports for absolute paths

Development Patterns & Constraints

Coding style:

Formatter: Prettier (via Vite or similar)
Linter: ESLint
TypeScript strict mode
Single quotes (or specify your preference)
100-char line limit (or specify)
Tabs vs spaces: [SPECIFY]

Component pattern (adapt to your stack):

// Example for React
import { useYourContext } from '@/contexts/YourContext';
import { Button } from '@/components/ui/button';

export function MyComponent() {
  const { data } = useYourContext();
  if (!data) return null;
  return <Button>...</Button>;
}

Service pattern:

// Example service wrapper
export class ApiService {
  async fetchData() {
    // Implementation
  }
}

TDD workflow:

## Write Tests FIRST

Create `__tests__/feature.test.ts`:
- test_function_handles_valid_input()
- test_function_rejects_invalid_input()
- test_function_handles_edge_cases()

Run: npm test
Expected: All tests FAIL (no implementation yet)

## Implement to Make Tests Pass

Create/modify implementation files...

Run: npm test
Expected: All tests PASS ✅

Task Organization & Droid Exec Delegation

Task Workflow

# Mark task complete
python scripts/complete_task.py task_name
# Moves from pending/ to completed/YYYY-MM-DD_task_name.md

Autonomy Levels

--auto low: File operations only (create, edit, delete files)
--auto medium: File operations + commands (npm, pytest, build tools)
--auto high: Production operations (git push, deploys)

Choose based on need:

Run tests? → medium
Install packages? → medium
Just creating/editing files? → low
Push code? → high

Spec Guidelines

Droid exec is SMART - focus on WHAT, not HOW.

Good spec (50-100 lines):

Clear requirements
List tests to write FIRST
Define success criteria
Provide validation steps
Show example patterns

Bad spec:

200+ lines of code examples
Detailed implementation instructions
No mention of tests

TDD section (MANDATORY):

## TDD Approach

### Write Tests FIRST
Create tests/test_feature.test.ts with:
- test_1()
- test_2()

Run: npm test
Expected: FAIL (no implementation)

### Implement to Pass
Create implementation...

Tech Stack

Frontend: React 18 + TypeScript + Vite (or your stack)
Styling: TailwindCSS + shadcn/ui (or your approach)
State: React Context (or Redux/Zustand/etc.)
Testing: Vitest (or Jest/Pytest/etc.)
Build: Vite (or Webpack/etc.)
Deploy: Vercel (or your platform)

Key Patterns & Conventions

API calls:

// Example pattern (adapt to your needs)
const response = await apiService.getData();

State management:

// Example (if using React Context)
const { state, dispatch } = useContext(YourContext);

Error handling:

// Your error handling pattern
try {
  await operation();
} catch (error) {
  console.error('Operation failed:', error);
  // Handle error
}

Testing Standards

Test structure:

src/__tests__/
├── components/          # Component tests
├── services/            # Service tests
└── integration/         # Integration tests

Naming: <module>.test.ts

Coverage: Minimum 80% (critical paths 100%)

Run tests:

npm test                    # All tests
npm run test:coverage       # With coverage

Common Gotchas

[SPECIFIC TO YOUR PROJECT] - Example: "Token scopes need repo + workflow"
[SPECIFIC TO YOUR PROJECT] - Example: "Empty repos: Create README first"
[SPECIFIC TO YOUR PROJECT] - Example: "API rate limits: 5000 req/hour"
Bundle size - Watch if grows beyond [SPECIFY]
Environment vars - Production needs [LIST VARS]
[YOUR GOTCHA] - [YOUR SOLUTION]

External Services & Environment

Required environment variables:

# Core
API_KEY="your-key-here"          # Description
DATABASE_URL="postgres://..."     # Description

# Optional
DEBUG_MODE="false"               # Enables verbose logging

External services:

Service Name - Purpose (e.g., "GitHub OAuth for authentication")
Service Name - Purpose (e.g., "Vercel for deployment")

AI-Specific Rules

Read [TECHNICAL.md/STATUS.md] FIRST every session (if you have one)
Create feature branch before work (if needed, MAX 24 hours)
Write tests before implementation (TDD)
Run tests before committing
Update [STATUS DOC] after completing work
Keep responses SHORT (no walls of text)
Default to delegation (droid exec does work, you review)
Never write code directly
Always deploy to production after fixes (if applicable)
Wait for deployment success before responding to user

Resources

Component Library: [Link] (e.g., ui.shadcn.com)
Droid Exec Docs: [Link to your templates]
Project Status: [TECHNICAL.md or similar] (READ FIRST)
Task Examples: tasks/completed/ for delegation patterns

Quick Start (New Task)

Check [STATUS_DOC] for current status (if applicable)
Review relevant docs
git log --oneline -10 (recent changes)
Write spec in tasks/pending/ (if using droid exec)
Start building!

Note: This AGENTS.md is for AI coding agents. Human contributors should read README.md first.

SPXOmega/AGENTS.md