Autonomous Project Onboarding

A read-only, terminal Codex skill for inspecting a project or complex task before execution. It maps the outcome, risks, proof surfaces, workflow stages, downstream skills, context pressure, and model-effort recommendations, then emits one strict compiler-validated launch bundle with an exact native /goal launch command and returns control to the user.

The canonical skill ID is autonomous-project-onboarding. Its display name is Autonomous Project Onboarding.

Control Boundary

The onboarding turn follows:

DISCOVER (read-only) -> CLASSIFY -> RECOMMEND -> EMIT HANDOFF -> STOP

It does not research, compile goals, invoke downstream skills, edit files, or begin implementation. A later message in the same Codex task can accept the emitted offer.

Repository Layout

autonomous-project-onboarding/  Exact installable skill package
PACKAGE_SHA256SUMS              Package integrity manifest

Downstream skills recommended by onboarding are not bundled in this repository. Availability is resolved from the user's trusted installed-skill inventory.

Install

Clone the repository:

git clone https://github.com/oniivan/autonomous-project-onboarding.git
cd autonomous-project-onboarding

Install the skill package. This honors CODEX_HOME, stages the new copy first, and moves any existing installation to a timestamped backup instead of deleting it:

CODEX_HOME="${CODEX_HOME:-$HOME/.codex}"
skills_dir="$CODEX_HOME/skills"
destination="$skills_dir/autonomous-project-onboarding"
stamp="$(date +%Y%m%d%H%M%S)"
staging="$skills_dir/.autonomous-project-onboarding.install-$stamp-$$"
mkdir -p "$skills_dir"
cp -R autonomous-project-onboarding "$staging"
if [ -e "$destination" ]; then
  mv "$destination" "$destination.backup-$stamp"
fi
mv "$staging" "$destination"

The command changes only the skill's destination and its optional timestamped backup. No AGENTS.md setup, installer mutation, wrapper, alias, or companion continuation rule is required. Restart Codex or open a fresh task after installation so the skill inventory is reloaded.

When upgrading from version 1, remove only the old marker-delimited ONBOARDING_CONTINUATION_V1 block from ~/.codex/AGENTS.md if you previously installed it. Leave every unrelated instruction unchanged. Version 2 rejects the old execution offer schema and does not read that global block.

Use

Explicitly invoke the skill:

$autonomous-project-onboarding onboard this project and recommend the best workflow.

Onboarding emits a terminal packet ending with:

ONBOARDING_COMPLETE_AWAITING_USER_SELECTION

Approve, revise, or cancel the visible offer in ordinary language. Every packet also displays one exact command in its Start section:

/goal Execute Autonomous Project Onboarding offer <activation-id> from the complete packet visible in this task ...

Copy and paste that displayed command verbatim; there is no nested field to locate. Its launch preflight reparses the exact bundle and recomputes its digest before any native goal state is created. The command contains no duplicated skill stack: each stage's exact_prompt remains the sole authority for its exact $skill tokens.

The compiler accepts a smaller semantic authoring form and derives fixed versions, offer status, native-goal constants, the exact command, and stage skill-token headers. Prefer direct noninteractive stdin. The --json-argument fallback is limited to non-sensitive input of at most 65,536 UTF-8 bytes; it rejects duplicate keys, excessive depth, oversized integers, and non-finite constants. Literal apostrophes may be represented as JSON \u0027 escapes.

The exact /goal command is the deterministic start path. A blocked offer gets a safe command that may only present its degraded route and request the missing owner choice.

The launch contract grants no new credential, publication, purchase, destructive-action, or external-side-effect authority. Native /goal availability is reported in the packet; the command is still included when availability is unknown or unavailable.

Validate

Run the package-local deterministic tests:

PYTHONDONTWRITEBYTECODE=1 python3 -m unittest discover \
  -s autonomous-project-onboarding/scripts -p 'test_*.py' -v

Compile and revalidate the package-local example:

python3 autonomous-project-onboarding/scripts/compile_launch_bundle.py \
  autonomous-project-onboarding/references/launch-bundle-example.json |
python3 autonomous-project-onboarding/scripts/compile_launch_bundle.py \
  --validate-compiled -

Run the Codex skill validator from an environment with PyYAML:

python3 "${CODEX_HOME:-$HOME/.codex}/skills/.system/skill-creator/scripts/quick_validate.py" \
  autonomous-project-onboarding

Verify the published package snapshot:

shasum -a 256 -c PACKAGE_SHA256SUMS

Current Status

The package-local suite proves deterministic contract structure: terminal behavior, routing fixtures, exact stage skill sets, bounded raw-input handling, compiler-bound bundle and digest generation, state-aware ready/blocked transformation, agent-observed activation barriers, model-effort mapping, exact /goal generation, pre-goal fail-closed ordering, non-Ultra delegation proposals, deferred inputs, bounded skill amendments, and the absence of global or sibling-package runtime dependencies.

The checked-in live-malformed fixture is a minimal faithful reduction of the packet that motivated the compiler boundary. Deterministic tests do not prove host behavior. Fresh-session traces bound to the tested commit remain required evidence for actual terminal output and later-turn launch behavior.

License

MIT