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
| Trigger Phrase |
Operation |
scan golden principles |
Full principle compliance scan |
check principle compliance |
Scan with summary report |
golden principle violations |
Scan and list violations |
run garbage collection |
Deep scan with fix-up recommendations |
audit principles |
Scan specific rules only |
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
- Run
python3 .claude/skills/golden-principles/scripts/scan_principles.py with target
- Review AGENT_REMEDIATION blocks in output
- Apply suggested fixes
- Re-run to confirm compliance
Usage
# Scan entire repository
python3 .claude/skills/golden-principles/scripts/scan_principles.py
# Scan specific directory
python3 .claude/skills/golden-principles/scripts/scan_principles.py --directory .claude/skills/
# Scope to a pull request diff (only files changed vs the base branch)
python3 .claude/skills/golden-principles/scripts/scan_principles.py --diff-scope "origin/$BASE_BRANCH"
# Run specific rules only
python3 .claude/skills/golden-principles/scripts/scan_principles.py --rules script-language,skill-frontmatter
# JSON output for tooling
python3 .claude/skills/golden-principles/scripts/scan_principles.py --format json
# Write results to file
python3 .claude/skills/golden-principles/scripts/scan_principles.py --output scan-results.json --format json
Rules
| Rule |
Principle |
What it checks |
script-language |
GP-001 |
No new .sh/.bash files |
skill-frontmatter |
GP-003 |
SKILL.md has required frontmatter fields |
agent-definition |
GP-004 |
Agent .md files have required sections |
yaml-logic |
GP-005 |
No inline logic in workflow YAML |
actions-pinned |
GP-006 |
GitHub Actions pinned to SHA |
GP-002, GP-007, GP-008 are enforced by existing tools (git hooks, taste-lints).
Exit Codes
| Code |
Meaning |
| 0 |
No violations found |
| 1 |
Script error (bad arguments, file not found) |
| 10 |
Violations detected |
Scripts
| Script |
Purpose |
Exit codes |
scripts/scan_principles.py |
Scan a path (repo, directory, or diff scope) for GP-001..GP-006 violations and emit AGENT_REMEDIATION blocks. Supports --directory, --diff-scope, --rules, --format, --output. |
0 no violations; 10 violations detected; 1 tool error (bad arguments, file not found). |
Suppression
Add a comment in the file header to suppress a specific rule:
# golden-principle: ignore script-language
Valid rules: script-language, skill-frontmatter, agent-definition, yaml-logic, actions-pinned
Verification
After execution, run the bundled validator and require exit 0:
python3 .claude/skills/golden-principles/scripts/scan_principles.py <path>
echo "exit=$?" # 0 = clean, 10 = violations found, 1 = tool error
References
- Code Qualities - Five foundational qualities: cohesion, coupling, non-redundancy, encapsulation, testability
- SOLID Principles - SRP, OCP, LSP, ISP, DIP with violation signs and code examples
- Programming by Intention - Sergeant pattern for expressing intent over implementation
- Separation of Concerns - Decomposition at method, class, layer, and service levels
- DRY Principle - Single authoritative representation with scope, violations, and when NOT to DRY
Cross-References
- Golden Principles Document:
.agents/governance/golden-principles.md
- Taste Lints for GP-007, GP-008
- Quality Grades for domain-level grading
1---2name: golden-principles3version: 1.0.04description: Scan repository for golden principle violations with agent-readable remediation. Enforces GP-001 through GP-008 from .agents/governance/golden-principles.md. Use when auditing compliance, preparing PRs, or running garbage collection scans.5license: MIT6metadata:7 source: https://skillmd.com/skills/rjmurillo/golden-principles8---910# Golden Principles1112Scan the repository for violations of mechanically enforced golden principles.13Produces remediation instructions that agents can act on directly.1415<!-- vendor-portability: declared. This skill enforces GP-001 through GP-008 defined in .agents/governance/golden-principles.md and cites that document plus .claude/skills/ siblings. The governance file is the upstream rule source; a vendored install without it loses the canonical principle text, while the bundled scanner still applies its built-in GP-001 and GP-003 through GP-006 checks against the consumer's files (GP-002 is enforced elsewhere, not by this scanner). Issue #2050. -->1617Inspired by [OpenAI Harness Engineering](https://openai.com/index/harness-engineering/):1819> "We started encoding what we call 'golden principles' directly into the repository20> and built a recurring cleanup process."2122## Triggers2324| Trigger Phrase | Operation |25|----------------|-----------|26| `scan golden principles` | Full principle compliance scan |27| `check principle compliance` | Scan with summary report |28| `golden principle violations` | Scan and list violations |29| `run garbage collection` | Deep scan with fix-up recommendations |30| `audit principles` | Scan specific rules only |3132## When to Use3334Use this skill when:3536- Preparing a PR for submission (catch violations early)37- Running periodic garbage collection scans38- Auditing a domain or directory for compliance39- Adding new files to the repository4041Use `taste-lints` instead when:4243- Checking code-level invariants only (file size, naming, complexity)44- Running pre-commit checks on staged files4546Use `quality-grades` instead when:4748- Grading domains across architectural layers49- Producing quality trend reports5051## Process52531. Run `python3 .claude/skills/golden-principles/scripts/scan_principles.py` with target542. Review AGENT_REMEDIATION blocks in output553. Apply suggested fixes564. Re-run to confirm compliance5758## Usage5960```bash61# Scan entire repository62python3 .claude/skills/golden-principles/scripts/scan_principles.py6364# Scan specific directory65python3 .claude/skills/golden-principles/scripts/scan_principles.py --directory .claude/skills/6667# Scope to a pull request diff (only files changed vs the base branch)68python3 .claude/skills/golden-principles/scripts/scan_principles.py --diff-scope "origin/$BASE_BRANCH"6970# Run specific rules only71python3 .claude/skills/golden-principles/scripts/scan_principles.py --rules script-language,skill-frontmatter7273# JSON output for tooling74python3 .claude/skills/golden-principles/scripts/scan_principles.py --format json7576# Write results to file77python3 .claude/skills/golden-principles/scripts/scan_principles.py --output scan-results.json --format json78```7980## Rules8182| Rule | Principle | What it checks |83|------|-----------|----------------|84| `script-language` | GP-001 | No new .sh/.bash files |85| `skill-frontmatter` | GP-003 | SKILL.md has required frontmatter fields |86| `agent-definition` | GP-004 | Agent .md files have required sections |87| `yaml-logic` | GP-005 | No inline logic in workflow YAML |88| `actions-pinned` | GP-006 | GitHub Actions pinned to SHA |8990GP-002, GP-007, GP-008 are enforced by existing tools (git hooks, taste-lints).9192## Exit Codes9394| Code | Meaning |95|------|---------|96| 0 | No violations found |97| 1 | Script error (bad arguments, file not found) |98| 10 | Violations detected |99100## Scripts101102| Script | Purpose | Exit codes |103|---|---|---|104| `scripts/scan_principles.py` | Scan a path (repo, directory, or diff scope) for GP-001..GP-006 violations and emit AGENT_REMEDIATION blocks. Supports `--directory`, `--diff-scope`, `--rules`, `--format`, `--output`. | `0` no violations; `10` violations detected; `1` tool error (bad arguments, file not found). |105106## Suppression107108Add a comment in the file header to suppress a specific rule:109110```python111# golden-principle: ignore script-language112```113114Valid rules: `script-language`, `skill-frontmatter`, `agent-definition`, `yaml-logic`, `actions-pinned`115116## Verification117118After execution, run the bundled validator and require exit 0:119120```bash121python3 .claude/skills/golden-principles/scripts/scan_principles.py <path>122echo "exit=$?" # 0 = clean, 10 = violations found, 1 = tool error123```124125- [ ] Exit 0 to pass; exit 10 means violations exist and must be reported with principle ID and remediation126- [ ] Exit 1 (tool error) is a BLOCKED result, not a pass127- [ ] Report lists scanned file count128- [ ] Output format matches --format flag129130## References131132- [Code Qualities](references/design-code-qualities.md) - Five foundational qualities: cohesion, coupling, non-redundancy, encapsulation, testability133- [SOLID Principles](references/design-solid-principles.md) - SRP, OCP, LSP, ISP, DIP with violation signs and code examples134- [Programming by Intention](references/design-programming-by-intention.md) - Sergeant pattern for expressing intent over implementation135- [Separation of Concerns](references/design-separation-of-concerns.md) - Decomposition at method, class, layer, and service levels136- [DRY Principle](references/design-dry-principle.md) - Single authoritative representation with scope, violations, and when NOT to DRY137138## Cross-References139140- Golden Principles Document: `.agents/governance/golden-principles.md`141- [Taste Lints](../taste-lints/SKILL.md) for GP-007, GP-008142- [Quality Grades](../quality-grades/SKILL.md) for domain-level grading