2.작동 원리

2.1 시스템 아키텍처

SoloSquad는 3개의 핵심 프로세스와 1개의 영속 저장소로 구성됩니다.

메시지 처리 흐름 (현재 v0.6)v0.6

키워드 단발 호출은 v0.3에서 PM 세션 모델로, v0.5에서 4채널 라우팅 + 3-tier 검색 + atomic swap hot-reload로 진화했고, v0.6에서 chokidar 기반 fs.watch 자동 hot-reload + 8-layer JIT spawn assembly + org × agent 단위 budget envelope이 추가됐습니다. 라우터 미스 시 FTS5 cold archive fallback이 과거 결정을 회상합니다.

사용자 → PM session (claude --resume <session-id>)
            ↓
            buildRoutes(): 3-tier 스캔
              [1] <org>/.agents/                  (org 로컬 override)
              [2] ~/.solosquad/agents/             (user 글로벌 override)
              [3] <workspace>/.solosquad/agents/   (번들 25개)
            ↓
            4채널 resolver (우선순위: slash > explicit > keyword > freq)
              · slash    — "/think /plan /build /review /ship" 등
              · explicit — PM이 추론으로 직접 호출
              · keyword  — 1턴 메시지 단어 매칭
              · freq     — 최근 N턴 누적 빈도 임계 초과 시 자동 로드
                           (cooldown_turns 동안 재발화 금지 — hysteresis)
            ↓
            매칭된 SKILL을 컨텍스트에 JIT inject
            ↓
            Task: <agent> "..." (fresh subagent session, [stage:<id> wf:<id>] marker 부착)
            ↓
            결과 요약을 PM 컨텍스트에 합침 → 다음 spawn 또는 사용자 보고
            ↓
            git-snapshot before-spawn / after-spawn 자동 커밋 (<org>/.solosquad/snapshot.git)

[병렬] 새 SKILL.md 저장 시 라우터 atomic swap:
        새 인덱스 빌드 → ref 교체 → 빌드 중 메시지는 이전 인덱스로 처리 (봇 재시작 불필요)

v0.4 자율 실행 진입 시 solosquad goal run <goal-id>이 background PM session(bg-<goal-id>-<runId>)을 띄워 같은 4채널 라우팅을 cycle 안에서 반복합니다. 메트릭 게이팅 keep/discard, git-snapshot revert, 누적 비용 cap이 cycle 단위로 적용됩니다.

2.2 폴더 위계 구조

현재 npm 배포 (v0.8.5) 구조

3-tier 검색 우선순위 (v0.5): SKILL은 같은 이름이면 <org>/.agents/ > ~/.solosquad/agents/ > <workspace>/.solosquad/agents/ (번들) 순으로 상위 계층이 override합니다. 라우터가 부트 시 세 위치를 모두 스캔해 한 인덱스로 합칩니다.

v0.6 신설 자산v0.6

조직별로 25 specialist의 톤·강조점·budget을 흡수하는 Org Layer + 사용자 누적 craft를 분리하는 Workspace Knowledge Layer가 정식 자산으로 도입됐습니다. 워크스페이스 번들 SKILL은 한 줄도 변경 없이, 조직 색채는 아래 자산에서만 들어옵니다.

• assets/agents/{team}/KNOWLEDGE.md — 기존 _teams/*/TEAM_KNOWLEDGE.md가 co-location으로 이동 (Team=Domain). 같은 team agent spawn 시 자동 inject.
• <org>/core/{PRINCIPLES,VOICE}.md — 조직 철학·톤 (workspace core/ override). 비어 있어도 spawn 정상 동작.
• <org>/agent-profile.yaml — 25 agent 조직별 modifier (defaults + agent별 섹션 + budget + schema_version: 1). budget은 agent별 섹션이 *defaults보다 좁은* 값만 허용.
• <org>/domain/{market,customers,product}.md — 조직 도메인 지식 (시장·고객·제품).
• .solosquad/knowledge/ — 사용자 누적 공용 지식 (의사결정 프레임워크·도메인 용어집). 키워드 매칭 시 selective inject.
• ~/.solosquad/agent-profile-defaults.yaml — user-global 상속. N개 org가 공유할 budget·voice 기본값. 상속 순서: workspace bundle defaults → user global → org agent-profile.
• <org>/memory/archive.sqlite — FTS5 cold archive (8일 이상 된 JSONL을 SQLite FTS5 가상 테이블로 이전, 검색 fallback).

agent-profile.yaml 예시

schema_version: 1
defaults:
  tone: conservative
  budget:
    daily_usd: 5
    weekly_usd: 25
    on_cap_action: pause       # pause | warn

business-strategist:
  emphasis: "한국 SMB 시장 컨텍스트 우선"
  decision_frame: "현금흐름 > 성장률"

content-writer:
  voice: "professional, no hype"
  ban_phrases: ["혁신적인", "획기적인"]

paid-marketer:
  budget:                       # defaults보다 좁힘만 허용
    daily_usd: 2

명시되지 않은 agent는 defaults만 적용. spawn 직전 cap 도달 시 spawn 거부 + PM이 "Daily budget 도달 — 내일 다시 시도해주세요" 응답. 누적은 <org>/memory/agent-costs.jsonl.

2.3 컨텍스트 & 메모리 관리

현재 메모리 구조 (v0.2.4)

모든 routine 결과는 JSONL append-only로 기록됩니다. JSON 한 줄 = 한 이벤트.

<org>/memory/signals.jsonl 예시:
{"ts":"2026-05-12T12:00:00Z","kind":"signal","source":"reddit/r/saas","content":"...","urgency":"med"}
{"ts":"2026-05-12T12:00:15Z","kind":"signal","source":"twitter","content":"...","urgency":"high"}

3계층 컨텍스트 (보고서 P/E/T 어휘)

Just-in-Time Injection 원칙v0.5

모든 SKILL.md를 매 호출마다 컨텍스트에 넣지 않습니다. 사용자 메시지의 키워드, 슬래시 명령, 빈도 카운팅에 따라 *그 호출에 필요한 SKILL만* 선택적으로 주입. v0.5에서는 4채널 라우터(slash/explicit/keyword/freq)가 매 턴 매칭해 컨텍스트 가산을 결정합니다.

v0.6 메모리 처리 흐름v0.6

v0.5 turn 흐름은 그대로 유지되며, v0.6에서 spawn budget·8-layer drop 로그·spec-gate 평가·마이그레이션 비용이 추가됐습니다. 한 PM 턴이 진행될 때 다음 파일이 갱신됩니다.

• <org>/.solosquad/sessions/<user>.json — last interaction, cumulative cost USD, activeWorkflowId, freqCooldowns (v0.5 — 매 턴 decay 유지)
• <org>/workflows/<wf-id>/_events.jsonl — PM 메시지·spawn·완료 이벤트
• <org>/.solosquad/snapshot.git — before/after-spawn 커밋 (memory/ + workflows/)
• <org>/memory/author-costs.jsonl — author 루프 단계별(USD) 누적 (v0.5)
• <org>/memory/agent-costs.jsonl v0.6 — agent별 spawn 비용 누적, agent-profile budget cap 산정용
• <org>/memory/spawn-decisions.jsonl v0.6 — 8-layer assemble에서 토큰 cap 도달 시 drop된 layer 기록 (§4.6 FTS5 인덱싱 대상)
• <org>/memory/stop-hook-events.jsonl v0.6 — spec-gate cycle 종료 직전 hook 평가 결과
• <org>/memory/migration-costs.jsonl v0.6 — 0.5→0.6 마이그레이션 자체 LLM fallback 누적
• <org>/memory/pm-skills/_recent.md — pm-compaction이 외부화한 완료 워크플로 1줄 요약 (PM이 다음 턴에 자동 인지)

FTS5 Cold Archivev0.6

JSONL이 누적되면 검색이 느려지므로, 8일 이상 된 항목은 SQLite FTS5 가상 테이블 <org>/memory/archive.sqlite로 옮겨 토큰 매칭 기반 검색 가능하게 보관합니다. 매일 00:00 archive-rotate routine이 자동 수행. 시맨틱 임베딩 인프라 없이 검색성 확보.

4 event_type 인덱싱v0.6

v0.6은 기존 routine-logs/*.jsonl 외에 라우터·author·spawn 이벤트 3종을 같은 archive로 인덱싱합니다. §3 trajectory 추출·§3.4 freq 자동 추천의 데이터원.

Retention 정책v0.6

archive는 기본 365일 보존(workspace.yaml.archive.retention_days: 365). archive-rotate routine이 *오래된 항목 삭제* 단계 수행. 옵션 archive.compress_before_delete: true 설정 시 archive-<year-month>.zst로 분기 보관. 디스크 사용량은 solosquad memory stats --disk로 확인.

2.4 워크플로우 정의

4종 디폴트 워크플로우

핵심 파일: _status.yaml + _handoff.md

_status.yaml은 단계별 진행 상태(pending → in_progress → completed)를 추적. _handoff.md는 각 단계가 종료 시 다음 에이전트에게 전달할 컨텍스트 슬라이스.

_handoff.md 표준 섹션:
- Summary: 3줄 요약
- Artifacts: 산출물 목록
- Key Decisions: 결정 + 근거
- Context for Next Agent: 다음 에이전트가 알아야 할 것
- Open Questions: 미해결 질문

v0.6 핸드오프 3변형v0.6

단계마다 협업 패턴이 다른데 같은 템플릿을 강요하는 한계를 해소했습니다. 25 agent SKILL.md에 collab_pattern frontmatter가 정식 필드로 추가되어 spawn 시 해당 변형 템플릿이 자동 적용됩니다.

• hierarchical (22 agent) — PM → specialist 표준 흐름. 기존 4섹션 유지 (templates/handoff-hierarchical.md)
• graph (data-analyst, feature-planner) — 양방향 수렴 루프 (예: research ↔ data-analyst). state_object_diff, loop_count 추가 (templates/handoff-graph.md)
• dynamic (content-writer) — 결과 내용에 따라 다음 에이전트가 분기. routing_signal 추가 (templates/handoff-dynamic.md)

2.5 Spawn assembly (8-layer JIT inject)v0.6

specialist를 spawn할 때 컨텍스트는 다음 8 layer를 우선순위 순으로 조립합니다. workspace.yaml.spawn.max_context_tokens (기본 80,000) cap 도달 시 우선순위 낮은 layer부터 drop, 결정 로그는 <org>/memory/spawn-decisions.jsonl에 기록되어 §2.3 FTS5 인덱싱 대상이 됩니다.

spawn(business-strategist, org=Acme, repo?)
  └─ assemble:
       [1] .solosquad/knowledge/ + assets/knowledge/  (workspace 공용, 키워드 selective)
       [2] agents/strategy/KNOWLEDGE.md               (team(=domain) 공유 지식, 같은 team만)
       [3] agents/strategy/business-strategist/SKILL.md  (agent 정체성, 워크스페이스 불변)
       [4] <org>/core/                                (조직 철학·톤)
       [5] <org>/agent-profile.yaml의 defaults + business-strategist 섹션 (org modifier)
       [6] <org>/domain/                              (조직 도메인 지식)
       [7] <org>/workflows/<id>/_handoff.md + <org>/memory/ (recent + FTS5 recall)
       [8] target_repo 컨텍스트 (target_repo 필드 있을 때만)

Drop priority 표

drop 발생 시 <org>/memory/spawn-decisions.jsonl에 어느 layer를 truncate했는지 기록 — §2.3 FTS5 archive에 event_type: spawn_decision으로 인덱싱.

3.개념 정리

3.1 SKILL.md — 에이전트 정체성 정의

SKILL.md는 한 에이전트의 "이 역할은 어떻게 일하는가"를 기술한 매뉴얼입니다. Anthropic의 Agent Skills 공식 포맷을 따르며, SoloSquad는 라우팅·loop_mode·budget 등 확장 필드를 더해 사용합니다.

---
name: "Business Strategist"
description: "사업 전략·시장 분석·경쟁 포지셔닝"
team: strategy
stateful: false                    # v0.5 — 모든 specialist는 stateless
triggers:                          # v0.5 — 4채널 진입점
  slash: ["/strategize"]
  keyword: ["사업 전략", "비즈니스 모델"]
  freq:                            # 누적 빈도 자동 로드 (cooldown_turns 동안 재발화 금지)
    keywords: ["전략", "포지셔닝", "경쟁"]
    window_turns: 10
    threshold: 3
    cooldown_turns: 6
  explicit: true                   # PM이 추론으로 직접 호출 가능
inputs:
  required: [market_context, hypothesis]
  optional: [time_range]
outputs:
  - strategy.md
handoff_to:
  - feature-planner
  - pmf-planner
loop_mode:                         # v0.5 — spec-gate(Ralph 루프) 모드 명시. null | spec-gate
  kind: spec-gate
  stop_when: "all tests pass"
budget:                            # v0.5 — paperclip envelope 차용. author 루프·explicit 호출에 forward
  per_call_usd: 1.5
  daily_usd: 10
---

# Business Strategist Agent

당신은 1인 창업자를 돕는 사업 전략 전문가입니다.

## Process
1. 시장 컨텍스트 파악
2. 경쟁 분석
3. 가설 수립 + 검증 방법 제시
...

• 위치 (3-tier 검색): <org>/.agents/ > ~/.solosquad/agents/ > <workspace>/.solosquad/agents/ (번들 25개)
• 로드 시점: 라우터가 4채널 매칭으로 선택 → PM이 Task tool로 spawn 시 시스템 프롬프트에 주입
• 속성: Stateless (v0.5 강제) — 매 호출이 fresh session이며 state는 외부(workflows/handoff/memory)에 보관. stateful: true는 PM과 v0.4 goal-runner background session 두 actor만 사용
• 필수 필드: name·description (Anthropic 사양). 나머지는 SoloSquad 확장이며 누락 시 라우터가 fallback 처리
• loop_mode = spec-gate: author 루프가 자동으로 <org>/goals/<goal-id>/goal.md도 emit → v0.4 goal-runner에 자율 cycle로 등록

3.2 KNOWLEDGE.md — 팀(=도메인) 공유 지식v0.6

같은 팀의 모든 에이전트가 공유하는 craft·정의·anti-pattern을 한 파일에 모읍니다. v0.6에서 agents/{team}/KNOWLEDGE.md로 co-location 완료, 같은 team agent spawn 시 자동 inject (8-layer assemble의 [2] layer).

3.3 CLAUDE.md — 프로젝트/리포 지침

CLAUDE.md는 Claude Code(범용 코딩 CLI)가 매 세션 시작 시 자동으로 읽어들이는 프로젝트 지침 파일입니다. SoloSquad의 자체 컨벤션이 아니라, Claude Code 공식 컨벤션입니다.

• 위치: 프로젝트 루트 (또는 .claude/ 폴더 안)
• 용도: 코드베이스 구조, 사용 기술, 사용자 지침을 모델에게 전달
• 로드 시점: Claude Code가 자동 — 사용자가 명시 지시 불필요

SoloSquad의 루트 CLAUDE.md는 *SoloSquad 자체를 개발하는* 개발자(이 리포에서 코딩하는 사람)를 위한 지침입니다. 사용자가 자기 제품 리포에서 작업할 때는 *그 리포의 CLAUDE.md*가 적용됩니다.

예시: 사용자의 SaaS 리포 CLAUDE.md
# My SaaS

TypeScript + Next.js. Vercel 배포.

## Conventions
- 컴포넌트는 src/components/ 아래에 PascalCase
- API route는 src/pages/api/
...

3.4 SKILL.md vs AGENTS.md — 다른 레이어, 다른 역할

SoloSquad는 두 파일을 모두 사용하되 책임이 명확히 다릅니다. 한 워크스페이스에서 SKILL.md는 여러 개, AGENTS.md는 단 1개.

요점: SKILL.md는 "이 agent가 누구인지·뭘 잘하는지"를 적고, AGENTS.md는 "이 워크스페이스를 만지는 모든 AI 도구가 따라야 할 룰"을 적습니다. 둘은 경쟁이 아니라 다른 레이어입니다.

CLAUDE.md는 더 이상 사용하지 않습니다 v0.4. 종전에는 CLAUDE.md와 AGENTS.md를 워크스페이스 루트에 함께 두는 설계였으나, 같은 위계에 두 파일을 두면 "어디 적어야 하지" 혼란이 발생하고 두 출처가 발산할 위험이 큽니다. v0.4부터 SoloSquad는 워크스페이스 영속 가이드를 AGENTS.md 단일 파일로 통일합니다. 기존 CLAUDE.md는 마이그레이션이 손대지 않고 컨텐츠만 AGENTS.md로 1회 복사 — 사용자가 필요 없으면 수동 삭제. 최신 Claude Code도 AGENTS.md를 fallback으로 인식하므로 호환성 손실 없음.

3.5 워크플로 메이커 메타-skillv0.5

사용자가 코드를 안 만지고 메신저 대화 1-2턴만으로 새 SKILL.md(또는 workflow chain)를 등록할 수 있게 하는 author 루프 시스템입니다. assets/agents/_meta/workflow-maker/SKILL.md가 author 루프 시스템 프롬프트 역할을 하며, PM이 "이 작업을 자동화하고 싶다" 의도를 분류하면 [META workflow-maker] explicit 호출로 진입합니다.

5단계 상태기

1. CLARIFY — 입력·출력·실행 빈도 등 1-2턴 명확화 (답 못 하면 default 채택 + 추후 수정 가능 명시)
2. DRAFT — SKILL.md + (선택) workflow.yaml + (선택) routine cron entry preview
3. SANDBOX_PROMPT — dry-run sandbox로 1회 실행 → 사용자 확인 요청
4. AWAIT_CONFIRM — 사용자 승인 게이트 ("확정할까요?")
5. APPLIED — 결정적 머지: solosquad agent validate <path> → 라우터 atomic swap → 다음 호출부터 즉시 사용 가능. loop_mode.kind: spec-gate draft는 <org>/goals/<goal-id>/goal.md도 자동 emit

CLI 연동

• solosquad agent add --name X --team Y — 스캐폴딩 (frontmatter 템플릿 + 빈 body)
• solosquad agent validate <path> — 스키마 + 필수 섹션 검증. author 루프 저장 직후 자동 실행
• solosquad agent validate --all [--corpus] — 워크스페이스 전체 + 번들 + corpus 회귀. CI 게이트(.github/workflows/ci.yml)에서 실행
• solosquad agent list / info — 등록된 SKILL 인벤토리·상세

비용 cap (paperclip envelope)

명확화 + draft + validate + sandbox 각 단계 LLM 호출이 <org>/memory/author-costs.jsonl에 누적됩니다 (ts, skill_draft_id, step, usd). workspace.yaml.author 섹션의 per_call_usd·daily_usd·weekly_usd cap 도달 시 PM이 "Daily budget 도달 — 내일 다시 시도해주세요" 응답.

분석 트랙

기존 repo의 .claude/skills/ 자산은 solosquad analyze repo <path>로 흡수합니다. 4-라벨 분류(role / workflow / codebase-fact / domain) 보고서가 <org>/.solosquad/analysis/에 저장되고, 사람 검토 후 solosquad add repo --from-report <report>로 결정적 머지(backup → apply → verify). 두 번째 실행은 analysis-ledger.yaml의 hash로 신규/변경분만 LLM 호출.

3.6 4채널 라우팅 + freq cooldownv0.5

v0.2.4의 60+ 키워드 하드코딩 AGENT_ROUTES는 v0.5에서 제거됐습니다. 각 SKILL.md의 triggers frontmatter가 부트 시 수집되어 라우터 인덱스를 만들고, 4채널 우선순위로 매칭합니다.

우선순위: slash > explicit > keyword > freq. 동일 채널 안에서는 3-tier 검색 경로(org > user > bundle)로 override.

Freq 채널 hysteresis (cooldown)

한 번 자동 로드된 SKILL은 frontmatter triggers.freq.cooldown_turns (기본 6) 동안 같은 SKILL의 freq 매칭 score 계산을 건너뜁니다. 같은 주제로 길게 대화할 때 매 턴 재발화하는 잡음 회피용. 라우터 메모리 구조: <org>/.solosquad/sessions/<user>.json의 freqCooldowns: { skill_name: until_turn } 필드가 매 턴 decay.

Freq 등록 SKILL 상한

workspace당 freq 등록 SKILL 상한은 20개. validator가 21번째 등록 시도부터 거부 (매 메시지 정규식 매칭 비용 보호 — p95 < 10ms 목표). 키워드 토큰화 후 hashmap 카운터로 O(|tokens|) 매칭, 정규식은 fallback.

자동 로드 통지 (UX)

freq 채널로 로드된 SKILL은 사용자에게 1회 알림: 🧠 {agent} 컨텍스트 자동 로드됨 (최근 키워드: ...). 사용자가 의도하지 않은 라우팅을 즉시 거부할 수 있습니다.

Hot-reload (atomic swap)

author 루프가 새 SKILL.md를 저장하면 src/bot/index.ts가 라우터를 재빌드합니다. 빌드 중 도착한 메시지는 이전 인덱스로 처리되고, 빌드 완료 후 ref 교체(routeIndexRef = newIndex) — 빌드 중 도달한 메시지가 부분 인덱스에 닿지 않음. 봇 재시작 불필요. 빌드 실패 시 이전 인덱스 유지 + PM에 경고.

메타-skill scanner 분리

_meta/ 폴더는 일반 scanner에서 계속 skip. 별도 listMetaSkills()가 assets/agents/_meta/*/SKILL.md만 스캔하고 triggers.explicit: true만 인정합니다. workflow-maker 메타-skill은 PM이 explicit 호출로만 진입 — slash/keyword/freq 채널 등록은 거부됩니다.

3.7 위계별 파일 종류 (마스터 표)

워크스페이스 위계 (Layer 0)

조직 위계 (Layer 1)

리포 위계 (Layer 2)

3.8 collab_pattern + 자가 진화 인프라v0.6

v0.5에서 extra bag으로 받던 collab_pattern이 v0.6에서 정식 SkillSpec 필드로 격상되었습니다. SKILL.md frontmatter에서 collab_pattern: hierarchical | graph | dynamic을 명시하면 spawn 시점에 해당 변형 핸드오프 템플릿이 자동 적용됩니다.

Trajectory 추출 (반복 패턴 자동 SKILL 추출)v0.6

같은 (agent sequence + workflow template) 조합이 최근 30일 내 3회+ 발생하면 야간 pm-compaction routine이 draft SKILL.md를 <org>/memory/pm-skills/_suggestions/에 생성합니다. 다음 아침 브리핑에 "지난 30일 동안 X 패턴을 3회 실행하셨습니다. SKILL로 등록할까요?" 1줄 알림. 사용자 확정 시 v0.5 S3의 applyDraft()를 그대로 호출 — 별도 applier 작성 없음 (코드 중복 회피).

30일 rolling window — archive-rotate가 카운트도 함께 decay. 자동 등록 없음 (사람 게이트 유지).

Freq keyword miner (키워드 자동 추천)v0.6

FTS5 archive의 route_miss 이벤트 + author-draft 명확화 질문 N-gram을 분석해 *기존 SKILL frontmatter의 triggers.keyword 배열에 추가할 후보*를 제안합니다. 새 SKILL 생성이 아닌 부분 적용. 사용자 확정 시 applyDraft({ mode: "frontmatter-only" }) 정식 옵션으로 v0.5 코드 재사용 — 본문은 한 글자도 안 건드리고 frontmatter만 패치. 거절 시 (keyword, skill) 쌍은 30일 재제안 금지.

Stop-hook DSL (v0.5 spec-gate 실 작동)v0.6

v0.5에서 명세만 있던 loop_mode.kind: spec-gate가 v0.6에서 Anthropic 2025-12 stop-hook 플러그인 어댑터(src/engine/stop-hook-adapter.ts)로 실제 작동합니다. stop_when 3 형식 지원:

# (1) command — exit code 기반 (가장 결정적)
loop_mode:
  kind: spec-gate
  stop_when:
    command: "npm test"           # exit 0 = 충족, != 0 = 계속

# (2) metric — results.tsv 임계 (v0.4 자율 실행과 호환)
loop_mode:
  kind: spec-gate
  stop_when:
    metric:
      name: "cvr_7day"
      threshold: 0.10
      direction: "≥"

# (3) natural — LLM fallback (budget cap 적용)
loop_mode:
  kind: spec-gate
  stop_when:
    natural: "all tests pass and lint clean"

Hook timeout 5초, 실패 시 보수적으로 *계속* (false positive보다 false negative 안전). 결과는 <org>/memory/stop-hook-events.jsonl에 기록.

3.9 v0.7 farewell archive 포맷v0.7

uninstall이 항상 zip을 먼저 생성하며 포맷은 다음과 같다: archive.yaml (schema_version=1) + manifest.tsv (streaming SHA256) + workspace/ + orgs/<slug>/{memory,workflows,goals,domain,core,repos}/ + credentials/env.template (masked) + REVOKE-CHECKLIST.md + PII-NOTICE.md. v0.8.1은 solosquad import·solosquad archive verify로 reverse path를 잠근다.

클래스 A/A*/B/C/D/E (v0.7 데이터 분류)

3.10 멀티 유저 채널 모델v0.8

v0.7까지의 1인 운영자 모델에서 다수 사용자 컨텍스트로 확장. 각 사용자는 command-<handle>(요청)·works-<handle>(작업 결과) 채널 쌍을 갖고, <org>/.solosquad/users/<handle>.yaml에 메타가 저장됩니다. author-guard가 다른 사용자가 자기 채널에서 응답을 가로채는 것을 차단합니다. 등록은 solosquad messenger add <handle>로.

3.11 dev_capability (개발 권한)v0.8.2

SKILL.md frontmatter의 dev_capability: true 필드로 에이전트가 코드 수정 dev action(파일 변경·git commit·push)을 수행할 수 있음을 선언. boolean — 켜기/끄기. 세부 권한은 별도 dev_permissions sub-tree로 분리:

• bash.allowed / bash.denied — 호출 가능·차단 bash 명령 리스트. workspace-level denylist(workspace.yaml.dev_capability.bash_denylist)가 항상 위에 merge되어 SKILL이 override 불가
• network — 외부 HTTP 호출 (curl/wget 등) 허용 여부. MCP server는 별도 채널
• push_targets.requires_confirmation — git push 시 사용자 확인 게이트 (기본 true)
• merge.auto — 영구 false 박제 (v0.8.2 §2 / §3.1) — 자동 머지 정책 영구 추가 안 함

모든 sensitive 명령 (git push, gh pr merge, gh pr close)은 SENSITIVE_BASH_PREFIXES에 박혀 있고 30분 timeout dev-confirmation 게이트를 통과해야 실행됩니다. 결과는 <org>/memory/dev-confirmations.jsonl에 append-only 기록.

3.12 .solosquad/ 폴더 위계 — 왜 디렉터리마다 하나씩 있는가v0.8.5

워크스페이스를 처음 보면 세 위치에 .solosquad/ 폴더가 나타나서 헷갈리기 쉽습니다. 각각 다른 scope의 시스템 메타데이터를 담고, *사용자 콘텐츠*와 *디스크에서 시각적으로 분리*하기 위한 dotfile 컨벤션입니다.

왜 위계마다 따로 있는가

• 모두 시스템 메타데이터 — SoloSquad가 관리. 사용자 콘텐츠(memory/ · workflows/ · repositories/<repo>/ 본체)와 *시각적으로 분리*
• dotfile 컨벤션 — ls 기본 출력에 안 보임. .gitignore에 .solosquad/ 한 줄로 모든 위계의 시스템 자산 제외 가능
• 위계마다 담는 내용이 다른 이유 — scope가 다름:
  • (A) 워크스페이스 = 전역 (모든 org가 공유하는 agent SKILL · envs · timezone)
  • (B) org = org당 1회 박혀야 하는 식별 (멀티유저 handle → bot_user_id 매핑)
  • (C) repo = repo가 어느 org 소속이고 role이 뭔지 (한 repo가 여러 org에 동시 등장 X)
• 사용자 콘텐츠는 hidden이 아닌 일반 디렉터리 (memory/·workflows/·repositories/) — 사용자가 ls·git에서 즉시 보고 편집할 수 있어야 하므로

4.온보딩

4.1 사용자 유형 판별

본인이 어느 유형인지 먼저 확인하세요. 유형에 따라 진행할 절차가 달라집니다.

4.2 신규 사용자 — 첫 워크스페이스 만들기

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

winget install OpenJS.NodeJS.LTS
winget install Git.Git
npm install -g @anthropic-ai/claude-code

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

node --version    # v18 이상
git --version
claude --version

npm install -g solosquad
solosquad --version

# 예시: 이름은 자유롭게 — 아래는 "my-saas"
mkdir my-saas
cd my-saas
solosquad init

claude login

solosquad doctor                  # 기본 진단
solosquad doctor --messenger-check  # 토큰까지 실제 검증

# Option A — 터미널 두 개
solosquad bot          # 메신저 봇
solosquad schedule     # 자동 routine

# Option B — Docker (v0.5+ — deploy/docker/ 안에서)
cd deploy/docker && docker compose up -d --build
# 자세한 옵션·환경 변수: deploy/docker/README.md 참조

4.3 기존 리포 마이그레이션

이미 코드 리포가 있고 거기에 AI 팀을 붙이고 싶을 때.

현재 (v0.2.4) 방법v0.2.4

1. 먼저 §4.2 Step 1~7로 워크스페이스를 만듭니다 (조직 1개라도 생성).
2. 리포를 워크스페이스로 등록:

   cd ~/solosquad-workspace
   solosquad add repo /path/to/existing-repo      # 로컬 경로
   solosquad add repo https://github.com/me/x.git # 또는 git URL (clone)

3. 조직이 여러 개면 어느 조직 소속인지 물어봅니다. 단일이면 자동 배정.
4. 리포가 <workspace>/<org>/repositories/<repo>/로 들어갑니다.
5. 해당 리포에 자체 .claude/skills/나 CLAUDE.md가 있으면 그대로 유지 — 해당 리포의 작업 시 Claude Code가 자동으로 로드.

v0.5 분석기 흐름v0.5

기존 리포의 .claude/skills/를 SoloSquad 자산으로 흡수하는 분석기가 출시되었습니다.

solosquad analyze repo /path/to/legacy-repo
# → 4-라벨 분류 (role / workflow / codebase-fact / domain)
# → <org>/.solosquad/analysis/YYYY-MM-DD-*.md 보고서 생성
# → analysis-ledger.yaml에 path + SHA256[:12] 기록 (두 번째 실행은 신규/변경분만 LLM 호출)

solosquad analyze repo <path> --force            # 모델 업그레이드 시 전체 재분석
solosquad analyze repo <path> --prune-orphans    # 파일 사라진 ledger 항목 정리

solosquad add repo /path/to/legacy-repo --from-report 2026-XX-XX-initial.md
# → backup → 결정적 머지 → verify

solosquad add repo <path> --merge-policy append|override|replace
# → 머지 정책 명시 (기본 append)

4.5 기존 리포 가져오기 — 권장 5단계v0.8.3

사용자가 자기 product code를 SoloSquad 워크스페이스 안으로 옮기는 시점은 1회 — 실수의 비용이 크므로 dry-run을 default 권고로 합니다.

# [Step 1] 기존 작업 정리 + commit + push
cd ~/projects/my-saas
git status            # untracked·unstaged 0건 확인
git push origin main  # 안전망

# [Step 2] SoloSquad 초기화
mkdir ~/solosquad && cd ~/solosquad
solosquad init        # 워크스페이스 + 첫 org 생성

# [Step 3] dry-run 미리보기 (v0.8.3 신규)
solosquad add repo ~/projects/my-saas --dry-run
# 출력: From/To, 파일 수·사이즈, IDE 워크스페이스 감지, 심링크,
#       활성 프로세스(lsof/handle.exe), slug 충돌, 위험 요약

# [Step 4] 실제 이동
solosquad add repo ~/projects/my-saas
# 또는: --keep-original 으로 복사 모드 (디스크 2× 사용)

# [Step 5] 검증
solosquad sync                       # repositories/ ↔ .org.yaml 정합
cd ~/solosquad/main/repositories/my-saas
git status                           # working tree clean
git log -1                           # 직전 commit 그대로

4.6 위험 시나리오 + dry-run 감지v0.8.3

위 위험은 warn 레벨 — 사용자는 무시하고 진행 가능. dry-run 자체는 디스크 변경 0건.

4.4 이전 버전 사용자 업데이트

버전 규칙 (semver)

• vN.N.N 3자리 (예: v0.1.5, v0.2.0)
• patch (세 번째 자리): 버그 수정·작은 개선 — 마이그레이션 거의 없음
• minor (두 번째 자리): 새 기능·구조 변경 — 마이그레이션 필요할 수 있음
• major (첫 번째 자리): 근본적 개편 — 마이그레이션 필수

npm 실제 출시 번호는 별도 semver 트랙. 문서 라벨 v0.x ↔ npm 버전 1:1 매칭 아님 — 정책은 docs/product-roadmap.md §3.5.

현재 버전 확인

solosquad --version           # 설치된 CLI 버전
solosquad update              # 레지스트리 최신과 비교 (실제 업데이트 전 안내만)

일반 업데이트 (마이그레이션 불필요)

대부분의 patch 업데이트는 아래 한 줄로 끝.

solosquad update              # "New version available" → y → 자동 설치
# 또는 수동
npm install -g solosquad@latest
solosquad --version
solosquad doctor              # ✓ 다섯 줄 모두 통과해야 정상

구조 변경 업데이트 (마이그레이션 필요)

solosquad update가 다음과 같은 경고를 표시하면 마이그레이션 필요:

⚠ This update includes breaking changes to the workspace layout.
  A workspace migration is required. After updating the CLI, run:
    solosquad migrate --dry-run   (preview)
    solosquad migrate --apply     (perform)

실행 순서:

1. npm install -g solosquad@latest — CLI 먼저
2. 워크스페이스로 cd
3. solosquad migrate --dry-run — 미리보기
4. 출력 검토 후 solosquad migrate --apply
5. solosquad doctor로 검증
6. solosquad bot 재시작

Dry-run 출력 예시

$ solosquad migrate --dry-run
Workspace: /Users/you/solosquad-workspace
Detected structure: v0.1.x  (source)
Target version:     v0.2.0  (installed CLI)

Migration plan (0.1.x → 0.2.0):

  ✓ Move workspace config to .solosquad/
  ✓ Convert each product → organization directory
  ✓ Rename projects/ → workflows/
  ✓ Remove obsolete env vars (REPOS_BASE_PATH)

Estimated disk usage: +0 MB (moves only, no copies)
Backup location:      /Users/you/.solosquad-backups/2026-...

Nothing written yet. Re-run with `--apply` to perform the migration.

Dry-run은 아무것도 바꾸지 않습니다. 마음에 안 들면 그냥 무시.

Apply가 자동으로 해주는 것

• 작업 전 워크스페이스 전체 스냅샷 백업 (~/.solosquad-backups/<타임스탬프>/)
• 파일·폴더 이동/이름변경
• 새 설정 파일 자동 생성 (.solosquad/workspace.yaml, .org.yaml 등)
• 마이그레이션 후 doctor 자동 실행으로 검증

여러 버전을 건너뛸 때 (체인 마이그레이션)

v0.1.2를 쓰다가 v0.3.0으로 직접 업데이트할 경우 마이그레이션이 체인으로 순차 실행됩니다:

Chaining migrations:
  0.1.x → 0.2.0  (layout restructure)
  0.2.0 → 0.4.0  (cross-repo enhancements)

각 단계는 dry-run 후 한꺼번에 apply. 중간 실패 시 해당 단계까지만 롤백.

v0.2.4 업데이트 특별 사항

v0.2.4는 메신저 채널 구조와 routine 모델을 바꾸고 Telegram 지원을 제거합니다.

전 사용자 공통:

• migrate --apply가 .solosquad/workspace.yaml에 timezone·briefings·background_routines 필드 주입 (기본 Asia/Seoul · 08:00 / 18:00)
• 메신저 채널은 자동으로 줄어들지 않음. 봇이 더 이상 daily-brief·signals·experiments·weekly-review·errors로 송신하지 않으므로 원하면 메신저 UI에서 수동 archive
• JSONL 메모리·workflows 디렉터리는 손대지 않음

Discord 사용자:

• 봇 권한에 Create Public Threads 추가 → 동일 서버에 re-invite (덮어쓰기, 데이터 영향 없음). 시스템 스레드 4개(system-daily-signals 등) 자동 생성에 필요.

Slack 사용자:

• Bot Token Scopes에 channels:manage 추가 → "Reinstall to Workspace". 없으면 #workflow 채널 생성 실패.

Telegram 사용자 (지원 제거)v0.2.4 제거

• v0.2.4부터 MESSENGER=telegram은 작동하지 않음. 봇 시작 시 명확한 에러 메시지 출력.
• 전환 절차:
  1. solosquad migrate --apply 먼저 실행 (workspace.yaml 신규 필드 주입은 메신저와 무관)
  2. Discord 또는 Slack 봇 setup (§5.1 또는 §5.2)
  3. .solosquad/.env에서 MESSENGER=telegram → discord 또는 slack
  4. TELEGRAM_BOT_TOKEN / TELEGRAM_CHAT_ID 라인 삭제 (남아 있어도 무시되지만 정리 권장)
  5. solosquad bot 재시작 → 새 플랫폼의 #owner-command + #workflow 자동 생성
• JSONL 메모리는 그대로 보존 — 새 메신저로 전환해도 과거 시그널·실험·결정은 모두 살아 있음

알려진 이슈 (v0.1.x → v0.2.0 점프 시)

• solosquad update가 마이그레이션 경고를 띄우지 않을 수 있음 — 마이그레이션 감지 코드가 v0.2.0에 신규 추가됐기 때문. v0.1.x에서 올라오는 사용자는 업데이트 직후 solosquad migrate를 수동으로 한 번 실행.
• --dry-run 플래그 미등록 — v0.2.0 초기 빌드에서. v0.2.1+에서 정식 등록. 플래그 없이 solosquad migrate만 써도 기본 dry-run.

마이그레이션 후 첫 작업 — solosquad sync

v0.1.x → v0.2.0 마이그레이션 스크립트는 각 product를 org로 바꾸되 .git을 org 루트에 그대로 둡니다 (v0.1.x의 product=repo 자취). sync 첫 실행 시 두 가지 선택 제공:

⚠ bv-ai-native-po/ has a .git folder at the organization root (v0.1.x legacy layout).
  How would you like to handle this?
  ❯ Normalize — move code into repositories/<org-slug>/ (recommended)
    Keep legacy — register repo.yaml at org root, skip restructure

• Normalize (권장) — 코드와 .git이 <org>/repositories/<org-slug>/로 이동. 시스템 폴더는 org 루트 유지. 앞으로 repo 여러 개 붙일 거면 필수.
• Keep legacy — 현상 유지. <org>/.solosquad/repo.yaml을 org 루트에 생성. 저장소 한 개만 쓸 거면 OK.

Docker 사용자 업데이트 흐름

# 모든 명령은 deploy/docker/ 안에서 (v0.5+)
cd deploy/docker

# 1. 컨테이너 중지
docker compose down

# 2. 호스트에서 CLI 업데이트 (마이그레이션 감지 + 실행용)
npm install -g solosquad@latest

# 3. 마이그레이션 필요 시 (워크스페이스 루트에서)
cd ../..
solosquad migrate --dry-run
solosquad migrate --apply

# 4. Docker 이미지 재빌드
cd deploy/docker
docker compose up -d --build

마이그레이션은 반드시 호스트에서. 컨테이너 안에서 하면 볼륨 매핑 혼란 가능. v0.5+ 컨테이너는 ~/.solosquad/ + ~/.solosquad-backups/를 추가로 마운트하므로 user-global SKILL override와 backup이 정상 작동합니다.

멀티 워크스페이스 업데이트

페르소나별 워크스페이스 여러 개 사용 시 CLI 업데이트는 한 번이지만 마이그레이션은 각 워크스페이스에서 개별 실행:

npm install -g solosquad@latest

cd ~/solopreneur
solosquad migrate --dry-run
solosquad migrate --apply

cd ~/elon-24-7
solosquad migrate --dry-run
solosquad migrate --apply

각 워크스페이스는 독립 백업 — 하나 실패해도 다른 워크스페이스 영향 없음.

롤백

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

주의: 롤백 후에는 복원된 버전에 맞는 CLI를 쓰세요. v0.2.0로 마이그레이션했다가 v0.1.5로 롤백했다면:

npm install -g solosquad@0.1.5

CLI와 워크스페이스 버전 불일치 시 doctor가 경고합니다.

백업 관리

백업 기본 위치: ~/.solosquad-backups/<ISO-타임스탬프>-v<소스버전>/

solosquad migrate --list-backups        # 목록
solosquad migrate --delete-backup <id>  # 수동 삭제

자동 보존: 최근 5개만 유지. 6번째 마이그레이션 시 가장 오래된 백업 삭제. 중요한 시점의 백업은 외장 디스크나 클라우드 드라이브로 별도 보관 권장.

업그레이드 실패 트러블슈팅

"Cannot find package.json" 류 에러

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

마이그레이션 중단

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

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

Claude Code 인증 풀림 — v0.2.0+ Docker 이미지가 ${HOME}/.claude를 마운트하므로 호스트의 claude login 상태가 컨테이너에 공유됩니다:

claude login
docker compose restart

베타·개발 채널

solosquad update --channel dev     # 베타 (안정성 보장 없음)
solosquad update --channel stable  # 기본

5.메신저 연결

AI가 메신저에서 메시지를 주고받으려면 봇 계정이 필요합니다. v1.0의 공식 지원 메신저는 Discord 한 종류입니다. Slack 어댑터 코드도 동봉되어 동작하지만 v1.0 SemVer 약속에 포함되지 않습니다 (post-v1.0 슬롯 — `docs/plan/v1.0-formal-launch.md` §5 참조). 한 워크스페이스당 1개 메신저만 선택합니다.

5.1 Discord 봇 설정 (v1.2 정합) v1.2

최종 결과물: .env 의 DISCORD_TOKEN + 워크스페이스 owner 의 messenger_user_id + OrgYaml.chief_name 박제. Discord 서버에 봇 초대 → guildCreate 가 자동으로 welcome embed 송신 → #command-<handle> / #works-<handle> 채널 페어 자동 생성 → owner 가 "안녕" 메시지 → Chief (예: Hermes) 가 답.

cd ~/your-workspace
solosquad init

solosquad bot                       # 봇 기동
# 다른 터미널:
solosquad doctor --discord          # 5-hop diagnostic
# 결과: ✓ 1.DISCORD_TOKEN  ✓ 2./users/@me  ✓ 3.bot_user_id match
#       ✓ 4.guild membership  ✓ 5.config.yaml + command channel

5.2 Slack 봇 설정 (post-v1.0 슬롯) post-v1.0

본 절은 post-v1.0 슬롯 — v1.0 SemVer 약속 대상이 아닙니다. v1.2.x adapter 슬롯 활성화 시 복원. v0.9.x ~ v1.1 에서 이미 Slack 을 운영 중인 사용자는 아래 v0.x 절차 그대로 참조.

최종 결과물: .env에 SLACK_BOT_TOKEN=xoxb-...와 SLACK_APP_TOKEN=xapp-...가 저장되고, Slack 워크스페이스의 #owner-command 채널에서 봇이 응답.

MESSENGER=slack
SLACK_BOT_TOKEN=xoxb-1234567890-...
SLACK_APP_TOKEN=xapp-1-...
SLACK_COMMAND_CHANNEL=owner-command

solosquad doctor --messenger-check
solosquad bot

5.3 동작 검증

두 플랫폼 공통:

solosquad doctor                    # 기본 환경 점검
solosquad doctor --messenger-check  # 메신저 토큰까지 live API로 검증
solosquad bot                       # 봇 기동, 콘솔에 로그 출력
solosquad bot --debug               # 자세한 로그

#owner-command에 안녕 → 봇이 [제품명 (agent-name)] ... 형태로 응답하면 전 구간 정상.

6.사용법

6.1 명령어 레퍼런스

현재 사용 가능 (v0.7.0 ~ v0.8.3)v0.7~v0.8.3

추후 추가 예정v1.1+

6.2 일상 운영

메신저에서 일 시키기 (v0.6)v0.6

PM 세션과의 멀티턴 대화가 기본 흐름입니다. PM이 의도를 분류해 specialist를 Task tool로 spawn합니다. 라우터는 4채널(slash/explicit/keyword/freq) 우선순위로 적절한 SKILL을 컨텍스트에 inject.

매칭 없으면 PM이 general 모드로 응답하거나 추가 명확화 질문.

PM 모드 멀티턴 대화v0.3

사용자: "랜딩페이지 리디자인 진행해줘"
PM:    기존 랜딩의 어떤 부분을 바꾸시려는가요?
        (1) 히어로 섹션  (2) 가격 섹션  (3) 전체 리뉴얼
사용자: 1번
PM:    [PRD 작성 → desk-researcher spawn → ui-designer spawn → ...]
       완료. stage-1-research/와 stage-2-design/에 산출물.

슬래시 명령v0.3

의도를 명시하고 싶으면 자연어 대신 슬래시 사용 (gstack 패턴 차용). [SLASH /xyz] <args>로 PM 프롬프트에 래핑되어 안정 파싱.

• /think <주제> — 가설·시장 신호 정리 (PRD 분해 전)
• /plan <주제> — PRD 작성 + status.yaml 분해
• /build — 직전 plan의 ready stage 실행
• /review — 완료 stage 종합 + 차단 이슈 보고
• /ship — release/배포 routine 트리거
• /help — 봇 측에서 short-circuit, 사용법 텍스트만 응답

메신저에서 새 SKILL 만들기v0.5

"이런 작업 자주 하니까 자동화하고 싶다" → PM이 의도를 분류해 workflow-maker 메타-skill을 explicit 호출 → 1-2턴 명확화 → SKILL.md draft → 사용자 승인 → atomic swap → 다음 호출부터 즉시 사용 가능. §3.5 참조.

0.5 → 0.6 마이그레이션v0.6

v0.5에서 올라오는 사용자는 다음 순서로 진행합니다.

1. npm install -g solosquad@latest — CLI 먼저 갱신
2. solosquad migrate --dry-run — Pass 1 시뮬레이션 + 보고서 <org>/memory/migration-2026-XX-dryrun.md 생성. 파일시스템 변경 0건
3. 보고서 검토 — 이동 N건 / 사람 검토 필요 M건 / 변경 0건(이미 final이었음) K건 분류
4. solosquad migrate --apply --confirm — --confirm 플래그 없으면 거부 (실수 방지)
5. human_review_required: true 마킹된 항목은 사용자가 사후 수동 보강 후 재실행
6. Pass 2 — solosquad agent validate --all 자동 실행 + 실패 항목 STDOUT 보고

마이그레이션 자체에 budget cap (workspace.yaml.migration.budget_usd, 기본 5 USD) 적용. 휴리스틱 fail-soft가 LLM fallback으로 떨어질 때 누적 토큰 폭증 방지. cap 도달 시 *나머지 항목은 human_review_required 마킹*하고 안전 종료. 누적은 <org>/memory/migration-costs.jsonl.

readiness checkv0.6

v0.6 회고 본문 시작 전 자동 측정 도구. solosquad readiness check --target v0.6 실행 시 workspace 스캔 → v0.5 사용 데이터(author-costs.jsonl 행 수) / 4종 워크플로 실행 카운트 X/4 / author SKILL Y건(<org>/.agents/ + ~/.solosquad/agents/) / ledger 분석 → "S1 시작 가능 ✓" 또는 "데이터 부족 — N주 추가 권고" 결정적 출력. exit code로 자동화 가능.

fs.watch mode 선택v0.6

v0.6은 외부 편집(VSCode 직접 수정 · git pull · 별도 CLI 조작)도 라우터에 자동 반영합니다 — chokidar 기반 3-tier watch + 300ms debounce. workspace.yaml.fs_watch.mode로 3 모드 선택:

• auto — v0.5 atomic swap 그대로. 모든 외부 변경 즉시 반영
• prompt (기본) — PM에 🔄 N개 SKILL 변경 감지 — 적용? [y/N] 1턴 알림. 사용자 y/n
• manual — 자동 reload 안 함. solosquad agent reload 명시 실행 필요

추가 안전 모드 fs_watch.git_only: true 설정 시 *HEAD ≡ upstream + clean tree*만 자동 반영 — git pull로 검토 안 된 SKILL이 작동 중 봇에 즉시 반영되는 위험을 차단합니다.

6.3 권장 첫 작업 (온보딩 직후)

1. solosquad doctor가 모두 ✓ 인지 확인.
2. 메신저 #owner-command에 안녕 → 응답 확인.
3. 첫 routine 수동 실행:

   solosquad run-routine signal-scan

   #workflow 채널의 system-daily-signals 스레드에 결과가 표시되는지 확인.
4. 사용자 프로필 수정 — assets/core/OWNER.md (또는 .solosquad/core/OWNER.md)를 본인 이름·역할·관심사로 갱신. 모든 agent가 매 세션 이 파일을 참조.
5. 행동 원칙 — core/PRINCIPLES.md에 본인의 의사결정 기준 적기 (예: "현금흐름 우선", "VC 펀딩 받지 않음", "주 50시간 이하 작업").
6. 글쓰기 톤 — core/VOICE.md에 콘텐츠 어조 명시 (예: "전문적이지만 따뜻한 톤, 과장 표현 금지").
7. 제품 이름 결정 + 워크플로 폴더 생성 (~/solosquad-workspace/<org>/workflows/wf-2026-XX-XX-test/ 직접 생성).
8. brief 시각 조정 — .solosquad/workspace.yaml의 briefings.morning.time 등 본인 생활 패턴에 맞춰 수정.

6.4 자동 루틴v0.8.5

총 4건. 사용자가 보는 brief 3건 + 시스템 인프라 1건. v0.8.5에서 분석 routine 4건(signal-scan / experiment-check / weekly-review / v06-retrospective-stats)을 영구히 제거하고, 인프라 2건(archive-rotate + log-rotate)을 단일 system-housekeeping으로 통합.

사용자가 보는 brief (3건)

시스템 인프라 (사용자 의식 X, 항상 활성, silent)

v0.8.5 변경 — routine 9건 → 4건:

• 제거 (영구): signal-scan · experiment-check · weekly-review · v06-retrospective-stats. 사용자 도메인 prompt 없이는 무의미한 분석 routine. 도메인 분석은 워크플로우/goal로 표현
• 통합: archive-rotate + log-rotate → system-housekeeping (단일 cron 00:00, try/catch 격리)
• backward-compat: workspace.yaml.background_routines 키는 read-ignore (에러 X)

업데이트 ↔ 마이그레이션 흐름v0.8.3

두 명령은 별개입니다. solosquad doctor가 CLI ↔ workspace version mismatch 감지 시 어느 쪽이 필요한지 명시적으로 안내합니다 (§7.3).

# 1. 진단
solosquad doctor
# ├─ "CLI: v0.8.3,  workspace: v0.8.3" → OK
# ├─ "CLI: v0.8.3,  workspace: v0.7.0" → solosquad migrate --apply 권고
# └─ "CLI: v0.7.0,  workspace: v0.8.3" → npm install -g solosquad@latest 권고

# 2. CLI 업그레이드 (npm 패키지 자체)
solosquad update          # npm registry 확인 + 자동 self-install
# 또는: npm install -g solosquad@latest

# 3. (CLI 새 버전이 되면) 워크스페이스 정합
solosquad migrate --dry-run    # 무엇이 바뀔지 미리보기
solosquad migrate --apply      # 적용 (자동 backup → apply → verify)
solosquad migrate --rollback   # 직전 backup으로 복원 (필요 시)

• update = CLI 바이너리(npm 패키지) 자체를 갱신
• migrate = 워크스페이스(.solosquad/·org/·workflows/·memory/) 스키마/레이아웃을 새 CLI 버전에 맞게 변환

시간대·시각·활성화 변경

.solosquad/workspace.yaml을 직접 편집:

timezone: Asia/Seoul        # IANA tz 자유
briefings:
  morning:
    time: "08:00"
    enabled: true
  evening:
    time: "18:00"
    enabled: true
background_routines:
  signal_scan:
    time: "12:00"
    enabled: true
  experiment_check:
    time: "16:00"
    enabled: true
  weekly_review:
    day: "sunday"
    time: "20:00"
    enabled: true

수동 실행

solosquad run-routine                # 인터랙티브 메뉴
solosquad run-routine signal-scan    # 특정 루틴
solosquad run-routine --all          # 전부

7.운영 가이드

7.1 24/7 운영 방식 선택

봇이 메신저와 연결을 유지하려면 solosquad bot이 계속 실행 중이어야 합니다. 방식 비교:

A-1. 터미널 열어두기 (가장 간단)

solosquad bot

터미널이 열려 있는 동안만 동작. Ctrl+C나 창 닫으면 멈춤. PC 슬립 시 연결 끊김.

macOS 슬립 방지 (Mac Mini에 특히 유용):

caffeinate -dims

또는 시스템 설정 → 에너지 절약 → "디스플레이 끄기 제외" + 절전 모드 비활성화.

Windows 슬립 방지: 설정 → 시스템 → 전원 → "절대 절전 모드로 설정 안 함".

스케줄러도 병행하려면 별도 터미널:

solosquad schedule

A-2. Docker Compose (백그라운드 + 자동 재시작, 권장)

전제: Docker Desktop 설치 (https://docs.docker.com/desktop/). macOS Apple Silicon/Intel 모두 동작. solosquad init이 Dockerfile과 docker-compose.yml을 워크스페이스에 복사했는지 확인.

cd ~/solosquad-workspace
docker compose up -d --build      # 최초 빌드 + 백그라운드 기동
docker compose logs -f bot        # 봇 로그
docker compose logs -f scheduler  # 스케줄러 로그
docker compose ps                 # 서비스 상태
docker compose restart            # 재시작
docker compose down               # 정지

Claude Code 인증 공유: 컨테이너 내부의 claude CLI도 인증이 필요. docker-compose.yml이 호스트의 ${HOME}/.claude를 컨테이너의 /root/.claude로 마운트 → 호스트 로그인 세션 공유.

1. 호스트에서 claude login 완료
2. docker compose up -d --build
3. 컨테이너 안의 claude가 호스트 자격증명을 읽어 동일 계정으로 동작

다른 경로면 .env에 명시:

CLAUDE_AUTH_DIR=/Users/youruser/.claude

PC 재부팅 후: Docker Desktop 자동 시작 설정 시 (Docker Desktop 설정 → "Start Docker Desktop when you log in") 컨테이너는 restart: unless-stopped 정책으로 자동 복귀.

A-3. macOS launchd / Windows NSSM (서비스화)

Docker 없이 네이티브 프로세스를 로그인 시 자동 시작하려면.

macOS — launchd. ~/Library/LaunchAgents/com.solosquad.bot.plist:

<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN"
  "http://www.apple.com/DTDs/PropertyList-1.0.dtd">
<plist version="1.0">
<dict>
  <key>Label</key><string>com.solosquad.bot</string>
  <key>ProgramArguments</key>
  <array>
    <string>/usr/local/bin/solosquad</string>
    <string>bot</string>
  </array>
  <key>WorkingDirectory</key><string>/Users/YOURNAME/solosquad-workspace</string>
  <key>RunAtLoad</key><true/>
  <key>KeepAlive</key><true/>
  <key>StandardOutPath</key><string>/tmp/solosquad-bot.log</string>
  <key>StandardErrorPath</key><string>/tmp/solosquad-bot.err</string>
</dict>
</plist>

경로(/usr/local/bin/solosquad)는 which solosquad로 확인. 등록/시작:

launchctl load ~/Library/LaunchAgents/com.solosquad.bot.plist
launchctl start com.solosquad.bot
tail -f /tmp/solosquad-bot.log

스케줄러도 동일하게 com.solosquad.scheduler.plist 추가.

Windows — NSSM:

1. https://nssm.cc 에서 NSSM 다운로드 → nssm.exe를 PATH에 추가
2. 관리자 PowerShell:

   nssm install SolosquadBot "C:\Users\YOU\AppData\Roaming\npm\solosquad.cmd" bot
   nssm set SolosquadBot AppDirectory "C:\Users\YOU\solosquad-workspace"
   nssm start SolosquadBot

B. 클라우드 VPS (고급)

"집에 서버 둘 생각 없음" 또는 "PC 꺼도 봇은 살아있어야" 할 때.

고려 시점:

• 집에 24/7 켜둘 PC 없음
• 여행 중이거나 노트북만 쓰는 라이프스타일
• 팀원 추가로 봇을 공동 운영해야 함
• 안정성이 사업에 직결 (자동 알림/루틴 실패가 손실)

빠른 요약 (VPS + systemd):

# VPS SSH 접속 후
sudo apt update && sudo apt install -y nodejs npm git
npm install -g @anthropic-ai/claude-code solosquad
mkdir ~/solosquad && cd ~/solosquad
solosquad init
claude login
# systemd 서비스 등록 — 상세는 docs/cloud-deployment.md

7.2 멀티 워크스페이스 (페르소나 분리)

본업/사이드 페르소나를 분리하고 싶을 때 Discord 워크스페이스를 여러 개 만듭니다. (Slack 어댑터로 분리하는 것도 코드상 가능하지만 v1.0 SemVer 약속 외.)

~/solopreneur/      # Discord 봇, 본업 페르소나
~/personal-lab/     # Discord 봇, 사이드 페르소나

각각 독립된 .env·토큰·봇 계정을 갖습니다. 서로 간섭 없이 동시 운영 가능. 이 제약은 v0.2.0부터 — 이전 v0.1.x의 MESSENGER=discord,slack 복수 지정은 더 이상 지원하지 않습니다.

업데이트 시: CLI 업데이트는 한 번이면 되지만 마이그레이션은 각 워크스페이스에서 개별 실행 (§4.4 참조).

7.3 제품 여러 개 운영 (조직·저장소 관리)

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

조직 추가

solosquad add org <name>                        # 대화형 (provider/remote_url 질의)
solosquad add org my-side --provider github --remote-url https://github.com/my-side

<workspace>/<name>/ 폴더 + .org.yaml + memory/ (routine-logs/ + 4개 JSONL 스키마) + workflows/ + repositories/ + 메신저 폴더 자동 생성.

저장소 추가

URL이면 clone, 경로면 등록(필요시 이동).

solosquad add repo https://github.com/foo/bar.git                       # clone + 등록
solosquad add repo ./existing-local-repo                                # 이동(확인 후) + 등록
solosquad add repo https://github.com/foo/bar.git --org tesla --role frontend
solosquad add repo <url|path> --slug my-custom-slug                     # 폴더명 override

org 자동 판정 순서:

1. --org <slug> 명시 → 즉시 사용
2. 워크스페이스에 조직이 하나뿐 → 자동 선택 (묻지 않음)
3. 현재 cwd가 특정 org 폴더 안 → 그 org 자동
4. 복수 org + 위 모두 해당 안 됨 → 대화형 선택

자동 추출:

• remote_url — git remote에서 읽어 repo.yaml에 기록
• language — package.json (TypeScript 자동 감지) / pyproject.toml / go.mod / Cargo.toml에서 감지
• role 기본값 — .git 있으면 main, 없으면 unknown

Bulk 동기화

이미 repositories/에 clone해둔 repo들을 한 번에 등록:

solosquad sync                # 모든 org 스캔
solosquad sync --org tesla    # 특정 org만
solosquad sync --dry-run      # 미리보기 (아무 것도 쓰지 않음)

동작:

• <org>/repositories/<folder> 중 .git 있는데 repo.yaml 없는 경우 → 자동 등록
• 이미 등록된 repo → = 표시로 스킵
• .git 없는 폴더 → ? 경고 표시 후 스킵
• .org.yaml.products[].repos를 실제 존재 repo 목록으로 갱신
• .org.yaml에 나열됐지만 실제 폴더가 없는 repo → - 빨간색 경고

Cross-repo workflow (v0.2.1+)

v0.2.1 런타임은 워크플로우 _status.yaml의 stage에 target_repo 필드가 있으면 해당 stage 실행 시 그 repo를 cwd로 사용합니다. 여러 repo에 걸친 작업 흐름을 하나의 workflow로 조율 가능:

# <org>/workflows/model-y-refresh/_status.yaml
stages:
  - id: stage-1-vision
    target_repo: autopilot-vision       # Claude가 이 repo를 cwd로
    status: in_progress
    depends_on: []

  - id: stage-2-planner
    target_repo: autopilot-planner      # 다른 repo
    status: pending
    depends_on: [stage-1-vision]

활성 stage 판정:

1. status: in_progress인 stage가 있으면 그것
2. 없으면 status: pending 중 depends_on이 모두 completed인 첫 stage
3. 둘 다 없으면 role=main repo → org 루트 순 fallback

stage 상태 전환 (pending → in_progress → completed)은 v0.3 PM 모드에서 자동화됩니다 — PM이 specialist를 spawn하기 전에 in_progress로 표시하고, Task tool 응답을 합치며 completed로 갱신.

7.4 보안 체크리스트

이 시스템은 AI가 코드와 명령을 실행합니다. 다음을 꼭 확인.

• .env가 .gitignore에 포함되어 있는지
• 봇 토큰 주기적 교체 (90일 권장)
• AI 출력을 프로덕션에 배포하기 전 반드시 검토
• 메신저 봇 권한은 최소로 설정 — §5의 scope 리스트 이상 주지 않기
• solosquad doctor 주기적 실행
• 클라우드 운영 시: SSH 키 인증만 허용, 방화벽은 아웃바운드만 허용
• v0.8.1+: solosquad archive verify를 외부 저장 전에 1회 실행 (PII-NOTICE 스캔 + manifest SHA 검증)
• v0.8 멀티유저: 추가 사용자 등록 시 봇 multiplicity 안내 — 각 유저는 자기 채널 쌍(command-<handle>/works-<handle>)에서만 응답 (author-guard)

상세: docs/plan/v0.2-safety-security.md, docs/plan/v0.8.1-security-lifecycle-pair.md

7.5 정기 백업 + 관측성v0.8.3

운영 중 정기 백업 + 로그 관측을 위한 흐름.

• 정기 백업: 월 1회 권장. solosquad uninstall --mode archive-only로 farewell archive zip만 생성(워크스페이스는 그대로). archive는 manifest.tsv SHA로 무결성 보장. 외부 저장 전 solosquad archive verify로 PII-NOTICE 스캔 권장. 마이그레이션 백업(~/.solosquad-backups/)은 solosquad backup list로 조회, 오래된 백업은 solosquad backup purge --keep-recent 3로 정리
• gh CLI 인증: dev_capability(patch/pr)가 PR을 만들려면 gh auth login이 호스트에 완료되어 있어야 함. solosquad doctor가 gh 존재만 체크 — 토큰 유효성은 gh auth status로 별도 확인
• 로그 위치 + retention: SOLOSQUAD_LOG_FILE=1 활성 시 <workspace>/.solosquad/logs/solosquad-YYYY-MM-DD.log 일별 rolling. 14일 보존(매일 00:30 log-rotate routine). SOLOSQUAD_LOG_FORMAT=json으로 구조화 출력 가능
• solosquad logs 명령: 4 operational jsonl(agent-costs / spawn-decisions / stop-hook-events / dev-confirmations / migration-costs)을 한 곳에서 tail/follow/필터 가능
• CLI ↔ workspace mismatch: solosquad doctor가 mismatch 감지 시 migrate vs update 어느 쪽이 필요한지 명시

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.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

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에서 추가).