agent-pragma

Agent Pragma

The problem: AI coding agents follow rules inconsistently. Rules get forgotten mid-conversation, ignored during complex tasks, or applied partially. There's no enforcement mechanism.

The solution: agent-pragma provides skills that mechanically inject rules and validate compliance. Rules aren't remembered - they're enforced by validators that run automatically on every implementation.

Works with both Claude Code and OpenCode.

System Requirements

• Claude Code or OpenCode
• Git
• uv (for /star-chamber)
• Language toolchains for deterministic linting: Go (golangci-lint), TypeScript (biome, tsc), Python (ruff, ty/mypy)

Quick Start

Claude Code

1. Add the marketplace:

   /plugin marketplace add peteski22/agent-pragma
   

2. Install the plugin:

   /plugin install pragma@agent-pragma
   

3. Enable auto-update (recommended):

   /plugin
   → Marketplaces tab → select agent-pragma → Enable auto-update
   

   Third-party marketplaces have auto-update disabled by default. Enabling it ensures you receive new versions automatically when Claude Code starts.

4. Run /validate in any project — immediate value, no setup needed. Example (after modifying Go files):

   > /validate
   
   # Validation Results
   
   | Validator | Result | HARD | SHOULD | WARN |
   |-----------|--------|------|--------|------|
   | security | ✓ pass | 0 | 0 | 0 |
   | state-machine | ✓ pass | 0 | 0 | 0 |
   | error-handling | ✓ pass | 0 | 0 | 0 |
   | go-effective | ✗ fail | 1 | 0 | 0 |
   
   ## HARD violations (must fix)
   - **go-effective** `auth.go:45` — Exported function `HandleLogin` missing doc comment
   
   ## Verdict
   **FAIL** — 1 HARD violation must be fixed before commit
   

Optionally run /setup-project to configure project-specific rules — see Configure Project Rules.

Note: Skills are shown as /star-chamber (pragma) in the CLI autocomplete. The short form /star-chamber is the easiest way to invoke them. The fully-qualified form /pragma:star-chamber also works.

OpenCode

# Clone the repo
git clone https://github.com/peteski22/agent-pragma.git
cd agent-pragma

# Install globally (skills, agents, and commands available in all sessions)
make install AGENT=opencode

# Run /validate in any project — works immediately
/validate

This symlinks skills and generates agents and commands into ~/.config/opencode/. Run /validate in any project — works immediately with built-in rules. For project-specific rules, see Configure Project Rules.

To install into a specific project instead of globally:

make install AGENT=opencode PROJECT=/path/to/your/project

What Works Immediately

Every skill works after install with zero additional setup (/star-chamber requires API keys — see Environment Variables).

flowchart TD
    A["/validate"] --> B["Detect changed file types"]
    B --> C["Dispatch applicable validators"]
    C --> D["security + state-machine + error-handling + language validators"]
    D --> E["Aggregate results"]
    E --> F["Severity-graded report"]

/review uses the same validator dispatch rules.

Validators

/validate orchestrates all applicable validators based on changed file types:

Skill	Language	What it checks
/security	All	Secrets, injection, path traversal, auth gaps
/state-machine	All	State transitions, terminal state correctness, cleanup enforcement
/error-handling	Go, Python, TS	Swallowed errors, empty catches, ignored returns, silent fallbacks
/go-effective	Go	Effective Go — naming, error handling, interface design
/go-proverbs	Go	Go Proverbs — idiomatic patterns, concurrency
/python-style	Python	Google docstrings, type hints, exception chaining, architecture
/typescript-style	TypeScript	Strict mode, React patterns, hooks, state management

Code Review

Skill	What it does
/review	Runs security, state-machine, error-handling + language-specific validators on current changes. Injects project rules if configured.
/star-chamber	Multi-LLM consensus review — prompts for provider setup on first run (requires API keys)

Severity Levels

Level	Meaning	What happens
HARD	Must fix	Blocks /implement completion
SHOULD	Fix or justify	Requires explicit justification to proceed
WARN	Advisory	Noted in output but doesn't block

Configure Project Rules (/setup-project)