@jetrabbits/agentic 0.3.0 → 0.3.2

package/docs/agentic-stabilization/README.md

@@ -4,16 +4,19 @@
 
 - Post-install doctor checks run independently for `codex`, `opencode`, `claude`, and `gemini`.
 - `AGENTIC_DOCTOR_TIMEOUT_SECONDS` defaults to `10`; a timeout is reported as a doctor failure and install continues.
-- Codex doctor runs non-interactively with `--ephemeral` and `--sandbox workspace-write`.
+- Codex doctor runs non-interactively with `--ephemeral`, `--sandbox workspace-write`, and the same lightweight smoke prompt as other supported doctor targets.
 - OpenCode uses `agent-model-mapper` instead of the removed `model-checker` artifacts.
 - `agent-model-mapper` writes `.opencode/opencode.json` during interactive install only after confirmation.
 - `agent-model-mapper` uses `fzf` for install-time model dropdowns when available and OpenCode startup skips once all roles are mapped.
 - The runtime OpenCode plugin never opens `fzf`, asks questions, or writes project files.
-- Context7 no longer asks for an API key; it uses `CONTEXT7_API_KEY` when set and otherwise prints config-path guidance for adding one later.
-- OpenCode MemPalace setup writes `mempalace-mcp` config without running `mempalace init` automatically.
-- Telegram notification credentials are read only from `OPENCODE_TELEGRAM_BOT_TOKEN` and `OPENCODE_TELEGRAM_CHAT_ID`.
+- Context7 offers an interactive key mode: configure without a key or enter `CONTEXT7_API_KEY` for the selected target configs.
+- OpenCode MemPalace setup writes `mempalace-mcp` config and initializes/mines project memory into a project-specific wing without LLM calls.
+- Telegram notification credentials are read from project `.agentic.json` when the plugin is enabled.
 - MemPalace-enabled installs create a managed `.mempalaceignore` unless the target project already has one.
-- Real Codex, OpenCode, and Telegram blackbox scenarios are part of `make test`.
+- `make test` runs the fast deterministic e2e suite; longer deterministic checks, real blackbox, and coverage checks are explicit targets.
+- `make test-all` runs the full local suite including longer deterministic checks, install/evidence blackbox, and coverage.
+- Real Codex, OpenCode, and Telegram blackbox install/evidence scenarios run through `make test-real-blackbox`.
+- Live Codex/OpenCode/Telegram blackbox sessions require `AGENTIC_REAL_BLACKBOX_LIVE=1`.
 - `make test-coverage` traces `agentic` through e2e runs and fails below 90% line coverage.
 
 ## Acceptance Criteria
@@ -24,10 +27,11 @@
 - `extensions/opencode/opencode.json` lists `agent-model-mapper`.
 - Runtime model mapper execution does not prompt or modify project files.
 - Telegram plugin tests prove environment-only credentials and no secret output.
-- Real blackbox tests print created files, instruction evidence, MCP usage prompts, and MemPalace fact prompts without printing Telegram secrets.
+- Real blackbox tests print created files, managed guidance sources, and MCP config evidence, then save instruction evidence to a temp file without printing Telegram secrets.
 
 ## Operational Constraints
 
-- `make test` now requires real `codex` and `opencode` binaries, working model auth, network access, Context7/MemPalace access, and Telegram credentials.
+- `make test` is deterministic, designed for a sub-minute local loop, and does not require real agent binaries, model auth, network access, Context7/MemPalace access, or Telegram credentials.
+- `AGENTIC_REAL_BLACKBOX_LIVE=1 make test-real-blackbox` requires real `codex` and `opencode` binaries, working model auth, network access, Context7/MemPalace access, and Telegram credentials for the Telegram case.
 - Telegram credentials must never be committed or written to Agentic config.
 - Coverage is line-based Bash trace coverage for the `agentic` script, not branch coverage.

package/docs/agentic-token-minimization/README.md

@@ -32,15 +32,17 @@ When installing for OpenCode, `agentic` writes optional plugin state to:
 ~/.config/agentic/opencode-plugins.json
 ```
 
-Interactive installs ask whether to enable Telegram notifications and model checking. Non-interactive installs default optional plugins to disabled when no config exists.
+Interactive installs ask whether to enable Telegram notifications and model mapping. Non-interactive installs default optional plugins to disabled when no config exists.
 
-The OpenCode plugins read this config at startup and return no hooks when disabled. Telegram credentials can also be supplied through:
+The OpenCode plugins read project `.agentic.json` at startup and return no hooks when disabled. When Telegram is enabled, credentials are stored in plaintext at:
 
 ```text
-OPENCODE_TELEGRAM_BOT_TOKEN
-OPENCODE_TELEGRAM_CHAT_ID
+settings.opencode_plugins.telegram.botToken
+settings.opencode_plugins.telegram.chatId
 ```
 
+Do not commit a Telegram-enabled `.agentic.json` to public repositories.
+
 ## Context7
 
 `agentic` adds Context7 MCP configuration for known project-level formats:
@@ -54,7 +56,7 @@ OPENCODE_TELEGRAM_CHAT_ID
 - `.kilocode/mcp.json` for `kilocode`
 - `~/.gemini/antigravity/mcp_config.json` for `antigravity` (global user config)
 
-Interactive installs ask whether to enable Context7. If enabled, Context7 is configured without a key unless `CONTEXT7_API_KEY` is already set; the install output prints the config path(s) and an example key placement. Non-interactive installs enable Context7 when either `AGENTIC_ENABLE_CONTEXT7=y` or `CONTEXT7_API_KEY` is set. Generated guidance requires agents to use Context7 for framework, SDK, library, and API documentation before relying on model memory when the project config is present.
+Interactive installs ask whether to enable Context7. If enabled, Context7 can be configured without a key or with a `CONTEXT7_API_KEY` entered during setup. Non-interactive installs enable Context7 when either `AGENTIC_ENABLE_CONTEXT7=y` or `CONTEXT7_API_KEY` is set. Generated guidance requires agents to use Context7 for framework, SDK, library, and API documentation before relying on model memory when the project config is present.
 
 Directory copies are processed in batches so large specialization installs avoid spawning a separate marker/manifest process for every copied file. Manifest protection still applies: existing unmanaged files are skipped on rerun, user-modified managed files are skipped, and new generated files can be added by newer `agentic` versions.
 

package/docs/agentic-usage.md

@@ -104,7 +104,7 @@ The final install line prints the exact path:
 Agentic log file: /tmp/agentic-20260512-114203.ABC123
 ```
 
-`agentic` also runs a final doctor smoke check for selected real agent targets (`codex`, `opencode`, `claude`, `gemini`). The doctor runs in a temporary copy of the project and prints one status row per selected agent. OpenCode uses a lightweight pure smoke prompt instead of the full `develop-feature` command, so install-time doctor checks do not start a long SDLC workflow. Each agent has an independent timeout controlled by `AGENTIC_DOCTOR_TIMEOUT_SECONDS` and defaults to `10` seconds. Doctor failures and timeouts are reported but do not roll back or fail the install. Disable doctor for cheap checks with:
+`agentic` also runs a final doctor smoke check for selected real agent targets (`codex`, `opencode`, `claude`, `gemini`). The doctor runs in a temporary copy of the project and prints one status row per selected agent. All supported doctor targets use a lightweight pure smoke prompt, so install-time doctor checks do not start a long SDLC workflow. Each agent has an independent timeout controlled by `AGENTIC_DOCTOR_TIMEOUT_SECONDS` and defaults to `10` seconds. Doctor failures and timeouts are reported but do not roll back or fail the install. Disable doctor for cheap checks with:
 
 ```bash
 AGENTIC_DOCTOR=0 agentic install ...
@@ -169,11 +169,11 @@ When `opencode` is selected, interactive installs ask whether to enable Telegram
 ~/.config/agentic/opencode-plugins.json
 ```
 
-Non-interactive installs create a disabled config when no config exists. Telegram reads `OPENCODE_TELEGRAM_BOT_TOKEN` and `OPENCODE_TELEGRAM_CHAT_ID` from the environment only; tokens are not written to `~/.config/agentic/opencode-plugins.json`. When enabled, `agent-model-mapper` runs during interactive `agentic install`/`agentic tui`, uses `fzf` as a dropdown picker when available, and writes `.opencode/opencode.json` only after confirmation. OpenCode startup never prompts for model mapping; the runtime plugin only reports whether install-time mapping is already complete.
+Non-interactive installs create a disabled config when no config exists. Interactive installs ask for Telegram `botToken` and `chatId` when `telegram-notification` is selected. Those credentials are written to the target project `.agentic.json` under `settings.opencode_plugins.telegram`, not to `~/.config/agentic/opencode-plugins.json`. Treat `.agentic.json` as plaintext secret-bearing project config when Telegram is enabled and do not commit it to public repositories. When enabled, `agent-model-mapper` runs during interactive `agentic install`/`agentic tui`, uses `fzf` as a dropdown picker when available, and writes `.opencode/opencode.json` only after a Confirm action. OpenCode startup never prompts for model mapping; the runtime plugin only reports whether install-time mapping is already complete.
 
 ## Context7
 
-For `opencode`, `codex`, `claude`, `cursor`, `gemini`, `kilocode`, and `antigravity`, interactive installs ask whether to add Context7 MCP configuration. If enabled, Context7 is configured without a key unless `CONTEXT7_API_KEY` is already set in the environment. The install output prints the generated config path(s) and an example showing where to add the key later. Most targets use project-level files, while `antigravity` is written to the global user path `~/.gemini/antigravity/mcp_config.json`.
+For `opencode`, `codex`, `claude`, `cursor`, `gemini`, `kilocode`, and `antigravity`, interactive installs ask whether to add Context7 MCP configuration. If enabled, a follow-up menu chooses either keyless mode or entering `CONTEXT7_API_KEY`. The selected key is written to all selected target configs for the current project. Most targets use project-level files, while `antigravity` is written to the global user path `~/.gemini/antigravity/mcp_config.json`.
 
 Non-interactive installs enable Context7 when either `AGENTIC_ENABLE_CONTEXT7=y` or `CONTEXT7_API_KEY` is set. Agents are instructed to use Context7 for framework, library, SDK, API, and setup documentation when the project config is present.
 
@@ -183,14 +183,21 @@ For `opencode`, `codex`, `claude`, `cursor`, `gemini`, `kilocode`, and `antigrav
 
 Generated configs run `mempalace-mcp` without arguments for all supported agent targets. Runtime startup and MCP tool errors are checked by the post-install doctor stage.
 
-During install, if MemPalace is enabled, `agentic` writes a managed `.mempalaceignore` when the target project does not already have one. OpenCode installs do not run `mempalace init` automatically; project indexing is optional and printed as a manual follow-up. If auto-install or runtime checks fail, install continues, manual setup instructions are printed, and agents fall back to standard context discovery.
+During install, if MemPalace is enabled, `agentic` writes a managed `.mempalaceignore` when the target project does not already have one. It initializes the project with `mempalace init --yes --no-llm`, then mines project knowledge into a wing named from the target project basename. If `docs/` exists, those files are also mined into the shared `shared_docs` wing for cross-project Markdown knowledge. MemPalace commands time out after `60` seconds by default; override with `AGENTIC_MEMPALACE_TIMEOUT_SECONDS`. If auto-install, initialization, mining, timeout, or runtime checks fail, install continues, manual setup instructions are printed, and agents fall back to standard context discovery. If `pip install mempalace` fails, `agentic` prints the pip exit status, a temporary pip output log path, and the first non-empty pip output line as the likely reason; the full pip output is also copied into the main Agentic run log.
+
+For environments that already provide `mempalace-mcp` and need a fast install path, set `AGENTIC_MEMPALACE_SETUP=skip`. This writes the same MCP configuration and `.mempalaceignore` but skips Python package installation and project indexing.
 
 ## Real agent blackbox E2E
 
-`make test` includes real Codex, OpenCode, and Telegram blackbox scenarios. The local environment must provide working `codex`, `opencode`, Context7/MemPalace access, network access, valid auth, and Telegram credentials in `OPENCODE_TELEGRAM_BOT_TOKEN` and `OPENCODE_TELEGRAM_CHAT_ID`. Secrets are redacted from test output.
+`make test` runs the fast deterministic e2e suite and is intended to finish in under a minute on a normal local machine. Longer deterministic checks (`test-doctor`, `test-markers`), real-agent blackbox, and coverage checks are explicit targets so the default local loop stays short.
+
+`make test-real-blackbox` validates real Codex/OpenCode install artifacts, generated guidance, MCP config, and manifest evidence without starting live LLM sessions by default. Set `AGENTIC_REAL_BLACKBOX_LIVE=1` to execute live `codex`/`opencode` runs. Live Telegram checks require Telegram credentials to be present in the target project `.agentic.json`; secrets are redacted from test output.
+
+Makefile test targets print timestamped `[make-timing]` start, success/failure, exit status, and elapsed seconds for every top-level test step. `test-real-blackbox` is split into separate Codex, OpenCode, OpenCode mapper, and Telegram timed steps. Blackbox instruction evidence is saved to a `/tmp/agentic-instruction-evidence.*` file and the path is printed. `test-coverage` also prints timing for each traced coverage scenario before the final coverage parser. Use `make test-all` when you want the fast suite, longer deterministic checks, install/evidence blackbox, and coverage in one command.
 
 ```bash
 make test-real-blackbox
+AGENTIC_REAL_BLACKBOX_LIVE=1 make test-real-blackbox
 ```
 
 ## Deprecated wrapper

package/docs/guidance-updates/2026-05-22-centralized-guidance-memory.md

@@ -0,0 +1,19 @@
+# Centralized guidance loading and memory writes
+
+## User-facing behavior
+
+Agent guidance loading rules are defined in the root `AGENTS.md` instead of being repeated in each `areas/**/AGENTS.md` specialization index. Area files now focus on scope, inherited constraints, overrides, and spec maps.
+
+`MEMORY.md` now explicitly tells agents to use `mempalace_store` proactively for durable project facts when those facts are discovered, decided, or corrected.
+
+## Acceptance criteria
+
+- Root `AGENTS.md` contains the canonical guidance chain and `.agent/**/*.md` discovery patterns.
+- Area specialization `AGENTS.md` files do not repeat `## Guidance chain` or `## Discovery patterns`.
+- `areas/template/AGENTS.tmpl.md` does not reintroduce the duplicated sections for future specs.
+- `MEMORY.md` includes a concise `mempalace_store` example with wing, optional confirmed room, text, and tags.
+
+## Operational constraints
+
+- Token-budget reporting uses a dependency-free estimate of `ceil(chars / 4)` unless a tokenizer dependency is intentionally added later.
+- Validation continues to run through Makefile targets: `make lint` and `make build`.

package/docs/opencode_setup.md

@@ -33,18 +33,20 @@ When `agentic` installs the OpenCode extension, it configures optional plugins i
 ~/.config/agentic/opencode-plugins.json
 ```
 
-Telegram notifications and agent model mapping are opt-in. If the config is absent or a plugin is disabled, the plugin returns no hooks and OpenCode continues without that behavior.
+Telegram notifications and agent model mapping are opt-in. Interactive `agentic install` and `agentic tui` ask for OpenCode plugin selection whenever `opencode` is selected; the answer rewrites this config. During manifest-based upgrade/re-install sync, existing plugin settings are kept so automated refreshes do not open prompts. If the config is absent or a plugin is disabled, the plugin returns no hooks and OpenCode continues without that behavior.
 
-Telegram notifications read credentials from environment variables only:
+When `telegram-notification` is selected interactively, `agentic` asks for `botToken` and `chatId` and stores them in the target project's `.agentic.json`:
 
 ```text
-OPENCODE_TELEGRAM_BOT_TOKEN
-OPENCODE_TELEGRAM_CHAT_ID
+settings.opencode_plugins.telegram.botToken
+settings.opencode_plugins.telegram.chatId
 ```
 
+The runtime plugin reads credentials from the project `.agentic.json`; it does not read Telegram credentials from environment variables. This file stores credentials in plaintext, so do not commit a Telegram-enabled `.agentic.json` to public repositories.
+
 Non-interactive `agentic install` defaults optional plugins to disabled when no config exists.
 
-`agent-model-mapper` reads roles from target `.opencode/agents/*.md` and discovers model names from `~/.config/opencode/opencode.json`, falling back to a built-in list only when that file has no model names. When enabled, interactive `agentic install`/`agentic tui` prompts for a main and fallback model per role, using `fzf` as a dropdown picker when available, and writes `.opencode/opencode.json` only after confirmation. OpenCode startup never opens `fzf` or waits for model input; the runtime plugin only reports whether install-time mapping is complete.
+`agent-model-mapper` reads roles from target `.opencode/agents/*.md` and discovers model names from `~/.config/opencode/opencode.json`, then adds models from active providers in `~/.local/share/opencode/auth.json` using non-deprecated entries in `~/.cache/opencode/models.json`. When enabled, interactive `agentic install`/`agentic tui` prompts for a main and fallback model per role, using `fzf` as a dropdown picker when available, and writes `.opencode/opencode.json` only after a Confirm action. OpenCode startup never opens `fzf` or waits for model input; the runtime plugin only reports whether install-time mapping is complete.
 
 For OpenCode targets, `agentic` writes generated operating guidance to `.opencode/AGENTS.md`. If OpenCode is installed
 alongside another agent target, root `AGENTS.md` is generated as well for the non-OpenCode target.

package/docs/review-pipeline.md

@@ -0,0 +1,82 @@
+# Review Pipeline
+
+Agentic ships two optional post-task specialist agents:
+
+- `instruction_reviewer`: reviews how instructions affected task execution.
+- `memory_curator`: recommends long-term memory store, update, merge, ignore, and delete-candidate actions.
+
+These agents are outside the mandatory SDLC role matrix. They do not replace `product-owner`, `pm`, `team-lead`,
+`developer`, `qa`, `designer`, or `devops-engineer`.
+
+## Guidance-mode integration
+
+Agentic currently provides guidance and IDE agent definitions for the review pipeline. It does not run a generic
+post-task review runner. The parent or orchestrating agent should call the specialists after task execution when the
+task size and risk justify the extra review.
+
+Small tasks may skip this pipeline.
+
+```yaml
+review_pipeline:
+  enabled: true
+  default:
+    - qa
+    - instruction_reviewer
+    - memory_curator
+  task_types:
+    agent_system:
+      - qa
+      - instruction_reviewer
+      - memory_curator
+    docs:
+      - instruction_reviewer
+      - memory_curator
+    code:
+      - qa
+      - instruction_reviewer
+      - memory_curator
+```
+
+`tool_optimizer` may be added to `agent_system` tasks in projects that install such a role. This repository does not
+ship a `tool_optimizer` role.
+
+## Output files
+
+When the orchestrating agent writes review artifacts, use this layout:
+
+```text
+.reviews/<task-id>/
+├── instruction-review.md
+├── memory-curation.md
+└── summary.md
+```
+
+If the task id is unavailable, use a timestamp in `YYYY-MM-DD-HHMMSS` format, for example:
+
+```text
+.reviews/2026-05-26-153000/
+```
+
+The specialist agents only produce Markdown reports. They do not write memory automatically and do not create review
+files unless the parent task explicitly grants file-writing scope.
+
+Example reports live under `docs/review-pipeline/examples/`.
+
+## Report boundaries
+
+`instruction_reviewer` reviews instruction effects only:
+
+- `AGENTS.md`, `MEMORY.md`, role prompts, workflows, and tool guidance
+- instruction clarity, usefulness, conflicts, redundancy, and missing rules
+- repeated search loops, unnecessary memory lookups, unnecessary MCP calls, and token/tool waste
+
+It must not review code quality or product requirements.
+
+`memory_curator` reviews memory hygiene only:
+
+- durable project facts, conventions, workflows, decisions, constraints, and rationale
+- duplicate, stale, contradictory, or low-value memory candidates
+- store/update/merge/ignore/delete recommendations
+
+It must not store temporary logs, one-time commands, transient errors, generated code, secrets, temporary URLs, noisy
+debug output, or current task state.

package/extensions/claude/agents/instruction_reviewer.md

@@ -0,0 +1,132 @@
+---
+name: instruction_reviewer
+description: Use this agent after task execution to review how AGENTS.md, MEMORY.md, role prompts, and tool-use instructions affected the run. It does not review code quality or product requirements.
+---
+
+# Instruction Reviewer
+
+You are Instruction Reviewer.
+Your job is to evaluate how agent instructions affected task execution.
+You do NOT review code quality.
+You do NOT review product requirements.
+You do NOT rewrite the implementation unless an instruction directly caused a problem.
+
+Analyze:
+- AGENTS.md
+- MEMORY.md
+- role prompts
+- task description
+- execution log
+- tool calls
+- final diff
+- test results
+- review artifacts
+
+Focus on:
+- instruction clarity
+- instruction usefulness
+- instruction conflicts
+- redundant rules
+- missing rules
+- excessive tool usage
+- repeated search loops
+- unnecessary memory lookups
+- unnecessary MCP calls
+- token waste
+- context reuse
+
+Output only a markdown report.
+Use this structure:
+
+# Instruction Effectiveness Review
+
+## Summary
+
+Brief 3-5 sentence summary.
+
+## Scores
+
+| Category | Score 0-10 | Notes |
+|---|---:|---|
+| Clarity | | |
+| Usefulness | | |
+| Tool discipline | | |
+| Memory discipline | | |
+| Ambiguity resistance | | |
+| Token efficiency | | |
+| Overall | | |
+
+## Effective instructions
+
+| Instruction | Impact | Evidence |
+|---|---|---|
+| | | |
+
+## Harmful instructions
+
+| Instruction | Problem | Evidence |
+|---|---|---|
+| | | |
+
+## Missing instructions
+
+| Missing instruction | Why needed | Suggested text |
+|---|---|---|
+| | | |
+
+## Redundant instructions
+
+| Instruction | Reason |
+|---|---|
+| | |
+
+## Tool usage findings
+
+| Tool | Calls | Useful | Waste | Notes |
+|---|---:|---:|---:|---|
+| | | | | |
+
+## Suggested edits
+
+### Remove
+
+```md
+...
+```
+
+### Replace
+
+```md
+...
+```
+
+with:
+
+```md
+...
+```
+
+### Add
+
+```md
+...
+```
+
+## Estimated waste
+
+| Metric | Estimate |
+|---|---:|
+| Extra tokens | |
+| Extra tool calls | |
+| Extra retries | |
+| Extra runtime | |
+
+## Final recommendation
+
+Choose one:
+
+- Keep as-is
+- Minor edits
+- Significant rewrite
+
+Explain in 2-5 sentences.

package/extensions/claude/agents/memory_curator.md

@@ -0,0 +1,97 @@
+---
+name: memory_curator
+description: Use this agent after task execution to recommend high-quality long-term memory stores, updates, merges, ignores, and delete candidates. It does not write memory automatically.
+---
+
+# Memory Curator
+
+You are Memory Curator.
+Your job is to maintain high-quality long-term memory.
+Store only facts that are likely to be useful in future tasks.
+Prefer fewer, higher-quality memories.
+
+Store:
+- stable project architecture
+- coding conventions
+- recurring workflows
+- user preferences
+- infrastructure decisions
+- persistent environment details
+- reusable troubleshooting knowledge
+- important constraints
+- decision rationale
+
+Do not store:
+- temporary debugging output
+- one-time shell commands
+- transient errors
+- generated code
+- secrets
+- tokens
+- passwords
+- temporary URLs
+- logs
+- current task state
+- low-value facts
+
+Analyze:
+- task description
+- final result
+- changed files
+- review reports
+- existing memory
+- execution log
+
+Output only a markdown report.
+Use this structure:
+
+# Memory Curation Report
+
+## Summary
+
+Brief 3-5 sentence summary.
+
+## Store
+
+| Priority | Fact | Reason | Suggested memory text |
+|---|---|---|---|
+| High/Medium/Low | | | |
+
+## Update
+
+| Existing memory | Replace with | Reason |
+|---|---|---|
+| | | |
+
+## Merge
+
+| Memory A | Memory B | Merged memory | Reason |
+|---|---|---|---|
+| | | | |
+
+## Ignore
+
+| Fact | Reason |
+|---|---|
+| | |
+
+## Delete candidates
+
+| Memory | Reason |
+|---|---|
+| | |
+
+## Contradictions
+
+| Memory | New information | Resolution |
+|---|---|---|
+| | | |
+
+## Final recommendation
+
+Store count:
+Update count:
+Merge count:
+Delete candidate count:
+Memory quality score: X/10
+Short conclusion.

package/extensions/codex/AGENTS.override.md

@@ -49,6 +49,14 @@ Use the shipped role agents under `.codex/agents/`:
 - `@qa` for verification, test strategy, and go or no-go recommendations
 - `@devops-engineer` for CI/CD, infrastructure, deployment safety, and observability
 
+Optional post-task specialist agents:
+
+- `@instruction_reviewer` for instruction effectiveness, tool discipline, memory discipline, ambiguity, and token-efficiency reports
+- `@memory_curator` for long-term memory store/update/merge/ignore/delete-candidate recommendations
+
+These specialist agents are not SDLC owners and do not replace the mandatory SDLC role mapping. Use them after
+non-trivial task execution when instruction quality, memory hygiene, or future task performance needs review.
+
 Role selection guidance:
 
 - Prefer read-only agents for planning and review: `@product-owner`, `@pm`, `@team-lead`, `@designer`.
@@ -69,6 +77,15 @@ Suggested default flow:
 2. `@team-lead` and `@designer` for technical and UX review
 3. `@developer` or `@devops-engineer` for execution
 4. `@qa` and `@team-lead` for verification and release readiness
+5. Optional: `@instruction_reviewer` and `@memory_curator` for post-task review reports
+
+When these optional specialists produce artifacts, use:
+
+- `.reviews/<task-id>/instruction-review.md`
+- `.reviews/<task-id>/memory-curation.md`
+- `.reviews/<task-id>/summary.md`
+
+If no task id exists, use a timestamp directory in `YYYY-MM-DD-HHMMSS` format.
 
 ## 5. Enforcement
 

package/extensions/codex/agents/instruction_reviewer.toml

@@ -0,0 +1,139 @@
+name = "instruction_reviewer"
+description = "Use this agent after task execution to review how AGENTS.md, MEMORY.md, role prompts, and tool-use instructions affected the run. It does not review code quality or product requirements."
+model = "gpt-5.5"
+model_reasoning_effort = "high"
+sandbox_mode = "read-only"
+developer_instructions = """
+You are Instruction Reviewer.
+Your job is to evaluate how agent instructions affected task execution.
+You do NOT review code quality.
+You do NOT review product requirements.
+You do NOT rewrite the implementation unless an instruction directly caused a problem.
+
+Codex operating rules
+- You are a read-only post-task review agent. Do not edit files or perform write-capable actions.
+- Output only a deterministic Markdown report in the required structure.
+- Review instruction effectiveness, tool discipline, memory discipline, and context efficiency only.
+- If an issue is caused by implementation quality rather than instructions, mark it out of scope.
+- When suggesting edits, keep them scoped to instructions such as AGENTS.md, MEMORY.md, role prompts, workflows, or tool guidance.
+
+Analyze:
+- AGENTS.md
+- MEMORY.md
+- role prompts
+- task description
+- execution log
+- tool calls
+- final diff
+- test results
+- review artifacts
+
+Focus on:
+- instruction clarity
+- instruction usefulness
+- instruction conflicts
+- redundant rules
+- missing rules
+- excessive tool usage
+- repeated search loops
+- unnecessary memory lookups
+- unnecessary MCP calls
+- token waste
+- context reuse
+
+Output only a markdown report.
+Use this structure:
+
+# Instruction Effectiveness Review
+
+## Summary
+
+Brief 3-5 sentence summary.
+
+## Scores
+
+| Category | Score 0-10 | Notes |
+|---|---:|---|
+| Clarity | | |
+| Usefulness | | |
+| Tool discipline | | |
+| Memory discipline | | |
+| Ambiguity resistance | | |
+| Token efficiency | | |
+| Overall | | |
+
+## Effective instructions
+
+| Instruction | Impact | Evidence |
+|---|---|---|
+| | | |
+
+## Harmful instructions
+
+| Instruction | Problem | Evidence |
+|---|---|---|
+| | | |
+
+## Missing instructions
+
+| Missing instruction | Why needed | Suggested text |
+|---|---|---|
+| | | |
+
+## Redundant instructions
+
+| Instruction | Reason |
+|---|---|
+| | |
+
+## Tool usage findings
+
+| Tool | Calls | Useful | Waste | Notes |
+|---|---:|---:|---:|---|
+| | | | | |
+
+## Suggested edits
+
+### Remove
+
+```md
+...
+```
+
+### Replace
+
+```md
+...
+```
+
+with:
+
+```md
+...
+```
+
+### Add
+
+```md
+...
+```
+
+## Estimated waste
+
+| Metric | Estimate |
+|---|---:|
+| Extra tokens | |
+| Extra tool calls | |
+| Extra retries | |
+| Extra runtime | |
+
+## Final recommendation
+
+Choose one:
+
+- Keep as-is
+- Minor edits
+- Significant rewrite
+
+Explain in 2-5 sentences.
+"""