spec

Feature Specification: Markdown Documentation Editor

Epic: MDE - Markdown Documentation Editor Initiative: TP-2141-Work-Management Created: 2025-11-27 Status: Draft Input: User description: “Expand the existing documentation reader to support editing, updating, and creating markdown files for business users”

Clarifications

Session 2025-11-27

Q: What authorization model for editing? → A: Open with audit - any authenticated user can edit; all changes logged with user attribution
Q: How to handle concurrent edits? → A: Soft lock - show “User X is editing” indicator; allow override but discourage simultaneous editing
Q: Where to store auto-saved drafts? → A: Browser localStorage only; drafts are device-specific, not synced across devices
Q: How should search work? → A: Client-side filtering; load all doc titles/snippets and filter in browser (suitable for <200 docs)
Q: Session expiry during edit? → A: Prompt re-login modal; draft preserved in localStorage and restored after re-authentication

Session 2025-11-29

Q: How to handle large documents (>100KB)? → A: Allow editing with debounced preview (500ms delay for >100KB docs)
Q: How to handle special characters in filenames? → A: Slugify - lowercase, replace spaces with hyphens, strip special chars (e.g., “My Agent! 🚀” → “my-agent.md”)
Q: What if file is deleted externally during edit? → A: Detect on save, show “File was deleted” error with option to recreate
Q: How to handle invalid markdown syntax? → A: Allow save silently - preview shows what will render, user can self-correct
Q: What if duplicate filename on create? → A: Auto-append number (e.g., “my-agent.md” exists → “my-agent-2.md”)

User Scenarios & Testing (mandatory)

User Story 1 - Edit Existing Documentation (Priority: P1)

A business user or team member views an existing document (agent, command, skill, or initiative file) in the documentation reader and notices content that needs updating. They click an “Edit” button, make their changes in an intuitive editor interface with live preview, and save the updated document.

Why this priority: This is the core functionality that transforms the read-only viewer into a collaborative tool. Without editing capability, users must manually edit files in their development environment, creating friction and limiting adoption by non-technical stakeholders.

Independent Test: Can be fully tested by navigating to any existing document, clicking Edit, modifying text, saving, and verifying the changes persist when the page is refreshed.

Acceptance Scenarios:

Given a logged-in user viewing an agent document, When they click the Edit button, Then they see an editor interface with the document’s current content loaded
Given a user in edit mode typing content, When they pause, Then they see a live preview of the rendered markdown alongside their edits
Given a user who has made changes, When they click Save, Then the document is updated and they see a success confirmation
Given a user editing a document, When they click Cancel, Then they return to view mode without saving changes
Given a user editing a document with frontmatter (metadata), When they modify the frontmatter section, Then the metadata is validated and saved correctly

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

A team member needs to document a new agent, command, skill, or add a file to an initiative. They navigate to the appropriate section, click “Create New”, fill in the required metadata through a guided form, write their content, and save the new document.

Why this priority: Creating new documentation expands the system’s utility beyond maintaining existing content. This enables teams to grow their documentation organically without developer intervention.

Independent Test: Can be fully tested by navigating to any document type index, clicking Create New, filling in the form, saving, and verifying the new document appears in the listing.

Acceptance Scenarios:

Given a user on the Agents index page, When they click “Create New Agent”, Then they see a form with required fields (name, description) and optional fields
Given a user creating a new command, When they submit the form with valid data, Then a new markdown file is created in the correct directory with proper frontmatter
Given a user creating a document, When they leave required fields empty, Then they see validation errors preventing submission
Given a user on an Epic detail page, When they click “Add Document”, Then they can create additional markdown files within that epic’s folder

User Story 3 - Manage Document Metadata (Priority: P2)

A user needs to update a document’s metadata (frontmatter) such as changing an agent’s associated tools, updating a command’s description, or modifying an epic’s phase. They access a structured metadata editor that validates entries and maintains data integrity.

Why this priority: Metadata drives relationships and display throughout the system. A structured editor prevents errors and ensures consistency without requiring users to understand YAML syntax.

Independent Test: Can be fully tested by opening metadata editor for any document type, modifying fields, saving, and verifying the frontmatter in the file matches the changes.

Acceptance Scenarios:

Given a user editing an agent, When they access the metadata panel, Then they see a form with labeled fields for name, description, color, tools, model, and related items
Given a user selecting tools for an agent, When they use the tools selector, Then they see a list of available tools to choose from
Given a user editing an initiative epic, When they change the phase, Then they see valid phase options appropriate for that epic type

User Story 4 - Navigate and Organize Documents (Priority: P3)

A user wants to find specific documentation quickly or understand the overall structure. They use search and filtering capabilities to locate documents, and can see how documents relate to each other.

Why this priority: As documentation grows, discoverability becomes essential. Search reduces time spent looking for information and helps users understand relationships between documents.

Independent Test: Can be fully tested by using the search feature to find a known document, applying filters, and verifying results match the criteria.

Acceptance Scenarios:

Given a user on any documentation page, When they type in the search field, Then they see matching documents across all types (agents, commands, skills, initiatives)
Given a user viewing search results, When they filter by document type, Then results are narrowed to only that type
Given a user viewing a document, When they look at related items, Then they can click through to view connected documents

User Story 5 - Delete or Archive Documents (Priority: P3)

A user determines that a document is obsolete or was created in error. They can remove the document from the system with appropriate safeguards to prevent accidental deletion.

Why this priority: Complete document lifecycle management requires the ability to remove content. However, this is lower priority as most users will focus on creating and editing.

Independent Test: Can be fully tested by selecting a document, clicking Delete, confirming the action, and verifying the document no longer appears in listings.

Acceptance Scenarios:

Given a user viewing a document, When they click Delete, Then they see a confirmation dialog explaining the consequences
Given a user confirming deletion, When the action completes, Then the file is removed and they are redirected to the index page
Given a user attempting to delete an initiative with epics, When they click Delete, Then they are warned about nested content and must confirm explicitly

Edge Cases

When two users edit simultaneously: Show “User X is editing” indicator; if user proceeds anyway, last-write-wins with both changes logged
Large documents (>100KB): Allow editing with debounced preview updates (500ms delay) to maintain performance
Session expiry: Show re-login modal; draft preserved in localStorage and restored after authentication
Filename generation: Slugify names - lowercase, replace spaces with hyphens, strip special chars and unicode
External file deletion during edit: Detect on save, show error with option to recreate file
Invalid markdown syntax: Allow save silently - preview shows rendered output, user self-corrects
Duplicate filename on create: Auto-append number (e.g., “my-agent-2.md”)

Requirements (mandatory)

Functional Requirements

Editing:

FR-001: System MUST provide an edit button on all viewable documents
FR-002: System MUST display a markdown editor with syntax highlighting when editing
FR-003: System MUST show a live preview of rendered markdown while editing
FR-004: System MUST preserve original content if user cancels editing
FR-005: System MUST render live preview showing how markdown will display (no validation blocking save)
FR-006: System MUST handle concurrent edit conflicts gracefully

Creating:

FR-007: System MUST provide a “Create New” action on document index pages
FR-008: System MUST present a form for required metadata based on document type
FR-009: System MUST generate valid filename from provided name/title
FR-010: System MUST create files in the correct directory structure
FR-011: System MUST prevent creation of duplicate filenames within the same directory

Metadata Management:

FR-012: System MUST provide a structured form for editing frontmatter
FR-013: System MUST validate metadata against expected schema for each document type
FR-014: System MUST maintain relationships when metadata references are updated

Navigation & Search:

FR-015: System MUST provide full-text search across all documentation
FR-016: System MUST allow filtering search results by document type
FR-017: System MUST display search results with relevant context snippets

Deletion:

FR-018: System MUST require confirmation before deleting any document
FR-019: System MUST warn users when deleting folders with nested content
FR-020: System MUST remove deleted files from the filesystem

User Experience:

FR-021: System MUST auto-save drafts periodically to prevent data loss
FR-022: System MUST indicate unsaved changes before navigation
FR-023: System MUST provide keyboard shortcuts for common actions (save, preview toggle)

Key Entities

Document: Represents any markdown file in the .claude directory structure. Has content, metadata (frontmatter), type, and path.
Document Type: Category of document (Agent, Command, Skill, MCP Server, Initiative, Epic). Each type has its own metadata schema.
Metadata Schema: Defines required and optional fields for each document type’s frontmatter.
Draft: Temporary storage of unsaved changes for a document, associated with a user session.

Success Criteria (mandatory)

Measurable Outcomes

SC-001: Users can edit and save an existing document within 30 seconds of clicking Edit
SC-002: Users can create a new document of any type within 2 minutes
SC-003: 95% of edit operations complete successfully without data loss
SC-004: Search returns relevant results within 1 second for queries across all documents
SC-005: Users receive clear error messages for 100% of validation failures
SC-006: System handles documents up to 500KB without performance degradation
SC-007: Auto-save captures changes every 30 seconds while editing
SC-008: 90% of users can successfully create their first document without external assistance

Assumptions

Users have appropriate authentication and authorization to view the documentation section
Any authenticated user with documentation access can edit/create documents (open access model)
All document changes are logged with user attribution for audit purposes
The existing .claude/ directory structure will be maintained
Documents will continue to use markdown format with YAML frontmatter
The system will not implement version control (Git integration is out of scope for initial release)
Permission to edit/create will initially be available to all authenticated users with documentation access
File operations will be performed directly on the filesystem (no separate database for content)