Skip to content

Instantly share code, notes, and snippets.

@PeterHa-UoH

PeterHa-UoH/AGENTS.md

Forked from dctmfoo/AGENTS.md
Created October 13, 2025 07:09
Show Gist options
  • Save PeterHa-UoH/48c03d74d65d7e97b1b912aadf300d47 to your computer and use it in GitHub Desktop.
Save PeterHa-UoH/48c03d74d65d7e97b1b912aadf300d47 to your computer and use it in GitHub Desktop.
Download ZIP

Revisions

  1. @dctmfoo dctmfoo revised this gist Oct 11, 2025. 1 changed file with 176 additions and 314 deletions.
    490 changes: 176 additions & 314 deletions AGENTS.md
    View file
    Original file line number Diff line number Diff line change
    @@ -1,401 +1,263 @@
    # Project Name
    # AGENTS.md - Essential Briefing for AI Agents

    **Last Updated**: [Current Month Year]

    Brief one-sentence description of what this project does and who it's for.
    > **For human contributors:** See README.md for getting started guide.
    ---

    ## Roles & Responsibilities
    ## 🤖 THE 3-ENTITY WORKFLOW (CORE CONCEPT)

    This project uses a 3-entity collaboration pattern between Human, Droid Assistant, and Droid Exec.

    ### 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
    - **Reads:** PROJECT_STATUS.md or equivalent (current progress, blockers)
    - **Role:** Sets direction, provides requirements, reviews final output, approves changes
    - **Decides:** What to build, priorities, when work is complete

    **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
    - **Reads:** AGENTS.md (this file) + PROJECT_STATUS.md
    - **Role:** Plans work, writes specs in `tasks/`, delegates to Droid Exec, reviews output
    - **NEVER:** Writes code directly - always delegates to Droid Exec
    - **Does:** Planning, spec writing, code review, coordination

    **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

    ```bash
    # 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)
    - **Reads:** Task specs (`tasks/*.md`) + AGENTS.md
    - **Role:** Executes specs autonomously, implements code with TDD (tests first)
    - **Always:** Follows AGENTS.md conventions, writes tests before code
    - **Does:** Coding, testing, implementation

    # Linting
    npm run lint # Check code style
    ### The Workflow Pattern

    # 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.

    ```bash
    # Run tests before and after changes
    npm test
    Human → Tells Droid Assistant what to build
    ↓
    Droid Assistant → Creates spec in tasks/
    ↓
    Droid Assistant → Commits spec FIRST
    ↓
    Droid Assistant → Runs: droid exec --auto medium -f tasks/spec.md
    ↓
    Droid Exec → Writes tests → Implements code → All tests pass
    ↓
    Droid Assistant → Reviews output, tests deployment (if needed)
    ↓
    Droid Assistant → Commits Droid Exec's work
    ↓
    Human → Tests and provides feedback → Iteration continues
    ```

    **Coverage requirement:** ≥80% for all new code.

    ### 2. Never Write Code Directly
    ### Critical Rules

    **RULE:** AI agents NEVER write code directly. Always delegate to droid exec.
    1. **TDD is MANDATORY** when writing code
    - Droid Exec writes tests FIRST, then implementation
    - For simple work (HTML/CSS, docs), TDD may not be needed - use judgment

    **Why:**
    - Droid exec follows TDD properly (writes tests first)
    - You writing code = no tests = bugs in production
    - Delegation is faster and higher quality
    2. **NEVER write code directly**
    - Droid Assistant creates specs and delegates to Droid Exec
    - If you catch yourself writing code, STOP and write a spec instead

    **Your role:**
    - ✅ Write specs in `tasks/pending/`
    - ✅ Review droid exec output
    - ✅ Verify correctness
    - ❌ Write code yourself

    **Example workflow:**
    ```bash
    # 1. Create spec
    vim tasks/pending/feature_name.md
    3. **Always commit spec before delegating**
    - Keeps git history clean (spec → implementation → completion)
    - Easy to see what was requested vs what was produced

    # 2. Commit spec FIRST
    git add tasks/pending/feature_name.md
    git commit -m "spec: add feature spec"
    4. **API key required for Droid Exec**
    ```bash
    export FACTORY_API_KEY="your-key-from-https://app.factory.ai/settings/api-keys"
    ```

    # 3. Delegate to droid exec
    droid exec --auto medium -f tasks/pending/feature_name.md
    ### Example Workflow (Real Conversation)

    # 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>"
    ```
    Human: I need a contact form with validation
    Droid: I'll create a spec for this. Let me check the project structure first.
    $ ls src/components/
    # [output shown]
    ━━━ Step 1: Droid Creates Spec ━━━
    Droid: Creating task spec with TDD requirements...
    $ vim tasks/contact_form.md
    # Part of tasks/contact_form.md:
    #
    # Create contact form component with validation
    # - Email, name, message fields
    # - Validation: email format, required fields
    # - Submit handler with loading state
    #
    # TDD Approach:
    # - Write tests FIRST in __tests__/ContactForm.test.tsx
    # - test_validates_email_format()
    # - test_prevents_submit_when_invalid()
    # - test_shows_loading_state()
    # - test_handles_submit_success()
    #
    # Then implement ContactForm.tsx to make tests pass
    ━━━ Step 2: Droid Commits Spec ━━━
    Droid: Committing spec before delegation...
    $ git add tasks/contact_form.md
    $ git commit -m "spec: add contact form with validation"
    ━━━ Step 3: Droid Delegates to Droid Exec ━━━
    Droid: Delegating to Droid Exec...
    $ droid exec --auto medium -f tasks/contact_form.md
    # Droid Exec: Writes tests FIRST → Implements component → All tests pass ✓
    ━━━ Step 4: Droid Reviews Output ━━━
    Droid: Reviewing what Droid Exec created...
    $ cat src/components/ContactForm.tsx
    $ npm test __tests__/ContactForm.test.tsx
    # ✓ 4/4 tests passing
    ━━━ Step 5: Droid Commits Work ━━━
    Droid: Tests pass, committing...
    $ git add src/components/ContactForm.tsx __tests__/ContactForm.test.tsx
    $ git commit -m "feat: add contact form with validation (via droid exec)
    ### 3. Git Workflow

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

    ```bash
    # Daily workflow
    git checkout main
    git pull
    Co-authored-by: factory-droid[bot] <138933559+factory-droid[bot]@users.noreply.github.com>"
    # Make changes (via droid exec)
    git add [specific files]
    git commit -m "type: description"
    git push
    ━━━ Step 6: Human Tests ━━━
    Human: Form works great! Can you add a character limit to the message field?
    # 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
    Droid: I'll update the spec and re-delegate to Droid Exec...
    ```

    **Commit message format:**
    ```
    type(scope): description
    ### Droid Exec Autonomy Levels

    - Detail 1
    - Detail 2
    - **`--auto low`**: File operations only (create, edit, delete)
    - **`--auto medium`**: File ops + commands (npm, pip, pytest, git commit)

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

    **Types:** `feat`, `fix`, `refactor`, `docs`, `chore`, `test`, `spec`
    **How to choose:**
    - Need to run tests? → medium
    - Need to install packages? → medium
    - Just creating/editing files? → low

    ---

    ## Project Structure
    ### Reinforcing the Workflow

    ```
    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
    ```
    **Pro Tip:** If Droid Assistant starts writing code directly or skips delegation steps, remind it:

    > "Follow AGENTS.md - delegate to droid exec instead."
    **File naming:**
    - Components: `PascalCase.tsx`
    - Services: `kebab-case.ts`
    - Tests: `component.test.ts` or `service.test.ts`
    - Use `@/*` imports for absolute paths
    Droid learns from feedback and will correct course.

    ---

    ## Development Patterns & Constraints
    ## 📁 Project Setup

    **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):
    ```typescript
    // 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>;
    }
    ```
    [AI Agent: Insert your project structure, file naming conventions, and import patterns here]

    **Service pattern:**
    ```typescript
    // Example service wrapper
    export class ApiService {
    async fetchData() {
    // Implementation
    }
    }
    Example:
    ```
    src/
    ├── components/ # React components
    ├── services/ # Business logic
    └── __tests__/ # Tests mirror src/
    **TDD workflow:**
    ```markdown
    ## 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 ✅
    tasks/ # Task specs for droid exec
    ```

    ---

    ## Task Organization & Droid Exec Delegation
    ## 🛠️ Core Commands

    ### Task Workflow
    [AI Agent: Insert your project's essential commands here]

    Example:
    ```bash
    # 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):**
    ```markdown
    ## 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...
    npm install # Install dependencies
    npm run dev # Start dev server
    npm test # Run tests
    npm run build # Production build
    ```

    ---

    ## Tech Stack
    ## 🎨 Coding Conventions

    **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)
    [AI Agent: Insert your formatting, linting, and code style rules here]

    ---
    Example:
    - Formatter: Prettier
    - Linter: ESLint
    - TypeScript strict mode
    - 100-char line limit

    ## Key Patterns & Conventions
    ---

    **API calls:**
    ```typescript
    // Example pattern (adapt to your needs)
    const response = await apiService.getData();
    ```
    ## 🧪 Testing Standards

    **State management:**
    ```typescript
    // Example (if using React Context)
    const { state, dispatch } = useContext(YourContext);
    ```
    [AI Agent: Insert your testing approach, coverage requirements, and test organization here]

    **Error handling:**
    ```typescript
    // Your error handling pattern
    try {
    await operation();
    } catch (error) {
    console.error('Operation failed:', error);
    // Handle error
    }
    ```
    Example:
    - Minimum 80% coverage
    - Tests mirror src/ structure
    - Test naming: `component.test.ts`

    ---

    ## Testing Standards
    ## 🔑 Environment & Services

    **Test structure:**
    ```
    src/__tests__/
    ├── components/ # Component tests
    ├── services/ # Service tests
    └── integration/ # Integration tests
    ```

    **Naming:** `<module>.test.ts`

    **Coverage:** Minimum 80% (critical paths 100%)
    [AI Agent: Insert required environment variables and external service configurations here]

    **Run tests:**
    Example:
    ```bash
    npm test # All tests
    npm run test:coverage # With coverage
    API_KEY="your-key"
    DATABASE_URL="postgres://..."
    ```

    ---

    ## Common Gotchas
    ## ⚠️ Project-Specific 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]
    [AI Agent: Insert project-specific issues, workarounds, and important notes here]

    Example:
    - Empty repos: Create README first
    - API rate limits: 5000 req/hour
    - Bundle size: Keep under 1MB

    ---

    ## External Services & Environment
    ## 🚀 Git Workflow

    **Required environment variables:**
    ```bash
    # Core
    API_KEY="your-key-here" # Description
    DATABASE_URL="postgres://..." # Description
    [AI Agent: Insert your branching strategy, commit message format, and merge policies here]

    # Optional
    DEBUG_MODE="false" # Enables verbose logging
    Example:
    ```bash
    git checkout main
    git pull
    # make changes via droid exec
    git commit -m "type: description"
    git push
    ```

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

    ---

    ## AI-Specific Rules

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

    ---
    [AI Agent: Insert your framework, libraries, and tooling choices here]

    ## 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
    Example:
    - Frontend: React 18 + TypeScript
    - Styling: TailwindCSS
    - Testing: Vitest
    - Deploy: Vercel

    ---

    ## Quick Start (New Task)
    ## 🔗 Resources

    [AI Agent: Insert links to documentation, templates, and helpful resources here]

    1. Check `[STATUS_DOC]` for current status (if applicable)
    2. Review relevant docs
    3. `git log --oneline -10` (recent changes)
    4. Write spec in `tasks/pending/` (if using droid exec)
    5. Start building!
    Example:
    - Droid Exec Examples: `tasks/` directory
    - Component Library: ui.shadcn.com
    - API Docs: [link]

    ---

    **Note:** This AGENTS.md is for AI coding agents. Human contributors should read README.md first.
    **Remember:** The 3-entity workflow (Human → Droid Assistant → Droid Exec) is the core pattern. When in doubt, refer back to the workflow diagram at the top.
  2. @dctmfoo dctmfoo revised this gist Oct 11, 2025. 1 changed file with 272 additions and 158 deletions.
    430 changes: 272 additions & 158 deletions AGENTS.md
    View file
    Original file line number Diff line number Diff line change
    @@ -1,26 +1,58 @@
    # AGENTS.md - Guide for AI Agents
    # Project Name

    > **Copy this template to new repositories and customize for your project.**
    **Last Updated**: [Current Month Year]

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

    Keep documentation minimal and focused:
    ---

    ## 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

    ---

    1. **AGENTS.md** (this file) - HOW to work on this codebase
    2. **PROJECT_STATUS.md** - WHAT's done, what's next, current blockers
    3. **README.md** - Project overview for humans
    ## Core Commands

    **Rule:** Update AGENTS.md when conventions change. Update PROJECT_STATUS.md after every task.
    ```bash
    # Install dependencies
    npm install # or: pip install -e . / cargo build

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

    **Project Name:** [Your Project Name]
    # Testing
    npm test # Run all tests
    npm run test:coverage # Coverage report (when configured)

    **Goal:** [One sentence describing the project goal]
    # Linting
    npm run lint # Check code style

    **Tech Stack:** [Languages, frameworks, key tools]
    # Build
    npm run build # Production build

    **See PROJECT_STATUS.md for current sprint and next steps.**
    # Deploy
    vercel --prod # Deploy (or your deployment command)
    ```

    ---

    ## Core Principles

    @@ -29,11 +61,8 @@ Keep documentation minimal and focused:
    **MANDATORY:** Write tests FIRST, then implementation.

    ```bash
    # Run tests
    pytest tests/ -v

    # Check coverage
    pytest tests/ --cov=. --cov-report=term-missing
    # Run tests before and after changes
    npm test
    ```

    **Coverage requirement:** ≥80% for all new code.
    @@ -48,240 +77,325 @@ pytest tests/ --cov=. --cov-report=term-missing
    - Delegation is faster and higher quality

    **Your role:**
    - ✅ Write specs
    - ✅ Write specs in `tasks/pending/`
    - ✅ Review droid exec output
    - ✅ Verify correctness
    - ❌ Write code
    - ❌ Write code yourself

    ### 3. Git Workflow (Simplified)
    **Example workflow:**
    ```bash
    # 1. Create spec
    vim tasks/pending/feature_name.md

    **Default:** Work on `develop` branch
    # 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)

    ```bash
    # Daily workflow
    git checkout develop
    git checkout main
    git pull

    # Make changes (via droid exec)
    git add files
    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
    ```

    **Feature branches:** Only if needed, MAX 24 hours
    **Commit message format:**
    ```
    type(scope): description
    ```bash
    # Create short-lived branch
    git checkout -b feat/quick-feature
    - Detail 1
    - Detail 2
    # Work (max 1 day!)
    git commit -m "feat: something"
    Co-authored-by: factory-droid[bot] <138933559+factory-droid[bot]@users.noreply.github.com>
    ```

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

    ---

    ## Project Structure

    # Merge same day
    git checkout develop
    git merge feat/quick-feature --no-ff
    git branch -d feat/quick-feature
    git push
    ```
    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
    **Rules:**
    - Merge daily (no long-lived branches)
    - Never commit to `master` directly
    - Feature branches MAX 24 hours
    docs/ # Additional documentation
    ```

    ## Droid Exec Delegation
    **File naming:**
    - Components: `PascalCase.tsx`
    - Services: `kebab-case.ts`
    - Tests: `component.test.ts` or `service.test.ts`
    - Use `@/*` imports for absolute paths

    ### When to Delegate
    ---

    **ALWAYS delegate if:**
    - Writing any code (even "quick" fixes)
    - Creating new files
    - Modifying multiple files
    - Writing tests
    - Bug fixes
    ## 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):
    ```typescript
    // 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>;
    }
    ```

    **Only do yourself:**
    - Reading/analyzing code
    - Writing specs
    - Code review
    - Planning with user
    **Service pattern:**
    ```typescript
    // Example service wrapper
    export class ApiService {
    async fetchData() {
    // Implementation
    }
    }
    ```

    ### Delegation Workflow
    **TDD workflow:**
    ```markdown
    ## Write Tests FIRST

    ```bash
    # 1. Create spec in tasks/pending/
    vim tasks/pending/feature_name.md
    Create `__tests__/feature.test.ts`:
    - test_function_handles_valid_input()
    - test_function_rejects_invalid_input()
    - test_function_handles_edge_cases()

    # 2. Commit spec FIRST
    git add tasks/pending/feature_name.md
    git commit -m "spec: add feature spec"
    Run: npm test
    Expected: All tests FAIL (no implementation yet)

    # 3. Run droid exec
    droid exec --auto {low|medium|high} -f tasks/pending/feature_name.md
    ## Implement to Make Tests Pass

    # 4. Review ALL output
    # - Read generated files
    # - Run tests
    # - Verify correctness
    Create/modify implementation files...

    # 5. Commit droid exec output
    git add {files}
    git commit -m "feat: description (via droid exec)
    Run: npm test
    Expected: All tests PASS ✅
    ```

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

    ## Task Organization & Droid Exec Delegation

    # 6. Move spec to completed
    mv tasks/pending/feature_name.md tasks/completed/$(date +%Y-%m-%d)_feature_name.md
    git add tasks/
    git commit -m "chore: mark feature as completed"
    ### Task Workflow

    ```bash
    # 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 (pip, npm, pytest, build tools)
    - **`--auto medium`**: File operations + commands (npm, pytest, build tools)
    - **`--auto high`**: Production operations (git push, deploys)

    **How to choose:**
    - Need to run tests? → medium
    - Need to install packages? → medium
    **Choose based on need:**
    - Run tests? → medium
    - Install packages? → medium
    - Just creating/editing files? → low
    - Need to push code? → high
    - Push code? → high

    ### Spec Guidelines

    **Droid exec is SMART** - don't write implementation code for it.
    **Droid exec is SMART** - focus on WHAT, not HOW.

    **Good spec:**
    - 50-100 lines
    - Focus on WHAT (not HOW)
    - List requirements clearly
    - Include TDD section (tests to write FIRST)
    **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 in every spec):**

    **TDD section (MANDATORY):**
    ```markdown
    ## TDD Approach

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

    Create `tests/test_feature.py` with:
    - test_function_handles_valid_input()
    - test_function_rejects_invalid_input()
    - test_function_handles_edge_cases()

    Run: pytest tests/test_feature.py -v
    Expected: All tests FAIL (no implementation yet)

    ### Implement to Make Tests Pass
    Run: npm test
    Expected: FAIL (no implementation)

    Create/modify implementation files...
    ### Implement to Pass
    Create implementation...
    ```

    ## Task Organization
    ---

    ```
    tasks/
    ├── pending/ # Not started or in progress
    ├── completed/ # Done (dated: 2025-10-11_task_name.md)
    └── templates/ # Spec templates
    ```
    ## Tech Stack

    **Completion script:**
    ```bash
    # Mark task complete
    python scripts/complete_task.py task_name
    # Moves from pending/ to completed/YYYY-MM-DD_task_name.md
    # Updates PROJECT_STATUS.md
    ```
    **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)

    ## Code Conventions
    ---

    **Style:**
    - Formatter: [Black / Prettier / your choice]
    - Linter: [Flake8 / ESLint / your choice]
    - Files: `lowercase_with_underscores`
    - Classes: `PascalCase`
    - Functions: `snake_case`
    ## Key Patterns & Conventions

    **Commit messages:**
    **API calls:**
    ```typescript
    // Example pattern (adapt to your needs)
    const response = await apiService.getData();
    ```
    type(scope): description

    Types: feat, fix, test, docs, refactor, chore
    **State management:**
    ```typescript
    // Example (if using React Context)
    const { state, dispatch } = useContext(YourContext);
    ```

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

    ---

    ## Testing Standards

    **Test structure:**
    ```
    tests/
    ├── test_module_name.py # Unit tests
    ├── test_integration.py # Integration tests
    └── conftest.py # Pytest fixtures
    src/__tests__/
    ├── components/ # Component tests
    ├── services/ # Service tests
    └── integration/ # Integration tests
    ```

    **Naming:**
    - Test files: `test_<module_name>.py`
    - Test functions: `test_<function>_<scenario>()`
    - Test classes: `Test<ClassName>`
    **Naming:** `<module>.test.ts`

    **Coverage:**
    - Minimum: 80%
    - Critical paths: 100%
    - Check: `pytest --cov=. --cov-report=term-missing`

    ## Common Commands
    **Coverage:** Minimum 80% (critical paths 100%)

    **Run tests:**
    ```bash
    # Test
    pytest tests/ -v
    npm test # All tests
    npm run test:coverage # With coverage
    ```

    ---

    ## Common Gotchas

    # Format
    [your formatter command]
    - **[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]

    ---

    # Lint
    [your linter command]
    ## External Services & Environment

    # Run project
    [your run command]
    **Required environment variables:**
    ```bash
    # 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

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

    ---

    ## Resources

    - **Droid Exec Docs:** [Link to your droid exec documentation]
    - **Project Status:** PROJECT_STATUS.md (READ FIRST)
    - **Task Examples:** `tasks/completed/` for delegation patterns
    - **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

    ---

    ## Customization Checklist
    ## Quick Start (New Task)

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

    When copying this template to a new repo:
    ---

    - [ ] Update project name and goal
    - [ ] Update tech stack
    - [ ] Update test commands
    - [ ] Update formatting/linting tools
    - [ ] Update common commands
    - [ ] Add project-specific conventions
    - [ ] Create PROJECT_STATUS.md
    - [ ] Create tasks/ directory structure
    **Note:** This AGENTS.md is for AI coding agents. Human contributors should read README.md first.
  3. @dctmfoo dctmfoo created this gist Oct 10, 2025.
    287 changes: 287 additions & 0 deletions AGENTS.md
    View file
    Original file line number Diff line number Diff line change
    @@ -0,0 +1,287 @@
    # AGENTS.md - Guide for AI Agents

    > **Copy this template to new repositories and customize for your project.**
    ## Documentation Structure

    Keep documentation minimal and focused:

    1. **AGENTS.md** (this file) - HOW to work on this codebase
    2. **PROJECT_STATUS.md** - WHAT's done, what's next, current blockers
    3. **README.md** - Project overview for humans

    **Rule:** Update AGENTS.md when conventions change. Update PROJECT_STATUS.md after every task.

    ## Project Overview

    **Project Name:** [Your Project Name]

    **Goal:** [One sentence describing the project goal]

    **Tech Stack:** [Languages, frameworks, key tools]

    **See PROJECT_STATUS.md for current sprint and next steps.**

    ## Core Principles

    ### 1. TDD (Test-Driven Development)

    **MANDATORY:** Write tests FIRST, then implementation.

    ```bash
    # Run tests
    pytest tests/ -v

    # Check coverage
    pytest tests/ --cov=. --cov-report=term-missing
    ```

    **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
    - ✅ Review droid exec output
    - ✅ Verify correctness
    - ❌ Write code

    ### 3. Git Workflow (Simplified)

    **Default:** Work on `develop` branch

    ```bash
    # Daily workflow
    git checkout develop
    git pull

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

    **Feature branches:** Only if needed, MAX 24 hours

    ```bash
    # Create short-lived branch
    git checkout -b feat/quick-feature

    # Work (max 1 day!)
    git commit -m "feat: something"

    # Merge same day
    git checkout develop
    git merge feat/quick-feature --no-ff
    git branch -d feat/quick-feature
    git push
    ```

    **Rules:**
    - Merge daily (no long-lived branches)
    - Never commit to `master` directly
    - Feature branches MAX 24 hours

    ## Droid Exec Delegation

    ### When to Delegate

    **ALWAYS delegate if:**
    - Writing any code (even "quick" fixes)
    - Creating new files
    - Modifying multiple files
    - Writing tests
    - Bug fixes

    **Only do yourself:**
    - Reading/analyzing code
    - Writing specs
    - Code review
    - Planning with user

    ### Delegation Workflow

    ```bash
    # 1. Create spec in tasks/pending/
    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. Run droid exec
    droid exec --auto {low|medium|high} -f tasks/pending/feature_name.md

    # 4. Review ALL output
    # - Read generated files
    # - Run tests
    # - Verify correctness

    # 5. Commit droid exec output
    git add {files}
    git commit -m "feat: description (via droid exec)
    Co-authored-by: factory-droid[bot] <138933559+factory-droid[bot]@users.noreply.github.com>"

    # 6. Move spec to completed
    mv tasks/pending/feature_name.md tasks/completed/$(date +%Y-%m-%d)_feature_name.md
    git add tasks/
    git commit -m "chore: mark feature as completed"
    ```

    ### Autonomy Levels

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

    **How to choose:**
    - Need to run tests? → medium
    - Need to install packages? → medium
    - Just creating/editing files? → low
    - Need to push code? → high

    ### Spec Guidelines

    **Droid exec is SMART** - don't write implementation code for it.

    **Good spec:**
    - 50-100 lines
    - Focus on WHAT (not HOW)
    - List requirements clearly
    - Include TDD section (tests to write FIRST)
    - Define success criteria
    - Provide validation steps

    **Bad spec:**
    - 200+ lines of code examples
    - Detailed implementation instructions
    - No mention of tests

    **TDD section (MANDATORY in every spec):**

    ```markdown
    ## TDD Approach

    ### Write Tests FIRST

    Create `tests/test_feature.py` with:
    - test_function_handles_valid_input()
    - test_function_rejects_invalid_input()
    - test_function_handles_edge_cases()

    Run: pytest tests/test_feature.py -v
    Expected: All tests FAIL (no implementation yet)

    ### Implement to Make Tests Pass

    Create/modify implementation files...
    ```

    ## Task Organization

    ```
    tasks/
    ├── pending/ # Not started or in progress
    ├── completed/ # Done (dated: 2025-10-11_task_name.md)
    └── templates/ # Spec templates
    ```

    **Completion script:**
    ```bash
    # Mark task complete
    python scripts/complete_task.py task_name
    # Moves from pending/ to completed/YYYY-MM-DD_task_name.md
    # Updates PROJECT_STATUS.md
    ```

    ## Code Conventions

    **Style:**
    - Formatter: [Black / Prettier / your choice]
    - Linter: [Flake8 / ESLint / your choice]
    - Files: `lowercase_with_underscores`
    - Classes: `PascalCase`
    - Functions: `snake_case`

    **Commit messages:**
    ```
    type(scope): description
    Types: feat, fix, test, docs, refactor, chore
    ```

    ## Testing Standards

    **Test structure:**
    ```
    tests/
    ├── test_module_name.py # Unit tests
    ├── test_integration.py # Integration tests
    └── conftest.py # Pytest fixtures
    ```

    **Naming:**
    - Test files: `test_<module_name>.py`
    - Test functions: `test_<function>_<scenario>()`
    - Test classes: `Test<ClassName>`

    **Coverage:**
    - Minimum: 80%
    - Critical paths: 100%
    - Check: `pytest --cov=. --cov-report=term-missing`

    ## Common Commands

    ```bash
    # Test
    pytest tests/ -v

    # Format
    [your formatter command]

    # Lint
    [your linter command]

    # Run project
    [your run command]
    ```

    ## AI-Specific Rules

    1. Read **PROJECT_STATUS.md FIRST** every session
    2. Create feature branch before work (if needed)
    3. Write tests before implementation (TDD)
    4. Run tests before committing
    5. Update PROJECT_STATUS.md after completing work
    6. Keep responses SHORT (no walls of text)
    7. Default to delegation (droid exec does work, you review)
    8. Never write code directly

    ## Resources

    - **Droid Exec Docs:** [Link to your droid exec documentation]
    - **Project Status:** PROJECT_STATUS.md (READ FIRST)
    - **Task Examples:** `tasks/completed/` for delegation patterns

    ---

    ## Customization Checklist

    When copying this template to a new repo:

    - [ ] Update project name and goal
    - [ ] Update tech stack
    - [ ] Update test commands
    - [ ] Update formatting/linting tools
    - [ ] Update common commands
    - [ ] Add project-specific conventions
    - [ ] Create PROJECT_STATUS.md
    - [ ] Create tasks/ directory structure