2.How It Works

2.1 System Architecture

SoloSquad consists of 3 core processes and 1 persistent store.

Message processing flow (v0.6+)v0.6

Single-shot keyword routing evolved into the PM session model in v0.3, then to 4-channel routing + 3-tier search + atomic-swap hot-reload in v0.5. v0.6 added chokidar-based fs.watch hot-reload + 8-layer JIT spawn assembly + per-org × agent budget envelopes. On router miss, the FTS5 cold archive fallback recalls past decisions.

User → PM session (claude --resume <session-id>)
         ↓
         buildRoutes(): 3-tier scan
           [1] <org>/.agents/                  (org-local override)
           [2] ~/.solosquad/agents/             (user-global override)
           [3] <workspace>/.solosquad/agents/   (25 bundled)
         ↓
         4-channel resolver (priority: slash > explicit > keyword > freq)
           · slash    — "/think /plan /build /review /ship" etc.
           · explicit — PM calls a SKILL via reasoning
           · keyword  — single-turn message word match
           · freq     — auto-load when accumulated count crosses threshold
                        (cooldown_turns suppresses re-firing — hysteresis)
         ↓
         JIT inject matched SKILLs into context
         ↓
         Task: <agent> "..." (fresh subagent session, [stage:<id> wf:<id>] marker)
         ↓
         Merge result summary into PM context → next spawn or report to user
         ↓
         git-snapshot before-spawn / after-spawn auto-commits (<org>/.solosquad/snapshot.git)

[Parallel] When a new SKILL.md is saved, the router does an atomic swap:
            build new index → swap ref → messages in flight keep using the old index
            (no bot restart required)

For v0.4 autonomous execution, solosquad goal run <goal-id> spawns a background PM session (bg-<goal-id>-<runId>) that runs the same 4-channel routing inside each cycle. Metric-gated keep/discard, git-snapshot revert, and cumulative cost caps apply per cycle.

2.2 Directory Hierarchy

Current npm release (v0.8.5) structure

3-tier search priority (v0.5): for a SKILL with the same name, override order is <org>/.agents/ > ~/.solosquad/agents/ > <workspace>/.solosquad/agents/ (bundled). The router scans all three at boot and merges them into a single index.

v0.6 new assetsv0.6

The Org Layer (which absorbs each organization's tone/emphasis/budget for the 25 specialists) and the Workspace Knowledge Layer (which separates accumulated craft) are formally introduced as first-class assets in v0.6. Bundled SKILLs are not modified line-by-line — org flavor enters only through the assets below.

• assets/agents/{team}/KNOWLEDGE.md — previously _teams/*/TEAM_KNOWLEDGE.md, now co-located (Team = Domain). Auto-injected when any same-team agent spawns.
• <org>/core/{PRINCIPLES,VOICE}.md — org philosophy / tone (overrides workspace core/). Spawn still works with empty files.
• <org>/agent-profile.yaml — per-org modifiers for 25 agents (defaults + per-agent section + budget + schema_version: 1). Per-agent budgets may only *narrow* the defaults.
• <org>/domain/{market,customers,product}.md — org domain knowledge (market, customers, product).
• .solosquad/knowledge/ — accumulated shared user knowledge (decision frameworks, domain glossary). Selectively injected on keyword match.
• ~/.solosquad/agent-profile-defaults.yaml — user-global inheritance. Shared budget/voice defaults across N orgs. Inheritance: workspace bundle defaults → user-global → org agent-profile.
• <org>/memory/archive.sqlite — FTS5 cold archive (JSONL older than 8 days moves to SQLite FTS5 virtual table, search fallback).

agent-profile.yaml example

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

business-strategist:
  emphasis: "Prioritize the Korean SMB market context"
  decision_frame: "Cash flow > growth rate"

content-writer:
  voice: "professional, no hype"
  ban_phrases: ["revolutionary", "groundbreaking"]

paid-marketer:
  budget:                       # may only narrow defaults
    daily_usd: 2

Agents not specified inherit only the defaults block. When the cap is hit at spawn time, the spawn is refused and the PM responds "Daily budget reached — please try again tomorrow." Accumulator: <org>/memory/agent-costs.jsonl.

2.3 Context & Memory Management

Current memory structure (v0.2.4)

Every routine result appends to a JSONL file. One JSON line = one event.

<org>/memory/signals.jsonl example:
{"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-layer context (P/E/T vocabulary)

Just-in-Time injection principlev0.5

Not every SKILL.md is added to context on every call. The 4-channel router (slash/explicit/keyword/freq) matches each turn and decides what to inject that turn, based on user keywords, slash commands, and frequency counts.

v0.6 memory flowv0.6

The v0.5 per-turn flow is preserved; v0.6 added spawn budget · 8-layer drop log · spec-gate evaluation · migration cost. During one PM turn, these files are updated:

• <org>/.solosquad/sessions/<user>.json — last interaction, cumulative cost USD, activeWorkflowId, freqCooldowns (v0.5 — per-turn decay)
• <org>/workflows/<wf-id>/_events.jsonl — PM messages · spawn · completion events
• <org>/.solosquad/snapshot.git — before/after-spawn commits (memory/ + workflows/)
• <org>/memory/author-costs.jsonl — author-loop cumulative USD per step (v0.5)
• <org>/memory/agent-costs.jsonl v0.6 — per-agent spawn cost accumulator for agent-profile budget cap
• <org>/memory/spawn-decisions.jsonl v0.6 — log of which layers were dropped when token cap was hit (FTS5-indexed §4.6)
• <org>/memory/stop-hook-events.jsonl v0.6 — spec-gate hook evaluation result at cycle end
• <org>/memory/migration-costs.jsonl v0.6 — 0.5→0.6 migration's own LLM fallback cost accumulator
• <org>/memory/pm-skills/_recent.md — one-line summaries of workflows externalized by pm-compaction (PM reads this on the next turn)

FTS5 cold archivev0.6

As JSONL accumulates, search slows down. v0.6 moves entries older than 8 days to the SQLite FTS5 virtual table <org>/memory/archive.sqlite, keeping them searchable via token matching. The nightly archive-rotate routine (00:00; merged into system-housekeeping in v0.8.5) does this automatically. Search recall without a semantic-embedding infrastructure.

4 event_type indexingv0.6

v0.6 indexes 3 new event sources (router · author · spawn) alongside existing routine-logs/*.jsonl into the same archive. Data sources for §3 trajectory extraction and §3.4 freq auto-suggestion:

Retention policyv0.6

The archive retains 365 days by default (workspace.yaml.archive.retention_days: 365). The archive-rotate routine performs the *delete old entries* step. Optional archive.compress_before_delete: true keeps an archive-<year-month>.zst for quarterly retention. Disk usage: solosquad memory stats --disk.

2.4 Workflow Definitions

4 default workflows

Key files: _status.yaml + _handoff.md

_status.yaml tracks per-stage progress (pending → in_progress → completed). _handoff.md is the context slice each stage hands off to the next agent.

_handoff.md standard sections:
- Summary: 3-line summary
- Artifacts: list of outputs
- Key Decisions: decisions + rationale
- Context for Next Agent: what the next agent should know
- Open Questions: unresolved questions

v0.6 handoff variants (3 types)v0.6

Different stages need different collaboration patterns; one template doesn't fit all. The 25 agent SKILL.md files now carry collab_pattern as a formal frontmatter field, and spawn applies the matching variant template automatically.

• hierarchical (22 agents) — Standard PM → specialist flow. Keep 4 sections (templates/handoff-hierarchical.md)
• graph (data-analyst, feature-planner) — Bidirectional convergence loop (e.g. research ↔ data-analyst). Adds state_object_diff, loop_count (templates/handoff-graph.md)
• dynamic (content-writer) — Next agent branches by result content. Adds routing_signal (templates/handoff-dynamic.md)

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

When a specialist spawns, context is assembled from the 8 layers below in priority order. When workspace.yaml.spawn.max_context_tokens (default 80,000) is hit, lower-priority layers are dropped, and the decision log is written to <org>/memory/spawn-decisions.jsonl (FTS5-indexed per §2.3):

spawn(business-strategist, org=Acme, repo?)
  └─ assemble:
       [1] .solosquad/knowledge/ + assets/knowledge/  (workspace shared, keyword-selective)
       [2] agents/strategy/KNOWLEDGE.md               (team(=domain) shared knowledge, same team only)
       [3] agents/strategy/business-strategist/SKILL.md  (agent identity, workspace-immutable)
       [4] <org>/core/                                (org philosophy/tone)
       [5] <org>/agent-profile.yaml defaults + business-strategist section (org modifier)
       [6] <org>/domain/                              (org domain knowledge)
       [7] <org>/workflows/<id>/_handoff.md + <org>/memory/ (recent + FTS5 recall)
       [8] target_repo context (only when target_repo field is set)

Drop-priority table

When drops occur, <org>/memory/spawn-decisions.jsonl records which layer was truncated — that line is indexed in the §2.3 FTS5 archive with event_type: spawn_decision.

3.Core Concepts

3.1 SKILL.md — Agent Identity Definition

SKILL.md is the manual describing "how this role works" for a single agent. It follows Anthropic's official Agent Skills format, with SoloSquad extensions for routing, loop_mode, budget, etc.

---
name: "Business Strategist"
description: "Business strategy · market analysis · competitive positioning"
team: strategy
stateful: false                    # v0.5 — all specialists are stateless
triggers:                          # v0.5 — 4-channel entry points
  slash: ["/strategize"]
  keyword: ["business strategy", "business model"]
  freq:                            # auto-load when cumulative count crosses threshold
    keywords: ["strategy", "positioning", "competition"]
    window_turns: 10
    threshold: 3
    cooldown_turns: 6
  explicit: true                   # PM can call directly via reasoning
inputs:
  required: [market_context, hypothesis]
  optional: [time_range]
outputs:
  - strategy.md
handoff_to:
  - feature-planner
  - pmf-planner
loop_mode:                         # v0.5 — spec-gate (Ralph loop) mode. null | spec-gate
  kind: spec-gate
  stop_when: "all tests pass"
budget:                            # v0.5 — paperclip envelope. Forwarded to author loop / explicit
  per_call_usd: 1.5
  daily_usd: 10
---

# Business Strategist Agent

You are a business strategy specialist helping a solo founder.

## Process
1. Understand the market context
2. Competitive analysis
3. Frame hypotheses + propose validation methods
...

• Location (3-tier search): <org>/.agents/ > ~/.solosquad/agents/ > <workspace>/.solosquad/agents/ (25 bundled)
• Load timing: Router picks via 4-channel matching → PM injects into system prompt when spawning via Task tool
• Property: Stateless (v0.5 enforced) — every call is a fresh session; state lives outside (workflows / handoff / memory). stateful: true is used only by PM and v0.4 goal-runner background sessions
• Required fields: name, description (Anthropic spec). The rest are SoloSquad extensions with router fallbacks if missing
• loop_mode = spec-gate: the author loop auto-emits <org>/goals/<goal-id>/goal.md as well → registers an autonomous cycle in the v0.4 goal-runner

3.2 KNOWLEDGE.md — Team (= Domain) Shared Knowledgev0.6

All agents in the same team share craft / definitions / anti-patterns through this file. v0.6 co-located it as agents/{team}/KNOWLEDGE.md, auto-injected when any same-team agent spawns (layer [2] of the 8-layer assembly).

3.3 CLAUDE.md — Project / Repo Guide

CLAUDE.md is the project-guide file that Claude Code (the general-purpose coding CLI) auto-loads at every session start. It is Claude Code's official convention, not a SoloSquad invention.

• Location: project root (or inside .claude/)
• Purpose: convey codebase structure, tech stack, user instructions to the model
• Load timing: Claude Code reads it automatically — no explicit user instruction needed

SoloSquad's own root CLAUDE.md targets developers of SoloSquad itself. When you work in your own product repo, that repo's CLAUDE.md applies.

Example: a user's SaaS repo CLAUDE.md
# My SaaS

TypeScript + Next.js. Deployed on Vercel.

## Conventions
- Components live in src/components/ as PascalCase
- API routes in src/pages/api/
...

3.4 SKILL.md vs AGENTS.md — Different Layers, Different Roles

SoloSquad uses both files but with clearly different responsibilities. A workspace has many SKILL.md files but exactly one AGENTS.md.

Bottom line: SKILL.md says "who this agent is, what they're good at"; AGENTS.md says "rules every AI tool touching this workspace must follow." They aren't rivals — they're different layers.

CLAUDE.md is no longer used v0.4. Previously both CLAUDE.md and AGENTS.md sat at the workspace root, but having two files at the same level created "where should I write this?" confusion and risked divergence. From v0.4, SoloSquad consolidates the workspace persistent guide into AGENTS.md alone. Migration leaves existing CLAUDE.md untouched; content is copied once into AGENTS.md — users may delete CLAUDE.md manually if no longer needed. Modern Claude Code also recognizes AGENTS.md as a fallback, so no compat loss.

3.5 Workflow Maker Meta-Skillv0.5

An author-loop system letting users, without touching code, register a new SKILL.md (or workflow chain) via 1-2 messenger turns. assets/agents/_meta/workflow-maker/SKILL.md acts as the author-loop system prompt; when PM classifies the intent as "I want to automate this task," it enters via explicit [META workflow-maker] invocation.

5-stage state machine

1. CLARIFY — Clarify inputs / outputs / cadence in 1-2 turns (if user can't answer, default is taken with a "you can modify later" note)
2. DRAFT — Preview SKILL.md + (optional) workflow.yaml + (optional) routine cron entry
3. SANDBOX_PROMPT — Run once in dry-run sandbox → request user confirmation
4. AWAIT_CONFIRM — User approval gate ("Confirm?")
5. APPLIED — Deterministic merge: solosquad agent validate <path> → router atomic swap → usable from next call. loop_mode.kind: spec-gate drafts also auto-emit <org>/goals/<goal-id>/goal.md

CLI integration

• solosquad agent add --name X --team Y — scaffold (frontmatter template + empty body)
• solosquad agent validate <path> — schema + required-section check. Author-loop auto-runs this after save
• solosquad agent validate --all [--corpus] — entire workspace + bundle + corpus regression. Runs in CI gate (.github/workflows/ci.yml)
• solosquad agent list / info — inventory and details of registered SKILLs

Cost cap (paperclip envelope)

LLM calls during clarification + draft + validate + sandbox accumulate in <org>/memory/author-costs.jsonl (ts, skill_draft_id, step, usd). When the workspace.yaml.author per_call_usd / daily_usd / weekly_usd cap is hit, PM replies "Daily budget reached — please try again tomorrow."

Analysis track

Existing .claude/skills/ assets in legacy repos are absorbed via solosquad analyze repo <path>. A 4-label classification report (role / workflow / codebase-fact / domain) is stored under <org>/.solosquad/analysis/, and after human review, solosquad add repo --from-report <report> performs a deterministic merge (backup → apply → verify). The second run uses analysis-ledger.yaml hashes so only new/changed parts incur LLM calls.

3.6 4-Channel Routing + Freq Cooldownv0.5

The hardcoded 60+ keyword AGENT_ROUTES constant from v0.2.4 was removed in v0.5. Each SKILL.md's triggers frontmatter is collected at boot into a router index, matched in 4-channel priority order:

Priority: slash > explicit > keyword > freq. Within each channel, the 3-tier search path (org > user > bundle) handles overrides.

Freq channel hysteresis (cooldown)

Once a SKILL is auto-loaded via freq, its freq-match scoring is skipped for triggers.freq.cooldown_turns (default 6). Prevents re-firing the same SKILL every turn when the conversation lingers on one topic. Router memory: the freqCooldowns: { skill_name: until_turn } field in <org>/.solosquad/sessions/<user>.json decays per turn.

Freq SKILL ceiling

Up to 20 SKILLs may register on the freq channel per workspace. Validator refuses the 21st (to bound per-message regex matching cost — p95 < 10 ms target). Keyword tokens are hashmap-counted (O(|tokens|)), with regex as fallback.

Auto-load notification (UX)

When a SKILL is loaded via the freq channel, the user gets one notification: 🧠 {agent} context auto-loaded (recent keywords: ...). The user can immediately reject an unintended routing.

Hot-reload (atomic swap)

When the author loop saves a new SKILL.md, src/bot/index.ts rebuilds the router. Messages arriving during the build are handled by the previous index, and after build the ref is swapped (routeIndexRef = newIndex) — so in-flight messages never see a partial index. No bot restart needed. If the build fails, the previous index is retained and the PM is warned.

Meta-skill scanner isolation

The _meta/ folder is still skipped by the general scanner. A separate listMetaSkills() scans assets/agents/_meta/*/SKILL.md only and accepts only triggers.explicit: true. The workflow-maker meta-skill is enterable only through PM's explicit call — slash/keyword/freq registrations are refused.

3.7 Master Table — File Types per Hierarchy

Workspace layer (Layer 0)

Organization layer (Layer 1)

Repository layer (Layer 2)

3.8 collab_pattern + Self-Evolution Infrastructurev0.6

collab_pattern, which v0.5 carried as an extra bag, was promoted to a formal SkillSpec field in v0.6. Declaring collab_pattern: hierarchical | graph | dynamic in SKILL.md frontmatter makes the matching handoff variant template apply automatically at spawn time.

Trajectory extraction — auto-extract recurring patterns into SKILLsv0.6

When the same (agent sequence + workflow template) combination occurs 3+ times in the last 30 days, the nightly pm-compaction routine generates a draft SKILL.md at <org>/memory/pm-skills/_suggestions/. Next morning brief shows: "You ran the X pattern 3 times in the past 30 days. Register as a SKILL?" If confirmed, the v0.5 S3 applyDraft() is called directly — no separate applier code (avoiding duplication).

30-day rolling window — archive-rotate decays counts alongside. Auto-registration disabled (human gate retained).

Freq keyword miner — auto-suggest keywordsv0.6

Analyzes route_miss events in the FTS5 archive + N-grams from author-draft clarification questions to suggest additions to the triggers.keyword array of existing SKILL frontmatters. Not new SKILL creation — partial application. On user confirmation, applyDraft({ mode: "frontmatter-only" }) is the formal v0.5 option reused — body untouched, frontmatter patched. Rejected (keyword, skill) pairs are blocked from re-suggestion for 30 days.

Stop-hook DSL (v0.5 spec-gate actually operates)v0.6

The loop_mode.kind: spec-gate specced in v0.5 actually operates in v0.6 via the Anthropic 2025-12 stop-hook plugin adapter (src/engine/stop-hook-adapter.ts). Three forms of stop_when:

# (1) command — exit-code based (most deterministic)
loop_mode:
  kind: spec-gate
  stop_when:
    command: "npm test"           # exit 0 = satisfied, != 0 = continue

# (2) metric — results.tsv threshold (compatible with v0.4 autonomous execution)
loop_mode:
  kind: spec-gate
  stop_when:
    metric:
      name: "cvr_7day"
      threshold: 0.10
      direction: "≥"

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

Hook timeout 5 seconds; on failure, conservatively continue (false negatives are safer than false positives). Results: <org>/memory/stop-hook-events.jsonl.

3.9 v0.7 Farewell Archive Formatv0.7

Uninstall always generates a zip first. Format: 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 closes the reverse path with solosquad import · solosquad archive verify.

Classes A/A*/B/C/D/E (v0.7 data classification)

3.10 Multi-User Channel Modelv0.8

The single-operator model from v0.7 was extended to a multi-user context. Each user has a command-<handle> (requests) and works-<handle> (work output) channel pair, with metadata at <org>/.solosquad/users/<handle>.yaml. An author-guard prevents another user from intercepting responses in their channel. Register via solosquad messenger add <handle>.

3.11 dev_capability (development permissions)v0.8.2

The dev_capability: true field in a SKILL.md frontmatter declares that the agent can perform code-modifying dev actions (file changes, git commit, push). boolean — on/off. Granular permissions are split into the separate dev_permissions sub-tree:

• bash.allowed / bash.denied — allowed/blocked bash command lists. The workspace-level denylist (workspace.yaml.dev_capability.bash_denylist) always merges on top — SKILLs cannot override
• network — whether outbound HTTP calls (curl/wget etc.) are permitted. MCP servers are a separate channel
• push_targets.requires_confirmation — user confirmation gate on git push (default true)
• merge.auto — permanently false, pinned (v0.8.2 §2 / §3.1) — auto-merge policy never added

All sensitive commands (git push, gh pr merge, gh pr close) are pinned in SENSITIVE_BASH_PREFIXES and must pass a 30-min dev-confirmation gate to execute. Results: append-only log at <org>/memory/dev-confirmations.jsonl.

3.12 The .solosquad/ Hierarchy — why a folder per levelv0.8.5

On first glance, a workspace shows three locations with a .solosquad/ folder, which can be confusing. Each contains system metadata at a different scope, and the dotfile convention visually separates them from user content on disk.

Why one at each level

• All are system metadata — managed by SoloSquad. Visually separated from user content (memory/ · workflows/ · repositories/<repo>/ body)
• Dotfile convention — invisible to default ls output. A single .solosquad/ line in .gitignore excludes system assets at every level
• Why different contents at different levels — scopes differ:
  • (A) workspace = global (agent SKILLs · envs · timezone shared across all orgs)
  • (B) org = one-time identification per org (multi-user handle → bot_user_id mapping)
  • (C) repo = which org a repo belongs to and what role it plays (a repo never appears in multiple orgs simultaneously)
• User content stays in non-hidden directories (memory/, workflows/, repositories/) — the user must be able to see and edit them with ls / git immediately

4.Onboarding

4.1 Identify Your User Type

Check which type you are first. The steps differ by type.

4.2 New User — Create Your First Workspace

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 or newer
git --version
claude --version

npm install -g solosquad
solosquad --version

# Example: name it whatever you like — here we use "my-saas"
mkdir my-saas
cd my-saas
solosquad init

claude login

solosquad doctor                    # basic diagnosis
solosquad doctor --messenger-check  # actually verify tokens

# Option A — two terminals
solosquad bot          # messenger bot
solosquad schedule     # automated routines

# Option B — Docker (v0.5+ — inside deploy/docker/)
cd deploy/docker && docker compose up -d --build
# See deploy/docker/README.md for options/env vars

4.3 Existing Repo Migration

When you already have a code repo and want to attach an AI team.

Current method (v0.2.4)v0.2.4

1. First create a workspace via §4.2 Steps 1~7 (with at least one org).
2. Register the repo:

   cd ~/solosquad-workspace
   solosquad add repo /path/to/existing-repo      # local path
   solosquad add repo https://github.com/me/x.git # or git URL (clone)

3. With multiple orgs, you'll be asked which one. Auto-assigned for single org.
4. The repo ends up at <workspace>/<org>/repositories/<repo>/.
5. If that repo has its own .claude/skills/ or CLAUDE.md, they remain — Claude Code auto-loads them when working on that repo.

v0.5 analyzer flowv0.5

A separate analyzer absorbs existing .claude/skills/ from legacy repos as SoloSquad assets.

solosquad analyze repo /path/to/legacy-repo
# → 4-label classification (role / workflow / codebase-fact / domain)
# → <org>/.solosquad/analysis/YYYY-MM-DD-*.md report
# → analysis-ledger.yaml records path + SHA256[:12] (second run only LLM-processes new/changed)

solosquad analyze repo <path> --force            # full re-analysis when upgrading models
solosquad analyze repo <path> --prune-orphans    # clean ledger entries whose files are gone

solosquad add repo /path/to/legacy-repo --from-report 2026-XX-XX-initial.md
# → backup → deterministic merge → verify

solosquad add repo <path> --merge-policy append|override|replace
# → explicit merge policy (default: append)

4.5 Recommended 5-Step Repo Importv0.8.3

Moving your own product code into a SoloSquad workspace happens once — the cost of mistakes is high, so dry-run is the default recommendation.

# [Step 1] Clean working tree + commit + push
cd ~/projects/my-saas
git status            # 0 untracked / unstaged
git push origin main  # safety net

# [Step 2] Initialize SoloSquad
mkdir ~/solosquad && cd ~/solosquad
solosquad init        # creates workspace + first org

# [Step 3] dry-run preview (v0.8.3 new)
solosquad add repo ~/projects/my-saas --dry-run
# Output: From/To, file count/size, IDE workspace detection, symlinks,
#         active processes (lsof/handle.exe), slug collisions, risk summary

# [Step 4] Actual move
solosquad add repo ~/projects/my-saas
# Or: --keep-original for copy mode (2× disk usage)

# [Step 5] Verify
solosquad sync                       # repositories/ ↔ .org.yaml sync
cd ~/solosquad/main/repositories/my-saas
git status                           # working tree clean
git log -1                           # same commit as before

4.6 Risk scenarios + dry-run detectionv0.8.3

The risks above are warn-level — users can ignore and proceed. dry-run itself writes 0 bytes to disk.

4.4 Updating from an Older Version

Version rules (semver)

• vN.N.N 3-segment (e.g. v0.1.5, v0.2.0)
• patch (3rd): bug fix / small improvement — rarely needs migration
• minor (2nd): new features / structural change — may need migration
• major (1st): fundamental rework — migration required

npm published version numbers are on a separate semver track. Document labels v0.x ≠ 1:1 with npm versions — policy in docs/product-roadmap.md §3.5.

Check current version

solosquad --version           # installed CLI
solosquad update              # compare with registry (announces only, no install)

Regular update (no migration)

Most patch updates: one line.

solosquad update              # "New version available" → y → installs
# Or manual:
npm install -g solosquad@latest
solosquad --version
solosquad doctor              # all 5 lines must be ✓

Structural update (migration required)

If solosquad update shows a warning like:

⚠ 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)

Execution order:

1. npm install -g solosquad@latest — CLI first
2. cd into the workspace
3. solosquad migrate --dry-run — preview
4. Review output, then solosquad migrate --apply
5. Verify with solosquad doctor
6. Restart solosquad bot

Dry-run output example

$ 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 changes nothing. Don't like it? Just ignore.

What apply does automatically

• Snapshot backup of the entire workspace before any action (~/.solosquad-backups/<timestamp>/)
• File / folder moves and renames
• Creates new config files (.solosquad/workspace.yaml, .org.yaml, etc.)
• Auto-runs doctor after migration for verification

Skipping multiple versions (chain migration)

When jumping from v0.1.2 directly to v0.3.0, migrations run in sequence:

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

Each step is dry-run before apply. If a mid-step fails, rollback stops there.

v0.2.4 update specifics

v0.2.4 changes messenger channel structure / routine model and removes Telegram support.

All users:

• migrate --apply injects timezone, briefings, background_routines (default Asia/Seoul, 08:00 / 18:00) into .solosquad/workspace.yaml
• Messenger channels don't auto-shrink. The bot no longer broadcasts to daily-brief / signals / experiments / weekly-review / errors — you may archive them in the messenger UI manually
• JSONL memory / workflows directories are untouched

Discord users:

• Add Create Public Threads bot permission → re-invite (overwrites, no data effect). Required for auto-creation of system threads (system-daily-signals etc.).

Slack users:

• Add channels:manage to Bot Token Scopes → "Reinstall to Workspace". Without it, #workflow channel creation fails.

Telegram users (support removed)v0.2.4 removed

• MESSENGER=telegram no longer works since v0.2.4. The bot exits with a clear error message on startup.
• Transition:
  1. Run solosquad migrate --apply first (workspace.yaml field injection is messenger-agnostic)
  2. Set up Discord or Slack bot (§5.1 or §5.2)
  3. Change MESSENGER=telegram to discord or slack in .solosquad/.env
  4. Delete TELEGRAM_BOT_TOKEN / TELEGRAM_CHAT_ID lines (ignored if left, but cleanup recommended)
  5. Restart solosquad bot → new platform's #owner-command + #workflow auto-created
• JSONL memory is preserved — past signals / experiments / decisions all survive after switching messengers

Known issues (v0.1.x → v0.2.0 jump)

• solosquad update may not show the migration warning — migration detection code was added in v0.2.0. Users upgrading from v0.1.x should run solosquad migrate manually once.
• --dry-run flag unregistered in the v0.2.0 initial build. v0.2.1+ registered it formally. Even without the flag, solosquad migrate is dry-run by default.

First task after migration — solosquad sync

The v0.1.x → v0.2.0 migration converts each product to an org but leaves .git at the org root (relic of v0.1.x's product = repo). First sync offers two choices:

⚠ 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 (recommended) — code and .git move to <org>/repositories/<org-slug>/. System folders stay at org root. Required for future multi-repo.
• Keep legacy — as-is. <org>/.solosquad/repo.yaml created at org root. OK for single-repo setups.

Docker user update flow

# All commands in deploy/docker/ (v0.5+)
cd deploy/docker

# 1. Stop containers
docker compose down

# 2. Update CLI on host (for migration detection + execution)
npm install -g solosquad@latest

# 3. If migration needed (from workspace root)
cd ../..
solosquad migrate --dry-run
solosquad migrate --apply

# 4. Rebuild Docker image
cd deploy/docker
docker compose up -d --build

Migration must run on the host. Running it inside a container risks volume-mapping confusion. v0.5+ containers also mount ~/.solosquad/ + ~/.solosquad-backups/ so user-global SKILL overrides and backups work normally.

Multi-workspace update

When using multiple workspaces per persona, the CLI update is one-shot but migration runs per workspace:

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

Each workspace has an independent backup — one failure doesn't affect others.

Rollback

solosquad migrate --rollback   # restore from the most recent backup

Warning: after rollback, use the CLI version matching the restored workspace. If you migrated to v0.2.0 and rolled back to v0.1.5:

npm install -g solosquad@0.1.5

doctor warns on CLI ↔ workspace version mismatch.

Backup management

Default backup location: ~/.solosquad-backups/<ISO-timestamp>-v<source-version>/

solosquad migrate --list-backups        # list
solosquad migrate --delete-backup <id>  # manual delete

Auto-retention: keeps the most recent 5. The 6th migration deletes the oldest. Preserve critical backups separately on an external drive or cloud.

Upgrade failure troubleshooting

"Cannot find package.json" type errors:

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

Migration aborted:

solosquad migrate --rollback   # restore most recent backup

Then report to GitHub Issues with logs.

Claude Code auth lost — v0.2.0+ Docker images mount ${HOME}/.claude, so host's claude login state is shared into the container:

claude login
docker compose restart

Beta / dev channels

solosquad update --channel dev     # beta (no stability guarantee)
solosquad update --channel stable  # default

5.Messenger Setup

For an AI to send / receive messages on a messenger, you need a bot account. The v1.0 officially supported messenger is Discord. The Slack adapter ships in the codebase and works, but it is not part of the v1.0 SemVer promise (post-v1.0 slot — see docs/plan/v1.0-formal-launch.md §5). Pick one messenger per workspace.

5.1 Discord Bot Setup (v1.2 path) v1.2

End result: .env has DISCORD_TOKEN; the workspace owner's messenger_user_id + OrgYaml.chief_name are persisted. Invite the bot → guildCreate auto-sends a welcome embed → channel pair #command-<handle> / #works-<handle> is auto-created → the owner sends "hi" → Chief (e.g. Hermes) replies.

cd ~/your-workspace
solosquad init

solosquad bot                       # foreground
# Another terminal:
solosquad doctor --discord          # 5-hop diagnostic
# Expected: ✓ 1.DISCORD_TOKEN  ✓ 2./users/@me  ✓ 3.bot_user_id match
#           ✓ 4.guild membership  ✓ 5.config.yaml + command channel

5.2 Slack Bot Setup (post-v1.0 slot) post-v1.0

This section is a post-v1.0 slot — not covered by the v1.0 SemVer promise. Restored when the v1.2.x adapter slot is activated. v0.9.x ~ v1.1 users already running Slack: follow the v0.x procedure below as-is.

End result: .env has SLACK_BOT_TOKEN=xoxb-... and SLACK_APP_TOKEN=xapp-..., and the bot responds in #owner-command of your Slack workspace.

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 Operation Verification

Common to both platforms:

solosquad doctor                    # base environment check
solosquad doctor --messenger-check  # verify tokens via live messenger API
solosquad bot                       # start bot, logs to console
solosquad bot --debug               # verbose logs

Send hi in #owner-command → if the bot responds in the form [product-name (agent-name)] ..., the whole pipeline is fine.

6.Usage

6.1 Command Reference

Currently available (v0.7.0 ~ v0.8.5)v0.7~v0.8.5

Plannedv1.1+

6.2 Daily Operation

Get work done on the messenger (v0.6)v0.6

The main flow is multi-turn dialog with the PM session. PM classifies intent and spawns specialists via Task tool. The router injects appropriate SKILLs through the 4-channel priority (slash / explicit / keyword / freq).

If nothing matches, the PM falls back to general mode or asks clarifying questions.

PM-mode multi-turn dialogv0.3

User: "Redesign the landing page"
PM:   Which section do you want to change?
       (1) Hero  (2) Pricing  (3) Full redesign
User: 1
PM:   [PRD drafted → spawn desk-researcher → spawn ui-designer → ...]
      Done. Artifacts in stage-1-research/ and stage-2-design/.

Slash commandsv0.3

When you want to be explicit, use slash instead of natural language (gstack-style pattern). Wrapped in PM prompt as [SLASH /xyz] <args> for stable parsing.

• /think <topic> — organize hypotheses / market signals (before PRD)
• /plan <topic> — author PRD + decompose status.yaml
• /build — execute the ready stage from the latest plan
• /review — summarize completed stages + report blocking issues
• /ship — trigger release / deployment routine
• /help — short-circuit on bot side, returns usage text only

Create a new SKILL from the messengerv0.5

"I do this often, I want to automate it" → PM classifies intent → explicit call to workflow-maker meta-skill → 1-2 clarification turns → SKILL.md draft → user approval → atomic swap → usable from next call. See §3.5.

0.5 → 0.6 migrationv0.6

For users upgrading from v0.5:

1. npm install -g solosquad@latest — CLI first
2. solosquad migrate --dry-run — Pass 1 simulation + report at <org>/memory/migration-2026-XX-dryrun.md. 0 filesystem changes
3. Review report — N moves / M items requiring human review / K items unchanged (already final)
4. solosquad migrate --apply --confirm — refused without --confirm flag (mistake prevention)
5. human_review_required: true items must be manually augmented by the user, then re-run
6. Pass 2 — solosquad agent validate --all auto-runs + failures reported to STDOUT

The migration itself has a budget cap (workspace.yaml.migration.budget_usd, default 5 USD). When the heuristic fail-soft path falls to LLM fallback, this prevents token-spike runaway. On cap hit, remaining items are marked human_review_required and the migration exits safely. Accumulator: <org>/memory/migration-costs.jsonl.

readiness checkv0.6

Automatic measurement before v0.6 retro starts. solosquad readiness check --target v0.6 scans workspace → v0.5 data (author-costs.jsonl row count) / 4-workflow run count X/4 / author SKILL Y count (<org>/.agents/ + ~/.solosquad/agents/) / ledger analysis → deterministic output of "S1 can start ✓" or "Insufficient data — wait N weeks". Exit codes for automation.

fs.watch mode selectionv0.6

v0.6 auto-reflects external edits (direct VSCode edits · git pull · separate CLI ops) into the router — chokidar-based 3-tier watch + 300ms debounce. workspace.yaml.fs_watch.mode chooses 3 modes:

• auto — v0.5 atomic swap as-is. All external changes reflected immediately
• prompt (default) — PM gets 🔄 N SKILL changes detected — apply? [y/N] per turn. User y/n
• manual — no auto-reload. solosquad agent reload must be called explicitly

Additionally, fs_watch.git_only: true only reflects when HEAD ≡ upstream + clean tree — blocking the risk of unreviewed SKILLs from git pull reaching a running bot.

6.3 Recommended First Tasks (right after onboarding)

1. Confirm solosquad doctor shows all ✓.
2. Send hi in #owner-command → confirm response.
3. Run the first routine manually:

   solosquad run-routine morning-brief

   Confirm output appears in works-<handle> channel.
4. Edit user profile — Update assets/core/OWNER.md (or .solosquad/core/OWNER.md) with your name / role / interests. Every agent reads this each session.
5. Behavioral principles — Write your decision criteria in core/PRINCIPLES.md (e.g. "cash flow first", "no VC funding", "≤50 hours/week").
6. Writing tone — Write content tone in core/VOICE.md (e.g. "professional but warm, no hyperbole").
7. Decide product name + create a workflow folder (~/solosquad-workspace/<org>/workflows/wf-2026-XX-XX-test/).
8. Adjust brief times — edit briefings.morning.time etc. in .solosquad/workspace.yaml to match your daily rhythm.

6.4 Automated Routinesv0.8.5

Total 4. Three user-facing briefs + one infrastructure routine. v0.8.5 permanently removed 4 analysis routines (signal-scan / experiment-check / weekly-review / v06-retrospective-stats) and unified the 2 infrastructure routines (archive-rotate + log-rotate) into a single system-housekeeping.

User-facing briefs (3)

System infrastructure (user-invisible, always on, silent)

v0.8.5 change — routines 9 → 4:

• Removed (permanent): signal-scan · experiment-check · weekly-review · v06-retrospective-stats. Analysis routines meaningless without user-authored domain prompts. Domain analysis goes into workflows / goals instead
• Merged: archive-rotate + log-rotate → system-housekeeping (single 00:00 cron, try/catch isolated)
• Backward-compat: workspace.yaml.background_routines keys are read-ignored (no error)

Update ↔ migration flowv0.8.3

These two commands are separate. solosquad doctor explicitly tells you which one is needed on CLI ↔ workspace version mismatch (§7.3).

# 1. Diagnose
solosquad doctor
# ├─ "CLI: v0.8.5,  workspace: v0.8.5" → OK
# ├─ "CLI: v0.8.5,  workspace: v0.7.0" → recommends `solosquad migrate --apply`
# └─ "CLI: v0.7.0,  workspace: v0.8.5" → recommends `npm install -g solosquad@latest`

# 2. CLI upgrade (npm package itself)
solosquad update          # checks npm registry + self-install
# or: npm install -g solosquad@latest

# 3. (After CLI is new version) align workspace
solosquad migrate --dry-run    # preview changes
solosquad migrate --apply      # apply (auto backup → apply → verify)
solosquad migrate --rollback   # restore from last backup (if needed)

• update = updates the CLI binary (npm package) itself
• migrate = converts the workspace (.solosquad/ · org/ · workflows/ · memory/) schema/layout to match new CLI

Edit timezone / times / activation

Edit .solosquad/workspace.yaml directly:

timezone: Asia/Seoul        # any IANA tz
briefings:
  morning:
    time: "08:00"
    enabled: true
  evening:
    time: "18:00"
    enabled: true

Manual execution

solosquad run-routine                   # interactive menu
solosquad run-routine morning-brief     # specific routine
solosquad run-routine --all             # all

7.Operations Guide

7.1 Choose a 24/7 Operating Mode

The bot needs solosquad bot running continuously to maintain its messenger connection. Comparison:

A-1. Keep terminal open (simplest)

solosquad bot

Runs only while the terminal is open. Stops on Ctrl+C or window close. PC sleep breaks the connection.

macOS sleep prevention (especially useful on Mac Mini):

caffeinate -dims

Or System Settings → Energy Saver → "Prevent display sleep" + disable Power Nap.

Windows sleep prevention: Settings → System → Power → "Never go to sleep."

For the scheduler in parallel, separate terminal:

solosquad schedule

A-2. Docker Compose (background + auto-restart, recommended)

Prerequisite: Docker Desktop installed (https://docs.docker.com/desktop/). Works on macOS Apple Silicon / Intel. Verify solosquad init copied Dockerfile and docker-compose.yml to the workspace.

cd ~/solosquad-workspace
docker compose up -d --build      # initial build + background start
docker compose logs -f bot        # bot logs
docker compose logs -f scheduler  # scheduler logs
docker compose ps                 # service status
docker compose restart            # restart
docker compose down               # stop

Sharing Claude Code authentication: the in-container claude CLI also needs auth. docker-compose.yml mounts host's ${HOME}/.claude to container's /root/.claude → host login session is shared.

1. claude login on host
2. docker compose up -d --build
3. In-container claude reads host credentials, operates under the same account

For a different path, set in .env:

CLAUDE_AUTH_DIR=/Users/youruser/.claude

After PC reboot: with Docker Desktop set to auto-start (Docker Desktop settings → "Start Docker Desktop when you log in"), containers auto-recover via restart: unless-stopped.

A-3. macOS launchd / Windows NSSM (service-ify)

For native process auto-start on login without Docker.

macOS — launchd. Create ~/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>

Verify the path (/usr/local/bin/solosquad) with which solosquad. Register / start:

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

Add com.solosquad.scheduler.plist similarly for the scheduler.

Windows — NSSM:

1. Download NSSM from https://nssm.cc → add nssm.exe to PATH
2. Admin 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. Cloud VPS (advanced)

When you have no plan to keep a home server on, or "bot must live even when PC is off."

Worth considering when:

• No 24/7 PC at home
• Traveling / laptop-only lifestyle
• Multiple team members co-operate the bot
• Stability ties directly to business (auto-alert / routine failures cause losses)

Quick summary (VPS + systemd):

# SSH into VPS
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
# Register systemd service — see docs/cloud-deployment.md

7.2 Multi-Workspace (persona separation)

When you want day-job / side-project persona separation, run multiple Discord workspaces. (Slack adapter still works for legacy separation but is outside the v1.0 SemVer promise.)

~/solopreneur/      # Discord bot, day-job persona
~/personal-lab/     # Discord bot, side persona

Each gets independent .env / tokens / bot accounts. Operate in parallel without interference. This constraint exists from v0.2.0+ — v0.1.x's MESSENGER=discord,slack (multi-target) is no longer supported. v1.0 ships only the Discord adapter under the SemVer promise; the Slack adapter remains in code but is a post-v1.0 slot.

Updating: CLI update is one-shot but migration runs per workspace (see §4.4).

7.3 Multi-Product Operation (organizations & repos)

A workspace can hold multiple organizations (= product/business). Each has fully isolated memory / workflows / messenger channels.

Add organization

solosquad add org <name>                        # interactive (asks for provider/remote_url)
solosquad add org my-side --provider github --remote-url https://github.com/my-side

Creates <workspace>/<name>/ folder + .org.yaml + memory/ (routine-logs/ + 4 JSONL schemas) + workflows/ + repositories/ + messenger folder automatically.

Add repository

URL → clone, path → register (move if needed).

solosquad add repo https://github.com/foo/bar.git                       # clone + register
solosquad add repo ./existing-local-repo                                # move (after confirm) + register
solosquad add repo https://github.com/foo/bar.git --org tesla --role frontend
solosquad add repo <url|path> --slug my-custom-slug                     # folder name override

Org auto-decision order:

1. --org <slug> explicit → use immediately
2. Workspace has exactly one org → auto-pick (don't ask)
3. Current cwd is inside a specific org folder → auto-use that org
4. Multiple orgs + above all fail → interactive prompt

Auto-extraction:

• remote_url — read from git remote, recorded in repo.yaml
• language — detected from package.json (TypeScript auto-detected) / pyproject.toml / go.mod / Cargo.toml
• role default — main if .git exists, else unknown

Bulk sync

If repos are already cloned in repositories/, register them all at once:

solosquad sync                # scan all orgs
solosquad sync --org tesla    # specific org
solosquad sync --dry-run      # preview (writes nothing)

Behavior:

• Folders under <org>/repositories/<folder> with .git but no repo.yaml → auto-register
• Already-registered repos → skipped with = marker
• Folders without .git → ? warning, skipped
• .org.yaml.products[].repos updated to actually-existing repos
• Repos listed in .org.yaml but no longer existing → - red warning

Cross-repo workflow (v0.2.1+)

The v0.2.1 runtime, when a stage in _status.yaml has a target_repo field, uses that repo as cwd when executing the stage. Workflows spanning multiple repos can be coordinated as one workflow:

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

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

Active stage decision:

1. A stage with status: in_progress → that one
2. Otherwise, the first status: pending whose depends_on are all completed
3. If neither, fall back to role=main repo → org root

Stage transitions (pending → in_progress → completed) are automated by v0.3 PM mode — PM marks in_progress before spawning a specialist, merges the Task tool response, then advances to completed.

7.4 Security Checklist

This system has AI executing code and commands. Confirm the following:

• .env is in .gitignore
• Rotate bot tokens periodically (90 days recommended)
• Always review AI output before deploying to production
• Keep messenger bot permissions minimal — don't grant beyond §5's scope list
• Run solosquad doctor periodically
• Cloud ops: SSH key auth only, firewall outbound-only
• v0.8.1+: run solosquad archive verify once before externally storing an archive (PII-NOTICE scan + manifest SHA verify)
• v0.8 multi-user: when adding another user, explain bot multiplicity — each user only responds in their own channel pair (command-<handle> / works-<handle>) per author-guard

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

7.5 Periodic Backup + Observabilityv0.8.3

Backup + log observability flow during operation.

• Periodic backup: monthly recommended. solosquad uninstall --mode archive-only creates just the farewell archive zip (workspace stays). Archive integrity ensured via manifest.tsv SHA. solosquad archive verify recommended before external storage. Migration backups (~/.solosquad-backups/) listed via solosquad backup list; old backups cleaned via solosquad backup purge --keep-recent 3
• gh CLI authentication: for dev_capability (patch / pr) to create PRs, gh auth login must be complete on the host. solosquad doctor only checks gh existence — token validity is verified separately via gh auth status
• Log location + retention: with SOLOSQUAD_LOG_FILE=1 enabled, daily rolling at <workspace>/.solosquad/logs/solosquad-YYYY-MM-DD.log. Retained 14 days (daily 00:00 system-housekeeping). SOLOSQUAD_LOG_FORMAT=json for structured output
• solosquad logs command: tail/follow/filter 4 operational jsonl (agent-costs / spawn-decisions / stop-hook-events / dev-confirmations / migration-costs) in one place
• CLI ↔ workspace mismatch: solosquad doctor explicitly indicates whether migrate or update is needed

8.Glossary

This section explains every term and filename a newcomer to AI / dev might hit while reading these docs or the code.

8.1 Core Terms

Workspace

SoloSquad user's top-level folder, typically ~/solosquad-workspace. Holds 1+ organizations. A workspace is one user's "AI assistant HQ."

Organization (org)

A business / product unit inside the workspace. e.g. day-job, side project. Each has isolated memory / workflows / messenger channels. The folder name is <slug> (e.g. my-startup).

Repository (repo)

Actual code in a git repo. One org may hold multiple repos. Location: <workspace>/<org>/repositories/<repo>/.

Agent

An AI worker performing one role (e.g. Business Strategist). SoloSquad has 25 specialists + 1 PM (v0.3+).

Specialist

Domain-specific expert agent. 25 of them. Distinct from PM (orchestrator).

PM / Orchestrator

The persistent agent talking directly with the user. Introduced in v0.3. Spawns specialists to drive multi-stage workflows.

SKILL.md

Manual file describing one agent's identity and operation. Anthropic Agent Skills official format.

KNOWLEDGE.md (v0.6)

Per-team (= domain) shared craft / definitions / anti-patterns. Located at agents/{team}/KNOWLEDGE.md (v0.6 co-location). Auto-injected as 8-layer assemble [2] when any agent in the team spawns.

Org Layer (v0.6)

Three new assets absorbing org-specific flavor: <org>/core/{PRINCIPLES,VOICE}.md (org philosophy/tone) + <org>/agent-profile.yaml (25-agent modifier + budget) + <org>/domain/ (org domain knowledge). Workspace SKILLs stay unchanged; org color comes solely from these 3 assets.

Workspace Knowledge (v0.6)

.solosquad/knowledge/ — accumulated shared user knowledge (decision frameworks, domain glossary). Keeps agent SKILL.md short by separating craft / domain. Selective inject on keyword match.

8-layer JIT inject (v0.6)

At spawn time, context is assembled in order: workspace knowledge → team KNOWLEDGE → agent SKILL → org core → agent-profile → org domain → memory/handoff → repo. When max_context_tokens is hit, lower-priority layers drop first. See §2.5.

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

Paperclip-style LLM call cap. v0.5 applied it to author loop only; v0.6 generalizes per (org × agent). Configured via agent-profile.yaml's budget.daily_usd / weekly_usd / on_cap_action. On cap → spawn refused + PM response. Accumulator: <org>/memory/agent-costs.jsonl.

FTS5 cold archive (v0.6)

<org>/memory/archive.sqlite — JSONL older than 8 days moved into a SQLite FTS5 virtual table, kept searchable. Nightly archive-rotate at 00:00 (v0.8.5: merged into system-housekeeping). 4 event_types indexed (route_hit / route_miss / author_turn / spawn_decision) + existing routine_log. Fallback recall on router miss.

Trajectory extraction (v0.6)

Same (agent sequence + workflow template) occurring 3+ times in 30 days → auto SKILL draft suggestion. Nighttime pm-compaction step. Reuses v0.5 applyDraft() directly (0 code duplication). No auto-registration — human gate retained.

Freq miner (v0.6)

Analyzes FTS5 route_miss + author-draft clarification N-grams → suggests additions to existing SKILL's triggers.keyword. Body untouched + frontmatter patched via applyDraft({ mode: "frontmatter-only" }).

Stop-hook DSL (v0.6)

v0.5's loop_mode.spec-gate actually runs via Anthropic 2025-12 stop-hook plugin. 3 forms: command (exit 0) · metric (results.tsv threshold) · natural (LLM fallback + budget cap). 5-second timeout; on failure, conservatively continue.

collab_pattern (v0.6)

Formal frontmatter field in SKILL.md (was extra bag in v0.5). hierarchical | graph | dynamic. 25-agent split: 22 hierarchical · 2 graph (data-analyst, feature-planner) · 1 dynamic (content-writer). Spawn auto-applies the matching handoff variant template.

Hot-reload (chokidar, v0.6)

fs.watch-based router auto-rebuild. 3-tier watch (workspace · org · user-global) + 300ms debounce + atomic swap. workspace.yaml.fs_watch.mode: auto / prompt (default) / manual. git_only safety mode allows only HEAD ≡ upstream + clean tree.

schema_version: 1 (v0.6)

Forward-compat flag on v0.6 new assets (.org.yaml · agent-profile.yaml · v0.6 ledger). v0.7 migration branches by version check.

Routine

Task that runs automatically at scheduled times. SoloSquad ships 4 (v0.8.5): Morning Brief, Evening Brief, PM Compaction, System Housekeeping.

Workflow

A multi-stage project. 4 defaults: PMF Discovery, Feature Expansion, Rebranding, Rapid Prototype. Each workflow lives at <org>/workflows/<id>/.

Stage

One step inside a workflow. Stored in folders like stage-1-research/.

Handoff

Artifact passed from one stage to the next agent at stage end. _handoff.md with standard sections: Summary, Artifacts, Decisions, etc.

Brief

Morning/evening summary from the bot. Morning = overnight events + today's plan. Evening = today's events + tonight's plan.

Agent Router

Module that decides which specialist to invoke based on user message. v0.5 evolved to 4-channel triggers (slash > explicit > keyword > freq) + 3-tier search + atomic-swap hot-reload. AGENT_ROUTES hardcode removed; trigger info now lives in each SKILL.md's triggers frontmatter.

Spawn

Action of PM (or router) starting a specialist agent in a fresh session. Each spawn is independent; state lives in external files. v0.3+ uses the PM's built-in Task tool with [stage:<id> wf:<id>] markers in the prompt.

4-channel routing (v0.5)

SKILL match channels: slash (explicit intent) > explicit (PM direct call) > keyword (single-turn match) > freq (accumulated frequency over N turns). Each SKILL.md frontmatter's triggers collected as router index at boot.

Freq cooldown (v0.5)

Once a SKILL auto-loads via freq, it's blocked from re-firing for cooldown_turns (default 6) (hysteresis). Prevents noise when conversations linger on one topic. State stored in <org>/.solosquad/sessions/<user>.json freqCooldowns field, decayed per turn.

Hot-reload / Atomic swap (v0.5)

On new SKILL.md save, the router index is rebuilt in background → ref swapped. Messages in flight see the old index. No bot restart needed.

Author loop (v0.5)

5-stage state machine for creating a new SKILL.md via 1-2 PM messenger turns (CLARIFY → DRAFT → SANDBOX_PROMPT → AWAIT_CONFIRM → APPLIED). assets/agents/_meta/workflow-maker/SKILL.md meta-skill serves as the system prompt.

Spec-gate / Loop mode (v0.5)

SKILL.md loop_mode.kind: spec-gate means Ralph-loop mode (stop_when condition). Author loop auto-emits <org>/goals/<goal-id>/goal.md as well → registers an autonomous cycle in v0.4 goal-runner.

3-tier SKILL search (v0.5)

Same-name SKILL priority: <org>/.agents/ > ~/.solosquad/agents/ > <workspace>/.solosquad/agents/ (bundled). Higher tier overrides.

Stateless / Stateful

Stateless = each call independent; Stateful = retains state across calls. SoloSquad specialists are stateless; the PM session is stateful.

JIT (Just-in-Time) Injection

Principle of not pre-loading all context but injecting only what this call needs at the moment. Prevents token-cost blowup.

Memory

Persistent store for routine / decision / signal results. v0.6 layout: JSONL append-only (signals / experiments / decisions / author-costs / agent-costs / spawn-decisions / stop-hook-events / migration-costs) + PM compaction externalization (memory/pm-skills/) + per-org snapshot.git + FTS5 cold archive (archive.sqlite — 8d+ auto-move, 4 event_type indexing).

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

Vocabulary classifying memory into 3 layers. SoloSquad's SKILL = Persistent, workflows = Episodic, Claude session prompt = Transient.

3-Layer Context

Workspace (Layer 0) / Organization (Layer 1) / Repository (Layer 2). Basic data-isolation units.

PRD (Product Requirements Document)

Product spec doc. Authored by PM, handed to specialists.

PMF (Product-Market Fit)

Whether the market truly needs this product.

GTM (Go-To-Market)

Strategy for entering the market — channels, message, pricing, first users.

Anthropic / Claude

Anthropic is the company behind Claude AI. Claude Code is Anthropic's coding CLI. SoloSquad uses Claude Code as its backend engine.

Claude Code

Anthropic's general-purpose coding CLI tool. SoloSquad calls claude to get AI responses. Separate install: npm install -g @anthropic-ai/claude-code.

npm (Node Package Manager)

Node.js package installer. npm install -g solosquad installs SoloSquad.

CLI (Command Line Interface)

Terminal-driven program. solosquad is a CLI.

cron

Standard schedule format for repeated tasks. SoloSquad routines are cron-based.

JSONL (JSON Lines)

Text format where one line = one JSON object. Useful for append-only event logs. SoloSquad memory's default format.

FTS5 (Full-Text Search v5)

SQLite's built-in full-text search extension. Fast keyword search. Adopted in v0.6 as the memory archive index (depends on better-sqlite3 ^12.10.0).

MCP (Model Context Protocol)

Standard protocol connecting AI agents to external tools / data. Announced by Anthropic in 2024. SoloSquad can use MCP for external integrations (Notion, Figma, etc.).

IANA tz (Timezone Database)

International standard timezone names (e.g. Asia/Seoul, America/Los_Angeles). Used in workspace.yaml.timezone.

YAML

Human-readable config file format. SoloSquad uses YAML in workspace.yaml, .org.yaml, _status.yaml, etc. Structure via indentation.

Frontmatter

YAML metadata block at top of a Markdown file, wrapped in ---. SKILL.md's name / description / triggers etc. are frontmatter.

Docker / docker-compose

Container virtualization tool. Useful when you want SoloSquad bot/scheduler running in background with auto-restart. Optional.

VPS (Virtual Private Server)

Cloud virtual server. For 24/7 ops when you can't keep a PC on. ~$4-6/month.

Slug

URL/folder-friendly name. Lowercase + hyphens. e.g. "My Startup" → my-startup.

8.2 File Dictionary

Meaning of every file you'll encounter in a workspace or the code.

.env

File holding secrets (API tokens, etc.) such as SLACK_BOT_TOKEN / DISCORD_TOKEN. Never commit to git.

.env.example

Template for .env, with empty values to show what to fill in. OK to commit.

.gitignore

Patterns git ignores. SoloSquad ignores .env, node_modules, dist, repos, etc.

.npmignore

Patterns excluded from npm package publish (dev-only files).

package.json

npm package manifest. Name, version, dependencies, scripts. SoloSquad's solosquad CLI entry point declared here.

package-lock.json

Auto-generated file pinning exact dependency versions. Do not edit by hand.

tsconfig.json

TypeScript compile config. ES2022 / strict, etc.

workspace.yaml

Workspace-wide config at .solosquad/workspace.yaml. timezone / briefings / background_routines schedule, messenger type, etc.

.org.yaml

Per-org config at <org>/.org.yaml. Org name / messenger / registered repos.

repo.yaml

Per-repo config at <repo>/.solosquad/repo.yaml. Repo slug / role (main/sub) / target_org.

SKILL.md

Agent identity manual in Anthropic Agent Skills format. See §3.1.

KNOWLEDGE.md (v0.6)

Team (= domain) shared knowledge at agents/{team}/KNOWLEDGE.md. See §3.2.

TEAM_KNOWLEDGE.md (v0.2.4, removed in v0.6)

Renamed & relocated to agents/{team}/KNOWLEDGE.md in v0.6. _teams/ parallel hierarchy fully removed.

agent-profile.yaml (v0.6)

At <org>/agent-profile.yaml. Org-specific modifiers for 25 agents (tone, emphasis, voice, ban_phrases, budget). defaults + per-agent + schema_version: 1.

archive.sqlite (v0.6)

At <org>/memory/archive.sqlite. FTS5 cold archive. JSONL ≥8d → moved here + 4 event_type indexing + 365d retention.

CLAUDE.md

Project guide auto-loaded by Claude Code each session. See §3.3.

OWNER.md

Your profile / interests / work pattern. Every agent reads it each session. assets/core/OWNER.md.

PRINCIPLES.md

Your decision-making principles. Guide every agent should follow. assets/core/PRINCIPLES.md.

VOICE.md

Your writing tone / voice. Guides agents that produce text (Content Writer, etc.). assets/core/VOICE.md.

_status.yaml

Workflow progress. State per stage: pending → in_progress → completed.

_handoff.md

Context passed to the next agent when a stage completes. Standard sections: Summary, Artifacts, Decisions, Open Questions.

_events.jsonl (v0.3+)

All PM session event logs. PM messages, spawns, subagent completions.

signals.jsonl

Results from Signal Scan routine (deprecated default in v0.8.5).

experiments.jsonl

Results from Experiment Check routine (deprecated default in v0.8.5).

decisions.jsonl

Decisions accumulated from Evening Brief / Weekly Review.

routine-logs/*.jsonl

Full execution logs for routines. Used for debugging / retro.

Dockerfile (deploy/docker/Dockerfile)

Docker image build recipe. For containerizing SoloSquad bot/scheduler. Moved to deploy/docker/ in v0.5.

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

Settings for running multiple containers (bot + scheduler) together. v0.5+ also mounts ~/.solosquad/ + ~/.solosquad-backups/ — user-global SKILL override and backups compatible.

README.md

First-impression document. Shown on npm/GitHub. SoloSquad's README covers install + quick start.

LICENSE

License file. SoloSquad is MIT.

CONTRIBUTING.md

Guide for contributing (developer-facing).

8.3 Abbreviation Dictionary

API

Application Programming Interface. Inter-software protocol. Slack API, Claude API, etc.

CAC

Customer Acquisition Cost. Marketing metric.

CLI

Command Line Interface.

CRUD

Create / Read / Update / Delete. The 4 basic data ops.

DAG

Directed Acyclic Graph. Used to express workflow stage dependencies.

E2E

End-to-End. Full user-flow testing.

ESM

ECMAScript Module. JS module standard (Node16+).

FDE

Forward Deployed Engineer. Customer-on-site engineer. One agent in SoloSquad engineering team.

FTS5

Full-Text Search v5. SQLite built-in full-text search.

GTM

Go-To-Market.

IANA

Internet Assigned Numbers Authority. SoloSquad uses IANA timezone names (Asia/Seoul etc.).

JIT

Just-in-Time. Load/run only when needed. Context-management principle.

LTV

Lifetime Value. Total revenue from one customer. LTV:CAC ≥ 3:1 is the typical SaaS health metric.

MCP

Model Context Protocol. AI ↔ external tools standard.

npm

Node Package Manager.

PaaS

Platform-as-a-Service. Cloud without server management. 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. Remote-server access protocol. Used for VPS ops.

TS

TypeScript. JavaScript with static types. SoloSquad's implementation language.

TTL

Time-To-Live.

tz

timezone (abbreviation).

UI / UX

User Interface / User Experience.

VPS

Virtual Private Server.

YAML

YAML Ain't Markup Language.

9.CHANGELOG

Core changes per released version. Full release notes live in CHANGELOG.md — this section mirrors the same content so the manual is self-contained.

9.1 Released (npm-published)

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

• Strict workspace detection — bare .solosquad/ no longer qualifies as a workspace root; workspace.yaml is required. Running solosquad bot from inside <org>/ no longer creates ghost owner-command / workflow channels.
• messenger_user_id auto-populate — init Step 3.5 prompt + first-message hydration. Owner-only gate is finally protective in practice.
• Slack temporarily hidden from init messenger picker. Picker step kept for the v1.2.x adapter slot.
• Path quote stripping — solosquad add repo "C:\path" tolerates the quotes PowerShell / Explorer "Copy as path" wraps Windows paths in.
• Claude Code trust auto-grant — bot's claude --print spawns no longer hit the interactive trust dialog. scaffoldOrg + init repo loop + add repo all stamp ~/.claude.json. v1.2.3 → v1.2.6 migration backfills every existing org cwd + every registered repo path — one solosquad migrate --apply retroactively grants trust for paths registered before the v1.2.6 install.
• Chief identity plumbing — bot reply prefix uses chief_name ([Hermes], not [bv-po]). LLM system prompt receives an [identity] line so Chief signs by name.
• Chief name prompt copy — explains the 6 surfaces + 7 examples (Hermes / Atlas / Apollo / Iris / Janus / Athena / Hephaestus).
• Vocabulary — [Bot] PM turn → [Bot] Chief turn, PM sessions: → Chief sessions:, etc. JSONL event kind pm.* stays for schema_version backward-compat.
• Manual §5 reorder — Discord = §5.1 (was §5.2). §5.1 content rewritten for v1.2 — the v0.2.x "server name = product slug" rule and the AI Team Reports channel tree are gone.
• §10 FAQ moved to bottom — 10.3 Uninstall / 10.4 Bot & Scheduler / 10.5 FAQ.
• Details: 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 package whitelist fix — root-level bundle directories (agents/ · skills/ · teams/ · schedules/ · user/ · knowledge/) added to package.json.files. Tarball 567 → 652 files.
• Restores v1.0.4 → v1.1.0 migration verify — chief SKILL.md + 4 teams OKR + problem-definition workflow.yaml were silently missing from the tarball.
• Details: 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 and v1.2.1 were burned during pre-launch (npm policy: cannot re-publish); v1.2.2 was broken (bundle gap). v1.2.3 is effectively the first usable publish in the series.

• One Chief bot per org — OrgYaml.chief_name, recommended to match the Discord Developer Portal Bot name.
• OAuth Invite URL 1-click — solosquad discord invite-url synthesizes the recommended 10-perm bitfield + opens the browser + clipboard fallback.
• Handle-based channel portability — the same command-<handle> / works-<handle> pair across multiple Discord guilds and future Slack workspaces.
• Owner-only gate — message.author.id === user.yaml.messenger_user_id. v1.0.2's real reason for removing the author-guard (user-id channel names breaking bot recognition) is resolved by handle-based channels, so the reversal is justified. Fresh installs land ON, upgrades land OFF (neutral).
• TRIAGE kind branching — Chief emits [kind:chat|workflow|schedule|goal] as the first reply line. chat replies flat; workflow/schedule/goal post a task card embed + thread in works-<handle> with stage narration (DECOMPOSE / DISPATCH / AWAIT).
• solosquad add-org bootstraps a fully working org — Chief name + the entire v1.1.0 hierarchy + problem-definition workflow seed.
• guildCreate onboarding embed with 2 buttons (Auto-create / Manual choose), /chat slash fallback for MESSAGE_CONTENT intent denial.
• solosquad doctor --discord 5-hop diagnostic.
• Details: 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, only user-facing agent) and PM (workspace-bundle autonomous product manager, never talks to the user directly) are now distinct roles.
• 4 main bots (chief / pm / engineer / designer / marketer) + 20 specialists (flat catalog, 4 merges + paid→performance rename) + 18 skills + 4 teams.
• 9-layer JIT context with Team OKR as Layer 4a.
• Chief 6+1 stage machine — TRIAGE → DECOMPOSE → DISPATCH → AWAIT → SYNTHESIZE → DECIDE → RETROSPECT, emitted to <org>/memory/chief-stage-events.jsonl.
• open_questions[] async-batch protocol.
• External references: Hermes V2, gstack (Garry Tan), RO-PNA pna-builders, phuryn pm-skills.
• Details: 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 — formal launch. Stable API guarantees. 42-command CLI surface freeze. docs/api-stability.md goes live. Discord-only messenger (Slack is a post-v1.0 slot).
• v1.0.1 — discord.js v15 deprecation fix, @<slug> mention parser, multi-repo intent routing.
• v1.0.2 — Discord author-guard removed (real reason at the time: user-id channel names blocked bot recognition — v1.2.6 reinstates the gate as owner-only after handle-based channels solved the recognition layer).
• v1.0.3 — 5 bugs fixed: versionMatches slice math / npm sudo prefix permission check / guild-org binding via ownOrgSlug / update next-step hint / category rename ("AI Team Reports" → "solosquad").
• v1.0.4 — Discord config.yaml auto-create + Slack author-guard cleanup + 5-hop diagnostic message + 9-reference research persisted.
• Details: CHANGELOG.md §[1.0.0]~[1.0.4]

v0.x series (pre-launch) — condensed

Self-use validation + infrastructure build-up before the v1.0 formal launch. Full history in CHANGELOG.md §[0.x.x] + docs/prd/product-roadmap.md §5.1.

• v0.8.x — Multi-User Messenger (command-<handle> / works-<handle> channel pair + handle-based routing + author-guard + opt-in broadcast), Security & Lifecycle Pair (archive completion + 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). User code is sacred (class A), WAL-safe SQLite backup, REVOKE-CHECKLIST.md auto-generated.
• v0.6.0 — Default workflow tuning, FTS5 cold archive, trajectory + freq miner, Org Layer specialization, chokidar hot-reload.
• v0.5.0 — Workflow maker + frontmatter routing (4-channel router: slash > explicit > keyword > freq).
• v0.4.0 — Autonomous overnight engine (goal.md + solosquad goal run), AGENTS.md cross-tool standard adopted.
• v0.3.0 — PM mode + multi-agent orchestration, slash chain /think /plan /build /review /ship.
• v0.2.x — Workspace structure normalized (.solosquad/ + multi-organization).
• v0.1.x — First npm publishes, 25 specialist agents, Discord/Slack adapters.

9.2 Upcoming slots (planned)

v1.2.x — Next patches / sub-versions

• v1.2.1 follow-up — thread continuity: referencedMessage chain + LRU cache (PRD §7.3) + thread token budget guard (PRD §9.2). v1.2.0 = one task = one thread; continuous conversation surface comes here.
• v1.2.x — Slack adapter restored: init messenger picker re-enables Slack and the v1.2 feature set is re-implemented behind the same ChiefMessenger interface.

v1.3 — Scheduling + memo

• n-jobber time / memory integration. Calendar / Apple Notes / Obsidian / Notion MCP connectors.
• Layered on top of the v1.x knowledge ontology slot.

v1.x — Cascade-shifted slots

• Dashboard interaction: companion web dashboard in a separate repo (solopreneur-dashboard + solopreneur-api).
• Knowledge ontology + MCP external connectors: graph backend + Notion / Obsidian / external APIs / other agents.
• LLM backend abstraction: multi-backend (single Claude → pluggable).

10.Troubleshooting & FAQ

10.1 Install / Run Issues

"solosquad: command not found"

• Verify install: npm install -g solosquad
• Verify Node.js 18+: node --version
• On Linux permission errors: sudo npm install -g solosquad or set up ~/.npm-global

"claude: command not found"

npm install -g @anthropic-ai/claude-code
claude login
solosquad doctor       # final check

Bot doesn't respond on messenger

First check for environment mismatch:

solosquad doctor                    # base diagnosis
solosquad doctor --messenger-check  # live API token verification

If you see .env vs process.env mismatch, update to latest solosquad (the .env-load bug was fixed in v0.1.3).

Slack checklist (re-verify §5.1 Step 9):

• Event Subscriptions enabled + message.channels subscribed
• After scope changes, performed Reinstall to Workspace
• Bot invited to #owner-command

Discord checklist (final list in §5.2):

• Message Content Intent ON
• Bot has Create Public Threads permission (v0.2.4+, for system thread creation)
• Server name contains product slug

Existing Telegram users: removed in v0.2.4. Change MESSENGER=telegram to discord or slack in .solosquad/.env and complete fresh setup (see §4.4).

Routines don't run

• Verify solosquad schedule is running (ps or docker compose ps)
• Manual test: solosquad run-routine morning-brief

Docker: claude: command not found inside container

• Verify CLAUDE_AUTH_DIR volume mount
• Auth directly inside container: docker exec -it solosquad-bot claude login

Strange behavior after update

solosquad doctor
solosquad update                    # if already latest, only announces
docker compose up -d --build        # if Docker, rebuild image

git push authentication failed (when using agent dev_capability)

If the agent committed but failed at push with fatal: Authentication failed or Permission denied (publickey):

cd <repo>
git push --dry-run    # reproduce the same error directly

• Windows: Git for Windows installer auto-enables Git Credential Manager. Reinstall (winget install Git.Git), then verify first push opens browser OAuth
• macOS: Set git config --global credential.helper osxkeychain, then first push prompts for GitHub PAT → permanently stored in Keychain
• Linux: Set up SSH key (ssh-keygen + register public key in GitHub) or PAT + credential.helper store manually

Authentication itself is outside SoloSquad's scope. For detailed procedures, see the GitHub official docs.

10.2 Migration Troubleshooting

"Cannot find package.json" type errors

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

Migration aborted

solosquad migrate --rollback   # restore most recent backup

Then report to GitHub Issues with logs.

Bot doesn't start after migration

solosquad doctor

Check output. Missing tokens / wrong .env location are common causes.

Claude Code auth lost

claude login
docker compose restart    # if Docker

Not sure which version to upgrade to

Check release notes first:

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

For minor updates containing breaking changes in important projects, observing for about a week before upgrading is reasonable.

10.3 Uninstall · Reinstall · Migration Workaroundv0.8.5

Safe uninstall sequence

Because npm v7+ does not invoke the preuninstall hook on global packages (npm/cli#3042), you must follow the order yourself for the farewell archive and REVOKE-CHECKLIST to be generated.

1. Stop bot · scheduler (required) — if still running, the archive snapshot SHA will mismatch.

   # macOS / Linux
   docker compose down              # if using Docker
   # or Ctrl+C in bot/scheduler terminals
   
   # Windows (PowerShell)
   docker compose down
   # or Ctrl+C in terminals
   # or force-stop by PID:
   Stop-Process -Id <pid1>,<pid2> -Force

   solosquad doctor's "solosquad bot/schedule processes alive (pid ...)" warning shows remaining PIDs. The solosquad uninstall precheck also refuses entry without --force when live PIDs are detected.
   v0.9.2 hotfix — On Windows with v0.9.1 or earlier, the precheck blocked uninstall with phantom PIDs even when no bot was running (the WMI query self-matched its own powershell.exe process). The workaround was --force; v0.9.2 adds a $_.Name -eq 'node.exe' guard so the precheck behaves correctly. See CHANGELOG.md §[0.9.2].
2. Preview with uninstall dry-run

   solosquad uninstall --dry-run
   # Output: archive zip path, what gets archived / deleted / preserved,
   #         REVOKE targets (Discord/Slack/Anthropic tokens), disk free space

3. Execute uninstall — 3 modes

   solosquad uninstall                          # default --mode full (complete cleanup)
   solosquad uninstall --mode keep              # preserve workflows/memory/knowledge (for reinstall)
   solosquad uninstall --mode archive-only      # archive zip only, skip cleanup

   User code at repositories/<repo>/ is never modified or deleted under any mode/flag (v0.7 class A inviolability).
4. Store archive zip safely — ~/solosquad-archive-<workspace>-<ts>.zip auto-created. Recommended: copy to external disk / cloud drive. Verify:

   solosquad archive verify ~/solosquad-archive-...zip
   # manifest.tsv SHA256 + PII-NOTICE scan

5. Clean up external resources — REVOKE-CHECKLIST.md — copy in both workspace root and archive zip. Guides you through:
   • Discord Application ID — delete bot or reset token in Developer Portal
   • Slack workspace ID — remove bot or revoke OAuth in App management
   • Anthropic Claude — estimated ~/.claude/projects/<path-hash>/ path (manual cleanup at user discretion)
   • pm2 / systemctl / crontab — if external automation is registered, unregister commands auto-extracted
6. Remove npm package (optional)

   npm uninstall -g solosquad

   Skip this if reinstalling — npm install -g solosquad@latest overwrites.

uninstall + reinstall to bypass migration

When you want to start the workspace fresh, or skip a large migration chain:

# 1. Uninstall via safe sequence (can use --mode archive-only to only create a data backup zip)
solosquad uninstall --mode archive-only

# 2. Update CLI (skip if already latest)
npm install -g solosquad@latest

# 3. New workspace init (v0.8.5 wizard — workspace.yaml.version is 0.8.5 from start)
mkdir new-workspace
cd new-workspace
solosquad init

# 4. (Optional) Import previous data — restore workflows/memory/knowledge
solosquad import ~/solosquad-archive-<old>-<ts>.zip --mode merge
# or --mode replace (workspace must be empty)

This is the shortcut path that skips the migration chain in one go. Instead of running 9 migrations from v0.4 → v0.8.5, archive → re-init → import jumps straight to the new format. Caveat: archive zip uses v0.7 format, so some pre-v0.6 raw assets are preserved but may not be re-placed into v0.8 multi-user structure (user verification needed).

Getting to 0 doctor warnings after fresh install

Right after a new init, solosquad doctor warnings split into *always-shown info* vs *action-required*:

10.4 Bot · Scheduler · Agent git Operationsv0.8.2~v0.8.6

Scheduler does not auto-start

SoloSquad has no daemon / background auto-start. solosquad init does not register cron, and there is no OS-boot auto-start. You must explicitly start with:

solosquad bot         # messenger bot (Socket Mode + fs.watch)
solosquad schedule    # cron routine runner (morning/evening brief, system-housekeeping)

These two are separate processes. For both to run 24/7, use two terminals or two Docker compose services. solosquad doctor's △ solosquad bot/schedule processes alive (pid ...) warning shows whenever *either one* is alive — on Windows it uses Get-CimInstance Win32_Process to find node.exe processes whose commandLine matches solosquad + (bot|schedule|run-routine).

Agent dev_capability — *up to git push* (v0.8.6 current scope)

With v0.8.2's dev_capability, agents — through messenger conversation alone — *write code → commit → push*. PR creation, review, discussion, and merge happen in the GitHub web UI by the user. v0.8.6 scope statement:

Prerequisites — all *user pre-setup* (not automated by SoloSquad)

1. git installed + push auth working — §4.2 Step 1 prerequisites are enough. Windows/macOS handle this automatically on first push. Linux may need SSH key or PAT setup separately (git/GitHub docs). Verify:

   cd <workspace>/<org>/repositories/<repo>
   git push --dry-run
   # "Everything up-to-date" or "To <url>..." → ✓ pass
   # "Authentication failed" → see troubleshooting §10.1

2. Register repo

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

3. Enable workspace.yaml dev_capability

   # <workspace>/.solosquad/workspace.yaml
   dev_capability:
     enabled: true                      # master toggle (default true)
     require_push_confirmation: true    # user confirmation on git push (permanently true, immutable)
     bash_denylist:                     # workspace-strict blocked commands (optional)
       - "rm -rf /"
       - "shutdown"

Agent push flow

User (command-<handle>): "Integrate Stripe payment module"
                ↓
PM classifies intent → spawn Backend Developer SKILL (dev_capability: true)
                ↓
BD enters repo cwd → analyzes code → adds src/payments/ → writes tests
                ↓
git checkout -b feat/stripe-payment
git add src/payments/
git commit -m "feat: Stripe payment integration"
                ↓
🛑 [dev-confirm gate] PM notifies user via messenger:
   "git push origin feat/stripe-payment? (30-min timeout) [y/N]"
                ↓
User "y"  → push executed
                ↓
BD's final reply (works-<handle>):
   "✓ Branch pushed.
    Open this URL to create the PR:
    https://github.com/me/my-saas/compare/main...feat/stripe-payment"
                ↓
[From here, user responsibility]
User clicks URL → GitHub web UI to create PR → review code → merge

git push is pinned in SENSITIVE_BASH_PREFIXES and must pass a 30-min dev-confirmation gate (src/bot/dev-confirm.ts). If user doesn't respond within timeout, push auto-aborts + logged to <org>/memory/dev-confirmations.jsonl.

Onboarding additions (for dev_capability users)

Beyond the §4.2 9-step, additional setup for dev_capability users — *gh CLI install unnecessary in v0.8.6 scope*:

• Step 1.5 — verify git push auth (optional, only if failing)

  git push --dry-run    # in any of your own repos
  # If failing: see troubleshooting §10.1

• Step 7.5 (right after doctor) — register repo + verify push

  solosquad add repo <url> --org <org>
  cd <workspace>/<org>/repositories/<repo>
  git push --dry-run        # confirm auth works inside the workspace too

• Step 7.7 — set workspace.yaml dev_capability explicitly

  dev_capability:
    enabled: true
    require_push_confirmation: true  # immutable, pinned
    bash_denylist: []

• Step 8.5 (right after starting bot) — messenger first dry test

  In command-<handle> channel:
  "Fix one typo in <repo-name>'s README and push it"
  → Small change verifies the full flow (spawn → diff → commit → dev-confirm → push → compare URL)

• (Optional) Step 8.7 — branch protection rules — In GitHub repo settings, enable Require pull request before merging + Require approvals: 1 on the main branch. Forces explicit user approval for PR merges as a safety net.

10.5 FAQ

Q. How much does it cost?
A. Any Claude Code-capable subscription works (Max recommended). As of v0.9, SoloSquad uses *Claude Code via OAuth* as its single backend. Cloud ops add ~$4-6/month for VPS.

Q. Is Slack supported in v1.0?
A. The v1.0 officially supported messenger is Discord. The Slack adapter ships in the codebase and continues to work for v0.9.x users, but it is not covered by the v1.0 SemVer promise (post-v1.0 slot). New users should start with Discord. For persona separation, run two Discord workspaces: ~/solopreneur/ + ~/elon-24-7/, each with independent .env / tokens / bot accounts. This constraint exists since v0.2.0+ — the older MESSENGER=discord,slack multi-target syntax is not supported.

Q. What if my timezone isn't Korea?
A. Change TZ= in .env (e.g. TZ=America/Los_Angeles). Same in Docker.

Q. What if the AI gives a wrong answer?
A. AI is a tool. Always verify important decisions yourself. solosquad rollback --workflow <id> (v0.3+) can revert spawn results. v0.4 autonomous execution auto-protects via per-cycle git-snapshot keep/discard.

Q. Can I run it on a Raspberry Pi instead of Mac Mini?
A. Possible if Node.js 18+ runs. But verify whether Claude Code CLI officially supports arm64 Linux first.

Q. Can I use it fully offline?
A. No. Claude API and Slack/Discord server communication are required.

Q. Anything I must do before updating?
A. If solosquad bot / schedule is running, stop it first. docker compose down or Ctrl+C in terminal.

Q. Do I have to update every time?
A. No. If you're using it stably, there's no rush. But security hotfixes (e.g. v0.1.3 dotenv miss) should be applied quickly.

Q. Can I automate updates?
A. With Docker, scheduling docker compose up -d --build in cron will refresh the image. But automation isn't possible when migration is required — human confirmation is the principle.

Q. I want to pin an older version.
A. Install explicitly: npm install -g solosquad@0.1.5. Decline solosquad update's upgrade prompts.

Q. Multiple people use one machine.
A. Use different OS accounts. Each account's home directory holds an independent workspace. Run migration per account.

Q. Are there beta / dev channels?
A. solosquad update --channel dev switches to beta (no stability guarantee). --channel stable is default.

Q. How do I upgrade from v0.5 to v0.6?
A. npm install -g solosquad@latest, then from workspace root run solosquad migrate --dry-run → review report (<org>/memory/migration-2026-XX-dryrun.md) → if OK, solosquad migrate --apply --confirm. The --confirm flag is required (mistake prevention). After migration, solosquad agent validate --all auto-runs and reports failures to STDOUT.

Q. Migration reported "human_review_required" items — now what?
A. Some v0.5 ledger assets use heuristic re-placement that can't be 100% accurate — e.g. "org flavor" extraction from a SKILL body with 0 matches. These items are marked human_review_required: true and refused for auto-application. Review the report, manually augment the relevant agent section in <org>/agent-profile.yaml, then re-run migration. Originals are never touched (non-destructive principle).

Q. (v0.6) Auto-reload feels too aggressive — I want to trigger it manually.
A. Set workspace.yaml.fs_watch.mode: manual to disable auto-reload. After SKILL changes, call solosquad agent reload explicitly. fs_watch.mode: prompt (default) is an intermediate mode where the PM asks in messenger whether to apply.

Q. (v0.8.3) What's the difference between solosquad update and solosquad migrate?
A. update refreshes the CLI binary (npm package). migrate converts the workspace schema / layout to match the new CLI. Typical flow: ① solosquad doctor to check CLI ↔ workspace mismatch → ② npm install -g solosquad@latest or solosquad update to refresh CLI → ③ solosquad migrate --dry-run preview → ④ solosquad migrate --apply. doctor explicitly tells you which command is needed (v0.8.3 §7.3).

Q. (v0.8.3) How do I bring existing product code into a SoloSquad workspace?
A. ① cd ~/projects/my-saas && git status to clean untracked + git push for safety → ② mkdir ~/solosquad && cd ~/solosquad && solosquad init → ③ solosquad add repo ~/projects/my-saas --dry-run to pre-check folder mapping / size / 5 risks (IDE lock · symlinks · external abs paths · slug collision · active processes) → ④ solosquad add repo ~/projects/my-saas to actually move (or --keep-original to copy). Your original files remain byte-identical (v0.7 class A rule). The only thing SoloSquad adds is one <repo>/.solosquad/repo.yaml.

Q. (v0.8.3) After moving an existing repo, IDE paths broke.
A. If IDE configs like .vscode/settings.json / .idea/workspace.xml contain absolute paths, SoloSquad doesn't modify user files — you have to update them manually. The dry-run output flags IDE files with absolute-path settings. Same for cron jobs / aliases / CI runner paths — external systems pointing at old paths must be updated by the user.

Q. (v0.8.3) I want to see what the bot is doing — where are the logs?
A. Set SOLOSQUAD_LOG_FILE=1 for daily rolling at <workspace>/.solosquad/logs/solosquad-YYYY-MM-DD.log. Tail in real-time with solosquad logs --tail 200 --follow. Directly query 4 operational jsonl with --type costs/spawn/stop-hook/dev-confirm/migration. 14-day retention (system-housekeeping at 00:00 auto-cleans).

Q. (v0.8.3) Where did solosquad logout go?
A. Added in v0.7, removed in v0.8.3. Judged value < complexity. Replacement flow: pause bot via Ctrl+C to kill the process (restart with solosquad bot); .env secret masking / REVOKE checklist is provided by solosquad uninstall --archive-only; sessions preservation via direct file move under <org>/.solosquad/sessions/ or solosquad pm reset --user <id>. Existing logout.lock files are inert as of v0.8.3 and can be deleted manually.

Q. (v0.8.3) When does trajectory auto-registration activate?
A. When all 4 ROI metrics defined in v0.6 pass (① 30-day suggestions ≥ 5 ② adoption rate ≥ 60% ③ adopted SKILLs' 30-day usage rate ≥ average ④ reject cooldown < 30%), workspace.yaml.trajectory.auto_register: true becomes default in v0.9. If any one fails, "suggestion-only forever" is locked. The v0.8.3 patch only pins the measured values in CHANGELOG; auto-registration code lands in v0.9.