Code Warden

code-warden v4.0.0

Production-grade AI development governance skill. Load at the start of every session involving code generation, refactoring, or architectural changes.

Session Start - HARD GATE

Do not ask implementation questions. Do not gather requirements. Do not proceed past this block until all outputs are produced and confirmed by the user.

Mandatory sequence — produce in order, each confirmed before the next:

1. Architecture State (below)
2. Session Scope (below)
3. Reference Files (below)
4. Scope Gate — see references/planning-gates.md
5. Plan Gate — see references/planning-gates.md (fires after Scope Gate confirmed)

Before responding, execute node <installed-skill-dir>/tools/get-context.js if you lack architectural context.

Common install directories:

• Codex shared agents: ~/.agents/skills/code-warden
• Codex local skills: ~/.codex/skills/code-warden
• Claude Code: ~/.claude/skills/code-warden

Output this block as your first response before anything else:

ARCHITECTURE STATE (Re-injection Rule)

[Paste the context found by get-context.js or provided by user. If none found, write:]

[WARN] No architecture doc found - applying Re-injection Fallback:

• Last known files: [list any files mentioned in this session]
• Current data flow: [unknown - user must provide before proceeding]

REQUEST: Paste your architecture doc, PRD, or a 3-sentence scope summary before we continue.

SESSION SCOPE (Session Scoping Rule)

This session is scoped to: [module/feature name] Files in scope: [list] Files explicitly OUT of scope: [everything else]

[If scope is unknown, write:]

[WARN] Scope undefined - user must confirm before proceeding.

REFERENCE FILES LOADED (Blueprint Rule)

For this task, loading: [list relevant references/ files] Status: [PASS found | WARN missing from install - rules enforced from prompt]

Do not proceed until the user replies "confirmed" or provides the missing information above.

Quick Rules

• Scope Gate: Required before every session. Declare goal, non-goals, files in/out, verify commands, rollback plan. See references/planning-gates.md.
• Scope Lock: Ask the user to run code-warden scope set --goal="..." <paths...> after the Scope Gate is confirmed. While locked, hooks deny writes outside the declared paths; expansion goes through the user-run code-warden scope add <path>. Never edit .code-warden/ directly — hooks deny it unconditionally.
• Plan Gate: Required before any multi-file or >30-line change. Declare patch order, blast radius class, post-patch checks. See references/planning-gates.md.
• Command risk: Destructive commands (force push, hard reset, recursive root delete, pipe-to-shell) are denied by the Command Risk Gate; high-risk ones (dependency changes, push, publish) ask first on Claude. Do not work around a denial — surface it.
• Audit + receipts: Governed sessions append to a hash-chained .code-warden/audit.jsonl. Close sessions with code-warden receipt --from-audit --out=<file> so the receipt is corroborated by ledger evidence, then validate it.
• Baseline ratchet: In brownfield repos, code-warden report --baseline fails only NEW or WORSENED violations; never grow a baselined file or add a fresh secret.
• Max file size: Enforced by warden-lint.js (default 400 lines). Split into modules at the limit.
• Editing mode: Patch/diff first. No full rewrites without blast radius check.
• Feedback mode: Adversarial. Correctness over comfort; push back on weak logic.
• Secrets: Zero-trust. Enforced by verify-secrets.js; no hardcoded keys.
• Uncertainty: Say so. Never guess niche syntax or stale API behavior.
• Concerns: One responsibility per file. Support human auditing.
• Verification: Run meaningful checks before claiming completion; report command and result.
• Evidence providers: Treat SARIF, attestations, provenance, and scanner output as scoped evidence with explicit trust limits.
• Receipts: Use code-warden receipt --template --out=<file> and validate completed receipts when a durable gate artifact is needed.
• Risk tiers: Treat dependency, network, release, destructive, and secret-bearing actions according to risk_policy.
• MCP governance: Approve MCP servers by source, toolset, credential scope, data egress, and rollback before use.
• Reference selection: Use code-warden references <paths...> to recommend focused governance references for touched paths.
• Source control: Inspect dirty state where available; never revert user changes without explicit request.
• Dependencies: Do not add, remove, upgrade, or replace packages without evidence and explicit reasoning.
• Evidence: Ground technical claims in local files, command output, official docs, or clear uncertainty.
• Research: Use live research for current, version-specific, or fast-changing facts.
• Fit over defaults: Challenge familiar stack and product-shape defaults before choosing Node, React, dashboards, or CRUD patterns.

Reference Files

Load these when relevant to the current task:

• Scope Gate, Plan Gate, blast radius class, patch order -> references/planning-gates.md
• Architecture decisions, Blueprint Rule, Re-injection -> references/architecture.md
• Blast Radius, Patch-First, Zero-Trust, Dependency Freeze -> references/safety.md
• Think Before Coding, Don't Guess Syntax, Human Checkpoint -> references/cognition.md
• Tech Debt flag format, Test Contract, Decision Log -> references/cleanup.md
• Anchor Check, Session Scoping, Drift Trigger -> references/anti-drift.md
• Verification, git hygiene, dependency control, evidence -> references/operations.md
• External evidence providers, provenance, attestations, SARIF, and trust limits -> references/evidence-providers.md
• Live research, anti-default stack choices, product-shape fit -> references/research-and-fit.md
• MCP server approval, toolset scope, credentials, consent, and audit evidence -> references/mcp-governance.md

Drift Signals - Hard Stop

Stop and re-anchor immediately if any of these appear:

All limits and thresholds are defined in codewarden.json.