diff --git a/PROJECTS.md b/PROJECTS.md index 0390458..befc822 100644 --- a/PROJECTS.md +++ b/PROJECTS.md @@ -81,20 +81,24 @@ When adding a new project, include: **Description**: Brief overview of what this project is and its purpose. **Technologies**: + - List main technologies, frameworks, languages **Goals**: + - Primary objectives and success criteria **Current Status**: + - What's working - What's in progress - Any blockers **Links**: -- [Repository](#) -- [Documentation](#) -- [Live Demo](#) _(if applicable)_ + +- Repository: (link here) +- Documentation: (link here) +- Live Demo: (link here if applicable) **Related Projects**: References to related work @@ -158,4 +162,5 @@ Common tags used in tags.json: --- -**Note**: Run `./scripts/update-project-list.sh` to auto-generate project summaries from filesystem and tags.json. +**Note**: Run `./scripts/update-project-list.sh` to auto-generate +project summaries from filesystem and tags.json. diff --git a/README.md b/README.md index 4e46da2..029d8b6 100644 --- a/README.md +++ b/README.md @@ -5,6 +5,7 @@ A centralized repository for tracking all my work, projects, and learning activi ## Purpose This repository serves as: + - **Project Portfolio**: Showcase of completed and ongoing work - **Work Tracker**: Organized documentation of development progress - **Learning Log**: Record of experiments, courses, and technical growth @@ -12,7 +13,7 @@ This repository serves as: ## Repository Structure -``` +```text Projects/ ├── active/ # Currently active projects ├── completed/ # Finished projects @@ -44,17 +45,20 @@ Projects/ The `project-docs/` submodule provides Claude Code commands for maintaining documentation: **Installation** (if not already installed): + ```bash claude plugins add teresa-torres-plugins/project-docs ``` **Key Commands**: + - `/project-docs:readme` - Update project README with setup/usage info - `/project-docs:architecture` - Document system design and patterns - `/project-docs:process-notes` - Log work history and decisions - `/project-docs:ab-test ` - Document A/B tests and experiments **When to Use**: + - Start of each work session: Review existing docs - During development: Log key decisions and blockers - End of session: Update process-notes with progress @@ -71,23 +75,29 @@ claude plugins add teresa-torres-plugins/project-docs ## Project Categories ### Active Projects + Currently under development with regular updates. ### Completed Projects + Finished projects that are deployed or delivered. ### Experiments + Quick proofs-of-concept, spikes, and technical explorations. ### Learning + Tutorial projects, course work, and skill development. ### Archived + Deprecated, paused, or superseded projects kept for reference. ## Documentation Standards Each project should include: + - `README.md` - What it is, how to use it, setup instructions - `ARCHITECTURE.md` - Design decisions, patterns, system overview - `process-notes.md` - Development history and decisions (gitignored) @@ -111,6 +121,7 @@ Each project should include: ## Resources See `resources/` directory for: + - Curated bookmarks and articles - Course materials and notes - Technical references @@ -119,6 +130,7 @@ See `resources/` directory for: ## Tools & Scripts The `scripts/` directory contains utilities for: + - Scaffolding new projects - Generating project summaries - Archiving completed work @@ -130,10 +142,6 @@ Run `./scripts/new-project.sh --help` for usage information. For current project status and statistics, see [PROJECTS.md](./PROJECTS.md). -## License - -See [LICENSE](./LICENSE) for details. - --- **Last Updated**: 2026-01-09 diff --git a/WORKFLOW.md b/WORKFLOW.md index 1cf58a6..3f933a1 100644 --- a/WORKFLOW.md +++ b/WORKFLOW.md @@ -65,9 +65,11 @@ This document outlines my personal workflow for managing projects in this reposi - `learning/` - Tutorial or learning exercise 2. **Create Structure** + ```bash ./scripts/new-project.sh ``` + Or manually: - Create project directory - Copy templates from `templates/` @@ -121,9 +123,11 @@ This document outlines my personal workflow for managing projects in this reposi - Tag final version 3. **Move to Completed** + ```bash ./scripts/archive-project.sh completed ``` + Or manually: - Move from `active/` to `completed/` - Update `PROJECTS.md` status @@ -145,6 +149,7 @@ For projects that are paused, deprecated, or no longer relevant: ``` Or manually: + - Move to `archived/` directory - Update `PROJECTS.md` with reason for archiving - Update `tags.json` status @@ -153,30 +158,35 @@ Or manually: ## Naming Conventions ### Projects + - Use `kebab-case-names` - Be descriptive but concise - Include tech stack if ambiguous: `python-data-analyzer` - Include purpose if needed: `learning-rust-basics` ### Git Branches + - `feature/add-authentication` - `fix/memory-leak-in-parser` - `experiment/try-new-algorithm` - `docs/update-architecture` ### Git Commits + - Use imperative mood: "Add feature" not "Added feature" - Start with verb: Add, Update, Fix, Remove, Refactor - Keep first line under 72 characters - Add details in body if needed Examples: + - `Add user authentication with JWT` - `Fix memory leak in data parser` - `Update README with installation instructions` - `Refactor database queries for performance` ### Files + - `README.md` - Project overview and usage - `ARCHITECTURE.md` - Design and technical details - `process-notes.md` - Work log (gitignored) @@ -188,7 +198,9 @@ Examples: ### When to Use Each Command #### `/project-docs:readme` + Use when: + - Starting a new project - Adding user-facing features - Changing setup/installation process @@ -196,7 +208,9 @@ Use when: - Adding configuration options #### `/project-docs:architecture` + Use when: + - Designing initial system architecture - Adding new infrastructure components - Establishing new patterns or conventions @@ -205,7 +219,9 @@ Use when: - Making architectural decisions #### `/project-docs:process-notes` + Use when: + - End of work session - Context window approaching limit (~90%) - Completing a major feature or milestone @@ -215,7 +231,9 @@ Use when: - Learning something significant #### `/project-docs:ab-test` + Use when: + - Planning experiments or comparisons - Testing multiple approaches - Measuring feature impact @@ -224,7 +242,9 @@ Use when: ### Agent Usage #### `/project-docs:plan-review` + Use before implementing complex features: + - After creating implementation plan - Before writing significant code - To check consistency with ARCHITECTURE.md @@ -235,6 +255,7 @@ Use before implementing complex features: ### tags.json Structure Keep `tags.json` updated with: + - Project name and location - Current status (active, completed, archived, paused) - Technology tags @@ -243,6 +264,7 @@ Keep `tags.json` updated with: - Related projects Update when: + - Creating new project - Changing project status - Moving project directories @@ -251,19 +273,25 @@ Update when: ## Tools and Scripts ### new-project.sh + Creates new project with template files: + ```bash ./scripts/new-project.sh ``` ### archive-project.sh + Moves project to completed or archived: + ```bash ./scripts/archive-project.sh ``` ### update-project-list.sh + Regenerates project summaries in PROJECTS.md: + ```bash ./scripts/update-project-list.sh ``` @@ -271,30 +299,35 @@ Regenerates project summaries in PROJECTS.md: ## Tips and Best Practices ### Documentation + - Write for your future self - you'll forget context - Document the "why" not just the "what" - Capture dead ends to avoid repeating mistakes - Keep docs close to code they describe ### Git Practices + - Commit before trying risky changes - One logical change per commit - Write commit messages that explain why - Push regularly for backup ### Context Management + - Save important details before they scroll away - Use process-notes proactively, not reactively - Include file paths in notes for easy navigation - Link related decisions together ### Project Organization + - Start simple, add structure as needed - Prefer real organization over metadata - Keep related things together - Archive liberally - disk space is cheap ### Learning Projects + - Document learnings as you go - Compare with previous approaches - Note resources and references @@ -302,6 +335,7 @@ Regenerates project summaries in PROJECTS.md: --- -**Note**: This workflow is a living document. Update it as practices evolve and new patterns emerge. +**Note**: This workflow is a living document. Update it as practices +evolve and new patterns emerge. **Last Updated**: 2026-01-09 diff --git a/resources/bookmarks.md b/resources/bookmarks.md index eeea3ba..b545213 100644 --- a/resources/bookmarks.md +++ b/resources/bookmarks.md @@ -5,10 +5,12 @@ Useful websites, tools, and online resources organized by category. ## Development Tools ### Code Editors & IDEs + - [Visual Studio Code](https://code.visualstudio.com/) - Free, extensible code editor - [JetBrains IDEs](https://www.jetbrains.com/) - Professional development environments ### Version Control + - [GitHub](https://github.com/) - Git hosting and collaboration - [GitLab](https://gitlab.com/) - DevOps platform with CI/CD - [Git Documentation](https://git-scm.com/doc) - Official Git docs @@ -16,11 +18,13 @@ Useful websites, tools, and online resources organized by category. ## Documentation ### Writing & Publishing + - [Markdown Guide](https://www.markdownguide.org/) - Markdown syntax reference - [GitHub Flavored Markdown](https://github.github.com/gfm/) - GFM specification - [Read the Docs](https://readthedocs.org/) - Documentation hosting ### Diagramming + - [Mermaid](https://mermaid.js.org/) - Markdown-based diagrams - [Draw.io](https://app.diagrams.net/) - Free diagramming tool - [Excalidraw](https://excalidraw.com/) - Hand-drawn style diagrams @@ -28,6 +32,7 @@ Useful websites, tools, and online resources organized by category. ## Learning Platforms ### Online Learning + - [freeCodeCamp](https://www.freecodecamp.org/) - Free coding education - [Coursera](https://www.coursera.org/) - Online courses from universities - [Udemy](https://www.udemy.com/) - Course marketplace @@ -35,6 +40,7 @@ Useful websites, tools, and online resources organized by category. - [Frontend Masters](https://frontendmasters.com/) - Advanced web development ### Practice & Challenges + - [LeetCode](https://leetcode.com/) - Algorithm practice - [HackerRank](https://www.hackerrank.com/) - Coding challenges - [Exercism](https://exercism.org/) - Code practice with mentoring @@ -43,18 +49,21 @@ Useful websites, tools, and online resources organized by category. ## Reference & Documentation ### Language References + - [MDN Web Docs](https://developer.mozilla.org/) - Web development reference - [Python Documentation](https://docs.python.org/) - Official Python docs - [Rust Book](https://doc.rust-lang.org/book/) - Learn Rust - [Go Documentation](https://go.dev/doc/) - Go language docs ### Design Patterns + - [Refactoring Guru](https://refactoring.guru/) - Design patterns explained - [Patterns.dev](https://www.patterns.dev/) - Modern web patterns ## Developer Communities ### Forums & Q&A + - [Stack Overflow](https://stackoverflow.com/) - Programming Q&A - [Dev.to](https://dev.to/) - Developer community and articles - [Hacker News](https://news.ycombinator.com/) - Tech news and discussion @@ -63,17 +72,20 @@ Useful websites, tools, and online resources organized by category. ## Tools & Utilities ### Testing + - [Jest](https://jestjs.io/) - JavaScript testing framework - [Pytest](https://pytest.org/) - Python testing framework - [Postman](https://www.postman.com/) - API testing tool ### DevOps & Deployment + - [Docker Documentation](https://docs.docker.com/) - Container platform - [Kubernetes Docs](https://kubernetes.io/docs/) - Container orchestration - [Netlify](https://www.netlify.com/) - Static site hosting - [Vercel](https://vercel.com/) - Frontend deployment ### Monitoring & Analytics + - [Sentry](https://sentry.io/) - Error tracking - [DataDog](https://www.datadoghq.com/) - Monitoring and analytics - [New Relic](https://newrelic.com/) - Application performance monitoring @@ -81,21 +93,25 @@ Useful websites, tools, and online resources organized by category. ## Design & UI/UX ### Design Tools + - [Figma](https://www.figma.com/) - Collaborative design tool - [Canva](https://www.canva.com/) - Graphic design platform ### Design Resources + - [Dribbble](https://dribbble.com/) - Design inspiration - [Behance](https://www.behance.net/) - Creative portfolios ## Blogs & News ### Technology Blogs + - [Martin Fowler](https://martinfowler.com/) - Software architecture - [Joel on Software](https://www.joelonsoftware.com/) - Software development - [CSS-Tricks](https://css-tricks.com/) - Web development ### Newsletters + - [JavaScript Weekly](https://javascriptweekly.com/) - [Python Weekly](https://www.pythonweekly.com/) - [TLDR Newsletter](https://tldr.tech/) - Tech news summary @@ -103,6 +119,7 @@ Useful websites, tools, and online resources organized by category. ## Add Your Bookmarks Below ### Category Name + - [Resource](https://example.com/) - Description --- diff --git a/resources/tools.md b/resources/tools.md index 598d598..1579ec8 100644 --- a/resources/tools.md +++ b/resources/tools.md @@ -5,12 +5,17 @@ Curated list of development tools, utilities, and software. ## Editors & IDEs ### Code Editors -- **[Visual Studio Code](https://code.visualstudio.com/)** - Free, extensible code editor + +- **[Visual Studio Code](https://code.visualstudio.com/)** - Free, + extensible code editor - Essential extensions: Prettier, ESLint, GitLens -- **[Sublime Text](https://www.sublimetext.com/)** - Fast, lightweight editor -- **[Vim](https://www.vim.org/)** / **[Neovim](https://neovim.io/)** - Terminal-based editors +- **[Sublime Text](https://www.sublimetext.com/)** - Fast, + lightweight editor +- **[Vim](https://www.vim.org/)** / **[Neovim](https://neovim.io/)** - + Terminal-based editors ### IDEs + - **[JetBrains Suite](https://www.jetbrains.com/)** - Professional IDEs - WebStorm (JavaScript/TypeScript) - PyCharm (Python) @@ -20,6 +25,7 @@ Curated list of development tools, utilities, and software. ## Version Control ### Git Tools + - **[Git](https://git-scm.com/)** - Distributed version control - **[GitHub Desktop](https://desktop.github.com/)** - Git GUI client - **[GitKraken](https://www.gitkraken.com/)** - Visual Git client @@ -28,11 +34,13 @@ Curated list of development tools, utilities, and software. ## Terminal & Shell ### Terminal Emulators + - **[iTerm2](https://iterm2.com/)** - macOS terminal replacement - **[Windows Terminal](https://aka.ms/terminal)** - Modern Windows terminal - **[Alacritty](https://alacritty.org/)** - GPU-accelerated terminal ### Shell Enhancement + - **[Oh My Zsh](https://ohmyz.sh/)** - Zsh configuration framework - **[Starship](https://starship.rs/)** - Cross-shell prompt - **[Fig](https://fig.io/)** - Terminal autocomplete @@ -54,7 +62,8 @@ Curated list of development tools, utilities, and software. ## Container & Orchestration -- **[Docker Desktop](https://www.docker.com/products/docker-desktop)** - Container platform +- **[Docker Desktop](https://www.docker.com/products/docker-desktop)** - + Container platform - **[Kubernetes](https://kubernetes.io/)** - Container orchestration - **[k9s](https://k9scli.io/)** - Kubernetes CLI management - **[Helm](https://helm.sh/)** - Kubernetes package manager @@ -62,13 +71,17 @@ Curated list of development tools, utilities, and software. ## Cloud Tools ### AWS + - **[AWS CLI](https://aws.amazon.com/cli/)** - Command-line interface - **[AWS Console](https://console.aws.amazon.com/)** - Web interface ### Azure -- **[Azure CLI](https://docs.microsoft.com/en-us/cli/azure/)** - Command-line tool + +- **[Azure CLI](https://docs.microsoft.com/en-us/cli/azure/)** - + Command-line tool ### GCP + - **[gcloud CLI](https://cloud.google.com/sdk/gcloud)** - Google Cloud CLI ## CI/CD @@ -88,16 +101,20 @@ Curated list of development tools, utilities, and software. ## Productivity ### Project Management + - **[Notion](https://www.notion.so/)** - All-in-one workspace - **[Obsidian](https://obsidian.md/)** - Knowledge base - **[Linear](https://linear.app/)** - Issue tracking ### Documentation + - **[Notion](https://www.notion.so/)** - Documentation and wikis -- **[Confluence](https://www.atlassian.com/software/confluence)** - Team workspace +- **[Confluence](https://www.atlassian.com/software/confluence)** - + Team workspace - **[GitBook](https://www.gitbook.com/)** - Documentation platform ### Communication + - **[Slack](https://slack.com/)** - Team communication - **[Discord](https://discord.com/)** - Community platform @@ -110,17 +127,20 @@ Curated list of development tools, utilities, and software. ## Command-Line Utilities ### File Management + - **[fzf](https://github.com/junegunn/fzf)** - Fuzzy finder - **[ripgrep](https://github.com/BurntSushi/ripgrep)** - Fast grep alternative - **[fd](https://github.com/sharkdp/fd)** - Fast find alternative - **[bat](https://github.com/sharkdp/bat)** - Cat with syntax highlighting ### System Monitoring + - **[htop](https://htop.dev/)** - Interactive process viewer - **[btop](https://github.com/aristocratos/btop)** - Resource monitor - **[ncdu](https://dev.yorhel.nl/ncdu)** - Disk usage analyzer ### Network + - **[mtr](https://www.bitwizard.nl/mtr/)** - Network diagnostic tool - **[ngrok](https://ngrok.com/)** - Secure tunnels to localhost - **[httpstat](https://github.com/reorx/httpstat)** - HTTP timing visualization @@ -128,11 +148,13 @@ Curated list of development tools, utilities, and software. ## Package Managers ### System-Level + - **[Homebrew](https://brew.sh/)** - macOS/Linux package manager - **[Chocolatey](https://chocolatey.org/)** - Windows package manager - **[apt](https://wiki.debian.org/Apt)** - Debian/Ubuntu package manager ### Language-Specific + - **[npm](https://www.npmjs.com/)** - JavaScript package manager - **[pip](https://pip.pypa.io/)** - Python package installer - **[cargo](https://doc.rust-lang.org/cargo/)** - Rust package manager @@ -147,9 +169,12 @@ Curated list of development tools, utilities, and software. ## Performance & Profiling -- **[Chrome DevTools](https://developer.chrome.com/docs/devtools/)** - Browser debugging -- **[Lighthouse](https://developers.google.com/web/tools/lighthouse)** - Performance auditing -- **[webpack-bundle-analyzer](https://github.com/webpack-contrib/webpack-bundle-analyzer)** - Bundle analysis +- **[Chrome DevTools](https://developer.chrome.com/docs/devtools/)** - + Browser debugging +- **[Lighthouse](https://developers.google.com/web/tools/lighthouse)** - + Performance auditing +- **[webpack-bundle-analyzer](https://github.com/webpack-contrib/webpack-bundle-analyzer)** + \- Bundle analysis tool ## Miscellaneous @@ -164,6 +189,7 @@ Curated list of development tools, utilities, and software. ## Tool Configurations Store tool configuration files in `dotfiles/` or project root: + - `.vscode/` - VS Code workspace settings - `.editorconfig` - Editor configuration - `.prettierrc` - Prettier config diff --git a/templates/ARCHITECTURE-template.md b/templates/ARCHITECTURE-template.md index 1a74fc3..43f4b10 100644 --- a/templates/ARCHITECTURE-template.md +++ b/templates/ARCHITECTURE-template.md @@ -10,7 +10,7 @@ High-level description of how the system is designed and why these choices were ### Architecture Diagram -``` +```text [ASCII diagram or link to diagram] User → API Gateway → Application Server → Database @@ -20,7 +20,8 @@ User → API Gateway → Application Server → Database ### Components -**Component Name** +### Component Name + - Purpose: What it does - Technology: What it's built with - Responsibilities: Key functions @@ -30,8 +31,9 @@ User → API Gateway → Application Server → Database ### Entities -**Entity Name** -``` +### Entity Name + +```json { "field1": "type", "field2": "type", @@ -60,7 +62,8 @@ CREATE TABLE table_name ( ); ``` -**Indexes**: +### Indexes + - Index on field1 for query performance - Composite index on (field2, field3) @@ -68,13 +71,15 @@ CREATE TABLE table_name ( ### REST Endpoints -**GET /api/resource** +### GET /api/resource + - Purpose: Retrieve resources - Parameters: `?filter=value` - Response: `{ "data": [...] }` - Authentication: Required/Not required -**POST /api/resource** +### POST /api/resource + - Purpose: Create new resource - Request Body: `{ "field": "value" }` - Response: `{ "id": "123", "status": "created" }` @@ -98,7 +103,10 @@ CREATE TABLE table_name ( ### Services and Resources -**Service Name** (e.g., AWS Lambda, EC2, RDS) +### Service Name + +(e.g., AWS Lambda, EC2, RDS) + - Purpose - Configuration - Scaling strategy @@ -114,7 +122,10 @@ CREATE TABLE table_name ( ### Key User Flows -**Flow Name** (e.g., User Registration) +### Flow Name + +(e.g., User Registration) + 1. User submits form 2. API validates input 3. Database creates record @@ -123,7 +134,8 @@ CREATE TABLE table_name ( ### Background Jobs -**Job Name** +### Job Name + - Trigger: What initiates this job - Frequency: How often it runs - Purpose: What it accomplishes @@ -133,7 +145,7 @@ CREATE TABLE table_name ( (If applicable - for complex state transitions) -``` +```text Initial State → Action → New State Pending → Process → Complete → Failure → Failed @@ -143,14 +155,17 @@ Pending → Process → Complete ### Patterns Used -**Pattern Name** (e.g., Repository Pattern, Factory Pattern) +### Pattern Name + +(e.g., Repository Pattern, Factory Pattern) + - Where: Which components use this - Why: Rationale for choosing this pattern - Implementation: How it's implemented ### Code Organization -``` +```text src/ ├── controllers/ # HTTP request handlers ├── services/ # Business logic @@ -226,17 +241,20 @@ src/ ### Testing Strategy -**Unit Tests** +### Unit Tests + - What's tested - Coverage goals - Key test cases -**Integration Tests** +### Integration Tests + - Component interactions tested - Test environment setup - Key scenarios -**E2E Tests** +### E2E Tests + - Critical user flows tested - Tools used - Test data management @@ -252,6 +270,7 @@ src/ ### Third-Party Libraries List major dependencies and why they were chosen: + - **Library Name** (version): Purpose and alternatives considered ## Deployment @@ -296,7 +315,8 @@ Steps to rollback if deployment fails. ### Major Architectural Decisions -**[Date] - Decision Title** +### [Date] - Decision Title + - **Context**: What was the situation - **Decision**: What was decided - **Rationale**: Why this was chosen diff --git a/templates/README-template.md b/templates/README-template.md index e02ddd3..aadcd61 100644 --- a/templates/README-template.md +++ b/templates/README-template.md @@ -40,7 +40,8 @@ Description of configuration needed: - API keys or credentials Example `.env` file: -``` + +```env VARIABLE_NAME=value API_KEY=your_api_key_here ``` @@ -60,7 +61,7 @@ Additional examples and use cases. ## Project Structure -``` +```text project-name/ ├── src/ # Source code ├── tests/ # Test files @@ -92,6 +93,7 @@ project-name/ ### Deployment Steps for deployment: + 1. Step one 2. Step two 3. Step three @@ -109,8 +111,13 @@ Steps for deployment: Common issues and solutions: -**Issue**: Description -**Solution**: How to fix +### Issue + +Description + +### Solution + +How to fix ## Contributing