Add docs directory

Project documentation and workflow definitions.

1 files changed, 540 insertions, 0 deletions

diff --git a/docs/workflows/session-start.org b/docs/workflows/session-start.org
new file mode 100644
index 0000000..66973ab
--- /dev/null
+++ b/docs/workflows/session-start.org
@@ -0,0 +1,540 @@
+#+TITLE: Session Start Workflow
+#+AUTHOR: Craig Jennings & Claude
+#+DATE: 2025-11-14
+
+* Overview
+
+This workflow defines the process for beginning a Claude Code session. It ensures Claude has the necessary context, is aware of current priorities, and can work effectively with Craig from the start.
+
+This workflow runs **automatically at the beginning of EVERY session** without needing to be triggered by Craig.
+
+* Problem We're Solving
+
+Without a structured session start process, sessions can begin poorly:
+
+** Missing Context
+- Claude doesn't know what happened in previous sessions
+- Important reminders or decisions are overlooked
+- No awareness of project-specific conventions or preferences
+- Time wasted re-explaining project context
+
+** Outdated Information
+- Missing protocol updates from template improvements
+- Unaware of new workflows available in the project
+- Using old conventions that have been superseded
+- Templates and project drift out of sync
+
+** Missed Priorities
+- New documents in inbox go unnoticed
+- Critical reminders aren't surfaced
+- Pending decisions remain unaddressed
+- User has urgent work but Claude suggests non-urgent tasks
+
+** Inefficient Start
+- Reading entire NOTES.org file (wasting tokens on static content)
+- No clear next steps or priorities
+- User must orient Claude manually
+- Lack of structure for beginning work
+
+*Impact:* Slow session starts, missed context, wasted time, and frustration from having to repeat information.
+
+* Exit Criteria
+
+The session start is complete when:
+
+1. **Claude has current context:**
+   - Knows project-specific information and goals
+   - Aware of how user prefers to work
+   - Understanding of recent session history (last 2-3 sessions)
+   - Current reminders and pending decisions surfaced
+
+2. **Templates are synced:**
+   - Checked for updates from claude-templates
+   - Any new workflows or improvements identified
+   - Project templates directory is current
+
+3. **Inbox is processed:**
+   - New documents identified and reviewed
+   - Recommendations provided for each
+   - Documents filed appropriately
+
+4. **Next steps are clear:**
+   - User has stated urgent work, OR
+   - Claude has suggested following what's-next workflow
+   - Session has clear direction
+
+*Measurable validation:*
+- Active Reminders have been surfaced to user
+- Pending Decisions have been mentioned
+- Inbox is empty or user has deferred processing
+- User has confirmed what to work on OR agreed to what's-next workflow
+
+* When to Use This Workflow
+
+**IMPORTANT: This workflow runs AUTOMATICALLY at the start of EVERY session.**
+
+Do NOT ask the user if they want to run it - just execute it immediately when a new session begins.
+
+The only exception is if the user immediately provides urgent instructions that require immediate action (e.g., "the server is down, help me debug it right now").
+
+* First Time Setup
+
+If this is the first time using this workflow in a project, perform this one-time cleanup:
+
+** Clean Up Old "Session Start" Documentation
+
+Before using this workflow, check if NOTES.org contains old/redundant session start instructions:
+
+1. **Search NOTES.org for duplicate content:**
+   #+begin_src bash
+   grep -n "Session Start\|session start" docs/NOTES.org
+   #+end_src
+
+2. **Look for sections that duplicate this workflow:**
+   - Detailed "Session Start Routine" instructions
+   - Step-by-step template sync instructions
+   - Inline instructions for reading NOTES.org sections
+   - Inbox processing instructions
+
+3. **Replace with link to this workflow:**
+   - Remove the detailed inline instructions
+   - Replace with: "See [[file:docs/workflows/session-start.org][Session Start Workflow]]"
+   - Keep brief summary if helpful for quick reference
+
+4. **Why this matters:**
+   - Prevents conflicting instructions (e.g., different diff commands)
+   - Single source of truth for session start process
+   - Easier to maintain and update in one place
+   - Reduces NOTES.org file size
+
+**Example cleanup:**
+
+Before:
+#+begin_example
+* Session Start Routine
+
+When starting a new session with Craig, follow these steps:
+
+1. Add Timestamp for Session History
+   [detailed instructions...]
+2. Sync with Templates
+   [detailed instructions...]
+3. Scan workflows directory
+   [detailed instructions...]
+[30+ lines of detailed instructions]
+#+end_example
+
+After:
+#+begin_example
+* Session Start Routine
+
+**IMPORTANT: ALWAYS run this routine automatically at the start of EVERY session.**
+
+Execute the session start workflow defined in [[file:docs/workflows/session-start.org][session-start.org]].
+
+Brief summary: Add timestamp, sync templates, scan workflows, read key NOTES.org sections, process inbox, ask about priorities.
+#+end_example
+
+This cleanup should only be done ONCE when first adopting this workflow.
+
+* The Workflow
+
+** Step 1: Add Session Start Timestamp
+
+Record when the session begins for tracking purposes.
+
+*** Why This Matters
+
+- Helps identify if previous session was interrupted (no end timestamp)
+- Provides session duration tracking
+- Creates clear session boundaries in history
+
+*** How to Add Timestamp
+
+1. **Navigate to Session History section** in =docs/NOTES.org=
+
+2. **Check the last session entry:**
+   - If it has a start timestamp but NO end timestamp → previous session was interrupted
+   - If it has both start and end timestamps → previous session completed normally
+
+3. **Prepare for new session entry** (will be written during wrap-up):
+   - Note the current time for internal reference
+   - Session entry will be created at wrap-up, not now
+   - This step is just to CHECK for interrupted sessions
+
+4. **If previous session was interrupted:**
+   - Mention to user: "I notice the last session (DATE) didn't complete normally. Should I review what was being worked on?"
+   - This helps recover context if something went wrong
+
+*** Format
+
+Session timestamps follow this format (added during wrap-up, not session start):
+- Start: Recorded at beginning of session
+- End: Recorded during wrap-up workflow
+
+Example:
+#+begin_example
+** Session: November 14, 2025 (Morning)
+Started: 09:30 AM
+Ended: 11:45 AM
+#+end_example
+
+** Step 2: Sync with Templates
+
+Keep the project aligned with latest best practices from claude-templates.
+
+*** CRITICAL: Template is Authoritative
+
+**The template is the single source of truth.** Do not review diffs or decide whether to apply changes - just copy from template to project. There should NEVER be differences between template files and project files, not even cosmetic differences like trailing whitespace.
+
+If a project needs project-specific protocol additions, put them in NOTES.org under a "Project-Specific Protocols" section - NEVER modify protocols.org in the project.
+
+*** Why This Matters
+
+- Ensures consistent behavior across all projects
+- Eliminates drift between template and projects
+- Protocol improvements automatically propagate to all projects
+- Single source of truth prevents confusion
+
+*** How to Copy
+
+Copy template files directly to the project's docs/ directory:
+
+#+begin_src bash
+cp ~/projects/claude-templates/docs/protocols.org docs/protocols.org
+cp -r ~/projects/claude-templates/docs/workflows docs/
+cp -r ~/projects/claude-templates/docs/scripts docs/
+#+end_src
+
+**Mention any significant updates** if you notice them:
+- If protocols.org has new sections, mention briefly
+- If new workflows were added, mention them
+- Example: "protocols.org now includes alarm instructions"
+
+That's it. No diff review, no decisions - template always wins.
+
+*** Workflow Directory Structure
+
+There are TWO workflow directories:
+
+**=docs/workflows/=** - Template workflows (standard across all projects)
+- Copied from template on every session start
+- NEVER edit these in a project - edit in template instead
+- Safe to overwrite completely during copy
+- Examples: session-start.org, session-wrap-up.org, create-workflow.org
+
+**=docs/project-workflows/=** - Project-specific workflows (unique to this project)
+- NEVER copied or touched by template sync
+- Created and maintained within the project only
+- Examples: morning-checkin.org (health), danneel-inbox-zero.org (danneel)
+
+*** What Gets Copied (Template → Project)
+
+- **protocols.org** - Always overwrite from template
+- **workflows/** - Template workflows (overwritten completely)
+- **scripts/** - Template scripts (overwritten completely)
+
+*** What Is NEVER Copied (Project-Specific)
+
+- **NOTES.org** - Project-specific content (context, history, reminders)
+- **previous-session-history.org** - Project-specific history
+- **session-context.org** - Project-specific live session data
+- **someday-maybe.org** - Project-specific ideas
+- **project-workflows/** - Project-specific workflows (separate directory, never touched)
+
+** Step 3: Scan Workflows Directory
+
+Understand what workflows are available in this project.
+
+*** Why This Matters
+
+- Enables Claude to suggest appropriate workflows
+- Builds vocabulary for understanding user requests
+- Shows what standardized processes exist
+- Helps answer "how do we do X?" questions
+
+*** How to Scan
+
+1. **List workflow files:**
+   #+begin_src bash
+   ls -1 docs/workflows/
+   #+end_src
+
+2. **Note the workflow names** (just filenames, don't read contents):
+   - create-workflow.org
+   - create-v2mom.org
+   - session-start.org
+   - session-wrap-up.org
+   - [project-specific workflows]
+
+3. **Remember these exist** for suggesting to user later
+
+4. **Do NOT read full workflow contents** - they're long and will be read when actually executing a workflow
+
+*** When User Says "Let's Run the X Workflow"
+
+1. Check if workflow exists in docs/workflows/
+2. If yes: Read that specific workflow file and execute it
+3. If no: Offer to create it using create-workflow process
+
+** Step 4: Read protocols.org and NOTES.org
+
+Get behavioral instructions and project context.
+
+*** Why Two Files?
+
+Documentation is now split into two files:
+- **protocols.org** - How Claude should behave (consistent across all projects)
+- **NOTES.org** - Project-specific content (unique to each project)
+
+This separation allows protocol updates to sync automatically without affecting project data.
+
+*** Read protocols.org First
+
+Read the entire =docs/protocols.org= file. It contains:
+- Session management protocols (context files, compacting)
+- Important terminology and trigger phrases
+- User information and preferences
+- Git commit requirements
+- File format and naming conventions
+- Session start instructions
+
+This file is relatively short and should be read in full.
+
+*** Then Read NOTES.org
+
+NOTES.org now contains only project-specific content:
+
+1. **Project-Specific Context** section
+   - **THIS IS THE KEY SECTION** - contains what the project is about
+   - People involved and their roles
+   - Current state of the project
+   - Goals and objectives
+   - Important background information
+   - Technical architecture or key decisions
+
+2. **Active Reminders** section
+   - Critical items to surface to user
+   - Time-sensitive follow-ups
+   - Important tasks user asked to be reminded about
+
+3. **Pending Decisions** section
+   - Decisions awaiting user input
+   - Blockers that need resolution
+   - Questions that need answering
+
+4. **Session History - Last 2-3 entries only**
+   - Recent work completed
+   - Recent decisions made
+   - Context from previous sessions
+   - What was being worked on
+   - **Do NOT read entire session history** - older entries are archived
+
+*** What to SKIP in NOTES.org
+
+- About This File (brief, just links to protocols.org)
+- Available Workflows catalog (just scanned in Step 3)
+- Session History format instructions (reference material)
+- Full Session History (only read last 2-3 entries)
+- Archived sessions in previous-session-history.org (unless specifically needed)
+
+*** How to Read Efficiently
+
+#+begin_example
+1. Read docs/protocols.org (entire file - it's the behavioral guide)
+2. Read docs/NOTES.org Project-Specific Context section
+3. Read docs/NOTES.org Active Reminders section
+4. Read docs/NOTES.org Pending Decisions section
+5. Read last 2-3 Session History entries (count backwards from end)
+#+end_example
+
+** Step 5: Process Inbox
+
+Check for new documents and help user file them appropriately.
+
+*** Why This Matters
+
+- New documents need to be reviewed and filed
+- Unprocessed inbox items can contain important information
+- Helps maintain organized project structure
+- Ensures nothing gets missed
+
+*** Inbox Location
+
+Default inbox location: =./inbox/= (at project root)
+
+Some projects may have different locations - check NOTES.org or ask user on first session.
+
+*** How to Process
+
+1. **Check inbox directory:**
+   #+begin_src bash
+   ls -lh inbox/
+   #+end_src
+
+2. **If inbox is empty:**
+   - No action needed
+   - Continue to Step 6
+
+3. **If inbox contains files:**
+   - **Do NOT ask if user wants to process** - process is MANDATORY
+   - Say: "I see X items in your inbox. Let me review them."
+
+4. **For each file in inbox:**
+   - Read the file to understand content
+   - Determine:
+     - Who it's from (if applicable)
+     - What it's about
+     - What action should be taken
+   - Consider project history and context
+   - Recommend appropriate action:
+     - File to =assets/emails/= if it's an email
+     - File to =assets/= if it's a document/attachment
+     - File to =docs/= if it's project documentation
+     - Add TODO items if action is needed
+   - Recommend appropriate filename:
+     - Format: =YYYY-MM-DD-Source-Description.ext=
+     - Example: =2025-11-14-Mark-Response-To-Settlement.txt=
+   - Get user approval before filing
+
+5. **File the document:**
+   - Move (not copy) from inbox to destination
+   - Use approved filename
+   - Update any relevant TODO items or event logs
+
+6. **Repeat for all inbox items** until inbox is empty
+
+*** Inbox Processing Workflow
+
+Some projects may have a specific inbox-zero workflow (e.g., =docs/workflows/danneel-inbox-zero.org=).
+
+If it exists:
+- Use that workflow instead of the generic process above
+- It may have project-specific filing conventions
+
+** Step 6: Ask About Priorities
+
+Determine what to work on this session.
+
+*** Why This Matters
+
+- User may have urgent work that takes priority
+- Prevents suggesting V2MOM tasks when there's a crisis
+- Gives user control over session direction
+- Enables following structured workflow if no urgent work
+
+*** How to Ask
+
+**Say to user:**
+
+"Is there something urgent you'd like to work on, or should we follow the what's-next workflow to identify priorities?"
+
+Wait for user response.
+
+*** If User Has Urgent Work
+
+- Proceed with the urgent work immediately
+- Skip what's-next workflow
+- Focus session on user's stated priority
+
+*** If User Says Follow What's-Next
+
+- Check if =docs/workflows/whats-next.org= exists
+- If yes: Execute that workflow
+- If no: Check if V2MOM exists and suggest working on top priority method
+- If no V2MOM: Offer to create one using create-v2mom workflow
+
+*** If User is Unsure
+
+Provide helpful context:
+- Remind them of Active Reminders (from Step 4)
+- Mention any Pending Decisions (from Step 4)
+- Reference recent session history (what was being worked on)
+- Suggest continuing previous work if it's unfinished
+
+** Session Start Complete
+
+Once all steps are done:
+- Claude has full context
+- User knows what's being worked on
+- Session can proceed productively
+
+Don't announce "session start complete" - just begin working on the chosen task.
+
+* Tips for Effective Session Starts
+
+** Template Sync
+
+1. **Don't panic about changes** - Most are improvements
+2. **Review carefully** - Understand what changed before applying
+3. **Project-specific workflows** - Don't overwrite if customized
+4. **Mention significant updates** - User should know about workflow improvements
+5. **First sync is clean** - No diff needed, just copy
+
+** Reading NOTES.org
+
+1. **Use line numbers** - More efficient than searching
+2. **Read in order** - Builds context progressively
+3. **Focus on Project-Specific Context** - This is the most important section
+4. **Surface reminders immediately** - Don't wait until later
+5. **Note interrupted sessions** - Helps recover from crashes
+
+** Inbox Processing
+
+1. **Be thorough** - Read files completely to understand context
+2. **Consider history** - Recommendations should fit project patterns
+3. **Suggest good filenames** - Use established conventions
+4. **Don't delete without asking** - User may want to review first
+5. **Update related systems** - Add TODOs, update event logs as needed
+
+** Priorities Discussion
+
+1. **Ask clearly** - Don't be vague about what's being offered
+2. **Respect urgency** - If user has crisis, drop everything else
+3. **Provide context** - Remind user of reminders and decisions
+4. **Don't assume** - Even if previous session had direction, ask
+5. **Be helpful** - If user is unsure, provide gentle guidance
+
+* Common Mistakes to Avoid
+
+1. **Reading entire NOTES.org file** - Wastes tokens on static content
+2. **Skipping template sync** - Miss important updates
+3. **Not checking for interrupted sessions** - Lose context from crashes
+4. **Forgetting to surface Active Reminders** - User misses critical items
+5. **Asking if user wants inbox processed** - It's mandatory, not optional
+6. **Processing inbox after asking about priorities** - Should be before
+7. **Not excluding NOTES.org from template diff** - Creates noise
+8. **Not excluding previous-session-history.org from diff** - Project-specific content
+9. **Announcing "session start complete"** - Just begin working
+10. **Reading full workflow files during scan** - Just note filenames
+
+* Validation Checklist
+
+Before considering session start complete, verify:
+
+- [ ] Checked for interrupted previous session (missing end timestamp)
+- [ ] Template sync executed (diff or first-time copy)
+- [ ] Template changes reviewed and applied if needed
+- [ ] Workflows directory scanned (filenames noted)
+- [ ] IMPORTANT TERMINOLOGY section read
+- [ ] User Information section read
+- [ ] Project-Specific Context section read (CRITICAL)
+- [ ] Active Reminders section read and surfaced to user
+- [ ] Pending Decisions section read and mentioned to user
+- [ ] Last 2-3 Session History entries read
+- [ ] Inbox checked for new files
+- [ ] Inbox processed (if contained files) or confirmed empty
+- [ ] Asked user about urgent work vs what's-next workflow
+- [ ] User has confirmed what to work on OR agreed to follow workflow
+- [ ] Ready to begin productive work
+
+* Meta Notes
+
+This workflow should evolve based on experience:
+
+- If session starts consistently miss something important, update the checklist
+- If reading NOTES.org sections takes too long, further optimize what's read
+- If template sync creates too much noise, refine what's excluded
+- Craig can modify this workflow at any time to better fit needs
+
+The goal is efficient session starts with full context, not rigid adherence to format.