Swain Help

<!-- swain-model-hint: sonnet, effort: medium — default for conceptual explanations; see per-section overrides below -->

swain-help

Contextual help for the swain skill ecosystem.

Mode detection

Determine the mode from context:

Onboarding mode

Present a concise orientation — help the user understand what they just installed without overwhelming them. Adapt tone to context (first-time dev vs experienced engineer).

Present this:

Welcome to swain. Here's how it works:

>

The big picture: Swain manages your project's documentation artifacts (specs, epics, ADRs, etc.) and tracks implementation work — so nothing falls through the cracks between sessions.

>

Three things to know:

>

1. `/swain` is your entry point. It routes to the right sub-skill automatically. You can also call skills directly (/swain-design, /swain-do, etc.).

>

2. Design before you build. When you want to implement something, start with /swain to create a spec. Swain enforces a "plan before code" workflow — it creates tracked tasks before implementation begins.

>

3. Health checks are automatic. /swain-doctor runs at session start to ensure routing rules are in place and .tickets/ is healthy. You don't need to think about it.

>

Common starting points:

- "I want to plan a new feature" → creates an Epic or Spec

- "Write a spec for X" → creates an Agent Spec

- "What should I work on next?" → checks your task backlog

- "File a bug" → creates a Spec with type: bug

- "Let's release" → version bump + changelog

>

Need more? Ask me anything about swain, or say /swain help reference for a full cheat sheet.

Then stop. Let the user ask follow-up questions — don't dump everything at once.

Question mode

Answer the user's specific question using your knowledge of swain. If you need details beyond what's in this skill, read the relevant reference:

Guidelines for answering:

• Be concise. Answer the question, don't dump the entire reference.
• Use examples when they clarify — "You'd say /swain create a spec for auth token rotation".
• Hand off when appropriate. If the user's question is really a request to do something (e.g., "how do I create a spec?" followed by "ok do it"), invoke the relevant skill directly via the Skill tool. Explain what you're doing: "I'll hand this off to swain-design."
• Admit gaps. If something isn't covered, say so rather than inventing swain features.

<!-- swain-model-hint: haiku, effort: low — reference lookups are simple file reads -->

Reference mode

When the user wants an overview or cheat sheet, read references/quick-ref.md and present the relevant section. If they want "everything", present the full quick reference but note it's dense.

For workflow walkthroughs, read references/workflows.md.

Swain Quick Reference

Skills at a Glance

Artifacts

Swain manages 10 artifact types, organized into three lifecycle tracks.

Implementable track (tracked via tk)

These require a tracked plan (via swain-do) before implementation begins.

Container track (children are tracked)

Standing track (no tracking)

Artifact relationships

• Vision → decomposes into Initiatives, Epics, and Journeys
• Initiative → groups related Epics (and optionally Specs) under a Vision
• Epic → decomposes into Specs, Spikes
• Spec → may reference ADRs, Personas, Designs
• Spike → attaches to any artifact, may produce ADRs
• Any artifact can declare depends-on: blocking dependencies

When to use which

• Initiative vs Epic: Initiative = strategic direction with multiple deliverables ("harden security"). Epic = single deliverable with multiple specs ("build scanning tool"). If it needs 2+ epics, it's an Initiative.
• Spec under Initiative: Small work (bugs, enhancements) can attach directly to an Initiative without an Epic wrapper. If it clusters, promote to an Epic.
• Spec under Epic vs standalone Spec: Use parent-epic when the spec is part of a planned deliverable. Standalone specs are for one-off fixes.

Commands

Creating artifacts

/swain create a vision for X
/swain write a spec for Y
/swain file a bug about Z
/swain plan an epic for W
/swain create an ADR for this decision
/swain create a runbook for deployment

Managing lifecycle

/swain move SPEC-001 to Ready
/swain transition SPEC-003 to Complete
/swain abandon SPIKE-002

Task tracking

/swain what should I work on next?
/swain show my tasks
/swain create a plan for SPEC-001

Validation and auditing

/swain check for stale references
/swain show the dependency graph
/swain validate ADRs

Releasing and committing

/swain sync
/swain release
/swain bump version

Key Concepts

The "plan before code" rule

When a SPEC comes up for implementation, swain requires a tracked plan (via tk) before code is written. This ensures work is visible and manageable across sessions. Swain-design enforces this automatically — when you transition an artifact to its implementation phase, it triggers swain-do to create the plan.

tk (ticket)

The vendored, git-backed task tracker swain uses. Verified by swain-init, operated by swain-do. Key commands:

Governance block

The <!-- swain governance --> block in AGENTS.md contains routing rules that make swain skills discoverable. Managed automatically by swain-doctor. Don't edit it manually — customize anything outside the markers.

The @AGENTS.md pattern

CLAUDE.md contains just @AGENTS.md, which includes the full AGENTS.md file. This lets one file serve Claude Code, GitHub, Cursor, and other tools that read AGENTS.md natively.

Project Structure

<project>/
├── CLAUDE.md              # Contains: @AGENTS.md
├── AGENTS.md              # Project instructions + governance block
├── .tickets/              # tk database (git-tracked)
├── .agents/               # Swain config and logs
└── docs/
    ├── vision/            # VISION artifacts
    ├── initiative/        # INITIATIVE artifacts
    ├── epic/              # EPIC artifacts
    ├── spec/              # SPEC artifacts
    ├── spike/             # SPIKE artifacts
    ├── adr/               # ADR artifacts
    ├── persona/           # PERSONA artifacts
    ├── runbook/           # RUNBOOK artifacts
    ├── design/            # DESIGN artifacts
    ├── journey/           # JOURNEY artifacts
    └── list-*.md          # Lifecycle indexes per type

Common Workflows

New feature (end-to-end)

1. Define scope: /swain create an epic for user authentication

• Swain-design creates EPIC-NNN with scope, success criteria, and acceptance tests

2. Decompose: /swain create a spec for JWT token handling (reference the epic)

• Creates SPEC-NNN linked to the epic

3. Plan implementation: When the spec reaches Ready, swain-design triggers swain-do to create a tracked plan with tasks

4. Work the plan: /swain what should I work on?

• Swain-do shows the next ready task (blocker-aware)
• Claim it, do the work, mark complete

5. Commit: /swain sync

6. Release: /swain release when the epic is complete

Bug fix

1. File the bug: /swain file a bug: login fails when password contains special characters

• Creates a SPEC with type: bug, including reproduction steps, severity, and expected vs. actual behavior

2. Plan the fix: Swain creates tracked tasks before code changes begin

3. Fix and verify: Work the tasks, mark resolved, verify

4. Commit: /swain sync

Research spike

1. Create the spike: /swain create a spike to evaluate WebSocket vs SSE for real-time updates

• Time-boxed investigation with clear questions to answer

2. Do the research: Spike moves to Active

3. Record findings: Complete the spike with conclusions

• May produce an ADR if an architectural decision was made

Checking project status

1. Get the dashboard: /swain-session or just ask "what's next?" / "where are we?"

• Shows active epics with progress ratios (e.g., 3/5 specs complete)
• Surfaces blocked items, in-progress tasks, and GitHub issues
• Provides a ranked recommendation for what to work on next

2. Drill into specifics: Follow up on anything in the dashboard

• "Tell me more about EPIC-003"
• "What's blocking SPEC-012?"

3. Act on the recommendation: The dashboard points you to the highest-leverage next step

Starting a new session

1. Health check: /swain-doctor runs automatically (or invoke manually)

2. Context restore: /swain-session runs automatically — restores your last context bookmark

3. See what's in progress: /swain-session or tk ready

4. Pick up work: Follow the dashboard's recommendation or ask /swain what should I work on?

Adopting swain in an existing project

1. Run init: /swain init

• Migrates CLAUDE.md, verifies tk, adds governance rules

2. Orientation: Swain-help walks you through what's available

3. Start creating artifacts: /swain create a vision for this project

Artifact lifecycle walkthrough

A typical implementation-tier artifact (Spec) goes through:

1. Proposed — artifact lands in docs/spec/Proposed/ 2. Ready — transition when scope, acceptance criteria, and dependencies are confirmed 3. In Progress — swain-do creates tracked tasks; implementation begins 4. Needs Manual Test — all tasks complete; populate the Verification table with evidence 5. Complete — artifact moves to docs/spec/Complete/ after all criteria pass 6. Validate — specwatch checks for stale refs; adr-check validates compliance