---
name: project-generator
description: >
  새 웹 앱·API·CLI·라이브러리·자동화 프로젝트의 실행 가능한 초기 구조를 만들 때 쓴다.
  목적과 스택·실행 환경을 확인하고 최소 기능·설정 예시·실행 방법을 생성해 검증한다.
  기존 프로젝트 기능 추가는 implement-feature이며 새 원격 저장소 생성·공개 배포는 별도 요청이다.
---

# 새 프로젝트 생성

사용할 수 있는 프로젝트를 만든다. 디렉터리와 빈 파일만 만든 것을 구현 완료라고 하지 않는다.

## 생성 위치와 입력

목적·핵심 기능·사용 형태·언어/스택·실행 환경과 결과 위치를 확인한다. 사용자가 고른 기술을 유지하고,
필요 없는 인증·결제·클라우드·외부 서비스를 기본으로 추가하지 않는다. 중요한 정보가 없으면
짧게 확인하고, 이미 정해진 부분은 진행한다.

Agent Studio에서는 먼저 `Workspace.options`를 읽는다.
사용자 지정 Runtime을 우선하고, 미지정이면 options의 default_runtime을 따른다. 코딩 Runtime에는
완결된 자연어 task를 전달하며 command인 경우 실제 실행할 셸 스크립트를 구성한다.
CLI·명령행 도구를 만든다는 뜻과 command Runtime에서 이미 작성된 셸을 실행한다는 뜻을 구분한다.

- 기존 저장소에 생성·게시할 요청이면 최초 `start`에 허용된 repository와 base_branch를 지정한다.
- Git 없이 생성할 요청이면 두 값을 null로 시작한다. 등록 목록의 첫 저장소를 임의로 선택하지 않는다.
- 현재 공간이 있으면 파일 목록을 확인하고 `run`으로 이어간다. 기존 파일을 덮지 않는 상대 경로를 사용한다.
- `attach_repository`는 **빈 Git-free workdir에만** 가능하다. Git 없는 공간에 먼저 생성한 파일을
  나중에 자동 attach·push할 수 있다고 약속하지 않는다. Git 게시가 필요하면 생성 전에 대상을 정한다.

## 원격 저장소 준비

허용 목록에 이름이 있어도 원격 저장소가 존재하거나 clone 가능하다는 뜻은 아니다. 새 저장소 생성이
요청됐으면 파일 작업 전에 아래 순서를 완료한다.

1. 연결된 GitHub 계정과 요청한 owner/name을 확인한다. Workspace가 제공되면 원격 생성 전에
   `check_repository_access`의 기존 접근 `allowed`와 생성 권한 `creation_allowed`를 구분한다.
   `new` 모드는 미등록 이름의 기존 접근은 거절하지만 Workspace를 통한 신규 생성은 허용할 수 있다.
   둘 다 거절되면 `repository_policy_url`을 전달하고 정책 변경까지 보류한다. 관리 메뉴·권한을
   추측하거나 다른 이름의 저장소를 만들지 않는다.
   도구가 없는 환경에서는 실제 제공된 저장소 정책을 확인하고 범위가 불명확하면 외부 생성 전에 확인한다.
2. 제공된 조회 도구로 같은 이름의 저장소를 확인한다.
   404는 비공개 저장소 접근 거절일 수도 있다. 다른 이름·fork·공개 전환으로 우회하지 않는다.
3. Workspace의 `create_repository`가 제공되면 이를 사용한다. `repository: "owner/name"`,
   `description`, `private`를 전달하며 서버가 README와 첫 commit을 만든다. `new` 모드는 성공한
   저장소를 자동 등록한다. 공개 범위는 사용자 요청을 따르고 정해지지 않았으면 private=true다.
   반환된 status·allowed·repository_url·base_branch를 확인한다. Workspace 생성 기능이 없으면
   해당 환경의 실제 저장소 권한 범위에서 제공된 GitHub 생성 도구로 초기화할 수 있으나 Workspace 자동 등록은 약속하지 않는다.
   결과 불명·전송 중단에는 생성 호출을 반복하지 않는다. 이미 존재하는 저장소를 신규라고 주장해 등록하지 않는다.
4. 기존 저장소가 비어 있으면 clone할 branch가 없다. 첫 commit을 만드는 지원 경로와 요청 범위를 확인하고
   초기화한다. 존재하는 파일을 덮거나 Native Git 보호 경계를 우회하지 않는다.
5. 제공되는 경우 `Workspace.check_repository`로 서버 계정의 접근과 반환된 base_branch를 확인한다.
   GitHub MCP 계정과 Workspace 서버 계정의 접근은 별개다. 정책을 바꾼 뒤에는 options와 검사를 다시 읽는다.
6. 준비된 저장소를 선택해 최초 start하거나, 이미 선택된 실패 Workspace가 같은 저장소라면 run으로 재개한다.
   clone 실패를 새 Workspace 생성으로 해결하지 않는다. 네트워크·401·403·404·빈 저장소·없는 branch를
   구분하고 확인된 원인을 고친 뒤 재개한다.

## 구현과 검증

1. 코딩 Runtime에 목적·스택·생성 경로·최소 동작·검사 방법을 전달한다. command Runtime에는
   자연어 단계가 아닌 실제 비대화형 스크립트를 전달한다.
2. 공식 생성기·템플릿 또는 작은 수동 구조 중 목적에 맞는 것을 선택한다. 생성기가 기존 파일을
   지우거나 원격 Git·telemetry·인증을 요구하는지 확인하고 현재 실행 환경에 맞춘다.
3. 핵심 기능, 의존성·lockfile, 필요한 환경변수 예시와 실행·검사 방법을 만든다. 실제 시크릿은 넣지 않는다.
4. 설치·빌드·테스트 또는 CLI/API smoke 검증을 실행한다. 서버 프로세스가 종료될 수 있는 Sandbox의
   주소를 지속적인 공개 서비스 주소로 안내하지 않는다. 브라우저가 없으면 시각 검증은 미실행으로 밝힌다.

생성 파일 경로, 실행 명령, 구현한 최소 기능과 검증 결과를 전달한다. Workspace 파일과 별도
다운로드 Artifact는 다르며, 실제 제공된 전달 도구가 없으면 Workspace 링크를 제공한다.
내부 파일명은 상대 경로를 코드로 표시하고 `/workspace/...`를 다운로드 링크로 만들지 않는다.
게시·PR·배포까지 요청됐으면 연결된 `workspace-task`와 서비스 승인 절차를 사용한다.