Add context-load/start-claude scripts and clean up CLAUDE.md

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>
This commit is contained in:
Paul O'Reilly
2026-03-13 11:49:40 +13:00
parent 00fa1af898
commit a463dc0793
3 changed files with 179 additions and 31 deletions

View File

@@ -15,9 +15,9 @@
Scan the directories at runtime so the list is always current. Include a brief description if the project has a CLAUDE.md or README.md you can glean one from.
2. Based on the user's choice:
- **Existing project**: `cd` into the directory, read all `.md` files, and read `~/dev/claude/secrets/` (read-only reference — review every file to refresh context). Then read the [Best Practices Index](best-practices/INDEX.md) and load any topic files relevant to the selected project's technology stack. Ask clarifying questions if anything is unclear or incomplete, and note context in MEMORY.md.
- **Existing project**: `cd` into the directory, read all `.md` files, and read `~/dev/claude/secrets/` (read-only reference — review every file to refresh context). Then read the [Best Practices Index](best-practices/INDEX.md) in the `claude-foundations` repo and load any topic files relevant to the selected project's technology stack. Ask clarifying questions if anything is unclear or incomplete, and note context in MEMORY.md.
- **No project right now**: Do nothing further — just respond normally.
- **New project!**: Follow the "New Projects" section below. Also read `~/dev/claude/secrets/` as above. Read the [Best Practices Index](best-practices/INDEX.md) and load topic files relevant to the new project's technology stack.
- **New project!**: Follow the "New Projects" section below. Also read `~/dev/claude/secrets/` as above. Read the [Best Practices Index](best-practices/INDEX.md) in the `claude-foundations` repo and load topic files relevant to the new project's technology stack.
## Secrets (`~/dev/claude/secrets/`)
@@ -116,7 +116,7 @@ Three skills form a continuous learning pipeline across projects:
1. **`/log`** — Run at end of session. Captures decisions, gotchas, open questions to `memory/log/YYYY-MM-DD.<HHMMSS>.md` in the current project. Also prunes old reflected logs.
2. **`/reflect-logs`** — Run periodically. Processes unprocessed session logs into topic memory files (`memory/gotchas-*.md`, `memory/process-lessons.md`, etc.). Flags stale entries. Tracks state in `.reflection-state.json`.
3. **`/distill-best-practices`** — Run from any project. Reads changed memory files across all tracked projects and proposes updates to `claude-foundations/best-practices/`. Tracks state in `best-practices/.distill-state.json`.
3. **`/distill-best-practices`** — Run from any project. Reads changed memory files across all tracked projects and proposes updates to the `claude-foundations` repo's `best-practices/` folder. Tracks state in `best-practices/.distill-state.json`.
### State Files
- **`.reflection-state.json`** — Per-project, tracks which logs have been reflected on (md5 hashes of log file content)
@@ -145,18 +145,6 @@ Break projects into numbered milestones (M1, M2, ...). Every milestone completio
3. **Updated README.md** — scripts section, milestone table, any new setup steps
4. **Updated CLAUDE.md** — repo structure, conventions, new patterns discovered
## Validate Before Deploying
Every new config, manifest, or template should be validated locally before deploying. The target environment is not a test environment — each deploy-crash-fix cycle wastes time and clutters Git history. Batch fixes locally, push once.
Examples:
- `helm template` for Helm values
- `kustomize build` for Kustomize apps
- `docker run <app> validate-configuration` for app configs
- `docker inspect` for unfamiliar container images
- Lint/typecheck/test for application code
- `curl --resolve` for the full request chain after deployment
## Version Management
- Use the latest stable version of dependencies unless pinned for a reason
@@ -170,7 +158,6 @@ Examples:
- The `.sops.yaml` at the repo root defines path-based encryption rules
- Filenames containing `secret` trigger SOPS encryption via pre-commit hooks
- Non-secret files must NOT contain `secret` in their name
- Never pass secrets via command-line arguments (visible in `ps` output) — use `@file` references or environment variables
- Keep unencrypted secrets in `local_secrets/` (gitignored)
## Scripting Conventions
@@ -185,24 +172,10 @@ Examples:
These are hard-won lessons from real project work:
- **Validate locally, deploy once.** Don't use the live environment as a test bed. Catch errors with local validation tools before pushing.
- **Validate locally, deploy once.** Don't use the live environment as a test bed. Catch errors with local validation tools before pushing (`helm template`, `kustomize build`, lint/typecheck, `docker inspect`, etc.). Batch fixes locally, push once.
- **Check before you act.** Before writing firewall/network rules, check actual routing (`ip route get`). Before running config management with variables, ensure values are real, not placeholders. Before assuming a container has a shell, `docker inspect` it.
- **Test the full chain immediately.** After wiring up a new service or endpoint, test end-to-end from the user's perspective right away. Don't assume intermediate steps working means the whole chain works.
- **Verify scripts should be environment-resilient.** Avoid needing sudo or special access. Test from the accessible side of a connection. Use `curl --resolve` to bypass DNS/proxy layers when testing direct connectivity.
- **Automate repeated sequences.** If you run the same 3+ commands in sequence more than once, it should become a script.
- **Reflect after milestones.** Don't just finish — review what happened, what went wrong, what can be improved. Write it down so future sessions benefit.
## Ansible Conventions (where applicable)
- Roles follow standard structure: `tasks/main.yml`, `templates/*.j2`, `handlers/main.yml`
- Jinja2 templates have `.j2` extension and include a "managed by Ansible" header comment
- Variables that need customisation go in `inventory.yml`, not scattered across role defaults
- Always pass `-i inventory.yml` explicitly or run from the directory containing `ansible.cfg`
- Never use placeholder values with `-e` for vars that template config files
## Helm Chart Conventions (where applicable)
- Always validate values against the chart schema before committing
- Run `helm show values <repo>/<chart> --version <ver>` to check actual structure
- Schemas change between versions — field names and nesting can differ from docs or online examples
- A quick `helm template` test locally catches schema errors before deployment