diff --git a/.agents/skills/feature-planning/SKILL.md b/.agents/skills/feature-planning/SKILL.md new file mode 100644 index 0000000..3c356d6 --- /dev/null +++ b/.agents/skills/feature-planning/SKILL.md @@ -0,0 +1,251 @@ +# Feature Planning Skill + +This skill provides a structured workflow for implementing new features in the TimeTracker project. Use this skill when the user requests a new feature or significant functionality change. + +## Workflow Overview + +``` +1. Requirements Discovery (iterative) + └── Clarify edge cases, acceptance criteria, constraints + +2. Feature Plan Creation + └── docs/features/{feature-name}.md + +3. Implementation + └── Use plan as single source of truth +``` + +## Phase 1: Requirements Discovery + +**Goal:** Understand exactly what needs to be built before writing any code. + +### Questions to Ask + +Ask targeted questions to clarify: + +#### Core Functionality +- What is the primary purpose of this feature? +- What user problem does it solve? +- How should users interact with this feature? + +#### Data & API +- What new data needs to be stored? +- What existing data structures are affected? +- What API endpoints are needed (if any)? + +#### User Interface +- Where in the UI should this feature appear? +- What views or components are needed? +- What user interactions are required? + +#### Edge Cases +- What happens when inputs are invalid? +- How should errors be handled? +- What are the boundary conditions? +- Are there any race conditions to consider? + +#### Constraints +- Are there performance requirements? +- Any security considerations? +- Browser/device compatibility? +- Integration with existing features? + +### Iteration Process + +1. **Initial Questions** — Ask 3-5 focused questions based on the feature description +2. **Wait for Answers** — Let the programmer respond +3. **Follow-up Questions** — Dig deeper based on responses +4. **Confirm Understanding** — Summarize your understanding and ask for confirmation +5. **Iterate** — Repeat until requirements are clear + +### Example Question Flow + +``` +User: "Add the ability to export time entries to CSV" + +Agent: "Before I start planning, I have a few questions: + +1. Should the export include all entries or only filtered entries (if filters are active)? +2. What columns should be included in the CSV? (date, duration, project, client, description?) +3. Should the CSV include break minutes and net duration, or just total time? +4. Is there a date range limit, or can users export all historical data? +5. Should the export be triggered from the Time Entries page, or from a separate Export page?" +``` + +## Phase 2: Feature Plan + +**Goal:** Create a comprehensive plan document before implementation. + +### Plan Location + +Create the plan at: `docs/features/{feature-name}.md` + +Use kebab-case for the filename (e.g., `csv-export.md`, `dark-mode.md`). + +### Plan Template + +```markdown +# Feature: {Feature Name} + +## Overview + +Brief description of what this feature does and why it's needed. + +## Requirements + +### Functional Requirements +- Requirement 1 +- Requirement 2 +- Requirement 3 + +### Non-Functional Requirements +- Performance: ... +- Security: ... +- Usability: ... + +### Constraints +- Constraint 1 +- Constraint 2 + +## Technical Approach + +### Architecture Decisions +- Decision 1 and rationale +- Decision 2 and rationale + +### Database Changes +- New tables/columns +- Migrations needed +- Data migration strategy (if any) + +### API Changes +- New endpoints +- Modified endpoints +- Request/response formats + +### Frontend Changes +- New components +- Modified components +- State management approach + +## Implementation Steps + +1. **Step 1: Backend - Database** + - Create migration + - Update Prisma schema + - Regenerate client + +2. **Step 2: Backend - Service** + - Add service methods + - Add validation schemas + +3. **Step 3: Backend - Routes** + - Create route handlers + - Add middleware + +4. **Step 4: Frontend - API Client** + - Add API functions + +5. **Step 5: Frontend - Components** + - Create/update components + - Add to routes if needed + +6. **Step 6: Testing** + - Manual testing steps + - Edge case verification + +## File Changes + +### New Files +- `backend/src/services/export.service.ts` +- `frontend/src/hooks/useExport.ts` + +### Modified Files +- `backend/src/routes/timeEntry.routes.ts` — Add export endpoint +- `frontend/src/pages/TimeEntriesPage.tsx` — Add export button +- `frontend/src/api/timeEntries.ts` — Add export function + +### Database +- No changes required (or specify migration) + +## Edge Cases + +| Case | Handling | +|------|----------| +| No entries match filter | Show empty state, export empty CSV with headers | +| Very large export (>10k entries) | Stream response, show progress indicator | +| User cancels export mid-stream | Gracefully close connection | +| Invalid date range | Return 400 error with clear message | + +## Testing Strategy + +### Manual Testing +1. Navigate to Time Entries page +2. Apply date filter +3. Click Export button +4. Verify CSV downloads with correct data +5. Open CSV and verify format + +### Edge Case Testing +1. Export with no entries +2. Export with 1000+ entries +3. Export with special characters in descriptions +4. Export while timer is running + +## Open Questions + +- [ ] Question 1 (to be resolved during implementation) +- [ ] Question 2 +``` + +### Plan Review + +After creating the plan: + +1. Present the plan to the programmer +2. Ask for feedback and approval +3. Make requested changes +4. Get final approval before proceeding to implementation + +## Phase 3: Implementation + +**Goal:** Implement the feature exactly as planned. + +### Rules + +1. **Read the plan first** — Start by reading the full plan file +2. **Follow the plan** — Implement step by step as outlined +3. **Update if needed** — If implementation differs from plan, update the plan file +4. **Document changes** — After completion, update relevant documentation + +### Implementation Checklist + +- [ ] Read `docs/features/{feature-name}.md` +- [ ] Implement database changes (if any) +- [ ] Implement backend service logic +- [ ] Implement backend routes +- [ ] Implement frontend API client +- [ ] Implement frontend components +- [ ] Run linting: `npm run lint` +- [ ] Manual testing +- [ ] Update plan if implementation differs +- [ ] Update `project.md` if requirements changed +- [ ] Update `README.md` if API changed +- [ ] Update `AGENTS.md` if patterns changed + +## Quick Reference + +### Commands +- Frontend lint: `npm run lint` (in `frontend/`) +- Backend build: `npm run build` (in `backend/`) +- DB migration: `npm run db:migrate` (in `backend/`) +- DB generate: `npm run db:generate` (in `backend/`) + +### File Locations +- Backend routes: `backend/src/routes/` +- Backend services: `backend/src/services/` +- Backend schemas: `backend/src/schemas/` +- Frontend pages: `frontend/src/pages/` +- Frontend hooks: `frontend/src/hooks/` +- Frontend API: `frontend/src/api/` +- Feature plans: `docs/features/` diff --git a/AGENTS.md b/AGENTS.md index b28a3ea..733103b 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -49,6 +49,30 @@ This document describes the structure, conventions, and commands for the `vibe_c ### After Making Changes **Always update documentation.** See [Documentation Maintenance](#documentation-maintenance). +## Feature Development Workflow + +**For new features, AI agents MUST follow this process before writing any code.** + +### Phase 1: Requirements Discovery +1. Ask clarifying questions about the feature request +2. Identify edge cases, constraints, and acceptance criteria +3. Confirm understanding with the programmer +4. Iterate until requirements are clear + +### Phase 2: Feature Plan +1. Create `docs/features/{feature-name}.md` with the feature plan +2. Include: overview, requirements, technical approach, file changes, edge cases, testing +3. Present plan for review +4. Iterate until approved by the programmer + +### Phase 3: Implementation +1. Use the approved plan as the single source of truth +2. Implement step by step following the plan +3. Update the plan if implementation differs +4. Update documentation after completion + +**See the `feature-planning` skill for detailed workflow and templates.** + ## Documentation Maintenance **Every code change requires a documentation review.** When you modify the codebase, check whether documentation needs updating. diff --git a/DOCS.md b/DOCS.md index b0202d6..786bf35 100644 --- a/DOCS.md +++ b/DOCS.md @@ -8,6 +8,13 @@ | `README.md` | Setup instructions, API reference, features list | New endpoints, config changes, new features, technology stack changes | | `project.md` | Requirements, data model, functional specifications | Business logic changes, new entities, validation rules, UI requirements | | `DOCS.md` | Documentation standards and index | Documentation process changes, new documentation files | +| `docs/features/*.md` | Feature implementation plans | Created during feature development, updated if implementation differs | + +## AI Agent Skills + +| Skill | Purpose | When to Use | +|-------|---------|-------------| +| `feature-planning` | Structured workflow for new features | When implementing new features or significant functionality changes | ## Documentation Standards diff --git a/docs/features/.gitkeep b/docs/features/.gitkeep new file mode 100644 index 0000000..e69de29