path: root/docs/protocols.org

#+TITLE: Claude Code Protocols
#+AUTHOR: Craig Jennings & Claude
#+DATE: 2025-11-05

* About This File

This file contains instructions and protocols for how Claude should behave when working with Craig. These protocols are consistent across all projects.

**When to read this:**
- At the start of EVERY session (this is the single entry point)
- Before making any significant decisions
- When unclear about user preferences or conventions

**What's in this file:**
- Directory architecture (docs/ file/directory map)
- Session management protocols (context files, compacting)
- Terminology and trigger phrases
- User information and preferences
- Git commit requirements
- File format and naming conventions
- Startup instructions (runs docs/workflows/startup.org)

**What's NOT in this file:**
- Project-specific context (see notes.org)
- Session history (see notes.org)
- Active reminders (see notes.org)
- Pending decisions (see notes.org)

* Directory Architecture

The =docs/= directory has a specific structure. Every file and directory has a defined purpose:

| Item | Purpose |
|------+---------|
| =protocols.org= | Single entry point — behavioral instructions + directory map |
| =notes.org= | Project data: context, reminders, decisions, session history |
| =session-context.org= | Live crash recovery (exists only during active sessions) |
| =previous-session-history.org= | Archived session history |
| =workflows/= | Template workflows (synced from claude-templates, never edit in project) |
| =project-workflows/= | Project-specific workflows (never touched by sync) |
| =scripts/= | Template scripts |
| =announcements/= | One-off cross-project instructions from Craig |
| =someday-maybe.org= | Project ideas backlog |

* IMPORTANT - MUST DO

** CRITICAL: Always Check the Time with =date= Command

***NEVER GUESS THE TIME. ALWAYS RUN =date= TO CHECK.***

Claude's internal sense of time is unreliable. When mentioning what time it is - whether in conversation, session notes, timestamps, or scheduling - ALWAYS run:

#+begin_src bash
date "+%A %Y-%m-%d %H:%M %Z"
#+end_src

This applies to:
- "What time is it?"
- Session start/end timestamps
- Calculating time until appointments
- Setting alarms
- Any time-related statement

Do NOT estimate, guess, or rely on memory. Just run the command. It takes one second and prevents errors.

** !!!!! SESSION CONTEXT FILE - READ THIS EVERY TIME !!!!!

#+begin_example
╔══════════════════════════════════════════════════════════════════════════════╗
║  STOP. THIS IS THE MOST IMPORTANT PROTOCOL IN THIS ENTIRE FILE.              ║
║                                                                              ║
║  UPDATE docs/session-context.org EVERY 3RD RESPONSE.                         ║
║                                                                              ║
║  NOT "when convenient." NOT "when there's a lot to write." EVERY 3RD ONE.    ║
║  Count: 1, 2, 3, UPDATE. 1, 2, 3, UPDATE. 1, 2, 3, UPDATE.                   ║
║                                                                              ║
║  FAILURE TO DO THIS HAS ALREADY CAUSED LOST WORK. DON'T LET IT HAPPEN AGAIN. ║
╚══════════════════════════════════════════════════════════════════════════════╝
#+end_example

*** Why This Is Here In Giant Letters

On 2026-01-22, a session crashed and 20+ minutes of detailed workflow planning was lost because the session context file wasn't updated. The information was gone forever. This protocol exists to prevent that from EVER happening again.

*** Location
=docs/session-context.org= (always this exact path, every project)

*** UPDATE FREQUENCY: EVERY. 3RD. RESPONSE.

This means:
- Craig says something, you respond (1)
- Craig says something, you respond (2)
- Craig says something, you respond (3) → **UPDATE THE FILE NOW**
- Repeat: 1, 2, 3 → UPDATE

"Response" = one Claude response. After THREE of these, update the file. No exceptions.

*** What Counts as "Updating"

Actually write to the file using the Edit or Write tool. Not "I should update it." Not "I'll update it soon." ACTUALLY WRITE TO THE FILE.

Include:
- Current task/goal being worked on
- Key decisions made this session
- Workflows being designed (capture the FULL details)
- Data collected (vitals, measurements, paths, commands, etc.)
- Files modified or created
- Next steps planned
- ANY context needed to resume if session crashes RIGHT NOW

*** Why This Is Non-Negotiable

If the machine freezes, the network drops, or Claude crashes:
- Session history in notes.org? NOT WRITTEN YET (only at wrap-up)
- Your memory of the conversation? GONE
- The ONLY way to recover context? THIS FILE

If you don't update it, the work is LOST. Period. There is no recovery.

*** At Session Start - CHECK FOR THIS FILE
If =docs/session-context.org= exists when starting a new session, it means the previous session was interrupted. Read it IMMEDIATELY to recover context.

** Before Compacting
If you know you're about to compact, update the session context file FIRST, with enough detail that you can pick up the discussion without having lost any essential information.

** After Compacting
Review the session context file to make sure you aren't forgetting key aspects of our discussion or plan, then continue working with the user.

** When Session Ends (Wrap-Up Workflow)
Write your session summary to notes.org, leveraging the session context file. Delete session-context.org ONLY AFTER you've written the session history entry. The file's existence indicates an interrupted session, so it must be deleted at the end of each successful wrap-up.

** NEVER =cd= Into Directories You Will Delete

If you =cd= into a directory and then delete that directory, the shell's working directory becomes invalid. All subsequent commands will fail silently (exit code 1) with no useful error message. The only fix is to restart the session.

***Rule:*** Always use absolute paths for file operations in temporary directories. Never =cd= into extraction directories, build directories, or any directory that will be cleaned up.

This caused a session break on 2026-02-06 when an extraction directory was =cd='d into and then deleted during cleanup.

* Important Terminology

** "Let's run the [X] workflow" vs "I want to create an [X] workflow"

These phrases mean DIFFERENT things!

*** "Let's run/do the [workflow name] workflow"
This means: **Execute the existing workflow** for that process.

*Example:*
- "Let's run the refactor workflow" -> Read docs/workflows/refactor.org and guide through workflow
- "Let's do a refactor workflow" -> Same as above

*** "I want to create an [X] workflow"
This means: **CREATE a new workflow definition** for doing X (meta-work).
This does **NOT** mean "let's DO X right now."

*Example:*
- "I want to create a refactor workflow" -> Create docs/workflows/refactor.org using create-workflow process

When Craig uses this phrasing, trigger the create-workflow process from docs/workflows/create-workflow.org. New workflows go to =docs/project-workflows/= by default. Only put a workflow in =docs/workflows/= (and =~/projects/claude-templates/docs/workflows/=) if Craig explicitly says it's for all projects.

** "Wrap it up" / "That's a wrap" / "Let's call it a wrap"

Execute the wrap-up workflow (details in Session Protocols section below):
1. Write session notes to notes.org
2. Git commit and push all changes
3. Valediction summary

* User Information

** Calendar Location
Craig's calendars are at: =~/.emacs.d/data/*cal.org= (gcal.org, dcal.org, pcal.org)

These files are **READ-ONLY** — NEVER add anything to them.

Use this to:
- Check meeting times and schedules
- Verify when events occurred
- See what's upcoming

If there are tasks or events to schedule, put them in the todo.org file in the project root, not in Craig's calendar.

** Task List Location
Craig's global task list is available at: =/home/cjennings/sync/org/roam/inbox.org=

Use this to:
- See all the tasks that he's working on outside of projects like this one

**Note:** Some projects may have a project-specific task file (e.g., =todo.org= at project root). Check notes.org for project-specific task locations.

** Working Style

*** General Preferences
- Prefers detailed preparation before high-stakes meetings
- Values practice/role-play for negotiations and general learning
- Makes decisions based on principles and timeline arguments
- Prefers written documentation over verbal agreements

*** Emacs as a Primary Working Tool
- Craig uses Emacs as his primary tool (most everything Craig does is inside Emacs)
- Consider Emacs packages along with other software when recommending software solutions
- Look for ways to streamline routine work with Emacs custom code if no packages exist

*** Wayland Environment (No XWayland)
Craig runs a pure Wayland setup (Hyprland) and avoids XWayland/Xorg apps.

- Clipboard: Use =wl-copy= and =wl-paste= (NOT =xclip= or =xsel=)
- Window management: Use Hyprland commands (NOT =xkill=, =xdotool=, etc.)
- Prefer Wayland-native tools over X11 equivalents
- Open URLs in browser: Use =google-chrome-stable "URL" &>/dev/null &=
  - The =&>/dev/null &= is required to detach the process and suppress output
  - Without it, the command may appear to hang or produce no result

** Miscellaneous Information
- Craig currently lives in New Orleans, LA
- Craig's phone number: 510-316-9357
- Craig maintains a remote server at the cjennings.net domain
- This project is in a git repository which is associated with a remote repository on cjennings.net

** Setting Alarms / Reminders

Use Craig's =notify= script with the =at= daemon for persistent reminders.

**IMPORTANT:** Always check the current date and time (=date=) before setting alarms to ensure accurate calculations.

*** Setting an alarm
#+begin_src bash
echo 'notify alarm "Title" "Message"' | at 10:55am
#+end_src

*** Examples
#+begin_example
echo 'notify alarm "Standup" "Daily standup in 5 minutes"' | at 10:55am
echo 'notify alarm "BP Reading" "Time to take BP"' | at 2:00pm
echo 'notify alert "Meeting" "Ryan call starting"' | at 11:25am
#+end_example

*** Notify types available
- =alarm= - Alarm clock icon, alarm sound
- =alert= - Yellow exclamation, attention tone
- =info= - Blue info icon, confident tone
- =success= - Green checkmark, pleasant chime
- =fail= - Red X, warning tone

Full usage: =notify --help= or see =~/.local/bin/notify=

*** Managing alarms
- =atq= - list all scheduled alarms
- =atrm [number]= - remove an alarm by its queue number

* Session Protocols

** CRITICAL: Git Commit Requirements

***IMPORTANT: ALL commits must be made as Craig, NOT as Claude.***

***CRITICAL: NO Claude Code or Anthropic attribution ANYWHERE in commits.***

When creating commits:

1. **Author Identity**: NEVER commit as Claude. All commits must use Craig's identity.
   - Git will use the configured user.name and user.email
   - Do NOT modify git config
   - **ABSOLUTELY NO** Co-Authored-By lines
   - **ABSOLUTELY NO** "Generated with Claude Code" text
   - **ABSOLUTELY NO** Anthropic attribution of any kind
   - Write commits AS CRAIG, not as Claude Code

2. **Commit Message Format**:
   - Use project-specific commit format if defined
   - Otherwise: concise subject line and terse description only
   - **ONLY subject line and terse description - NO Claude Code attribution**
   - Keep messages clear and informative

3. **Validation**:
   - Claude should validate commit message format before committing
   - Ensure no AI attribution appears anywhere in commit

** IMPORTANT: Reminders Protocol

When starting a new session:
- Check "Active Reminders" section in notes.org
- Remind Craig of outstanding tasks he's asked to be reminded about
- This ensures important follow-up actions aren't forgotten between sessions

When Craig says "remind me" about something:
1. Add it to Active Reminders section in notes.org
2. If it's something he needs to DO, also add to the todo.org file in the project root as an org-mode task (e.g., =* TODO [description]=). If this project does not have a todo.org at the project root, alert Craig and offer to create it.
3. If not already provided, ask for the priority and a date for scheduled or deadline.

** Workflows: "Let's run/do the [workflow name] workflow"

When Craig says this phrase:

1. **Check =docs/workflows/= for match**
   - If exact match found: Read and guide through process
   - Example: "refactor workflow" -> read docs/workflows/refactor.org

2. **Check =docs/project-workflows/= for match**
   - If exact match found: Read and guide through process

3. **Fuzzy match across both directories:** Ask for clarification
   - Example: User says "empty inbox" but we have "inbox-zero.org"
   - Ask: "Did you mean the 'inbox zero' workflow, or create new 'empty inbox'?"

4. **No match at all:** Offer to create it
   - Say: "I don't see '[workflow-name]' yet. Create it using create-workflow process?"
   - If yes: Run create-workflow — new workflows go to =docs/project-workflows/= by default

** Long-Running Process Status Updates

When monitoring a long-running process (rsync, large downloads, builds, VM tests, etc.), follow this protocol:

***At Start:***
1. Run =date= to get accurate time
2. Announce the task/job beginning
3. Provide best-guess ETA for completion

#+begin_example
**14:30** - Starting ISO build. ETA: ~10 minutes.
#+end_example

***Every 5 Minutes:***
- Check progress and display status in format: =HH:MM= - terse description - ETA

#+begin_example
**14:35** - ISO build: packages installed, creating squashfs. ETA: ~5 min.
**14:40** - ISO build: squashfs 95% complete. ETA: ~1 min.
#+end_example

***At Completion:***
1. Send notification via notify script:
   #+begin_src bash
   notify success "Task Complete" "Description of what finished"
   #+end_src
   Use =fail= type instead of =success= if the task failed.
2. Provide summary of success or failure

#+begin_example
**14:42** - ISO build complete. Size: 2.0G. Ready for testing.
#+end_example

***Guidelines:***
- Always run =date= for accurate timestamps
- Keep progress descriptions terse but informative
- Update ETA as job progresses
- If ETA cannot be determined, say "ETA unknown" rather than guessing wildly

***Why This Matters:***
- Craig may be working on other things while waiting
- Status updates provide confidence the process is still running
- ETAs help with planning (e.g., "I have time for coffee" vs "stay close")
- Sound notification alerts Craig when he's away from the screen
- If something stalls, the updates make it obvious

** "Wrap it up" / "That's a wrap" / "Let's call it a wrap"

When Craig says any of these phrases (or variations), execute wrap-up workflow:

1. **Write session notes** to notes.org (Session History section)
   - Key decisions made
   - Work completed
   - Context needed for next session
   - Any pending issues or blockers
   - New conventions or preferences learned
   - Critical reminders for tomorrow go in Active Reminders section

2. **Git commit and push** (if project is in git repository)
   - Check git status and diff
   - Create commit message following requirements (see "Git Commit Requirements" above)
   - **ONLY subject line and terse description - NO Claude Code attribution**
   - Commit as Craig (NOT as Claude)
   - **ABSOLUTELY NO** Co-Authored-By, Claude Code, or Anthropic attribution
   - Push to ALL remotes (check with =git remote -v=)
   - Ensure working tree is clean
   - Confirm push succeeded to all remotes

3. **Valediction** - Brief, warm goodbye
   - Acknowledge the day's work
   - What was accomplished
   - What's ready for next session
   - Any important reminders
   - Keep it warm but concise

This ensures clean handoff between sessions and nothing gets lost.

** The docs/ Directory

Claude needs to add information to notes.org. For large amounts of information:

- Create separate document in docs/ directory
- Link it in notes.org with explanation of document's purpose
- **Project-specific decision:** Should docs/ be committed to git or added to .gitignore?
  - Ask Craig on first session if not specified
  - Some projects keep docs/ private, others commit it
- Unless specified otherwise, all Claude-generated documents go in docs/ folder

**When to break out documents:**
- If notes.org gets very large (> 1500 lines)
- If information isn't all relevant anymore
- Example: Keep only last 3-4 months of session history here, move rest to separate file

* File Format Preferences

** ALWAYS Use Org-Mode Format

Craig uses Emacs as primary tool. **ALWAYS** create new documentation files in =.org= format, not =.md= (markdown).

*Rationale:*
- Org-mode files are well-supported in Emacs
- Can be easily exported to any other format (HTML, PDF, Markdown, etc.)
- Better integration with user's workflow

*Exception:* Only use .md if specifically requested or if file is intended for GitHub/web display where markdown is expected.

** NEVER Use Spaces in Filenames

**ALWAYS** use hyphens (=-=) to separate words in filenames. Underscores (=_=) are also acceptable.

*Rationale:*
- Spaces cause problems with links across different operating systems
- User works with Mac, Windows, Linux, and potentially other systems
- Hyphens create more reliable, portable filenames
- Easier to work with in command-line tools

*Examples:*
- Good: =project-meeting-notes.org=
- Good: =change-log-2025-11-04.md=
- Bad: =project meeting notes.org=
- Bad: =change log 2025.11.04.md=

* File Naming Conventions

** Files Too Large to Read

PDFs or other files that are too large for Claude to read should be prefixed with =TOOLARGE-= to prevent read errors that halt the session.

Example:
- Original: =assets/large-architectural-plans.pdf=
- Renamed: =assets/TOOLARGE-large-architectural-plans.pdf=

** Unreadable Binary Files (.docx Format)

Binary .docx files cannot be read directly by Claude. When encountering these:
- Convert to markdown format using pandoc: =pandoc file.docx -o file.md=
- Keep the original .docx file for reference
- Work with the converted .md file for analysis and editing

** CRITICAL: Always Keep Links Current

Many documents are linked in org files using org-mode =file:= links. Craig relies on these links being valid at all times.

**MANDATORY WORKFLOW - When renaming or moving ANY file:**

1. **BEFORE renaming:** Search ALL org files for references to that file
   - Use grep or search tools to find both filename and partial matches
   - Check in TODO items and event log sections

2. **Rename or move the file**

3. **IMMEDIATELY AFTER:** Update ALL =file:= links to new path/filename
   - Update links in task files
   - Update links in event logs
   - Update links in reference sections

4. **Verify:** Test a few updated links to ensure they point to valid files

Example workflow:
#+begin_example
# Step 1: Search before renaming
grep -rn "2025-10-15-invoice.pdf" *.org

# Step 2: Rename the file
mv documents/2025-10-15-invoice.pdf documents/2025-10-15-vendor-invoice.pdf

# Step 3: Update all references in affected .org files
# Edit to change:
#   file:documents/2025-10-15-invoice.pdf
# to:
#   file:documents/2025-10-15-vendor-invoice.pdf

# Step 4: Verify links work
#+end_example

*Why This is Critical:*
- Org files are primary task tracking and reference system
- Event logs document complete history with file references
- Craig depends on clicking links to access documents quickly
- Broken links disrupt workflow and make documentation unreliable

**NEVER rename or move files without updating links in the same session.**

* Session Start - AUTOMATIC

At the start of EVERY session, run [[file:workflows/startup.org][docs/workflows/startup.org]]. Do NOT ask — just do it automatically.