agentic-dev 0.2.11 → 0.2.13

package/README.md

@@ -1,69 +1,87 @@
 # agentic-dev
 
-`agentic-dev`는 `say828`의 공개 `template-*` 레포를 설치하는 scaffold CLI다.
+`agentic-dev`는 `say828/template-*` 레포를 조회해 설치하고, GitHub Project 기반 멀티에이전트 개발 환경까지 같이 구성하는 installer/orchestrator CLI다.
 
-## 사용법
+## 역할
+
+이 저장소는 runtime app 자체를 들고 있는 template monorepo가 아니다.
+
+- template app/runtime payload: `say828/template-*`
+- installer/orchestration logic: `agentic-dev`
+- shared sub-agent assets: `.agent`, `.claude`, `.codex`
+- target repo workflow/runtime automation: install 시 target repo에 주입
+
+## Interactive Flow
 
 ```bash
 npx agentic-dev
 ```
 
-또는 비대화형:
+wizard는 아래 정보를 모두 먼저 받는다.
 
-```bash
-npx agentic-dev init my-app --template template-fullstack-mono --yes
-npx agentic-dev init my-app --template template-web --yes --skip-bootstrap
-```
+- project directory
+- project name
+- GitHub repository
+- GitHub auth mode
+- GitHub project mode
+- GitHub project title
+- template repo
+- app mode
+- AI runtime profiles
+- workspace agent surfaces
+- non-empty directory 진행 여부
+- final confirmation
 
-## 동작
-
-1. GitHub에서 공개 `say828/template-*` 레포 목록을 조회한다.
-2. interactive TTY에서는 wizard 화면을 순서대로 보여준다.
-   - `←/→`: 이전/다음 화면 이동
-   - `↑/↓`: 고정 선택지 이동
-   - `Space`: AI providers 다중 선택 토글
-   - `Enter`: 현재 화면 값 확정
-3. wizard는 최소한 아래 정보를 모두 먼저 받는다.
-   - project directory
-   - project name
-   - GitHub auth mode
-   - GitHub PAT (`auth mode = pat`일 때만)
-   - template repo
-   - app mode
-   - AI providers
-   - non-empty directory 진행 여부가 필요하면 그 확인
-4. 모든 입력이 끝나면 실행 계획 요약과 최종 확인 화면을 보여준다.
-5. 최종 확인 전에는 clone, install, bootstrap을 시작하지 않는다.
-6. 확인 후에만 선택한 레포를 새 디렉터리로 복제한다.
-7. `.env.example`이 있으면 `.env`를 자동 생성한다.
-8. `pnpm install`을 자동 실행한다.
-9. 템플릿의 `repo-contract.json`에서 `frontend.default_target`을 읽는다.
-10. `app mode != backend`이면 그 target에 대해 `playwright install chromium`과 parity bootstrap을 실행한다.
-11. `AI providers` 선택에 따라 `.codex`, `.claude` 디렉터리를 정리하고 `.agentic-dev/setup.json`에 wizard 입력값을 기록한다.
-
-`frontend.default_target`이 있으면 multi-surface 템플릿도 그대로 지원한다. 예를 들어 `template-fullstack-mono`는 `client/web`과 `client/admin`을 함께 포함하지만 기본 bootstrap 대상은 `web`이다.
-
-## 예시
+조작:
 
-```bash
-mkdir my-fullstack-app
-cd my-fullstack-app
-npx agentic-dev init . --template template-fullstack-mono --yes
-```
+- `←/→`: 이전/다음 화면 이동
+- `↑/↓`: 선택 이동
+- `Space`: multi-select toggle
+- `Enter`: 현재 화면 확정
+
+중요:
 
-설치가 끝나면 CLI가 아래까지 자동 처리한다.
+- 모든 입력이 끝나기 전에는 clone/install/bootstrap을 실행하지 않는다.
+- 최종 확인 뒤에만 GitHub repo/project, template install, workflow wiring을 실행한다.
 
-- `.env.example -> .env`
-- `pnpm install`
-- `pnpm --dir client/web exec playwright install chromium`
-- `bash sdd/99_toolchain/01_automation/agentic-dev/bootstrap_frontend_parity.sh . web`
-- `.agentic-dev/setup.json` 생성
+## After Confirm
 
-## 옵션
+CLI는 이 순서로 동작한다.
 
-- `--template`, `-t`: template repo name 또는 suffix
-- `--owner`: GitHub owner. 기본값 `say828`
-- `--force`: 비어 있지 않은 디렉터리 허용
-- `--yes`, `-y`: interactive prompt 생략
-- `--skip-bootstrap`: install까지만 하고 bootstrap은 생략
-- `--help`, `-h`: 도움말 출력
+1. GitHub repository create-or-use
+2. GitHub Project create-or-use
+3. selected `template-*` repo clone
+4. shared `.agent`, `.claude`, `.codex` asset install
+5. `.agentic-dev/orchestration.json` / `.agentic-dev/setup.json` write
+6. `.github/workflows/agentic-orchestration.yml` install
+7. `.agentic-dev/runtime/*.mjs` install
+8. `.env.example -> .env`
+9. `pnpm install`
+10. `app mode != backend`이면 Playwright/bootstrap
+
+## Workflow Contract
+
+설치된 repo는 아래 orchestration surface를 가진다.
+
+- `sdd/02_plan/**` push
+- `.agentic-dev/runtime/sdd_to_ir.mjs`
+- `.agentic-dev/runtime/sync_project_tasks.mjs`
+- `.agentic-dev/runtime/run_multi_agent_queue.mjs`
+- `.agentic-dev/runtime/close_completed_tasks.mjs`
+- `.github/workflows/agentic-orchestration.yml`
+
+즉 SDD planning 산출물이 push되면 workflow가 task IR를 만들고, GitHub task mirror와 multi-agent queue를 갱신하는 구조다.
+
+## Non-interactive Example
+
+```bash
+npx agentic-dev init my-app \
+  --template template-fullstack-mono \
+  --project-name my-app \
+  --github-repo say828/my-app \
+  --github-project-title "My App Delivery" \
+  --github-project-mode create-if-missing \
+  --provider-profiles codex-subscription,openai-api \
+  --providers codex,claude \
+  --yes
+```

package/bin/agentic-dev.mjs

@@ -8,15 +8,18 @@ import {
   DEFAULT_TEMPLATE_OWNER,
   ensureTargetDir,
   fetchTemplateRepos,
+  finalizeRepositoryGit,
   installTemplateRepo,
   parseArgs,
   resolveTemplateRepo,
+  resolveGitHubOrchestration,
   usage,
 } from "../lib/scaffold.mjs";
 
 const DEFAULT_TARGET_DIR = ".";
 const DEFAULT_APP_MODE = "fullstack";
 const DEFAULT_AI_PROVIDERS = ["codex", "claude"];
+const DEFAULT_PROVIDER_PROFILES = ["codex-subscription", "claude-subscription"];
 
 const GITHUB_AUTH_CHOICES = [
   {
@@ -72,6 +75,28 @@ const AI_PROVIDER_CHOICES = [
   },
 ];
 
+const PROVIDER_PROFILE_CHOICES = [
+  { label: "codex-subscription", value: "codex-subscription", description: "Codex subscription/runtime access" },
+  { label: "codex-api", value: "codex-api", description: "Codex API access" },
+  { label: "claude-subscription", value: "claude-subscription", description: "Claude subscription/runtime access" },
+  { label: "claude-api", value: "claude-api", description: "Claude API access" },
+  { label: "openai-api", value: "openai-api", description: "OpenAI API access" },
+  { label: "ollama-self-hosted", value: "ollama-self-hosted", description: "Local Ollama runtime" },
+];
+
+const GITHUB_PROJECT_MODE_CHOICES = [
+  {
+    label: "create-if-missing",
+    value: "create-if-missing",
+    description: "Use an existing GitHub Project with the same title, otherwise create it",
+  },
+  {
+    label: "use-existing",
+    value: "use-existing",
+    description: "Require an existing GitHub Project and fail if it does not exist",
+  },
+];
+
 const CONFIRM_CHOICES = [
   {
     label: "Proceed",
@@ -128,6 +153,16 @@ function uniqueProviders(providers) {
     : [];
 }
 
+function normalizeProviderProfiles(providerProfiles) {
+  const normalized = Array.isArray(providerProfiles)
+    ? providerProfiles.map((profile) => profile.trim()).filter(Boolean)
+    : [];
+  if (normalized.length > 0) {
+    return [...new Set(normalized)];
+  }
+  return [...DEFAULT_PROVIDER_PROFILES];
+}
+
 function hydrateOptions(options) {
   const state = {
     targetDir: (options.targetDir || DEFAULT_TARGET_DIR).trim() || DEFAULT_TARGET_DIR,
@@ -137,6 +172,10 @@ function hydrateOptions(options) {
     githubPat: options.githubPat || "",
     appMode: (options.appMode || DEFAULT_APP_MODE).trim() || DEFAULT_APP_MODE,
     aiProviders: normalizeProviders(options.aiProviders),
+    providerProfiles: normalizeProviderProfiles(options.providerProfiles),
+    githubRepositoryInput: (options.githubRepositoryInput || "").trim(),
+    githubProjectMode: (options.githubProjectMode || "create-if-missing").trim() || "create-if-missing",
+    githubProjectTitle: (options.githubProjectTitle || "").trim(),
     force: Boolean(options.force),
     skipBootstrap: Boolean(options.skipBootstrap),
     owner: options.owner || DEFAULT_TEMPLATE_OWNER,
@@ -145,6 +184,12 @@ function hydrateOptions(options) {
   if (!state.projectName) {
     state.projectName = inferProjectName(state.targetDir);
   }
+  if (!state.githubRepositoryInput) {
+    state.githubRepositoryInput = state.projectName;
+  }
+  if (!state.githubProjectTitle) {
+    state.githubProjectTitle = `${state.projectName} Delivery`;
+  }
 
   return state;
 }
@@ -166,6 +211,7 @@ function sanitizeStateForInstall(state) {
     targetDir: (state.targetDir || DEFAULT_TARGET_DIR).trim() || DEFAULT_TARGET_DIR,
     projectName: (state.projectName || inferProjectName(state.targetDir)).trim(),
     aiProviders: normalizeProviders(state.aiProviders),
+    providerProfiles: normalizeProviderProfiles(state.providerProfiles),
   };
 }
 
@@ -193,6 +239,13 @@ function buildSteps(state, repos) {
       description: "Written into scaffold metadata and Claude workspace nickname.",
       placeholder: inferProjectName(state.targetDir),
     },
+    {
+      key: "githubRepositoryInput",
+      type: "text",
+      label: "GitHub repository",
+      description: "Use owner/name, a GitHub URL, or just a repo name to create/use the repository.",
+      placeholder: state.projectName,
+    },
     {
       key: "githubAuthMode",
       type: "single",
@@ -213,6 +266,20 @@ function buildSteps(state, repos) {
   }
 
   steps.push(
+    {
+      key: "githubProjectMode",
+      type: "single",
+      label: "GitHub project mode",
+      description: "Choose whether the orchestration must reuse an existing GitHub Project or create one if needed.",
+      choices: GITHUB_PROJECT_MODE_CHOICES,
+    },
+    {
+      key: "githubProjectTitle",
+      type: "text",
+      label: "GitHub project title",
+      description: "This project is used for SDD task orchestration.",
+      placeholder: `${state.projectName} Delivery`,
+    },
     {
       key: "template",
       type: "single",
@@ -227,11 +294,18 @@ function buildSteps(state, repos) {
       description: "Choose how much of the bootstrap flow should run after clone.",
       choices: APP_MODE_CHOICES,
     },
+    {
+      key: "providerProfiles",
+      type: "multi",
+      label: "AI runtime profiles",
+      description: "Use Space to toggle provider/runtime profiles.",
+      choices: PROVIDER_PROFILE_CHOICES,
+    },
     {
       key: "aiProviders",
       type: "multi",
-      label: "AI providers",
-      description: "Use Space to toggle. At least one provider must stay selected.",
+      label: "Workspace agent surfaces",
+      description: "Use Space to toggle Codex/Claude workspace assets.",
       choices: AI_PROVIDER_CHOICES,
     },
   );
@@ -275,6 +349,12 @@ function stepValue(state, step) {
   if (step.key === "projectName") {
     return state.projectName || step.placeholder || inferProjectName(state.targetDir);
   }
+  if (step.key === "githubRepositoryInput") {
+    return state.githubRepositoryInput || step.placeholder || state.projectName;
+  }
+  if (step.key === "githubProjectTitle") {
+    return state.githubProjectTitle || step.placeholder || `${state.projectName} Delivery`;
+  }
   if (step.key === "githubPat") {
     return state.githubPat || "";
   }
@@ -356,10 +436,14 @@ function executionPreview(state, selectedRepo) {
   const lines = [
     `Project directory: ${path.resolve(process.cwd(), state.targetDir)}`,
     `Project name: ${state.projectName}`,
+    `GitHub repository: ${state.githubRepositoryInput}`,
+    `GitHub project mode: ${state.githubProjectMode}`,
+    `GitHub project title: ${state.githubProjectTitle}`,
     `GitHub auth mode: ${state.githubAuthMode}`,
     `Template repo: ${selectedRepo?.name || state.template}`,
     `App mode: ${state.appMode}`,
     `AI providers: ${state.aiProviders.join(", ")}`,
+    `Provider profiles: ${state.providerProfiles.join(", ")}`,
     `Allow non-empty directory: ${state.force ? "yes" : "no"}`,
   ];
 
@@ -368,14 +452,17 @@ function executionPreview(state, selectedRepo) {
   }
 
   lines.push("Run plan:");
-  lines.push(`  1. Clone ${selectedRepo?.name || state.template}`);
-  lines.push("  2. Copy .env.example to .env if needed");
-  lines.push("  3. Run pnpm install");
+  lines.push(`  1. Ensure GitHub repo ${state.githubRepositoryInput}`);
+  lines.push(`  2. Ensure GitHub Project ${state.githubProjectTitle}`);
+  lines.push(`  3. Clone ${selectedRepo?.name || state.template}`);
+  lines.push("  4. Install shared sub-agent assets and orchestration workflow");
+  lines.push("  5. Copy .env.example to .env if needed");
+  lines.push("  6. Run pnpm install");
   if (state.appMode === "backend") {
-    lines.push("  4. Skip browser install and parity bootstrap");
+    lines.push("  7. Skip browser install and parity bootstrap");
   } else {
-    lines.push("  4. Install Playwright Chromium for the default frontend target");
-    lines.push("  5. Run frontend parity bootstrap");
+    lines.push("  7. Install Playwright Chromium for the default frontend target");
+    lines.push("  8. Run frontend parity bootstrap");
   }
 
   return lines;
@@ -464,6 +551,22 @@ function validateStepValue(step, state, value) {
     return trimmed;
   }
 
+  if (step.key === "githubRepositoryInput") {
+    const trimmed = value.trim();
+    if (!trimmed) {
+      throw new Error("GitHub repository cannot be empty.");
+    }
+    return trimmed;
+  }
+
+  if (step.key === "githubProjectTitle") {
+    const trimmed = value.trim();
+    if (!trimmed) {
+      throw new Error("GitHub project title cannot be empty.");
+    }
+    return trimmed;
+  }
+
   if (step.key === "githubPat") {
     const trimmed = value.trim();
     if (!trimmed) {
@@ -480,6 +583,14 @@ function validateStepValue(step, state, value) {
     return providers;
   }
 
+  if (step.key === "providerProfiles") {
+    const profiles = normalizeProviderProfiles(value);
+    if (profiles.length === 0) {
+      throw new Error("Select at least one provider profile.");
+    }
+    return profiles;
+  }
+
   if (step.key === "force" && value === false) {
     throw new Error("Prompt cancelled");
   }
@@ -603,14 +714,22 @@ async function runWizard(initialState, repos) {
       }
 
       if (step.type === "multi" && chunk === " ") {
-        const selected = new Set(uniqueProviders(state.aiProviders));
+        const selected = new Set(
+          step.key === "providerProfiles"
+            ? normalizeProviderProfiles(state.providerProfiles)
+            : uniqueProviders(state.aiProviders),
+        );
         const currentChoice = step.choices[cursors.get(step.key)];
         if (selected.has(currentChoice.value)) {
           selected.delete(currentChoice.value);
         } else {
           selected.add(currentChoice.value);
         }
-        state.aiProviders = [...selected];
+        if (step.key === "providerProfiles") {
+          state.providerProfiles = [...selected];
+        } else {
+          state.aiProviders = [...selected];
+        }
         rerender();
         return undefined;
       }
@@ -698,6 +817,10 @@ async function promptForMultiChoice(rl, label, choices, defaults) {
   }
 }
 
+async function promptMultiProfiles(rl, label, choices, defaults) {
+  return promptForMultiChoice(rl, label, choices, defaults);
+}
+
 function printFallbackPlan(state, repos) {
   const selectedRepo = resolveTemplateRepo(state.template, repos);
   console.log("");
@@ -719,6 +842,9 @@ async function promptLinearly(initialState, repos) {
     const projectNameAnswer = await rl.question(`Project name [${state.projectName || defaultProjectName}]: `);
     state.projectName = projectNameAnswer.trim() || state.projectName || defaultProjectName;
 
+    const repoAnswer = await rl.question(`GitHub repository [${state.githubRepositoryInput || state.projectName}]: `);
+    state.githubRepositoryInput = repoAnswer.trim() || state.githubRepositoryInput || state.projectName;
+
     state.githubAuthMode = await promptForChoice(rl, "GitHub auth mode", GITHUB_AUTH_CHOICES);
     if (state.githubAuthMode === "pat") {
       state.githubPat = (await rl.question("GitHub PAT: ")).trim();
@@ -727,8 +853,19 @@ async function promptLinearly(initialState, repos) {
       }
     }
 
+    state.githubProjectMode = await promptForChoice(rl, "GitHub project mode", GITHUB_PROJECT_MODE_CHOICES);
+    const projectTitleAnswer = await rl.question(`GitHub project title [${state.githubProjectTitle || `${state.projectName} Delivery`}]: `);
+    state.githubProjectTitle =
+      projectTitleAnswer.trim() || state.githubProjectTitle || `${state.projectName} Delivery`;
+
     state.template = await promptForChoice(rl, `Template repo from ${state.owner}`, buildTemplateChoices(repos));
     state.appMode = await promptForChoice(rl, "App mode", APP_MODE_CHOICES);
+    state.providerProfiles = await promptMultiProfiles(
+      rl,
+      "AI runtime profiles",
+      PROVIDER_PROFILE_CHOICES,
+      state.providerProfiles,
+    );
     state.aiProviders = await promptForMultiChoice(rl, "AI providers", AI_PROVIDER_CHOICES, state.aiProviders);
 
     if (!state.force && directoryHasUserFiles(state.targetDir)) {
@@ -789,6 +926,12 @@ function validateNonInteractiveState(state) {
   if (!state.projectName) {
     state.projectName = inferProjectName(state.targetDir);
   }
+  if (!state.githubRepositoryInput) {
+    state.githubRepositoryInput = state.projectName;
+  }
+  if (!state.githubProjectTitle) {
+    state.githubProjectTitle = `${state.projectName} Delivery`;
+  }
   if (state.githubAuthMode === "pat" && !state.githubPat) {
     throw new Error("`--github-auth pat` requires `--github-pat`.");
   }
@@ -843,6 +986,7 @@ async function main() {
         : await promptLinearly(state, repos);
 
     applyRuntimeGitHubAuth(resolvedState);
+    const orchestration = await resolveGitHubOrchestration(resolvedState);
     const selectedRepo = resolveTemplateRepo(resolvedState.template, repos);
     const destinationRoot = ensureTargetDir(resolvedState.targetDir, {
       force: resolvedState.force,
@@ -850,9 +994,16 @@ async function main() {
     const result = installTemplateRepo({
       destinationRoot: path.resolve(destinationRoot),
       templateRepo: selectedRepo,
-      setupSelections: resolvedState,
+      setupSelections: {
+        ...resolvedState,
+        ...orchestration,
+      },
       skipBootstrap: resolvedState.skipBootstrap,
     });
+    finalizeRepositoryGit(path.resolve(destinationRoot), {
+      ...resolvedState,
+      ...orchestration,
+    });
     printSuccess(result);
   } catch (error) {
     console.error(error.message);