Skip to main content

007-RULES

Documentation & Coding Instructions for Agents

1. AGENTS.md​

When coding begins, do not place every implementation rule in one enormous AGENTS.md.

Use:

AGENTS.md
    platform-wide operating rules

code/AGENTS.md
    repository-wide coding rules

code/backend/AGENTS.md
    backend-specific rules

code/frontend/AGENTS.md
    frontend-specific rules

individual canonical coding specifications
    complete normative implementation guidance

1.1. Endpoint handler documentation​

Every endpoint handler shall declare, immediately adjacent to the handler:

  • canonical operation identifier;
  • concise human-readable summary;
  • complete behavioral description;
  • authentication and authorization requirements;
  • tenant-isolation behavior;
  • request contract;
  • success response contract;
  • error response contracts;
  • idempotency semantics;
  • replay semantics;
  • emitted audit and telemetry events;
  • consumed and produced CSI identifiers;
  • applicable constitutional and policy references.

Descriptions shall explain business and constitutional behavior rather than repeat the method name.

Annotations shall be the authoritative input to generated OpenAPI documentation and shall be validated in CI.

For example, conceptually:

POST /trustgate/signals

Summary:
Submit a signal to the TrustGate assurance pipeline.

Description:
Accepts a canonical signal submission, binds tenant and source identity,
initiates governed TrustGate processing, and returns the accepted execution
identity. Submission does not imply trust acceptance.

Consumes:
comp.TG.INPUT.RAW-SIGNAL.v1_0

Produces:
comp.TG.OUTPUT.SUBMISSION-RECEIPT.v1_0

Replay:
EXACT for receipt construction.

Authorization:
Requires signal.submit permission within the active tenant.

The exact annotation syntax should be defined once the backend framework is fixed—for example, ASP.NET attributes/XML documentation, FastAPI decorators, NestJS decorators, or another stack. The constitutional requirements should remain language-independent; the coding profile translates them into framework-specific syntax.

2. Future coding specification should define matters such as:​

  • endpoint handler annotations;
  • OpenAPI descriptions;
  • request/response schema binding;
  • authorization declarations;
  • tenant boundary declarations;
  • replay behavior;
  • audit events;
  • error contracts;
  • idempotency;
  • DAL eligibility;
  • CSI bindings;
  • observability;
  • test requirements.


GitHub RepoRequest for Change (RFC)