init

AGENTS.md

@@ -0,0 +1,179 @@
+# AGENTS
+
+## Operational Guidance for Autonomous Agents Using specification (ABC Specification)
+
+MUST USE `index.md` 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.