Optimization

[Zochory]

This pull request primarily improves documentation and project configuration, with a focus on developer experience, architectural clarity, and lifecycle extensibility for agents. It introduces a comprehensive onboarding and workflow guide for WARP users, documents new extensibility points (like agent lifecycle hooks and progress emitters), and clarifies architectural and validation patterns. It also removes deprecated configuration and CI files.

Documentation improvements:

• Added a new WARP.md file providing a complete onboarding and workflow guide for contributors using WARP, including stack overview, common commands, architecture, extension points, and conventions.
• Expanded docs/AGENTS.md with a section on Agent Lifecycle Hooks, documenting the AgentLifecycle protocol with warmup() and teardown() methods, including a full example implementation.
• Updated docs/Project_Architecture_Blueprint.md to:
  • Document the new ProgressEmitter interface for custom progress reporting, including usage examples. [1] [2] [3] [4]
  • Clarify the role of Pydantic models in workflow YAML validation, and update architectural component descriptions for accuracy.
  • Reference the OpenTelemetry integration guide for observability setup.

Configuration and workflow:

• Added a $schema directive to config/workflows.yaml for YAML language server support, improving IDE validation and developer experience.

Developer workflow and CI:

• Removed the deprecated .github/workflows/codex-autofix.yml workflow, which previously attempted to auto-fix CI failures using Codex.

Project hygiene:

• Removed the unused .cursor/mcp.json configuration file.
• Minor cleanup in README.md (removed a blank line and trailing whitespace). [1] [2]

Other documentation fixes:

• Corrected the health check route reference in docs/api/developer-guide.md to point to api/routers/health.py instead of the outdated path.## Description

Type of Change

• Bug fix (non-breaking change which fixes an issue)
• New feature (non-breaking change which adds functionality)
• Breaking change (fix or feature that would cause existing functionality to not work as expected)
• Documentation update
• Code refactoring
• Performance improvement
• Test updates
• Configuration change

Related Issues

Fixes #

Changes Made

• (describe your changes here)

Testing

• All existing tests pass (uv run pytest)
• Added new tests for new functionality
• Configuration validation passes (uv run python tests/test_config.py)
• Linting passes (uv run ruff check .)
• Formatting is correct (uv run black .)
• Type checking passes (uv run mypy .)

Test Commands Run

# Commands run to validate changes
uv run pytest
uv run python tests/test_config.py
uv run ruff check .
uv run black .

Documentation

• Updated relevant documentation
• Added docstrings to new functions/classes
• Updated README if needed
• Updated CHANGELOG if needed

Screenshots (if applicable)

Checklist

• My code follows the project's style guidelines
• I have performed a self-review of my code
• I have commented my code, particularly in hard-to-understand areas
• I have made corresponding changes to the documentation
• My changes generate no new warnings
• I have added tests that prove my fix is effective or that my feature works
• New and existing unit tests pass locally with my changes
• Any dependent changes have been merged and published

Additional Notes

This pull request introduces several documentation improvements and new developer guides to clarify architectural concepts, agent lifecycle management, and frontend-backend integration. The changes expand on how to extend and operate the system, including new features for agent lifecycle hooks, dynamic agent composition, and progress reporting.

Key documentation and architecture updates:

Developer & Operator Documentation

• Added a comprehensive WARP.md guide for developers using WARP, detailing the stack, common commands, architecture, and extension points for both backend and frontend.
• Updated the root README.md to remove the architecture banner image and minor formatting adjustments. [1] [2]
• Added a schema directive to config/workflows.yaml for better YAML validation tooling support.

Architecture & Extensibility

• Expanded the architecture blueprint (docs/Project_Architecture_Blueprint.md) to document the new ProgressEmitter interface for pluggable progress reporting, including example usage and integration points in the orchestration layer. [1] [2] [3] [4]
• Clarified the use of Pydantic models for workflow config validation and improved documentation around error handling, validation, and OpenTelemetry integration. [1] [2]

Agent Lifecycle & Extension

• Added a new section to docs/AGENTS.md describing agent lifecycle hooks (warmup() and teardown()), including a code example for managing stateful resources within agents.

API & Frontend Integration

• Updated the frontend-backend integration guide to document dynamic agent composition via the agents parameter in chat requests, and described new SSE event types for incremental reasoning updates (reasoning.delta, reasoning.completed). [1] [2]
• Clarified streaming feature flags and their effect on event emission and frontend behavior.
• Fixed a reference in the API developer guide to the correct health check route file.

[github-actions]

🤖 Hi @Zochory, I've received your request, and I'm working on it now! You can track my progress in the logs for more details.

[coderabbitai]

Important

Review skipped

Auto reviews are disabled on base/target branches other than the default branch.

Please check the settings in the CodeRabbit UI or the .coderabbit.yaml file in this repository. To trigger a single review, invoke the @coderabbitai review command.

You can disable this status message by setting the reviews.review_status to false in the CodeRabbit configuration file.

Note

Other AI code review bot(s) detected

CodeRabbit has detected other AI code review bot(s) in this pull request and will avoid duplicating their findings in the review comments. This may lead to a less comprehensive review.

✨ Finishing touches

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Post copyable unit tests in a comment
• Commit unit tests in branch experimental

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

_{Comment @coderabbitai help to get the list of available commands and usage tips.}

[Copilot]

Pull Request Overview

This pull request introduces significant improvements to documentation, project architecture, and extensibility for the AgenticFleet system. It focuses on enhancing developer experience through comprehensive guides, introducing agent lifecycle hooks, adding caching and checkpointing capabilities, and modernizing the codebase with typed configurations.

Key Changes:

• Added WARP.md developer onboarding guide with comprehensive workflow documentation
• Introduced agent lifecycle hooks (warmup() and teardown()) via the AgentLifecycle protocol
• Implemented Redis-based caching with LangCache integration for workflow responses
• Added workflow checkpointing support via WorkflowCheckpointService
• Migrated from dataclass to Pydantic models for workflow configuration validation
• Introduced OpenTelemetry integration for observability
• Enhanced frontend with conversation sidebar, message history loading, and SSE stream cancellation
• Added health check endpoints with framework version validation

Reviewed Changes

Copilot reviewed 78 out of 81 changed files in this pull request and generated 2 comments.

Show a summary per file

File	Description
tests/validate_test_improvements.py	Updated test execution to use asyncio.run(), added type ignores, improved mock safety checks, and converted timestamps to datetime objects
tests/test_workflow_factory.py	Added WorkflowConfig import, helper function for YAML writing, and serialization round-trip test
tests/test_response_aggregator.py	Refactored to test reasoning delta streaming with simplified helper functions and event parsing
tests/test_framework_health.py	New comprehensive test suite for framework health checks and package version validation
tests/test_event_bridge.py	Added test for AgentRunUpdateEvent reasoning delta conversion
tests/test_agent_lifecycle.py	New test suite for agent lifecycle hooks (warmup/teardown) with async support
src/frontend/	Added conversation management, sidebar UI, message history loading, and stream cancellation
src/agentic_fleet/workflow/magentic_workflow.py	Extensive refactoring with caching, checkpointing, telemetry, and structured request handling
src/agentic_fleet/workflow/events.py	Added reasoning delta event conversion and backward compatibility stubs
src/agentic_fleet/utils/telemetry.py	New optional OpenTelemetry integration module
src/agentic_fleet/utils/redis_cache.py	New Redis cache manager with LangCache integration
src/agentic_fleet/models/workflow_config.py	New Pydantic models replacing dataclasses for typed configuration
src/agentic_fleet/agents/coordinator.py	Added lifecycle hook execution with async/sync support
src/agentic_fleet/agents/base.py	New AgentLifecycle protocol definition
src/agentic_fleet/api/routers/health.py	New health check endpoints with Redis rate limiting
src/agentic_fleet/framework/health.py	New framework health validation with package version checks
Documentation files	Comprehensive updates to architecture, configuration, and API integration guides

[Copilot]

Unused variable state.

[Zochory]

@copilot code review

[Copilot]

@Zochory I've opened a new pull request, #347, to work on those changes. Once the pull request is ready, I'll request review from you.