# SESSION START — Coding Agent Onboarding for a Multi-Repo Project

**Purpose:**
This is the single document a coding agent should read at the start of any new coding session.

It tells the agent:

- which repository it is working in,
- which other repositories are related,
- which documents to read,
- in what order,
- which files are source of truth,
- which decisions are deferred,
- how frontend, backend, database, and infrastructure relate,
- and how to work without guessing.

Use this file as the durable entry point for AI coding agents working on large projects.

---

## 1. Project context

> Replace this section with your real project context.

**Project name:** `<PROJECT_NAME>`

**What the project does:**
`<Explain the project from the customer/user perspective. Do not start with tech stack. Explain the business or product goal first.>`

**Primary users:**
`<Who uses this system?>`

**Critical workflows:**

1. `<Workflow 1>`
2. `<Workflow 2>`
3. `<Workflow 3>`

**What must not break:**

- `<Critical workflow or data path>`
- `<Critical integration>`
- `<Critical reporting, billing, compliance, or operational dependency>`

---

## 2. Repository map

| Repo           | Local path               | Role                                | Owns                                  | Depends on                  |
| -------------- | ------------------------ | ----------------------------------- | ------------------------------------- | --------------------------- |
| Backend API    | `<path/to/backend>`      | Primary backend service             | APIs, business logic, database models | DB, auth, external services |
| Frontend app   | `<path/to/frontend>`     | User interface / admin console      | Screens, forms, service calls         | Backend APIs                |
| Auth service   | `<path/to/auth-service>` | Authentication / user identity      | Users, sessions, tokens               | Backend/frontend            |
| Worker service | `<path/to/worker>`       | Background jobs                     | Async processing                      | Backend, queues, storage    |
| Infra repo     | `<path/to/infra>`        | Cloud / deployment / infrastructure | IaC, deployment config, env vars      | All services                |

Update this table whenever repo ownership changes.

---

## 3. Pick your task type before reading

| Your task is…        | Read first           | Then read                        |
| -------------------- | -------------------- | -------------------------------- |
| Backend only         | Backend prompt       | Backend reading list             |
| Frontend only        | Frontend prompt      | Frontend reading list            |
| Cross-stack          | Cross-stack rules    | Backend + frontend lists         |
| Database / migration | Backend prompt       | Data model docs + migration docs |
| Infrastructure       | Infra prompt         | Deployment docs + env var docs   |
| Bug fix              | RCA protocol         | Impact analysis docs             |
| New feature          | Requirement protocol | Design docs + affected repo docs |

---

# Backend Prompt

Copy this prompt into the coding agent, then append the task.

```text
You are a coding agent working on <BACKEND_REPO_PATH>.

This repository is responsible for:
- <API/domain responsibility>
- <business logic responsibility>
- <database responsibility>
- <integration responsibility>

Do not start coding until you have read the documents below in order.

These documents are the project memory. Read them before guessing.

==================================================
TIER 0 — ALWAYS READ FIRST
==================================================

1. <docs/PROJECT_OVERVIEW.md>
   High-level project goal, product context, users, and critical workflows.

2. <docs/ARCHITECTURE.md>
   Current architecture, service boundaries, dependencies, deployment assumptions, and major data flows.

3. <CLAUDE.md / AGENTS.md / MEMORY.md>
   Coding rules, review expectations, testing commands, documentation update rules, and agent behavior rules.

4. <docs/DOCUMENTATION_INDEX.md>
   Navigation map for all major docs.

==================================================
SOURCE-OF-TRUTH RULES
==================================================

- For implemented behavior, code is the source of truth.
- For intended product behavior, read the product/design spec.
- For database structure, read actual models/migrations before relying on old docs.
- Where docs and code disagree, flag the drift before changing behavior.
- Do not silently "fix" code to match outdated documentation.
- Do not invent missing business rules.
- If a design decision is ambiguous, stop and ask.

==================================================
TIER 1 — CURRENT STATE AND BACKLOG
==================================================

Read before deciding what to build:

1. CHANGELOG.md
   Read the latest entries to understand what changed recently.

2. TODO.md or docs/TODO_<MODULE>.md
   Active work list, status, open issues, and pending tasks.

3. DESIGN_<MODULE>.md
   Current design for the module you are touching.

4. DEFERRED_<MODULE>.md
   Deferred decisions and why they were deferred.

5. WORKING_<MODULE>.md
   Current build notes, in-progress design, and active implementation context.

6. IMPACT_<MODULE>.md
   Known blast radius, callers, dependent screens, APIs, database tables, jobs, and integrations.

==================================================
TIER 2 — DEEP CONTEXT
==================================================

Read only the documents relevant to the task:

- <docs/domain/module/README.md>
- <docs/domain/module/gap_analysis.md>
- <docs/domain/module/test_scenarios.md>
- <docs/domain/module/api_contract.md>
- <docs/domain/module/data_model.md>
- <docs/domain/module/integration_notes.md>

==================================================
HOW TO WORK
==================================================

Before coding:

1. Restate the requirement in functional terms.
2. Identify affected files, APIs, tables, jobs, screens, and integrations.
3. Perform impact analysis.
4. Identify risks and possible regressions.
5. Propose the implementation plan.
6. Wait for approval if the task has high blast radius.

During coding:

1. Follow existing code patterns.
2. Keep changes minimal and scoped.
3. Do not change API contracts unless required.
4. Do not change database models without migration impact analysis.
5. Do not remove existing behavior unless explicitly instructed.

After coding:

1. Run relevant tests.
2. Add or update tests where needed.
3. Update CHANGELOG.md.
4. Update TODO_<MODULE>.md.
5. Update DESIGN_<MODULE>.md if design changed.
6. Update DEFERRED_<MODULE>.md if any decision was deferred.
7. Report exactly what changed and what was tested.

My task for this session is:

<APPEND TASK HERE>
```

---

# Frontend Prompt

Copy this prompt into the coding agent, then append the task.

```text
You are a coding agent working on <FRONTEND_REPO_PATH>.

This repository is responsible for:
- screens,
- forms,
- navigation,
- API service calls,
- client-side state,
- UX validation,
- and frontend integration with backend services.

This frontend does not own business rules. Business correctness belongs to the backend unless explicitly documented otherwise.

Do not start coding until you have read the documents below in order.

==================================================
TIER 0 — ALWAYS READ FIRST
==================================================

1. docs/ARCHITECTURE.md
   Frontend architecture, app structure, routing, state model, auth/session model, backend topology, and env vars.

2. docs/API_INTEGRATION.md
   Service layer, API client rules, request/response handling, headers, errors, and backend ownership.

3. docs/CONVENTIONS.md
   Component structure, page/client split, styling, forms, toasts, service functions, and known smells.

4. CLAUDE.md / AGENTS.md / MEMORY.md
   Project-specific agent rules, test commands, review expectations, and documentation update rules.

==================================================
FRONTEND LAWS
==================================================

- The frontend owns UX, not business truth.
- Do not hardcode tenant, company, org, or user identifiers unless the project explicitly allows it.
- Do not call APIs directly from components if the project uses a service layer.
- Do not invent backend fields.
- Confirm request and response contracts against the backend.
- If backend behavior is unclear, inspect the backend or ask.

==================================================
TIER 1 — ORIENTATION MAPS
==================================================

Read the relevant files:

1. docs/SCREEN_MAP.md
   Route -> screen -> component -> service -> backend endpoint.

2. docs/TODO_FRONTEND.md
   Current frontend gaps and active tasks.

3. docs/DESIGN_<MODULE>.md
   Current frontend design for the feature or module.

4. docs/IMPACT_<MODULE>.md
   Known cross-screen and cross-service impact.

5. Shared API contract docs
   Usually maintained in backend or shared docs.

==================================================
HOW TO WORK
==================================================

Before coding:

1. Find the screen and component.
2. Find the service file.
3. Confirm the backend endpoint.
4. Confirm payload and response shape.
5. Check related screens using the same service or data model.
6. Perform impact analysis.

During coding:

1. Follow existing component and service patterns.
2. Keep business rules out of the frontend unless documented.
3. Preserve existing UX behavior unless instructed.
4. Avoid changing shared services without checking all callers.

After coding:

1. Run lint/tests/build commands.
2. Exercise the screen locally where practical.
3. Update CHANGELOG.md.
4. Update TODO_FRONTEND.md.
5. Update DESIGN_<MODULE>.md if design changed.
6. Report what changed and what was tested.

My task for this session is:

<APPEND TASK HERE>
```

---

# Cross-Stack Rules

Use this section when a task spans frontend, backend, database, worker jobs, infrastructure, or more than one repository.

## 1. Read both sides

Do not assume the other repository's behavior.

Read:

- frontend screen map,
- frontend service file,
- backend route,
- backend handler/service,
- data model,
- migration,
- background jobs,
- infrastructure dependencies,
- and shared API contract.

## 2. Identify ownership first

Before changing anything, answer:

- Which repo owns the business rule?
- Which repo owns the data?
- Which repo owns validation?
- Which repo owns authorization?
- Which repo owns display behavior?
- Which repo owns background processing?
- Which repo owns external integration?

Do not fix a frontend symptom if the backend contract is wrong.
Do not change backend behavior without checking frontend callers.

## 3. Build the impact map

For every cross-stack task, produce this before coding:

| Area               | Impact                        |
| ------------------ | ----------------------------- |
| Frontend screens   | `<screens affected>`          |
| Components         | `<components affected>`       |
| API endpoints      | `<endpoints affected>`        |
| Backend functions  | `<functions affected>`        |
| Database tables    | `<tables affected>`           |
| Jobs/queues        | `<jobs affected>`             |
| Cloud/storage      | `<resources affected>`        |
| Tests              | `<tests to run>`              |
| Regression risk    | `<risks>`                     |
| Deferred decisions | `<decisions not handled now>` |

## 4. Sequence the change

Preferred sequence:

1. Confirm backend contract.
2. Confirm data model.
3. Update backend if needed.
4. Add or update backend tests.
5. Update frontend service layer.
6. Update screen/component behavior.
7. Run frontend tests.
8. Run integrated/manual flow.
9. Update shared documentation.
10. Log changes in all touched repos.

## 5. Log on both sides

If both frontend and backend changed:

- update backend `CHANGELOG.md`,
- update frontend `CHANGELOG.md`,
- update shared API contract docs,
- update `DESIGN_<MODULE>.md`,
- update `TODO_<MODULE>.md`,
- update `DEFERRED_<MODULE>.md` if any decision was deferred.

---

# RCA Protocol for Bug Fixes

Before fixing a bug, the agent must produce:

1. Symptom
2. Reproduction path
3. Expected behavior
4. Actual behavior
5. Suspected root cause
6. Files inspected
7. Confirmed root cause
8. Proposed fix
9. Impact analysis
10. Tests to run
11. Regression risks

Do not implement until the root cause is identified.

---

# New Requirement Protocol

Before implementing a new requirement, the agent must produce:

1. Functional restatement
2. User/business goal
3. Affected workflows
4. Affected screens
5. Affected APIs
6. Affected tables
7. Affected jobs/integrations
8. Proposed design
9. Alternatives considered
10. Deferred decisions
11. Risks
12. Test plan
13. Documentation updates required

---

# Documentation Update Rules

At the end of every meaningful task, update the relevant docs.

## Required documentation files

| File                                    | Update when                                        |
| --------------------------------------- | -------------------------------------------------- |
| `TODO.md` / `TODO_<module>.md`          | Task status changes                                |
| `DESIGN_<module>.md`                    | Current design changes                             |
| `DEFERRED_<module>.md`                  | A decision is consciously postponed                |
| `CHANGELOG.md`                          | Any code, API, schema, behavior, or config changes |
| `MEMORY.md` / `CLAUDE.md` / `AGENTS.md` | Agent operating rules change                       |
| `IMPACT_<module>.md`                    | Blast radius knowledge changes                     |
| Shared API contract docs                | Request/response shape changes                     |

## Status labels

Use a consistent status legend:

- Done
- Built but unverified
- Open
- Needs decision
- Deferred
- Rejected

## Deferred decision format

Use this format in `DEFERRED_<module>.md`:

```markdown
## <Decision title>

**Status:** Deferred
**Date:** <YYYY-MM-DD>
**Reason for deferral:** <Why not now?>
**Current workaround:** <What are we doing instead?>
**Trigger to revisit:** <When should this be reopened?>
**Affected files/modules:** <List>
```

## Changelog format

Use this format in `CHANGELOG.md`:

```markdown
- **<Type> · <summary> — <files changed>:** <what changed + why + tested?> — _Directed by: <name>_ · _Impl: <agent/person>_ · _Status: <done|open|deferred>_
```

---

# Parallel Agent Rules

Use parallel agents only when work can be safely separated.

Before starting parallel work, define:

| Agent   | Tool     | Task     | Files/modules owned | Must not touch | Output expected |
| ------- | -------- | -------- | ------------------- | -------------- | --------------- |
| Agent 1 | `<tool>` | `<task>` | `<scope>`           | `<boundaries>` | `<deliverable>` |
| Agent 2 | `<tool>` | `<task>` | `<scope>`           | `<boundaries>` | `<deliverable>` |

Rules:

- Do not let two agents edit the same file unless explicitly coordinated.
- Tell every agent what the other agents are doing.
- Ask each agent to report integration risks.
- Merge only after human review.
- Run tests after integration, not only after isolated changes.

---

# Final Session Report Template

At the end of the session, the agent must report:

```markdown
## Session Report

### Task
<What was requested>

### Work completed
<What was changed>

### Files changed
<List files>

### Tests run
<Commands and results>

### Impact analysis
<Screens/APIs/tables/jobs/integrations affected>

### Documentation updated
<TODO / DESIGN / DEFERRED / CHANGELOG / MEMORY / API contract>

### Deferred decisions
<Anything postponed and why>

### Risks or follow-ups
<What still needs attention>

### Confidence
<High / Medium / Low, with reason>
```