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 "${COPILOT_PLUGIN_ROOT:-${CLAUDE_PLUGIN_ROOT:-.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 "${COPILOT_PLUGIN_ROOT:-${CLAUDE_PLUGIN_ROOT:-.claude}}/skills/golden-principles/scripts/scan_principles.py"
# Scan specific directory
python3 "${COPILOT_PLUGIN_ROOT:-${CLAUDE_PLUGIN_ROOT:-.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 "${COPILOT_PLUGIN_ROOT:-${CLAUDE_PLUGIN_ROOT:-.claude}}/skills/golden-principles/scripts/scan_principles.py" --diff-scope "origin/$BASE_BRANCH"
# Run specific rules only
python3 "${COPILOT_PLUGIN_ROOT:-${CLAUDE_PLUGIN_ROOT:-.claude}}/skills/golden-principles/scripts/scan_principles.py" --rules script-language,skill-frontmatter
# JSON output for tooling
python3 "${COPILOT_PLUGIN_ROOT:-${CLAUDE_PLUGIN_ROOT:-.claude}}/skills/golden-principles/scripts/scan_principles.py" --format json
# Write results to file
python3 "${COPILOT_PLUGIN_ROOT:-${CLAUDE_PLUGIN_ROOT:-.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 "${COPILOT_PLUGIN_ROOT:-${CLAUDE_PLUGIN_ROOT:-.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-principles-33description: 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.4metadata:5 source: https://skillmd.com/skills/rjmurillo/golden-principles-36---78# Golden Principles910Scan the repository for violations of mechanically enforced golden principles.11Produces remediation instructions that agents can act on directly.1213<!-- 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). -->1415Inspired by [OpenAI Harness Engineering](https://openai.com/index/harness-engineering/):1617> "We started encoding what we call 'golden principles' directly into the repository18> and built a recurring cleanup process."1920## Triggers2122| Trigger Phrase | Operation |23|----------------|-----------|24| `scan golden principles` | Full principle compliance scan |25| `check principle compliance` | Scan with summary report |26| `golden principle violations` | Scan and list violations |27| `run garbage collection` | Deep scan with fix-up recommendations |28| `audit principles` | Scan specific rules only |2930## When to Use3132Use this skill when:3334- Preparing a PR for submission (catch violations early)35- Running periodic garbage collection scans36- Auditing a domain or directory for compliance37- Adding new files to the repository3839Use `taste-lints` instead when:4041- Checking code-level invariants only (file size, naming, complexity)42- Running pre-commit checks on staged files4344Use `quality-grades` instead when:4546- Grading domains across architectural layers47- Producing quality trend reports4849## Process50511. Run `python3 "${COPILOT_PLUGIN_ROOT:-${CLAUDE_PLUGIN_ROOT:-.claude}}/skills/golden-principles/scripts/scan_principles.py"` with target522. Review AGENT_REMEDIATION blocks in output533. Apply suggested fixes544. Re-run to confirm compliance5556## Usage5758```bash59# Scan entire repository60python3 "${COPILOT_PLUGIN_ROOT:-${CLAUDE_PLUGIN_ROOT:-.claude}}/skills/golden-principles/scripts/scan_principles.py"6162# Scan specific directory63python3 "${COPILOT_PLUGIN_ROOT:-${CLAUDE_PLUGIN_ROOT:-.claude}}/skills/golden-principles/scripts/scan_principles.py" --directory .claude/skills/6465# Scope to a pull request diff (only files changed vs the base branch)66python3 "${COPILOT_PLUGIN_ROOT:-${CLAUDE_PLUGIN_ROOT:-.claude}}/skills/golden-principles/scripts/scan_principles.py" --diff-scope "origin/$BASE_BRANCH"6768# Run specific rules only69python3 "${COPILOT_PLUGIN_ROOT:-${CLAUDE_PLUGIN_ROOT:-.claude}}/skills/golden-principles/scripts/scan_principles.py" --rules script-language,skill-frontmatter7071# JSON output for tooling72python3 "${COPILOT_PLUGIN_ROOT:-${CLAUDE_PLUGIN_ROOT:-.claude}}/skills/golden-principles/scripts/scan_principles.py" --format json7374# Write results to file75python3 "${COPILOT_PLUGIN_ROOT:-${CLAUDE_PLUGIN_ROOT:-.claude}}/skills/golden-principles/scripts/scan_principles.py" --output scan-results.json --format json76```7778## Rules7980| Rule | Principle | What it checks |81|------|-----------|----------------|82| `script-language` | GP-001 | No new .sh/.bash files |83| `skill-frontmatter` | GP-003 | SKILL.md has required frontmatter fields |84| `agent-definition` | GP-004 | Agent .md files have required sections |85| `yaml-logic` | GP-005 | No inline logic in workflow YAML |86| `actions-pinned` | GP-006 | GitHub Actions pinned to SHA |8788GP-002, GP-007, GP-008 are enforced by existing tools (git hooks, taste-lints).8990## Exit Codes9192| Code | Meaning |93|------|---------|94| 0 | No violations found |95| 1 | Script error (bad arguments, file not found) |96| 10 | Violations detected |9798## Scripts99100| Script | Purpose | Exit codes |101|---|---|---|102| `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). |103104## Suppression105106Add a comment in the file header to suppress a specific rule:107108```python109# golden-principle: ignore script-language110```111112Valid rules: `script-language`, `skill-frontmatter`, `agent-definition`, `yaml-logic`, `actions-pinned`113114## Verification115116After execution, run the bundled validator and require exit 0:117118```bash119python3 "${COPILOT_PLUGIN_ROOT:-${CLAUDE_PLUGIN_ROOT:-.claude}}/skills/golden-principles/scripts/scan_principles.py" <path>120echo "exit=$?" # 0 = clean, 10 = violations found, 1 = tool error121```122123- [ ] Exit 0 to pass; exit 10 means violations exist and must be reported with principle ID and remediation124- [ ] Exit 1 (tool error) is a BLOCKED result, not a pass125- [ ] Report lists scanned file count126- [ ] Output format matches --format flag127128## References129130- [Code Qualities](references/design-code-qualities.md) - Five foundational qualities: cohesion, coupling, non-redundancy, encapsulation, testability131- [SOLID Principles](references/design-solid-principles.md) - SRP, OCP, LSP, ISP, DIP with violation signs and code examples132- [Programming by Intention](references/design-programming-by-intention.md) - Sergeant pattern for expressing intent over implementation133- [Separation of Concerns](references/design-separation-of-concerns.md) - Decomposition at method, class, layer, and service levels134- [DRY Principle](references/design-dry-principle.md) - Single authoritative representation with scope, violations, and when NOT to DRY135136## Cross-References137138- Golden Principles Document: `.agents/governance/golden-principles.md`139- [Taste Lints](../taste-lints/SKILL.md) for GP-007, GP-008140- [Quality Grades](../quality-grades/SKILL.md) for domain-level grading