@jaimevalasek/aioson 1.28.1 → 1.30.0

package/template/.aioson/docs/deyvin/pair-execution.md

@@ -1,5 +1,8 @@
 ---
 description: "Deyvin pair execution — working mode, small-slice loop, memory updates, and implementation governance."
+agents: [deyvin]
+task_types: [implementation, pair-session]
+triggers: [pair execution, small slice, polish]
 ---
 
 # Deyvin Pair Execution

package/template/.aioson/docs/deyvin/runtime-handoffs.md

@@ -1,5 +1,8 @@
 ---
 description: "Deyvin runtime and handoffs — tracked session behavior, live milestones, direct sessions, and dashboard visibility."
+agents: [deyvin]
+task_types: [runtime, handoff]
+triggers: [live session, runtime handoff, tracked session]
 ---
 
 # Deyvin Runtime and Handoffs
@@ -35,8 +38,8 @@ 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.
 
-## Cross-session handoffs — persist before /clear
-
-The runtime helpers above cover same-session handoffs (`live:handoff`, `runtime:session:finish`). For cross-session handoffs — when the next agent will run in a fresh terminal or after `/clear` — chat memory does not survive. Before suggesting `/clear`, persist the diagnostic to `plans/{slug}.md` so the next agent works from an artifact rather than from a seed prompt.
+## Cross-session handoffs — persist before /compact or /clear
+
+The runtime helpers above cover same-session handoffs (`live:handoff`, `runtime:session:finish`). For cross-session handoffs — when the next agent will run in a fresh terminal, after `/compact`, or after `/clear` — chat memory may be compressed or unavailable. Before suggesting `/compact` or `/clear`, persist the diagnostic to `plans/{slug}.md` so the next agent works from an artifact rather than from a seed prompt. Prefer `/compact` for same-feature continuation; use `/clear` only for a hard reset, feature switch, polluted context, or security-sensitive reset.
 
 Load `.aioson/docs/handoff-persistence.md` for the full pattern (when to apply, what to write, the exit-block template). Apply it whenever the recommended next agent is one that consumes raw plans (`/aioson:agent:briefing` foremost, sometimes `/aioson:agent:product`) or needs the full diagnostic to operate (`/aioson:agent:analyst`, `/aioson:agent:architect`, `/aioson:agent:sheldon`). Skip when the next agent continues in the same session, or when the handoff is trivial.

package/template/.aioson/docs/dossier/agent-templates.md

@@ -1,5 +1,8 @@
 ---
 description: "Templates concretos por agente da cadeia (9 chain agents) para escrita no dossier via dossier:add-finding, dossier:add-codemap, dossier:link-rule e dossier:add-research. Bumped Phase 4 (agent-chain-continuity): @sheldon override (Why → Agent Trail + Research Index); novos templates para @ux-ui, @pm, @orchestrator; convenção DRIFT: para @dev."
+agents: [product, analyst, sheldon, architect, pm, dev, qa, tester, briefing]
+task_types: [dossier]
+triggers: [dossier, agent trail, add finding]
 ---
 
 # Agent Dossier Templates

package/template/.aioson/docs/dossier/schema.md

@@ -1,5 +1,8 @@
 ---
 description: "Feature dossier schema (canônico v1.0 + v1.1 Phase 3 + v1.2 Research Index) e handoff-protocol artifact_uris v2. Lido por src/dossier/schema.js e src/session-handoff.js — toda mudança aqui exige bump de schema_version."
+agents: [product, analyst, sheldon, architect, pm, dev, qa, tester, briefing]
+task_types: [dossier]
+triggers: [dossier schema, dossier structure]
 ---
 
 # Feature Dossier — Schema canônico

package/template/.aioson/docs/example-external-api-context.md

@@ -1,5 +1,7 @@
 ---
 description: "Template for documenting an external API integration context — replace with real content"
+task_types: [integration]
+triggers: [external api, integration context]
 scope: "global"
 agents: []
 ---

package/template/.aioson/docs/feature-expansion-taxonomy.md

@@ -0,0 +1,53 @@
+---
+name: feature-expansion-taxonomy
+description: "Shared taxonomy for optional feature expansion: classify richer product possibilities without inflating MVP scope."
+agents: [briefing, briefing-refiner, product, sheldon]
+modes: [planning, executing]
+task_types: [feature-expansion, product-discovery, prd-enrichment, briefing-refinement]
+load_tier: trigger
+triggers: [feature expansion, rich surface, MVP options, product scope, capability map, Trello, generator, dashboard, workflow, editor, collaboration]
+---
+
+# Feature Expansion Taxonomy
+
+Use this shared vocabulary when a feature has a rich surface: workflow tools, collaboration, editors/builders, generators, media outputs, dashboards, CRM/Kanban-style systems, automation, templates, customization, or repeated operational use.
+
+Expansion is not approval. It reveals options, classifies value and risk, and makes scope easier to choose.
+
+## Buckets
+
+| Bucket | Meaning |
+|---|---|
+| Core | The minimum needed for the feature to exist. |
+| Recommended MVP | The smallest version that feels genuinely useful, not just technically present. |
+| Optional V1 | Useful additions that can ship in V1 if cost/risk stays low. |
+| Delight | Experience boosters that make the feature feel polished, but are not required. |
+| V2 / Later | Good ideas that should not enter MVP without explicit approval. |
+| Cut List | Ideas that look attractive but should be rejected or deferred for this feature. |
+
+## Expansion Lenses
+
+Check only lenses relevant to the feature:
+
+- Primary objects: entities, documents, posts, cards, boards, templates, reports.
+- User roles: creator, viewer, collaborator, admin, reviewer, owner.
+- Lifecycle states: draft, active, archived, failed, approved, published, scheduled.
+- Actions: create, edit, duplicate, move, assign, comment, approve, export, restore.
+- Repeated-use UX: presets, defaults, saved views, bulk actions, keyboard/drag interactions.
+- Collaboration: members, mentions, comments, assignment, activity log, notifications.
+- Control and trust: permissions, audit trail, undo/redo, validation, moderation, safety limits.
+- Discovery: search, filters, sort, tags, labels, grouping, saved filters.
+- Output quality: preview, variants, formats, export, accessibility, localization.
+- Integrations and automation: imports, exports, webhooks, scheduled jobs, simple rules.
+- Implementation leverage: framework-native features, low-cost libraries, existing modules.
+
+## Required Trace
+
+Every expansion artifact should state:
+
+- whether prior expansion artifacts were found
+- which bucket each suggestion belongs to
+- which ideas need explicit user approval
+- which ideas are intentionally deferred
+- how the expansion affects project classification or delivery risk
+

package/template/.aioson/docs/handoff-persistence.md

@@ -1,94 +1,98 @@
----
-description: "Persist context to plans/{slug}.md before suggesting /clear in a cross-session handoff — preserves the diagnostic so the next agent works from an artifact, not from chat memory."
----
-
-# Handoff Persistence
-
-Load this when you are about to issue a routing recommendation that involves `/clear`, a fresh terminal, or any other context boundary that drops the current conversation. Same-session handoffs (the next agent inherits the same chat) do not need this — skip the doc.
-
-## The problem
-
+---
+description: "Persist context to plans/{slug}.md before suggesting /compact or /clear in a cross-session handoff — preserves the diagnostic so the next agent works from an artifact, not from chat memory."
+task_types: [handoff]
+triggers: [handoff, session persistence, last handoff]
+---
+
+# Handoff Persistence
+
+Load this when you are about to issue a routing recommendation that involves `/compact`, `/clear`, a fresh terminal, or any other context boundary that may compress or drop the current conversation. Same-session handoffs that remain inside the same feature and do not depend on session-only diagnostics usually do not need this — skip the doc unless nuance would be lost.
+
+## The problem
+
 A routing agent (`@neo`, `@deyvin`) ends a session by suggesting:
 1. `/agent` — activate the next agent
-2. `/clear` — fresh context window before continuing
-
-If the recommendation depends on diagnostic work done in this session (file reads, line numbers, decisions made, options weighed), and the user runs `/clear` first, **all of that context is lost**. The next agent reads only the seed prompt the user types — which can never capture the nuance of the actual diagnostic.
-
-A seed prompt is a memory of a conversation. An artifact is a memory of work.
-
-## The rule
-
-Before suggesting `/clear` to the user, persist the actionable diagnostic to `plans/{slug}.md` at the project root. Then the recommendation becomes:
-
-```
+2. `/compact` — preserve continuity while freeing context before continuing
+
+If the recommendation depends on diagnostic work done in this session (file reads, line numbers, decisions made, options weighed), and the user runs `/clear` first, **all of that context is lost**. `/compact` keeps a summary, but it can still compress away low-salience details. The next agent should read a durable artifact instead of relying on a seed prompt or chat memory.
+
+A seed prompt is a memory of a conversation. An artifact is a memory of work.
+
+## The rule
+
+Before suggesting `/compact` or `/clear` to the user, persist the actionable diagnostic to `plans/{slug}.md` at the project root. Then the recommendation becomes:
+
+```
 1. Activate /briefing (or /product / /architect / …)
-2. /clear is safe — the next agent reads plans/{slug}.md
-```
-
-`plans/` is the canonical input directory for `/aioson:agent:briefing` (and a useful seed for `/aioson:agent:product` too). The directory may not exist yet — create it.
-
-## When to apply
-
-| Situation | Persist? |
-|---|---|
-| Handoff routes to an agent that takes raw plans (`/aioson:agent:briefing` first and foremost, sometimes `/aioson:agent:product`) | Yes |
-| Handoff routes to an agent that needs a discovery pass (`/aioson:agent:analyst`, `/aioson:agent:architect`, `/aioson:agent:sheldon`) | Yes — they read context from `.aioson/context/` AND from raw plans |
-| Same-session continuation (`/aioson:agent:dev` keeps going, `/aioson:agent:qa` reviews implementation just done) | No — context is in chat |
-| Handoff happens via tracked live session (`aioson live:handoff`) | No — telemetry already carries the trail |
-| Trivial routing ("you want `/aioson:agent:setup` first") with no diagnostic to preserve | No |
-
-## What to write
-
-Structure of `plans/{slug}.md` (lightweight — `/aioson:agent:briefing` will enrich it):
-
-```md
-# {Short title} — raw plan
-
-> Status: raw input for /{next-agent}. Generated {date} during a /{this-agent} session.
-
-## Why this exists
-1-2 paragraphs framing the problem in the user's terms.
-
-## Symptoms observed
-Concrete pinned facts: line numbers, file paths, command outputs. Not opinions.
-
-## What's already delivered
-If part of the work landed in this session, name the commits/files.
-
-## Proposed scope (if applicable)
-Layers / phases / options the next agent should consider. Mark recommendations.
-
-## Open decisions for the next agent to surface
-Questions that need user input but were out of scope for this session.
-
-## Pointers
-Files, commits, line numbers, related plans/. The next agent reads these directly.
-
-## Out of scope
-What you deliberately did NOT cover. Prevents the next agent from re-litigating.
-```
-
-Slug rules: kebab-case, descriptive, unique inside `plans/`. Examples: `lay-user-agent-mode.md`, `payment-integration.md`, `auth-rewrite-rfc.md`. Avoid generic names like `notes.md` or `plan.md`.
-
-## What to tell the user
-
-After persisting, end with a clear handoff block. Example:
-
-```
-## Next Up
-- Routed to: /briefing
-- Activate: /briefing
-- Context persisted: plans/lay-user-agent-mode.md
-- /clear is safe — the next agent reads from the file
-
-Session artifacts written:
-- [x] plans/lay-user-agent-mode.md
-- [x] {any other files this session produced}
-```
-
-## Anti-patterns
-
-- **Inlining 2 KB of diagnostic as a "seed prompt" in the routing message.** The user shouldn't have to copy-paste a wall of text. Persist it.
-- **Persisting trivial routings.** A user who asks "what does `/aioson:agent:setup` do" doesn't need a `plans/` file written. Apply the table above.
-- **Persisting code archaeology.** Code lives in code; reading recommendations live in the artifact only when they would otherwise be lost across `/clear`.
-- **Forgetting to mention the file.** If you wrote `plans/{slug}.md` but the handoff message doesn't reference it, the user won't know to read it (or to let the next agent read it).
+2. /compact is safe for same-feature continuation — the next agent reads plans/{slug}.md
+3. /clear is safe only if the user wants a hard reset — the next agent still reads plans/{slug}.md
+```
+
+`plans/` is the canonical input directory for `/aioson:agent:briefing` (and a useful seed for `/aioson:agent:product` too). The directory may not exist yet — create it.
+
+## When to apply
+
+| Situation | Persist? |
+|---|---|
+| Handoff routes to an agent that takes raw plans (`/aioson:agent:briefing` first and foremost, sometimes `/aioson:agent:product`) | Yes |
+| Handoff routes to an agent that needs a discovery pass (`/aioson:agent:analyst`, `/aioson:agent:architect`, `/aioson:agent:sheldon`) | Yes — they read context from `.aioson/context/` AND from raw plans |
+| Same-session continuation (`/aioson:agent:dev` keeps going, `/aioson:agent:qa` reviews implementation just done) | No — context is in chat |
+| Handoff happens via tracked live session (`aioson live:handoff`) | No — telemetry already carries the trail |
+| Trivial routing ("you want `/aioson:agent:setup` first") with no diagnostic to preserve | No |
+
+## What to write
+
+Structure of `plans/{slug}.md` (lightweight — `/aioson:agent:briefing` will enrich it):
+
+```md
+# {Short title} — raw plan
+
+> Status: raw input for /{next-agent}. Generated {date} during a /{this-agent} session.
+
+## Why this exists
+1-2 paragraphs framing the problem in the user's terms.
+
+## Symptoms observed
+Concrete pinned facts: line numbers, file paths, command outputs. Not opinions.
+
+## What's already delivered
+If part of the work landed in this session, name the commits/files.
+
+## Proposed scope (if applicable)
+Layers / phases / options the next agent should consider. Mark recommendations.
+
+## Open decisions for the next agent to surface
+Questions that need user input but were out of scope for this session.
+
+## Pointers
+Files, commits, line numbers, related plans/. The next agent reads these directly.
+
+## Out of scope
+What you deliberately did NOT cover. Prevents the next agent from re-litigating.
+```
+
+Slug rules: kebab-case, descriptive, unique inside `plans/`. Examples: `lay-user-agent-mode.md`, `payment-integration.md`, `auth-rewrite-rfc.md`. Avoid generic names like `notes.md` or `plan.md`.
+
+## What to tell the user
+
+After persisting, end with a clear handoff block. Example:
+
+```
+## Next Up
+- Routed to: /briefing
+- Activate: /briefing
+- Context persisted: plans/lay-user-agent-mode.md
+- /compact is recommended — the next agent reads from the file
+- /clear is safe only if you want a hard reset
+
+Session artifacts written:
+- [x] plans/lay-user-agent-mode.md
+- [x] {any other files this session produced}
+```
+
+## Anti-patterns
+
+- **Inlining 2 KB of diagnostic as a "seed prompt" in the routing message.** The user shouldn't have to copy-paste a wall of text. Persist it.
+- **Persisting trivial routings.** A user who asks "what does `/aioson:agent:setup` do" doesn't need a `plans/` file written. Apply the table above.
+- **Persisting code archaeology.** Code lives in code; reading recommendations live in the artifact only when they would otherwise be lost across `/compact` or `/clear`.
+- **Forgetting to mention the file.** If you wrote `plans/{slug}.md` but the handoff message doesn't reference it, the user won't know to read it (or to let the next agent read it).

package/template/.aioson/docs/pentester/app-playbooks.md

@@ -1,5 +1,8 @@
 ---
 description: "Pentester deep playbooks for app_target surfaces TS-A01..A07 — IDOR/BOLA, secrets/crypto, injection/XSS, race/insecure design, auth/rate-limit. Load when review_contract.target_mode = app_target."
+agents: [pentester]
+task_types: [security, pentest]
+triggers: [pentest, app target, security review]
 ---
 
 # Pentester — App Target Playbooks