Guidelines
When to use
- "set up guidelines", "update guidelines"
- "change our stack", "add a convention"
- Any request to establish or modify project-wide principles
Create or update the project guidelines document at .specs/guidelines.md.
Recommended effort: medium. Interview-driven with structured generation into a fixed section template.
Pre-flight
Run python3 ${CLAUDE_PLUGIN_ROOT}/scripts/validate-prereqs.py guidelines and use the specsDir value from the JSON output. Abort if the output reports missing prerequisites.
Modes
This skill operates in two modes depending on whether .specs/guidelines.md already exists.
Create mode (no existing guidelines)
If .specs/guidelines.md does not exist, this is a fresh project. Ask the user:
- What is the tech stack? (language, runtime, framework, core libraries)
- What architectural style do they prefer? (functional, OOP, procedural, hybrid)
- Any hard conventions? (naming, file layout, error handling patterns)
- What's the testing philosophy? (when to test, what to skip, coverage attitude, framework, file location pattern, naming convention)
- Deployment and infrastructure constraints?
- What is the check command? This is the full CLI command chain that must pass for code to be considered correct — it runs after every implementation task. (e.g.,
npm run lint && npm run typecheck && npm run build && npm run test, or ruff check . && mypy . && pytest)
If the user provides a description or the project already has code, infer what you can and confirm with them.
Update mode (existing guidelines)
If .specs/guidelines.md already exists, read it first. Then ask the user:
- What changed? (new library, dropped dependency, revised convention, infrastructure shift)
- Why? (one sentence is fine; this helps evaluate downstream impact)
Generation
After gathering all user input via the interview, spawn the guideliner agent. Pass it: the specs directory path and all interview responses. The agent will generate the guidelines document.
Quality gate
1---2name: trellis-guidelines3description: Creates or updates .specs/guidelines.md with project-wide stack, conventions, and principles. Use when starting a project or when a fundamental technology decision has changed.4---56# Guidelines78## When to use910- "set up guidelines", "update guidelines"11- "change our stack", "add a convention"12- Any request to establish or modify project-wide principles1314Create or update the project guidelines document at `.specs/guidelines.md`.1516**Recommended effort: medium.** Interview-driven with structured generation into a fixed section template.1718## Pre-flight1920Run `python3 ${CLAUDE_PLUGIN_ROOT}/scripts/validate-prereqs.py guidelines` and use the `specsDir` value from the JSON output. Abort if the output reports missing prerequisites.2122## Modes2324This skill operates in two modes depending on whether `.specs/guidelines.md` already exists.2526### Create mode (no existing guidelines)2728If `.specs/guidelines.md` does not exist, this is a fresh project. Ask the user:29301. What is the tech stack? (language, runtime, framework, core libraries)312. What architectural style do they prefer? (functional, OOP, procedural, hybrid)323. Any hard conventions? (naming, file layout, error handling patterns)334. What's the testing philosophy? (when to test, what to skip, coverage attitude, framework, file location pattern, naming convention)345. Deployment and infrastructure constraints?356. What is the check command? This is the full CLI command chain that must pass for code to be considered correct — it runs after every implementation task. (e.g., `npm run lint && npm run typecheck && npm run build && npm run test`, or `ruff check . && mypy . && pytest`)3637If the user provides a description or the project already has code, infer what you can and confirm with them.3839### Update mode (existing guidelines)4041If `.specs/guidelines.md` already exists, read it first. Then ask the user:42431. What changed? (new library, dropped dependency, revised convention, infrastructure shift)442. Why? (one sentence is fine; this helps evaluate downstream impact)4546## Generation4748After gathering all user input via the interview, spawn the `guideliner` agent. Pass it: the specs directory path and all interview responses. The agent will generate the guidelines document.4950## Quality gate5152- [ ] Could a new developer read this and write code that matches the project's style?53- [ ] Are there concrete examples (not just rules) for every convention?54- [ ] Is every stack decision specific (named packages, not categories)?55- [ ] Does it avoid feature-specific content? (That belongs in specs, not guidelines.)
robmclarty