SoloSquad

🇰🇷 한국어 README: README.kr.md

A 24/7 AI assistant system for solo founders, small teams, and n-jobbers — Discord bot + scheduled crons + team-based agents, distributed as a single npm package.

Running a company alone doesn't mean working alone. SoloSquad gives you a virtual team — 1 Chief (org-level supervisor, the only user-facing agent), 4 main bots (pm / engineer / designer / marketer), and 20 specialists across 4 teams (product, engineering, design, marketing) — reachable from your messenger, with automated daily crons, per-org memory isolation, and a 6+1 stage decision loop (TRIAGE → DECOMPOSE → DISPATCH → AWAIT → SYNTHESIZE → DECIDE → RETROSPECT).

Output ≠ Goal. Output = Means to achieve the goal.

Topology — hierarchical supervisor (orchestrator-workers)

SoloSquad is a hierarchical orchestrator-workers system, not a decentralized swarm: a central Chief dynamically decomposes and delegates but keeps control to the end (agents-as-tools — Chief owns the SYNTHESIZE step). Three tiers:

👤 User (Discord / terminal)
        │ handleUserMessage
        ▼
   Chief  (tier: leader · team: chief)          ── org-level supervisor
        │ DECOMPOSE → DISPATCH
        ├──▶ pm         (leader · product)      ── also a 2nd-tier orchestrator
        ├──▶ engineer   (leader · engineering)     (pm.used_by routes to eng/des/mkt too)
        ├──▶ designer   (leader · design)
        └──▶ marketer   (leader · marketing)
                  │
                  ▼
             specialists (member) ── 20 bounded workers across the 4 teams

The delegation graph is a DAG, not a pure tree — pm calls the other three leaders (plan→hand-off), so reference-integrity + cycle validation matters (solosquad agent validate --graph). Each spawn gets an independent context window. Full detail: docs/architecture.md §5.1.

Platforms: Windows · macOS · Linux (cross-platform CLI, CI-tested) Messenger: Discord — one per workspace. Slack adapter code ships but is not part of the v1.0 SemVer promise (post-v1.0 slot). Telegram support removed in v0.2.4. Stack: TypeScript + Node.js 18+ · Claude Code as the AI engine · file-based memory (JSONL)

Documentation

📖 The canonical user guide is the menu-divided HTML manual:

manual/master-guide_en.html (English) · manual/master-guide_ko.html (한국어) — open in a browser.

It covers, in ten menu-divided sections:

| # | Section | What's inside | |---|---|---| | 1 | Getting Started | Project intent, core concepts, expected value | | 2 | How It Works | System architecture, folder hierarchy, memory model, workflow definition | | 3 | Concept Glossary | SKILL.md, KNOWLEDGE.md, CLAUDE.md, AGENTS.md comparison; per-layer file inventory; 4-channel routing | | 4 | Onboarding | Branches for new users, existing-repo migration, and version upgrades | | 5 | Messenger Setup | 8-step Discord token walkthrough (Slack walkthrough retained as a post-v1.0 reference) | | 6 | Usage | CLI reference (current + planned), daily ops, first-run checklist, automated crons | | 7 | Glossary | 60+ core terms, file-name dictionary, acronym dictionary — beginner-friendly | | 8 | Version Differences | v1.3.2 (npm-published) vs upcoming releases | | 9 | Operations | 24/7 hosting options (terminal · Docker · launchd/NSSM · VPS), multi-workspace, multi-org, security checklist | | 10 | Troubleshooting & FAQ | Install/runtime issues, migration failures, FAQ |

Every feature is tagged with a version badge.

For internal architecture, release planning, and decision history, see docs/roadmap.md + docs/architecture.md.

What's new in v1.4.3 (2026-07-12)

Research Workflow — validate before you build. A third bundled main workflow, research, runs autonomous hypothesis validation before feature development: spec (a falsifiable question + a pre-registered rubric) → diverge/converge hypothesis (web/literature search, not just internal knowledge) → experiment cycles → a blind, leakage-controlled backtest with numeric eval → a Track2-style verifier review → report, looping until the rubric passes or the budget runs out. A goal can now run this unattended for 8h+.

Reports are first-class deliverables. Market-research reports, papers, and prototypes now land at the org top level in <org>/reports/ (out of the internal docs/ layer).

Continuity migration 1.4.2 → 1.4.3 moves each org's reports from docs/reports/ up to reports/ (files moved, never overwritten); no session reset. Update with solosquad update → migrate --apply, then restart (solosquad start).

Full release notes: CHANGELOG.md §1.4.3.

What's new in v1.4.1 (2026-06-27)

Chief reads & replies in works task threads. Until now, messages in a works-<handle> task thread were silently ignored — Chief only listened on command-<handle> channels. Now you can keep talking to Chief inside the task's thread, where the work lives.

• No permission change — the bot invite already grants Create/Send-in-Threads + the MessageContent intent; this was a code boundary, now lifted.
• Thread → task context — Chief is told which task the thread is about (looked up from the thread's workflow), so follow-ups land in context.
• Single shared session (Approach A) — the thread uses your existing Chief session; per-task isolation ("only that task's context") is the next step.

Also — one command for bot + cron. solosquad start runs the bot, the cron scheduler, and a supervisor together (single-host all-in-one); solosquad bot --with-cron adds the scheduler without the supervisor. A scheduler singleton lock stops double-firing if a separate cron start / scheduler service is also up, so the 2-service Docker split keeps working unchanged.

Bundle-only — continuity migration 1.4.0 → 1.4.1 is a plain version bump (no session reset). Restart the bot after solosquad update → migrate --apply.

Full release notes: CHANGELOG.md §1.4.1.

What's new in v1.4.0 (2026-06-27)

Session orchestration — re-scoped, low-risk subset. The non-destructive slice of the session-orchestration line; session 교대 (token-threshold handoff + rotation) and GC destructive deletion are deferred to v1.4.x after their side-effects are validated.

• 🆕 session-start marker — a new / reset / rotated Chief session shows a "🆕 세션 시작" marker before the Chief name on its first Discord reply, so you can tell the context was wiped.
• Crons see your repos (S-1) — scheduler crons now resolve external-path repos (repositories/<slug>.yaml), instead of running at org-root only.
• Token-usage telemetry (S-2a) — each Chief turn records a chief.usage event (context-window occupancy). Observation only — nothing rotates on it yet.
• leading-indicator cron preset (§5.5) — solosquad cron preset leading-indicator enables the autonomy-health indicators (incl. avg_context_tokens from S-2a).
• _log.md workflow audit log (S-3) — additive to _handoff.md; plus a spawn-change session-reset migration helper (§5.7).

Bundle-only — continuity migration 1.3.11 → 1.4.0 is a plain version bump (no session reset; spawn behaviour unchanged). Restart the bot after solosquad update → migrate --apply.

Full release notes: CHANGELOG.md §1.4.0.

What's new in v1.3.11 (2026-06-25)

Windows --add-dir hotfix (on 1.3.10). After updating to 1.3.10, Windows bots still couldn't read registered repos because of a second bug: on Windows the bot spawns claude through a shell command string, and a newline in the Chief system prompt (--append-system-prompt) broke the cmd.exe command line, dropping every flag after it — including --add-dir. The system prompt is now passed via a temp file (--append-system-prompt-file), so its newlines stay off the command line and --add-dir survives. (macOS/Linux were unaffected.) Windows users on 1.3.10: solosquad update → migrate --apply → restart the bot.

What's new in v1.3.10 (2026-06-25)

Bot permission UX + a claude-code compatibility fix. Three bot fixes that converged on one symptom — "the bot can't read my registered repos / it asks for approval on every action".

• Registered repos are readable again. Claude Code 2.1.x silently ignores --add-dir when input is fed as --input-format stream-json over stdin, which blocked the bot from reading repos registered under <org>/repositories/. The bot now sends the message as plain text over stdin (output streaming unchanged), so --add-dir is honored. (Upstream claude-code bug.)
• Safe operations no longer interrupt you. Reading/editing registered repos, Bash, WebFetch, git add/commit, and feature-branch git push run with no approval. Only a push to a protected branch (main/master/develop) or gh pr merge/gh pr close gates — and a protected push now shows the ✅승인/❌거절 approval card instead of a hard block.
• No more phantom "press approve". The Chief no longer tells you to press an approval button that doesn't exist; permissions are handled by the system.

Bundle-only — resumed sessions pick up the fixes on their next turn (spawn args rebuild per turn).

Docs management system + a docs skill (from 1.3.8). The documentation slice of the 1.3.x "primitive & doc authoring internalization" line. Docs and versioning are made repository-scoped, with a single curation authority and an expanded pre-publish gate.

• Docs scope = repository unit — each repo owns its package.json/docs//CHANGELOG/manual and bumps x/y/z independently (work ≠ release). Two orthogonal axes: external/internal (enforced by package.json files) and repo layer (prd · architecture · roadmap · README · CHANGELOG · manual = release-bound) vs org workspace layer (ideation · reports = cross-repo research). A single-repo project collapses both into the same docs/.
• New docs skill — the single authority for classification, naming (<version>_<name>_<date>), PRD↔release-version 1:1 (hotfix = next 3-segment patch with its own hotfix-format PRD), the publish gate, and INDEX upkeep. prd stays the per-PRD writer.
• prd 8 authoring rules — R1–R5 (context / over-spec) + R6–R8 (AI-product PRD branch: range of acceptable answers · Eval Plan · guardrails; completeness score; Given-When-Then AC).
• 6-doc conditional gate — docs-check expands 4→6 (roadmap · architecture · CHANGELOG · README required + manual conditional) + PRD existence + a docs/-leak invariant.
• Migration — 1.3.7 → 1.3.8 force-seeds org-layer ideation/+reports/ (with INDEX) in the workspace; repo working trees are untouched.

Bundle-only — no user-workspace data changes beyond the seeded org dirs.

Full release notes: CHANGELOG.md §1.3.11.

Quick Start (5 minutes)

# 1. Prerequisites (one-time)
brew install node git                             # macOS — see master-guide §4.2 for Windows/Linux
npm install -g @anthropic-ai/claude-code

# 2. Install SoloSquad
npm install -g solosquad
mkdir ~/solosquad-workspace && cd ~/solosquad-workspace
solosquad init                                    # wizard handles Claude OAuth (Step 1.5) + Chief name + Discord token + invite URL auto-open
solosquad doctor                                  # verify environment
solosquad doctor --discord                        # focused 5-hop Discord diagnostic (v1.2)

# 3. Start the bot
solosquad bot                                     # foreground
# or
docker compose up -d --build                      # background + auto-restart (from workspace root; init dropped the compose file here)

When you invite the bot to a guild, the guildCreate onboarding embed appears in the system channel. Click Auto-create channels → the bot creates #command-<handle> and #works-<handle>, posts a first greeting in the command channel, and you're ready. Send a message — the Chief responds.

Messenger token setup takes 3–5 minutes (Discord). Follow master-guide §5 step-by-step.

Upgrading from v0.5.x

npm install -g solosquad@latest             # 0.5.x → 0.6.0
solosquad migrate --dry-run                 # Pass 1 simulation + report under <org>/memory/
# review the report, then:
solosquad migrate --apply --confirm         # 2-pass with human-review gate

Pass 2 automatically runs solosquad agent validate --all. Entries marked human_review_required: true are not auto-applied — you reclassify them manually after the migration. Migration LLM fallback costs accumulate in <org>/memory/migration-costs.jsonl under a per-run cap.

What you get

25 agents across 4 teams, frontmatter-routed automatically

| Team | Agents | Role | |---|---|---| | Strategy (7) | PMF Planner · Feature Planner · Data Analyst · Business Strategist · Idea Refiner · Scope Estimator · Policy Architect | Market analysis, hypothesis design, planning | | Growth (4) | GTM Strategist · Content Writer · Brand Marketer · Paid Marketer | Marketing, branding, copy, paid acquisition | | Experience (4) | User Researcher · Desk Researcher · UX Designer · UI Designer | Research, design | | Engineering (10) | Creative Frontend · FDE · Architect · Backend · API · Data Collector · Data Engineer · Cloud Admin · QA · Security | Development, infra, quality, security |

You: "Write landing page copy"        → Content Writer (Growth)
You: "Analyze the signup funnel"      → Data Analyst (Strategy)
You: "Design the login UI"            → UI Designer (Experience)
You: "Design the signup API"          → API Developer (Engineering)

v0.5 4-channel routing (priority: slash > explicit > keyword > freq) decides which specialist's SKILL.md is injected each turn. Triggers live in each agent's frontmatter (triggers.slash / .keyword / .freq), collected at bot boot via a 3-tier scan (<org>/.agents/ > ~/.solosquad/agents/ > bundled). The old hard-coded AGENT_ROUTES constant was removed in v0.5.

v0.6 chokidar hot-reload watches the same 3 tiers (forced polling on Windows + WSL, 300 ms debounce) and atomically swaps the router index — no bot restart on SKILL edits. Reload behaviour is configurable: auto (default) / prompt / manual with an optional git_only safe mode (HEAD ≡ upstream + clean tree only). solosquad agent reload triggers a manual rebuild.

Six automated crons, runs while you sleep

| Default time | Cron | Output channel | Memory | |---|---|---|---| | 08:00 daily | Morning Brief | #workflow root | — | | 12:00 daily | Signal Scan | #workflow → system-daily-signals thread | signals.jsonl | | 16:00 daily | Experiment Check | #workflow → system-experiments thread | experiments.jsonl | | 18:00 daily | Evening Brief | #workflow root | decisions.jsonl | | Sun 20:00 | Weekly Review | #workflow → system-weekly-review thread | decisions.jsonl | | 23:00 daily (v0.3) | PM Compaction | #workflow → system-pm-compaction thread | memory/pm-skills/ |

All times configurable in .solosquad/workspace.yaml (timezone defaults to Asia/Seoul).

3-Layer context isolation

Layer 0 · Workspace (universal)    → Owner profile, principles, 25 agent definitions
   ↓
Layer 1 · Organization (per-product) → Memory, workflows, messenger channels
   ↓
Layer 2 · Repository (per-codebase) → Code + repo-specific skills

Product A's agents never see Product B's data. Multiple products coexist cleanly under one workspace.

Self-hosted

Runs on your Mac Mini, PC, or VPS. Your data stays with you. Only outbound calls: Claude API and your messenger's servers.

CLI Reference (v0.8.3)

# Workspace ops (v0.1+)
solosquad init                                    # workspace setup wizard
solosquad bot                                     # start messenger bot
solosquad cron start                              # start automated cron scheduler
solosquad status                                  # dashboard (orgs, workflows, recent activity)
solosquad doctor                                  # environment diagnostics
solosquad doctor --messenger-check                # validate tokens via live API
solosquad update                                  # check & install latest npm release
solosquad cron run [name]                         # manual cron execution

# Chief session ops (v0.3, renamed PM→Chief in v1.1)
solosquad chief status                            # active Chief sessions, cumulative cost
solosquad chief reset                             # archive a user's session, mint a new one
solosquad chief compact                           # externalize completed workflows
solosquad workflow list                           # list workflows
solosquad workflow show <wf-id>                   # stages + recent events
solosquad workflow focus <wf-id> [--clear]        # set/clear active workflow per session
solosquad rollback [--workflow <id>] [--to <sha>] [--list]   # git-snapshot revert

# Autonomous engine (v0.4)
solosquad goal new [goal-id]                      # scaffold goal.md from template
solosquad goal list                               # list goals
solosquad goal show <goal-id>                     # spec + recent cycles
solosquad goal run <goal-id> [--hours N | --cycles N]   # background autonomous loop
solosquad goal status [goal-id]                   # cycle counts, cost, ship candidate
solosquad goal stop <goal-id>                     # stop in-flight run (current cycle finishes)
solosquad goal verify <goal-id> --cycle N         # re-run evaluator, check determinism

# Agent authoring (v0.5 + v0.6)
solosquad agent validate <path>                   # validate one SKILL.md against v0.5 schema
solosquad agent validate --all [--corpus]         # validate every bundled + workspace SKILL.md
solosquad agent add --name <slug> --team <team>   # scaffold a new SKILL.md (no LLM)
solosquad agent list [--workspace]                # v1.3.2 — actors grouped by team
solosquad agent show <id> [--workspace]           # v1.3.2 — spec + delegation edges
solosquad agent reload [--org <slug>]             # v0.6 — manual router rebuild (manual fs.watch mode)
npm run validate-skills                           # CI gate (= agent validate --all --corpus)

# Asset managers + adoption (v1.3.2)
solosquad commands                                # full CLI tree + one-line descriptions
solosquad asset list [kind]                       # list assets (skill|agent|workflow|cron, or all)
solosquad asset show <kind> <id>                  # show one asset
solosquad asset validate [kind]                   # deterministic validation gate (all kinds, or one)
solosquad adopt <repo> [--apply] [--classify]     # discover + validate + adopt a repo's assets
solosquad cron new <id> [--cron …|--at …]         # scaffold a recurring (--cron "@daily"|"every 1h") or one-shot (--at "20m") cron
solosquad cron list|show|validate                 # inspect user-defined crons
solosquad cron edit <ref> [--cron|--name|…]       # patch fields, then re-validate
solosquad cron enable|disable <ref>               # resume / pause (pause ≠ delete)
solosquad cron delete <ref> [--hard]              # archive (default) or hard-remove
solosquad cron runs [ref] [-n N]                  # recent run history (status / when / duration)
solosquad cron freq [--apply <id>]                # freq-miner routing suggestions (suggest-only)

# Memory archive (v0.6)
solosquad readiness check [--target v0.6]         # v0.5 data + 4 default workflows + author SKILL counts → pass/short
solosquad memory search <query> [--limit N]       # FTS5 full-text search over archived events
                       [--event-type X]           #   routine_log | route_hit | route_miss | author_turn | spawn_decision
solosquad memory stats [--disk]                   # indexed row counts + per-event-type breakdown (+ sqlite file size)

# Repo analyzer (v0.5) + dry-run inspect (v0.8.3)
solosquad analyze repo <path> [--force] [--prune-orphans]    # scan .claude/skills/, classify, write report
solosquad add repo --from-report <report> --merge-policy <append|override|replace>
solosquad add repo <path> --dry-run               # v0.8.3 — simulate, print 5-scenario risk report
solosquad add repo <path> --keep-original         # v0.8.3 — copy instead of move (disk 2×)
                                                  # (v0.8.4: --inspect alias deprecated, removed in v1.0)

# Migration
solosquad migrate                                 # upgrade workspace layout (dry-run by default)
solosquad migrate --apply                         # perform migration
solosquad migrate --rollback                      # restore from backup

# Org / repo
solosquad add org <name>                          # add an organization
solosquad add repo <url|path>                     # clone or register a repository
solosquad sync                                    # sync repositories/ with .org.yaml

# Lifecycle (v0.7 + v0.8.1, surface frozen by v0.8.4)
solosquad uninstall [--mode full|keep|archive-only] [--dry-run] [--force]
                                                  # farewell archive + cleanup, user code untouchable
                                                  # default: full. keep = retain workflows/memory/knowledge,
                                                  # archive-only = zip only, no cleanup
solosquad import <archive.zip> [--workspace <path>] [--into <org>]
                               [--dry-run] [--mode merge|replace]
                                                  # v0.8.1 — restore farewell archive (paired with uninstall)
solosquad archive verify <archive.zip>            # v0.8.1 — manifest SHA × actual SHA + schema compat
solosquad archive info <archive.zip>              # v0.8.1 — metadata + per-class entry counts
solosquad archive list <archive.zip> [--class X]  # v0.8.1 — manifest entries

# Backup management (v0.8.4 — absorbs migrate/uninstall backup flags)
solosquad backup list                             # list ~/.solosquad-backups/ entries
solosquad backup delete <id>                      # remove a single backup
solosquad backup purge [--keep-recent N] [--dry-run] [-y]
                                                  # bulk delete (all, or keep N newest)

# Multi-user messenger (v0.8.0)
solosquad messenger broadcast-handover --to <handle>   # reassign designated broadcaster bot
                                                       # (broadcast cross-user feed §3.6 v2 — opt-in)

# Observability (v0.8.3)
solosquad logs [--level X] [--tail N] [--follow] [--since "1 hour ago"]
               [--type runtime|costs|spawn|stop-hook|dev-confirm|migration]
                                                  # structured logs + 4 ops jsonl unified view

See master-guide §6 for the per-command walkthrough and v1.0+ planned commands.

Architecture Overview

Two long-running processes plus a file-based memory layer:

| Process | Role | |---|---| | solosquad bot | Receives messenger message → resumes the user's long-lived PM session (orchestrator/SKILL.md, v0.3) → 4-channel router resolves which specialist to load (slash > explicit > keyword > freq, v0.5) → delegates to a fresh subagent via Claude Code's native Task tool → synthesizes the tool result and replies | | solosquad cron start | Runs scheduled crons (built-ins + user-defined), appends results to JSONL memory files. Set timezone + a crons block in a user's .solosquad/users/<handle>.yaml to get personalized morning/evening briefs in their own works-<handle> channel at their own timezone |

Two additional modes layer on top of the bot:

• v0.5 author loop — messenger-native skill creation. The _meta/workflow-maker meta-skill walks the user through CLARIFY → DRAFT → SANDBOX_PROMPT → AWAIT_CONFIRM → APPLIED, with paperclip-style budget caps logged to <org>/memory/author-costs.jsonl. Spec-gate drafts auto-emit a <org>/goals/<goal-id>/goal.md.
• v0.4 goal-runner — background autonomous cycle. solosquad goal run <id> boots a bg-<goal-id>-<runId> PM session that loops pipeline → evaluator (metric gate) → git-snapshot keep/discard until the time/cycle/cost budget runs out or all metrics pass CONFIRMING. solosquad goal verify re-runs the evaluator on a past cycle to check determinism.

v0.6 layers five more pieces over the v0.3–v0.5 base:

• Spawn assembly — src/bot/spawn-assembler.ts builds each Task prompt as an 8-layer JIT injection (knowledge → team KNOWLEDGE → SKILL → <org>/core/ → agent-profile.yaml → <org>/domain/ → handoff + memory recall → target repo) bounded by workspace.yaml.spawn.max_context_tokens (default 80000). When the budget is exceeded, lower-priority layers drop in a fixed order and every decision is recorded to <org>/memory/spawn-decisions.jsonl (FTS5-indexed).
• Budget envelope — two separate namespaces: author-loop turns log to author-costs.jsonl, spawn calls log to agent-costs.jsonl. Per-agent caps in <org>/agent-profile.yaml can only narrow the workspace defaults, never widen them. Migration LLM fallback costs are isolated in migration-costs.jsonl so a misbehaving migration cannot starve the running bot.
• FTS5 cold archive — src/memory/ rotates cron-logs/*.jsonl older than 8 days into <org>/memory/archive.sqlite once a day (assets/routines/archive-rotate.md, 00:00). Retention defaults to 365 days, with an optional .zst compress-before-delete step. Four event types are indexed (route_hit / route_miss / author_turn / spawn_decision); on a router miss the bot surfaces a single recall hint to the user.
• Hot-reload — chokidar 3-tier fs.watch (forced polling on Windows + WSL, 300 ms debounce) feeds src/bot/reload-policy.ts, which atomically swaps the router index in auto / prompt / manual mode. An optional git_only safe mode requires HEAD ≡ upstream + clean tree before any reload.
• Stop-hook — v0.5's loop_mode.spec-gate SKILL field is now executable through src/engine/stop-hook-adapter.ts. The DSL accepts three forms (command / metric / natural), runs with a 5-second timeout, and on ambiguity defaults to continue (conservative). Every evaluation is appended to <org>/memory/stop-hook-events.jsonl and threaded back into the v0.4 goal-runner.

For production-grade always-on, choose one of:

• Docker Compose (recommended, background + auto-restart) — solosquad init drops docker-compose.yml + Dockerfile in your workspace root; run docker compose up -d --build there. See master-guide §Docker.
• macOS launchd plist / Windows NSSM service
• VPS + systemd (see manual/cloud-deployment.md)

Full details in master-guide §7.1.

Versions

Current npm release: v1.3.2 (npm registry: 1.3.2).

v1.0 marked the formal release with stable API guarantees. Shipped + planned milestones (full history in CHANGELOG.md, decision log in docs/roadmap.md §6):

| Version | Theme | Highlights | |---|---|---| | v0.3 (released) | PM mode + multi-agent orchestration | Long-lived PM session per (user, org); specialists delegated via Claude Code's native Task tool; slash chain /think /plan /build /review /ship; workflow reconciler on bot boot; solosquad pm / workflow / rollback CLIs; per-org snapshot.git | | v0.4 (released) | Autonomous overnight engine | goal.md intent file + solosquad goal run background loop; metric-driven keep/discard with git-snapshot revert; AGENTS.md as the single immutable workspace guide (cross-tool); 3-tier guardrails (Input / Runtime / Output); solosquad goal verify for determinism checks | | v0.5 (released) | Workflow maker + frontmatter routing | Messenger-native author loop (_meta/workflow-maker); 4-channel router (slash > explicit > keyword > freq) with paperclip budget envelope; repo analyzer (4-label classification + incremental ledger); 25 SKILL.md with Anthropic-compatible frontmatter; spec-gate ↔ goal.md integration | | v0.6 (released) | Default workflow tuning + memory archive + pattern miner + Org Layer | Org Layer (<org>/{core,domain,agent-profile.yaml} + spawn-assembler 8-layer + budget generalization); FTS5 archive with 4-event-type indexing for cumulative memory recall; trajectory + freq miners that auto-extract repeated patterns into SKILL drafts (reuses v0.5 applyDraft); stop-hook DSL (command / metric / natural) making v0.5 spec-gate executable; chokidar hot-reload + CI PR review bot | | v0.7 (released) | Uninstall & Lifecycle (Farewell Archive) | solosquad uninstall; data 5-classification (A/A*/B/C/D/E) with user code untouchable (class A); farewell archive with WAL-safe SQLite backup + streaming SHA256 manifest; concurrent-uninstall lockfile + stage progress journal (idempotent resume); REVOKE-CHECKLIST.md auto-generated; --keep-workspace class matrix; solosquad reset/clean permanently rejected (lifecycle is install ↔ uninstall). solosquad logout was added then removed in v0.8.3 | | v0.8.0 (released) | Multi-User Messenger | Same Discord server with N members each running their own bot. command-<handle> + works-<handle> channel pairs per user; bot multiplicity (1 user = 1 bot application); author-guard defense-in-depth (channel owner enforcement); explicit handle-collision rejection; opt-in broadcast channel (cross-user work feed in v1.x). Solo user remains a first-class citizen. (Slack adapter exposes the same channel pair convention but ships outside the v1.0 SemVer promise.) | | v0.8.1 (released) | Security & Lifecycle Pair | npm audit 7 → 0 (discord.js 14.16 → 14.26 + undici 6.21 → 6.24 + overrides); solosquad import <zip> completes the v0.7 archive pair (dry-run + --merge/--replace + journal-idempotent resume); solosquad archive verify/info/list (yauzl-based); docs/policy/schema-stability.md 6 schema_version bump rules; SKILL.md schema_version: 1 backfill | | v0.8.2 (released) | Dev Capability | SKILL frontmatter dev_capability + dev_permissions (Bash allow/deny, network, push confirmation, merge.auto: false permanently forbidden); engineering 5 SKILLs (backend-developer / fde / api-developer / creative-frontend / qa-engineer) baked in true, others false; workspace master toggle; src/bot/dev-confirm.ts 30-min timeout gate; gh auth status doctor check | | v0.8.3 (released) | Onboarding UX + Observability | solosquad add repo --dry-run + 5-scenario risk detection (lsof / symlinks / abs-paths / slug collision / IDE files); 5-step legacy repo migration guide; solosquad logout removed (replaced by Ctrl+C + .env mask + REVOKE-CHECKLIST); structured logger + solosquad logs CLI (level / JSON / file / 14-day rolling); master-guide §3/§6/§8/§9/§10 re-aligned for v0.7+v0.8; doctor CLI↔workspace version mismatch advisor; trajectory ROI gate measurement placeholder | | v1.0.0 (released) | Formal launch | Stable API guarantees · 42 CLI surface freeze · docs/policy/schema-stability.md 공개 약속 발효 · Discord 단일 메신저 (Slack post-v1.0 슬롯) | | v1.0.1 – v1.0.4 (released) | Discord robustness patch chain | discord.js v15 deprecation · @<slug> mention · author-guard 정합 · guild-org binding · category rename · config.yaml load-or-empty + 5-hop diagnostic + Slack author-guard cleanup | | v1.1.0 (released) | Multi-Agent Team Architecture | Single PM session → Team-Centric. Chief (org-level supervisor, 사용자 대면) + PM (workspace-bundle, 자율 product manager) 분리. 4 main bot + 20 specialist + 18 skill + 4 team. 9-layer JIT (team OKR Layer 4a). Chief 6+1 stage state machine. open_questions[] async-batch protocol. Goal queue (1-active-per-org). 4 workflow templates. 외부 reference: Hermes V2 + gstack (Garry Tan) + RO-PNA pna-builders + phuryn pm-skills | | v1.2.6 (released) | Messenger Connection (Chief on Discord, auto-connect first) | 조직 1개당 1 Chief 봇 (OrgYaml.chief_name) · OAuth Invite URL 1-click (solosquad discord invite-url) · handle 기반 채널 멀티-메신저 portable · owner-only 게이트 (v1.0.2 reversal, default ON 신규 / OFF 업그레이드) · TRIAGE kind 분기 → works-<handle> task card + thread + stage narration · solosquad add-org 가 v1.1.0 위계 + problem-definition workflow 기본 시드까지 완전 부트스트랩 · solosquad doctor --discord 5-hop diagnostic · guildCreate onboarding embed + 2 button · /chat slash fallback. 53 신규 test (728/728 pass) | | v1.3.0 (released) | Messenger UX overhaul | dev-confirm push-approval 게이트 · 인터랙션 컴포넌트 · 🛑 stop 버튼 + 라이브 stage narration · 산출물 filing | | v1.3.1 (released) | Legacy asset cleanup | v1.1 리오그가 절반만 끝낸 구 assets/ 비우기 + CI/deps 하드닝 (사용자 대면 기능 0) | | v1.3.2 (released) | Asset lifecycle managers + asset adoption | 5개 1급 자산(skill·agent·workflow·goal·cron) 공통 매니저 추상(validate/list/show + 공유 graph·validation·guardrail·naming 코어) · agent 매니저 신설(validate --graph) · 에셋 채택 adopt <repo>(discover→validate→additive apply, init/add-repo 인터랙티브 오퍼) · 통합 입구 asset + 일람 commands · conversational-first(LLM 동사는 asset-review 스킬로) · skill-author→skill-manager. 872 test pass | | v1.2.1 (planned) | Messenger thread continuity | referencedMessage chain + LRU cache + thread token budget guard. messageCreate가 thread 메시지 수신 + thread→workflow_id reverse lookup. Slack adapter 동일 슬롯 | | v1.3 (planned) | Schedule + Memo | n-jobber time/memory management. Calendar integration · todo · notes | | v1.x (planned) | Dashboard interaction | Companion web dashboard (별도 리포 solopreneur-dashboard + solopreneur-api) | | v1.x (planned) | Knowledge ontology + MCP | Graph backend + MCP external connectors (Notion, Obsidian, etc.) | | v1.x (planned) | LLM backend abstraction | Multi-backend (single Claude → pluggable) |

Decision log: docs/roadmap.md §6.

Multi-Workspace

Want separate Discord personas (e.g., business vs personal)? Create multiple workspaces:

~/solopreneur/      # Discord bot, business persona
~/personal-lab/     # Discord bot, hobby persona

Each has independent .env, tokens, memory, and messenger account. They run side-by-side without interference. (Note: a single workspace is bound to one messenger — the v0.1.x MESSENGER=discord,slack multi-target syntax is no longer supported. v1.0 ships only the Discord adapter under the SemVer promise; the Slack adapter remains in the codebase but is a post-v1.0 slot.)

Repository Layout

Source tree (this repo):

package.json                      → npm package config (v1.2.6)
tsconfig.json                     → TypeScript config
bin/solosquad.ts                  → CLI entry point
AGENTS.md                         → canonical workspace guide (v0.4 — immutable, cross-tool)
CLAUDE.md                         → 3-line redirect to AGENTS.md (backward-compat)
src/
  cli/                            → CLI commands (init, bot, cron, doctor, doctor-discord,
                                     pm, workflow, goal, agent, analyze, add, sync, migrate,
                                     rollback, memory, readiness, discord)
  bot/                            → chief-runner, claude-process, session-store, events,
                                     agents-builder, workflow-reconciler, slash-commands,
                                     git-snapshot, skill-parser, agent-router,
                                     meta-skill-scanner, skill-author, author-budget,
                                     spawn-assembler (v0.6 8-layer JIT),
                                     agent-budget (v0.6 — author-budget generalized),
                                     fs-watcher + reload-policy (v0.6 hot-reload)
  engine/                         → v0.4 autonomous engine — goal-parser, agents-md-loader,
                                     guards, evaluator, tracker, reconciliation, goal-runner;
                                     stop-hook-adapter (v0.6 spec-gate DSL)
  memory/                         → v0.6 FTS5 archive — archive-db, archive-rotate,
                                     archive-search, route-event-sink
  analyze/                        → v0.5 repo analyzer — scanner, classifier, ledger,
                                     workflow-matcher, report-writer, applier
  messenger/                      → Discord adapter (v1.0). Slack adapter present but post-v1.0 slot
  scheduler/                      → Cron-based crons + memory append;
                                     trajectory-extractor + freq-keyword-miner (v0.6),
                                     v06-stats-extract (v0.6 retrospective ETL)
  util/                           → Config, paths, logger, platform, cost, agent-profile (v0.6)
  migrations/                     → Versioned workspace migration scripts (0.1.x → 0.6.0)
assets/                           → Bundled defaults (copied to user workspace on `solosquad init`)
  agents/{team}/{agent}/SKILL.md  → 25 specialist definitions (v0.5 frontmatter + v0.6
                                     collab_pattern)
  agents/{team}/KNOWLEDGE.md      → v0.6 — team(=domain) shared craft (moved from
                                     agents/_teams/{team}/TEAM_KNOWLEDGE.md, git mv)
  agents/_meta/workflow-maker/    → v0.5 author loop meta-skill + references
  knowledge/                      → v0.6 — bundled workspace knowledge starter
  core/                           → Owner profile, principles, voice (universal layer)
  routines/                       → Routine prompts (incl. v0.3 pm-compaction +
                                     v0.6 archive-rotate, v06-retrospective-stats)
  orchestrator/SKILL.md           → PM role definition (v0.3 + v0.4 goal-md-spec append)
  templates/                      → PRD / handoff (×3 variants) / status / goal.md /
                                     AGENTS.md / workflow.yaml / agent-profile.yaml /
                                     hooks.json / migration-redestination-report.md
deploy/
  docker/                         → Container deployment (Dockerfile + compose + README)
docs/
  manual/master-guide_{en,ko}.html → 📖 Canonical user manual (10 sections, EN + KO)
  roadmap.md                      → Master roadmap + decision log §4 (repo layer, living)
  architecture.md                 → Internal system design (repo layer, living)
  prd/                            → Per-release PRDs (repo layer) + INDEX.md
  reports/ · ideation/            → Product research/exploration (org layer) + INDEX.md
  manual/cloud-deployment.md        → VPS + systemd setup
  poc/                            → v0.3 PoC integration scripts (archive)
  reference/                      → Design vocabulary sources
  trend-record/                   → Peer-project comparisons
.github/workflows/                → CI + v0.6 skill-review.yml (PR diff frontmatter +
                                     keyword conflict + agent-profile schema lint)
scripts/                          → backfill-bundled-frontmatter,
                                     inject-collab-pattern (v0.6),
                                     skill-pr-review/ (v0.6 CI PR bot, 6 modules)

End-user workspace (created by solosquad init, evolved through migrations):

~/solosquad-workspace/
├── AGENTS.md                            (v0.4 — single persistent guide)
├── .solosquad/
│   ├── workspace.yaml                   (timezone, briefings, pm, skill_loader, author,
│   │                                       v0.6: spawn, fs_watch, archive)
│   ├── .env                             (messenger tokens, MESSENGER, …)
│   ├── agents/{team}/{agent}/SKILL.md   (v0.5 — bundled 25 + frontmatter + collab_pattern)
│   ├── agents/{team}/KNOWLEDGE.md       (v0.6 — team shared craft, co-located)
│   ├── agents/_meta/workflow-maker/     (v0.5 — author loop meta-skill)
│   ├── knowledge/                       (v0.6 — user-accumulated craft, decision frameworks)
│   └── routines/, core/                 (optional user overrides)
├── .agents/                             (v0.5 — optional workspace-wide SKILL override)
└── <org-slug>/
    ├── .org.yaml                        (schema_version: 1 — v0.6 forward-compat)
    ├── core/                            (v0.6 — org philosophy overrides workspace)
    │   ├── PRINCIPLES.md
    │   └── VOICE.md
    ├── agent-profile.yaml               (v0.6 — 25-agent modifier + budget cap, schema_version: 1)
    ├── domain/                          (v0.6 — org domain knowledge: market.md, customers.md, …)
    ├── .agents/                         (v0.5 — optional per-org SKILL override, highest priority)
    ├── memory/
    │   ├── signals.jsonl · experiments.jsonl · decisions.jsonl
    │   ├── author-costs.jsonl           (v0.5 — author loop cost log)
    │   ├── agent-costs.jsonl            (v0.6 — agent spawn cost log, separate namespace)
    │   ├── migration-costs.jsonl        (v0.6 — migration LLM fallback cost log)
    │   ├── spawn-decisions.jsonl        (v0.6 — 8-layer drop log, FTS5-indexed)
    │   ├── stop-hook-events.jsonl       (v0.6 — spec-gate evaluation log)
    │   ├── archive.sqlite               (v0.6 — FTS5 cold archive, 365d retention)
    │   ├── pm-skills/                   (v0.3 — PM compaction externalization)
    │   └── cron-logs/                   (hot tier — rotated into archive.sqlite after 8d)
    ├── workflows/<wf-id>/               (v0.3 — _status.yaml, _events.jsonl, stages)
    ├── goals/<goal-id>/                 (v0.4 — goal.md, results.tsv, _best.json, _last-run.md)
    ├── .solosquad/
    │   ├── sessions/<user>.json         (v0.3 PM session id + cost; v0.5 adds freqCooldowns)
    │   ├── snapshot.git                 (v0.3 — bare repo for memory/ + workflows/)
    │   ├── analysis/                    (v0.5 — analyze-repo Markdown reports)
    │   └── analysis-ledger.yaml         (v0.5 — incremental ledger, path + SHA256[:12])
    ├── repositories/<repo>/             (Layer 2 — user product code)
    ├── discord/                          (channel config — v1.0 default). slack/ available but post-v1.0 slot
    └── product/                         (per-org artifacts)

~/.solosquad/
├── agents/                              (v0.5 — user-global SKILL override across workspaces)
└── agent-profile-defaults.yaml          (v0.6 — user-global agent-profile defaults)

References (peer-project inspirations)

| Project | Adopted pattern | |---|---| | Anthropic Effective Harnesses | initializer + coding agent split; context compaction; subagent spawning | | gstack | slash chain protocol — direct source for v0.3 /think /plan /build /review /ship | | Hermes Agent | hot+cold FTS5 memory archive, trajectory → skill auto-summary (adopted in v0.6) | | autoresearch | metric gate + git keep/rollback loop (adopted in v0.4) | | phuryn/pm-skills | auto-load + slash dual-trigger SKILL routing (adopted in v0.5 4-channel router) | | OpenClaw | npm publishing + update / doctor CLI patterns |

Explicitly rejected as over-engineered for solo founders: 3-repo physical splits, LangGraph v3 graph orchestration, MCP-based internal skill registries, Vector + Graph DB hybrids. See docs/roadmap.md §4 for the reasoning.

Contributing

Active solo development. Issues and pull requests welcome, but the API is unstable until v1.0. See CONTRIBUTING.md.

License

MIT — see LICENSE.