directory changes and restructuring

🤖 Generated with [Claude Code](https://claude.com/claude-code)

Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>

official-skills/notion-spec-to-implementation/SKILL.md

@@ -0,0 +1,219 @@
+---
+name: notion-spec-to-implementation
+description: Turns product or tech specs into concrete Notion tasks that Claude code can implement. Breaks down spec pages into detailed implementation plans with clear tasks, acceptance criteria, and progress tracking to guide development from requirements to completion.
+---
+
+# Spec to Implementation
+
+Transforms specifications into actionable implementation plans with progress tracking. Fetches spec documents, extracts requirements, breaks down into tasks, and manages implementation workflow.
+
+## Quick Start
+
+When asked to implement a specification:
+
+1. **Find spec**: Use `Notion:notion-search` to locate specification page
+2. **Fetch spec**: Use `Notion:notion-fetch` to read specification content
+3. **Extract requirements**: Parse and structure requirements from spec
+4. **Create plan**: Use `Notion:notion-create-pages` for implementation plan
+5. **Find task database**: Use `Notion:notion-search` to locate tasks database
+6. **Create tasks**: Use `Notion:notion-create-pages` for individual tasks in task database
+7. **Track progress**: Use `Notion:notion-update-page` to log progress and update status
+
+## Implementation Workflow
+
+### Step 1: Find the specification
+
+```
+1. Search for spec:
+   - Use Notion:notion-search with spec name or topic
+   - Apply filters if needed (e.g., created_date_range, teamspace_id)
+   - Look for spec title or keyword matches
+   - If not found or ambiguous, ask user for spec URL/ID
+
+Example searches:
+- "User Authentication spec"
+- "Payment Integration specification"
+- "Mobile App Redesign PRD"
+```
+
+### Step 2: Fetch and analyze specification
+
+```
+1. Fetch spec page:
+   - Use Notion:notion-fetch with spec URL/ID from search results
+   - Read full content including requirements, design, constraints
+
+2. Parse specification:
+   - Identify functional requirements
+   - Note non-functional requirements (performance, security, etc.)
+   - Extract acceptance criteria
+   - Identify dependencies and blockers
+```
+
+See [reference/spec-parsing.md](reference/spec-parsing.md) for parsing patterns.
+
+### Step 3: Create implementation plan
+
+```
+1. Break down into phases/milestones
+2. Identify technical approach
+3. List required tasks
+4. Estimate effort
+5. Identify risks
+
+Use implementation plan template (see [reference/standard-implementation-plan.md](reference/standard-implementation-plan.md) or [reference/quick-implementation-plan.md](reference/quick-implementation-plan.md))
+```
+
+### Step 4: Create implementation plan page
+
+```
+Use Notion:notion-create-pages:
+- Title: "Implementation Plan: [Feature Name]"
+- Content: Structured plan with phases, tasks, timeline
+- Link back to original spec
+- Add to appropriate location (project page, database)
+```
+
+### Step 5: Find task database
+
+```
+1. Search for task database:
+   - Use Notion:notion-search to find "Tasks" or "Task Management" database
+   - Look for engineering/project task tracking system
+   - If not found or ambiguous, ask user for database location
+
+2. Fetch database schema:
+   - Use Notion:notion-fetch with database URL/ID
+   - Get property names, types, and options
+   - Identify correct data source from <data-source> tags
+   - Note required properties for new tasks
+```
+
+### Step 6: Create implementation tasks
+
+```
+For each task in plan:
+1. Create task in task database using Notion:notion-create-pages
+2. Use parent: { data_source_id: 'collection://...' }
+3. Set properties from schema:
+   - Name/Title: Task description
+   - Status: To Do
+   - Priority: Based on criticality
+   - Related Tasks: Link to spec and plan
+4. Add implementation details in content
+```
+
+See [reference/task-creation.md](reference/task-creation.md) for task patterns.
+
+### Step 7: Begin implementation
+
+```
+1. Update task status to "In Progress"
+2. Add initial progress note
+3. Document approach and decisions
+4. Link relevant resources
+```
+
+### Step 8: Track progress
+
+```
+Regular updates:
+1. Update task properties (status, progress)
+2. Add progress notes with:
+   - What's completed
+   - Current focus
+   - Blockers/issues
+3. Update implementation plan with milestone completion
+4. Link to related work (PRs, designs, etc.)
+```
+
+See [reference/progress-tracking.md](reference/progress-tracking.md) for tracking patterns.
+
+## Spec Analysis Patterns
+
+**Functional Requirements**: User stories, feature descriptions, workflows, data requirements, integration points
+
+**Non-Functional Requirements**: Performance targets, security requirements, scalability needs, availability, compliance
+
+**Acceptance Criteria**: Testable conditions, user validation points, performance benchmarks, completion definitions
+
+See [reference/spec-parsing.md](reference/spec-parsing.md) for detailed parsing techniques.
+
+## Implementation Plan Structure
+
+**Plan includes**: Overview → Linked Spec → Requirements Summary → Technical Approach → Implementation Phases (Goal, Tasks checklist, Estimated effort) → Dependencies → Risks & Mitigation → Timeline → Success Criteria
+
+See [reference/standard-implementation-plan.md](reference/standard-implementation-plan.md) for full plan template.
+
+## Task Breakdown Patterns
+
+**By Component**: Database, API endpoints, frontend components, integration, testing
+**By Feature Slice**: Vertical slices (auth flow, data entry, report generation)
+**By Priority**: P0 (must have), P1 (important), P2 (nice to have)
+
+
+## Progress Logging
+
+**Daily Updates** (active work): Add progress note with completed items, current focus, blockers
+**Milestone Updates** (major progress): Update plan checkboxes, add milestone summary, adjust timeline
+**Status Changes** (task transitions): Update properties (In Progress → In Review → Done), add completion notes, link deliverables
+
+**Progress Format**: Date heading → Completed → In Progress → Next Steps → Blockers → Notes
+
+See [reference/progress-tracking.md](reference/progress-tracking.md) for detailed patterns.
+
+## Linking Spec to Implementation
+
+**Forward Links**: Update spec page with "Implementation" section linking to plan and tasks
+**Backward Links**: Reference spec in plan and tasks with "Specification" section
+**Bidirectional Traceability**: Maintain both directions for easy tracking
+
+## Implementation Status Tracking
+
+**Plan Status**: Update with phase completion (✅ Complete, 🔄 In Progress %, ⏳ Not Started) and overall percentage
+**Task Aggregation**: Query task database by plan ID to generate summary (complete, in progress, blocked, not started)
+
+## Handling Spec Changes
+
+**Detection**: Fetch updated spec → compare with plan → identify new requirements → assess impact
+**Propagation**: Update plan → create new tasks → update affected tasks → add change note → notify via comments
+**Change Log**: Track spec evolution with date, what changed, and impact
+
+## Common Patterns
+
+**Feature Flag**: Backend (behind flag) → Testing → Frontend (flagged) → Internal rollout → External rollout
+**Database Migration**: Schema design → Migration script → Staging test → Production migration → Validation
+**API Development**: API design → Backend implementation → Testing & docs → Client integration → Deployment
+
+
+## Best Practices
+
+1. **Always link spec and implementation**: Maintain bidirectional references
+2. **Break down into small tasks**: Each task should be completable in 1-2 days
+3. **Extract clear acceptance criteria**: Know when "done" is done
+4. **Identify dependencies early**: Note blockers in plan
+5. **Update progress regularly**: Daily notes for active work
+6. **Track changes**: Document spec updates and their impact
+7. **Use checklists**: Visual progress indicators help everyone
+8. **Link deliverables**: PRs, designs, docs should link back to tasks
+
+## Advanced Features
+
+For additional implementation patterns and techniques, see the reference files in [reference/](reference/).
+
+## Common Issues
+
+**"Can't find spec"**: Use Notion:notion-search with spec name/topic, try broader terms, or ask user for URL
+**"Multiple specs found"**: Ask user which spec to implement or show options
+**"Can't find task database"**: Search for "Tasks" or "Task Management", or ask user for database location
+**"Spec unclear"**: Note ambiguities in plan, create clarification tasks
+**"Requirements conflicting"**: Document conflicts, create decision task
+**"Scope too large"**: Break into smaller specs/phases
+
+## Examples
+
+See [examples/](examples/) for complete workflows:
+- [examples/api-feature.md](examples/api-feature.md) - API feature implementation
+- [examples/ui-component.md](examples/ui-component.md) - Frontend component
+- [examples/database-migration.md](examples/database-migration.md) - Schema changes
+

official-skills/notion-spec-to-implementation/evaluations/README.md

@@ -0,0 +1,120 @@
+# Spec to Implementation Skill Evaluations
+
+Evaluation scenarios for testing the Spec to Implementation skill across different Claude models.
+
+## Purpose
+
+These evaluations ensure the Spec to Implementation skill:
+- Finds and parses specification pages accurately
+- Breaks down specs into actionable implementation plans
+- Creates tasks that Claude can implement with clear acceptance criteria
+- Tracks progress and updates implementation status
+- Works consistently across Haiku, Sonnet, and Opus
+
+## Evaluation Files
+
+### basic-spec-implementation.json
+Tests basic workflow of turning a spec into an implementation plan.
+
+**Scenario**: Implement user authentication feature from spec  
+**Key Behaviors**:
+- Searches for and finds the authentication spec page
+- Fetches spec and extracts requirements
+- Parses requirements into phases (setup, core features, polish)
+- Creates implementation plan page linked to original spec
+- Breaks down into clear phases with deliverables
+- Includes timeline and dependencies
+
+### spec-to-tasks.json
+Tests creating concrete tasks from a specification in a task database.
+
+**Scenario**: Create tasks from API redesign spec  
+**Key Behaviors**:
+- Finds spec page in Notion
+- Extracts specific requirements and acceptance criteria
+- Searches for or creates task database
+- Fetches task database schema
+- Creates multiple tasks with proper properties (Status, Priority, Sprint, etc.)
+- Each task has clear title, description, and acceptance criteria
+- Tasks have dependencies where appropriate
+- Links all tasks back to original spec
+
+## Running Evaluations
+
+1. Enable the `spec-to-implementation` skill
+2. Submit the query from the evaluation file
+3. Verify the skill finds the spec page via search
+4. Check that requirements are accurately parsed
+5. Confirm implementation plan is created with phases
+6. Verify tasks have clear, implementable acceptance criteria
+7. Check that tasks link back to spec
+8. Test with Haiku, Sonnet, and Opus
+
+## Expected Skill Behaviors
+
+Spec to Implementation evaluations should verify:
+
+### Spec Discovery & Parsing
+- Searches Notion for specification pages
+- Fetches complete spec content
+- Extracts all requirements accurately
+- Identifies technical dependencies
+- Understands acceptance criteria
+- Notes any ambiguities or missing details
+
+### Implementation Planning
+- Creates implementation plan page
+- Breaks work into logical phases:
+  - Phase 1: Foundation/Setup
+  - Phase 2: Core Implementation
+  - Phase 3: Testing & Polish
+- Includes timeline estimates
+- Identifies dependencies between phases
+- Links back to original spec
+
+### Task Creation
+- Finds or identifies task database
+- Fetches database schema for property names
+- Creates tasks with correct properties
+- Each task has:
+  - Clear, specific title
+  - Context and description
+  - Acceptance criteria (checklist format)
+  - Appropriate priority and status
+  - Link to spec page
+- Tasks are right-sized (not too big, not too small)
+- Dependencies between tasks are noted
+
+### Progress Tracking
+- Implementation plan includes progress markers
+- Tasks can be updated as work progresses
+- Status updates link to completed work
+- Blockers or changes are noted
+
+## Creating New Evaluations
+
+When adding Spec to Implementation evaluations:
+
+1. **Test different spec types** - Features, migrations, refactors, API changes, UI components
+2. **Vary complexity** - Simple 1-phase vs. complex multi-phase implementations
+3. **Test task granularity** - Does it create appropriately-sized tasks?
+4. **Include edge cases** - Vague specs, conflicting requirements, missing details
+5. **Test database integration** - Creating tasks in existing task databases with various schemas
+6. **Progress tracking** - Updating implementation plans as tasks complete
+
+## Example Success Criteria
+
+**Good** (specific, testable):
+- "Searches Notion for spec page using feature name"
+- "Creates implementation plan with 3 phases: Setup → Core → Polish"
+- "Creates 5-8 tasks in task database with properties: Task (title), Status, Priority, Sprint"
+- "Each task has acceptance criteria in checklist format (- [ ] ...)"
+- "Tasks link back to spec using mention-page tag"
+- "Task titles are specific and actionable (e.g., 'Create login API endpoint' not 'Authentication')"
+
+**Bad** (vague, untestable):
+- "Creates good implementation plan"
+- "Tasks are well-structured"
+- "Breaks down spec appropriately"
+- "Links to spec"
+

official-skills/notion-spec-to-implementation/evaluations/basic-spec-implementation.json

@@ -0,0 +1,32 @@
+{
+  "name": "Create Implementation Plan from Spec",
+  "skills": ["spec-to-implementation"],
+  "query": "Create an implementation plan for the User Authentication spec page",
+  "expected_behavior": [
+    "Step 1: Uses Notion:notion-search to find 'User Authentication spec' with keywords like 'User Authentication' or 'auth spec'",
+    "Step 2: If not found or ambiguous, asks user for spec page URL/ID",
+    "Step 3: Fetches spec page using Notion:notion-fetch with URL/ID from search results",
+    "Step 4: Parses spec using patterns from reference/spec-parsing.md to extract requirements, acceptance criteria, constraints",
+    "Step 5: Identifies functional requirements (user stories, features, workflows) and non-functional requirements (performance, security)",
+    "Step 6: Creates implementation plan following structure from reference/templates.md",
+    "Step 7: Includes sections: Overview, Linked Spec, Requirements Summary, Technical Approach, Implementation Phases",
+    "Step 8: Breaks work into logical phases with Goal, Tasks checklist, Estimated effort per phase",
+    "Step 9: Identifies dependencies and risks from spec content",
+    "Step 10: Links plan back to original spec page using <mention-page url='...'>",
+    "Step 11: Creates plan page using Notion:notion-create-pages with appropriate title (e.g., 'Implementation Plan: User Authentication')",
+    "Step 12: Places plan appropriately (asks user or suggests under project/spec parent)"
+  ],
+  "success_criteria": [
+    "Spec is found using Notion:notion-search before attempting to fetch (or user is asked for URL if not found)",
+    "Spec is fetched using Notion:notion-fetch with correct URL/ID from search results",
+    "Plan includes clear overview and spec link with mention-page tag",
+    "Requirements are extracted from actual spec content (not generic) using spec-parsing patterns",
+    "Work is broken into multiple phases (typically 3-5) following template structure",
+    "Each phase has Goal, Tasks (as checkboxes), and Estimated effort",
+    "Dependencies and risks sections are included with specific details from spec",
+    "Plan follows Implementation Plan structure from reference/templates.md",
+    "Success criteria or acceptance criteria from spec are referenced in plan",
+    "Uses correct tool names and sequence: Notion:notion-search → Notion:notion-fetch → Notion:notion-create-pages"
+  ]
+}
+

official-skills/notion-spec-to-implementation/evaluations/spec-to-tasks.json

@@ -0,0 +1,35 @@
+{
+  "name": "Create Tasks from Specification",
+  "skills": ["spec-to-implementation", "task-manager"],
+  "query": "Read the Payment Integration spec and create implementation tasks in our Tasks database",
+  "expected_behavior": [
+    "Step 1: Uses Notion:notion-search to find Payment Integration spec or asks for URL",
+    "Step 2: Fetches spec page using Notion:notion-fetch to read full content",
+    "Step 3: Parses spec using reference/spec-parsing.md patterns to identify work items",
+    "Step 4: Breaks down into appropriately-sized tasks using breakdown patterns from reference/task-creation.md",
+    "Step 5: Uses Notion:notion-search to find Tasks database location",
+    "Step 6: Fetches Tasks database using Notion:notion-fetch to get schema, property names, and data sources",
+    "Step 7: Identifies correct data source from <data-source> tags in fetch results",
+    "Step 8: Optionally creates implementation plan page first (recommended per workflow)",
+    "Step 9: For each task - creates task page using Notion:notion-create-pages with parent: { data_source_id: 'collection://...' }",
+    "Step 10: Sets task properties from schema: Title, Status (To Do), Priority, Related Tasks (link to spec)",
+    "Step 11: Includes task description with context, acceptance criteria from spec, dependencies",
+    "Step 12: Links tasks to spec page using <mention-page> and to each other for dependencies",
+    "Step 13: Sequences tasks appropriately (setup → implementation → testing per reference/task-creation.md)",
+    "Step 14: Reports summary: 'Created X tasks for Payment Integration: [task list with links]'"
+  ],
+  "success_criteria": [
+    "Spec is found using Notion:notion-search before attempting to fetch",
+    "Task database is found using Notion:notion-search before attempting to fetch schema",
+    "Database schema is fetched and data source identified from <data-source> tags",
+    "Multiple tasks created (at least 3-5) covering spec scope",
+    "Tasks are right-sized per reference/task-creation.md (1-2 days each)",
+    "Each task has clear acceptance criteria extracted from spec",
+    "Tasks are properly sequenced with dependencies using relation properties",
+    "All tasks link back to original spec using mention-page tags",
+    "Task properties match exact schema from fetched database",
+    "Tasks use correct parent (data_source_id: 'collection://...') for database placement",
+    "Uses correct tool names and sequence: Notion:notion-search (2x) → Notion:notion-fetch (2x) → Notion:notion-create-pages (Nx)"
+  ]
+}
+

official-skills/notion-spec-to-implementation/examples/api-feature.md

@@ -0,0 +1,461 @@
+# Example: API Feature Implementation
+
+## User Request
+
+> "Create an implementation plan for the User Profile API spec"
+
+## Workflow Execution
+
+### Step 1: Fetch Specification
+
+```
+Notion:notion-search
+query: "User Profile API spec"
+query_type: "internal"
+```
+
+Found: "User Profile API Specification" in Engineering Specs
+
+```
+Notion:notion-fetch
+id: "user-profile-api-spec-page-id"
+```
+
+### Step 2: Parse Specification
+
+**Spec Content Extracted:**
+
+```markdown
+# User Profile API Specification
+
+## Overview
+RESTful API for user profile management
+
+## Requirements
+
+### Functional
+- FR-1: Get user profile by ID
+- FR-2: Update user profile (name, bio, avatar)
+- FR-3: Upload profile avatar
+- FR-4: Get user's public profile (limited fields)
+- FR-5: Search users by name
+
+### Non-Functional
+- NFR-1: Response time < 200ms (p95)
+- NFR-2: Support 1000 concurrent users
+- NFR-3: Avatar upload < 5MB
+- NFR-4: GDPR compliant (data portability)
+
+## API Endpoints
+
+GET /api/v1/users/:id
+PUT /api/v1/users/:id
+POST /api/v1/users/:id/avatar
+GET /api/v1/users/:id/public
+GET /api/v1/users/search
+
+## Data Model
+- id (UUID)
+- email (string, unique)
+- name (string)
+- bio (text, max 500 chars)
+- avatar_url (string)
+- created_at (timestamp)
+- updated_at (timestamp)
+
+## Security
+- Authentication: JWT bearer token
+- Authorization: Users can only update own profile
+- Rate limiting: 100 req/min per user
+
+## Acceptance Criteria
+- AC-1: All endpoints return proper HTTP status codes
+- AC-2: Validation errors return 400 with error details
+- AC-3: Unauthorized access returns 401
+- AC-4: Rate limit exceeded returns 429
+- AC-5: Avatar images stored in S3
+```
+
+### Step 3: Create Implementation Plan
+
+```
+Notion:notion-create-pages
+
+parent: { page_id: "engineering-plans-parent-id" }
+
+pages: [{
+  properties: {
+    "title": "Implementation Plan: User Profile API"
+  },
+  content: "[Implementation plan]"
+}]
+```
+
+**Implementation Plan Created:**
+
+```markdown
+# Implementation Plan: User Profile API
+
+## Overview
+Build RESTful API for user profile management with CRUD operations, avatar upload, and search functionality.
+
+## Linked Specification
+<mention-page url="...">User Profile API Specification</mention-page>
+
+## Requirements Summary
+
+### Functional Requirements
+- ✅ Get user profile (authenticated)
+- ✅ Update profile fields (name, bio)
+- ✅ Upload avatar with image processing
+- ✅ Public profile view (limited fields)
+- ✅ User search by name
+
+### Non-Functional Requirements
+- **Performance**: < 200ms response time (p95)
+- **Scalability**: 1000 concurrent users
+- **Storage**: Avatar files < 5MB to S3
+- **Compliance**: GDPR data portability
+
+### Acceptance Criteria
+- All endpoints with proper status codes
+- Input validation with error details
+- JWT authentication required
+- Rate limiting enforced
+- Avatars stored in S3
+
+## Technical Approach
+
+### Architecture
+- **Framework**: Express.js (Node.js)
+- **Database**: PostgreSQL
+- **Storage**: AWS S3 for avatars
+- **Cache**: Redis for profile data
+- **Search**: PostgreSQL full-text search
+
+### Key Design Decisions
+1. **JWT Authentication**: Stateless auth, scales horizontally
+2. **S3 for Avatars**: Offload storage, CDN integration ready
+3. **Redis Caching**: Reduce DB load for frequently accessed profiles
+4. **Rate Limiting**: Token bucket algorithm, per-user limits
+
+## Implementation Phases
+
+### Phase 1: Foundation (Days 1-2)
+**Goal**: Set up core infrastructure
+
+**Tasks**:
+- [ ] <mention-page url="...">Setup database schema</mention-page>
+- [ ] <mention-page url="...">Configure S3 bucket</mention-page>
+- [ ] <mention-page url="...">Setup Redis cache</mention-page>
+- [ ] <mention-page url="...">Create API scaffolding</mention-page>
+
+**Deliverables**: Working skeleton with DB, storage, cache ready  
+**Estimated effort**: 2 days
+
+### Phase 2: Core Endpoints (Days 3-5)
+**Goal**: Implement main CRUD operations
+
+**Tasks**:
+- [ ] <mention-page url="...">Implement GET user profile</mention-page>
+- [ ] <mention-page url="...">Implement PUT update profile</mention-page>
+- [ ] <mention-page url="...">Add input validation</mention-page>
+- [ ] <mention-page url="...">Add JWT authentication middleware</mention-page>
+- [ ] <mention-page url="...">Implement rate limiting</mention-page>
+
+**Deliverables**: Working CRUD operations with auth  
+**Estimated effort**: 3 days
+
+### Phase 3: Avatar Upload (Days 6-7)
+**Goal**: Avatar management with S3
+
+**Tasks**:
+- [ ] <mention-page url="...">Implement avatar upload endpoint</mention-page>
+- [ ] <mention-page url="...">Add image validation (size, format)</mention-page>
+- [ ] <mention-page url="...">Process and resize images</mention-page>
+- [ ] <mention-page url="...">Upload to S3 with signed URLs</mention-page>
+
+**Deliverables**: Avatar upload/update functionality  
+**Estimated effort**: 2 days
+
+### Phase 4: Search & Public Profile (Days 8-9)
+**Goal**: Complete remaining features
+
+**Tasks**:
+- [ ] <mention-page url="...">Implement user search</mention-page>
+- [ ] <mention-page url="...">Implement public profile endpoint</mention-page>
+- [ ] <mention-page url="...">Add search indexing</mention-page>
+- [ ] <mention-page url="...">Optimize search queries</mention-page>
+
+**Deliverables**: Search and public profiles working  
+**Estimated effort**: 2 days
+
+### Phase 5: Testing & Optimization (Days 10-12)
+**Goal**: Production-ready quality
+
+**Tasks**:
+- [ ] <mention-page url="...">Write unit tests</mention-page>
+- [ ] <mention-page url="...">Write integration tests</mention-page>
+- [ ] <mention-page url="...">Performance testing</mention-page>
+- [ ] <mention-page url="...">Security audit</mention-page>
+- [ ] <mention-page url="...">API documentation</mention-page>
+
+**Deliverables**: Tested, documented, production-ready API  
+**Estimated effort**: 3 days
+
+## Dependencies
+
+### External Dependencies
+- AWS S3 bucket created ✅
+- Redis instance available ✅
+- PostgreSQL database provisioned ✅
+
+### Internal Dependencies
+- JWT authentication service (exists)
+- User database table (exists)
+- Logging infrastructure (exists)
+
+### Blockers
+None currently
+
+## Risks & Mitigation
+
+### Risk 1: Image Processing Performance
+- **Probability**: Medium
+- **Impact**: Medium
+- **Mitigation**: Use background job queue for processing, return signed upload URL immediately
+
+### Risk 2: S3 Upload Failures
+- **Probability**: Low
+- **Impact**: Medium
+- **Mitigation**: Implement retry logic with exponential backoff, fallback to local storage temporarily
+
+### Risk 3: Rate Limiting Complexity
+- **Probability**: Low
+- **Impact**: Low
+- **Mitigation**: Use proven library (express-rate-limit with Redis store)
+
+### Risk 4: Search Performance
+- **Probability**: Medium
+- **Impact**: Medium
+- **Mitigation**: Add database indexes, consider Elasticsearch if needed later
+
+## Timeline
+
+| Milestone | Target Date | Status |
+|-----------|-------------|--------|
+| Phase 1 Complete | Oct 16 | ⏳ Planned |
+| Phase 2 Complete | Oct 19 | ⏳ Planned |
+| Phase 3 Complete | Oct 21 | ⏳ Planned |
+| Phase 4 Complete | Oct 23 | ⏳ Planned |
+| Phase 5 Complete | Oct 26 | ⏳ Planned |
+| **Production Deploy** | **Oct 28** | ⏳ Planned |
+
+**Total Duration**: 12 working days (~2.5 weeks)
+
+## Success Criteria
+
+### Technical Success
+- [ ] All 5 endpoints implemented and working
+- [ ] Response time < 200ms (p95) verified in load testing
+- [ ] Handles 1000 concurrent users
+- [ ] All acceptance criteria met
+- [ ] Test coverage > 80%
+- [ ] Security scan passed
+- [ ] API documentation complete
+
+### Business Success
+- [ ] User profile updates functional
+- [ ] Avatar uploads working reliably
+- [ ] Search returns relevant results in < 500ms
+- [ ] Zero critical bugs in first week
+
+## Resources
+
+### Documentation
+- <mention-page url="...">User Profile API Specification</mention-page> (original spec)
+- <mention-page url="...">Authentication Service Docs</mention-page>
+- <mention-page url="...">AWS S3 Setup Guide</mention-page>
+
+### Related Work
+- <mention-page url="...">User Authentication API</mention-page> (similar pattern)
+- <mention-page url="...">File Upload Service</mention-page> (avatar upload reference)
+
+### External References
+- Express.js best practices
+- AWS S3 SDK documentation
+- PostgreSQL full-text search guide
+
+## Progress Tracking
+
+### Phase Status
+- Phase 1: ⏳ Not Started
+- Phase 2: ⏳ Not Started
+- Phase 3: ⏳ Not Started
+- Phase 4: ⏳ Not Started
+- Phase 5: ⏳ Not Started
+
+**Overall Progress**: 0% complete
+
+### Latest Update
+*Implementation plan created on October 14, 2025*
+```
+
+### Step 4: Find Task Database
+
+```
+Notion:notion-search
+query: "Tasks database"
+query_type: "internal"
+```
+
+Found: "Engineering Tasks" database
+
+### Step 5: Fetch Task Database Schema
+
+```
+Notion:notion-fetch
+id: "tasks-database-id"
+```
+
+**Schema retrieved:**
+- Data source: `collection://tasks-db-uuid`
+- Properties: Name (title), Status (select), Priority (select), Related Tasks (relation), Story Points (number), Tags (multi_select)
+
+### Step 6: Create Implementation Tasks
+
+Now create tasks for Phase 1:
+
+**Task 1: Setup database schema**
+
+```
+Notion:notion-create-pages
+
+parent: { data_source_id: "collection://tasks-db-uuid" }
+
+pages: [{
+  properties: {
+    "Name": "Setup database schema for User Profile API",
+    "Status": "To Do",
+    "Priority": "High",
+    "Related Tasks": ["impl-plan-page-id", "spec-page-id"],
+    "Story Points": 3,
+    "Tags": "backend, database, api"
+  },
+  content: "## Context\nImplementation task for <mention-page url=\"...\">User Profile API Specification</mention-page>\n\nPart of <mention-page url=\"...\">Implementation Plan: User Profile API</mention-page> - Phase 1\n\n## Objective\nCreate database schema for user profile storage\n\n## Requirements\nBased on spec data model:\n- id (UUID, primary key)\n- email (string, unique index)\n- name (string, not null)\n- bio (text, max 500 chars)\n- avatar_url (string, nullable)\n- created_at (timestamp)\n- updated_at (timestamp)\n\n## Acceptance Criteria\n- [ ] Migration file created\n- [ ] Schema includes all required fields\n- [ ] Indexes on email (unique) and name (search)\n- [ ] Constraints validated (bio length, email format)\n- [ ] Migration tested on dev database\n- [ ] Rollback migration created\n\n## Technical Approach\n```sql\nCREATE TABLE user_profiles (\n  id UUID PRIMARY KEY DEFAULT gen_random_uuid(),\n  email VARCHAR(255) UNIQUE NOT NULL,\n  name VARCHAR(255) NOT NULL,\n  bio TEXT CHECK (length(bio) <= 500),\n  avatar_url TEXT,\n  created_at TIMESTAMP DEFAULT NOW(),\n  updated_at TIMESTAMP DEFAULT NOW()\n);\n\nCREATE INDEX idx_user_profiles_email ON user_profiles(email);\nCREATE INDEX idx_user_profiles_name ON user_profiles USING gin(to_tsvector('english', name));\n```\n\n## Dependencies\n- Blocked By: None\n- Blocks: All Phase 2 tasks\n\n## Estimated Effort\n3 story points (half day)\n"
+}]
+```
+
+*[Create similar tasks for all phases - 20 tasks total]*
+
+### Step 7: Link Plan Back to Spec
+
+```
+Notion:notion-update-page
+page_id: "user-profile-api-spec-page-id"
+command: "insert_content_after"
+selection_with_ellipsis: "## Acceptance Criteria..."
+new_str: "
+
+---
+
+## Implementation
+
+**Implementation Plan**: <mention-page url=\"...\">Implementation Plan: User Profile API</mention-page>
+
+**Implementation Tasks**: See plan for full task breakdown (20 tasks across 5 phases)
+
+**Status**: Planning complete, ready to start implementation
+"
+```
+
+## Summary Provided to User
+
+```markdown
+## Implementation Plan Created ✅
+
+### Plan Overview
+- **Feature**: User Profile API
+- **Duration**: 12 days (~2.5 weeks)
+- **Phases**: 5 (Foundation → Core → Avatar → Search → Testing)
+- **Tasks**: 20 tasks created
+- **Target Launch**: October 28, 2025
+
+### Implementation Phases
+
+**Phase 1: Foundation** (2 days)
+- Database schema
+- S3 and Redis setup
+- API scaffolding
+
+**Phase 2: Core Endpoints** (3 days)
+- GET/PUT user profile
+- Authentication & validation
+- Rate limiting
+
+**Phase 3: Avatar Upload** (2 days)
+- Image upload & validation
+- S3 integration
+- Image processing
+
+**Phase 4: Search & Public Profile** (2 days)
+- User search
+- Public profile endpoint
+
+**Phase 5: Testing & Optimization** (3 days)
+- Unit & integration tests
+- Performance testing
+- Documentation
+
+### Key Deliverables
+- 5 REST API endpoints
+- Avatar upload to S3
+- User search functionality
+- Comprehensive tests
+- API documentation
+
+### Links Created
+✅ Plan page: <mention-page url="...">Implementation Plan: User Profile API</mention-page>
+✅ Spec updated with plan link
+✅ 20 tasks created in task database
+✅ All tasks linked to plan and spec
+
+### Next Steps
+1. Review and approve plan
+2. Assign tasks to team members
+3. Begin Phase 1 (Foundation)
+4. Daily standups for progress tracking
+
+**Ready to start implementation! 🚀**
+```
+
+## Key Features Demonstrated
+
+### Spec Parsing
+- Extracted requirements (functional & non-functional)
+- Identified API endpoints
+- Noted data model
+- Captured acceptance criteria
+- Understood security requirements
+
+### Implementation Planning
+- Broke into logical phases
+- Sequenced work appropriately (foundation → features → testing)
+- Identified dependencies
+- Estimated effort per phase
+- Created realistic timeline
+
+### Task Creation
+- Generated 20 specific tasks
+- Each task has context, acceptance criteria, technical approach
+- Tasks link to both spec and plan
+- Proper dependencies noted
+
+### Bidirectional Linking
+- Plan links to spec
+- Spec updated to link to plan
+- Tasks link to both
+- Easy navigation between all artifacts
+
+Perfect for: Feature implementation, API development, technical projects
+

official-skills/notion-spec-to-implementation/examples/database-migration.md

@@ -0,0 +1,81 @@
+# Example: Database Migration Implementation
+
+**User Request**: "Plan and implement the database migration for user preferences schema"
+
+## Workflow
+
+### 1. Find & Fetch Spec
+```
+Notion:notion-search → Found "User Preferences Schema Migration Spec"
+Notion:notion-fetch → Extracted requirements
+```
+
+**Spec Summary**: Migrate from JSON blob to structured schema for better performance and data integrity.
+
+### 2. Parse Requirements
+- **Current**: JSONB preferences column
+- **Target**: Separate `user_preferences` and `notification_preferences` tables
+- **Must maintain**: Backward compatibility during migration
+- **Performance**: Support 1M+ users with zero downtime
+
+### 3. Create Implementation Plan
+```
+Notion:notion-create-pages
+pages: [{
+  properties: {
+    title: "Implementation Plan: User Preferences Migration"
+  },
+  content: "[Full implementation plan with phases]"
+}]
+```
+
+**Plan included**:
+- **Phase 1**: Create new tables with indexes
+- **Phase 2**: Backfill data from JSONB
+- **Phase 3**: Dual-write mode (both old and new)
+- **Phase 4**: Switch reads to new schema
+- **Phase 5**: Drop old JSONB column
+
+### 4. Find Task Database & Create Tasks
+```
+Notion:notion-search → Found "Engineering Tasks" database
+Notion:notion-fetch → Got schema (Task, Status, Priority, Assignee, etc.)
+
+Notion:notion-create-pages
+parent: { data_source_id: "collection://xyz" }
+pages: [
+  {
+    properties: {
+      "Task": "Write migration SQL scripts",
+      "Status": "To Do",
+      "Priority": "High",
+      "Sprint": "Sprint 25"
+    },
+    content: "## Context\nPart of User Preferences Migration...\n\n## Acceptance Criteria\n- [ ] Migration script creates tables\n- [ ] Indexes defined..."
+  },
+  // ... 4 more tasks
+]
+```
+
+**Tasks created**:
+1. Write migration SQL scripts
+2. Implement backfill job
+3. Add dual-write logic to API
+4. Update read queries
+5. Rollback plan & monitoring
+
+### 5. Track Progress
+Regular updates to implementation plan with status, blockers, and completion notes.
+
+## Key Outputs
+
+**Implementation Plan Page** (linked to spec)
+**5 Tasks in Database** (with dependencies, acceptance criteria)
+**Progress Tracking** (updated as work progresses)
+
+## Success Factors
+- Broke down complex migration into clear phases
+- Created tasks with specific acceptance criteria
+- Established dependencies (Phase 1 → 2 → 3 → 4 → 5)
+- Zero-downtime approach with rollback plan
+- Linked all work back to original spec

official-skills/notion-spec-to-implementation/examples/ui-component.md

@@ -0,0 +1,68 @@
+# Example: UI Component Implementation
+
+**User Request**: "Implement the new search component from the design spec"
+
+## Workflow
+
+### 1. Find Spec
+```
+Notion:notion-search
+query: "search component design spec"
+```
+Found: "Global Search Redesign Spec"
+
+### 2. Fetch & Parse Spec
+```
+Notion:notion-fetch
+```
+
+**Requirements**:
+- Instant search with debounced API calls
+- Keyboard navigation (↑↓ arrows, Enter, Esc)
+- Recent searches history
+- Result categories (pages, people, files)
+- Mobile responsive
+- Accessibility (ARIA labels, screen reader)
+
+### 3. Create Implementation Plan
+```
+Notion:notion-create-pages
+```
+
+**Plan phases**:
+- Phase 1: Base component structure
+- Phase 2: API integration & debouncing
+- Phase 3: Keyboard navigation
+- Phase 4: Recent searches
+- Phase 5: Polish & accessibility
+
+### 4. Create Tasks
+```
+Notion:notion-create-pages (7 tasks)
+```
+
+**Tasks**:
+1. Create SearchInput component
+2. Implement useDebounce hook
+3. Add keyboard navigation
+4. LocalStorage for recent searches
+5. Result categorization UI
+6. Accessibility audit
+7. Mobile responsive styling
+
+### 5. Implement & Track
+As each task completed, updated status and added progress notes with screenshots and implementation details.
+
+## Key Outputs
+
+**Implementation Plan** (linked to design spec)
+**7 Component Tasks** (in Engineering Tasks database)
+**Progress Updates** (with code snippets and demo links)
+
+## Success Factors
+- Clear component breakdown
+- Separated concerns (logic, UI, accessibility)
+- Each task had acceptance criteria
+- Referenced design spec throughout
+- Included accessibility from start, not afterthought
+- Tracked progress with visual updates

official-skills/notion-spec-to-implementation/reference/milestone-summary-template.md

@@ -0,0 +1,27 @@
+# Milestone Summary Template
+
+Use this when completing major phases or milestones.
+
+```markdown
+## Phase [N] Complete: [Date]
+
+### Accomplishments
+- [Major item delivered]
+- [Major item delivered]
+
+### Deliverables
+- <mention-page url="...">Deliverable 1</mention-page>
+- [Link to PR/deployment]
+
+### Metrics
+- [Relevant metric]
+- [Relevant metric]
+
+### Learnings
+- [What went well]
+- [What to improve]
+
+### Next Phase
+Starting [Phase name] on [Date]
+```
+

official-skills/notion-spec-to-implementation/reference/progress-tracking.md

@@ -0,0 +1,458 @@
+# Progress Tracking
+
+## Update Frequency
+
+### Daily Updates
+
+For active implementation work:
+
+**What to update**:
+- Task status if changed
+- Add progress note to task
+- Update blockers
+
+**When**:
+- End of work day
+- After completing significant work
+- When encountering blockers
+
+### Milestone Updates
+
+For phase/milestone completion:
+
+**What to update**:
+- Mark phase complete in plan
+- Add milestone summary
+- Update timeline if needed
+- Report to stakeholders
+
+**When**:
+- Phase completion
+- Major deliverable ready
+- Sprint end
+- Release
+
+### Status Change Updates
+
+For task state transitions:
+
+**What to update**:
+- Task status property
+- Add transition note
+- Notify relevant people
+
+**When**:
+- Start work (To Do → In Progress)
+- Ready for review (In Progress → In Review)
+- Complete (In Review → Done)
+- Block (Any → Blocked)
+
+## Progress Note Format
+
+### Daily Progress Note
+
+```markdown
+## Progress: [Date]
+
+### Completed
+- [Specific accomplishment with details]
+- [Specific accomplishment with details]
+
+### In Progress
+- [Current work item]
+- Current status: [Percentage or description]
+
+### Next Steps
+1. [Next planned action]
+2. [Next planned action]
+
+### Blockers
+- [Blocker description and who/what needed to unblock]
+- Or: None
+
+### Decisions Made
+- [Any technical/product decisions]
+
+### Notes
+[Additional context, learnings, issues encountered]
+```
+
+Example:
+
+```markdown
+## Progress: Oct 14, 2025
+
+### Completed
+- Implemented user authentication API endpoints (login, logout, refresh)
+- Added JWT token generation and validation
+- Wrote unit tests for auth service (95% coverage)
+
+### In Progress
+- Frontend login form integration
+- Currently: Form submits but need to handle error states
+
+### Next Steps
+1. Complete error handling in login form
+2. Add loading states
+3. Implement "remember me" functionality
+
+### Blockers
+None
+
+### Decisions Made
+- Using HttpOnly cookies for refresh tokens (more secure than localStorage)
+- Session timeout set to 24 hours based on security review
+
+### Notes
+- Found edge case with concurrent login attempts, added to backlog
+- Performance of auth check is good (<10ms)
+```
+
+### Milestone Summary
+
+```markdown
+## Phase [N] Complete: [Date]
+
+### Overview
+[Brief description of what was accomplished in this phase]
+
+### Completed Tasks
+- <mention-page url="...">Task 1</mention-page> ✅
+- <mention-page url="...">Task 2</mention-page> ✅
+- <mention-page url="...">Task 3</mention-page> ✅
+
+### Deliverables
+- [Deliverable 1]: [Link/description]
+- [Deliverable 2]: [Link/description]
+
+### Key Accomplishments
+- [Major achievement]
+- [Major achievement]
+
+### Metrics
+- [Relevant metric]: [Value]
+- [Relevant metric]: [Value]
+
+### Challenges Overcome
+- [Challenge and how it was solved]
+
+### Learnings
+**What went well**:
+- [Success factor]
+
+**What to improve**:
+- [Area for improvement]
+
+### Impact on Timeline
+- On schedule / [X days ahead/behind]
+- Reason: [If deviation, explain why]
+
+### Next Phase
+- **Starting**: [Next phase name]
+- **Target start date**: [Date]
+- **Focus**: [Main objectives]
+```
+
+## Updating Implementation Plan
+
+### Progress Indicators
+
+Update plan page regularly:
+
+```markdown
+## Status Overview
+
+**Overall Progress**: 45% complete
+
+### Phase Status
+- ✅ Phase 1: Foundation - Complete
+- 🔄 Phase 2: Core Features - In Progress (60%)
+- ⏳ Phase 3: Integration - Not Started
+
+### Task Summary
+- ✅ Completed: 12 tasks
+- 🔄 In Progress: 5 tasks
+- 🚧 Blocked: 1 task
+- ⏳ Not Started: 8 tasks
+
+**Last Updated**: [Date]
+```
+
+### Task Checklist Updates
+
+Mark completed tasks:
+
+```markdown
+## Implementation Phases
+
+### Phase 1: Foundation
+- [x] <mention-page url="...">Database schema</mention-page>
+- [x] <mention-page url="...">API scaffolding</mention-page>
+- [x] <mention-page url="...">Auth setup</mention-page>
+
+### Phase 2: Core Features
+- [x] <mention-page url="...">User management</mention-page>
+- [ ] <mention-page url="...">Dashboard</mention-page>
+- [ ] <mention-page url="...">Reporting</mention-page>
+```
+
+### Timeline Updates
+
+Update milestone dates:
+
+```markdown
+## Timeline
+
+| Milestone | Original | Current | Status |
+|-----------|----------|---------|--------|
+| Phase 1 | Oct 15 | Oct 14 | ✅ Complete (1 day early) |
+| Phase 2 | Oct 30 | Nov 2 | 🔄 In Progress (3 days delay) |
+| Phase 3 | Nov 15 | Nov 18 | ⏳ Planned (adjusted) |
+| Launch | Nov 20 | Nov 22 | ⏳ Planned (adjusted) |
+
+**Timeline Status**: Slightly behind due to [reason]
+```
+
+## Task Status Tracking
+
+### Status Definitions
+
+**To Do**: Not started
+- Task is ready to begin
+- Dependencies met
+- Assigned (or available)
+
+**In Progress**: Actively being worked
+- Work has started
+- Assigned to someone
+- Regular updates expected
+
+**Blocked**: Cannot proceed
+- Dependency not met
+- External blocker
+- Waiting on decision/resource
+
+**In Review**: Awaiting review
+- Work complete from implementer perspective
+- Needs code review, QA, or approval
+- Reviewers identified
+
+**Done**: Complete
+- All acceptance criteria met
+- Reviewed and approved
+- Deployed/delivered
+
+### Updating Task Status
+
+When updating:
+
+```
+1. Update Status property
+2. Add progress note explaining change
+3. Update related tasks if needed
+4. Notify relevant people via comment
+
+Example:
+properties: { "Status": "In Progress" }
+
+Content update:
+## Progress: Oct 14, 2025
+Started implementation. Set up basic structure and wrote initial tests.
+```
+
+## Blocker Tracking
+
+### Recording Blockers
+
+When encountering a blocker:
+
+```markdown
+## Blockers
+
+### [Date]: [Blocker Description]
+**Status**: 🚧 Active
+**Impact**: [What's blocked]
+**Needed to unblock**: [Action/person/decision needed]
+**Owner**: [Who's responsible for unblocking]
+**Target resolution**: [Date or timeframe]
+```
+
+### Resolving Blockers
+
+When unblocked:
+
+```markdown
+## Blockers
+
+### [Date]: [Blocker Description]
+**Status**: ✅ Resolved on [Date]
+**Resolution**: [How it was resolved]
+**Impact**: [Any timeline/scope impact]
+```
+
+### Escalating Blockers
+
+If blocker needs escalation:
+
+```
+1. Update blocker status in task
+2. Add comment tagging stakeholder
+3. Update plan with blocker impact
+4. Propose mitigation if possible
+```
+
+## Metrics Tracking
+
+### Velocity Tracking
+
+Track completion rate:
+
+```markdown
+## Velocity
+
+### Week 1
+- Tasks completed: 8
+- Story points: 21
+- Velocity: Strong
+
+### Week 2
+- Tasks completed: 6
+- Story points: 18
+- Velocity: Moderate (1 blocker)
+
+### Week 3
+- Tasks completed: 9
+- Story points: 24
+- Velocity: Strong (blocker resolved)
+```
+
+### Quality Metrics
+
+Track quality indicators:
+
+```markdown
+## Quality Metrics
+
+- Test coverage: 87%
+- Code review approval rate: 95%
+- Bug count: 3 (2 minor, 1 cosmetic)
+- Performance: All targets met
+- Security: No issues found
+```
+
+### Progress Metrics
+
+Quantitative progress:
+
+```markdown
+## Progress Metrics
+
+- Requirements implemented: 15/20 (75%)
+- Acceptance criteria met: 42/56 (75%)
+- Test cases passing: 128/135 (95%)
+- Code complete: 80%
+- Documentation: 60%
+```
+
+## Stakeholder Communication
+
+### Weekly Status Report
+
+```markdown
+## Weekly Status: [Week of Date]
+
+### Summary
+[One paragraph overview of progress and status]
+
+### This Week's Accomplishments
+- [Key accomplishment]
+- [Key accomplishment]
+- [Key accomplishment]
+
+### Next Week's Plan
+- [Planned work]
+- [Planned work]
+
+### Status
+- On track / At risk / Behind schedule
+- [If at risk or behind, explain and provide mitigation plan]
+
+### Blockers & Needs
+- [Active blocker or need for help]
+- Or: None
+
+### Risks
+- [New or evolving risk]
+- Or: None currently identified
+```
+
+### Executive Summary
+
+For leadership updates:
+
+```markdown
+## Implementation Status: [Feature Name]
+
+**Overall Status**: 🟢 On Track / 🟡 At Risk / 🔴 Behind
+
+**Progress**: [X]% complete
+
+**Key Updates**:
+- [Most important update]
+- [Most important update]
+
+**Timeline**: [Status vs original plan]
+
+**Risks**: [Top 1-2 risks]
+
+**Next Milestone**: [Upcoming milestone and date]
+```
+
+## Automated Progress Tracking
+
+### Query-Based Status
+
+Generate status from task database:
+
+```
+Query task database:
+SELECT 
+  "Status",
+  COUNT(*) as count
+FROM "collection://tasks-uuid"
+WHERE "Related Tasks" CONTAINS 'plan-page-id'
+GROUP BY "Status"
+
+Generate summary:
+- To Do: 8
+- In Progress: 5
+- Blocked: 1
+- In Review: 2
+- Done: 12
+
+Overall: 44% complete (12/28 tasks)
+```
+
+### Timeline Calculation
+
+Calculate projected completion:
+
+```
+Average velocity: 6 tasks/week
+Remaining tasks: 14
+Projected completion: 2.3 weeks from now
+
+Compares to target: [On schedule/Behind/Ahead]
+```
+
+## Best Practices
+
+1. **Update regularly**: Don't let updates pile up
+2. **Be specific**: "Completed login" vs "Made progress"
+3. **Quantify progress**: Use percentages, counts, metrics
+4. **Note blockers immediately**: Don't wait to report blockers
+5. **Link to work**: Reference PRs, deployments, demos
+6. **Track decisions**: Document why, not just what
+7. **Be honest**: Report actual status, not optimistic status
+8. **Update in one place**: Keep implementation plan as source of truth
+

official-skills/notion-spec-to-implementation/reference/progress-update-template.md

@@ -0,0 +1,25 @@
+# Progress Update Template
+
+Use this to update progress on implementation plans and tasks.
+
+```markdown
+## Progress: [Date]
+
+### Completed Today
+- [Specific item completed]
+- [Specific item completed]
+
+### In Progress
+- [Current work item and status]
+
+### Next Steps
+1. [Next action]
+2. [Next action]
+
+### Blockers
+- [Blocker description] or None
+
+### Notes
+[Additional context, decisions made, issues encountered]
+```
+

official-skills/notion-spec-to-implementation/reference/quick-implementation-plan.md

@@ -0,0 +1,26 @@
+# Quick Implementation Plan Template
+
+For simpler features or small changes.
+
+```markdown
+# Implementation: [Feature Name]
+
+## Spec
+<mention-page url="...">Specification</mention-page>
+
+## Summary
+[Quick description]
+
+## Tasks
+- [ ] <mention-page url="...">Task 1</mention-page>
+- [ ] <mention-page url="...">Task 2</mention-page>
+- [ ] <mention-page url="...">Task 3</mention-page>
+
+## Timeline
+Start: [Date]
+Target completion: [Date]
+
+## Status
+[Update as work progresses]
+```
+

official-skills/notion-spec-to-implementation/reference/spec-parsing.md

@@ -0,0 +1,383 @@
+# Specification Parsing
+
+## Finding the Specification
+
+Before parsing, locate the spec page:
+
+```
+1. Search for spec:
+   Notion:notion-search
+   query: "[Feature Name] spec" or "[Feature Name] specification"
+   
+2. Handle results:
+   - If found → use page URL/ID
+   - If multiple → ask user which one
+   - If not found → ask user for URL/ID
+
+Example:
+Notion:notion-search
+query: "User Profile API spec"
+query_type: "internal"
+```
+
+## Reading Specifications
+
+After finding the spec, fetch it with `Notion:notion-fetch`:
+
+1. Read the full content
+2. Identify key sections
+3. Extract structured information
+4. Note ambiguities or gaps
+
+```
+Notion:notion-fetch
+id: "spec-page-id-from-search"
+```
+
+## Common Spec Structures
+
+### Requirements-Based Spec
+
+```
+# Feature Spec
+## Overview
+[Feature description]
+
+## Requirements
+### Functional
+- REQ-1: [Requirement]
+- REQ-2: [Requirement]
+
+### Non-Functional
+- PERF-1: [Performance requirement]
+- SEC-1: [Security requirement]
+
+## Acceptance Criteria
+- AC-1: [Criterion]
+- AC-2: [Criterion]
+```
+
+Extract:
+- List of functional requirements
+- List of non-functional requirements
+- List of acceptance criteria
+
+### User Story Based Spec
+
+```
+# Feature Spec
+## User Stories
+### As a [user type]
+I want [goal]
+So that [benefit]
+
+**Acceptance Criteria**:
+- [Criterion]
+- [Criterion]
+```
+
+Extract:
+- User personas
+- Goals/capabilities needed
+- Acceptance criteria per story
+
+### Technical Design Doc
+
+```
+# Technical Design
+## Problem Statement
+[Problem description]
+
+## Proposed Solution
+[Solution approach]
+
+## Architecture
+[Architecture details]
+
+## Implementation Plan
+[Implementation approach]
+```
+
+Extract:
+- Problem being solved
+- Proposed solution approach
+- Architectural decisions
+- Implementation guidance
+
+### Product Requirements Document (PRD)
+
+```
+# PRD: [Feature]
+## Goals
+[Business goals]
+
+## User Needs
+[User problems being solved]
+
+## Features
+[Feature list]
+
+## Success Metrics
+[How to measure success]
+```
+
+Extract:
+- Business goals
+- User needs
+- Feature list
+- Success metrics
+
+## Extraction Strategies
+
+### Requirement Identification
+
+Look for:
+- "Must", "Should", "Will" statements
+- Numbered requirements (REQ-1, etc.)
+- User stories (As a... I want...)
+- Acceptance criteria sections
+- Feature lists
+
+### Categorization
+
+Group requirements by:
+
+**Functional**: What the system does
+- User capabilities
+- System behaviors
+- Data operations
+
+**Non-Functional**: How the system performs
+- Performance targets
+- Security requirements
+- Scalability needs
+- Availability requirements
+- Compliance requirements
+
+**Constraints**: Limitations
+- Technical constraints
+- Business constraints
+- Timeline constraints
+
+### Priority Extraction
+
+Identify priority indicators:
+- "Critical", "Must have", "P0"
+- "Important", "Should have", "P1"
+- "Nice to have", "Could have", "P2"
+- "Future", "Won't have", "P3"
+
+Map to implementation phases based on priority.
+
+## Handling Ambiguity
+
+### Unclear Requirements
+
+When requirement is ambiguous:
+
+```markdown
+## Clarifications Needed
+
+### [Requirement ID/Description]
+**Current text**: "[Ambiguous requirement]"
+**Question**: [What needs clarification]
+**Impact**: [Why this matters for implementation]
+**Assumed for now**: [Working assumption if any]
+```
+
+Create clarification task or add comment to spec.
+
+### Missing Information
+
+When critical info is missing:
+
+```markdown
+## Missing Information
+
+- **[Topic]**: Spec doesn't specify [what's missing]
+- **Impact**: Blocks [affected tasks]
+- **Action**: Need to [how to resolve]
+```
+
+### Conflicting Requirements
+
+When requirements conflict:
+
+```markdown
+## Conflicting Requirements
+
+**Conflict**: REQ-1 says [X] but REQ-5 says [Y]
+**Impact**: [Implementation impact]
+**Resolution needed**: [Decision needed]
+```
+
+## Acceptance Criteria Parsing
+
+### Explicit Criteria
+
+Direct acceptance criteria:
+
+```
+## Acceptance Criteria
+- User can log in with email and password
+- System sends confirmation email
+- Session expires after 24 hours
+```
+
+Convert to checklist:
+- [ ] User can log in with email and password
+- [ ] System sends confirmation email
+- [ ] Session expires after 24 hours
+
+### Implicit Criteria
+
+Derive from requirements:
+
+```
+Requirement: "Users can upload files up to 100MB"
+
+Implied acceptance criteria:
+- [ ] Files up to 100MB upload successfully
+- [ ] Files over 100MB are rejected with error message
+- [ ] Progress indicator shows during upload
+- [ ] Upload can be cancelled
+```
+
+### Testable Criteria
+
+Ensure criteria are testable:
+
+❌ **Not testable**: "System is fast"
+✓ **Testable**: "Page loads in < 2 seconds"
+
+❌ **Not testable**: "Users like the interface"
+✓ **Testable**: "90% of test users complete task successfully"
+
+## Technical Detail Extraction
+
+### Architecture Information
+
+Extract:
+- System components
+- Data models
+- APIs/interfaces
+- Integration points
+- Technology choices
+
+### Design Decisions
+
+Note:
+- Technology selections
+- Architecture patterns
+- Trade-offs made
+- Rationale provided
+
+### Implementation Guidance
+
+Look for:
+- Suggested approach
+- Code examples
+- Library recommendations
+- Best practices mentioned
+
+## Dependency Identification
+
+### External Dependencies
+
+From spec, identify:
+- Third-party services required
+- External APIs needed
+- Infrastructure requirements
+- Tool/library dependencies
+
+### Internal Dependencies
+
+Identify:
+- Other features needed first
+- Shared components required
+- Team dependencies
+- Data dependencies
+
+### Timeline Dependencies
+
+Note:
+- Hard deadlines
+- Milestone dependencies
+- Sequencing requirements
+
+## Scope Extraction
+
+### In Scope
+
+What's explicitly included:
+- Features to build
+- Use cases to support
+- Users/personas to serve
+
+### Out of Scope
+
+What's explicitly excluded:
+- Features deferred
+- Use cases not supported
+- Edge cases not handled
+
+### Assumptions
+
+What's assumed:
+- Environment assumptions
+- User assumptions
+- System state assumptions
+
+## Risk Identification
+
+Extract risk information:
+
+### Technical Risks
+- Unproven technology
+- Complex integration
+- Performance concerns
+- Scalability unknowns
+
+### Business Risks
+- Market timing
+- Resource availability
+- Dependency on others
+
+### Mitigation Strategies
+
+Note any mitigation approaches mentioned in spec.
+
+## Spec Quality Assessment
+
+Evaluate spec completeness:
+
+✓ **Good spec**:
+- Clear requirements
+- Explicit acceptance criteria
+- Priorities defined
+- Risks identified
+- Technical approach outlined
+
+⚠️ **Incomplete spec**:
+- Vague requirements
+- Missing acceptance criteria
+- Unclear priorities
+- No risk analysis
+- Technical details absent
+
+Document gaps and create clarification tasks.
+
+## Parsing Checklist
+
+Before creating implementation plan:
+
+☐ All functional requirements identified
+☐ Non-functional requirements noted
+☐ Acceptance criteria extracted
+☐ Dependencies identified
+☐ Risks noted
+☐ Ambiguities documented
+☐ Technical approach understood
+☐ Scope is clear
+☐ Priorities are defined
+

official-skills/notion-spec-to-implementation/reference/standard-implementation-plan.md

@@ -0,0 +1,146 @@
+# Standard Implementation Plan Template
+
+Use this template for most feature implementations.
+
+```markdown
+# Implementation Plan: [Feature Name]
+
+## Overview
+[1-2 sentence feature description and business value]
+
+## Linked Specification
+<mention-page url="...">Original Specification</mention-page>
+
+## Requirements Summary
+
+### Functional Requirements
+- [Requirement 1]
+- [Requirement 2]
+- [Requirement 3]
+
+### Non-Functional Requirements
+- **Performance**: [Targets]
+- **Security**: [Requirements]
+- **Scalability**: [Needs]
+
+### Acceptance Criteria
+- [ ] [Criterion 1]
+- [ ] [Criterion 2]
+- [ ] [Criterion 3]
+
+## Technical Approach
+
+### Architecture
+[High-level architectural decisions]
+
+### Technology Stack
+- Backend: [Technologies]
+- Frontend: [Technologies]
+- Infrastructure: [Technologies]
+
+### Key Design Decisions
+1. **[Decision]**: [Rationale]
+2. **[Decision]**: [Rationale]
+
+## Implementation Phases
+
+### Phase 1: Foundation (Week 1)
+**Goal**: Set up core infrastructure
+
+**Tasks**:
+- [ ] <mention-page url="...">Database schema design</mention-page>
+- [ ] <mention-page url="...">API scaffolding</mention-page>
+- [ ] <mention-page url="...">Authentication setup</mention-page>
+
+**Deliverables**: Working API skeleton
+**Estimated effort**: 3 days
+
+### Phase 2: Core Features (Week 2-3)
+**Goal**: Implement main functionality
+
+**Tasks**:
+- [ ] <mention-page url="...">Feature A implementation</mention-page>
+- [ ] <mention-page url="...">Feature B implementation</mention-page>
+
+**Deliverables**: Core features working
+**Estimated effort**: 1 week
+
+### Phase 3: Integration & Polish (Week 4)
+**Goal**: Complete integration and refinement
+
+**Tasks**:
+- [ ] <mention-page url="...">Frontend integration</mention-page>
+- [ ] <mention-page url="...">Testing & QA</mention-page>
+
+**Deliverables**: Production-ready feature
+**Estimated effort**: 1 week
+
+## Dependencies
+
+### External Dependencies
+- [Dependency 1]: [Status]
+- [Dependency 2]: [Status]
+
+### Internal Dependencies
+- [Team/component dependency]
+
+### Blockers
+- [Known blocker] or None currently
+
+## Risks & Mitigation
+
+### Risk 1: [Description]
+- **Probability**: High/Medium/Low
+- **Impact**: High/Medium/Low
+- **Mitigation**: [Strategy]
+
+### Risk 2: [Description]
+- **Probability**: High/Medium/Low
+- **Impact**: High/Medium/Low
+- **Mitigation**: [Strategy]
+
+## Timeline
+
+| Milestone | Target Date | Status |
+|-----------|-------------|--------|
+| Phase 1 Complete | [Date] | ⏳ Planned |
+| Phase 2 Complete | [Date] | ⏳ Planned |
+| Phase 3 Complete | [Date] | ⏳ Planned |
+| Launch | [Date] | ⏳ Planned |
+
+## Success Criteria
+
+### Technical Success
+- [ ] All acceptance criteria met
+- [ ] Performance targets achieved
+- [ ] Security requirements satisfied
+- [ ] Test coverage > 80%
+
+### Business Success
+- [ ] [Business metric 1]
+- [ ] [Business metric 2]
+
+## Resources
+
+### Documentation
+- <mention-page url="...">Design Doc</mention-page>
+- <mention-page url="...">API Spec</mention-page>
+
+### Related Work
+- <mention-page url="...">Related Feature</mention-page>
+
+## Progress Tracking
+
+[This section updated regularly]
+
+### Phase Status
+- Phase 1: ⏳ Not Started
+- Phase 2: ⏳ Not Started
+- Phase 3: ⏳ Not Started
+
+**Overall Progress**: 0% complete
+
+### Latest Update: [Date]
+[Brief status update]
+```
+

official-skills/notion-spec-to-implementation/reference/task-creation-template.md

@@ -0,0 +1,34 @@
+# Task Creation Template
+
+When creating tasks from spec.
+
+```markdown
+# [Task Name]
+
+## Context
+Part of implementation for <mention-page url="...">Feature Spec</mention-page>
+
+Implementation plan: <mention-page url="...">Implementation Plan</mention-page>
+
+## Description
+[What needs to be done]
+
+## Acceptance Criteria
+- [ ] [Criterion 1]
+- [ ] [Criterion 2]
+
+## Technical Details
+[Technical approach or notes]
+
+## Dependencies
+- Blocked by: [Task] or None
+- Blocks: [Task] or None
+
+## Resources
+- [Link to design]
+- [Link to related code]
+
+## Progress
+[To be updated during implementation]
+```
+

official-skills/notion-spec-to-implementation/reference/task-creation.md

@@ -0,0 +1,441 @@
+# Task Creation from Specs
+
+## Finding the Task Database
+
+Before creating tasks, locate the task database:
+
+```
+1. Search for task database:
+   Notion:notion-search
+   query: "Tasks" or "Task Management" or "[Project] Tasks"
+   
+2. Fetch database schema:
+   Notion:notion-fetch
+   id: "database-id-from-search"
+   
+3. Identify data source:
+   - Look for <data-source url="collection://..."> tags
+   - Extract collection ID for parent parameter
+   
+4. Note schema:
+   - Required properties
+   - Property types and options
+   - Relation properties for linking
+
+Example:
+Notion:notion-search
+query: "Engineering Tasks"
+query_type: "internal"
+
+Notion:notion-fetch
+id: "tasks-database-id"
+```
+
+Result: `collection://abc-123-def` for use as parent
+
+## Task Breakdown Strategy
+
+### Size Guidelines
+
+**Good task size**:
+- Completable in 1-2 days
+- Single clear deliverable
+- Independently testable
+- Minimal dependencies
+
+**Too large**:
+- Takes > 3 days
+- Multiple deliverables
+- Many dependencies
+- Break down further
+
+**Too small**:
+- Takes < 2 hours
+- Too granular
+- Group with related work
+
+### Granularity by Phase
+
+**Early phases**: Larger tasks acceptable
+- "Design database schema"
+- "Set up API structure"
+
+**Middle phases**: Medium-sized tasks
+- "Implement user authentication"
+- "Build dashboard UI"
+
+**Late phases**: Smaller, precise tasks
+- "Fix validation bug in form"
+- "Add loading state to button"
+
+## Task Creation Pattern
+
+For each requirement or work item:
+
+```
+1. Identify the work
+2. Determine task size
+3. Create task in database
+4. Set properties
+5. Write task description
+6. Link to spec/plan
+```
+
+### Creating Task
+
+```
+Use Notion:notion-create-pages:
+
+parent: {
+  type: "data_source_id",
+  data_source_id: "collection://tasks-db-uuid"
+}
+
+properties: {
+  "[Title Property]": "Task: [Clear task name]",
+  "Status": "To Do",
+  "Priority": "[High/Medium/Low]",
+  "[Project/Related]": ["spec-page-id", "plan-page-id"],
+  "Assignee": "[Person]" (if known),
+  "date:Due Date:start": "[Date]" (if applicable),
+  "date:Due Date:is_datetime": 0
+}
+
+content: "[Task description using template]"
+```
+
+## Task Description Template
+
+```markdown
+# [Task Name]
+
+## Context
+Implementation task for <mention-page url="...">Feature Spec</mention-page>
+
+Part of <mention-page url="...">Implementation Plan</mention-page> - Phase [N]
+
+## Objective
+[What this task accomplishes]
+
+## Requirements
+Based on spec requirements:
+- [Relevant requirement 1]
+- [Relevant requirement 2]
+
+## Acceptance Criteria
+- [ ] [Specific, testable criterion]
+- [ ] [Specific, testable criterion]
+- [ ] [Specific, testable criterion]
+
+## Technical Approach
+[Suggested implementation approach]
+
+### Components Affected
+- [Component 1]
+- [Component 2]
+
+### Key Decisions
+- [Decision point 1]
+- [Decision point 2]
+
+## Dependencies
+
+### Blocked By
+- <mention-page url="...">Prerequisite Task</mention-page> or None
+
+### Blocks
+- <mention-page url="...">Dependent Task</mention-page> or None
+
+## Resources
+- [Link to design mockup]
+- [Link to API spec]
+- [Link to relevant code]
+
+## Estimated Effort
+[Time estimate]
+
+## Progress
+[To be updated during implementation]
+```
+
+## Task Types
+
+### Infrastructure/Setup Tasks
+
+```
+Title: "Setup: [What's being set up]"
+Examples:
+- "Setup: Configure database connection pool"
+- "Setup: Initialize authentication middleware"
+- "Setup: Create CI/CD pipeline"
+
+Focus: Getting environment/tooling ready
+```
+
+### Feature Implementation Tasks
+
+```
+Title: "Implement: [Feature name]"
+Examples:
+- "Implement: User login flow"
+- "Implement: File upload functionality"
+- "Implement: Dashboard widget"
+
+Focus: Building specific functionality
+```
+
+### Integration Tasks
+
+```
+Title: "Integrate: [What's being integrated]"
+Examples:
+- "Integrate: Connect frontend to API"
+- "Integrate: Add payment provider"
+- "Integrate: Link user profile to dashboard"
+
+Focus: Connecting components
+```
+
+### Testing Tasks
+
+```
+Title: "Test: [What's being tested]"
+Examples:
+- "Test: Write unit tests for auth service"
+- "Test: E2E testing for checkout flow"
+- "Test: Performance testing for API"
+
+Focus: Validation and quality assurance
+```
+
+### Documentation Tasks
+
+```
+Title: "Document: [What's being documented]"
+Examples:
+- "Document: API endpoints"
+- "Document: Setup instructions"
+- "Document: Architecture decisions"
+
+Focus: Creating documentation
+```
+
+### Bug Fix Tasks
+
+```
+Title: "Fix: [Bug description]"
+Examples:
+- "Fix: Login error on Safari"
+- "Fix: Memory leak in image processing"
+- "Fix: Race condition in payment flow"
+
+Focus: Resolving issues
+```
+
+### Refactoring Tasks
+
+```
+Title: "Refactor: [What's being refactored]"
+Examples:
+- "Refactor: Extract auth logic to service"
+- "Refactor: Optimize database queries"
+- "Refactor: Simplify component hierarchy"
+
+Focus: Code quality improvement
+```
+
+## Sequencing Tasks
+
+### Critical Path
+
+Identify must-happen-first tasks:
+
+```
+1. Database schema
+2. API foundation
+3. Core business logic
+4. Frontend integration
+5. Testing
+6. Deployment
+```
+
+### Parallel Tracks
+
+Tasks that can happen simultaneously:
+
+```
+Track A: Backend development
+- API endpoints
+- Business logic
+- Database operations
+
+Track B: Frontend development
+- UI components
+- State management
+- Routing
+
+Track C: Infrastructure
+- CI/CD setup
+- Monitoring
+- Documentation
+```
+
+### Phase-Based Sequencing
+
+Group by implementation phase:
+
+```
+Phase 1 (Foundation):
+- Setup tasks
+- Infrastructure tasks
+
+Phase 2 (Core):
+- Feature implementation tasks
+- Integration tasks
+
+Phase 3 (Polish):
+- Testing tasks
+- Documentation tasks
+- Optimization tasks
+```
+
+## Priority Assignment
+
+### P0/Critical
+- Blocks everything else
+- Core functionality
+- Security requirements
+- Data integrity
+
+### P1/High
+- Important features
+- User-facing functionality
+- Performance requirements
+
+### P2/Medium
+- Nice-to-have features
+- Optimizations
+- Minor improvements
+
+### P3/Low
+- Future enhancements
+- Edge case handling
+- Cosmetic improvements
+
+## Estimation
+
+### Story Points
+
+If using story points:
+- 1 point: Few hours
+- 2 points: Half day
+- 3 points: Full day
+- 5 points: 2 days
+- 8 points: 3-4 days (consider breaking down)
+
+### Time Estimates
+
+Direct time estimates:
+- 2-4 hours: Small task
+- 1 day: Medium task
+- 2 days: Large task
+- 3+ days: Break down further
+
+### Estimation Factors
+
+Consider:
+- Complexity
+- Unknowns
+- Dependencies
+- Testing requirements
+- Documentation needs
+
+## Task Relationships
+
+### Parent Task Pattern
+
+For large features:
+
+```
+Parent: "Feature: User Authentication"
+Children:
+- "Setup: Configure auth library"
+- "Implement: Login flow"
+- "Implement: Password reset"
+- "Test: Auth functionality"
+```
+
+### Dependency Chain Pattern
+
+For sequential work:
+
+```
+Task A: "Design database schema"
+↓ (blocks)
+Task B: "Implement data models"
+↓ (blocks)
+Task C: "Create API endpoints"
+↓ (blocks)
+Task D: "Integrate with frontend"
+```
+
+### Related Tasks Pattern
+
+For parallel work:
+
+```
+Central: "Feature: Dashboard"
+Related:
+- "Backend API for dashboard data"
+- "Frontend dashboard component"
+- "Dashboard data caching"
+```
+
+## Bulk Task Creation
+
+When creating many tasks:
+
+```
+For each work item in breakdown:
+  1. Determine task properties
+  2. Create task page
+  3. Link to spec/plan
+  4. Set relationships
+
+Then:
+  1. Update plan with task links
+  2. Review sequencing
+  3. Assign tasks (if known)
+```
+
+## Task Naming Conventions
+
+**Be specific**:
+✓ "Implement user login with email/password"
+✗ "Add login"
+
+**Include context**:
+✓ "Dashboard: Add revenue chart widget"
+✗ "Add chart"
+
+**Use action verbs**:
+- Implement, Build, Create
+- Integrate, Connect, Link
+- Fix, Resolve, Debug
+- Test, Validate, Verify
+- Document, Write, Update
+- Refactor, Optimize, Improve
+
+## Validation Checklist
+
+Before finalizing tasks:
+
+☐ Each task has clear objective
+☐ Acceptance criteria are testable
+☐ Dependencies identified
+☐ Appropriate size (1-2 days)
+☐ Priority assigned
+☐ Linked to spec/plan
+☐ Proper sequencing
+☐ Resources noted
+