Skip to content

REQUIREMENTS.md

Latest commit

 

History

History
141 lines (109 loc) · 5.65 KB

REQUIREMENTS.md

File metadata and controls

141 lines (109 loc) · 5.65 KB
Raw

Requirements

Functional Requirements

Skill System

  • FR-S1: Skills are loaded from configured directories (yoker.toml skills_dirs)
  • FR-S2: Skills are loaded from YOKER_SKILLS_PATH environment variable
  • FR-S3: /skill-name command invokes skill via CLI
  • FR-S4: /skill-name args command passes arguments to skill
  • FR-S5: Skill discovery shows available skills to agent
  • FR-S6: Agent can invoke skills dynamically via SkillTool
  • FR-S7: Skills use user-level message injection for context
  • FR-S8: Skills have namespace support (pkg:skill format)
  • FR-S9: Skill content size limited to 100KB (security)
  • FR-S10: Skill paths validated against allowed directories (security)
  • FR-S11: Skill schema with name, description, content, triggers, tools
  • FR-S12: SkillLoader parses Markdown + YAML frontmatter
  • FR-S13: SkillRegistry manages loaded skills with name lookup
  • FR-S14: format_discovery_block() shows skill list for LLM context
  • FR-S15: format_invocation_block() injects full skill content

Package Plugin System

  • FR-PP1: Packages provide tools/skills/agents via yoker module
  • FR-PP2: --with <package> loads package components before agent starts
  • FR-PP3: Namespaced components (pkg:skill, pkg:tool, pkg:agent)
  • FR-PP4: Graceful failure when package lacks yoker support
  • FR-PP5: Multiple packages can be loaded (--with pkg1 --with pkg2)

Async-First Agent Architecture

  • FR1: process() method is async and handles all core logic
  • FR2: All Agent methods are async-native
  • FR3: _emit() supports both sync and async event handlers
  • FR4: Async Ollama streaming works correctly with AsyncClient
  • FR5: begin_session() and end_session() are async methods
  • FR6: All tools use async def execute()
  • FR7: All existing tests pass (1047 tests)
  • FR8: Documentation updated with async API examples
  • FR9: CLI uses async API internally with asyncio.run()
  • FR10: Tool base class has execute() as abstract async method

Core Agent Features

  • FR-A1: Agent processes messages and returns responses
  • FR-A2: Agent uses tools to perform operations
  • FR-A3: Agent emits events during processing
  • FR-A4: Agent manages conversation context
  • FR-A5: Agent loads definitions from Markdown files
  • FR-A6: Agent filters tools based on definition
  • FR-A7: Agent supports hierarchical spawning

Tool System

  • FR-T1: Tools have structured schemas
  • FR-T2: Tools have guardrails for safety
  • FR-T3: Tools return structured results
  • FR-T4: Tools can be registered dynamically
  • FR-T5: Path-based guardrails enforce filesystem permissions

Configuration System

  • FR-C1: Configuration loaded from TOML files
  • FR-C2: Configuration validated for schema and semantics
  • FR-C3: Agent definitions loaded from Markdown
  • FR-C4: Tool guardrails configured globally
  • FR-C5: Tool availability configured per-agent

Context Management

  • FR-CM1: Context persisted to JSONL files
  • FR-CM2: Context loaded on resume
  • FR-CM3: Context isolated for subagents
  • FR-CM4: Context tracks conversation and state

Event System

  • FR-E1: Events emitted for all operations
  • FR-E2: Event handlers registered dynamically
  • FR-E3: Events support session, turn, thinking, content, tool types
  • FR-E4: Console handler provides default visualization

Backend Integration

  • FR-B1: Ollama client integration
  • FR-B2: Streaming response support
  • FR-B3: Tool call parsing and execution
  • FR-B4: Configurable model parameters
  • FR-B5: API key authentication for ollama.com

Non-Functional Requirements

Async-First Architecture

  • NFR-ASYNC1: Async-native implementation with no sync wrappers
  • NFR-ASYNC2: Async API properly handles concurrent operations
  • NFR-ASYNC3: Resource cleanup works correctly (no event loop leaks)
  • NFR-ASYNC4: Error handling preserves async stack traces
  • NFR-ASYNC5: Type hints updated for async methods

Performance

  • NFR-P1: Streaming responses for perceived performance
  • NFR-P2: Lazy tool loading (Phase 2)
  • NFR-P3: Context window management (Phase 2)

Security

  • NFR-S1: Guardrails enforce filesystem permissions
  • NFR-S2: Path validation prevents traversal attacks
  • NFR-S3: Blocked patterns prevent sensitive file access
  • NFR-S4: Subprocess execution secured (future tools)
  • NFR-S5: Recursion depth limits prevent runaway spawning

Quality

  • NFR-Q1: Test coverage >80%
  • NFR-Q2: Full type hints (mypy strict mode)
  • NFR-Q3: Code formatted with ruff
  • NFR-Q4: Documentation via Sphinx

Maintainability

  • NFR-M1: Pluggable architecture
  • NFR-M2: Clear separation of concerns
  • NFR-M3: Comprehensive logging
  • NFR-M4: Structured error handling

Completed Requirements

  • FR-A1 through FR-A7: Core Agent Features
  • FR-T1 through FR-T5: Tool System
  • FR-C1 through FR-C5: Configuration System
  • FR-CM1 through FR-CM4: Context Management
  • FR-E1 through FR-E4: Event System
  • FR-B1 through FR-B5: Backend Integration
  • NFR-P1: Streaming responses
  • NFR-S1 through NFR-S5: Security requirements
  • NFR-Q1 through NFR-Q4: Quality requirements
  • NFR-M1 through NFR-M4: Maintainability requirements