@jetrabbits/agentic 0.3.1 → 0.3.2

package/AGENTS.md

@@ -1,34 +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/
-```
-
-## Guidance chain
-
-1. Project `.agent/` baseline
-2. `.agent/rules/*` — load all
-3. `.agent/skills/*/SKILL.md` — load only the skill matching the current task
-4. `.agent/workflows/*` — load the workflow matching the triggered command
-
-**Discovery patterns:**
-
-- `.agent/rules/*.md`
-- `.agent/skills/*/SKILL.md`
-- `.agent/workflows/*.md`
-- `.agent/prompts/*.md`
+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.
 
@@ -73,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,11 @@
 # 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.

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)                     |

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/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.
+"""