Skip to content

AGENTS.md

Latest commit

 

History

History
96 lines (74 loc) · 6.61 KB

AGENTS.md

File metadata and controls

96 lines (74 loc) · 6.61 KB

AGENTS

Warning

This file is automatically synced from Doist/shared-configs.

Do not edit this file directly. Any local changes will be overwritten on the next sync. To make changes, edit the file in the source repository.

Core Principles

These principles apply to all agent interactions:

  1. Documentation-First for Intended Behavior: Prioritize human-written documentation from the docs/ directory when the task is about intended behavior, architecture, workflows, conventions, or checklists.
  2. Code as Source of Truth for Implementation: Use the codebase as the source of truth for implementation details such as method signatures, parameter requirements, control flow, and concrete behavior. Consult documentation for additional context, intent, or repository-specific guidance.
  3. Augment, Don't Override: Use information from docs/ to augment and guide your process. The instructions in this file define the how (your process), while the docs/ directory provides the repository-specific what (the conventions, checklists, and knowledge). The code clarifies the concrete implementation details.
  4. Minimal Scope: When inspecting code, focus on the smallest possible scope (specific files or modules). Do not read entire directories.
  5. Transparency: If you are unsure about an approach or need to expand your scope, ask the user for confirmation first.

Documentation Navigation

Before performing any task that requires consulting documentation:

  1. Check for Index: First, read docs/README.md. If this file exists, it must be used as the primary index for navigating the docs/ directory.
  2. Use Index for Navigation: Rely on the index's descriptions and tags to identify which documents are relevant to your task. Do not scan the entire docs/ folder when the index provides clear guidance.
  3. Fallback to Scanning: Only if docs/README.md does not exist or does not provide sufficient guidance should you fall back to scanning the docs/ directory.

Task-Specific Guidelines

Knowledge Queries

When asked a question about the project's codebase or development process, follow this mandatory process:

  1. Choose the Right Primary Source: If the question is about architecture, process, intended behavior, or documented conventions, start with the Documentation Navigation process above. If the question is about implementation details such as specific methods, functions, parameters, types, control flow, or concrete behavior, inspect the relevant code directly.
  2. Synthesize from the Best Source: Answer from the most relevant primary source. Use documentation for documented intent and guidance, and use code for implementation details.
  3. Cross-Check When Helpful: Consult the other source when it adds useful context or when you notice ambiguity or a mismatch between documented intent and actual behavior.
  4. Be Clear About the Basis of the Answer: State whether your answer is based on documentation, code, or both when that distinction matters.

Code Reviews

When asked to perform a code review, follow this mandatory process:

  1. Consult Documentation: Use the Documentation Navigation process above to find relevant guidelines in docs/. Look for documents related to:
    • Coding conventions and style guides.
    • Testing guidelines and best practices.
    • Architecture or design patterns.
    • Any domain-specific standards relevant to the code being reviewed.
  2. Review: Analyze the code against the guidelines found in the documentation.
  3. Provide Feedback: Structure your feedback based on the principles and checklists you have found.

Code Generation

When asked to write new code or implement features, follow this mandatory process:

  1. Consult Documentation: Use the Documentation Navigation process above to find relevant guidelines in docs/. Look for documents related to:
    • Coding conventions and style guides.
    • Architecture patterns and design principles.
    • Testing requirements and test structure.
    • Security guidelines and best practices.
    • Any domain-specific standards or templates.
  2. Inspect Existing Code: Examine existing code in the relevant area to understand:
    • Naming conventions and code organization.
    • Existing patterns and idioms used in similar features.
    • How related functionality is currently implemented.
  3. Implement: Write the code following the guidelines and patterns you've identified, ensuring:
    • Consistency with existing codebase style.
    • Adherence to documented conventions.
    • Appropriate error handling and validation.
    • Inclusion of necessary tests (unit, integration, etc.).

PR Creation

When asked to create a pull request, follow this mandatory process:

  1. Determine Creation Method: Check if GitHub CLI (gh) is available and confirm with the user whether to:
    • Create the PR directly using GitHub CLI, or
    • Generate the PR body for manual creation (copy-paste into GitHub UI).
  2. Gather Context: Identify the branch name, parent branch (default: main), and any related PRs or issues that should be referenced or closed.
  3. Consult PR Template: Read the repository's PR template (typically at .github/PULL_REQUEST_TEMPLATE.md) to understand the required sections and format.
  4. Consult Documentation: Use the Documentation Navigation process above to find relevant guidelines in docs/. Look for documents related to:
    • PR creation guidelines and best practices.
    • Changelog format and conventions.
    • Testing requirements.
    • Any repository-specific PR standards.
  5. Analyze Changes: Review the commits and diff to summarize the changes and complete the required sections in the pull request body.
  6. Create or Generate PR:
    • If using GitHub CLI: Execute gh pr create with the appropriate flags (title, body, labels, base branch).
    • If generating body only: Output the complete PR title and body in a format ready for copy-paste, clearly indicating which labels should be applied manually.
  7. Critical Requirements:
    • Follow the exact template structure from .github/PULL_REQUEST_TEMPLATE.md.
    • Pay special attention to changelog format if it's parsed by automation.
    • Include appropriate testing information (e.g., "Smoke tested", unit tests added).
    • Add relevant labels (e.g., "👀 Show PR" for small, obvious changes).
    • Link related issues and PRs in the Reference section.

Enforcement

These guidelines are non-negotiable. Deviation from this process constitutes a failure to follow core instructions. When in doubt, ask for clarification.