@jaimevalasek/aioson 1.8.0 → 1.9.0

package/docs/en/2-start/initial-decisions.md

@@ -0,0 +1,223 @@
+# Initial decisions — MICRO, SMALL, or MEDIUM? Which AI client?
+
+> **Who this is for:** you're about to run `aioson init` and want to choose well.
+> **Reading time:** 6 min
+> **What you'll know after:** how AIOSON classifies your project, and how to choose AI client / design / language.
+
+---
+
+## The classification: MICRO, SMALL, MEDIUM
+
+AIOSON is the opposite of "one size fits all." It applies **more ceremony to larger projects and less to smaller ones**. This is Article II of the Constitution: *Right-Sized Process*.
+
+### How the score is calculated
+
+The sum of three factors (each worth 0, 1, or 2 points):
+
+| Factor | 0 pts | 1 pt | 2 pts |
+|---|---|---|---|
+| **User types** | 1 | 2 | 3+ |
+| **External integrations** | 0 | 1–2 | 3+ |
+| **Non-obvious business rules** | none | some | complex |
+
+| Score | Classification |
+|---|---|
+| 0–1 | **MICRO** |
+| 2–3 | **SMALL** |
+| 4–6 | **MEDIUM** |
+
+### What changes at each level
+
+#### MICRO — `@setup → @product (optional) → @dev`
+
+- For: scripts, automations, prototypes, simple personal apps.
+- No `@analyst` or `@architect`. You talk directly to `@dev`.
+- `@product` is optional — you can pass the spec directly in chat if you prefer.
+- No `@qa` in the standard flow (you can invoke it manually).
+
+**Typical examples:**
+- Python script that processes CSV
+- Simple Telegram bot
+- Static portfolio page
+- Mini API with 3 endpoints
+
+#### SMALL — `@setup → @product → @analyst → @architect → @dev → @qa`
+
+- For: most real apps.
+- Full discovery+development+QA cycle.
+- No `@ux-ui`, `@pm`, or `@orchestrator` in the standard flow (you can invoke them individually).
+
+**Typical examples:**
+- SaaS app for a single persona
+- API with auth and some business rules
+- Simple online store
+- Blog with admin panel
+
+#### MEDIUM — full workflow
+
+- For: products with multiple user types, several integrations, complex rules.
+- Adds `@ux-ui`, `@pm`, `@orchestrator`.
+- Quality gates applied at each handoff.
+- Parallel lanes possible (`@orchestrator` coordinates).
+- More aggressive context threshold (55% — warns early).
+
+**Typical examples:**
+- Marketplace (seller + buyer + admin)
+- ERP / CRM
+- Multi-tenant platform with tier billing
+- Fintech app with KYC and compliance
+
+### Edge cases
+
+| Situation | Suggestion |
+|---|---|
+| Personal project, but with one heavy external integration | SMALL — the integration justifies `@architect` |
+| Score 1, but I know it will grow | Start MICRO. Can promote later with `@setup` |
+| Score 4, but the team is just me | MEDIUM anyway. Complex business rules benefit from the artifacts |
+| Score 2, but greenfield and I want careful design | SMALL + activate a design skill in the wizard |
+
+> **Frequently forgotten truth:** AIOSON fights unnecessary ceremony. If you're unsure between two levels, **choose the smaller one**. Promoting later is easy. Demoting later is painful.
+
+---
+
+## Choosing an AI client
+
+You can mark **more than one** in the wizard — they coexist in the same project.
+
+| Client | Strong for... | Distinctive features |
+|---|---|---|
+| **Claude Code** | Long agents, refactoring, planned tasks | Native skills, slash commands, hooks |
+| **Codex CLI** | Short tasks, focus on direct code | `@` mode to include files |
+| **Gemini CLI** | Multi-modal, low cost on some plans | Generous context window |
+| **OpenCode** | Open-source, integrates with multiple providers | Granular configuration |
+
+**Recommendation for beginners:** start with Claude Code — it has the highest parity with AIOSON. Add others later with `aioson install --reconfigure`.
+
+---
+
+## Choosing Mode: Development vs Development + Squads
+
+### Development (default)
+
+Includes the 28 official agents (product, analyst, dev, qa, etc.). Sufficient for 95% of projects.
+
+### Development + Squads
+
+Adds the squad system — you can create custom squads for domains outside the standard.
+
+**Practical example:** your project is legal. You create a "compliance" squad with agents:
+- `@regulator` — understands local regulation
+- `@attorney` — interprets clauses
+- `@auditor` — checks conformity
+
+```bash
+# Inside the AI client
+> @squad assemble compliance
+
+# Or via CLI
+npx @jaimevalasek/aioson squad:assemble compliance
+```
+
+**When to activate Squads:**
+- You know you'll need specialization outside the standard
+- Large team with different domains
+- You'll publish squads on aioson.com (see `system:publish`)
+
+**When NOT to activate:**
+- MICRO personal project
+- You haven't used the standard agents enough yet to know if you need it
+
+> Can be activated later with `aioson install --reconfigure`.
+
+---
+
+## Choosing a Design System
+
+Available in the wizard:
+
+| Skill | Style | Use cases |
+|---|---|---|
+| **Clean SaaS UI** | Clean, clear typography, neutral | Panels, dashboards |
+| **Aurora Command UI** | Dark, subtle gradients, central command | Developer tools |
+| **Cognitive Core UI** | Weighted cards, depth via shadows | Information-dense apps |
+| **Bold Editorial UI** | Editorial typography, strong hierarchy | Blogs, content |
+| **Warm Craft UI** | Warm colors, soft texture | Artisan e-commerce |
+| **Glassmorphism UI** | Glass, blur, translucent | Modern premium apps |
+| **Neo Brutalist UI** | Black outlines, strong colors, no shadow | Bold brands |
+
+**Skipping** is a valid option. You can:
+- Choose later with `@ux-ui`
+- Clone a real site's design with `@site-forge`
+- Create a hybrid with `@design-hybrid-forge` (e.g., clean-saas + neo-brutalist)
+
+---
+
+## Choosing the interaction language
+
+| Language | When it makes sense |
+|---|---|
+| **English** | International teams; want maximum prompt quality |
+| **Português (pt-BR)** | 100% PT team; end users read PT |
+| **Español** | 100% ES team |
+| **Français** | 100% FR team |
+
+**Important:** internal agent files always stay in English (they're prompts, and models perform best in English). `interaction_language` only changes how the agent **speaks to you** — questions, explanations, messages.
+
+Deliberate project decision: separate **prompt language** (en, always) from **interaction language** (your choice). This separation was introduced in commits `efb0902` and `6629730`.
+
+---
+
+## Wizard skip — lightning installs
+
+```bash
+# Everything: all clients, Squads mode, no design, EN
+npx @jaimevalasek/aioson init my-app --all
+
+# No prompts (defaults), English
+npx @jaimevalasek/aioson install --no-interactive
+```
+
+---
+
+## How do I change later?
+
+| I want to change... | Command |
+|---|---|
+| Add Codex/Gemini to the same project | `aioson install --reconfigure` |
+| Activate Squads | `aioson install --reconfigure` (and select it) |
+| Switch design skill | `@ux-ui` in the AI client or `aioson install --reconfigure` |
+| Change interaction language | Edit `interaction_language:` in `project.context.md` or run `@setup` again |
+| Change the classification | Edit `classification:` in `project.context.md`. Next sessions respect it. |
+
+---
+
+## Final decision in 30 seconds
+
+```
+What are you building? Risk level? How many integrations?
+                              │
+                              ▼
+                       Small and simple?
+                       YES → MICRO
+                       NO → ↓
+                              ▼
+                  3+ user types OR 3+ integrations
+                       OR complex rules?
+                       YES → MEDIUM
+                       NO → SMALL
+
+Main AI client? Claude Code (recommended to start)
+Squads? Not yet
+Design? Skip or Clean SaaS UI
+Language? English
+
+Done. Run aioson init.
+```
+
+---
+
+## Next step
+
+- [First project from scratch](./first-project.md)
+- [Existing project](./existing-project.md)
+- Curious about the principles? → [Why it exists](../1-understand/why-it-exists.md)

package/docs/en/3-recipes/README.md

@@ -0,0 +1,28 @@
+# Recipes — ready-to-copy guides
+
+Each recipe is an end-to-end guide with simulated dialogues, runnable examples, and troubleshooting. Choose by your scenario:
+
+## Canonical trails (recommended starting point)
+
+These three trails show **how features reach development** in AIOSON. You almost always fall into one of them.
+
+| Trail | When to use | Key agents |
+|---|---|---|
+| **[Full feature with @sheldon](./full-feature-with-sheldon.md)** | You have a PRD in mind and want the complete canonical trail (most used) | @product → @sheldon → @analyst → @architect → @ux-ui → @pm → @orchestrator → @dev → @qa |
+| [From idea to PRD via @briefing](./from-idea-to-prd-via-briefing.md) | Your idea is still vague, several loose notes | @briefing → @product |
+| [External plans for @product](./external-plans-for-product.md) *(coming soon)* | You already planned in another chat (ChatGPT, Claude.io, Gemini Web) | @product (reads `/plans/`) |
+
+## Recipes by scenario
+
+| Recipe | Scenario | Main agents |
+|---|---|---|
+| [Landing page](./landing-page.md) *(coming soon)* | Create a presentation page with copy and design | @product, @copywriter, @ux-ui, @dev, @qa |
+| [SaaS app from scratch](./saas-app-from-scratch.md) *(coming soon)* | Full SaaS: auth, Stripe billing, admin | Full MEDIUM workflow + @orchestrator |
+| [Integration in large codebase](./integration-in-large-codebase.md) *(coming soon)* | Install AIOSON on a 10k–100k line legacy project | @discover, @analyst |
+| [Large refactor](./large-refactor.md) *(coming soon)* | Rewrite a critical module without breaking anything | @sheldon, @tester, @dev, @qa |
+| [Security audit](./security-audit.md) *(coming soon)* | Review vulnerabilities before production | @pentester |
+| [Publish on aioson.com](./publish-on-aioson-com.md) *(coming soon)* | Distribute a squad, skill, or genome | system:package, system:publish |
+| [Clone site design](./clone-site-design.md) *(coming soon)* | Extract a site's visual or combine two styles | @site-forge, @design-hybrid-forge |
+| [Continuity between sessions](./continuity-between-sessions.md) | Resume a feature after the session ended | @deyvin, dossier, dev-state |
+
+Back to the main portal: [docs/en/README.md](../README.md)

package/docs/en/3-recipes/continuity-between-sessions.md

@@ -0,0 +1,303 @@
+# Recipe: Continuity between sessions
+
+> **Who this is for:** any developer working on long features spread across multiple sessions — who doesn't want to start over every time they open the project.
+> **Time to run:** 10 min of setup the first time; nearly zero in subsequent sessions.
+> **What you'll have at the end:** every feature with a dossier on disk — spec, plan, decisions, touched code, status — that any agent reads and resumes without needing to re-read chat history.
+
+---
+
+## Scenario
+
+You were implementing the Stripe checkout feature. You spent three hours with `@dev`, reached 80%, and the Claude Code session ended. The next day you open the project and ask the AI: "where did we leave off?" The AI doesn't know. It only has recent history, and yesterday's context was compacted.
+
+This is the **prompt-monolith problem**: all memory lives in the conversation, which is temporary.
+
+The **Feature Dossier** (agent-chain continuity system, implemented in 8 phases between Mar–May 2026) solves this. Each feature has a folder with persistent artifacts. When you resume, `@deyvin` reads the dossier and continues where it left off — without interviewing you about what was already done.
+
+---
+
+## Prerequisites
+
+- AIOSON installed in the project
+- A feature in progress (or about to start)
+- Claude Code open in the project
+
+---
+
+## How a dossier is created
+
+The dossier is initialized automatically when you start a feature via the normal workflow (`@product` → `@analyst` → `@dev`). You can also create it manually:
+
+```bash
+npx @jaimevalasek/aioson dossier:init --slug=checkout-stripe
+```
+
+```
+Dossier initialized at:
+.aioson/context/features/checkout-stripe/
+├── dossier.md          ← main document (spec, plan, decisions, trail)
+├── codemap/            ← map of files touched by the feature
+└── research/           ← index of research done during the feature
+```
+
+---
+
+## Anatomy of the dossier
+
+```
+.aioson/context/features/checkout-stripe/dossier.md
+```
+
+The file has standardized sections:
+
+```
+## Meta
+slug: checkout-stripe
+status: in_progress
+classification: SMALL
+agents_trail: [@product, @analyst, @architect, @dev]
+last_agent: @dev
+last_updated: 2026-05-06T14:32:00Z
+
+## Spec Summary
+[spec summary — what the feature solves, main ACs]
+
+## Plan
+[implementation plan steps with checkboxes]
+- [x] Database schema (payments table)
+- [x] POST /checkout/create-session route
+- [ ] Webhook handler /webhooks/stripe
+- [ ] Confirmation page
+
+## Decisions
+[decisions made during the feature with rationale]
+- Using Stripe Checkout (not Elements) — lower PCI complexity
+- Webhook verified with stripe.webhooks.constructEvent
+
+## Code Map
+[files that belong to this feature]
+- src/routes/checkout.js       (created)
+- src/services/stripe.js       (created)
+- src/db/migrations/005_payments.js (created)
+- src/routes/webhooks.js       (pending)
+- app/pages/checkout/success.tsx (pending)
+
+## Agent Trail
+[what each agent did]
+@product: spec created on 2026-05-05
+@analyst: Payment, Order mapped
+@architect: Stripe Checkout chosen, structure defined
+@dev: 3/5 plan steps completed
+```
+
+---
+
+## Resuming a feature — real flow
+
+### New session, agent `@deyvin`
+
+```
+You > @deyvin
+
+@deyvin > Reading project-pulse.md... feature checkout-stripe in progress.
+           Reading dossier.md...
+
+@deyvin > Here is where you left off:
+
+           FEATURE: checkout-stripe
+           Status: in_progress (80%)
+           Last agent: @dev
+
+           DONE:
+           ✓ Payments schema (migration 005)
+           ✓ POST /checkout/create-session
+           ✓ Stripe Checkout integration
+
+           PENDING:
+           ✗ Webhook handler /webhooks/stripe
+           ✗ Confirmation page /checkout/success
+
+           RECORDED DECISIONS:
+           - Stripe Checkout (not Elements)
+           - Webhook verification with constructEvent
+
+           Do you want to continue implementing the 2 pending steps?
+You > Yes, start with the webhook.
+
+@deyvin > [implements src/routes/webhooks.js]
+           Webhook handler created. Testing with stripe-cli...
+           Event payment_intent.succeeded received ✓
+           Dossier updated: webhooks marked as done.
+```
+
+---
+
+## Detecting drift
+
+The dossier has **drift detection**: if the code changed since the last agent update, it detects the divergence before continuing.
+
+```
+@deyvin > Checking for drift...
+           File: src/services/stripe.js
+           Last known version: created by @dev on 2026-05-05
+           Current state: modified outside the agent (1 function added)
+
+           Drift detected. Before continuing, I'll read what changed...
+           [reads diff]
+           Change: handleRefund() function added manually.
+           I'll include this in the codemap and continue.
+```
+
+---
+
+## Adding research to the dossier
+
+When you (or an agent) research something important for the feature, add it to the research index:
+
+```bash
+npx @jaimevalasek/aioson dossier:add-research . \
+  --slug=checkout-stripe \
+  --url="https://stripe.com/docs/webhooks" \
+  --summary="Stripe requires signature verification on all webhooks. Use constructEvent." \
+  --agent=dev
+```
+
+This lands in `research/` and future agents find it without having to re-read the documentation.
+
+---
+
+## Auditing the dossier
+
+To verify the dossier is consistent with the actual code state:
+
+```bash
+npx @jaimevalasek/aioson dossier:audit --slug=checkout-stripe
+```
+
+```
+Auditing checkout-stripe...
+
+✓ All codemap files exist
+✓ Migration 005 applied (verified via introspection)
+✗ src/routes/webhooks.js listed as pending but file exists on disk
+
+  Possible inconsistency: file created but dossier not updated.
+  Recommendation: run @deyvin to sync the status.
+```
+
+---
+
+## View current dossier state
+
+```bash
+npx @jaimevalasek/aioson dossier:show --slug=checkout-stripe
+```
+
+```
+FEATURE: checkout-stripe
+Status: in_progress
+Agents: @product, @analyst, @architect, @dev, @deyvin
+Progress: 4/5 steps done (80%)
+Files: 5 (3 created, 2 pending)
+Research: 1 (stripe webhooks)
+Last updated: 2026-05-07 10:15
+```
+
+---
+
+## `dev-state.md` — the dossier's complement
+
+Beyond the dossier, `@dev` maintains `.aioson/context/dev-state.md` — a more granular snapshot of the implementation state:
+
+```
+## Dev State — checkout-stripe
+
+### Done
+- src/routes/checkout.js: POST /checkout/create-session → Stripe Checkout
+- src/services/stripe.js: createCheckoutSession, handleRefund
+- src/db/migrations/005_payments.js: payments table with Stripe fields
+
+### In progress
+- src/routes/webhooks.js: partial handler, missing payment_intent.payment_failed
+
+### Blocked
+- (none)
+
+### Next steps
+1. Complete webhook handler (payment_failed case)
+2. Create /checkout/success page with session_id query param
+3. Activate @qa to validate ACs
+```
+
+---
+
+## What happens when the feature is closed
+
+When you run `aioson feature:close --slug=checkout-stripe`, the dossier is moved to `.aioson/context/done/`. The feature archive stores:
+
+```
+.aioson/context/done/
+└── checkout-stripe/
+    ├── dossier.md        ← final state
+    ├── codemap/          ← all touched files
+    └── research/         ← accumulated research
+```
+
+This creates an auditable history of all features — useful for onboarding new devs or for `@neo` to understand the project's history.
+
+---
+
+## What was left on disk (audit trail)
+
+```
+.aioson/context/features/checkout-stripe/
+├── dossier.md           ← central document (spec, plan, decisions, trail)
+├── codemap/
+│   └── files.json       ← files, status (created/modified/pending), agent
+└── research/
+    └── index.md         ← research indexed with summaries
+
+.aioson/context/
+├── dev-state.md         ← granular implementation state
+└── project-pulse.md     ← global project state (active feature, next step)
+```
+
+---
+
+## When NOT to use the dossier
+
+- Feature you finish in one 1-hour session — unnecessary overhead.
+- MICRO project with a single feature — `project.context.md` and `dev-state.md` are enough.
+- Quick code exploration — use `@deyvin` directly without initializing a dossier.
+
+For SMALL and MEDIUM projects, the dossier is strongly recommended. MEDIUM projects with `@orchestrator` use it by default.
+
+---
+
+## Variations
+
+| Situation | Adjustment |
+|---|---|
+| Multiple parallel features | One dossier per feature slug. `project-pulse.md` shows which is active. |
+| Team with multiple devs | Commit the dossiers to Git. Each dev sees the state of all features. |
+| Feature resumed by a different agent | Any agent reads the dossier. The agent trail is recorded. |
+| Session dropped without saving `dev-state.md` | `@deyvin` uses the dossier + git diff to reconstruct the state. |
+
+---
+
+## Troubleshooting
+
+| Problem | Solution |
+|---|---|
+| `@deyvin` didn't find the dossier | Run `dossier:show --slug=X` to confirm it exists. If not, `dossier:init`. |
+| Dossier is out of sync with the code | `dossier:audit` detects inconsistencies and guides correction. |
+| `dev-state.md` was overwritten | Git has the history. The dossier has the agent trail. |
+| Drift detection fired incorrectly | Tell `@deyvin`: "the file was modified intentionally, update the codemap". |
+
+---
+
+## Next step
+
+- Want to start with this flow on a legacy project? → [Integration in large codebase](./integration-in-large-codebase.md)
+- Want to understand what else the dossier tracks? See the [Glossary — Dossier](../1-understand/glossary.md).
+- Want the full artifact map? → [Ecosystem map](../1-understand/ecosystem-map.md).