e7c8214499
- Add statusline.sh and set-topic.sh for per-session status line topics - Update context-load with improved directory walking and output format - Update CLAUDE.md with status line docs and early-call safety note - Update MEMORY.md and README.md with new script/skill entries - Add memory files: script-statusline, skill-decompose, skill-orchestrate, gotchas-gitea - Add networking.md best practice (nftables, systemd sockets, Docker forwarding, TLS) - Update best practices from prior distill: documentation, kubernetes, scripting, secrets-management, skills-development - Prune reflected session logs, add new session logs - Update reflection state Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
4.3 KiB
Architecture & Design Decisions
Knowledge Pipeline: Separate /reflect-logs from /reflect
/reflect-logs handles continuous log processing; /reflect handles milestone reflections. Different purpose, different cadence — combining them would overcomplicate the milestone skill.
Knowledge Pipeline: MD5 for reflection state, git SHAs for distill state
Log files may not be committed when reflected on, so MD5 of file content is the right identity. /distill-best-practices works across committed repos, so git SHAs are appropriate there.
Knowledge Pipeline: Pruning happens in /log, not /reflect-logs
/log runs most frequently (every session end), so it naturally keeps the log directory clean as a side effect.
Knowledge Pipeline: /distill-best-practices is interactive
Cross-project convention changes need human judgment. The skill proposes updates and waits for approval before writing.
Session Logs: Timestamp-based IDs (HHMMSS)
Human-readable, naturally sorted, no external dependencies. Format: YYYY-MM-DD.HHMMSS.md.
Linting: Formatter exit codes vs hook exit codes
Formatter scripts exit 1 on lint errors. The dispatcher hook decides the final exit code (exit 2 for PostToolUse feedback). This separates formatter logic from hook semantics — same scripts work for both PostToolUse and pre-commit.
Linting: Checkpoint via git hash-object with .pre-lint sidecar
Fast (~1ms), no commits or stash needed, orphan blobs auto-GC'd. Falls back to cp outside git repos.
Linting: Project opt-in via formatter symlinks
Projects opt in by having a formatters/ directory with symlinks back to canonical scripts. Zero-config, visible in ls, no parsing needed. The hook walks up the directory tree to find formatters/.
Skills: Use CLAUDE_PROJECT_ROOT for cross-project path resolution
Skills that reference files outside their own project (e.g., /distill-best-practices reading settings.yaml) use CLAUDE_PROJECT_ROOT env var instead of hardcoded ~/dev/claude/ or relative ../ paths. Makes skills portable across users. Env var exported in ~/.bashrc, with runtime fallback (walk up directory tree to find highest CLAUDE.md).
Skills: settings.yaml paths relative to project root
settings.yaml uses relative paths (projects_dir: projects) rather than absolute paths. Combined with CLAUDE_PROJECT_ROOT, this keeps config portable. The extra_projects section handles projects outside the standard projects_dir (e.g., small-scripts at root level).
CLAUDE.md: Remove technology-specific sections from root
Ansible and Helm sections removed from root CLAUDE.md — already covered with more detail in best-practices/ansible.md and best-practices/helm.md. Technology-specific practices belong in best-practices, not root guidelines.
context-load: Walk upward collecting context files
Walks from cwd upward collecting CLAUDE.md, CONTEXT.md, MEMORY.md, BESTPRACTICES.md at each level. Gives hierarchical context inheritance — highest ancestor provides global guidelines, project dir provides specifics.
context-load: Dedup via readlink -f
Root CLAUDE.md is a symlink to claude-foundations. Without dedup it would load twice. readlink -f resolves all symlinks before comparison.
context-load: Tree depth 3
Deep enough to show project structure without overwhelming output. Applied at every CLAUDE.md location.
CONTEXT.md follows MEMORY.md pattern
Thin index + context/ folder. Consistency with MEMORY.md. CONTEXT.md focuses on active work for agent orientation; MEMORY.md on accumulated learnings.
Status line: Per-session topic files keyed by session ID
Topic files at ~/.claude/status/<session-id>/claude-topic.txt. Session ID uniquely identifies each session, allowing multiple concurrent sessions to have independent topics without collisions.
Status line: Bridge session ID via /tmp file
Claude has no direct access to its own session ID. The status line script writes it to /tmp/claude-session-id-<md5 of cwd>, which set-topic.sh reads to find the correct per-session topic directory.
Status line: Config must exist in every profile settings file
Each profile (~/.claude, ~/.claude-octopus, ~/.claude-oreillyit) has its own settings.json with no inheritance. The statusLine entry must be added to each independently.