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 before applying examples.

Resolve the harness first

Before any other step, resolve the target's harness: tiers, delegation limits and routing differ per repository. This holds for every task, code or not; with no target repository, resolve the library itself. 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 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. Follow the workspace contract. 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: 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. 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. 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; 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. 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 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. Use local resources first; 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. 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 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 by volume, not by kind: a simple question stays with you, and reading about five or more independent sources goes to scouts on the cheapest tier while you keep the judgement (general task). Pieces of one task go to subagents; a task with its own branch or PR may get its own session in parallel mode or on request. Send wide read-only searches to a scout and a code or large docs diff to one reviewer child before its PR, in its own slot beside max_children (review before the PR); a reviewer session only when the user asks. 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). No recursive agent chains. When the same step fails the same way twice, change the approach once, then stop and report (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).

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 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 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 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).

Before delivery, run the relevant library checks in 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 and retention. 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. 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 when tools differ, and pass search scope and required guidance explicitly to delegates.

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