|
1 | 1 | # Devlog Project - Copilot Instructions |
2 | 2 |
|
3 | | -<!-- ## 🚨 CRITICAL RULES (READ FIRST!) |
| 3 | +## 🎯 Core Instruction System |
4 | 4 |
|
5 | | -### ⚠️ MANDATORY FIRST STEP: Always Discover Before Creating |
| 5 | +This file applies **Occam's razor principle** - the simplest solution that works is the best solution. All development patterns, architecture decisions, and coding standards are consolidated here as a single, focused source of truth. |
6 | 6 |
|
7 | | -🔍 BEFORE creating ANY devlog entry, ALWAYS run: `discover_related_devlogs` |
| 7 | +## Development Philosophy |
8 | 8 |
|
9 | | -**Why this matters:** |
10 | | -- Prevents duplicate work and entries |
11 | | -- Builds upon existing insights and progress |
12 | | -- Maintains project continuity and context |
13 | | -
|
14 | | -## 📋 Devlog Creation Workflow |
15 | | -
|
16 | | -**This project uses ITSELF for development tracking. ALWAYS follow this workflow:** |
17 | | -
|
18 | | -### ✅ Required Devlog Creation Steps |
19 | | -1. **🔍 DISCOVER FIRST**: Use `discover_related_devlogs` to find existing relevant work |
20 | | -2. **📖 REVIEW**: Analyze discovered entries to understand context and avoid overlaps |
21 | | -3. **✅ CREATE ONLY IF NEEDED**: Create new devlog entry using MCP tools only if no overlapping work exists |
22 | | -4. **📝 TRACK PROGRESS**: Update entries with notes and status changes via MCP functions |
23 | | -5. **🔗 LINK WORK**: Reference devlog IDs in commits and documentation --> |
24 | | - |
25 | | -## Development Philosophy (Brief) |
26 | | - |
27 | | -**IMPORTANT**: This project is in early development. We prioritize clean, modern architecture over backwards compatibility. |
| 9 | +**IMPORTANT**: This project prioritizes clean, modern architecture over backwards compatibility. |
28 | 10 |
|
29 | 11 | - **Quality over continuity**: Well-architected solutions over preserving broken legacy code |
30 | | -- **Rapid iteration**: Make bold changes to improve codebase structure |
31 | | -- **Breaking changes acceptable**: Not bound by API compatibility during this phase |
32 | | - |
33 | | -## 🔧 TypeScript ESM Requirements |
34 | | - |
35 | | -### Import System Rules |
36 | | -- **File extensions**: Always add `.js` to import paths for runtime imports |
37 | | -- **Internal imports**: Use relative paths (`./`, `../`) within packages |
38 | | -- **Cross-package imports**: Use `@codervisor/devlog-*` aliases for inter-package references |
39 | | -- **Avoid self-reference aliases**: Don't use `@/` for intra-package imports (ambiguous) |
40 | | - |
41 | | -### Examples |
42 | | -```typescript |
43 | | -// ✅ Correct patterns |
44 | | -import { DevlogManager } from './managers/devlog-manager.js'; // Internal |
45 | | -import { ChatParser } from '@codervisor/devlog-ai'; // Cross-package |
46 | | -import type { DevlogEntry } from '../types/index.js'; // Type-only can omit .js |
| 12 | +- **Rapid iteration**: Make bold changes to improve codebase structure |
| 13 | +- **Breaking changes acceptable**: Not bound by API compatibility during early development |
| 14 | +- **Simple is better**: Occam's razor applied to all technical decisions |
47 | 15 |
|
48 | | -// ❌ Avoid these patterns |
49 | | -import { DevlogEntry } from '@/types'; // Ambiguous self-reference |
50 | | -import { StorageProvider } from '../storage/providers'; // Missing .js extension |
51 | | -``` |
| 16 | +## 🎯 Essential Patterns |
52 | 17 |
|
53 | | -## Essential SOPs |
| 18 | +- **Architecture**: Use `DevlogService` and `ProjectService` singleton patterns |
| 19 | +- **Imports**: Add `.js` extensions to relative imports, use `@codervisor/devlog-*` for cross-package |
| 20 | +- **TypeScript**: No `any` types, proper error handling, constructor dependency injection |
| 21 | +- **Testing**: Mock externals, test success/failure paths, isolated tests |
| 22 | +- **React**: Functional components, Server Components by default, Tailwind utilities |
54 | 23 |
|
55 | | -### Documentation Synchronization Process |
| 24 | +## 🚨 Critical Development Requirements |
56 | 25 |
|
57 | | -#### Instruction File Update Workflow |
58 | | -When making significant architectural or pattern changes: |
| 26 | +### Temporary Files |
| 27 | +- **Use `tmp/` folder**: All experimental code, test scripts, and temporary files |
| 28 | +- **Not committed**: `tmp/` is gitignored for transient work |
59 | 29 |
|
60 | | -1. **IMMEDIATE UPDATES**: Update instruction files as part of the same work session |
61 | | -2. **PATTERN DOCUMENTATION**: Add new patterns with examples to relevant instruction files |
62 | | -3. **DEPRECATION NOTES**: Mark old patterns as deprecated with migration guidance |
63 | | -4. **VALIDATION**: Test AI agent behavior with updated prompts |
64 | | -5. **REVIEW**: Ensure consistency across all instruction files |
65 | | - |
66 | | -#### When to Update Instruction Files |
67 | | -- **New architectural patterns** (e.g., WorkspaceDevlogManager introduction) |
68 | | -- **Import/export pattern changes** (e.g., ESM .js extension requirements) |
69 | | -- **Testing methodology updates** (e.g., new test isolation patterns) |
70 | | -- **Tooling changes** (e.g., new build processes, new package structures) |
71 | | -- **Error pattern discoveries** (e.g., common mistakes to avoid) |
72 | | - |
73 | | -#### Instruction File Maintenance Checklist |
74 | | -```markdown |
75 | | -For every significant architectural change: |
76 | | -□ Identify which instruction files need updates (.github/instructions/*.md) |
77 | | -□ Update examples to reflect current patterns |
78 | | -□ Add deprecation warnings for old patterns |
79 | | -□ Include migration guidance for existing code |
80 | | -□ Test AI agent behavior with new prompts |
81 | | -□ Verify consistency across all instruction files |
82 | | -□ Document the instruction update in devlog notes |
83 | | -``` |
84 | | - |
85 | | -### Temporary Files and Scripts |
86 | | - |
87 | | -#### Use `tmp/` Folder for Temporary Work |
88 | | -- **ALWAYS use `tmp/` folder**: Place all temporary scripts, test files, and experimental code in the `tmp/` directory |
89 | | -- **Not committed to git**: The `tmp/` folder is gitignored and will not be committed to version control |
90 | | -- **Examples of tmp/ usage**: |
91 | | - - Test scripts for debugging |
92 | | - - Temporary configuration files |
93 | | - - Experimental code snippets |
94 | | - - One-off migration scripts |
95 | | - - Build artifacts for testing |
96 | | -- **Clean up**: Remove temporary files when no longer needed to keep the tmp directory tidy |
97 | | - |
98 | | -### Testing Requirements |
99 | | - |
100 | | -#### Build vs Dev Server Conflicts |
101 | | -- **Use `pnpm build:test` for AI testing**: When AI agents need to test builds, always use `pnpm build:test` instead of `pnpm build` |
102 | | -- **Why this matters**: `pnpm build` overwrites `.next/` directory and breaks active development servers |
103 | | -- **Solution implemented**: |
104 | | - - `pnpm build:test` uses `.next-build/` directory (separate from dev server's `.next/`) |
105 | | - - Dev servers can run concurrently with build testing |
106 | | - - No workflow disruption when testing build success |
107 | | -- **Commands available**: |
108 | | - - `docker compose -f docker-compose.dev.yml up web-dev -d --wait` - Runs containerized dev server in detached mode with health check wait |
109 | | - - `pnpm build:test` - Tests build using `.next-build/` directory |
110 | | - - `pnpm build` - Production build (still uses `.next/` by default) |
| 30 | +### Build Testing |
| 31 | +- **Use `pnpm build:test`**: Tests builds without breaking active dev servers |
| 32 | +- **Development containers**: `docker compose -f docker-compose.dev.yml up web-dev -d --wait` |
| 33 | +- **Build order**: Core → MCP → Web (follow dependency chain) |
111 | 34 |
|
112 | | -#### Docker-Based Development Policy |
113 | | -- **Use Docker Compose for development**: The development environment now runs in containers for consistency |
114 | | -- **Configurable storage**: Storage type determined by `.env` file configuration (PostgreSQL, SQLite, JSON, or GitHub) |
115 | | -- **Hot reloading preserved**: Volume mounts ensure code changes trigger hot reloads |
116 | | -- **Port management**: Docker handles port allocation and prevents conflicts |
117 | | -- **Environment isolation**: Development dependencies are containerized |
118 | | -- **⚠️ IMPORTANT**: Keep development container running during development sessions - do NOT stop unless explicitly requested |
119 | | -- **Commands**: |
120 | | - - Start: `docker compose -f docker-compose.dev.yml up web-dev -d --wait` |
121 | | - - Stop: `docker compose -f docker-compose.dev.yml down` (only when explicitly requested) |
122 | | - - Logs: `docker compose logs web-dev -f` |
| 35 | +### UI Development |
| 36 | +- **Use Playwright MCP tools**: Required for React debugging and console monitoring |
| 37 | +- **Keep containers running**: Don't stop development containers unless explicitly requested |
123 | 38 |
|
124 | | -#### UI-Related Development Tasks |
125 | | -- **ALWAYS use Playwright**: Use Playwright MCP tools for UI validation and debugging |
126 | | -- **Browser Tool Selection**: |
127 | | - - **Playwright**: Required for React error debugging, console monitoring, state analysis |
128 | | - - **Simple Browser**: Basic navigation/UI testing only - NOT reliable for error detection |
129 | | -- **Testing Steps**: |
130 | | - - **Start Web App**: Run `docker compose -f docker-compose.dev.yml up web-dev -d --wait` to start the containerized web app (if not already running) |
131 | | - - **Verify**: Ensure the web app is running correctly before testing (check http://localhost:3200) |
132 | | - - **Run Tests**: Use Playwright to run UI tests against the web app |
133 | | - - **Update Devlog**: Add test results and any fixes to the devlog entry |
134 | | - - **Keep Running**: Leave the web app running for continued development (do NOT stop unless explicitly requested) |
| 39 | +### Quality Standards |
| 40 | +- **No `any` types**: Use proper TypeScript typing |
| 41 | +- **Handle async errors**: All async operations must have error handling |
| 42 | +- **Test critical paths**: Both success and failure scenarios |
| 43 | +- **Export types**: Always export types alongside implementations |
135 | 44 |
|
136 | | -#### React Debugging Verification Protocol |
137 | | -- **MANDATORY for React Issues**: Use Playwright console monitoring before concluding any fix |
138 | | -- **Verification Checklist**: |
139 | | - - [ ] Playwright console messages captured and analyzed |
140 | | - - [ ] No "Maximum update depth exceeded" errors |
141 | | - - [ ] No React warnings or error boundary triggers |
142 | | - - [ ] Functional testing of affected user workflows |
143 | | -- **Multi-Stage Validation**: Apply Fix → Playwright Test → Console Analysis → User Flow Test → Confirmation |
144 | | -- **If ANY stage fails**: Return to analysis phase, do not mark issue as resolved |
| 45 | +## 📖 Remember |
145 | 46 |
|
146 | | -#### Build Dependencies |
147 | | -- **Build order**: Core → MCP → Web (follow dependency chain) |
148 | | -- **After core changes**: `pnpm --filter @codervisor/devlog-core build` then restart MCP server |
| 47 | +Simple, focused solutions over complex, comprehensive ones. When in doubt, choose the clearer, more maintainable approach. |
0 commit comments