Remove all best-practices topic files and .distill-state.json from
claude-foundations. BESTPRACTICES.md now redirects to the standalone
repo at ~/dev/claude/projects/best-practices/. Remove the now-unnecessary
sync-best-practices.sh script.
Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
Hard rule: any service with a FQDN, multiple consumers, or concurrent
access MUST use PostgreSQL from day one. Documents the cost of "we'll
migrate later" based on the Gitea SQLite→PostgreSQL migration that cost
nearly a full day of productivity.
Extracted from cluster-bootstrap gitea-scaling session (2026-03-28).
Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
No server-side credential may cross the server boundary to the client.
The only credentials that cross are the client's own identity (MFA, OIDC, etc.).
Covers: proxy + identity mapping pattern, defense in depth layers,
anti-patterns (browser tokens, shared service accounts, embedded keys),
presigned URL exception for direct uploads, CMS real-world example.
Extracted from hugo-accelerator M4 where this principle drove the
CMS proxy architecture (Authelia + per-user Gitea tokens server-side).
Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
- 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>
New files:
- PLATFORMHUB.md: index for Platform Hub guidance
- platformhub/architecture.md: Git→PlatformHub→Projects model
- platformhub/ocl-syntax.md: complete OCL reference for templates
- platformhub/process-template-patterns.md: 5 proven patterns
- platformhub/gotchas.md: every error hit and how to fix it
- platformhub/api-reference.md: API vs UI capabilities
- best-practices/octopus-process-templates.md: consolidated best practices
Learned from building PlatformHub-Demo (30 microservices, 3 clouds).
Key discoveries: step templates are space-scoped (can't cross-reference),
worker_pool parameter is mandatory, publishing/sharing is UI-only.
Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
Pattern for matching container user UID/GID to mounted volume owner
via a gosu-based entrypoint wrapper. Covers UID conflicts (Ubuntu 24.04
ships ubuntu:1000), K8s securityContext compatibility, and alternatives.
Learned from agent-runtimes M1 where Claude Code refuses
--dangerously-skip-permissions as root.
Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
Add "Spec-Driven Development" section to global CLAUDE.md:
- Specs must exist before code for any multi-milestone coding project
- Always read SDD and TDD best practices at project start
- SPEC.md index + spec/ directory with numbered requirements
- Tests must reference spec requirement IDs
- Workflow: Plan → Spec → Test → Code
Also update "New Projects" section to reference the SDD requirement.
Prompted by customer-discovery project where we jumped from plan
straight to code, missing the spec step entirely.
Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
Documents the /housekeeping skill: purpose, usage, how it works,
and which scripts it orchestrates.
Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
Includes: spec-driven and test-driven development best practices,
reproduce-before-fixing debugging workflow, require-plan-file hook,
find-project-root script, session logs, memory files for decisions/
gotchas/process-lessons, and updates to existing best practice topics.
Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
Creates MEMORY.md index and 10 memory files documenting:
- Scripts: context-load, start-claude, install-hooks, setup-formatters, git-status-report
- Skills: /log, /reflect-logs, /reflect, /distill-best-practices, /linter
Each file covers purpose, usage, how it works, and gotchas.
Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
Every script in claude-foundations and skill in custom-claude-skills must
have a memory file in claude-foundations/memory/ with an index entry in
MEMORY.md, so future sessions can discover tooling without reading sources.
Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
Aligns index files with context-load discovery: BESTPRACTICES.md and CONTEXT.md
now follow the same thin-index pattern as MEMORY.md, auto-loaded at session start.
Adds documentation for both new index types to CLAUDE.md Documentation Standards.
Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
First use of the CONTEXT.md pattern — thin index pointing to
context/ topic files, loaded by context-load at session start.
Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
PostToolUse hook auto-formats files after Edit/Write/MultiEdit with
git-blob checkpoints for safe revert. Pre-commit hook for staged files.
Canonical formatter scripts for py, sh, ts, sql, json (+ symlinks for
js, yaml, md). Install and setup scripts for project opt-in.
Includes best-practices/linting.md, HOOKS.md docs, README.md, and
session log.
Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
context-load walks from cwd upward, loading CLAUDE.md, CONTEXT.md,
MEMORY.md, and BESTPRACTICES.md files with directory trees and git
status. start-claude wraps the claude CLI with --append-system-prompt.
CLAUDE.md: removed Ansible/Helm sections (in best-practices/), folded
Validate Before Deploying into Process Principles, deduped secrets
bullet, fixed best-practices path references.
Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
Hook source of truth now in hooks/, symlinked from ~/.claude/hooks/.
HOOKS.md covers what each hook does and installation steps.
Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
Hook implemented at ~/.claude/hooks/pre-compact-backup.sh, configured
in ~/.claude/settings.json for both auto and manual compaction triggers.
Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
- best-practices/: 11 topic files + INDEX.md extracted from cluster-bootstrap
and custom-claude-skills (validation, k8s, helm, ansible, secrets, debugging, etc.)
- settings.yaml: pipeline config (log retention, tracked projects, max logs per run)
- CLAUDE.md: updated with best-practices loading and pipeline documentation
- memory/log/: first session log demonstrating the format
Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
Conventions, community best practices research (Sept 2025 - March 2026),
and prioritized improvement backlog for Claude Code workflows.
Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
