Orient

Orient is a methodology for producing a bounded mental-model update for a human developer working in a code repository. One Orient run inspects the repo, writes a disposable read pack under .methodologies/orient/scratch/, and leaves product files unchanged.

What Orient Delivers

• a read pack that states what the developer should understand differently
• repo-grounded findings that support that update
• disposable runtime output written only under .methodologies/orient/scratch/

Start Here

• Read methodology/ORIENT.md for the Orient model, boundaries, and companion documents.
• Use methodology/WORKFLOW.md as the runtime entrypoint when executing or resuming an Orient run.
• Use setup/orient-setup.md to install Orient into a target repo.
• Use library/overview.md when you need local library guidance such as read-set, lens, adapter, or claim selection.
• Run scripts/verify-orient.sh from this source repo to verify the source package or an installed target repo.

Repo Layout

• methodology/: core methodology docs, templates, and appendix references
• library/: read-set, lens, adapter, and claim libraries
• setup/: installation instructions for target repos
• scripts/: source-repo helper scripts

Quickstart

Source repo:

• run scripts/copy-orient.sh /path/to/target-repo [--scope entire-repo|selected-paths] [--scope-path <repo-relative-path> ...]

Installed runtime:

• set up Orient under .methodologies/orient/
• run orientation passes from .methodologies/orient/methodology/WORKFLOW.md

Recommended install flow:

1. From this source repo, copy methodology/ and library/ into the target repo under .methodologies/orient/.
2. Add the Orient section to the target repo AGENTS.md using setup/orient-setup.md.
3. In the target repo, set .methodologies/orient/status.md operating scope, then approve explicit permissions using .methodologies/orient/methodology/STATUS.md.
4. In the target repo, start the run at .methodologies/orient/methodology/WORKFLOW.md.

Use In Another Repo

Use setup/orient-setup.md for the source-repo install procedure and the target-repo AGENTS.md snippet.

Contributing

Please see our Contributing Guide for details.

Run scripts/verify-orient.sh and npx --yes markdownlint-cli --disable MD013 -- "**/*.md" before opening a pull request.

Source files should include SPDX-License-Identifier: (CC0-1.0 OR 0BSD) where applicable.

License

This project is released under a dual-license model. Choose either:

• CC0-1.0 - Creative Commons Zero v1.0 Universal
• 0BSD - Zero-Clause BSD

This applies to all project materials.