company-os-cli

재사용 가능한 Multi-Agent Company Operating System 스켈레톤을 pip으로 설치해 CLI 한 줄로 만들어내는 도구입니다. Role · Skill · Workflow · Memory를 Git Markdown(SSOT)으로 관리하고, LangGraph/LangChain 기반 Agent가 이를 읽어 추측 없이 협업하도록 설계되었습니다.

설치

# PyPI에 배포된 이후
pip install company-os-cli

# 배포 전 / 최신 개발 버전을 바로 쓰고 싶다면 GitHub에서 직접 설치
pip install git+https://github.com/as950118/ai-company.git

설치하면 company-os 명령이 생깁니다.

빠른 시작

A. 독립 Company OS 레포로 (SSOT 문서를 최상위에 그대로 노출)

이 프로젝트 자체가 "회사 운영체제"인 경우 — GitHub에서 열었을 때 company/, roles/, skills/가 바로 보이는 게 맞습니다.

company-os init \
  --name "Acme Agent Co" \
  --product "Acme Task Hub" \
  --slug acme-task-hub \
  --out ./my-company-os

cd my-company-os

B. 기존 프로젝트에 얹기 (숨김 폴더로 격리)

이미 소스코드가 있는 프로젝트에 Company OS를 추가하는 경우, --out을 생략하면 현재 폴더의 .company-os/(.git, .github, .vscode, .cursor와 같은 패턴)에 자동으로 만들어져 기존 폴더 구조(예: 이미 있는 docs/, runtime/)와 충돌하지 않습니다.

cd my-existing-project
company-os init --name "Acme Agent Co" --product "Acme Task Hub"
# → ./.company-os/ 에 생성됨

company-os --version
company-os init --help

옵션:

옵션	설명	기본값
--name	회사 표시명	(필수)
--product	제품명	(필수)
--out	생성 경로	현재 폴더의 ./.company-os
--slug	경로/ID용 슬러그	--product에서 자동 생성
--force	비어있지 않은 폴더에 덮어쓰기 허용	off
--llm-provider	기본 LLM 프로바이더	openrouter
--model	기본 모델 ID	openrouter/free
--langsmith-project	LangSmith 프로젝트명	slug와 동일

생성 후:

1. cd <out> 후 company/vision.md 등 플레이스홀더 잔여({{…}}) 검색: rg '\{\{[A-Z0-9_]+\}\}'
2. runtime/.env.example → .env 복사, OpenRouter / LangSmith 키 설정
3. workflows/create-feature.md로 첫 Feature 시작

버전 업그레이드 (company-os upgrade)

company-os-cli를 새 버전으로 올리면 roles/, skills/, workflows/, .claude/skills/ 등 템플릿이 개선됩니다. 이미 memory/(결정·프로젝트·태스크 기록)와 projects/<slug>/(작성해 둔 PRD·ADR)를 채워둔 상태라면, init --force로 재생성하는 대신 이 명령을 쓰세요:

cd my-existing-project   # 또는 임베드 안 한 standalone 레포 루트
company-os upgrade

동작 원칙:

• 템플릿에 없는 파일은 절대 건드리지 않습니다. memory/의 실제 기록, projects/<slug>/에 작성한 PRD/ADR처럼 CLI가 만든 적 없는 파일은 애초에 비교 대상이 아닙니다.
• 직접 수정한 적 없는 템플릿 파일(예: 아직 손대지 않은 roles/qa.md)은 새 버전으로 안전하게 갱신됩니다.
• 직접 수정한 템플릿 파일(예: roles/architect.md에 우리 팀 규칙을 추가한 경우)은 그대로 두고, 새 템플릿 내용을 roles/architect.md.upgrade-<version>으로 옆에 남겨 수동으로 diff/병합하도록 합니다. 다시 company-os upgrade를 돌려도 이 파일은 병합 전까지 계속 conflict로 표시됩니다(조용히 덮어쓰지 않음).
• company-os-cli 0.3.0 이전 버전으로 만든 인스턴스(매니페스트가 없음)에서는 처음 한 번 --name/--product와 함께 실행해야 하며, 이 첫 실행은 아무 파일도 바꾸지 않고 현재 상태를 기준선으로만 기록합니다. 실제 갱신은 그다음 company-os upgrade 호출부터 적용됩니다.
• --dry-run으로 실제로 반영하지 않고 add/update/conflict 목록만 미리 볼 수 있습니다.

생성되는 구조

my-company-os/
├── README.md                  ← 제품용 README (TEMPLATE_README.md에서 렌더링됨)
├── .company-os-manifest.json  ← `company-os upgrade`가 쓰는 파일별 해시 기록 (직접 편집 금지)
├── company/                   ← Vision / Mission / Values / Org / Tech Stack / Glossary
├── roles/                     ← Role별 R&R + System Prompt (10종)
├── skills/                    ← 역할 공통 재사용 절차 (write-prd, write-adr, create-api …)
├── workflows/                 ← create-feature / fix-bug / release / incident / onboarding
├── docs/                      ← PRD·Architecture·API·Task·ADR 템플릿 + 협업 규칙
├── agents/                    ← Role별 Agent YAML (도구·메모리·핸드오프·시스템 프롬프트)
├── langgraph/                 ← Feature/BugFix/Release Graph 설계 (Markdown SSOT)
├── memory/                    ← 5종 Memory 인덱스 (company/project/decision/task/lessons-learned)
├── projects/<slug>/           ← 첫 프로젝트 (prd/architecture/adr/api)
├── tasks/                     ← Task 인덱스
├── runtime/                   ← LangChain/LangGraph 최소 Python 스텁 (company_os 패키지)
└── .claude/skills/            ← Claude Code Skill 16종 (아래 "Claude Code에서 쓰기" 참고)

--out을 생략해 .company-os/에 임베드하는 경우, .claude/skills/만은 .company-os/ 안이 아니라 호스트 프로젝트 루트(.company-os/의 부모 폴더)에 생성됩니다. Claude Code는 시작 디렉터리부터 리포 루트까지의 .claude/skills/만 즉시 인식하기 때문입니다.

설계 원칙 (Kit이 강제하는 것)

1. Git Markdown = SSOT — 모든 지식은 Role/Skill/Workflow/Memory로 문서화
2. Role / Skill / Workflow 분리 — 한 Agent가 모든 역할을 하지 않는다
3. 승인 게이트 없이 Prod 금지 — Reviewer → QA → DevOps 순서 강제
4. ADR로 결정 기록 — 기술 선택은 반드시 memory/decision-memory/에 남긴다
5. 추측 금지 — 문서 없으면 질문

협업 파이프라인

CEO → PM → Architect → Backend/Frontend → Reviewer → QA → Release(DevOps)
              ↘ Designer (Design System/UX, Architect와 병행 → Frontend)
                                                              ↘ Technical Writer (문서화 지원, 전 단계 개입 가능)

생성된 프로젝트의 docs/agent-collaboration-rules.md에서 Stage Contract를 확인할 수 있습니다.

Claude Code에서 쓰기

스캐폴딩 결과물에는 Claude Code Agent Skills가 자동으로 포함됩니다 (.claude/skills/, 16개). 각 스킬은 company-os 문서를 복제하지 않고, 필요한 파일(roles/, workflows/, agents/*.yaml, docs/agent-collaboration-rules.md 등)을 그때그때 읽으라고 안내만 합니다.

• 통합 스킬 company-os — 진입점. 어떤 역할/문서를 봐야 할지 모를 때
• 역할별 스킬 10종 company-os-pm, company-os-architect, company-os-designer, company-os-backend, company-os-frontend, company-os-reviewer, company-os-qa, company-os-devops, company-os-technical-writer, company-os-ceo
• 워크플로우별 스킬 5종 company-os-create-feature, company-os-fix-bug, company-os-release, company-os-incident, company-os-onboarding

스캐폴딩된 프로젝트에서 Claude Code를 실행한 뒤 "PM으로서 PRD 작성해줘", "Designer로서 디자인 시스템 잡아줘", "create-feature 워크플로우 시작해줘" 처럼 자연어로 요청하면 해당 스킬이 자동으로 트리거됩니다. /company-os-pm처럼 슬래시 커맨드로 직접 불러도 됩니다.

스킬이 16개라 다른 프로젝트 고유 스킬이 많다면 discovery 목록 예산이 빠듯할 수 있습니다. 필요하면 호스트 프로젝트의 .claude/settings.json에 skillOverrides로 자주 안 쓰는 스킬을 name-only로 낮추거나, skillListingBudgetFraction을 올리세요 (자세한 옵션은 Claude Code 공식 문서 참고).

Cursor에서 쓰기

새 프로젝트에 스캐폴드한 뒤:

당신은 {{PRODUCT_NAME}} Company OS의 Architect다.
company/, roles/, workflows/를 읽고 추측하지 마라.
지금은 create-feature의 Design 단계만 수행한다.

이 레포 구조 (패키지 개발자용)

ai-company/                        ← company-os-cli 패키지 소스 레포
├── pyproject.toml                  ← 패키징 메타데이터 (hatchling, entry point: company-os)
├── LICENSE
├── src/company_os_cli/
│   ├── __init__.py                 ← __version__
│   ├── cli.py                      ← Typer CLI (`company-os` 명령)
│   ├── scaffold.py                 ← 핵심 스캐폴딩 로직 (CLI 비의존, 테스트/재사용 가능)
│   └── template/                   ← 위 "생성되는 구조"의 원본 (company/, roles/, skills/, .claude/skills/ …)
├── tests/test_scaffold.py          ← scaffold() 함수 + CLI 엔드투엔드 스모크 테스트
└── .github/workflows/              ← CI (테스트) + publish (태그 push 시 PyPI 배포)

로컬 개발

python3 -m venv .venv && source .venv/bin/activate
pip install -e ".[dev]"

company-os --version
python -m unittest discover -s tests -v

# 배포용 빌드 확인
python -m build
python -m zipfile -l dist/company_os_cli-*-py3-none-any.whl

릴리스 (PyPI 배포)

1. pyproject.toml의 version을 올린다
2. git tag v0.1.0 && git push origin v0.1.0
3. .github/workflows/publish.yml이 태그 push 시 테스트 → 빌드 → PyPI 업로드까지 수행
   • PyPI API 토큰(https://pypi.org/manage/account/token/) 발급 후, GitHub 저장소의 pypi Environment(Settings → Environments → pypi)에 PYPI_API_TOKEN 시크릿으로 등록
   • 프로젝트가 PyPI에 아직 없는 첫 배포라면 "Entire account" 스코프 토큰을 써야 합니다 (프로젝트 스코프 토큰은 프로젝트가 이미 존재해야 발급 가능). 첫 배포 성공 후엔 company-os-cli 프로젝트 스코프로 좁힌 토큰으로 교체 권장

실습 산출물 안내

실제 실행 로그, Review dump 등 산출물은 이 레포(Kit)에 포함하지 않습니다. company-os init으로 생성한 각 프로젝트의 memory/, projects/<slug>/에 쌓아가세요.