# AIOSON Config ## Principles - Less is more: complexity must match problem size. - Single source of truth: rules live in `.aioson/agents/`. - Never assume stack: detect first, then ask. - The visual system is never a question: `design_skill` is `interface-design` (the one design engine) by default; a project-forged skill replaces it only when the field names it explicitly. ## Project sizes - MICRO: `@setup -> @product -> @sheldon -> @planner -> @dev -> @qa` (terse artifacts and narrow review) - SMALL: `@setup -> @product -> @sheldon -> @planner -> @dev -> @qa` - MEDIUM: `@setup -> @product -> @sheldon -> @planner -> @dev -> @qa` MICRO, SMALL, and MEDIUM use the same feature agents and the same three-artifact contract. Classification controls budgets and depth inside the PRD, plan, implementation, tests, and runtime evidence; it does not add or remove document-producing hops. An already-specified bounded technical task uses the separate Simple Plan lane. Canonical artifacts are exactly: one PRD from `@product`, mandatorily reviewed/enriched in place by `@sheldon`, one `implementation-plan-{slug}.md` from `@planner`, and one `qa-report-{slug}.md` from `@qa`. Raw source packs under `plans/{slug}/`, Briefing, Refiner, and an approved owned prototype are cumulative pre-product inputs when used. Requirements/spec/design/readiness/conformance/harness documents are never canonical prerequisites. The lightweight feature dossier, selected project knowledge, and all specialists are intelligence available to every classification. `@sheldon` is the mandatory pre-Planner PRD reviewer. `@orchestrator` remains opt-in for a concrete unresolved question. `@tester`, `@pentester`, and `@validator` run only when the approved plan, the risk surface, QA findings, or the user explicitly trigger them. None is a classification-driven gate. The normal runtime smoke uses the real application and real production path; a separate harness is optional. Scope alignment: the engine's always-on scope drift gate in `workflow:next` checks delivery at dev/qa completion. When `@dev`, `@qa`, `@tester`, or `@pentester` corrections changed planned behavior, touched unexpected files, or skipped approved scope, `@qa` classifies the drift (`.aioson/docs/qa/scope-drift.md`). Optional test engineering (activate after @dev when coverage is insufficient): - `@quality` — optional engineering assessment for products or AIOSON itself: static analysis, test effectiveness, benchmarks and evaluations. Produces evidence and a remediation backlog; QA retains acceptance and implementing agents retain responsibility for correctness. - `@tester` — systematic test engineering for implemented apps. Activate when: (1) app was built without adequate tests, (2) @qa identifies coverage gaps in 3+ modules, or (3) working on a legacy/brownfield project. Optional completeness walkthrough (activate after @qa, on an archived feature, after a Simple Plan delivery, or on a direct target): - `@shakedown` — spec-independent tech-lead walkthrough: QA verifies the promise; shakedown audits the silence (incomplete CRUD, unvalidated forms, missing states, sibling inconsistencies, plus reproducible bugs). Produces a `shakedown-{slug}.md` punch list with suggested fix lanes; it finds and lists, never fixes, and is never a gate. Optional deployment (activate when an app goes to a self-hosted VPS with Dokploy): - `@deployer` — guides the operator stage by stage (app readiness, panel hardening, database/cache services, read-only deploy key, application, domain and TLS, provider firewall, access gate before real data), verifies every stage from outside, and keeps a deployment diary. It writes no application code (readiness gaps route to `@dev`) and is never a gate. ## Official classification Score (0-6): - User types: 1=0, 2=1, 3+=2 - External integrations: 0=0, 1-2=1, 3+=2 - Non-obvious rules: none=0, some=1, complex=2 Ranges: - 0-1: MICRO - 2-3: SMALL - 4-6: MEDIUM For feature classification, never compute this rubric by hand — the command owns it: run `aioson classify . --feature={slug} --apply --json` after the PRD capability/acceptance map is complete and again after Sheldon enrichment, and read `classification`, `floor_reasons`, and `recommend_prototype` from the output. It applies the base score plus deterministic scope floors (multiple traceable `CAP-*`, broad `AC-*` coverage, multiple delivery phases, affected modules, runtime boundaries); an explicit higher owner classification is a floor and is never lowered. Use `--interactive` only when the detected inputs contradict what the PRD plainly says. The score table above remains the definition — used directly only for project-level classification at setup, where no PRD exists yet. ## Context budget warning Setting: `context_warning_threshold` (default: 65%) | Classification | Recommended threshold | |---------------|-----------------------| | MICRO | 75% (short phases, acceptable to go higher) | | SMALL | 65% (default) | | MEDIUM | 55% (long phases, warn earlier) | When an agent notices it is close to the threshold: 1. Write all in-progress artifacts to disk (disk-first) 2. Emit this warning in the selected project language: "Context at {X}% — I recommend `/compact` before the next phase; use `/clear` only for a hard reset, feature switch, polluted context, or security-sensitive reset" 3. Include the current work in `last_checkpoint` ## Context contract `project.context.md` must contain YAML frontmatter with: - `project_name` - `project_type` - `profile` - `framework` - `framework_installed` (boolean) — `true` means the framework was detected in the workspace; downstream agents skip installation commands. `false` means it was not detected; agents must include installation steps before any implementation. - `classification` - `interaction_language` (BCP-47, for example `en`, `pt-BR`) - `conversation_language` (legacy compatibility alias; keep synchronized with `interaction_language`) - `aioson_version` Optional UI context fields: - `design_skill` (`interface-design` by default — the CLI writes it and a blank value resolves to the same engine; a skill this project forged replaces it only when named explicitly) Optional testing fields: - `test_runner` (for example `pest`, `jest`, `vitest`, `pytest`, `rspec`, `foundry`) Optional workflow fields: - `auto_handoff` (boolean, default `false`) — when `true`, the canonical feature chain advances `@product -> @sheldon -> @planner -> @dev -> @qa` until a real human decision or failed gate stops it. Other specialists run only through an explicit evidence-based detour. Protocol and stop conditions: `.aioson/docs/autopilot-handoff.md`. - `phase_restart` (`auto` | `suggest` | `off`; absent means `auto` inside AIOSON Play, `suggest` elsewhere) — what `aioson phase:next` tells `@dev` at the end of each plan phase. `auto`: the conversation ends and the Play continues with the next phase — and with QA after the last one, when Autopilot is on — in a new conversation or, while the context is still small, in the same one. Outside the Play `auto` behaves as `suggest`. `suggest`: it continues here and quotes the kickoff once, for a manual restart. `off`: it continues as before. Protocol: `.aioson/docs/dev/phase-loop.md`. Allowed `project_type` values: - `web_app` - `api` - `site` - `script` - `dapp` - `desktop_app` Optional Web3 context fields (recommended for `project_type=dapp`): - `web3_enabled` (boolean) - `web3_networks` (for example `ethereum`, `solana`, `cardano`, `ethereum,solana`) - `contract_framework` (for example `Hardhat`, `Foundry`, `Anchor`, `Aiken`) - `wallet_provider` (for example `wagmi`, `RainbowKit`, `Phantom`, `Lace`) - `indexer` (for example `The Graph`, `Helius`, `Blockfrost`) - `rpc_provider` (for example `Alchemy`, `Infura`, `QuickNode`) ## Visual system gate - `design_skill` defaults to `interface-design`; blank means the same engine. No agent asks which design skill to use — there is no menu. - `@site-forge` and `@design-hybrid-forge` register a project-forged skill by name when the user forges one; `@setup` and `@product` never offer or confirm a choice. - `@dev` and `@refiner` consume the value as the single visual system (`identity.md` is its input, never a second system); they never swap, mix, or invent one. - `@refiner` records `design_skill: interface-design (default)` in the prototype manifest when the field is blank. ## Runtime lifecycle When AIOSON manages the session via `aioson workflow:next`, ALL orchestration is handled by the CLI: - Workflow state (which agent is next, what was completed) - Event emission to `.aioson/runtime/aios.sqlite` (read by the AIOSON Dashboard at /tasks and /logs) - Sequence enforcement and required-agent checks The agent `.md` files define WHAT each agent does. The CLI defines HOW the session is orchestrated. **Agents keep the dashboard in sync with the modern telemetry commands (skip if `aioson` CLI is not installed):** | Moment | Command | |---|---| | Milestones / step evidence | `aioson runtime:emit . --agent= --type= --summary="..."` | | Session end — heartbeat | `aioson pulse:update . --agent= --feature= --action="..." --next="..."` | | Session end — completion | `aioson agent:done . --agent= --summary="..."` (or `agent:epilogue` where the kernel says so) | | Advance workflow | `aioson workflow:next . --complete=` when the agent kernel instructs it | `workflow:next` injects the tracked-session lifecycle block into agent prompts itself. Never replay telemetry manually with ad-hoc `runtime-log` shell snippets and never open a parallel runtime session inside an active live envelope (`.aioson/docs/gateway/workflow-runtime.md`). In direct mode (LLM without CLI), agents call the same commands manually following the rules in CLAUDE.md / AGENTS.md. ## Devlog (direct LLM mode without CLI) When the `aioson` CLI is **not available**, agents must write a devlog file at the end of the session (or when the user asks to save progress). This is the only way to preserve session history for the dashboard when the CLI is missing. **Directory:** `aioson-logs/` (create if absent) **Filename:** `devlog-{agent}-{unix-timestamp}.md` **Template:** ```markdown --- agent: dev feature: {feature-slug or "project"} session_key: direct-session:{unix-timestamp}:{agent} started_at: {ISO 8601} finished_at: {ISO 8601} status: completed verdict: null plan_step: null --- # Devlog: @{agent} — {feature} — {YYYY-MM-DD} ## Summary {One sentence of what was accomplished.} ## Artifacts - {path/to/file.ext} ## Decisions - {decision} → {why} ## Learnings - [process] {any process learning from this session} - [domain] {any domain learning} ## Blockers - {blocker or "None"} ``` **Minimum viable devlog (if session was cut short):** ```markdown --- agent: {agent} feature: {slug} status: partial started_at: {ISO 8601} finished_at: {ISO 8601} --- # Devlog: @{agent} — {feature} — {date} ## Summary {one sentence of what was done} ## Learnings - [process] {any process learning} ``` **Rules:** - Frontmatter fields `agent`, `started_at`, `finished_at` are required. All others are optional. - `[process]` / `[domain]` / `[quality]` / `[preference]` prefixes in Learnings enable automatic promotion to project memory. - Record **why** decisions were made — the "what" is in the git diff. - Skip the devlog for trivial sessions (quick questions, no code changes). - When the CLI becomes available: `aioson devlog:process .` imports devlogs into SQLite (learnings, artifacts, decisions, verdict). ## On-demand context layers AIOSON uses three on-demand context layers that any agent can load automatically. Each layer is optional — if the directory is empty or absent, agents skip it silently. ### Rules (`.aioson/rules/`) Project-specific rules that override agent defaults. Each file must have YAML frontmatter: ```markdown --- agents: [dev, planner] # empty [] = universal rule loaded by all agents --- # Database conventions - Always use soft deletes - Never use raw SQL — use the ORM query builder ``` **When to use:** coding standards, naming conventions, architecture constraints, security policies, team agreements. ### Docs (`.aioson/docs/`) Persistent documentation loaded on-demand based on relevance. Each file must have YAML frontmatter: ```markdown --- description: "Auth module refactoring plan — migration from JWT to sessions" --- # Refactoring Plan — Auth Module ... ``` Agents load a doc only when its `description` matches the current task or when a loaded rule references it. **When to use:** - Refactoring plans that span multiple sessions - Integration guides (Stripe, external APIs) - Domain knowledge the LLM needs but cannot infer from code - Migration strategies and rollback procedures - Performance benchmarks and constraints **Key principle:** docs persist across sessions. A refactoring plan saved here will be available to any future agent that works on the same area — no need to re-explain context. ### Code governance (`.aioson/design-docs/`) Persistent code-structure governance surfaced by `aioson preflight` and loaded on demand by agents. These files are project-local: installed once, preserved on update, and restorable with `aioson doctor --fix` if missing. Default governance files: - `folder-structure.md` - `componentization.md` - `code-reuse.md` - `naming.md` - `file-size.md` **When to use:** folder structure, naming, reuse, component boundaries, file-size thresholds, and maintainability constraints. ### Optional design docs (`.aioson/context/design-doc.md`) Design docs are opt-in decision records for a genuinely unresolved technical boundary, written by the project team when a named decision deserves a standing record. Nothing installs one and no agent produces one by default: the installer used to seed this path with the framework's own code layout (retired — `aioson doctor` names a leftover copy and `--fix` deletes a verbatim one), and the Planner records boundary decisions in the plan instead of a separate document. Per-feature decisions live in the PRD's decision sections, the plan's ADR section and `aioson decision:add`; this file is never a SMALL or MEDIUM prerequisite. ```markdown --- description: "Billing module — Stripe integration with metered pricing" scope: "billing" agents: [dev, planner] # empty [] = all agents load it --- ``` **Design-doc vs PRD — when to use each:** | | PRD (`prd.md`) | Code governance (`.aioson/design-docs/`) | Design doc (`design-doc.md`) | |---|---|---|---| | **Produced by** | `@product`, enriched in place by `@sheldon` | Installer + project team | Project team, opt-in (no agent writes it by default) | | **Focus** | What and why — vision, users, problem, features | Structural code quality rules | How — technical flows, decisions, risks, slices | | **Audience** | All agents | Agents doing structural planning or implementation | Technical agents (planner, dev, qa) | | **Lifecycle** | One feature authority, refined in place | Stable, edited when conventions change | Living only while its named decision remains relevant | | **When to create** | Every substantive project/feature | Installed by default | Only for a named unresolved technical decision | A feature may have both, but the implementation plan remains the canonical technical delivery artifact. The design doc is supporting evidence, never another gate by mere classification. ### Bootstrap (`.aioson/context/bootstrap/`) Semantic knowledge cache that gives agents instant understanding of the system without reading the codebase. Generated by `@discover`. | File | Content | Loaded by | |------|---------|-----------| | `what-is.md` | System identity, users, value proposition | `@product` | | `how-it-works.md` | Architecture, modules, data flow, integrations | `@dev`, `@planner` | | `what-it-does.md` | Features, business rules, user workflows | `@product` | | `current-state.md` | Implementation status, tech debt, recent changes | `@dev`, `@qa` | **When to use:** run `@discover` once after setup, and re-run when significant changes accumulate. Agents read bootstrap files at session start for instant context. **Key difference from `discovery.md`:** `discovery.md` is a technical scan (routes, entities, structure). Bootstrap is semantic (meaning, purpose, business rules). They complement each other. ## Skills AIOSON ships three types of skills in `.aioson/skills/`: | Type | Directory | How agents load them | |---|---|---| | **Design skills** | `.aioson/skills/design/` | Explicit — via `design_skill` in project.context.md. Only ONE can be active; the template ships only the `interface-design` engine, forged skills are project-local. | | **Static skills** | `.aioson/skills/static/` | Automatic — agents match by `framework` in project.context.md | | **Dynamic skills** | `.aioson/skills/dynamic/` | Automatic — agents load when task references external services | | **Process skills** | `.aioson/skills/process/` | Loaded on demand when an agent needs a workflow method such as SDD, decision presentation, prompt sharpening, feature expansion, or design-skill creation | First-party process skills include: - `prompt-sharpener` — improves agent prompts, skills, PRDs, plans, and handoffs by turning vague guidance into evidence-driven decision behavior while preserving workflow contracts. - `briefing-expansion-scout`, `product-scope-expansion`, `sheldon-expansion-audit` — enrich feature thinking only when a rich surface or prior expansion artifact justifies it, using `.aioson/docs/feature-expansion-taxonomy.md`. ### Installed skills (`.aioson/installed-skills/`) Third-party or custom skills installed via CLI: ```bash aioson skill:install --slug=my-skill --from=./path/to/SKILL.md aioson skill:install --slug=my-skill --from=npm aioson skill:install --slug=my-skill --from=cloud ``` After installation, skills are distributed to editor directories (`.claude/skills/`, `.cursor/skills/`, `.windsurf/skills/`) and become available as slash commands in supported editors. ### Listing available skills ```bash aioson skill:list # show installed skills aioson skill:remove --slug=x # remove an installed skill ``` **Note:** Source skills in `.aioson/skills/` are loaded automatically by agents — they do not need installation. Only third-party skills require `skill:install`. ## Session handoff When a workflow stage completes or an agent finishes via `runtime-log --finish`, AIOSON generates `.aioson/context/last-handoff.json` with: - What was done in the last session - What comes next - Which agent should be activated - Open decisions pending Agents can read this file on activation to resume work without losing context between sessions. ## Context compaction template For an active feature, first update `mappings/{slug}/continuity.md` when material session-only context could otherwise be compressed away. Follow `.aioson/docs/feature-continuity-mapping.md`: the file is temporary, noncanonical, and can never replace raw sources under `plans/{slug}/`, approved feature artifacts, implementation, or verification evidence. When approaching context threshold, any agent can write a structured checkpoint to `.aioson/context/last-handoff.json` before compacting: ```json { "agent": "", "session_summary": { "messages_processed": "", "tools_used": ["", ""], "recent_requests": [""], "pending_work": ["", ""], "key_files": ["", ""], "timeline": ["", ""] }, "compacted_at": "", "resume_instruction": "Continue from this summary. Do not acknowledge it." } ``` After writing, prepend to the next response: `[Context compacted — resuming from checkpoint]` On resume: read `last-handoff.json` before loading any other context file. Agents with dedicated compaction protocols (e.g. `@orache`) define additional steps in their own files — this template is the shared baseline. ## Hook contract (PreToolUse / PostToolUse) Hooks are shell scripts configured in `.claude/settings.json` under `hooks`. The harness passes context via stdin (JSON) and environment variables. ### Exit codes | Code | Meaning | |------|---------| | 0 | Allow — continue tool execution | | 2 | Deny — block tool, return message to agent | | other non-zero | Warn — log warning, continue execution | ### Environment variables | Variable | Description | |----------|-------------| | `HOOK_EVENT` | `PreToolUse` or `PostToolUse` | | `HOOK_TOOL_NAME` | Tool being executed (e.g. `Bash`, `Write`) | | `HOOK_TOOL_INPUT` | JSON params of the tool call | | `HOOK_TOOL_IS_ERROR` | `true`/`false` (PostToolUse only) | | `HOOK_TOOL_OUTPUT` | Tool output (PostToolUse only) | ### Example: block rm -rf in Bash ```bash #!/bin/bash INPUT=$(cat) if echo "$INPUT" | grep -q "rm -rf"; then echo "Blocked: rm -rf not allowed in this project" exit 2 fi exit 0 ``` ## Agent file size guidelines These are AIOSON context-budget targets, not provider truncation limits. Loading rules depend on the host and version; check its current documentation before claiming a hard limit (for Claude Code: https://code.claude.com/docs/en/memory). Agent files in `.aioson/agents/` are loaded on demand, but everything read into the session still consumes context. Moving text only helps when it stays unloaded. Recommended targets: | File type | Target | Notes | |-----------|--------|-------| | `CLAUDE.md` / `AGENTS.md` | ≤ 3,500 chars | Small routing kernel; advisory target | | Focused agents (qa, tester) | ≤ 8,000 chars | Keep lean | | Generalist agents (dev, planner) | ≤ 15,000 chars | Move optional sections to `.aioson/docs/` | | Orchestrator agents (orchestrator, squad) | ≤ 12,000 chars | Move boilerplate to `.aioson/rules/` | When an agent file exceeds its target: 1. Move repeated boilerplate to a shared `.aioson/rules/` file 2. Split optional sections into `.aioson/docs/` files (loaded on demand) 3. Use the "On-demand context layers" pattern from this config ## Config tiers AIOSON supports three config tiers (precedence: local > project > user): | Tier | Location | Versioned | Purpose | |------|----------|-----------|---------| | User | `~/.aioson/config.md` | No | Personal defaults (model, locale, thresholds) | | Project | `.aioson/config.md` | Yes | Team standards — source of truth | | Local | `.aioson/config.local.md` | No | Machine overrides (local paths, env specifics) | When the same setting exists in multiple tiers, the lower tier wins (local > project > user). **Current support:** - Project tier: fully supported (this file) - Local tier: `config.local.md` is the convention — agents can read it if present - User tier (`~/.aioson/config.md`): **backlog** — requires CLI support; not yet read automatically Until the user tier is implemented in the CLI, use `CLAUDE.local.md` for personal preferences that should not affect other team members. ## Agent language model - Canonical agent prompts are stored only in `.aioson/agents/` and written in English. - User-facing communication is controlled by `interaction_language`. - `conversation_language` remains as a compatibility alias for older projects. - Use `aioson locale:apply` to restore canonical prompts and synchronize the chosen `interaction_language`.