swain-help
Contextual help for the swain skill ecosystem.
Mode detection
Determine the mode from context:
| Signal | Mode |
|---|---|
| Invoked from swain-init Phase 4, or user says "just set up swain" / "what now after init" | Onboarding |
| User asks a specific question ("how do I...", "what is...", "when should I...") | Question |
| User asks for a reference, cheat sheet, commands, or overview | Reference |
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./swainis 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/swainto create a spec. Swain enforces a "plan before code" workflow — it creates tracked tasks before implementation begins. 3. Health checks are automatic./swain-doctorruns 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 withtype: bug- "Let's release" → version bump + changelog Need more? Ask me anything about swain, or say/swain help referencefor 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:
| Topic | Where to look |
|---|---|
| Artifact types, phases, relationships | references/quick-ref.md — Artifacts section |
| Commands and invocations | references/quick-ref.md — Commands section |
| Step-by-step walkthroughs | references/workflows.md |
| Artifact definitions and templates | sibling skill swain-design/references/<type>-definition.md |
| tk (ticket) CLI reference | sibling skill swain-do/references/tk-cheatsheet.md |
| Troubleshooting | sibling skill swain-design/references/troubleshooting.md |
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.
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.