tasks

Tasks: Markdown Documentation Editor (MDE)

Spec: spec.md | Plan: plan.md | Design: design-spec.md Created: 2025-11-27 | Updated: 2025-11-29 Epic: TP-XXXX-MDE | Initiative: TP-2141-Work-Management

Phase 1: Setup

T001 Install CodeMirror 6 dependencies: npm install codemirror @codemirror/lang-markdown @codemirror/view @codemirror/state @codemirror/theme-one-dark
T002 [P] Create TypeScript types for documentation editor in resources/js/types/documentation.d.ts
T003 [P] Create audit logs migration in database/migrations/2025_11_29_070408_create_documentation_audit_logs_table.php

Phase 2: Foundation (Backend Services)

T004 Add getRawContent(string $type, string $id): string method to domain/Documentation/Services/DocumentationService.php
T005 [P] Create DocumentationAuditService in domain/Documentation/Services/DocumentationAuditService.php with log(string $type, string $id, string $action, array $changes) method (DEFERRED - focus on editor first)
T006 Add updateDocument(string $type, string $id, string $content, array $metadata): bool method to domain/Documentation/Services/DocumentationService.php
T007 [P] Create UpdateDocumentRequest in domain/Documentation/Http/Requests/UpdateDocumentRequest.php with frontmatter schema validation per document type
T008 Add PUT route /documentation/{type}/{id} to domain/Documentation/Routes/documentationRoutes.php
T009 Add update(UpdateDocumentRequest $request, string $type, string $id) method to domain/Documentation/Http/Controllers/DocumentationController.php
T010 [P] Add GET route /api/documentation/{type}/{id}/raw to return raw markdown content

Phase 3: User Story 1 - Edit Existing Documentation (P1)

Goal: A user can click Edit on any document, modify content in a split-pane editor with live preview, and save changes. Test Criteria: Navigate to any document, click Edit, modify text, save, refresh page, verify changes persisted.

Frontend Components

T011 [US1] Create MarkdownEditor.vue in resources/js/Components/Documentation/Editor/MarkdownEditor.vue - CodeMirror 6 wrapper with syntax highlighting, line numbers, emit update:modelValue
T012 [P] [US1] Create MarkdownPreview.vue in resources/js/Components/Documentation/Editor/MarkdownPreview.vue - render markdown using marked library, match documentation viewer styling
T013 [US1] Create AutoSaveStatus.vue in resources/js/Components/Documentation/Editor/AutoSaveStatus.vue - display “Saved Xs ago”, “Saving…”, “Unsaved changes” states
T014 [US1] Create useDocumentDraft composable in resources/js/composables/useDocumentDraft.ts - localStorage draft management with 30s auto-save interval
T015 [US1] Create DocumentEditor.vue in resources/js/Components/Documentation/Editor/DocumentEditor.vue - split-pane layout (50/50) with MarkdownEditor + MarkdownPreview, header with Cancel/Save buttons, footer with AutoSaveStatus

Page Integration

T016 [US1] Add isEditing ref and Edit button to resources/js/Components/Documentation/DocumentationShowLayout.vue
T017 [US1] Modify resources/js/Pages/Documentation/Agents/Show.vue to toggle between view mode and DocumentEditor component
T018 [P] [US1] Modify resources/js/Pages/Documentation/Commands/Show.vue to toggle between view mode and DocumentEditor component
T019 [P] [US1] Modify resources/js/Pages/Documentation/Skills/Show.vue to toggle between view mode and DocumentEditor component
T020 [P] [US1] Modify resources/js/Pages/Documentation/MCP/Show.vue to toggle between view mode and DocumentEditor component

Save Flow

T021 [US1] Implement save handler in DocumentEditor.vue using Inertia form PUT to /documentation/{type}/{id}
T022 [US1] Add success toast notification on save using existing toast component (via flash messages)
T023 [US1] Add cancel confirmation dialog when unsaved changes exist

Phase 4: User Story 2 - Create New Documentation Files (P2)

Goal: A user can click “Create New” on any index page, fill in metadata, write content, and save a new document. Test Criteria: Navigate to Agents index, click Create New, fill name/description, save, verify new file exists and appears in listing.

Backend

T024 [US2] Add createDocument(string $type, string $name, string $content, array $metadata): string method to domain/Documentation/Services/DocumentationService.php - returns created file path
T025 [P] [US2] Add generateFilename(string $name): string helper method to DocumentationService - slugify name, ensure .md extension
T026 [P] [US2] Add checkFilenameExists(string $type, string $filename): bool method to DocumentationService
T027 [US2] Create StoreDocumentRequest in domain/Documentation/Http/Requests/StoreDocumentRequest.php with type-specific required field validation
T028 [US2] Add POST route /documentation/{type} to domain/Documentation/Routes/documentationRoutes.php
T029 [US2] Add store(StoreDocumentRequest $request, string $type) method to DocumentationController - create file and redirect to new document

Frontend

T030 [US2] Create CreateDocumentModal.vue in resources/js/Components/Documentation/CreateDocumentModal.vue - form with name, description fields, filename preview, document type passed as prop
T031 [US2] Add “Create New Agent” button to resources/js/Pages/Documentation/Agents/Index.vue that opens CreateDocumentModal
T032 [P] [US2] Add “Create New Command” button to resources/js/Pages/Documentation/Commands/Index.vue
T033 [P] [US2] Add “Create New Skill” button to resources/js/Pages/Documentation/Skills/Index.vue
T034 [US2] Implement form submission in CreateDocumentModal using Inertia form POST

Phase 5: User Story 3 - Manage Document Metadata (P2)

Goal: A user can expand a metadata panel while editing to update frontmatter fields through a structured form. Test Criteria: Edit an agent, expand metadata panel, change the model field, save, verify frontmatter in file updated correctly.

Frontend

T035 [US3] Create MetadataPanel.vue in resources/js/Components/Documentation/Editor/MetadataPanel.vue - collapsible panel with dynamic fields based on document type
T036 [US3] Define metadata field configurations per document type in resources/js/config/documentMetadataFields.ts
T037 [P] [US3] Create tools selector component for agent metadata (multi-select from available tools list)
T038 [P] [US3] Create model selector component for agent metadata (dropdown: sonnet, haiku, opus)
T039 [US3] Integrate MetadataPanel into DocumentEditor.vue - toggle visibility from footer, sync with editor content frontmatter
T040 [US3] Update save handler to merge metadata panel changes with editor content

Phase 6: User Story 4 - Navigate and Search Documents (P3)

Goal: A user can search across all documentation and filter by type to quickly find documents. Test Criteria: Type a search term in header, see matching documents from all types, filter to agents only, verify results narrow correctly.

Frontend

T041 [US4] Create useDocumentSearch composable in resources/js/composables/useDocumentSearch.ts - client-side filtering with debounce
T042 [US4] Create DocumentSearch.vue in resources/js/Components/Documentation/DocumentSearch.vue - search input with type filter chips, results dropdown
T043 [US4] Add DocumentSearch to documentation header/layout component
T044 [P] [US4] Add inline filter input to resources/js/Pages/Documentation/Agents/Index.vue
T045 [P] [US4] Add inline filter input to resources/js/Pages/Documentation/Commands/Index.vue

Phase 7: User Story 5 - Delete Documents (P3)

Goal: A user can delete a document with appropriate confirmation and warnings. Test Criteria: View a document, click Delete, see confirmation modal with document details, confirm, verify file removed and redirected to index.

Backend

T046 [US5] Add deleteDocument(string $type, string $id): bool method to domain/Documentation/Services/DocumentationService.php
T047 [P] [US5] Add getNestedContent(string $path): array method to check for files inside folders (for epic deletion)
T048 [US5] Add DELETE route /documentation/{type}/{id} to domain/Documentation/Routes/documentationRoutes.php
T049 [US5] Add destroy(string $type, string $id) method to DocumentationController - delete file and redirect to index

Frontend

T050 [US5] Create DeleteConfirmModal.vue in resources/js/Components/Documentation/DeleteConfirmModal.vue - show document details, warning message, nested content list if applicable
T051 [US5] Add Delete button to DocumentationShowLayout.vue (view mode only)
T052 [US5] Wire up delete confirmation flow with Inertia DELETE request

Phase 8: Concurrency Handling (P2)

Goal: Users see when someone else is editing and can choose to wait or proceed with warning. Test Criteria: User A opens document for edit, User B visits same document, User B sees “User A is editing” banner, User B can click “Edit Anyway”.

Backend

T053 Create DocumentationLockService in domain/Documentation/Services/DocumentationLockService.php with acquire(type, id, userId), release(type, id), check(type, id), refresh(type, id) methods using cache
T054 Add API route GET /api/documentation/{type}/{id}/lock to check lock status
T055 [P] Add API route POST /api/documentation/{type}/{id}/lock to acquire/refresh lock
T056 [P] Add API route DELETE /api/documentation/{type}/{id}/lock to release lock
T057 Create API controller methods for lock endpoints in new DocumentationLockController.php

Frontend

T058 Create useDocumentLock composable in resources/js/composables/useDocumentLock.ts - poll lock status, acquire on edit, release on close
T059 Create DocumentLockBanner.vue in resources/js/Components/Documentation/DocumentLockBanner.vue - “User X is editing” warning with timestamp
T060 Add DocumentLockBanner to DocumentationShowLayout.vue (show when locked by another user)
T061 Create “Edit Anyway” confirmation dialog with conflict warning
T062 Integrate lock acquisition into edit mode entry flow

Phase 9: Polish & Edge Cases

T063 Add keyboard shortcuts to DocumentEditor: Cmd/Ctrl+S (save), Esc (cancel with confirmation)
T064 [P] Add debounced preview updates for large documents (>50KB) in DocumentEditor.vue
T065 [P] Add mobile detection to DocumentationShowLayout - show “Edit on desktop” toast when Edit button tapped on mobile
T066 Add unsaved changes warning on browser back/navigation using Inertia router.on('before')
T067 [P] Add loading skeleton to DocumentEditor while fetching raw content
T068 [P] Add error boundary/handling for file write failures with retry option
T069 Run Laravel Pint on all new PHP files: vendor/bin/pint domain/Documentation/
T070 Run ESLint on all new Vue/TS files: npm run lint -- --fix

Dependencies

graph TD
    Setup[Phase 1: Setup] --> Foundation[Phase 2: Foundation]
    Foundation --> US1[Phase 3: US1 - Edit]
    US1 --> US2[Phase 4: US2 - Create]
    US1 --> US3[Phase 5: US3 - Metadata]
    US1 --> Concurrency[Phase 8: Concurrency]
    US2 --> US4[Phase 6: US4 - Search]
    US3 --> US5[Phase 7: US5 - Delete]
    US4 --> Polish[Phase 9: Polish]
    US5 --> Polish
    Concurrency --> Polish

Parallel Execution

Tasks marked [P] can run in parallel within their phase:

Phase	Parallel Tasks
Setup	T002, T003
Foundation	T005, T007, T010
US1	T012 with T011; T018, T019, T020 together
US2	T025, T026; T032, T033
US3	T037, T038
US4	T044, T045
US5	T047
Concurrency	T055, T056
Polish	T064, T065, T067, T068

Summary

Metric	Value
Total Tasks	70
Setup/Foundation	10 tasks
US1 - Edit	13 tasks
US2 - Create	11 tasks
US3 - Metadata	6 tasks
US4 - Search	5 tasks
US5 - Delete	7 tasks
Concurrency	10 tasks
Polish	8 tasks

MVP Scope

Recommended MVP: Phases 1-3 (Setup + Foundation + US1 - Edit)

This delivers the core value proposition (editing existing documents) with 23 tasks. Users can edit any document with live preview and auto-save drafts. Create, delete, search, and concurrency can follow in subsequent iterations.