abc-ai/AGENTS.md

# AGENTS

## Operational Guidance for Autonomous Agents Using specification (ABC Specification)

MUST USE `README.md` within same directory as this file as entrypoint for
specification and subsequent referenced documents within.

### Purpose of this document

This document defines how an autonomous agent must operate when using the
Abstract Base Cloud (ABC) Specification (specification) as the authoritative
source of truth. It does not redefine, summarize, or restate the ABC Pattern.
Its purpose is to establish procedures, behaviors, and decision rules that
ensure all agent actions remain compliant with the specification.

### How to Read and Interpret spec.txt

1. Treat specification as canonical; all definitions, rules, and schemas
   originate there.
2. When encountering ambiguity, defer to specification rather than internal
   heuristics.
3. When interpreting any rule:
   - Use the identifiers in specification as binding references.
   - Do not reinterpret or rephrase the rule; apply it operationally.
4. When a task requires clarification, locate the relevant section in
   specification and apply its constraints directly.

### How to Apply the ABC Normative Rules

1. Use normative rules as constraints on generation and transformation.
2. For any action:
   : - Identify which normative rules apply.
     - Enforce them mechanically.
3. When generating constructs:
   : - Ensure hierarchy, relationships, interfaces, and data flow conform to
       normative rules.
4. When routing data:
   : - Apply downward and upward flow rules exactly as defined.
5. When evaluating a user request:
   : - Reject or correct requests that would violate normative rules.

### How to Apply the ABC Validation Rules

1. Treat validation rules as mechanical checks.
2. For any ABC architecture:
   : - Validate structure.
     - Validate contracts.
     - Validate data flow.
     - Validate instantiation semantics.
3. When a violation is detected:
   : - Identify the violated rule by its identifier.
     - Provide a corrective action path.
4. Never modify validation rules; only apply them.

### SECTION 5 — How to Use the ABC Schema

1. Use the schema as the machine-readable representation of an ABC architecture.
2. When generating or transforming architectures:
   : - Produce JSON that conforms exactly to the schema.
3. When validating:
   : - Apply schema constraints before normative or validation rules.
4. When consuming the schema:
   : - Use `$defs` to resolve construct types, contracts, and rule bindings.
5. Never alter the schema; only instantiate or validate against it.

### How to Use the Code Generation Profiles

1. Profiles define how to map ABC constructs into specific IaC tools.
2. When generating code:
   : - Select the appropriate profile.
     - Apply profile rules exactly as written in specification.
3. When a profile conflicts with user instructions:
   : - The profile takes precedence.
4. When generating code:
   : - Use the ABC hierarchy as the structural backbone.
     - Use Input/Output Contracts as the only wiring mechanism.
5. Never invent new profile rules; only apply those defined in specification.

### Operational Procedures for Construct Creation

1. Determine the construct type.
2. Create the construct with:
   : - A unique ID.
     - A valid parent (except ApplicationStack).
     - A complete Input Contract.
     - A complete Output Contract.
3. Instantiate children strictly top-down.
4. Ensure no lateral references are introduced.
5. Enforce immutability of Input Contracts.

### Operational Procedures for Data Flow Wiring

1. For downward flow:
   : - Pass only the required subset of parent inputs/outputs.
     - Ensure all downward values originate from the parent’s declared contracts.
2. For upward flow:
   : - Expose only declared outputs.
     - Aggregate or transform outputs only at the parent level.
3. Never allow:
   : - Sibling-to-sibling communication.
     - Access to undeclared values.
     - Implicit or hidden data flow.

### Operational Procedures for Validation

1. Validate in this order:
   : - Schema conformance.
     - Structural validation rules.
     - Contract validation rules.
     - Data-flow validation rules.
     - Instantiation validation rules.
2. For each violation:
   : - Identify the rule ID.
     - Provide a deterministic correction path.
3. Do not proceed with generation or transformation until validation passes.

### Operational Procedures for Refactoring

1. Load the existing architecture from its schema representation.
2. Identify the target change.
3. Determine which constructs, contracts, or data flows are affected.
4. Apply changes while enforcing:
   : - Contract stability requirements.
     - Parent–child mediation rules.
     - No lateral references.
5. After refactoring:
   : - Revalidate the entire architecture.
     - Ensure all rule identifiers remain satisfied.

### Reasoning Patterns for Agents

Agents must use the following reasoning patterns:

Deterministic Reasoning
: Always derive outcomes from specification rather than heuristics.

Hierarchical Reasoning
: Always reason from parent → child → parent; never horizontally.

Contract-Bound Reasoning
: Only use values present in Input/Output Contracts.

Schema-Driven Reasoning
: Treat the schema as the authoritative shape of all architectures.

Rule-Bound Reasoning
: Map every decision to one or more rule identifiers.

### Forbidden Behaviors

Agents must never:

- Restate, summarize, paraphrase, or rewrite any part of specification.
- Invent new ABC rules or modify existing ones.
- Introduce lateral references between constructs.
- Generate architectures that violate any rule in specification.
- Infer missing contract fields not explicitly provided.
- Create implicit dependencies or hidden data flow.
- Generate code that does not follow the selected profile.
- Produce constructs outside the allowed hierarchy.
- Mutate Input Contracts after instantiation.
- Expose values not declared in Output Contracts.

### Agent Behavioral Contract

Agents must:

1. Treat specification as the single source of truth.
2. Apply rules without reinterpretation.
3. Produce deterministic, reproducible outputs.
4. Validate all generated artifacts before returning them.
5. Reject or correct user requests that violate the specification.
6. Maintain strict separation of hierarchy, contracts, data flow, and
   instantiation.
7. Ensure all transformations preserve rule compliance.
8. Use profile mappings exactly as defined.
9. Operate without assumptions, guesses, or implicit dependencies.
10. Maintain full traceability from every action to the relevant rule(s) in
    specification.