# Adding AIOSON to an existing project > **Who this is for:** you already have a codebase and want to bring AIOSON into it. > **Execution time:** 20–60 min, depending on project size. > **What you'll have at the end:** AIOSON installed, initial context mapped, and the first feature of the new era ready to run. --- ## First rule: nothing will be overwritten `aioson install` is **additive**. It creates the `.aioson/`, `.claude/`, etc. directories, and adds `CLAUDE.md`, `AGENTS.md`, `OPENCODE.md` files to the root. It **does not touch**: - Your code (`src/`, `app/`, etc.) - Your `package.json` / `pyproject.toml` / `Gemfile` - Your `.gitignore` (on updates) - Your infra (`Dockerfile`, CI configs) If you ever want to leave, just delete `.aioson/` and the `CLAUDE.md`/`AGENTS.md`/`OPENCODE.md` files. --- ## Step 1 — Install ```bash cd my-existing-project npx @jaimevalasek/aioson install ``` The interactive wizard appears: ``` ? Which AI tools? › ◉ Claude Code ◉ Codex CLI ◯ OpenCode ? Mode? › ◉ Development ◯ Development + Squads ? Agent language? › ◉ English ◯ Português ◯ Español ◯ Français ``` > **Tip:** `--all` installs everything without the wizard (all tools, Development+Squads mode). `--no-interactive` for CI. --- ## Step 2 — Scan the project ```bash npx @jaimevalasek/aioson scan:project ``` The scan will: - Detect language, framework, package manager - Map the folder structure - List dependencies - Save to `.aioson/context/scan-*.md` > Don't confuse `scan:project` with `@discover` — the **scan** is static (file analysis). **`@discover`** goes further: it builds a semantic cache with a search index. --- ## Step 3 — Run `@setup` ```bash claude . # or: codex . / opencode . ``` Inside the AI client: ``` You > @setup @setup > Detected: Node.js + Next.js + Postgres + Prisma. Confirm? You > Yes @setup > How many user types currently exist in the project? You > Admin, customer, supplier (3) @setup > External integrations? You > Stripe, SendGrid, S3 (3) @setup > Complex business rules (calculations, conditional flows)? You > Yes — discount policy by customer tier, commission rules @setup > Score: 2 + 2 + 2 = 6 → MEDIUM. @setup > Interaction language? › English @setup > project.context.md created with MEDIUM classification. @setup > Since you already have running code, I recommend: - Run @discover to build the semantic cache - Start the feature with @product - Let @product capture domain rules and @planner map the code as the feature needs ``` --- ## Step 4 — `@discover` indexes the knowledge ``` You > @discover @discover > Indexing .aioson/context/bootstrap... - 1,247 files analyzed - 84 semantic entities extracted - 23 flows identified - Cache ready at .aioson/brains/discover/ @discover > When any agent needs something from the codebase, it queries this cache instead of scanning everything. Saves a lot of context. ``` This step is **optional for small projects**, but critical in medium and large codebases (>5k files). --- ## Step 5 — Domain and codebase questions stay in the main cycle The semantic cache is already available to Product, Sheldon, Planner, DEV, and QA. There is no separate discovery stage: `@product` records the domain rules a feature depends on (entities, states, business rules), and `@planner` does the repo discovery and code map for the plan. > **Why this matters:** when you create the next feature with `@product`, it will already come with **context**. The agent knows Customer already exists and won't suggest creating it again. --- ## Step 6 — First feature of the new era ``` You > @product @product > We have the base mapped. What feature? You > "order-cancellation" — allow canceling an order within 1 hour @product > Acceptance criteria? You > [...] @product > PRD saved to prd-order-cancellation.md. Next: @sheldon for the mandatory independent review. ``` From there, the canonical flow applies at MEDIUM depth: `@product → @sheldon → @planner → @dev → @qa`. Product owns one PRD, Sheldon independently reviews and seals it, Planner owns one implementation plan, and QA writes one evidence-backed verdict. Domain rules live in the PRD, architecture decisions and code mapping live in the plan, and scope drift is checked by QA and the engine's scope drift gate. See [Full feature with mandatory @sheldon review](../3-recipes/full-feature-with-sheldon.md) for the walkthrough. --- ## Special cases ### I have legacy code without tests Explicitly opt into **`@tester`** when you want systematic test engineering beyond the canonical QA review. Classification does not enable it. ``` You > @tester @tester > Current coverage: 12%. Quality tier: LOW. @tester > Strategy: cover the 5 most critical modules first (auth, payments, orders, discounts, webhook handler). ``` ### I want a security audit before touching anything ``` You > @pentester @pentester > Mapping attack surfaces (OWASP Top 10 + LLM Top 10 + supply chain). ... Findings: - HIGH: /admin/* routes without rate-limiting - MEDIUM: dependency X with known CVE - LOW: error logs leak email addresses Saved to context/security-findings-project.json ``` ### I want to migrate understanding between AI clients The `.aioson/` files are **client-agnostic**. You use Claude Code today, switch to Codex tomorrow on the same project: ```bash npx @jaimevalasek/aioson install --reconfigure # Also mark Codex CLI in the wizard ``` The `.codex/` and `AGENTS.md` files appear. Agents read the same files as before. ### I have code rules I need to enforce Create `.aioson/rules/.md`. Example: ```markdown # .aioson/rules/no-direct-db-from-controllers.md Controllers never access the ORM directly. Always via the service layer. ``` Every technical agent (`@dev`, `@qa`, etc.) loads applicable rules automatically. See [Design Docs Governance (PT)](../../pt/5-referencia/design-docs-governance.md). ### Whole team on the same project Commit the `.aioson/` folder. Every developer will have the same agent team, the same rules, the same Constitution. Keep only `.aioson/runtime/` in `.gitignore` (local telemetry). --- ## Quick verification After install, these commands should work: ```bash # 1. General diagnostics npx @jaimevalasek/aioson doctor # 2. Project state npx @jaimevalasek/aioson workflow:next . # 3. Confirm context is OK cat .aioson/context/project.context.md # 4. Inside the AI client > @neo ``` --- ## Next step - Want to understand which classification makes sense? → [Initial decisions](./initial-decisions.md) - How does continuity between sessions work? → [Continuity between sessions](../3-recipes/continuity-between-sessions.md) - Team overview → [Ecosystem map](../1-understand/ecosystem-map.md)