2.How It Works

2.1 Components

SoloSquad runs as two long-lived processes plus a file-based store. There is no separate database server and no cloud backend.

Both processes call Claude Code internally to run the agents. In other words, Claude does the actual work, and SoloSquad is the orchestration layer that wires the messenger to the agents to the file store.

2.2 How a Message Is Processed

When you send a message to #command-<handle>, it is processed in the following order.

1. Your message  (#command-<handle>)
       ▼
2. The Chief classifies the intent  → chat │ workflow │ goal │ schedule
       ▼
3. chat        → answered right there in the #command channel
   anything else → a task card + thread is created in #works-<handle>, and the work is delegated to the PM
       ▼
4. The PM breaks the work into stages and calls (Task) the specialists it needs
       ▼
5. The results are gathered and the Chief reports back to you

The Chief keeps a separate conversation session per (user, organization), so even if you restart the bot it picks up "what we were talking about last time." Workflow stage state, goal cycles, and memory are all persisted to disk and are never lost.

2.3 Folder Structure

A single workspace contains one or more organizations (businesses/products), and each organization contains repositories (code) — a three-layer structure. Reduced to the essentials, it looks like this.

Per-organization character (philosophy, tone, domain knowledge) is layered in from files such as <org>/core/ and <org>/domain/, without ever touching the bundled agent definitions themselves. The files you are most likely to edit by hand are just workspace.yaml (brief times and timezone) and .env (tokens).

2.4 Context & Memory

SoloSquad injects only the context that's needed on every call (Just-in-Time). Because it doesn't always load the full set of agent definitions, both cost and confusion are reduced. Memory falls into three kinds.

Every routine and decision record is appended as JSONL (one line equals one event), and older entries are automatically rolled into a searchable archive (archive.sqlite). You will almost never need to manage memory by hand — a housekeeping routine runs every midnight and takes care of archiving and log cleanup on its own.

3.Key Concepts

3.1 Chief · PM · Specialists

SoloSquad's agents are organized into three layers. You only ever need to talk to one of them — the Chief.

Each specialist's role and operating procedure is defined in a file called SKILL.md (see 3.4), and you don't have to summon them one by one — the Chief and the PM attach the right specialist for you.

3.2 The Three Work Types — workflow · goal · schedule

The Chief sorts every request into one of the following three types (light conversation is answered directly, with no classification).

These three types are the whole of how SoloSquad works. Think of "do this once, now" as a workflow, "keep pushing this number up" as a goal, and "do a set task every day or week" as a schedule.

3.3 Channel Structure — command · works

Two Discord channels are created automatically for each user. The handle is your own identifier (chosen during onboarding; see Chapter 5).

Because the channel names are handle-based, the same channel pair is reused even if you use several Discord servers or later move to a different messenger. And when the owner-only gate is enabled, only you (the registered user ID) receive the Chief's responses.

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

An agent's behavior is defined by a handful of Markdown files. You don't normally need to think about them, but if you want to customize behavior it helps to know what they are.

Per-organization character is added without touching SKILL.md, through separate files such as <org>/core/ (philosophy, tone) and <org>/domain/ (market, customer, and product knowledge). The CLAUDE.md inside one of your code repositories is read automatically by Claude Code whenever it works in that repository.

4.Onboarding

4.1 Pick Your Situation

The steps you follow differ depending on your situation. Pick your type first.

4.2 New Install — Creating Your First Workspace

The full sequence is prerequisites → install → the init wizard → messenger connection → start the bot. Because the messenger (Discord) bot token is entered partway through the wizard, finishing the preparation in Chapter 5 §5.1 first (creating the bot token) lets you run through everything in one pass.

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

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

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

claude login        # Browser OAuth — your credentials are stored on this machine

npm install -g solosquad
solosquad --version

mkdir my-saas
cd my-saas
solosquad init

solosquad doctor            # Environment diagnostics — confirm everything is ✓
solosquad bot               # Messenger bot (separate terminal)
solosquad schedule          # Automated routines (separate terminal)

4.3 Attach an Existing Repo

If you already have a code repository, register it with the workspace. Because the move is one-off and a mistake is costly, we recommend previewing first with --dry-run.

# 1) Tidy up existing work
cd ~/projects/my-saas
git status && git push          # safety net

# 2) Preview from the workspace → then actually register
solosquad add repo ~/projects/my-saas --dry-run   # check for risks (zero disk changes)
solosquad add repo ~/projects/my-saas             # actual registration
#   or, for a git URL, clone:  solosquad add repo https://github.com/me/x.git

# 3) Verify
solosquad sync                  # reconcile repositories/ ↔ .org.yaml

The repo lands in <org>/repositories/<repo>/, and the repo's own .git, CLAUDE.md, and .claude/skills/ are preserved as-is and loaded automatically when work happens. If you have several organizations, it asks which one to attach to; if you have just one, it's assigned automatically.

4.4 Version Update

Two things are distinct — update (refreshing the CLI package) and migrate (reconciling the workspace structure). solosquad doctor tells you which of the two you need.

# 1) Refresh the CLI
solosquad update                 # compare with latest + auto-install
#   or: npm install -g solosquad@latest

# 2) Only when a structural change is involved — reconcile the workspace
solosquad migrate --dry-run      # preview (zero changes)
solosquad migrate --apply        # apply (auto-backup → apply → verify)
solosquad migrate --rollback     # restore from the latest backup (if needed)

5.Messenger Connection

For the AI to converse in a messenger, it needs a bot account. The official messenger for v1.0 is a single one, Discord (the Slack adapter ships in the code but is a post-v1.0 slot). One workspace uses one messenger.

The full flow is (1) Developer Portal preparation → (2) the init wizard → auto-generated invite URL → (3) add to your server + auto-create channels. It's designed to finish with a single click.

5.1 Preparation — Discord Developer Portal

Before running init, create one bot and obtain its token.

5.2 init → Invite → Auto-create Channels

Once you enter the bot token above into the init wizard from §4.2, the rest is mostly automatic.

5.3 Verify It Works

solosquad bot                 # start the bot
solosquad doctor --discord    # 5-step diagnostics (in another terminal)
#  ✓ token  ✓ /users/@me  ✓ bot_user_id match  ✓ guild membership  ✓ channel registration

Send hi to #command-<handle>; if the Chief replies in the form **[name]** ..., the whole path is healthy. If something's wrong, doctor --discord tells you which step is blocked and what to do next.

6.Usage

6.1 The Basic Conversation Flow

The way you work is simple. Make a request in the #command-<handle> channel as if you were just talking, and the Chief classifies the intent and handles it (see the three work types in 3.2).

• A light question or chat → answered right there on the spot.
• Something that needs several stages → captured as a workflow, with a task card + progress thread created in #works-<handle>, and specialists called stage by stage.
• When you want to make the intent explicit → use a slash command.

You: rewrite the landing page hero copy
Chief: (calls Content Writer) — here are 3 draft versions. ...

You: /plan revise the pricing policy
Chief: Wrote the PRD → broke it into stages → registered it in the #works channel.

Adding @<repo> to a request lets you target a specific repository (e.g. "@my-api add a signup endpoint").

6.2 Commands

These are the commands you'll use most in day-to-day work (for the full list, run solosquad --help).

6.3 Automated Routines (schedule)

solosquad schedule runs the following automatically at fixed times. The briefs you see are posted to #works-<handle>.

Adjust the times and which routines are active by editing timezone and briefings in .solosquad/workspace.yaml to fit your own daily rhythm. To run a specific routine right away, use solosquad run-routine morning-brief.

6.4 Recommended First Tasks

1. Confirm solosquad doctor is all ✓.
2. Send hi to #command-<handle> and confirm the Chief responds.
3. Introduce yourself. Tell the Chief about you, your business, and your goals in a single paragraph, and your later responses will have the right context (principles and tone are recorded in <org>/core/).
4. Run one small workflow. For example: "Lay out this week's single key hypothesis and how to validate it." Watch a task card appear in the #works channel.
5. Adjust the brief times. Set the morning/evening times in workspace.yaml to match your own routine.

7.Operations Guide

7.1 Running 24/7

For the bot to keep its messenger connection alive, solosquad bot (and schedule) must stay up. Choose the approach that fits your situation.

# Local — two terminals
solosquad bot
solosquad schedule

# Docker — from the workspace
docker compose up -d --build
docker compose logs -f bot

7.2 Updates & Bot Restart v1.2.8~9

When you update (§4.4), there's no need to manually stop and start the bot. The behavior differs by environment.

7.3 Multiple Businesses & Repositories

A single workspace can hold several organizations (= businesses/products), and each organization's memory, workflows, and channels are fully isolated.

solosquad add org my-side                          # add a new organization (interactive)
solosquad add repo https://github.com/foo/bar.git  # clone + register
solosquad add repo ./local-repo                    # register a local one
solosquad sync                                      # reconcile repositories/ ↔ .org.yaml

How the organization is chosen: an explicit --org wins → if there's only one org it's automatic → if the cwd is inside an org folder, that org → otherwise an interactive picker. Cross-repo work, targeting a different repository at each stage within a single workflow, is also possible.

If you need persona separation (main job vs. side project), create multiple workspaces — each has its own independent bot, token, and memory. The CLI update is done once, but migration is run separately in each workspace.

7.4 Security & Backup

• Protect your tokens. .env is gitignored automatically. Rotate the bot token periodically (e.g. every 90 days).
• Least privilege. Don't grant more than the recommended permissions on the invite URL. Use the owner-only gate so only you can issue commands.
• Review outputs. Always review AI-generated results before applying them to production. Sensitive commands (such as git push) go through a confirmation gate.
• Backups. List migration backups with solosquad backup list and prune old ones with solosquad backup purge --keep-recent 3. Create a full workspace archive with solosquad uninstall --mode archive-only, and before storing it externally, check its integrity and PII with solosquad archive verify.
• Cloud operations. Allow only SSH key authentication and configure the firewall around outbound traffic.
• Logs. Watch in real time with solosquad logs --follow. Cost, spawn, and confirmation-gate logs are all in one place.

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 (workspace root)

Docker image build recipe. For containerizing SoloSquad bot/scheduler. Since v1.2.10, solosquad init copies it to the workspace root (source template lives in assets/docker/).

docker-compose.yml (workspace root)

Settings for running multiple containers (bot + scheduler) together. Run docker compose up -d --build from the workspace root. Also mounts ~/.solosquad/ + ~/.solosquad-backups/ — user-global SKILL override and backups compatible. v1.2.10: removed the maintainer-only deploy/docker/ repo-self-hosting stack and consolidated user Docker assets into a single home at assets/docker/.

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.3.0 (2026-06-16) latest — Messenger UX overhaul: dev-confirm push-approval gate + interaction components + artifact filing

• git push approval gate (Part A) — right before an agent runs git push / gh pr merge / gh pr close, a ✅ approve / ❌ reject card is posted to your command-<handle> channel. The push proceeds only on approval. A direct push to a protected branch (main/master/develop) is auto-blocked with no card. The approval is recorded with the commit hashes in <org>/memory/dev-confirmations.jsonl. Failure policy: no answer in 30 min = blocked; a hook error = allowed (protected branches stay blocked regardless). Config: workspace.yaml pm.git (protected branch list, timeout). SoloSquad sends no push notifications — register your own GitHub→Discord native webhook for that.
• Button/menu interactions (Part B) — approvals and choices come as buttons / select menus instead of free-text y/n. Misfire recovery: ❌ reject asks a 2-step ephemeral confirm, buttons disable after a confirmed click, and reversible choices get an undo grace window. (The 🛑 stop button + live progress narration shipped earlier in the v1.3.0 line.)
• Artifact filing (Part C P1) — long replies (~1500+ chars) are saved to <org>/artifacts/ and posted as a Discord file attachment + preview card instead of a wall of chunked text. Git-versioned.
• Details: CHANGELOG.md §[1.3.0], docs/prd/v1.3.0-dev-confirm-gate-live.md

v1.2.10 (2026-06-16) — Consolidation cleanup: finish PM→Chief rename · roll back the git channel · remove the repo-self-hosting Docker stack

• Chief rename settled (Part A) — CLI solosquad chief status/reset/compact is canonical (pm … kept as a hidden deprecated alias); events pm.*→chief.* with read-compat for older logs.
• git channel rollback (Part C) — removed v1.2.9's git-<handle> channel + self-built push notifications. The only thing needed is push approval (→v1.3.0); completion notices are delegated to the native webhook.
• Docker asset cleanup (Part D) — removed the repo-self-hosting stack and consolidated user Docker assets into a single home at assets/docker/ (no regression).
• Details: CHANGELOG.md §[1.2.10], docs/prd/v1.2.10-consolidation-cleanup.md

v1.2.9 (2026-06-01) — Discord app-ID auto-detect + invite-URL restored · git channel · chat UX · cancel · permission toggle

• Fixes "onboarding never asks for the app ID / never generates the invite URL" — the v1.2.6 OAuth invite-URL 1-click flow never worked, defeated by a single non-existent API field. fetchBotIdentity read application_id from GET /users/@me (the bot User object), but that object has no such field → appId was always undefined → init's invite-URL block was always skipped, no app-ID prompt existed, and a later discord invite-url failed.
• Correct endpoint — GET /oauth2/applications/@me (the only endpoint that returns the application id for a bot token), falling back to the bot user id (identical snowflake for Discord bots) on any failure.
• Explicit Application ID confirmation prompt — init Step 3.5 surfaces the detected id with Enter-to-accept; on detection failure the user pastes it from Developer Portal → General Information → Application ID (17-20 digit validation).
• solosquad doctor --discord Hop 2 — now populates the live app id via the same endpoint, so the Hop 3 "bot_application_id missing" warning and the Hop 4 invite-URL hint actually fire.
• Net effect — finishing init on the Discord path now auto-detects the app ID, confirms it with one Enter, and prints + opens the invite URL at the end — finally delivering the v1.2.6 "finish init → click once → channels auto-create in under 5 minutes" promise.
• git event channel + chat UX (Part B·C) — new git-<handle> channel (agent push-notification feed — channel + config live; the notification itself goes live in v1.3.0). Chief now knows its surface (Discord/Slack/CLI), stops wrapping whole replies in code blocks, and drops the trailing -name sign-off. solosquad chat lets you talk to Chief from the terminal.
• cancel /cancel (Part D) — abort in-flight work from Discord/terminal. Previously a second message just queued behind the first.
• dev permission toggle /grant·/revoke (Part E) — fixes agents hanging when they lacked file-write/git permission. Dev mode ON injects acceptEdits + an allow-list into the spawn (file writes + git add/commit/checkout/branch + npm; push / PR-merge excluded). Default ON at onboarding; /revoke drops to read-only.
• Details: CHANGELOG.md §[1.2.9], docs/prd/v1.2.9-discord-app-id-fix-and-git-events-channel.md (+ v1.3.0-dev-confirm-gate-live.md design)

v1.2.8 (2026-05-29) — Bot restart automation + ESM/CJS fix

• v1.2.7's --add-dir wiring made to actually run — chief-runner helpers used require("fs"|"path"|"js-yaml") inside an ESM package → silent throw → addDirs came back empty → --add-dir never reached the spawn. v1.2.8 replaces with top-level import so the bot actually receives access to every registered repo.
• Bot PID file + migration SIGTERM — solosquad bot writes its PID to <workspace>/.solosquad/bot.pid. solosquad migrate --apply reads it after a successful migration and sends SIGTERM. Cloud users (systemd / PM2 / Docker restart: unless-stopped) auto-respawn — no systemctl restart / docker compose restart needed.
• solosquad bot --supervise — local wrapper that spawns the bot as a child, respawns on clean exit (1.5s backoff). Crash threshold = 3 consecutive non-zero exits. Lets local users get migration auto-restart without configuring a process manager.
• Graceful drain on SIGTERM — when the bot receives a signal mid Chief turn, it enters drain mode (refuses new turns), waits up to 120s for active turns to finish (so the user gets the reply, not silence), then clean-exits. Second signal forces immediate exit.
• Pre-publish ESM purity gate — npm run prepublishOnly now greps dist/**/*.js for bare require( and aborts publish if any exist. Skips comments / string literals / createRequire(import.meta.url) (the legitimate ESM bridge). Catches the v1.2.7-class bug 1 second before npm publish.
• Details: CHANGELOG.md §[1.2.8], docs/prd/v1.2.8-bot-restart-and-esm-fix.md

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

npm publish completed but the wiring didn't actually run due to an ESM/CJS notation bug. v1.2.8 fixes and chains. No need to install v1.2.7 directly — users jump straight to v1.2.8.

• Bot was supposed to scan <org>/repositories/*.yaml on every spawn, collect registered repo paths, and pass them as claude --print --add-dir <path1> <path2> .... Users would no longer have to run /add-dir manually (intended behavior).
• Default clone target for Chief-requested new repos = parent directory shared by existing registered repos (dynamic per-user, not hardcoded).
• v0.x-era migrate / sync CLI messages updated to match the v1.0+ path-reference model (no more "clone into repositories/" prompts).
• Details: CHANGELOG.md §[1.2.7]

v1.2.6 (2026-05-29) — 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 (npm 1.2.4 / 1.2.5 were burned during pre-launch, so the actual publish slot is 1.2.6)

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.