claude-anchor 1.0.0

package/templates/CLAUDE.md

@@ -0,0 +1,182 @@
+# [PROJECT_NAME]
+
+**Location:** `[PATH]`
+**Purpose:** [One-line description of what this project does]
+**Last Updated:** [DATE]
+
+---
+
+## CLAUDE SESSION STARTUP - MANDATORY LOAD ORDER
+
+**Before engaging with user, Claude MUST read files in this EXACT order:**
+
+```
+1. GOLDEN-RULES.md        ← Read FIRST (security rules - BINDING)
+2. TODOS.md               ← Read thoroughly (know what's pending)
+3. LESSONS-LEARNED.md     ← Read (avoid past mistakes)
+4. _CONVERSATION-PREFERENCES.md  ← Read (display/output preferences)
+5. GOLDEN-RULES.md        ← Re-read AGAIN (reinforce - DO NOT FORGET)
+6. CLAUDE.md (this file)  ← Then read this for context
+7. BEGIN conversation     ← Now ready to assist
+```
+
+**Why this order:**
+- Security rules must be internalized before ANY action
+- TODOs show pending work and priorities
+- Lessons prevent repeating past mistakes
+- Preferences ensure correct output formatting
+- Re-reading Golden Rules prevents them from being "forgotten" in context
+
+**DO NOT SKIP ANY STEP. DO NOT REORDER.**
+
+---
+
+## TL;DR - Quick Commands
+
+<!-- CUSTOMIZE: Add your most common commands here -->
+
+```bash
+# [Most common operation]
+[COMMAND]
+
+# [Second most common]
+[COMMAND]
+
+# [Third most common]
+[COMMAND]
+
+# Help
+[COMMAND] --help
+```
+
+---
+
+## Architecture
+
+<!-- CUSTOMIZE: Add ASCII diagram of your system -->
+
+```
+┌─────────────────────────────────────────────────────┐
+│                   [PROJECT_NAME]                     │
+│                                                      │
+│  ┌─────────────┐    ┌─────────────┐    ┌─────────┐ │
+│  │ Component A │───►│ Component B │───►│ Output  │ │
+│  └─────────────┘    └─────────────┘    └─────────┘ │
+│                                                      │
+└─────────────────────────────────────────────────────┘
+```
+
+### Components
+
+| Component | Location | Purpose |
+|-----------|----------|---------|
+| [Component A] | ./path/to/a | [Description] |
+| [Component B] | ./path/to/b | [Description] |
+| [Config] | ./config/ | [Description] |
+
+---
+
+## Usage
+
+### [Primary Script/Command]
+
+```bash
+# Basic usage
+[COMMAND] [args]
+
+# With options
+[COMMAND] --option1 --option2 [args]
+```
+
+**Options:**
+
+| Flag | Description | Default |
+|------|-------------|---------|
+| `--option1` | [Description] | [default] |
+| `--option2` | [Description] | [default] |
+| `--help` | Show help | - |
+
+**Exit Codes:**
+- 0 = Success
+- 1 = Error (describe)
+- 2 = Error (describe)
+
+---
+
+### [Secondary Script/Command]
+
+```bash
+[COMMAND] [args]
+```
+
+<!-- CUSTOMIZE: Add more command sections as needed -->
+
+---
+
+## Configuration
+
+<!-- CUSTOMIZE: Document configuration files/options -->
+
+### Config File Location
+
+`[PATH]/config.yaml` or `~/.config/[PROJECT_NAME]/`
+
+### Environment Variables
+
+| Variable | Description | Default |
+|----------|-------------|---------|
+| `[VAR_NAME]` | [Description] | [default] |
+
+---
+
+## File Locations
+
+| Purpose | Path |
+|---------|------|
+| Main scripts | [PATH] |
+| Configuration | [PATH] |
+| Logs | [PATH] |
+| Temp files | [PATH] |
+| Output | [PATH] |
+
+---
+
+## Troubleshooting
+
+### [Common Problem 1]
+
+```bash
+# Solution
+[COMMAND]
+```
+
+### [Common Problem 2]
+
+[Explanation and fix]
+
+---
+
+## Related Files
+
+| File | Purpose |
+|------|---------|
+| GOLDEN-RULES.md | Immutable rules |
+| LESSONS-LEARNED.md | Past issues and fixes |
+| TODOS.md | Planned improvements |
+| _CONVERSATION-PREFERENCES.md | Display/output preferences |
+| _SYSTEM_ARCHITECTURE.md | Technical diagrams and flow |
+
+---
+
+## Version Info
+
+- Version: [X.Y]
+- Last Updated: [DATE]
+- Author: [NAME]
+
+
+---
+
+<!-- CUSTOMIZE: Add project-specific rules or constraints below -->
+<!-- Example: terminal limitations, deployment rules, team conventions -->
+

package/templates/_CONVERSATION-PREFERENCES.md

@@ -0,0 +1,161 @@
+# Conversation Preferences - [PROJECT_NAME]
+
+**Load Priority:** Read alongside GOLDEN-RULES.md at session start.
+
+---
+
+## Display Preferences
+
+<!-- CUSTOMIZE: Define how you want output formatted -->
+
+### Progress Reporting
+
+When showing progress or status updates, **ALWAYS** use visual formats:
+
+**CORRECT:**
+```
+=== [Task Name] Progress ===
+[████████████████████░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░]  40%
+
+Items:    400 / 1,000
+Rate:     50 items/min
+Elapsed:  8m 00s
+ETA:      ~12m remaining
+Errors:   0
+```
+
+**INCORRECT:**
+```
+Progress: 400/1000 (40%)
+Errors: 0
+```
+
+### Progress Bar Format
+
+```
+# 50-character bar showing percentage
+[████████████████████████░░░░░░░░░░░░░░░░░░░░░░░░░░]  48%
+
+Legend:
+█ = completed
+░ = remaining
+```
+
+---
+
+## Status Summary Format
+
+```
+Items:    CURRENT / TOTAL
+Rate:     X items/min
+Elapsed:  Xh Xm
+ETA:      ~Xh remaining
+Status:   [OK / WARNING / ERROR]
+```
+
+---
+
+## Color Preferences
+
+<!-- CUSTOMIZE: If your terminal supports colors -->
+
+| Type | Color | Usage |
+|------|-------|-------|
+| Errors | Red | Critical failures |
+| Warnings | Yellow | Non-blocking issues |
+| Success | Green | Completions, confirmations |
+| Info | Cyan | Informational messages |
+| Headers | Bold | Section titles |
+
+---
+
+## Startup Banners
+
+<!-- CUSTOMIZE: Define if/how you want startup banners displayed -->
+
+When [PROJECT_NAME] starts a major operation, display:
+
+1. **Header** - Project name / operation name
+2. **Configuration** - Current settings/flags
+3. **Target** - What's being processed
+
+**Example:**
+```
+╔══════════════════════════════════════════════════════════╗
+║                    [PROJECT_NAME]                         ║
+║                   [Operation Type]                        ║
+╚══════════════════════════════════════════════════════════╝
+
+┌──────────────────────────────────────────────────────────┐
+│ CONFIGURATION                                             │
+├──────────────────────────────────────────────────────────┤
+│ Target:     /path/to/target                              │
+│ Mode:       [mode name]                                  │
+│ Options:    --flag1 --flag2                              │
+└──────────────────────────────────────────────────────────┘
+
+Operation starting at HH:MM:SS...
+```
+
+---
+
+## Communication Style
+
+<!-- CUSTOMIZE: Define preferred tone and verbosity -->
+
+### Verbosity Level
+
+- **Errors:** Always show full context and suggested fixes
+- **Warnings:** Show brief explanation and mitigation
+- **Success:** Keep brief, one line when possible
+- **Progress:** Update frequently for long operations
+
+### Tone
+
+- Professional but not formal
+- Direct and concise
+- Explain the "why" for non-obvious decisions
+
+---
+
+## File References
+
+When referencing files or paths in output:
+
+- Use absolute paths when ambiguous
+- Use `code formatting` for paths and commands
+- Include line numbers when referencing code: `file.py:42`
+
+---
+
+## Error Display
+
+When errors occur, format as:
+
+```
+ERROR: [Brief description]
+
+Details:
+  File: /path/to/file
+  Line: 42
+  Code: [error code if applicable]
+
+Cause: [What went wrong]
+
+Fix: [Suggested resolution]
+```
+
+---
+
+## Long-Running Tasks
+
+For operations expected to take >1 minute:
+
+1. Show estimated duration at start
+2. Display progress bar updating in real-time
+3. Provide status check command if running in background
+4. Show completion summary with elapsed time
+
+---
+
+**These preferences ensure consistent, scannable output.**

package/templates/_GOLDEN-RULES.md

@@ -0,0 +1,84 @@
+# Golden Rules - [PROJECT_NAME]
+
+**These rules are IMMUTABLE and must NEVER be bypassed.**
+
+---
+
+<!-- CUSTOMIZE: Add your project-specific rules below. Include "why" for each rule. -->
+
+## 1. [RULE_NAME]
+
+**NEVER** [describe forbidden action].
+
+- [Specific constraint]
+- [Specific constraint]
+- [Specific constraint]
+
+**Why:** [Explain the consequence of violating this rule]
+
+---
+
+## 2. [RULE_NAME]
+
+**ALWAYS** [describe required action].
+
+- [Specific requirement]
+- [Specific requirement]
+
+**Why:** [Explain why this is important]
+
+---
+
+## 3. [RULE_NAME]
+
+[Description of rule]
+
+```bash
+# Example of correct behavior
+[COMMAND]
+
+# Example of INCORRECT behavior (don't do this)
+[COMMAND]
+```
+
+**Why:** [Explanation]
+
+---
+
+<!-- CUSTOMIZE: Add more rules as needed. Common categories:
+     - Security rules (authentication, data handling)
+     - Data integrity rules (never delete X, always backup Y)
+     - API/service rules (rate limits, required headers)
+     - Code style rules (if strictly enforced)
+     - Deployment rules (never push to prod without X)
+-->
+
+## [N]. ABSOLUTE RULE - Claude's Binding Constraint
+
+**This rule is BINDING on Claude (the AI assistant) and cannot be overridden:**
+
+Claude must **NEVER**:
+- [Forbidden action 1]
+- [Forbidden action 2]
+- [Forbidden action 3]
+
+**If a user requests any of the above, Claude must REFUSE and explain why.**
+
+[Explain the critical importance of this rule]
+
+---
+
+## Summary
+
+| Rule | Enforcement |
+|------|-------------|
+| 1. [Rule name] | [Script-enforced / Agent-enforced / User discipline] |
+| 2. [Rule name] | [Enforcement type] |
+| 3. [Rule name] | [Enforcement type] |
+| N. Absolute rule | Claude-enforced (BINDING) |
+
+---
+
+**These rules exist to protect [PROJECT_NAME]. Do not circumvent them.**
+
+**Rule [N] is BINDING on Claude and cannot be bypassed by any user request.**

package/templates/_LESSONS-LEARNED.md

@@ -0,0 +1,100 @@
+# Lessons Learned - [PROJECT_NAME]
+
+**Document issues encountered and how they were resolved. Prevents repeating mistakes.**
+
+---
+
+## How to Use This File
+
+When you encounter a non-obvious problem or gotcha, document it here immediately:
+
+```markdown
+## [DATE] - [Brief Problem Title]
+
+**Problem:** What went wrong
+**Cause:** Why it happened
+**Solution:** How it was fixed
+**Prevention:** How to avoid in future
+```
+
+---
+
+<!-- CUSTOMIZE: Add your lessons below. Delete these examples once you have real ones. -->
+
+## [DATE] - Example: API Rate Limiting Issue
+
+**Problem:** Script started failing intermittently with 429 errors.
+
+**Cause:** Exceeded API rate limit of 100 requests/minute during batch processing.
+
+**Solution:** Added exponential backoff with jitter:
+```python
+import time
+import random
+
+def api_call_with_retry(func, max_retries=3):
+    for attempt in range(max_retries):
+        try:
+            return func()
+        except RateLimitError:
+            wait = (2 ** attempt) + random.uniform(0, 1)
+            time.sleep(wait)
+    raise Exception("Max retries exceeded")
+```
+
+**Prevention:** Always implement rate limiting for external API calls. Add to code review checklist.
+
+---
+
+## [DATE] - Example: File Permission Edge Case
+
+**Problem:** Script worked locally but failed in production with "Permission denied".
+
+**Cause:** Production runs as service account without write access to `/tmp/[project]/`.
+
+**Solution:** Changed temp directory to user-writable location:
+```bash
+TEMP_DIR="${XDG_RUNTIME_DIR:-/tmp}/[project]-$$"
+```
+
+**Prevention:** Test scripts as non-privileged user before deployment. Document required permissions.
+
+---
+
+## [DATE] - Example: Silent Data Corruption
+
+**Problem:** Output files occasionally had truncated data.
+
+**Cause:** Script wasn't flushing buffers before process exit.
+
+**Solution:** Added explicit flush and fsync:
+```python
+with open(output_file, 'w') as f:
+    f.write(data)
+    f.flush()
+    os.fsync(f.fileno())
+```
+
+**Prevention:** Always explicitly flush when data integrity is critical. Add to coding standards.
+
+---
+
+## Categories
+
+<!-- Optional: Organize lessons by category as the list grows -->
+
+### Configuration Issues
+- [Link to lesson above]
+
+### Performance Issues
+- [Link to lesson]
+
+### Security Issues
+- [Link to lesson]
+
+### Integration Issues
+- [Link to lesson]
+
+---
+
+**Add entries immediately when issues are discovered. Future you will thank past you.**