{"id":32848943,"url":"https://github.com/vpetreski/prd","last_synced_at":"2025-11-08T10:02:09.841Z","repository":{"id":322927277,"uuid":"1091463987","full_name":"vpetreski/prd","owner":"vpetreski","description":"PRD System for Claude Code - Manage development tasks with Product Requirements Documents","archived":false,"fork":false,"pushed_at":"2025-11-07T03:55:43.000Z","size":22,"stargazers_count":0,"open_issues_count":0,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2025-11-07T05:34:29.593Z","etag":null,"topics":["ai","claude","claude-code","prd"],"latest_commit_sha":null,"homepage":"","language":"Just","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":null,"status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/vpetreski.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":null,"code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2025-11-07T03:46:17.000Z","updated_at":"2025-11-07T03:55:46.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/vpetreski/prd","commit_stats":null,"previous_names":["vpetreski/prd"],"tags_count":null,"template":false,"template_full_name":null,"purl":"pkg:github/vpetreski/prd","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/vpetreski%2Fprd","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/vpetreski%2Fprd/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/vpetreski%2Fprd/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/vpetreski%2Fprd/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/vpetreski","download_url":"https://codeload.github.com/vpetreski/prd/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/vpetreski%2Fprd/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":283333707,"owners_count":26818628,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","status":"online","status_checked_at":"2025-11-08T02:00:06.281Z","response_time":57,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["ai","claude","claude-code","prd"],"created_at":"2025-11-08T10:00:59.374Z","updated_at":"2025-11-08T10:02:09.814Z","avatar_url":"https://github.com/vpetreski.png","language":"Just","funding_links":[],"categories":[],"sub_categories":[],"readme":"# PRD System for Claude Code\n\n\u003e **📝 Read the full article:** [PRD System for Claude Code](https://vanja.io/prd-system-for-claude-code/)\n\nA lightweight, file-based system for managing tasks across multiple projects using Product Requirements Documents (PRDs), designed specifically for **Claude Code**.\n\n## What This Is\n\nThis system helps you organize and track development tasks across different projects with **Claude Code** as your AI pair programmer. Each task gets its own folder with:\n- A **task.md** file containing requirements, goals, and context\n- A **sessions.md** file tracking your work sessions and progress\n\nThis approach keeps your tasks organized, makes it easy to resume work after interruptions, and provides a clear history of decisions and progress. Claude Code reads these files to understand your project context and help you implement features efficiently.\n\n## How It Works: Two Contexts for Claude Code\n\nWorking on a task involves using **Claude Code in TWO different contexts**:\n\n### Context 1: Planning \u0026 Architecture (in ~/prd)\n\n**Location:** `~/prd` directory\n**Role:** Product/Architecture/Orchestration\n**Tools:** `just` commands + `claude`\n\n**What you do here:**\n- Create and manage tasks (`just new`, `just edit`)\n- Work with Claude Code to refine requirements from external sources\n- Have Claude help you create detailed task.md files\n- Generate workflow.md guides for complex/multi-repo tasks\n- Plan implementation strategies\n- Track high-level progress\n\n**Example:**\n```bash\ncd ~/prd\nclaude\n# \"Help me create a task.md for migrating our auth system.\n#  Here are the requirements: [paste external requirements]\"\n```\n\n**Think of this as:** The product/architect side where you define WHAT needs to be done and HOW to approach it.\n\n### Context 2: Implementation (in your actual code repos)\n\n**Location:** Your actual project directories (e.g., `~/code/my-project`)\n**Role:** Engineering/Implementation\n**Tools:** `claude` (reading PRD files for context)\n\n**What you do here:**\n- Run Claude Code in your actual codebase\n- Reference the PRD files you created in ~/prd\n- Have Claude help with actual implementation, debugging, testing\n- Update sessions.md to track what you accomplished\n- Make commits, run tests, deploy code\n\n**Example:**\n```bash\ncd ~/code/my-project\nclaude\n# \"Read ~/prd/prj/my-project/auth-migration/task.md and sessions.md\n#  and help me implement the JWT token changes\"\n```\n\n**Think of this as:** The engineering side where you DO the actual work.\n\n### The Complete Flow\n\n1. **Plan in ~/prd** → Work with Claude to create task.md and workflow.md\n2. **Code in your repos** → Work with Claude to implement, referencing PRD files\n3. **Track in ~/prd** → Have Claude update sessions.md with progress\n4. **Repeat** → Continue cycling between planning and coding as needed\n\n**Key Insight:** You're working with Claude Code in both places, but for different purposes:\n- **~/prd = Product thinking** (requirements, strategy, planning)\n- **~/code/project = Engineering thinking** (implementation, debugging, testing)\n\n## Requirements\n\nTo use this system, you need:\n\n- **[Claude Code](https://claude.com/claude-code)** - The official CLI from Anthropic\n  - Install: `brew upgrade claude-code` (macOS) or download from [claude.com/claude-code](https://claude.com/claude-code)\n  - Version: Latest recommended\n- **[Just](https://github.com/casey/just)** - Command runner for automation\n  - Install: `brew install just` (macOS) or see [installation guide](https://github.com/casey/just#installation)\n- **Git** - For version control and updates\n- **Terminal/Shell** - bash, zsh, or similar\n\n## 🔒 Privacy Model\n\n**Your projects stay private.** This repository is designed so you can:\n- Fork it to your own GitHub account\n- Track your peronal/work projects locally\n- Pull updates to the PRD system without exposing your work\n\n**How it works:**\n- All your projects live in `prj/` directory\n- The `prj/` folder is **git-ignored** (except for the example project)\n- Only the PRD system files are version controlled (README, Justfile, TEMPLATE.md)\n- When you pull updates, you get new features without conflicts with your projects\n\n**Example project:** The `prj/acme-app/` directory is the only exception - it's version controlled to serve as documentation. You can delete it anytime.\n\n## 🚀 Installation\n\n### Prerequisites\n\nBefore installing, make sure you have the requirements (see Requirements section above):\n\n```bash\n# Install Claude Code (required!)\nbrew upgrade claude-code  # macOS\n# Or download from: https://claude.com/claude-code\n\n# Install Just (required!)\nbrew install just  # macOS\n# Or see: https://github.com/casey/just#installation\n\n# Verify installations\nclaude --version\njust --version\n```\n\n### Setup Steps\n\n**Important:** This system is designed to work in `~/prd` directory. Clone it there:\n\n```bash\n# 1. Fork this repository on GitHub to your own account\n#    Click \"Fork\" button at https://github.com/vpetreski/prd\n\n# 2. Clone YOUR fork to ~/prd (not just any directory!)\ngit clone https://github.com/YOUR-USERNAME/prd.git ~/prd\ncd ~/prd\n\n# 3. Set up upstream to pull system updates\ngit remote add upstream https://github.com/vpetreski/prd.git\n\n# 4. Verify setup\ngit remote -v\n# Should show:\n# origin    https://github.com/YOUR-USERNAME/prd.git (fetch/push)\n# upstream  https://github.com/vpetreski/prd.git (fetch/push)\n\n# 5. Test it out!\njust list\n# Should show the example acme-app project\n```\n\n**Why ~/prd specifically?**\n- All documentation examples use `~/prd`\n- Justfile commands assume this location\n- Makes it consistent across your machines\n- Easy to remember and navigate to\n\n### Repository Permissions\n\n**You can:**\n- ✅ Fork this repo to your own GitHub account\n- ✅ Clone your fork to ~/prd\n- ✅ Create unlimited private projects (automatically git-ignored)\n- ✅ Pull updates from upstream (vpetreski/prd) anytime\n- ✅ Push to your own fork (if you want to sync across your machines)\n- ✅ Customize your fork however you like\n\n**Only the original author (vpetreski) can:**\n- ❌ Push updates to the upstream repository (vpetreski/prd)\n- ❌ Release new versions of the PRD system\n\n**This means:**\n- Your projects stay private on your machine\n- You get system updates by pulling from upstream\n- You can't accidentally push to the upstream repo (you don't have permission)\n- Your fork is yours - push to it if you want your projects on GitHub\n\n### Pulling System Updates\n\nWhen new features are released:\n\n```bash\ncd ~/prd\n\n# Pull latest system improvements\ngit fetch upstream\ngit merge upstream/main\n\n# Your projects are safe! Only system files get updated:\n# - README.md (new documentation)\n# - Justfile (new commands)\n# - TEMPLATE.md (improved template)\n# - prj/acme-app/ (updated example)\n#\n# Your projects in prj/* remain untouched!\n```\n\n### Optional: Sync Your Projects Across Machines\n\nIf you want to sync your own projects via GitHub:\n\n```bash\n# Option 1: Push to your fork (WARNING: This makes your projects public!)\ngit add prj/my-project  # This will fail - prj/* is ignored!\n# You'd need to modify .gitignore first\n\n# Option 2 (Recommended): Use a separate private repo for projects\ncd ~/prd/prj\ngit init\ngit add .\ngit remote add origin https://github.com/YOUR-USERNAME/prd-projects-private.git\ngit push -u origin main\n\n# Now ~/prd system updates and ~/prd/prj are separate repos!\n```\n\n## Quick Start\n\nReady to try it? Here's the two-phase workflow:\n\n### Phase 1: Planning in ~/prd (Product/Architecture)\n\n```bash\n# Create task structure\ncd ~/prd\njust new my-project user-login\n\n# Option A: Write requirements manually\njust edit my-project user-login  # Opens in text editor\n\n# Option B: Work with Claude to refine requirements\ncd ~/prd\nclaude\n# \"I need to create a task for user login with OAuth support.\n#  Here are the requirements: [paste requirements].\n#  Help me create a comprehensive task.md file.\"\n```\n\n### Phase 2: Implementation in your code repo (Engineering)\n\n```bash\n# Go to your actual project\ncd ~/code/my-project\nclaude\n\n# Tell Claude to load the PRD:\n\"Read ~/prd/prj/my-project/user-login/task.md and sessions.md,\n then help me implement the requirements\"\n\n# Work with Claude to build the feature...\n\n# When done, tell Claude to save the session:\n\"Update ~/prd/prj/my-project/user-login/sessions.md with today's progress\"\n```\n\n### Common Commands\n\n**Use `just` in ~/prd to manage tasks:**\n\n```bash\ncd ~/prd\njust                    # Show all commands\njust new PROJECT TASK   # Create a new task\njust edit PROJECT TASK  # Edit requirements in text editor\njust list              # List all tasks with status\njust status            # Show overview stats\njust work-on PROJECT TASK  # Show how to work on this task\njust view PROJECT TASK  # View task.md quickly\njust archive PROJECT TASK  # Archive completed task\n```\n\n**Use `claude` in your actual project directory only:**\n\n```bash\ncd ~/code/your-project\nclaude  # Work with Claude Code here, referencing ~/prd files\n```\n\n## Folder Structure\n\n```\n~/prd/\n├── README.md              # This file (version controlled)\n├── TEMPLATE.md            # Template for new task.md files (version controlled)\n├── Justfile               # Automation commands (version controlled)\n├── .gitignore             # Git ignore rules (version controlled)\n└── prj/                   # Your projects directory (git-ignored!)\n    └── {project}/         # One folder per project\n        └── {task}/        # One folder per task\n            ├── task.md        # Task requirements and details\n            ├── sessions.md    # Work session log\n            └── workflow.md    # Optional: Step-by-step workflow guide\n```\n\n**What gets version controlled:**\n- ✅ System files: README.md, Justfile, TEMPLATE.md, .gitignore\n- ✅ Example project: `prj/acme-app/` (for documentation)\n- ❌ Your projects: Everything else in `prj/` stays local\n\n**Example with your projects:**\n```\n~/prd/\n├── README.md\n├── TEMPLATE.md\n├── Justfile\n├── .gitignore\n└── prj/\n    ├── acme-app/               # ✅ Version controlled (example only)\n    │   └── user-authentication/\n    │       ├── task.md\n    │       └── sessions.md\n    ├── work-project/           # ❌ Git-ignored (your private work)\n    │   ├── feature-x/\n    │   └── feature-y/\n    └── personal-site/          # ❌ Git-ignored (your personal stuff)\n        └── blog-redesign/\n```\n\n\u003e **Note:** The `prj/acme-app/` directory is included as a working example. Explore `prj/acme-app/user-authentication/` to see how tasks should be structured. Delete it anytime - it's just for learning!\n\n## Creating a New Task\n\n```bash\ncd ~/prd\njust new PROJECT-NAME TASK-NAME\n```\n\nThis automatically:\n- Creates the project directory if it doesn't exist\n- Creates the task directory\n- Copies the template to task.md\n- Creates an empty sessions.md file\n- Shows you the next steps\n\nThen edit the task requirements in your text editor:\n```bash\njust edit PROJECT-NAME TASK-NAME\n```\n\nThis opens task.md in your default editor (set via $EDITOR, or uses code/vim/nano). Fill in:\n- Background (why this task exists)\n- Requirements (what needs to be done)\n- Goals (what success looks like)\n- Success Criteria (how to know when it's complete)\n\n**Pro tip:** For complex requirements, work with Claude Code in ~/prd:\n```bash\ncd ~/prd\nclaude\n# \"I have these requirements [paste]. Help me create a comprehensive\n#  task.md file at prj/PROJECT/TASK/task.md\"\n```\n\n## Daily Workflow\n\nRemember: You'll be working in **two contexts** - planning in ~/prd and coding in your repos.\n\n### 1. Check Your Tasks (Context: ~/prd)\n\n```bash\ncd ~/prd\njust list    # See all your tasks\njust status  # Quick overview\n```\n\n### 2. Review Task Details (Context: ~/prd)\n\n```bash\ncd ~/prd\njust work-on PROJECT TASK   # Get instructions\njust view PROJECT TASK      # View task.md\njust sessions PROJECT TASK  # View session history\njust workflow PROJECT TASK  # View workflow guide (if exists)\n```\n\n### 3. Refine/Plan if Needed (Context: ~/prd with Claude)\n\nIf you need to update requirements, create workflow guides, or plan approach:\n\n```bash\ncd ~/prd\nclaude\n# \"Read prj/PROJECT/TASK/task.md. I need to add requirements for X.\n#  Also create a workflow.md with implementation phases.\"\n```\n\n### 4. Implement in Your Code Repo (Context: your code repo with Claude)\n\n**Go to your actual project directory**:\n\n```bash\ncd ~/code/your-actual-project\nclaude\n```\n\n**Tell Claude Code to load the task:**\n```\nRead ~/prd/prj/PROJECT/TASK/task.md and ~/prd/prj/PROJECT/TASK/sessions.md\n\nGive me a summary of:\n1. What this task requires\n2. What was accomplished in the last session\n3. What needs to be done next\n\nThen help me implement the requirements.\n```\n\nClaude Code will:\n- Read your PRD files for context\n- Understand the requirements\n- See what's been done\n- Help you implement the remaining work\n\n### 5. Save Your Session (Context: back in code repo with Claude)\n\nWhen you're done working, tell Claude Code to update your session log:\n\n```\nUpdate ~/prd/prj/PROJECT/TASK/sessions.md with a new session entry for today.\n\nInclude:\n- Date: [today's date]\n- Accomplished: [what we did]\n- Blockers: [any issues]\n- Decisions: [choices we made]\n- Next steps: [what to do next]\n- Status: In Progress\n```\n\nClaude will append the session entry to your sessions.md file.\n\n### 6. Archive When Complete (Context: ~/prd)\n\n```bash\ncd ~/prd\njust archive PROJECT TASK\n```\n\n### Example: Complete Workflow\n\nHere's a complete example from start to finish:\n\n```bash\n# ============================================\n# Part 1: Set up the task (in ~/prd)\n# ============================================\n\ncd ~/prd\njust new acme-app user-authentication\n\n# Edit requirements in your text editor\njust edit acme-app user-authentication\n# Fill in: Background, Requirements, Goals, Success Criteria\n# Save and close\n\n# Review what you created\njust view acme-app user-authentication\n\n# Get instructions for working on it\njust work-on acme-app user-authentication\n\n# ============================================\n# Part 2: Implement the feature (in your project)\n# ============================================\n\ncd ~/code/acme-app\nclaude\n\n# Tell Claude:\n# \"Read ~/prd/prj/acme-app/user-authentication/task.md and sessions.md\n#\n#  Summarize:\n#  1. What this task requires\n#  2. What was accomplished previously (if any)\n#  3. What needs to be done\n#\n#  Then help me implement the authentication system.\"\n\n# Work with Claude to implement, test, iterate...\n\n# When done for the day, tell Claude:\n# \"Update ~/prd/prj/acme-app/user-authentication/sessions.md with a new session.\n#\n#  Accomplished:\n#  - Set up JWT token generation\n#  - Implemented login endpoint\n#  - Added password hashing with bcrypt\n#\n#  Blockers: None\n#\n#  Decisions:\n#  - Using HTTP-only cookies for tokens\n#  - Session expiry set to 7 days\n#\n#  Next steps:\n#  - Add password reset functionality\n#  - Write tests for login endpoint\n#\n#  Status: In Progress\"\n\n# ============================================\n# Part 3: Continue next session (next day)\n# ============================================\n\ncd ~/code/acme-app\nclaude\n\n# Tell Claude:\n# \"Read ~/prd/prj/acme-app/user-authentication/task.md and sessions.md\n#  Show me where we left off and help me continue.\"\n\n# ============================================\n# Part 4: Archive when complete (in ~/prd)\n# ============================================\n\ncd ~/prd\njust archive acme-app user-authentication\n```\n\n## Writing Good task.md Files\n\n### Be Specific\n- Clearly define what \"done\" looks like\n- Include concrete acceptance criteria\n- List specific technical constraints\n\n### Provide Context\n- Explain WHY this task exists\n- Link to related documents or resources\n- Note dependencies on other tasks\n\n### Define Scope\n- Explicitly state what's IN scope\n- Explicitly state what's OUT of scope (Non-Goals)\n- This prevents scope creep\n\n### Example Structure\n```markdown\n## Requirements\n- MUST authenticate users via OAuth2\n- MUST support GitHub and Google providers\n- MUST redirect to dashboard after login\n\n## Non-Goals\n- Social login with Twitter (future task)\n- Password-based authentication (deprecated)\n```\n\n## sessions.md Format\n\nEach session entry follows this structure:\n\n```markdown\n## Session: 2025-01-15 - 2 hours\n\n**Accomplished:**\n- Implemented OAuth2 flow for GitHub\n- Added redirect logic to dashboard\n- Created login button component\n\n**Blockers:**\n- Google OAuth credentials not yet available in staging\n- Need design review for button placement\n\n**Decisions:**\n- Using NextAuth.js instead of custom OAuth implementation\n- Storing session in HTTP-only cookies (not localStorage)\n\n**Next Steps:**\n- Get Google OAuth credentials from DevOps\n- Schedule design review meeting\n- Add error handling for failed auth\n\n**Status:** In Progress\n```\n\n### Guidelines for Sessions\n\n1. **Update after each work session** (even short ones)\n2. **Be honest about blockers** - they help you track patterns\n3. **Document decisions** - you'll forget why you chose something\n4. **Keep \"Next Steps\" actionable** - make it easy to resume\n5. **Update status** - In Progress, Blocked, Complete, or On Hold\n\n## Tips for Staying Organized\n\n### 1. One Task, One Folder\nDon't combine multiple unrelated tasks in one folder. If a task grows too large, split it.\n\n### 2. Archive Completed Tasks\n```bash\ncd ~/prd\njust archive PROJECT TASK\n```\n\n### 3. Use Descriptive Names\n- Good: `user-authentication`, `api-rate-limiting`, `dark-mode-ui`\n- Bad: `task1`, `fix-bug`, `new-feature`\n\n### 4. Reference Tasks in Commits\nLink commits to your PRD tasks:\n```bash\ngit commit -m \"Add OAuth flow (prd: acme-app/user-authentication)\"\n```\n\n### 5. Review Weekly\nSpend 15 minutes each week reviewing:\n- What tasks are in progress?\n- What tasks are blocked and why?\n- What tasks can be archived?\n\n### 6. Start Small\nDon't create PRDs for every tiny task. Use this system for:\n- Tasks taking more than 1 hour\n- Tasks spanning multiple sessions\n- Tasks requiring research or planning\n- Tasks with multiple requirements\n\n## Working with Project-Specific CLAUDE.md Files\n\nMany projects have a `CLAUDE.md` file at the repository root with project-specific context. This PRD system complements those files:\n\n- **CLAUDE.md**: Project-wide context, architecture, conventions\n- **PRD task.md**: Specific feature/task requirements and goals\n\n### Example Workflow\n\n1. Project has `/code/acme-app/CLAUDE.md` with architecture details\n2. You create `~/prd/acme-app/user-authentication/task.md` for a specific feature\n3. When working, Claude reads both:\n   ```\n   \"Read ~/code/acme-app/CLAUDE.md for project context,\n    then read ~/prd/acme-app/user-authentication/task.md for this task's\n    requirements, and help me implement the authentication system\"\n   ```\n\n### Best Practice\n\nInclude a \"Resources\" section in your task.md that references the project's CLAUDE.md:\n```markdown\n## Resources\n- Project context: ~/code/acme-app/CLAUDE.md\n- API docs: https://docs.acme-app.dev\n- Design mockups: Figma link\n```\n\n## Working with Multi-Repo Tasks\n\nSome tasks require changes across multiple repositories (e.g., updating a backend API and its consumer service). You can track these in a single PRD task.\n\n### Strategy for Multi-Repo Tasks\n\n1. **One task, multiple repos** - Keep everything in one task.md and sessions.md\n2. **Document the repos** - List all involved repositories in Technical Notes\n3. **Note which repo** - When updating sessions.md, mention which repo you worked in\n4. **Switch contexts** - Change directories and start Claude in each repo as needed\n\n### Example Workflow\n\n```bash\n# Create a single task for the multi-repo work\ncd ~/prd\njust new backend-migration api-migration\n\n# Edit task.md to document both repos\njust edit backend-migration api-migration\n# Add: Local project paths for both repos in Technical Notes\n# Add: Multi-Repo Strategy section explaining which changes go where\n\n# Work on first repo\ncd ~/code/api-service\nclaude\n# Tell Claude: \"Read ~/prd/prj/backend-migration/api-migration/task.md and sessions.md\n#               Work on the API changes. Note 'api-service repo' in session log.\"\n\n# Work on second repo\ncd ~/code/consumer-service\nclaude\n# Tell Claude: \"Read ~/prd/prj/backend-migration/api-migration/task.md and sessions.md\n#               Work on the consumer changes. Note 'consumer-service repo' in session log.\"\n```\n\n### Using workflow.md for Complex Tasks\n\nFor complex tasks (especially multi-repo ones), create a `workflow.md` file in your task directory with detailed, step-by-step instructions:\n\n**What to include:**\n- Phase-by-phase breakdown of the entire task\n- Exact bash commands to run (which directory, which repo)\n- Complete Claude prompts to use at each step\n- Expected outcomes for each phase\n- Tips, gotchas, and lessons learned\n- Quick reference (paths, contacts, key info)\n\n**Why it's useful:**\n- Provides a clear roadmap when you have a complex task\n- Ensures you don't forget steps when switching between sessions\n- Makes it easy to pick up where you left off\n- Serves as documentation for similar tasks in the future\n\n**Example structure:**\n```markdown\n# Task Name - Detailed Workflow\n\n## Phase 1: Discovery\n### Session 1a: Analyze Repo A\ncd /path/to/repo-a\nclaude\n# Tell Claude: \"Read ~/prd/prj/PROJECT/TASK/task.md and sessions.md...\"\n\n### Session 1b: Analyze Repo B\ncd /path/to/repo-b\nclaude\n# Tell Claude: \"Read ~/prd/prj/PROJECT/TASK/task.md and sessions.md...\"\n```\n\n**View your workflow:**\n```bash\njust workflow PROJECT TASK\n```\n\n### Best Practices\n\n- **Implementation order matters** - Document which repo to work on first (usually consumer before producer, or API before client)\n- **Test integration** - Your Success Criteria should include integration testing across both repos\n- **Track both repos** - Session entries should note which repo work was done in\n\nExample session entry:\n```markdown\n## Session: 2025-01-15 - 3 hours\n\n**Repo: api-service**\n\n**Accomplished:**\n- Created new /chargebacks endpoint\n- Added validation logic\n...\n```\n\n## Quick Reference\n\n### Just Commands (run in ~/prd)\n\n| Command | Purpose |\n|---------|---------|\n| `just` or `just --list` | Show all available commands |\n| `just new PROJECT TASK` | Create new task with template |\n| `just edit PROJECT TASK` | Edit task.md in text editor |\n| `just view PROJECT TASK` | View task.md quickly |\n| `just sessions PROJECT TASK` | View session history |\n| `just workflow PROJECT TASK` | View workflow guide (if exists) |\n| `just list` | List all projects and tasks with status |\n| `just status` | Show overview stats |\n| `just work-on PROJECT TASK` | Show instructions for working on task |\n| `just path PROJECT TASK` | Get full path to task directory |\n| `just search KEYWORD` | Search across all tasks |\n| `just archive PROJECT TASK` | Archive completed task |\n| `just tree` | Show file tree structure |\n\n### Working with Claude Code (run in your project)\n\n```bash\n# From your actual project directory (NOT ~/prd):\ncd ~/code/your-project\nclaude\n\n# Tell Claude to load your PRD task:\n\"Read ~/prd/prj/PROJECT/TASK/task.md and sessions.md, then help me implement it\"\n\n# Tell Claude to save your session:\n\"Update ~/prd/prj/PROJECT/TASK/sessions.md with today's session\"\n```\n\n## 🔄 Staying Up to Date\n\nThis system is actively maintained with new features and improvements. Here's how to stay current:\n\n### Getting Updates\n\n```bash\ncd ~/prd\n\n# Pull latest improvements from upstream\ngit fetch upstream\ngit merge upstream/main\n\n# If you haven't set up upstream yet, see Installation section above\n```\n\n**What gets updated when you pull:**\n- ✅ New automation commands in Justfile\n- ✅ Documentation improvements in README\n- ✅ Enhanced templates in TEMPLATE.md\n- ✅ Updates to the example project (acme-app)\n\n**What stays completely untouched:**\n- ✅ Your projects (everything in `prj/` except acme-app)\n- ✅ Your work-in-progress tasks\n- ✅ Your session histories and notes\n\n### Verifying Your Setup\n\nTo ensure your projects are private and protected:\n\n```bash\ncd ~/prd\n\n# Check what git is tracking\ngit ls-files prj/\n# Should ONLY show: prj/acme-app/* files\n\n# Create a test project\njust new test-project test-task\n\n# Verify it's not tracked\ngit status\n# Should show: \"nothing to commit, working tree clean\"\n# (your test project won't appear in untracked files)\n\n# Clean up\nrm -rf prj/test-project\n```\n\n### Optional: Version Control Your Own Projects\n\nIf you want to track your own projects separately:\n\n```bash\n# Option 1: Separate repo for projects\ncd ~/prd/prj\ngit init\ngit add .\ngit commit -m \"My personal PRD projects\"\n\n# Option 2: Modify .gitignore to track specific projects\n# Edit .gitignore and add:\n# !prj/my-important-project\n# !prj/my-important-project/**\n```\n\n## Customization \u0026 Tips\n\nThis system is designed to be simple and flexible. Adapt it to your needs:\n- **Add custom fields** to task.md (e.g., Priority, Estimated Time)\n- **Change the session format** to match your workflow\n- **Create project-specific templates** for common task types\n- **Extend the Justfile** with your own automation recipes\n- **Add git tracking** to your PRD directory to version control your tasks\n\n### Example: Adding a Custom Justfile Recipe\n\nEdit `~/prd/Justfile` and add:\n```justfile\n# List only blocked tasks\nblocked:\n    @grep -r \"Status.*Blocked\" --include=\"sessions.md\" . || echo \"No blocked tasks\"\n```\n\n### Example: Tracking the PRD System\n\nThe system files are already tracked if you forked/cloned the repo. To track your own projects:\n\n```bash\n# Track a specific project (modify .gitignore first)\n# Add to .gitignore:\n# !prj/my-important-project\n# !prj/my-important-project/**\n\ngit add prj/my-important-project\ngit commit -m \"Add my important project\"\n```\n\nThe goal is to make it easier to manage complex tasks across multiple projects without losing context or progress.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fvpetreski%2Fprd","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fvpetreski%2Fprd","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fvpetreski%2Fprd/lists"}