Windsurf rules

1---
2name: write-document
3model: sonnet
4description: "Write, organize, and sync high-integrity technical documents using the BMAD methodology. Ensures every document is Bold, Minimal, Actionable, and Durable. Use when creating architectural docs, technical guides, or organizing the specs/ directory."
5---
6 
7# Write Document (BMAD)
8 
9Create high-signal technical documentation that serves as an expert collaborator for both humans and AI. This skill enforces the BMAD principles to prevent context rot and ensure architectural durability.
10 
11**Distinct from `edit-document`:** Use this skill to create a document that does not yet exist. Use `edit-document` when a document already exists and needs restructuring, clarity, or prose improvements.
12 
13> **HARD GATE** — Every document must have a clear "Reason for Existence." If a document doesn't provide actionable leverage for a caller or test, do not create it.
14 
15## The BMAD Principles
16 
17| Principle | Execution |
18| :--- | :--- |
19| **B**old | Make strong assertions. Define clear boundaries and "Never" rules. No "it might" or "usually." |
20| **M**inimal | High-density, low-filler. **Circuit Breaker**: If the file exceeds 300 lines or the session exceeds 20 turns, you MUST run `terse-mode` and compact state before saving. |
21| **A**ctionable | Link every doc to a verifiable outcome. **Architectural Docs**: Verify via Gherkin features (`specs/verifications/features/`) or grep-based structure checks (`grep -c "pattern" file`) that prove the design's *constraints* are present. |
22| **D**urable | Design for the long-term. **Scalability**: Use "Nested Indexing"—root files link to module-level `GEMINI.md` indexes; do not list individual sub-files in the root. |
23 
24## Process
25 
26### 1. Identify the Artifact Type & Scope
27 
28Choose the correct BMAD-BigPowers artifact:
29- **Decision Record (ADR)**: For "Why" decisions (saved to `specs/adr/`).
30- **Context Map**: For system-wide architectural mapping (`specs/tech-architecture/tech-stack.md`).
31- **Technical Guide**: For "How-to" with verification (saved to `<module>/REFERENCE.md`).
32- **Behavioral Feature**: Gherkin-style compliance specs (saved to `specs/verifications/features/`).
33- **Project README**: Project-facing documentation (saved to `README.md` at project root).
34 
35**Cross-Cutting Concerns**: If a doc affects multiple modules, place the authoritative source in the lowest common ancestor directory and use "Delegates" (one-line pointers) in sub-directories to maintain the Single Source of Truth without violating the Stepdown Rule.
36 
37### 2. Draft with Semantic Velocity
38 
39> **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.
40 
41Write the document focusing on "Expert Collaboration":
42- **Instructions over Descriptions**: Tell the reader (human or AI) exactly how to interact with the system.
43- **Provenance Links**: Link to ADRs, Issues, or Commits to preserve intent.
44- **The Stepdown Rule**: Information should descend exactly one level of abstraction. If a root doc needs to explain a leaf-level detail, it must point to a sub-index first.
45 
46### Quick README (Project READMEs only)
47 
481. Ask: "Project name? One-sentence description?"
492. Generate `README.md` at project root using the template in [REFERENCE.md](REFERENCE.md) — no TOC, no second interview round.
503. Fill gaps from `CLAUDE.md` / `AGENTS.md` commands if available (prefer `AGENTS.md`); use `TODO` markers otherwise.
514. Output and suggest `edit-document` for polish.
52 
53→ verify: `test -f README.md && [ "$(grep -c '^## ' README.md)" -ge 7 ]`
54 
55### 3. Apply the 94% Quality Gate
56 
57Before finalizing, audit the document against these red flags:
58- [ ] **Filler Language**: Are there pleasantries or "I hope this helps"? (Delete them).
59- [ ] **Ambiguity**: Are there "usually," "often," or "it depends" without specific conditions?
60- [ ] **Dead Ends**: Does the document end without a "Next Step" or "Verification" command?
61- [ ] **Shallow Content**: Does it restate the code without explaining the *intent* or *contracts*?
62 
63### 4. Sync and Organize
64 
65- **Big Powers Hierarchy**: Place the document in the correct tier (Global -> Project -> Sub-directory). Project READMEs are an exception — they go to project root (`README.md`), not `specs/`.
66- **Nested Indexing**: If adding a module-level doc, ensure the module's `GEMINI.md` is updated. If the module's index is new, add it to the root `GEMINI.md`.
67- **Sync**: Run `scripts/sync-skills.sh` if the document is a `SKILL.md` or affects generated artifacts.
68 
69## Rules
70 
71- **Minimalism is a requirement**: If a document can be a 5-line table, do not make it a 5-line essay.
72- **Verifiable outcomes**: Every technical document must include at least one `verify:` command. For architecture, this can be a `grep` or `run_shell_command` that validates the existence of required files or patterns.
73- **No speculative docs**: Do not write documentation for features that do not exist yet unless explicitly doing `elaborate-spec`.
74 
75 
76Suggest next skill: `audit-code` or `sync-skills.sh`.
77 
78---
79 
80# Project README Template
81 
82Combined from dbader/readme-template and jehna/readme-best-practices. No TOC.
83 
84## Navigation
85 
86| Lines | Section |
87|-------|---------|
88| 1 | Title |
89| 5–40 | Navigation |
90| 41–42 | Sections |
91| 43–54 | 1. Title + Badges |
92| 55–60 | 2. Tagline |
93| 61–64 | 3. Description |
94| 65–67 | 4. Prerequisites |
95| 68–75 | Prerequisites |
96| 76–78 | 5. Installation |
97| 79–89 | Installation |
98| 90–92 | 6. Usage |
99| 93–102 | Usage |
100| 103–105 | 7. Features |
101| 106–113 | Features |
102| 114–116 | 8. Configuration |
103| 117–125 | Configuration |
104| 126–128 | 9. Development Setup |
105| 129–139 | Development |
106| 140–142 | 10. Running Tests |
107| 143–152 | Tests |
108| 153–155 | 11. Contributing |
109| 156–164 | Contributing |
110| 165–167 | 12. Changelog |
111| 168–172 | Changelog |
112| 173–175 | 13. Links |
113| 176–181 | Links |
114| 182–184 | 14. License |
115| 185–191 | License |
116| 192–194 | 15. Credits (optional) |
117| 195–199 | Credits |
118| 200–202 | Verify |
119 
120## Sections
121 
122### 1. Title + Badges
123 
124```markdown
125# Project Name
126 
127![License](https://img.shields.io/badge/License-MIT-yellow.svg)
128![npm version](https://img.shields.io/npm/v/your-package.svg)
129 
130```
131 
132Fill badges from CLAUDE.md stack info if available. Default to license + version badges.
133 
134### 2. Tagline
135 
136```markdown
137> One-line description of what this project does and why it matters.
138```
139 
140### 3. Description
141 
1422-3 paragraphs: what problem it solves, who it's for, and what makes it different.
143 
144### 4. Prerequisites
145 
146```markdown
147## Prerequisites
148 
149- **Runtime**: Node.js v18+ (from CLAUDE.md)
150- **Package manager**: npm (or pnpm/yarn)
151```
152 
153Auto-fill from CLAUDE.md commands section when possible.
154 
155### 5. Installation
156 
157```markdown
158## Installation
159 
160```bash
161npm install -g your-package
162# or
163npx your-package
164```
165```
166 
167Prefer npx one-shot if applicable; list global install as alternative.
168 
169### 6. Usage
170 
171```markdown
172## Usage
173
174```bash
175your-command --help
176your-command do-something
177```
178```
179 
180Include the most common 1-2 commands. Link to full docs if they exist.
181 
182### 7. Features
183 
184```markdown
185## Features
186 
187- Feature 1: short description
188- Feature 2: short description
189```
190 
1913-6 bullet points of what the project does. Derived from the project's purpose.
192 
193### 8. Configuration
194 
195```markdown
196## Configuration
197 
198| Variable | Default | Description |
199|----------|---------|-------------|
200| `VAR_NAME` | `value` | What it controls |
201```
202 
203Use `TODO` markers if unknown.
204 
205### 9. Development Setup
206 
207```markdown
208## Development
209 
210```bash
211git clone <repo-url>
212cd project
213npm install
214```
215```
216 
217Auto-fill from CLAUDE.md `Run` and `Build` commands.
218 
219### 10. Running Tests
220 
221```markdown
222## Tests
223
224```bash
225npm test
226npm run lint
227```
228```
229 
230Auto-fill from CLAUDE.md `Test` and `Lint` commands.
231 
232### 11. Contributing
233 
234```markdown
235## Contributing
236
2371. Fork the repo.
2382. Create a feature branch (`git checkout -b feature/my-thing`).
2393. Commit changes (`git commit -am 'Add my thing'`).
2404. Push (`git push origin feature/my-thing`).
2415. Open a Pull Request.
242```
243 
244### 12. Changelog
245 
246```markdown
247## Changelog
248 
249See [CHANGELOG.md](../../CHANGELOG.md) or [Releases](https://github.com/user/repo/releases).
250```
251 
252### 13. Links
253 
254```markdown
255## Links
256 
257- Repository: https://github.com/user/repo
258- Issue tracker: https://github.com/user/repo/issues
259```
260 
261### 14. License
262 
263```markdown
264## License
265 
266MIT — see [LICENSE](../../LICENSE) for details.
267```
268 
269Detect from CLAUDE.md or project LICENSE file.
270 
271### 15. Credits (optional)
272 
273```markdown
274## Credits
275 
276Built with [bigpowers](https://www.npmjs.com/package/bigpowers).
277```
278 
279## Verify
280 
281After generation, run: `grep -c "^## " README.md` — expect ≥ 7 section headings.
282