agentf 0.3.0 → 0.4.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: dc86ebb30ccffc8b338dd6e728947f87886c302046e81c01e10d739aac78095f
-  data.tar.gz: dda17a3643259253dac2b299e8b45c4f016f4e01f381e6b81956f54633eebcd3
+  metadata.gz: 31fbac11988e521fb26969fc26f2da9c434541fb0ada47c1b681a6717c4ee018
+  data.tar.gz: 761c50541fc3b7207089b22ac710f07b3fd004ae984a1d46b548e92277290196
 SHA512:
-  metadata.gz: ff8dd589ee31f74de1a35b0fc8122292b7b78747eb3d45338cc4f9fdcff4f8956f69ad0935aa0cc9b3d7bc3395b607b98d5143e1563c786f83eae44902153bb3
-  data.tar.gz: 4334dabaf36eabfdfbfeac1b7ff4bda60f1f2b17361df549ef641a85479c2b80b82806a5c18ffacfcba1ee0f7d618c13d55e0ffef8d7e66d0164aade58298a86
+  metadata.gz: 348d7d27eae2dddac25859f79c3b8fd99b5be0ebbd7d1447308c146155bb70908519e5ece270fd67255aaa2c313d5f689ce2b1ca46442789c6c229fc8ef47561
+  data.tar.gz: 3064ce1fc1f05c85b4d88e3f415202193427dcf21ad57827571eeda79a7975555390a6c506eca05ed36fce9c00d10fda3d9b357ab97930243f83b9934d1dca15

data/lib/agentf/agent_roles.rb

@@ -0,0 +1,29 @@
+# frozen_string_literal: true
+
+module Agentf
+  module AgentRoles
+    ORCHESTRATOR = "ORCHESTRATOR"
+    PLANNER = "PLANNER"
+    ENGINEER = "ENGINEER"
+    REVIEWER = "REVIEWER"
+    KNOWLEDGE_MANAGER = "KNOWLEDGE_MANAGER"
+    RESEARCHER = "RESEARCHER"
+    QA_TESTER = "QA_TESTER"
+    INCIDENT_RESPONDER = "INCIDENT_RESPONDER"
+    UI_ENGINEER = "UI_ENGINEER"
+    SECURITY_REVIEWER = "SECURITY_REVIEWER"
+
+    ALL = [
+      ORCHESTRATOR,
+      PLANNER,
+      ENGINEER,
+      REVIEWER,
+      KNOWLEDGE_MANAGER,
+      RESEARCHER,
+      QA_TESTER,
+      INCIDENT_RESPONDER,
+      UI_ENGINEER,
+      SECURITY_REVIEWER
+    ].freeze
+  end
+end

data/lib/agentf/agents/architect.rb

@@ -22,6 +22,22 @@ module Agentf
         COMMANDS
       end
 
+      def self.typed_name
+        Agentf::AgentRoles::PLANNER
+      end
+
+      def self.when_to_use
+        "Use for planning, decomposition, and constraints mapping before implementation."
+      end
+
+      def self.deliverables
+        ["Execution plan", "Decomposed subtasks", "Risk and pitfall notes"]
+      end
+
+      def self.working_style
+        "Strategic and constraint-aware with explicit decomposition."
+      end
+
       def self.memory_concepts
         MEMORY_CONCEPTS
       end

data/lib/agentf/agents/base.rb

@@ -14,6 +14,18 @@ module Agentf
         "Agent for #{typed_name.downcase}"
       end
 
+      def self.when_to_use
+        "Use when the workflow needs #{typed_name.downcase.tr('_', ' ')} expertise."
+      end
+
+      def self.deliverables
+        []
+      end
+
+      def self.working_style
+        "Structured, evidence-based, and outcome-oriented."
+      end
+
       def self.commands
         []
       end

data/lib/agentf/agents/debugger.rb

@@ -23,6 +23,22 @@ module Agentf
         COMMANDS
       end
 
+      def self.typed_name
+        Agentf::AgentRoles::INCIDENT_RESPONDER
+      end
+
+      def self.when_to_use
+        "Use for incident triage, root-cause analysis, and remediation paths."
+      end
+
+      def self.deliverables
+        ["Root-cause analysis", "Fix guidance", "Incident lesson record"]
+      end
+
+      def self.working_style
+        "Diagnostic, hypothesis-driven, and remediation-focused."
+      end
+
       def self.memory_concepts
         MEMORY_CONCEPTS
       end

data/lib/agentf/agents/designer.rb

@@ -23,6 +23,22 @@ module Agentf
         COMMANDS
       end
 
+      def self.typed_name
+        Agentf::AgentRoles::UI_ENGINEER
+      end
+
+      def self.when_to_use
+        "Use for transforming design specs into framework-ready UI components."
+      end
+
+      def self.deliverables
+        ["Component implementation", "Generated UI code", "Design-system alignment"]
+      end
+
+      def self.working_style
+        "Specification-driven with implementation-grade UI output."
+      end
+
       def self.memory_concepts
         MEMORY_CONCEPTS
       end

data/lib/agentf/agents/documenter.rb

@@ -22,6 +22,22 @@ module Agentf
         COMMANDS
       end
 
+      def self.typed_name
+        Agentf::AgentRoles::KNOWLEDGE_MANAGER
+      end
+
+      def self.when_to_use
+        "Use for memory synthesis, knowledge rollups, and delivery-ready summaries."
+      end
+
+      def self.deliverables
+        ["Success summary", "Pitfall summary", "Knowledge digest"]
+      end
+
+      def self.working_style
+        "Concise synthesis with attention to sensitive data boundaries."
+      end
+
       def self.memory_concepts
         MEMORY_CONCEPTS
       end

data/lib/agentf/agents/explorer.rb

@@ -23,6 +23,22 @@ module Agentf
         COMMANDS
       end
 
+      def self.typed_name
+        Agentf::AgentRoles::RESEARCHER
+      end
+
+      def self.when_to_use
+        "Use for codebase discovery, evidence gathering, and dependency tracing."
+      end
+
+      def self.deliverables
+        ["Relevant file list", "Search evidence", "Context breadcrumbs"]
+      end
+
+      def self.working_style
+        "Fast exploration with concrete references and traceable findings."
+      end
+
       def self.memory_concepts
         MEMORY_CONCEPTS
       end

data/lib/agentf/agents/reviewer.rb

@@ -22,6 +22,22 @@ module Agentf
         COMMANDS
       end
 
+      def self.typed_name
+        Agentf::AgentRoles::REVIEWER
+      end
+
+      def self.when_to_use
+        "Use for approval decisions, regression checks, and evidence-backed review."
+      end
+
+      def self.deliverables
+        ["Approval decision", "Issue list", "Pitfall-aligned feedback"]
+      end
+
+      def self.working_style
+        "Evidence-first with explicit approval criteria."
+      end
+
       def self.memory_concepts
         MEMORY_CONCEPTS
       end

data/lib/agentf/agents/security.rb

@@ -23,6 +23,22 @@ module Agentf
         COMMANDS
       end
 
+      def self.typed_name
+        Agentf::AgentRoles::SECURITY_REVIEWER
+      end
+
+      def self.when_to_use
+        "Use for security gating, prompt-injection checks, and secret leak detection."
+      end
+
+      def self.deliverables
+        ["Security findings", "Best-practice checklist", "Pass/warn outcome"]
+      end
+
+      def self.working_style
+        "Risk-focused with redaction-safe reporting."
+      end
+
       def self.memory_concepts
         MEMORY_CONCEPTS
       end

data/lib/agentf/agents/specialist.rb

@@ -22,6 +22,22 @@ module Agentf
         COMMANDS
       end
 
+      def self.typed_name
+        Agentf::AgentRoles::ENGINEER
+      end
+
+      def self.when_to_use
+        "Use for implementation, code edits, and deterministic execution outcomes."
+      end
+
+      def self.deliverables
+        ["Implemented code", "Execution status", "Success or pitfall memory"]
+      end
+
+      def self.working_style
+        "Execution-focused, deterministic, and evidence-driven."
+      end
+
       def self.memory_concepts
         MEMORY_CONCEPTS
       end

data/lib/agentf/agents/tester.rb

@@ -23,6 +23,22 @@ module Agentf
         COMMANDS
       end
 
+      def self.typed_name
+        Agentf::AgentRoles::QA_TESTER
+      end
+
+      def self.when_to_use
+        "Use for test generation, red/green validation, and execution verification."
+      end
+
+      def self.deliverables
+        ["Generated test artifacts", "Pass/fail evidence", "TDD phase signals"]
+      end
+
+      def self.working_style
+        "Quality-gate oriented with explicit pass/fail reporting."
+      end
+
       def self.memory_concepts
         MEMORY_CONCEPTS
       end

data/lib/agentf/cli/memory.rb

@@ -54,6 +54,10 @@ module Agentf
           list_tags
         when "search"
           search_memories(args)
+        when "neighbors"
+          neighbors(args)
+        when "subgraph"
+          subgraph(args)
         when "summary", "stats"
           show_summary
         when "by-tag"
@@ -195,7 +199,7 @@ module Agentf
 
         tags = parse_list_option(args, "--tags=")
         context = parse_single_option(args, "--context=").to_s
-        agent = parse_single_option(args, "--agent=") || "SPECIALIST"
+        agent = parse_single_option(args, "--agent=") || Agentf::AgentRoles::ENGINEER
         code_snippet = parse_single_option(args, "--code=").to_s
 
         intent_id = @memory.store_episode(
@@ -297,6 +301,34 @@ module Agentf
         output(result)
       end
 
+      def neighbors(args)
+        node_id = args.shift.to_s
+        if node_id.empty?
+          $stderr.puts "Error: neighbors requires a node id"
+          exit 1
+        end
+
+        relation = parse_single_option(args, "--relation=")
+        depth = parse_integer_option(args, "--depth=", default: 1)
+        limit = extract_limit(args)
+        result = @reviewer.neighbors(node_id, relation: relation, depth: depth, limit: limit)
+        output_graph(result)
+      end
+
+      def subgraph(args)
+        seeds = args.shift.to_s.split(",").map(&:strip).reject(&:empty?)
+        if seeds.empty?
+          $stderr.puts "Error: subgraph requires comma-separated seed ids"
+          exit 1
+        end
+
+        relation_filters = parse_list_option(args, "--relation=")
+        depth = parse_integer_option(args, "--depth=", default: 2)
+        limit = extract_limit(args, default: 200)
+        result = @reviewer.subgraph(seed_ids: seeds, relation_filters: relation_filters, depth: depth, limit: limit)
+        output_graph(result)
+      end
+
       def merge_memory_results(*results, limit:)
         entries = results.flat_map { |result| result["memories"] || [] }
         sorted = entries.sort_by { |entry| -(entry["created_at_unix"] || 0) }
@@ -331,6 +363,28 @@ module Agentf
         end
       end
 
+      def output_graph(result)
+        if result["error"]
+          if @json_output
+            puts JSON.generate({ "error" => result["error"] })
+          else
+            $stderr.puts "Error: #{result['error']}"
+          end
+          exit 1
+        end
+
+        if @json_output
+          puts JSON.generate(result)
+          return
+        end
+
+        puts "Graph result: #{result['count']} edges"
+        puts "Nodes: #{Array(result['nodes']).length}"
+        Array(result["edges"]).each do |edge|
+          puts "  - #{edge['source_id']} --#{edge['relation']}--> #{edge['target_id']}"
+        end
+      end
+
       def format_memory(mem)
         <<~OUTPUT
           [#{mem["type"]&.upcase}] #{mem["title"]}
@@ -366,6 +420,8 @@ module Agentf
             add-pitfall               Store pitfall memory
             tags                      List all unique tags
             search <query>            Search memories by keyword
+            neighbors <id>            Traverse graph edges from a memory id
+            subgraph <ids>            Build graph from comma-separated seed ids
             summary, stats            Show summary statistics
             by-tag <tag>              Get memories with specific tag
             by-agent <agent>          Get memories from specific agent
@@ -381,9 +437,10 @@ module Agentf
             agentf memory intents business -n 5
             agentf memory add-business-intent "Reliability" "Prioritize uptime" --tags=ops,platform --constraints="No downtime;No vendor lock-in"
             agentf memory add-feature-intent "Agent handoff" "Improve orchestrator continuity" --acceptance="Keeps context;Preserves task state"
-            agentf memory add-lesson "Refactor strategy" "Extracted adapter seam" --agent=ARCHITECT --tags=architecture
-            agentf memory add-success "Provider install works" "Installed copilot + opencode manifests" --agent=SPECIALIST
+            agentf memory add-lesson "Refactor strategy" "Extracted adapter seam" --agent=PLANNER --tags=architecture
+            agentf memory add-success "Provider install works" "Installed copilot + opencode manifests" --agent=ENGINEER
             agentf memory search "react"
+            agentf memory neighbors episode_abcd --depth=2
             agentf memory by-tag "performance"
             agentf memory summary
         HELP

data/lib/agentf/cli/router.rb

@@ -90,7 +90,7 @@ module Agentf
 
           Examples:
             agentf memory recent -n 5
-            agentf memory add-lesson "Title" "Description" --agent=ARCHITECT
+            agentf memory add-lesson "Title" "Description" --agent=PLANNER
             agentf code glob "lib/**/*.rb"
             agentf code grep "def execute" --file-pattern=*.rb
             agentf install --provider opencode,copilot --scope local

data/lib/agentf/cli/update.rb

@@ -138,11 +138,11 @@ module Agentf
 
         old_files = [
           File.join(opencode_dir, "tools", "agentf-tools.ts"),
-          File.join(opencode_dir, "agents", "WORKFLOW_ENGINE.md"),
+          File.join(opencode_dir, "agents", "ORCHESTRATOR.md"),
           File.join(opencode_dir, "memory", "REDIS_SCHEMA.md")
         ]
 
-        old_agent_names = %w[EXPLORER ARCHITECT DESIGNER DEBUGGER REVIEWER TESTER DOCUMENTER SECURITY SPECIALIST]
+        old_agent_names = %w[RESEARCHER PLANNER UI_ENGINEER INCIDENT_RESPONDER REVIEWER QA_TESTER KNOWLEDGE_MANAGER SECURITY_REVIEWER ENGINEER]
         old_files.concat(old_agent_names.map { |name| File.join(opencode_dir, "agents", "#{name}.md") })
 
         old_command_names = %w[explorer tester metrics security_scanner memory_reviewer designer debugger architecture]

data/lib/agentf/commands/memory_reviewer.rb

@@ -23,7 +23,9 @@ module Agentf
             { "name" => "get_by_type", "type" => "function" },
             { "name" => "get_by_agent", "type" => "function" },
             { "name" => "search", "type" => "function" },
-            { "name" => "get_summary", "type" => "function" }
+            { "name" => "get_summary", "type" => "function" },
+            { "name" => "neighbors", "type" => "function" },
+            { "name" => "subgraph", "type" => "function" }
           ]
         }
       end
@@ -150,6 +152,18 @@ module Agentf
         { "error" => e.message }
       end
 
+      def neighbors(node_id, relation: nil, depth: 1, limit: 50)
+        @memory.neighbors(node_id: node_id, relation: relation, depth: depth, limit: limit)
+      rescue => e
+        { "error" => e.message }
+      end
+
+      def subgraph(seed_ids:, depth: 2, relation_filters: nil, limit: 200)
+        @memory.subgraph(seed_ids: seed_ids, depth: depth, relation_filters: relation_filters, limit: limit)
+      rescue => e
+        { "error" => e.message }
+      end
+
       private
 
       def format_memories(memories)
@@ -169,6 +183,9 @@ module Agentf
           "code_snippet" => m["code_snippet"],
           "tags" => m["tags"],
           "agent" => m["agent"],
+          "metadata" => m["metadata"],
+          "entity_ids" => m["entity_ids"],
+          "relationships" => m["relationships"],
           "created_at" => format_time(m["created_at"]),
           "created_at_unix" => m["created_at"]
         }

data/lib/agentf/commands/metrics.rb

@@ -35,7 +35,7 @@ module Agentf
           description: metric_description(metrics),
           context: metric_context(metrics),
           tags: metric_tags(metrics),
-          agent: "WORKFLOW_ENGINE",
+          agent: Agentf::AgentRoles::ORCHESTRATOR,
           code_snippet: ""
         )
 
@@ -128,12 +128,12 @@ module Agentf
       end
 
       def reviewer_approved?(results)
-        review = results.find { |entry| entry["agent"] == "REVIEWER" }
+        review = results.find { |entry| entry["agent"] == Agentf::AgentRoles::REVIEWER }
         review&.dig("result", "approved") == true
       end
 
       def security_issue_count(results)
-        security_result = results.find { |entry| entry["agent"] == "SECURITY" }
+        security_result = results.find { |entry| entry["agent"] == Agentf::AgentRoles::SECURITY_REVIEWER }
         issues = security_result&.dig("result", "issues")
         Array(issues).length
       end
@@ -190,12 +190,11 @@ module Agentf
 
         memories
           .select { |m| Array(m["tags"]).include?(WORKFLOW_METRICS_TAG) }
-          .filter_map do |m|
+          .map do |m|
             context = parse_context_json(m["context"])
-            next if context.nil?
-
             context
           end
+          .compact
       end
 
       def parse_context_json(value)