# BitoAIArchitect — Cross-Repo Intelligence

BitoAIArchitect is a pre-indexed knowledge base of **your organization's indexed repositories** — code, dependencies, API contracts, architecture patterns, tech stacks, business rules, and live production signals — that local files cannot show you. Local files show the file in front of you; BitoAIArchitect shows how it connects to everything else.

Use it alongside local exploration, in parallel rather than as a fallback, whenever a task touches code, repositories, architecture, dependencies, or implementation. Don't answer cross-repo or architecture questions from memory or a partial snippet — verify against the index first. Don't ask permission to search; call the relevant tool.

## What It Answers

Reach for it based on what the task needs to know, not on literal words in the prompt. Call a tool when you need:

- **Discovery** — which repositories exist, what one contains, what it depends on.
- **Code & patterns** — where something lives, how a feature works, an existing pattern to follow before writing new code.
- **Architecture** — cross-repo design patterns, API contracts, how the system decomposes into subsystems, and what a change would affect.
- **Knowledge** — business rules, glossary terms, conventions, and past architecture decisions that span repos.
- **Health & risk** — code-health, hotspots, ownership, and plan-vs-execution drift (git-derived).
- **Production** — live runtime behavior: error rates, latency, SLOs, and recent incidents.

## Choosing a Tool

Pick the tool whose description matches what the task needs, and follow that description for parameters and efficiency notes. When a tool's description and these guidelines conflict, follow the description.

## Call Contract

- Pass `purposeType` (enum) and `purpose` (≤500 chars, why this call) on every call — omitting either fails validation. Keep `purposeType` constant across one workflow.
  - Example: `searchSymbols({ pattern: "logger", isRegex: true, purposeType: "code_generation", purpose: "Find existing logging patterns before adding new logs" })`
- Pass `callerPlatform` (required string) identifying your platform on every call — same enforcement as purposeType. Use a short uppercase identifier for your platform (e.g. SLACK, JIRA, LINEAR, CLAUDE_CODE, CURSOR, WINDSURF, COPILOT).
- Pass `callerRequestId` (optional) with a unique ID for this request or session (request_id, event_id, session ID).
- Pass `callerGroupKey` (optional) with a grouping key that ties related calls together (channel_id, issue_key, project name).
- Treat repository names as case-sensitive. Don't guess them — discover the exact name first (e.g. `listRepositories` / `searchRepositories`).
- Start narrow and widen only if needed: prefer a schema or summary view before a full fetch, and extract a single field surgically instead of pulling a whole repository.

## Habits That Pay Off

| Don't | Do instead |
|---|---|
| Fetch an entire repository to read one field | Extract that field surgically |
| Make N separate calls to compare repos | Make one cross-repo query over the same field |
| Guess a repo name | Discover the exact (case-sensitive) name first |
| Treat git-derived code-health as production health | Use the code-health tool for code-health, the observability tool for live production signals |

## Example Workflows

- **Add a component** → find a relevant pattern (`searchSymbols`) → read it (`getCode`) → follow it.
- **"What handles [feature]?"** → `searchRepositories` → `getRepositoryInfo` → drill with `getFieldPath`.
- **"Is this claim about another repo true?"** → `searchWithinRepository` / `searchCode` → confirm on source with `getCode`.

## Available Skills

Invoke a skill by describing the task — the agent matches it to the right skill.

| Skill | Trigger Phrases | What It Does |
|-------|----------------|-------------|
| **bito-prd** | "write a PRD", "product requirements for", "what should this feature do" | Define WHAT to build — requirements, user stories, scope |
| **bito-trd** | "write a TRD", "design the implementation", "technical design for", "architecture for this feature" | Design HOW to build — technical design / architecture an engineer can code from |
| **bito-build-plan** | "plan this work", "plan this feature/story", "break down this ticket", "create plan from story" | Convert any unit of work into a sprint-ready plan with effort estimates |
| **bito-feature-plan** | "plan this one feature to build myself", "build-ready plan for a feature" | Single-engineer, single-feature build-ready implementation plan |
| **bito-feasibility** | "is this feasible", "impact analysis", "go/no-go" | Go/no-go feasibility and impact analysis before committing |
| **bito-spike** | "run a spike", "investigate feasibility", "technical exploration" | Structured technical investigation of feasibility, options, and risks |
| **bito-codebase-explorer** | "explore codebase", "explain architecture", "how does this work" | Explore any codebase from high-level architecture to line-level traces |
| **bito-code-review** | "review my PR/MR", "review my changes", "review staged/unstaged", "audit this branch" | Review code at any target with cross-repo impact; covers pre-commit review |
| **bito-production-triage** | "production issue", "incident triage", "prod is down", "triage this error" | Production incident diagnosis and triage |
| **bito-plan-to-coding-tasks** | "turn this plan into coding tasks", "make this implementable by an agent" | Transform an implementation plan into self-contained workstream coding tasks |
| **bito-coding-task-executor** | "execute this coding task", "implement this workstream coding task" | Execute a workstream coding task with verification gates + two-stage review |

## Routing: planning, designing, and implementing changes

When a request implies building something, route it to the right Bito skill before writing code yourself. These rules disambiguate the common overlaps:

- **Requirements vs design vs plan.** "What should this do / what are the requirements?" → **bito-prd**. "How should we build or architect this?" (technical design) → **bito-trd**. "Turn this into a sprint-ready plan or tickets" → **bito-build-plan**. A single engineer planning one feature to code themselves → **bito-feature-plan**.
- **Implementing a change that isn't planned yet.** When the user asks to implement / build / add a **non-trivial** change with no plan, don't jump straight to code — plan it first, then implement against that plan. Pick the planning entry by scope: a single feature one engineer will build themselves → **bito-feature-plan**; anything larger (spans multiple files/services, touches data models or public APIs, has non-obvious edge cases, or needs an approach choice) → **bito-build-plan**, which already includes the technical design. Don't also run **bito-trd** — build-plan designs as part of planning.
- **Trivial changes go straight to code.** A typo, one-line fix, rename, or other small well-scoped edit does not need a plan or design — implement it directly. Don't force ceremony on small work.
- **"Design and implement X" together.** Run **bito-trd** for the design first, then implement against it.