ffx/AGENTS.md

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:

/
|-- 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:

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:

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:

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.

Project-Specific Requirements

Project-specific material should live outside the generic sections above.

Recommended location:

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/.

4. Relevant modular guides in guidance/stacks/, guidance/conventions/, or guidance/workflows/.

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