unstuck

Two agent skills for keeping long-running work from collapsing into tunnel vision:

Skill	Role
north-star	A delivery-point hook that re-injects the goal, structured state, and scoped failure log; it detects repeated null results and decides when to escalate.
moa	An on-demand, isolated multi-view consultation using a fresh-context native subagent plus Claudex and GLM through aligned Claude Code headless harnesses. Each route can write code and run experiments in its own disposable workspace.

north-star is the smoke detector; moa is the fire brigade. They remain separate because the detector is cheap and frequent while the consultation is expensive and evidence-driven.

How they compose

work → deliver → North Star hook re-injects vision/state/failures
                         │
                         ├─ within-frame stuck
                         │    └─ MOA project mode: isolated copies of current WIP
                         │
                         └─ frame may be wrong
                              └─ MOA prompt-only mode: empty project workspaces

independent experiments → quality gate → disagreement map → main-agent decision

The two MOA context modes solve different problems:

• project (default) lets every route inspect current WIP, edit an isolated Worktree or copy, write scripts, and run tests without touching the live project.
• prompt-only gives every route an empty writable workspace. Use it when the accumulated project state may itself encode the wrong frame. The consultation packet must also contain only the raw problem and necessary external signals.

The main agent remains the judge. MOA keeps each route's labelled evidence intact; it does not vote, pre-aggregate the answers, or enlarge the user's authorization.

MOA routes

1. A fresh-context native subagent from the current harness. Freshness must be explicit; in Codex use fork_turns: "none".
2. Claudex through Claude Code headless with gpt-5.6-sol, xhigh, no session persistence, and the Claude Code OS sandbox.
3. GLM through the same Claude Code headless contract with glm-5.2[1m] and max.

All three routes get independent writable workspaces. Headless workspaces are recycled automatically unless --keep-worktrees is requested; native workspaces are prepared and recycled explicitly by the main harness.

Install

Clone the repository and copy or link the two folders into your shared skill root:

git clone https://github.com/ele-yufo/unstuck
mkdir -p "$HOME/.agents/skills"
cp -R unstuck/moa "$HOME/.agents/skills/moa"
cp -R unstuck/north-star "$HOME/.agents/skills/north-star"

If multiple harnesses share personal skills, keep ~/.agents/skills as the shared source and link these two skills into harness-specific roots. Do not replace an entire harness skill directory if it also contains harness-exclusive skills.

Requirements

moa:

• Python 3.10+ and Git. Projects without a usable Git HEAD fall back to an isolated filtered copy.
• Claudex with a readable local proxy env file and working CLIProxyAPI transport. The configured default is gpt-5.6-sol at xhigh effort.
• Claude Code with GLM_API_KEY configured for the Zhipu Anthropic-compatible endpoint. The configured default is glm-5.2[1m] at max effort. Linux hosts also need bwrap and socat for the mandatory sandbox.
• A current harness that can create a genuinely fresh-context native subagent. If it cannot, that route must be reported unavailable.

north-star:

• jq for installation and STATUS rendering.
• A harness with a PostToolUse hook that can inject additionalContext. The bundled installer targets Claude Code's hook shape.

Common commands

# Probe local Headless adapters
python3 moa/scripts/dispatch.py --list-backends

# Default project-context consultation
printf '%s' '<decision packet>' \
  | python3 moa/scripts/dispatch.py --project "$(pwd)"

# Frame-reset consultation: no project files are supplied to advisors
printf '%s' '<raw problem + external signals>' \
  | python3 moa/scripts/dispatch.py --project "$(pwd)" --context-mode prompt-only

# Prepare the matching native-subagent workspace
python3 moa/scripts/dispatch.py --project "$(pwd)" \
  --context-mode prompt-only --prepare-native-workspace

# Inspect or recycle retained workspaces
python3 moa/scripts/dispatch.py --list-worktrees
python3 moa/scripts/dispatch.py --cleanup-worktrees <id>

See moa/SKILL.md for the full dispatch contract and north-star/references/mechanism.md for the escalation decision.

Why the frame-reset mode exists

North Star is deliberately an anchor: at each delivery it puts the goal, state, and failed attempts back into context. That is useful when execution is drifting inside a sound frame. It becomes dangerous when the frame itself is wrong, because the same files can turn accumulated reasoning into a self-reinforcing story.

For that case, prompt-only removes both sources of anchoring:

• the packet omits STATUS, failed attempts, and the current hypothesis;
• the advisors receive empty project workspaces, so they cannot read the same state back from disk.

The failure mode that motivated this split is documented in north-star/CASE_STUDY_nemotron.md. The successful within-frame use case is in north-star/CASE_STUDY_earthquake.md.

Design boundaries

• More routes are not stronger evidence. A well-supported minority opinion can beat a shallow majority.
• Worktree experiments are evidence and candidate patches, not automatic changes to the live project.
• A failed or unavailable route is labelled and preserved; it does not erase successful routes.
• External model services can still receive the consultation packet or project files visible in their isolated workspace. Do not use project mode for sensitive material that must not leave the machine.
• MOA improves judgment but does not grant implementation, publishing, submission, or messaging authority that the original request did not grant.

中文概述

这套仓库包含两个联动 skill：

• north-star 在长周期项目的每次交付点重新注入目标、状态和失败清单，发现连续无进展时触发升级。
• moa 调用当前 harness 的空上下文原生 Subagent，以及 Claude Code Harness 下的 Claudex 与 GLM；三路各自在独立可写工作区中写代码、跑脚本、做实验，再由主 Agent 按证据做分歧地图。

MOA 默认的 project 模式包含当前 WIP，适合检查实现；prompt-only 模式提供空项目工作区，适合 NorthStar 判断“框架本身可能错”的换框会诊。后者不仅不能把 STATUS/FAILED_ATTEMPTS 写进 prompt，也不能让顾问从仓库里重新读回这些内容。

License

MIT © 2026 ele-yufo (欧稽里得)