Team Policies Overview

A .shellfirm.yaml file committed to your repository lets teams codify safety rules that travel with the code. Every developer (and every AI agent) working in the repo inherits the same protections automatically.

What is a team policy?

A team policy is a YAML file named .shellfirm.yaml placed in your repository root (or any directory). It can:

• Deny specific patterns entirely (no challenge, just blocked)
• Override challenge types for specific patterns (e.g., force Yes for dangerous operations)
• Add custom checks with team-specific patterns
• Configure context settings for the project (protected branches, production k8s patterns, etc.)

The additive-only rule

Policies are additive only. They can make things stricter, never more lenient:

• New checks are appended to the global check list
• Deny-list entries are merged (union of global + policy)
• Challenge overrides are applied only if they escalate the challenge (Math to Enter, Enter to Yes)
• A policy cannot remove a global deny-list entry
• A policy cannot downgrade a challenge from Yes to Math

This guarantees that a committed .shellfirm.yaml cannot weaken the protections a user has configured globally.

Policy discovery

When shellfirm evaluates a command, it walks up the directory tree from the current working directory looking for a .shellfirm.yaml file. The first one found is loaded and merged with the global settings.

/home/dev/myapp/services/api/  ← CWD
/home/dev/myapp/services/      ← checked
/home/dev/myapp/               ← .shellfirm.yaml found here!
/home/dev/                     ← not checked (stopped at first match)

Minimal example

# .shellfirm.yaml
version: 1
deny:
  - "git:force_push"

This single rule prevents anyone working in this repository from force-pushing, period. No challenge, no override -- just denied.

Full example

# .shellfirm.yaml
version: 1

# Block these patterns entirely
deny:
  - "git:force_push"
  - "fs:format_filesystem"
  - "kubernetes:delete_namespace"

# Escalate challenges for specific patterns
overrides:
  - id: "fs:recursively_delete"
    challenge: Yes
  - id: "git:reset_hard"
    challenge: Yes
    on_branches:
      - main
      - production

# Add team-specific patterns
checks:
  - id: "team:deploy_prod"
    from: base
    test: "deploy\\s+--env\\s+prod"
    severity: High
    description: "Production deployment detected"
    alternative: "deploy --env staging"
    alternative_info: "Deploy to staging first"

# Project-specific context
context:
  protected_branches:
    - staging
    - "deploy/*"

Who should use team policies?

• DevOps teams enforcing deployment safety across the organization
• Platform teams protecting shared infrastructure
• Security teams mandating compliance rules
• Any team that wants consistent safety standards in their repositories