@jetrabbits/agentic 0.3.0 → 0.3.2

package/AGENTS.md

@@ -1,27 +1,17 @@
 # AGENTS — root guidance
 
-## Dynamic loading of guidance
+## Dynamic guidance loading
 
-The set of loaded guidance is configurable per project and may change per task. Do not assume only statically listed
-files are available.
+The loaded guidance set is project-specific and may change per task. Do not assume the statically listed files are
+complete; first discover optional guidance under the target project's `.agent/` directory.
 
-Discover and load custom files from the target project when present:
+Discover and load guidance in this order:
 
-```text
-project_dir/
-└── .agent/
-    ├── rules/
-    ├── skills/
-    ├── workflows/
-    └── prompts/
-```
-
-**Discovery patterns:**
-
-- `project_dir/.agent/rules/*`
-- `project_dir/.agent/skills/*`
-- `project_dir/.agent/workflows/*`
-- `project_dir/.agent/prompts/*`
+1. `.agent/*.md` — project baseline files, when present
+2. `.agent/rules/*.md` — all project rules
+3. `.agent/skills/*/SKILL.md` — only the skill matching the current task
+4. `.agent/workflows/*.md` — only the workflow matching the triggered command
+5. `.agent/prompts/*.md` — only when explicitly requested or referenced by loaded guidance
 
 Prefer relative paths in references inside markdown files.
 
@@ -66,13 +56,17 @@ Cross-cutting practices that apply to every project regardless of area.
 ### Documentation of Behavior Changes
 
 - Any behavior change captured in Markdown artifacts must be documented under the project `docs/` directory.
-- Use documentation paths that match the change type, for example `docs/<feature>/README.md` for feature behavior and `docs/incidents/<date>-<workload>-root-cause.md` for incident root cause reports.
-- Create or update the relevant `docs/` artifact in the same change set; do not leave behavior changes documented only in workflow outputs, tickets, or PR comments.
-- Apply the `product-owner` role to confirm that docs describe the user-facing behavior, acceptance criteria, and operational constraints of the change.
+- Use documentation paths that match the change type, for example `docs/<feature>/README.md` for feature behavior and
+  `docs/incidents/<date>-<workload>-root-cause.md` for incident root cause reports.
+- Create or update the relevant `docs/` artifact in the same change set; do not leave behavior changes documented only
+  in workflow outputs, tickets, or PR comments.
+- Apply the `product-owner` role to confirm that docs describe the user-facing behavior, acceptance criteria, and
+  operational constraints of the change.
 
 ### MCP Memory Providers
 
-See [MEMORY.md](MEMORY.md) for the full protocol: provider roles, Context7 usage, MemPalace session-start queries, fact-writing triggers, tool call examples, and fallback order.
+See [MEMORY.md](MEMORY.md) for the full protocol: provider roles, Context7 usage, MemPalace session-start queries,
+fact-writing triggers, tool call examples, and fallback order.
 
 ### Code Style
 

package/CHANGELOG.md

@@ -1,5 +1,24 @@
 # Changelog
 
+## v0.3.2
+
+- Added optional post-task specialist agents `instruction_reviewer` and `memory_curator` outside the mandatory SDLC role matrix.
+- Added review pipeline guidance, `.reviews/<task-id>/` output conventions, and documented example instruction/memory review reports.
+- Registered the new specialists in OpenCode role configuration and extended deterministic install/model-mapper coverage.
+
+## v0.3.1
+
+- Added project-level OpenCode plugin settings in `.agentic.json`, including Telegram `botToken` and `chatId` when `telegram-notification` is enabled.
+- Renamed the OpenCode optional plugin menu entry to `telegram-notification` while preserving the old `telegram-opencode-notifier` alias for compatibility.
+- Changed `telegram-notification` runtime credentials to read from the target project's `.agentic.json` instead of Telegram environment variables.
+- Removed Telegram message formatting entirely: notifications are sent as plain text without `parse_mode`, MarkdownV2 escaping, or markdown-to-Telegram conversion.
+- Added interactive Context7 key mode selection with English menu entries for keyless setup or entering `CONTEXT7_API_KEY`.
+- Removed the post-install Context7 "add API key later" path/example guidance because key selection now happens during setup.
+- Extended `agent-model-mapper` model discovery to include active providers from `~/.local/share/opencode/auth.json` and non-deprecated models from `~/.cache/opencode/models.json`.
+- Added a Confirm/Cancel save step after OpenCode role model selection before writing `.opencode/opencode.json`.
+- Preserved OpenCode plugin settings across manifest replay/re-install so automated sync does not prompt again or lose project-level credentials.
+- Updated OpenCode, Context7, Telegram, and lifecycle docs plus deterministic e2e coverage for the new configuration flow.
+
 ## v0.3.0
 
 - Added per-agent doctor timeouts with elapsed-time and exit-status logging while keeping install non-fatal.

package/MEMORY.md

@@ -1,113 +1,67 @@
 # MEMORY — MCP context providers
 
-Guidance for using MemPalace and Context7 MCP servers across all agent sessions.
-
----
-
-## Provider roles
-
-| Provider | Purpose |
-|---|---|
-| **MemPalace** | Project-specific knowledge: architecture decisions, domain rules, conventions, known issues, integration contracts |
-| **Context7** | Framework, library, SDK, and API reference documentation |
-
-Use both when available. They are complementary, not interchangeable.
-
----
+Use MCP context only when it improves accuracy. Keep searches narrow.
 
 ## Context7
 
-- Use Context7 for framework, library, SDK, API, and setup documentation before relying on model memory.
-- Resolve the library or framework identity first, then request focused docs for the exact task and version when version matters.
-- If Context7 is unavailable, state that explicitly and fall back to local docs or official project documentation.
-
----
+- Use Context7 for external framework, library, SDK, API, and setup docs.
+- Resolve the exact package/framework first; ask for focused docs only.
+- If Context7 is unavailable, use local `docs/**`, then official upstream docs.
 
 ## MemPalace
 
-### Loading context — session start
-
-Query MemPalace **before** reading any source files. Orientation queries to run at the start of every session:
+MemPalace stores project memory by wing. The current project wing is the sanitized project directory basename. Cross-project Markdown knowledge belongs in `shared_docs`.
 
-```
-mempalace_search({ "query": "project architecture decisions" })
-mempalace_search({ "query": "domain entities and relationships" })
-mempalace_search({ "query": "known constraints and non-negotiables" })
-```
+### Cheap search pattern
 
-Before touching any subsystem, query for accumulated knowledge about it:
+Do not run broad startup searches. Search only for the task at hand:
 
-```
-mempalace_search({ "query": "<module or service name> design decisions" })
-mempalace_search({ "query": "<module or service name> known issues" })
+```json
+mempalace_search({
+  "query": "short exact keywords",
+  "wing": "<current_project_wing>",
+  "limit": 3,
+  "max_distance": 0.55
+})
 ```
 
-### Writing facts — when to store
+Rules:
 
-Store a fact **immediately** when you discover or confirm any of the following. Do not wait until the end of the session — subsequent steps in the same session benefit from facts stored earlier.
+- Keep `query` short; put background in `context` only if needed.
+- Use `wing` whenever you know it.
+- Use `limit: 3` by default; raise it only when evidence is thin.
+- Use `max_distance` around `0.4-0.6` for precise fact lookup.
+- Search `shared_docs` only for reusable docs or cross-project behavior.
+- Call `mempalace_list_wings` or `mempalace_list_rooms` only when the wing or room is unknown.
+- Add `room` only after confirming the room name.
 
-| Trigger | What to store |
-|---|---|
-| Architecture decision made or confirmed | Decision, alternatives considered, rationale |
-| Non-obvious module dependency or integration point | What connects to what and why |
-| Business rule or domain constraint clarified | The rule in plain language, where it is enforced |
-| Recurring bug pattern or root cause identified | Pattern description, affected area, mitigation |
-| API contract or data shape locked down | Shape, version, owning service |
-| Performance characteristic or known bottleneck noted | Where, measured or estimated, relevant thresholds |
-| Convention or team agreement not captured in docs | The agreement and its scope |
-| Environment or deployment constraint discovered | What the constraint is and which target it affects |
+### Writing facts
 
-### Writing facts — examples
+Use `mempalace_store` proactively when a durable fact is discovered, decided, or corrected. Do not wait for a later search to make project knowledge persistent.
 
-```
-mempalace_store({
-  "type": "architecture_decision",
-  "title": "Auth uses JWT with 15-min expiry, refresh via Redis",
-  "body": "Decided in task TASK-88. Rationale: stateless verification at API gateway; Redis holds refresh token allowlist for revocation support.",
-  "tags": ["auth", "jwt", "redis", "architecture"]
-})
-```
+Store only durable, self-contained facts:
 
-```
-mempalace_store({
-  "type": "domain_rule",
-  "title": "Orders cannot transition from CANCELLED back to any active state",
-  "body": "Enforced in OrderStateMachine.apply(). No UI path or API endpoint bypasses this; confirmed with product owner in TASK-102.",
-  "tags": ["orders", "state-machine", "domain-rule"]
-})
-```
+- architecture decisions and rationale;
+- domain rules and API/data contracts;
+- non-obvious integrations or constraints;
+- known issues, bottlenecks, and mitigations;
+- team conventions not already captured in `docs/**`.
 
-```
-mempalace_store({
-  "type": "known_issue",
-  "title": "ReportService N+1 on invoice line items — not yet fixed",
-  "body": "Affects reports with >50 invoices. Tracked in TASK-119. Workaround: batch fetch via InvoiceRepository.findByReportId().",
-  "tags": ["reporting", "performance", "n+1"]
-})
-```
+Store one fact per call, tagged with project/module/domain nouns. Write project facts to the current project wing. Write to `shared_docs` only when the knowledge is intentionally reusable across projects.
 
-```
+```json
 mempalace_store({
-  "type": "convention",
-  "title": "Feature flags go through FeatureToggleService — no direct env checks in domain code",
-  "body": "Established to keep domain layer portable. All flag reads must go through FeatureToggleService.isEnabled(flag, context).",
-  "tags": ["conventions", "feature-flags"]
+  "wing": "<current_project_wing>",
+  "room": "<known_room_if_confirmed>",
+  "text": "Durable fact stated as a complete sentence with enough context to stand alone.",
+  "tags": ["project", "module", "domain"]
 })
 ```
 
-### Quality bar for stored facts
-
-- **Concrete, not vague.** "Auth uses JWT" is a fact. "Auth is secure" is not.
-- **Self-contained.** The fact must make sense without the surrounding chat context.
-- **Tagged for retrieval.** Include module names, domain nouns, and problem-type tags.
-- **One fact per store call.** Do not bundle multiple unrelated facts into one entry.
-
----
-
-## Fallback order
+## Fallback
 
-When MCP providers are unavailable, fall back in this order:
+If MCP providers are unavailable, use:
 
-1. Local `docs/**` in the project repository
-2. Official upstream documentation
-3. Model knowledge (least preferred — state explicitly when used)
+1. local `docs/**`;
+2. official upstream documentation;
+3. model knowledge, explicitly marked as fallback.

package/Makefile

@@ -1,11 +1,30 @@
-.PHONY: help install dev test test-cli test-tui test-cross test-doctor test-markers test-opencode-plugins test-telegram-plugin test-real-agent-doctor test-real-blackbox test-real-opencode-mapper test-coverage lint fmt clean build assess-areas
+.PHONY: help install dev test test-all test-cli test-tui test-cross test-doctor test-markers test-opencode-plugins test-telegram-plugin test-ubuntu-blackbox test-real-agent-doctor test-real-blackbox test-real-blackbox-codex test-real-blackbox-opencode test-real-blackbox-telegram test-real-opencode-mapper test-coverage _test-coverage-steps lint fmt clean build assess-areas
+
+define timed_step
+	@label='$(1)'; \
+	start=$$(date +%s); \
+	timestamp=$$(date '+%Y-%m-%d %H:%M:%S'); \
+	printf '%s [make-timing] START %s\n' "$$timestamp" "$$label"; \
+	$(2); \
+	status=$$?; \
+	end=$$(date +%s); \
+	elapsed=$$((end - start)); \
+	timestamp=$$(date '+%Y-%m-%d %H:%M:%S'); \
+	if [ "$$status" -eq 0 ]; then \
+	  printf '%s [make-timing] OK %s elapsed=%ss\n' "$$timestamp" "$$label" "$$elapsed"; \
+	else \
+	  printf '%s [make-timing] FAIL %s elapsed=%ss exit=%s\n' "$$timestamp" "$$label" "$$elapsed" "$$status"; \
+	fi; \
+	exit "$$status"
+endef
 
 help:
 	@printf '%s\n' \
 		"Available targets:" \
 		"  install       Install local development prerequisites" \
 		"  dev           Show local development entrypoints" \
-		"  test          Run end-to-end tests (all groups)" \
+		"  test          Run fast deterministic end-to-end tests" \
+		"  test-all      Run fast tests, real blackbox, and coverage" \
 		"  test-cli      Run CLI end-to-end tests" \
 		"  test-tui      Run TUI end-to-end tests" \
 		"  test-cross    Run cross-mode end-to-end tests" \
@@ -13,8 +32,12 @@ help:
 		"  test-markers  Run generated marker and idempotency tests" \
 		"  test-opencode-plugins  Run OpenCode plugin deterministic tests" \
 		"  test-telegram-plugin   Run Telegram plugin deterministic tests" \
+		"  test-ubuntu-blackbox   Run make test in a clean Docker Ubuntu image" \
 		"  test-real-agent-doctor  Run real agent doctor checks" \
 		"  test-real-blackbox      Run real Codex/OpenCode/Telegram blackbox tests" \
+		"  test-real-blackbox-codex  Run real Codex blackbox test" \
+		"  test-real-blackbox-opencode  Run real OpenCode blackbox test" \
+		"  test-real-blackbox-telegram  Run real OpenCode Telegram blackbox test" \
 		"  test-real-opencode-mapper  Run real OpenCode mapper input blackbox" \
 		"  test-coverage  Run traced e2e coverage for agentic" \
 		"  lint          Run prompt and catalog validation" \
@@ -30,48 +53,83 @@ dev:
 	@printf '%s\n' "Use ./agentic tui or ./agentic install ..."
 
 test:
-	bash tests/e2e/cli.e2e.sh
-	bash tests/e2e/tui.e2e.sh
-	bash tests/e2e/cross.e2e.sh
-	bash tests/e2e/doctor.e2e.sh
-	bash tests/e2e/markers.e2e.sh
-	bash tests/e2e/opencode_plugins.e2e.sh
-	bash tests/e2e/telegram_plugin.e2e.sh
-	bash tests/e2e/real_agent_blackbox.e2e.sh
-	$(MAKE) test-coverage
+	$(call timed_step,test-cli,bash tests/e2e/cli.e2e.sh)
+	$(call timed_step,test-tui,bash tests/e2e/tui.e2e.sh)
+	$(call timed_step,test-cross,bash tests/e2e/cross.e2e.sh)
+	$(call timed_step,test-opencode-plugins,bash tests/e2e/opencode_plugins.e2e.sh)
+	$(call timed_step,test-telegram-plugin,bash tests/e2e/telegram_plugin.e2e.sh)
+
+test-all:
+	$(call timed_step,test,$(MAKE) test)
+	$(call timed_step,test-doctor,bash tests/e2e/doctor.e2e.sh)
+	$(call timed_step,test-markers,bash tests/e2e/markers.e2e.sh)
+	$(call timed_step,test-real-blackbox-codex,AGENTIC_REAL_BLACKBOX_ONLY=codex bash tests/e2e/real_agent_blackbox.e2e.sh)
+	$(call timed_step,test-real-blackbox-opencode,AGENTIC_REAL_BLACKBOX_ONLY=opencode bash tests/e2e/real_agent_blackbox.e2e.sh)
+	$(call timed_step,test-real-opencode-mapper,AGENTIC_REAL_BLACKBOX_ONLY=opencode-mapper bash tests/e2e/real_agent_blackbox.e2e.sh)
+	$(call timed_step,test-real-blackbox-telegram,AGENTIC_REAL_BLACKBOX_ONLY=telegram bash tests/e2e/real_agent_blackbox.e2e.sh)
+	$(call timed_step,test-coverage,$(MAKE) test-coverage)
 
 test-cli:
-	bash tests/e2e/cli.e2e.sh
+	$(call timed_step,test-cli,bash tests/e2e/cli.e2e.sh)
 
 test-tui:
-	bash tests/e2e/tui.e2e.sh
+	$(call timed_step,test-tui,bash tests/e2e/tui.e2e.sh)
 
 test-cross:
-	bash tests/e2e/cross.e2e.sh
+	$(call timed_step,test-cross,bash tests/e2e/cross.e2e.sh)
 
 test-doctor:
-	bash tests/e2e/doctor.e2e.sh
+	$(call timed_step,test-doctor,bash tests/e2e/doctor.e2e.sh)
 
 test-markers:
-	bash tests/e2e/markers.e2e.sh
+	$(call timed_step,test-markers,bash tests/e2e/markers.e2e.sh)
 
 test-opencode-plugins:
-	bash tests/e2e/opencode_plugins.e2e.sh
+	$(call timed_step,test-opencode-plugins,bash tests/e2e/opencode_plugins.e2e.sh)
 
 test-telegram-plugin:
-	bash tests/e2e/telegram_plugin.e2e.sh
+	$(call timed_step,test-telegram-plugin,bash tests/e2e/telegram_plugin.e2e.sh)
+
+test-ubuntu-blackbox:
+	$(call timed_step,test-ubuntu-blackbox,bash tests/e2e/ubuntu_blackbox.e2e.sh)
 
 test-real-agent-doctor:
-	bash tests/e2e/real_agent_doctor.e2e.sh
+	$(call timed_step,test-real-agent-doctor,bash tests/e2e/real_agent_doctor.e2e.sh)
 
 test-real-blackbox:
-	bash tests/e2e/real_agent_blackbox.e2e.sh
+	$(call timed_step,test-real-blackbox-codex,AGENTIC_REAL_BLACKBOX_ONLY=codex bash tests/e2e/real_agent_blackbox.e2e.sh)
+	$(call timed_step,test-real-blackbox-opencode,AGENTIC_REAL_BLACKBOX_ONLY=opencode bash tests/e2e/real_agent_blackbox.e2e.sh)
+	$(call timed_step,test-real-opencode-mapper,AGENTIC_REAL_BLACKBOX_ONLY=opencode-mapper bash tests/e2e/real_agent_blackbox.e2e.sh)
+	$(call timed_step,test-real-blackbox-telegram,AGENTIC_REAL_BLACKBOX_ONLY=telegram bash tests/e2e/real_agent_blackbox.e2e.sh)
+
+test-real-blackbox-codex:
+	$(call timed_step,test-real-blackbox-codex,AGENTIC_REAL_BLACKBOX_ONLY=codex bash tests/e2e/real_agent_blackbox.e2e.sh)
+
+test-real-blackbox-opencode:
+	$(call timed_step,test-real-blackbox-opencode,AGENTIC_REAL_BLACKBOX_ONLY=opencode bash tests/e2e/real_agent_blackbox.e2e.sh)
+
+test-real-blackbox-telegram:
+	$(call timed_step,test-real-blackbox-telegram,AGENTIC_REAL_BLACKBOX_ONLY=telegram bash tests/e2e/real_agent_blackbox.e2e.sh)
 
 test-real-opencode-mapper:
-	AGENTIC_REAL_BLACKBOX_ONLY=opencode-mapper bash tests/e2e/real_agent_blackbox.e2e.sh
+	$(call timed_step,test-real-opencode-mapper,AGENTIC_REAL_BLACKBOX_ONLY=opencode-mapper bash tests/e2e/real_agent_blackbox.e2e.sh)
 
 test-coverage:
-	AGENTIC_COVERAGE_TRACE_FILE=$$(mktemp /tmp/agentic-coverage.XXXXXX) bash -c 'AGENTIC_TEST_CLI="$(CURDIR)/tests/e2e/coverage_shim.sh" bash tests/e2e/agentic.e2e.sh >/tmp/agentic-coverage-agentic.log 2>&1 && AGENTIC_TEST_CLI="$(CURDIR)/tests/e2e/coverage_shim.sh" bash tests/e2e/tui.e2e.sh >/tmp/agentic-coverage-tui.log 2>&1 && AGENTIC_TEST_CLI="$(CURDIR)/tests/e2e/coverage_shim.sh" bash tests/e2e/cross.e2e.sh >/tmp/agentic-coverage-cross.log 2>&1 && AGENTIC_TEST_CLI="$(CURDIR)/tests/e2e/coverage_shim.sh" bash tests/e2e/markers.e2e.sh >/tmp/agentic-coverage-markers.log 2>&1 && AGENTIC_TEST_CLI="$(CURDIR)/tests/e2e/coverage_shim.sh" bash tests/e2e/cli.e2e.sh >/tmp/agentic-coverage-cli.log 2>&1 && AGENTIC_TEST_CLI="$(CURDIR)/tests/e2e/coverage_shim.sh" bash tests/e2e/doctor.e2e.sh >/tmp/agentic-coverage-doctor.log 2>&1 && bash tests/e2e/coverage_parse.sh "$$AGENTIC_COVERAGE_TRACE_FILE"'
+	@if [ -n "$${AGENTIC_COVERAGE_TRACE_FILE:-}" ]; then \
+	  trace_file="$$AGENTIC_COVERAGE_TRACE_FILE"; \
+	else \
+	  trace_file="$$(mktemp /tmp/agentic-coverage.XXXXXX)"; \
+	fi; \
+	$(MAKE) _test-coverage-steps AGENTIC_COVERAGE_TRACE_FILE="$$trace_file"
+
+_test-coverage-steps:
+	$(call timed_step,test-coverage-agentic,AGENTIC_COVERAGE_TRACE_FILE="$(AGENTIC_COVERAGE_TRACE_FILE)" AGENTIC_TEST_CLI="$(CURDIR)/tests/e2e/coverage_shim.sh" bash tests/e2e/agentic.e2e.sh >/tmp/agentic-coverage-agentic.log 2>&1)
+	$(call timed_step,test-coverage-tui,AGENTIC_COVERAGE_TRACE_FILE="$(AGENTIC_COVERAGE_TRACE_FILE)" AGENTIC_TEST_CLI="$(CURDIR)/tests/e2e/coverage_shim.sh" bash tests/e2e/tui.e2e.sh >/tmp/agentic-coverage-tui.log 2>&1)
+	$(call timed_step,test-coverage-cross,AGENTIC_COVERAGE_TRACE_FILE="$(AGENTIC_COVERAGE_TRACE_FILE)" AGENTIC_TEST_CLI="$(CURDIR)/tests/e2e/coverage_shim.sh" bash tests/e2e/cross.e2e.sh >/tmp/agentic-coverage-cross.log 2>&1)
+	$(call timed_step,test-coverage-markers,AGENTIC_COVERAGE_TRACE_FILE="$(AGENTIC_COVERAGE_TRACE_FILE)" AGENTIC_TEST_CLI="$(CURDIR)/tests/e2e/coverage_shim.sh" bash tests/e2e/markers.e2e.sh >/tmp/agentic-coverage-markers.log 2>&1)
+	$(call timed_step,test-coverage-cli,AGENTIC_COVERAGE_TRACE_FILE="$(AGENTIC_COVERAGE_TRACE_FILE)" AGENTIC_TEST_CLI="$(CURDIR)/tests/e2e/coverage_shim.sh" bash tests/e2e/cli.e2e.sh >/tmp/agentic-coverage-cli.log 2>&1)
+	$(call timed_step,test-coverage-doctor,AGENTIC_COVERAGE_TRACE_FILE="$(AGENTIC_COVERAGE_TRACE_FILE)" AGENTIC_TEST_CLI="$(CURDIR)/tests/e2e/coverage_shim.sh" bash tests/e2e/doctor.e2e.sh >/tmp/agentic-coverage-doctor.log 2>&1)
+	$(call timed_step,test-coverage-parse,bash tests/e2e/coverage_parse.sh "$(AGENTIC_COVERAGE_TRACE_FILE)")
 
 lint:
 	bash -n agentic

package/README.md

@@ -1,6 +1,6 @@
 # Agent Intelligence Configuration (agentic)
 
-> **18 areas · 10 Software specs · 8 DevOps specs · 7 SDLC agents · 105+ skills · 73+ workflows**
+> **18 areas · 10 Software specs · 8 DevOps specs · 7 SDLC agents + 2 specialists · 105+ skills · 73+ workflows**
 
 A unified catalog of agentic specializations and the `agentic` CLI. Install orchestrator-ready rules, skills, workflows,
 and prompts into any project — and run a full SDLC agent team out of the box.
@@ -77,14 +77,14 @@ agent-guides/
 │       └── database-ops/      # PostgreSQL, Redis, migrations, backup/restore
 ├── extensions/
 │   ├── opencode/              # OpenCode agent definitions, commands, skills
-│   │   └── agents/            # 7 SDLC agents for .opencode/agents/
+│   │   └── agents/            # SDLC agents + optional specialists for .opencode/agents/
 │   ├── claude/                # Claude Code configs
-│   │   └── agents/            # 7 SDLC agents for .claude/agents/
+│   │   └── agents/            # SDLC agents + optional specialists for .claude/agents/
 │   ├── antigravity/           # Antigravity platform configs
 │   ├── codex/                 # Codex custom agents and override configs
-│   │   └── agents/            # 7 SDLC agents for .codex/agents/
+│   │   └── agents/            # SDLC agents + optional specialists for .codex/agents/
 │   └── gemini/                # Gemini-specific configs
-│   │   └── agents/            # 7 SDLC agents for .gemini/agents/
+│   │   └── agents/            # SDLC agents + optional specialists for .gemini/agents/
 ├── areas/template/            # Authoring templates — start here for new content
 ├── docs/                      # Setup and usage guides
 ├── AGENTS.md                  # Root agent guidance (loaded into every project)
@@ -140,8 +140,8 @@ guidance bundle.
 
 ## SDLC Agent team
 
-The same 7-agent team works across **Claude Code**, **OpenCode**, **Codex**, and any tool that supports agent or
-subagent files.
+The same 7-agent SDLC team works across **Claude Code**, **OpenCode**, **Codex**, and any tool that supports agent or
+subagent files. Agentic also ships optional post-task review specialists for instruction quality and memory hygiene.
 
 | Agent             | Role                                           | Invoke when                                   |
 |:------------------|:-----------------------------------------------|:----------------------------------------------|
@@ -156,6 +156,16 @@ subagent files.
 Each agent has a `vibe` (one-line personality), `Identity`, `Communication Style`, `Success Metrics`, and explicit
 `Boundaries` — so roles never overlap and handoffs are always documented.
 
+Optional specialist agents run outside the mandatory SDLC role matrix:
+
+| Agent                  | Role                                             | Invoke when                                      |
+|:-----------------------|:-------------------------------------------------|:-------------------------------------------------|
+| `instruction_reviewer` | Post-task instruction effectiveness review       | Instructions, tool use, or role guidance changed |
+| `memory_curator`       | Post-task memory hygiene recommendations         | Durable facts or memory quality need review      |
+
+See [Review Pipeline](docs/review-pipeline.md) for the guidance-mode pipeline and `.reviews/<task-id>/` output
+convention.
+
 | Platform    | Agent path                      | Format                         | Guide                                                                                           |
 |:------------|:--------------------------------|:-------------------------------|:------------------------------------------------------------------------------------------------|
 | Claude Code | `project/.claude/agents/*.md`   | Markdown with YAML frontmatter | [Claude Code subagents](https://docs.claude.com/en/api/agent-sdk/subagents)                     |