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.
2description: "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."
3alwaysApply: false
4---
5
6# story: e10s01
7# story: e47s02
8# story: e10s02
9# story: e51s02
10# story: e45s21
11# story: e79s03
12
13
14# Seed Conventions
15> **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?'
One repository carrying more than one format is the comparison this product exists for: does anyone actually write different content in each file, or is one a copy of the other?
A badge carrying the measured quality of the strongest agent config file in this repository, out of 100. It reads from this index every time somebody loads your page, so it changes when the measurement changes and there is nothing to keep up to date. Free, no account, and the value is not something you or we can set by hand.
Would rather not hotlink us? Every badge is also served in shields.io’s endpoint schema, so shields renders the image and your readers never talk to our domain:
Published by Toolproof, the masthead over this index and eight others. The method behind the number is at toolproof.kynth.studio/methodology, and the whole thing is readable as JSON with no key at /api.
332b. **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`.
343.**Commands** — "What commands do you use for: run, test, build, lint?"
353b. **Preflight (optional)** — "What command runs test, lint, and build together? If none, chain Test + Lint + Build into one **Preflight** row."
364.**Architecture** — "Key modules and relationships in 1–2 sentences."
375.**Conventions** — "Any naming, file organization, or patterns all agents must follow?"
386.**Never-do list** — "What are the hard stops? Things an agent must never touch?"
81This is the **canonical integrate-mode signal** for all skills.
82Set it once here. Skills such as `release-branch` read this file instead of sniffing profiles.
83
84When generating `CLAUDE.md`, chain Test + Lint + Build into one **Preflight** row if the user named no Preflight command.
85
86### Self-installing fenced markers (e45s21)
87
88Skills that write into `CLAUDE.md` or `AGENTS.md` MUST use **fenced HTML comment markers** so handwritten content outside the fence is never clobbered:
89
90```markdown
91<!-- BEGIN bigpowers:section-id -->
92…agent-managed content only…
93<!-- END bigpowers:section-id -->
94```
95
96**Merge rule:** On update, replace only content between matching `BEGIN`/`END` pairs.
97If a marker pair is missing, append a new fenced block at file end.
98Never rewrite the whole file.
99
100**Standard marker IDs** for seeded projects (see [REFERENCE.md](REFERENCE.md) § Fenced markers):
214[1–2 sentences. Key modules and their relationships.]
215
216## Conventions
217- [convention 1]
218- [convention 2]
219
220## Never
221- Never dismiss reproducible gate failures as pre-existing or out of scope
222- Never proceed on red Preflight or red CI — invoke quick-fix or fix-bug first
223- [hard stop 1]
224- [hard stop 2]
225
226## Agent Rules
227- **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".
228- **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.
229- Read specs/ before writing code.
230- All planning and specifications MUST be written to `specs/` (`product/SCOPE_LATEST.yaml`, `release-plan.yaml`, `epics/`) before any code is generated.
231- Write the minimum code that solves the stated problem. Nothing extra.
232- Run tests after every change. Show evidence before declaring done.
233- One clarifying question beats a wrong assumption baked into 200 lines.
259Codex is instruction-file-only — no slash skills. When Codex wiring is opted in:
260
261```toml
262# .codex/config.toml
263instructions = ["AGENTS.md"]
264```
265
266Use AGENTS.md header `# [Project Name] — AI Agents` (shared with OpenCode/Cline). Single AGENTS.md serves dual-tool projects.
267
268## CONVENTIONS.md
269
270Use the standard bigpowers CONVENTIONS.md as the base. Fill in the project-specific defensive code categories from the interview answers.
271
272**Always embed** these doctrine sections from bigpowers (adapt commands only):
273
274-**§ Always Green / Shift Left** — 1-10-100 rationale, Preflight + CI green definitions
275-**§ Discovered Defects** — fix-or-log ladder (quick-fix → fix-bug), separate commits for discovered fixes
276-**Banned dismissive phrases** table — pre-existing, unrelated to session, not introduced by my changes, out of scope (ignoring a red gate)
277
278## Stack profile fragments
279
280If 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.
281
282## Local tool wiring (optional interview step 8)
283
284Offered 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.
293Cursor 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.
305OpenCode 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.
306
307`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`.
308
309### When to offer
310
311Only 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.
The most expressive format here. Many small .mdc files, each with frontmatter declaring when it should load, so a rule about migrations only enters context when a migration is open. Costs the most to maintain and only one editor reads it.
