189 lines
5.4 KiB
Markdown
189 lines
5.4 KiB
Markdown
# GitHub Copilot Instructions for Memory Palace
|
|
|
|
## Project Overview
|
|
|
|
This is a hybrid workspace combining:
|
|
|
|
- **Documentation**: Obsidian-style knowledge management with wiki-links and backlinks
|
|
- **Code Development**: Bookmarklets, scratchpad code, and project prototypes
|
|
|
|
## Documentation Guidelines
|
|
|
|
### Writing Style
|
|
|
|
- Use clear, concise markdown
|
|
- Employ wiki-style `[[links]]` for connecting notes
|
|
- Include frontmatter metadata in notes (date, type, tags)
|
|
- Keep daily notes in `/docs/daily/` with format `daily-YYYY-MM-DD.md`
|
|
- Place evergreen concept notes in `/docs/concepts/`
|
|
|
|
### Note Structure
|
|
|
|
```markdown
|
|
---
|
|
type: concept|project|fleeting
|
|
created: YYYY-MM-DD
|
|
tags: []
|
|
---
|
|
|
|
# Title
|
|
|
|
## Overview
|
|
|
|
Brief summary
|
|
|
|
## Content
|
|
|
|
Main content with [[links]]
|
|
|
|
## Related
|
|
|
|
- [[other-note]]
|
|
```
|
|
|
|
## Code Development Guidelines
|
|
|
|
### Bookmarklets (`/code/bookmarklets/`)
|
|
|
|
- Write as regular Node.js-compatible JavaScript files
|
|
- Use modern ES6+ syntax, let/const, etc. (will be minified)
|
|
- Include JSDoc comments for documentation (removed in final bookmarklet)
|
|
- Write clear, readable code - the generator handles minification
|
|
- Use descriptive variable and function names
|
|
- Test logic in Node.js if possible before converting
|
|
|
|
**Conversion Process:**
|
|
|
|
1. Write bookmarklet as normal `.js` file in `/code/bookmarklets/`
|
|
2. Run: `npm run bookmarklet -- code/bookmarklets/your-file.js`
|
|
3. Generator automatically:
|
|
- Removes all comments
|
|
- Minifies code
|
|
- Wraps in IIFE: `javascript:(function(){...})();`
|
|
- Copies to clipboard
|
|
4. Paste into browser bookmark URL field
|
|
|
|
### Scratchpad Code (`/code/scratchpad/`)
|
|
|
|
- This is experimental space - be creative
|
|
- Add `TODO:` comments for work in progress
|
|
- Use descriptive variable names
|
|
- Include usage examples
|
|
- Python: Follow PEP 8 style
|
|
- JavaScript/TypeScript: Use modern ES6+ syntax
|
|
|
|
### Code Style
|
|
|
|
- **Python**: PEP 8, type hints preferred
|
|
- **JavaScript**: Modern ES6+, const/let over var, **ES modules (import/export)**
|
|
- **TypeScript**: Explicit types, interfaces over types
|
|
- Comments: Explain _why_, not _what_
|
|
- Functions: Single responsibility, descriptive names
|
|
|
|
### Module System
|
|
|
|
**This project uses ES modules (import/export), not CommonJS (require).**
|
|
|
|
- Use `import` for dependencies: `import fs from 'fs';`
|
|
- Use `export` for exporting: `export default myFunction;` or `export { myFunction };`
|
|
- Package.json is configured with `"type": "module"`
|
|
- Use `.js` extension for ES modules
|
|
- For Node.js built-ins requiring special handling: `import { fileURLToPath } from 'url';`
|
|
|
|
## File Organization
|
|
|
|
### When to Create Files
|
|
|
|
- **Fleeting notes**: Quick captures, temporary thoughts → `/docs/fleeting/`
|
|
- **Concept notes**: Refined ideas, evergreen content → `/docs/concepts/`
|
|
- **Project docs**: Specific project documentation → `/docs/projects/`
|
|
- **Bookmarklets**: Browser utilities → `/code/bookmarklets/`
|
|
- **Experiments**: Testing/learning → `/code/scratchpad/`
|
|
|
|
### Naming Conventions
|
|
|
|
- Documentation: `kebab-case.md` (e.g., `my-note.md`)
|
|
- JavaScript: `kebab-case.js` (e.g., `my-bookmarklet.js`)
|
|
- Python: `snake_case.py` (e.g., `my_script.py`)
|
|
- TypeScript: `kebab-case.ts` (e.g., `my-module.ts`)
|
|
|
|
## Git Commit Practices
|
|
|
|
GitDoc auto-commits on save. For manual commits:
|
|
|
|
- Use conventional commits: `type: description`
|
|
- Types: `docs:`, `feat:`, `fix:`, `refactor:`, `chore:`
|
|
- Examples:
|
|
- `docs: add note on memory techniques`
|
|
- `feat: create bookmark highlighter bookmarklet`
|
|
- `fix: correct regex in search bookmarklet`
|
|
|
|
## Special Considerations
|
|
|
|
### Cross-Linking
|
|
|
|
When suggesting note connections:
|
|
|
|
- Look for conceptual relationships
|
|
- Suggest bidirectional links
|
|
- Consider creating index notes for related topics
|
|
|
|
### Code Reusability
|
|
|
|
- Create templates in `/code/templates/` for common patterns
|
|
- Extract reusable functions into utility modules
|
|
- Document APIs and interfaces
|
|
|
|
### Search & Discovery
|
|
|
|
- Use descriptive titles and headers
|
|
- Include relevant tags in frontmatter
|
|
- Add aliases for alternative terms
|
|
- Consider TODO tags: `TODO:`, `FIXME:`, `NOTE:`, `IDEA:`
|
|
|
|
## Preferences
|
|
|
|
- **Brevity**: Favor concise, clear explanations
|
|
- **Examples**: Include practical examples in code
|
|
- **Context**: Assume this is a personal knowledge workspace
|
|
- **Flexibility**: This is a scratchpad - prioritize exploration over perfection
|
|
- **Learning**: Explain concepts when introducing new patterns or techniques
|
|
|
|
## README Maintenance
|
|
|
|
**IMPORTANT**: Keep README files synchronized with project structure changes.
|
|
|
|
### When to Update READMEs
|
|
|
|
Update relevant README.md files whenever you:
|
|
|
|
- Add or remove folders
|
|
- Change file organization
|
|
- Add new tools or utilities
|
|
- Modify workflows or conventions
|
|
- Add new features or capabilities
|
|
|
|
### README Locations
|
|
|
|
- `/README.md` - Main project overview and quick start
|
|
- `/docs/README.md` - Documentation hub and note-taking guide
|
|
- `/code/README.md` - Code section overview
|
|
- `/code/bookmarklets/README.md` - Bookmarklet creation guide
|
|
- `/.github/README.md` - GitHub templates and structure
|
|
|
|
### Update Guidelines
|
|
|
|
- Keep structure diagrams accurate
|
|
- Update examples to reflect current patterns
|
|
- Maintain consistency across all READMEs
|
|
- Add new sections before implementation when adding major features
|
|
- Remove outdated information immediately
|
|
|
|
## Tools & Extensions Available
|
|
|
|
- Foam (wiki-links, backlinks, graph)
|
|
- Code Runner (quick code execution)
|
|
- Todo Tree (tracks TODO comments)
|
|
- Bookmarks (mark important code locations)
|
|
- ESLint (JavaScript linting)
|