# Tasks: HackerNews MCP Server
**Input**: Design documents from `/specs/001-hackernews-mcp-server/`
**Prerequisites**: plan.md ✅, spec.md ✅, research.md ✅, data-model.md ✅, contracts/ ✅
**Tests**: Tests are NOT explicitly requested in the feature specification. However, the Constitution requires 80%+ test coverage. Tests will be included and follow TDD workflow as documented in research.md.
**Organization**: Tasks are grouped by user story to enable independent implementation and testing of each story.
## Format: `[ID] [P?] [Story] Description`
- **[P]**: Can run in parallel (different files, no dependencies)
- **[Story]**: Which user story this task belongs to (e.g., US1, US2, US3, US4, US5, US6)
- Include exact file paths in descriptions
## Path Conventions
- **Single project**: `src/`, `tests/`, `docs/` at repository root
- Project follows modular tool-per-file structure
---
## Phase 1: Setup (Shared Infrastructure)
**Purpose**: Project initialization and basic structure
- [X] T001 Create project directory structure: `src/`, `src/tools/`, `src/services/`, `src/types/`, `src/utils/`, `tests/unit/`, `tests/integration/`, `tests/contract/`, `docs/`, `.github/workflows/`
- [X] T002 Initialize Node.js project with `package.json`: name "hn-mcp-server", version "1.0.0", type "module", dependencies: `@modelcontextprotocol/sdk`, `zod`, devDependencies: `typescript`, `@biomejs/biome`, `vitest`, `@types/node`
- [X] T003 [P] Create TypeScript configuration in `tsconfig.json`: strict mode enabled, target ES2022, module ESNext, moduleResolution node16, outDir dist
- [X] T004 [P] Create Biome configuration in `biome.json`: enable linting and formatting, TypeScript support, line width 100, recommended rules
- [X] T005 [P] Create Vitest configuration in `vitest.config.ts`: coverage enabled with c8, threshold 80%, include tests/**/*.test.ts
- [X] T006 [P] Create `.gitignore`: node_modules, dist, coverage, .env, .DS_Store
- [X] T007 [P] Create `README.md` with project overview, installation instructions, and basic usage
- [X] T008 [P] Create `LICENSE` file with MIT license
- [X] T009 Add npm scripts to `package.json`: build (tsc), test (vitest), lint (biome check), format (biome format --write), dev (tsc --watch)
---
## Phase 2: Foundational (Blocking Prerequisites) ✅ COMPLETE
**Purpose**: Core infrastructure that MUST be complete before ANY user story can be implemented
**⚠️ CRITICAL**: No user story work can begin until this phase is complete
- [X] T010 [P] Define HackerNews API types in `src/types/hn-types.ts`: HNItem, HNStory, HNComment, HNUser, SearchResult, ItemResult (copy from contracts/types.ts)
- [X] T011 [P] Define MCP types in `src/types/mcp-types.ts`: ToolResultContent, ToolResult, APIError, ValidationError, ServerConfig, ToolMetadata (copy from contracts/types.ts)
- [X] T012 [P] Create input/output type definitions in `src/types/index.ts`: export all tool input/output types from contracts/types.ts
- [X] T013 Create HackerNews API client service in `src/services/hn-api.ts`: class HNAPIClient with methods: search(), searchByDate(), getItem(), getUser(), base URL constant, fetch wrapper with timeout (5s), error handling
- [X] T014 Create validation utilities in `src/utils/validators.ts`: helper functions for validating query strings, page numbers, hitsPerPage range, username format, itemId format
- [X] T015 Create error handler utilities in `src/utils/error-handlers.ts`: functions to map API errors to MCP error responses, format validation errors, handle network errors, handle rate limit errors (429)
- [X] T016 Write unit tests for validators in `tests/unit/validators.test.ts`: test all validation rules from data-model.md
- [X] T017 Write unit tests for error handlers in `tests/unit/error-handlers.test.ts`: test all error mapping functions
- [X] T018 Write integration tests for HackerNews API client in `tests/integration/hn-api.test.ts`: test all API methods with real API calls, handle timeouts, handle API errors
- [X] T019 Initialize MCP server in `src/index.ts`: import McpServer from SDK, create server instance with name "hackernews-mcp-server" and version "1.0.0", setup StdioServerTransport, add error handling, connect server to transport
**Checkpoint**: Foundation ready - user story implementation can now begin in parallel
---
## Phase 3: User Story 1 - Search Posts by Keyword (Priority: P1) 🎯 MVP - PARTIAL
**Goal**: Enable searching HackerNews for posts with keywords, filters, and pagination. Delivers core content discovery capability.
**Independent Test**: Execute searches with various keywords (e.g., "AI"), apply filters (story tag, points>=100), and verify relevant results are returned. Pagination works correctly.
### Tests for User Story 1 (TDD - Write First)
**NOTE: Write these tests FIRST, ensure they FAIL before implementation**
- [X] T020 [P] [US1] Create contract test for search-posts tool input validation in `tests/contract/search-posts.test.ts`: test query min length, tags array optional, numericFilters format, page non-negative, hitsPerPage range 1-1000
- [X] T021 [P] [US1] Create contract test for search-posts tool output schema in `tests/contract/search-posts.test.ts`: verify SearchResult structure, hits array, pagination fields, response matches Zod schema
- [X] T022 [P] [US1] Create integration test for search-posts basic search in `tests/integration/tools/search-posts.test.ts`: search for "Python", verify results contain keyword, check response structure
- [X] T023 [P] [US1] Create integration test for search-posts with filters in `tests/integration/tools/search-posts.test.ts`: search with tags ["story"], numericFilters ["points>=100"], verify filtered results
- [X] T024 [P] [US1] Create integration test for search-posts pagination in `tests/integration/tools/search-posts.test.ts`: request page 0 and page 1, verify different results, check pagination metadata
- [X] T025 [P] [US1] Create integration test for search-posts error handling in `tests/integration/tools/search-posts.test.ts`: test empty query (validation error), test API failure handling
### Implementation for User Story 1
- [X] T026 [US1] Implement search-posts tool in `src/tools/search-posts.ts`: define Zod input schema (SearchPostsInput), define output schema (SearchPostsOutput), implement handler function that calls HNAPIClient.search(), map results to ToolResult format, handle validation errors, handle API errors, export tool registration function
- [X] T027 [US1] Register search-posts tool in `src/index.ts`: import search-posts tool, register with server.registerTool(), include comprehensive description for LLM understanding
- [X] T028 [US1] Verify all User Story 1 tests pass: run `npm test -- search-posts`, verify 100% pass rate, check test coverage for search-posts tool
**Checkpoint**: At this point, User Story 1 (search-posts) should be fully functional and testable independently. Users can search HackerNews and get relevant results.
---
## Phase 4: User Story 2 - View Front Page Posts (Priority: P1) ✅ COMPLETE
**Goal**: Enable retrieval of current HackerNews front page posts. Delivers trending content discovery.
**Independent Test**: Request front page posts and verify they match what's currently on HackerNews homepage. Pagination works.
### Tests for User Story 2 (TDD - Write First)
- [X] T029 [P] [US2] Create contract test for get-front-page tool in `tests/contract/get-front-page.test.ts`: test page non-negative, hitsPerPage range 1-1000, output schema matches SearchResult
- [X] T030 [P] [US2] Create integration test for get-front-page basic request in `tests/integration/tools/get-front-page.test.ts`: request front page, verify results have front_page tag, check response structure
- [X] T031 [P] [US2] Create integration test for get-front-page pagination in `tests/integration/tools/get-front-page.test.ts`: request with custom hitsPerPage, verify pagination works
- [X] T032 [P] [US2] Create integration test for get-front-page error handling in `tests/integration/tools/get-front-page.test.ts`: test invalid parameters, API failure handling
### Implementation for User Story 2
- [X] T033 [US2] Implement get-front-page tool in `src/tools/get-front-page.ts`: define Zod input schema (GetFrontPageInput), define output schema (GetFrontPageOutput), implement handler that calls HNAPIClient.search() with tags=["front_page"], map results to ToolResult, handle errors
- [X] T034 [US2] Register get-front-page tool in `src/index.ts`: import tool, register with server.registerTool(), add description
- [X] T035 [US2] Verify all User Story 2 tests pass: run tests, check coverage
**Checkpoint**: At this point, User Stories 1 AND 2 should both work independently. Users can search and view front page.
---
## Phase 5: User Story 3 - Get Latest Posts (Priority: P1) ✅ COMPLETE
**Goal**: Enable retrieval of most recent posts sorted by date. Delivers real-time content monitoring.
**Independent Test**: Request latest posts sorted by date and verify they are ordered correctly. Can filter by type (stories, comments).
### Tests for User Story 3 (TDD - Write First)
- [X] T036 [P] [US3] Create contract test for get-latest-posts tool in `tests/contract/get-latest-posts.test.ts`: test tags optional, page non-negative, hitsPerPage range, output matches SearchResult
- [X] T037 [P] [US3] Create integration test for get-latest-posts all types in `tests/integration/tools/get-latest-posts.test.ts`: request without filters, verify results sorted by date (most recent first)
- [X] T038 [P] [US3] Create integration test for get-latest-posts with filters in `tests/integration/tools/get-latest-posts.test.ts`: filter by tags ["story"], verify only stories returned, check date ordering
- [X] T039 [P] [US3] Create integration test for get-latest-posts comments in `tests/integration/tools/get-latest-posts.test.ts`: filter by tags ["comment"], verify only comments returned
- [X] T040 [P] [US3] Create integration test for get-latest-posts error handling in `tests/integration/tools/get-latest-posts.test.ts`: test invalid parameters
### Implementation for User Story 3
- [X] T041 [US3] Implement get-latest-posts tool in `src/tools/get-latest-posts.ts`: define Zod input schema (GetLatestPostsInput), define output schema (GetLatestPostsOutput), implement handler that calls HNAPIClient.searchByDate() with empty query, support optional tags filter, map results to ToolResult, handle errors
- [X] T042 [US3] Register get-latest-posts tool in `src/index.ts`: import tool, register with server, add description
- [X] T043 [US3] Verify all User Story 3 tests pass: run tests, check coverage
**Checkpoint**: At this point, User Stories 1, 2, AND 3 should all work independently. Core search/discovery features complete.
---
## Phase 6: User Story 4 - Retrieve Individual Items (Priority: P2) ✅ COMPLETE
**Goal**: Enable fetching complete details for specific posts with nested comment threads. Essential for deep-linking and discussion views.
**Independent Test**: Request a known item ID and verify all details and nested children are returned correctly. Comment tree structure preserved.
### Tests for User Story 4 (TDD - Write First)
- [X] T044 [P] [US4] Create contract test for get-item tool in `tests/contract/get-item.test.ts`: test itemId required, non-empty string, output matches ItemResult schema
- [X] T045 [P] [US4] Create integration test for get-item story in `tests/integration/tools/get-item.test.ts`: fetch known story ID, verify title/url/points, check children array exists
- [X] T046 [P] [US4] Create integration test for get-item comment in `tests/integration/tools/get-item.test.ts`: fetch known comment ID, verify text/author/parent_id
- [X] T047 [P] [US4] Create integration test for get-item nested comments in `tests/integration/tools/get-item.test.ts`: fetch story with comments, verify nested children structure, check multiple levels of nesting
- [X] T048 [P] [US4] Create integration test for get-item error handling in `tests/integration/tools/get-item.test.ts`: test empty itemId (validation error), test non-existent ID (not found error)
### Implementation for User Story 4
- [X] T049 [US4] Implement get-item tool in `src/tools/get-item.ts`: define Zod input schema (GetItemInput), define output schema (GetItemOutput), implement handler that calls HNAPIClient.getItem(itemId), recursively fetch nested children, map to ItemResult with complete comment tree, handle errors (validation, not found, API)
- [X] T050 [US4] Register get-item tool in `src/index.ts`: import tool, register with server, add description mentioning nested comment support
- [X] T051 [US4] Verify all User Story 4 tests pass: run tests, check coverage, verify nested comment handling works
**Checkpoint**: At this point, all P1 and P2 priority stories work. Users can search, view front page, get latest, and view detailed items.
---
## Phase 7: User Story 5 - Get User Information (Priority: P3) ✅ COMPLETE
**Goal**: Enable retrieval of user profile information. Enriches author details in UI contexts.
**Independent Test**: Request a known username and verify profile data is returned (karma, bio, creation date).
### Tests for User Story 5 (TDD - Write First)
- [X] T052 [P] [US5] Create contract test for get-user tool in `tests/contract/get-user.test.ts`: test username required, alphanumeric+underscore validation, output matches HNUser schema
- [X] T053 [P] [US5] Create integration test for get-user known user in `tests/integration/tools/get-user.test.ts`: fetch known user (e.g., "pg"), verify username/karma/about/created fields
- [X] T054 [P] [US5] Create integration test for get-user error handling in `tests/integration/tools/get-user.test.ts`: test empty username (validation error), invalid format, non-existent user (not found)
### Implementation for User Story 5
- [X] T055 [US5] Implement get-user tool in `src/tools/get-user.ts`: define Zod input schema (GetUserInput with regex validation), define output schema (GetUserOutput), implement handler that calls HNAPIClient.getUser(username), map to HNUser, handle errors (validation, not found, API)
- [X] T056 [US5] Register get-user tool in `src/index.ts`: import tool, register with server, add description
- [X] T057 [US5] Verify all User Story 5 tests pass: run tests, check coverage
**Checkpoint**: All user stories through P3 are complete. Full API coverage achieved.
---
## Phase 8: User Story 6 - Filter and Refine Search Results (Priority: P2)
**Goal**: Enable advanced filtering (points threshold, comment count, URL matching, specific tags) to narrow search results. Enhances search power for specialized use cases.
**Independent Test**: Apply various filters to searches (points>=100, num_comments>=50, URL-only) and verify results match filter criteria.
**Note**: This story enhances User Story 1 (search-posts) rather than creating a new tool. Implementation verifies existing search-posts tool handles all advanced filter scenarios.
### Tests for User Story 6 (TDD - Write First)
- [X] T058 [P] [US6] Create integration test for search-posts points filter in `tests/integration/tools/search-posts.test.ts`: search with numericFilters ["points>=100"], verify all results have 100+ points
- [X] T059 [P] [US6] Create integration test for search-posts comment count filter in `tests/integration/tools/search-posts.test.ts`: search with numericFilters ["num_comments>=50"], verify all results have 50+ comments
- [X] T060 [P] [US6] Create integration test for search-posts combined filters in `tests/integration/tools/search-posts.test.ts`: combine multiple numericFilters ["points>=100", "num_comments>=20"], verify results match all criteria
- [X] T061 [P] [US6] Create integration test for search-posts OR tags in `tests/integration/tools/search-posts.test.ts`: search with tags ["(story,poll)"], verify results include both stories and polls
- [X] T062 [P] [US6] Create integration test for search-posts author filter in `tests/integration/tools/search-posts.test.ts`: search with tags ["author_pg"], verify all results by that author
### Implementation for User Story 6
- [X] T063 [US6] Verify search-posts tool supports all filter types: review src/tools/search-posts.ts implementation, confirm tags array supports AND/OR logic, confirm numericFilters passed to API correctly, add JSDoc examples for advanced filtering
- [X] T064 [US6] Update search-posts tool description in src/index.ts: add examples of advanced filters (points>=100, author_username, OR tags), document numeric filter operators (<, <=, =, >=, >)
- [X] T065 [US6] Verify all User Story 6 tests pass: run tests, ensure advanced filtering works correctly
**Checkpoint**: All user stories are now independently functional. Search capabilities are comprehensive with advanced filtering.
---
## Phase 9: Documentation & Polish ✅ COMPLETE
**Purpose**: Create comprehensive user-facing documentation and polish for open source distribution
- [X] T066 [P] Create detailed API reference in `docs/API.md`: document all 5 tools with parameter descriptions, examples, error conditions, copy from contracts/tool-contracts.md and enhance with usage patterns
- [X] T067 [P] Create architecture documentation in `docs/ARCHITECTURE.md`: system design overview, component interactions (tools → services → API), data flow diagrams, error handling strategy, testing approach
- [X] T068 [P] Create contributing guidelines in `docs/CONTRIBUTING.md`: development setup instructions, running tests, code style (Biome), pull request process, issue templates
- [X] T069 Update README.md: expand with quickstart examples, add badges (build status, coverage), link to docs/, add usage examples for all tools, installation instructions
- [X] T070 [P] Create GitHub Actions CI workflow in `.github/workflows/ci.yml`: install dependencies, run linting (biome check), run formatting check (biome format), run tests with coverage, fail if coverage < 80%
- [X] T071 [P] Update `.github/copilot-instructions.md`: add HackerNews MCP Server to active technologies, list all 5 tools, note TypeScript strict mode and Biome usage
- [X] T072 Run full test suite and verify 80%+ coverage: run `npm run test:coverage`, check coverage report, ensure all files meet threshold
- [X] T073 Validate against quickstart.md scenarios: manually test each example from quickstart.md, verify all acceptance scenarios from spec.md pass
- [X] T074 Code cleanup and refactoring: remove console.logs, add JSDoc comments to all public functions, ensure consistent error messages, verify all TODOs resolved
- [X] T075 Final integration test: build project (`npm run build`), test with MCP client (Claude Desktop), verify all tools work end-to-end
---
## Dependencies & Execution Order
### Phase Dependencies
- **Setup (Phase 1)**: No dependencies - can start immediately
- **Foundational (Phase 2)**: Depends on Setup (Phase 1) completion - BLOCKS all user stories
- **User Story 1 (Phase 3)**: Depends on Foundational (Phase 2) - Can start once foundation ready
- **User Story 2 (Phase 4)**: Depends on Foundational (Phase 2) - Can start in parallel with US1
- **User Story 3 (Phase 5)**: Depends on Foundational (Phase 2) - Can start in parallel with US1/US2
- **User Story 4 (Phase 6)**: Depends on Foundational (Phase 2) - Can start in parallel with other stories
- **User Story 5 (Phase 7)**: Depends on Foundational (Phase 2) - Can start in parallel with other stories
- **User Story 6 (Phase 8)**: Depends on User Story 1 (Phase 3) implementation - Enhances existing search-posts tool
- **Documentation (Phase 9)**: Depends on all desired user stories being complete
### User Story Dependencies
- **US1 - Search Posts (P1)**: No dependencies on other stories - Can start after Foundational phase
- **US2 - Front Page (P1)**: No dependencies on other stories - Can start after Foundational phase - Independent
- **US3 - Latest Posts (P1)**: No dependencies on other stories - Can start after Foundational phase - Independent
- **US4 - Item Details (P2)**: No dependencies on other stories - Can start after Foundational phase - Independent
- **US5 - User Info (P3)**: No dependencies on other stories - Can start after Foundational phase - Independent
- **US6 - Advanced Filters (P2)**: Depends on US1 (search-posts tool must exist) - Tests and enhances existing functionality
### Within Each User Story Phase
1. Tests MUST be written FIRST and FAIL before implementation (TDD workflow per Constitution)
2. All tests for a story marked [P] can run in parallel (different test files)
3. Implementation tasks run sequentially (same tool file)
4. Verify tests pass before moving to next story
### Parallel Opportunities
**Within Setup Phase**:
- T003, T004, T005, T006, T007, T008 can all run in parallel (different config files)
**Within Foundational Phase**:
- T010, T011, T012 can run in parallel (different type files)
- T016, T017 can run in parallel after T014, T015 complete (different test files)
**Across User Stories (after Foundational complete)**:
- All user stories US1-US5 can start in parallel (different tool files)
- Each story's test tasks marked [P] can run in parallel
- US6 must wait for US1 to complete (enhances same tool)
**Within Documentation Phase**:
- T066, T067, T068, T070, T071 can all run in parallel (different doc files)
---
## Parallel Example: Foundational Phase
```bash
# After T009 completes, launch type definitions in parallel:
Task: "Define HackerNews API types in src/types/hn-types.ts"
Task: "Define MCP types in src/types/mcp-types.ts"
Task: "Create input/output type definitions in src/types/index.ts"
# After T015 completes, launch unit tests in parallel:
Task: "Write unit tests for validators in tests/unit/validators.test.ts"
Task: "Write unit tests for error handlers in tests/unit/error-handlers.test.ts"
```
## Parallel Example: User Story Tests
```bash
# Launch all contract/integration tests for US1 in parallel (TDD - they should FAIL):
Task: "Contract test for search-posts input validation"
Task: "Contract test for search-posts output schema"
Task: "Integration test for search-posts basic search"
Task: "Integration test for search-posts with filters"
Task: "Integration test for search-posts pagination"
Task: "Integration test for search-posts error handling"
```
## Parallel Example: Multiple User Stories
```bash
# After Foundational phase complete, different developers can work on:
Developer A: Phase 3 - User Story 1 (search-posts)
Developer B: Phase 4 - User Story 2 (get-front-page)
Developer C: Phase 5 - User Story 3 (get-latest-posts)
# All three stories are independent and can proceed in parallel
```
---
## Implementation Strategy
### MVP First (User Story 1 Only)
1. Complete Phase 1: Setup (T001-T009)
2. Complete Phase 2: Foundational (T010-T019) - **CRITICAL CHECKPOINT**
3. Complete Phase 3: User Story 1 (T020-T028)
4. **STOP and VALIDATE**: Test search-posts independently with real queries
5. Build and deploy MVP: Users can search HackerNews with full filtering
### Recommended Incremental Delivery (All P1 Stories)
1. Complete Setup + Foundational → Foundation ready ✅
2. Add User Story 1 (search-posts) → Test independently → **MVP v0.1** 🚀
3. Add User Story 2 (get-front-page) → Test independently → **v0.2** 🚀
4. Add User Story 3 (get-latest-posts) → Test independently → **v0.3** 🚀
5. All P1 features complete: Core search, front page, latest posts → **v1.0 candidate**
6. Add User Story 4 (get-item) → Test independently → **v1.1**
7. Add User Story 5 (get-user) → Test independently → **v1.2**
8. Add User Story 6 (advanced filters) → Test independently → **v1.3**
9. Complete Documentation → **v1.0.0 RELEASE** 🎉
### Parallel Team Strategy
With multiple developers (after Foundational phase complete):
1. **Team completes Setup + Foundational together** (T001-T019)
2. **Once Foundational done, split work**:
- Developer A: User Story 1 - Search Posts (T020-T028)
- Developer B: User Story 2 - Front Page (T029-T035)
- Developer C: User Story 3 - Latest Posts (T036-T043)
3. **After P1 stories complete**:
- Developer A: User Story 4 - Item Details (T044-T051)
- Developer B: User Story 5 - User Info (T052-T057)
- Developer A: User Story 6 - Advanced Filters (T058-T065) - after US1 done
4. **Documentation phase**: Team collaborates on polish (T066-T075)
Each story integrates independently, allowing continuous deployment.
---
## Test Coverage Targets
**Constitution Requirement**: Minimum 80% overall coverage
**Per Component**:
- `src/types/`: 100% (type definitions, no executable code)
- `src/utils/validators.ts`: 100% (critical path, all validation rules)
- `src/utils/error-handlers.ts`: 100% (critical path, all error scenarios)
- `src/services/hn-api.ts`: 90%+ (all API methods, error paths)
- `src/tools/*.ts`: 85%+ per tool (all tool handlers, success and error paths)
- `src/index.ts`: 80%+ (server initialization, tool registration)
**Test Types**:
- **Unit Tests**: validators, error handlers (pure functions, no I/O)
- **Integration Tests**: HN API client, all tool handlers (with real API)
- **Contract Tests**: Tool input/output schema validation (Zod schemas)
---
## Success Metrics Verification
Map to success criteria from spec.md:
| Criterion | Verification Task | When |
|-----------|------------------|------|
| SC-001: Search < 2s | Integration tests measure response time | T022-T025 |
| SC-002: 100% front/latest accuracy | Integration tests verify API pass-through | T030, T037 |
| SC-003: Item retrieval < 3s | Integration test with timer | T045-T047 |
| SC-004: User profile < 1s | Integration test with timer | T053 |
| SC-005: All endpoints supported | All 5 tools implemented and tested | T028, T035, T043, T051, T057 |
| SC-006: Pagination works | Integration tests for pagination | T024, T031 |
| SC-007: All filters work | Integration tests for each filter type | T023, T058-T062 |
| SC-008: Clear error messages | Unit tests for error handlers | T017 |
| SC-009: Rate limit handling | Integration test with 429 simulation | T025, T032, T040, T048, T054 |
| SC-010: 95% first-attempt success | Manual validation | T073 |
| SC-011: API compatibility | All integration tests use real API | T018, T022-T025, T030-T032, etc. |
| SC-012: All scenarios pass | Manual quickstart validation | T073 |
---
## Notes
- **[P] tasks** = different files, no dependencies, can run in parallel
- **[Story] label** maps task to specific user story for traceability
- Each user story is independently completable and testable
- **TDD workflow**: Write tests first, watch them fail, implement, watch them pass
- Commit after each task or logical group
- Stop at each checkpoint to validate story independently
- **Foundation phase is critical**: No story work can start until T010-T019 complete
- US6 enhances US1 rather than creating new tool (advanced filtering)
- Tests included due to Constitution requirement (80%+ coverage non-negotiable)
---
## Total Task Count
- **Setup**: 9 tasks (T001-T009)
- **Foundational**: 10 tasks (T010-T019) - BLOCKS all stories
- **User Story 1 (P1)**: 9 tasks (T020-T028) - MVP core
- **User Story 2 (P1)**: 7 tasks (T029-T035)
- **User Story 3 (P1)**: 8 tasks (T036-T043)
- **User Story 4 (P2)**: 8 tasks (T044-T051)
- **User Story 5 (P3)**: 6 tasks (T052-T057)
- **User Story 6 (P2)**: 8 tasks (T058-T065)
- **Documentation & Polish**: 10 tasks (T066-T075)
**Total**: 75 tasks
**Estimated Completion**:
- MVP (Setup + Foundation + US1): ~19 tasks = 2-3 days
- All P1 features (+ US2, US3): ~24 additional tasks = 4-5 days total
- Full v1.0 (all stories + docs): ~75 tasks = 7-10 days total
**Parallel Opportunities**: With 3 developers, could complete in 3-4 days (after foundation).