oden-forge 2.0.0

package/.claude/hooks/README.md

@@ -0,0 +1,130 @@
+# Claude Hooks Configuration
+
+## Bash Worktree Fix Hook
+
+This hook automatically fixes the Bash tool's directory reset issue when working in git worktrees.
+
+### Problem
+
+The Bash tool resets to the main project directory after every command, making it impossible to work in worktrees without manually prefixing every command with `cd /path/to/worktree &&`.
+
+### Solution
+
+The pre-tool-use hook automatically detects when you're in a worktree and injects the necessary `cd` prefix to all Bash commands.
+
+### How It Works
+
+1. **Detection**: Before any Bash command executes, the hook checks if `.git` is a file (worktree) or directory (main repo)
+2. **Injection**: If in a worktree, prepends `cd /absolute/path/to/worktree && ` to the command
+3. **Transparency**: Agents don't need to know about this - it happens automatically
+
+### Configuration
+
+Add to your `.claude/settings.json`:
+
+
+```json
+{
+  "hooks": {
+    "pre-tool-use": {
+      "Bash": {
+        "enabled": true,
+        "script": ".claude/hooks/bash-worktree-fix.sh",
+        "apply_to_subagents": true
+      }
+    }
+  }
+}
+```
+
+### Testing
+
+To test the hook:
+
+```bash
+# Enable debug mode
+export CLAUDE_HOOK_DEBUG=true
+
+# Test in main repo (should pass through)
+.claude/hooks/bash-worktree-fix.sh "ls -la"
+
+# Test in worktree (should inject cd)
+cd /path/to/worktree
+.claude/hooks/bash-worktree-fix.sh "npm install"
+# Output: cd "/path/to/worktree" && npm install
+```
+
+### Advanced Features
+
+The script handles:
+
+- Background processes (`&`)
+- Piped commands (`|`)
+- Environment variable prefixes (`VAR=value command`)
+- Commands that already have `cd`
+- Commands using absolute paths
+- Debug logging with `CLAUDE_HOOK_DEBUG=true`
+
+### Edge Cases Handled
+
+1. **Double-prefix prevention**: Won't add prefix if command already starts with `cd`
+2. **Absolute paths**: Skips injection for commands using absolute paths
+3. **Special commands**: Skips for `pwd`, `echo`, `export`, etc. that don't need context
+4. **Background processes**: Correctly handles `&` at the end of commands
+5. **Pipe chains**: Injects only at the start of pipe chains
+
+### Troubleshooting
+
+If the hook isn't working:
+
+1. **Verify the hook is executable:**
+   ```bash
+   chmod +x .claude/hooks/bash-worktree-fix.sh
+   ```
+
+2. **Enable debug logging to see what's happening:**
+   ```bash
+   export CLAUDE_HOOK_DEBUG=true
+   ```
+
+3. **Test the hook manually with a sample command:**
+   ```bash
+   cd /path/to/worktree
+   .claude/hooks/bash-worktree-fix.sh "npm test"
+   ```
+
+4. **Check that your settings.json is valid JSON:**
+   ```bash
+   cat .claude/settings.json | python -m json.tool
+   ```
+
+### Integration with Claude
+
+Once configured, this hook will:
+
+- Automatically apply to all Bash tool invocations
+- Work for both main agent and sub-agents
+- Be completely transparent to users
+- Eliminate the need for worktree-specific instructions
+
+### Result
+
+With this hook in place, agents can work in worktrees naturally:
+
+**Agent writes:**
+
+```bash
+npm install
+git status
+npm run build
+```
+
+**Hook transforms to:**
+
+```bash
+cd /path/to/my/project/epic-feature && npm install
+cd /path/to/my/project/epic-feature && git status
+cd /path/to/my/project/epic-feature && npm run build
+```
+
+**Without the agent knowing or caring about the worktree context!**

package/.claude/hooks/bash-worktree-fix.sh

@@ -0,0 +1,189 @@
+#!/bin/sh
+# POSIX-compliant pre-tool-use hook for Bash tool
+# If inside a Git *worktree checkout*, prefix the incoming command with:
+#   cd '<worktree_root>' && <original_command>
+# No sh -c. No tokenization. Quoting preserved. Robust worktree detection.
+
+DEBUG_MODE="${CLAUDE_HOOK_DEBUG:-false}"
+
+debug_log() {
+    case "${DEBUG_MODE:-}" in
+        true|TRUE|1|yes|YES)
+            printf '%s\n' "DEBUG [bash-worktree-fix]: $*" >&2
+            ;;
+    esac
+}
+
+# Safely single-quote a string for shell usage: foo'bar -> 'foo'"'"'bar'
+shell_squote() {
+    printf "%s" "$1" | sed "s/'/'\"'\"'/g"
+}
+
+# Detect if CWD is inside a *linked worktree* and print the worktree root.
+# Returns 0 with path on stdout if yes; 1 otherwise.
+get_worktree_path() {
+    check_dir="$(pwd)"
+
+    if [ ! -d "${check_dir}" ]; then
+        debug_log "pwd is not a directory: ${check_dir}"
+        return 1
+    fi
+
+    while [ "${check_dir}" != "/" ]; do
+        if [ -f "${check_dir}/.git" ]; then
+            gitdir_content=""
+            if [ -r "${check_dir}/.git" ]; then
+                IFS= read -r gitdir_content < "${check_dir}/.git" || gitdir_content=""
+                # Strip a possible trailing CR (CRLF files)
+                gitdir_content=$(printf %s "$gitdir_content" | tr -d '\r')
+            else
+                debug_log "Unreadable .git file at: ${check_dir}"
+            fi
+
+            case "${gitdir_content}" in
+                gitdir:*)
+                    gitdir_path=${gitdir_content#gitdir:}
+                    # Trim leading spaces (portable)
+                    while [ "${gitdir_path# }" != "${gitdir_path}" ]; do
+                        gitdir_path=${gitdir_path# }
+                    done
+                    # Normalize to absolute
+                    case "${gitdir_path}" in
+                        /*) abs_gitdir="${gitdir_path}" ;;
+                        *)  abs_gitdir="${check_dir}/${gitdir_path}" ;;
+                    esac
+                    if [ -d "${abs_gitdir}" ]; then
+                        case "${abs_gitdir}" in
+                            */worktrees/*)
+                                debug_log "Detected worktree root: ${check_dir} (gitdir: ${abs_gitdir})"
+                                printf '%s\n' "${check_dir}"
+                                return 0
+                                ;;
+                            *)
+                                debug_log "Non-worktree .git indirection at: ${check_dir}"
+                                return 1
+                                ;;
+                        esac
+                    else
+                        debug_log "gitdir path does not exist: ${abs_gitdir}"
+                        return 1
+                    fi
+                    ;;
+                *)
+                    debug_log "Unknown .git file format at: ${check_dir}"
+                    return 1
+                    ;;
+            esac
+
+        elif [ -d "${check_dir}/.git" ]; then
+            # Regular repo with .git directory — not a linked worktree
+            debug_log "Found regular git repo at: ${check_dir}"
+            return 1
+        fi
+
+        check_dir=$(dirname "${check_dir}")
+    done
+
+    debug_log "No git repository found"
+    return 1
+}
+
+# Decide whether to skip prefixing.
+# Returns 0 => SKIP (pass through as-is)
+# Returns 1 => Prefix with cd
+should_skip_command() {
+    cmd=$1
+
+    # Empty or whitespace-only?
+    # If there are no non-space characters, skip.
+    if [ -z "${cmd##*[![:space:]]*}" ]; then
+        debug_log "Skipping: empty/whitespace-only command"
+        return 0
+    fi
+
+    # Starts with optional spaces then 'cd' (with or without args)?
+    case "${cmd}" in
+        [[:space:]]cd|cd|[[:space:]]cd[[:space:]]*|cd[[:space:]]*)
+            debug_log "Skipping: command already begins with cd"
+            return 0
+            ;;
+    esac
+
+    # Builtins / trivial commands that don't require dir context
+    case "${cmd}" in
+        :|[[:space:]]:|true|[[:space:]]true|false|[[:space:]]false|\
+        pwd|[[:space:]]pwd*|\
+        echo|[[:space:]]echo*|\
+        export|[[:space:]]export*|\
+        alias|[[:space:]]alias*|\
+        unalias|[[:space:]]unalias*|\
+        set|[[:space:]]set*|\
+        unset|[[:space:]]unset*|\
+        readonly|[[:space:]]readonly*|\
+        umask|[[:space:]]umask*|\
+        times|[[:space:]]times*|\
+        .|[[:space:]].[[:space:]]*)
+            debug_log "Skipping: trivial/builtin command"
+            return 0
+            ;;
+    esac
+
+    # Do NOT skip absolute-path commands; many still depend on cwd.
+    # We want: cd '<root>' && /abs/cmd ... to preserve semantics.
+
+    return 1
+}
+
+# Inject the worktree prefix without changing semantics.
+# We do NOT wrap in 'sh -c'. We just prepend 'cd ... && '.
+# We preserve trailing '&' if present as the last non-space char.
+inject_prefix() {
+    worktree_path=$1
+    command=$2
+
+    qpath=$(shell_squote "${worktree_path}")
+
+    # Right-trim spaces (portable loop)
+    trimmed=${command}
+    while [ "${trimmed% }" != "${trimmed}" ]; do
+        trimmed=${trimmed% }
+    done
+
+    case "${trimmed}" in
+        *"&")
+            cmd_without_bg=${trimmed%&}
+            while [ "${cmd_without_bg% }" != "${cmd_without_bg}" ]; do
+                cmd_without_bg=${cmd_without_bg% }
+            done
+            printf '%s\n' "cd '${qpath}' && ${cmd_without_bg} &"
+            ;;
+        *)
+            printf '%s\n' "cd '${qpath}' && ${command}"
+            ;;
+    esac
+}
+
+main() {
+    # Capture the raw command line exactly as provided
+    original_command="$*"
+
+    debug_log "Processing command: ${original_command}"
+
+    # Fast path: if not in a worktree, pass through unchanged
+    if ! worktree_path="$(get_worktree_path)"; then
+        debug_log "Not in worktree, passing through unchanged"
+        printf '%s\n' "${original_command}"
+        exit 0
+    fi
+
+    if should_skip_command "${original_command}"; then
+        debug_log "Passing through unchanged"
+        printf '%s\n' "${original_command}"
+    else
+        modified_command="$(inject_prefix "${worktree_path}" "${original_command}")"
+        debug_log "Modified command: ${modified_command}"
+        printf '%s\n' "${modified_command}"
+    fi
+}
+
+main "$@"

package/.claude/rules/agent-coordination.md

@@ -0,0 +1,224 @@
+# Agent Coordination
+
+Rules for multiple agents working in parallel within the same epic worktree.
+
+## Parallel Execution Principles
+
+1. **File-level parallelism** - Agents working on different files never conflict
+2. **Explicit coordination** - When same file needed, coordinate explicitly
+3. **Fail fast** - Surface conflicts immediately, don't try to be clever
+4. **Human resolution** - Conflicts are resolved by humans, not agents
+
+## Work Stream Assignment
+
+Each agent is assigned a work stream from the issue analysis:
+```yaml
+# From {issue}-analysis.md
+Stream A: Database Layer
+  Files: src/db/*, migrations/*
+  Agent: backend-specialist
+
+Stream B: API Layer
+  Files: src/api/*
+  Agent: api-specialist
+```
+
+Agents should only modify files in their assigned patterns.
+
+## File Access Coordination
+
+### Check Before Modify
+Before modifying a shared file:
+```bash
+# Check if file is being modified
+git status {file}
+
+# If modified by another agent, wait
+if [[ $(git status --porcelain {file}) ]]; then
+  echo "Waiting for {file} to be available..."
+  sleep 30
+  # Retry
+fi
+```
+
+### Atomic Commits
+Make commits atomic and focused:
+```bash
+# Good - Single purpose commit
+git add src/api/users.ts src/api/users.test.ts
+git commit -m "Issue #1234: Add user CRUD endpoints"
+
+# Bad - Mixed concerns
+git add src/api/* src/db/* src/ui/*
+git commit -m "Issue #1234: Multiple changes"
+```
+
+## Communication Between Agents
+
+### Through Commits
+Agents see each other's work through commits:
+```bash
+# Agent checks what others have done
+git log --oneline -10
+
+# Agent pulls latest changes
+git pull origin epic/{name}
+```
+
+### Through Progress Files
+Each stream maintains progress:
+```markdown
+# .claude/epics/{epic}/updates/{issue}/stream-A.md
+---
+stream: Database Layer
+agent: backend-specialist
+started: {datetime}
+status: in_progress
+---
+
+## Completed
+- Created user table schema
+- Added migration files
+
+## Working On
+- Adding indexes
+
+## Blocked
+- None
+```
+
+### Through Analysis Files
+The analysis file is the contract:
+```yaml
+# Agents read this to understand boundaries
+Stream A:
+  Files: src/db/*  # Agent A only touches these
+Stream B:
+  Files: src/api/* # Agent B only touches these
+```
+
+## Handling Conflicts
+
+### Conflict Detection
+```bash
+# If commit fails due to conflict
+git commit -m "Issue #1234: Update"
+# Error: conflicts exist
+
+# Agent should report and wait
+echo "❌ Conflict detected in {files}"
+echo "Human intervention needed"
+```
+
+### Conflict Resolution
+Always defer to humans:
+1. Agent detects conflict
+2. Agent reports issue
+3. Agent pauses work
+4. Human resolves
+5. Agent continues
+
+Never attempt automatic merge resolution.
+
+## Synchronization Points
+
+### Natural Sync Points
+- After each commit
+- Before starting new file
+- When switching work streams
+- Every 30 minutes of work
+
+### Explicit Sync
+```bash
+# Pull latest changes
+git pull --rebase origin epic/{name}
+
+# If conflicts, stop and report
+if [[ $? -ne 0 ]]; then
+  echo "❌ Sync failed - human help needed"
+  exit 1
+fi
+```
+
+## Agent Communication Protocol
+
+### Status Updates
+Agents should update their status regularly:
+```bash
+# Update progress file every significant step
+echo "✅ Completed: Database schema" >> stream-A.md
+git add stream-A.md
+git commit -m "Progress: Stream A - schema complete"
+```
+
+### Coordination Requests
+When agents need to coordinate:
+```markdown
+# In stream-A.md
+## Coordination Needed
+- Need to update src/types/index.ts
+- Will modify after Stream B commits
+- ETA: 10 minutes
+```
+
+## Parallel Commit Strategy
+
+### No Conflicts Possible
+When working on completely different files:
+```bash
+# These can happen simultaneously
+Agent-A: git commit -m "Issue #1234: Update database"
+Agent-B: git commit -m "Issue #1235: Update UI"
+Agent-C: git commit -m "Issue #1236: Add tests"
+```
+
+### Sequential When Needed
+When touching shared resources:
+```bash
+# Agent A commits first
+git add src/types/index.ts
+git commit -m "Issue #1234: Update type definitions"
+
+# Agent B waits, then proceeds
+# (After A's commit)
+git pull
+git add src/api/users.ts
+git commit -m "Issue #1235: Use new types"
+```
+
+## Best Practices
+
+1. **Commit early and often** - Smaller commits = fewer conflicts
+2. **Stay in your lane** - Only modify assigned files
+3. **Communicate changes** - Update progress files
+4. **Pull frequently** - Stay synchronized with other agents
+5. **Fail loudly** - Report issues immediately
+6. **Never force** - No `--force` flags ever
+
+## Common Patterns
+
+### Starting Work
+```bash
+1. cd ../epic-{name}
+2. git pull
+3. Check {issue}-analysis.md for assignment
+4. Update stream-{X}.md with "started"
+5. Begin work on assigned files
+```
+
+### During Work
+```bash
+1. Make changes to assigned files
+2. Commit with clear message
+3. Update progress file
+4. Check for new commits from others
+5. Continue or coordinate as needed
+```
+
+### Completing Work
+```bash
+1. Final commit for stream
+2. Update stream-{X}.md with "completed"
+3. Check if other streams need help
+4. Report completion
+```

package/.claude/rules/branch-operations.md

@@ -0,0 +1,147 @@
+# Branch Operations
+
+Git branches enable parallel development by allowing multiple developers to work on the same repository with isolated changes.
+
+## Creating Branches
+
+Always create branches from a clean main branch:
+```bash
+# Ensure main is up to date
+git checkout main
+git pull origin main
+
+# Create branch for epic
+git checkout -b epic/{name}
+git push -u origin epic/{name}
+```
+
+The branch will be created and pushed to origin with upstream tracking.
+
+## Working in Branches
+
+### Agent Commits
+- Agents commit directly to the branch
+- Use small, focused commits
+- Commit message format: `Issue #{number}: {description}`
+- Example: `Issue #1234: Add user authentication schema`
+
+### File Operations
+```bash
+# Working directory is the current directory
+# (no need to change directories like with worktrees)
+
+# Normal git operations work
+git add {files}
+git commit -m "Issue #{number}: {change}"
+
+# View branch status
+git status
+git log --oneline -5
+```
+
+## Parallel Work in Same Branch
+
+Multiple agents can work in the same branch if they coordinate file access:
+```bash
+# Agent A works on API
+git add src/api/*
+git commit -m "Issue #1234: Add user endpoints"
+
+# Agent B works on UI (coordinate to avoid conflicts!)
+git pull origin epic/{name}  # Get latest changes
+git add src/ui/*
+git commit -m "Issue #1235: Add dashboard component"
+```
+
+## Merging Branches
+
+When epic is complete, merge back to main:
+```bash
+# From main repository
+git checkout main
+git pull origin main
+
+# Merge epic branch
+git merge epic/{name}
+
+# If successful, clean up
+git branch -d epic/{name}
+git push origin --delete epic/{name}
+```
+
+## Handling Conflicts
+
+If merge conflicts occur:
+```bash
+# Conflicts will be shown
+git status
+
+# Human resolves conflicts
+# Then continue merge
+git add {resolved-files}
+git commit
+```
+
+## Branch Management
+
+### List Active Branches
+```bash
+git branch -a
+```
+
+### Remove Stale Branch
+```bash
+# Delete local branch
+git branch -d epic/{name}
+
+# Delete remote branch
+git push origin --delete epic/{name}
+```
+
+### Check Branch Status
+```bash
+# Current branch info
+git branch -v
+
+# Compare with main
+git log --oneline main..epic/{name}
+```
+
+## Best Practices
+
+1. **One branch per epic** - Not per issue
+2. **Clean before create** - Always start from updated main
+3. **Commit frequently** - Small commits are easier to merge
+4. **Pull before push** - Get latest changes to avoid conflicts
+5. **Use descriptive branches** - `epic/feature-name` not `feature`
+
+## Common Issues
+
+### Branch Already Exists
+```bash
+# Delete old branch first
+git branch -D epic/{name}
+git push origin --delete epic/{name}
+# Then create new one
+```
+
+### Cannot Push Branch
+```bash
+# Check if branch exists remotely
+git ls-remote origin epic/{name}
+
+# Push with upstream
+git push -u origin epic/{name}
+```
+
+### Merge Conflicts During Pull
+```bash
+# Stash changes if needed
+git stash
+
+# Pull and rebase
+git pull --rebase origin epic/{name}
+
+# Restore changes
+git stash pop
+```