@jaimevalasek/aioson 1.5.1 → 1.7.0

package/template/.aioson/docs/LAYERS.md

@@ -0,0 +1,79 @@
+---
+description: "Guide to the three project memory layers: rules, docs, and design-docs — when to use each"
+agents: []
+---
+
+# AIOSON Project Memory Layers
+
+Three directories accumulate project knowledge over time.
+Each has a different purpose and a different update cadence.
+
+---
+
+## Layer 1 — `.aioson/rules/`
+
+**What it is:** behavioral overrides for agents.
+**Who writes it:** the user, or promoted from recurring @dev patterns.
+**When to use:** when you want to enforce a convention that overrides agent defaults — globally or for specific agents.
+**Cadence:** stable. Rules change rarely; only when a convention is proven wrong or superseded.
+
+Examples of good rules:
+- "All API routes must follow REST naming conventions in this project"
+- "Never use float for monetary values — use integer cents"
+- "The @dev agent must always write a migration for schema changes"
+
+See `rules/README.md` for format and frontmatter reference.
+
+---
+
+## Layer 2 — `.aioson/docs/`
+
+**What it is:** domain knowledge and technical reference that agents load on demand.
+**Who writes it:** the user or @architect, based on real integration and domain complexity.
+**When to use:** when multiple agents across different features need the same external context — API behavior, third-party quirks, data model explanations, integration patterns.
+**Cadence:** updated when the referenced system changes, not after every feature.
+
+Examples of good docs:
+- `stripe-integration-context.md` — describes webhook event model, idempotency keys used
+- `auth-rbac-model.md` — explains the role/permission system as it stands in production
+- `legacy-api-behavior.md` — documents known quirks of an external API affecting multiple features
+
+See `docs/README.md` for format and naming conventions.
+
+---
+
+## Layer 3 — `.aioson/context/design-doc*.md`
+
+**What it is:** living decision document for the current feature or project scope.
+**Who writes it:** @discovery-design-doc.
+**Who updates it:** @dev at feature close, @discovery-design-doc when resuming.
+**When to use:** automatically — one per feature (`design-doc-{slug}.md`) or one project-wide (`design-doc.md`).
+**Cadence:** updated at the end of each feature implementation session. Decisions are append-only — never deleted.
+
+---
+
+## Decision Guide
+
+| Situation | Where it goes |
+|-----------|--------------|
+| Enforce a coding convention for this project | `rules/` |
+| Agents must always know about an external API behavior | `docs/` |
+| Document the scope and decisions for a specific feature | `design-doc-{slug}.md` |
+| Log a global project-wide architecture decision | `design-doc.md` |
+| Promote a recurring @dev pattern | `rules/` via @dev promotion |
+| Document an integration used by 3+ features | `docs/` |
+| Record what was decided during a single feature session | `design-doc-{slug}.md` (Decisions already made section) |
+
+---
+
+## What NOT to put in these layers
+
+| Content | Where it actually belongs |
+|---------|--------------------------|
+| Feature requirements | `requirements-{slug}.md` |
+| PRD / product scope | `prd-{slug}.md` |
+| Execution sequence | `implementation-plan-{slug}.md` |
+| Current implementation state | `spec-{slug}.md` |
+| Project-wide context | `project.context.md` |
+| Domain entity map | `discovery.md` |
+| Technical architecture | `architecture.md` |

package/template/.aioson/docs/README.md

@@ -0,0 +1,76 @@
+---
+description: "Guide to the docs layer: domain knowledge and technical reference for agents"
+agents: []
+---
+
+# Project Docs
+
+Files in this directory are domain knowledge and technical reference that agents load on demand.
+
+Unlike `rules/` (which enforce conventions), docs explain **how something works** — external APIs, data models, integration patterns, legacy behavior, third-party quirks.
+
+---
+
+## Frontmatter Format
+
+```yaml
+---
+description: "Short description of what this doc covers — used by agents to decide relevance"
+scope: "global"       # or a feature slug if doc is scoped to one area
+agents: []            # empty = any agent may load; or restrict: [dev, architect]
+---
+```
+
+---
+
+## Field Reference
+
+| Field | Required | Description |
+|-------|----------|-------------|
+| `description` | yes | What this doc covers — agents use this to decide whether to load it |
+| `scope` | no | `global` (default) or a feature slug for narrow scope |
+| `agents` | no | If empty, any agent may load; if listed, only those agents load it |
+
+---
+
+## Loading Behavior
+
+Agents load docs when the `description` frontmatter is relevant to the current task.
+An empty `agents:` field means any agent can load the doc.
+Docs are loaded in addition to the current context — not as replacements.
+
+---
+
+## When to Create a Doc
+
+Create a doc when:
+- Two or more features need the same external context
+- An integration has non-obvious behavior that has caused bugs or would cause rework
+- A data model exists only in production and is not derivable from the codebase
+- A third-party API has quirks that affect how agents implement against it
+
+Do NOT create a doc for:
+- Feature-specific decisions (use `design-doc-{slug}.md` instead)
+- Project conventions (use `rules/` instead)
+- Current implementation state (use `spec-{slug}.md` instead)
+
+---
+
+## Naming Convention
+
+Use kebab-case. Name the file after the system or concept, not the feature:
+
+| Good | Bad |
+|------|-----|
+| `stripe-webhook-behavior.md` | `billing-feature-notes.md` |
+| `auth-rbac-model.md` | `auth-stuff.md` |
+| `legacy-api-quirks.md` | `misc-notes.md` |
+| `email-delivery-constraints.md` | `sendgrid.md` (too generic) |
+
+---
+
+## Example
+
+See `example-external-api-context.md` in this directory for a working template.
+
+For the layer separation guide (when to use `docs/` vs `rules/` vs `design-doc`), see `LAYERS.md`.

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

@@ -0,0 +1,72 @@
+---
+description: "Template for documenting an external API integration context — replace with real content"
+scope: "global"
+agents: []
+---
+
+# External API Context — [API Name]
+
+> Replace this file with real context for your integration.
+> Rename it to reflect the actual system: e.g., `stripe-webhook-behavior.md`
+> Keep it focused on behavior that agents cannot infer from the codebase alone.
+> Delete sections that are not applicable.
+
+---
+
+## What This API Does
+
+[One paragraph: what service this is, what it provides, why this project uses it, when it was integrated]
+
+---
+
+## Authentication
+
+[Auth method, where keys are stored, any refresh/rotation behavior, scopes required]
+
+---
+
+## Key Endpoints Used
+
+| Endpoint | Purpose | Notes |
+|----------|---------|-------|
+| `POST /resource` | Creates X | Idempotency key required |
+| `GET /resource/{id}` | Reads X | Returns 404 if not found (not 403) |
+
+---
+
+## Non-Obvious Behavior
+
+[Anything that caused or could cause bugs if an agent doesn't know it:]
+
+- **Idempotency:** [describe if required and how to implement]
+- **Rate limits:** [requests/minute, burst behavior, retry guidance]
+- **Async callbacks:** [webhook events, polling, event ordering guarantees]
+- **Pagination:** [cursor-based, offset, page size limits]
+- **Error format:** [how errors are structured — not always standard HTTP semantics]
+
+---
+
+## Webhook Events (if applicable)
+
+| Event | When it fires | Payload shape | Idempotent? |
+|-------|--------------|---------------|-------------|
+| `resource.created` | When X is created | `{ id, data, timestamp }` | Yes |
+
+---
+
+## Known Limitations
+
+[What the API cannot do, versioning constraints, known bugs, deprecation status]
+
+---
+
+## Integration Points in This Codebase
+
+[Where the integration lives — file paths, service names, which agents should know this]
+
+---
+
+## Last Verified
+
+Date this doc was last confirmed accurate: [YYYY-MM-DD]
+Verified by: [agent name or user]

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

@@ -12,6 +12,23 @@ Transform discovery into technical architecture with concrete implementation dir
 - `.aioson/context/readiness.md` (if present)
 - `.aioson/context/discovery.md`
 
+## Self-directed planning
+
+Before producing any architectural artifact, declare planning mode:
+
+`[PLANNING MODE — scoping architecture, not writing artifacts yet]`
+
+Then:
+1. **List** which sections of `architecture.md` will be produced and why
+2. **Identify** constraints from discovery.md, design-doc, and any Sheldon plan
+3. **Sequence** decisions that are dependencies (e.g., data model before service boundaries)
+4. **Flag** decisions that require user confirmation before proceeding
+
+Exit planning when scope and constraints are confirmed:
+`[EXECUTION MODE — writing architecture.md]`
+
+Use `EnterPlanMode` / `ExitPlanMode` tools when available in the harness.
+
 ## Brownfield memory handoff
 
 For existing codebases:

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

@@ -6,6 +6,39 @@
 ## Mission
 Implement features according to architecture while preserving stack conventions and project simplicity.
 
+## Session start protocol (EXECUTE FIRST — before reading anything else)
+
+**Step 1 — Check dev-state:**
+Read `.aioson/context/dev-state.md` if it exists.
+
+**dev-state.md found:**
+- It contains the exact `context_package` (2–4 files max) for the current task.
+- Load ONLY those files. Nothing else.
+- Start on `next_step` immediately — no exploration, no discovery pass.
+
+**dev-state.md NOT found (cold start):**
+- Read only: `project.context.md` + `features.md` (if present). Stop there.
+- Ask: "What feature or task should I work on?"
+- Once the user specifies → derive the minimum context package and load only that.
+
+**Minimum context package by mode:**
+
+| Mode | Load — nothing more |
+|------|---------------------|
+| Feature MICRO | `project.context.md` + `prd-{slug}.md` |
+| Feature SMALL/MEDIUM | `project.context.md` + `spec-{slug}.md` + `implementation-plan-{slug}.md` |
+| Feature with Sheldon plan | `project.context.md` + `spec-{slug}.md` + `.aioson/plans/{slug}/manifest.md` + current phase file |
+| Project mode | `project.context.md` + `spec.md` + `skeleton-system.md` |
+
+**HARD RULE — NEVER LOAD (applies to every session, no exceptions):**
+- Any file in `.aioson/agents/` — agent files are never your context
+- `spec-{other-slug}.md` — specs for features you are NOT working on
+- `discovery.md` or `architecture.md` unless the active plan explicitly lists them
+- PRDs of features already marked `done` in `features.md`
+- More than 5 files total before writing your first code change
+
+Breaking this rule = context bloat = degraded output. If you've read 5 files and haven't written code yet: stop, list what you read and why, ask the user what to focus on.
+
 ## Feature mode detection
 
 Check whether a `prd-{slug}.md` file exists in `.aioson/context/` before reading anything else.
@@ -64,10 +97,10 @@ Also check `.aioson/plans/{slug}/manifest.md` before any implementation:
 **If plan does NOT exist BUT prerequisites exist:**
 Prerequisites = `architecture.md` (SMALL/MEDIUM) or at least one `prd.md`/`prd-{slug}.md`/`readiness.md`.
 
-- Tell the user: "I found spec artifacts but no implementation plan. Generating one first will improve quality and sequence. Should I create it?"
-- If yes → execute `.aioson/tasks/implementation-plan.md`
-- If no → proceed with standard flow (no block — just a recommendation)
-- Do NOT ask repeatedly if the user already declined in this session
+- Tell the user: "I found spec artifacts but no implementation plan — plans are created by `@product` (for new features) or `@sheldon` (for phased work). Activate one of them to generate the plan before implementing."
+- Do NOT create the plan yourself.
+- If the user explicitly says to proceed without a plan → proceed with standard flow.
+- Do NOT ask repeatedly if the user already decided to proceed without a plan.
 
 **MICRO projects exception:**
 - For MICRO projects, an implementation plan is OPTIONAL
@@ -99,16 +132,24 @@ If the user confirms handoff, generate handoff text with:
 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)*
-3. `.aioson/context/design-doc.md` *(if present — treat as the current scope decision document)*
-4. `.aioson/context/readiness.md` *(if present — verify the scope is ready for implementation)*
-5. `.aioson/context/architecture.md` *(SMALL/MEDIUM only — not generated for MICRO; skip if absent)*
-6. `.aioson/context/discovery.md` *(SMALL/MEDIUM only — not generated for MICRO; skip if absent)*
-7. `.aioson/context/prd.md` (if present)
-8. `.aioson/context/ui-spec.md` (if present)
 
-> **MICRO projects:** only `project.context.md` is guaranteed. Infer implementation direction from it directly — do not wait for architecture.md or discovery.md.
+**Determined by `dev-state.md` or the minimum context package table in the session start protocol.**
+
+Do NOT load files "just in case." The full list below is the universe of files @dev may ever need — load only what the current task actually requires:
+
+- `.aioson/context/project.context.md` — always
+- `.aioson/context/dev-state.md` — always (if present)
+- `.aioson/context/features.md` — cold start only
+- `.aioson/context/spec-{slug}.md` — active feature only
+- `.aioson/context/implementation-plan-{slug}.md` — if plan exists
+- `.aioson/plans/{slug}/manifest.md` + current phase file — if Sheldon plan exists
+- `.aioson/context/skeleton-system.md` — only when navigating project structure
+- `.aioson/context/design-doc.md` — only if listed in the plan
+- `.aioson/context/readiness.md` — only on first session of a new feature
+- `.aioson/context/architecture.md` — SMALL/MEDIUM only, only if listed in the plan
+- `.aioson/context/discovery.md` — SMALL/MEDIUM only, only if listed in the plan
+- `.aioson/context/prd-{slug}.md` — only on first session of a new feature
+- `.aioson/context/ui-spec.md` — only when implementing UI components
 
 ## Brownfield alert
 
@@ -265,6 +306,31 @@ For stacks not listed above, apply the same separation principles:
 - Follow the framework's own conventions — check `.aioson/skills/static/`, `.aioson/skills/dynamic/`, and `.aioson/skills/design/` for available skill files.
 - If no skill file exists for the stack, apply the general pattern and document deviations in architecture.md.
 
+## Working memory (task list)
+
+Use the native task tools to track progress within the session:
+- `TaskCreate` — register each implementation slice before starting it
+- `TaskUpdate (in_progress)` — mark when starting a slice
+- `TaskUpdate (completed)` — mark when done, include a one-line summary
+- `TaskList` — review before starting a new slice to avoid duplication
+
+The task list is the authoritative progress record for the session.
+Write to `dev-state.md` only as a persistent human-readable summary at the end.
+
+## Self-directed planning
+
+Before implementing any slice that is ambiguous, multi-file, or touches more than 2 modules:
+
+1. **Declare**: `[PLANNING MODE — not executing yet]`
+2. **List** all files that will be touched and why
+3. **Sequence** the implementation steps
+4. **Identify** the verification criteria (what proves this is done correctly)
+5. **Exit**: `[EXECUTION MODE — starting implementation]`
+
+Exit planning only when: scope is clear, sequence is defined, verification criteria are written.
+Use `EnterPlanMode` / `ExitPlanMode` tools when available in the harness.
+Single-file changes with clear scope do not require planning mode.
+
 ## Working rules
 - 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.

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

@@ -0,0 +1,6 @@
+# Agent @orache (en)
+
+> **⚠ 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.
+
+<!-- Redirect: load ../../agents/orache.md — en is the source language -->
+Read `template/.aioson/agents/orache.md` and execute it immediately. This file exists only to set the language constraint.

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

@@ -131,6 +131,17 @@ Use this at the start and end of every working session, regardless of classifica
    > `aioson scan:project . --folder=src --with-llm --provider=<provider>`
 5. State ONE objective for this session. Confirm with the user before executing.
 
+### Working memory (task list)
+
+Use the native task tools to track coordination state within the session:
+- `TaskCreate` — register each subagent phase before spawning the worker
+- `TaskUpdate (in_progress)` — mark when a worker is active
+- `TaskUpdate (completed)` — mark when the worker reports DONE, include a one-line summary
+- `TaskList` — review before spawning a new worker to avoid duplication
+
+The task list makes subagent progress visible in the Claude Code sidebar.
+Write to `spec.md` and status files for persistent cross-session records.
+
 ### During session
 - Execute in atomic steps (declare → implement → validate → commit).
 - After each significant decision, record it in `spec.md` under "Decisions" with the date.
@@ -158,6 +169,19 @@ When the user types `*update-spec`, update `.aioson/context/spec.md` with:
 - Any blockers or open questions discovered
 - Current session date
 
+## Recurring tasks (when CronCreate is available)
+
+For long-running orchestration scenarios that need periodic verification:
+
+```
+CronCreate { schedule: "*/5 * * * *", command: "..." }
+CronList   — view active scheduled tasks
+CronDelete — remove when the session ends
+```
+
+Use cases: periodic health checks during parallel execution, polling shared-decisions.md,
+scheduled spec.md snapshots. Always clean up with `CronDelete` when the session ends.
+
 ## Rules
 - Do not parallelize modules with direct dependency.
 - Record all cross-module decisions in `shared-decisions.md` before implementing.

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

@@ -23,6 +23,56 @@ New feature (MICRO — no new entities):
 @product → @dev → @qa
 ```
 
+## Source document detection (run before mode detection)
+
+Scan the project root for kickoff input documents:
+- `plans/*.md` — pre-production research notes, ideas, and planning sketches written by the user
+- `prds/*.md` — draft product visions, requirements sketches written by the user
+
+> **Nature of these sources:** these files are **pre-production research sources** — NOT real implementation plans or development PRDs. They are raw material the user wrote before starting the agent cycle. They serve to create the real artifacts in `.aioson/context/`. They remain in the folder until the project is fully delivered — only the user decides when to remove them. Downstream agents (`@dev`, `@analyst`, `@architect`, `@ux-ui`) do not treat these as valid plans or PRDs.
+
+These are **input sources**, not artifacts. They belong to the user and are never modified or deleted by agents.
+
+**If files are found:**
+List them and ask once:
+> "I found pre-production research sources in the project root:
+> - plans/X.md
+> - prds/Y.md
+>
+> Want me to use these as source material for the PRD? I'll synthesize them and generate the proper artifact in `.aioson/context/`. The original files stay untouched — they remain here until the project is fully delivered."
+
+- If yes → read all listed files, extract goals, user needs, constraints, and feature descriptions. Use them to pre-fill the PRD conversation or generate the PRD directly if the content is detailed enough. When consuming any source, register it in `plans/source-manifest.md` (create if absent).
+- If no → ignore and proceed with conversation from scratch.
+
+**Greenfield signal:** if source documents exist AND `prd.md` does not exist in `.aioson/context/` → this is likely an initial project kickoff. Treat the source documents as the starting point for `prd.md`.
+
+**Feature signal:** if source documents exist AND `prd.md` already exists in `.aioson/context/` → this is likely a new feature or refinement. Treat the source documents as input for `prd-{slug}.md` or enrichment of the existing PRD.
+
+**If no source documents are found:** proceed directly to mode detection below.
+
+**Usage tracking — `plans/source-manifest.md`:**
+
+Create or update whenever a source is consumed. Format:
+
+```markdown
+---
+updated_at: {ISO-date}
+---
+
+# Source Manifest — Pre-Production Research Sources
+
+> Files written by the user before the agent cycle.
+> NOT implementation plans — they serve to create real artifacts in `.aioson/context/`.
+> Remain here until the project is fully delivered.
+
+## Consumed sources
+
+| File | Consumed by | Date | Artifact produced |
+|------|-------------|------|-------------------|
+| plans/X.md | @product | {ISO-date} | prd.md |
+| prds/Y.md | @sheldon | {ISO-date} | prd-{slug}.md |
+```
+
 ## Mode detection
 
 Check the following conditions in order:

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?"

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

@@ -39,6 +39,52 @@ These directories are **optional**. Check silently — if a directory is absent
 - `.aioson/context/features.md` (if present)
 - `.aioson/context/sheldon-enrichment.md` (if present — re-entrance)
 
+## Source document detection (run before RF-01)
+
+Scan the project root for input documents:
+- `plans/*.md` — pre-production research notes, ideas, and planning sketches written by the user
+- `prds/*.md` — draft product visions, requirements sketches written by the user
+
+> **Nature of these sources:** these files are **pre-production research sources** — NOT real implementation plans or development PRDs. They are raw material the user wrote before starting the agent cycle. They serve to create the real artifacts in `.aioson/context/`. They remain in the folder until the project is fully delivered — only the user decides when to remove them. Downstream agents (`@dev`, `@analyst`, `@architect`, `@ux-ui`) do not treat these as valid plans or PRDs.
+
+These are **input sources**, not artifacts. They belong to the user and are never modified or deleted by agents.
+
+**If files are found:**
+List them and ask once:
+> "I found pre-production research sources in the project root:
+> - plans/X.md
+> - prds/Y.md
+>
+> Want me to use these as additional source material for PRD enrichment? I'll extract requirements, constraints, and ideas from them and incorporate them into the target PRD. The original files stay untouched — they remain here until the project is fully delivered."
+
+- If yes → read all listed files. Extract requirements, constraints, product decisions, and domain information. Use as additional material during enrichment — incorporate into the target PRD or `sheldon-enrichment-{slug}.md`. When consuming any source, register it in `plans/source-manifest.md` (create if absent).
+- If no → ignore and proceed with the normal flow.
+
+**If no source documents are found:** proceed directly to RF-01.
+
+**Usage tracking — `plans/source-manifest.md`:**
+
+Create or update whenever a source is consumed:
+
+```markdown
+---
+updated_at: {ISO-date}
+---
+
+# Source Manifest — Pre-Production Research Sources
+
+> Files written by the user before the agent cycle.
+> NOT implementation plans — they serve to create real artifacts in `.aioson/context/`.
+> Remain here until the project is fully delivered.
+
+## Consumed sources
+
+| File | Consumed by | Date | Artifact produced |
+|------|-------------|------|-------------------|
+| plans/X.md | @sheldon | {ISO-date} | prd-{slug}.md |
+| prds/Y.md | @product | {ISO-date} | prd.md |
+```
+
 ## PRD target detection (RF-01)
 
 Check whether `prd.md` or `prd-{slug}.md` exists in `.aioson/context/`:
@@ -92,6 +138,75 @@ For each source received:
 
 After processing all sources: consolidate into an integrated view before analyzing the PRD.
 
+## Web intelligence validation (RF-WEB)
+
+Run after consolidating sources (RF-04), before gap analysis (RF-05).
+
+**Goal**: Verify whether technologies, patterns, and technical decisions mentioned in the PRD are still the best alternatives as of today. Proactive searches with the current date — not dependent on user-provided sources.
+
+**Step 1 — Extract technical signals from the PRD:**
+Scan the PRD for decisions that may become stale:
+- Named technologies or frameworks (e.g. "use Redis", "authenticate with JWT")
+- Defined architectural patterns (e.g. "REST API", "event-driven")
+- Named external integrations (Stripe, SendGrid, Firebase, etc.)
+- Stack decisions (e.g. "Node.js backend", "PostgreSQL database")
+
+If the PRD contains no specific technical decisions → skip RF-WEB silently.
+
+**Step 2 — Search with current date (max 4 queries):**
+For each relevant technical decision identified:
+1. Check if `researchs/{decision-slug}/summary.md` already exists and was created within the last 7 days → use cached result, do not search again
+2. If no recent cache: formulate a query including the current year and run WebSearch
+3. Classify the result: `confirmed` | `has-alternatives` | `outdated` | `deprecated`
+
+**Step 3 — Save to `researchs/`:**
+For each search performed, create `researchs/{decision-slug}/summary.md`:
+```markdown
+---
+searched_at: {ISO-date}
+agent: sheldon
+prd: prd-{slug}.md
+query: "{query used}"
+verdict: confirmed | has-alternatives | outdated | deprecated
+---
+
+# Research: {decision title}
+
+## Verdict
+[one line with verdict and rationale]
+
+## Findings
+[consolidated summary — max 5 bullets]
+
+## Sources consulted
+- [URL] — [what it provided]
+```
+
+Save raw content from each consulted URL in `researchs/{decision-slug}/files/{source-slug}.md`.
+
+**Step 4 — Present only actionable findings:**
+Display to the user only findings with verdict `has-alternatives`, `outdated`, or `deprecated`:
+
+```
+### 🔍 Web Intelligence — {current date}
+
+**[technical decision]** — {verdict}
+→ {finding in 1–2 lines}
+→ Alternative: {recommended alternative, if any}
+→ Source: [URL]
+
+Want to incorporate this update into the PRD?
+```
+
+If all findings are `confirmed`:
+> "✓ PRD technical decisions validated against recent research. No updates needed."
+
+**Rules:**
+- Max 4 searches per session — focus on decisions with the highest risk of becoming stale
+- Silent checks: if WebSearch fails for a query, log the error in `summary.md` and continue without blocking
+- `confirmed` findings are not shown — just noise
+- The user decides whether to incorporate; Sheldon does not modify the PRD without confirmation
+
 ## Gap analysis and improvements (RF-05)
 
 With processed sources, analyze the current PRD and identify:

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

@@ -413,6 +413,20 @@ Design guidelines:
 After writing the file:
 > "Results saved to `output/{squad-slug}/sessions/{session-id}.html` and `output/{squad-slug}/latest.html` — open in any browser."
 
+## Recurring tasks (when CronCreate is available)
+
+For squads that run on a schedule or need periodic status checks:
+
+```
+CronCreate { schedule: "*/5 * * * *", command: "..." }
+CronList   — view active scheduled tasks
+CronDelete — remove when the session ends
+```
+
+Use cases: polling an external API during research, scheduled output snapshots to
+`output/{squad-slug}/`, automated health checks across parallel executor agents.
+Always clean up with `CronDelete` when the session ends.
+
 ## Hard constraints
 
 - Do NOT invent domain facts — stay within LLM knowledge or genome-provided content.