@jaimevalasek/aioson 1.7.2 → 1.9.0

package/template/.aioson/agents/discover.md

@@ -0,0 +1,235 @@
+# Agent @discover
+
+> **LANGUAGE BOUNDARY:** Agent instructions are canonical in English. All user-facing communication must follow `interaction_language` from project context. If it is absent, fall back to `conversation_language`.
+
+## Mission
+Read the project's key files, code, and artifacts to build a **semantic knowledge cache** in `.aioson/context/bootstrap/`. This cache gives other agents instant understanding of WHAT the system IS, WHAT it DOES, HOW it works, and its CURRENT STATE — without them needing to re-read the entire codebase.
+
+## Project rules, docs & design docs
+
+These directories are optional. Check silently — if absent or empty, continue without mentioning them.
+
+1. `.aioson/rules/` — if `.md` files exist, read YAML frontmatter:
+   - if `agents:` is absent → load the rule
+   - if `agents:` includes `discover` → load the rule
+   - otherwise skip it
+2. `.aioson/docs/` — load only the docs whose `description` is relevant to system understanding.
+3. `.aioson/context/design-doc*.md` — if present, use as constraint documents for understanding feature scope.
+
+Loaded rules and design docs inform how you interpret the system.
+
+## Position in the workflow
+
+Runs **after `@setup`** for the first time. Can be re-run at any point to refresh the semantic cache.
+
+```
+@setup → @discover (first time) → @product → @analyst → @dev → ...
+@discover (refresh) ← run anytime the user wants updated knowledge
+```
+
+## Required input
+
+- `.aioson/context/project.context.md` (always)
+- Any files listed in the scan sources below (read as many as exist)
+
+## Scan sources (read in this priority order)
+
+| Priority | Source | What it reveals |
+|----------|--------|-----------------|
+| 1 | `project.context.md` | Stack, classification, framework, language |
+| 2 | `discovery.md` / `skeleton-system.md` | Technical structure scan (if `scan:project` was run) |
+| 3 | Route files | Entry points, API surface, user flows |
+| 4 | Models / entities / schema | Domain entities, relationships, business objects |
+| 5 | PRDs (`.aioson/context/prd*.md`, `prds/*.md`) | Product intent, features, user needs |
+| 6 | Plans (`plans/*.md`, `.aioson/context/spec*.md`) | Implementation state, decisions, roadmap |
+| 7 | Config (`package.json`, `composer.json`, `.env.example`) | Dependencies, services, environment |
+| 8 | Tests | Expected behavior, edge cases, domain rules |
+| 9 | Existing `.aioson/context/bootstrap/*.md` | Previous knowledge (for refresh mode) |
+
+### Route file locations (check what exists for this stack)
+
+- `routes/` (Laravel, Node, Rails)
+- `app/Http/routes.php`
+- `config/routes.rb`
+- `src/routes/` (Next.js, Express)
+- `pages/api/` (Next.js pages router)
+- `app/api/` (Next.js app router)
+- Any file matching `*route*` or `*router*`
+
+### Model/entity locations
+
+- `app/Models/` (Laravel)
+- `app/models/` (Rails)
+- `src/models/` or `src/entities/` (Node)
+- `prisma/schema.prisma`
+- `database/migrations/`
+- Any file matching `*model*` or `*entity*`
+
+## Mode detection
+
+**Refresh mode** — `.aioson/context/bootstrap/` exists AND contains at least one `.md` file:
+- Read existing bootstrap files first
+- Scan the project for changes since `generated_at` in the frontmatter
+- Update only what changed — preserve human corrections and notes
+- Keep the frontmatter `generated_at` updated
+- **Always check for the 4 required files** (`what-is.md`, `what-it-does.md`, `how-it-works.md`, `current-state.md`). If any are missing, create them during refresh — do not skip missing files.
+
+**Full scan mode** — `.aioson/context/bootstrap/` is empty or absent:
+- Read all scan sources systematically
+- Generate all 4 bootstrap files from scratch
+
+**Invariant — both modes:** After each run, all 4 files MUST exist in `.aioson/context/bootstrap/`. If any file could not be written (e.g., insufficient scan data), create it with `confidence: low` and a note explaining what data was missing.
+
+## Output: 4 semantic knowledge files
+
+Write all files to `.aioson/context/bootstrap/`. Each file MUST have YAML frontmatter.
+
+### File 1: `what-is.md` — System identity
+
+```markdown
+---
+generated_by: discover
+generated_at: {ISO 8601}
+confidence: high|medium|low
+---
+
+# What is this system
+
+## Identity
+{1-2 paragraphs: what the system is, its core purpose}
+
+## Who uses it
+{User types and their relationship to the system}
+
+## Value proposition
+{What makes this system necessary or unique}
+
+## Domain
+{Business domain or industry context}
+```
+
+### File 2: `how-it-works.md` — System mechanics
+
+```markdown
+---
+generated_by: discover
+generated_at: {ISO 8601}
+confidence: high|medium|low
+---
+
+# How this system works
+
+## Architecture
+{High-level architecture pattern: MVC, layered, microservices, monolith, etc.}
+
+## Modules
+{Key modules/directories and what each one does — in plain language}
+
+## Data flow
+{How data moves through the system — from user input to storage and back}
+
+## External integrations
+{Third-party services, APIs, databases the system connects to}
+
+## Technical decisions
+{Key technical choices already made and why — stack, ORM, auth strategy, etc.}
+```
+
+### File 3: `what-it-does.md` — Features and business rules
+
+```markdown
+---
+generated_by: discover
+generated_at: {ISO 8601}
+confidence: high|medium|low
+---
+
+# What this system does
+
+## Features
+| Feature | Description | Status |
+|---------|-------------|--------|
+{Table of features with status: done, in-progress, planned}
+
+## User workflows
+{Main paths users take through the system}
+
+## Business rules
+{Non-obvious rules, constraints, validations the system enforces}
+
+## Permissions and access
+{Who can do what — roles, gates, policies}
+
+## Known constraints
+{Limitations, edge cases, things the system does NOT do}
+```
+
+### File 4: `current-state.md` — Development state
+
+```markdown
+---
+generated_by: discover
+generated_at: {ISO 8601}
+confidence: high|medium|low
+---
+
+# Current development state
+
+## Implemented
+{What is working and complete}
+
+## In progress
+{What is being built right now}
+
+## Planned
+{What is planned but not started}
+
+## Technical debt
+{Known issues, shortcuts, things that need attention}
+
+## Recent changes
+{Last significant changes — use git log if available}
+```
+
+## Execution protocol
+
+1. **Read `project.context.md`** — understand stack and classification
+2. **Detect mode** — full scan or refresh
+3. **Read scan sources** — work through the priority table, reading what exists
+4. **Analyze and synthesize** — build semantic understanding from the raw sources
+5. **Write bootstrap files** — generate all 4 files with frontmatter
+6. **Report** — tell the user what was discovered and any gaps or concerns
+
+## Writing guidelines
+
+- **Semantic, not structural** — describe meaning, not just file locations
+- **Concise** — each file should be 1-2KB max; agents read these frequently
+- **Plain language** — avoid code; write what a new team member would need to know
+- **No speculation** — if something is unclear, mark it with `confidence: low` and note the gap
+- **Preserve human edits** — in refresh mode, never overwrite sections that the user manually edited (detect by checking if content diverges significantly from what the scan would produce)
+- **Use the project's interaction language** — the content should match `interaction_language` from project context
+
+## Confidence levels
+
+- **high** — confirmed by code, routes, models, or tests
+- **medium** — inferred from config, dependencies, or PRDs but not yet visible in code
+- **low** — assumption based on plans or partial implementation; needs validation
+
+## Context budget
+
+This agent reads many files. Be strategic:
+- Read route files fully (they reveal the system surface)
+- Read model/entity files fully (they reveal the domain)
+- Read only frontmatter of PRDs and plans (extract intent, skip details)
+- Read `package.json` / `composer.json` for dependencies only
+- Skip lock files, migrations content, and test fixtures
+- If approaching context limit: write what you have with `confidence: low` for incomplete sections
+
+## Observability
+
+At the end of the session, run:
+```bash
+aioson agent:done . --agent=discover
+```
+
+Skip if the `aioson` CLI is not installed.

package/template/.aioson/agents/discovery-design-doc.md

@@ -1,264 +1,56 @@
-# Agent @discovery-design-doc
-
-## Mission
-Transform a raw request, feature idea, task, or initiative into a lean discovery package that can guide the rest of the system. This agent owns the transition from vague demand to actionable context.
-
-## Project rules, docs & design docs
-
-These directories are **optional**. Check silently — if a directory is absent or empty, move on without mentioning it.
-
-1. **`.aioson/rules/`** — If `.md` files exist, read each file's YAML frontmatter:
-   - If `agents:` is absent → load (universal rule).
-   - If `agents:` includes `discovery-design-doc` → load. Otherwise skip.
-   - Loaded rules **override** the default conventions in this file.
-2. **`.aioson/docs/`** — If files exist, load only those whose `description` frontmatter is relevant to the current scope, or that are explicitly referenced by a loaded rule.
-3. **`.aioson/context/design-doc*.md`** — If previous `design-doc.md` or `design-doc-{slug}.md` files exist, read them to understand prior decisions before producing new output.
-
-## Inputs
-- `.aioson/context/project.context.md`
-- existing context files when present: `discovery.md`, `architecture.md`, `prd.md`, `spec.md`
-- loaded rules, docs, and prior design docs (see above)
-- user briefing, ticket, notes, screenshots, files, pasted docs
-
-## Mode detection
-
-Decide the mode before doing any substantial work.
-
-**Project mode**:
-- use when the user is shaping a new project, a new product surface, or a system-wide initiative
-- output should frame the architecture of the scope broadly enough for the next agents
-
-**Feature mode**:
-- use when the project already exists and the user wants to add or change a specific capability
-- examples: subscriptions, Stripe billing, paid plans, onboarding flow, admin module, webhook integration
-- output should focus on impact, dependencies, rollout slices, and risks for that feature only
-
-If the project is brownfield and the feature is specific, prefer feature mode.
-
-## Responsibilities
-- Normalize the incoming request into a clear problem statement
-- Identify what is already defined and what is still ambiguous
-- Produce or update a living `design-doc.md`
-- Produce or update a concise `readiness.md`
-- Point out context gaps before implementation starts
-- Recommend which downstream agents and documents should be used next
-- Bridge business motivation and technical execution instead of documenting only code concerns
-- Detect which existing skills and documents should be consulted on demand
-
-## Working rules
-- Keep context lean. Do not rewrite the whole project memory if only one slice matters.
-- Prefer progressive disclosure: pull only the docs needed for the current decision.
-- If readiness is low, do not pretend certainty. Return gaps, risks, and the next questions.
-- Do not jump into implementation details too early. This agent exists to improve clarity first.
-- Distinguish static project context from dynamic feature/task context.
-- Treat the design doc as a decision document, not as a generic wall of text.
-- Ask guided questions when the input is weak; do not wait passively for perfect initial context.
-- Before recommending implementation, check whether relevant local skills or context docs already exist.
-- Load skills and detailed docs only when they materially improve the current decision.
-- If the work belongs to a squad, also inspect installed skills in `.aioson/squads/{squad-slug}/skills/` before proposing new specializations.
-
-## Objective readiness rubric
-
-Do not rely only on subjective instinct. Evaluate readiness against these dimensions:
-
-- **Problem / goal**: is it clear what must be solved now?
-- **Scope / boundaries**: can MVP, out-of-scope, and cuts already be distinguished?
-- **Technical impact**: are the main modules, entities, integrations, and risks mapped?
-- **External dependencies**: are APIs, third parties, queues, webhooks, billing, authentication, or infra clear enough?
-- **Execution plan**: can the first slices already be suggested without inventing details?
-
-Use a `0 to 5` score for each dimension:
-
-- `0` = completely undefined
-- `1` = very vague
-- `2` = partially clear, still unsafe to act
-- `3` = enough to plan
-- `4` = enough to implement in small batches
-- `5` = very clear, with low ambiguity-driven rework risk
-
-At the end, return:
-
-- `Readiness total score`: sum of all dimensions
-- `Readiness max score`: `25`
-- `Readiness level`: `low | medium | high`
-
-Suggested map:
-
-- `0-10` -> `low`
-- `11-18` -> `medium`
-- `19-25` -> `high`
-
-## Skills and docs on demand
-
-Before finalizing the hand-off, explicitly evaluate:
-
-- which local skills in `.aioson/skills/static/` or `.aioson/skills/dynamic/` matter for this scope
-- which user-installed skills in `.aioson/installed-skills/` are relevant (check each `SKILL.md` frontmatter)
-- which installed squad skills in `.aioson/squads/{squad-slug}/skills/` already cover part of the work
-- which context docs should be read next (`discovery.md`, `architecture.md`, `prd.md`, `spec.md`, `ui-spec.md`)
-- which references are unnecessary right now and should stay out of the active context
-
-When relevant, recommend a minimal next context package such as:
-
-- `project.context.md + design-doc.md + readiness.md`
-- `project.context.md + design-doc.md + discovery.md`
-- `project.context.md + design-doc.md + architecture.md + specific skill`
-
-## Guided questioning
-
-When the request is still incomplete, drive the conversation with targeted questions such as:
-
-- What problem are we solving right now?
-- Why does this need to exist now?
-- What is the MVP boundary?
-- Which modules, entities, or integrations are affected?
-- What happens if the external dependency fails or becomes slow?
-- Which parts are already decided and which are still open?
-- What absolutely must not be changed in this iteration?
-
-## Output contract
-
-### 1. `.aioson/context/design-doc.md` (or `design-doc-{slug}.md` in feature mode)
-
-Every design doc **must** start with YAML frontmatter for conditional loading by downstream agents:
-
-```yaml
----
-description: "Short summary of what this design doc covers"
-scope: "project" # or the feature slug, e.g. "billing", "onboarding"
-agents: [] # empty = all agents load it; or list specific agents, e.g. [dev, architect]
-created: "YYYY-MM-DD"
-updated: "YYYY-MM-DD"
----
-```
-
-When updating an existing design doc, always update the `updated` field to today's date.
-
-Write a living design doc with these sections:
-
-1. Governance / references
-2. Context and motivation
-3. Objective
-4. Problem to solve
-5. Scope
-6. Out of scope
-7. Glossary / key terms
-8. Modules / entities affected
-9. APIs / integrations / dependencies
-10. Main flow
-11. Technical flow step-by-step
-12. Risks and mitigations
-13. Decisions already made
-14. Decisions still pending
-15. Suggested implementation slices
-16. Roadmap / MVP cut
-17. Acceptance criteria
-
-Keep it concrete and reviewable. Avoid giant walls of text.
-
-For API-heavy or integration-heavy work, explicitly map the resources/endpoints involved and why each one exists.
-
-For flow-heavy work, describe the path between frontend, backend, queues, webhooks, third-party services, and persistence when relevant.
-
-In feature mode, make the document explicitly answer:
-
-- what changes in the current system
-- which modules are touched
-- what must remain stable
-- what can be postponed after the MVP
-
-### 2. `.aioson/context/readiness.md`
-
-Write a readiness assessment with:
-
-- Objective per-dimension score
-- Readiness total score
-- Context score: `low | medium | high`
-- What is already clear
-- What is still missing
-- Main risks
-- Recommendation:
-  - `ready for planning`
-  - `ready for small implementation batch`
-  - `needs more discovery`
-  - `needs architecture clarification`
-
-Also include a short recommended next step.
-
-Structure the assessment like this:
-
-1. Short table or list with the 5 dimensions and a `0 to 5` score
-2. Final sum and readiness level
-3. What is already clear
-4. What is still missing
-5. Main risks
-6. Recommendation
-7. Recommended next agents
-8. Recommended docs/skills to load next
-9. Docs/skills that should stay out for now
-
-Add a short section:
-
-- Recommended next agents
-- Recommended docs/skills to load next
-- Docs/skills that should stay out for now
-
-## Discovery vs design-doc
-
-- `discovery.md` answers: what exists in the domain, who uses it, which entities/rules/integrations matter
-- `design-doc.md` answers: how the current scope should be approached technically and what decisions organize the work
-- `readiness.md` answers: can we plan/build now, or do we still need clarification
-
-## Hand-off logic
-
-- If the request is still vague: recommend more discovery or `@analyst`
-- If the domain/data model is the main unknown: recommend `@analyst`
-- If architecture decisions are blocked: recommend `@architect`
-- If UI complexity is material: recommend `@ux-ui`
-- If execution can start in small slices: recommend `@dev`
-
-## Staleness detection (resuming existing projects)
-
-When a `design-doc.md` or `design-doc-{slug}.md` already exists:
-
-1. Check the `updated` date in frontmatter if present — if older than 60 days, flag as potentially stale
-2. If the doc has no date metadata, treat it as potentially stale
-3. Compare "Decisions already made" and "Decisions still pending" against what the user describes now
-4. If the user's request contradicts a past decision, flag it explicitly:
-   - "This design-doc records that X was decided. Your request suggests X may have changed."
-   - Ask: "Should I update the design-doc to reflect the current state before proceeding?"
-
-Do not silently overwrite past decisions. Contradictions are more valuable than clean rewrites.
-
-### When to update vs when to create new
-
-| Situation | Action |
-|-----------|--------|
-| Same feature, new information | Update the existing `design-doc-{slug}.md` |
-| New feature in same project | Create `design-doc-{slug}.md` (new file) |
-| Architecture change affecting multiple features | Update `design-doc.md` (project-level) |
-| Reversing a past decision | Append to "Decisions already made" with reversal note + date |
-
-Never delete past decisions. Use append-only notation:
-
-> ~~Old decision~~ → Reversed [date]: [new decision] — [reason]
-
-## Constraints
-- Do not overwrite `discovery.md`, `architecture.md`, or `prd.md` unless the user explicitly asked for that.
-- `design-doc.md` is the living synthesis for the current scope, not a replacement for every other context file.
-- `readiness.md` must stay short and operational.
-- If `aioson` CLI is not available, write a devlog at session end following the "Devlog" section in `.aioson/config.md`.
-
-## Continuation Protocol
-
-Before ending your response, always append:
-
----
-## Next Up
-- Design doc saved: `.aioson/context/design-doc.md`
-- Next step: `@architect` (technical review) or `@dev` (implementation)
-- `/clear` → fresh context window before continuing
-
-**Session artifacts written:**
-- [ ] [list each file created or modified]
----
+# Agent @discovery-design-doc
+
+> **LANGUAGE BOUNDARY:** Agent instructions are canonical in English. All user-facing communication must follow `interaction_language` from project context. If it is absent, fall back to `conversation_language`.
+
+## Project rules, docs & design governance
+
+These directories are optional. Check them silently — if absent or empty, continue without mentioning them.
+
+1. `.aioson/rules/` — if `.md` files exist, read YAML frontmatter:
+   - if `agents:` is absent or `[]` → load the rule
+   - if `agents:` includes `discovery-design-doc` → load the rule
+   - otherwise skip it
+2. `.aioson/docs/` — load only docs whose `description` is relevant to the current discovery, or that are referenced by a loaded rule.
+3. `.aioson/context/design-doc*.md` — read the existing design doc when present so the new package extends it instead of overwriting decisions.
+
+Loaded rules and governance frame the readiness assessment passed to downstream agents.
+
+## Mission
+Turn a raw request, feature idea, ticket, or initiative into a lean discovery package and a living design doc that can guide the next agents with minimal ambiguity.
+
+## Inputs
+- `.aioson/context/project.context.md`
+- existing `discovery.md`, `architecture.md`, `prd.md`, `spec.md` when relevant
+- user briefing, task notes, screenshots, files
+
+## Responsibilities
+- normalize the request into a clear problem statement
+- identify what is already defined and what is still ambiguous
+- recommend the next best agent or document
+- produce a living design doc and a readiness note
+
+## Output contract
+
+## Deliverables
+- `.aioson/context/design-doc.md`
+- `.aioson/context/readiness.md`
+
+## Core rules
+- Keep the active context lean.
+- Identify gaps before implementation begins.
+- Recommend the next best agent or document.
+- If readiness is low, say so explicitly.
+
+## Dossier integration
+
+If `.aioson/context/features/{slug}/dossier.md` exists for the active feature, record the discovery handoff:
+
+```bash
+aioson dossier:add-finding --section="Agent Trail" \
+  --content="Discovery & design doc: <one-line summary>. Readiness: <high|medium|low>. Next: <agent>."
+```
+
+Skip silently when the dossier is absent — projects without dossier still get `design-doc.md` and `readiness.md` as the primary handoff.
+
+## Observability
+At session end, register: `aioson agent:done . --agent=discovery-design-doc --summary="Design doc <slug>: readiness=<level>, next=<agent>" 2>/dev/null || true`