Governed engineering runtime

Governed Engineering Runtime

Operate the target project root through the ai CLI. Treat this skill as a governance workflow, not as extra programming knowledge. Installing this Codex skill copies instructions and bundled runtime assets only; it does not install or expose the ai command.

Prepare

1. Confirm codex login status succeeds, or ask the user to run codex login.

2. Check whether ai --help succeeds.

3. If ai is missing, ask before installing executable code. Resolve the current skill directory from this loaded SKILL.md, inspect the bundled runtime/ source when required, then run:

   python3 <skill-directory>/scripts/bootstrap_runtime.py
   

   The bootstrap installs from the local runtime source bundled inside this skill. Pip may still resolve declared dependencies from configured package indexes. If the command installs successfully but ai --help still fails, ask the user to activate the intended virtual environment if they installed into one. For a user-level Python install, ask them to add the Python user scripts directory to PATH only after confirming the ai executable exists there:

   test -x "$(python3 -m site --user-base)/bin/ai" &&
     export PATH="$(python3 -m site --user-base)/bin:$PATH"
   ai --help
   

4. Change into the intended target project root, including an empty workspace when appropriate. Never initialize the installed skill directory.

5. Run ai init . in that target project root when .ai/project.yaml is absent. Do not replace an existing configuration.

6. Read references/runtime-checklist.md before the first run.

Execute

After successful project initialization, run an end-to-end governed change from the initialized target project root with:

ai build "<engineering objective>"

For human-controlled delivery, persist and approve each phase independently:

ai specify "<objective>"
ai approve specification
ai architect
ai approve architecture
ai delegate
ai approve delegation
ai implement
ai code-review
ai security-review
ai test
ai commit

Use ai status, ai tasks, and ai task use <task-id> to inspect or resume persisted work. Do not bypass phase prerequisites. ai review is a convenience command for code review, security review, and testing after implementation.

Empty target project roots are supported after ai init .. If a later run needs a branch, git.auto_init: true allows the runtime to initialize Git in that exact project root before creating its <git.branch_prefix>/<objective-slug> branch, such as ai/add-login-page. Branch slugs are lowercase ASCII kebab-case derived from the objective after removing resolved build-stack text, fall back to task, and are bounded to 96 characters. Existing local and already-present remote-tracking refs are checked without fetching; collisions use the smallest available suffix from -2 through -99. Run IDs remain unchanged for .ai/tasks, .ai/summaries, status, resume, and logs.

Allow the runtime to complete these stages in order:

1. specification;
2. architecture and specialist delegation;
3. required human approval;
4. implementation by a write-authorized agent;
5. independent correctness and security review;
6. testing against acceptance criteria;
7. optional Git commit.

Declare task dependencies when work within a stage is ordered. Run only independent tasks in parallel; reroute repository context before starting dependent tasks.

Do not bypass an approval gate, grant write access to the controller, or reinterpret an infrastructure failure as incomplete engineering work. Preserve existing repository changes.

Report

At completion, report the run status, branch, commit when created, affected files, validation results, remaining risks, and the location of persisted .ai/summaries and .ai/tasks records.