Agents App - Features & Capabilities Report

Template Version: 1.0.0 Generated: 2026-01-22 Package: @epicdm/flowstate-app-agents App ID: agents

Table of Contents

1. Overview
2. App Identity
3. Feature Categories
4. Capabilities
5. Data Models
6. User Workflows
7. Integration Points
8. Architecture Summary
9. Quality & Compliance

Overview

Purpose

The Agents App provides autonomous agent and task approval management for AI-driven workflows. It enables users to orchestrate AI agents, manage automated task execution, review agent outputs through approval workflows, monitor worker status, and track execution logs across codebases.

Target Users

Value Proposition

• Autonomous Task Execution: Agents execute spec-driven tasks automatically
• Human-in-the-Loop Approvals: Review and approve agent outputs before finalization
• Worker Management: Monitor agent health, activity, and performance metrics
• Codebase Organization: Organize work by workspace and codebase
• Execution Transparency: Comprehensive logging with filtering and search
• Conversation Support: Threaded discussions for human-agent collaboration

App Identity

Entry Points

Feature Categories

Category 1: Dashboard & Metrics

Central dashboard with real-time agent metrics

Feature: Dashboard Overview

Description: Main dashboard displaying key metrics including active workers, task queue size, pending approvals, and 24-hour success rate.

User Story: As an AI engineer, I want to see a dashboard so that I can quickly understand the state of my agent fleet.

Acceptance Criteria:

• [x] Display active worker count
• [x] Show task queue length
• [x] Display pending approvals count
• [x] Calculate and show 24-hour success rate
• [x] Activity feed from recent logs
• [x] Quick task creation action

Implementation:

Routes:

• /dashboard - Main dashboard (default route)

Category 2: Task Management

Agent task creation, execution tracking, and status management

Feature: Task List & Filtering

Description: Comprehensive task list with status filtering, execution status filtering, multi-field sorting, and hierarchical task display with navigation controls.

User Story: As a developer, I want to view and filter agent tasks so that I can track work progress.

Acceptance Criteria:

• [x] Status filtering (all, pending, in-progress, completed)
• [x] Execution status filtering (all, success, failure, in-progress)
• [x] Sorting by updatedAt, createdAt, title, status
• [x] Hierarchical rendering with indentation
• [x] Navigation controls (top, bottom, next task)
• [x] Real-time updates via reactive queries
• [x] Loading skeleton and empty states

Implementation:

Routes:

• /tasks - Task list
• /tasks/:taskId - Task detail

Feature: Task Detail View

Description: Detailed task view with tabbed navigation for overview, conversation history, approvals, and metadata. Includes agent assignment, execution timing, and conversation response capabilities.

User Story: As a developer, I want to view task details so that I can understand task status and respond to agent queries.

Acceptance Criteria:

• [x] Task header with status and timing
• [x] Tabbed navigation (Overview, Conversation, Approvals, Metadata)
• [x] Execution output display
• [x] Conversation history from discussions
• [x] Response input for human-agent collaboration
• [x] Task status updates

Implementation:

Feature: Task Creation

Description: Dialog-based task creation with title, description, and navigation to created task.

User Story: As a developer, I want to create tasks so that I can assign work to agents.

Acceptance Criteria:

• [x] Modal dialog for task creation
• [x] Form validation
• [x] Navigation to created task
• [x] Available from dashboard and tasks page

Implementation:

Category 3: Approval Workflow

Human-in-the-loop approval for agent outputs

Feature: Approval List

Description: Table-based approval list with status badges, color coding, click-to-open dialog, and approval summary statistics.

User Story: As a project manager, I want to view pending approvals so that I can review and approve agent work.

Acceptance Criteria:

• [x] Status badges with color coding (pending, approved, rejected, needs-revision)
• [x] Responsive table layout
• [x] Click-to-open dialog for pending approvals
• [x] Approval counts summary
• [x] Loading and empty states

Implementation:

Routes:

• /approvals - Approvals list

Feature: Approval Actions

Description: Modal dialog for reviewing and taking action on approvals (approve, reject, request revision) with optional comments.

User Story: As a reviewer, I want to approve or reject agent outputs so that I can ensure quality.

Acceptance Criteria:

• [x] Approve with optional comments
• [x] Reject with optional comments
• [x] Request revision with feedback
• [x] Status change notifications

Implementation:

Category 4: Worker Management

Monitor and manage autonomous workers/agents

Feature: Worker Overview

Description: Overview dashboard showing total workers, active workers, active tasks, and completed tasks with aggregated statistics.

User Story: As an operations engineer, I want to see worker status so that I can monitor agent health.

Acceptance Criteria:

• [x] Total workers count
• [x] Active workers count (activity < 5 min)
• [x] Active tasks count
• [x] Completed tasks count
• [x] Statistics grid layout

Implementation:

Routes:

• /workers - Worker management

Feature: Worker Cards

Description: Individual worker cards showing status (Active/Idle/Inactive), active tasks, completed tasks, failed tasks, success rate, last activity, and log viewing.

User Story: As an AI engineer, I want to see individual worker stats so that I can identify performance issues.

Acceptance Criteria:

• [x] Status determination based on last activity
• [x] Task statistics per worker
• [x] Success rate calculation
• [x] Last activity timestamp
• [x] View logs action
• [x] Sorted by active status and last activity

Implementation:

Category 5: Codebase Management

Organize codebases within workspaces

Feature: Codebase List

Description: Workspace-scoped codebase listing with status badges, descriptions, and navigation to codebase details.

User Story: As a developer, I want to view codebases so that I can organize agent work by repository.

Acceptance Criteria:

• [x] Filter by current workspace
• [x] Status badges (active/inactive)
• [x] Codebase description display
• [x] Navigation to detail view
• [x] Create new codebase action

Implementation:

Routes:

• /codebases - Codebase list
• /codebases/new - Create codebase
• /codebases/:id - Codebase detail

Feature: Codebase Detail

Description: Detailed codebase view with metadata, editing capabilities, and associated information.

User Story: As a developer, I want to view codebase details so that I can manage repository configuration.

Acceptance Criteria:

• [x] Display codebase metadata
• [x] Edit codebase details
• [x] Status display
• [x] Created/updated timestamps

Implementation:

Category 6: Logging & Monitoring

Comprehensive execution logging with filtering

Feature: Log Viewer

Description: Log viewer with level filtering, category filtering, search, expandable details, and color-coded severity levels.

User Story: As an operations engineer, I want to view execution logs so that I can debug issues.

Acceptance Criteria:

• [x] Filter by level (debug, info, warn, error, critical)
• [x] Filter by category
• [x] Search by message content
• [x] Expandable log details
• [x] Metadata display (command, exit code, duration, error)
• [x] Color-coded severity levels
• [x] Relative timestamps

Implementation:

Routes:

• /logs - Logs viewer

Category 7: Spec Workflow Support

Spec-driven development workflow

Feature: Spec Management

Description: Support for spec-driven workflow with phases (requirements, design, tasks, implementation), milestone timeline, and phase documents.

User Story: As a developer, I want to manage specs so that I can follow structured development workflows.

Acceptance Criteria:

• [x] Spec list view
• [x] Spec detail view
• [x] Phase document management
• [x] Milestone timeline display
• [x] Markdown editor for documents

Implementation:

Capabilities

Core Capabilities

Technical Capabilities

Integration Capabilities

Data Models

Collections Used

Entity Relationships

Workspace
    |
    +-- Codebases (hasMany)
            |
            +-- Specs (hasMany, via categoryId)
                    |
                    +-- Milestones (hasMany)
                    |       |
                    |       +-- Tasks (hasMany)
                    |               |
                    |               +-- Discussions (hasMany)
                    |               |
                    |               +-- Logs (hasMany)
                    |
                    +-- Approvals (hasMany)

Task
    |
    +-- Subtasks (hasMany, via parentTaskId)
    |
    +-- TimeEntries (hasMany)
    |
    +-- Worker (belongsTo, via metadata.assignedAgent)

Key Data Flows

User Action --> Component --> Hook --> RxDB Collection --> UI Update
                                  |
                                  +--> Service (complex logic)
                                  |
                                  +--> Replication --> Server

Agent Execution:
Task Created --> Orchestrator Picks Up --> Agent Executes -->
    --> Logs Created --> Status Updated --> Approval Created (if needed)

User Workflows

Workflow 1: Task Execution Monitoring

Monitor agent task execution

Trigger: Navigate to Tasks page

Steps:

Success Outcome: Task status tracked, human input provided Failure Handling: Logs available for debugging

Workflow 2: Approval Review

Review and approve agent outputs

Trigger: Pending approval notification

Steps:

Success Outcome: Approval processed, workflow continues Failure Handling: Revision requested with feedback

Workflow 3: Worker Health Check

Monitor worker status and health

Trigger: Navigate to Workers page

Steps:

Success Outcome: Worker health verified Failure Handling: Inactive workers identified

State Transitions

Task Status States

+----------+     +--------------+     +----------+
|  To Do   |---->| In Progress  |---->| Complete |
+----------+     +--------------+     +----------+
     |                  |
     v                  v
+----------+     +--------------+
| On Hold  |<--->|   Blocked    |
+----------+     +--------------+

Approval Status States

+----------+     +----------+
| Pending  |---->| Approved |
+----------+     +----------+
     |
     +---------->+----------+
     |           | Rejected |
     |           +----------+
     |
     +---------->+----------------+
                 | Needs Revision |
                 +----------------+

Integration Points

Internal Integrations

External Integrations

MCP Integration

Architecture Summary

Directory Structure

src/
+-- components/          # UI components (25+ files)
|   +-- codebases/      # Codebase components
|   +-- variables/      # Variable components
|   +-- ActivityFeed.tsx
|   +-- AgentSelector.tsx
|   +-- AgentTaskItem.tsx
|   +-- AgentTaskList.tsx
|   +-- ApprovalDialog.tsx
|   +-- ApprovalList.tsx
|   +-- DashboardStats.tsx
|   +-- ErrorBoundary.tsx
|   +-- Header.tsx
|   +-- LogViewer.tsx
|   +-- MarkdownEditor.tsx
|   +-- MarkdownRenderer.tsx
|   +-- MilestoneTimeline.tsx
|   +-- NewTaskDialog.tsx
|   +-- PhaseDocuments.tsx
|   +-- Sidebar.tsx
|   +-- SpecCard.tsx
|   +-- SpecDetailView.tsx
|   +-- SpecListView.tsx
|   +-- TaskList.tsx
|   +-- WorkerManagement.tsx
+-- hooks/              # Custom React hooks (10 hooks)
|   +-- useTaskDiscussions.ts
|   +-- useWorkflowApprovals.ts
|   +-- useWorkflowCodebases.ts
|   +-- useWorkflowLogs.ts
|   +-- useWorkflowMilestones.ts
|   +-- useWorkflowSpecs.ts
|   +-- useWorkflowTasks.ts
|   +-- useWorkflowVariables.ts
|   +-- useWorkflowWorkspaces.ts
+-- pages/              # Page components (11 pages)
+-- types/              # TypeScript definitions
+-- db/                 # Database configuration
+-- lib/                # Utility libraries

Key Architectural Patterns

Hooks Overview

Quality & Compliance

Test Coverage

Accessibility

Security Considerations

FlowState Alignment

Spec-Driven Development

This app follows the FlowState Standard for spec-driven development:

• Requirements: .flowstate/specs/{{feature-name}}/requirements.md
• Design: .flowstate/specs/{{feature-name}}/design.md
• Wireframes: .flowstate/specs/{{feature-name}}/wireframes.html
• Tasks: .flowstate/specs/{{feature-name}}/tasks.md

Quality Gates

Appendix

Related Documentation

Version History