377 lines
12 KiB
Markdown
377 lines
12 KiB
Markdown
# AGENTS.md
|
|
|
|
This file is the entry point for agent guidance in this repository.
|
|
|
|
It is intentionally generic and reusable across projects. Keep this file focused on non-project-specific constraints, working style, and the structure used to link more detailed guidance.
|
|
|
|
# Purpose
|
|
|
|
- Provide a small default rule set for agents working in this repository.
|
|
- Keep the base guidance modular and easy to extend.
|
|
- Separate reusable agent behavior from project-specific requirements.
|
|
|
|
# Comment Syntax
|
|
|
|
- A segment wrapped in `<!--` and `-->` is a comment and must be ignored by agents.
|
|
- Use HTML comments for optional guidance that should stay inactive until enabled.
|
|
- To enable an optional segment, remove the surrounding `<!--` and `-->` markers.
|
|
|
|
# Core Principles
|
|
|
|
- Prefer the simplest solution that satisfies the current goal.
|
|
- Keep guidance lightweight: only add detail when it meaningfully improves outcomes.
|
|
- Reuse modular guideline files instead of expanding this file indefinitely.
|
|
- Treat project-specific documents as the source of truth for project behavior.
|
|
- When guidance conflicts, use the most specific applicable document.
|
|
|
|
# Rule Terms
|
|
|
|
- A `rule` is the general term for any constraint, requirement, definition, or similar guidance item.
|
|
- A `rule set` addresses all rules inside one file that share the same rule set ID.
|
|
- Any rule inside a rule set shall use an ID following the schema `RULESET-0001`, `RULESET-0002`, and so on.
|
|
- Rules without a rule set ID are also valid, but they are not addressable by rule ID.
|
|
|
|
# Scope Of This File
|
|
|
|
This file should contain:
|
|
|
|
- Generic agent behavior and constraints.
|
|
- Rules that are reusable across multiple projects.
|
|
- Links to optional guideline modules.
|
|
- Links to project-specific requirements.
|
|
- Commented optional templates for released-product documentation and agent-output locations.
|
|
|
|
This file should not contain:
|
|
|
|
- Project business requirements.
|
|
- Project architecture decisions.
|
|
- Stack-specific implementation details unless they are universally applicable.
|
|
- Task-specific runbooks that belong in dedicated modules.
|
|
|
|
# Default Agent Behavior
|
|
|
|
- Read the relevant context before making changes.
|
|
- Prefer small, understandable edits over broad refactors.
|
|
- Preserve existing patterns unless there is a clear reason to change them.
|
|
- Document assumptions when context is missing.
|
|
- Ignore HTML comment segments.
|
|
- If a more specific enabled guideline exists for the current task, follow it.
|
|
|
|
# Guideline Structure
|
|
|
|
Use the following structure for reusable guidance files and project-specific documentation as needed:
|
|
|
|
```text
|
|
/
|
|
|-- AGENTS.md
|
|
|-- guidance/
|
|
| |-- stacks/
|
|
| |-- conventions/
|
|
| `-- workflows/
|
|
|-- prompts/
|
|
`-- requirements/
|
|
|
|
Optional files and directories
|
|
|-- SCRATCHPAD.md
|
|
|-- docs/
|
|
| |-- readme.md
|
|
| |-- installation.md
|
|
| `-- history.md
|
|
|-- process/
|
|
| |-- log.md
|
|
| `-- coding-handbook.md
|
|
```
|
|
|
|
# Optional Reusable Modules
|
|
|
|
Add files under `guidance/` only when they are needed.
|
|
|
|
# Optional Scratchpad
|
|
|
|
- `SCRATCHPAD.md` is an optional repo-root scratchpad for temporary
|
|
information aimed at the next iteration.
|
|
- Developers may create or delete `SCRATCHPAD.md` at any time.
|
|
- Developers may refer to `SCRATCHPAD.md` as `scratchpad` when giving agents a
|
|
source or target for information.
|
|
- Agents may read, update, create, or remove the scratchpad when the task
|
|
explicitly calls for it.
|
|
- Treat the scratchpad as low-formality working context rather than canonical
|
|
project truth.
|
|
- Use the scratchpad for short-lived notes, open questions, sketches, and
|
|
temporary decisions that should be resolved away.
|
|
- Move durable outcomes into `requirements/`, `guidance/`, code, tests, or
|
|
another long-lived location.
|
|
- If `SCRATCHPAD.md` is absent, agents should continue normally.
|
|
|
|
# Optional Rule Sets
|
|
|
|
- Optional rule sets may be stored in `guidance/optional/` or in `guidance/{section}/optional/`.
|
|
- Optional rule sets are inactive by default and shall only be applied when a prompt explicitly requests them, for example by phrases such as `Apply rules for lean interface iteration in the following steps.` or `Apply LII rules.`
|
|
- An optional rule set may be requested by its descriptive name, by its rule set ID, or by another equally clear explicit reference.
|
|
- Agents shall never infer or auto-enable optional rule sets from general intent alone.
|
|
- If an optional rule or rule set cannot be identified and addressed clearly, agents shall stop and ask before proceeding.
|
|
|
|
# Prepared Orders
|
|
|
|
- An `order` is a prepared prompt for one isolated operation rather than a general workflow or standing rule set.
|
|
- Orders shall be stored under `prompts/`.
|
|
- Order files shall use the naming schema `ORDER-0001-<slug>.md`, `ORDER-0002-<slug>.md`, and so on.
|
|
- The canonical order identifier is the `ORDER-0001` style prefix. The trailing slug is descriptive only.
|
|
- Recommended internal order file structure is: prompt ID, prompt name, purpose, trigger examples, scope, operation, and expected output.
|
|
- Orders shall only be executed when they are explicitly requested by a prompt such as `Execute ORDER-0007.` or `Execute ORDER 7.`
|
|
- Agents may accept an unambiguous short numeric reference such as `ORDER 7` as an alias for `ORDER-0007`.
|
|
- If an order cannot be identified uniquely and clearly, agents shall stop and ask before proceeding.
|
|
|
|
# Toolstack Guides
|
|
|
|
Location:
|
|
|
|
```text
|
|
guidance/stacks/
|
|
```
|
|
|
|
Examples:
|
|
|
|
- `guidance/stacks/python.md`
|
|
- `guidance/stacks/typescript.md`
|
|
- `guidance/stacks/docker.md`
|
|
- `guidance/stacks/terraform.md`
|
|
|
|
Use for:
|
|
|
|
- Language or framework expectations.
|
|
- Tooling and environment conventions.
|
|
- Build, test, and runtime guidance tied to a specific stack.
|
|
|
|
# Coding Conventions
|
|
|
|
Location:
|
|
|
|
```text
|
|
guidance/conventions/
|
|
```
|
|
|
|
Examples:
|
|
|
|
- `guidance/conventions/naming.md`
|
|
- `guidance/conventions/testing.md`
|
|
- `guidance/conventions/review.md`
|
|
|
|
Use for:
|
|
|
|
- Naming and structure conventions.
|
|
- Testing expectations.
|
|
- Code review and quality rules.
|
|
|
|
# Recurring Workflows
|
|
|
|
Location:
|
|
|
|
```text
|
|
guidance/workflows/
|
|
```
|
|
|
|
Examples:
|
|
|
|
- `guidance/workflows/feature-delivery.md`
|
|
- `guidance/workflows/bugfix.md`
|
|
- `guidance/workflows/release.md`
|
|
- `guidance/workflows/incident-response.md`
|
|
|
|
Use for:
|
|
|
|
- Repeatable task flows.
|
|
- Checklists for common delivery work.
|
|
- Operational or maintenance procedures.
|
|
|
|
|
|
<!-- Enable this optional section by removing the outer HTML comment markers from this segment
|
|
when you want agents to create, update, and consult released-product
|
|
documentation in `docs/`.
|
|
|
|
# Released Product Documentation
|
|
|
|
Released-product documentation should live outside the generic sections above.
|
|
|
|
Recommended location:
|
|
|
|
```text
|
|
docs/
|
|
```
|
|
|
|
Examples:
|
|
|
|
- `docs/readme.md`
|
|
- `docs/installation.md`
|
|
- `docs/history.md`
|
|
|
|
Agent rules for docs output:
|
|
|
|
- Keep content compact but comprehensive.
|
|
- Write for end users, operators, or other consumers of the released product.
|
|
- Prefer shipped behavior, supported workflows, and stable terminology over
|
|
internal implementation detail.
|
|
- Keep documentation synchronized with released behavior.
|
|
- Update release history when user-visible changes are shipped.
|
|
|
|
Recommended topics:
|
|
|
|
- Product overview and intended use.
|
|
- Installation, configuration, and upgrade guidance.
|
|
- Usage patterns, operational instructions, and support boundaries.
|
|
- Compatibility notes, migration notes, and release history.
|
|
- Troubleshooting and common pitfalls when relevant. -->
|
|
|
|
|
|
<!-- Enable this optional section by removing the outer HTML comment markers from this
|
|
segment when you want agents to produce and consult workflow output in `process/`.
|
|
|
|
# Agent Output In `process/`
|
|
|
|
The `process/` directory is primarily for agent output created during
|
|
delivery, maintenance, and review work.
|
|
|
|
Recommended location:
|
|
|
|
```text
|
|
process/
|
|
```
|
|
|
|
Agent rules for process output:
|
|
|
|
- Use `process/` for agent-produced artifacts rather than released-product
|
|
documentation.
|
|
- Keep entries concise, traceable, and tied to resulting changes.
|
|
- Treat `process/` as workflow output, not as the primary source of product
|
|
truth.
|
|
- Prefer summaries and rationale over raw transcript dumps unless a workflow
|
|
explicitly requires full prompt history.
|
|
|
|
# Agent Change Log
|
|
|
|
Location:
|
|
|
|
```text
|
|
process/log.md
|
|
```
|
|
|
|
Use for:
|
|
|
|
- Capturing prompts given to agents.
|
|
- Recording concise explanations of the resulting changes made by agents.
|
|
- Preserving task-by-task rationale, decisions, and implementation notes.
|
|
|
|
# Coding Handbook
|
|
|
|
Location:
|
|
|
|
```text
|
|
process/coding-handbook.md
|
|
```
|
|
|
|
Use for:
|
|
|
|
- A tutorial-style handbook that explains the programming components used in
|
|
the project.
|
|
- Compact but comprehensive technical onboarding material for future
|
|
contributors.
|
|
- Written explanations that connect code structure, concepts, and
|
|
implementation patterns. -->
|
|
|
|
|
|
# Project-Specific Requirements
|
|
|
|
|
|
Project-specific material should live outside the generic sections above.
|
|
|
|
Recommended location:
|
|
|
|
```text
|
|
requirements/
|
|
```
|
|
|
|
Examples:
|
|
|
|
- `requirements/project.md`
|
|
- `requirements/architecture.md`
|
|
- `requirements/decisions.md`
|
|
- `requirements/domain.md`
|
|
|
|
Use for:
|
|
|
|
- Product and business requirements.
|
|
- Project goals and constraints.
|
|
- Architecture and design decisions.
|
|
- Domain knowledge that is specific to this repository.
|
|
|
|
# Agent-Level Variables
|
|
|
|
When present, `requirements/identifiers.yml` is an optional project-specific
|
|
input that defines agent-level variables for use inside `requirements/` and
|
|
`guidance/`.
|
|
|
|
Variable schema:
|
|
|
|
- Use `@{VARIABLE_NAME}` for agent-level variables.
|
|
- Prefer uppercase snake case names such as `@{PROJECT_ID}` or `@{VENDOR_ID}`.
|
|
- Do not treat `${...}` as an agent-level variable form; that syntax may appear
|
|
in Bash or other code and should not be interpreted as agent metadata.
|
|
|
|
Scope:
|
|
|
|
- The effective scope of `requirements/identifiers.yml` is limited to
|
|
`requirements/` and `guidance/`.
|
|
- Definitions from `requirements/identifiers.yml` must not leak into product code.
|
|
|
|
Defaults:
|
|
|
|
- Default `@{VENDOR_ID}` is `osgw`.
|
|
- Default `@{PROJECT_ID}` is the current repository directory name.
|
|
|
|
Resolution rules:
|
|
|
|
- Treat `requirements/identifiers.yml` as optional; when it is absent, agents
|
|
may still resolve the defaults defined above.
|
|
- If a variable is used in `requirements/` or `guidance/` and it is not
|
|
defined in `requirements/identifiers.yml` and does not have a default in this
|
|
file, agents may stop and report the undefined variable.
|
|
- Prefer updating duplicated identifier values in `requirements/` and
|
|
`guidance/` to use the variable schema when that improves consistency.
|
|
|
|
# Precedence
|
|
|
|
Some precedence levels may be absent because optional levels can remain inside
|
|
HTML comments. The smaller numeric index wins.
|
|
|
|
Apply guidance in this order:
|
|
|
|
1. Direct user or task instructions.
|
|
2. Project-specific documents in `requirements/`.
|
|
<!-- 3. Released-product documentation in `docs/` when shipped behavior or
|
|
user-facing expectations are relevant. -->
|
|
4. Relevant modular guides in `guidance/stacks/`, `guidance/conventions/`, or `guidance/workflows/`.
|
|
<!-- 5. Agent output in `process/` when prior prompts, rationale, or
|
|
implementation notes are relevant. -->
|
|
6. This `AGENTS.md`.
|
|
|
|
# Maintenance
|
|
|
|
- Keep this file short and stable.
|
|
- Move detail into dedicated modules when a section becomes too specific or too long.
|
|
- Add new guideline files only when they solve a recurring need.
|
|
- Remove outdated references when the repository structure changes.
|
|
|
|
# Current Status
|
|
|
|
This repository defines the base `AGENTS.md` structure plus project-specific
|
|
requirements and modular guidance.
|
|
|
|
Future project work can add:
|
|
|
|
- Reusable modules under `guidance/`
|
|
- Project-specific documentation under `requirements/`
|
|
- Optional temporary iteration context in `SCRATCHPAD.md`
|
|
- Optional released-product documentation under `docs/` by uncommenting its segment
|
|
- Optional agent output under `process/` by uncommenting its segment
|
|
- Cross-references from this file once those documents exist
|