Feature: Mandatory Terraphim Search for Planning/Exploration Tasks

Feature Request: Mandatory Terraphim Search for Planning/Exploration

Summary

Implement a mechanism to enforce Terraphim knowledge graph search before any planning or exploration task, ensuring agents leverage existing knowledge before generating new plans.

Motivation

Currently, agents may plan or explore without checking the Terraphim knowledge graph, leading to:

• Duplicate efforts (solving already-solved problems)
• Ignoring established patterns and best practices
• Missing relevant skills and tools
• Suboptimal solutions due to lack of context

Proposed Solution

Implement multi-layer enforcement:

Layer 1: Configuration-Based (Recommended)

Add to terraphim-agent configuration:

# ~/.config/terraphim/agent.yaml
enforcement:
  mandatory_search:
    before_planning: true
    before_exploration: true
    
  search_defaults:
    planning:
      limit: 5
      roles: [planner, architect, researcher]
    exploration:
      limit: 10
      roles: [researcher, analyst]
      
  on_missing_search: abort  # Options: warn, abort, ignore

Layer 2: Hook-Based

Pre-task hooks that run automatically:

# Before planning task
terraphim-agent pre-task --type planning --keywords "$TASK_DESC"

# Before exploration task  
terraphim-agent pre-task --type exploration --topic "$TOPIC"

Layer 3: Skill-Based Reminder

Create mandatory-terraphim-search skill for agents:

## Rule
I CANNOT start planning or exploration without first searching Terraphim.

## Process
1. Extract keywords/topic
2. Run: terraphim-agent search "<query>" --role <role>
3. Review and incorporate findings
4. Proceed with task

Implementation Options

Option A: Wrapper Command (Quick Win)

Create terraphim-plan and terraphim-explore commands:

#!/bin/bash
# terraphim-plan

echo "🔍 Searching Terraphim knowledge graph..."
terraphim-agent search "$*" --role planner --limit 5

echo "✅ Search complete. Proceeding with planning..."
# Continue with planning task

Option B: Agent Configuration (Preferred)

Add to agent config:

{
  "task_hooks": {
    "planning": {
      "pre_execute": [
        {
          "command": "terraphim-agent search '{{task.description}}' --role planner",
          "required": true,
          "abort_on_failure": true
        }
      ]
    },
    "exploration": {
      "pre_execute": [
        {
          "command": "terraphim-agent search '{{task.topic}}' --limit 10",
          "required": true,
          "abort_on_failure": true
        }
      ]
    }
  }
}

Option C: Environment Variable

export TERRAPHIM_ENFORCE_SEARCH=1
export TERRAPHIM_SEARCH_BEFORE=planning,exploration

Use Cases

Use Case 1: Architecture Planning

# Before designing a new system
terraphim-agent search "microservices architecture patterns" --role architect
# Finds existing patterns, avoids reinventing

Use Case 2: Bug Investigation

# Before debugging
terraphim-agent search "similar errors: database connection timeout"
# Finds past solutions, accelerates resolution

Use Case 3: Technology Evaluation

# Before exploring new tech
terraphim-agent search "Rust vs Go evaluation" --role researcher
# Finds existing analysis, builds on it

Acceptance Criteria

• Configuration option to enable mandatory search
• Pre-task hook for planning tasks
• Pre-task hook for exploration tasks
• Configurable search parameters (limit, roles)
• Option to abort/warn/ignore on missing search
• Documentation for agent developers
• Example configurations

Related

• Metacognitive self-correction skill: https://git.terraphim.cloud/kimie05c34be198a20b9/metacognitive-skill
• FINAL-Bench research: https://huggingface.co/blog/FINAL-Bench/metacognitive

Priority

Medium — Improves agent effectiveness significantly but not blocking.

Effort Estimate

1-2 weeks for full implementation with configuration and documentation.

Start by locating the terraphim-agent configuration and task execution entry points described in the issue, then compare the configuration, pre-task hook, wrapper-command, and environment-variable options. Define how planning and exploration tasks are identified, how search parameters are applied, and how warn, abort, and ignore behave. Done means the selected enforcement path, documentation, and example configurations satisfy the listed acceptance criteria.