# Phase 6 — Implementation Guide

> **Deliverable:** how to place, adopt, and maintain the `CLAUDE.md` documentation system.
> **Index:** [../README.md](../README.md)

## 1. File placement strategy
```
CLAUDE.md                        ← MUST stay at repo root (Claude Code auto-loads it)
docs/phases/                     ← everything else, organized by phase
├── README.md
├── phase-1-analysis/ANALYSIS.md
├── phase-2-components/COMPONENT_*.md
├── phase-3-shared/MASTER_*.md
├── phase-4-master/ORCHESTRATOR.md
├── phase-5-validation/VALIDATION.md
└── phase-6-implementation/IMPLEMENTATION_GUIDE.md
```
- All docs are version-controlled with the code so they evolve together.
- Keep links **relative**; if you move a file, re-run a link check (grep for `](` targets) and fix.

## 2. How Claude Code uses it
- The root `CLAUDE.md` is loaded automatically and routes to the right component + shared rules.
- Reference specific files in a prompt with `@`-style paths, e.g.
  `@docs/phases/phase-3-shared/MASTER_RULES.md`.
- For a component task, open the matching Phase 2 doc; for cross-boundary work, start at
  `MASTER_INTEGRATION.md`.

## 3. Team adoption
1. **Announce** the entry point: "read root `CLAUDE.md` first."
2. **Onboarding:** new devs read Phase 1 (what the system is) → the component doc for their area.
3. **PR checklist:** adopt the Definition of Done from `MASTER_RULES.md` (gated route, FormRequest,
   activitylog, reversible migration, Pint+Pest, no copy/backup files).
4. **Feedback loop:** capture doc gaps as issues; fold fixes into the relevant phase folder.

## 4. Maintenance plan
| Trigger | Update |
|---------|--------|
| New module/controller | Component doc (Phase 2) + root routing table if it's a new boundary |
| New sync field/endpoint | Desktop doc + `MASTER_INTEGRATION.md §2` (both Push & Pull) |
| New shared rule/command/tool | The relevant `MASTER_*` file (Phase 3) |
| Ledger/costing change | Web core §accounting + `MASTER_INTEGRATION.md §1`; run `Test*` commands |
| Any file move | Re-run the link check; fix relative paths |

- **Ownership:** the core ERP team owns `MASTER_*` and the root orchestrator; each component doc is
  owned by whoever owns that code area.
- **Review cadence:** revisit the docs whenever a boundary or contract changes; treat stale docs as
  a bug.

## 5. Fill-in items (need team input)
- **Team size** and **development workflow** specifics.
- **CI/CD:** none detected in-repo. If added, wire `pint --test` + `php artisan test` as required
  checks and document the pipeline in `MASTER_TOOLS.md`.

## 6. Suggested next step
Open a small cleanup PR to remove the non-routed legacy duplicates flagged in Phase 1 / `MASTER_RULES`
(`*copy*.php`, `*_backup.php`, `Api/Backup/`, `extra/GatepassController1.php`), so the tree matches the
documented rules.