architecture-reference

Evidence-based architecture guidance grounded in 142 production codebases and 17 production system case studies. Reviews project goals, examines the user's codebase, and provides data-driven recommendations for architecture style selection, quality attribute trade-offs, and pattern validation. Use when the user asks "which architecture should I use", "is my architecture right for this", "architecture review", "help me choose between X and Y", "what patterns work for my domain", "architecture trade-offs", "validate my architecture", or any question about choosing, evaluating, or improving software architecture. Also triggers on "architecture patterns", "quality attributes", "ADR examples", "feasibility analysis", "fitness functions", or "kata preparation".

Create, validate, and transition documentation artifacts (Vision, Epic, Story, Spec, Spike, ADR, Persona, Runbook, Bug, Design, Journey) through lifecycle phases. Handles spec writing, feature planning, epic creation, user stories, ADR drafting, research spikes, persona definition, runbook creation, bug filing, design capture, architecture docs, phase transitions, implementation planning, cross-reference validation, and audits. Chains into swain-do for implementation tracking on SPEC/STORY/BUG; decomposes EPIC/VISION/JOURNEY into children first.

Bootstrap, install, and operate an external task-management CLI as the source of truth for agent execution tracking (instead of built-in todos). Provides the abstraction layer between swain-design intent (implementation plans and tasks) and concrete CLI commands. MUST be invoked when any implementation-tier artifact (SPEC, STORY, BUG) comes up for implementation — create a tracked plan before writing code. Optional but recommended for complex SPIKEs. For coordination-tier artifacts (EPIC, VISION, JOURNEY), swain-design must decompose into implementable children first — this skill tracks the children, not the container. Also use for standalone tasks that require backend portability, persistent progress across agent runtimes, or external supervision. Use this skill whenever the user asks to track tasks, create an implementation plan, check what to work on next, see task status, manage dependencies between work items, or close/abandon tasks — even if they don't mention "execution tracking" explicitly.

ALWAYS invoke this skill at the START of every session before doing any other work. Validates project health: governance rules, tool availability, memory directory, settings files, script permissions, .agents directory, and .beads/.gitignore hygiene. Remediates issues across all swain skills. Idempotent — safe to run every session.

Contextual help and onboarding for the swain skill ecosystem. Use when users ask about swain — what skills exist, how to use them, what artifacts are available, how workflows connect, or when they need a quick reference. Also invoked after swain-init to orient new users. Triggers on: 'how do I...', 'what is...', 'help', 'what can swain do', 'show me the commands', 'I'm confused', 'where do I start', any question about swain skills, artifacts, or workflows, and after project onboarding completes.

One-time project onboarding for swain. Migrates existing CLAUDE.md content to AGENTS.md (with the @AGENTS.md include pattern), installs and initializes bd (beads) for task tracking, cleans bd's auto-injected AGENTS.md content, and offers to add swain governance rules. Run once when adopting swain in a new project — use swain-doctor for ongoing per-session health checks.

Tmux workspace manager — creates layout presets (review, browse, focus), opens editor/browser/shell panes, runs an animated MOTD status panel, and lets the agent directly manage panes during work. Only activates in tmux sessions.

Cross-cutting project status dashboard. Shows active epics with progress ratios, actionable next steps, blocked items, in-progress tasks, GitHub issues, and session context. Produces rich terminal output with clickable links. Triggers on: 'status', 'progress', 'what's next', 'dashboard', 'overview', 'where are we', 'what should I work on'.

Update swain skills to the latest version. Use when the user says 'update swain', 'upgrade swain', 'pull latest swain', or wants to refresh their swain skills installation. Runs the skills package manager (npx) with a git-clone fallback, then invokes swain-doctor to reconcile governance and validate project health.

Compare a codebase's architecture against the evidence catalog of 200+ real-world projects. Finds similar projects by style, domain, scope, and quality attributes; generates a markdown comparison report with statistical context, strengths/gaps analysis, and evidence-grounded recommendations. Use when the user says "compare my architecture", "how does this compare", "find similar projects", "architecture comparison", "benchmark my architecture", or "what projects look like mine".

Analyze a codebase to discover its architecture style(s) through direct source code inspection. Reads actual code structure, dependency graphs, module boundaries, and runtime patterns — no heuristics or filesystem signal counting. Produces a classification report with evidence citations. Use when the user says "what architecture is this", "analyze this repo", "discover architecture", "classify this codebase", "what patterns does this use", or points you at a repo and asks about its structure. Also triggers on "architecture review", "codebase analysis", or "how is this system structured".