Legendary: Actors, Skills & Tool Execution (Workstream C) #374

Open
opened 2026-02-22 23:41:45 +00:00 by freemo · 2 comments
Owner

Background

This Legendary covers the complete actor and skill system: hierarchical actor YAML schema, actor compiler (to LangGraph), MCP tool adapter, Agent Skills discovery, skill registry flattening, tool lifecycle management, and LSP integration stubs.

Expected Behavior

Actors can be defined in YAML, compiled to LangGraph StateGraphs, discover and route tools via MCP and Agent Skills, and persist flattened tool sets for runtime use.

Child Epics

  • #392 Epic: Actor YAML & Compiler
  • #393 Epic: Skill & Tool Lifecycle
  • #824 Epic: LSP Functional Runtime

Definition of Done

This Legendary is complete when all child Epics and their constituent issues are closed and merged. Actor compilation and tool routing pass all M2 E2E verification suites.

## Background This Legendary covers the complete actor and skill system: hierarchical actor YAML schema, actor compiler (to LangGraph), MCP tool adapter, Agent Skills discovery, skill registry flattening, tool lifecycle management, and LSP integration stubs. ## Expected Behavior Actors can be defined in YAML, compiled to LangGraph StateGraphs, discover and route tools via MCP and Agent Skills, and persist flattened tool sets for runtime use. ## Child Epics - #392 Epic: Actor YAML & Compiler - #393 Epic: Skill & Tool Lifecycle - #824 Epic: LSP Functional Runtime ## Definition of Done This Legendary is complete when all child Epics and their constituent issues are closed and merged. Actor compilation and tool routing pass all M2 E2E verification suites.
Author
Owner

Implementation Notes — Critical Architectural Decision: Tool-Based Resource Modification

2026-02-06: CRITICAL ARCHITECTURAL DECISION - Tool-Based Resource Modification

  • REPLACED: OutputParser/code fence parsing approach.
  • WITH: Tool-based change tracking (modern approach used by Claude Code, Cursor, Aider).
  • Key changes:
    • LLMs call skills/tools directly (edit_file, write_file, delete_file, etc.).
    • Skills operate on sandbox state directly.
    • ChangeSet is built from skill invocation history, NOT by parsing LLM text output.
  • Added built-in resource skills (now C4.file/C4.search/C4.git): file ops, dir ops, search, git ops.
  • Added MCP skill adapter (now C7.mcp): connect to external MCP servers.
    • Replaced C4 "Multi-File ChangeSet Generation" with "Tool-Based Change Tracking".
    • Added SkillInvocationTracker and ToolCallRouter components.
  • Rationale:
    • No parsing ambiguity (is this code or explanation?).
    • Each operation is explicit, typed, and trackable.
    • Supports rollback (replay inverse of recorded changes).
    • Resource-agnostic (works for files, databases, APIs, any resource type).
    • Compatible with MCP standard for external tools.

(Migrated from docs/implementation-notes.md)

## Implementation Notes — Critical Architectural Decision: Tool-Based Resource Modification **2026-02-06**: CRITICAL ARCHITECTURAL DECISION - Tool-Based Resource Modification - **REPLACED**: OutputParser/code fence parsing approach. - **WITH**: Tool-based change tracking (modern approach used by Claude Code, Cursor, Aider). - **Key changes**: - LLMs call skills/tools directly (edit_file, write_file, delete_file, etc.). - Skills operate on sandbox state directly. - ChangeSet is built from skill invocation history, NOT by parsing LLM text output. - Added built-in resource skills (now C4.file/C4.search/C4.git): file ops, dir ops, search, git ops. - Added MCP skill adapter (now C7.mcp): connect to external MCP servers. - Replaced C4 "Multi-File ChangeSet Generation" with "Tool-Based Change Tracking". - Added SkillInvocationTracker and ToolCallRouter components. - **Rationale**: - No parsing ambiguity (is this code or explanation?). - Each operation is explicit, typed, and trackable. - Supports rollback (replay inverse of recorded changes). - Resource-agnostic (works for files, databases, APIs, any resource type). - Compatible with MCP standard for external tools. *(Migrated from `docs/implementation-notes.md`)*
freemo self-assigned this 2026-02-24 03:37:59 +00:00
Author
Owner

Day 36 — Epic/Legendary dependency audit findings

This Legendary has 3 non-Epic issues (#883, #882, #879) linked as direct children, which breaks the Legendary → Epic → Issue hierarchy convention. Legendaries should only contain Epics as children, not individual issues.

These issues should be moved under the appropriate Epic:

  • #883 (feat: built-in tools) → should be under Epic #392 (Actor YAML & Compiler) or a tool-related Epic
  • #882 (feat: BuiltinAdapter + MCP) → should be under Epic #392 (Actor YAML & Compiler)
  • #879 (feat: tool env preferences) → should be under Epic #392 (Actor YAML & Compiler)

Action: Remove the direct dependency links from #374 to #883/#882/#879 and add them as dependencies of Epic #392 instead. Since the Forgejo dependency creation API is broken in version 14.0.2, this must be done via the web UI.

**Day 36 — Epic/Legendary dependency audit findings** This Legendary has **3 non-Epic issues** (#883, #882, #879) linked as direct children, which breaks the Legendary → Epic → Issue hierarchy convention. Legendaries should only contain Epics as children, not individual issues. These issues should be moved under the appropriate Epic: - #883 (feat: built-in tools) → should be under Epic #392 (Actor YAML & Compiler) or a tool-related Epic - #882 (feat: BuiltinAdapter + MCP) → should be under Epic #392 (Actor YAML & Compiler) - #879 (feat: tool env preferences) → should be under Epic #392 (Actor YAML & Compiler) **Action:** Remove the direct dependency links from #374 to #883/#882/#879 and add them as dependencies of Epic #392 instead. Since the Forgejo dependency creation API is broken in version 14.0.2, this must be done via the web UI.
freemo added this to the v3.2.0 milestone 2026-03-17 18:32:48 +00:00
Sign in to join this conversation.
No milestone
No project
No assignees
1 participant
Notifications
Due date
The due date is invalid or out of range. Please use the format "yyyy-mm-dd".

No due date set.

Depends on
#354 Epic: Actor & Skill Schema + CLI (C0)
cleveragents/cleveragents-core
#392 Epic: Actor YAML & Compiler
cleveragents/cleveragents-core
#393 Epic: Skill & Tool Lifecycle
cleveragents/cleveragents-core
#824 Epic: LSP Functional Runtime
cleveragents/cleveragents-core
Reference
cleveragents/cleveragents-core#374
No description provided.