Windsurf rules

1---
2name: craft-skill
3model: sonnet
4description: "Create new bigpowers skills with proper structure, progressive disclosure, and bundled resources. Use when user wants to create, write, or build a new skill for the bigpowers lifecycle."
5---
6 
7# Craft Skill
8 
9> **HARD GATE** — Do NOT name a skill without a two-word verb-noun pair. Do NOT merge a new skill without running `sync-skills.sh`. Generated `.cursor/rules/` and `.gemini/` artifacts MUST match the source SKILL.md.
10 
11## CSO Description Discipline (e45s02)
12 
13The YAML `description` is the **Catalog Selection Object** — the only field agents see when picking a skill.
14 
15| Rule | Limit |
16|------|-------|
17| Max length | 1024 characters |
18| Voice | Third person |
19| Content | Capability + `Use when …` triggers only |
20| Forbidden | Workflow steps, phase chains, numbered lists, `→ verify:`, HARD GATE prose |
21 
22Move process detail into the SKILL.md body or REFERENCE.md — never into `description`.
23 
24## Agentic STE body discipline (e79s02)
25 
26Skill-body instructional prose MUST follow [AGENTIC-STE.md](../../docs/AGENTIC-STE.md).
27 
28| Rule | Limit |
29|------|-------|
30| Sentence length | ≤20 words per instruction sentence |
31| Voice | Imperative, active |
32| Directive terms | MUST, MUST NOT, NEVER, ALWAYS, DO, DO NOT |
33| Banned modals | should, might, could, may, consider, try, generally, typically |
34| Scope | SKILL.md body only — not YAML `description`, not `terse-mode` output |
35 
36> **HARD GATE** — Do NOT merge a new or edited skill until `bash scripts/validate-agentic-ste.sh --strict skills/<name>/SKILL.md` exits 0. Fix violations before `sync-skills.sh`.
37 
38## Process
39 
401. **Gather requirements** — ask user about:
41   - What task/domain does the skill cover?
42   - Which use cases must the skill handle?
43   - Does it need executable scripts or just instructions?
44   - Any reference materials to include?
45   - What specs/ output does it produce (if any)?
46 
472. **Verify Principles** — Ensure the skill aligns with [PRINCIPLES.md](../../docs/PRINCIPLES.md):
48   - Is it atomic (verb-noun)?
49   - Is it "deep" (simple interface, complex internal logic)?
50   - Does it include Hard Gates?
51   - Is it verifiable with a `.feature` file?
52 
533. **Draft the skill** — create:
54   - SKILL.md with concise instructions (see [REFERENCE.md](REFERENCE.md) for template)
55   - Additional reference files if content exceeds 100 lines
56   - Utility scripts if deterministic operations needed
57 
58   **Auto-skill from library README:** When user provides a library README or API docs URL, extract triggers and HARD GATEs.
59   Draft verify commands and specs/ output into SKILL.md. Do NOT invent APIs not in the source.
60 
614. Add `model:` frontmatter (`haiku` | `sonnet` | `opus`) per [model-profiles.md](../../docs/references/model-profiles.md).
62 
63> **STREAM CONTINUITY** — When writing file content, output in continuous chunks of ~200 lines. Do not pause. Continue immediately until complete. If you need time, emit a placeholder comment rather than going silent.
64 
655. **Review with user** — present draft and ask:
66   - Does this cover your use cases?
67   - Anything missing or unclear?
68   - Does any section need more or less detail?
69 
706. **Completion-honesty gate (HARD GATE — e45s02)** — Before declaring done:
71   - Run `bash scripts/validate-skill-description.sh skills/<name>/SKILL.md` — must exit 0
72   - Run `bash scripts/validate-agentic-ste.sh --strict skills/<name>/SKILL.md` — must exit 0 (e79s02)
73   - Run `bash scripts/sync-skills.sh` — must complete without error
74   - Run `bash scripts/run-skill-verify.sh <name>` if the skill defines a verify command
75   - Show terminal output for each — narration without evidence is rejected
76 
77## Naming Rules
78 
79Every skill name must be a **two-word verb-noun pair**. See [REFERENCE.md](REFERENCE.md) for full rules, examples, and documented exceptions.
80 
81## specs/ Output
82 
83If the skill produces written output, it goes in `specs/` at the project root. Document the output file path in the skill body and in CONVENTIONS.md's output files table.
84 
85## Review Checklist
86 
87After drafting, verify:
88 
89- [ ] Name is a two-word verb-noun pair (or follows grill-me exception)
90- [ ] Description < 1024 chars, triggers only, no workflow-summary leakage
91- [ ] Description includes triggers ("Use when...")
92- [ ] SKILL.md under 100 lines
93- [ ] No time-sensitive info
94- [ ] Consistent terminology with CONVENTIONS.md
95- [ ] specs/ output documented if applicable
96- [ ] `validate-skill-description.sh` exits 0
97- [ ] `validate-agentic-ste.sh --strict` exits 0 (e79s02)
98- [ ] `sync-skills.sh` run to propagate to Cursor/Gemini
99- [ ] `bash scripts/validate-skill-catalog.sh` passes for the new skill (HARD GATE — completion honesty)
100 
101> **HARD GATE** — Do NOT declare the skill done until `bash scripts/validate-skill-catalog.sh --strict --skill <name>` exits 0. Validator enforces verb-noun name, HARD GATE block, description ≤1024 chars, and `→ verify:` command.
102 
103## Verify
104 
105→ verify: `bash scripts/validate-skill-catalog.sh --strict --skill craft-skill && bash scripts/validate-skill-description.sh skills/craft-skill/SKILL.md`
106 
107---
108 
109# Craft Skill — Reference
110 
111## Naming Rules (full)
112 
113Every skill name must be a **two-word verb-noun pair**:
114- First word: a verb (survey, model, define, develop, audit…)
115- Second word: a noun from PMBOK 6 / Agile vocabulary (context, domain, language, tdd, code…)
116- Pronounceable in any language, searchable, no noise words, no encodings
117- Exception precedent: `grill-me` — kept for recognizability
118 
119Good: `survey-context`, `audit-code`, `validate-fix`
120Bad: `context-surveyor`, `code-auditing-skill`, `fix-validator`
121 
122Any new naming exception requires an entry in CONVENTIONS.md before the skill is published.
123 
124## Skill Structure
125 
126```
127skill-name/
128├── SKILL.md           # Main instructions (required)
129├── REFERENCE.md       # Detailed docs (if needed)
130├── EXAMPLES.md        # Usage examples (if needed)
131└── scripts/           # Utility scripts (if needed)
132    └── helper.sh
133```
134 
135## SKILL.md Template
136 
137```md
138---
139name: skill-name
140description: Brief description of capability. Use when [specific triggers].
141---
142 
143# Skill Name
144 
145## Quick start
146 
147[Minimal working example]
148 
149## Workflows
150 
151[Step-by-step processes with checklists for complex tasks]
152 
153## Advanced features
154 
155[Link to separate files: See [REFERENCE.md](REFERENCE.md)]
156```
157 
158## Description Requirements
159 
160The description is **the only thing your agent sees** when deciding which skill to load.
161 
162**Format**:
163- Max 1024 chars
164- Write in third person
165- First sentence: what it does
166- Second sentence: "Use when [specific triggers]"
167 
168**Good example**:
169```
170Investigate a bug by exploring the codebase to find root cause, then write a TDD-based fix plan to specs/bugs/BUG-*.md. Use when user reports a bug, wants to investigate a problem, or mentions "triage".
171```
172 
173## When to Add Scripts
174 
175Add utility scripts when:
176- Operation is deterministic (validation, formatting)
177- Same code would be generated repeatedly
178- Errors need explicit handling
179 
180## When to Split Files
181 
182Split into separate files when:
183- SKILL.md exceeds 100 lines
184- Content has distinct domains
185- Advanced features are rarely needed
186 
187## sync-skills.sh Propagation
188 
189After adding a new skill directory with SKILL.md, run `scripts/sync-skills.sh` from the bigpowers repo root. This automatically generates:
190- `.cursor/rules/<name>.mdc` — for Cursor
191- `.gemini/extensions/bigpowers/skills/<name>/SKILL.md` — Agent Skill
192- `.gemini/extensions/bigpowers/commands/<name>.toml` — Slash Command
193- `.gemini/extensions/bigpowers/commands/prompts/<name>.md` — Command Prompt
194- Updated `gemini-extension.json`
195 
196verify: `bash scripts/sync-skills.sh 2>&1 | grep "skills synced"`
197