Workspace layout

Requirements

• A healthy opentide workspace MUST contain objects/ with subdirectories for each core object family.
• Generated artifacts MUST live under .opentide/ — not committed as hand-edited sources.
• .opentide/states/deployment/ is generated deployment state and MUST be committed. .opentide/states/sharing.jsonl is a regenerable cache and SHOULD be gitignored. Implementations MUST NOT gitignore the whole .opentide/states/ directory (deployment-state.md).
• Client configuration overrides MUST live only under .opentide/configurations/.
• Object YAML files MUST reside in the paths defined by merged paths.toml configuration.
• An object instance MUST be a YAML file placed directly in its family directory (objects/rules/rule.yaml, not objects/rules/team/rule.yaml). A file in a subdirectory of a family directory is not an object instance: implementations MUST NOT deploy or share it, and SHOULD warn that it is outside the catalogue. Nested folders under a family directory are otherwise outside this specification.
• Object YAML filenames SHOULD use dash-case slugs (lowercase, hyphens) ideally aligned with the object name field via the same slugify() rules the opentide engine uses for documentation paths. The name field itself MAY be richer (title case, punctuation, spaces). On slug collision, append a short UUID suffix. This is a soft convention for catalogue hygiene, not a schema validation requirement.
• opentide generate schemas MUST emit schema artifacts to .opentide/schemas/.
• opentide generate templates MUST emit templates to .opentide/templates/.

Definition

Core object families

Registered objects list: threat, objective, rule.

.opentide/ layout

Documentation mirror paths

Generated schema artifacts

Inflight shard schema source of truth: schemas/inflight.shard.1.0.schema.json. Deployment state shard schema source of truth: schemas/deployment.state.1.0.schema.json. Generated copies MAY be emitted to .opentide/schemas/ by opentide generate schemas when supported.

visibility.1.0.schema.json is not an object family — there are no visibility objects under objects/. It is the schema used to validate the client visibility.toml configuration, emitted here alongside the object schemas. opentide.schema.json is the IDE router that dispatches object YAML to the correct object schema by metadata.schema.

Generated template artifacts

Export artifacts

Other paths

Example workspace tree

detection-repo/
├── objects/
│   ├── threats/
│   ├── objectives/
│   └── rules/
├── docs/
│   ├── rules/
│   ├── threats/
│   └── objectives/
├── .opentide/
│   ├── configurations/
│   │   └── platforms/
│   ├── schemas/
│   ├── templates/
│   ├── exports/
│   ├── inflight/
│   └── states/
│       ├── deployment/
│       │   └── <uuid>.json
│       └── sharing.jsonl
├── .vscode/
├── .github/workflows/
├── README.md
└── .gitignore

Inflight preview shards

CI writes one JSON file per changed object UUID under .opentide/inflight/<uuid>.json on pull requests and merge requests. Shards use schema inflight.shard::1.0 and wrap the parsed object document plus PR/MR metadata:

Consumers overlay shards onto the committed registry when the shard object metadata.version is greater than the committed version, or equal with a wrapped shard (preview wins on ties). After merge to the default branch, opentide generate inflight prune removes shards superseded by committed YAML.

CI metadata sources

change.source_path is the object YAML path relative to the workspace root (OPENTIDE_REPO_ROOT).

CI jobs

share is the production release. Setup defaults the stage off (--no-sharing; the wizard checkbox is unchecked). opentide setup MUST NOT emit it, or any other opentide share command, on a pull request or merge request. The trigger, the setup choice, and the diff are specified in sharing.md.

Production deployment state

The production deploy job (opentide deploy --strategy RELEASE on a push to the default branch) is the only generated job that commits deployment state. opentide setup and opentide setup ci MUST generate it to meet deployment-state.md CI requirements 1–7:

1. Queue production jobs without dropping runs (no GitHub concurrency group, GitLab resource_group, Azure the strongest available lock, documented).
2. Before the dry run and the deploy, overlay .opentide/states/deployment/ from the default-branch tip.
3. Run the write-back whenever the deploy started, including after a failure, a cancellation, or a timeout.
4. Stage shards independently of rule files; commit rule files only when opentide validate --strict passes on exactly those files, read NUL-delimited.
5. On a rebase conflict, replay this run's state delta per platform and tenant (opentide deploy replay-state); a concurrent change to the same binding is deployment_state_conflict and fails the job.
6. On every terminal write-back failure, print the state diff and push the commit to refs/opentide/deployment-state/<commit> before failing.
7. Log every recorded id as external_id_recorded at WARNING.

Staging, pull-request, and merge-request deploy jobs MUST NOT commit deployment state. A create on Defender for Endpoint, SentinelOne, or CrowdStrike in those jobs is refused with deployment_state_unpersisted before the vendor call (deployment-state.md).

Relationships

• configuration.md — how paths.toml is merged and overridden
• deployment-state.md — .opentide/states/deployment/ and the production write-back
• versioning.md — schema artifact naming
• Object specs — where instances are stored

Defaults & overrides

Bundled paths.toml ships in the opentide package. Clients MAY override path values via .opentide/configurations/paths.toml. See configuration.md.

Examples

Object fixtures assume the default layout: rules under objects/rules/, etc.

History