Ariadne Thread

---
name: ariadne-thread
description: Create AI-friendly project structures using progressive disclosure indexing (AGENTS.md, module INDEX.md files, file intent headers). ALWAYS use this skill when the user wants to: create or update AGENTS.md or llms.txt, add INDEX.md files to modules, set up project navigation for AI agents, retrofit an existing codebase with AI-friendly indexes, design module boundaries with explicit dependency and modification-risk documentation, or mentions "AI-friendly project", "progressive disclosure", "project index", "codebase navigation", or "ariadne". Also use when the user asks how to structure a new project so AI tools can navigate it efficiently, even if they don't use these exact terms.
---

# Ariadne Thread

Create codebases that AI agents can navigate efficiently through progressive disclosure — revealing only what's needed, when it's needed.

## When to Use

Apply this skill when the user:
- Starts a new project and wants AI-friendly structure
- Restructures or indexes an existing codebase
- Adds project navigation (AGENTS.md, INDEX.md, llms.txt)
- Designs module boundaries and dependencies
- Mentions: "AI-friendly project", "progressive disclosure", "project index", "codebase navigation", or "ariadne"

**Language-agnostic**: applies to any language. See [language-adaptation.md](references/language-adaptation.md) for per-language mappings.

**When NOT to apply**: Minimal single-file projects, quick prototypes, or codebases where indexing overhead outweighs benefit. Skip full L1/L2 when the project has fewer than ~5 source files; a lightweight AGENTS.md may suffice.

## Core Philosophy

Like Ariadne's thread through the labyrinth, a well-indexed codebase gives AI agents a clear path from project overview to implementation detail. **An agent should understand your project structure, locate any function, and assess the impact of any modification — without reading the entire codebase.**

Two optimization targets:
1. **Navigation efficiency** — minimize tokens consumed to find the right code
2. **Modification safety** — maximize probability of correct changes via explicit contracts and dependency visibility

## The 4-Level Index Architecture

```
L0  PROJECT ROOT     ← AGENTS.md (80–150 lines, prefer brevity)
│                       Project map, navigation table, build commands, cross-cutting patterns
│
L1  MODULE INDEX     ← Each directory gets an INDEX.md (~50 lines)
│                       Purpose, public API, bidirectional dependencies, contracts,
│                       task routing, modification risk, test mapping
│
L2  FILE INTENT      ← File headers (~5-10 lines per file)
│                       What this file does, public interface, contracts, side effects
│
L3  INLINE DETAIL    ← Comments on non-obvious logic only
                        Why, not what; tricky edge cases; business rules
```

AI agents start at L0 and drill down only as needed.

### L0: Project Root Index

Create an `AGENTS.md` at the project root with:

1. **One-line project description**
2. **Directory map** — ASCII tree with purpose annotations
3. **Quick navigation table** — key entry points by area
4. **Build & test commands**
5. **Code conventions summary**
6. **Architectural constraints** — illegal dependency directions, global invariants
7. **Cross-cutting behavior patterns** — error handling, logging, concurrency model
8. **Agent Workflow** — at the **end** of the file (Checklist-at-END format): mandatory steps before editing — locate module via Quick Navigation, open `INDEX.md` and check Dependents before modifying public API, confirm Modification Risk for breaking changes, run Tests before finishing
9. **Index exclusions** — Optional `.cursorignore` (same syntax as `.gitignore`) to exclude build artifacts, dependencies, generated code; common examples: `node_modules/`, `dist/`, `vendor/`, `__pycache__/`, `target/`, `*.generated.*` — adapt to your ecosystem

The cross-cutting patterns section is critical: it prevents the AI from reading 3-4 existing files just to infer "how do we handle errors here?". One 30-line declaration replaces ~1500 tokens of pattern inference.

**All 9 sections are required** — they are the difference between an AGENTS.md that actually guides AI behavior and one that merely documents the project for humans. The sections that get skipped most often (Architectural Constraints, Cross-Cutting Patterns, Agent Workflow checklist) are also the ones with the highest AI value.

**Navigation priority**: Prefer navigating via `INDEX.md` Dependents and Dependencies over semantic/keyword search. Structural dependency paths surface architecturally critical files that retrieval often misses. When modifying a module's public API, always consult its Dependents list first to assess blast radius.

**Information placement (Lost in the Middle)**: LLMs attend more to context start and end. Place high-priority content (Build, Quick Navigation, Agent Workflow) at the beginning or end of AGENTS.md; keep secondary sections toward the middle.

```markdown
## Architectural Constraints

<!-- Typical Web app layers; adapt to project: app/, packages/, layers/, etc. -->
- Dependency direction: presentation → domain → infrastructure (never reverse)
  Example: ui/ → core/ → infra/ — or app/features/, packages/core/, etc.
- All external calls (HTTP, DB, cache) go through infrastructure layer — e.g. `src/infra/` or `[project-path]/infra/`
- No direct file I/O outside designated storage module

## Cross-Cutting Patterns

### Error Handling
- Throw typed errors (e.g. [ErrorType], [ValidationError]), never raw strings
- Log errors before re-throwing across module boundaries
- Public functions document all throwable error types in file header

### Logging
- Use structured logger from [project logger location]
- Include [trace_id or request_id] in all log entries
- Levels: ERROR (failures), WARN (degradation), INFO (operations)

### Concurrency (if applicable)
- Document thread-safety per module (single-threaded vs thread-safe)
- Define lock ordering strategy (e.g. by resource name, by hierarchy) and record in AGENTS.md
- Apply consistently to avoid deadlocks
```

For the full AGENTS.md template, see [index-templates.md](references/index-templates.md).

### L1: Module Index

Every module directory gets an `INDEX.md` — any directory that has a public API, a barrel/`__init__`, or 3+ source files. This is the **most information-dense layer** — it must answer not just "what does this module do?" but also "who depends on it?", "what will break if I change it?", and "which file should I edit for task X?".

*Example below uses domain `auth`; replace with your domain — billing, reporting, catalog, etc.*

```markdown
# Module: auth

Handle user authentication and session management.

Status: stable | Fan-in: 5 | Fan-out: 2

## Public API

| Export | File | Description |
|--------|------|-------------|
| `authenticate()` | `authenticate.*` | Verify credentials, return session |
| `authorize()` | `authorize.*` | Check permissions for resource |
| `SessionStore` | `session_store.*` | Session lifecycle management |

## Dependencies (Fan-out: 2)

<!-- Use repo-root-relative paths. Optional edge type: [imports] | [inherits] | [instantiates] -->

- `src/infra/db` — user record lookups
- `src/shared/crypto` — password hashing

## Dependents (Fan-in: 5)

<!-- Prefer structural navigation via this list over semantic search. Use repo-root-relative paths. -->

- `src/api/routes/user` → authenticate()
- `src/api/middleware/auth-guard` → authorize()
- `src/core/billing` → get_session()
- `src/core/notification` → get_user_from_session()
- `src/api/routes/admin` → authorize()

## Interface Contract

- authenticate(): returns Session (token non-empty, expires_at > now) or throws AuthError
- All failed auth attempts → audit log written before exception propagates
- Thread-safe: all public functions can be called concurrently
- Side effect: authenticate() writes to audit_log