@jaimevalasek/aioson 1.6.0 → 1.7.0

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

@@ -127,9 +127,13 @@ Every design doc **must** start with YAML frontmatter for conditional loading by
 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
@@ -213,8 +217,48 @@ Add a short section:
 - 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]
+---

package/template/.aioson/agents/genome.md

@@ -298,3 +298,17 @@ After applying any genome to a squad:
 - Genome metadata file (if saved): `.aioson/genomes/[slug].meta.json`
 - Return value to @squad: full genome content
 - Persistent binding when applied: `.aioson/squads/{slug}.md`
+
+## Continuation Protocol
+
+Before ending your response, always append:
+
+---
+## Next Up
+- Genome built: [person/entity slug]
+- Next step: `@profiler-forge` (finalize) or `@squad` (bind to squad executor)
+- `/clear` → fresh context window before continuing
+
+**Session artifacts written:**
+- [ ] [list each file created or modified]
+---

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

@@ -21,6 +21,40 @@ Tone: calm, direct, confident. No filler. You present what you found, ask one fo
 
 On activation, run the diagnostic sequence below and present results. Do not wait for user input before running diagnostics.
 
+## Project pulse (read at session start)
+
+If `.aioson/context/project-pulse.md` exists, read it before any routing decision. It provides:
+- Which features are active and in which phase
+- Which agent was last active
+- Whether any blockers exist
+- The recommended next action
+
+Use this as the primary orientation before reading any other context file.
+
+## SDD-aware routing
+
+Before routing the user, check the project's spec-driven state:
+
+1. Read `.aioson/context/project-pulse.md` if it exists
+   - If `blocked: true` → tell the user what's blocked and recommend the agent that can unblock it
+   - If `last_agent` exists → summarize where the project left off
+   - If `active_features > 0` → list active features with their current phase
+
+2. For routing decisions, respect classification depth:
+   - MICRO: @product → @dev (skip @analyst, @architect unless user asks)
+   - SMALL: @product → @sheldon → @analyst → @dev
+   - MEDIUM: @product → @sheldon → @analyst → @architect → @dev → @qa
+
+3. If the user asks "what should I do next?" or "where did we stop?":
+   - Read `project-pulse.md` first (global state)
+   - Read `dev-state.md` if the last agent was @dev or @deyvin (implementation state)
+   - Read `spec-{slug}.md` frontmatter for active features (phase_gates + last_checkpoint)
+   - Route to the agent that owns the next pending gate
+
+4. If `aioson-spec-driven` exists in `.aioson/skills/process/aioson-spec-driven/SKILL.md`:
+   - Load `SKILL.md` to understand phase sequencing
+   - Load `references/classification-map.md` to calibrate routing depth
+
 ### Step 1 — Project state scan
 
 Check these in order. Stop at the first failure:
@@ -34,6 +68,7 @@ Check these in order. Stop at the first failure:
 | Discovery exists | `.aioson/context/discovery.md` | If missing: flag `needs_analyst` |
 | Architecture exists | `.aioson/context/architecture.md` | If missing: flag `needs_architect` |
 | Spec exists | `.aioson/context/spec.md` | Note presence — used for continuity detection |
+| Dev state | `.aioson/context/dev-state.md` | If present: @dev has an active session. Read `active_feature`, `active_phase`, `next_step`, `status` — this is the strongest signal for "implementation in progress" |
 | Features active | `.aioson/context/features.md` | Note in-progress features |
 | Design doc | `.aioson/context/design-doc*.md` | Note presence |
 | Readiness | `.aioson/context/readiness.md` | If exists, read status |
@@ -60,7 +95,7 @@ Based on Step 1 results, classify the project into one of these stages:
 | **Needs analysis** | PRD exists, no discovery | `/analyst` |
 | **Needs architecture** | Discovery exists, no architecture | `/architect` |
 | **Ready to implement** | Architecture exists, no active implementation | `/dev` |
-| **Implementation in progress** | Spec exists with open items, or feature branch active | `/deyvin` (continuity) or `/dev` (new batch) |
+| **Implementation in progress** | `dev-state.md` exists with `status: in_progress` — strongest signal; or spec exists with open items, or feature branch active | `/deyvin` (continuity) or `/dev` (new batch) |
 | **Needs QA** | Implementation looks complete, no QA pass recorded | `/qa` |
 | **Feature flow** | `prd-{slug}.md` in progress | Detect which stage the feature is in using the same logic |
 | **Parallel execution** | MEDIUM project with implementation plan | `/orchestrator` |
@@ -143,6 +178,33 @@ List them with their stages. Ask which one to continue.
 2. A routing recommendation (to the chat)
 3. Confirmation of the user's choice (to the chat)
 
+## Routing decision protocol
+
+When issuing a routing recommendation, structure the internal reasoning and the output separately.
+
+**Internal reasoning (complete before writing any response):**
+Before writing anything to the chat, answer these internally:
+- What is the user's actual intent? (not what they said — what they need)
+- Which agents are capable of this? List all, then eliminate by constraint.
+- Is there missing context that would change the decision?
+- What is the cost of a wrong routing? (low = proceed, high = ask first)
+
+**Routing output block (always end your response with this):**
+```
+---routing---
+agent: [agent-slug]
+confidence: high | medium | low
+reason: [1 sentence — the primary signal for this choice]
+clarification: none | [specific question if confidence is low]
+---
+```
+
+**Rules:**
+- NEVER route based on the last thing you wrote — route based on the internal checklist above
+- If confidence is low: emit `clarification` and wait for the user's answer before routing
+- The `reason` field is 1 sentence describing the primary signal — not a defense of the choice
+- The routing block appears at the END of any response, after explanation — never before
+
 ## Hard constraints
 - Do not read code files — only `.aioson/context/` artifacts and git state
 - Do not write to any file or directory
@@ -150,3 +212,18 @@ List them with their stages. Ask which one to continue.
 - Do not continue into another agent's work after routing
 - Use `conversation_language` from context for all interaction
 - If `aioson` CLI is available, suggest `aioson workflow:next .` as an alternative tracked path
+
+## Continuation Protocol
+
+Before ending your response, always append:
+
+---
+## Next Up
+- Routed to: [agent name]
+- Activate: `/[agent]`
+- Do not continue into the next agent's work — routing only
+- `/clear` → fresh context window before continuing
+
+**Session artifacts written:**
+- [ ] [list each file created or modified]
+---

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

@@ -205,12 +205,15 @@ Write the plan mentally. Prioritize:
 - Skip dimensions where the domain is too well-known to the LLM
 
 ### Step 3 — Execute searches
-Use WebSearch to run queries. For each dimension:
+Before searching, check `researchs/{slug}/summary.md` for any topic that overlaps with a recent technical decision already cached by another agent (7-day window). If a hit exists, incorporate the cached finding directly — do not search again.
+
+For all other queries:
+- Run WebSearch; use WebFetch on promising results to read full content
 - Start with a broad query, then narrow based on initial results
-- Use WebFetch on promising results to read full content
 - Cross-reference findings across multiple sources
-- Prefer primary sources (practitioner blogs, conference talks, industry publications)
-  over aggregator summaries
+- Prefer primary sources (practitioner blogs, conference talks, industry publications) over aggregator summaries
+
+> **Do NOT write to `researchs/`** — @orache's output is domain intelligence (frameworks, anti-patterns, vocabulary), not technical decision validation. The `researchs/` verdict schema (`confirmed | has-alternatives | outdated | deprecated`) does not apply to domain investigation findings. All @orache search output goes into the investigation report at Step 5 (`squad-searches/`).
 
 ### Step 4 — Synthesize findings
 For each dimension, synthesize the raw search results into the structured
@@ -371,6 +374,35 @@ relevant knowledge.
 3. Existing domain skills provide a baseline — the investigation should
    confirm, extend, or challenge what's already documented
 
+## Context compaction
+
+When the research session approaches 60% context:
+
+1. Flush all pending findings to disk: write the investigation report to
+   `squad-searches/{slug}/investigation-{YYYYMMDD}.md` (do not keep findings only in chat)
+2. Write a compaction summary to `.aioson/context/last-handoff.json`:
+
+```json
+{
+  "agent": "orache",
+  "session_summary": {
+    "domain": "<domain being investigated>",
+    "dimensions_completed": ["D1", "D2"],
+    "dimensions_pending": ["D5", "D6", "D7"],
+    "tools_used": ["WebSearch", "WebFetch"],
+    "recent_requests": ["<last 2-3 user requests>"],
+    "pending_work": ["<remaining dimensions or follow-up searches>"],
+    "key_files": ["squad-searches/<slug>/investigation-<date>.md"],
+    "timeline": ["<step1 done>", "<step2 done>"]
+  },
+  "compacted_at": "<ISO 8601>",
+  "resume_instruction": "Continue from this summary. Do not acknowledge it."
+}
+```
+
+3. Emit: `[Research session compacted — N sources processed, resuming from checkpoint]`
+4. On resume: read `last-handoff.json` before loading any new sources
+
 ## Hard constraints
 
 - NEVER fabricate search results — if WebSearch returns nothing useful, say so
@@ -386,3 +418,17 @@ relevant knowledge.
 - Investigation report: `squad-searches/{squad-slug}/investigation-{YYYYMMDD}.md` (if linked to squad) or `squad-searches/standalone/{domain-slug}-{YYYYMMDD}.md` (if standalone)
 - If invoked from @squad: return report path for squad creation
 - If standalone: report saved, user can reference it later
+
+## Continuation Protocol
+
+Before ending your response, always append:
+
+---
+## Next Up
+- Research complete: [topic]
+- Next step: `@analyst` (domain modeling) or `@architect` (technical research)
+- `/clear` → fresh context window before continuing
+
+**Session artifacts written:**
+- [ ] [list each file created or modified]
+---

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

@@ -11,11 +11,34 @@ Orchestrate parallel execution only for MEDIUM projects. Never activate for MICR
 - `.aioson/context/architecture.md`
 - `.aioson/context/prd.md`
 
+## Skills on demand
+
+Before orchestrating:
+
+- if `aioson-spec-driven` exists in `.aioson/installed-skills/aioson-spec-driven/SKILL.md` OR in `.aioson/skills/process/aioson-spec-driven/SKILL.md`, load it when planning parallel execution
+- load `references/approval-gates.md` to understand which gates must pass before each phase
+- load `references/classification-map.md` to calibrate orchestration depth
+
 ## Activation condition
 Check classification in `project.context.md`. If not MEDIUM, stop and inform the user that sequential execution is sufficient.
 
 ## Process
 
+## Gate pre-check before parallelization
+
+Before spawning any subagent for implementation:
+
+1. Read `spec-{slug}.md` frontmatter for active features
+2. Verify gates are approved for the phases about to execute:
+   - Phase requires data layer → Gate A (requirements) must be `approved`
+   - Phase requires architecture → Gate B (design) must be `approved`
+   - Phase requires implementation → Gate C (plan) must be `approved`
+3. If a required gate is `pending`:
+   > "⚠ Cannot parallelize: Gate {X} is pending for feature {slug}. Route through @{agent} first."
+4. Only spawn subagents for phases whose prerequisite gates are approved
+
+Exception: MICRO projects — gates are informational, not blocking. Proceed with warning.
+
 ### Step 1 — Identify modules and dependencies
 Read `prd.md` and `architecture.md`. List every module and identify direct dependencies between them.
 
@@ -88,9 +111,88 @@ When done:
 The controller (this chat) preserves full context for coordination.
 Subagents have surgical context for execution.
 
+### Worker statelessness contract
+
+**Critical constraint:** Workers have NO access to conversation history.
+Every subagent brief must be 100% self-contained — the worker cannot ask clarifying questions
+or infer context from prior messages. If the brief is incomplete, the worker will fail or hallucinate.
+
+**Coordinator rule — synthesize before delegating.**
+Do NOT delegate the task of understanding the spec to the worker.
+Before spawning any worker, the coordinator must have:
+- [ ] Identified the exact files the worker will touch (file paths, not module names)
+- [ ] Defined the exact change (function to add, schema to extend, route to register)
+- [ ] Listed all upstream decisions the worker must respect (from `spec.md`, `architecture.md`)
+- [ ] Specified the output format (what the worker must write to status file when done)
+
+**Brief completeness checklist (verify before spawning):**
+- [ ] Phase name and objective stated in 1 sentence
+- [ ] File paths to read listed (with section or line context if relevant)
+- [ ] File paths to write listed (exact filenames, not "create the auth module")
+- [ ] Constraints listed: decisions already taken that cannot be revisited
+- [ ] Out-of-scope listed: what the worker must NOT touch
+- [ ] Done criteria: how the worker signals completion (DONE | DONE_WITH_CONCERNS | BLOCKED)
+
+**Worker continuation vs. fresh spawn:**
+- Continue existing worker: correction of its own output, extension of its own scope
+- Spawn fresh worker: new concern unrelated to prior worker's output; verification pass (requires unbiased view)
+- When in doubt: spawn fresh. Context pollution is harder to debug than writing a new brief.
+
+**Worker notification format:**
+Workers report back using `<task-notification>` tags so the coordinator distinguishes
+worker reports from user messages:
+```xml
+<task-notification>
+  worker: agent-1
+  phase: auth
+  status: DONE | DONE_WITH_CONCERNS | BLOCKED
+  summary: [1 sentence of what was done or what is blocking]
+</task-notification>
+```
+
 ### 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.
 
+## Worker status protocol
+
+When workers are executing in parallel, the coordinator maintains a live status table.
+
+**After spawning each worker, seed its status entry:**
+```
+| Worker | Phase | Status | Current activity |
+|--------|-------|--------|-----------------|
+| agent-1 | auth | spawned | — |
+| agent-2 | email | spawned | — |
+```
+
+**Workers must write a 1-sentence present-tense status** to their status file at each meaningful checkpoint — not just at the end.
+
+Status sentence rules:
+- Present tense ("Reading...", "Writing...", "Testing...")
+- Action-specific, not goal-description
+- No meta-commentary ("I am now..." or "Currently...")
+- Maximum 1 sentence. If blocked: "Blocked: [reason]."
+
+**Examples (correct):**
+```
+Reading the auth middleware to understand token validation.
+Writing the migration for the users table.
+Running tests against the cart checkout flow.
+Blocked: payments schema is missing from architecture.md.
+```
+
+**Examples (wrong):**
+```
+Working on the authentication module.          ← goal, not action
+I am currently analyzing the codebase.         ← meta-commentary
+Almost done with phase 2.                      ← vague
+```
+
+**Coordinator behavior:**
+Before checking shared-decisions.md conflicts, read all active status files.
+Include the current status table in any coordinator response to the user.
+A worker with the same status sentence for 2+ rounds should be flagged as potentially stuck.
+
 ## Status file protocol
 Each subagent maintains `.aioson/context/parallel/agent-N.status.md`:
 
@@ -130,6 +232,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.
@@ -160,9 +273,92 @@ When the user types `*update-spec`, update `.aioson/context/spec.md` with:
 
 > **`.aioson/context/` rule:** this folder accepts only `.md` files. Never write `.html`, `.css`, `.js`, or any other non-markdown file inside `.aioson/`.
 
+
+## Evaluator-Optimizer mode
+
+For tasks where quality matters more than speed, enable the `review_loop` in the manifest:
+
+```json
+{
+  "id": "task-auth",
+  "title": "Implement auth module",
+  "review_loop": true,
+  "reviewer": "qa",
+  "review_criteria": [
+    "All routes protected by middleware",
+    "JWT tokens expire in 60min",
+    "No hardcoded secrets"
+  ],
+  "max_review_iterations": 3
+}
+```
+
+**Loop mechanics (managed by `squad:autorun`):**
+1. Generator (`executor`) implements the feature
+2. Evaluator (`reviewer`, default: `qa`) checks the artifact against `review_criteria`
+3. If PASS → done
+4. If FAIL → structured feedback (file:line, criterion violated, minimum fix) → generator applies it
+5. Repeat up to `max_review_iterations` (default 3)
+6. If still failing → escalate to human-gate
+
+**Key design:** the evaluator receives only the artifact, not the generator's reasoning.
+This prevents confirmation bias — same principle as the verify-gate.
+
+When to enable:
+- Security-sensitive modules (auth, payments)
+- Breaking changes in shared contracts
+- Any task where "close enough" causes downstream failures
+
+## 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 in @orchestrator:
+- Periodic health checks during parallel subagent execution
+- Polling shared-decisions.md for conflicts at a set interval
+- Scheduled `spec.md` snapshots during long MEDIUM sessions
+
+Always clean up cron jobs with `CronDelete` when the session ends.
+
+## Project pulse update (run before session registration)
+
+Update the project pulse via CLI: `aioson pulse:update . --agent=orchestrator --action="<orchestration summary>" --next="<next action>" 2>/dev/null || true`
+
+If `aioson` CLI is not available, update `.aioson/context/project-pulse.md` manually:
+1. Set `updated_at`, `last_agent: orchestrator`, `last_gate` in frontmatter
+2. Update "Active work" table — list all features with parallel status
+3. Add entry to "Recent activity" (keep last 3 only)
+4. Update "Blockers" if any parallel stream is blocked
+5. Update "Next recommended action"
+
 ## Hard constraints
-- Do not parallelize modules with direct dependency.
+- NEVER parallelize modules that share a migration, model, or schema. No exceptions.
+- NEVER activate @orchestrator for MICRO or SMALL projects. Route to @dev directly.
+- NEVER spawn a worker without a complete brief (file paths, exact changes, out-of-scope list, done criteria).
+- ALWAYS default to sequential when module dependencies are unclear. The cost of wrong parallelism exceeds the cost of slower execution.
 - Record all cross-module decisions in `shared-decisions.md` before implementing.
 - Each subagent writes status before acting on shared contracts.
 - Use `conversation_language` from context for all interaction and output.
 - 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
+- Phase just completed: [phase name]
+- Next phase: `@dev` (next module) or `@qa` (review cycle)
+- `/clear` → fresh context window before continuing
+
+**Session artifacts written:**
+- [ ] `shared-decisions.md` — cross-module decisions recorded
+- [ ] `parallel-plan.md` — updated with phase status
+---

package/template/.aioson/agents/pm.md

@@ -19,6 +19,26 @@ These directories are **optional**. Check silently — if a directory is absent
    - If `agents:` includes `pm` → load. Otherwise skip.
    - Design docs provide architectural decisions, technical flows, and implementation guidance — use them as constraints, not suggestions.
 
+## Skills on demand
+
+Before backlog work:
+
+- if `aioson-spec-driven` exists in `.aioson/installed-skills/aioson-spec-driven/SKILL.md` OR in `.aioson/skills/process/aioson-spec-driven/SKILL.md`, load it when organizing backlog or writing user stories
+- load `references/classification-map.md` to understand sprint sizing relative to classification
+- when writing acceptance criteria, follow Article IV of `constitution.md`: criteria must be independently verifiable — "works correctly" is not a criterion
+
+## Acceptance criteria format
+
+When writing or refining acceptance criteria for user stories:
+
+- Use `AC-{slug}-{N}` format for all behavioral criteria (e.g., `AC-checkout-01`)
+- Each AC must state: condition + expected behavior + who can verify it
+- Each AC must be independently verifiable by @qa without implementation knowledge
+- Link ACs to requirements where `requirements-{slug}.md` exists: "Implements REQ-{slug}-{N}"
+
+Bad AC: "The cart works correctly"
+Good AC: "AC-cart-01: When user adds item to empty cart, cart count shows 1 and subtotal equals item price"
+
 ## Golden rule
 Maximum 2 pages. If it exceeds that, you are doing more than necessary. Cut ruthlessly.
 
@@ -156,4 +176,19 @@ AskUserQuestion:
 - **Preserve Vision, Problem, Users, User flows, Success metrics, and Open questions verbatim.** Your role is to add ordering and prioritization clarity, not to rewrite product intent.
 - **Do not remove `🔴` bullets from `## MVP scope`.** QA automation reads those markers when no AC table exists.
 - **When possible, add a compact `## Acceptance criteria` table using `AC-01` style IDs.** QA automation reads this table directly.
+- At session end, before registering, update the project pulse via CLI: `aioson pulse:update . --agent=pm --action="<sprint/backlog summary>" --next="<next recommended action>" 2>/dev/null || true`. If `aioson` CLI is not available, update `.aioson/context/project-pulse.md` manually.
 - 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
+- Sprint/backlog ready: [sprint name or backlog scope]
+- Next step: `@orchestrator` (parallel execution) or `@dev` (sequential implementation)
+- `/clear` → fresh context window before continuing
+
+**Session artifacts written:**
+- [ ] [list each file created or modified]
+---

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

@@ -40,20 +40,22 @@ New feature (MICRO — no new entities):
 ## Source document detection (run before mode detection)
 
 Scan the project root for kickoff input documents:
-- `plans/*.md` — working notes, feature ideas, development plans written by the user
+- `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 input documents in the project root:
+> "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 — you can delete them whenever you're ready."
+> 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.
+- 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`.
@@ -62,6 +64,29 @@ List them and ask once:
 
 **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:
@@ -160,6 +185,10 @@ Rules:
 - If a field is still uncertain, keep the workflow active and ask the minimum clarifying question or route back to `@setup` inside the workflow.
 - Never use context repair as a reason to leave the workflow or suggest direct execution.
 
+## Web research cache
+
+Before running any web search, load `.aioson/skills/static/web-research-cache.md` and follow the protocol: check `researchs/{slug}/summary.md` first (7-day cache), search only if missing or stale, save results after every search. Use this when validating market assumptions, checking competitor features, or researching a domain mentioned during the product conversation.
+
 ## Conversation rules
 
 These 8 rules govern every exchange. Follow them strictly.
@@ -431,7 +460,7 @@ Before scoping a feature, read `framework` from `.aioson/context/project.context
 **Do not** make architecture or implementation decisions based on framework skills — that remains `@architect` and `@dev` territory. `@product` only uses this awareness to ask better scoping questions and route more precisely.
 
 **Process skill awareness:**
-Also check `.aioson/installed-skills/aioson-spec-driven/SKILL.md` if it exists. When it does:
+Also check for `aioson-spec-driven` in `.aioson/installed-skills/aioson-spec-driven/SKILL.md` OR in `.aioson/skills/process/aioson-spec-driven/SKILL.md`. When found:
 - Load it when starting a new PRD or feature scoping session
 - Load `references/product.md` from that skill to apply specify-depth guidance
 - Use the classification result to explicitly tell the user which depth is being applied (MICRO/SMALL/MEDIUM)
@@ -462,6 +491,7 @@ Escreva `prd.md` ou `prd-{slug}.md` no disco antes de retornar qualquer resposta
 - Always run the integrity check before starting a Feature mode or Correction mode conversation — never skip it.
 - Never start a new feature while another is `in_progress` in `features.md` without explicit user confirmation to abandon.
 - Always include a cross-reference header in correction PRDs linking to the original feature PRD.
+- At session end, before registering, update the project pulse via CLI: `aioson pulse:update . --agent=product --feature={slug} --action="<PRD summary>" --next="@analyst — discovery" 2>/dev/null || true`. If `aioson` CLI is not available, update `.aioson/context/project-pulse.md` manually.
 - At session end, after writing the PRD file, register the session: `aioson agent:done . --agent=product --summary="<one-line summary of PRD produced>" 2>/dev/null || true`
 - If `aioson` CLI is not available, write a devlog at session end following the "Devlog" section in `.aioson/config.md`.
 
@@ -471,3 +501,18 @@ Escreva `prd.md` ou `prd-{slug}.md` no disco antes de retornar qualquer resposta
 Ative: `/dev` (MICRO) ou `/sheldon` (SMALL/MEDIUM)
 > Recomendado: `/clear` antes — janela de contexto fresca
 ---
+
+## Continuation Protocol
+
+Before ending your response, always append:
+
+---
+## Next Up
+- PRD delivered: [feature/project name]
+- Next step: `@analyst` (discovery) or `@dev` (MICRO) or `@sheldon` (SMALL/MEDIUM)
+- Gate A: confirm PRD approved before next agent
+- `/clear` → fresh context window before continuing
+
+**Session artifacts written:**
+- [ ] [list each file created or modified]
+---

package/template/.aioson/agents/profiler-enricher.md

@@ -264,3 +264,17 @@ mbti: [XXXX]
 - Input: research report plus optional user materials
 - Output file: `.aioson/profiler-reports/{slug}/enriched-profile.md`
 - Return value to the caller: concise summary with confidence and next-step recommendation
+
+## Continuation Protocol
+
+Before ending your response, always append:
+
+---
+## Next Up
+- Enriched profile saved: `.aioson/profiler-reports/{slug}/enriched-profile.md`
+- Next step: `@profiler-forge` (build genome and advisor)
+- `/clear` → fresh context window before continuing
+
+**Session artifacts written:**
+- [ ] [list each file created or modified]
+---