harness

Imported from revfactory/harness-for-agy (skills/harness/SKILL.md). Install upstream with npx skills add revfactory/harness-for-agy --skill harness. Copyright stays with the author.

Project Harness Scaffolder (/harness)

이 스킬은 사용자가 구축하고자 하는 어떠한 프로젝트 형태나 비전에 맞춰, 특화된 **에이전트 페르소나(Personas)**팀과 그들이 사용할 공식 규격 커스텀 스킬(Skills) 구조를 일괄 설계하고 프로젝트 폴더 하위에 스캐폴딩(자동 뼈대 생성)하거나, 이미 구축된 에이전트 및 스킬 전체 구성을 분석하여 필요 시 에이전트를 추가 구성하고 기존 구성을 완벽히 보완합니다.

When to use this skill

• 새로운 프로젝트를 시작할 때, 그에 특화된 다중 에이전트 협업 팀을 구축하고자 할 때.
• 사용자가 "React 테스트 자동화 팀을 구성해줘" 혹은 "데이터 분석 파이프라인 전용 에이전트와 스킬들을 빌드해줘"라고 도메인별 요청을 할 때.
• 기존에 구성된 에이전트 및 스킬 목록 전체를 분석하고 검토하여, 필요 시 새로운 에이전트를 추가 구성하거나 기존 에이전트의 강령(Persona)과 스킬들을 보완 및 리팩토링하고자 할 때.
• 일일이 손으로 하부 폴더를 만들고 SKILL.md를 채워 넣는 반복 작업을 자동화하고 싶을 때.

Instructions

이 스킬이 가동되면 에이전트는 아래 규칙에 맞춰 정교한 설계, 검토 및 파일 생성을 처리해야 합니다.

[!IMPORTANT] 구현 계획서(Implementation Plan) 작성 생략: 하네스 스킬 작업 시에는 별도의 구현 계획서(implementation_plan.md) 작성을 요구하거나 대기하지 않고, 바로 도메인 분석과 아키텍처 설계를 완료한 뒤 곧바로 에이전트 및 스킬 구성을 즉시 실행(생성/업데이트)합니다.

1. 기존 에이전트 및 스킬 상태 진단 (Review Phase)

• 프로젝트 루트에 이미 AGENTS.md 또는 .agents/ 디렉토리가 존재하는 경우, 기존에 설계된 에이전트들의 역할, 담당 업무 및 등록된 커스텀 스킬 전체 구조를 정밀하게 분석합니다.

2. 사용자 요구사항 도출 및 격차 분석 (Gap Analysis)

• 사용자의 도메인 요구사항과 기술 스택을 바탕으로 기존 팀 구성의 빈틈(Gap)을 파악합니다.
• 이를 해결하기 위해 추가로 구성해야 할 전문 에이전트 역할군(예: 성능 모니터링, 보안 감사 등)이나 기존 에이전트의 보완책을 도출하고, 이들이 협업에서 활용할 새로운 핵심 스킬 및 기존 스킬의 개선점을 기획합니다.

3. 프로젝트 폴더 하위 스캐폴딩 및 점진적 업데이트 규칙

1) 통합 에이전트 가이드라인 (/AGENTS.md)

• 프로젝트 루트 디렉토리에 생성 또는 업데이트합니다.
• 기존의 에이전트 정보 및 컨벤션을 최대한 보존하면서, 새롭게 보완/추가되는 에이전트의 역할 명세 및 업데이트된 협업 규칙을 누적 반영하여 업데이트합니다.
• [Change History] 하네스 구성이 완료되거나 업데이트될 때마다 변경 일자, 구성 유형(신규/수정), 에이전트 팀 구성 난이도, 주요 변경 사항(추가/수정된 에이전트 및 스킬 목록)을 기록하는 구성 변경 이력(Change History) 섹션을 AGENTS.md 파일 하단에 누적하여 표(Table) 또는 목록 형태로 상세히 기술하도록 반영해야 합니다.

2) 개별 에이전트 상세 명세 (.agents/agents/<AgentName>.md)

• .agents/agents/ 디렉토리에 개별 마크다운 파일로 생성하거나 기존 파일을 업데이트합니다.
• 상단에 YAML Frontmatter(name, role, description)를 포함하고 바디에 구체적인 행동 가이드를 작성합니다.

3) 개별 에이전트 실행 프로필 (.agents/agents/<agent_name>/agent.json)

• 각 에이전트 폴더에 agent.json 파일을 작성하여 에이전트의 런타임 지침과 권한을 기재합니다.
• Antigravity CLI의 최신 플랫(Flat) JSON 스펙을 반드시 준수하여 선언합니다:

  {
    "name": "에이전트 이름",
    "description": "에이전트 역할 설명",
    "system_prompt": "시스템 지침 및 협업 SOP 상세 기술",
    "enable_write_tools": true,   // 쓰기 및 명령어 실행 도구 사용 여부
    "enable_mcp_tools": true,     // MCP 연동 도구 사용 여부
    "enable_subagent_tools": false // 하위 에이전트 기동 도구 사용 여부
  }

4) 표준 규격 스킬들 (.agents/skills/<skill-folder>/SKILL.md)

• 추가 및 보완되는 스킬 이름은 케밥 케이스(kebab-case)로 지정하고 개별 폴더를 생성/선택합니다.
• 각 폴더 내에 반드시 SKILL.md 파일명으로 생성 또는 수정합니다.
• 파일 상단에 필수 YAML Frontmatter를 채워 넣습니다:

  ---
  name: <kebab-case-name>
  description: <3인칭 시점의 기능 설명 및 트리거 조건 포함>
  allowed-tools:
    - <허용할 도구 1>
    - <허용할 도구 2>
  ---

• 바디에는 반드시 아래의 3대 필수 헤더를 포함시킵니다:
  • ## When to use this skill (언제 호출해야 하는지 상황과 트리거 제시)
  • ## Instructions (동작에 필요한 세부 프롬프트 지침)
  • ## Workflow (에이전트가 실행해야 할 순차적 수행 절차)

5) 중간 결과물 및 산출물 보관용 작업 공간 (_workspace/)

• 하네스로 빌드되는 모든 에이전트들이 태스크를 수행하면서 생성하는 모든 중간 소스코드, 분석 파일, 임시 산출물, 임시 데이터셋 및 실행 결과는 반드시 프로젝트 루트 하위에 _workspace/ 폴더를 생성하고 그 하위에 기록을 남기도록 해야 합니다.
• 이는 프로젝트의 핵심 소스 트리를 깨끗하게 보존하고, 에이전트가 생성하는 임시 산출물을 안전하게 격리/관리하기 위함입니다. 구성하는 모든 에이전트의 강령(Persona) 및 스킬들의 동작 정의 시 중간 결과물 경로가 항상 이 _workspace/ 디렉토리를 향하도록 시스템 프롬프트와 지침을 강력하게 설계해야 합니다.

4. 에이전트 오케스트레이션 아키텍처 패턴 설계 가이드

도메인 복잡성과 태스크 요구에 부합하도록 에이전트 간의 관계를 설계할 때 아래 6가지 핵심 오케스트레이션 아키텍처 패턴 중 최적의 구성을 명시하고, 이를 AGENTS.md에 공식화 및 구조화해야 합니다:

1. Pipeline (파이프라인): 순차적인 직렬 작업 흐름 (예: 스펙 정의 -> 코드 구현 -> 검증).
2. Fan-out/Fan-in (분산 및 병렬 처리): 병렬로 독립적인 태스크를 처리한 후, 최종 취합하는 방식.
3. Expert Pool (전문가 선택 풀): 당면한 태스크 유형에 따라 적합한 전문가 에이전트를 풀(Pool)에서 동적으로 선택.
4. Producer-Reviewer (생성자 및 검토자): 생성 담당 에이전트와 이를 감사/테스트/보완하는 에이전트의 2단계 협업 구조.
5. Supervisor (감독관): 중앙에서 마스터 에이전트가 실시간으로 하부 태스크를 동적 디스패치 및 통제.
6. Hierarchical Delegation (계층적 위임): 복잡한 대규모 태스크를 하위 서브에이전트들에게 재귀적으로 쪼개어 위임.

5. Antigravity CLI 최적화 런타임 및 메시지 규격 (Runtime Collaboration Protocol)

에이전트들은 Antigravity CLI 런타임 상에서 단순히 정적으로 대기하지 않고, 고도화된 연동 도구 API 및 실시간 통신 규격 프로토콜을 사용하여 상호 협업해야 합니다.

1) 런타임 에이전트 라이프사이클 관리

• 서브에이전트 등록 (define_subagent): 에이전트가 런타임 중에 필요한 전문 자아(Name, Description, System Prompt 및 도구 권한 플래그)를 동적으로 등록합니다. 세션이 시작되거나 프로젝트가 로드될 때, 기존 .agents/agents/{agent_name}/agent.json 파일에 정의된 에이전트 프로필을 로딩하여 define_subagent 도구를 통해 세션 런타임에 선제적으로 일괄 등록해 줍니다.
• 서브에이전트 기동 (invoke_subagent): 실시간 병렬 태스크 실행이 필요한 경우 invoke_subagent를 통해 에이전트를 백그라운드에서 실행하고 반환되는 고유의 Conversation ID를 획득하여 태스크 실행 흐름을 지휘합니다.

2) Antigravity CLI 표준 메시징 프로토콜

send_message 툴을 사용해 격리된 에이전트 간의 컨텍스트를 동기화하고 의사를 전달할 때는, 파싱 및 후속 작업 자동화를 위해 JSON 구조가 래핑된 표준 메시지 규격을 사용하여 교신하도록 에이전트 시스템 프롬프트에 내재화합니다.

메시지 페이로드 포맷(JSON) 규격:

{
  "sender": "송신 에이전트명",
  "action": "액션 유형 (REQUEST_REVIEW | TASK_COMPLETE | REFACTOR_REQUEST | STATUS_UPDATE)",
  "target_artifact": "작업 중인 대상 파일 경로 (절대 경로)",
  "content": "상세 텍스트 설명 및 요청 사항",
  "metadata": {
    "task_id": "작업 식별용 ID",
    "status": "현재 상태 값",
    "additional_context": "기타 참고 데이터"
  }
}

에이전트들은 send_message 호출 시 이 JSON을 문자열 형태로 텍스트 바디에 삽입하여 송신해야 하며, 이를 수신한 서브에이전트는 JSON 데이터를 우선 파싱하여 목표물과 요청 사양을 정확히 식별하고 도구 작업에 임하도록 설계되어야 합니다.

3) 오케스트레이터 스킬과의 유기적 연동

메인 에이전트에게 장착된 오케스트레이터 스킬은 전체 서브에이전트들을 기동(invoke_subagent), 대기, 결과 수합 및 통신 조율을 관리해야 하며, 각 서브에이전트가 돌려주는 JSON 형식의 표준 메시지 페이로드를 해석하여 후속 단계 에이전트 기동이나 피드백 전달 등을 효율적으로 오케스트레이션합니다.

6. 사용자 수련도(Skill Level)별 차등 구성 지침

사용자의 요청 사항 및 수준(수련도)을 분석하여 하네스 에이전트 팀 구성의 난이도와 구조적 복잡성을 다음과 같이 3단계로 차등화하여 설계합니다.

• 초급 (Beginner):

  • 목적: 직관적인 이해와 단순성 극대화.
  • 아키텍처: 단순 파이프라인(Pipeline) 또는 1~2개의 에이전트로 구성된 단순 생성자-검토자(Producer-Reviewer) 패턴을 선택합니다.
  • 스킬 구성: 복잡한 비동기나 분기 제어가 없는, 핵심 동작 위주의 쉽고 명료한 1~2개 단위 스킬로 구성합니다.
  • 오케스트레이션: 중앙 메인 에이전트가 단선적으로 하위 에이전트를 차례로 구동하여 피드백을 사용자에게 보여주는 형태이며 복잡한 병렬/비동기 흐름은 생략합니다.

• 중급 (Intermediate):

  • 목적: 기능의 모듈화와 효율적인 자동 협업.
  • 아키텍처: 전문가 풀(Expert Pool) 또는 파이프라인 + 생성자-검토자의 복합형 아키텍처를 적용하며, 2~3개의 개별 정문화된 에이전트를 배치합니다.
  • 스킬 구성: 독립성과 재사용성이 높은 기능별 모듈 스킬로 분리하여 설계합니다.
  • 오케스트레이션: 명확한 메시징 프로토콜을 사용한 세미 오토메이티드 협업 구조를 갖추고, 에이전트 간 순차적 피드백과 예외 상황 처리를 가이드합니다.

• 고급 (Advanced/Expert):

  • 목적: 극대화된 자동화, 고도의 예외 복구, 병렬 처리 및 자율성.
  • 아키텍처: 계층적 위임(Hierarchical Delegation) 또는 감독관(Supervisor) 패턴 등 복잡한 하이브리드 아키텍처를 설계하며, 3개 이상의 고도로 분화된 전문 에이전트를 구성합니다.
  • 스킬 구성: 고성능 자율 실행, 다이나믹 상태 관리, 병렬 실행 복구 능력(Recovery Strategy)을 갖춘 고급 스킬로 채워넣습니다.
  • 오케스트레이션: 메인 에이전트가 백그라운드로 여러 서브 에이전트를 동시에 기동(Fan-out/Fan-in)하고, 동적 define_subagent 기동 및 JSON 규격 통신을 활용한 완전 자율적 상호 피드백 루프를 구축하여 에러 및 충돌 복구 전략을 오케스트레이터 스킬에 깊이 내재화합니다.

Workflow

사용자가 하네스 스킬로 작업을 요청하면, 에이전트는 반드시 아래의 6단계 순서에 따라 작업을 정밀하게 진행해야 합니다:

Step 1. 사용자 요청 도메인 분석 (Domain Analysis)

• 사용자의 목표 시스템 및 도메인 요구사항과 기술 스택을 완벽히 분석합니다.
• 사용자 요청 문맥을 토대로 사용자의 수련도(초급/중급/고급)를 판별하여 적용할 에이전트 팀 및 스킬 구성의 난이도를 설정합니다.

Step 2. 에이전트 팀 아키텍처 설계 (Architecture Design)

• 결정된 난이도(수련도)에 부합하는 최적의 오케스트레이션 아키텍처 패턴을 설계합니다.
• 에이전트 간의 관계, 데이터 흐름, 호출 순서를 사용자가 직관적으로 이해할 수 있도록 AGENTS.md에 명확히 기술하여 설계안을 구조화합니다.

Step 3. 에이전트 구성 (Agent Configuration)

• 아키텍처 설계에 정의된 전문 에이전트들의 마크다운 파일(.agents/agents/<AgentName>.md) 및 Antigravity flat 규격을 준수한 agent.json 프로필 파일을 구성합니다.
• 프로젝트 루트 디렉토리에 전체 에이전트 가이드라인인 AGENTS.md를 신규 생성하거나 기존 컨벤션을 깨뜨리지 않으면서 점진적으로 업데이트합니다. 이 과정에서 오케스트레이터 스킬(orchestrator)을 가동하여 사용자가 내린 작업 명령(예: 하네스 자동 기획 및 기술 연구)을 실질적으로 실행하고 처리하는 구체적인 구동 지침 및 사용자 대화형 조작 매뉴얼에 관한 설명 섹션을 반드시 추가해야 합니다.

Step 4. 에이전트들이 사용할 스킬 구성 (Skill Configuration)

• 각 에이전트가 업무 수행 시 직접 탑재하고 동작할 커스텀 스킬 목록을 확정합니다.
• .agents/skills/<skill-folder>/SKILL.md 디렉토리 하위에 표준 규격(Frontmatter 및 When to use, Instructions, Workflow 3대 헤더)을 엄격히 준수한 스킬 파일들을 생성하거나 기존 구조를 정밀 리팩토링합니다.

Step 5. 오케스트레이터 스킬 구성 (Orchestrator Skill Configuration)

• 에이전트들이 유기적이고 효과적으로 상호작용하며 자동화 루프를 돌 수 있도록 Antigravity CLI 메인 에이전트에게 장착할 오케스트레이터 스킬을 전용으로 구성합니다.
• .agents/skills/orchestrator/SKILL.md 경로에 오케스트레이터 스킬 파일을 생성하고, 메인 에이전트가 서브 에이전트들을 기동(invoke_subagent), 통제 및 메시지(send_message) 처리하여 협업 루프를 지휘하고 실패 시 대응하는 구체적인 SOP와 프롬프트 지침을 구현합니다. 이 과정에서 현재 해당 하네스 시스템에 배포되고 연동된 전체 서브 에이전트 명세(이름, 역할)와 개별 에이전트들이 소유한 커스텀 스킬(이름, 자동화 임무)에 대한 상세한 기술적 설명 명세 목록을 오케스트레이터 스킬 본문에 명시적으로 삽입해야 합니다.

Step 6. 하네스 구성 검토 및 테스트 (Review & Test)

• 생성 또는 업데이트된 하네스 구조(에이전트 프로필, 스킬 마크다운)가 Antigravity 표준 규격에 맞게 적재되었는지 최종 점검합니다.
• [CRITICAL] 에이전트 즉시 등록: 하네스 스킬 수행 에이전트는 구성 완료 단계에서 반드시 생성된 모든 에이전트의 프로필(.agents/agents/{agent_name}/agent.json) 파일을 직접 읽고 파싱하여, define_subagent 도구를 실제로 호출해서 현재 대화 세션 런타임에 에이전트들을 실질적으로 즉시 등록해야 합니다. (에이전트 등록 누락 방지)
• invoke_subagent 및 send_message를 가상으로 작동시켜 에이전트 간의 자율적 통신 및 오케스트레이터 스킬의 협업 시나리오가 에러 없이 잘 매끄럽게 흐르는지 철저히 테스트하고 검증합니다.
• 모든 테스트와 작업이 완료되면, 에이전트 및 스킬 구조 트리 맵(Tree Map)을 시각적으로 콘솔에 출력하고, 사용자가 이번에 구축된 에이전트 팀과 스킬들을 신속히 인지할 수 있도록 리뷰를 위한 정보를 군더더기 없이 짧고 명료하게 작성하여 제시해야 합니다. 이 과정에서 새롭게 구축된 각 커스텀 스킬들의 고유 '스킬명(kebab-case)'과 이들이 담당하는 명확한 기술적 역할, 핵심 기능(예: 어떤 일을 자동화하는지 1줄 핵심 요약)에 대한 세부 설명을 누락 없이 명시하여 제공해야 합니다. (단순히 파일 경로(SKILL.md)를 그대로 노출하여 설명하는 대신, 사용자가 인지하기 쉽도록 공식 스킬명을 확실하게 보여주어야 합니다)
• 마지막으로, 사용자가 리뷰 후 이상이 없을 시 현재 구축된 하네스를 실제로 가동할 수 있도록, 터미널 셸 명령어 대신 Antigravity CLI 대화창 안에서 간단한 자연어 프롬프트(예: "하네스 기획 협업을 시작해줘", "하네스 연구 보고서와 교육 과정을 구축해줘" 등 직관적인 대화 시나리오)로 작업을 지시하고 제어하는 구체적인 대화 예시를 최종 활용 가이드 안내 문구에 반드시 포함하여 마무리합니다.