doist§typist

Imported from gencau/test-practices-agent-configurations (dataset/repos/doist§typist/AGENTS.md). Install upstream with npx skills add gencau/test-practices-agent-configurations --skill doist§typist. Copyright stays with the author.

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: Always prioritize human-written documentation from the docs/ directory as the primary source of truth. Before performing any task, search docs/ for relevant guidelines, checklists, or architectural diagrams.
2. Code as Fallback: Inspect the codebase only when documentation is insufficient or when explicitly requested by the user. If you must inspect code because documentation was lacking, state this clearly.
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).
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. Search Documentation: Use the Documentation Navigation process above to find relevant documentation in docs/.
2. Synthesize Answer: Formulate your answer based only on the documentation you find.
3. Fallback to Code: If and only if the documentation does not provide a sufficient answer, you may proceed with code inspection. Announce that you are doing so because the documentation was insufficient.

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.