# Ocas Mentor

> Self-improving orchestration and evaluation engine. Manages long-running multi-skill workflows, analyzes journals from all skills, evaluates champion vs challenger variants, and proposes skill improvements to Forge. Use for multi-step project management, heartbeat runs, skill performance evaluation, or multi-skill coordination. NOT for: web research (use Sift), skill building (use Forge), user co…

- **Type:** Skill
- **Install:** `agentstack add skill-indigokarasu-mentor-mentor`
- **Verified:** Pending review
- **Seller:** [indigokarasu](https://agentstack.voostack.com/s/indigokarasu)
- **Installs:** 0
- **Category:** [Agent Skills](https://agentstack.voostack.com/c/agent-skills)
- **Latest version:** 0.1.0
- **License:** MIT
- **Upstream author:** [indigokarasu](https://github.com/indigokarasu)
- **Source:** https://github.com/indigokarasu/mentor

## Install

```sh
agentstack add skill-indigokarasu-mentor-mentor
```

Requires the [AgentStack CLI](https://agentstack.voostack.com/docs/cli). Works with Claude Code, Cursor, and any MCP-compatible agent.

## About

# Mentor
Mentor is the system's control plane — in runtime mode it decomposes goals into task graphs, supervises execution across skills, and dynamically repairs failures through layered escalation. In heartbeat mode it reads journals from every skill, scores OKR performance against baselines, and generates improvement proposals that flow to Forge and Fellow.
Mentor reads journals to evaluate skill performance. Chronicle ingestion of journal entity observations happens via the Chronicle daily embed pipeline.

## When to Use

- OKR evaluation across all OCAS skills
- Skill performance scoring and improvement recommendations
- Post-major-session learning synthesis
- Skill library health assessment
- When Critique identifies issues needing Mentor follow-up
- **Cron-triggered heartbeats**: Always use stdin redirect (`python3 script.py  /root/.hermes/commons/data/mentor/evidence.jsonl` to confirm the line exists in commons. If present, sync is already done — proceed to next step.

**`execute_code` is blocked in cron-triggered jobs.** All heartbeat, update, and plan runs triggered by cron must use `terminal()` with inline `python3 /path/to/scripts.py` for multi-stage logic. **CRITICAL: Do NOT use ` file > file` for JSONL appends — never `execute_code`. Attempting `execute_code` in cron produces: `BLOCKED: execute_code runs arbitrary local Python`. This is a hard runtime constraint, not a suggestion.

**Python runtime resolution (confirmed 2026-06-24):** The skill docs historically reference `/root/hermes-agent/.venv/bin/python3.13` but this path does NOT exist. The venv symlinks all resolve to `/usr/bin/python3` (3.14). To run mentor/taste scripts that need `googleapiclient`:
1. Install deps: `pip3 install --break-system-packages google-api-python-client google-auth google-auth-oauthlib`
2. Use `/usr/bin/python3` (system Python 3.14, has googleapiclient after install)
3. Do NOT use `/root/.local/share/uv/python/cpython-3.13.13-linux-x86_64-gnu/bin/python3.13` — it's externally-managed and cannot install packages
4. Do NOT use `/root/.hermes/profiles/indigo/commons/data/ocas-taste/venv/bin/python3` — symlinks to system 3.14 but googleapiclient is not installed there
**Script path: skill name vs data directory mismatch (confirmed 2026-06-24 dispatch #49, #55, #63):** The skill name is `ocas-mentor` so scripts live at `/root/.hermes/profiles/indigo/skills/ocas-mentor/scripts/`. The data directory is `/root/.hermes/profiles/indigo/commons/data/mentor/` (no `ocas-` prefix). Do NOT derive the script path from the data directory name — always use `skills/ocas-mentor/scripts/.py`. The correction script specifically is at `skills/ocas-mentor/scripts/correct_active_skills_30d.py` (NOT `skills/mentor/scripts/`). **Hard rule:** Before invoking ANY Mentor script, verify the path starts with `skills/ocas-mentor/scripts/`. A quick `ls skills/ocas-mentor/scripts/.py` confirms. The agent has fallen into this trap 3+ times despite knowing the rule — the instinct to derive the path from the data directory name (`commons/data/mentor/`) is strong and must be actively countered.

**Inline Python variable scoping in `terminal()`** — When composing multi-step Python logic inline in `terminal()` (either as heredoc or `python3 -c`), variables defined inside a function are NOT available in the outer scope. This manifests as `NameError: name 'X' is not defined` at a line that logically follows the definition. **Fix:** Structure inline scripts so all logic is in a single flat scope (no nested functions), or write the script to `/tmp/` via `write_file` where you can verify scoping independently. Confirmed 2026-06-24 dispatch: `skill = jid.split("/")[0]` inside `extract_signals()` was invisible to the caller's loop.

**Sandbox file discovery failure:** In the cron sandbox, Python's `subprocess.run(["find", ...])` and `os.walk()` silently return 0 results even when the filesystem is fully accessible via shell tools. Use the shell-pipe pattern: `find JOURNALS_DIR -name "*.json" -mtime -3 | sort -u > /tmp/mentor_files_3d.txt && python3 scripts/cron-heartbeat-light.py  /tmp/out && python3 -c "..." >` / `cat >` for critical evidence/journal writes. See `references/shell-write-pattern.md`.

**Heredoc vs. pipe conflict:** `cat file | python3  file.json ` in the heredoc redirect combined with `${}` patterns confuses bash's parser. **Fix:** Always use Python (`json.dump()`) to write JSON journal files, never shell heredocs with bash variable substring operations. For simple non-JSON appends, `echo >> file` is safe.

## Operational Recipes (light / deep heartbeat, commons sync)

The full command recipes, anti-journalization gates, field-name traps, and backup
workflows live in `references/mentor-operational-recipes.md`. Load it before running any
heartbeat or commons-sync. Summary of the mandatory caller workflow:

**Light heartbeat — verify-and-backup (SINGLE `terminal()` call):**

- [ ] Record pre-run counts (evidence, ingestion, journal dir) at PROFILE path in the SAME call as script execution
- [ ] Run `cron-heartbeat-light.py  commons via timestamp-based set-difference (NOT line-count); `ingestion_log.jsonl` uses `ingested_at`

**Deep heartbeat — verify-and-backup (SINGLE `terminal()` call):**

- [ ] `mkdir -p` proposals dir before running
- [ ] Build dual-path file list (commons + profile), `sort -u`
- [ ] Run `cron-heartbeat-deep-dualpath.py  /tmp/mentor_files_3d.txt`
2. Record pre-run evidence count: `wc -l  /tmp/mentor_files_3d.txt`
2. Record pre-run evidence count: `wc -l  `last_ingest_run`. The journal is genuinely new but wasn't found by the current wave's mtime scan because `last_ingest_run` hadn't been updated yet. Self-correcting: the next wave's mtime scan will find it. Do NOT mark as `second_wave_no_op` — the work is pending.

2. **Concurrent Praxis race:** Journal mtime `.
- **Log compaction**: 30 days (no-op) / 90 days (error/gap). Last 7 days retained.

See `references/self-update-mentor.md`.

## Support File Map

| File | When to read |
|------|-------------|
| `references/schemas.md` | Before creating projects, tasks, proposals, or decisions |
| `references/default-config.md` | During `mentor.init` |
| `references/orchestration_engine.md` | Before goal decomposition or failure repair |
| `references/evaluation_engine.md` | Before journal ingestion or OKR scoring |
| `references/evolution_engine.md` | Before improvement detection or proposal generation |
| `references/workflow_plans.md` | Before any mentor.plan.* command |
| `references/gotchas-mentor.md` | Before any heartbeat or orchestration run |
| `references/multi-skill-dispatch-workflow.md` | **READ BEFORE EVERY MULTI-SKILL DISPATCH** — consolidated Forge + Mentor + Praxis pipeline sequence with cross-pitfall table, timing fixes, and third-wave/gap-backfill mitigation. Session log table (50+ dispatches) in this file. |
| `references/gotchas-mentor-cron-envvars.md` | **READ BEFORE EVERY CRON HEARTBEAT** — env var propagation gotchas for piped Python in cron |
| `references/heartbeat-gap-debugging.md` | When evidence log shows gaps >2h |
| `references/okrs-mentor.md` | During OKR evaluation |
| `references/self-update-mentor.md` | Before running `mentor.update` |
| `references/evidence-log-maintenance.md` | When evidence.jsonl grows corrupt entries or heartbeat crashes on gap detection |
| `references/data-paths.md` | Before writing any heartbeat or data script — canonical vs legacy paths |
| `references/dual-path-journal-discovery.md` | **READ BEFORE EVERY CRON HEARTBEAT** — journals live in two locations |
| `references/shell-write-pattern.md` | **READ BEFORE EVERY CRON HEARTBEAT** — the only reliable write method in cron |
| `templates/mentor-dispatch-quick-ref.md` | Before running Mentor in dispatch mode — canonical 7-step workflow |
| `references/mandatory-correction-workflow.md` | **READ AFTER EVERY LIGHT HEARTBEAT** — the mandatory `active_skills_30d` correction procedure, field naming, and two-evidence-lines-per-heartbeat pattern |
| `references/okrs.md` | During OKR evaluation (legacy OKR definitions) |
| `references/heartbeat-scan-technique.md` | When debugging journal scan or discovery issues |
| `references/gotcha-error-grep-false-positives.md` | **READ DURING URGENT-ISSUE SCANS** — grep for "error" in journal content produces false positives; parse JSON and check `outcome` field instead |
| `references/deep-heartbeat-dual-path.md` | **READ BEFORE EVERY DEEP HEARTBEAT** — dual-path wrapper fixes gotcha #32 |
| `references/deep-heartbeat-backup-procedure.md` | **READ WHEN INGESTION DELTA=0 AFTER DEEP HEARTBEAT** — backup workflow for silent write failures (confirmed 2026-06-29) |
| `references/multi-skill-dispatch-pattern.md` | When triggered by dispatcher with multi-skill dispatch (Forge+Mentor+Praxis) |
| `scripts/correct_active_skills_30d.py` | After every light heartbeat — compute true dual-path 30d count and write corrected evidence |
| `scripts/discover_recent_journals.py` | Tight-window (sub-3-day) journal discovery via CONTENT timestamp; counters the ~7h12m mtime lag. Emits a filtered file list for `cron-heartbeat-light.py`. **NOTE:** also recognizes `generated_at` and ANY `run_id` prefix (regex-extracted timestamp) — fixed 2026-07-13 to stop silently skipping praxis-cron/dispatch-wave/forge-scan journals. See `references/cron-mtime-discovery-gotcha.md` §3 and `references/discover-recent-journals-gotcha.md`. |
| `references/evidence-log-maintenance.md` | **When evidence.jsonl grows corrupt entries or heartbeat crashes on gap detection** — full scan-and-repair procedure: brace-depth splitting for concatenated JSON, null-byte removal, dual-repair requirement. |
| `scripts/repair_evidence_jsonl.py` | Standalone evidence.jsonl repair tool — scans both profile and commons for concatenated JSON, null-byte lines. Usable as `python3 scripts/repair_evidence_jsonl.py`. |
| `scripts/cron-heartbeat-deep.py` | Original deep heartbeat (single-path, commons only — use dualpath instead) |
| `scripts/cron-heartbeat-deep-dualpath.py` | **Preferred** deep heartbeat with dual-path scan + profile data sync |
| `scripts/deep_ingest_backup.py` | Deep heartbeat ingestion backup — run when `wc -l` shows delta=0 after deep heartbeat |
| `references/gap-backfill-auto-correct.md` | **When you discover a phantom filename entry in the eval file** — gap backfill auto-corrects wrong filenames from script stdout rollover; the phantom entry is inert and harmless |
| `references/ingestion-cross-reference-technique.md` | **READ DURING INGESTION CROSS-REFERENCE** — naive `comm -23` is misleading; use Python set difference instead |
| `references/cron-execution-patterns.md` | **READ BEFORE RUNNING MENTOR HEARTBEATS IN CRON** — critical patterns for script execution, verification workflows, and common pitfalls in cron-triggered heartbeats |
| `references/dispatch-bridge-script-reality.md` | **When a dispatch wave needs eval bridging** — the documented `bridge_eval_both_stores.py` / `close_dispatch_gap*.py` / `robust_eval_reconcile.py` / `reconcile_dispatch_eval_today.py` / `scan_eval_missing_journals.py` helpers DO NOT EXIST on disk. Use `scripts/bridge_eval_inline.py` (idempotent, in-process, both eval stores) instead. |

## Source & license

This open-source skill is cataloged on AgentStack and links to its original source — we do not rehost the code.

- **Author:** [indigokarasu](https://github.com/indigokarasu)
- **Source:** [indigokarasu/mentor](https://github.com/indigokarasu/mentor)
- **License:** MIT

Install and usage instructions live in the source repository linked above.

## Pricing

- **Free** — Free

## Security capabilities

Automated source analysis of v0.1.0 — what this tool can access:

- **Network access:** no
- **Filesystem access:** yes
- **Shell / process execution:** yes
- **Environment & secrets:** no
- **Dynamic code execution:** no

*"Yes" means the capability is present in the source — more access means more to trust, not that it is unsafe.*


## Versions

- **0.1.0** — security scan: flagged — Imported from the upstream source.

## Links

- Listing page: https://agentstack.voostack.com/l/skill-indigokarasu-mentor-mentor
- Seller: https://agentstack.voostack.com/s/indigokarasu
- Browse the marketplace: https://agentstack.voostack.com/browse

---
Listed on AgentStack — the marketplace for AI agent skills and MCP servers. Every listing is security-reviewed. Creators keep 70%.