Swain Design

This is a comprehensive documentation lifecycle manager for engineering teams that want structured artifact tracking. It handles eleven artifact types from high-level Vision documents down to Specs, ADRs, Runbooks, and Training docs, each with defined phases and templates. The hierarchy is Vision → Initiative → Epic → Spec, with strict parent-child validation and priority cascading. It enforces session checks before state changes, syncs with repository AGENTS.md files, and chains into swain-do for implementation tracking. The skill includes detailed reference files for each artifact type with lifecycle definitions and frontmatter templates. If you're running a serious agent-driven workflow and need more than a flat task list, this gives you the scaffolding. Opinionated but thorough.

skills.sh installs: 125
GitHub stars: 2
last updated: Aug 21, 2026

View on GitHub

Install

$ npx -y skills add cristoslc/swain --skill swain-design --agent claude-code

Installs into .claude/skills of the current project.

Files

Spec Management

Before proceeding with any state-changing operation, check for an active session:

REPO_ROOT="$(git rev-parse --show-toplevel 2>/dev/null || pwd)" && bash "$REPO_ROOT/.agents/bin/swain-session-check.sh" 2>/dev/null

If the JSON output has "status" other than "active", inform the operator: "No active session — start one with /swain-init?" Proceed if they dismiss.

This skill defines the canonical artifact types, phases, and hierarchy. Detailed definitions and templates live in references/ (relative to this skill's directory). If the host repo has an AGENTS.md, keep its artifact sections in sync with the skill's reference data.

Artifact type definitions

Each artifact type has a definition file (lifecycle phases, conventions, folder structure) and a template (frontmatter fields, document skeleton). Read the definition for the artifact type you are creating or transitioning.

SKILL.md on GitHub