Orientation

---
name: orientation
description: Get someone ready to use this harness. Checks the clone, asks what job they want to hand to an agent, which tool they drive it with and where their company's data lives, maps how the agent can reach that data, interviews them for a short company record, then walks them through the five layers around their job, one drafted file at a time. Use when someone runs /orientation, says "get me started", "orient me", "how do I use this", "new here", "set this up for my job", or asks where to begin.
license: MIT. From the Sanvio Labs harness starter, https://github.com/SanvioLabs/sanvio-harness-starter
---

# Orientation

The person has just cloned this repo. Show them the harness working on them:
check their setup, find out what they do, where their company's data lives and
who the company is, then build the five layers around their job one at a time. Instructions, a
skill, a gate, the hook, a review agent.

You draft. They say yes or no. Nothing gets written without a yes.

## Rules for this skill

- Never write a file the person hasn't seen and said yes to. Show the whole
  draft for a new file, and a diff for an edit.
- Never overwrite silently. If a file you're about to write already exists,
  it's probably from an earlier run: show what's there and ask whether to keep
  it, edit it or replace it.
- Never remove or weaken a check in [`.githooks/pre-commit`](../../.githooks/pre-commit) or any gate. New
  checks go alongside the ones already there.
- Never edit [`examples/`](../../examples/). It's the reference the person copies from. Their job
  is built at the root.
- Never rewrite [`AGENTS.md`](../../AGENTS.md) wholesale. Add to it. The existing rules and the
  Skills, Agents and Examples tables stay.
- Never run a fix the setup check names, never run `git checkout`, and never
  commit. Name the command and let the person run it.
- Never add, log in to or configure a connector or MCP server, and never ask
  for, read or print a token, key or password. Name the setup step in their
  tool and let them do it.
- Record where company data lives, never what's in it. Don't copy company data
  into the repo to look at it, and don't quote it back into a file.
- A no skips that step or layer and offers the next one. It doesn't end the
  conversation.
- If a request needs a tool-specific hook ([`.claude/settings.json`](../../.claude/settings.json), a Codex or
  Kiro hook) or a change to an existing gate, stop and say it's outside this
  skill. The in-loop hook is the last bonus in [`EXERCISES.md`](../../EXERCISES.md).

## Steps

### 1. Check the clone

Read-only. Run both and report what they print:

```bash
python3 scripts/check_setup.py
python3 -m unittest discover -s tests
```

`check_setup.py` prints one `PASS`, `WARN` or `FAIL` line per item with the fix
under it: Python version, whether the hook is switched on, whether the
[`CLAUDE.md`](../../CLAUDE.md), [`.claude/skills`](../../.claude/skills) and Kiro links work, whether the example in
[`examples/proposal/`](../../examples/proposal/) passes its gate, whether a company record exists yet,
whether a personal skill is hiding one of the repo's, and where `origin`
points. Pass its lines through as printed. For the tests, one line: passed, or the names that failed.

Say these out loud when they show up:

- **Hook FAIL.** Every check in the hook silently does nothing until they run
  the fix. Don't run it for them.
- **Remote WARN on the public starter.** Everything in [`company/`](../../company/) is
  gitignored, so the company record and the data map stay on their machine
  either way. Their own job's files (the five layers) are tracked, though, and
  before they push those anywhere they need their own private copy. On GitHub
  that's *Use this template* with the visibility set to private. If `gh` is
  installed and `origin` is on GitHub, run
  `gh repo view --json visibility -q .visibility` and say what it returns.
- **Gate or tests FAIL.** On a clean clone of `main` these pass, so suggest
  `git status` to look for local changes.
- **Skills WARN.** A skill in their personal `~/.claude/skills` has the same
  name as one here, and in Claude Code the personal copy wins, so the repo's
  never runs. Offer to compare the two. If the personal one is better, the fix
  is to bring it into [`skills/`](../) (through [`skills/review-skill/`](../review-skill/) if someone else
  wrote it) and then rename or remove the personal copy. Don't touch anything
  in their home directory yourself.
- **Started below the root.** If your working directory isn't the harness
  root, say so first: the skills, agents and guards didn't load. Ask them to
  restart at the root, and stop there.

Then list any files in [`skills/`](../), [`gates/`](../../gates/) and [`agents/`](../../agents/) beyond the ones this
repo ships (the skills `orientation`, `learn`, `review-pr`, `review-tests`,
`review-skill` and `whats-new`, [`gates/README.md`](../../gates/README.md), and [`agents/reviewer.md`](../../agents/reviewer.md)), and whether
`company/COMPANY.md`
and `company/DATA.md` exist. Those are from an earlier run and show where the
person left off. Read them, and skip the questions they've already answered.

A FAIL doesn't stop the walk. Go on to step 2.

### 2. Ask three questions

In one message, ask exactly these three, then stop and wait for the answers:

1. What job do you do every week that you'd like to hand to an agent? (A
   status update, a code review, an invoice, a support reply, a release note.)
2. Which tool are you driving it with (Claude Code, Codex or Kiro), and is it
   on a personal plan or one your company manages?
3. Where does the company information that job needs live? Docs (Google
   Drive, Notion, Confluence, SharePoint), chat (Slack, Teams), tickets (Jira,
   Linear, GitHub), a CRM, a database, a code repo, files on your laptop.

If an answer is missing or vague, ask again for that one. Don't guess the job,
and don't guess where the data is.

If the job works on code, say once where it goes: clone the repos into
[`projects/`](../../projects/) and keep starting the agent from the harness root.
[`projects/README.md`](../../projects/README.md) has why.

From the job, pick a short kebab-case name (`weekly-status`, `release-notes`)
and use it in every path below. Say the name in the first draft so the person
can change it.

### 3. Map how the agent reaches each source

For each place they named in question 3, work out how the agent gets at it.
Start with what you can actually see: list the connectors and MCP servers
available to you in this session, by name only. Never show their config. Then
sort each source into one of four:

| Reach | Means | What to tell them |
|---|---|---|
| **Connected** | A connector or MCP server for it is live in this session | Nothing to do. Say which one |
| **Connectable** | A connector exists for it but isn't set up here | Where to add it in their tool: `/mcp` and `claude mcp add` in Claude Code, `codex mcp add` in Codex, the MCP settings in Kiro. Point at the tool's own docs and the vendor's official server. Connect read-only where it offers that |
| **Export** | No connector, but files can be exported | Put exports in `local-data/`, which is gitignored, and never commit them |
| **By hand** | None of the above | They paste what a task needs into the conversation, each time |

Then ask two things, once, for the whole list:

- **Is it cleared for this tool?** Company data reaching an AI tool is the
  company's call, and the plan matters: a personal plan can leave training on
  your data to a setting, where a business, enterprise or API plan usually
  rules it out by contract. If they don't know, mark the source `unconfirmed`
  and say not to connect anything sensitive until someone who owns that
  decision says yes.
- **Is anything off-limits outright?** Customer personal data, health or
  payment details, credentials. Those stay out of the agent's reach whatever
  the plan, and out of the repo whatever happens.

A connector that can write (send email, edit a doc, post a message) goes on the
list of things the agent never does on its own in layer 1.

### 4. Write down where the data lives

Draft `company/DATA.md`:

```markdown
# Where company data lives

| Source | What's there | How you reach it | Cleared for this tool |
|---|---|---|---|
| Google Drive, "Clients" folder | Signed proposals, briefs | Google Drive connector, read-only | yes |
| Billing system | Hours logged per client | CSV export into `local-data/` | unconfirmed |

- Read it where it lives. Never copy its contents into a tracked file.
- Exports go in `local-data/` and are never committed.
- Never use a source marked `unconfirmed`, or anything off-limits, until a human
  says so in this session.
- Never write to any of these without a human saying so in this session.
```

Fill it from the person's answers, not the example rows. Write on a yes.

Say once that [`company/`](../../company/) is gitignored, so this stays on their machine, and that
every session reads it: the next agent that opens the repo knows where to look
without asking. [`company/README.md`](../../company/README.md) says how to share it with a team once their
copy is private.

### 5. Write the company record

Offer it in one line: "Want to spend five minutes telling me about the company?
I'll write it down so every session knows who it's working for." A no skips to
step 6, and a later run picks it up.

On a yes:

1. If `company/COMPANY.md` doesn't exist, copy [`company/COMPANY.example.md`](../../company/COMPANY.example.md)
   there. If it does, read it and only ask about the sections still empty. A
   section is empty when everything under its heading is blank or an HTML
   comment: the `<!-- -->` prompts are not answers.
2. Ask one section at a time, in order, as a real question rather than the
   heading. "What do you turn down, even when the money's good?" not "What we
   won't do".
3. After each answer, write it into that section in their words, lightly
   cleaned up, then ask the next. Write as you go, so stopping halfway keeps
   everything answered so far. This file is gitignored and theirs, so each
   answer they give is the yes to write it.
4. Set `updated:` to today when they finish or stop.

Never draft an answer for them and never fill a section they skipped. "Skip"
leaves a section empty, "stop" ends the interview.

### 6. If they want to see the layers first

Offer it in one line: each layer is a tag, and `git diff step-1 step-2` shows
exactly what one adds. If they want the tour, run
`git diff step-<n-1> step-<n> --stat` for each layer in turn, show it, and say
in two sentences what that layer adds and what it fixes (the table in
[`README.md`](../../README.md) has it). Don't check anything out: [`skills/orientation/`](./) doesn't
exist at `step-0`, and this conversation would lose its instructions.

If they'd rather build now, go on to step 7.

### 7. Build the five layers, in order

For each layer: say in one sentence what it's for, draft the files for the
person's job, show the drafts, and ask "Write this?" Write only on a yes. On a
no, say the layer is skipped and offer the next one. Keep a list of every file
you write or edit.

**Layer 1: Instructions.** Draft a new section in [`AGENTS.md`](../../AGENTS.md) headed with the
job, below the Rules section. Three things only:

- Where the inputs come from, pointing at `company/DATA.md` for where they
  live if step 4 wrote it rather than copying its rows into this tracked file,
  and that the agent never invents them
- Where the output goes, and what it's called
- What the agent never does on its own (send, pay, delete, merge, and anything
  a connector from step 3 can write)

Ask for anything you'd have to guess. In Codex it's read as is, in Claude
Code through [`CLAUDE.md`](../../CLAUDE.md), and in Kiro through [`.kiro/steering/`](../../.kiro/steering/), so it's one
edit for all three.

**Layer 2: Skill.** Draft `skills/<job-name>/SKILL.md`, shaped like
[`examples/proposal/skills/draft-proposal/SKILL.md`](../../examples/proposal/skills/draft-proposal/SKILL.md): `name` and `description` frontmatter, with
the description saying when to use it; Inputs; numbered Steps; Output. If the
person can't say what the output is, ask until they can. In the same draft,
add a row for it to the Skills table in [`AGENTS.md`](../../AGENTS.md). Tell them
`python3 -m unittest discover -s tests` now fails if a skill is missing its
frontmatter or its row. Claude Code finds it through the [`.claude/skills`](../../.claude/skills) link;
Codex and Kiro find it through [`AGENTS.md`](../../AGENTS.md).

**Layer 3: Gate.** Draft `gates/<job-name>_gate.py`, shaped like
[`examples/proposal/gates/proposal_gate.py`](../../examples/proposal/gates/proposal_gate.py) ([`gates/README.md`](../../gates/README.md) has the rules): standard library only, Python 3.9, one `PASS` or
`FAIL` line per file, each problem named on its own line, exit 1 on any
failure. Check what's cheap to check and expensive to miss: an empty section,
a placeholder, a number that doesn't match its source. With file paths it
checks those; with none it checks every output the job has. Anything that
needs judgement goes to the brief in layer 5 instead ([`steering/gates.md`](../../steering/gates.md) has
the test). In the same draft, show:

- The edit to the last steps of their skill, if Layer 2 was written: run the
  gate, fix what it names, run it again until it passes
- A line in their [`AGENTS.md`](../../AGENTS.md) section, if Layer 1 was written: the job is
  done when the gate passes, and the gate is never edited to make it pass

After writing, suggest they ask the agent to call the job done with the gate
failing, and watch it refuse.

**Layer 4: Hook.** This needs a gate for the job. If Layer 3 was skipped and
no gate for the job exists, say the hook has nothing to run yet and offer
Layer 5. Otherwise draft a diff to [`.githooks/pre-commit`](../../.githooks/pre-commit) that adds a new
numbered block after block 2, in the same style: collect the staged files
matching the job's output path and run the new gate on them with
`|| status=1`. Blocks 1 and 2 stay exactly as they are. In the same draft, add
a step to [`.github/workflows/ci.yml`](../../.github/workflows/ci.yml) that runs the gate with no arguments, after
the example's step: the hook can be skipped, CI can't once it's a required
check. If the gate takes more than a few seconds, leave it out of the hook and
put it in CI only, and say why ([`steering/gates.md`](../../steering/gates.md)). If the hook was FAIL in
step 1, repeat the fix, `git config core.hooksPath .githooks`, and say the hook
won't run until they do. To test it, they commit an output that should fail and
watch the commit refuse.

**Layer 5: Review agent.** The harness already has one reviewer,
[`agents/reviewer.md`](../../agents/reviewer.md), that reads any work as the person who receives it. What
this job needs is a brief for it. Draft `agents/<job-name>-brief.md`, shaped
like [`examples/proposal/agents/proposal-reviewer.md`](../../examples/proposal/agents/proposal-reviewer.md): who receives the output,
what they'll hold the author to, and what to look for that the gate can't
check. In the same draft, add a line to the last step of their skill, if Layer
2 was written: hand the output to the `reviewer` agent with this brief. In
Claude Code that's the `reviewer` subagent. In Codex or Kiro, tell them to run
a separate session with [`agents/reviewer.md`](../../agents/reviewer.md) as its instructions and point it
at the brief.

**Watch the layers work.** Only if they drive the agent with Claude Code
(question 2). Point at the line above the prompt: it's the harness lens,
[`examples/mods/harness-lens/`](../../examples/mods/harness-lens/), and it names which layer just acted: the
steering read, the skill followed, the gate and how it went, a tool the guard
refused, the reviewer. It's on by default, from [`.claude/settings.json`](../../.claude/settings.json). Say
how to use it: run the job they just built and watch the line light up layer
by layer, a failed gate or a refusal in red, and type `/lens` for everything
the harness did in the session. If they don't see the line, name the two
commands in its README that install it from inside the session, and let them
run them. In Codex or Kiro, skip this: neither has mods.

**Last: the release log.** If any layer was written, draft one entry for the
top of [`CHANGELOG.md`](../../CHANGELOG.md) in the shape of the ones there: today's date, the job's
name, the files written, and a **Do:** line. Write it on a yes.

## Output

Last, in one message:

- Every file written or edited, one per line, with created or edited
- Each data source, with how the agent reaches it and whether it's cleared,
  and any source still `unconfirmed` or still to connect
- Which sections of `company/COMPANY.md` are written and which are still
  empty
- For each gate added, the one command that checks it:
  `python3 gates/<job-name>_gate.py <path to an output>`. If no gate was
  added, say so
- Any FAIL or WARN from step 1 still open, with its fix
- In Claude Code, whether the harness lens is showing, and `/lens` for the
  session so far
- The steps and layers skipped, so they know what's left if they run this
  again
- One line on what to do next time the agent gets something wrong: say "learn
  from that", and [`skills/learn/`](../learn/) writes the rule down where it governs