elsa-core/specs/001-shell-reload-api/tasks.md

Tasks: Shell Reload API Endpoints

Input: Design documents from /specs/001-shell-reload-api/ Prerequisites: plan.md (required), spec.md (required for user stories), research.md, data-model.md, contracts/, quickstart.md

Tests: Tests are required for this feature by the repository constitution, so each user story includes component-test coverage.

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

Phase 1: Setup (Shared Infrastructure)

Purpose: Add the minimum project references and client resource scaffolding required by the feature.

• T001 Update src/modules/Elsa.Workflows.Api/Elsa.Workflows.Api.csproj to reference the CShells package needed for IShellManager, IShellSettingsProvider, and IShellSettingsCache
• T002 [P] Create the shell API client contract scaffold in src/clients/Elsa.Api.Client/Resources/Shells/Contracts/IShellsApi.cs

---

Phase 2: Foundational (Blocking Prerequisites)

Purpose: Establish shared orchestration infrastructure and shared non-endpoint result types used by all shell reload stories.

⚠️ CRITICAL: No user story work can begin until this phase is complete

• T003 Create shared orchestration result contracts in src/modules/Elsa.Workflows.Api/Contracts/ShellReloadStatus.cs, src/modules/Elsa.Workflows.Api/Contracts/ShellReloadItemResult.cs, and src/modules/Elsa.Workflows.Api/Contracts/ShellReloadResult.cs
• T004 [P] Create shared client-side reload DTOs in src/clients/Elsa.Api.Client/Resources/Shells/Models/ShellReloadItemResult.cs, src/clients/Elsa.Api.Client/Resources/Shells/Models/ShellReloadStatus.cs, and src/clients/Elsa.Api.Client/Resources/Shells/Responses/ShellReloadResponse.cs
• T005 Create the reload orchestration contract and base implementation in src/modules/Elsa.Workflows.Api/Contracts/IShellReloadOrchestrator.cs and src/modules/Elsa.Workflows.Api/Services/ShellReloadOrchestrator.cs
• T006 Register the shell reload orchestrator in src/modules/Elsa.Workflows.Api/ShellFeatures/WorkflowsApiFeature.cs

Checkpoint: Shared DTOs and orchestration infrastructure are ready for story implementation.

---

Phase 3: User Story 1 - Reload all shells after configuration changes (Priority: P1) 🎯 MVP

Goal: Let operators trigger a full shell reload and receive detailed per-shell results.

Independent Test: Change shell configuration for one or more shells, call the reload-all endpoint, and verify the updated behavior is active without restarting the host.

Tests for User Story 1

• T007 [P] [US1] Add component tests for successful full-shell reload results in test/component/Elsa.Workflows.ComponentTests/Scenarios/RestApis/Endpoints/Shells/ReloadAllTests.cs

Implementation for User Story 1

• T008 [US1] Implement full-reload snapshotting and successful per-shell result mapping around the current full-reload fallback in src/modules/Elsa.Workflows.Api/Services/ShellReloadOrchestrator.cs
• T009 [P] [US1] Implement the reload-all endpoint and collocated response handling in src/modules/Elsa.Workflows.Api/Endpoints/Shells/ReloadAll/Endpoint.cs and src/modules/Elsa.Workflows.Api/Endpoints/Shells/ReloadAll/Models.cs
• T010 [P] [US1] Add the reload-all client method to src/clients/Elsa.Api.Client/Resources/Shells/Contracts/IShellsApi.cs

Checkpoint: User Story 1 is independently functional through the API and client surface.

---

Phase 4: User Story 2 - Request reload for one shell (Priority: P2)

Goal: Expose a targeted shell reload endpoint that validates the shell ID and enforces requested-shell strict success semantics while still using the current full-reload fallback.

Independent Test: Call the targeted reload endpoint for a known shell and verify the requested shell refreshes; call it for an unknown shell and verify a not-found outcome.

Tests for User Story 2

• T011 [P] [US2] Add component tests for targeted reload success, unknown shell handling, and requested-shell strict outcomes in test/component/Elsa.Workflows.ComponentTests/Scenarios/RestApis/Endpoints/Shells/ReloadTests.cs

Implementation for User Story 2

• T012 [US2] Extend targeted reload validation and requested-shell strict result handling in src/modules/Elsa.Workflows.Api/Services/ShellReloadOrchestrator.cs
• T013 [P] [US2] Implement the targeted reload endpoint and collocated models in src/modules/Elsa.Workflows.Api/Endpoints/Shells/Reload/Endpoint.cs and src/modules/Elsa.Workflows.Api/Endpoints/Shells/Reload/Models.cs
• T014 [P] [US2] Add the targeted reload client method to src/clients/Elsa.Api.Client/Resources/Shells/Contracts/IShellsApi.cs

Checkpoint: User Story 2 works independently for known and unknown shell IDs.

---

Phase 5: User Story 3 - Handle failed reload attempts safely (Priority: P3)

Goal: Return clear busy, unavailable, and partial-success outcomes without falsely reporting that shells refreshed.

Independent Test: Simulate concurrent reloads, unavailable shell settings, and invalid configuration for one shell, then verify the API returns the required error or partial-success responses with shell-level detail.

Tests for User Story 3

• T015 [P] [US3] Add component tests for busy rejection, unavailable configuration, and partial-success reload behavior in test/component/Elsa.Workflows.ComponentTests/Scenarios/RestApis/Endpoints/Shells/ShellReloadFailureTests.cs

Implementation for User Story 3

• T016 [US3] Implement busy-state rejection and provider-unavailable failure handling in src/modules/Elsa.Workflows.Api/Services/ShellReloadOrchestrator.cs
• T017 [US3] Implement partial-success reconciliation for invalid shell configurations in src/modules/Elsa.Workflows.Api/Services/ShellReloadOrchestrator.cs
• T018 [US3] Map busy, partial-success, requested-shell failure, and provider-failure outcomes to HTTP responses in src/modules/Elsa.Workflows.Api/Endpoints/Shells/ReloadAll/Endpoint.cs and src/modules/Elsa.Workflows.Api/Endpoints/Shells/Reload/Endpoint.cs

Checkpoint: All failure and partial-success behaviors are independently testable through the API.

---

Phase 6: Polish & Cross-Cutting Concerns

Purpose: Bring implementation, client surface, and planning artifacts into final alignment.

• T019 [P] Update specs/001-shell-reload-api/contracts/shell-reload-api.yaml to match the final implemented routes, statuses, and response payloads
• T020 Run the quickstart validation against specs/001-shell-reload-api/quickstart.md using test/component/Elsa.Workflows.ComponentTests/Elsa.Workflows.ComponentTests.csproj and fix any mismatches in src/modules/Elsa.Workflows.Api/Endpoints/Shells/ and src/clients/Elsa.Api.Client/Resources/Shells/

---

Dependencies & Execution Order

Phase Dependencies

• Setup (Phase 1): No dependencies; start immediately.
• Foundational (Phase 2): Depends on Phase 1; blocks all user story work.
• User Story 1 (Phase 3): Depends on Phase 2 only.
• User Story 2 (Phase 4): Depends on Phase 2 only.
• User Story 3 (Phase 5): Depends on Phase 2 only.
• Polish (Phase 6): Depends on the user stories you intend to ship.

User Story Dependencies

• US1: No dependency on other user stories; this is the MVP.
• US2: No functional dependency on US1, but it reuses the shared orchestrator and response models from Phase 2.
• US3: No functional dependency on US1 or US2, but it extends the same orchestrator and endpoint files, so coordinate file ownership if multiple developers work in parallel.

Within Each User Story

• Write the component tests first and confirm they fail before implementation.
• Implement orchestration logic before endpoint wiring.
• Add API client methods after the corresponding endpoint contract is stable.
• Validate the story through the hosted component-test server before moving on.

Parallel Opportunities

• T002 can run in parallel with T001.
• T004 can run in parallel with T003 once Phase 1 is complete.
• T007, T009, and T010 can proceed in parallel after T008 starts stabilizing the shared orchestration shape.
• T011, T013, and T014 can proceed in parallel after T012 defines the targeted behavior.
• T015 can run in parallel with T016 because tests are in a separate file.
• T019 can run in parallel with final cleanup before T020.

---

Parallel Example: User Story 1

# After T008 defines the US1 orchestration behavior:
Task: "Add component tests for successful full-shell reload results in test/component/Elsa.Workflows.ComponentTests/Scenarios/RestApis/Endpoints/Shells/ReloadAllTests.cs"
Task: "Implement the reload-all endpoint and collocated response handling in src/modules/Elsa.Workflows.Api/Endpoints/Shells/ReloadAll/Endpoint.cs and src/modules/Elsa.Workflows.Api/Endpoints/Shells/ReloadAll/Models.cs"
Task: "Add the reload-all client method to src/clients/Elsa.Api.Client/Resources/Shells/Contracts/IShellsApi.cs"

---

Implementation Strategy

MVP First (User Story 1 Only)

1. Complete Phase 1: Setup.
2. Complete Phase 2: Foundational.
3. Complete Phase 3: User Story 1.
4. Validate the reload-all endpoint and client flow with the component tests.

Incremental Delivery

1. Deliver US1 to provide immediate operational value.
2. Add US2 so automation can target one shell explicitly while still using the full-reload fallback.
3. Add US3 to complete the failure-handling and partial-success contract.
4. Finish with Phase 6 to ensure the generated contract and quickstart remain accurate.

Parallel Team Strategy

1. One developer completes Phase 1 and Phase 2.
2. Then split work by story, with coordination around src/modules/Elsa.Workflows.Api/Services/ShellReloadOrchestrator.cs and src/clients/Elsa.Api.Client/Resources/Shells/Contracts/IShellsApi.cs because those files are shared touchpoints.
3. Rejoin for Phase 6 validation and contract alignment.

---

Notes

• [P] tasks are limited to work that can proceed without editing the same files concurrently.
• Story labels map directly to the prioritized stories in spec.md.
• The task list assumes the design decision to keep this feature inside Elsa.Workflows.Api, Elsa.Api.Client, and Elsa.Workflows.ComponentTests.
• T020 is the final verification checkpoint before handing the feature off for implementation completion.