Add 3 MCP tools, h3 splitting, CONTRIBUTING.md, remove TODO.md

AGENTS.md

@@ -111,6 +111,83 @@ Four Docker Compose services:
 3. Verify with `get_screenshot()`
 4. Then implement the code changes
 
+## GitHub Project Task Workflow
+
+When the user says **"do tasks"**, **"pick up tasks"**, **"work on ready tasks"**, or similar — follow this workflow:
+
+### 1. Parse tasks from Ready column
+
+```bash
+# Get all items in Ready status
+gh project item-list 2 --owner @me --format json | python3 -c "
+import json, sys
+data = json.load(sys.stdin)
+for item in data.get('items', []):
+    if item.get('status') == 'Ready':
+        print(f\"#{item.get('number', '?')} — {item['title']} (Size: {item.get('size', '?')}, Priority: {item.get('priority', '?')})\")"
+```
+
+Present the list to the user and ask which tasks to implement (or implement all if user says so).
+
+### 2. Plan implementation
+
+Enter plan mode. For each task:
+- Read the GitHub issue body (`gh issue view <number>`)
+- Identify affected files and dependencies between tasks
+- Determine implementation order (simplest first, dependencies respected)
+
+### 3. Implement each task
+
+For each task being worked on, **first** move it to "In progress":
+
+```bash
+# Move to "In progress" BEFORE starting implementation
+gh project item-edit --project-id PVT_kwHOAcEVs84BR7UH --id <ITEM_ID> \
+  --field-id PVTSSF_lAHOAcEVs84BR7UHzg_nCMQ --single-select-option-id e56656c8
+```
+
+Then:
+- Implement the changes following existing code patterns
+- Add tests in `tests/test_mcp_tools.py` and/or `tests/test_ui_api.py`
+- Run tests after each task: `.venv/bin/pytest tests/ -v -x`
+- Update docs (`README.md`, `docs/tool-reference.md`, `AGENTS.md`) if needed
+
+### 4. Move to "In review"
+
+After implementation + tests pass, move the task to **In review** (NOT Done):
+
+```bash
+# Move to "In review"
+gh project item-edit --project-id PVT_kwHOAcEVs84BR7UH --id <ITEM_ID> \
+  --field-id PVTSSF_lAHOAcEVs84BR7UHzg_nCMQ --single-select-option-id 65241aaf
+```
+
+Do NOT close the issue yet. The user will verify and move to Done / close manually.
+
+### 5. Project board column reference
+
+| Column | Option ID | Meaning |
+|--------|-----------|---------|
+| Backlog | `bf802e7a` | Not prioritized yet |
+| Ready | `83e6dfa4` | Prioritized, ready to pick up |
+| In progress | `e56656c8` | Currently being worked on |
+| In review | `65241aaf` | Implemented, needs user verification before Done |
+| Done | `d0415fde` | Verified and complete |
+
+**Project ID:** `PVT_kwHOAcEVs84BR7UH`
+**Status field ID:** `PVTSSF_lAHOAcEVs84BR7UHzg_nCMQ`
+
+### Getting item IDs
+
+```bash
+# Find item IDs for specific issues
+gh project item-list 2 --owner @me --format json | python3 -c "
+import json, sys
+data = json.load(sys.stdin)
+for item in data.get('items', []):
+    print(f\"{item['id']}  #{item.get('number', '?')}  {item['title']}  [{item.get('status', '?')}]\")"
+```
+
 ## Common Tasks
 
 **Adding a new MCP tool:**
@@ -165,6 +242,8 @@ Always work on **feature branches**, never commit directly to `main` or `multius
 # 1. Create branch from main
 git checkout -b feature/my-feature main
 
+ONLY AFTER USER APPROVE
+
 # 2. Make changes, commit
 git add <files>
 git commit -m "Description of changes"
@@ -183,7 +262,12 @@ gh pr create --base main --title "Short title" --body "..."
 
 ## Critical Rules
 
-- **NEVER DROP THE DATABASE.** Do not run `DROP SCHEMA`, `DROP DATABASE`, `DROP TABLE` or any destructive SQL on the PRDforge PostgreSQL database. It contains user project data (sections, revisions, dependencies, comments) that cannot be recreated. For database restores, use `psql < backup.sql` directly — never drop-and-restore. Always ask the user before any destructive database operation.
+- **BACKUP BEFORE ANY DATABASE CHANGES.** The PRDforge database is a live service storing user PRD projects, sections, revisions, comments, and dependencies. Before ANY operation that touches the database (schema migrations, ALTER TABLE, column type changes, docker compose down -v, volume operations), **create a backup first**:
+  ```bash
+  docker compose exec postgres pg_dump -U prdforge prdforge > backup_$(date +%Y%m%d_%H%M%S).sql
+  ```
+  This is non-negotiable. Lost data cannot be recreated — PRD content is user-authored.
+- **NEVER DROP THE DATABASE.** Do not run `DROP SCHEMA`, `DROP DATABASE`, `DROP TABLE`, `docker compose down -v`, or any destructive SQL/Docker command. For schema changes, use `ALTER TABLE` with `IF NOT EXISTS` guards. For restores, use `psql < backup.sql` — never drop-and-restore. Always ask the user before any destructive database operation.
 - **Never add AI/agent signatures to git commits.** No "Co-Authored-By: Claude", "Generated by AI", etc.
 - **Never install packages globally.** Always use `uvx` or a virtual environment (`.venv`).
 

CONTRIBUTING.md

@@ -0,0 +1,129 @@
+# Contributing to PRDforge
+
+## Prerequisites
+
+- **Docker** (Docker Desktop or Docker Engine + Compose)
+- **Python 3.11+** (for backend/MCP server development)
+- **Node 22+** and **Yarn** (for frontend development)
+
+## Quick Start
+
+```bash
+git clone <repo-url> && cd PRDforge
+./install.sh
+```
+
+This starts all services (PostgreSQL, MCP server, API, Frontend, Redis) and seeds a sample project.
+
+## Local Development
+
+### Backend (API + MCP Server)
+
+Services run in Docker. Watch logs:
+
+```bash
+docker compose logs -f python-api mcp-server
+```
+
+To iterate on Python code, the containers mount source directories — changes are picked up on restart:
+
+```bash
+docker compose restart python-api mcp-server
+```
+
+### Frontend
+
+```bash
+cd frontend
+yarn install
+yarn dev
+```
+
+Runs on http://localhost:3000 with hot reload.
+
+### Database
+
+PostgreSQL runs in Docker on port 5432 (or next available if taken).
+
+Connect directly:
+
+```bash
+docker compose exec postgres psql -U prdforge -d prdforge
+```
+
+## Running Tests
+
+### Backend tests (MCP + API)
+
+```bash
+# Requires running PostgreSQL (docker compose up postgres -d)
+pytest tests/ -v
+```
+
+### Frontend tests
+
+```bash
+cd frontend
+yarn lint
+yarn typecheck
+yarn test --run
+```
+
+## Database Migrations
+
+SQL files live in `db/` with numbered prefixes (`01_init.sql`, `02_comments.sql`, etc.).
+
+**Pattern for new migrations:**
+- Use `IF NOT EXISTS` / `DO $$ ... $$` blocks for idempotency
+- Name: `NN_description.sql` where NN is the next number
+- Test locally before committing
+
+## Adding MCP Tools
+
+All MCP tools are in `mcp_server/server.py`. Follow the existing pattern:
+
+```python
+@mcp.tool(
+    annotations={"readOnlyHint": False, "destructiveHint": False, "idempotentHint": True, "openWorldHint": False}
+)
+async def prd_your_tool(project: str, ...) -> str:
+    """Docstring shown to Claude — keep it concise."""
+    try:
+        pool = await get_pool()
+        pid = await resolve_project_id(pool, project)
+        if not pid:
+            return err(f"project '{project}' not found")
+
+        # ... logic ...
+
+        return ok({...})
+    except Exception as e:
+        logger.error("prd_your_tool: %s", e)
+        return err(str(e))
+```
+
+**Transaction rule:** Inside `conn.transaction()`, never `return err(...)` — always `raise ValueError(msg)`. Catch outside to return `err()`. This ensures auto-rollback on any validation failure.
+
+After adding a tool:
+1. Add tests in `tests/test_mcp_tools.py`
+2. Update tool count in `README.md` and `docs/tool-reference.md`
+3. Add entry in `docs/tool-reference.md` tool index
+
+## Code Style
+
+- Python: standard library formatting, type hints where useful
+- Frontend: ESLint + TypeScript strict mode (`yarn lint && yarn typecheck`)
+- No AI/agent signatures in git commits (no "Co-Authored-By: Claude", "Generated by AI", etc.)
+
+## Commit Guidelines
+
+- Write clear, concise commit messages
+- No AI-generated signatures or attributions
+- One logical change per commit
+
+## Pull Request Process
+
+1. Create a feature branch from `main`
+2. Ensure all tests pass (`pytest tests/ -v` and `cd frontend && yarn lint && yarn typecheck && yarn test --run`)
+3. Update documentation if adding/changing tools
+4. Open PR with description of changes

README.md

@@ -4,7 +4,7 @@
 
 ![PRDforge Demo](demo.gif)
 
-PRD Forge splits your product requirements into independently addressable sections stored in PostgreSQL, then gives Claude surgical read/write access through 31 MCP tools. The result: edits that used to burn ~15,000 tokens now cost 500-2,000 — an **85-95% reduction** in context per operation.
+PRD Forge splits your product requirements into independently addressable sections stored in PostgreSQL, then gives Claude surgical read/write access through 34 MCP tools. The result: edits that used to burn ~15,000 tokens now cost 500-2,000 — an **85-95% reduction** in context per operation.
 
 ## The Problem
 
@@ -22,7 +22,7 @@ Each section stores both its full **content** and a short **summary** (1-3 sente
 
 ## Features
 
-- **31 MCP tools** — read, write, search, import/export, manage dependencies, track revisions, resolve comments
+- **34 MCP tools** — read, write, search, import/export, manage dependencies, track revisions, resolve comments
 - **Multi-user auth** — Better Auth (email/password + Google OAuth), 5 roles (owner/admin/editor/commenter/viewer), org-scoped access control
 - **Real-time collaboration** — WebSocket presence, live section updates across clients
 - **Project templates** — start with Blank, SaaS MVP, Mobile App, or API Design — pre-built section structures with starter content
@@ -52,7 +52,7 @@ Five Docker services:
 | Service | Stack | Port | Purpose |
 |---------|-------|------|---------|
 | **PostgreSQL 16** | 15+ tables, 2 views | 5432 | Source of truth |
-| **MCP Server** | FastMCP / Python | 8080 | 31 tools for Claude |
+| **MCP Server** | FastMCP / Python | 8080 | 34 tools for Claude |
 | **Python API** | FastAPI | 8088 | REST backend (projects, sections, chat, auth, audit) |
 | **Frontend** | Next.js 15, React 19, Tailwind v4, shadcn/ui, Better Auth | 3000 | Web UI |
 | **Redis 7** | — | 6379 | WebSocket token uniqueness, real-time pub/sub |
@@ -165,7 +165,7 @@ Chat is an experimental feature, disabled by default. Enable per-project in **Se
 
 ## MCP Tools Reference
 
-31 MCP tools across 10 groups: project management, section CRUD, dependencies, comments, context/search, revisions, import/export, batch operations, token stats, and settings.
+34 MCP tools across 10 groups: project management, section CRUD, dependencies, comments, context/search, revisions, import/export, batch operations, token stats, and settings.
 
 See **[docs/tool-reference.md](docs/tool-reference.md)** for the full tool table and usage examples.
 
@@ -205,7 +205,7 @@ PRDforge/
 ├── docker-compose.yml
 ├── frontend/            # Next.js 15 app (React 19, Tailwind v4, shadcn/ui)
 ├── api/                 # FastAPI backend (REST, chat, auth, WebSocket)
-├── mcp_server/          # FastMCP server (31 tools, stdio + HTTP)
+├── mcp_server/          # FastMCP server (34 tools, stdio + HTTP)
 ├── shared/              # Shared Python modules (settings, constants, templates)
 ├── db/                  # PostgreSQL schema migrations (13 files)
 ├── tests/               # pytest test suite
@@ -246,6 +246,10 @@ docker exec prdforge-postgres-1 pg_dump -U prdforge prdforge > backup.sql
 docker compose down -v && docker compose up -d
 ```
 
+## Contributing
+
+See [CONTRIBUTING.md](CONTRIBUTING.md) for development setup, testing, and contribution guidelines.
+
 ## License
 
 MIT