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 Slack 봇 설정 (9단계) post-v1.0

본 절은 post-v1.0 슬롯 — v1.0 SemVer 약속 대상이 아닙니다. v0.9.x에서 이미 Slack을 운영 중이거나 향후 슬롯이 활성화될 때 참조하세요. 새로 시작하는 사용자는 §5.2 Discord를 권장합니다.

최종 결과물: .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.2 Discord 봇 설정 (8단계)

최종 결과물: .env에 DISCORD_TOKEN=...이 저장되고, Discord 서버의 #owner-command에서 봇이 응답.

MESSENGER=discord
DISCORD_TOKEN=MTIzNDU2...

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.용어 사전

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

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

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

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

7.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. 사람이 읽기 쉬운 설정 파일 포맷.

8.버전별 차이

현재 npm에서 받을 수 있는 기능과 향후 출시 예정 기능을 명확히 구분합니다.

8.1 현재 npm 배포 가능 (v0.7.0 ~ v0.8.3)사용 가능

코어 기능 (v0.1~v0.2)

• npm install -g solosquad 한 줄 설치 (Mac/Windows/Linux)
• 25 specialist agents (전략 7 / 그로스 4 / 경험 4 / 엔지니어링 10)
• 2채널 메신저 (Discord / Slack — 워크스페이스당 1개)
• 5종 자동 routine (Morning/Evening Brief, Signal Scan, Experiment Check, Weekly Review)
• 3-Layer Context (workspace / organization / repository)
• JSONL append-only 메모리 (signals, experiments, decisions, routine-logs)
• workspace.yaml 설정 (timezone, briefing 시각, routine 활성화)
• 마이그레이션 프레임워크 (v0.1.x → v0.2.x backup → apply → verify → rollback)
• Docker compose 옵션 (백그라운드 + 자동 재시작)
• VPS systemd 서비스 등록 가이드 (docs/cloud-deployment.md)
• 다중 조직 / 다중 repo 지원 (solosquad add org/repo/sync)
• 환경 진단 (solosquad doctor·--messenger-check)

PM 모드 + 멀티 에이전트 오케스트레이션v0.3

• PM 에이전트가 사용자와의 모든 소통 전담 (영구 session, claude --resume)
• specialist는 ephemeral subagent로 spawn via 내장 Task tool (depth=1)
• 슬래시 5종 (/think /plan /build /review /ship) + /help
• _events.jsonl 표준 (PM session 이벤트 로그) + spawn 마커 [stage:<id> wf:<id>]
• focus 마커 [focus:<wf-id>] / [focus:none] 양방향
• PM compaction routine (완료 워크플로 → memory/pm-skills/ 외부화, 23:00 daily)
• boot-time recovery (workflow-reconciler.ts) — orphaned in_progress → needs_revision, 누락 응답 재전송
• per-org snapshot.git (memory/ + workflows/만) + solosquad rollback --workflow <id> revert
• solosquad pm · solosquad workflow · solosquad rollback 전체 CLI

자율 실행 엔진 (Goal Runner)v0.4

• 2계층 구조: goal.md (1회 실행 의도) + AGENTS.md (영속 가이드, cross-tool 표준)
• OpenAI Codex /goal 패턴 차용 — 사람만 수정, 모델은 시작·완료만
• 3단계 가드레일: preflight Input guard / runtime guard (timeout · discard streak · cost cap 90% 워닝) / Output guard (forbidden side-effects + HTTP whitelist)
• AGENTS.md에 immutable_paths · modifiable_paths · external_side_effects · 가드레일 임계치 박제
• 메트릭 측정 → keep/discard → git-snapshot per cycle. CONFIRMING 게이트(모든 메트릭 ≥ threshold) 통과 시에만 _best.json 갱신
• solosquad goal run <goal-id> [--hours N | --cycles N] — N시간 자율 반복 (background PM session bg-<goal-id>-<runId>)
• solosquad goal verify — 결정론 재계산 검증 (reconciliation)
• 전체 CLI: goal new / list / show / run / status / stop / verify

워크플로 메이커 + SKILL 시스템 통합v0.5

• SKILL.md Anthropic Agent Skills 호환 frontmatter 파서 + validator (src/bot/skill-parser.ts)
• SKILL 스키마 확장: stateful·triggers(4채널)·loop_mode(spec-gate)·budget
• 4채널 라우터 (slash > explicit > keyword > freq) + 3-tier 검색(org > user > bundle) + atomic swap hot-reload
• Freq 채널: 빈도 카운팅 자동 로드 + cooldown_turns hysteresis + workspace당 20개 상한
• AGENT_ROUTES 하드코드 상수 제거 — 각 SKILL.md의 triggers.keyword에 분산. 25개 번들 SKILL frontmatter 백필 완료 (idempotent)
• 메신저 author 루프(CLARIFY → DRAFT → SANDBOX → AWAIT_CONFIRM → APPLIED) via assets/agents/_meta/workflow-maker/SKILL.md
• spec-gate SKILL은 goal.md도 자동 emit → v0.4 goal-runner에 자율 cycle로 등록
• paperclip envelope 차용 author 일/주 budget cap + <org>/memory/author-costs.jsonl
• repo analyzer: 4-라벨 분류(role / workflow / codebase-fact / domain), 결정적 매칭, ledger 증분, applier backup/apply/verify/rollback
• solosquad agent add / list / info / validate + analyze repo + add repo --from-report CLI
• CI 게이트: npm run validate-skills (= solosquad agent validate --all --corpus)

디폴트 워크플로 튜닝 + 메모리 인프라 + 자가 진화v0.6

v0.3~v0.5에서 누적된 실전 데이터를 회고할 인프라 + 누적 메모리의 FTS5 검색 + 반복 패턴 자동 SKILL 추출 + org × agent 색채/budget 분리 + chokidar hot-reload + CI PR 봇 + 0.5→0.6 마이그레이션을 한 릴리스에 통합. 코드 분량 ~12,000 LOC, 신규 테스트 152 (총 회귀 421/421 그린).

• S1 — readiness + ETL + onboarding 두 트랙: solosquad readiness check --target v0.6 CLI + 5 v0.5 데이터원 ETL → 야간 v06-retrospective-stats routine + 신규 vs 기존 v0.5 사용자 init 분기
• S2 — 폴더 재편 + 핸드오프 3변형: agents/_teams/ → agents/{team}/KNOWLEDGE.md co-location + handoff-{hierarchical,graph,dynamic}.md + 25 SKILL.md collab_pattern frontmatter 정식화 (22 hierarchical / 2 graph / 1 dynamic)
• S3 — Org Layer + budget + spawn-assembler: <org>/core/·agent-profile.yaml·domain/ 신설 + 8-layer JIT inject + max_context_tokens drop 정책 + ~/.solosquad/agent-profile-defaults.yaml user-global 상속 + schema_version: 1 forward-compat
• S4 — FTS5 archive + 4 event_type + retention: archive.sqlite + 매일 00:00 archive-rotate + route_hit/route_miss/author_turn/spawn_decision 인덱싱 + retention_days: 365 + compress_before_delete 옵션
• S5 — Trajectory + Freq miner + Stop-hook DSL: 야간 패턴 추출 (v0.5 applyDraft() 직접 재사용) + 키워드 자동 추천 (frontmatter-only mode) + stop_when 3 형식(command/metric/natural) DSL + 5초 timeout
• S6.A — fs.watch + 3 mode + git_only: chokidar 3-tier watch + 300ms debounce + fs_watch.mode: auto/prompt/manual + git_only 안전 모드 + solosquad agent reload
• S6.B — CI PR 자동 리뷰 봇: .github/workflows/skill-review.yml + frontmatter diff 댓글 + 키워드 충돌 경고 + agent-profile/core/domain/.org.yaml 6 validator
• S6.C — Migration 0.5→0.6: 2-pass dry-run + 사람 검수 게이트 + v0.5 ledger pending_v0.6_redestination 자동 재분류 + 휴리스틱 fail-soft는 human_review_required: true 마킹 + 자체 budget cap
• CLI 신규: readiness check·memory search/stats [--disk]·agent reload

Uninstall & Lifecycle (Farewell Archive)v0.7

install ↔ uninstall 2단으로 라이프사이클을 닫는다. solosquad reset·solosquad clean 같은 "초기화" 명령은 영구히 추가하지 않음 (재설치 = uninstall + farewell + 새 워크스페이스 init).

• 사용자 코드 절대 불가침 — <org>/repositories/<repo>/ 트리는 어떤 플래그로도 변경/삭제 0건. 트리 enumerate조차 안 함
• Farewell archive 강제 — uninstall은 항상 zip을 먼저 생성, --no-archive 같은 플래그 없음. 포맷: archive.yaml(schema_version=1) + manifest.tsv(streaming SHA256) + workspace/ + orgs/<slug>/{memory,workflows,goals,domain,core,repos}/ + credentials/env.template(마스킹) + REVOKE-CHECKLIST.md + PII-NOTICE.md
• 데이터 5분류 (A/A*/B/C/D/E) + --keep-workspace 매트릭스 — class B는 archive 후 디스크 보존, sessions는 _archived/로 이동, workspace.yaml은 새로 발급 위해 삭제
• WAL-safe SQLite backup (Hermes 차용) — v0.6 memory/archive.sqlite를 better-sqlite3 backup() API로 live write 중에도 일관 복사
• concurrent-uninstall lockfile — <workspace>/.solosquad/uninstall.lock 원자적 acquire + stale PID 자동 정리
• stage progress journal — uninstall.journal.jsonl append-only, cleanup 50% 중단 시 idempotent 재개
• PM/scheduler PID 거부 — archive walking 중 jsonl grow → SHA 불일치 방지. --force 없이는 진입 거부
• 워크스페이스 git tree 감지 — <workspace>/.git 존재 시 명시적 사용자 동의 강제
• archive 경로 writable + 디스크 free × 1.5 검증
• PII-NOTICE.md 자동 동봉 + opt-in --scrub-content (regex 룰셋: 카드번호·이메일·전화·SSN/주민번호 — false-negative 가능성 명시, 자동 스크럽 확장은 v1.x)
• logout/uninstall 분리 (gh CLI 차용) — solosquad logout는 .env 마스킹 + sessions _archived/로 + logout.lock 생성 (이후 solosquad bot/schedule은 진입 거부)
• REVOKE-CHECKLIST.md 동적 생성 — Discord application ID, Slack workspace ID, ~/.claude/projects 추정 경로, pm2/systemctl/crontab 점검 명령 자동 추출
• doctor 확장 — npm 글로벌 훅 한계 경고(solosquad uninstall을 npm uninstall -g보다 먼저), stale lockfile 감지, PM PID 점검, archive 디렉토리 free space
• CLI: solosquad uninstall [--dry-run --archive-only --keep-workspace --also-purge-backups --scrub-content --force], solosquad logout [--org <slug> --all --force]
• 마이그레이션: 0.6.0-to-0.7.0.ts — version bump + workspace.yaml.uninstall 기본값. schema 변경 거의 없음 (uninstall 인프라 신설 위주)
• 의존성: archiver ^7.0.1 (streaming write — adm-zip OOM 회피로 선택)

Multi-User Messengerv0.8.0

워크스페이스가 1인 운영자 모델에서 다수 사용자 컨텍스트를 다룰 수 있는 구조로 확장. 모든 메시지 라우팅은 command-<handle>·works-<handle> 채널 쌍에 author-guard로 차단된다 (도용 방지). 상세는 docs/plan/v0.8-multiuser-messenger.md.

• <org>/.solosquad/users/<handle>.yaml per-user 메타 — handle/platform/userId/channels/registered_at
• 채널 자동 부트스트랩 (channel-bootstrap.ts) + 멀티유저 broadcast (messenger/broadcast.ts)
• solosquad messenger CLI (사용자 등록·재발급·broadcast 토글)
• doctor 확장: 사용자 등록 합산·채널 매핑 검증
• 마이그레이션 0.7→0.8: workspace.yaml.messenger 기본값 + 운영자 1명 자동 등록 (Discord/Slack 토큰으로 /users/@me 조회)

Security & Lifecycle Pairv0.8.1

v0.7 archive 포맷의 reverse path를 잠그고 secret/PII 처리를 강화. 상세는 docs/plan/v0.8.1-security-lifecycle-pair.md.

• solosquad import <archive.zip> — farewell archive를 새 워크스페이스로 복원 (manifest SHA 검증 + merge strategy)
• solosquad archive verify <archive.zip> — manifest.tsv 무결성 + PII-NOTICE 스캔
• SKILL.md frontmatter requires_secret — 필요 시크릿 명세 (workflow-maker 게이트)

Dev Capabilityv0.8.2

"PR까지 만들어줘" 패턴을 SKILL의 dev_capability frontmatter로 표준화. dev confirmation 흐름(30분 timeout)으로 봇이 직접 git 변경을 만들기 전 사용자 확인을 받는다. 상세는 docs/plan/v0.8.2-dev-capability.md.

• SKILL.md dev_capability: read|propose|patch|pr 4단계 권한
• spawn-assembler가 capability 검증 후 layer 8(target_repo)에 read/write 권한 분기
• dev-confirm.ts 30분 timeout — 미응답 시 자동 abort + dev-confirmations.jsonl 기록

Onboarding UX + Observabilityv0.8.3

처음 SoloSquad를 만났을 때의 경험 + 문제가 생겼을 때 디버깅 경험을 동시에 잡는 마지막 v0.8.x 패치. 상세는 docs/plan/v0.8.3-onboarding-ux-observability.md.

• add repo --dry-run / --inspect — 사용자가 자기 product code를 SoloSquad로 들여올 때 폴더 매핑·사이즈·위험 시나리오 5종(IDE lock·심링크·외부 절대경로·slug 충돌·활성 프로세스) 미리보기. 디스크 변경 0건
• --keep-original — 이동 대신 복사 (디스크 2× 사용, 원본 안전망)
• logger 확장 — SOLOSQUAD_LOG_LEVEL·SOLOSQUAD_LOG_FORMAT=json·SOLOSQUAD_LOG_FILE=1 → <workspace>/.solosquad/logs/solosquad-YYYY-MM-DD.log rolling 14일. 기존 logger.info/warn/error API 그대로
• solosquad logs CLI — --level/--tail/--follow/--since/--type 으로 runtime + costs/spawn/stop-hook/dev-confirm/migration jsonl 한 곳에서 조회
• log-rotate routine — 매일 00:30 보존 기간 초과 파일 삭제 (silent)
• solosquad logout 제거 — v0.7 추가 후 가치 < 복잡도 판정. 대체 흐름: Ctrl+C로 봇 중지 / solosquad uninstall --archive-only로 토큰 정리
• doctor 보강 — CLI ↔ workspace version mismatch 감지 + 어느 명령(update vs migrate)을 써야 할지 명시
• trajectory ROI 측정 — v0.6 §3.X 4지표를 30일 데이터로 측정 후 CHANGELOG [0.8.3]에 박제. 통과 시 v0.9에서 auto_register 활성
• 마이그레이션 0.8.2→0.8.3: workspace.yaml.trajectory.auto_register 키 + log-rotate routine 복사

제거됨

• Telegram 어댑터 — v0.2.4부터 미지원v0.2.4 제거
• 채널 자동 정리 안 됨 — 이전 daily-brief·signals·experiments·weekly-review·errors 5개 채널은 사용자가 메신저 UI에서 수동 archive
• AGENT_ROUTES 하드코드 상수v0.5 제거 — 키워드 라우팅은 각 SKILL.md의 triggers.keyword frontmatter로 분산
• assets/agents/_teams/ 디렉토리v0.6 제거 — agents/{team}/KNOWLEDGE.md co-location 후 평행 hierarchy 폐지. 마이그레이션이 사용자 워크스페이스의 .solosquad/agents/_teams/도 자동 이동
• solosquad reset·solosquad clean 같은 "초기화" 명령v0.7에서 영구 거부 — 라이프사이클은 install ↔ uninstall 2단으로 충분. 재설치는 uninstall + 새 워크스페이스 init으로 표현
• solosquad logoutv0.8.3 제거 — v0.7에서 gh CLI 차용으로 도입했으나 가치 < 복잡도. 봇 일시 정지는 Ctrl+C, 토큰 정리는 solosquad uninstall --archive-only로 대체. logout.lock·logoutLockPath 코드도 함께 제거

8.2 추후 업데이트기획 단계

v1.0 — 정식 출시 (Formal Launch)

• v0.6까지 안정화 완료 + 솔로 파운더 자기 사용 검증
• 안정 API 약속 시작
• Breaking change 정책 도입
• v0.6 trajectory 자동 추출 ROI 지표 충족 시 *자동 등록 게이트* 검토

v1.0.4 — Discord config.yaml 자동 생성 + Slack author-guard 통째 cleanupv1.0.4

• Bug G — Discord 메신저 연결 실패 진짜 fix. v1.0.3 의 Bug D fix 가 *서버명 휴리스틱* 만 제거하고 *file-existence silent early-return* 분기는 남겨둠. scaffoldOrg 가 <org>/discord/config.yaml 을 never 작성해서 사용자가 v1.0.3 설치 후에도 "No product linked to this server" 받음. v1.0.4 는 load-or-empty + auto-write 패턴 — 봇 첫 시작 시 자동으로 그 파일 만들고 guild_id + channels 박제. 본 사용자 incident 진짜 해결.
• Bug H — Slack 어댑터 author-guard 통째 cleanup. v1.0.2 가 Discord 어댑터에서 제거했지만 Slack 의존성 때문에 유보했던 파일 삭제 마무리. src/messenger/slack-adapter.ts 의 author-guard 호출 제거 + audit log 추가. src/bot/author-guard.ts + test/author-guard.test.ts 통째 삭제.
• plan §1.3 박제 — v1.0.3 plan §6 의 반복 패턴 에 3번째 변형 추가: 권위 결정자가 있는데도 옛 기록 파일 유무로 silently bail 하는 코드도 trip-wire 대상. if (!fs.existsSync(x)) return; 류 silent bail 회귀 catcher 가이드라인 보강.
• Best Practice P 일부 — 5-hop 진단 메시지. 9-reference 조사 (OpenClaw / Claude Code Channels / LangChain / AutoGen / Composio / llmcord / openai-gpt-discord-bot / LibreChat / AnythingLLM) 합의된 Best Practice 5번 (누락값 hard fail + actionable hint) 즉시 도입. "No product linked to this server" generic 메시지를 5-hop chain 의 어느 마디가 깨졌는지 명시하는 진단 메시지 로 교체. 사용자가 어디부터 봐야 할지 즉시 파악. 향후 binding 회귀 시 attributable hop 으로 잡힘.
• plan §7.2 — Discord ↔ AI agent/LLM 연결 9-reference 조사 결과 박제. SoloSquad 가 (b) Runtime pairing 의 *자동 캡처* 만 채택하고 *명시 approve* 부재 = v1.0.2 ~ v1.0.4 4번 누적 회귀 root cause. 나머지 best practice (L 페어링 + approve CLI / M snowflake branded types / N silent early-return 전수 제거 / O token precedence) 는 v1.0.5 ~ v1.1 슬롯.
• 619 tests green (613 baseline + 12 신규 − 6 삭제). schema 변경 0, CLI surface 변경 0.

v1.0.3 — Discord 5-bug fix (migrate · sudo · 메신저 연결 · update next-step · 카테고리 이름)v1.0.3

• Bug A — solosquad migrate 영구 차단 해소. versionMatches 의 slice 산수가 X.Y.Z.x 패턴을 exact X.Y.Z 와 매치 못 해서 v1.0.0 → v1.0.x patch chain 이 영구 차단되던 회귀. "No migration found for source version 1.0.0" 오류 사라짐.
• Bug B — solosquad update 가 nvm/Homebrew 사용자에게 잘못된 sudo 권유 해소. process.getuid() 추측 → npm config get prefix + fs.accessSync(W_OK) 실제 권한 체크. 본인 prefix 가 user-owned 인 대다수 macOS 사용자 비번 입력 단계 사라짐.
• Bug D — Discord 메신저 연결 실패 해소. syncGuildProductMapping 의 v0.1.x 휴리스틱 (Discord 서버 이름이 SoloSquad org slug 를 포함해야 함) 제거 → 봇이 이미 자기 org 를 안다 (ownOrgSlug) 는 사실 활용. 서버 이름 임의로 두고도 "No product linked to this server" 오류 사라짐. 부팅 로그에 [Discord] Bound guild <name> (<id>) → org=<slug> 명시.
• Bug E — solosquad update 직후 다음 단계 안내. install 성공 후 workspace 버전 lag 검사 → Next step: solosquad migrate --apply 명시 출력. doctor 후속 round-trip 없이 한 흐름에서 path 받음.
• Bug F — Discord 카테고리 이름 "solosquad". v0.1.x 시절 agent-team-as-product vocab 의 "AI Team Reports" 카테고리 명 → 신규 생성은 "solosquad". 기존 카테고리는 lookup 으로 매치 + 재사용 (봇 강제 rename 안 함).
• 613 tests green (596 baseline + 17 신규). schema 변경 0, CLI surface 변경 0.

v1.0.2 — Discord author-guard 정합 + 온보딩 reorderv1.0.2

• Discord author-guard 영구 제거 — src/messenger/discord-adapter.ts 의 isAuthorizedAuthor 가드 블록 삭제. seungw1n. 처럼 Discord username 에 . 가 포함된 사용자가 자기 채널에서 자기 자신을 추방 당하던 false positive 영구 해소. 채널명 charset [a-z0-9_] 와 Discord username charset 의 영구 불일치를 정직히 박제 — *"username = handle"* 이라는 v0.8 §3.4 의 암묵 invariant 가 보편적으로 깨졌음을 인정.
• handle = SoloSquad 유일 canonical user identifier 로 격상. Discord message.author.username 은 더 이상 비교 대상 아님 — audit log 에 박제만 (사후 추적용, 게이팅 0). Discord 채널 ACL 이 유일 permission boundary.
• 온보딩 wizard reorder — handle 확인 단계를 Step 5.2 (토큰 입력 4 단계 뒤) → Step 3.5 (토큰 입력 직후) 이동. 사이에 timezone/workspace.yaml/org/repos 4 단계가 끼던 narrative 단절 해소. yaml write 는 Step 6 silent.
• handle 선택 안내 추가 — prompt 위에 "메신저 서버의 다른 멤버 username/display name 과 겹치지 않게" guidance 표시. 채팅 혼선 방지.
• Slack 동등 fix 는 v1.0.3 슬롯 — post-v1.0 분리 release. v1.0.2 에선 src/bot/author-guard.ts 파일 *유지* (Slack 어댑터 단일 사용자).
• 596 tests green (588 baseline + 8 신규). schema 변경 0, CLI surface 변경 0.

v1.0.1 — Discord deprecation + 다중-repo 라우팅v1.0.1

• discord.js ready 이벤트 → Events.ClientReady 전환. v14.26이 ready alias를 deprecate (게이트웨이 READY opcode와 이름 충돌 해소), v15에서 완전 제거 예고. 봇 시작 시 매번 출력되던 Node DeprecationWarning 사라짐 + v15 silent-failure 사전 차단
• repo role prompt 제거 — solosquad init / solosquad add repo의 Role: 질문 삭제. 신규 등록은 silent role = "main". --role flag는 power-user override로 유지(deprecation 안내). 사유: role의 실제 load-bearing 소비처는 스케줄러 default cwd 결정 1건뿐이었고, 사용자 메시지 routing에는 일절 관여 안 했음 — "frontend/backend/data/infra/docs" 값들은 어떤 라우팅에도 안 쓰이는 cargo cult
• @<slug> mention 라우팅 신설 — 사용자가 @landing-site 히어로 수정처럼 적으면 봇 pre-processor가 [target_repo:landing-site] 마커를 메시지 앞에 주입해 PM에 전달. 등록 slug 셋과 교집합 + Discord 핑(<@123456789>) 무시. routing 시점 LLM 호출 0 (GitHub Slack @<repo> + Nx nx run <project>:<target> 패턴)
• PM SKILL.md §"Multi-Repo Intent" 신설 — 마커 honor, 단일 repo 자동, 모호하면 *짧은 clarifying question 1번*. silent guessing 금지
• 588 tests green (573 baseline + 15 신규). schema 변경 0, CLI surface 변경 0 — api-stability 정책 준수

v1.1 — Multi-Agent Team Architecturev1.1

• 5-layer 위계 (Hermes V2 차용): L1 Gateway(v1.2) → L2 Orchestrator(Chief session, 구 PM) → L3 Team(team/{team}/{KNOWLEDGE,OKR}.md) → L4 Agent(4 main bots) → L5 Specialist(20 + skills/)
• 디렉토리 재편 (2026-05-27): assets/ 폴더 폐지 → workspace 루트 5 디렉토리. agents/main(4) + agents/specialists/{team}(20) + skills/(cross-agent 도구) + user/(founder 정보) + team/{team}/{KNOWLEDGE,OKR}.md(팀 지식+OKR) + schedules/(구 routines)
• Chief = orchestrator + 도메인 전문가 겸업: <org>/agents/main/chief/SKILL.md — organization 위계 거주, org 마다 도메인 전문가화 customize. 기존 PM session 격상
• 4 main + 20 specialist (2-tier): chief · designer · engineer · marketer + 각 팀 specialists. 5 specialist 병합 — backend-engineer · data-engineer · idea-scoper · researcher · content-marketer 신설
• Chief = Supervisor 6 stage: TRIAGE → DECOMPOSE → DISPATCH → AWAIT → SYNTHESIZE → DECIDE (LangGraph + AutoGen 합의 패턴)
• Educational Nudge (Triage stage 0): 막연한 입력 → KNOWLEDGE.md slice 우선 제시 후 진행 확인
• Dependency Injection (8-layer JIT Layer 6.5): stage 도메인 키워드 매칭 → signals.jsonl 자동 inject. Layer 4a (Team OKR) 신설
• 실험 인프라: <org>/experiments/<id>/manifest.yaml + Amplitude 4 패턴 차용 + significance check
• SKILL frontmatter v1 → v2: bot_name / tier / domain_tags / routing_keywords 4 신규 필드
• routine → schedule 어휘 통일: assets/routines/ → schedules/, CLI run-routine → run-schedule (alias 6개월)
• Board of Agents 톤: Chief = "이사회 의장", 사용자 = "founder", specialist = "이사회 멤버"
• 자세히 docs/prd/v1.1-multi-agent-team-architecture.md (§21 Amendment 포함)

v1.2 — 메신저 연결 (Discord 우선)v1.2

• L1 Gateway 분리: v1.1 의 L2~L5 위에 메신저 표면만 추가
• Bot Identity Registry (<org>/.solosquad/bots.json) + 9-hop diagnostic + Echo guard
• Forum Channel + Thread budget: goal 1 cycle = 1 forum post
• Mention routing 확장: v1.0.1 @<slug> 위에 @<bot> 추가 (예: @eng 이거 어떻게 짜)
• v1.0.4 G+H+P + 미적용 L+M+N+O Best Practice 본 슬롯 흡수. Slack 동등 fix 는 v1.2.x patch
• 자세히 docs/prd/v1.2-messenger-connection-discord-first.md

v1.x — cascade-shifted 슬롯v1.x

• 구 v1.1 → v1.x 대시보드 상호작용 — 웹 대시보드 자체는 별도 리포(solopreneur-dashboard/solopreneur-api). 본 리포는 상호작용 클라이언트·인박스만
• 구 v1.2 → v1.x 지식·암묵지 온톨로지 — MCP 외부 연결 (Notion·Obsidian·외부 API·타 에이전트)
• cascade 사유: 1인 dogfooder 단계 leading indicator(24/7 자율 팀)가 dashboard·ontology 보다 우선. 자세히 docs/prd/product-roadmap.md §6 2026-05-24 entry

참고 문서

• docs/plan/v0.3-pm-mode-orchestration.md
• docs/plan/v0.4-autonomous-engine.md
• docs/plan/v0.5-workflow-maker.md
• docs/plan/v0.6-default-workflow-tuning.md
• docs/plan/v0.7-uninstall-lifecycle.md
• docs/plan/v0.8-multiuser-messenger.md
• docs/plan/v0.8.1-security-lifecycle-pair.md
• docs/plan/v0.8.2-dev-capability.md
• docs/plan/v0.8.3-onboarding-ux-observability.md
• docs/prd/v1.1-multi-agent-team-architecture.md — 신 v1.1. Multi-Agent Team Architecture
• docs/prd/v1.2-messenger-connection-discord-first.md — 신 v1.2. 메신저 연결 (L1 Gateway)
• docs/prd/v1.x-dashboard-interaction.md — 구 v1.1 cascade-shifted
• docs/prd/v1.x-knowledge-ontology.md — 구 v1.2 cascade-shifted
• docs/prd/product-roadmap.md — 전체 결정 로그
• docs/reference/AI_Agent_Harness_Report.md — 설계 어휘 출처
• docs/trend-record/2026-05-11-baseline-survey.md — 피어 프로젝트 비교

9.운영 가이드

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

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

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

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

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

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

9.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로 갱신.

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

9.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 어느 쪽이 필요한지 명시

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 자주 묻는 질문 (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에서 추가).

10.4 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.5 봇 · 스케줄러 · 에이전트 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 머지를 사용자가 명시적으로 승인하게 강제하는 안전망.