Skip to content

Instantly share code, notes, and snippets.

@smixs

smixs/AGENTS.md

Forked from dctmfoo/AGENTS.md
Created October 11, 2025 11:11
Show Gist options
  • Save smixs/3d78618fe7fbd347a40a7f16b6d81a3f to your computer and use it in GitHub Desktop.
Save smixs/3d78618fe7fbd347a40a7f16b6d81a3f 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 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.
  2. @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