# 0026 Explicit Onboarding Skills In Default Core

Date: 2026-07-23

## Status

Accepted and active.

## Context

Decision 0020 kept the default installation small and excluded generic
evaluation machinery. Application-legibility work then tested an
explicit, repository-owned onboarding workflow against the brownfield
`e-inna-brain` consumer.

The pilot produced two forward-tested skills:

- `$onboard-repository` maps one real repository path, remains read-only on its
  first pass, and emits evidence-backed proposals; and
- `$audit-onboarding-proposal` independently checks the producer transcript and
  exact proposed patches before application.

The frozen replay showed a direct improvement: replacing a stale installed
instruction removed one obsolete command attempt. It also showed why the
guardrails belong with the workflow: incomplete preflight, ownership omissions,
and unsupported runtime claims remained visible rather than being promoted as
product truth.

Keeping the skills only in a consumer experiment makes the learned workflow
unavailable to the next installed repository. Auto-running them, however,
would add hidden startup work and could inspect or propose changes when the
user did not request onboarding.

## Decision

1. The default Harness core installs both skills under `.agents/skills/`.
2. Both skills remain explicit-only through
   `allow_implicit_invocation: false`. Installation does not invoke them and
   does not create a first-run hook.
3. `$onboard-repository` is the user-facing entry point. Its first pass is
   inspection and proposal only; repository edits require exact user approval.
4. `$audit-onboarding-proposal` is the independent verification companion. It
   remains read-only and does not grant approval by itself.
5. Their scripts and references are managed core files because they provide
   deterministic patch rendering, evidence transport, and validation for the
   two skills. They do not become mandatory steps for ordinary repository work.
6. The skills may use Python when explicitly invoked. Core installation,
   updates, and ordinary work do not require Python. A missing runtime
   prerequisite must stop the invoked skill safely rather than trigger an
   installer-side dependency installation.
7. This decision narrowly amends decision 0020. The installer still has one
   core profile; engineering wisdom remains an independent opt-in add-on. The
   core excludes generic benchmarks, trace scoring, orchestrators, application
   adapters, databases, and any consumer runtime.

## Alternatives Considered

1. **Keep the skills only in the pilot consumer.** Rejected because validated
   onboarding behavior would not reach newly installed repositories.
2. **Auto-run onboarding after installation.** Rejected because installation
   cannot determine whether a repository is ready for inspection, which
   operational path the user wants mapped, or whether the current agent owns
   the necessary runtime state.
3. **Add a third installer profile.** Rejected because the skills are generic
   repository workflow guidance, while another profile would recreate the
   feature-matrix problem rejected by decision 0020.
4. **Install only the producer skill.** Rejected because the pilot repeatedly
   found plausible but unsupported proposal clauses that required an
   independent fail-closed audit.
5. **Remove deterministic scripts before promotion.** Rejected because exact
   patch rendering and authenticated evidence transport fixed observed
   transcription and incomplete-preimage failures.

## Consequences

Positive:

- A fresh Harness installation exposes a tested brownfield onboarding path.
- The first pass remains safe and approval-gated.
- Installed skills and their deterministic resources update through the same
  provenance-aware merge as the rest of the core.
- Ordinary tasks retain the compact `AGENTS.md` plus `docs/WORKFLOW.md` entry
  context because neither skill is implicitly invoked.

Tradeoffs:

- The default managed payload grows by two skills and seven bundled resources.
- Explicit onboarding currently needs Python for deterministic rendering and
  validation.
- Consumer edits to managed skill files can produce normal three-way update
  conflicts.
- The evidence protocol is more complex than the ordinary task workflow and
  must remain isolated until explicitly invoked.

## Follow-Up

- Keep both skill packages valid under `quick_validate.py`.
- Exercise fresh and merge installation on Bash and PowerShell.
- Treat further simplification as a measured skill revision, not an untested
  rewrite during packaging.