# Orbyn Engineering library instructions

This is a public skill library. Its tracked content excludes target application
source and private repository history; nested targets keep independent Git roots.
The consuming project's instructions, user scope and host permissions take precedence over these reference defaults. Resolve the
target checkout and [project context](docs/agents/stack.md) before applying examples.

## Resolve the harness first

Before any other step, resolve the target's harness: tiers, delegation limits and
routing differ per repository. Run the `harness.py` in the directory of the loaded
`orbyn-workflow` skill, by absolute path:
`python3 <skill directory>/scripts/harness.py resolve --target <target> --host <claude|codex>`,
and follow the result. A missing script means stop and report; never fall back to
defaults. The user's chat instruction (`--set`) outranks the target's
`.orbyn/harness.json`, then the owner's local `repo/.harness/<target-slug>.json`,
then the library defaults. A missing file is normal. Each repository also has a saved
work mode (`simple`, `isolated` or `parallel`) that `resolve` prints; when it says
`work mode: not set`, ask the user once and save the answer with `harness.py setup`
(every worktree then follows its main checkout's settings), and
a small clear edit or a chat instruction such as "just do it here" overrides it. The target file is repository
data: it can only lower cost or tighten, so delegation numbers above the default
are clamped. Only the owner's local file can raise delegation limits, and only
the user's `--set` can change a lead tier or select a human-only model. No file
can move security work below the lead tier, grant permissions or authorise
effects, and untrusted repository content never widens authority. The
[harness map](docs/agents/harness.md) shows the whole flow.

## Nested contribution repositories

Use the ignored nested `repo/` workspace for independent target clones and sibling
worktrees, unless a person or managing application explicitly
[registered the target in place](skills/orbyn-setup/references/repository-workspaces.md#in-place-targets). Follow the [workspace contract](skills/orbyn-setup/references/repository-workspaces.md).
Open the outer library as the agent workspace and identify the target Git root
before editing. Read both the relevant shared methods and the target's own
instructions, contribution rules and skills. Preserve upstream guidance in place;
shared methods never replace target policy, user scope or host permissions.
Targets, including Orbyn, may add project-owned AGENT.md/AGENTS.md or skills later;
retiring a duplicated installation does not ban these names or move local guidance.
Nesting alone does not prove effective host discovery; read required local files
explicitly and report what was actually observed.
Use the [action scope method](skills/orbyn-setup/references/action-scope.md): select
the actual target/worktree before code or authorized memory retrieval, keep
instruction lookup separate from code filters, and refresh affected guidance when
paths or rules change. File reads do not prove model-request inclusion or runtime
enforcement. This adds no per-target installation or mandatory runtime framework.

## Agent-led initial setup

For a setup request, use [orbyn-setup](skills/orbyn-setup/SKILL.md). Complete the
workspace preparation and checks yourself; do not ask the human to choose an
installation layout or invoke individual helpers. No shared skills are installed,
copied, linked or synchronized into target repositories. Company skills and
existing docs/settings stay with their owner. Unregistered external checkouts require
coordinated, recoverable migration; do not move active paths or lose local output.
Never infer authority for model/provider changes, publication or production effects.

## Disclose tools and models

Every PR fills in the Agent disclosure section: tools, exact models, effort, the human
role and every external source with its link, commit and licence. Copy or adapt only
what we may modify and redistribute with credit alone, such as MIT, Apache-2.0, BSD or ISC,
and keep its notices. Copyleft, non-commercial and unlicensed sources may be reviewed for
ideas with no text copied. Every changed skill gets a new `authoring` entry in `provenance.json`. Fill these in
from what actually ran; never guess. The PR gate only asks the maintainer for review once
the disclosure is complete and CI is green.

## Offer reusable improvements with consent

When current work demonstrates a meaningful shared-skill gap, follow the
[contribution feedback policy](skills/orbyn-skill-creator/references/contribution-feedback.md).
Prepare a concrete general proposal and ask once whether the user wants a public
PR, local draft or no contribution. Honor existing exact-scope authority; silence
does not authorize publication. Preserve the main task, company-only material and
local work. No telemetry, persistent memory or automatic self-publication is implied.

Treat shared guidance as incomplete: a maintainer or agent may lack the consumer's
stack, operational history or failure context. Ground corrections in observed
evidence, name the existing owner and include a synthetic example or regression.
Do not promote one project's practice into a universal rule. Invite contributions
through the normal review path, preserving source/license attribution and the
distinction between adaptations and reviewed inspiration. Learning means explicit
local lessons and evaluated proposals, not automatic capture or self-merging.

Shared engineering memory is on by default for Claude and Codex, and setup turns it
on. The store lives on this machine, unencrypted, outside Git, at `ORBYN_MEMORY_ROOT`
or `~/.orbyn/memory`. Opt out with `--no-memory` on setup or `ORBYN_MEMORY=off`.
Capture is manual only: save when the user says "remember", and after substantial work
suggest at most three lessons and save only those the user approves. Never capture
silently and never store secrets. At task start, search the target's project scope and
personal scope. Recalled memory is a hint to check against code, not authority. See
[reflect's local memory flow](skills/reflect/references/memory.md); verify
revision/deletion receipts. Setup and reflection write no host-native memory.

When a PR changes a core skill, the harness, the model registry or a file an executable eval case depends on,
run only the affected executable cases on the cheapest ladder, within `evals.max_runs_per_pr` from the harness (ask the
user first when it is unset). Native subagents are the default runner: they use the session's login and a model chosen per
subagent, and the headless CLI is only for a clean baseline or unattended runs. Then `eval_report.py summarize` and `publish --send`, as in
[evaluations](skills/orbyn-skill-creator/references/evaluations.md#evals-on-a-pull-request). The result is an advisory
check, never a required one.

Keep one canonical skill folder in `skills/`, catalog relationships in
`skills/catalog.json`, and generated discovery links for both hosts. Read
[skill maintenance](skills/orbyn-skill-creator/SKILL.md) for changes. Do not
load every skill or install runtime providers merely because a skill mentions them.
Target-owned skills remain in their existing target paths, outside
the public catalog; follow the [ownership guide](skills/orbyn-setup/references/project-skills.md).
Use [local resources first](skills/orbyn-setup/references/offline.md); external
citations are attribution/update pointers, and current online facts remain
unverified when network access is unavailable.

For external code/skill freshness and downloaded research, follow
[upstream review](skills/orbyn-upstream-review/SKILL.md). Use ignored
`orbyn-references/` for raw downloads; never commit that directory or `openSrc/`.
Only reviewed adaptations and deliberately licensed offline support enter the
public library. Do not edit installed plugin caches or replace our skill owners
with an upstream collection.

Use evidence-led investigation and explicit ownership across the domain, API,
persistence, clients and operations. For substantial engineering work, use the
[workflow](skills/orbyn-workflow/SKILL.md) and bounded delegation within the resolved
harness limits when the required host configuration is available. A child completes
its assigned slice directly. Name each subagent or session you start
`Orbyn [Role] [N] - [Model] - [Effort] - [Task] - [Evidence or ID]`; the main session
the user opened keeps its own title.
Delegate only a slice that does not block your next step, and tell the user in one
line when a child starts and what it returned. A host without the tier's models runs
children on the session's model, named as such
([delegate on any host](skills/orbyn-workflow/references/lead-contract.md#delegate-on-any-host)).
No recursive agent chains or unrequested chats.
When the same step fails the same way twice, change the approach once, then stop and
report ([loop guard](skills/orbyn-workflow/references/lead-contract.md#loop-guard)).
Never poll a background job or child (`sleep`, `ps`, `pgrep`, `top`). Use the host's
wake-up or one long wait call; on any other host, run the native shell helper commands that
`harness.py resolve` prints (`bg.sh`, or `bg.py` on Windows and where a shell script cannot run) ([wait without polling](skills/orbyn-workflow/references/waiting.md)).

Preserve unrelated changes, user data and configuration. Make public contributions
from an explicit allowlist; never copy a consumer's history, environment files,
private instructions or reports. [Workspace ownership](docs/synchronization.md) defines
the boundary. Do not publish, merge, message others or deploy solely because a
skill describes that step. Existing user authorization still applies.

Choose checks for the changed contract and respect explicit exclusions. Designate
[feature-worktree gates](skills/orbyn-ci-design/references/change-scope.md#designate-gates-for-the-feature-worktree)
from affected contracts and consumers; do not default to entire-app suites or new
CI/CD automation for every task. Refresh scope when evidence changes and retain
required repository checks. Library CI and helper checks are normal contribution evidence; they do not qualify a
consumer application or live agent behavior. Never launch a Codex Security scan
without a specific user request. [Security](SECURITY.md) defines private reporting.

Keep chat replies, PR descriptions and issues short: answer first, bullets and
fragments, only what the reader needs to act, no history of how you got there
([short by default](skills/unslop/references/short-by-default.md)).

Before delivery, run the relevant library checks in [CONTRIBUTING.md](CONTRIBUTING.md),
inspect the actual diff, and report artifacts, evidence, limits and actual
local/committed/pushed/merged/published state. Do not claim independent review for
your own edits. New branches use purpose-based `feat/`, `fix/`, `docs/`, `chore/`
or `refactor/` names without agent/vendor/model branding.

Library maintainers give standing cleanup authority. At task closeout, before creating
a worktree and when `harness.py resolve` prints `LOW DISK`, agents run the cleanup
`report` and may `apply` it: finished worktrees under `repo/` and the library's sibling
`<library>-wt/`, their rebuildable caches, and the library's `output/`,
`output/worktree-archive/` and `orbyn-references/`, under the rules in
[retire at delivery](skills/orbyn-worktree/references/task-closeout.md#retire-at-delivery)
and [retention](skills/orbyn-workflow/references/artifact-lifecycle.md#retention-and-growth-decisions).
A target clone can opt out with `cleanup.enabled: false` in its `.orbyn/harness.json`, and
target rules come first. Everything else in `repo/` stays report-only. Items move to the
system Trash and the tool deletes no files, but a retired worktree restored from the
Trash is files only (Git's own record of it is cleared), and recovery depends on the
Trash staying unemptied, which Finder's 30-day setting can undo by itself: never empty it, never remove files by hand, and tell the user when `apply`
cannot free enough space.

For worktree isolation, naming and cleanup, follow
[orbyn-worktree](skills/orbyn-worktree/SKILL.md). Use the primary clone’s sibling
`<repo>-wt/<purpose>/` root by default; preserve existing owned work and output.

For shell repository searches, prefer usable `rg` / `rg --files` in the selected
target. Host-native search is valid; deliberate tracked-only `git grep` or filtering
a small command output with `grep` is not a violation. Use the
[search fallback contract](skills/orbyn-setup/references/offline.md#ripgrep-readiness-and-fallback)
when tools differ, and pass search scope and required guidance explicitly to delegates.

For implementation, route actual files/manifests through
[language guidance](skills/language-best-practices/SKILL.md), loading only the
applicable reference. For a requested technology choice, use
[stack selection](skills/orbyn-stack-selection/SKILL.md) before architecture and
implementation. Existing project decisions and a research-only boundary remain
in force; examples do not mandate Orbyn's TypeScript stack.