Keep every developer's AI aligned on one project direction.
v0.7 — Team conventions delegated to project-brief.md. No more hardcoded workflow rules.
The concept of an AI "harness" — structured markdown files that guide LLM coding agents — has become a foundational pattern in AI-assisted development. Frameworks like BMAD, gstack, and GSD pioneered this approach for solo developers.
Musher Engineering takes harness engineering to the next level. Built by AIDD-Projects, it evolves the harness concept from a 1-person tool into an enterprise-grade direction management framework for multi-developer teams.
| Traditional Harness | Musher Engineering | |
|---|---|---|
| Target | Solo developer | Multi-developer teams |
| Focus | What the AI does | Where the AI is going |
| Direction management | ❌ | ✅ Direction Guard + pivot + Decision Log |
| Team state sharing | ❌ | ✅ Shared/personal state separation |
| Token budget | 200+ files | ~25 files (~17K tokens) — works with small LLMs too |
When one developer uses an AI coding assistant, direction stays consistent. But in enterprise teams, each developer runs their own AI sessions — and each AI drifts independently. Developer A's AI refactors toward microservices while Developer B's AI doubles down on the monolith. Without shared direction management, AI agents across multiple developers pull the project apart.
Musher Engineering solves this. It gives every developer's AI the same goals, non-goals, decisions, and project state — so all AI sessions converge on one direction, regardless of who's coding or which IDE they use.
Musher manages your project's direction — goals, decisions, scope — so LLM coding agents stay aligned across developers and sessions. Zero dependencies, 6 IDE support, native format generation.
- Direction Guard — Every coding request is checked against project goals/non-goals before execution
- State Files — 5 markdown files that persist project knowledge across LLM sessions
- Skills — Step-by-step procedures for planning, review, debugging, and direction changes
- Agents — Role-based personas that enforce the workflow (planner, reviewer, sprint-manager)
- Failure Patterns — Project-specific failure log that prevents repeat mistakes
- Decision Log — Records why decisions were made so LLMs don't re-debate settled choices
# Solo mode (default)
npx musher-engineering init
# Team mode (multi-developer)
npx musher-engineering init --teamSelect your IDE when prompted. Files are installed into the current directory.
After installation, ask your LLM to run the bootstrap skill:
"Run bootstrap to onboard this project."
This scans your codebase and fills all 5 state files automatically.
npx musher-engineering init --ide vscode
npx musher-engineering init --ide claude
npx musher-engineering init --ide cursor
npx musher-engineering init --ide codex
npx musher-engineering init --ide windsurf
npx musher-engineering init --ide antigravity| Flag | Description |
|---|---|
--ide <name> |
Target IDE: vscode, claude, cursor, codex, windsurf, antigravity |
--mode <mode> |
Project mode: solo (default) or team |
--dir <path> |
Target directory (default: current directory) |
--team |
Shorthand for --mode team |
--batch |
Non-interactive mode (requires --ide; defaults to solo mode) |
--overwrite |
Overwrite existing files (including state files) |
--version |
Show version number |
# Verify Musher files are installed
npx musher-engineering doctor
# Verify state files have real content (not just placeholders)
npx musher-engineering validate| IDE | Dispatcher (always-on) | Skills | Agents |
|---|---|---|---|
| VS Code Copilot | .github/copilot-instructions.md |
.github/skills/*/SKILL.md |
.github/agents/*.agent.md |
| Claude Code | .claude/rules/core.md |
.claude/skills/*/SKILL.md |
.claude/agents/*.md |
| Cursor | .cursor/rules/core.mdc |
.cursor/skills/*/SKILL.md |
.cursor/agents/*.md |
| Codex | AGENTS.md |
.agents/skills/*/SKILL.md |
.codex/agents/*.toml |
| Windsurf | .windsurf/rules/core.md |
.windsurf/skills/*/SKILL.md |
(agents installed as skills) |
| Antigravity | GEMINI.md |
.gemini/skills/*/SKILL.md |
.gemini/agents/*.md |
All IDEs also get state files (project-state.md, project-brief.md, features.md, failure-patterns.md, dependency-map.md) in the docs/ directory.
- Core Rules — 42-line dispatcher: session start guidance, workflow references, state file list, and Iron Laws. Detailed rules are embedded in each skill/agent that enforces them.
- bootstrap — Onboard project into Musher: scans codebase + fills state files automatically
- learn — End-of-session wrap-up: captures failure patterns, updates project state, detects direction drift
- pivot — Propagate direction changes across all state files when goals/tech/scope changes
- test-integrity — Verify mock/interface synchronization before committing
- security-checklist — Pre-commit security risk scan
- investigate — 4-phase systematic debugging (evidence → scope → fix → verify)
- impact-analysis — Assess change blast radius before modifying shared modules
- feature-breakdown — Decompose features into dependency-ordered implementation tasks
- code-review-pr — Review incoming Pull Requests for quality, security, and direction alignment
- deployment — Pre-deployment validation checklist (tests, state files, security, versioning)
- planner — Feature planning, dependency analysis, Direction Alignment (goal/non-goal/decision check)
- reviewer — Code review + State File Audit (verifies state files were actually updated)
- sprint-manager — Sprint/Story state management, scope drift prevention, Next Step Recommendation
- architect — Design review gate: validates structural changes against project direction and module boundaries
- project-brief.md — Project vision, goals, non-goals, Decision Log (the "why")
- project-state.md — Current sprint, stories, and progress tracking (the "where")
- features.md — Living feature registry so LLMs know what exists (the "what")
- dependency-map.md — Module dependency graph for impact analysis (the "how")
- failure-patterns.md — Project-specific failure patterns that prevent repeat mistakes (the "watch out")
After musher init, run the bootstrap skill. It scans your codebase, interviews you about goals/non-goals, and fills all 5 state files automatically. This is the most important step — without it, Direction Guard and other skills have no context.
Before ANY coding task, the LLM reads project-brief.md and checks:
- Does this align with Goals? → proceed
- Does this fall under Non-Goals? → warn, suggest
pivot - Does this contradict a Decision Log entry? → warn, suggest
pivot
bootstrap → planner → [code] → reviewer → sprint-manager → learn
- planner: Checks direction alignment, breaks down features
- reviewer: Reviews code + audits state file updates
- sprint-manager: Tracks progress, recommends next action
- learn: Captures lessons before session ends
When goals, technology, or scope changes, run the pivot skill:
- Updates ALL 5 state files consistently
- Records the decision with reasoning in Decision Log
- Prevents silent inconsistencies across files
This is where Musher Engineering shines. When multiple developers each run their own AI sessions, direction divergence is inevitable — unless you have shared guardrails.
npx musher-engineering init --team| Solo Mode | Team Mode | |
|---|---|---|
| Shared State | docs/ (git tracked) |
docs/ (git tracked): project-brief, features, dependency-map |
| Personal State | docs/ (git tracked) |
.harness/ (gitignored): project-state, failure-patterns |
| Agent Memory | docs/agent-memory/ |
.harness/agent-memory/ |
| Target | Solo developer | Enterprise team |
| Team Rules | — | Pre-Pull, Owner, Read-Only, Append-Only, Pivot Lock, FP Promotion |
How it keeps everyone aligned:
- Shared state (
project-brief.md,features.md,dependency-map.md) is git-tracked — every developer's AI reads the same goals, non-goals, and decisions - Personal state (
project-state.md,failure-patterns.md) goes to.harness/(gitignored) — each developer tracks their own sprint progress without conflicts - Pre-Pull Protocol — Before every session, AI pulls latest shared state so no one works on stale direction
- Pivot Lock — Direction changes require the
pivotskill, which updates ALL state files atomically and records the decision with reasoning - FP Promotion — Local failure patterns get promoted to shared
failure-patterns.mdso the whole team learns from each developer's mistakes - Owner Tracking — Dependency map marks module owners to prevent accidental cross-team overwrites
These 8 rules are enforced across all skills and agents. They form the quality backbone of every Musher-managed project.
| # | Law | Enforced By |
|---|---|---|
| 1 | Mock Sync — Interface change → update mocks in the same commit | reviewer, test-integrity |
| 2 | Type Check — Read the source before calling constructors. Never trust memory. | reviewer |
| 3 | Scope Compliance — Stay within current Story scope. Report before modifying out-of-scope files. | sprint-manager, reviewer |
| 4 | Security — No credentials, passwords, or API keys in code or commits. | security-checklist, reviewer |
| 5 | 3-Failure Stop — Same approach fails 3 times → stop and report. | All agents |
| 6 | Dependency Map — New/modified module → update dependency-map.md in the same commit. |
reviewer, learn |
| 7 | Feature Registry — New feature → register in features.md in the same commit. |
reviewer, learn |
| 8 | Session Handoff — Session end → update project-state.md Quick Summary. |
learn |
See docs/reference.md for detailed descriptions of every skill, agent, rule, and state file.
Existing AI coding frameworks focus on what the AI does (generate code, run tests, deploy). Musher focuses on where the AI is going — ensuring every developer's AI moves in the same direction. This is the difference between a dog sled where each dog runs wherever it wants, and one where a musher keeps the whole team on course.
| BMAD v6.2.2 | gstack v0.15.1 | GSD v1.33.0 | Musher | |
|---|---|---|---|---|
| Focus | Enterprise SDLC methodology | 1-person software factory | Full lifecycle automation | Multi-developer direction alignment |
| Files | 200+ | ~40 | Hundreds | ~25 |
| Dependencies | Node 20+ | Bun + Node + Playwright | Node 18+ | Zero |
| IDE support | 20+ (installer) | 5 (setup --host) | 13 (runtime select) | 6 (native format) |
| Direction management | ❌ | ❌ | ❌ | ✅ (Direction Guard + pivot + Decision Log) |
| Iron Laws (code quality rules) | ❌ | ❌ | ❌ | ✅ (8 laws embedded in skills) |
| Cold start | ❌ | ❌ | /gsd-new-project |
✅ (bootstrap skill) |
| Context per task | 4-6 files | 1 file | Fresh 200k per plan | 2-3 files (42-line dispatcher) |
Musher is at v0.7.2 — the framework is feature-complete. Next priority is real-world validation.
| Phase | Version | Status | Focus |
|---|---|---|---|
| Foundation | v0.5.0 | ✅ Done | Core framework: 6 IDE support, 8 skills, 3 agents, Team Mode, Direction Guard |
| Hardening | v0.6.5 | ✅ Done | 10 skills, 4 agents, Iron Laws, CLI batch/doctor/validate, merge conflict SOP, direction drift detection |
| Flexibility | v0.7.x | ✅ Current | Delegate team conventions to project-brief.md, remove prescriptive rules, opt-in personal context (.harness/my-context.md) |
| Validation | — | 🔜 Next | Real-world project adoption, user feedback collection, case studies, pain point discovery |
- Adopt Musher in real projects and collect usage data
- Document case studies: solo vs team, small vs large projects
- Gather user feedback on friction points and missing features
- Iterate based on real-world evidence, not assumptions
Musher is in active development and we'd love your input.
- Bug reports & feature requests → GitHub Issues
- Discussions & ideas → GitHub Discussions
- Try it on your project →
npx musher-engineering initand tell us what works (or doesn't)
We're especially interested in:
- How Direction Guard performs in teams of 3+ developers
- Whether the 6 Team Rules (Pre-Pull, Owner, Read-Only, etc.) are sufficient or need more
- Which IDE integrations need improvement
- What skills or agents are missing for your workflow
MIT