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, stories, ADRs, etc.) and tracks implementation work — so nothing falls through the cracks between sessions.
Three things to know:
/swain is your entry point. It routes to the right sub-skill automatically. You can also call skills directly (/swain-design, /swain-do, etc.).
Design before you build. When you want to implement something, start with /swain to create a spec or story. Swain enforces a "plan before code" workflow — it creates tracked tasks before implementation begins.
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 Story
- "Write a spec for X" → creates an Agent Spec
- "What should I work on next?" → checks your task backlog
- "File a bug" → creates a Bug artifact
- "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:
| Topic |
Where to look |
| Artifact types, phases, relationships |
skills/swain-help/references/quick-ref.md — Artifacts section |
| Commands and invocations |
skills/swain-help/references/quick-ref.md — Commands section |
| Step-by-step walkthroughs |
skills/swain-help/references/workflows.md |
| Artifact definitions and templates |
skills/swain-design/references/<type>-definition.md |
| tk (ticket) CLI reference |
skills/swain-do/references/tk-cheatsheet.md |
| Troubleshooting |
skills/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 skills/swain-help/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 skills/swain-help/references/workflows.md.
1---2name: swain-help3description: 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.4license: MIT5---67<!-- swain-model-hint: sonnet, effort: medium — default for conceptual explanations; see per-section overrides below -->89# swain-help1011Contextual help for the swain skill ecosystem.1213## Mode detection1415Determine the mode from context:1617| Signal | Mode |18|--------|------|19| Invoked from swain-init Phase 4, or user says "just set up swain" / "what now after init" | **Onboarding** |20| User asks a specific question ("how do I...", "what is...", "when should I...") | **Question** |21| User asks for a reference, cheat sheet, commands, or overview | **Reference** |2223## Onboarding mode2425Present a concise orientation — help the user understand what they just installed without overwhelming them. Adapt tone to context (first-time dev vs experienced engineer).2627Present this:2829> **Welcome to swain.** Here's how it works:30>31> **The big picture:** Swain manages your project's documentation artifacts (specs, stories, ADRs, etc.) and tracks implementation work — so nothing falls through the cracks between sessions.32>33> **Three things to know:**34>35> 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.).36>37> 2. **Design before you build.** When you want to implement something, start with `/swain` to create a spec or story. Swain enforces a "plan before code" workflow — it creates tracked tasks before implementation begins.38>39> 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.40>41> **Common starting points:**42> - "I want to plan a new feature" → creates an Epic or Story43> - "Write a spec for X" → creates an Agent Spec44> - "What should I work on next?" → checks your task backlog45> - "File a bug" → creates a Bug artifact46> - "Let's release" → version bump + changelog47>48> **Need more?** Ask me anything about swain, or say `/swain help reference` for a full cheat sheet.4950Then stop. Let the user ask follow-up questions — don't dump everything at once.5152## Question mode5354Answer the user's specific question using your knowledge of swain. If you need details beyond what's in this skill, read the relevant reference:5556| Topic | Where to look |57|-------|---------------|58| Artifact types, phases, relationships | `skills/swain-help/references/quick-ref.md` — Artifacts section |59| Commands and invocations | `skills/swain-help/references/quick-ref.md` — Commands section |60| Step-by-step walkthroughs | `skills/swain-help/references/workflows.md` |61| Artifact definitions and templates | `skills/swain-design/references/<type>-definition.md` |62| tk (ticket) CLI reference | `skills/swain-do/references/tk-cheatsheet.md` |63| Troubleshooting | `skills/swain-design/references/troubleshooting.md` |6465Guidelines for answering:6667- **Be concise.** Answer the question, don't dump the entire reference.68- **Use examples** when they clarify — "You'd say `/swain create a spec for auth token rotation`".69- **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."70- **Admit gaps.** If something isn't covered, say so rather than inventing swain features.7172<!-- swain-model-hint: haiku, effort: low — reference lookups are simple file reads -->73## Reference mode7475When the user wants an overview or cheat sheet, read `skills/swain-help/references/quick-ref.md` and present the relevant section. If they want "everything", present the full quick reference but note it's dense.7677For workflow walkthroughs, read `skills/swain-help/references/workflows.md`.
cristoslc