# Engineering OS
**An engineering organization you can inspect, install into a capable host, and give a bounded mission.**
Engineering OS turns a project challenge or an accepted issue into explicit scope, independent work, observable evidence, and a human decision. It is designed for teams where agents can produce code faster than people can preserve coherence.
> Clear authority. Bounded agents. Real verification. One canonical backlog.
This repository contains an **Agentik OS package**, its methods and typed artifacts, two compiled workflow plans, an optional Codex skill, and local verification tools. The skill is one entry point into the organization; it is not the organization itself.
**Status: `draft_reference` · Version: `0.1.0` · License: Apache-2.0**
The package compiles against the current Agentik OS v0.2 compiler. It is **not a qualified candidate or a released cloud service**. Read [the proof boundary](#what-is-proven) before treating compilation as operational readiness.
## What it does
- **Challenge a project:** inspect actual source and evidence, question the user outcome, identify conflicting authorities, define meaningful evaluations, and propose dependency-ordered issues.
- **Deliver one accepted issue:** establish file scope, implement in an isolated worktree, exercise the real journey, obtain independent reviews, and prepare a human decision packet.
- **Keep ideas useful:** receive evidence and experiments from Ideation OS or another research process, then route accepted work into the existing backlog.
- **Reduce context noise:** load the mission, relevant contracts, one role method, and the corresponding artifact schema. Historical prompts remain available research, not mandatory context for every job.
It does not introduce a project-management database, scheduler, credential store, model-provider proxy, or automatic production release system. Those authorities belong to the host and the selected project tools.
## The organization
```mermaid
flowchart TB
D[Engineering Director]
D --> R[Research Team]
D --> P[Planning Team]
D --> Q[Quality Team]
D --> L[Delivery Team]
R --> ER[Evidence Researcher]
R --> OC[Outcome Challenger]
P --> CA[Contract Architect]
P --> IP[Issue Planner]
Q --> SR[Security Reviewer]
Q --> AR[Architecture Reviewer]
Q --> ED[Eval Designer]
L --> I[Implementer]
L --> TE[Test Engineer]
L --> RV[Release Verifier]
```
**11 logical roles, 4 teams.** They are persistent organizational definitions, not 11 permanent machines or an instruction to invoke everyone. Start with the smallest useful topology. An implementation and its independent review must use separate contexts/principals.
| Team | Owns | Produces |
| --- | --- | --- |
| Research | Source evidence and user-outcome challenge | Revision-scoped inventory, simpler baseline, falsifiable experiment |
| Planning | Authority contracts and atomic work | ADR proposals, authority map, bounded issue and context manifest |
| Quality | Independent architecture/security review and eval design | Revision-bound findings, failure cases, baseline comparison plan |
| Delivery | Implementation, actual journey checks, decision preparation | Candidate diff, readback receipts, human decision packet |
Each role has its own [method](methods/) and [typed deliverable schema](schemas/). The full graph and permissions are inspectable in [os.json](os.json).
## Two workflows
```mermaid
flowchart LR
F[Frame mission] --> E[Inspect evidence]
F --> O[Challenge outcome]
E --> C[Define contracts]
O --> C
E --> V[Define evals]
O --> V
C --> S[Security review]
C --> A[Architecture review]
S --> P[Plan issues]
A --> P
V --> P
P --> R[One recommendation + gaps]
```
`project-challenge` is read-only. Findings do not silently become product changes, accepted architecture, or backlog commitments.
```mermaid
flowchart LR
S[Bound issue scope] --> G[Human scope gate]
G --> I[Implement]
I --> T[Exercise journey]
I --> R[Independent reviews]
T --> P[Decision packet]
R --> P
P --> H[Human decision]
```
`bounded-issue-delivery` ends with a decision. It does **not** merge or release. The real host must enforce capability grants, worktree isolation, revision binding, cancellation, budget, and human gates. Existing valid authorization must not be replaced by repeated conversational permission requests; it must be represented by a legitimate host receipt when the compiled gate requires one.
## Quick start
### Inspect and test locally
Python 3.10+ is sufficient for the local tools. These commands run no model calls and make no external mutations:
```bash
python3 -m unittest discover -s tests -v
python3 scripts/verify-generated.py
python3 integrations/codex/engineering-os/scripts/context.py --role contract-architect
```
The GitHub workflow runs the same local tests and checks source/artifact integrity. It does not run the separate compiler or claim runtime qualification. The context command returns the exact method, schema, and host-contract paths with hashes. Read those alongside the authorized issue context.
### Compile the OS
The compiler is separate software. Supply an existing, compatible Agentik compiler checkout with its dependencies installed:
```bash
python3 scripts/compile.py --compiler-checkout /path/to/agentik-compiler
```
This runs the real offline compiler, replaces this repository's generated `evidence/compilation` directory, and records a sanitized receipt. It does not invoke Jev, promote a candidate, connect to a backend, install the OS, or deploy anything. The command uses the compiler's normal contract validation; it does not lower the candidate depth gate.
### Use with Codex
Keep the complete repository available. Point Codex at [the skill](integrations/codex/engineering-os/SKILL.md), or link that directory into your existing Codex skills directory. Do not copy only `SKILL.md`, because its role methods and schemas live in the OS package.
Example request:
> Use Engineering OS to challenge this project's next user journey. Read the relevant source and accepted decisions. Run evidence research and outcome challenge independently. Propose the first five bounded issues. Do not edit product code, create external issues, or release anything.
For a delivery request, identify the accepted issue, repository/revision, allowed files, existing authorization, and required verification. A host without delegation can use the methods, but must label its work as a single-host fallback and cannot claim independent review.
### Use with Agentik MCP
The host must expose an authenticated Agentik MCP connection and a real installation of this package/version. Discover the actual available tools and permissions; use the supported installation and workflow flow. There is no public installation endpoint or bundled MCP server in this repository. Compiler-generated projections are integration artifacts, not a live connection.
See [the host contract](docs/HOST_CONTRACT.md) for the boundary and fallback behavior.
## Evidence without false confidence
The local receipt checker validates workspace/mission/revision alignment, independent review identifiers, exact file scope, artifact hashes, and supported progress claims:
```bash
python3 programs/check-evidence.py --root /path/to/private-mission < /path/to/bundle.json
```
It returns `readyForHumanReview`, never permission to merge or release. It does not prove that a claimed test really happened, authenticate a reviewer identity, or enforce a sandbox. Those facts require trusted host receipts and actual observation. [The synthetic test fixture](tests/test_evidence.py) demonstrates the input format and negative cases.
Keep actual project mission history private. This public repository contains original methods, schemas, generated package artifacts, and synthetic verification fixtures.
## Evals and Jev
### Applied through a real host
The methods and context selector were exercised in a bounded project review by independent agent contexts. Reviewers found an incomplete qualification dependency and an underspecified single-role baseline; the project plan was corrected. A separate source review distinguished existing account connections from a proposed mission-resume flow, and draft compilation from approved installation.
The evidence CLI rejected forged hashes, stale review, self-review, unrun checks and an unsupported release claim. The host also made a real typed Jev request (`jev-1.13.0`). See [the sanitized host review](evidence/manual-host-review.json).
This demonstrates useful **manual host use of the methods**, not execution of every compiled workflow node or installation through MCP. It does not establish multi-agent uplift, semantic eval success or production readiness. Private project source, sessions and reports are intentionally excluded.
[33 role-specific cases](evals/cases.json) cover scope drift, duplicate authority, stale reviews, missing grants, provider boundaries, failed readback, and false completion. Their current status is **NOT_RUN**. Local unit tests are not a substitute for these agent outcome evals.
Compare the relevant team against one capable agent using matched cases and budgets. Measure outcome quality, latency, usage, failures, and human correction effort separately. Do not invent a success percentage from a planned suite.
[Optional Jev review](docs/JEV.md) uses a host-provided TypeSafe AI System One connection for typed advisory judgments. A Jev result cannot override tests, capability checks, human approval, or external readback.
## What is proven
| Surface | Evidence | Current limit |
| --- | --- | --- |
| Agentik package contract | [Actual compiler receipt](evidence/compilation-receipt.json) | Offline compilation only |
| Two workflow plans and 11 agent cards | [Generated artifacts](evidence/compilation/) | No claim of host execution |
| Receipt integrity and context selection | [Local verification receipt](evidence/local-verification.json) | Synthetic fixtures and local CLI |
| Codex skill structure | Skill-creator validator | Structural validation, not full behavioral qualification |
| Role outcome evals | 33 declared scenarios | NOT_RUN |
| MCP installation/cloud execution | None in this repository | NOT_RUN |
| Candidate qualification | Depth score 70/100; unjudged | Four-level management requirement is unsatisfied |
| Release | No release receipt | `draft_reference` |
The current candidate standard requires four management levels. This package intentionally retains a compact Director → Team → Specialist structure because an extra management layer has no demonstrated benefit yet. That is an **unresolved qualification gap**, not an exception or a claim that the standard was met. No compiler threshold was modified.
## Repository map
```text
os.json Canonical organization and workflow contracts
methods/ Original role methods
schemas/ Mission, role result, and domain deliverables
evals/ Declared role cases and baseline strategy
programs/check-evidence.py Local receipt-integrity checker
scripts/compile.py Real compiler adapter; no deployment
integrations/codex/engineering-os/ Invocation skill and bounded context selector
docs/ Host, provenance, Ideation, and Jev boundaries
tests/ Synthetic local verification
evidence/compilation/ Generated plans, cards, and compiler reports
```
Change source contracts and methods together, recompile, run relevant checks, and record actual results. Human approval, release status, and deployed behavior remain separate from source changes. Read [AGENTS.md](AGENTS.md) before contributing.
## License
Original source is licensed under [Apache-2.0](LICENSE). See [NOTICE](NOTICE). The Agentik compiler, hosting services, provider subscriptions, and third-party tools remain separate software and services with their own terms.