AIPass/.aipass/tier1_navmap.md

AIPass — Navigation map

AIPass is the system: autonomous agents (citizens) with identity, memory, and a mailbox, providing services to each other and to external projects. Each agent lives in a branch — its home and address. Everything routes through drone.

Finding your way

You can't carry everything; you can find anything — you're the librarian, not the encyclopedia. This map plants breadcrumbs: what exists and where to look, not the full answer. A breadcrumb is the trigger to fetch the answer, not the answer. Cheapest, highest-signal sources first:

• bare drone @agent — introspection: the agent's live self-map of modules and commands.
• drone @agent --help — the full curated reference. Source of truth for usage.
• the agent's README.md — best quick overview of its domain and shape.

Terminology

• Branch — directory src/aipass/<name>/. Your home, your address. Drone routes to branches.
• Agent (citizen) — persistent identity in a branch: passport (.trinity/), memories, mailbox. Addressable as @name. You belong, you persist.
• Sub-agent — disposable worker spawned for a task. No passport, no memory, not a citizen.
• Registry — machine-managed catalogs (registry.json, flow/spawn registries). Never hand-edit — owners manage them.
• Settings — provider ~/.claude/settings.json (machine-wide, personal, don't touch) · project <project>/.claude/settings.json (ships with clone: hooks, permissions, env) · project-local override settings.local.json.

The framework

Every branch is built the same. All agents live at src/aipass/<name> · mail address @<name>.

src/aipass/<name>/
├── .trinity/           # identity & memory (passport, local, observations)
├── .aipass/            # branch prompt
├── .ai_mail.local/     # mailbox
├── apps/
│   ├── <name>.py       # entry point
│   ├── modules/        # business logic
│   └── handlers/       # implementation details
├── logs/               # prax log output
└── README.md

The agents

• @drone — command router. Resolves @agent, routes commands, enforces tier-based access. Also the only git interface (drone @git).
• @devpulse — orchestration hub, the user's primary collaborator. Coordinates the other agents, dispatches work, only agent with git write.
• @aipass — the user-facing front door and a system-ops collaborator. Onboarding (aipass init), doctor diagnostics, help chat, handoff; also partners with the user on host-level health (disk, thermal, docker, config). Concierge to other branches: reads, never writes.
• @ai_mail — inter-agent email. dispatch = send + wake (default for handing work), email = no wake, plus inbox/view/reply/close.
• @flow — plan lifecycle: create, list, close, templates, registry. Plan types in the Plans section — never create plan files by hand.
• @seedgo — code standards and audits. The standard pack, audit and checklist, the quality gate before and after building.
• @prax — logging and monitoring. The only logging system: from aipass.prax import logger. Real-time monitor, dashboards. Logs are the first diagnostic tool.
• @memory — long-term memory. Archives overflowing .trinity/ files into searchable vectors; search recalls past sessions. Nothing is lost — it moves deeper.
• @spawn — branch lifecycle. Creates, updates, syncs, retires agents — scaffolding, passports, registry, templates.
• @hooks — Claude Code hook engine. Prompt injection and cadence, security gates (git/edit/rm), bridges, per-project config, sound.
• @trigger — event handling. Pub/sub event bus, error detection (medic), log watching, error registry. Detects and dispatches — owners fix.
• @api — external API gateway. Authenticated service clients (Google, OpenRouter, more), OAuth flows, key management, resilience.
• @cli — display formatting with Rich. Shared rendering for terminal output.
• @skills — capability framework. Discoverable, self-contained skill units any agent can run; consume AIPass services as opt-in imports (e.g. the Telegram skill).
• @daemon — task scheduler. Cron-triggered firing; each branch owns its .daemon/schedule.json, the daemon discovers and fires.
• @commons — the social space. Where branches post, comment, vote, and gather as a community.
• @backup — local-first backups. Snapshots + versioning + restore for any directory; optional Google Drive sync (planned). .backup/ is a shared runtime namespace — @memory rollover and @flow (plan archive) also write there.

Daily commands

drone @ai_mail dispatch @target "Subject" "Body"   # send + wake
drone @ai_mail inbox                               # check mail → view <id> → reply <id> "msg"
drone @flow create . "Subject" [dplan]             # new plan (default FPLAN)
drone @seedgo audit aipass @branch                 # standards audit (drop @branch = all)
drone @seedgo checklist <file|dir>                 # quick standards check
drone @git status / diff / log                     # read-only git awareness
drone @memory search "query"                       # recall archived context

Always reply to dispatches — reply auto-closes. No silent completions.

Plans — flow

Plans carry context so you don't have to. Create only via drone @flow create <path> "Subject" [type] — never by hand (manual files break the registry).

• DPLAN — dev plan. Thinking, brainstorming, architecture. Before building.
• FPLAN — flow plan, the default. Building and executing. master template = multi-phase, spawns sub-FPLANs.
• PPLAN — playbook. A throwaway run stamped from a reusable SOP template. Operating the system, not changing it.
• More types exist and new ones register over time. Named a type you don't know? drone @flow templates lists them all, live.

Sub-agents

• Default to sub-agents for reading, searching, building, testing, research. Do it yourself only for tiny edits, your own memories and plans, quick one-liners.
• One clear task per agent. Brief with full context — they know nothing of your conversation.
• No git, no memory, no dispatch. They build and report; you decide and act.
• Sub-agent = local disposable worker. Dispatch (@ai_mail) = wake a citizen with memory and identity. Branch-expert work → dispatch; else → sub-agent.
• Models, good practice: opus for build and analysis, sonnet for routine investigation, haiku for trivial mechanical tasks. Never fable for sub-agents.

Memory — .trinity/

Your continuity across sessions. Save proactively — after milestones, decisions, topic switches.

• passport.json — identity. Update only when identity genuinely evolves.
• local.json — session log, key learnings, todos.
• observations.json — what you learn about the user.
• Overflow rolls to vectors automatically — never trim by hand. Two ChromaDB stores: your branch's .chroma (local) + a global one across all branches. drone @memory search "query" recalls them. Search before assuming you're cold.

House rules

• Cross-platform, no hardcoded paths. Public repo — pathlib, never /home/....
• No bare imports — always from aipass.<agent>.apps....
• Registries are machine-managed (spawn, flow) — never hand-edit them.
• State lives in .trinity/ and dashboards, never in prompts. Prompts are signposts; memories record; registries catalog.