Skip to content

STD-OPS-100: Orchestration Engineering Standards

1. Context

To maintain order in a high-velocity monorepo, all automation (Scripts, Workflows, CI) must follow a unified "Registry Pattern." This standard implements the governance defined in STD-GEN-001 for implementation files.

2. The Standard (The Floor)

2.1 Naming Taxonomy

We follow a hierarchy of Category > Action > Target.

Format Pattern Human-Readable Constraint
Operational Scripts [CAT]_[ACTION]_[TARGET].ts TARGET must be a descriptive slug (e.g., MAIN, I18N).
Agent Workflows [action]_[target].md target must be a human-parsable slug.
GitHub Actions [action]-[target].yml target must be the descriptive domain name.

Reserved Category Prefixes (Aligned with STD-GEN-001):

  • AGENT -> OPS: Higher-order orchestration (Converge, Cleanup).
  • DEV -> DEV: Developer environment wakeup/management.
  • CI -> OPS/DEV: Deployment and remote validation.
  • SYS -> GOV/OPS: Housekeeping, database migrations, logs.
  • DAT -> DAT: Seeding, ingestion, exports.

2.2 Metadata Blocks (Self-Identification)

Every orchestration file MUST contain a standardized metadata block.

TypeScript Scripts (.ts)

Must include a JSDoc-style header at Line 1:

/**
 * @protocol [ID] [Title]
 * @standard STD-OPS-XXX
 * @env [Local | Emulator | Cloud]
 * @impact [Low (Read-only) | Medium (State-change) | High (Destructive/Nuke)]
 */

Agent Workflows (.md)

Must include YAML frontmatter:

---
id: [FILENAME_SLUG]
description: [One sentence rationale]
prerequisites: [Locked branch, clean working dir, etc.]
---

2.3 Variable Declaration Hygiene

Scripts MUST separate Environment Configuration from Process Logic.

  • Rule: Declare an env or config object at the top level (after imports) that aggregates all process.env dependencies.
  • Rule: Use a verificationEnv pattern for emulator-scoped tasks.

2.4 Pedagogical Scripting

Scripts MUST NOT be opaque. They are educational documents as much as they are execution logic.

  • Rule: JSDoc/Header tags MUST include a @rationale (Why) and @guidance (How to use/safeguards).
  • Rule: Complex logic blocks MUST be preceded by descriptive comments explaining the intent for both Human and AI readers.

3. Governance: Centralized vs. Decentralized

We adopt the "Distributed Brain" pattern:

  1. Centralized Registry (The Ledger): A master document in documentation/knowledge/ARCH-002_PROCESS_LEDGER.md that indexes all scripts and their standard IDs.
  2. Decentralized Intelligence: The actual logic resides in the most relevant directory (scripts/, .agent/workflows/, .github/workflows/), but it MUST link back to the Ledger using its @protocol ID.

4. Automation Checklist

  • [MUST] Non-Interactive: Scripts used in CI should default to non-interactive mode.
  • [MUST] Safe-to-AutoRun: Workflows with destructive commands (e.g. nuke) MUST NOT have // turbo annotations.

5. Version History

Version Date Author Change
1.0.0 2026-02-10 Antigravity Initial RFC for Orchestration Standards