--- name: swain-config description: "ALWAYS invoke this skill at the START of every session before doing any other work. This skill ensures the host project has agent governance rules (skill routing, pre-implementation protocol, issue tracking conventions) installed in its context file. It is idempotent — if rules are already present, it exits silently. Without this skill running first, other swain skills (swain-design, swain-do, swain-release) will not be routable." license: MIT allowed-tools: Bash, Read, Write, Edit, Grep, Glob metadata: short-description: Agent routing and swain configuration rules version: 1.1.0 author: cristos --- # Governance Ensure the host project's agent context file contains the swain governance rules. This skill is idempotent — run it every session; it only writes on first use. ## Session-start check 1. Detect the agent platform and locate the context file: | Platform | Context file | Detection | |----------|-------------|-----------| | Claude Code | `CLAUDE.md` (project root) | Default — use if no other platform detected | | Cursor | `.cursor/rules/swain-governance.mdc` | `.cursor/` directory exists | 2. Check whether governance rules are already present: ```bash grep -l "swain governance" CLAUDE.md AGENTS.md .cursor/rules/swain-governance.mdc 2>/dev/null ``` If any file matches, governance is already installed. Proceed to [Legacy cleanup](#legacy-cleanup), then stop. 3. If no match, run [Legacy cleanup](#legacy-cleanup), then proceed to [First-use setup](#first-use-setup). ## Legacy cleanup Remove pre-rename skill directories that are superseded by the current `swain-*` names. Check for each of these in `.claude/skills/` and delete any that exist: ```bash rm -rf .claude/skills/governance .claude/skills/spec-management .claude/skills/execution-tracking .claude/skills/release 2>/dev/null ``` Only delete a legacy directory if its `swain-*` replacement is already present — if somehow only the old names exist, leave them alone (the update likely didn't complete). Next, check whether the governance block in the context file references old skill names (`spec-management`, `execution-tracking`). If it does, delete the entire block between `` and `` (inclusive) and re-inject via [First-use setup](#first-use-setup) so the block picks up the current names. This is safe because the block is machine-managed — user customizations live outside the markers. ## First-use setup When governance rules are not found, inject them into the appropriate context file. ### Claude Code Determine the target file for governance injection: 1. If `CLAUDE.md` exists and its content is just `@AGENTS.md` (the include pattern set up by swain-init), inject into `AGENTS.md` instead. 2. Otherwise, inject into `CLAUDE.md` (create it if it doesn't exist). Append the following block to the target file: ```markdown ## Skill routing When the user wants to create, plan, write, update, transition, or review any documentation artifact (Vision, Journey, Epic, Story, Agent Spec, Spike, ADR, Persona, Runbook, Bug) or their supporting docs (architecture overviews, competitive analyses, journey maps), **always invoke the swain-design skill**. This includes requests like "write a spec", "let's plan the next feature", "create an ADR for this decision", "move the spike to Active", "add a user story", "create a runbook", "file a bug", or "update the architecture overview." The skill contains the artifact types, lifecycle phases, folder structure conventions, relationship rules, and validation procedures — do not improvise artifact creation outside the skill. **For all task tracking and execution progress**, use the **swain-do** skill instead of any built-in todo or task system. This applies whether tasks originate from swain-design (implementation plans) or from standalone work. The swain-do skill bootstraps and operates the external task backend — it will install the CLI if missing, manage fallback if installation fails, and translate abstract operations (create plan, add task, set dependency) into concrete commands. Do not use built-in agent todos when this skill is available. ## Pre-implementation protocol (MANDATORY) Implementation of any SPEC artifact (Epic, Story, Agent Spec, Spike) requires a swain-do plan **before** writing code. Invoke the swain-design skill — it enforces the full workflow. ## Issue Tracking This project uses **bd (beads)** for all issue tracking. Do NOT use markdown TODOs or task lists. Invoke the **swain-do** skill for all bd operations — it provides the full command reference and workflow. ``` ### Cursor Write the governance rules to `.cursor/rules/swain-governance.mdc`. Create the directory if needed. ```markdown --- description: "swain governance — skill routing, pre-implementation protocol, issue tracking" globs: alwaysApply: true --- ## Skill routing When the user wants to create, plan, write, update, transition, or review any documentation artifact (Vision, Journey, Epic, Story, Agent Spec, Spike, ADR, Persona, Runbook, Bug) or their supporting docs (architecture overviews, competitive analyses, journey maps), **always invoke the swain-design skill**. This includes requests like "write a spec", "let's plan the next feature", "create an ADR for this decision", "move the spike to Active", "add a user story", "create a runbook", "file a bug", or "update the architecture overview." The skill contains the artifact types, lifecycle phases, folder structure conventions, relationship rules, and validation procedures — do not improvise artifact creation outside the skill. **For all task tracking and execution progress**, use the **swain-do** skill instead of any built-in todo or task system. This applies whether tasks originate from swain-design (implementation plans) or from standalone work. The swain-do skill bootstraps and operates the external task backend — it will install the CLI if missing, manage fallback if installation fails, and translate abstract operations (create plan, add task, set dependency) into concrete commands. Do not use built-in agent todos when this skill is available. ## Pre-implementation protocol (MANDATORY) Implementation of any SPEC artifact (Epic, Story, Agent Spec, Spike) requires a swain-do plan **before** writing code. Invoke the swain-design skill — it enforces the full workflow. ## Issue Tracking This project uses **bd (beads)** for all issue tracking. Do NOT use markdown TODOs or task lists. Invoke the **swain-do** skill for all bd operations — it provides the full command reference and workflow. ``` ### After injection Tell the user: > Governance rules installed in ``. These rules ensure swain-design, swain-do, and swain-release skills are routable. You can customize the rules — just keep the `` markers so this skill can detect them on future sessions. ## Governance content reference The canonical governance rules are embedded in the [First-use setup](#first-use-setup) section above. If the upstream rules change in a future swain release, update the embedded blocks and bump the skill version. Consumers who want the updated rules can delete the `` block from their context file and re-run this skill.