# Onboarding: Working on `muse` and `musehub`

Welcome aboard. This is the workflow to follow on every ticket until it's
second nature. You have `write` access on both `muse` and `musehub` —
no fork required.

## Step 0 — Clone both repos (skip if you already have them)

If you don't already have local copies, clone both directly — your write
access means you're cloning the real repos, not a fork:

```bash
muse clone https://staging.musehub.ai/gabriel/muse
muse clone https://staging.musehub.ai/gabriel/musehub
```

Same semantics as `git clone` — this creates two regular directories in your
current location, named after each repo: a `muse` folder and a `musehub`
folder (not hidden — no leading dot). Each one has a hidden `.muse/`
directory inside it (that's Muse's own metadata, same role as `.git/`), plus
`origin` already pointing at the source URL. Check out `dev` in each if it
isn't already the default:

```bash
muse -C muse checkout dev
muse -C musehub checkout dev
```

Everything below assumes you're starting from one of these two directories
— substitute the actual path where you cloned each one.

## The standard cycle

```bash
# 1. Start from dev, always
muse -C ~/path/to/muse checkout dev
muse -C ~/path/to/muse pull local dev   # or: muse -C ~/path/to/muse pull staging dev

# 2. Branch — never work directly on dev or main
muse -C ~/path/to/muse checkout -b task/short-description \
  --intent "what this branch does" \
  --resumable

# 3. Do the work, commit as you go
muse code add .
muse commit -m "feat: what changed and why"

# 4. Push your branch (not dev, not main — your branch)
muse -C ~/path/to/muse push staging task/short-description

# 5. Open a merge proposal (MP) — MuseHub's equivalent of a PR
muse -C ~/path/to/muse hub proposal create \
  --title "Plain-English description of the change" \
  --from-branch task/short-description \
  --to-branch dev \
  --hub https://staging.musehub.ai

# 6. Assign the MP to gabriel for review
muse -C ~/path/to/muse hub proposal reviewer request <proposal-id> gabriel \
  --hub https://staging.musehub.ai
```

Gabriel reviews and merges (or sends it back with comments). You don't merge
your own MPs into `dev`/`main` — that's the review gate.

## Picking up work

- Gabriel will assign you tickets directly, or you can browse/self-assign
  open issues:
  ```bash
  muse -C ~/path/to/muse hub issue list --state open --hub https://staging.musehub.ai
  muse -C ~/path/to/muse hub issue assign <number> --assignee aaronrene --hub https://staging.musehub.ai
  ```
- You can also file your own issues for things you find:
  ```bash
  muse -C ~/path/to/muse hub issue create --title "..." --body-file /path/to/plan.md --hub https://staging.musehub.ai
  ```

## A few conventions worth knowing up front

- **Branch naming**: `task/...` for general work, `fix/...` for bug fixes,
  `feat/...` for new features. The type prefix goes in the branch name, not
  the MP title — MP titles should be plain English (e.g. "Fix push
  authorization gap for private repos," not "fix: push authz").
- **Always pass `--hub https://staging.musehub.ai`** on `muse hub` commands
  unless you're deliberately targeting a different instance.
- **Non-trivial work gets a plan first.** For anything more than a small
  fix, write the issue body as: Background (why this exists), Goal
  (what "done" looks like), Phases (ordered, TDD — write the test red before
  the fix), Acceptance Criteria. Look at any recently-closed issue on
  staging for the shape.
- **Read before you write.** If you're updating an existing issue/proposal's
  body, always read the current live content first — don't assume you
  remember what it says, and never overwrite it blind.
- **Never force-push, never `--force` anything** without checking with
  gabriel first. If you hit a conflict or unexpected state, stop and ask
  rather than resolving it unilaterally.

## Getting unstuck

If a `muse` command does something surprising, check `muse <command> --help`
first — most commands document their exact JSON schema and exit codes. If
something seems genuinely broken (not just unfamiliar), that's useful
signal — file an issue describing exactly what you ran and what happened;
plenty of real bugs get found exactly that way.

Ping gabriel directly for anything blocking. Welcome to the team.