feature-orchestrator-agent

Full-stack Feature orchestration specialist. Used for complete Feature creation from backend to frontend

항목	내용
Invoke	/feature:create
Aliases	/feature:full, /feature:orchestrate
Tools	Read, Edit, Write, Bash, Glob, Grep
Model	inherit
Skills	feature

/feature:create — 기능 하나를 처음부터 끝까지 만드는 총감독#

한마디로#

새 기능 하나를 서버(백엔드)부터 화면(프론트엔드)까지 한 번에 통째로 만들어주는 "현장 총감독" 입니다. 집 한 채를 지을 때 기초 공사·골조·인테리어를 각 전문 팀에 순서대로 맡기고 마지막에 직접 살아보며 점검하는 현장소장 역할이라고 보면 됩니다.

누가·언제 쓰나요#

새로운 기능(예: 게시판, 알림, 결제 내역 등)을 데이터 저장부터 사용자 화면까지 전부 새로 만들어야 할 때
백엔드 따로, 프론트엔드 따로 만들지 않고 한 번에 일관되게 만들고 싶을 때
/feature:create 명령을 실행하면 이 총감독이 깨어나 작업을 시작합니다.

무엇을 해주나요#

기능 이름과 핵심 데이터 이름만 알려주면, 아래 결과물이 올바른 위치에 자동으로 만들어집니다.

서버 쪽: 데이터 모델 파일(*.spy.yaml), 통신 창구({feature}_endpoint.dart), 처리 로직({feature}_service.dart), DB 변경분(마이그레이션)
앱 쪽: 업무 규칙(domain), 데이터 연결(data), 화면·상태관리(presentation), 연결 설정(di/injection.dart)
마지막에는 실제 서버를 띄워 앱과 서버가 진짜로 잘 맞물려 동작하는지까지 직접 확인해 줍니다.

어떻게 쓰나요#

# 기본 형태 (느낌상): 기능 이름과 데이터 이름을 지정
/feature:create   # 실행하면 feature_name, entity_name 등을 물어봅니다

# 같은 명령의 다른 이름(별칭)으로도 실행 가능
/feature:full
/feature:orchestrate

지정할 수 있는 값들:

feature_name (필수) — 기능 모듈 이름 (예: order_history)
entity_name (필수) — 핵심 데이터 이름 (예: OrderHistory)
location (선택) — 어디에 둘지: application / common / console (기본 application)
caching (선택) — 데이터 캐싱 방식: swr / cache-first / none (기본 swr)
endpoint_type (선택) — 통신 창구 종류: app / console / both (기본 app)

위 옵션과 값들은 모두 문서에 정의된 실제 항목입니다.

안에서 무슨 일이 벌어지나요#

총감독은 다음 순서로 일을 진행합니다.

사전 점검(Preflight) — 작업에 필요한 도구(MCP)가 깔려 있는지 확인하고, 없으면 자동으로 설치·등록합니다. 여기서 막히면 멈추고 사용자에게 보고합니다.
기존 기능 확인 — 같은 이름의 기능이 이미 있으면 "수정할지 / 건너뛸지 / 새로 만들지" 물어봅니다.
요구사항 정리 & 계획 수립 — 무엇을 만들지 대화로 확인하고 할 일 목록을 만듭니다.
서버(백엔드) 만들기 — 데이터 모델 → 통신 창구 → 코드 생성 → DB 변경 순으로 진행합니다.
앱(프론트엔드) 만들기 — 업무 규칙 → 데이터 연결 → 화면 순으로 만듭니다.
디자인 적용 & 실제 동작 구현 — 필요하면 Figma 스타일을 입히고 실제 동작을 채웁니다.
연결 & 검증 — 설정을 연결하고, 코드 분석·테스트를 돌린 뒤, 실제 서버를 띄워(serverpod start) 앱과 서버가 진짜로 맞물리는지 통합 검증합니다. 문제가 생기면 서버 로그를 보고 고친 뒤 다시 돌립니다.

⚙️ 상세 옵션·실행 명세 (개발자 / AI 에이전트용)

Role#

Orchestrates complete Feature creation from Serverpod backend to Flutter frontend.

Activation Conditions#

/feature:create Activated when command is invoked

Parameters#

Parameter	Required	Description
`feature_name`	✅	Feature module name (snake_case)
`entity_name`	✅	Entity name (PascalCase)
`location`	❌	`application`, `common`, `console` (default: `application`)
`caching`	❌	`swr`, `cache-first`, `none` (default: `swr`)
`endpoint_type`	❌	`app`, `console`, `both` (default: `app`)

Execution Flow Summary#

Phase 0: Preflight (MCP  &   환경 점검)
    ↓ - marionette_mcp 실행 파일 확인
    ↓ - 미설치 시 `fvm dart pub global activate marionette_mcp` 자동 실행
    ↓ - `claude mcp list`로 연결 상태 확인, 실패 시 절대 경로로 재등록
    ↓ - Cursor/Zed 설정(`~/.cursor/mcp.json`, `~/.config/zed/settings.json`) 동기화
    ↓ (실패 시 중단 후 사용자에게 보고)
Phase 0.5: Check existing Feature
    ↓ (Select update/skip/regenerate)
Phase 1: Requirements gathering (Interactive)
    ↓
Phase 2: Plan creation (TodoWrite)
    ↓
Phase 3: Backend implementation
  - Step 1: /serverpod:model 호출
  - Step 2: /serverpod:endpoint 호출
  - Step 3: backend:pod:generate
  - Step 4: 마이그레이션
    ↓
Phase 4: Frontend implementation
  - Step 5: /feature:domain 호출
  - Step 6: /feature:data 호출
  - Step 7: /feature:presentation 호출
    ↓
Phase 4.5: Figma style application (conditional)
    ↓
Phase 4.7: Actual behavior implementation
    ↓
Phase 5: Integration and verification
  - DI 등록, Route 등록
  - 코드 생성, 분석, 테스트
  - 로컬 풀스택 통합 검증 ⭐ (serverpod start: server+내장 Postgres+app)
    · 로컬 백엔드 대상 통합 (backend: dart test -t integration / front: 로컬 백엔드)
    · 백엔드 변경 시 마이그레이션/로그는 Serverpod MCP, 폴백(3.x): docker compose + dart run

Command Invocation Order#

Step	Command	Generated Content
1	`/serverpod:model`	Entity, DTO, Enum
2	`/serverpod:endpoint`	Endpoint, Service
3	`backend:pod:generate`	Code generation
4	`backend:pod:*-migration`	DB Migration
5	`/feature:domain`	Entity, Repository I/F, UseCase
6	`/feature:data`	Repository Implementation, Mixin, Cache
7	`/feature:presentation`	BLoC, Page, Widget, Route

Generated Files Summary#

backend/kobic_server/lib/src/feature/{feature}/
├── model/entities/*.spy.yaml
├── model/dto/*.spy.yaml
├── endpoint/{feature}_endpoint.dart
└── service/{feature}_service.dart

feature/{location}/{feature}/lib/src/
├── domain/ (entity, repository, usecase)
├── data/ (repository, mixin, cache, local)
├── presentation/ (bloc, page, widget, route)
└── di/injection.dart

Success Criteria#

✅ All files generated in correct locations
✅ melos run analyze No errors
✅ melos run test --scope={feature} Passes
✅ DI Registration complete
✅ Route Registration complete
✅ 로컬 풀스택(serverpod start: server+내장 Postgres+app) 기동 및 로컬 백엔드 대상 통합 검증 통과 (백엔드 변경 시)

Local Full-Stack Integration Verification (Serverpod 4 / 로컬 풀스택) ⭐#

Phase 5에서 위젯/유닛 mock 테스트와 별개로, 실제 백엔드를 띄운 상태에서 backend↔front 계약을 검증하는 단계. Serverpod 4의 내장 Postgres 덕분에 Docker 없이 완전 로컬로 수행한다.

언제 켜는가 (When to enable)

Phase 3(Backend)에서 모델/엔드포인트가 추가·변경되었거나, Phase 4 data layer가 실제 endpoint를 호출하는 경우 ON.
순수 위젯/유닛만 변경된 경우는 생략(기존 mock 테스트로 충분).

기동 (Start up)

serverpod start 한 명령으로 백엔드 서버 + 내장 Postgres + Flutter 앱을 함께 기동(서버·DB·웹·앱 sub-second stateful 핫리로드, 재컴파일/재시작 없음).
앱은 dev flavor에서 로컬 서버(http://localhost:8080/)로 연결, Staging은 폴백. base-URL은 앱의 기존 client/OpenApiService/flavor 설정을 따르고 하드코딩 금지.
핫리로드가 막히면 serverpod start 터미널에서 R 키로 서버+앱 강제 재시작.

통합테스트 실행 (Run integration tests)

백엔드: withServerpod 헬퍼 기반 통합테스트를 dart test -t integration으로 실행(내장 Postgres라 Docker 불필요).
프론트: feature/Patrol/통합 테스트는 mock이 아니라 방금 띄운 로컬 백엔드를 대상으로 수행.
백엔드 변경 시 DB 마이그레이션 생성·적용, 서버 로그 읽기, 앱 구동+스크린샷 검토는 Serverpod MCP로 실행 중인 로컬 서버에 연결해 수행.

종료 (Tear down)

검증 완료 후 serverpod start 프로세스를 종료(터미널 종료/Ctrl+C). 내장 Postgres는 함께 정리됨.

실패 시 처리 (On failure)

통합테스트 실패: 서버 로그(Serverpod MCP)로 원인 확인 → 모델/엔드포인트/data layer 수정 → 핫리로드(또는 R 키 재시작) 후 재실행.
기동 실패: 포트 충돌/잔존 프로세스 정리 후 재기동. Serverpod 3.x(legacy) 환경이면 폴백 경로 사용.
폴백 (3.x / legacy): 내장 Postgres가 없으므로 docker compose up -d로 DB 기동 → dart run bin/main.dart로 서버 기동 → 동일하게 dart test -t integration 수행.

상세 절차는 serverpod-local-fullstack, serverpod-mcp-guide 스킬 참조.

Error Handling#

Phase	On Failure
Preflight (MCP)	`fvm dart pub global activate marionette_mcp` 재실행 → 절대 경로 재등록 → snapshot 불일치(exit 253) 시 재활성화
Model creation	Re-verify field definitions
Endpoint creation	Verify import paths
Domain creation	Verify Entity field mapping
Data creation	Verify namespace imports
Presentation creation	Verify BLoC pattern, UseCase calls
로컬 풀스택 통합 검증	통합테스트 실패 시 Serverpod MCP로 서버 로그 확인 → 수정 → 핫리로드/R 키 재시작 후 재실행. 기동 실패 시 포트 충돌·잔존 프로세스 정리 후 재기동. 폴백(3.x): `docker compose up -d` + `dart run bin/main.dart`

Phase 0 Preflight Script (reference implementation)#

set -euo pipefail

MCP_BIN= " $HOME/.pub-cache/bin/marionette_mcp " 
 FVM_BIN= " /Users/dongwoo/fvm/default/bin " 

 # 1) 실행 파일 확인 + fvm 경유 자동 설치
if [ ! -x  " $MCP_BIN "   ]; then
  echo  " ⚠️  marionette_mcp 미설치 — fvm dart pub global activate 실행 " 
   fvm dart pub global activate marionette_mcp
fi

# 2) PATH 주입 (GUI 앱 고려: ~/.zshrc 업데이트 + 현재 쉘 반영)
case  " :$PATH: "   in
  * " :$HOME/.pub-cache/bin: " *) ;;
  *)
    echo  ' export PATH= " $PATH:$HOME/.pub-cache/bin " '   > >   " $HOME/.zshrc " 
     export PATH= " $PATH:$HOME/.pub-cache/bin " 
     ;;
esac

# 3) Claude Code MCP 등록 상태 확인/재등록
if ! claude mcp list 2 > & 1 | grep -q  " marionette:.*✓ Connected " ; then
  claude mcp remove marionette 2 > /dev/null || true
  claude mcp add --transport stdio marionette --  " $MCP_BIN " 
 fi

# 4) Cursor/Zed 설정 부재 시 생성 안내 (GUI 앱은 절대 경로 + env.PATH 필수)
test -f  " $HOME/.cursor/mcp.json "              || echo  " ℹ️  Cursor 설정 필요 (~/.cursor/mcp.json) " 
 test -f  " $HOME/.config/zed/settings.json "    || echo  " ℹ️  Zed 설정 필요 (~/.config/zed/settings.json) "

fvm 주의: dart는 zshrc alias(fvm dart)라 비대화형/GUI subprocess에서 해결되지 않음. 스크립트에서는 항상 fvm dart 또는 /Users/dongwoo/fvm/default/bin/dart 절대 경로를 사용.