Extra Reference Material

The

extra/

extra/

Finding extra/ (Critical for Worktrees)

The

extra/

Detection logic:

# If CWD contains .worktrees/, extract project root
# /home/user/project/.worktrees/feature → /home/user/project
pwd | grep -q '\.worktrees/' && echo "${PWD%/.worktrees/*}/extra" || echo "./extra"

Example:

• Working in:

  /home/user/myapp/.worktrees/auth-feature/src/

• extra/

  is at:

  /home/user/myapp/extra/

  (NOT

  /home/user/myapp/.worktrees/auth-feature/extra/

  )

Verify with:

git worktree list

Directory Structure

extra/
├── <repo-name>/           # Full git clones (e.g., extra/ratatui/)
├── <name>_docs/           # Documentation folders
├── <name>.md              # Single-file docs
├── screenshots/           # Visual references
└── *.pdf                  # PDF documentation

Using Reference Material

Priority order:

1. Search

   extra/

   with Grep/Glob
2. If not found → HALT (do NOT web search)

Quick lookup:

ls extra/

# Find files by name
find extra/<repo-name> -name "*.md" -o -name "border*" 2>/dev/null

# Search with ripgrep - ALWAYS scope to a subpath
rg "pattern" extra/<repo-name>/src/

ripgrep notes:

• NEVER run

  rg

  on

  extra/

  directly - millions of hits in cloned repos
• Always scope to a specific subpath:

  extra/<repo>/src/

  ,

  extra/<name>_docs/

• Passing the subpath directly respects the repo's own .gitignore (desirable)
• For broad searching, use a Task agent instead

Exploring Reference Material

Small files - read directly:

• Single markdown documents
• Images/screenshots
• Small config files
• Files you already know the path to

Large codebases - use Task tool agents:

Directly reading entire reference codebases pollutes your context window. Instead:

1. Review your available Task tool agents (Explore, codebase-analyzer, etc.)
2. Choose an appropriate agent for the task
3. Dispatch it to explore and summarize

Example:

Use Task tool with subagent_type=Explore:
- Prompt: "In extra/ratatui/, find how borders are implemented.
  Return: file paths, key types/functions, and a brief explanation."
- The subagent explores, you receive a concise summary

When to use agents:

• Searching for implementation patterns in cloned repos
• Understanding library architecture
• Finding specific APIs or types
• Generating documentation from source

What to do directly:

• ls extra/

  to see what's available

• find

  to locate files by name
• Scoped

  rg

  to verify something exists (always pass subpath, never top-level extra/)
• Read single markdown/text files
• View images and screenshots

HALT Behavior (Hard Stop)

If required material is not in

extra/

1. HALT immediately - stop current task
2. Report what's missing with specific suggestions
3. Wait for user - do NOT fall back to web search

HALT message format:

HALT: Missing reference material.

Required: <what you need>
Suggestion: <how to add it>

Example commands:
  git clone <url> extra/<name>
  # or
  Add file: extra/<name>.md

Example HALT:

HALT: Missing reference material.

Required: Ratatui widget implementation patterns
Suggestion: Clone ratatui source:
  git clone https://github.com/ratatui/ratatui extra/ratatui

Required: API documentation for external service
Suggestion: Save docs to extra/service_api.md or extra/service_docs/

Adding Material

With user permission, add material directly:

# Clone reference repos
git clone https://github.com/org/repo extra/repo

# Create doc folders
mkdir -p extra/screenshots

# Download specific files
curl -o extra/spec.pdf https://example.com/spec.pdf

Naming conventions:

• Repos:

  extra/<repo-name>/

  (use original repo name)
• Docs:

  extra/<name>_docs/

  or

  extra/<name>.md

• Screenshots:

  extra/screenshots/<descriptive-name>.png

Common Mistakes

ls extra/