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 20+ · Claude Code as the AI engine · file-based memory (JSONL)

v2 (개발 중 · 미배포) — The npm package solosquad stays at v1.4.3 (TypeScript), and everything in this README describes v1.4.3. The v2 engine is being developed in python/ (Python 3.12 · uv) — unreleased, not in the npm package, available only from a repository clone + uv. Goals: docs/roadmap.md §2.6 · setup: python/README.md.

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 nine menu-divided sections:

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, Node >=20 — see master-guide §4.2 for Windows/Linux
npm install -g @anthropic-ai/claude-code

# 2. Prepare the Discord bot BEFORE init — master-guide §5.1 (3–5 min, browser)
#    Create an Application → Reset Token → Message Content Intent ON
#    → copy the Application ID → copy your own User ID (Developer Mode)
#    init auto-detects the last two; have them ready for when it can't.

# 3. 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)

# 4. 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) and must happen before init — follow master-guide §5.1 step-by-step, then §4.2 for the wizard and §5.2 for the invite.

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

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

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

# Workspace ops (v0.1+)
solosquad init                                    # workspace setup wizard
solosquad bot                                     # start messenger bot
solosquad start                                   # v1.4.1 — bot + cron scheduler + supervisor together (single-host all-in-one)
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:

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.4.3 (npm registry: 1.4.3). v2 is in development in python/ and not published (see the note at the top).

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

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
tsconfig.json                     → TypeScript config
bin/solosquad.ts                  → CLI entry point
python/                           → v2 engine (unreleased, not in npm package)
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 (9 sections, EN + KO)
  roadmap.md                      → Master roadmap + decision log §6 (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)

Explicitly rejected as over-engineered for solo founders: 3-repo physical splits, LangGraph v3 graph orchestration (v1 기준 — v2 는 결정 19 로 swarm · LangGraph 모방 채택), MCP-based internal skill registries, Vector + Graph DB hybrids. See docs/roadmap.md §6 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.