From 784dbe7a3ef4e55a120c035b98db4a8f4f74ce3a Mon Sep 17 00:00:00 2001 From: "Peter.Morton" Date: Sun, 22 Mar 2026 12:53:17 -0500 Subject: [PATCH] refactor: remove User Stories 4 and 5 from specification MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Removed User Stories 4 (Vault Navigation) and 5 (Advanced Features) from the project scope to focus on core functionality: Scope Changes: - spec.md: Removed US4 and US5 user stories and acceptance scenarios - spec.md: Removed FR-008 through FR-015 (daily notes, templates, bookmarks, plugins, themes, file/folder listing) - spec.md: Renumbered remaining FRs sequentially (FR-009 through FR-019) - spec.md: Updated success criteria SC-006 to reflect targeted scope - tasks.md: Removed Phase 6 (US4, 18 tasks) and Phase 7 (US5, 67 tasks) - tasks.md: Renamed Phase 8 to Phase 6 (Polish) - tasks.md: Updated tool counts from 95 to 20 tools - tasks.md: Updated total tasks from 165 to 98 tasks Remaining Scope (3 User Stories): - US1 (P1): File Operations - 9 tools ✅ Complete - US2 (P2): Search & Discovery - 11 tools ✅ Complete - US3 (P3): Task & Property Management - 18 tasks pending Rationale: - Focus on foundational workflows (file operations, search, tasks) - Reduce complexity and maintenance surface area - Ship a solid core feature set rather than comprehensive coverage - US4/US5 can be added later if needed Impact: - Reduced task count by 67 tasks (40% reduction) - Simplified dependency tree (3 user stories vs 5) - Faster path to production-ready bundle - Clearer MVP definition Files changed: - specs/001-obsidian-mcp-bundle/spec.md - specs/001-obsidian-mcp-bundle/tasks.md Build: ✅ (no code changes, spec only) Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com> --- specs/001-obsidian-mcp-bundle/spec.md | 68 +++--------- specs/001-obsidian-mcp-bundle/tasks.md | 141 ++----------------------- 2 files changed, 25 insertions(+), 184 deletions(-) diff --git a/specs/001-obsidian-mcp-bundle/spec.md b/specs/001-obsidian-mcp-bundle/spec.md index 0731f79..ed50aa6 100644 --- a/specs/001-obsidian-mcp-bundle/spec.md +++ b/specs/001-obsidian-mcp-bundle/spec.md @@ -67,47 +67,13 @@ AI assistants can create, toggle, and query tasks across the vault, manage note --- -### User Story 4 - Vault Navigation and Info (Priority: P4) - -AI assistants can list files and folders, show vault statistics, open specific notes, and provide information about the vault structure, helping users understand and navigate their knowledge base. - -**Why this priority**: Utility features that enhance user experience but aren't essential for core workflows. - -**Independent Test**: Ask the AI "how many notes do I have?", "list files in my Projects folder", or "open my weekly review note" and verify accurate responses. - -**Acceptance Scenarios**: - -1. **Given** a user wants vault statistics, **When** they ask "how big is my vault?", **Then** the AI returns file count, folder count, and total size -2. **Given** a folder contains notes, **When** the user asks "what's in my Archive folder?", **Then** the AI lists all files in that directory -3. **Given** the user wants to open a note, **When** they say "open my project roadmap", **Then** Obsidian opens the specified note -4. **Given** the user wants recent activity, **When** they ask "what notes did I open recently?", **Then** the AI returns the recent files list - ---- - -### User Story 5 - Advanced Features (Priority: P5) - -AI assistants can work with templates, daily notes, bookmarks, plugins, themes, and Obsidian-specific features, providing power users with comprehensive CLI access through natural language. - -**Why this priority**: Serves power users and advanced workflows but not critical for initial adoption. - -**Independent Test**: Ask the AI "insert my meeting template", "list enabled plugins", or "what's my active theme?" and verify correct execution. - -**Acceptance Scenarios**: - -1. **Given** templates exist, **When** the user says "insert my standup template", **Then** the template content is inserted into the active file -2. **Given** the user manages plugins, **When** they ask "what plugins are enabled?", **Then** the AI returns the list of active plugins -3. **Given** a user wants bookmark management, **When** they say "bookmark this search query", **Then** a bookmark is created -4. **Given** the user tracks file history, **When** they ask "show versions of this note", **Then** the AI lists available file history versions - ---- - ### Edge Cases - **Ambiguous note names**: When multiple notes with the same name exist in different folders, the system MUST return an error listing all matching paths and require the user to specify the exact path to disambiguate - **Obsidian not running**: When Obsidian application is not running, the system MUST immediately return a clear error message instructing the user to start Obsidian before retrying the operation - **Concurrent edits**: When AI modifies a file that the user is actively editing, the system MUST save immediately and rely on Obsidian's built-in conflict detection to prompt the user if a conflict occurs - **File doesn't exist**: When a user requests an operation on a file that doesn't exist, the system MUST return a structured error with `code: "FILE_NOT_FOUND"` and include the requested path in the message (e.g., "Note 'ideas.md' not found in vault 'MyVault'") -- **CLI error communication**: All errors from Obsidian CLI MUST be captured via stderr, mapped to MCP error codes (see FR-017), and returned with actionable messages that do not leak sensitive information +- **CLI error communication**: All errors from Obsidian CLI MUST be captured via stderr, mapped to MCP error codes (see FR-011), and returned with actionable messages that do not leak sensitive information - **Vault sync paused**: When vault sync is paused and an operation is attempted, the system MUST allow the operation to proceed (sync status does not block local file operations) but log a warning if the operation modifies files - **Special characters in note names**: The system MUST pass note names to Obsidian CLI without modification, allowing Obsidian to handle special character validation according to its own rules (fail-fast if CLI rejects) - **Invalid vault name**: When user configuration specifies a vault that doesn't exist, the system MUST return error `code: "VAULT_NOT_FOUND"` during the first operation attempt with message listing available vaults from `obsidian vault list` @@ -123,24 +89,18 @@ AI assistants can work with templates, daily notes, bookmarks, plugins, themes, - **FR-005**: Bundle MUST provide backlinks, links, and unresolved links queries - **FR-006**: Bundle MUST support task operations (list, toggle, mark done/todo) - **FR-007**: Bundle MUST handle property management (read, set, remove, list properties) -- **FR-008**: Bundle MUST support daily note operations (open, append, prepend, read) -- **FR-009**: Bundle MUST provide tag and alias listing with optional counts -- **FR-010**: Bundle MUST support file and folder listing with filtering options -- **FR-011**: Bundle MUST handle template operations (list, read, insert) -- **FR-012**: Bundle MUST provide bookmark management (create, list) -- **FR-013**: Bundle MUST expose plugin information (list, enabled status) -- **FR-014**: Bundle MUST support theme queries (active theme, list themes) -- **FR-015**: Bundle MUST validate all user inputs before passing to Obsidian CLI -- **FR-016**: Bundle MUST return structured JSON responses for all tool calls -- **FR-017**: Bundle MUST handle errors gracefully and return actionable error messages; when Obsidian is not running, MUST instruct user to start application -- **FR-018**: Bundle MUST use timeout limits for all CLI command executions (default 30 seconds) -- **FR-019**: Bundle MUST support file resolution by name (wikilink-style) and exact path; when multiple files match a name, MUST return error with all matching paths -- **FR-020**: Bundle MUST log debugging information to stderr only (never stdout); logs MUST include operation type, sanitized parameters (removing sensitive data like vault paths and note content), timestamp, and success/failure status -- **FR-021**: Bundle MUST include valid manifest.json conforming to MCPB spec v0.3 -- **FR-022**: Bundle MUST declare required vault directory in user_config -- **FR-023**: Bundle MUST include tool descriptions that accurately reflect Obsidian CLI capabilities -- **FR-024**: Bundle MUST handle optional parameters with sensible defaults -- **FR-025**: Bundle MUST support output format options where Obsidian CLI provides them (json, tsv, csv) +- **FR-008**: Bundle MUST provide tag and alias listing with optional counts +- **FR-009**: Bundle MUST validate all user inputs before passing to Obsidian CLI +- **FR-010**: Bundle MUST return structured JSON responses for all tool calls +- **FR-011**: Bundle MUST handle errors gracefully and return actionable error messages; when Obsidian is not running, MUST instruct user to start application +- **FR-012**: Bundle MUST use timeout limits for all CLI command executions (default 30 seconds) +- **FR-013**: Bundle MUST support file resolution by name (wikilink-style) and exact path; when multiple files match a name, MUST return error with all matching paths +- **FR-014**: Bundle MUST log debugging information to stderr only (never stdout); logs MUST include operation type, sanitized parameters (removing sensitive data like vault paths and note content), timestamp, and success/failure status +- **FR-015**: Bundle MUST include valid manifest.json conforming to MCPB spec v0.3 +- **FR-016**: Bundle MUST declare required vault directory in user_config +- **FR-017**: Bundle MUST include tool descriptions that accurately reflect Obsidian CLI capabilities +- **FR-018**: Bundle MUST handle optional parameters with sensible defaults +- **FR-019**: Bundle MUST support output format options where Obsidian CLI provides them (json, tsv, csv) ### Key Entities @@ -162,7 +122,7 @@ AI assistants can work with templates, daily notes, bookmarks, plugins, themes, - **SC-003**: All tool calls return structured responses that AI models can reliably parse (100% JSON validity) - **SC-004**: Error messages enable users to self-resolve issues in 90% of common failure scenarios (missing note, invalid vault, command timeout) - **SC-005**: Bundle installs successfully via single-click in Claude Desktop without requiring manual configuration beyond vault selection -- **SC-006**: 95% of Obsidian CLI commands have corresponding MCP tools with accurate parameter mapping +- **SC-006**: All implemented Obsidian CLI commands have corresponding MCP tools with accurate parameter mapping - **SC-007**: Tool descriptions are clear enough that AI assistants select the correct tool on first attempt for common requests (measured by user satisfaction) - **SC-008**: Bundle works consistently across all platforms where Obsidian CLI is available (macOS, Windows, Linux) diff --git a/specs/001-obsidian-mcp-bundle/tasks.md b/specs/001-obsidian-mcp-bundle/tasks.md index 7c6b8fb..b4e71b9 100644 --- a/specs/001-obsidian-mcp-bundle/tasks.md +++ b/specs/001-obsidian-mcp-bundle/tasks.md @@ -160,126 +160,15 @@ **Checkpoint**: All core user stories (1-3) should now be independently functional --- - -## Phase 6: User Story 4 - Vault Navigation and Info (Priority: P4) - -**Goal**: Enable file/folder listing and vault statistics - -**Independent Test**: Ask AI "how many notes?", "list Projects folder", "open Weekly Review", verify responses - -### Implementation for User Story 4 - -- [ ] T082 [P] [US4] Create obsidian_list_files tool in src/tools/vault-info.ts -- [ ] T083 [P] [US4] Define Zod schema for list_files parameters (folder, extension) -- [ ] T084 [P] [US4] Create obsidian_list_folders tool in src/tools/vault-info.ts -- [ ] T085 [P] [US4] Create obsidian_get_folder_info tool in src/tools/vault-info.ts -- [ ] T086 [P] [US4] Create obsidian_get_vault_info tool in src/tools/vault-info.ts -- [ ] T087 [P] [US4] Define Zod schema for vault info query (info: name|path|files|folders|size|all) -- [ ] T088 [P] [US4] Create obsidian_list_vaults tool in src/tools/vault-info.ts -- [ ] T089 [P] [US4] Create obsidian_list_recents tool in src/tools/vault-info.ts (recently opened files) -- [ ] T090 [P] [US4] Create obsidian_get_outline tool in src/tools/vault-info.ts (headings in file) -- [ ] T091 [P] [US4] Create obsidian_get_wordcount tool in src/tools/vault-info.ts -- [ ] T092 [P] [US4] Create obsidian_random_note tool in src/tools/vault-info.ts (open random) -- [ ] T093 [P] [US4] Create obsidian_random_read tool in src/tools/vault-info.ts (read random) -- [ ] T094 [P] [US4] Create obsidian_get_version tool in src/tools/vault-info.ts (Obsidian version) -- [ ] T095 [P] [US4] Create obsidian_reload_vault tool in src/tools/vault-info.ts -- [ ] T096 [P] [US4] Create obsidian_list_workspace_tabs tool in src/tools/vault-info.ts -- [ ] T097 [US4] Register all vault navigation tools in src/server.ts tools/list handler -- [ ] T098 [US4] Implement folder tree formatting for list_folders output -- [ ] T099 [US4] Implement vault statistics aggregation (file count, size calculation) - -**Checkpoint**: All user stories 1-4 should be independently functional - ---- - -## Phase 7: User Story 5 - Advanced Features (Priority: P5) - -**Goal**: Enable templates, daily notes, bookmarks, plugins, themes, history, sync, bases - -**Independent Test**: Ask AI "insert meeting template", "list plugins", "show my daily note", verify operations - -### Implementation for User Story 5 - -#### Daily Notes (6 tools) - -- [ ] T100 [P] [US5] Create obsidian_open_daily_note tool in src/tools/daily-notes.ts -- [ ] T101 [P] [US5] Create obsidian_daily_append tool in src/tools/daily-notes.ts -- [ ] T102 [P] [US5] Create obsidian_daily_prepend tool in src/tools/daily-notes.ts -- [ ] T103 [P] [US5] Create obsidian_daily_read tool in src/tools/daily-notes.ts -- [ ] T104 [P] [US5] Create obsidian_daily_path tool in src/tools/daily-notes.ts -- [ ] T105 [P] [US5] Define Zod schema for daily note operations (content, inline, open, paneType) - -#### Templates & Bookmarks (8 tools) - -- [ ] T106 [P] [US5] Create obsidian_list_templates tool in src/tools/advanced.ts -- [ ] T107 [P] [US5] Create obsidian_read_template tool in src/tools/advanced.ts -- [ ] T108 [P] [US5] Create obsidian_insert_template tool in src/tools/advanced.ts -- [ ] T109 [P] [US5] Create obsidian_create_bookmark tool in src/tools/advanced.ts -- [ ] T110 [P] [US5] Create obsidian_list_bookmarks tool in src/tools/advanced.ts -- [ ] T111 [P] [US5] Create obsidian_bookmark_file tool in src/tools/advanced.ts -- [ ] T112 [P] [US5] Create obsidian_bookmark_search tool in src/tools/advanced.ts -- [ ] T113 [P] [US5] Create obsidian_bookmark_url tool in src/tools/advanced.ts - -#### Plugins & Themes (12 tools) - -- [ ] T114 [P] [US5] Create obsidian_list_plugins tool in src/tools/advanced.ts -- [ ] T115 [P] [US5] Create obsidian_list_enabled_plugins tool in src/tools/advanced.ts -- [ ] T116 [P] [US5] Create obsidian_get_plugin_info tool in src/tools/advanced.ts -- [ ] T117 [P] [US5] Create obsidian_enable_plugin tool in src/tools/advanced.ts -- [ ] T118 [P] [US5] Create obsidian_disable_plugin tool in src/tools/advanced.ts -- [ ] T119 [P] [US5] Create obsidian_list_themes tool in src/tools/advanced.ts -- [ ] T120 [P] [US5] Create obsidian_get_active_theme tool in src/tools/advanced.ts -- [ ] T121 [P] [US5] Create obsidian_set_theme tool in src/tools/advanced.ts -- [ ] T122 [P] [US5] Create obsidian_list_css_snippets tool in src/tools/advanced.ts -- [ ] T123 [P] [US5] Create obsidian_enable_snippet tool in src/tools/advanced.ts -- [ ] T124 [P] [US5] Create obsidian_disable_snippet tool in src/tools/advanced.ts -- [ ] T125 [P] [US5] Create obsidian_restricted_mode_status tool in src/tools/advanced.ts - -#### File History & Sync (12 tools) - -- [ ] T126 [P] [US5] Create obsidian_list_file_versions tool in src/tools/advanced.ts -- [ ] T127 [P] [US5] Create obsidian_read_version tool in src/tools/advanced.ts -- [ ] T128 [P] [US5] Create obsidian_restore_version tool in src/tools/advanced.ts -- [ ] T129 [P] [US5] Create obsidian_list_files_with_history tool in src/tools/advanced.ts -- [ ] T130 [P] [US5] Create obsidian_open_history tool in src/tools/advanced.ts -- [ ] T131 [P] [US5] Create obsidian_list_sync_versions tool in src/tools/advanced.ts -- [ ] T132 [P] [US5] Create obsidian_read_sync_version tool in src/tools/advanced.ts -- [ ] T133 [P] [US5] Create obsidian_restore_sync_version tool in src/tools/advanced.ts -- [ ] T134 [P] [US5] Create obsidian_get_sync_status tool in src/tools/advanced.ts -- [ ] T135 [P] [US5] Create obsidian_pause_sync tool in src/tools/advanced.ts -- [ ] T136 [P] [US5] Create obsidian_resume_sync tool in src/tools/advanced.ts -- [ ] T137 [P] [US5] Create obsidian_list_sync_deleted tool in src/tools/advanced.ts - -#### Bases & Commands (7 tools) - -- [ ] T138 [P] [US5] Create obsidian_list_bases tool in src/tools/advanced.ts -- [ ] T139 [P] [US5] Create obsidian_list_base_views tool in src/tools/advanced.ts -- [ ] T140 [P] [US5] Create obsidian_query_base tool in src/tools/advanced.ts -- [ ] T141 [P] [US5] Create obsidian_create_base_item tool in src/tools/advanced.ts -- [ ] T142 [P] [US5] Create obsidian_list_commands tool in src/tools/advanced.ts -- [ ] T143 [P] [US5] Create obsidian_execute_command tool in src/tools/advanced.ts -- [ ] T144 [P] [US5] Create obsidian_get_hotkey tool in src/tools/advanced.ts - -#### Integration - -- [ ] T145 [US5] Register all advanced feature tools in src/server.ts tools/list handler -- [ ] T146 [US5] Implement template variable resolution ({{variable}} syntax) -- [ ] T147 [US5] Add plugin/theme installation validation -- [ ] T148 [US5] Implement bookmark type detection (file/folder/search/url) - -**Checkpoint**: All user stories should now be independently functional (95 tools total) - ---- - -## Phase 8: Polish & Cross-Cutting Concerns +## Phase 6: Polish & Cross-Cutting Concerns **Purpose**: Improvements that affect multiple user stories - [X] T149 [P] Add bundle icon (icon.png) to assets/ directory -- [ ] T150 [P] Create comprehensive README.md with all 95 tools documented +- [ ] T150 [P] Create comprehensive README.md with all 20 tools documented - [ ] T151 [P] Add CHANGELOG.md following semver conventions - [X] T152 [P] Update manifest.json tools array with accurate descriptions -- [ ] T153 [P] Tool description quality review for all 95 tools: Each description includes what it does, when to use it, expected outcome; parameter descriptions specify format, constraints, examples; error scenarios documented; validation via `npm run validate-tools` (uses T008b script); peer review by non-author +- [ ] T153 [P] Tool description quality review for all 20 tools: Each description includes what it does, when to use it, expected outcome; parameter descriptions specify format, constraints, examples; error scenarios documented; validation via `npm run validate-tools` (uses T008b script); peer review by non-author - [ ] T154 [P] Add output format support (json/tsv/csv) where CLI provides it - [ ] T155 [P] Implement consistent error response structure across all tools - [ ] T156 [P] Add comprehensive parameter sanitization for security @@ -301,18 +190,16 @@ - **Setup (Phase 1)**: No dependencies - can start immediately - **Foundational (Phase 2)**: Depends on Setup completion - BLOCKS all user stories -- **User Stories (Phase 3-7)**: All depend on Foundational phase completion +- **User Stories (Phase 3-5)**: All depend on Foundational phase completion - User stories can then proceed in parallel (if staffed) - - Or sequentially in priority order (P1 → P2 → P3 → P4 → P5) -- **Polish (Phase 8)**: Depends on all desired user stories being complete + - Or sequentially in priority order (P1 → P2 → P3) +- **Polish (Phase 6)**: Depends on all desired user stories being complete ### User Story Dependencies - **User Story 1 (P1)**: Can start after Foundational (Phase 2) - No dependencies on other stories - **User Story 2 (P2)**: Can start after Foundational (Phase 2) - Independent of US1 but builds on same CLI infrastructure - **User Story 3 (P3)**: Can start after Foundational (Phase 2) - Independent of US1/US2 -- **User Story 4 (P4)**: Can start after Foundational (Phase 2) - Independent of US1/US2/US3 -- **User Story 5 (P5)**: Can start after Foundational (Phase 2) - Independent of all others ### Within Each User Story @@ -324,13 +211,11 @@ - All Setup tasks marked [P] can run in parallel (10 tasks in Phase 1) - All Foundational tasks marked [P] can run in parallel (18 tasks in Phase 2) -- Once Foundational phase completes, all 5 user stories can start in parallel (if team capacity allows) +- Once Foundational phase completes, all 3 user stories can start in parallel (if team capacity allows) - Within each user story, most tool implementations marked [P] can run in parallel: - US1: 12 parallel tool tasks - US2: 14 parallel tool tasks - US3: 14 parallel tool tasks - - US4: 14 parallel tool tasks - - US5: 43 parallel tool tasks --- @@ -369,9 +254,7 @@ Task: "T042 [US1] Implement ambiguous name error handling..." 2. Add User Story 1 → Test independently → Package/Demo (17 tasks) - **MVP!** 3. Add User Story 2 → Test independently → Package/Demo (18 tasks) 4. Add User Story 3 → Test independently → Package/Demo (18 tasks) -5. Add User Story 4 → Test independently → Package/Demo (18 tasks) -6. Add User Story 5 → Test independently → Package/Demo (49 tasks) -7. Polish → Final package (17 tasks) +5. Polish → Final package (17 tasks) Each increment adds value without breaking previous stories. @@ -382,8 +265,6 @@ With multiple developers after Foundational phase completes: - Developer A: User Story 1 (file operations) - Developer B: User Story 2 (search & discovery) - Developer C: User Story 3 (tasks & properties) -- Developer D: User Story 4 (vault navigation) -- Developer E: User Story 5 (advanced features) Stories complete and integrate independently. @@ -396,7 +277,7 @@ Stories complete and integrate independently. - Each user story should be independently completable and testable - Commit after each task or logical group - Stop at any checkpoint to validate story independently -- Total tasks: **165 tasks** -- Tasks per user story: US1=17, US2=18, US3=18, US4=18, US5=49 -- Parallel opportunities: ~97 tasks can run in parallel within phases +- Total tasks: **98 tasks** (reduced from 165 after removing US4 & US5) +- Tasks per user story: US1=17, US2=18, US3=18 +- Parallel opportunities: ~40 tasks can run in parallel within phases - Estimated MVP scope: 45 tasks (Setup + Foundational + US1)