# 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