Golden Principles

Scan the repository for violations of mechanically enforced golden principles. Produces remediation instructions that agents can act on directly.

Inspired by OpenAI Harness Engineering:

"We started encoding what we call 'golden principles' directly into the repository and built a recurring cleanup process."

Triggers

When to Use

Use this skill when:

• Preparing a PR for submission (catch violations early)
• Running periodic garbage collection scans
• Auditing a domain or directory for compliance
• Adding new files to the repository

Use taste-lints instead when:

• Checking code-level invariants only (file size, naming, complexity)
• Running pre-commit checks on staged files

Use quality-grades instead when:

• Grading domains across architectural layers
• Producing quality trend reports

Process

1. Run python3 .claude/skills/golden-principles/scripts/scan_principles.py with target
2. Review AGENT_REMEDIATION blocks in output
3. Apply suggested fixes
4. Re-run to confirm compliance

Usage

bash
1# Scan entire repository
2python3 .claude/skills/golden-principles/scripts/scan_principles.py
3
4# Scan specific directory
5python3 .claude/skills/golden-principles/scripts/scan_principles.py --directory .claude/skills/
6
7# Run specific rules only
8python3 .claude/skills/golden-principles/scripts/scan_principles.py --rules script-language,skill-frontmatter
9
10# JSON output for tooling
11python3 .claude/skills/golden-principles/scripts/scan_principles.py --format json
12
13# Write results to file
14python3 .claude/skills/golden-principles/scripts/scan_principles.py --output scan-results.json --format json

Rules

GP-002, GP-007, GP-008 are enforced by existing tools (git hooks, taste-lints).

Exit Codes

Suppression

Add a comment in the file header to suppress a specific rule:

python
1# golden-principle: ignore script-language

Valid rules: script-language, skill-frontmatter, agent-definition, yaml-logic, actions-pinned

Verification

After execution:

• Report lists scanned file count
• Each violation includes principle ID and remediation
• Exit code matches violation state
• Output format matches --format flag

Cross-References

• Golden Principles Document
• Taste Lints for GP-007, GP-008
• Quality Grades for domain-level grading