How the Three-Tier Boundary System (Always/Ask First/Never) Operates in Agent-Skills

The three-tier boundary system in addyosmani/agent-skills categorizes agent actions into "Always" (auto-execute), "Ask First" (human approval required), and "Never" (strictly forbidden) to enforce safe, spec-driven automation.

The addyosmani/agent-skills repository implements a three-tier boundary system to govern what AI agents can autonomously execute, what requires human oversight, and what remains off-limits entirely. This framework ensures that high-risk operations like database schema changes or secret commits cannot proceed without explicit approval, while routine safety checks run automatically.

What Is the Three-Tier Boundary System?

The system classifies every potential agent action into one of three enforcement tiers defined in skills/spec-driven-development/SKILL.md (lines 77-79).

Always

Actions in the Always tier execute automatically without human intervention. These are low-risk, routine safety measures that ensure code quality.

Examples from the source:

• Run tests before each commit
• Follow naming conventions
• Validate inputs

Ask First

The Ask First tier creates a mandatory pause. The agent must request human approval before proceeding with these higher-risk operations.

Examples from the source:

• Changing database schemas
• Adding new dependencies
• Modifying CI/CD configuration

Never

Actions classified as Never are strictly forbidden under any circumstances. The agent cannot execute these even with human approval, serving as hard security and integrity boundaries.

Examples from the source:

• Commit secrets
• Edit vendor directories
• Delete failing tests without approval

How Boundaries Are Defined in Source Code

The canonical definitions reside in skills/spec-driven-development/SKILL.md at specific line ranges:

• Always tier: "Always do: Run tests before commits, follow naming conventions, validate inputs" (line 77)
• Ask First tier: "Ask first: Database schema changes, adding dependencies, changing CI config" (line 78)
• Never tier: "Never do: Commit secrets, edit vendor directories, remove failing tests without approval" (line 79)

Additional reinforcement appears in skills/security-and-hardening/SKILL.md, which explicitly prohibits secret commits and vendor directory modifications under the "Never" classification.

Enforcement Through the Gated Workflow

The boundary system integrates with the repository's gated workflow (SPECIFY → PLAN → TASKS → IMPLEMENT). Each phase requires human review, but the boundary tiers determine automation levels within implementation:

def can_execute(action):
    if action in ALWAYS:
        return True                     # proceed silently

    if action in NEVER:
        raise PermissionError("Forbidden action")
    if action in ASK_FIRST:
        return ask_human("Approve action: " + action)  # wait for consent

The ALWAYS, ASK_FIRST, and NEVER sets populate from the Boundaries section of the active spec.

Practical Implementation Examples

Spec Template with Explicit Boundaries

When creating a new feature spec, developers define boundaries upfront:

# Spec: Add New Feature X

## Boundaries

- **Always**: Run `npm test` before committing.
- **Ask First**: Introduce the `lodash` dependency.
- **Never**: Commit any `.env` files or secrets.

The agent processes this spec by auto-executing tests, pausing for human approval before adding lodash, and rejecting any .env commits.

Automated "Never" Tier Enforcement

CI scripts can enforce the Never tier independently:

# CI script snippet

if git diff --name-only HEAD~1 | grep -qE '\.env|secrets'; then
  echo "❌ Forbidden file change detected – aborting build"
  exit 1
fi

This prevents secret leakage even if agent logic were compromised.

Summary

• The three-tier boundary system in addyosmani/agent-skills categorizes agent actions as Always (auto-execute), Ask First (human approval required), or Never (strictly forbidden).
• Definitions reside in skills/spec-driven-development/SKILL.md (lines 77-79) and are reinforced by skills/security-and-hardening/SKILL.md.
• The system integrates with the gated workflow (SPECIFY → PLAN → TASKS → IMPLEMENT) to ensure high-risk operations cannot proceed without explicit human consent.
• Practical implementation involves declaring boundaries in spec templates and enforcing "Never" rules through CI automation.

Frequently Asked Questions

What happens if an agent attempts a "Never" classified action?

The agent receives a PermissionError or equivalent rejection and cannot proceed. According to the source code in skills/spec-driven-development/SKILL.md, "Never" actions include committing secrets, editing vendor directories, and removing failing tests without approval. These boundaries are hard constraints that persist even if a human attempts to override them through the agent interface.

How does the "Ask First" tier integrate with the gated workflow?

The Ask First tier creates a mandatory checkpoint within the SPECIFY → PLAN → TASKS → IMPLEMENT workflow. When an agent encounters an action classified as "Ask First"—such as changing database schemas or adding dependencies—it pauses execution and invokes the ask_human() function (or equivalent UI prompt) to request explicit approval before the IMPLEMENT phase can continue.

Can the three-tier boundaries be customized for specific projects?

Yes. While the repository provides default definitions in skills/spec-driven-development/SKILL.md, developers can override or extend these boundaries within individual spec templates. By declaring custom "Always," "Ask First," and "Never" rules in the Boundaries section of a spec file, teams can adapt the safety model to project-specific requirements—such as adding "Ask First" rules for API contract changes or "Never" rules for direct main branch commits.

Where are the "Never" tier rules enforced outside of the agent logic?

The Never tier receives additional enforcement through CI/CD scripts and security hardening skills. For example, skills/security-and-hardening/SKILL.md reinforces rules against committing secrets, while CI scripts can detect forbidden file patterns (such as .env files) in git diff output and abort builds immediately. This layered enforcement ensures that "Never" actions remain blocked even if agent boundary checks were bypassed or compromised.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}