| 1 | --- |
| 2 | name: cw-orient |
| 3 | description: "Use at the start of any Codewhale work session, or when unsure which checkout, branch, or worktree is authoritative: establish live repo truth before reading a plan or editing a file." |
| 4 | --- |
| 5 | |
| 6 | # cw-orient |
| 7 | |
| 8 | Open every session on live truth, not on a handoff note, a directory name, or |
| 9 | what was true last time. This repo runs many worktrees at once; the cheapest bug |
| 10 | to avoid is editing the wrong one. Five commands, then you know where you are. |
| 11 | |
| 12 | This is stage 1 of the loop: **orient → [cw-slice](../cw-slice/SKILL.md) → |
| 13 | [cw-gates](../cw-gates/SKILL.md) → [cw-dogfood](../cw-dogfood/SKILL.md) → |
| 14 | [cw-land](../cw-land/SKILL.md) → [cw-handoff](../cw-handoff/SKILL.md)**. |
| 15 | |
| 16 | ## When to use |
| 17 | |
| 18 | - Starting a session, resuming one, or taking over from another agent. |
| 19 | - A handoff, issue, or plan tells you the state of the repo — verify before |
| 20 | trusting it. |
| 21 | - You are about to edit and are not certain this checkout owns the files. |
| 22 | |
| 23 | ## Workflow |
| 24 | |
| 25 | 1. **Locate yourself.** Checkout, branch, dirt, and how far you are from the |
| 26 | remote: |
| 27 | ```bash |
| 28 | git rev-parse --show-toplevel && git branch --show-current |
| 29 | git status --short --branch |
| 30 | git log --oneline --decorate -10 |
| 31 | ``` |
| 32 | A detached HEAD or a branch with no upstream is normal here — note it, don't |
| 33 | "fix" it silently. |
| 34 | |
| 35 | 2. **See the other lanes.** Worktree sprawl is the standing hazard: several |
| 36 | checkouts of this repo are usually live, each with its own dirty state. |
| 37 | ```bash |
| 38 | git worktree list |
| 39 | git branch --sort=-committerdate --format='%(committerdate:short) %(refname:short)' | head -20 |
| 40 | ``` |
| 41 | If the work you were asked to do already has a worktree, use it. Do not |
| 42 | start a second copy of the same lane. |
| 43 | |
| 44 | 3. **Read the dirt before you touch it.** Modified files you did not write |
| 45 | belong to someone else — another agent, another lane, an in-flight slice: |
| 46 | ```bash |
| 47 | git status --porcelain |
| 48 | git diff --stat |
| 49 | ``` |
| 50 | Preserve them. Leave them unstaged, and do not `git checkout --` or stash |
| 51 | another writer's work to get a clean tree. If your change genuinely conflicts |
| 52 | with the dirt, work in a fresh worktree instead. |
| 53 | |
| 54 | 4. **Fix which guidance applies.** The nearest scoped `AGENTS.md` wins over the |
| 55 | root one, and it is where the per-area rules actually live: |
| 56 | ```bash |
| 57 | find . -name AGENTS.md -not -path './tmp/*' -not -path '*/node_modules/*' -not -path './target/*' |
| 58 | ``` |
| 59 | Today: root `AGENTS.md`, `crates/tui/AGENTS.md`, |
| 60 | `crates/localization/locales/AGENTS.md`, `web/AGENTS.md`. Read the one that owns the |
| 61 | files you are about to touch. |
| 62 | |
| 63 | 5. **Establish version truth from source, not memory.** |
| 64 | ```bash |
| 65 | grep -m1 '^version' Cargo.toml |
| 66 | ./scripts/release/check-versions.sh |
| 67 | ``` |
| 68 | `check-versions.sh` is the drift gate across the workspace version, npm, |
| 69 | `Cargo.lock`, the changelog, and the README. If it disagrees with what you |
| 70 | were told, believe the script. |
| 71 | |
| 72 | 6. **Only if the task is about the community queue** — issues, PRs, harvesting, |
| 73 | credit — pull the live queue with the `gh-*` skills in this directory rather |
| 74 | than assuming from memory. When the task is local-only, stay offline and |
| 75 | record the missing external receipt instead. |
| 76 | |
| 77 | ## Red flags / don't |
| 78 | |
| 79 | - Don't infer the active lane from a directory name, a stale handoff, or a |
| 80 | `.md` file's confident prose. All three have been wrong here. |
| 81 | - Don't treat a plan document as current state. Plans describe intent; `git` |
| 82 | describes reality. |
| 83 | - Don't clean, stash, reset, or `git checkout --` files you did not modify. |
| 84 | Worktree dirt is usually another writer, not garbage. |
| 85 | - Don't start work in a worktree whose branch is already merged to `main` — |
| 86 | that lane is retirement material, not a base. |
| 87 | - Don't skip step 4 because the root `AGENTS.md` "probably covers it". The |
| 88 | scoped files carry the rules that actually get violated. |
| 89 | - Don't fetch, browse, or hit GitHub when the task was scoped local-only. |
| 90 | |
| 91 | ## Output |
| 92 | |
| 93 | Open with a short status block. Skip fields that are empty or normal — a |
| 94 | clean tree on `main` with no related worktrees is one line, not five: |
| 95 | |
| 96 | - checkout path, branch (or detached HEAD), base commit; |
| 97 | - dirty files and whose they appear to be; |
| 98 | - other worktrees that own related work; |
| 99 | - workspace version and whether `check-versions.sh` agrees; |
| 100 | - which `AGENTS.md` files govern this change. |
| 101 |