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>
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>
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>
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>
