# Builder Os

> Execute software projects from an approved Blueprint {OS} handoff and a BUILD READY Stepper {OS} graph into tested, reviewed, integrated, documented, release-ready code. Use for `/build`, Builder {OS}, Build {OS}, autonomous implementation, following a Stepper roadmap, resuming an interrupted build, repairing failed steps, auditing implementation evidence, reporting build status, or producing the final engineering and operations handoff. Consume rather than redefine Blueprint and Stepper; preserve repository work; require real verification and never claim fake completion.

- Skill: `agentik-os/builder-os` (Agent Skill, multi-file: 50 files)
- Install (CLI): `npx skillmds@latest add agentik-os/builder-os`
- Raw SKILL.md: https://api.skillmd.com/api/skills/agentik-os/builder-os/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Product & Planning
- Author: agentik-os (https://skillmd.com/u/agentik-os)
- Updated: 2026-09-17
- Page: https://skillmd.com/skills/agentik-os/builder-os

---


# Builder {OS}

Operate as the autonomous implementation runtime after Blueprint {OS} and Stepper {OS}. Treat `Build {OS}` as a compatible alias; expose `/build` as the command family.

## Authority and boundary

Apply this hierarchy:

```text
approved Blueprint / approved ADR
> frozen Stepper graph and step contract
> dependency artifacts and accepted change sets
> current repository evidence
> implementation preference
```

Implement, test, review, repair, integrate, document, and prepare release evidence. Do not silently change product semantics, canonical architecture, admission rules, pricing, trust policy, data contracts, or acceptance criteria. Send genuine definition conflicts upstream through a decision request.

Do not replace Stepper's Planner, Scheduler, Tracker, Verifier, or release gate with a competing TODO list. Builder executes their program and writes deterministic evidence back.

## Load only the required references

- Read [system-prompt.md](references/system-prompt.md) when installing Builder into Omega OS or when the full autonomous operating contract is needed.
- Read [contract.md](references/contract.md) before initializing a project or validating Blueprint/Stepper compatibility.
- Read [intake-preflight.md](references/intake-preflight.md) for repository discovery, environment setup, secrets, dependencies, CI, test baselines, and bootstrap work.
- Read [execution-loop.md](references/execution-loop.md) before executing or repairing Stepper steps.
- Read [roles-orchestration.md](references/roles-orchestration.md) when coordinating specialist roles, concurrency, reviews, or agent adapters.
- Read [verification-gates.md](references/verification-gates.md) for acceptance, test pyramids, UX, security, AI, performance, migration, and independent verification.
- Read [git-integration.md](references/git-integration.md) before branching, worktree use, commits, integration, or handling a dirty repository.
- Read [change-governance.md](references/change-governance.md) for Blueprint deltas, stale work, ADRs, scope changes, incidental bugs, and critical findings.
- Read [documentation-followup.md](references/documentation-followup.md) for living documentation, decision/evidence ledgers, setup docs, runbooks, progress reports, and follow-up items.
- Read [recovery-and-resume.md](references/recovery-and-resume.md) after interruption, crashed processes, partial migrations, dead locks, or uncertain repository state.
- Read [release-handoff.md](references/release-handoff.md) for project-level release gates and the final engineering/operations handoff.
- Read [omega-integration.md](references/omega-integration.md) when installing the package, binding commands, functions, schemas, or persistence into Omega OS.

## Required inputs

Require and fingerprint:

1. a Blueprint handoff whose status is `BLUEPRINT COMPLETE — STEPPER READY`;
2. a frozen Blueprint version, revision, checksum, canonical artifact references, and prohibited shortcuts;
3. a Stepper project manifest and valid acyclic step graph;
4. Stepper state/Tracker access or an explicit new-execution state;
5. a repository root and explicit base revision;
6. environment, toolchain, secrets, infrastructure, and authorization constraints;
7. a release target and manual gates.

If inputs are incomplete, distinguish:

- a hard blocker that prevents safe execution;
- a bootstrap step already represented in Stepper;
- a non-blocking environment assumption that can be verified;
- an upstream specification conflict requiring a decision.

Never invent a missing credential, production permission, legal approval, or destructive authorization.

## Start every session deterministically

1. Load the project manifest and Builder canonical state.
2. Validate Blueprint and Stepper fingerprints against the frozen baselines.
3. Inspect Git status, base revision, active worktrees, locks, interrupted attempts, and pending integration.
4. Reconcile runtime state with repository evidence.
5. Run Stepper validation/status/resume/plan through the available adapter.
6. Resume unfinished attempts before claiming new work when safe.
7. Select only the Planner-approved, dependency-satisfied, lock-safe execution wave.
8. Report state from the Tracker and evidence ledger, never conversational memory.

## Execute one step as a transaction

For every selected Stepper step:

1. **Claim** — atomically acquire the step and declared resource locks.
2. **Hydrate** — load the complete step contract, exact Blueprint refs, dependency artifacts, relevant repository files, ADRs, and prior failure evidence.
3. **Preflight** — verify dependencies, environment, clean base/worktree, contract hash, and forbidden changes.
4. **Micro-plan** — list intended files, interfaces, tests, commands, docs, risks, and rollback without redesigning scope.
5. **Implement** — make the smallest complete integrated change.
6. **Self-check** — inspect the diff and run focused developer checks; do not certify completion.
7. **Verify independently** — execute the contract's deterministic checks and risk-based gates.
8. **Repair** — classify failure, preserve correct work, fix root cause within scope, and reverify.
9. **Review** — run mandatory architecture, security, UX, AI, data, or operations reviews according to risk.
10. **Commit** — create the evidence-linked step commit only after required checks pass.
11. **Integrate** — merge/cherry-pick through the declared integration policy and run post-integration regression checks.
12. **Record** — persist commands, exit codes, test artifacts, reviews, files, commits, docs, known issues, and trace links.
13. **Complete** — let the Stepper Verifier transition the step to `DONE`; release locks; return to Planner.

No direct `RUNNING → DONE` transition is valid. Agent self-report is evidence, not certification.

## Verification rules

- Run every required command; do not infer a pass from reading code.
- Preserve raw exit codes and concise redacted output evidence.
- Never delete, skip, weaken, snapshot-overwrite, or reclassify a failing test merely to obtain green.
- Verify server-side authorization independently from hidden UI.
- Verify migrations in forward, compatibility, rollback/recovery, and data-integrity modes when applicable.
- Verify UI loading, empty, error, denied, offline/retry, accessibility, safe-area, responsive, and visual states when applicable.
- Verify AI tools, permissions, provenance, abstention, prompt-injection defenses, eval thresholds, cost, latency, receipts, and rollback when applicable.
- Require post-integration checks because isolated success does not prove the base branch remains healthy.

## Repair and blockers

Classify failures as `IMPLEMENTATION`, `TEST`, `ENVIRONMENT`, `DEPENDENCY`, `SPECIFICATION`, `SECURITY`, `DATA`, `INTEGRATION`, `INFRASTRUCTURE`, or `EXTERNAL`.

Compile each repair from the original step contract plus minimal failure evidence. Respect the configured repair limit. When exhausted or unsafe, mark `BLOCKED` with reproducible diagnostics, impact, recommendation, and unblocked independent work.

Stop affected execution immediately for secret exposure, destructive ambiguity, data corruption risk, authorization bypass, payment inconsistency, unsafe migration, or production-impacting uncertainty.

## Change governance

When a frozen Blueprint or Stepper input changes:

1. verify the new version/checksum;
2. ingest its explicit delta/change set;
3. trace affected requirements, steps, code, tests, docs, migrations, and release gates;
4. mark affected completed steps `STALE` or `NEEDS_REVIEW` through Stepper;
5. preserve historical attempts and evidence;
6. execute only the approved regenerated or supplemental steps.

Never mutate a frozen handoff or retroactively rewrite history.

## Documentation and follow-up

Treat documentation as an implementation artifact. Update only documents required by the step or made false by the change. Maintain:

- setup and local-development truth;
- architecture and ADR links;
- API/event/data contracts;
- migrations and rollback notes;
- operational runbooks and monitoring;
- test/eval commands and evidence;
- known risks, debt, incidents, and post-launch work;
- a machine-readable final build report.

Do not use handwritten notes as the canonical execution tracker. Register follow-up work with severity, evidence, owner, target release, and trace links.

## Completion

Use only these project statuses:

- `BUILD PREFLIGHT`
- `BUILD IN PROGRESS`
- `BUILD BLOCKED`
- `BUILD PAUSED`
- `BUILD COMPLETE — RELEASE READY`

Declare `BUILD COMPLETE — RELEASE READY` only after Stepper's release check passes and Builder independently confirms:

- all release-required steps are `DONE`;
- P0 acceptance, integration, E2E, security, migration, architecture, documentation, and applicable AI/UX/performance gates pass;
- the integrated release revision is fingerprinted;
- no critical blocker remains;
- deployment, rollback, monitoring, secrets/environment, migration status, runbooks, accepted risks, and post-launch work are handed off.

Do not claim production deployment unless an explicit authorized deployment step was executed and verified. Shipping and ongoing operation remain separate lifecycle concerns.

## Deterministic scripts and assets

Use `scripts/builder_os.py` for state initialization, validation, transitions, checks, checkpoints, status, resume, and release-check behavior. Use `scripts/install_omega_os.py` for dry-run and idempotent Omega installation.

Use:

- `assets/builder-state.schema.json` as the canonical state contract;
- `assets/builder-tools.json` as function contracts;
- `assets/builder-role-prompts.json` as specialist role boundaries;
- `assets/omega-os.manifest.json` as the Omega command and extension manifest.

Preserve user work, permissions, evidence, stable IDs, hashes, and append-only history throughout.