| name | ob-make-guardrails |
| description | Generate or update the ob-guardrails-project skill from ARCHITECTURE.md and relevant project files, then wire it into every engineer agent. Invoked by the /make-guardrails command and the repo-initialize flow. |
| license | MIT |
Make Guardrails
Analyze ARCHITECTURE.md and other project files to generate or update a ob-guardrails-project skill: a set of rules and constraints extracted from the project's own documentation that agents must follow.
Steps
-
Check current state
Read .agents/skills/ob-guardrails-project/SKILL.md. Determine which mode to use:
- Does not exist → Generate mode: create from scratch.
- Exists and has a
<!-- Last updated: footer → Update mode: incrementally update.
- Exists but no timestamp → proceed in Generate mode (full regeneration).
2a. Generate mode: read source documents
Read ALL of the following that exist:
ARCHITECTURE.md (primary source)DESIGN.md (design system, component conventions)AGENTS.md (existing agent instructions, optimizations)README.md (setup, conventions)CONTRIBUTING.md (if present).opencode/opencode-onboard.json (platform, models, concurrency)openspec/config.yaml (if present: domain context and rules)- Root config files:
package.json, tsconfig.json, biome.json, .eslintrc*, Cargo.toml, go.mod, pyproject.toml, pom.xml: whatever exists
- CI/CD workflows:
.github/workflows/*, azure-pipelines.yml: whatever exists
Use file tools to discover constraints: read the documents above, grep for lint/formatter config rules.
Do not rely on prior knowledge: read the actual files and query the actual code graph.
2b. Update mode: incremental analysis
Extract the <!-- Last updated: <ISO date> --> timestamp from the existing skill file. Then:
- Read
ARCHITECTURE.md and check its <!-- Last updated: timestamp. If ARCHITECTURE.md hasn't changed since the guardrails were last generated, report "Guardrails up to date" and stop.
- Run
git log --oneline --since="<date>" -- <config files, lint configs, CI workflows} to find what convention/config files changed.
- If nothing changed: report "Guardrails up to date" and stop.
- Update only the affected rule categories. Preserve manually-added rules in unchanged categories.
- If changes are pervasive (new architecture, new framework, new platform), fall back to Generate mode.
-
Extract guardrails
From the documents and code graph analysis, extract concrete, actionable rules in these categories. Only include a category if you found real evidence for it:
- Architecture constraints: layer boundaries, module dependencies, forbidden imports, directory ownership rules (e.g. "src/api/ must not import from src/ui/"). Use codegraph MCP tools to verify actual import boundaries.
- File organization: avoid god-files and dumping-ground constants. Each file should have one clear responsibility. Do NOT create files like
constants.js, types.ts, config.js, or utils.ts that collect unrelated things from different domains. Split by domain or feature instead (e.g. user-constants.ts, order-types.ts, auth-config.ts). A file that imports from 5+ unrelated modules is a sign it should be split.
- Naming conventions: file naming, component naming, API route conventions, branch naming
- Code style: formatter config, lint rules, import ordering, max line length: derive from actual config files, not guesses
- Testing rules: test file locations, naming, coverage gates, what must be tested before merge
- Build & deployment: build commands, env requirements, deployment targets, CI gates
- Data & state: migration rules, schema change process, state management patterns
- Security: auth boundaries, input validation requirements, secrets handling
- Dependencies: package manager, lockfile rules, upgrade policy, forbidden packages
- Git workflow: branch naming, commit message format, PR process (platform-specific from
opencode-onboard.json)
- Domain-specific rules: anything in
openspec/config.yaml context or ARCHITECTURE.md constraints/risks sections
Each rule must be:
- Concrete: "Use
pnpm not npm" not "Use the right package manager"
- Evidence-based: derive from the files/code graph you analyzed, do not invent rules
- Actionable: an agent can check it before acting
-
Write the skill
Write (or update) .agents/skills/ob-guardrails-project/SKILL.md:
---
name: ob-guardrails-project
description: Project-specific rules and constraints extracted from ARCHITECTURE.md. Load this skill before implementing any change to understand boundaries, conventions, and constraints for this codebase.
license: MIT
---
# Project Guardrails
> Auto-generated by `/make-guardrails`. Regenerate with the same command when architecture or conventions change.
## Architecture Constraints
- <rule>
- <rule>
## Naming Conventions
- <rule>
## Code Style
- <rule>
## Testing
- <rule>
## Build & Deployment
- <rule>
## Data & State
- <rule>
## Security
- <rule>
## Dependencies
- <rule>
## Git Workflow
- <rule>
<!-- Last updated: <current ISO timestamp> -->
Only include sections that have real rules. Omit empty sections.
-
Update agents
For every *-engineer.md in .opencode/agents/, add @ob-guardrails-project to the Guardrails ability line (skip if already present). Keep the line's existing entries exactly as they are: only insert @ob-guardrails-project after @ob-guardrails-generic, never add or remove other skills:
## Abilities
- Guardrails: @ob-guardrails-generic, @ob-guardrails-project[, ...existing entries unchanged]
Exclude tier variant files (*-engineer.build.md, *-engineer.fast.md, *-engineer.plan.md): they are generated copies; only update the base templates.
-
Store summary in agentmemory
write_note MCP tool with title guardrails-summary containing:
- The ISO timestamp of this run
- Number of rules per category
-
Report
Tell the user:
- Whether the skill was generated or updated (and which categories changed)
- Number of rules extracted per category
- Number of agent files updated
- Tip: "Rerun
/make-guardrails any time the architecture or conventions change significantly."
