SemianiakaVY/elsa-core
1
0
Fork 0
Code Issues Pull requests Actions 1 Packages Projects Releases Wiki Activity
elsa-core/specs/012-weaver-grounding-tools/tasks.md
Sipke Schoorstra c66f9aed45
Add Weaver grounding tools 
Adds Spec Kit-backed Weaver grounding tools for activities, workflow definitions, workflow proposals, runtime instances, incidents, and Studio capability discovery.
2026-06-08 15:40:10 +02:00

11 KiB
Raw Blame History

Tasks: Weaver Grounding Tools

Input: Design documents from specs/012-weaver-grounding-tools/ Prerequisites: plan.md, spec.md, research.md, data-model.md, contracts/

Tests: New grounding code must include unit and integration coverage.

Organization: Tasks are grouped by user story to enable independent implementation and testing of each story.

Phase 1: Setup (Shared Infrastructure)

Purpose: Establish shared grounding DTOs, options, and registration surfaces.

  • T001 Add grounding DTO records in src/modules/Elsa.AI.Abstractions/Models/AIGroundingModels.cs.
  • T002 Add grounding result size and paging options in src/modules/Elsa.AI.Host/Options/AIHostOptions.cs.
  • T003 [P] Add grounding tool registration extension helpers in src/modules/Elsa.AI.Host/Features/AIFeature.cs.
  • T004 [P] Update AI capability response models in src/modules/Elsa.AI.Host/Endpoints/AI/Capabilities/Endpoint.cs.

Phase 2: Foundational (Blocking Prerequisites)

Purpose: Shared services that all grounding tool families need.

  • T005 Add redaction and size-clamping helpers for grounding payloads in src/modules/Elsa.AI.Host/Services/AIGroundingResultFormatter.cs.
  • T006 Add model-safe activity descriptor mapping service in src/modules/Elsa.AI.Host/Services/ActivityGroundingMapper.cs.
  • T007 Add model-safe workflow graph mapping service in src/modules/Elsa.AI.Host/Services/WorkflowGroundingMapper.cs.
  • T008 Add model-safe runtime instance mapping service in src/modules/Elsa.AI.Host/Services/RuntimeGroundingMapper.cs.
  • T009 Register grounding services and built-in tools in src/modules/Elsa.AI.Host/Extensions/ServiceCollectionExtensions.cs.
  • T010 [P] Add unit tests for result formatting and redaction in test/unit/Elsa.AI.Host.UnitTests/Grounding/AIGroundingResultFormatterTests.cs.
  • T011 [P] Add unit tests for capability descriptor composition in test/unit/Elsa.AI.Host.UnitTests/Grounding/AIGroundingCapabilityTests.cs.

Checkpoint: Shared grounding services are available and tested.

Phase 3: User Story 1 - Discover available activities (Priority: P1) MVP

Goal: Let Weaver search and inspect installed Activity Registry metadata.

Independent Test: Search installed activities by capability and get one descriptor without using workflow or runtime tools.

Tests for User Story 1

  • T012 [P] [US1] Add unit tests for activity descriptor mapping in test/unit/Elsa.AI.Host.UnitTests/Grounding/ActivityGroundingMapperTests.cs.
  • T013 [P] [US1] Add integration tests for activities.search and activities.getDescriptor in test/integration/Elsa.AI.IntegrationTests/AIActivityGroundingToolTests.cs.

Implementation for User Story 1

  • T014 [US1] Implement activities.search tool in src/modules/Elsa.AI.Host/Tools/Activities/ActivitiesSearchTool.cs.
  • T015 [US1] Implement activities.getDescriptor tool in src/modules/Elsa.AI.Host/Tools/Activities/ActivityDescriptorTool.cs.
  • T016 [US1] Add activity search filtering by query, category, type, version, input, output, and trigger behavior in src/modules/Elsa.AI.Host/Services/ActivityGroundingSearchService.cs.
  • T017 [US1] Expose activity grounding capability metadata in src/modules/Elsa.AI.Host/Endpoints/AI/Capabilities/Endpoint.cs.
  • T018 [US1] Verify activity tools are listed by GET /ai/tools in test/integration/Elsa.AI.IntegrationTests/AIToolsEndpointTests.cs.

Checkpoint: Weaver can ground authoring in installed activities.

Phase 4: User Story 2 - Understand workflow definitions (Priority: P2)

Goal: Let Weaver search, retrieve, explain, and compare authorized workflow definitions.

Independent Test: Attach or search a workflow definition and ask for a graph summary without creating a proposal.

Tests for User Story 2

  • T019 [P] [US2] Add unit tests for workflow graph mapping in test/unit/Elsa.AI.Host.UnitTests/Grounding/WorkflowGroundingMapperTests.cs.
  • T020 [P] [US2] Add integration tests for workflow search/detail tools in test/integration/Elsa.AI.IntegrationTests/AIWorkflowGroundingToolTests.cs.

Implementation for User Story 2

  • T021 [US2] Implement workflows.search tool in src/modules/Elsa.AI.Host/Tools/Workflows/WorkflowsSearchTool.cs.
  • T022 [US2] Implement workflows.getDefinition tool in src/modules/Elsa.AI.Host/Tools/Workflows/WorkflowDefinitionTool.cs.
  • T023 [US2] Implement workflows.getDefinitionGraph tool in src/modules/Elsa.AI.Host/Tools/Workflows/WorkflowDefinitionGraphTool.cs.
  • T024 [US2] Implement workflows.findUsages tool in src/modules/Elsa.AI.Host/Tools/Workflows/WorkflowUsageSearchTool.cs.
  • T025 [US2] Extend WorkflowDefinitionContextProvider in src/modules/Elsa.AI.Host/Context/WorkflowDefinitionContextProvider.cs to use model-safe graph summaries.

Checkpoint: Weaver can explain and search workflows using authorized definition data.

Phase 5: User Story 3 - Create and update workflows safely (Priority: P3)

Goal: Let Weaver create or update workflow proposals using installed activity metadata and validation.

Independent Test: Ask Weaver to create or update a workflow and verify proposal-only output with diagnostics.

Tests for User Story 3

  • T026 [P] [US3] Add unit tests for draft validation against activity descriptors in test/unit/Elsa.AI.Host.UnitTests/Grounding/WorkflowDraftValidationTests.cs.
  • T027 [P] [US3] Add integration tests for proposal tools in test/integration/Elsa.AI.IntegrationTests/AIWorkflowProposalToolTests.cs.

Implementation for User Story 3

  • T028 [US3] Implement workflow draft validation service in src/modules/Elsa.AI.Host/Services/WorkflowDraftValidationService.cs.
  • T029 [US3] Implement workflows.validateDraft tool in src/modules/Elsa.AI.Host/Tools/Workflows/WorkflowValidateDraftTool.cs.
  • T030 [US3] Implement workflows.proposeCreate tool in src/modules/Elsa.AI.Host/Tools/Workflows/WorkflowProposeCreateTool.cs.
  • T031 [US3] Implement workflows.proposeUpdate tool in src/modules/Elsa.AI.Host/Tools/Workflows/WorkflowProposeUpdateTool.cs.
  • T032 [US3] Add proposal graph diff generation in src/modules/Elsa.AI.Host/Services/WorkflowProposalDiffService.cs.
  • T033 [US3] Add stale baseline checks for update proposals in src/modules/Elsa.AI.Host/Services/WorkflowDraftValidationService.cs.

Checkpoint: Weaver can produce governed workflow authoring proposals.

Phase 6: User Story 4 - Inspect runtime instances and incidents (Priority: P4)

Goal: Let Weaver inspect workflow instances and incidents with redacted runtime evidence.

Independent Test: Ask Weaver why a failed seeded instance failed and verify evidence-backed output.

Tests for User Story 4

  • T034 [P] [US4] Add unit tests for runtime grounding mapping in test/unit/Elsa.AI.Host.UnitTests/Grounding/RuntimeGroundingMapperTests.cs.
  • T035 [P] [US4] Add integration tests for instance and incident tools in test/integration/Elsa.AI.IntegrationTests/AIRuntimeGroundingToolTests.cs.

Implementation for User Story 4

  • T036 [US4] Implement instances.search tool in src/modules/Elsa.AI.Host/Tools/Runtime/InstancesSearchTool.cs.
  • T037 [US4] Implement instances.get tool in src/modules/Elsa.AI.Host/Tools/Runtime/WorkflowInstanceTool.cs.
  • T038 [US4] Implement instances.getExecutionHistory tool in src/modules/Elsa.AI.Host/Tools/Runtime/WorkflowInstanceExecutionHistoryTool.cs.
  • T039 [US4] Implement instances.getActivityState tool in src/modules/Elsa.AI.Host/Tools/Runtime/WorkflowInstanceActivityStateTool.cs.
  • T040 [US4] Implement incidents.search tool in src/modules/Elsa.AI.Host/Tools/Runtime/IncidentsSearchTool.cs.
  • T041 [US4] Implement incidents.get tool in src/modules/Elsa.AI.Host/Tools/Runtime/IncidentTool.cs.
  • T042 [US4] Extend WorkflowInstanceContextProvider in src/modules/Elsa.AI.Host/Context/WorkflowInstanceContextProvider.cs to include bounded incident and activity state summaries.

Checkpoint: Weaver can answer runtime inspection questions from authorized instance and incident data.

Phase 7: User Story 5 - Surface grounding capabilities to Studio (Priority: P5)

Goal: Let Studio discover and render available grounding features without provider-specific assumptions.

Independent Test: Call capabilities and tools endpoints and verify grounding families, attachment kinds, and unavailable states.

Tests for User Story 5

  • T043 [P] [US5] Extend capability endpoint tests in test/integration/Elsa.AI.IntegrationTests/AICapabilitiesEndpointTests.cs.
  • T044 [P] [US5] Extend chat stream tests for grounded tool result events in test/integration/Elsa.AI.IntegrationTests/AIChatEndpointTests.cs.

Implementation for User Story 5

  • T045 [US5] Add grounding capability response fields in src/modules/Elsa.AI.Host/Endpoints/AI/Capabilities/Endpoint.cs.
  • T046 [US5] Add supported attachment kinds for activity, workflow, runtime, diagnostics, and time range in src/modules/Elsa.AI.Abstractions/Models/AIContextAttachment.cs.
  • T047 [US5] Add disabled grounding capability reasons in src/modules/Elsa.AI.Host/Endpoints/AI/Capabilities/Endpoint.cs.

Checkpoint: Studio can discover Weaver grounding support and render UI affordances safely.

Phase 8: Polish & Cross-Cutting Concerns

Purpose: Documentation, safety review, and verification.

  • T048 [P] Add host README documentation for grounding tools in src/modules/Elsa.AI.Host/README.md.
  • T049 [P] Update Weaver quickstart references in specs/008-weaver-ai-copilot/quickstart.md.
  • T050 Run dotnet test test/unit/Elsa.AI.Host.UnitTests/Elsa.AI.Host.UnitTests.csproj.
  • T051 Run dotnet test test/integration/Elsa.AI.IntegrationTests/Elsa.AI.IntegrationTests.csproj.
  • T052 Run dotnet build Elsa.sln -m:1.

Dependencies & Execution Order

Phase Dependencies

  • Setup (Phase 1): No dependencies.
  • Foundational (Phase 2): Depends on Setup and blocks all user stories.
  • US1 Activity Discovery: First MVP story after Foundation.
  • US2 Workflow Understanding: Can start after Foundation; benefits from US1 for missing activity warnings.
  • US3 Workflow Proposals: Depends on US1 and US2.
  • US4 Runtime Inspection: Can start after Foundation and proceed independently of US3.
  • US5 Studio Capabilities: Can start after each tool family has capability metadata.
  • Polish: Depends on implemented target stories.

Parallel Opportunities

  • T003 and T004 can run in parallel.
  • T010 and T011 can run in parallel.
  • Test tasks within each user story can run in parallel with each other.
  • US2 and US4 can be implemented in parallel after Foundation.

Implementation Strategy

MVP First

  1. Complete Setup and Foundation.
  2. Complete US1 activity discovery.
  3. Validate that Weaver can search installed activities and answer activity questions.
  4. Add US2 workflow understanding.
  5. Add US3 proposal creation/update only after activity and workflow grounding are reliable.

Incremental Delivery

  1. Deliver activity grounding.
  2. Deliver workflow explanation/search.
  3. Deliver proposal validation and proposal creation/update.
  4. Deliver runtime inspection.
  5. Deliver Studio capability metadata for all enabled tool families.