Skip to main content

Task Breakdown: .works/works.yml Source-Controlled Work Configuration

Feature ID: works-config Plan: ./plan.md Status: Done (Retrospective — feature shipped via PR #395) Last updated: 2026-05-01

This is a retrospective task list — every task below has already shipped. It is preserved as the audit trail for the feature and as a template for similar future work.

Phase 1 — Service layer​

  • T1. WorksConfigService with loadFromRepository (multi-path fallback) and parse (alias-aware).
  • T2. WorksConfigWriterService with writeToDataRepository and raw-field preservation.
  • T3. WorksConfigImportPlannerService for pre-import dry-run validation.
  • T4. WorksConfigImportApplierService for atomic application of parsed config to the work entity.
  • T5. WorksConfigRestoreService for re-reading the file when the user requests a config refresh.

Phase 2 — Tests​

  • T6. works-config-data.spec.ts — mergeWorksConfigIntoDataConfig covering metadata enrichment.
  • T7. works-config.service.spec.ts — parse / load / repository-reference parsing / cadence normalization.
  • T8. works-config-writer.service.spec.ts — round-trip preservation, field clearing, schedule object emission.
  • T9. works-config-import-planner.service.spec.ts — plugin id validation, error cases.

Phase 3 — Integration​

  • T10. Import flow reads .works/works.yml and pre-fills the import form.
  • T11. Work generation pipeline calls the writer at the end of a successful run.
  • T12. Activity log entries cover parse failures, plugin-id failures, and sync failures.

Phase 4 — Docs​

  • T13. User-facing doc at docs/features/works-config.md.
  • T14. Cross-link from docs/features/index.md and the sidebar.
  • T15. Retrospective Spec Kit spec/plan/tasks (this work).

Definition of Done​

  • All tasks shipped.
  • Tests pass in CI.
  • User-facing doc present and linked.
  • Retrospective spec/plan/tasks present and reviewed.
  • Constitution gates verified — see spec.md §9.