mac-shell-mcp: Instructions file for Claude Code

CLAUDE.md

PM Conductor — operating rules

This repo is managed by the pm plugin. The conductor sits ABOVE OpenSpec and Superpowers. Epics are lane-agnostic (openspec | superpowers | claude-code | decision | external); OpenSpec is one lane. Stories come from each epic's source (OpenSpec tasks.md, a Superpowers plan, or a manual list). Follow these rules:

1. Detours — when something blocks the active epic, CLASSIFY before fixing:
   • Minimal (small, self-contained, no design ambiguity): fix → test → commit → push, then run /pm:detour --minimal "<what>" so it is recorded in .conductor/detours.log. Then resume.
   • Substantial (own design / changes shared behavior / multi-step): run /pm:detour. It becomes its own epic in the appropriate lane (OpenSpec proposal, Superpowers plan, etc.). Register that epic FIRST, then PUSH the current one onto the detour stack with push-detour <parent> --detour <new-id> --reason "<why>" (--reconcile | --no-reconcile). NEVER hand-edit .conductor/state.json to push or pop a frame. The verb IS the transition, and it is what supplies the validation, the write-conflict guard, the read-back verification and the Honcho line a hand-edit has none of. Exactly one of the two reconcile flags is REQUIRED and there is no default: whether the detour can invalidate the paused epic's plan is a judgment, and a default makes an absent decision look like a considered one. Say --reconcile unless you are certain the detour touches nothing the paused epic depends on.
2. State of record is .conductor/state.json. After any change to epics, status, priority, or the detour stack, re-render with /pm:status. Never hand-edit PROJECT.md.
3. Resuming after a detour — use /pm:resume, which pops the frame with pop-detour [<paused-id>] — again a verb, never a hand-edit. It removes the frame, resumes the epic and writes reconcileNeeded in the SAME write, which is what makes the obligation survive the frame's removal. If the popped frame had reconcileOnResume, run the reconcile gate (reconciler agent) BEFORE writing code, then write its verdict back durably with record-reconcile <id> --detour <detourId> --verdict valid|invalidated --amendments none (the reconciler's AMENDMENTS: none), or one --amendment "<line>" per other AMENDMENTS line — this attaches {verdict, amendments, reconciledAt} to the paused epic's link to that detour, instead of the judgment only ever living in conversation. It is accepted only for a detour pushed --reconcile and already popped, and reconcileNeeded clears only when no such detour is left unanswered; pop-detour names every detour owed. A BASH WRITE IS A WRITE TOO: a heredoc redirection, an in-place sed, a tee, a copier or anything else that puts bytes in a file is forbidden while the reconcile is owed, exactly as Edit is. The PreToolUse guard mechanically blocks a closed list of those shapes, and that list is incomplete BY CONSTRUCTION — a path built from a variable, an eval, a script invoked by name, an interpreter given inline source all pass it. Passing the check is not permission; this line is the obligation and the check is only its backstop.
4. Honcho — on every PUSH and POP, also write a one-line memory to Honcho ("paused X for Y" / "resumed X, reconciled vs Y") so the relationship survives outside this repo. push-detour prints the PUSH line for you and logs it to .conductor/honcho-memories.log; paste it into your Honcho tool call. pop-detour prints the POP line only when nothing needs reconciling — with a gate armed, "reconciled vs Y" is not yet true, so emit it with honcho-memory pop <id> "<detour>; reconcile = …" after the verdict. The engine formats and logs; it never calls Honcho itself.
5. Keep tasks.md checkboxes truthful — they are the source of truth for story progress.
6. Roadmap as backlog — work you intend to do but haven't proposed yet can be registered now with /pm:epic add … --status planned (any lane). Planned epics show as ordered backlog in PROJECT.md and a planned: N count in the briefing, without a "no change on disk" warning; /pm:sync flips an openspec planned epic to untriaged once its change is proposed. Have a roadmap doc? Read it in-session and load each item this way.
7. Delegate discovery. If you do not already know the file path, do not go looking yourself. A subagent's transcript never enters yours — only its final report does — so an open-ended read costs a conclusion instead of a transcript when it is delegated. "Where is X handled", "does a spec for this already exist", "what does this epic touch", "what did the last three changes here do": dispatch an Explore or general-purpose subagent and use what it concludes. Reserve an INLINE read for the narrow case where you already know the exact file and want one value out of it. This binds the ORCHESTRATING agent, which is the half that has no such rule: a dispatched child is already told to return a fixed report and not to narrate. It binds hardest across a hierarchy run or a multi-epic backlog, where your context survives many epics and is therefore the scarce resource — discovery you perform inline is paid for once per epic and never reclaimed. DELEGATING NEVER WEAKENS A FULL-READ REQUIREMENT. Where this instruction demands the whole document — the epic-level-autonomy preflight scan, and re-reading an epic's source before it becomes the work — the subagent reads the whole document and returns the finding. What is forbidden is substituting a keyword grep for a full read, and that is forbidden whoever performs it.