From fac7c59f63b49c39d7b7c75b62d2773f48d2ef48 Mon Sep 17 00:00:00 2001
From: DanConwayDev <DanConwayDev@protonmail.com>
Date: Tue, 13 Jan 2026 08:52:11 +0000
Subject: [PATCH] docs: update README with final dcdev-issues structure

---
 README.md | 56 +++++++++++++++++++++++++++++++++++++++++++++++++++++++
 1 file changed, 56 insertions(+)
 create mode 100644 README.md

diff --git a/README.md b/README.md
new file mode 100644
index 0000000..84b63d8
--- /dev/null
+++ b/README.md
@@ -0,0 +1,56 @@
+# dcdev-issues - User-Specific Issue Tracking
+
+This is an orphan git branch for tracking issues across all worktrees in this repository.
+
+## Structure
+
+- **Branch**: `dcdev-issues` (orphan branch, no shared history with main)
+- **Worktree**: `worktrees/dcdev-issues/`
+- **Issues**: Markdown files at the top level of this worktree
+
+## Access from Feature Worktrees
+
+All feature worktrees have a symlink: `dcdev/issues/` → `../dcdev-issues/`
+
+Example from a feature worktree:
+```bash
+cd worktrees/deletion-support
+ls dcdev/issues/           # List all issues
+cat dcdev/issues/foo.md    # Read an issue
+```
+
+## Creating or Updating Issues
+
+1. Navigate to the issues worktree:
+   ```bash
+   cd worktrees/dcdev-issues
+   ```
+
+2. Create/edit issue file:
+   ```bash
+   vim my-new-issue.md
+   ```
+
+3. Commit the change:
+   ```bash
+   git add .
+   git commit -m "issue: brief description"
+   ```
+
+## Why This Setup?
+
+- **User-specific**: `dcdev` namespace prevents conflicts with project files
+- **No .gitignore pollution**: Uses `.git/info/exclude` instead
+- **Portable**: Skills can set this up in any git repository
+- **Version controlled**: Full git history for issue tracking
+- **Shared across worktrees**: One source of truth for all issues
+
+## Git Ignore Configuration
+
+The `dcdev/` directory is ignored via `.git/info/exclude`:
+```bash
+# .git/info/exclude contains:
+dcdev
+```
+
+This keeps the symlink out of version control without modifying the project's `.gitignore`.