agentf 0.5.0 → 0.7.0

data/lib/agentf/installer.rb

@@ -9,12 +9,9 @@ module Agentf
   class Installer
     READ_ACTIONS = {
       "get_recent_memories" => { cli: "agentf memory recent -n 10", tool: "agentf-memory-recent" },
-      "get_pitfalls" => { cli: "agentf memory pitfalls -n 10", tool: "agentf-memory-recent" },
+      "get_episodes" => { cli: "agentf memory episodes -n 10", tool: "agentf-memory-episodes" },
       "get_lessons" => { cli: "agentf memory lessons -n 10", tool: "agentf-memory-recent" },
-      "get_successes" => { cli: "agentf memory successes -n 10", tool: "agentf-memory-recent" },
       "get_intents" => { cli: "agentf memory intents", tool: "agentf-memory-recent" },
-      "get_all_tags" => { cli: "agentf memory tags", tool: "agentf-memory-recent" },
-      "get_by_tag" => { cli: "agentf memory by-tag <tag> -n 10", tool: "agentf-memory-search" },
       "get_by_type" => { cli: "agentf memory by-type <type> -n 10", tool: "agentf-memory-search" },
       "get_by_agent" => { cli: "agentf memory by-agent <agent> -n 10", tool: "agentf-memory-search" },
       "search" => { cli: "agentf memory search \"<query>\" -n 10", tool: "agentf-memory-search" },
@@ -22,10 +19,10 @@ module Agentf
     }.freeze
 
     WRITE_ACTIONS = {
-      "store_lesson" => { cli: "agentf memory add-lesson \"<title>\" \"<description>\" --agent=<AGENT> --tags=learning", tool: "agentf-memory-add-lesson" },
-      "store_success" => { cli: "agentf memory add-success \"<title>\" \"<description>\" --agent=<AGENT> --tags=success", tool: "agentf-memory-add-success" },
-      "store_pitfall" => { cli: "agentf memory add-pitfall \"<title>\" \"<description>\" --agent=<AGENT> --tags=pitfall", tool: "agentf-memory-add-pitfall" },
-      "store_business_intent" => { cli: "agentf memory add-business-intent \"<title>\" \"<description>\" --tags=strategy", tool: "agentf-memory-add-business-intent" },
+      "store_lesson" => { cli: "agentf memory add-lesson \"<title>\" \"<description>\" --agent=<AGENT>", tool: "agentf-memory-add-lesson" },
+      "store_episode" => { cli: "agentf memory add-episode \"<title>\" \"<description>\" --outcome=positive --agent=<AGENT>", tool: "agentf-memory-episodes" },
+      "store_playbook" => { cli: "agentf memory add-playbook \"<title>\" \"<description>\" --steps=\"<step1>;<step2>\"", tool: "agentf-memory-add-playbook" },
+      "store_business_intent" => { cli: "agentf memory add-business-intent \"<title>\" \"<description>\"", tool: "agentf-memory-add-business-intent" },
       "store_feature_intent" => { cli: "agentf memory add-feature-intent \"<title>\" \"<description>\" --acceptance=\"<criteria>\"", tool: "agentf-memory-add-feature-intent" }
     }.freeze
 
@@ -84,6 +81,7 @@ module Agentf
         writes.concat(write_agents(root: root, layout: layout, provider: provider, only_agents: only_agents))
         writes.concat(write_commands(root: root, layout: layout, provider: provider, only_commands: only_commands))
         writes.concat(write_opencode_helpers(root: root)) if provider.to_s == "opencode"
+        writes.concat(write_copilot_helpers(root: root)) if provider.to_s == "copilot"
       end
 
       # Optionally install dependencies for opencode helper package.json
@@ -152,7 +150,7 @@ module Agentf
 
       classes.map do |klass|
         target = File.join(root, layout.fetch("agents_dir"), layout.fetch("agent_filename").call(klass))
-        write_manifest(target, render_agent_manifest(klass, provider: provider))
+        write_manifest(target, render_agent_manifest(klass))
       end
     end
 
@@ -162,7 +160,7 @@ module Agentf
 
       manifests.map do |manifest|
         target = File.join(root, layout.fetch("commands_dir"), layout.fetch("command_filename").call(manifest))
-        write_manifest(target, render_command_manifest(manifest, provider: provider))
+        write_manifest(target, render_command_manifest(manifest))
       end
     end
 
@@ -195,6 +193,12 @@ module Agentf
       writes
     end
 
+    def write_copilot_helpers(root:)
+      return [] unless root == @local_root
+
+      [write_copilot_mcp_json(root)]
+    end
+
     def opencode_plugin_runtime?
       @opencode_runtime == "plugin"
     end
@@ -233,7 +237,7 @@ module Agentf
       end
     end
 
-    def render_agent_manifest(klass, provider:)
+    def render_agent_manifest(klass)
       # Emit a minimal, stable manifest that acts as a pointer to the runtime
       # tool implemented by the plugin/CLI. Keep filename and `name` stable so
       # upgrades remain compatible with existing installs.
@@ -253,6 +257,9 @@ module Agentf
 
       description = klass.respond_to?(:description) ? klass.description.to_s.strip : ""
 
+      tdd_section = klass.respond_to?(:writes_code?) && klass.writes_code? ? tdd_requirement_section : ""
+      fallback = cli_fallback_section(klass)
+
       <<~MARKDOWN
         ---
         name: #{tool_name}
@@ -269,7 +276,50 @@ module Agentf
         do not retry the write.
 
         Policy Summary: #{policy_summary}
+        #{tdd_section}#{fallback}
+      MARKDOWN
+    end
+
+    def tdd_requirement_section
+      <<~MARKDOWN
+
+        ## TDD Requirement
+
+        This agent writes code. Every implementation MUST follow red/green discipline:
+
+        1. **Write the spec first** — create a failing test before any implementation code
+        2. **Run tests to confirm red** — verify the spec fails (`bundle exec rspec <spec_file>`)
+        3. **Implement the code** — write only enough to make the spec pass
+        4. **Run tests to confirm green** — verify all specs pass before reporting done
+        5. **Never skip** — do not create a class, method, or module without a corresponding spec file
 
+        Showing test output (red then green) is mandatory evidence of completion.
+      MARKDOWN
+    end
+
+    def cli_fallback_section(klass)
+      agent_name = klass.typed_name.downcase
+      read_cmds = READ_ACTIONS.values_at("get_recent_memories", "search").map { |a| "- `#{a[:cli]}`" }.join("\n")
+
+      write_actions = Array(klass.respond_to?(:memory_concepts) ? klass.memory_concepts["writes"] : [])
+        .map { |item| item.to_s.split("#").last }
+        .filter_map { |key| WRITE_ACTIONS[key] }
+        .map { |a| "- `#{a[:cli].gsub("<AGENT>", agent_name.upcase)}`" }
+        .join("\n")
+
+      write_section = write_actions.empty? ? "" : "\n**Memory writes**:\n#{write_actions}\n"
+
+      <<~MARKDOWN
+
+        ## CLI Fallback
+
+        If the `agentf` MCP server is unavailable, run equivalent commands directly in the terminal:
+
+        **Run this agent**: `agentf agent #{agent_name} "<input>"`
+
+        **Memory reads**:
+        #{read_cmds}
+        #{write_section}
       MARKDOWN
     end
 
@@ -325,9 +375,10 @@ module Agentf
       "agentf-#{name.to_s.downcase}"
     end
 
-    def render_command_manifest(manifest, provider:)
+    def render_command_manifest(manifest)
       cmd_name = command_identifier(manifest.fetch("name"))
       desc = manifest.fetch("description", "").to_s.strip
+      fallback = command_cli_fallback_section(manifest)
 
       <<~MARKDOWN
         ---
@@ -338,7 +389,45 @@ module Agentf
 
         IMPORTANT: Do not embed runtime logic here. Invoke the `#{cmd_name}` tool to perform
         any codebase or memory operations.
+        #{fallback}
+      MARKDOWN
+    end
+
+    def command_cli_fallback_section(manifest)
+      name = manifest.fetch("name")
+      cli_lines = case name
+                  when "explorer"
+                    [
+                      "`agentf code glob \"<pattern>\"`",
+                      "`agentf code grep \"<pattern>\"`",
+                      "`agentf code tree --depth=3`",
+                      "`agentf code related <file>`"
+                    ]
+                  when "memory"
+                    [
+                      "`#{READ_ACTIONS.fetch('get_recent_memories')[:cli]}`",
+                      "`#{READ_ACTIONS.fetch('search')[:cli]}`",
+                      "`#{READ_ACTIONS.fetch('get_episodes')[:cli]}`",
+                      "`#{WRITE_ACTIONS.fetch('store_lesson')[:cli]}`",
+                      "`#{WRITE_ACTIONS.fetch('store_episode')[:cli]}`"
+                    ]
+                  else
+                    [
+                      "`agentf code glob \"<pattern>\"`",
+                      "`#{READ_ACTIONS.fetch('get_recent_memories')[:cli]}`",
+                      "`#{READ_ACTIONS.fetch('search')[:cli]}`"
+                    ]
+                  end
+
+      tool_lines = cli_lines.map { |cmd| "- #{cmd}" }.join("\n")
+
+      <<~MARKDOWN
+
+        ## CLI Fallback
+
+        If the `agentf` MCP server is unavailable, run equivalent commands directly in the terminal:
 
+        #{tool_lines}
       MARKDOWN
     end
 
@@ -351,8 +440,8 @@ module Agentf
         Copilot should call the local `agentf` MCP server tools for runtime actions.
 
         - Code discovery tools: `agentf-code-glob`, `agentf-code-grep`, `agentf-code-tree`, `agentf-code-related-files`
-        - Memory read tools: `agentf-memory-recent`, `agentf-memory-search`
-        - Memory write tools (if enabled): `agentf-memory-add-lesson`, `agentf-memory-add-success`, `agentf-memory-add-pitfall`
+        - Memory read tools: `agentf-memory-recent`, `agentf-memory-search`, `agentf-memory-episodes`
+        - Memory write tools (if enabled): `agentf-memory-add-lesson`, `agentf-memory-add-playbook`
 
         MCP server is started via `agentf mcp-server` and runs locally over stdio.
       MARKDOWN
@@ -365,8 +454,8 @@ module Agentf
       recommended_tools = case command_name
                            when "explorer"
                              "`agentf-code-glob`, `agentf-code-grep`, `agentf-code-tree`, `agentf-code-related-files`"
-                           when "memory"
-                             "`agentf-memory-recent`, `agentf-memory-search`, `agentf-memory-add-lesson`, `agentf-memory-add-success`, `agentf-memory-add-pitfall`"
+                            when "memory"
+                              "`agentf-memory-recent`, `agentf-memory-search`, `agentf-memory-episodes`, `agentf-memory-add-lesson`, `agentf-memory-add-playbook`"
                            else
                              "`agentf-code-glob`, `agentf-code-grep`, `agentf-memory-recent`, `agentf-memory-search`"
                           end
@@ -401,7 +490,7 @@ module Agentf
         1. Build plan from provider adapter (`Agentf::Service::Providers::OpenCode` or `Agentf::Service::Providers::Copilot`)
         2. Enrich each agent step with brain context from Redis memory
         3. Persist feature intent at workflow start
-        4. Persist lessons/pitfalls from each agent execution
+        4. Persist lessons and negative episodes from each agent execution
         5. Return full workflow state for manual review and future autonomous control
         6. Enforce workflow contract stages (`spec`, `plan`, `execute`, `review`, `finalize`) when enabled
 
@@ -691,17 +780,6 @@ module Agentf
                 return runAgentfCli(context.directory, "memory", "search", [_args.query, "-n", String(limit)]);
               },
             }),
-            "agentf-memory-by-tag": tool({
-              description: "Get Agentf memories by tag.",
-              args: {
-                tag: tool.schema.string().describe("Tag to filter by"),
-                limit: tool.schema.number().int().min(1).max(100).optional().describe("How many results to return"),
-              },
-              async execute(_args: any, context: any) {
-                const limit = _args.limit ?? 10;
-                return runAgentfCli(context.directory, "memory", "by-tag", [_args.tag, "-n", String(limit)]);
-              },
-            }),
             "agentf-memory-by-agent": tool({
               description: "Get Agentf memories by agent.",
               args: {
@@ -716,7 +794,7 @@ module Agentf
             "agentf-memory-by-type": tool({
               description: "Get Agentf memories by type.",
               args: {
-                type: tool.schema.string().describe("Memory type (pitfall|lesson|success|business_intent|feature_intent)"),
+                type: tool.schema.string().describe("Memory type (episode|lesson|playbook|business_intent|feature_intent|incident)"),
                 limit: tool.schema.number().int().min(1).max(100).optional().describe("How many results to return"),
               },
               async execute(_args: any, context: any) {
@@ -724,19 +802,17 @@ module Agentf
                 return runAgentfCli(context.directory, "memory", "by-type", [_args.type, "-n", String(limit)]);
               },
             }),
-            "agentf-memory-tags": tool({
-              description: "List all unique memory tags.",
-              args: {},
-              async execute(_args: any, context: any) {
-                return runAgentfCli(context.directory, "memory", "tags", []);
+            "agentf-memory-episodes": tool({
+              description: "List episode memories.",
+              args: {
+                outcome: tool.schema.string().optional().describe("Optional outcome filter (positive|negative|neutral)"),
+                limit: tool.schema.number().int().min(1).max(100).optional(),
               },
-            }),
-            "agentf-memory-pitfalls": tool({
-              description: "List pitfall memories.",
-              args: { limit: tool.schema.number().int().min(1).max(100).optional() },
               async execute(_args: any, context: any) {
                 const limit = _args.limit ?? 10;
-                return runAgentfCli(context.directory, "memory", "pitfalls", ["-n", String(limit)]);
+                const commandArgs = ["-n", String(limit)];
+                if (_args.outcome) commandArgs.push(`--outcome=${_args.outcome}`);
+                return runAgentfCli(context.directory, "memory", "episodes", commandArgs);
               },
             }),
             "agentf-memory-lessons": tool({
@@ -747,14 +823,6 @@ module Agentf
                 return runAgentfCli(context.directory, "memory", "lessons", ["-n", String(limit)]);
               },
             }),
-            "agentf-memory-successes": tool({
-              description: "List success memories.",
-              args: { limit: tool.schema.number().int().min(1).max(100).optional() },
-              async execute(_args: any, context: any) {
-                const limit = _args.limit ?? 10;
-                return runAgentfCli(context.directory, "memory", "successes", ["-n", String(limit)]);
-              },
-            }),
             "agentf-memory-intents": tool({
               description: "List intents (business, feature or both).",
               args: { kind: tool.schema.string().optional(), limit: tool.schema.number().int().min(1).max(100).optional() },
@@ -786,13 +854,11 @@ module Agentf
               args: {
                 title: tool.schema.string(),
                 description: tool.schema.string(),
-                tags: tool.schema.array(tool.schema.string()).optional(),
                 constraints: tool.schema.array(tool.schema.string()).optional(),
                 priority: tool.schema.number().int().optional(),
               },
               async execute(_args: any, context: any) {
                 const commandArgs = [_args.title, _args.description];
-                if (_args.tags?.length) commandArgs.push(`--tags=${_args.tags.join(",")}`);
                 if (_args.constraints?.length) commandArgs.push(`--constraints=${_args.constraints.join(";")}`);
                 if (Number.isInteger(_args.priority)) commandArgs.push(`--priority=${String(_args.priority)}`);
                 return runAgentfCli(context.directory, "memory", "add-business-intent", commandArgs);
@@ -803,14 +869,12 @@ module Agentf
               args: {
                 title: tool.schema.string(),
                 description: tool.schema.string(),
-                tags: tool.schema.array(tool.schema.string()).optional(),
                 acceptance: tool.schema.array(tool.schema.string()).optional(),
                 non_goals: tool.schema.array(tool.schema.string()).optional(),
                 related_task_id: tool.schema.string().optional(),
               },
               async execute(_args: any, context: any) {
                 const commandArgs = [_args.title, _args.description];
-                if (_args.tags?.length) commandArgs.push(`--tags=${_args.tags.join(",")}`);
                 if (_args.acceptance?.length) commandArgs.push(`--acceptance=${_args.acceptance.join(";")}`);
                 if (_args.non_goals?.length) commandArgs.push(`--non-goals=${_args.non_goals.join(";")}`);
                 if (_args.related_task_id) commandArgs.push(`--task=${_args.related_task_id}`);
@@ -856,52 +920,32 @@ module Agentf
                 title: tool.schema.string(),
                 description: tool.schema.string(),
                 agent: tool.schema.string().optional(),
-                tags: tool.schema.array(tool.schema.string()).optional(),
                 context: tool.schema.string().optional(),
               },
               async execute(_args: any, context: any) {
                 const commandArgs = [_args.title, _args.description];
                 if (_args.agent) commandArgs.push(`--agent=${_args.agent}`);
-                if (_args.tags?.length) commandArgs.push(`--tags=${_args.tags.join(",")}`);
                 if (_args.context) commandArgs.push(`--context=${_args.context}`);
 
                 return runAgentfCli(context.directory, "memory", "add-lesson", commandArgs);
               },
             }),
-            "agentf-memory-add-success": tool({
-              description: "Store a success memory in Redis.",
+            "agentf-memory-add-playbook": tool({
+              description: "Store a playbook memory in Redis.",
               args: {
                 title: tool.schema.string(),
                 description: tool.schema.string(),
                 agent: tool.schema.string().optional(),
-                tags: tool.schema.array(tool.schema.string()).optional(),
-                context: tool.schema.string().optional(),
+                steps: tool.schema.array(tool.schema.string()).optional(),
+                feature_area: tool.schema.string().optional(),
               },
               async execute(_args: any, context: any) {
                 const commandArgs = [_args.title, _args.description];
                 if (_args.agent) commandArgs.push(`--agent=${_args.agent}`);
-                if (_args.tags?.length) commandArgs.push(`--tags=${_args.tags.join(",")}`);
-                if (_args.context) commandArgs.push(`--context=${_args.context}`);
+                if (_args.steps?.length) commandArgs.push(`--steps=${_args.steps.join(";")}`);
+                if (_args.feature_area) commandArgs.push(`--feature-area=${_args.feature_area}`);
 
-                return runAgentfCli(context.directory, "memory", "add-success", commandArgs);
-              },
-            }),
-            "agentf-memory-add-pitfall": tool({
-              description: "Store a pitfall memory in Redis.",
-              args: {
-                title: tool.schema.string(),
-                description: tool.schema.string(),
-                agent: tool.schema.string().optional(),
-                tags: tool.schema.array(tool.schema.string()).optional(),
-                context: tool.schema.string().optional(),
-              },
-              async execute(_args: any, context: any) {
-                const commandArgs = [_args.title, _args.description];
-                if (_args.agent) commandArgs.push(`--agent=${_args.agent}`);
-                if (_args.tags?.length) commandArgs.push(`--tags=${_args.tags.join(",")}`);
-                if (_args.context) commandArgs.push(`--context=${_args.context}`);
-
-                return runAgentfCli(context.directory, "memory", "add-pitfall", commandArgs);
+                return runAgentfCli(context.directory, "memory", "add-playbook", commandArgs);
               },
             }),
           };
@@ -961,6 +1005,10 @@ module Agentf
       JSON.pretty_generate(opencode_json_config(root))
     end
 
+    def render_copilot_mcp_json(root)
+      JSON.pretty_generate(copilot_mcp_config(root))
+    end
+
     def opencode_json_config(root)
       base = {
         "$schema" => "https://opencode.ai/config.json"
@@ -1019,6 +1067,37 @@ module Agentf
       write_manifest(path, JSON.pretty_generate(merged))
     end
 
+    def copilot_mcp_config(root)
+      {
+        "servers" => {
+          "agentf" => {
+            "type" => "stdio",
+            "command" => "agentf",
+            "args" => ["mcp-server"]
+          }
+        }
+      }
+    end
+
+    def write_copilot_mcp_json(root)
+      path = File.join(root, ".vscode", "mcp.json")
+      new_content = JSON.parse(render_copilot_mcp_json(root))
+
+      return write_manifest(path, JSON.pretty_generate(new_content)) unless File.exist?(path)
+
+      begin
+        existing = JSON.parse(File.read(path))
+      rescue StandardError => e
+        warn "Failed to parse existing #{path}: #{e.message}"
+        return write_manifest(path, JSON.pretty_generate(new_content))
+      end
+
+      merged = existing.dup
+      merged["servers"] = (existing["servers"] || {}).merge(new_content.fetch("servers"))
+
+      write_manifest(path, JSON.pretty_generate(merged))
+    end
+
     def render_opencode_tsconfig
       <<~JSON
         {
@@ -1093,19 +1172,20 @@ module Agentf
         - `agent`: string
 
         ### 2. Episodic Memory (`episodic:*`)
-        Used for success, pitfall, lesson, and intent records.
+        Used for episode, lesson, playbook, and intent records.
 
         **Search index**: `episodic:logs`
 
         **Schema fields**:
         - `$.id`
         - `$.type`
+        - `$.outcome`
         - `$.title`
         - `$.description`
         - `$.project`
         - `$.context`
         - `$.code_snippet`
-        - `$.tags`
+        - `$.embedding`
         - `$.created_at`
         - `$.agent`
         - `$.related_task_id`
@@ -1116,9 +1196,9 @@ module Agentf
 
         - Read recent: `agentf memory recent -n 10`
         - Search: `agentf memory search "query" -n 10`
+        - List episodes: `agentf memory episodes -n 10 --outcome=negative`
         - Add lesson: `agentf memory add-lesson "<title>" "<description>" --agent=<AGENT>`
-        - Add success: `agentf memory add-success "<title>" "<description>" --agent=<AGENT>`
-        - Add pitfall: `agentf memory add-pitfall "<title>" "<description>" --agent=<AGENT>`
+        - Add playbook: `agentf memory add-playbook "<title>" "<description>" --steps="<step1>;<step2>"`
       MARKDOWN
     end
   end