docs: add Phase 1 issue tracking and enhance project guidelines

nullcoder · claude · web-flow · commit f1b8ecebe9a3 · 2025-06-05T00:37:00.000-07:00
Enhanced project documentation to support organized development workflow with comprehensive issue tracking and best practices. TODO.md Updates: - Added GitHub issue references (#5-#12) to all Phase 1 tasks for direct progress tracking - Created new R2 verification task as issue #12 - Grouped related tasks under appropriate issue numbers for better organization CLAUDE.md Enhancements: - Added project management section with GitHub project board workflow - Documented issue management requirements and labeling standards - Included development workflow for issue-based development - Expanded best practices section with specific guidelines: - Documentation-first approach with official CLI usage - Code quality standards for edge runtime - Security guidelines for zero-knowledge architecture - Performance considerations for Cloudflare Workers - Testing requirements for critical paths This establishes a clear development process where team members can pick issues from the project board, track progress in TODO.md, and follow consistent practices throughout implementation. 🤖 Generated with [Claude Code](https://claude.ai/code) Co-Authored-By: Claude <noreply@anthropic.com>
diff --git a/CLAUDE.md b/CLAUDE.md
@@ -76,6 +76,62 @@ For detailed architecture, API specs, and data models, refer to `docs/SPEC.md`.
 - Prefer rebase over merge to keep history clean
 - Always pull latest changes from `main` before starting new work
 
+## Project Management
+
+### GitHub Project
+- All issues and PRs are tracked in the "👻 GhostPaste" project board
+- When creating issues or PRs, always add `--project "👻 GhostPaste"`
+- Follow the label system documented in `docs/LABELS.md`
+
+### Issue Management
+- Every issue must have: category label, priority label, and status label
+- Reference TODO.md line numbers in issues when applicable
+- Link related issues in the description
+
+### Progress Tracking
+- Check off completed tasks in `docs/TODO.md`
+- Update issue status labels as work progresses
+- Close issues only after PR is merged
+
+### Development Workflow
+1. Pick an issue from the project board
+2. Create feature branch: `git checkout -b feat/issue-description`
+3. Make changes following the issue requirements
+4. Create PR and link to issue with "Closes #XX"
+5. Add PR to project board
+6. Request review and address feedback
+
 ## Best Practices
 
-- Always check official documentation of frameworks, UI components, Cloudflare, CodeMirror before implementing changes. If they provide generator or command line, please follow the documentation instead of manually generate them.
+### Documentation First
+- Always check official documentation before implementing:
+  - Next.js 15: Use `create-next-app` and official guides
+  - shadcn/ui: Use `npx shadcn-ui@latest` CLI commands
+  - Cloudflare: Follow Workers and R2 official docs
+  - CodeMirror: Refer to v6 documentation
+- Use official CLIs and generators instead of manual setup
+
+### Code Quality
+- Run `npm run lint` and `npm run typecheck` before committing
+- Follow TypeScript strict mode practices
+- Write edge-runtime compatible code only
+- Keep components small and focused
+- Use proper error boundaries
+
+### Security
+- Never commit secrets or API keys
+- Always validate and sanitize user input
+- Use environment variables for sensitive data
+- Follow encryption best practices in `docs/SPEC.md`
+
+### Performance
+- Consider Cloudflare Workers limits (50ms CPU, 100MB request)
+- Optimize for edge runtime constraints
+- Minimize bundle sizes
+- Use dynamic imports where appropriate
+
+### Testing
+- Write tests for critical paths (encryption, binary format)
+- Test edge cases and error scenarios
+- Verify edge runtime compatibility
+- Run tests before creating PRs
diff --git a/docs/TODO.md b/docs/TODO.md
@@ -5,32 +5,33 @@ This document tracks the implementation progress of GhostPaste. Check off tasks
 ## 🏗️ Phase 1: Project Setup
 
 ### Initial Setup
-- [ ] Initialize Next.js 15 project with TypeScript (using `create-next-app`)
-- [ ] Set up Cloudflare Workers environment with wrangler
-- [ ] Configure project for Next.js on Cloudflare Workers using @cloudflare/next-on-pages
-- [ ] Configure Edge Runtime compatibility for all routes
-- [ ] Configure ESLint and Prettier
-- [ ] Set up Git hooks with Husky and lint-staged
-- [ ] Create wrangler.toml with R2 bucket bindings and environment variables
-- [ ] Configure path aliases in `tsconfig.json`
-- [ ] Set up VS Code workspace settings
-- [ ] Create .dev.vars for local development secrets
+- [ ] Initialize Next.js 15 project with TypeScript (using `create-next-app`) - [#5](https://github.com/nullcoder/ghostpaste/issues/5)
+- [ ] Set up Cloudflare Workers environment with wrangler - [#6](https://github.com/nullcoder/ghostpaste/issues/6)
+- [ ] Configure project for Next.js on Cloudflare Workers using @cloudflare/next-on-pages - [#6](https://github.com/nullcoder/ghostpaste/issues/6)
+- [ ] Configure Edge Runtime compatibility for all routes - [#6](https://github.com/nullcoder/ghostpaste/issues/6)
+- [ ] Configure ESLint and Prettier - [#7](https://github.com/nullcoder/ghostpaste/issues/7)
+- [ ] Set up Git hooks with Husky and lint-staged - [#7](https://github.com/nullcoder/ghostpaste/issues/7)
+- [ ] Create wrangler.toml with R2 bucket bindings and environment variables - [#6](https://github.com/nullcoder/ghostpaste/issues/6)
+- [ ] Configure path aliases in `tsconfig.json` - [#7](https://github.com/nullcoder/ghostpaste/issues/7)
+- [ ] Set up VS Code workspace settings - [#7](https://github.com/nullcoder/ghostpaste/issues/7)
+- [ ] Create .dev.vars for local development secrets - [#6](https://github.com/nullcoder/ghostpaste/issues/6)
 
 ### Dependencies
-- [ ] Install @cloudflare/next-on-pages for Workers deployment
-- [ ] Install wrangler for local development
-- [ ] Install and configure shadcn/ui (using official CLI)
-- [ ] Install CodeMirror 6 and language modes
-- [ ] Install nanoid for ID generation
-- [ ] Install @cloudflare/workers-types for type definitions
-- [ ] Install development dependencies (vitest, @testing-library/react)
-- [ ] Install next-themes for theme management
+- [ ] Install @cloudflare/next-on-pages for Workers deployment - [#6](https://github.com/nullcoder/ghostpaste/issues/6)
+- [ ] Install wrangler for local development - [#6](https://github.com/nullcoder/ghostpaste/issues/6)
+- [ ] Install and configure shadcn/ui (using official CLI) - [#8](https://github.com/nullcoder/ghostpaste/issues/8)
+- [ ] Install CodeMirror 6 and language modes - [#9](https://github.com/nullcoder/ghostpaste/issues/9)
+- [ ] Install nanoid for ID generation - [#9](https://github.com/nullcoder/ghostpaste/issues/9)
+- [ ] Install @cloudflare/workers-types for type definitions - [#9](https://github.com/nullcoder/ghostpaste/issues/9)
+- [ ] Install development dependencies (vitest, @testing-library/react) - [#10](https://github.com/nullcoder/ghostpaste/issues/10)
+- [ ] Install next-themes for theme management - [#8](https://github.com/nullcoder/ghostpaste/issues/8)
 
 ### Project Structure
-- [ ] Create folder structure (`app/`, `components/`, `lib/`, `types/`)
-- [ ] Set up app router pages structure
-- [ ] Create base layout with theme provider
-- [ ] Set up global styles and CSS variables
+- [ ] Create folder structure (`app/`, `components/`, `lib/`, `types/`) - [#11](https://github.com/nullcoder/ghostpaste/issues/11)
+- [ ] Set up app router pages structure - [#11](https://github.com/nullcoder/ghostpaste/issues/11)
+- [ ] Create base layout with theme provider - [#8](https://github.com/nullcoder/ghostpaste/issues/8)
+- [ ] Set up global styles and CSS variables - [#8](https://github.com/nullcoder/ghostpaste/issues/8)
+- [ ] Verify Cloudflare R2 setup - [#12](https://github.com/nullcoder/ghostpaste/issues/12)
 
 ## 🔧 Phase 2: Core Infrastructure
 
