🐮 Moo Tasks

AI 코딩 에이전트(Claude Code, Cursor, Windsurf, Antigravity, Copilot)와 인간이 참여하는 페어 프로그래밍(human-in-the-loop pair programming)을 위해 구축된 에이전틱 태스크 오케스트레이션 및 관리 엔진(Agentic Task Orchestration & Management Engine)입니다.

빠른 시작 • 에이전트 및 MCP 설정 • 에이전트 프로토콜 • 아키텍처 • MCP 도구

🌟 왜 Moo Tasks인가?

일반적인 AI 코딩 에이전트는 종종 다음과 같은 문제를 겪습니다:

1. 범위 이탈(Scope Drift): 원래 사용자 의도에서 벗어나 가치가 낮은 리팩토링을 끝없이 수행합니다.

2. 과잉 계획(Over-Planning): 실제로 실행하지도 않으면서 얕은 작업 40개를 생성합니다.

3. 반복 / 헤매기(Looping / Thrashing): 실패가 반복되는 수정을 중단하지 않고 계속 시도합니다.

4. 검증 불가한 작업(Unverifiable Work): 테스트를 실행하거나 증거를 만들지 않고도 코드가 완성됐다고 주장합니다.

5. 결정 재논쟁(Re-Debating Decisions): 컨텍스트가 초기화될 때마다 이미 확정된 아키텍처 선택을 다시 논쟁합니다.

Moo Tasks는 WAL 모드의 로컬 SQLite 엔진, 풍부한 실시간 웹 UI, 그리고 런타임에서 엄격한 엔터프라이즈 불변식(invariant)을 강제하는 Model Context Protocol(MCP) 서버를 제공하여 이러한 문제를 해결합니다.

Related MCP server: pith

✨ 핵심 기능 및 기능 매트릭스

🎯 1. 목표 및 범위 제어

• 사용자 프롬프트 원문 보존(Verbatim Human Prompts): 작업 위에 위치하며 원래 사용자 요청의 정확한 원문을 보존합니다.

• 목표 범위 및 누락 사항 추적(Goal Coverage & Loose Ends): 작업 완료율과 남아 있는 미해결 작업 수에 대한 실시간 지표를 제공합니다.

• 범위 이탈 감지(Scope Drift Detection): 연결된 목표가 없는 고아 작업(orphan task)를 자동으로 식별하고 플래그로 표시합니다.

• 목표별 open 작업 상한(Goal Open Caps): 목표별 최대 open 작업 수를 하드 제한(기본값: 10)으로 적용하여 에이전트가 과잉 계획을 세우지 못하게 합니다.

• 캐스케이드 연산(Cascade Operations): 목표 아래의 모든 작업을 필수 사유와 함께 원자적으로 삭제, 중단 또는 재오픈합니다.

📋 2. 작업 수명주기 및 DAG 의존성

• 하위 작업 중첩 제약(Subtask Nesting Constraint): 상위 작업 아래에는 정확히 1단계의 하위 작업만 허용됩니다.

• 유한 상태 머신(Finite State Machine): todo, doing, blocked-on-dependency, waiting-on-human, done, dropped.

• DAG 의존성 그래프(DAG Dependency Graph): 사이클을 자동 감지하고 하위 작업을 자동으로 차단 해제합니다.

• 상위 작업 닫기 보호(Parent Closure Guard): 하위 작업이 남아 있는 한 상위 작업을 닫지 못하게 보호합니다.

• 상태 취소 및 이력(Status Undo & History): 전환 감사 이력의 전체 기록을 활용해 잘못된 상태 전환을 롤백할 수 있습니다.

🛡️ 3. 완료, 검증 및 작업 증명

• 수용 조건(Acceptance Criteria): 작업을 시작하기 전에 반드시 Markdown으로 작성해야 하는 조건입니다.

• 증거 요구사항(Evidence Requirement): 작업을 닫으려면 검증 가능한 증거(실행한 명령, stdout 출력, 테스트 증명)가 필요합니다.

• 2단계 검증(Two-Phase Verification): 에이전트의 상태인 agent_completeditem을 인간의 verified_done 상태와 구분합니다.

• 사유 포함 거부(Rejection with Reason): 인간이나 동료 에이전트 가 피드백과 함께 완료 작업을 거부할 수 있으며, 작업은 todo로 되돌아가고 재오픈 카운터가 증가합니다.

🙋 4. 인간 협업 및 블로킹

• 인간 대기 큐(Waiting-on-Human Queue): 에이전트는 질문(예: clarification, approval, credential, decision)을 첨부하여 블로커를 일시 중지합니다.

• 반응형 재개(Reactive Resume): 웹 UI 또는 MCP를 통해 질문에 답하면 에이전트를 다시 시작하지 않고도 작업이 자동으로 준비 큐로 되돌아갑니다.

• 전용 인간 인박(Dedicated Human Inbox): 인간이 처리해야 할 모든 사항을 실시간으로 보여주는 큐지입니다.

🔍 5. 발견된 작업(Discovered Work)

• 작업의 중간 캐시 (Mid-Task Work Capture)**: 진행 중인 작업 클레임을 포기하지 않고 작업 중 발견한 새 작업을 캡처합니다.

• 즉시 수정 vs 보류(Must-Fix vs Deferred): must-fix-now(차단 작업으로 삽입) 또는 deferred(백로그)로 표시합니다.

🤖 6. 소유권, 동시성 및 임대(Leases)

• 작업 독점 클레임(Exclusive Changes): 내청이 발견된 상세트 유무 시 자동으로 임대(객체)가 만료됨 (default 5 minutes) — should be lease by timeout: "에이전트가 조용해지면 자동으로 타임아웃되는 리스(기본값 5분)을 사용합니다."

• Heartbeat 메커니즘: 장시간 실행되는 작업 중에도 임대를 연장할 수 있습니다.

• 에이전트 동시성 한도(Agent Concurrency Limits): 에이전트가 동시에 보유하는 작업 수를 제한합니다(기본값: 1).

• 파일 터치 충돌 경고(File Touch Conflict Warnings): 선언된 파일이 다른 active claims의 일부와 충돌하는지 확인합니다.

🔄 7. 정지 유도 및 반복(Stall & Thrash) 감지

• 시도 카운터: 각 클레임/시도마다 증가.

• 자동 상위 단계로 이동(Auto-Escalation): $N$번 반복(기본값 3/3) 후 무작위 반복 대신 작업을 waiting-on-human 상태로 자동으로 일시정지합니다.

• 상태 시간 추적(Time-in-State Tracking): doing 상태에서 소요된 시간을 감사하고 반복적으로 재오픈하는 것을 감지합니다.

🏛️ 8. 확정된 아키텍처 결정(ADR)

• 프로젝트 수준 기록(Project-Level Record)**: 개별 작업보다 오래 살아남아야 하는 선택과 그 이성을 보존합니다.

• 사전 계획 협의(Pre-Planning Consultation): 에이전트는 계획을 세우기 전에 이 확정된 결정을 먼저 읽습니다.

• 대체 결정 지원(Supersede Support): 대체된 결정을 필수 사유를 입력하여 깔끔하게 갱신하고 연결합니다.

🚀 빠른 시작 및 설치

옵션 A: 전역 설치( moo 명령어 사용 시 권장)

moo-tasks를 전역 실행해 어디서든지 간결한 moo 명령을 사용하세요:

npm install -g moo-tasks
# or: pnpm add -g moo-tasks | bun add -g moo-tasks

설치가 완료되면 moo 명령을 바로 사용할 수 있습니다:

moo init       # Initialize .moo workspace in current project
moo start      # Launch real-time Web UI (http://127.0.0.1:4242)
moo ws         # List registered global workspaces
moo status     # Show Where-Did-I-Leave-Off context
moo search     # Full-text SQLite search

대안 설명 moo vs npx:

• moo(인자 포함) 명령없이 설치하기 npm install -g moo-tasks로 전역 설치하여 사용 가능합니다.

• 전역 설치가 없다면 npx moo-tasks <command>로 실행합니다(npm 레지스트리의 moo는 별도 패키지이므로 npx moo` _NOT_사용하지 않는게 좋습니다).

• 전역 설치 실행 후 moo: command not found 오류가 발생하면 npm 전역 bin 디렉터리가 $PATH에 있는지 확인하세요.

export PATH="$(npm prefix -g)/bin:$PATH"

옵션 B: npx moo-tasks 로 온디맨드 실행

전역 설치 없이 직접 실행하는 방법입니다:

1. 작업 영역 및 에이전트 프로토콜 초기화

프로젝트 루트에서 실제 실행합니다:

npx moo-tasks init

이렇게 하면:

• .moo/tasks.db SQLite 데이터베이스를 WAL 모드로 초기화합니다.

• AGENTS.md, CLAUDE.md, .windsurf rules 및 .windsurfrules를 생성합니다.

2. 로컬 웹 UI 실행

npx moo-tasks start

브라우저에서 **http://127.0.0.1:4242**를 엽니다.

LAN(같은 네트워크)에서 다른 기기 또는 태블릿으로 웹 UI에 접근하는 경우:

npx moo-tasks start --lan
# Automatically logs: http://192.168.x.x:4242/

🔌 에이전트 & MCP 설정

원스텝 멀티 에이전트 설치

# Configure all detected agent IDEs at once:
npx moo-tasks install all

# Or configure specific clients:
npx moo-tasks install claude       # Updates ~/.claude.json
npx moo-tasks install cursor       # Generates .cursor/mcp.json
npx moo-tasks install windsurf     # Updates ~/.codeium/windsurf/mcp_config.json
npx moo-tasks install antigravity  # Generates .gemini/settings.json

수동 설정

{
  "mcpServers": {
    "moo-tasks": {
      "command": "npx",
      "args": ["moo-tasks", "mcp"]
    }
  }
}

🤖 필수 에이전트 프로토콜

모든 AI 코딩 에이전트는 6단계 주기를 따르도록 지시됩니다:

1. SESSION RESUME  → Call moo_session_resume() & moo_list_decisions()
2. ANCHOR GOAL     → Call moo_create_goal(title, verbatimPrompt)
3. PLAN & CRITERIA → Call moo_create_task() with markdown criteria BEFORE code
4. EXCLUSIVE CLAIM → Call moo_claim_task(taskId, agentId, sessionId)
5. IMPLEMENTATION  → If blocked, call moo_ask_human() or link blockers
6. VERIFIED PROOF  → Call moo_complete_task() with test proof & output snippet
7. ADR RECORD      → Call moo_record_decision() for architectural choices

🛠️ MCP 도구 참조

🏛️ 아키텍처 및 클린 코드

src/
├── domain/                    # Pure Enterprise Domain Rules & Invariants
│   ├── types.ts              # Domain interfaces & value types
│   ├── errors.ts             # Domain-specific typed error classes
│   ├── dependency.ts         # DAG cycle detector & unblocked evaluator
│   ├── conflict.ts           # File touch overlap conflict detector
│   └── similarity.ts         # Duplicate task similarity detector
│
├── infrastructure/            # Persistence & External Integrations
│   ├── db/database.ts        # SQLite manager (WAL mode, busy timeout)
│   ├── db/migrations.ts      # Schema DDL and versioning
│   ├── git/git-context.ts    # Git branch, commit, dirty status extractor
│   └── repositories/         # SQLite Repository Implementations
│
├── services/                  # Application Services (Use Cases)
│   ├── goal-service.ts        # Goal lifecycle & cap enforcement
│   ├── task-lifecycle-service.ts # State machine, ready queue, undo
│   ├── claim-service.ts       # Exclusive claims, leases, dead-agent timeout
│   ├── verification-service.ts# Proof of work & two-phase verification
│   ├── human-collab-service.ts# Human Q&A queue & reactive resume
│   ├── discovered-work-service.ts # Mid-flight discovered work
│   ├── decision-service.ts    # ADR logs & supersede linking
│   ├── duplicate-merge-service.ts # Idempotency & task merging
│   ├── session-service.ts     # Where-did-I-leave-off session resume
│   ├── housekeeping-service.ts# Archiving & multi-format export
│   └── index.ts               # Dependency Injection Container
│
├── mcp/                       # Model Context Protocol Stdio Server
├── server/                    # Fastify HTTP + Server-Sent Events (SSE) Engine
├── cli/                       # CLI Commands (start, init, install, mcp)
└── ui/                        # Vanilla JS + Tailwind + Lucide Icons Web UI

🤝 기여

기여를 환영합니다! 개발 설정, 테스트 및 PR 지침은 CONTRIBUTING.md를 확인해 주세요.

📄 라이선스

이 프로젝트는 MIT 라이선스에 따라 라이선스가 부여됩니다.