agentic-dev

agentic-dev는 say828/agentic-core와 say828/template-* 레포를 조합해 설치하고, GitHub Project 기반 멀티에이전트 개발 환경까지 같이 구성하는 installer/orchestrator CLI다.

기본 운영 모델은 GitHub-hosted Actions가 아니라 self-hosted Linux runner + 로컬/서버 모델 실행이다. 구독형 CLI와 외부 API 프로파일은 추가 지원 surface다.

역할

이 저장소는 runtime app 자체를 들고 있는 template monorepo가 아니다.

• core harness/runtime/policies/agent roles: say828/agentic-core
• template app/runtime payload: say828/template-*
• installer/orchestration logic: agentic-dev
• source-of-truth implementation: src/**/*.ts
• published CLI/runtime entry: dist/**/*.js
• shared sub-agent assets: .agent, .claude, .codex
• target repo workflow/runtime automation: install 시 target repo에 주입

Interactive Flow

npx agentic-dev

기본 명령은 설치기가 아니라 dashboard TUI다. 현재 레포의 .agentic-dev 상태, 설치된 에이전트, GitHub task mirror, queue/execution 상태를 풀스크린으로 보여주고 로컬 orchestration 액션을 실행할 수 있다.

• ←/→: tab 전환
• ↑/↓: 현재 리스트 이동
• r: refresh
• i: task IR 생성
• t: GitHub task sync
• p: queue plan
• d: dispatch build
• e: dispatch execute
• c: close pass
• q: 종료

설치는 명시적으로 아래처럼 시작한다.

npx agentic-dev init

init wizard는 아래 정보를 모두 먼저 받는다.

• project directory
• project name
• GitHub repository
• GitHub credential source
• GitHub project mode
• GitHub project title
• template repo
• AI execution adapters
• workspace agent surfaces
• non-empty directory 진행 여부
• final confirmation

조작:

• ←/→: 이전/다음 화면 이동
• ↑/↓: 선택 이동
• Space: multi-select toggle
• Enter: 현재 화면 확정

중요:

• 모든 입력이 끝나기 전에는 clone/install/bootstrap을 실행하지 않는다.
• 최종 확인 뒤에만 GitHub repo/project, template install, workflow wiring을 실행한다.
• TUI는 terminal alternate screen을 사용하므로 화면이 한 줄씩 밀리지 않는다.
• 설치가 끝나면 TUI는 종료되고 요약만 일반 터미널에 남긴다.

After Confirm

CLI는 이 순서로 동작한다.

1. GitHub repository create-or-use
2. GitHub Project create-or-use
3. selected template-* repo clone
4. say828/agentic-core clone and sync
5. core .agent, .claude, .codex, sdd, scripts/agentic-core, shared workflows install
6. installer-local .claude/agentic-dev.json / .codex/agentic-dev.json alias write
7. .agentic-dev/orchestration.json / .agentic-dev/settings.json write
8. github_project_kit.py bootstrap 실행
9. repo-local project-contract.json / role-map.json / artifact-contract.json materialize
10. repo secret AGENTIC_GITHUB_TOKEN / AGENTIC_PROJECT_TOKEN set
11. .github/workflows/agentic-orchestration.yml install
12. .agentic-dev/runtime/*.ts install
13. .agentic-dev/runtime/server.ts install
14. .env.example -> .env
15. pnpm install
16. selected template에 default frontend target이 있으면 Playwright/bootstrap

Workflow Contract

설치된 repo는 agentic-core와 template payload가 합쳐진 상태가 되며, 아래 orchestration surface를 가진다.

• sdd/02_plan/** push
• .agentic-dev/runtime/sdd_to_ir.ts
• .agentic-dev/runtime/sync_project_tasks.ts
• .agentic-dev/runtime/run_multi_agent_queue.ts
• .agentic-dev/runtime/dispatch_agents.ts
• .agentic-dev/runtime/dispatch_execute.ts
• .agentic-dev/runtime/close_completed_tasks.ts
• .agentic-dev/runtime/server.ts
• .github/workflows/agentic-orchestration.yml
• sdd/99_toolchain/01_automation/github-project-kit/project-contract.json
• sdd/99_toolchain/01_automation/github-project-kit/role-map.json
• sdd/99_toolchain/01_automation/github-project-kit/artifact-contract.json

즉 설치가 끝나면 target repo는 GitHub Project live contract와 task backlog contract까지 같이 가진다. 이후 SDD planning 산출물이 push되면 self-hosted Linux runner 위 workflow가 local orchestration server를 띄우고, 그 서버가 task IR, GitHub issue/project item sync, multi-agent queue, dispatch plan, dispatch execution, close pass를 처리한다.

기본 GitHub Project status field는 install 시 Todo, In Progress, In Review, Done 옵션을 맞춘다. 실행 중 status 전이는 todo -> in_progress -> in_review -> done을 사용한다.

기본 runner label은 self-hosted, linux다. 즉 GitHub billing에 묶인 ubuntu-latest baseline이 아니다. runner에는 Node, git, gh, 그리고 선택한 adapter에 맞는 codex / claude / ollama 또는 API key가 준비되어 있어야 한다.

GitHub Credential Source

이 선택은 사용자 레포가 퍼블릭인지 프라이빗인지 묻는 단계가 아니다.

• gh-session
  • 현재 머신의 gh auth login 세션을 GitHub repo/project orchestration에 사용한다.
• env
  • GH_TOKEN, GITHUB_TOKEN, AGENTIC_GITHUB_TOKEN, AGENTIC_PROJECT_TOKEN 중 사용 가능한 토큰을 GitHub repo/project orchestration에 사용한다.
• pat
  • 이번 실행에서만 붙여넣은 PAT를 GitHub repo/project orchestration에 사용한다.

모든 모드에서 템플릿 후보는 동일하게 say828/template-* 레포들이다.

Non-interactive Example

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-cli,ollama-self-hosted \
  --providers codex,ollama \
  --yes

AI Execution Adapters

현재 프로파일은 실제 실행 adapter 기준이다.

• codex-cli
  • self-hosted runner 위 로컬 codex CLI 세션을 사용한다.
  • 현재 autonomous repo mutation을 지원한다.
• ollama-self-hosted
  • self-hosted runner 위 로컬 ollama 서버를 사용한다.
  • 실제 provider 호출과 execution artifact 기록은 수행한다.
  • 아직 autonomous repo mutation은 지원하지 않으므로 실행 결과는 manual_follow_up_required로 남는다.
• openai-api
  • OPENAI_API_KEY로 OpenAI Responses API를 직접 호출한다.
  • 실제 provider 호출과 execution artifact 기록은 수행한다.
  • 아직 autonomous repo mutation은 지원하지 않으므로 실행 결과는 manual_follow_up_required로 남는다.
• claude-cli
  • self-hosted runner 위 로컬 claude CLI 세션을 사용한다.
  • 현재 autonomous repo mutation을 지원한다.
• anthropic-api
  • ANTHROPIC_API_KEY로 Anthropic Messages API를 직접 호출한다.
  • 실제 provider 호출과 execution artifact 기록은 수행한다.
  • 아직 autonomous repo mutation은 지원하지 않으므로 실행 결과는 manual_follow_up_required로 남는다.

legacy 값인 codex-subscription, codex-api, claude-subscription, claude-api는 내부에서 각각 codex-cli, openai-api, claude-cli, anthropic-api로 정규화된다.

즉 codex-api는 별도 독립 adapter가 아니고, OpenAI API 계열 direct adapter인 openai-api로 흡수된다.