Complete step-by-step instructions on setting up, using, and troubleshooting your Universal AI-Native Development Architecture across Cursor, Claude Code, and Codex.
You can bootstrap the agent-folders system into any new or existing project in seconds. Choose the method that best matches your workflow:
Open your terminal, navigate to your target project folder, and run:
# 1. Initialize canonical folders, policies, and adapters:
npx agent-folders init
# 2. Run system health & token budget check:
npx agent-folders doctor
# 3. Scaffold your first application:
npx agent-folders scaffold full-stack-app client-portalIf you don't have Node or npm globally installed, run this single shell command:
curl -fsSL https://raw.githubusercontent.com/rjbizsolution23-wq/agent-folders/main/install.sh | bashClick Use this template on GitHub to spawn an immediate clean repository under your own account.
The single most important principle in agent-folders is Progressive Context Disclosure. When you instruct an AI coding agent, never ask it to "read the entire repository." Doing so pollutes the context window and triggers hallucinated code.
AGENTS.md, sub-300 tokens). They read deeper levels only when their specific task requires it.
| Level | Artifact / Path | Token Size | When to Load |
|---|---|---|---|
| Level 0 | AGENTS.md |
~287 tokens | Every session start. Acts as the navigational compass. |
| Level 1 | .ai/policies/*.md |
~200 tokens each | On-demand: Read engineering.md before writing code, security.md before modifying auth, testing.md before writing tests. |
| Level 2 | .ai/context/*.md |
~500 tokens | During architecture planning or cross-module refactoring. |
| Level 3 | .ai/skills/<name>/SKILL.md |
~400 tokens | On trigger: Load debugging when tests fail, planning when starting a multi-file feature. |
| Level 4 | projects/<app>/src/* |
Variable | Surgical target files: Only the specific files being modified. |
| Level 5 | .ai/context/decisions-log.md |
~300 tokens | Historical edge cases: Consulted only when resolving past architectural ambiguities. |
Cursor automatically recognizes .cursorrules at the root of the project. The .cursorrules file directs Cursor to obey AGENTS.md and load rules from .ai/policies/.
Pro-Tip: In Cursor Chat composer (Cmd+I / Cmd+L), you can directly tag specific policies: @.ai/policies/engineering.md implement user authentication.
Claude Code automatically reads CLAUDE.md in your terminal. To invoke a specific skill with Claude Code, simply prompt:
Claude, activate .ai/skills/planning/SKILL.md to plan the database migration.Whenever you update an engineering or security rule in .ai/policies/, run:
npx agent-folders syncThis automatically regenerates CLAUDE.md, .cursorrules, and GEMINI.md so all AI tools follow the exact same standards.
You never have to search external documentation when stuck. agent-folders includes an interactive customer helpdesk built right into your CLI:
# Quick lookup on any topic:
npx agent-folders support tokens
npx agent-folders support cloudflare
npx agent-folders support cursor
npx agent-folders support scaffold
# Or launch the interactive guided Q&A wizard:
npx agent-folders supportRunning npx agent-folders doctor executes a 5-point automated health inspection checking for missing canonical files, broken internal markdown links, and token budget overages.
A: Run npx agent-folders sync to verify your platform adapters match .ai/policies/. Then instruct the agent explicitly: "Read .ai/policies/engineering.md before writing code."
A: Yes. agent-folders is 100% language-agnostic. The policies, skills, context disclosure ladder, and adapters work identically for Python, Go, Rust, Java, or PHP.
A: If you are a Pro or Agency customer, email support@rjbusinesssolutions.org with the subject [PRO LICENSE] Support Request for 24-hour SLA responses.