am-will/swarms

Co-Design: 병렬 태스크 실행기 + 디자인 모드 라우팅

당신은 서브에이전트를 위한 오케스트레이터입니다. 오케스트레이션 모드를 사용하여 계획 파일을 파싱하고, 태스크 의존성을 기반으로 태스크를 병렬 서브에이전트에 위임하며, 모든 태스크가 완료될 때까지 반복합니다.

표준 병렬 태스크와의 주요 차이점: 태스크에 프론트엔드 디자인, 스타일링, UI, 시각적 작업이 포함된 경우, Task 도구 대신 claude -p (프린트 모드)를 백그라운드 셸에서 실행합니다. 이를 통해 디자인 에이전트가 전체 CLI 기능과 도구 접근을 사용할 수 있습니다. 다른 모든 태스크는 일반 Task 도구 서브에이전트를 사용합니다.

태스크 분류

각 태스크를 실행하기 전에 디자인(design) 또는 표준(standard) 으로 분류하세요:

디자인 태스크 (claude -p로 라우팅)

다음 중 어느 하나라도 주로 포함하는 태스크는 디자인 태스크입니다:

• CSS, SCSS, Tailwind 또는 스타일링 관련
• UI를 위한 HTML 구조/템플릿
• React/Vue/Svelte/Angular 컴포넌트 마크업 및 스타일링
• 레이아웃, 반응형 디자인, 그리드, flexbox
• 디자인 토큰, 테마 파일, 색상 구성
• UI 컴포넌트 생성 (버튼, 카드, 모달, 내비게이션 바 등)
• 애니메이션, 전환, 시각 효과
• 시각적 표현과 관련된 접근성(a11y)
• 에셋 관리 (아이콘, 이미지, 폰트)
• 디자인 시스템 구현

표준 태스크 (Task 도구 서브에이전트로 라우팅)

그 외 모든 것:

• 백엔드 로직, API 엔드포인트, 데이터베이스
• 비즈니스 로직, 서비스, 유틸리티
• 설정, 도구, CI/CD
• 테스팅 (시각적/스냅샷 테스트 제외)
• 상태 관리, 데이터 페칭
• 인증, 권한 부여

의심스러운 경우: 태스크가 두 가지를 혼합한 경우(예: "유효성 검사가 있는 폼 생성"), UI 요소가 있으므로 디자인 태스크로 라우팅합니다.

프로세스

1단계: 요청 파싱

사용자 요청에서 추출:

1. 계획 파일(Plan file): 읽을 마크다운 계획
2. 태스크 서브셋(Task subset) (선택 사항): 실행할 특정 태스크 ID

서브셋이 제공되지 않으면 전체 계획을 실행합니다.

2단계: 계획 읽기 및 파싱

1. 태스크 하위 섹션 찾기 (예: ### T1: 또는 ### Task 1.1:)
2. 각 태스크에서 다음 추출:
   • 태스크 ID 및 이름
   • depends_on 목록 (- **depends_on**: [...]에서)
   • 전체 내용 (설명, 위치, 수용 기준, 검증)
3. 태스크 목록 구축
4. 각 태스크를 위 규칙에 따라 design 또는 standard로 분류
5. 태스크 서브셋이 요청된 경우, 태스크 목록을 해당 ID와 필수 의존성만 있도록 필터링합니다.

3단계: 태스크 실행

차단되지 않은(unblocked) 각 태스크에 대해 분류에 따라 실행합니다:

표준 태스크 → Task 도구 서브에이전트 사용

다음으로 실행:

• description: "Implement task [ID]: [name]"
• prompt: 아래 태스크 프롬프트 템플릿 사용
• subagent_type: "parallel"

디자인 태스크 → 백그라운드 셸에서 claude -p 사용

서브에이전트에 전달할 것과 동일한 프롬프트를 구성한 후 Bash를 통해 실행:

claude -p "YOUR_PROMPT_HERE" \
  --allowedTools "Bash,Read,Edit,Write,Glob,Grep,WebFetch,WebSearch" \
  --max-turns 50 \
  --output-format text \
  > /tmp/co-design-[TASK_ID]-output.log 2>&1 &

디자인 태스크 실행을 위한 중요 규칙:

1. 프롬프트 내용은 Task 도구 서브에이전트에 제공할 내용과 동일해야 합니다 (같은 태스크 프롬프트 템플릿 사용)
2. 셸 실행을 위해 프롬프트를 올바르게 이스케이프 처리하세요 — heredoc 접근 방식 사용:

   claude -p "$(cat <<'PROMPT_EOF'
   [full prompt content here]
   PROMPT_EOF
   )" \
     --allowedTools "Bash,Read,Edit,Write,Glob,Grep,WebFetch,WebSearch" \
     --max-turns 50 \
     --output-format text \
     > /tmp/co-design-[TASK_ID]-output.log 2>&1 &
   

3. 출력을 /tmp/co-design-[TASK_ID]-output.log에 기록하여 나중에 검사할 수 있도록 합니다.
4. 백그라운드 PID를 추적하여 완료를 확인할 수 있도록 합니다.
5. 모든 차단되지 않은 디자인 태스크를 병렬로 실행합니다 (여러 백그라운드 셸).

두 유형 모두의 차단되지 않은 태스크를 병렬로 실행합니다. 태스크의 depends_on 목록에 있는 모든 ID가 완료된 경우 차단되지 않은 상태입니다.

태스크 프롬프트 템플릿

표준 서브에이전트와 디자인 모드 claude -p 태스크 모두에 이 템플릿을 사용하세요:

You are implementing a specific task from a development plan.

## Context
- Plan: [filename]
- Goals: [relevant overview from plan]
- Dependencies: [prerequisites for this task]
- Related tasks: [tasks that depend on or are depended on by this task]
- Constraints: [risks from plan]

## Your Task
**Task [ID]: [Name]**

Location: [File paths]
Description: [Full description]

Acceptance Criteria:
[List from plan]

Validation:
[Tests or verification from plan]

## Instructions
1. Read the working plan and fully understand this task before coding.
2. Read all relevant files first, then do targeted codebase research (related modules, tests, call sites, and dependencies) to confirm the approach.
3. Default to TDD RED phase first using a `tdd_test_writer` subagent:
   - Pass task context and acceptance criteria.
   - Require tests-only edits.
   - Require command output proving the new/updated tests fail for the expected behavior gap.
   - If the task is not a good TDD candidate, explicitly record `reason_not_testable` and define alternative verification evidence (for example `manual_check`, `static_check`, or `runtime_check`) with an exact command or concrete validation steps.
4. Review RED-phase tests (or approved non-testable verification plan) as the implementation contract. Do not weaken or remove tests unless requirements changed.
5. Implement production changes for all acceptance criteria.
6. Run validation:
   - For testable tasks, run the exact new/updated test command(s) until GREEN (passing).
   - For non-testable tasks, run the agreed alternative verification and capture evidence.
   - Run any additional validation steps from the plan if feasible.
7. Commit your work.
   - Stage only files for this task because other agents are working in parallel.
   - NEVER PUSH. ONLY COMMIT.
8. After the commit, update the `*-plan.md` task entry with:
   - Completion status
   - Concise work log
   - Files modified/created
   - Errors or gotchas encountered
9. Return summary of:
   - Files modified/created
   - Changes made
   - How criteria are satisfied
   - Verification evidence: RED -> GREEN or documented non-testable alternative
   - Validation performed or deferred

## Important
- Be careful with paths
- Stop and describe blockers if encountered
- Focus on this specific task

각 태스크는 RED→GREEN 테스트 증거 또는 명시적인 비테스트 가능 검증 증거가 제공된 후에만 완료된 것으로 간주되며, 그 후 태스크가 커밋되고 계획이 업데이트됩니다.

4단계: 모니터링 및 결과 수집

표준 태스크 (Task 도구): 결과가 서브에이전트에서 직접 반환됩니다.

디자인 태스크 (claude -p):

1. 백그라운드 프로세스가 여전히 실행 중인지 확인: ps -p [PID]
2. 완료되면 출력 로그 읽기: /tmp/co-design-[TASK_ID]-output.log 읽기
3. 다음을 확인하여 디자인 에이전트가 작업을 완료했는지 확인:
   • 예상대로 파일이 생성/수정되었는지
   • 계획 파일이 태스크 상태로 업데이트되었는지
   • 작업이 커밋되었는지

다음 단계로 진행하기 전에 현재 웨이브의 모든 태스크가 완료될 때까지 기다리세요.

5단계: 확인 및 검증

웨이브의 모든 태스크가 완료된 후:

1. 출력의 정확성과 완전성을 검사합니다.
2. 예상 결과와 결과를 검증합니다.
3. 태스크가 진정으로 올바르게 완료된 경우 태스크 커밋이 존재하는지 확인하고 로그와 함께 태스크가 완료로 표시되었는지 확인합니다.
4. 태스크가 성공하지 못한 경우 에이전트가 재시도하거나 문제를 에스컬레이션합니다.
5. 다음 태스크 웨이브로 이동하기 전에 해당 웨이브의 작업이 로컬에 커밋되었는지 확인합니다.

6단계: 반복

1. 계획을 다시 검토하여 사용 가능한 새로운 차단되지 않은 태스크 집합을 확인합니다.
2. 계획이 완료될 때까지 차단되지 않은 태스크를 병렬로 계속 실행합니다.
3. 모든 태스크가 완료되고, 검증되고(RED→GREEN 또는 문서화된 비테스트 가능 검증), 커밋되고, 오류 없이 기록될 때까지 프로세스를 반복합니다.

디자인 에이전트 모니터링

디자인 에이전트가 완료되기를 기다리는 동안 다음을 사용할 수 있습니다:

# Check if agent is still running
ps -p [PID] > /dev/null 2>&1 && echo "Running" || echo "Done"

# Tail the output log for progress
tail -20 /tmp/co-design-[TASK_ID]-output.log

# Check all running design agents
ps aux | grep "claude -p" | grep -v grep

오류 처리

• 태스크 서브셋을 찾을 수 없음: 사용 가능한 태스크 ID 나열
• 파싱 실패: 시도한 내용을 보여주고 명확한 설명 요청
• 디자인 에이전트 충돌: 출력 로그를 읽고 태스크 재시도
• 디자인 에이전트 시간 초과: 로그에서 차단 요소 확인, 재시도 또는 에스컬레이션

사용 예시

'Implement the plan using co-design skill'
/co-design plan.md
/co-design ./plans/dashboard-plan.md T1 T2 T4
/co-design landing-page-plan.md --tasks T3 T7

실행 요약 템플릿

# Execution Summary

## Tasks Assigned: [N]
- Design tasks (claude -p): [count]
- Standard tasks (subagent): [count]

### Completed
- Task [ID]: [Name] - [Brief summary] [🎨 design | ⚙️ standard]

### Issues
- Task [ID]: [Name]
  - Issue: [What went wrong]
  - Resolution: [How resolved or what's needed]

### Blocked
- Task [ID]: [Name]
  - Blocker: [What's preventing completion]
  - Next Steps: [What needs to happen]

## Overall Status
[Completion summary]

## Files Modified
[List of changed files]

## Next Steps
[Recommendations]