@jaimevalasek/aioson 1.7.2 → 1.9.0

package/docs/en/1-understand/why-it-exists.md

@@ -0,0 +1,106 @@
+# Why AIOSON Exists
+
+> **Who this is for:** anyone already using AI to code who wants to understand the "why" behind the design.
+> **Reading time:** 7 min
+> **What you'll know after:** the 3 problems AIOSON solves, and the 6 principles of the Constitution.
+
+---
+
+## The 3 problems that motivated AIOSON
+
+### Problem 1 — The monolith prompt
+
+When you open an AI and type "build me a subscription SaaS with Stripe, auth, admin panel, and reports," you're asking it to be **everything at once**: Product Manager, architect, designer, backend dev, frontend dev, QA, security specialist.
+
+Typical result:
+- Important decisions are made implicitly, without you noticing.
+- The AI picks the first library that comes to mind instead of the right one.
+- When you ask for a tweak, it redoes three things that were already fine.
+- There's no audit trail: why did it choose Postgres? When? You can't find it.
+
+**How AIOSON solves it:** breaks the monolith into specialist agents. Each one has narrow focus, its own rules, and produces a verifiable artifact before handing off.
+
+### Problem 2 — Amnesia between sessions
+
+You work on a feature for 2 hours with the AI, go to sleep, come back the next day. What does the AI remember?
+
+- In IDEs without persistent memory: **nothing**.
+- In IDEs with memory: an approximate summary, usually dropping the "whys."
+
+**How AIOSON solves it:** decisions and context become **disk artifacts** (`project.context.md`, `spec.md`, `dossier.md`, `dev-state.md`, `project-pulse.md`). The next session reads those files before anything else. External memory, not model-internal memory.
+
+### Problem 3 — Inconsistency in the team
+
+In a team, each person has a different prompt style. Each AI client (Claude, Codex, Gemini) responds differently. The result is a codebase stitched together from different aesthetics and patterns.
+
+**How AIOSON solves it:**
+- The same agents (`.aioson/agents/`) are read by **any** AI client.
+- Project rules (`.aioson/rules/`) and governance (`.aioson/constitution.md`) are shared in Git.
+- New team members automatically inherit "how things are done here."
+
+---
+
+## The 6 principles of the Constitution
+
+AIOSON is governed by six articles that **no agent can override**. They live in `.aioson/constitution.md` and are cited by agents when they need to justify a decision.
+
+### Article I — Spec First
+> Features start as specification, not code. Implementation without a spec artifact is exploration, not development.
+
+**In practice:** `@dev` refuses to implement before reading a spec. This prevents you from waking up with 800 lines of code solving the wrong problem.
+
+### Article II — Right-Sized Process
+> MICRO, SMALL, and MEDIUM don't receive the same process depth. Applying MEDIUM ceremony to a MICRO project wastes more than it protects.
+
+**In practice:** the AI won't ask you for a 30-page PRD for a 50-line script. Each classification has its own flow.
+
+### Article III — Observable Work
+> Important actions leave visible artifacts or runtime signals. Work that exists only in conversation history is work that can be lost.
+
+**In practice:** if an agent makes an important decision, it appears in a file. You can review, veto, or roll back.
+
+### Article IV — Testable Behavior
+> Acceptance criteria must be independently verifiable. "Works correctly" is not a criterion. "Returns 403 when user A accesses user B's resource" is.
+
+**In practice:** `@qa` rejects vague ACs. You're forced to be specific before approving.
+
+### Article V — Clean Handoffs
+> Artifacts must be self-sufficient for the next agent to start without re-reading the entire chain. If the next agent needs to ask "where do I start?", the handoff failed.
+
+**In practice:** a feature's `dossier` includes everything: spec, decisions, touched code, status. When `@dev` hands off to `@qa`, `@qa` doesn't need to interview `@dev`.
+
+### Article VI — Simplicity Over Ceremony
+> Don't add layers, files, or workflows unless they reduce ambiguity down the line. Three similar lines are better than premature abstraction. A well-written spec is better than five thin artifacts.
+
+**In practice:** AIOSON constantly fights the temptation to add bureaucracy. **"Small project, small solution"** is the official motto.
+
+### Article VII — Zero Trust by Default
+> Security is a baseline, not a feature. Every technical agent (`@analyst`, `@architect`, `@dev`, `@qa`) consumes the baseline declared in `.aioson/rules/security-baseline.md`, with ID-versioned controls (`SEC-SBD-01..08`) that no one can silently weaken.
+
+**In practice:** `@dev` automatically knows it needs to sanitize input, validate authorization, and redact secrets. It's not an extra request from you — it's the default.
+
+---
+
+## The golden rule
+
+Above the 6 articles sits a phrase that appears in nearly every AIOSON prompt:
+
+> **Small project, small solution.**
+
+When you have to choose between an agent doing more things or fewer — always fewer. When you have to choose between creating one more artifact or making do with what already exists — always make do. AIOSON is proactively lazy, and that's a feature.
+
+---
+
+## What is NOT covered by the principles
+
+- **Personal code style.** AIOSON has no opinion on tabs vs spaces, eslint config, etc. That stays in your rules (`.aioson/rules/`).
+- **Technology stack.** Agents detect the project stack and adapt. AIOSON works in Node, Python, Go, Rust, PHP, Ruby, etc.
+- **Vendor lock-in.** Works with any AI client that reads `.md` files in the project.
+
+---
+
+## Next step
+
+- See the full team mapped out: [Ecosystem map](./ecosystem-map.md)
+- Full vocabulary: [Glossary](./glossary.md)
+- Put it into practice: [First project from scratch](../2-start/first-project.md)

package/docs/en/2-start/existing-project.md

@@ -0,0 +1,246 @@
+# 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
+   ◯ Gemini CLI
+   ◯ OpenCode
+
+? Mode? ›
+   ◉ Development
+   ◯ Development + Squads
+
+? Design system? ›
+   ◯ Clean SaaS UI
+   ◯ Aurora Command UI
+   ◯ (more options...)
+   ◉ Skip
+
+? 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 . / gemini . / 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
+        - Then @analyst to map the existing domain
+        - Only then start the next feature via @product
+```
+
+---
+
+## 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 — `@analyst` maps the existing domain
+
+```
+You > @analyst
+
+@analyst > [reads scan + @discover cache]
+        Identified:
+        - Customer, Supplier, Order, OrderItem, Payment, Discount, Commission
+        - Auth via NextAuth
+        - Active Stripe webhook
+        - Tier table in customer.tier (free|pro|enterprise)
+@analyst > Domain map saved to architecture.md.
+@analyst > Ready for the next feature.
+```
+
+> **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 > Spec saved. Next: @analyst.
+```
+
+From there the flow is the same as in [first-project.md](./first-project.md).
+
+---
+
+## Special cases
+
+### I have legacy code without tests
+
+Use **`@tester`** (not just `@qa`) — it does systematic test engineering for already-implemented apps. It recently gained *coverage quality tier* and *test smell audit*.
+
+```
+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/<name>.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 these rules automatically. See [Design Docs Governance](../5-reference/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)

package/docs/en/2-start/first-project.md

@@ -0,0 +1,307 @@
+# First project from scratch
+
+> **Who this is for:** anyone who has never used AIOSON and wants to run it once to understand it.
+> **Execution time:** 30–45 min.
+> **What you'll have at the end:** a simple web app (a to-do list) with a spec, code, tests, and a dossier — all traceable on disk.
+
+We're going to build a **mini TODO app** using the SMALL cycle. You'll see each agent enter, do its part, and hand off to the next.
+
+---
+
+## Prerequisites
+
+- **Node.js 18+** installed
+- An AI client configured: **Claude Code**, **Codex CLI**, **Gemini CLI**, or **OpenCode**. Examples here use Claude Code; switching is trivial.
+- A terminal open
+
+If you don't have an AI client yet: Claude Code is the most widely used by the AIOSON community. See [`clientes-ai.md`](../5-reference/clientes-ai.md).
+
+---
+
+## Step 1 — Create the project
+
+```bash
+npx @jaimevalasek/aioson init my-todo
+cd my-todo
+```
+
+The wizard will ask:
+
+```
+? Which AI tools? › Claude Code
+? Mode? › Development (no squads for now)
+? Design system? › (skip for now)
+? Agent language? › English
+```
+
+> **Beginner tip:** to skip the wizard and install everything, use `--all`. For CI environments, use `--no-interactive`.
+
+The command creates this structure:
+
+```
+my-todo/
+├── .aioson/         ← agents, rules, config
+├── .claude/         ← Claude Code integration
+├── CLAUDE.md        ← automatic instructions for Claude Code
+├── AGENTS.md        ← instructions for Codex
+└── (empty — no package.json yet)
+```
+
+---
+
+## Step 2 — Open the AI client in the project
+
+```bash
+claude .   # or: codex .   or: gemini .   or: opencode .
+```
+
+From here on, we'll interact with the AI.
+
+---
+
+## Step 3 — `@setup` handles onboarding
+
+```
+You > @setup
+```
+
+Expected dialogue (may vary):
+
+```
+@setup > Hello! I'll configure the context for this project.
+@setup > No stack detected yet. Starting from scratch — what type is it?
+        [web_app · api · site · script · dapp · desktop_app]
+You > web_app
+
+@setup > Preferred stack?
+You > Node.js + Express + SQLite
+
+@setup > How many user types?
+You > 1
+
+@setup > How many external integrations (APIs, gateways, etc.)?
+You > 0
+
+@setup > Any non-obvious business rules (special calculations, multi-condition flows)?
+You > No
+
+@setup > [calculates] Score: 0+0+0 = 0 → MICRO. But you asked for spec/tests...
+@setup > I recommend SMALL to have @qa at the end. Agree?
+You > Yes
+
+@setup > project.context.md created.
+@setup > Next agent: @product (to define the initial feature).
+```
+
+Look at what appeared on disk:
+
+```bash
+cat .aioson/context/project.context.md
+```
+
+```yaml
+---
+project_name: "my-todo"
+project_type: "web_app"
+profile: "developer"
+framework: "Node.js"
+classification: "SMALL"
+interaction_language: "en"
+...
+---
+```
+
+> **What happened:** `@setup` interviewed you and saved the answers to a file. **This file is the external memory** that all other agents will read.
+
+---
+
+## Step 4 — `@product` defines the first feature
+
+```
+You > @product
+
+@product > Let's define the initial feature. What's the short name (slug)?
+You > task-list
+
+@product > In one sentence, what problem does it solve?
+You > Let users create tasks and mark them as completed
+
+@product > What are the acceptance criteria?
+You > Create a task with text. Mark as completed. List pending and completed separately. Persist in SQLite.
+
+@product > [...details...] Spec saved to
+        .aioson/context/features/task-list/spec.md
+@product > Next: @analyst.
+```
+
+```bash
+cat .aioson/context/features/task-list/spec.md
+```
+
+You'll see a structured spec with scope, ACs, and out-of-scope items.
+
+---
+
+## Step 5 — `@analyst` maps the domain
+
+```
+You > @analyst
+
+@analyst > Reading spec... domain: personal tasks.
+@analyst > Entities:
+        - Task { id, text, completed, created_at }
+@analyst > No other entities in scope.
+@analyst > Domain map saved to context/architecture.md.
+@analyst > Next: @architect.
+```
+
+---
+
+## Step 6 — `@architect` decides the structure
+
+```
+You > @architect
+
+@architect > Stack confirmed: Node + Express + SQLite.
+@architect > Decisions:
+        - Structure: src/{routes,db,server}.js
+        - Persistence: better-sqlite3 (synchronous SQLite, simple)
+        - Validation: small, manual (no extra libs — Article VI)
+        - No heavy test framework: use node:test (built-in)
+@architect > Decisions recorded in architecture.md.
+@architect > Next: @dev.
+```
+
+> **Note Article VI ("Simplicity Over Ceremony"):** `@architect` avoided pulling in unnecessary libraries.
+
+---
+
+## Step 7 — `@dev` implements
+
+```
+You > @dev
+
+@dev > [reads spec, architecture, project.context]
+@dev > I'll create:
+        package.json
+        src/db.js          (init schema)
+        src/routes.js      (POST /tasks, PATCH /tasks/:id, GET /tasks)
+        src/server.js
+        tests/tasks.test.js (placeholder — @qa covers)
+
+@dev > [implements]
+@dev > Implementation OK. Running smoke:
+        $ node src/server.js → listening on 3000 ✓
+@dev > dev-state.md updated.
+@dev > Next: @qa.
+```
+
+See what changed:
+
+```bash
+ls src/
+# db.js  routes.js  server.js
+cat .aioson/context/dev-state.md
+```
+
+`dev-state.md` shows exactly what was done, in which files, and the current status.
+
+---
+
+## Step 8 — `@qa` tests
+
+```
+You > @qa
+
+@qa > Reading spec... 4 ACs identified.
+@qa > Test plan:
+        AC-01: create task → POST returns 201 and id
+        AC-02: mark completed → PATCH changes completed
+        AC-03: list separately → GET /tasks?status=pending|done
+        AC-04: persistence → restart process, data persists
+@qa > Writing tests/tasks.test.js... running...
+
+[If a test fails? Autonomous QA→Dev cycle (up to 2 iterations):]
+@qa > AC-03 failed: GET without filter returns mixed results.
+        Passing back to @dev (iteration 1/2)...
+@dev > Fixing... done.
+@qa > Re-running... 4/4 OK.
+@qa > test-plan.md and qa-report.md saved. Feature ready.
+```
+
+> **What's new:** the *autonomous QA→Dev cycle* (cap 2) lets `@qa` request small fixes without you having to manually reactivate it. Added in May/2026.
+
+---
+
+## Step 9 — Clean commit with `@committer`
+
+```
+You > @committer
+
+@committer > Reading diff and dev-state...
+        Proposed message:
+        ┌────────────────────────────────────────────────────┐
+        │ feat(tasks): add basic CRUD with SQLite            │
+        │                                                    │
+        │ - POST /tasks creates a task                       │
+        │ - PATCH /tasks/:id toggles completion              │
+        │ - GET /tasks supports status=pending|done filter   │
+        │                                                    │
+        │ Closes spec task-list. Tests: 4/4 pass.            │
+        └────────────────────────────────────────────────────┘
+        [✓] Accept  [ ] Edit  [ ] Cancel
+You > [Enter to accept]
+@committer > Committed.
+```
+
+---
+
+## What stayed traceable
+
+```
+.aioson/context/
+├── project.context.md         ← project view (step 3)
+├── architecture.md            ← decisions (steps 5+6)
+├── dev-state.md               ← what @dev did (step 7)
+├── test-plan.md               ← @qa's plan (step 8)
+├── qa-report-test-coverage.md ← QA report
+└── features/
+    └── task-list/
+        └── spec.md            ← original spec (step 4)
+```
+
+Three months from now, someone (you or another AI) can open this project and understand **everything** just by reading these files. No chat history needed.
+
+---
+
+## What if I want a new feature?
+
+Go back to step 4. `@product` creates a new feature → `@analyst` → `@architect` → `@dev` → `@qa`. `@setup` doesn't need to run again (context is already there).
+
+If you get lost in the middle:
+
+```
+You > @neo
+```
+
+It tells you who's next.
+
+---
+
+## Common troubleshooting
+
+| Problem | Solution |
+|---|---|
+| The agent "forgot" the context | Check `cat .aioson/context/project.context.md`. If fields are missing, run `@setup` again. |
+| I want to resume an interrupted feature | Run `@deyvin` — it reads `dev-state.md` and continues. |
+| Not sure if SMALL is the right classification | Ask `@neo` — it explains the calculation. |
+| Install failed | `npx @jaimevalasek/aioson doctor` — diagnoses and suggests a fix. |
+| I want to add Codex/Gemini later | `npx @jaimevalasek/aioson install --reconfigure`. |
+
+---
+
+## Next step
+
+- Have a project **that already exists** and want to add AIOSON? → [Existing project](./existing-project.md)
+- Want to understand when MICRO vs SMALL vs MEDIUM? → [Initial decisions](./initial-decisions.md)
+- Want to see the full team? → [Ecosystem map](../1-understand/ecosystem-map.md)