2.작동 원리

2.1 구성 요소

SoloSquad 는 2개의 상주 프로세스와 파일 기반 저장소로 동작합니다. 별도 DB 서버나 클라우드 백엔드가 없습니다.

두 프로세스 모두 내부적으로 Claude Code 를 호출해 에이전트를 실행합니다. 즉 실제 작업은 Claude 가 하고, SoloSquad 는 메신저 ↔ 에이전트 ↔ 파일 저장소를 잇는 오케스트레이션 layer 입니다.

2.2 메시지 처리 흐름

사용자가 #command-<handle> 에 메시지를 보내면 다음 순서로 처리됩니다.

① 사용자 메시지  (#command-<handle>)
       ▼
② Chief 가 의도 분류  → chat │ workflow │ goal │ schedule
       ▼
③ chat        → 그 자리에서 바로 답변 (#command 채널)
   그 외        → #works-<handle> 에 작업 카드 + thread 생성, PM 에게 위임
       ▼
④ PM 이 단계 분해 → 필요한 전문가를 호출(Task)하여 작업 수행
       ▼
⑤ 결과를 모아 Chief 가 사용자에게 보고

Chief 는 (사용자, 조직)별로 대화 세션을 유지하므로 봇을 재시작해도 "지난번에 하던 얘기"를 이어갑니다. workflow 단계 상태, goal cycle, 메모리는 모두 디스크에 저장되어 손실되지 않습니다.

2.3 폴더 구조

워크스페이스 한 개 안에 여러 조직(사업/제품)이 들어가고, 각 조직 안에 저장소(코드)가 들어가는 3계층 구조입니다. 핵심만 추리면 다음과 같습니다.

조직별 색채(철학·톤·도메인 지식)는 <org>/core/·<org>/domain/ 등에서 더해지며, 번들 에이전트 정의 자체는 건드리지 않습니다. 사용자가 직접 손댈 일이 가장 많은 파일은 workspace.yaml(브리프 시각·timezone)과 .env(토큰) 정도입니다.

2.4 컨텍스트 & 메모리

SoloSquad 는 매 호출마다 필요한 컨텍스트만 골라 주입합니다 (Just-in-Time). 전체 에이전트 정의를 항상 다 넣지 않으므로 비용과 혼선이 줄어듭니다. 메모리는 세 가지 성격으로 나뉩니다.

모든 루틴·결정 기록은 JSONL(한 줄 = 한 이벤트)로 누적되고, 오래된 항목은 자동으로 검색용 아카이브(archive.sqlite)로 정리됩니다. 사용자가 메모리를 직접 관리할 일은 거의 없습니다 — 매일 자정 housekeeping 루틴이 아카이빙과 로그 정리를 알아서 합니다.

3.개념 정리

3.1 Chief · PM · 전문가

SoloSquad 의 에이전트는 세 층으로 나뉩니다. 사용자는 Chief 한 명하고만 대화하면 됩니다.

각 전문가의 역할·작동 방식은 SKILL.md 라는 파일에 정의되어 있고(→ 3.4), 사용자가 일일이 호출할 필요 없이 Chief·PM 이 알아서 적합한 전문가를 붙입니다.

3.2 3가지 작업 유형 — workflow · goal · schedule

Chief 는 모든 요청을 다음 세 가지 중 하나로 분류합니다 (가벼운 대화는 분류 없이 바로 답합니다).

이 세 가지가 SoloSquad 가 일하는 방식의 전부입니다. "지금 한 번 해줘"는 workflow, "꾸준히 이 숫자를 올려줘"는 goal, "매일/매주 정해진 일을 해줘"는 schedule 로 생각하면 됩니다.

3.3 채널 구조 — command · works

사용자마다 Discord 채널 두 개가 자동으로 만들어집니다. handle 은 본인 식별자입니다(온보딩에서 정함, → 5장).

채널명이 handle 기반이라, 여러 Discord 서버를 쓰거나 나중에 다른 메신저로 옮겨도 같은 채널 쌍이 그대로 재사용됩니다. 또한 owner-only 게이트가 켜져 있으면 본인(등록된 user ID)만 Chief 의 응답을 받습니다.

3.4 SKILL.md · KNOWLEDGE.md · AGENTS.md

에이전트의 동작은 몇 가지 마크다운 파일로 정의됩니다. 평소엔 신경 쓸 필요 없지만, 동작을 커스터마이즈하려면 이 파일들을 알아두면 좋습니다.

조직별 색채는 SKILL.md 를 건드리지 않고 <org>/core/(철학·톤)·<org>/domain/(시장·고객·제품 지식) 같은 별도 파일에서 더해집니다. 사용자 코드 리포 안의 CLAUDE.md 는 Claude Code 가 그 리포에서 작업할 때 자동으로 읽습니다.

4.온보딩

4.1 내 상황 고르기

상황에 따라 진행할 절차가 다릅니다. 본인 유형을 먼저 고르세요.

4.2 신규 설치 — 첫 워크스페이스 만들기

전체 과정은 준비물 → 설치 → init 마법사 → 메신저 연결 → 봇 기동 순입니다. 메신저(Discord) 봇은 마법사 중간에 토큰을 입력하므로, 5장 §5.1 의 사전 준비(봇 토큰 발급)를 먼저 끝내두면 한 번에 진행됩니다.

# macOS
brew install node git
npm install -g @anthropic-ai/claude-code

# Windows (PowerShell)
winget install OpenJS.NodeJS.LTS
winget install Git.Git
npm install -g @anthropic-ai/claude-code

# Linux (Ubuntu)
curl -fsSL https://deb.nodesource.com/setup_22.x | sudo -E bash -
sudo apt install -y nodejs git
npm install -g @anthropic-ai/claude-code

claude login        # 브라우저 OAuth — 자격증명은 이 기기에 저장됩니다

npm install -g solosquad
solosquad --version

mkdir my-saas
cd my-saas
solosquad init

solosquad doctor            # 환경 진단 — 모두 ✓ 인지 확인
solosquad bot               # 메신저 봇 (별도 터미널)
solosquad schedule          # 자동 루틴 (별도 터미널)

4.3 기존 리포 붙이기

이미 코드 리포가 있다면 워크스페이스에 등록합니다. 이동은 1회성이라 실수 비용이 크므로 먼저 --dry-run 으로 미리보기하는 것을 권장합니다.

# 1) 기존 작업 정리
cd ~/projects/my-saas
git status && git push          # 안전망

# 2) 워크스페이스에서 미리보기 → 실제 등록
solosquad add repo ~/projects/my-saas --dry-run   # 위험 요소 점검 (디스크 변경 0)
solosquad add repo ~/projects/my-saas             # 실제 등록
#   또는 git URL 이면 clone:  solosquad add repo https://github.com/me/x.git

# 3) 검증
solosquad sync                  # repositories/ ↔ .org.yaml 정합

리포는 <org>/repositories/<repo>/ 로 들어가며, 리포 자체의 .git·CLAUDE.md·.claude/skills/ 는 그대로 보존되어 작업 시 자동 로드됩니다. 조직이 여러 개면 어느 조직에 붙일지 묻고, 하나면 자동 배정합니다.

4.4 버전 업데이트

두 가지가 별개입니다 — update(CLI 패키지 갱신)와 migrate(워크스페이스 구조 정합). solosquad doctor 가 둘 중 무엇이 필요한지 알려줍니다.

# 1) CLI 갱신
solosquad update                 # 최신 비교 + 자동 설치
#   또는: npm install -g solosquad@latest

# 2) 구조 변경이 포함된 경우에만 — 워크스페이스 정합
solosquad migrate --dry-run      # 미리보기 (변경 0)
solosquad migrate --apply        # 적용 (자동 백업 → 적용 → 검증)
solosquad migrate --rollback     # 직전 백업으로 복원 (필요 시)

5.메신저 연결

AI 가 메신저에서 대화하려면 봇 계정이 필요합니다. v1.0 의 공식 메신저는 Discord 한 종류입니다 (Slack 어댑터는 코드에 동봉되나 post-v1.0 슬롯). 한 워크스페이스당 메신저 하나를 씁니다.

전체 흐름은 ① Developer Portal 사전 준비 → ② init 마법사 → 자동 초대 URL → ③ 서버 추가 + 채널 자동 생성 입니다. 한 번 클릭으로 끝나도록 설계되어 있습니다.

5.1 사전 준비 — Discord Developer Portal

init 을 실행하기 전에 봇을 하나 만들어 토큰을 받아둡니다.

5.2 init → 초대 → 채널 자동 생성

§4.2 의 init 마법사에서 위 봇 토큰을 입력하면, 나머지는 대부분 자동입니다.

5.3 동작 검증

solosquad bot                 # 봇 기동
solosquad doctor --discord    # 5단계 진단 (다른 터미널)
#  ✓ 토큰  ✓ /users/@me  ✓ bot_user_id 매칭  ✓ 길드 멤버십  ✓ 채널 등록

#command-<handle> 에 안녕 → Chief 가 **[이름]** ... 형태로 답하면 전 구간 정상입니다. 문제가 있으면 doctor --discord 가 어느 단계에서 막혔는지와 다음 조치를 알려줍니다.

6.사용법

6.1 기본 대화 흐름

일하는 방식은 단순합니다. #command-<handle> 채널에서 평소 말하듯 요청하면, Chief 가 의도를 분류해 처리합니다 (→ 3.2 의 3가지 작업 유형).

• 가벼운 질문·대화 → 그 자리에서 바로 답합니다.
• 여러 단계가 필요한 일 → workflow 로 잡아 #works-<handle> 에 작업 카드 + 진행 thread 를 만들고, 전문가들을 단계별로 호출합니다.
• 의도를 명확히 하고 싶을 때 → 슬래시 명령을 씁니다.

나: 랜딩페이지 히어로 카피 다시 써줘
Chief: (Content Writer 호출) — 3개 버전 초안입니다. ...

나: /plan 가격 정책 개편
Chief: PRD 작성 → 단계 분해 → #works 채널에 등록했습니다.

요청에 @<repo> 를 붙이면 특정 저장소를 대상으로 지정할 수 있습니다 (예: "@my-api 회원가입 엔드포인트 추가해줘").

6.2 명령어

일상에서 가장 자주 쓰는 명령입니다 (전체는 solosquad --help).

6.3 자동 루틴 (schedule)

solosquad schedule 가 정해진 시각에 다음을 자동 실행합니다. 사용자가 보는 브리프는 #works-<handle> 에 올라옵니다.

시각·활성화는 .solosquad/workspace.yaml 의 timezone·briefings 를 편집해 본인 생활 패턴에 맞춥니다. 특정 루틴을 즉시 돌려보려면 solosquad run-routine morning-brief.

6.4 추천 첫 작업

1. solosquad doctor 가 모두 ✓ 인지 확인합니다.
2. #command-<handle> 에 안녕 → Chief 응답 확인.
3. 나를 소개합니다 — Chief 에게 본인·사업·목표를 한 단락으로 알려주면, 이후 응답의 맥락이 잡힙니다 (원칙·톤은 <org>/core/ 에 기록됩니다).
4. 작은 workflow 하나 — 예: "이번 주 핵심 가설 1개와 검증 방법 정리해줘". #works 채널에 작업 카드가 생기는지 봅니다.
5. 브리프 시각 조정 — workspace.yaml 의 morning/evening 시각을 본인 루틴에 맞춥니다.

7.운영 가이드

7.1 24/7 실행 방식

봇이 메신저 연결을 유지하려면 solosquad bot (그리고 schedule)이 계속 떠 있어야 합니다. 상황에 맞는 방식을 고르세요.

# 로컬 — 터미널 두 개
solosquad bot
solosquad schedule

# Docker — 워크스페이스에서
docker compose up -d --build
docker compose logs -f bot

7.2 업데이트 & 봇 재기동 v1.2.8~9

업데이트(§4.4) 시 봇을 수동으로 끄고 켤 필요가 없습니다. 환경별로 동작이 다릅니다.

7.3 여러 사업 · 저장소

한 워크스페이스 안에 조직(=사업/제품)을 여러 개 둘 수 있고, 각 조직은 메모리·워크플로·채널이 완전히 격리됩니다.

solosquad add org my-side                          # 새 조직 추가 (대화형)
solosquad add repo https://github.com/foo/bar.git  # clone + 등록
solosquad add repo ./local-repo                    # 로컬 등록
solosquad sync                                      # repositories/ ↔ .org.yaml 정합

조직 자동 판정: --org 명시 → 조직 하나면 자동 → cwd 가 조직 폴더 안이면 그 조직 → 그 외엔 대화형 선택. 하나의 workflow 안에서 단계마다 다른 저장소를 대상으로 지정하는 cross-repo 작업도 가능합니다.

페르소나 분리가 필요하면(본업 vs 사이드) 워크스페이스 자체를 여러 개 만듭니다 — 각각 독립된 봇·토큰·메모리를 가집니다. CLI 업데이트는 한 번이지만 마이그레이션은 워크스페이스마다 개별 실행합니다.

7.4 보안 & 백업

• 토큰 보호 — .env 는 자동으로 gitignore 됩니다. 봇 토큰은 주기적으로(예: 90일) 교체하세요.
• 최소 권한 — 초대 URL 의 권장 권한 이상을 주지 않습니다. owner-only 게이트로 본인만 명령할 수 있게 합니다.
• 출력 검토 — AI 가 만든 결과를 프로덕션에 반영하기 전에 반드시 검토합니다. 민감한 명령(git push 등)은 확인 게이트를 거칩니다.
• 백업 — 마이그레이션 백업은 solosquad backup list 로 조회하고 오래된 것은 solosquad backup purge --keep-recent 3 로 정리합니다. 워크스페이스 전체 아카이브는 solosquad uninstall --mode archive-only 로 만들고, 외부 저장 전 solosquad archive verify 로 무결성·PII 를 점검합니다.
• 클라우드 운영 — SSH 키 인증만 허용하고 방화벽은 아웃바운드 위주로 설정합니다.
• 로그 — solosquad logs --follow 로 실시간 확인. 비용·spawn·확인 게이트 로그를 한곳에서 봅니다.

8.용어 사전

AI/개발 초보자가 이 문서나 코드를 읽다 막힐 만한 모든 용어와 파일명을 친절히 설명합니다.

8.1 핵심 용어

Workspace (워크스페이스)

SoloSquad 사용자의 최상위 폴더. 보통 ~/solosquad-workspace. 안에 1개 이상의 organization을 담는다. 워크스페이스는 사용자 한 명의 "AI 비서 본부".

Organization (조직, org)

워크스페이스 안의 사업/제품 단위. 예: 본업, 사이드 프로젝트. 각자 메모리·워크플로·메신저 채널이 분리된다. 폴더명이 <slug>가 됨 (예: my-startup).

Repository (리포지토리, repo)

실제 코드가 있는 git 저장소. 조직 1개에 여러 repo가 있을 수 있다. 위치: <workspace>/<org>/repositories/<repo>/.

Agent (에이전트)

한 역할(예: Business Strategist)을 수행하는 AI 일꾼. SoloSquad는 25명의 specialist + 1명의 PM(v0.3+)이 있음.

Specialist (스페셜리스트)

특정 도메인 전문가 agent. 25명. PM(orchestrator)과 구분.

PM / Orchestrator (PM, 오케스트레이터)

사용자와 직접 대화하는 영구 에이전트. v0.3에서 도입. specialist를 spawn해서 멀티 단계 워크플로를 진행.

SKILL.md

한 agent의 정체성·작동 방식을 적은 매뉴얼 파일. Anthropic Agent Skills 공식 포맷.

KNOWLEDGE.md (v0.6)

한 팀(=도메인)의 공유 craft·정의·anti-pattern을 모은 파일. agents/{team}/KNOWLEDGE.md 위치 (v0.6 co-location). 같은 팀 agent가 spawn될 때 8-layer assemble의 [2] layer로 자동 inject.

Org Layer (v0.6)

조직별 색채를 흡수하는 3 신설 자산. <org>/core/{PRINCIPLES,VOICE}.md (조직 철학·톤) + <org>/agent-profile.yaml (25 agent modifier + budget) + <org>/domain/ (조직 도메인 지식). 워크스페이스 SKILL은 한 줄도 안 변경, 조직 색채는 이 3 자산에서만 들어옴.

Workspace Knowledge (v0.6)

.solosquad/knowledge/ — 사용자 누적 공용 지식 (의사결정 프레임워크·도메인 용어집). agent SKILL.md를 짧게 유지하기 위해 craft·도메인 지식을 분리. 키워드 매칭 시 selective inject.

8-layer JIT inject (v0.6)

spawn 시점에 workspace knowledge → team KNOWLEDGE → agent SKILL → org core → agent-profile → org domain → memory/handoff → repo 순으로 컨텍스트를 조립. max_context_tokens 도달 시 우선순위 낮은 layer부터 drop. §2.5 참조.

Budget envelope (v0.5 author + v0.6 agent)

paperclip 차용 LLM 호출 cap. v0.5에서 author 루프에만 적용, v0.6에서 org × agent 단위로 일반화. agent-profile.yaml의 budget.daily_usd / weekly_usd / on_cap_action. 도달 시 spawn 거부 + PM 응답. 누적은 <org>/memory/agent-costs.jsonl.

FTS5 cold archive (v0.6)

<org>/memory/archive.sqlite — 8일 이상 된 JSONL을 SQLite FTS5 가상 테이블로 옮겨 검색 가능 형태로 보관. 매일 00:00 archive-rotate routine 자동 수행. 4 event_type 인덱싱(route_hit / route_miss / author_turn / spawn_decision) + 기존 routine_log. 라우터 미스 시 fallback 회상.

Trajectory 추출 (v0.6)

같은 (agent sequence + workflow template) 조합이 30일 내 3회+ 발생 시 자동 SKILL draft 제안. 야간 pm-compaction 단계. v0.5 applyDraft() 직접 재사용 (코드 중복 0). 자동 등록 없음 — 사람 게이트 유지.

Freq miner (v0.6)

FTS5 route_miss + author-draft 명확화 질문 N-gram → 기존 SKILL의 triggers.keyword에 추가 제안. applyDraft({ mode: "frontmatter-only" })로 본문 무변경 + frontmatter만 패치.

Stop-hook DSL (v0.6)

v0.5 loop_mode.spec-gate를 Anthropic 2025-12 stop-hook 플러그인으로 실 작동. 3 형식: command (exit 0) · metric (results.tsv 임계) · natural (LLM fallback + budget cap). 5초 timeout, 실패 시 보수적으로 계속.

collab_pattern (v0.6)

SKILL.md frontmatter 정식 필드 (v0.5에선 extra bag 처리). hierarchical | graph | dynamic. 25 agent 분배: 22 hierarchical · 2 graph (data-analyst, feature-planner) · 1 dynamic (content-writer). spawn 시 해당 변형 핸드오프 템플릿 자동 적용.

Hot-reload (chokidar, v0.6)

fs.watch 기반 라우터 자동 재빌드. 3-tier watch (workspace · org · user-global) + 300ms debounce + atomic swap. workspace.yaml.fs_watch.mode: auto / prompt (기본) / manual. git_only 안전 모드는 HEAD ≡ upstream + clean tree만 허용.

schema_version: 1 (v0.6)

v0.6 신설 자산(.org.yaml · agent-profile.yaml · v0.6 ledger)에 부착된 forward-compat 플래그. v0.7 마이그레이션이 version 체크로 호환성 분기.

Routine (루틴)

정해진 시각에 자동 실행되는 작업. SoloSquad에는 5종 (Morning Brief, Signal Scan, Experiment Check, Evening Brief, Weekly Review).

Workflow (워크플로)

여러 단계의 작업을 묶은 프로젝트. PMF Discovery·Feature Expansion·Rebranding·Rapid Prototype 4종 디폴트. 각 워크플로는 <org>/workflows/<id>/ 폴더로 존재.

Stage (스테이지)

워크플로 안의 한 단계. stage-1-research/ 같은 폴더로 산출물 저장.

Handoff (핸드오프)

한 stage가 끝날 때 다음 agent에게 컨텍스트를 넘기는 산출물. _handoff.md 파일에 Summary·Artifacts·Decisions 등 표준 섹션으로 작성.

Brief (브리프)

아침/저녁에 봇이 전달하는 요약 보고. Morning Brief = 야간 일과 + 오늘 예정. Evening Brief = 주간 일과 + 야간 예정.

Signal Scan (시그널 스캔)

시장에서 관련된 신호(트렌드·경쟁사 움직임·뉴스)를 자동으로 탐지하는 routine. 결과는 signals.jsonl에 누적.

Experiment Check (실험 점검)

진행 중인 가설/실험의 상태를 점검하는 routine. experiments.jsonl에 누적.

Agent Router (에이전트 라우터)

사용자 메시지를 보고 어떤 specialist를 호출할지 결정하는 모듈. v0.5에서 4채널 trigger(slash > explicit > keyword > freq) + 3-tier 검색 + atomic swap hot-reload로 진화. AGENT_ROUTES 하드코딩은 제거되고 각 SKILL.md의 triggers frontmatter에 분산.

Spawn (스폰)

PM(또는 router)이 specialist agent를 새 fresh session으로 시작시키는 동작. 매번 독립 — state는 외부 파일에 보관. v0.3+는 PM이 내장 Task tool로 spawn하며 [stage:<id> wf:<id>] 마커를 프롬프트에 부착.

4채널 라우팅 (v0.5)

SKILL 매칭 4채널 — slash(명시 의도) > explicit(PM 직접 호출) > keyword(1턴 매칭) > freq(N턴 누적 빈도 임계). 각 SKILL.md frontmatter의 triggers 필드가 부트 시 라우터 인덱스로 수집됨.

Freq cooldown (v0.5)

한 번 freq 채널로 자동 로드된 SKILL은 cooldown_turns (기본 6) 동안 재발화 금지 (hysteresis). 같은 주제 장기 대화 시 잡음 회피. 상태는 <org>/.solosquad/sessions/<user>.json의 freqCooldowns 필드에 매 턴 decay.

Hot-reload / Atomic swap (v0.5)

새 SKILL.md 저장 시 라우터 인덱스를 background로 재빌드 → ref 교체. 빌드 중 도착한 메시지는 이전 인덱스로 처리. 봇 재시작 불필요.

Author 루프 (v0.5)

메신저에서 PM과 1-2턴 대화로 새 SKILL.md를 만드는 5단계 상태기 (CLARIFY → DRAFT → SANDBOX_PROMPT → AWAIT_CONFIRM → APPLIED). assets/agents/_meta/workflow-maker/SKILL.md 메타-skill이 시스템 프롬프트.

Spec-gate / Loop mode (v0.5)

SKILL.md loop_mode.kind: spec-gate면 Ralph 루프(stop_when 조건) 모드. author 루프가 자동으로 <org>/goals/<goal-id>/goal.md도 emit → v0.4 goal-runner에 자율 cycle로 등록.

3-tier SKILL 검색 (v0.5)

같은 이름 SKILL이 있을 때 우선순위: <org>/.agents/ > ~/.solosquad/agents/ > <workspace>/.solosquad/agents/ (번들). 상위 계층이 override.

Stateless / Stateful (무상태/유상태)

매 호출이 독립이면 stateless, 호출 간에 state를 들고 있으면 stateful. SoloSquad의 specialist는 stateless, PM session은 stateful.

JIT (Just-in-Time) Injection

모든 컨텍스트를 미리 로드하지 않고 *그 호출에 필요한 것만* 그때그때 주입하는 원칙. 토큰 비용 폭증 방지.

Memory (메모리)

routine·결정·신호 결과를 영속 저장하는 곳. v0.6 기준 JSONL append-only(signals/experiments/decisions/author-costs/agent-costs/spawn-decisions/stop-hook-events/migration-costs) + PM compaction 외부화(memory/pm-skills/) + per-org snapshot.git + FTS5 cold archive(archive.sqlite — 8일+ 자동 이전, 4 event_type 인덱싱).

P/E/T (Persistent / Episodic / Transient)

메모리를 영속/에피소드/일시 3계층으로 분류하는 어휘. SoloSquad의 SKILL은 Persistent, workflows는 Episodic, Claude session prompt는 Transient.

3-Layer Context

워크스페이스(Layer 0) / 조직(Layer 1) / 리포(Layer 2) 3 계층. 데이터 격리의 기본 단위.

PRD (Product Requirements Document)

제품 요구사항 문서. PM이 작성하여 specialist들에게 전달.

PMF (Product-Market Fit)

제품-시장 적합도. 사업이 "이 제품이 정말 필요한 시장이 있는가"를 검증하는 단계.

GTM (Go-To-Market)

시장 진입 전략. 어떤 채널·메시지·가격으로 첫 사용자를 얻을지 계획.

Anthropic / Claude

Anthropic은 Claude AI 모델을 만든 회사. Claude Code는 Anthropic이 만든 코딩 CLI. SoloSquad는 Claude Code를 백엔드 엔진으로 사용.

Claude Code

Anthropic이 만든 범용 코딩 CLI 도구. SoloSquad는 이 도구의 claude 명령을 호출해 AI 응답을 받는다. 별도 설치 필요: npm install -g @anthropic-ai/claude-code.

npm (Node Package Manager)

Node.js 패키지(라이브러리·CLI) 설치 도구. npm install -g solosquad로 SoloSquad 설치.

CLI (Command Line Interface)

명령줄 인터페이스. 터미널에서 명령어를 쳐서 사용하는 프로그램. solosquad가 CLI.

cron (크론)

정해진 시각에 작업을 반복 실행하는 표준 스케줄 형식. SoloSquad의 routine은 cron 기반.

JSONL (JSON Lines)

한 줄 = 한 JSON 객체인 텍스트 파일 포맷. append-only로 이벤트를 누적할 때 유용. SoloSquad 메모리의 기본 포맷.

FTS5 (Full-Text Search version 5)

SQLite 내장 전문검색 확장. 키워드 기반으로 텍스트를 빠르게 찾는다. v0.6에서 메모리 archive 인덱스로 정식 도입 (better-sqlite3 ^12.10.0 의존성).

MCP (Model Context Protocol)

AI 에이전트와 외부 도구·데이터를 잇는 표준 통신 규약. Anthropic이 2024년 발표. SoloSquad는 외부 연결(Notion·Figma 등)에 MCP 사용 가능.

IANA tz (시간대 데이터베이스)

국제 표준 시간대 이름 (예: Asia/Seoul, America/Los_Angeles). workspace.yaml의 timezone 값에 사용.

YAML

사람이 읽기 쉬운 설정 파일 포맷. SoloSquad는 workspace.yaml, .org.yaml, _status.yaml 등에 사용. JSON보다 들여쓰기로 구조를 표현.

Frontmatter (프론트매터)

Markdown 파일 맨 위에 ---로 감싼 YAML 메타데이터. SKILL.md의 name·description·triggers 등이 frontmatter.

Docker / docker-compose

컨테이너 가상화 도구. SoloSquad 봇·스케줄러를 백그라운드로 자동 재시작하며 돌리고 싶을 때 사용. 선택 사항.

VPS (Virtual Private Server)

클라우드의 가상 서버. PC를 24/7 켜둘 수 없을 때 SoloSquad를 클라우드에서 실행. 월 $4~6.

Slug

URL/폴더 친화적 이름. 소문자·하이픈만 사용. 예: "My Startup" → my-startup.

8.2 파일명 사전

워크스페이스나 코드에서 마주칠 모든 파일의 의미.

.env

환경 변수(API 토큰 등) 비밀 값을 담는 파일. SLACK_BOT_TOKEN·DISCORD_TOKEN 등. 절대 git에 커밋하지 말 것.

.env.example

.env의 템플릿. 어떤 변수를 채워야 하는지 보여주는 샘플. 토큰 값은 비어 있음. git에 포함 OK.

.gitignore

git이 추적하지 않을 파일 패턴. SoloSquad에서 .env·node_modules·dist·repos 등이 무시됨.

.npmignore

npm 패키지 배포 시 제외할 파일 패턴. dev 전용 파일들.

package.json

npm 패키지의 설명서. 이름·버전·의존성·실행 스크립트 명세. SoloSquad의 solosquad 명령이 어디서 시작되는지도 여기에 적혀 있음.

package-lock.json

의존성 버전을 정확히 고정한 자동 생성 파일. 직접 편집 안 함.

tsconfig.json

TypeScript 컴파일 설정. ES2022·strict 모드 등.

workspace.yaml

워크스페이스 전역 설정. .solosquad/workspace.yaml. timezone·briefings·background_routines 시각, 메신저 종류 등.

.org.yaml

조직별 설정. <org>/.org.yaml. 조직 이름·메신저·등록된 repo 목록.

repo.yaml

리포별 설정. <repo>/.solosquad/repo.yaml. repo slug·역할(main/sub)·target_org.

SKILL.md

에이전트 정의 매뉴얼. Anthropic Agent Skills 포맷. §3.1 참조.

KNOWLEDGE.md (v0.6)

팀(=도메인) 공유 지식. agents/{team}/KNOWLEDGE.md. §3.2 참조.

TEAM_KNOWLEDGE.md (v0.2.4, v0.6에서 폐지)

v0.6에서 agents/{team}/KNOWLEDGE.md로 이름·위치 변경되었습니다. _teams/ 평행 hierarchy는 완전 제거.

agent-profile.yaml (v0.6)

<org>/agent-profile.yaml. 25 agent의 조직별 modifier (tone·emphasis·voice·ban_phrases·budget). defaults + agent별 섹션 + schema_version: 1.

archive.sqlite (v0.6)

<org>/memory/archive.sqlite. FTS5 cold archive. 8일+ JSONL 이전 + 4 event_type 인덱싱 + retention 365일.

CLAUDE.md

Claude Code가 매 세션 자동 로드하는 프로젝트 지침. §3.3 참조.

OWNER.md

사용자 본인의 프로필·관심사·작업 패턴. 모든 agent가 매 세션 참조. assets/core/OWNER.md.

PRINCIPLES.md

본인의 의사결정 원칙. 모든 agent가 따라야 할 가이드. assets/core/PRINCIPLES.md.

VOICE.md

본인의 글쓰기 톤·문체. Content Writer 등 글을 쓰는 agent의 출력 톤 가이드. assets/core/VOICE.md.

_status.yaml

워크플로 진행 상태. 각 stage가 pending → in_progress → completed 어느 상태인지.

_handoff.md

stage 완료 시 다음 agent에게 전달하는 컨텍스트. Summary·Artifacts·Decisions·Open Questions 표준 섹션.

_events.jsonl (v0.3+)

PM session의 모든 이벤트 로그. PM 메시지·spawn·subagent 완료 등.

signals.jsonl

Signal Scan routine의 결과. 시장 신호를 한 줄씩 누적.

experiments.jsonl

Experiment Check routine의 결과. 진행 중 실험 상태.

decisions.jsonl

Evening Brief·Weekly Review에서 정한 결정 누적.

routine-logs/*.jsonl

routine 실행 전체 로그. 디버깅·회고에 사용.

Dockerfile (deploy/docker/Dockerfile)

Docker 이미지 빌드 레시피. SoloSquad 봇/스케줄러를 컨테이너로 만들 때. v0.5부터 deploy/docker/로 이동.

docker-compose.yml (deploy/docker/docker-compose.yml)

여러 컨테이너(bot + scheduler)를 한 번에 실행하는 설정. v0.5부터 ~/.solosquad/ + ~/.solosquad-backups/도 마운트 — user-global SKILL override와 backup 호환.

README.md

프로젝트 첫인상 문서. npm/GitHub에 표시되는 메인 설명. SoloSquad의 README는 설치·빠른 사용법.

LICENSE

라이선스 파일. SoloSquad는 MIT 라이선스.

CONTRIBUTING.md

이 프로젝트에 기여하는 방법 안내 (개발자용).

8.3 약어 사전

API

Application Programming Interface. 소프트웨어 간 통신 규약. Slack API·Claude API 등.

CAC

Customer Acquisition Cost. 고객 1명을 얻는 데 드는 비용. 마케팅 지표.

CLI

Command Line Interface. 명령줄 도구.

CRUD

Create·Read·Update·Delete. 데이터의 기본 4 연산.

DAG

Directed Acyclic Graph. 방향성 있고 순환이 없는 그래프. 워크플로 단계 의존성 표현.

E2E

End-to-End. 전체 사용자 흐름을 테스트하는 방식.

ESM

ECMAScript Module. JavaScript 모듈 표준 (Node16+).

FDE

Forward Deployed Engineer. 고객 현장에 깊이 들어가는 엔지니어. SoloSquad 엔지니어링 팀의 한 agent.

FTS5

Full-Text Search v5. SQLite 내장 전문검색 확장.

GTM

Go-To-Market. 시장 진입 전략.

IANA

Internet Assigned Numbers Authority. 인터넷 표준 명명을 관리하는 기관. SoloSquad는 IANA의 시간대 이름(Asia/Seoul 등)을 사용.

JIT

Just-in-Time. 필요한 순간에만 로드/실행. 컨텍스트 관리 원칙.

LTV

Lifetime Value. 한 고객으로부터 얻는 전체 매출. LTV:CAC ≥ 3:1이 SaaS 통상 건강 지표.

MCP

Model Context Protocol. AI ↔ 외부 도구 표준.

npm

Node Package Manager. JavaScript 패키지 관리자.

PaaS

Platform-as-a-Service. 서버 관리 없이 앱만 올리면 되는 클라우드. Railway·Fly.io.

PMF

Product-Market Fit. 제품-시장 적합도.

PRD

Product Requirements Document. 제품 요구사항 문서.

QA

Quality Assurance. 품질 보증·테스트.

SaaS

Software-as-a-Service. 구독형 소프트웨어.

SDK

Software Development Kit. 특정 플랫폼에 앱 만들 때 쓰는 도구 모음.

SQL

Structured Query Language. 데이터베이스 질의 언어.

SSH

Secure Shell. 원격 서버 접속 프로토콜. VPS 운영 시 사용.

TS

TypeScript. JavaScript에 정적 타입을 더한 언어. SoloSquad의 구현 언어.

TTL

Time-To-Live. 데이터/캐시 유효 시간.

tz

timezone (시간대) 약어.

UI / UX

User Interface (사용자 인터페이스) / User Experience (사용자 경험).

VPS

Virtual Private Server. 가상 사설 서버. 클라우드.

YAML

YAML Ain't Markup Language. 사람이 읽기 쉬운 설정 파일 포맷.

9.CHANGELOG

출시된 모든 버전의 핵심 변경 사항. 완전한 release note 는 CHANGELOG.md 참조 — 본 절은 메뉴얼 단독으로도 읽을 수 있도록 같은 내용을 정리.

9.1 출시된 버전 (npm 배포 완료)

v1.2.9 (2026-06-01) 최신 — Discord App ID 자동 감지 + Invite URL 복구 · git 채널 · 대화 UX · 작업취소 · 권한토글

• 온보딩에서 앱 ID 를 안 묻고 / 초대 URL 이 자동 생성 안 되던 결함 정정 — v1.2.6 가 설계한 OAuth Invite URL 1-click 흐름이 존재하지 않는 API 필드 1개 때문에 출시 이래 한 번도 작동 안 함. fetchBotIdentity 가 GET /users/@me (봇 User 객체) 에서 application_id 를 읽었으나 그 필드가 없음 → appId 영구 undefined → init 종료 시 invite URL 블록 항상 skip + 앱 ID prompt 부재 + 후속 discord invite-url 실패
• 정식 엔드포인트로 자동 감지 — GET /oauth2/applications/@me 로 application id 조회 (봇 토큰 auth). 실패 시 봇 user id 로 폴백 (Discord 봇은 봇 user id == application id 동일 snowflake)
• Application ID 확인 prompt 신설 — init Step 3.5 에서 자동 감지값을 기본으로 표시, Enter 1회 수락. 감지 실패 시 Developer Portal → General Information → Application ID 붙여넣기 안내 (17~20자리 검증)
• solosquad doctor --discord Hop 2 동반 수정 — app id 를 같은 엔드포인트로 채워 Hop 3 bot_application_id missing 경고 + Hop 4 invite URL 힌트가 실작동
• 순효과 — Discord 경로 init 완주 → 앱 ID 자동 감지 + Enter 확인 → 종료 시 invite URL 출력 + 브라우저 자동 open. v1.2.6 의 "완주 → click 1회 → 5분 내 채널 자동 생성" 약속 비로소 실현
• git 이벤트 채널 + 대화 UX (Part B·C) — git-<handle> 채널 신설(에이전트 push 알림 피드 — 채널·설정은 작동, 알림 실작동은 v1.3.0). Chief 가 대화 surface(Discord/Slack/CLI)를 인지하고, 메신저 응답을 통째로 코드블록으로 감싸지 않으며 말끝 -이름 서명을 제거. solosquad chat 으로 터미널에서도 Chief 와 대화
• 작업 취소 /cancel (Part D) — 진행 중인 작업을 디스코드/터미널에서 즉시 중단. 기존엔 두 번째 메시지가 큐에 쌓여 대기만 했음
• dev 권한 토글 /grant·/revoke (Part E) — 에이전트가 파일 쓰기·git 권한에 막혀 멈추던(hang) 문제 해결. dev 모드 ON 이면 spawn 에 acceptEdits + 허용 도구를 주입(파일쓰기·git add/commit/checkout/branch·npm, push·PR merge 제외). 온보딩 기본 ON, /revoke 로 read-only 전환
• 상세: CHANGELOG.md §[1.2.9], docs/prd/v1.2.9-discord-app-id-fix-and-git-events-channel.md (+ v1.3.0-dev-confirm-gate-live.md 설계)

v1.2.8 (2026-05-29) — Bot 재기동 자동화 + ESM/CJS fix

• v1.2.7 의 --add-dir wiring 실작동 복구 — chief-runner.ts 의 helper 들이 ESM 컨텍스트에서 require("fs"|"path"|"js-yaml") 호출 → silent throw → addDirs 빈 배열 → --add-dir spawn 에 안 들어감. v1.2.8 가 top-level import 로 교체 → 실제로 모든 등록된 repo 에 봇이 자유롭게 접근
• 봇 PID 파일 + migration 자동 SIGTERM — <workspace>/.solosquad/bot.pid 에 봇 PID 박제. solosquad migrate --apply 가 마이그레이션 성공 후 그 PID 에 SIGTERM 전송 → 클라우드 (systemd / PM2 / Docker restart: unless-stopped) 자동 respawn. 사용자는 systemctl restart / docker compose restart 입력 불필요
• solosquad bot --supervise — 로컬 wrapper. 자식으로 solosquad bot spawn → child 종료 감지 → 1.5초 후 자동 respawn. 3회 연속 crash 시 포기. 로컬 사용자도 process manager 없이 migration 자동 재기동 받을 수 있음
• Graceful drain on SIGTERM — 봇이 Chief turn 진행 중 SIGTERM 받으면 즉시 종료 안 함. 현재 turn 의 응답 송신까지 최대 120s 대기 → clean exit. 사용자는 *침묵 대신 응답 정상 수신*. 두번째 signal (Ctrl+C 한 번 더) 받으면 강제 exit
• Pre-publish ESM purity gate — npm run prepublishOnly 가 dist/**/*.js grep 으로 bare require( 검출 시 publish 차단. 같은 종류 사고 재발 방지. 주석 / 문자열 / createRequire(import.meta.url) 정당한 케이스 skip
• 상세: CHANGELOG.md §[1.2.8], docs/prd/v1.2.8-bot-restart-and-esm-fix.md

v1.2.7 (2026-05-29) — Bot spawn --add-dir (broken-as-published)

npm publish 완료 됐으나 ESM/CJS 표기 결함으로 wiring 이 실작동 안 함. v1.2.8 이 정정 + chain. 1.2.7 신규 install 불필요 — 사용자는 1.2.8 부터 받으면 됨.

• 봇이 매 spawn 마다 <org>/repositories/*.yaml 스캔 → 등록된 repo path 전부 모음 → claude --print --add-dir <path1> <path2> ... spawn 인자로 전달 (의도). 사용자가 */add-dir 슬래시 명령 직접 실행* 안 해도 봇이 자동 권한 확보 (의도)
• Chief 와 대화로 새 repo 클론 시 기본 위치 = 기존 등록 repo 의 공통 부모 디렉토리 (동적 계산, 사용자별로 다름)
• v0.x 시절 migrate / sync CLI 메시지의 path-reference 모델 정합 (in-workspace clone 안내 제거)
• 상세: CHANGELOG.md §[1.2.7]

v1.2.6 (2026-05-29) — Onboarding & Vocabulary Polish

• workspace 탐지 strict — .solosquad/ 디렉토리만으로 워크스페이스 판정 안 함. workspace.yaml 존재까지 가드 → cd <org> 에서 봇 실행해도 잘못된 루트 안 잡힘 (legacy owner-command / workflow 채널 fallback 결함 해소)
• messenger_user_id 자동 채움 — init Step 3.5 prompt + 첫 메시지 hydration. owner-only 게이트가 fail-open 으로 끝나지 않고 진짜 동작
• Slack picker 임시 비활성 — Discord 단독 선택, picker 단계는 유지 (v1.2.x adapter 슬롯 활성화 시 복원)
• Path 따옴표 strip — solosquad add repo "C:\path" 의 양옆 따옴표 자동 제거. PowerShell / Explorer "Copy as path" 패턴
• Claude Code trust 자동 grant — 봇이 claude --print spawn 할 때 디렉토리 trust 다이얼로그 안 띄움. scaffoldOrg + init repo loop + add repo 셋 다 ~/.claude.json 에 박제. v1.2.3 → v1.2.6 migration 이 기존 org cwd + 등록된 repo 경로 전부 backfill — solosquad migrate --apply 1회로 과거에 등록한 repo 모두 trust 적용
• Chief 정체성 plumbing — 봇 응답 prefix [Hermes] (chief_name 기준). LLM system prompt 에 [identity] 1줄 inject 로 Chief 가 자기 이름으로 self-reference
• Chief 이름 prompt 보강 — 6 surface 설명 + 7 예시 (Hermes / Atlas / Apollo / Iris / Janus / Athena / Hephaestus)
• 어휘 정합 — [Bot] PM turn → [Bot] Chief turn, PM sessions: → Chief sessions:, 등 사용자 대면 라벨. jsonl event kind pm.* 는 schema_version 호환을 위해 유지
• 매뉴얼 §5 재배치 — Discord = §5.1 (was §5.2), Slack = §5.2 (was §5.1). §5.1 Discord 본문 v1.2 정합 재작성 — 옛 "서버 이름 = 제품 slug" 규칙 제거, command-<handle> / works-<handle> 채널 모델 반영
• §10 FAQ 맨 아래로 — 10.3 Uninstall / 10.4 봇·스케줄러 / 10.5 FAQ
• 상세: CHANGELOG.md §[1.2.6], docs/prd/v1.2.6-onboarding-and-vocabulary-polish.md (npm 1.2.4 / 1.2.5 burned, 실제 publish 슬롯 1.2.6)

v1.2.3 (2026-05-28) — Bundle-files hotfix

• npm 패키지 화이트리스트 수정 — v1.2.2 publish 때 누락된 root-level bundle 디렉토리 (agents/ · skills/ · teams/ · schedules/ · user/ · knowledge/) 를 package.json.files 에 추가. tarball 567 → 652 파일
• v1.0.4 → v1.1.0 migration verify 통과 복구 — chief SKILL.md + 4 teams OKR + problem-definition workflow.yaml 누락 결함 해소
• 상세: CHANGELOG.md §[1.2.3], docs/prd/v1.2.3-bundle-files-hotfix.md

v1.2.0 ~ v1.2.2 (2026-05-28) — Messenger Connection (Chief on Discord)

v1.2.0/v1.2.1 은 pre-launch 시기 burned (npm 재사용 불가), v1.2.2 는 bundle 누락으로 broken → 사실상 v1.2.3 이 series 첫 usable publish.

• 조직 1개당 1 Chief 봇 — OrgYaml.chief_name, Discord Developer Portal Bot 이름과 동일 권장
• OAuth Invite URL 1-click — solosquad discord invite-url 가 권장 권한 bitfield (10 perms, verification trigger 6건 배제) 합성 + 브라우저 자동 open + clipboard fallback
• handle 기반 채널 portability — 멀티 Discord 서버 / 추후 Slack 모두 같은 command-<handle> / works-<handle> 페어 자동 재사용
• owner-only 게이트 — message.author.id === user.yaml.messenger_user_id. v1.0.2 author-guard 제거의 *실제* 사유 (= 채널명이 user-id 라 봇 인식 실패) 가 handle 기반 채널로 해소된 이상 reversal 정당. 신규 설치 default ON, 업그레이드 default OFF (neutral)
• TRIAGE kind 분기 — Chief 가 응답 첫 줄에 [kind:chat|workflow|schedule|goal] 출력. chat 은 command 채널 평탄, workflow/schedule/goal 은 works-<handle> 에 task card embed + thread + stage narration (DECOMPOSE / DISPATCH / AWAIT)
• solosquad add-org 가 새 조직을 완전 동작 상태로 부트스트랩 — Chief 이름 + v1.1.0 전체 위계 (agents/main/chief, 4 teams, memory/{open-questions,ledger}, knowledge/) + problem-definition workflow 기본 시드
• guildCreate onboarding embed + 2 button (Auto-create / Manual choose), /chat slash command (MESSAGE_CONTENT intent fallback)
• solosquad doctor --discord 5-hop diagnostic — token shape → REST /users/@me → bot_user_id match → guild membership → command 채널 ID
• 상세: CHANGELOG.md §[1.2.2], docs/prd/v1.2-messenger-connection-discord-first.md

v1.1.0 (2026-05-27) — Multi-Agent Team Architecture

• Single PM session → Team-Centric Multi-Agent
• Chief (org-level supervisor, 유일한 사용자 대면) + PM (workspace-bundle, 자율 product manager, 사용자와 직접 대화 안 함) 역할 분리
• 4 main bot (chief / pm / engineer / designer / marketer) + 20 specialist (평탄, 4 병합 + paid→performance rename) + 18 skill + 4 team (product / engineering / design / marketing)
• 9-layer JIT context — Team OKR Layer 4a 신설
• Chief 6+1 stage state machine — TRIAGE → DECOMPOSE → DISPATCH → AWAIT → SYNTHESIZE → DECIDE → RETROSPECT, <org>/memory/chief-stage-events.jsonl 자동 emit
• open_questions[] async-batch protocol — PM → Chief blocking question batch escalation
• Goal queue (1-active-per-org semaphore), 4 workflow templates, leading indicator 5 지표
• 외부 reference: Hermes V2 + gstack (Garry Tan) + RO-PNA pna-builders + phuryn pm-skills
• 상세: CHANGELOG.md §[1.1.0], docs/prd/v1.1-multi-agent-team-architecture.md

v1.0.0 ~ v1.0.4 (2026-05-21 ~ 2026-05-23) — Formal launch + Discord patch chain

• v1.0.0 — 정식 출시. 안정 API 보장. 42 CLI surface freeze. docs/api-stability.md 공개 약속 발효. Discord 단일 메신저 (Slack post-v1.0 슬롯)
• v1.0.1 — discord.js v15 deprecation fix, @<slug> mention parser, multi-repo intent routing
• v1.0.2 — Discord author-guard 제거 (당시 사유: 채널명이 user-id 라 봇 인식 실패 — v1.2.6 에서 handle 기반 채널로 해소된 후 owner-only 게이트로 reversal)
• v1.0.3 — 5건 fix: versionMatches slice 산수 / npm sudo prefix 권한 체크 / guild-org binding ownOrgSlug 직접 사용 / update next-step 안내 / 카테고리 이름 정합 ("AI Team Reports" → "solosquad")
• v1.0.4 — Discord config.yaml 자동 생성 + Slack author-guard 통째 cleanup + 5-hop diagnostic 메시지 + 9-reference 조사 박제
• 상세: CHANGELOG.md §[1.0.0]~[1.0.4]

v0.x series (pre-launch) — 압축 요약

v1.0 출시 전 자체 사용 검증 + 인프라 구축 단계. 상세 이력은 CHANGELOG.md §[0.x.x] + docs/prd/product-roadmap.md §5.1.

• v0.8.x — Multi-User Messenger (command-<handle> / works-<handle> 채널 페어 + handle 기반 라우팅 + author-guard 도입 + opt-in broadcast 채널), Security & Lifecycle Pair (archive 페어 완결 + api-stability.md), Dev Capability (SKILL frontmatter dev_capability), Onboarding UX + Observability (add repo --dry-run, solosquad logs)
• v0.7.0 — Uninstall & Lifecycle (Farewell Archive). 사용자 코드 불가침, WAL-safe SQLite backup, REVOKE-CHECKLIST.md 자동 생성
• v0.6.0 — 디폴트 워크플로우 튜닝, FTS5 cold archive, trajectory + freq miner, Org Layer specialization, chokidar hot-reload
• v0.5.0 — 워크플로우 메이커 + frontmatter routing (4채널 라우터 slash > explicit > keyword > freq)
• v0.4.0 — 자율 overnight 엔진 (goal.md + solosquad goal run), AGENTS.md cross-tool 표준 차용
• v0.3.0 — PM mode + 멀티 에이전트 오케스트레이션, 슬래시 체인 /think /plan /build /review /ship
• v0.2.x — 워크스페이스 구조 정립 (.solosquad/ + 다중 organization)
• v0.1.x — 최초 npm 배포, 25 specialist agents, Discord/Slack 어댑터

9.2 다음 슬롯 (기획 중)

v1.2.x — 다음 patch / sub-version

• v1.2.1 후속 — Thread 연속성: referencedMessage chain + LRU cache (PRD §7.3) + thread token budget guard (PRD §9.2). v1.2.0 = 작업 1개 = thread 1개 모델 → 연속 대화 surface 추가
• v1.2.x — Slack adapter 복원: init messenger picker 의 Slack 옵션 활성화 + 같은 ChiefMessenger 인터페이스로 v1.2 기능 재구현

v1.3 — 일정 관리 + 메모

• n잡 사용자 시간/기억 통합. Calendar / Apple Notes / Obsidian / Notion MCP 연결
• v1.2 지식 온톨로지 (v1.x slot) 위에 layer 로 얹음

v1.x — cascade-shifted 슬롯

• 대시보드 상호작용: 컴패니언 웹 대시보드 (별도 리포 solopreneur-dashboard + solopreneur-api)
• 지식 온톨로지 + MCP 외부 연결: 그래프 백엔드 + Notion / Obsidian / 외부 API / 타 에이전트
• LLM backend abstraction: Multi-backend (single Claude → pluggable)

10.트러블슈팅 & FAQ

10.1 설치·실행 문제

"solosquad를 찾을 수 없습니다"

• npm install -g solosquad로 설치했는지 확인
• node --version으로 Node.js 18+ 확인
• Linux에서 권한 오류 시: sudo npm install -g solosquad 또는 ~/.npm-global 설정

"claude를 찾을 수 없습니다"

npm install -g @anthropic-ai/claude-code
claude login
solosquad doctor       # 최종 확인

메신저에서 봇이 응답하지 않음

먼저 환경 불일치 확인:

solosquad doctor                    # 기본 진단
solosquad doctor --messenger-check  # 토큰 live API 검증

.env vs process.env mismatch 경고가 뜨면 solosquad 최신 버전으로 업데이트해야 합니다 (.env 로드 버그는 v0.1.3에서 수정).

Slack 체크리스트 (§5.1 Step 9 재확인):

• Event Subscriptions 활성화 + message.channels 구독
• Scope 변경 후 Reinstall to Workspace 수행
• #owner-command 채널에 봇 초대

Discord 체크리스트 (§5.2 마지막 체크리스트):

• Message Content Intent ON
• 봇 권한 Create Public Threads (v0.2.4+, 시스템 스레드 생성용)
• 서버 이름에 제품 이름/slug 포함

기존 Telegram 사용자: v0.2.4부터 지원 제거. .solosquad/.env의 MESSENGER=telegram을 discord 또는 slack으로 변경하고 setup 새로 진행 (§4.4 참조).

루틴이 실행되지 않음

• solosquad schedule이 실행 중인지 (ps 또는 docker compose ps)
• 수동 테스트: solosquad run-routine signal-scan

Docker: claude: command not found (컨테이너 내부)

• CLAUDE_AUTH_DIR 볼륨 마운트가 올바른지 확인
• 컨테이너 안에서 직접 인증: docker exec -it solosquad-bot claude login

업데이트 후 동작 이상

solosquad doctor
solosquad update                    # 이미 최신이면 안내만 출력
docker compose up -d --build        # Docker 사용 시 이미지 재빌드

git push 인증 실패 (에이전트 dev_capability 사용 시)

에이전트가 commit까지는 했는데 push 단계에서 fatal: Authentication failed 또는 Permission denied (publickey)로 실패한 경우:

cd <repo>
git push --dry-run    # 직접 실행해서 동일 에러 재현되는지 확인

• Windows: Git for Windows 설치 시 Git Credential Manager가 자동 활성되어야 함. 재설치 (winget install Git.Git) 후 첫 push가 브라우저 OAuth 띄우는지 확인
• macOS: git config --global credential.helper osxkeychain 설정 후 첫 push 시 GitHub PAT 입력 → Keychain 영구 저장
• Linux: SSH key (ssh-keygen + GitHub 공개키 등록) 또는 PAT + credential.helper store 직접 셋업

인증 자체는 SoloSquad 외부 영역입니다. 자세한 절차는 GitHub 공식 docs 참조.

10.2 마이그레이션 트러블슈팅

"Cannot find package.json" 류 에러

npm cache clean --force
npm uninstall -g solosquad
npm install -g solosquad@latest

마이그레이션 중단

solosquad migrate --rollback   # 가장 최근 백업으로 복원

그 다음 GitHub Issues에 로그와 함께 보고.

마이그레이션 후 bot이 안 뜸

solosquad doctor

출력 확인. 토큰 누락·.env 위치 이상이 흔한 원인.

Claude Code 인증 풀림

claude login
docker compose restart    # Docker 사용 시

어떤 버전으로 업그레이드할지 모르겠음

릴리스 노트를 먼저 확인:

• GitHub Releases: https://github.com/Adelie-Squad/solosquad/releases
• docs/product-roadmap.md

breaking change가 포함된 minor 업데이트는 중요 프로젝트용으로는 일주일 정도 관찰 후 올라가는 것도 합리적.

10.3 Uninstall · 재설치 · 마이그레이션 회피v0.8.5

안전한 uninstall 순서

npm v7+가 preuninstall 훅을 글로벌 패키지에서 호출하지 않는 한계(npm/cli#3042) 때문에, 사용자가 직접 순서를 지켜야 farewell archive와 REVOKE-CHECKLIST가 생성됩니다.

1. 봇·스케줄러 정지 (필수) — 실행 중이면 archive snapshot SHA가 불일치합니다.

   # macOS / Linux
   docker compose down              # Docker 사용 시
   # 또는 봇/스케줄러 터미널에서 Ctrl+C
   
   # Windows (PowerShell)
   docker compose down
   # 또는 봇·스케줄러 터미널에서 Ctrl+C
   # 또는 PID 강제 종료:
   Stop-Process -Id <pid1>,<pid2> -Force

   solosquad doctor의 "solosquad bot/schedule processes alive (pid ...)" 경고로 잔존 PID 확인 가능. solosquad uninstall 자체 precheck도 live PID 감지 시 --force 없이는 진입을 거부합니다.
   v0.9.2 hotfix — v0.9.1 이하 Windows 사용자는 봇이 안 도는데도 precheck가 phantom PID로 차단하던 버그가 있었습니다 (WMI 쿼리가 자기 자신을 매칭). 회피책은 --force였고, v0.9.2부터는 $_.Name -eq 'node.exe' 가드로 정상 동작합니다. 자세히 CHANGELOG.md §[0.9.2].
2. uninstall dry-run으로 미리보기

   solosquad uninstall --dry-run
   # 출력: archive zip 경로, 무엇이 archive로 / 삭제 / 보존되는지,
   #       REVOKE 대상 외부 자원 (Discord/Slack/Anthropic 토큰), 디스크 free space

3. uninstall 실행 — mode 3종

   solosquad uninstall                          # 기본 --mode full (완전 정리)
   solosquad uninstall --mode keep              # workflows·memory·knowledge 보존 (재설치용)
   solosquad uninstall --mode archive-only      # archive zip만 생성, cleanup 스킵

   repositories/<repo>/ 사용자 코드는 어떤 mode·플래그로도 변경/삭제되지 않습니다 (v0.7 class A 불가침).
4. archive zip 안전 보관 — ~/solosquad-archive-<workspace>-<ts>.zip 자동 생성. 외부 디스크·클라우드 드라이브로 별도 보관 권장. 검증:

   solosquad archive verify ~/solosquad-archive-...zip
   # manifest.tsv SHA256 정합 + PII-NOTICE 스캔

5. 외부 자원 정리 — REVOKE-CHECKLIST.md — 워크스페이스 루트와 archive zip 양쪽에 사본. 다음을 안내:
   • Discord Application ID — Developer Portal에서 봇 삭제 또는 token reset
   • Slack workspace ID — App management에서 봇 제거 또는 OAuth revoke
   • Anthropic Claude — ~/.claude/projects/<path-hash>/ 추정 경로 (수동 정리는 사용자 판단)
   • pm2 / systemctl / crontab — 외부 자동화 등록이 있으면 해제 명령 자동 추출
6. npm 패키지 제거 (선택)

   npm uninstall -g solosquad

   재설치 예정이면 이 단계는 건너뛰어도 OK — npm install -g solosquad@latest가 덮어쓰기.

uninstall + 재설치로 마이그레이션 우회

워크스페이스를 처음부터 다시 만들고 싶거나, 큰 마이그레이션 chain을 건너뛰고 싶을 때:

# 1. 위 안전 순서로 uninstall (--mode archive-only로 데이터 보존 zip만 만들기 가능)
solosquad uninstall --mode archive-only

# 2. CLI 최신화 (이미 됐으면 skip)
npm install -g solosquad@latest

# 3. 새 워크스페이스 init (v0.8.5 wizard — workspace.yaml.version이 처음부터 0.8.5)
mkdir new-workspace
cd new-workspace
solosquad init

# 4. (선택) 이전 데이터 import — workflows·memory·knowledge 복원
solosquad import ~/solosquad-archive-<old>-<ts>.zip --mode merge
# 또는 --mode replace (워크스페이스 비어 있어야)

이 흐름은 마이그레이션 chain을 한 번에 건너뛰는 우회 경로입니다. v0.4 워크스페이스에서 v0.8.5까지 9개 migration 돌리는 대신 archive → re-init → import로 한 번에 새 포맷으로 점프. 단점: archive zip이 v0.7 포맷 기준이라 일부 v0.6 이전 raw 자산은 보존되지만 v0.8 멀티유저 구조로 재배치되지 않을 수 있음 (사용자 확인 필요).

재설치 후 doctor 경고 0건 만들기

새 init 직후 solosquad doctor 경고들이 *항상* 뜨는 정보성 항목 vs *조치 필요* 항목 구분:

10.4 봇 · 스케줄러 · 에이전트 git 작업v0.8.2~v0.8.6

스케줄러는 디폴트 실행되지 않음

SoloSquad는 데몬 / 백그라운드 자동 시작이 없습니다. solosquad init이 cron 등록을 하지 않으며, OS 부팅 시 자동 실행도 없음. 다음 명령으로 *명시적으로* 시작해야 합니다:

solosquad bot         # 메신저 봇 (Socket Mode + fs.watch)
solosquad schedule    # cron routine 실행기 (morning/evening brief, system-housekeeping)

두 명령은 별개 프로세스. 둘 다 24/7 동작이 필요하면 각각 다른 터미널 또는 Docker compose 서비스로 실행. solosquad doctor의 △ solosquad bot/schedule processes alive (pid ...) 경고는 *둘 중 하나라도* 살아 있을 때 표시 — Windows에서는 Get-CimInstance Win32_Process로 commandLine이 solosquad + (bot|schedule|run-routine) 패턴인 node.exe 프로세스를 찾습니다.

에이전트의 dev_capability — *git push까지* (v0.8.6 현재 범위)

v0.8.2 dev_capability 기능을 활용하면 메신저 대화만으로 에이전트가 *코드 작성 → 커밋 → push*까지 자동 수행합니다. **PR 생성·리뷰·토론·머지는 사용자가 GitHub 웹 UI에서** 직접 진행. v0.8.6 기준 *범위 명시*:

전제 조건 — 모두 *사용자 사전 셋업* (SoloSquad가 자동화하지 않음)

1. git 설치 + push 인증 — §4.2 Step 1 준비물 설치만 따라가면 OK. Windows·macOS는 첫 push 시 OS가 자동 처리. Linux는 SSH key 또는 PAT 별도 셋업 필요할 수 있음 (git/GitHub docs). 검증:

   cd <workspace>/<org>/repositories/<repo>
   git push --dry-run
   # "Everything up-to-date" 또는 "To <url>..." → ✓ 통과
   # "Authentication failed" → 트러블슈팅 §10.1 참조

2. repo 등록

   solosquad add repo https://github.com/me/my-saas.git --org my-saas

3. workspace.yaml dev_capability 활성

   # <workspace>/.solosquad/workspace.yaml
   dev_capability:
     enabled: true                      # 마스터 토글 (기본 true)
     require_push_confirmation: true    # git push 시 사용자 확인 (영구 true, 변경 불가)
     bash_denylist:                     # workspace-strict 차단 명령 (선택)
       - "rm -rf /"
       - "shutdown"

에이전트의 push 흐름

사용자 (command-<handle>):  "결제 모듈 Stripe 통합해줘"
                ↓
PM이 의도 분류 → Backend Developer SKILL spawn (dev_capability: true)
                ↓
BD가 repo cwd로 이동 → 코드 분석 → src/payments/ 추가 → 테스트
                ↓
git checkout -b feat/stripe-payment
git add src/payments/
git commit -m "feat: Stripe payment integration"
                ↓
🛑 [dev-confirm gate] PM이 사용자에게 메신저로 통지:
   "git push origin feat/stripe-payment? (30분 timeout) [y/N]"
                ↓
사용자 "y"  → push 실행
                ↓
BD의 마지막 회신 (works-<handle>):
   "✓ Branch pushed.
    PR 생성하려면 아래 URL 클릭:
    https://github.com/me/my-saas/compare/main...feat/stripe-payment"
                ↓
[여기서부터 사용자 책임]
사용자가 URL 클릭 → GitHub 웹 UI에서 PR 생성 → 코드 검토 → 머지

git push는 SENSITIVE_BASH_PREFIXES에 박혀 있어 30분 timeout dev-confirmation 게이트를 통과해야 실행 (src/bot/dev-confirm.ts). 사용자가 timeout 내 응답 안 하면 push 자동 abort + <org>/memory/dev-confirmations.jsonl에 기록.

온보딩에 추가할 항목 (dev_capability 사용자용)

§4.2 9-step 외 dev_capability 사용자가 추가로 챙겨야 할 것 — *gh CLI 설치는 v0.8.6 범위에서 불필요*:

• Step 1.5 — git push 인증 확인 (선택, 실패 시만)

  git push --dry-run    # 임의의 본인 repo에서
  # 실패 시 트러블슈팅 §10.1 참조

• Step 7.5 (doctor 직후) — repo 등록 + push 검증

  solosquad add repo <url> --org <org>
  cd <workspace>/<org>/repositories/<repo>
  git push --dry-run        # 워크스페이스 안에서도 인증 동작 확인

• Step 7.7 — workspace.yaml dev_capability 명시

  dev_capability:
    enabled: true
    require_push_confirmation: true  # 변경 불가, 박제
    bash_denylist: []

• Step 8.5 (봇 실행 직후) — 메신저 첫 dry test

  command-<handle> 채널에:
  "<repo-name>에서 README의 오타 하나 고쳐서 push해줘"
  → 작은 변경으로 전체 흐름(spawn → diff → commit → dev-confirm → push → compare URL) 검증

• (선택) Step 8.7 — branch 보호 규칙 — GitHub repo settings에서 main branch에 Require pull request before merging + Require approvals: 1 활성. PR 머지를 사용자가 명시적으로 승인하게 강제하는 안전망.

10.5 자주 묻는 질문 (FAQ)

Q. 비용이 얼마나 드나요?
A. Claude Code 사용 가능한 플랜 구독료만 있으면 시작 가능 (Max 권장). SoloSquad는 v0.9 기준 *Claude Code via OAuth* 단일 백엔드. 클라우드 운영 시 VPS 월 $4~6 추가.

Q. v1.0에서 Slack은 지원되나요?
A. v1.0 공식 지원 메신저는 Discord 한 종류. Slack 어댑터는 코드상 동봉되어 v0.9.x에서 사용하던 사용자는 계속 동작하지만, v1.0 SemVer 약속 대상이 아닙니다 (post-v1.0 슬롯). 새로 시작하면 Discord 사용을 권장합니다. 페르소나를 분리하고 싶으면 Discord 워크스페이스 2개로 분리: ~/solopreneur/ + ~/elon-24-7/ 각자 독립된 .env·토큰·봇 계정. 이 제약은 v0.2.0+ — 이전 MESSENGER=discord,slack multi-target 문법은 미지원.

Q. 시간대가 한국이 아니면?
A. .env의 TZ=를 변경 (예: TZ=America/Los_Angeles). Docker도 동일.

Q. AI가 틀린 답을 하면?
A. AI는 도구입니다. 중요한 결정은 반드시 본인이 직접 확인. solosquad rollback --workflow <id> (v0.3+)로 spawn 결과 revert 가능. v0.4 자율 실행은 per-cycle git-snapshot keep/discard로 자동 보호.

Q. Mac Mini 대신 Raspberry Pi로 돌릴 수 있나요?
A. Node.js 18+이 돌면 가능. 단, Claude Code CLI는 arm64 기반 리눅스를 공식 지원하는지 먼저 확인 필요.

Q. 완전 오프라인에서 쓸 수 있나요?
A. 불가. Claude API와 Slack/Discord 서버 통신이 필수.

Q. 업데이트 전에 꼭 해야 할 일이 있나요?
A. solosquad bot / schedule이 실행 중이면 먼저 정지. docker compose down 또는 터미널 Ctrl+C.

Q. 매번 업데이트해야 하나요?
A. 아닙니다. 안정적으로 쓰고 있다면 급할 이유는 없음. 다만 보안 hotfix(예: v0.1.3 dotenv 누락)는 빠르게 적용 권장.

Q. 업데이트 자동화가 가능한가요?
A. Docker 환경이면 docker compose up -d --build를 cron에 걸면 이미지 최신화됩니다. 단 마이그레이션 필요 시엔 자동화 불가 — 사람의 확인이 들어가는 게 원칙.

Q. 예전 버전으로 고정하고 싶어요.
A. npm install -g solosquad@0.1.5처럼 명시적 버전으로 설치. solosquad update가 업그레이드 제안해도 거절하면 됨.

Q. 여러 사람이 한 머신에서 씁니다.
A. 각자 OS 계정을 다르게 쓰고, 각 계정의 홈 디렉토리에 독립된 워크스페이스를 두세요. 마이그레이션도 계정별로 따로 진행.

Q. 베타·개발 채널이 있나요?
A. solosquad update --channel dev로 전환 가능 (단, 안정성 보장 없음). --channel stable이 기본.

Q. v0.5에서 v0.6으로 업그레이드는 어떻게 하나요?
A. npm install -g solosquad@latest 후 워크스페이스 루트에서 solosquad migrate --dry-run 실행 → 보고서(<org>/memory/migration-2026-XX-dryrun.md) 검토 → 문제 없으면 solosquad migrate --apply --confirm. --confirm 플래그 없으면 거부됩니다 (실수 방지). 마이그레이션 후 solosquad agent validate --all이 자동 실행되어 실패 항목을 STDOUT에 보고합니다.

Q. 마이그레이션이 "human_review_required" 항목을 보고하면?
A. v0.5 ledger의 일부 자산은 휴리스틱 기반 재배치라 100% 정확 불가 — SKILL 본문에서 "조직 색채" 추출 매칭 0건 케이스 등이 해당. 해당 항목은 human_review_required: true 마킹되어 자동 적용이 거부됩니다. 사용자가 보고서를 보고 수동으로 <org>/agent-profile.yaml의 해당 agent 섹션을 보강한 후 마이그레이션을 재실행하세요. 비파괴 원칙으로 원본은 손대지 않습니다.

Q. v0.6 자율 reload가 너무 적극적이에요. 직접 트리거하고 싶어요.
A. workspace.yaml.fs_watch.mode: manual로 설정하면 자동 reload가 꺼집니다. SKILL 변경 후 solosquad agent reload로 명시 호출. fs_watch.mode: prompt(기본)는 PM이 메신저에서 적용 여부를 묻는 중간 모드입니다.

Q. (v0.8.3) solosquad update와 solosquad migrate의 차이는?
A. update는 CLI 바이너리(npm 패키지) 자체를 갱신, migrate는 워크스페이스 스키마/레이아웃을 새 CLI 버전에 맞게 변환. 일반적인 흐름: ① solosquad doctor로 CLI ↔ workspace mismatch 확인 → ② npm install -g solosquad@latest 또는 solosquad update로 CLI 갱신 → ③ solosquad migrate --dry-run 미리보기 → ④ solosquad migrate --apply로 적용. doctor가 어느 명령이 필요한지 명시적으로 안내합니다 (v0.8.3 §7.3).

Q. (v0.8.3) 기존 product code를 SoloSquad 워크스페이스 안으로 어떻게 옮기나요?
A. ① cd ~/projects/my-saas && git status로 untracked 정리·git push로 안전망 확보 → ② mkdir ~/solosquad && cd ~/solosquad && solosquad init → ③ solosquad add repo ~/projects/my-saas --dry-run으로 폴더 매핑·사이즈·위험 5종(IDE lock·심링크·외부 절대경로·slug 충돌·활성 프로세스) 미리 확인 → ④ solosquad add repo ~/projects/my-saas로 실제 이동(또는 --keep-original로 복사). 원본 사용자 파일은 byte-identical (v0.7 클래스 A 룰). SoloSquad가 추가하는 건 <repo>/.solosquad/repo.yaml 1개뿐.

Q. (v0.8.3) 기존 리포 이동 후 IDE 경로가 깨졌어요.
A. .vscode/settings.json·.idea/workspace.xml 같은 IDE 설정에 절대경로가 들어있는 경우 SoloSquad는 사용자 파일을 변형하지 않으므로 사용자가 수동으로 갱신해야 합니다. solosquad add repo <path> --dry-run 출력에 절대경로 설정이 감지된 IDE 파일 경고가 표시됩니다. cron 작업·alias·CI runner 경로도 동일 — 외부 시스템이 옛 경로를 가리키면 사용자가 갱신.

Q. (v0.8.3) 봇이 무엇을 하고 있는지 보고 싶어요 — 로그가 어디 있나요?
A. 환경변수 SOLOSQUAD_LOG_FILE=1을 설정하면 <workspace>/.solosquad/logs/solosquad-YYYY-MM-DD.log에 일별 rolling. solosquad logs --tail 200 --follow로 실시간 tail. --type costs/spawn/stop-hook/dev-confirm/migration로 4 operational jsonl 직접 조회. 보존은 14일(매일 00:30 log-rotate routine이 자동 정리).

Q. (v0.8.3) solosquad logout은 어디로 갔나요?
A. v0.7에서 추가됐다가 v0.8.3에서 제거됐습니다. 사용 가치 < 구현 복잡도 판정. 대체 흐름: 봇 일시 중지는 Ctrl+C로 프로세스 종료(다시 시작은 solosquad bot), .env 시크릿 마스킹/REVOKE 체크리스트는 solosquad uninstall --archive-only가 동일하게 제공, sessions 보관은 <org>/.solosquad/sessions/에서 직접 이동 또는 solosquad pm reset --user <id>. 기존 logout.lock 파일은 v0.8.3에서 inert가 되었으므로 수동 삭제 가능.

Q. (v0.8.3) trajectory 자동 등록은 언제 활성화되나요?
A. v0.6에서 정의한 ROI 4지표(① 30일 제안 ≥ 5건 ② 채택률 ≥ 60% ③ 채택 SKILL의 30일 사용률 ≥ 평균 ④ reject cooldown < 30%) 중 모두 통과 시 v0.9에서 workspace.yaml.trajectory.auto_register: true가 기본값이 됩니다. 1개라도 fail이면 "제안만 영구" 잠금. v0.8.3 패치는 측정값을 CHANGELOG에 박제만 합니다 (자동 등록 코드는 v0.9에서 추가).