---
name: auto-setup
description: >
  프로젝트 컨텍스트 생성 — 코드베이스를 분석하고 ARCHITECTURE.md 및 .autopus/project 문서를 생성합니다
---

# auto-setup — 프로젝트 컨텍스트 생성 스킬

## Codex Invocation

You can invoke this workflow through any of these compatible surfaces:

- `@auto setup ...` — preferred when the local Autopus plugin is installed
- `$auto-setup ...` — direct repository skill invocation
- `$auto setup ...` — via the router skill

Load and follow any helper documents referenced from this file under `.codex/skills/` and `.codex/rules/autopus/`.


## Autopus Branding

When handling this workflow, start the response with the canonical banner from `templates/shared/branding-formats.md.tmpl`:

```text
🐙 Autopus ─────────────────────────
```

End the completed response with `🐙`.


**프로젝트**: my-bot | **모드**: full

## 설명

프로젝트 구조와 기술 스택을 분석해 세션 간 지속되는 컨텍스트 문서를 생성하거나 갱신합니다.
이 스킬은 첫 세션 온보딩, 오래된 프로젝트 재진입, `@auto plan`/`@auto sync` 전 컨텍스트 복구에 사용합니다.

## 사용법

```bash
@auto setup
@auto setup --auto
```

## Codex 기본 실행 모델

- Codex에서는 `setup`도 `spawn_agent(...)` 기반 subagent-first 로 진행합니다.
- Step 1의 전체 코드베이스 분석은 반드시 `explorer` 서브에이전트로 먼저 수행합니다.
- 메인 세션은 결과를 검토한 뒤 `ARCHITECTURE.md`와 `.autopus/project/*` 산출물을 최종 정리하고 저장합니다.
- 현재 Codex 런타임 정책이 암묵적 `spawn_agent(...)` 호출을 제한하면, 하네스 기본값과 제약을 명시적으로 설명한 뒤 사용자에게 서브에이전트 진행 여부 또는 `--solo` 성격의 단일 세션 진행을 확인받습니다.

전체 라우팅 규칙은 `@auto setup` 라우터를 우선합니다.

## 실행 순서

### [REQUIRED] Step 1: 코드베이스 분석

IMPORTANT: 이 단계는 반드시 `explorer` 서브에이전트를 먼저 호출해야 합니다. 분석 없이 Step 2로 건너뛰면 안 됩니다.

`explorer` 에이전트가 최소한 아래 정보를 반환하게 합니다.
- 디렉터리 구조와 패키지 역할
- 기술 스택(언어, 프레임워크, 빌드 도구)
- 엔트리포인트와 주요 공개 API
- 아키텍처 패턴과 도메인 경계
- 사용자 접점이 있는 라우트, 명령, 화면

> **POST-STEP**: explorer 결과를 받으면 Step 2로 진행합니다. 탐색 요약 없이 완료 안내를 출력하지 않습니다.

### [REQUIRED] Step 2: `ARCHITECTURE.md` 생성 또는 갱신

Explorer 분석을 바탕으로 루트 `ARCHITECTURE.md`를 작성합니다.

포함 항목:
- 핵심 도메인과 레이어
- 의존성 흐름 및 경계
- 진입점과 주요 데이터 흐름
- 관찰된 규칙 위반 또는 위험 지점

> **POST-STEP**: `ARCHITECTURE.md` 저장 후 Step 3으로 진행합니다.

### [REQUIRED] Step 3: `.autopus/project/` 핵심 문서 생성 또는 갱신

다음 3개 파일을 explorer 결과 기준으로 작성합니다.
- `product.md` — 프로젝트 목적, 핵심 기능, 주요 유스케이스, 모드
- `structure.md` — 디렉터리 구조, 패키지 역할, 엔트리포인트, 주요 파일 분포
- `tech.md` — 언어, 프레임워크, 빌드/테스트 도구, 아키텍처 패턴

규칙:
- 추측보다 실제 코드베이스 증거를 우선합니다.
- monorepo면 workspace/module 경계를 드러냅니다.
- 기존 파일이 있어도 현재 상태를 반영해 갱신합니다.

> **POST-STEP**: `.autopus/project/` 3개 파일 저장 후 Step 4로 진행합니다.

### [REQUIRED] Step 4: `scenarios.md` 생성 또는 갱신

`.autopus/project/scenarios.md`에 사용자 관점 E2E 시나리오를 정리합니다.

프로젝트 유형별로 다음을 추출합니다.
- CLI: 주요 명령, 플래그, 정상/실패 경로
- API: 메서드, 경로, 인증/사전조건, 기대 응답
- Frontend: 핵심 페이지, 사용자 동작, 검증 포인트
- Library: 공개 API 진입점과 대표 사용 시나리오

각 시나리오는 최소한 아래를 포함합니다.
- **Command/Action**
- **Precondition**
- **Expect**
- **Verify**
- **Status**

> **POST-STEP**: `scenarios.md` 저장 후 Step 5로 진행합니다.

### [REQUIRED] Step 5: `canary.md` 생성 또는 갱신

`.autopus/project/canary.md`에 빌드/엔드포인트/브라우저 건강 검진 대상을 정의합니다.

우선 탐지 대상:
- `Dockerfile`, `docker-compose.yml`
- `railway.json`, `vercel.json`, `fly.toml`, `render.yaml`
- `k8s/`, `helm/`
- `.github/workflows/`
- 소스 코드의 health/status endpoint
- 프론트엔드 라우트와 대표 브라우저 타깃

최소 산출물:
- build health check
- endpoint health check 또는 해당 없음
- browser health check 또는 해당 없음
- detection source 요약

> **POST-STEP**: `canary.md` 저장 후 Pre-Completion Verification으로 진행합니다.

### [REQUIRED] Pre-Completion Verification

완료 메시지 전에 아래 항목이 모두 충족됐는지 확인합니다.

- [ ] Step 1: explorer 서브에이전트 호출 완료
- [ ] Step 2: `ARCHITECTURE.md` 저장 완료
- [ ] Step 3: `.autopus/project/product.md`, `structure.md`, `tech.md` 저장 완료
- [ ] Step 4: `.autopus/project/scenarios.md` 저장 완료
- [ ] Step 5: `.autopus/project/canary.md` 저장 완료

하나라도 비어 있으면 완료 메시지를 출력하지 말고 해당 단계로 돌아갑니다.

## Completion Message

```text
Project context documents have been generated/updated.
- ARCHITECTURE.md
- .autopus/project/product.md
- .autopus/project/structure.md
- .autopus/project/tech.md
- .autopus/project/scenarios.md
- .autopus/project/canary.md
Context will be loaded automatically on the next session.
```

## First Win Guidance

완료 후 현재 상태에 맞는 다음 액션을 최대 3개까지 추천합니다.

우선순위:
1. 항상 표시 가능: `@auto review`, `@auto idea`
2. SPEC이 없으면: `@auto plan "기능 설명"`
3. draft SPEC이 있으면: `@auto go {SPEC-ID}` 또는 `auto spec review {SPEC-ID}`

출력 형식:

```text
🐙 바로 해볼 수 있는 것 ──────────────
1. {command} — {one-line value}
```

## 출력

- `ARCHITECTURE.md`
- `.autopus/project/product.md`
- `.autopus/project/structure.md`
- `.autopus/project/tech.md`
- `.autopus/project/scenarios.md`
- `.autopus/project/canary.md`