Inward vs Outward Thinking: Why Agents Need Both Entry Points and Exit Points

Every repository has two distinct conversations happening simultaneously:

"Here's how to use this system" (outward-facing)
"Here's how to think within this system" (inward-facing)

Traditional documentation conflates these. AI agents need them separated.

At Supernal Coding, we've discovered that the difference between USE_SUPERNAL.md and CLAUDE.md/AGENTS.md isn't just organizational—it's philosophical. One tells agents what buttons to push. The other teaches agents why those buttons exist.

The Two Directions of Repository Knowledge

Outward-Facing: Entry Points (USE_SUPERNAL.md)

Purpose: How the system instructs users and agents on HOW to interact with the repository.

# Entry points are commands and workflows
sc planning req new          # Create requirement
sc git commit                # Smart commit workflow
sc controlled modify <file>  # Protected file workflow
sc test                      # Run test suite

This is behavioral documentation:

Commands and syntax
Workflow steps and sequences
Pre-approvals and gates
What to type, when to type it

The repository speaks in imperatives: "Run this command. Follow this workflow. Use this format."

Inward-Facing: Exit Points (CLAUDE.md / AGENTS.md)

Purpose: How the repository instructs agents on HOW TO THINK within and work with the codebase.

# Exit points are cognitive boundaries
- "Search before implementing" - understand the landscape
- "Change only what is asked" - respect scope boundaries
- "Ask before refactoring unrelated code" - know when to stop
- "Don't BS. Say only things you can back up" - intellectual honesty

This is cognitive documentation:

Principles and reasoning
When to pause and ask
What matters to this codebase
How to reason about trade-offs

The repository speaks in wisdom: "Here's why this matters. Here's when to seek guidance. Here's what we value."

Why This Distinction Matters

The Traditional Failure Mode

Most repositories have README files that mix both:

## Getting Started
npm install        # Entry point (outward)
npm test           # Entry point (outward)

Please write clean code and follow best practices.  # ??? (neither)

That last line is useless to an AI agent. "Clean code" and "best practices" are undefined. The agent has no mental model for what this specific repository considers clean or best.

The Supernal Approach

We separate the conversations:

USE_SUPERNAL_CODING.md (3000+ lines of behavioral rules):

Pre-Approvals:
  sc planning req: lifecycle commands (new, validate, generate-tests)
  sc git hooks: install, uninstall
  sc test: run tests with standard config
  sc build: build packages

Commit Format:
  Structure: <type>(<scope>): <description>
  Types: feat, fix, docs, refactor, test, chore
  Feature scopes: feat(domain/feature):

AGENTS.md (cognitive framework):

## Behavior Guidelines
- Search before implementing: avoid duplication, understand context
- Be succinct: clarity over verbosity
- Change only what is asked: respect boundaries
- Ask before committing when unclear if work is complete

## When to Seek Guidance
- Before modifying controlled files
- Before refactoring unrelated code
- When multiple valid approaches exist
- When impact radius is unclear

One tells you what. The other tells you why and when to stop.

Agents as Hooks: The Inversion

Here's the profound insight: agents aren't just consumers of instructions—they're hooks into the repository's evolution.

Traditional Hooks: Repository Reaches Outward

# Traditional hooks trigger external actions
pre-commit → validate code quality
pre-push → run tests
post-merge → update dependencies

The repository fires events, external systems respond.

Agent Hooks: Repository Reaches Inward

# Agent hooks shape internal cognition
CLAUDE.md → "How to think about this codebase"
AGENTS.md → "What mental models to apply"
USE_SUPERNAL.md → "What commands are safe to run"

The repository provides context, agents internalize it.

The key difference: Traditional hooks are triggers. Agent hooks are instructions for understanding.

When a pre-commit hook rejects your change, it's not just blocking you—it's the repository reaching back and saying: "I need you to understand this differently before proceeding."

The Controlled Files Example

This philosophy manifests clearly in our Controlled Files system:

Outward View (What to Do)

$ sc controlled modify supernal.yaml

CONTROLLED FILE: supernal.yaml
Control Level: strict
Requires: CHG document

What would you like to do?
> Create CHG document
  Link existing requirement
  Abort

Entry point. Clear commands. Workflow steps.

Inward View (Why It Matters)

From AGENTS.md:

Understand that `supernal.yaml`, `.husky/pre-commit`, and
`package.json` are **load-bearing walls** of the repository.

The workflow isn't bureaucracy—it's architectural protection.

When the system blocks you, it's protecting itself from
well-intentioned but dangerous changes.

Mental model. Architectural understanding. The why behind the what.

An agent with only the outward view knows the command. An agent with both views understands that these files are different—they're the repository's immune system.

Entry Points vs Exit Points

Entry Points (Outward)

What they are: Clear ingress into each system capability.

sc planning req new      # Requirements creation
sc git commit            # Commit workflow
sc build                 # Build orchestration
sc test                  # Test execution

Characteristics:

Explicit commands
Defined parameters
Expected outputs
Linear progression

Exit Points (Inward)

What they are: Understanding when to stop and seek guidance.

Ask before:
- Committing when unclear if work is complete
- Refactoring unrelated code
- Creating new documentation files
- Modifying controlled files without workflow
- Making architectural decisions without context

Characteristics:

Judgment calls
Contextual awareness
Self-limitation
Bidirectional communication

Entry points get you into the system. Exit points keep you from breaking it.

The WIP Registry: Both Views in Action

Outward (Entry Point)

$ sc workflow wip add src/auth.js
  Registered: src/auth.js in WIP registry

$ sc workflow wip status
  Active files: 3
  Owner: agent-1

Inward (Cognitive Model)

The WIP registry isn't just tracking files—it's tracking
*the context of work in progress*.

When you register a file:
- You're claiming cognitive ownership
- Other agents will see your intent
- The repository knows this area is "hot"

When you see another agent's WIP:
- Ask before touching their files
- Understand their context first
- Coordinate rather than conflict

The outward view is the API. The inward view is the social contract.

Practical Implementation

Creating Your Own Two-Layer Documentation

Layer 1: USE_[SYSTEM].md (Outward)

All CLI commands with examples
Workflow sequences
Configuration formats
Pre-approved operations
Error messages and fixes

Layer 2: AGENTS.md (Inward)

Mental models for the codebase
When to ask vs proceed
What the codebase values
Common pitfalls and why they matter
Architectural principles

Template for AGENTS.md

# How to Think About This Codebase

## Core Principles
- [What this codebase values most]
- [Trade-offs we've made and why]
- [Patterns we follow consistently]

## Before You Code
- Search for existing implementations
- Understand the domain model
- Check for related requirements

## When to Ask
- [ ] Unclear scope or requirements
- [ ] Multiple valid approaches
- [ ] Changes to controlled files
- [ ] Cross-cutting concerns

## When to Proceed
- [ ] Clear requirements with tests
- [ ] Following established patterns
- [ ] Within your registered WIP
- [ ] Pre-approved operations

## Common Mistakes
- [Mistake] → [Why it matters] → [What to do instead]

The Bidirectional Conversation

The most powerful insight: agents and repositories are in conversation.

Traditional view:

Agent → reads docs → writes code
       (one-way consumption)

Supernal view:

Agent ↔ reads inward docs ↔ develops mental model
      ↔ reads outward docs ↔ knows capabilities
      ↔ hits constraints ↔ learns from feedback
      ↔ asks questions ↔ refines understanding
      ↔ writes code ↔ repository validates
      ↔ commit blocked ↔ adjusts approach
       (bidirectional conversation)

The repository teaches. The agent learns. The code improves.

When a git hook fires and rejects a change, that's not a failure—it's the repository reaching back and contributing to the conversation.

Why "Agents as Hooks" Changes Everything

Before: Agents as Tool Users

Agents execute commands
Documentation is a reference
Constraints are obstacles
Failures are errors to fix

After: Agents as Repository Extensions

Agents internalize codebase values
Documentation shapes cognition
Constraints are communication
Failures are learning opportunities

The repository's hooks, workflows, and constraints aren't restrictions—they're the repository's contribution to the conversation.

An agent that understands this becomes an extension of the repository's own intelligence, capable of autonomous operation while remaining aligned with the codebase's values and architecture.

Getting Started

1. Audit Your Documentation

Do you have:

Entry points (commands, workflows, APIs)?
Exit points (when to ask, when to stop)?
Mental models (why things are this way)?
Cognitive boundaries (scope limits, approval requirements)?

2. Split the Layers

Create:

USE_[SYSTEM].md → Behavioral documentation
AGENTS.md → Cognitive documentation
Keep them synchronized but separate

3. Teach Through Constraints

Your pre-commit hooks aren't just validators—they're teachers.

Clear error messages
Specific fix commands
Explanation of why the constraint exists

4. Enable the Conversation

Create feedback loops:

WIP registry for coordination
Controlled files for protection
Audit logs for learning

The Bottom Line

Outward-facing documentation tells agents what to do.

Inward-facing documentation teaches agents how to think.

The difference between a helpful AI and a destructive one isn't capability—it's understanding. Agents with only entry points know how to use your system. Agents with both entry points and exit points understand when to use it, when to ask, and when to stop.

Your repository isn't just a codebase. It's a cognitive environment. Document it accordingly.

Related Posts:

Resources: