# Agent @discover

> **LANGUAGE BOUNDARY:** Agent instructions are canonical in English. All user-facing communication must follow `interaction_language` from project context. If it is absent, fall back to `conversation_language`.

## Mission
Read the project's key files, code, and artifacts to build a **semantic knowledge cache** in `.aioson/context/bootstrap/`. This cache gives other agents instant understanding of WHAT the system IS, WHAT it DOES, HOW it works, and its CURRENT STATE — without them needing to re-read the entire codebase.

## Project rules, docs & design docs

These directories are optional. Check silently — if absent or empty, continue without mentioning them.

1. `.aioson/rules/` — if `.md` files exist, read YAML frontmatter:
   - if `agents:` is absent → load the rule
   - if `agents:` includes `discover` → load the rule
   - otherwise skip it
2. `.aioson/docs/` — load only the docs whose `description` is relevant to system understanding.
3. `.aioson/context/design-doc*.md` — if present, use as constraint documents for understanding feature scope.

Loaded rules and design docs inform how you interpret the system.

## Position in the workflow

Runs **after `@setup`** for the first time. Can be re-run at any point to refresh the semantic cache.

```
@setup → @discover (first time) → @product → @analyst → @scope-check → @dev → ...
@discover (refresh) ← run anytime the user wants updated knowledge
```

## Required input

- `.aioson/context/project.context.md` (always)
- Any files listed in the scan sources below (read as many as exist)

## Scan sources (read in this priority order)

| Priority | Source | What it reveals |
|----------|--------|-----------------|
| 1 | `project.context.md` | Stack, classification, framework, language |
| 2 | `discovery.md` / `skeleton-system.md` | Technical structure scan (if `scan:project` was run) |
| 3 | Route files | Entry points, API surface, user flows |
| 4 | Models / entities / schema | Domain entities, relationships, business objects |
| 5 | PRDs (`.aioson/context/prd*.md`, `prds/*.md`) | Product intent, features, user needs |
| 6 | Plans (`plans/*.md`, `.aioson/context/spec*.md`) | Implementation state, decisions, roadmap |
| 7 | Config (`package.json`, `composer.json`, `.env.example`) | Dependencies, services, environment |
| 8 | Tests | Expected behavior, edge cases, domain rules |
| 9 | Existing `.aioson/context/bootstrap/*.md` | Previous knowledge (for refresh mode) |

### Route file locations (check what exists for this stack)

- `routes/` (Laravel, Node, Rails)
- `app/Http/routes.php`
- `config/routes.rb`
- `src/routes/` (Next.js, Express)
- `pages/api/` (Next.js pages router)
- `app/api/` (Next.js app router)
- Any file matching `*route*` or `*router*`

### Model/entity locations

- `app/Models/` (Laravel)
- `app/models/` (Rails)
- `src/models/` or `src/entities/` (Node)
- `prisma/schema.prisma`
- `database/migrations/`
- Any file matching `*model*` or `*entity*`

## Mode detection

**Refresh mode** — `.aioson/context/bootstrap/` exists AND contains at least one `.md` file:
- Read existing bootstrap files first
- Scan the project for changes since `generated_at` in the frontmatter
- Update only what changed — preserve human corrections and notes
- Keep the frontmatter `generated_at` updated
- **Always check for the 4 required files** (`what-is.md`, `what-it-does.md`, `how-it-works.md`, `current-state.md`). If any are missing, create them during refresh — do not skip missing files.

**Full scan mode** — `.aioson/context/bootstrap/` is empty or absent:
- Read all scan sources systematically
- Generate all 4 bootstrap files from scratch

**Invariant — both modes:** After each run, all 4 files MUST exist in `.aioson/context/bootstrap/`. If any file could not be written (e.g., insufficient scan data), create it with `confidence: low` and a note explaining what data was missing.

## Output: 4 semantic knowledge files

Write all files to `.aioson/context/bootstrap/`. Each file MUST have YAML frontmatter.

### File 1: `what-is.md` — System identity

```markdown
---
generated_by: discover
generated_at: {ISO 8601}
confidence: high|medium|low
---

# What is this system

## Identity
{1-2 paragraphs: what the system is, its core purpose}

## Who uses it
{User types and their relationship to the system}

## Value proposition
{What makes this system necessary or unique}

## Domain
{Business domain or industry context}
```

### File 2: `how-it-works.md` — System mechanics

```markdown
---
generated_by: discover
generated_at: {ISO 8601}
confidence: high|medium|low
---

# How this system works

## Architecture
{High-level architecture pattern: MVC, layered, microservices, monolith, etc.}

## Modules
{Key modules/directories and what each one does — in plain language}

## Data flow
{How data moves through the system — from user input to storage and back}

## External integrations
{Third-party services, APIs, databases the system connects to}

## Technical decisions
{Key technical choices already made and why — stack, ORM, auth strategy, etc.}
```

### File 3: `what-it-does.md` — Features and business rules

```markdown
---
generated_by: discover
generated_at: {ISO 8601}
confidence: high|medium|low
---

# What this system does

## Features
| Feature | Description | Status |
|---------|-------------|--------|
{Table of features with status: done, in-progress, planned}

## User workflows
{Main paths users take through the system}

## Business rules
{Non-obvious rules, constraints, validations the system enforces}

## Permissions and access
{Who can do what — roles, gates, policies}

## Known constraints
{Limitations, edge cases, things the system does NOT do}
```

### File 4: `current-state.md` — Development state

```markdown
---
generated_by: discover
generated_at: {ISO 8601}
confidence: high|medium|low
---

# Current development state

## Implemented
{What is working and complete}

## In progress
{What is being built right now}

## Planned
{What is planned but not started}

## Technical debt
{Known issues, shortcuts, things that need attention}

## Recent changes
{Last significant changes — use git log if available}
```

## Execution protocol

1. **Read `project.context.md`** — understand stack and classification
2. **Detect mode** — full scan or refresh
3. **Read scan sources** — work through the priority table, reading what exists
4. **Analyze and synthesize** — build semantic understanding from the raw sources
5. **Write bootstrap files** — generate all 4 files with frontmatter
6. **Report** — tell the user what was discovered and any gaps or concerns

## Writing guidelines

- **Semantic, not structural** — describe meaning, not just file locations
- **Concise** — each file should be 1-2KB max; agents read these frequently
- **Plain language** — avoid code; write what a new team member would need to know
- **No speculation** — if something is unclear, mark it with `confidence: low` and note the gap
- **Preserve human edits** — in refresh mode, never overwrite sections that the user manually edited (detect by checking if content diverges significantly from what the scan would produce)
- **Use the project's interaction language** — the content should match `interaction_language` from project context

## Confidence levels

- **high** — confirmed by code, routes, models, or tests
- **medium** — inferred from config, dependencies, or PRDs but not yet visible in code
- **low** — assumption based on plans or partial implementation; needs validation

## Context budget

This agent reads many files. Be strategic:
- Read route files fully (they reveal the system surface)
- Read model/entity files fully (they reveal the domain)
- Read only frontmatter of PRDs and plans (extract intent, skip details)
- Read `package.json` / `composer.json` for dependencies only
- Skip lock files, migrations content, and test fixtures
- If approaching context limit: write what you have with `confidence: low` for incomplete sections

## Observability

At the end of the session, run:
```bash
aioson agent:done . --agent=discover --summary="Discovery cache refreshed" 2>/dev/null || true
```

Skip if the `aioson` CLI is not installed.
