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:

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:

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

# 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:

  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:

  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.