brain-compliance

Validates frontmatter, filenames, and wikilinks for Gbrain-compliant brain pages.

1|Updated Jun 21, 2026
One-click install
npx skills add https://github.com/tapway/shogun-os --skill brain-compliance-tapway
Or copy as Structured Prompt for Agent
Please help me install this Agent Skill.
Skill: brain-compliance
Source: https://github.com/tapway/shogun-os/tree/main/skills/gbrain/brain-compliance
Command: npx skills add https://github.com/tapway/shogun-os --skill brain-compliance-tapway

SYSTEM DOCUMENTATION & REQUIREMENTS

💡 This Skill includes scripts (resource) and references (resource) components.

What problem does it solve? Brain pages written by humans, agents, and cron jobs often drift from structural standards, breaking search, graph links, and brain health scores. This Skill enforces consistent frontmatter, filename conventions, wikilink formats, and orphan prevention across every brain page. ## Core Features & Use Cases - Frontmatter Standards: Defines required YAML fields for 14 canonical entity types including person, company, deal, meeting, and daily pages. - Three-Layer Enforcement: Combines an agent gate, a git pre-commit hook, and batch audits so violations are caught at write time, commit time, and during weekly scans. - Orphan Prevention: Provides a shared helper that auto-links new pages to category index hubs and related entities so no page is left disconnected from the graph. - Use Case: A cron job creates a new deal page in deals/; the Skill validates its frontmatter, confirms the slug is lowercase-hyphenated, links it to deals-index/all, and runs the validator before delivery. ## Quick Start Ask the agent to create a new brain page for a person or company and validate it against the brain compliance standards before saving.

Frequently Asked Questions about brain-compliance

High-intent search queries and answers about installing and using this skill.

FAQPage Schema
How do I validate a brain page for compliance?

Run the validate-brain-page.py script on a single file or use the --batch flag to scan an entire folder. Alternatively, use gbrain-native MCP tools like schema_lint and get_health after writing a page.

What frontmatter fields are required for brain pages?

Every brain page needs at least a title and a type or tags classifier. Each of the 14 canonical types such as person, company, and deal has additional required fields like first_seen, source, stage, or date.

How do I prevent orphan pages in a gbrain knowledge graph?

Use the brain_compliance_helper write_brain_page function, which automatically links new pages to their category index hub and cross-links related entities. You can also run find_orphans periodically to catch pages that slipped through.

Does the pre-commit hook block non-compliant brain files?

Yes, the hook at ~/brain/.git/hooks/pre-commit validates every staged markdown file and blocks commits with violations such as missing titles or bare wikilinks. Use git commit --no-verify only as an emergency bypass.

When should I not use brain compliance validation?

Skip it for read-only brain queries, non-brain file operations, and pure operational tasks like docker or server management. It is designed specifically for writing, editing, or creating brain pages.