catlog22/maestro-flow

Intent-driven workflow orchestration for multi-agent AI development — adaptive lifecycle engine, self-reinforcing knowledge graph, and visual dashboard for Claude Code, Gemini, Codex & more

Maestro‑Flow – 의도 기반 다중 에이전트 워크플로우 오케스트레이션

무엇인가요 – 자연어로 "무엇을 달성하고 싶은지"를 설명하면, 자동으로 AI 에이전트 체인을 구축하고 스케줄링하며 개발 라이프사이클 전체(아이디어 → 계획 → 코드 → 테스트 → 리뷰 → 배포)를 수행하는 TypeScript/Node.js 프레임워크입니다. 여러 LLM 백엔드(Claude, Gemini, Codex, Qwen, Grok 등)와 호환되며 지속적인 지식 그래프를 유지하여 시스템이 시간이 지남에 따라 더 똑똑해집니다.

핵심 기능 (README에 기술됨)

기능	기능 설명
자기 적응형 오케스트레이션	Ralph 엔진은 의도를 40개 이상의 사전 정의된 명령 체인 중 하나로 분류하고, 각 결정 노드에서 계속 진행, 롤백, 또는 수리 루프 삽입 여부를 결정합니다. YAML 파일이 필요 없습니다.
백엔드 간 스케줄링	하나의 워크플로우 내에서 Claude, Codex, Gemini, Qwen, OpenCode, Grok 등 다양한 에이전트를 혼합 사용할 수 있으며, 4가지 협업 모드(Delegate: 비동기 위임, Team: 역할 기반 협업, Wave: 병렬 종속성, Swarm: 개미 군집 스타일 탐색)를 지원합니다.
지식 자가 강화	실행 중 발견된 패턴, 함정, 결정 사항은 자동으로 Spec 및 Knowhow 항목으로 저장됩니다. 훅 시스템을 통해 이 지식이 이후 프롬프트에 자동 주입되어 향후 실행이 더 효율적이 됩니다.
장기적 자가 수정	Odyssey 명령어는 수시간에 걸쳐 자율적인 루프를 실행하며, 수용 기준이 충족될 때까지 결과를 반복적으로 재평가하고 각 사이클마다 새로운 지식을 지속적으로 저장합니다.
정밀 검색	내장된 리터럴 검색(ripgrep 기반)과 선택적 의미적 재순위( BM25 → 임베딩)를 통해 코드 스니펫을 빠르게 찾을 수 있으며, `.gitignore`, `.maestroignore` 및 기타 보안 제한을 존중합니다.

설치 (README에서 요약된 빠른 단계)

# CLI의 전역 설치 (Node ≥22.19 필요)
npm install -g maestro-flow@0.5.82

# 인터랙티브 구성 요소 선택
maestro install

또한 최소 하나의 호스트 CLI(예: Claude Code(기본값) 또는 Grok Build)가 필요합니다. Codex CLI 및 agy CLI용 옵션 어댑터도 제공됩니다.

일반적인 워크플로우

의도를 표현하기 – 예: /maestro-ralph "OAuth2 인증 구현, refresh token 지원"
Ralph가 체인 생성 – analyze → plan → execute → verify → review → test (실패 시 자동으로 디버그/수리 루프 삽입).
세션 실행하기 – maestro session open 후 maestro run next를 반복하여 세션을 완료합니다.
지식 축적 – 발견된 패턴은 저장되며 이후 훅을 통해 주입됩니다.
장시간 실행 모드 – 대규모 리팩터링에는 /maestro-odyssey <의도> --mode <debug|planex|improve|…>를 사용하여 정의된 수용 기준이 충족될 때까지 루프를 반복합니다.

핵심 개념 및 용어

Ralph – 자연어 의도를 명령 체인으로 매핑하는 의사결정 엔진.
Odyssey – 대규모 디버깅, 보안 감사, UI 검사 등에 적합한 장시간 자율 루프.
결정 노드 – 엔진이 결과를 평가하고 다음 동작을 결정하는 체크포인트.
Spec / Knowhow – 미래 프롬프트에 자동으로 추가되는 지속 저장 지식 아티팩트.
훅 – 저장된 지식을 에이전트 프롬프트에 주입할 수 있는 17개의 사전 정의된 확장 포인트.
MCP (Model Context Protocol) – CLI와 LLM 백엔드 간 통신에 사용되는 프로토콜.

예제 명령어

# 간단한 의도 → 전체 파이프라인 (기본 품질 모드)
/maestro "사용자 프로필 페이지 추가"

# 전체 파이프라인 없이 단일 작업 직접 실행
/maestro-companion "README 철자 오류 수정"

# 리포지토리 내 리터럴 문자열 검색
maestro search "Authorization: Bearer" --exact --json

# 장시간 보안 감사 실행
/maestro-odyssey "프로젝트 전체 보안 감사" --mode security

문서 및 학습 리소스 (목록됨)

빠른 시작 가이드 – 설치 및 첫 번째 워크플로우.
Ralph 엔진 가이드 – 결정 로직, 품질 모드, 세션 처리.
명령어 참조 – 64개의 슬래시 명령어 및 35개 이상의 CLI 명령어.
지식 관리 가이드 – Specs, Knowhow 및 SQLite 지식 그래프의 작동 방식.
고급 설계 문서 – 다중 에이전트 협업, 오버레이 확장, 워크트리 병렬성, MCP 도구, 검색 시스템, MaestroGraph 아키텍처 등.

프로젝트 규모 및 기술 스택

코드 – 333개의 TypeScript 파일 (~80,000줄).
CLI – Commander.js, MCP SDK, better-sqlite3, web-tree-sitter로 구축.
대시보드 – React 19 + Zustand + Tailwind CSS, Hono/Vite로 제공.
에이전트 – 23개 정의, 45개 스킬 팩, 64개 슬래시 명령어.
템플릿 및 워크플로우 – 92개 JSON 템플릿, 115개 워크플로우 정의.

유사 도구와의 비교 (README 요약)

도구	초점	Maestro‑Flow의 강점
Superpowers	에이전트 스킬 프레임워크 (Markdown만)	전체 런타임 오케스트레이션, 백엔드 간 스케줄링, 지속적 지식 그래프
OpenSpec	Spec 기반 개발	의도 기반 자동 체인 생성, 동적 결정 노드
Trellis	다중 플랫폼 에이전트 테스트 환경	장시간 자율 루프(Odyssey) 및 자가 수정 파이프라인

유지보수자

@catlog22 (GitHub 사용자 catlog22)가 개발 및 유지보수 중입니다. 커뮤니티 토론을 위한 WeChat 그룹이 있으며, MIT 라이선스로 배포됩니다.

결론

Maestro‑Flow는 개발자가 여러 LLM 에이전트를 활용해 소프트웨어 개발 라이프사이클 전체를 자동화할 수 있는 프로덕션 수준의 의도 기반 오케스트레이션 계층이며, 각 실행에서 지속적으로 학습합니다. AI 강화 소프트웨어 엔지니어링의 최전선을 목표로 한 진정한 오픈소스 프로젝트입니다.