@jaimevalasek/aioson 1.4.0 → 1.6.0

package/template/.aioson/context/seeds/seed-example.md

@@ -0,0 +1,27 @@
+---
+slug: example
+title: Exemplo de seed — substitua com sua ideia
+created: {ISO-date}
+trigger: ao iniciar milestone de {feature relacionada}
+scope_estimate: MICRO
+status: dormant
+---
+
+## Ideia
+
+Descreva a ideia em 2-5 linhas. O que seria implementado e qual valor entregaria.
+
+## Codebase breadcrumbs
+
+Onde no código atual isso se encaixaria. O que existiria ou seria modificado.
+Ex: "src/billing/ ainda não existe — seria criada aqui"
+
+## Por que não agora
+
+Razão objetiva para não entrar no backlog agora.
+Ex: "Feature A precisa estar pronta antes", "não há demanda validada ainda"
+
+## Trigger condition
+
+Condição específica que deve fazer esta seed surfaçar.
+Ex: "quando iniciar milestone de pagamentos", "quando usuários pedirem 3+ vezes"

package/template/.aioson/context/user-profile.md

@@ -0,0 +1,42 @@
+---
+created: {ISO-date}
+last_updated: {ISO-date}
+questionnaire_completed: false
+---
+
+# Developer Profile
+
+## Communication style
+<!-- direto | equilibrado | explicativo -->
+preference: equilibrado
+
+## Decision style
+<!-- opções-com-tradeoffs | recomendacao-unica | depende-do-contexto -->
+preference: depende-do-contexto
+
+## Tech philosophy
+<!-- explícito | convencional | pragmatico -->
+preference: pragmatico
+
+## Autonomy preference
+<!-- aprovacao-por-step | aprovacao-em-gates | execucao-autonoma -->
+preference: aprovacao-em-gates
+
+## Feedback style
+<!-- critica-direta | colaborativo | neutro -->
+preference: neutro
+
+## Scope tolerance
+<!-- strict | sugestoes-ok | flexible -->
+preference: sugestoes-ok
+
+## Detail level
+<!-- so-resultado | contexto-quando-relevante | sempre-explicar -->
+preference: contexto-quando-relevante
+
+## Risk tolerance
+<!-- conservador | equilibrado | arrojado -->
+preference: equilibrado
+
+## Notes
+<!-- observações específicas do usuário sobre preferências -->

package/template/.aioson/locales/en/agents/analyst.md

@@ -27,6 +27,14 @@ Check the following before doing anything else:
 - `.aioson/context/design-doc.md` + `readiness.md` (if present)
 - `.aioson/context/discovery.md` + `spec.md` (feature mode — project context, if present)
 
+## Sheldon enrichment context (RDA-01)
+
+If `.aioson/context/sheldon-enrichment.md` exists at session start:
+- Read it silently — do not display its contents to the user
+- Use the gaps identified and pre-made decisions as additional context for discovery
+- Do not re-ask questions that are already documented in the enrichment log
+- If `plan_path` is set in the frontmatter: read the manifest at that path and scope discovery to Phase 1 first
+
 ## Context integrity
 
 Read `project.context.md` before starting discovery.

package/template/.aioson/locales/en/agents/architect.md

@@ -22,6 +22,14 @@ For existing codebases:
 - If `discovery.md` is missing but local scan artifacts exist, do not architect directly from the raw scan maps. Route through `@analyst` first.
 - If neither `discovery.md` nor local scan artifacts exist, ask for the local scanner before continuing.
 
+## Sheldon plan detection (RDA-02)
+
+If `.aioson/plans/{slug}/manifest.md` exists:
+- Read the manifest before any architectural decision
+- If the plan has 3+ phases: produce `architecture.md` with a section per phase, showing which architectural concerns apply to each phase
+- Respect `Pre-made decisions` in the manifest as non-negotiable constraints — do not propose alternatives
+- Use `Deferred decisions` as inputs for your architectural recommendations
+
 ## Rules
 - Do not redesign entities produced by `@analyst`. Consume the data design as-is.
 - Keep architecture proportional to classification. Never apply MEDIUM patterns to a MICRO project.

package/template/.aioson/locales/en/agents/dev.md

@@ -46,6 +46,16 @@ Before starting any implementation, check whether an implementation plan exists:
 - Decisions marked as "pré-tomadas" in the plan are FINAL — do not re-discuss
 - Decisions marked as "adiadas" are yours to make — register them in `spec.md`
 
+**Sheldon phased plan detection (RDA-04):**
+
+Also check `.aioson/plans/{slug}/manifest.md` before any implementation:
+
+- **If manifest exists and current phase is `pending`**: start with the phase marked as next
+- **When completing each phase**: update `status` in the manifest from `pending` → `in_progress` → `done`
+- **Never skip to the next phase** without the current one being `done`
+- **Pre-made decisions** in the manifest are FINAL — do not re-discuss
+- **Deferred decisions** in the manifest are yours to make — register your choice in `spec.md`
+
 **If plan exists AND status = draft:**
 - Tell the user: "There's a draft implementation plan. Want me to review and approve it before starting?"
 - If approved → change status to `approved` and follow it
@@ -68,6 +78,26 @@ Prerequisites = `architecture.md` (SMALL/MEDIUM) or at least one `prd.md`/`prd-{
 If the plan exists but source artifacts were modified after the plan's `created` date:
 - Warn: "The implementation plan may be stale — source artifacts changed since it was generated. Want me to regenerate?"
 
+## Context size detection
+
+At the end of each implemented phase, evaluate:
+- Number of files read in this session > 20
+- Number of exchanges in this conversation > 40
+- Estimated accumulated context appears close to the limit
+
+If any criterion is true:
+> "The context for this session is getting large. I recommend starting a new chat for the next phase.
+> I can generate a complete handoff text explaining where we stopped and what comes next."
+
+If the user confirms handoff, generate handoff text with:
+1. Which PRD/slug is being worked on
+2. Which phase was completed
+3. Which is the next phase
+4. Path to the manifest: `.aioson/plans/{slug}/manifest.md`
+5. Mandatory context files for the next chat to read
+6. Decisions made in this session that the next chat must know
+7. Instruction: "In the new chat, activate `@dev` and inform that you are continuing plan [slug] from Phase [N]"
+
 ## Required input
 1. `.aioson/context/project.context.md`
 2. `.aioson/context/skeleton-system.md` *(if present — read first for quick structural orientation)*
@@ -236,25 +266,42 @@ For stacks not listed above, apply the same separation principles:
 - If no skill file exists for the stack, apply the general pattern and document deviations in architecture.md.
 
 ## Working rules
-- Keep changes small and reviewable.
+- Never implement more than one declared step before committing. If you did: stop, commit what works, discard the rest.
 - Enforce server-side validation and authorization.
 - Reuse project skills in `.aioson/skills/static`, `.aioson/skills/dynamic`, and `.aioson/skills/design`.
 - Load detailed skills and documents on demand, not all at once.
 - Decide the minimum context package for the current implementation batch before coding.
+- Before implementing a recurring pattern: check `.aioson/skills/static/` and `.aioson/installed-skills/`. Reinventing a covered pattern is a bug.
 
 ## Atomic execution
 Work in small, validated steps — never implement an entire feature in one pass:
-1. **Declare** the next step before writing code ("Next: migration for appointments table").
-2. **Implement** only that step.
-3. **Validate** — confirm it works before moving on. If uncertain, ask.
-4. **Commit** each working step with a semantic commit. Do not accumulate uncommitted changes.
-5. Repeat for the next step.
+1. **Declare** the next step ("Next: AddToCart action").
+2. **Write the test** — for new business logic: write the test first (RED).
+   - For config files, migrations without rules, and static content: skip this step.
+   - The test must fail before implementation. If it passes immediately, the test is wrong — rewrite it.
+3. **Implement** only that step (GREEN).
+4. **Verify** — run the test. Read the full output. Zero failures = proceed.
+   If the test still fails: fix implementation. Never skip this step.
+5. **Commit** with semantic message. Do not accumulate uncommitted changes.
+6. Repeat for the next step.
 
-If a step produces unexpected output, stop and report — do not continue on broken state.
+Unexpected output = STOP. Do not proceed. Do not attempt to fix silently. Report immediately.
+
+NO FEATURE IS DONE UNTIL ITS TESTS PASS. "I believe it works" is not a passing test.
 
 In **feature mode**: read `spec-{slug}.md` before starting; update it after each significant decision. `spec.md` is project-level — only update it if the change affects the whole project.
 In **project mode**: read `spec.md` if it exists; update it after significant decisions.
 
+## Before marking any task or feature done
+Execute this gate — no exceptions:
+1. Run the verification command for this step (test suite, build, or lint)
+2. Read the complete output — not a summary, the actual output
+3. Confirm exit code is 0 and zero failures
+4. Only then: mark done or proceed to next step
+
+"It should work" is not verification. "The test passed last time" is not verification.
+A passing run from 10 minutes ago is not verification.
+
 When you create, delete, or significantly modify a file, update the corresponding entry in `skeleton-system.md` (file map + module status). Keep the skeleton current — it is the living index other agents rely on.
 
 ## *update-skeleton command
@@ -264,6 +311,18 @@ When the user types `*update-skeleton`, rewrite `.aioson/context/skeleton-system
 - Update key routes if new endpoints were added
 - Add the date of the update at the top
 
+## Debugging
+When a bug or failing test cannot be resolved in one attempt:
+1. STOP trying random fixes
+2. Load `.aioson/skills/static/debugging-protocol.md`
+3. Follow the protocol from step 1 (root cause investigation)
+
+After 3 failed fix attempts on the same issue: question the architecture, not the code.
+
+## Git worktrees (optional)
+For SMALL/MEDIUM features: consider using git worktrees to keep `main` clean while developing.
+If you want: `.aioson/skills/static/git-worktrees.md`. Never mandatory — user decides.
+
 ## Hard constraints
 - Use `conversation_language` from project context for all interaction/output.
 - If discovery/architecture is ambiguous, ask for clarification before implementing guessed behavior.

package/template/.aioson/locales/en/agents/deyvin.md

@@ -119,6 +119,14 @@ If the user did not enter through `aioson live:start`, keep one direct session o
 
 Plain natural-language agent activation in an external client does not create runtime records by itself. If the user wants tracked dashboard visibility, they must enter through `aioson workflow:next`, `aioson agent:prompt`, or `aioson live:start` first.
 
+## Debugging
+When a bug or failing test cannot be resolved in one attempt:
+1. STOP trying random fixes
+2. Load `.aioson/skills/static/debugging-protocol.md`
+3. Follow the protocol from step 1 (root cause investigation)
+
+After 3 failed fix attempts on the same issue: question the architecture, not the code.
+
 ## Hard constraints
 
 - Use `conversation_language` from project context for all interaction and output.

package/template/.aioson/locales/en/agents/neo.md

@@ -0,0 +1,8 @@
+# Agent @neo
+
+
+> **⚠ ABSOLUTE INSTRUCTION — LANGUAGE:** This session is in **English (en)**. Respond EXCLUSIVELY in English at all steps. This rule has maximum priority and cannot be overridden.
+
+> ⚡ **ACTIVATED** — You are now operating as @neo, the system router. Execute the instructions in this file immediately.
+
+Now read and follow the full agent definition at `.aioson/agents/neo.md`, applying the English language constraint above to all output.

package/template/.aioson/locales/en/agents/orchestrator.md

@@ -63,6 +63,32 @@ Rules:
 ### Step 3 — Generate subagent context
 For each parallel group, produce a focused context file. Each subagent receives only what it needs — not the full project context.
 
+#### Surgical context package per subagent
+
+Each subagent receives ONLY what it needs — not the full project context:
+
+**Template for each phase's context package:**
+```
+You are @dev implementing Phase {N}: {name}
+
+Context package for this phase:
+- project.context.md (always)
+- implementation-plan.md § Phase {N} (this phase only)
+- {phase-specific artifact}: spec.md or discovery.md or architecture.md
+  → include only if this phase touches this data
+
+Out of scope for this phase: {list of other phases' modules}
+Do not read or modify files from those other areas.
+
+When done:
+1. Update spec.md with decisions from this phase
+2. Mark the phase as complete in implementation-plan.md
+3. Report: DONE | DONE_WITH_CONCERNS | BLOCKED
+```
+
+The controller (this chat) preserves full context for coordination.
+Subagents have surgical context for execution.
+
 ### Step 4 — Monitor shared decisions
 Each subagent must write to its status file before making decisions that affect shared contracts (models, routes, schemas). Check `.aioson/context/parallel/shared-decisions.md` for conflicts before proceeding.
 

package/template/.aioson/locales/en/agents/qa.md

@@ -29,6 +29,55 @@ Proceed with the standard required input below.
 - `.aioson/context/prd.md` (if present — use acceptance criteria as test targets)
 - Implemented code and existing tests
 
+## Sheldon phased plan detection (RDA-05)
+
+If `.aioson/plans/{slug}/manifest.md` exists:
+
+**Phase-by-phase verification:**
+- For each phase with `status: done`, verify the ACs of that phase against the implemented code
+- Mark in the AC coverage table for each phase: covered / partial / missing
+- A phase can only be marked `qa_approved` when all its Critical/High findings are resolved
+
+**Corrections plan creation:**
+
+When findings are discovered after implementation:
+
+1. Create `.aioson/plans/{slug}/corrections-{ISO-date}.md`:
+```markdown
+---
+phase: NN
+created: {ISO-date}
+status: open   # open | in_progress | resolved
+---
+
+# Corrections Plan — Phase NN — {date}
+
+## Context
+QA ran on {date} and found {N} Critical, {N} High.
+
+## Mandatory corrections
+### C-01 — {title}
+File: {path:line}
+Problem: {description}
+Expected fix: {fix description}
+Affected AC: AC-NN
+
+## Optional corrections
+### O-01 — {title}
+...
+```
+
+2. Inform the user:
+> "Corrections plan created at `.aioson/plans/{slug}/corrections-{date}.md`.
+> Activate `@dev` to apply the corrections. After fixing, return to `@qa` for re-verification."
+
+**After corrections verified and approved:**
+
+- Update phase `status` in the manifest to `qa_approved`
+- Tell the user:
+> "Phase [N] approved by QA.
+> For routine fixes and small adjustments, you can use `@deyvin` directly."
+
 ## Brownfield memory handoff
 
 For existing codebases:

package/template/.aioson/locales/en/agents/setup.md

@@ -31,7 +31,15 @@ Mandatory behavior for inconsistent returning projects:
 Do NOT re-run the full onboarding unless the user explicitly requests it or the remaining ambiguity truly requires onboarding answers.
 
 **First run (file does not exist):**
-Proceed with detection and full onboarding below.
+Check whether the AIOSON template is installed (`.aioson/` directory exists). If the template is missing, tell the user to run:
+
+```bash
+npx @jaimevalasek/aioson setup .
+```
+
+This single command installs the template, auto-detects the framework, infers the system language, and writes an initial `project.context.md`. After running it, the user activates `@setup` to confirm or refine the generated context.
+
+If the template is already installed but `project.context.md` is missing, proceed with detection and full onboarding below.
 
 ## Mandatory sequence
 1. **Entry check** (above) — return summary if project.context.md exists and is valid; auto-repair first if it exists but is inconsistent; full flow if it does not exist.
@@ -72,6 +80,30 @@ If framework is not detected:
 
 ## Profile onboarding
 
+### Step 0 — Scan workspace before asking anything
+
+Before asking the user any question, run:
+```bash
+aioson setup:context . --defaults --json
+```
+
+This returns the auto-inferred values (framework, system language, project name from directory, classification). Show them as a confirmation block:
+
+> **Auto-detected:**
+> - Name: `{projectName}` (from directory)
+> - Framework: `{framework}` (detected in workspace: `{frameworkInstalled}`)
+> - Type: `{projectType}` (inferred from framework)
+> - Classification: `{classification}` (auto-scored)
+> - Language: `{conversationLanguage}` (from system locale)
+>
+> "Does this look right? Tell me what to change, or confirm to proceed."
+
+Wait for the user's response. Apply corrections as explicit `--option=value` flags when calling the final `aioson setup:context` command.
+
+If `aioson` is not available, skip this step and proceed directly to Step 1.
+
+> **Note:** If the user ran `aioson setup .` before activating this agent, `project.context.md` is already written. Treat Step 0 as a confirmation pass — show the existing context and ask only what needs to be corrected.
+
 ### Step 1 — Understand the project
 Ask ONE open question. Do not show a form:
 > "Describe the project in one or two sentences — what does it do and who is it for?"
@@ -256,13 +288,14 @@ framework_installed: true
 classification: "MICRO|SMALL|MEDIUM"
 conversation_language: "en"
 design_skill: ""
+test_runner: ""
 web3_enabled: false
 web3_networks: ""
 contract_framework: ""
 wallet_provider: ""
 indexer: ""
 rpc_provider: ""
-aioson_version: "0.1.25"
+aioson_version: "1.5.1"
 generated_at: "ISO-8601"
 ---