Windsurf rules

1---
2name: seed-conventions
3model: sonnet
4description: "Generate CLAUDE.md and CONVENTIONS.md for a brand-new project through a brief interview, and create the specs/ directory with evolved bigpowers structure (product/, tech-architecture/, verifications/, epics/archive/). Entry point for greenfield projects. Use when starting a new project from scratch, when user asks to set up AI agent conventions, or when there is no CLAUDE.md yet."
5---
6 
7# story: e10s01
8# story: e47s02
9# story: e10s02
10# story: e51s02
11# story: e45s21
12# story: e79s03
13 
14 
15# Seed Conventions
16> **HARD GATE** — Before any new code lands, confirm the project conventions are understood. Ask: 'What does a good commit message look like in this project?'
17 
18Bootstrap a new project with the AI agent conventions it needs. Run this once at the start of a greenfield project.
19 
20## What this creates
21 
22- `CLAUDE.md` — Claude Code session config (project-specific)
23- `CONVENTIONS.md` — shared rules for all AI agents
24- `specs/` — the specs directory where all planning output will live
25- `AGENTS.md` — for OpenCode and other agents (optional)
26- `GEMINI.md` — for Gemini CLI (optional)
27 
28## Interview
29 
30Ask the user these questions (one at a time, wait for each answer):
31 
321. **Project name and one-sentence description** — "What is this project? One sentence."
332. **Stack** — "What language, framework, and runtime? (e.g. TypeScript / Next.js / Node 22)"
342b. **Stack profile (optional)** — Offer: `swift`, `typescript-vue`, `node-service`, or none. If chosen, merge the matching fragment from `profiles/<name>.md` into generated `CONVENTIONS.md`.
353. **Commands** — "What commands do you use for: run, test, build, lint?"
363b. **Preflight (optional)** — "What command runs test, lint, and build together? If none, chain Test + Lint + Build into one **Preflight** row."
374. **Architecture** — "Key modules and relationships in 1–2 sentences."
385. **Conventions** — "Any naming, file organization, or patterns all agents must follow?"
396. **Never-do list** — "What are the hard stops? Things an agent must never touch?"
407. **Defensive code categories** — "Which apply? (Rate limit / Retry / Circuit breaker / Timeout / Graceful degradation)"
418. **Local tool wiring (optional)** — "Wire bigpowers for project-local tools? (Cursor, OpenCode, Cline, Aider, Codex CLI)" If yes, generate AGENTS.md spine artifacts per [REFERENCE.md](REFERENCE.md) §Local tool wiring and §AGENTS.md spine. If no, skip — standard seed output unchanged (no AGENTS.md spine unless opted in).
42 
43## Agentic STE for generated prose (e79s03)
44 
45When writing instructional lines in `CLAUDE.md`, `AGENTS.md`, or `CONVENTIONS.md`, follow [AGENTIC-STE.md](../../docs/AGENTIC-STE.md):
46 
47- Use directive vocabulary: MUST, MUST NOT, NEVER, ALWAYS, DO, DO NOT
48- Do NOT use hedge modals listed in AGENTIC-STE.md Rule 3
49- Cap each instruction sentence at 20 words
50- Write imperative, active-voice lines — one instruction per line
51- Do NOT apply Agentic STE to `terse-mode` (output compression is out of scope)
52 
53After generation, run `bash scripts/validate-agentic-ste.sh --strict CLAUDE.md CONVENTIONS.md` when those files exist in the target project.
54 
55## Generate files
56 
57After the interview, generate each file using the templates in [REFERENCE.md](REFERENCE.md):
58- `AGENTS.md` — from `docs/templates/AGENTS.md` Reach Template (canonical spine source)
59- `CLAUDE.md` — symlink to `AGENTS.md` (copy fallback on Windows when symlink fails)
60- `GEMINI.md` — symlink to `AGENTS.md` when Gemini wiring opted in
61- `opencode.json` — with `"instructions": ["AGENTS.md"]` when OpenCode opted in
62- `.aider.conf.yml` — with `read: AGENTS.md` when Aider opted in
63- `CONVENTIONS.md` — bigpowers standard template + project defensive code categories
64 
65### `specs/` directory
66 
67```bash
68mkdir -p specs/product specs/product/snapshots specs/epics/archive
69mkdir -p specs/tech-architecture specs/adr specs/verifications specs/bugs
70touch specs/product/SCOPE_LATEST.yaml specs/product/VISION_LATEST.yaml specs/product/GLOSSARY_LATEST.yaml
71touch specs/release-plan.yaml specs/execution-status.yaml specs/planning-status.yaml specs/state.yaml
72touch specs/tech-architecture/tech-stack.md specs/tech-architecture/SECURITY_PLAN_LATEST.md
73touch specs/tech-architecture/TEST_PLAN_LATEST.md specs/tech-architecture/DESIGN_PLAN_LATEST.md
74touch specs/tech-architecture/REFACTOR_LATEST.md specs/tech-architecture/IMPACT_LATEST.md
75touch specs/bugs/registry.yaml
76echo &quot;# Specs\n\nAll planning documents for this project." > specs/README.md
77```
78 
79**Note:** `specs/state.yaml.lock` is NOT pre-created — acquired/released dynamically.
80 
81`specs/state.yaml` carries top-level `workflow_mode` (`team-pr` | `solo-git`, default `solo-git`).
82This is the **canonical integrate-mode signal** for all skills.
83Set it once here. Skills such as `release-branch` read this file instead of sniffing profiles.
84 
85When generating `CLAUDE.md`, chain Test + Lint + Build into one **Preflight** row if the user named no Preflight command.
86 
87### Self-installing fenced markers (e45s21)
88 
89Skills that write into `CLAUDE.md` or `AGENTS.md` MUST use **fenced HTML comment markers** so handwritten content outside the fence is never clobbered:
90 
91```markdown
92<!-- BEGIN bigpowers:section-id -->
93…agent-managed content only…
94<!-- END bigpowers:section-id -->
95```
96 
97**Merge rule:** On update, replace only content between matching `BEGIN`/`END` pairs.
98If a marker pair is missing, append a new fenced block at file end.
99Never rewrite the whole file.
100 
101**Standard marker IDs** for seeded projects (see [REFERENCE.md](REFERENCE.md) § Fenced markers):
102 
103| Marker ID | Owner skill | Purpose |
104|-----------|-------------|---------|
105| `project` | seed-conventions | Project, Commands, Architecture |
106| `context-routing` | seed-conventions | Glob → sub-AGENTS.md routing table |
107| `learned-preferences` | session-state | Learned User Preferences + Workspace Facts |
108| `tooling` | setup-environment, guard-git | sqz/rtk/hook blocks installed by tooling skills |
109 
110Emit these fences in `AGENTS.md` (and therefore `CLAUDE.md` symlink) from `docs/templates/AGENTS.md`. User prose outside fences is sacred.
111 
112- [ ] CLAUDE.md exists and is populated
113- [ ] CONVENTIONS.md exists and includes specs/ output convention
114- [ ] specs/product/ exists with SCOPE_LATEST.yaml, VISION_LATEST.yaml, GLOSSARY_LATEST.yaml
115- [ ] specs/tech-architecture/ exists with tech-stack.md, security.md, test.md, design.md
116- [ ] specs/verifications/ exists
117- [ ] specs/epics/archive/ exists
118- [ ] specs/bugs/registry.yaml exists
119- [ ] Confirm with user: "Does CLAUDE.md accurately describe your project?"
120 
121---
122 
123# story: e51s02 e37s01 e37s03 e37s14
124# story: e45s21
125# Seed Conventions — Reference Templates
126 
127## Navigation
128 
129| Lines | Section |
130|-------|---------|
131| 1 | Title |
132| 5–29 | Navigation |
133| 30–53 | Fenced markers (e45s21) |
134| 54–65 | AGENTS.md spine (Reach Template — e37s01) |
135| 66–77 | Agent config template (legacy — prefer AGENTS.md spine) |
136| 78–81 | Project |
137| 82–91 | Commands |
138| 92–94 | Architecture |
139| 95–98 | Conventions |
140| 99–104 | Never |
141| 105–114 | Agent Rules |
142| 115–123 | opencode.json template |
143| 124–133 | Aider — `.aider.conf.yml` bridge (e37s03) |
144| 134–146 | Codex CLI — project-local `.codex/config.toml` + AGENTS.md (e37s14) |
145| 147–156 | CONVENTIONS.md |
146| 157–160 | Stack profile fragments |
147| 161–164 | Local tool wiring (optional interview step 8) |
148| 165–173 | Cursor — project-local `.cursor/rules` symlink |
149| 174–187 | OpenCode — project-local `opencode.json` + `AGENTS.md` |
150| 188–190 | When to offer |
151 
152## Fenced markers (e45s21)
153 
154Self-installing blocks prevent skills from overwriting user-authored prose. Pattern:
155 
156```markdown
157<!-- BEGIN bigpowers:section-id -->
158…managed content…
159<!-- END bigpowers:section-id -->
160```
161 
162**Merge algorithm:**
163 
1641. If `BEGIN bigpowers:<id>` exists → replace inner content only.
1652. If missing → append new fenced block at EOF.
1663. Never delete content outside fences.
167 
168Seed these marker IDs in generated `AGENTS.md`:
169 
170| ID | Initial content |
171|----|-----------------|
172| `project` | Project, Commands, Architecture, Conventions, Never, Agent Rules |
173| `context-routing` | Glob → sub-AGENTS.md table (see CLAUDE.md e45s22) |
174| `learned-preferences` | Empty Learned User Preferences + Workspace Facts lists |
175 
176## AGENTS.md spine (Reach Template — e37s01)
177 
178Canonical source: copy from `docs/templates/AGENTS.md` in the bigpowers repo (Reach Template).
179Do not invent structure ad hoc — the template includes multi-agent preamble, Preflight, Test/Lint/Build sections.
180 
181When local tool wiring is opted in:
1821. Copy Reach Template → project root `AGENTS.md`, fill interview placeholders
1832. `ln -sf AGENTS.md CLAUDE.md` (or content copy on Windows when symlink fails)
1843. Write `opencode.json` with `"instructions": ["AGENTS.md"]`
185 
186When user **opts out** of local tool wiring, do not emit AGENTS.md spine artifacts.
187 
188## Agent config template (legacy — prefer AGENTS.md spine)
189 
190All three files use the same structure — only the header differs:
191- `CLAUDE.md` → `# [Project Name] — Claude Code` (or symlink to AGENTS.md)
192- `GEMINI.md` → `# [Project Name] — Gemini CLI`
193- `AGENTS.md` → `# [Project Name] — AI Agents` (Reach Template header)
194 
195```markdown
196# [Project Name] — [Agent]
197 
198Read CONVENTIONS.md before any GitHub or git operation.
199 
200## Project
201[One sentence description]
202Stack: [language, framework, runtime]
203 
204## Commands
205| Action | Command |
206|--------|---------|
207| Run    | `[cmd]` |
208| Test   | `[cmd]` |
209| Build  | `[cmd]` |
210| Lint   | `[cmd]` |
211| Preflight | `[test && lint && build chain — or user-named full-green cmd]` |
212| CI     | `gh pr checks` (when a PR is open) |
213 
214## Architecture
215[1–2 sentences. Key modules and their relationships.]
216 
217## Conventions
218- [convention 1]
219- [convention 2]
220 
221## Never
222- Never dismiss reproducible gate failures as pre-existing or out of scope
223- Never proceed on red Preflight or red CI — invoke quick-fix or fix-bug first
224- [hard stop 1]
225- [hard stop 2]
226 
227## Agent Rules
228- **Workflow Mandate:** You MUST use the bigpowers skills (e.g. `plan-work`, `develop-tdd`, `orchestrate-project`) to perform tasks. DO NOT write code directly in response to a user prompt like "build this feature".
229- **Always Green:** Preflight and CI must be green before forward work. Reproducible gate failures require **fix-or-log** (quick-fix → fix-bug) per CONVENTIONS § Discovered Defects.
230- Read specs/ before writing code.
231- All planning and specifications MUST be written to `specs/` (`product/SCOPE_LATEST.yaml`, `release-plan.yaml`, `epics/`) before any code is generated.
232- Write the minimum code that solves the stated problem. Nothing extra.
233- Run tests after every change. Show evidence before declaring done.
234- One clarifying question beats a wrong assumption baked into 200 lines.
235```
236 
237## opencode.json template
238 
239```json
240{
241  "$schema": "https://opencode.ai/config.json",
242  "instructions": ["AGENTS.md"]
243}
244```
245 
246## Aider — `.aider.conf.yml` bridge (e37s03)
247 
248When Aider wiring is opted in:
249 
250```yaml
251read: AGENTS.md
252```
253 
254Upstream: [Aider-AI/aider](https://github.com/Aider-AI/aider) (not paul-gauthier/aider).
255 
256## Codex CLI — project-local `.codex/config.toml` + AGENTS.md (e37s14)
257 
258Source: https://developers.openai.com/codex/guides/agents-md
259 
260Codex is instruction-file-only — no slash skills. When Codex wiring is opted in:
261 
262```toml
263# .codex/config.toml
264instructions = ["AGENTS.md"]
265```
266 
267Use AGENTS.md header `# [Project Name] — AI Agents` (shared with OpenCode/Cline). Single AGENTS.md serves dual-tool projects.
268 
269## CONVENTIONS.md
270 
271Use the standard bigpowers CONVENTIONS.md as the base. Fill in the project-specific defensive code categories from the interview answers.
272 
273**Always embed** these doctrine sections from bigpowers (adapt commands only):
274 
275- **§ Always Green / Shift Left** — 1-10-100 rationale, Preflight + CI green definitions
276- **§ Discovered Defects** — fix-or-log ladder (quick-fix → fix-bug), separate commits for discovered fixes
277- **Banned dismissive phrases** table — pre-existing, unrelated to session, not introduced by my changes, out of scope (ignoring a red gate)
278 
279## Stack profile fragments
280 
281If the user selected a stack profile, merge the matching `profiles/<name>.md` fragment into the generated `CONVENTIONS.md` under a `## Stack Conventions` section. Profiles supply language-specific commands, architecture patterns, and never-do additions.
282 
283## Local tool wiring (optional interview step 8)
284 
285Offered after the standard interview. Covers the two tools that global install (`scripts/install.sh`) structurally cannot reach because they read project-root config, not global paths.
286 
287### Cursor — project-local `.cursor/rules` symlink
288 
289```bash
290# From the project root:
291ln -sfn &lt;bigpowers-install-path&gt;/.cursor/rules .cursor/rules
292```
293 
294Cursor reads `.cursor/rules/` from the project root. This symlink gives every project access to bigpowers skills as Cursor rules without duplicating the files. Run once per project.
295 
296### OpenCode — project-local `opencode.json` + `AGENTS.md`
297 
298`opencode.json` (project root):
299```json
300{
301  "$schema": "https://opencode.ai/config.json",
302  "instructions": [".cursor/rules/*.mdc", "AGENTS.md"]
303}
304```
305 
306OpenCode reads `opencode.json` from the project root, NOT from a global path. The `instructions` array points to the local `.cursor/rules` symlink (from the Cursor step above) and the project's `AGENTS.md`. Both must exist in the project for OpenCode to see bigpowers skills.
307 
308`AGENTS.md` is already generated by the standard interview (step 2 of Generate Files). When local tool wiring is opted in, ensure `AGENTS.md` includes the standard agent-config template header `# [Project Name] — OpenCode`.
309 
310### When to offer
311 
312Only offer local tool wiring when the user's project will be opened in Cursor or OpenCode. These tools are project-root scoped by design — no global installer can solve them. Global install (`install.sh`) already handles Claude Code, Gemini CLI, and pi globally. Do not offer for tools that read global config.
313