Skip to main content

Task Breakdown: Advanced Prompts

Feature ID: advanced-prompts Plan: ./plan.md Status: Done (Retrospective) Last updated: 2026-05-02

Phase 1 — Schema & contracts​

  • T1. WorkAdvancedPrompts entity at packages/agent/src/entities/work-advanced-prompts.entity.ts
    • All 7 prompt fields as text NULL; one-to-one with Work with cascade delete.
    • Export from packages/agent/src/entities/index.ts.
  • T2. Migration adding work_advanced_prompts table with unique index on workId. Additive only.
  • T3 (parallel with T2). DTO UpdateWorkAdvancedPromptsDto at packages/agent/src/dto/work-advanced-prompts.dto.ts with @IsOptional() @IsString() @MaxLength(2000) and sanitizeString Transform per field.
  • T4. Response interface WorkAdvancedPromptsResponseDto mirroring the entity with timestamps as ISO strings.

Phase 2 — Repository​

  • T5. WorkAdvancedPromptsRepository at packages/agent/src/database/repositories/work-advanced-prompts.repository.ts
    • findByWorkId(id) → entity | null
    • createOrUpdate(id, fields) → entity (upsert)
    • delete(id) → void
    • Tests: …repository.spec.ts with in-memory dataset.

Phase 3 — Service​

  • T6. WorkAdvancedPromptsService at packages/agent/src/services/work-advanced-prompts.service.ts
    • getAdvancedPrompts(workId) → response | null
    • updateAdvancedPrompts(workId, userId, dto) → response with editor-role check
    • getPromptsForGeneration(workId) → AdvancedPromptsContext returning a fully-populated context object (null fields preserved)
    • Tests: …service.spec.ts with mocked repository + role checker.
  • T7. Wire into the work module so the service is injectable from the API controller and from the items generator.

Phase 4 — Pipeline integration​

  • T8. appendCustomPrompt(base, custom?) → string utility at packages/agent/src/items-generator/utils/prompt.util.ts.
    • Empty/null/whitespace-only custom returns base unchanged.
    • Non-empty custom is trimmed and appended after the ## Additional User Instructions: header.
    • Tests cover: null, undefined, empty string, whitespace-only, and a normal multi-line prompt.
  • T9. Add advancedPrompts?: AdvancedPromptsContext | null to GenerationContext in packages/agent/src/items-generator/interfaces/pipeline.interface.ts.
  • T10. Load advanced prompts in ItemsGeneratorService.generateItems() via getPromptsForGeneration(workId) and attach to context before the pipeline executor starts. Always reload fresh (do not restore from checkpoint).
  • T11. Wire each pipeline step to call appendCustomPrompt with its respective context field:
    • Step 4a AiItemGenerationService → itemGeneration
    • Step 4b SearchQueryGenerationService → searchQuery
    • Step 6 ContentFilteringService → relevanceAssessment
    • Step 7 ItemExtractionService → itemExtraction
    • Step 8 AiDeduplicator → deduplication
    • Step 9 CategoryProcessingService → categorization
    • Step 10 SourceValidationService → sourceValidation

Phase 5 — API surface​

  • T12. GET /api/works/:id/advanced-prompts controller method on apps/api/src/works/works.controller.ts.
  • T13. PUT /api/works/:id/advanced-prompts controller method with editor-role guard.
  • T14. Swagger @ApiOperation / @ApiResponse decorators for both endpoints.
  • T15. e2e tests in apps/api/test/ covering: viewer cannot update (403), editor can update (200), invalid (>2000 chars) returns 400, missing work returns 404.

Phase 6 — Web UI​

  • T16. API client at apps/web/src/lib/api/work.ts:
    • getAdvancedPrompts(id)
    • updateAdvancedPrompts(id, data)
  • T17. Server action updateAdvancedPrompts(workId, data) at apps/web/src/app/actions/dashboard/works.ts with Zod validation (max 2000 chars per field).
  • T18. AdvancedPromptsSettings component at apps/web/src/components/works/detail/settings/AdvancedPromptsSettings.tsx:
    • Collapsible section, collapsed by default
    • Lazy-load on first expand
    • 7 textareas with auto-resize and character counter
    • Single Save button with loading state
    • Toast on success / error
  • T19. Embed component in SettingsForm.tsx.
  • T20. Translations under dashboard.workDetail.settings.advancedPrompts.* in apps/web/messages/en.json and other locale files.

Phase 7 — Docs​

  • T21. User-facing doc docs/features/advanced-prompts.md with the per-prompt usage examples and customization tips.
  • T22. Cross-link from docs/features/index.md and apps/docs/sidebarsPlatform.ts.
  • T23. Retrospective spec / plan / tasks (this set).

Phase 8 — Quality gates​

  • T24. pnpm format && pnpm lint && pnpm test && pnpm build green.
  • T25. pnpm --filter ever-works-docs build produces no broken-link warnings.

Definition of Done​

  • All 7 prompt fields editable from the UI and respected at run time
  • Editor-only authorization on PUT, all roles can read on GET
  • Sanitisation + length cap enforced at the DTO layer
  • appendCustomPrompt covered by unit tests for empty / whitespace / normal cases
  • Per-step integration covered by unit tests and one e2e
  • Constitution gates in spec.md §9 confirmed satisfied