# Data Department Agent Skills

A governed operating system for a complete Data Department: 32 role skills, 809 atomic task
contracts, risk-adaptive lifecycle controls and executable evidence gates. This file is the
cross-agent entry point, read by Codex, Google Antigravity and any harness following the
AGENTS.md convention. Claude Code additionally loads `CLAUDE.md`, `commands/` and `hooks/`.

## Supported harnesses

| Harness | Reads | Install |
|---|---|---|
| Claude Code | `.claude-plugin/`, `skills/`, `commands/`, `hooks/` | `claude --plugin-dir <suite>` |
| OpenAI Codex | this file, `.codex/skills/<name>/SKILL.md` | `python tools/install_agent_harness.py <project> --harness codex` |
| Google Antigravity | this file, `.agents/agents/<name>.md`, `.agents/skills/` | `python tools/install_agent_harness.py <project> --harness antigravity` |
| Other AGENTS.md harnesses | this file, `skills/<name>/SKILL.md` | copy or link `skills/` where the harness looks |

Codex skills use the same `name` + `description` frontmatter as this suite, so no translation
layer exists: the installer links the same directories rather than duplicating them. The
Antigravity surface at `.agents/agents/` is generated by `tools/build_suite.py`, one custom
agent per department, each pinned to `commandExecutionPolicy: sandbox`.

## Layout

```text
skills/<role>/SKILL.md                       role entry point, always-visible metadata only
skills/<role>/references/catalog-*.md        routing shards, loaded one at a time
skills/<role>/references/tasks/<id>.md       809 atomic task contracts
skills/<role>/scripts/                       deterministic evidence scripts (Python 3.10+, stdlib only)
skills/<role>/assets/                        record templates and JSON Schemas
commands/                                    slash commands: 13 controls + 32 departments
.agents/agents/                              Antigravity custom agents, one per department
hooks/                                       production and publishing guard (Claude Code)
schemas/                                     canonical Draft 2020-12 schemas
task-catalog.json                            canonical machine-readable task inventory
suite-manifest.yaml                          canonical role inventory
```

The layout matches the `skills/<name>/SKILL.md` convention used by the `skills` CLI, so
agents that discover skills from a repository can consume this suite directly.

## How to work in this repository

1. Route by **primary deliverable**, never by job title. Resolve the owning role from
   `suite-manifest.yaml` and the exact task ID from `task-catalog.json`.
2. Read the selected task contract **completely** before acting. Partial reads produce
   invented gates.
3. Load only what the contract names: one catalog shard, the lifecycle standard, and the
   matching technology adapter. Never preload all 809 contracts or all 98 adapter packs.
4. Classify every task by lifecycle profile, risk tier and execution path. The `R0-light`
   fast path is for genuinely read-only work. Never downgrade risk to meet a deadline.
5. Inspect live artifacts before making change-sensitive claims.

## Non-negotiable claims policy

Never claim production execution, publishing, access changes, deletion, certification or
model promotion without evidence and the required human approval. `not-run` and `incomplete`
are honest statuses; neither may be reported as a pass.

## Executable evidence

```bash
python skills/shared-task-controls/scripts/validate_evidence_bundle.py <bundle> --artifact-root <root> --mode complete
python skills/shared-task-controls/scripts/validate_task_result.py <result> --task-catalog task-catalog.json --mode complete
python skills/shared-task-controls/scripts/verify_deliverable.py <result> <evidence> --artifact-root <root>
python skills/data-department-orchestrator/scripts/validate_workflow.py <manifest> --mode complete
python skills/data-department-orchestrator/scripts/validate_run_state.py <state> --task-catalog task-catalog.json
python skills/data-department-orchestrator/scripts/validate_approval_record.py <record> --require-approved
python skills/shared-task-controls/scripts/validate_constitution.py <constitution> --proposal-file <plan>
python skills/data-architecture/scripts/scan_architecture_drift.py <repo> --max-depth 5
python skills/personal-second-brain-and-knowledge-os/scripts/build_entity_context_graph.py <vault> --query "<question>"
python skills/data-developer-experience/scripts/build_code_index.py <repo> --symbol <Name>
python skills/data-department-orchestrator/scripts/manage_instincts.py <ledger> --rescore
python skills/data-department-orchestrator/scripts/score_skill_quality.py <telemetry.jsonl> --task-catalog task-catalog.json
```

Exit `0` passed, `1` failed, `2` incomplete or unknown because a check could not run, `3` blocked by the constitution. Do not explain
away a validator failure in prose.

## Changing the suite

`skills/` is **generated**. Edit `docs/skill-map.md` (the canonical taxonomy) or
`tools/build_suite.py`, never the generated files. Then:

```bash
python tools/build_suite.py
python tools/generate_user_docs.py
python tools/validate_suite.py
python tools/validate_claude_skills.py
python tools/run_smoke_tests.py
python tools/run_benchmark_tests.py
python tools/run_control_tests.py
```

All seven must pass before a release.

## Licensing

Proprietary. Publishing this repository grants no redistribution right. Referenced
third-party projects remain governed by their own licenses; see `docs/source-integration-audit.md`.