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

# 새 프로젝트 생성

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

## 생성 위치와 입력

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

호스트 앱에서는 Agent Forge MCP로 실행한다. 연결된 `workspace-task`가 있으면 Workspace 준비 절차를 읽는다.
사용자 지정 Runtime을 우선하고, 미지정이면 사용자가 선택한 Forge Workspace profile을 따른다. native Runtime에는
완결된 자연어 작업을 전달하며 command인 경우 실제 실행할 셸 스크립트를 구성한다.
CLI·명령행 도구를 만든다는 뜻과 command Runtime에서 이미 작성된 셸을 실행한다는 뜻을 구분한다.

- 기존 저장소에 생성·게시할 요청이면 `git_connections`에 등록된 저장소로 Git `prepare`를 먼저 실행한다.
- Git 없이 생성할 요청이면 `prepare` 없이 시작한다. 등록 목록의 첫 저장소를 임의로 선택하지 않는다.
- 현재 Workspace가 있으면 파일 목록을 확인하고 같은 Workspace에서 이어간다. 기존 파일을 덮지 않는 상대 경로를 사용한다.
- Git 준비는 기존 작업 파일을 덮어쓰지 않는다. Git 없는 공간에 먼저 생성한 파일을 나중에 저장소로
  자동 게시할 수 있다고 약속하지 않는다. Git 게시가 필요하면 생성 전에 대상을 정한다.

## 원격 저장소 준비

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

1. 연결된 GitHub 계정과 요청한 owner/name을 확인한다. Forge에서는 `git_connections`의 `accounts`에서
   `accountId`를 확인한다. 연결이 없으면 사용자가 Forge 콘솔의 Git 설정에서 GitHub 계정을 연결해야 한다.
2. 생성에 쓸 Workspace profile이 그 이름을 허용하는지 확인한다. `repositoryMode`가 `new`이면 유효한 모든 이름,
   `selected`는 `repositories`, `owners`는 그 owner의 이름, `all`은 모든 이름을 허용한다. 허용되지 않으면
   profile 소유자가 Forge 콘솔에서 profile을 바꿔야 한다고 알린다. 다른 이름의 저장소를 만들거나 profile을 임의로 넓히지 않는다.
3. 제공된 조회 도구로 같은 이름의 저장소를 확인한다.
   404는 비공개 저장소 접근 거절일 수도 있다. 다른 이름·fork·공개 전환으로 우회하지 않는다.
4. Forge `repository_create`에 `accountId`, `profileId`, `profileRevision`, `repository: "owner/name"`,
   선택 `description`, `private`, `requestKey`를 보낸다. 공개 범위는 사용자 요청을 따르고 정해지지 않았으면 `private: true`다. 단, Agent Runway로 배포할 앱은 `app-delivery` 절차에 따라 `private: false`다.
   `status:"created"`이면 Forge가 초기 commit을 만들고 저장소를 사용자 연결로 등록한다. 반환된 실제 `defaultBranch`를 사용한다.
   `failed`는 GitHub 거절이다. `unknown`이거나 응답을 잃었으면 생성을 반복하지 않는다. `repository_lookup_request`·
   `repository_get`으로 영수증을 읽고, `requiresUserDecision`이면 사용자가 대상을 확인해 Forge 콘솔에서 직접 등록하도록 안내한다.
   대상이 존재해도 이 요청이 만들었다는 증거가 아니다.
   Forge 생성 기능이 없으면 해당 환경의 실제 저장소 권한 범위에서 제공된 GitHub 생성 도구로 초기화할 수 있으나 Forge 등록은 약속하지 않는다.
5. 기존 저장소가 비어 있으면 clone할 branch가 없다. 첫 commit을 만드는 지원 경로와 요청 범위를 확인하고
   초기화한다. 존재하는 파일을 덮거나 Git 보호 경계를 우회하지 않는다.
6. 준비된 저장소의 연결 `id`와 `defaultBranch`로 Git `prepare`를 실행한다. 실패하면 네트워크·권한·빈 저장소·없는 branch를
   구분하고 확인된 원인을 고친 뒤 같은 Workspace에서 다시 준비한다. 새 Workspace 생성으로 해결하지 않는다.

## 구현과 검증

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

생성 파일 경로, 실행 명령, 구현한 최소 기능과 검증 결과를 전달한다. Workspace 파일과 별도
다운로드 Artifact는 다르며, 실제 제공된 전달 도구가 없으면 Workspace 링크를 제공한다.
내부 파일명은 상대 경로를 코드로 표시하고 `/workspace/...`를 다운로드 링크로 만들지 않는다.
호스트 앱에서 저장소를 지정한 프로젝트 생성은 사용자가 제한하지 않으면 새 작업 브랜치에서 구현·검증 후
`workspace-task`의 Git 게시 절차로 커밋·푸시·PR까지 추가 승인 없이 완료한다.
Git-free 결과물에는 원격 게시를 추가하지 않는다. main 반영·태그·릴리즈·배포는 별도 요청과 확인을 따른다.