diff --git a/.claude/cos/adrs/ADR-001-consolidate-build-into-main-repo.md b/.claude/cos/adrs/ADR-001-consolidate-build-into-main-repo.md index 06db745..6f947fe 100644 --- a/.claude/cos/adrs/ADR-001-consolidate-build-into-main-repo.md +++ b/.claude/cos/adrs/ADR-001-consolidate-build-into-main-repo.md @@ -1,7 +1,7 @@ # ADR-001: Consolidate Build Pipeline into Main Repo **Date**: 2026-05-15 -**Status**: Proposed +**Status**: Accepted **Deciders**: Kevin Adams ## Context diff --git a/.claude/cos/adrs/ADR-002-ui-strategy.md b/.claude/cos/adrs/ADR-002-ui-strategy.md index 5f080cc..f8e0267 100644 --- a/.claude/cos/adrs/ADR-002-ui-strategy.md +++ b/.claude/cos/adrs/ADR-002-ui-strategy.md @@ -1,7 +1,7 @@ # ADR-002: UI Integration Strategy **Date**: 2026-05-15 -**Status**: Under Discussion +**Status**: Accepted **Deciders**: Kevin Adams ## Context diff --git a/.claude/cos/adrs/ADR-003-apt-repo-hosting.md b/.claude/cos/adrs/ADR-003-apt-repo-hosting.md index 4c3b0a1..ca6bbf9 100644 --- a/.claude/cos/adrs/ADR-003-apt-repo-hosting.md +++ b/.claude/cos/adrs/ADR-003-apt-repo-hosting.md @@ -1,7 +1,7 @@ # ADR-003: APT Repository Hosting **Date**: 2026-05-15 -**Status**: Under Discussion +**Status**: Accepted **Deciders**: Kevin Adams ## Context diff --git a/.claude/cos/adrs/ADR-004-cleanup-on-failure.md b/.claude/cos/adrs/ADR-004-cleanup-on-failure.md index 3003bd4..90490e8 100644 --- a/.claude/cos/adrs/ADR-004-cleanup-on-failure.md +++ b/.claude/cos/adrs/ADR-004-cleanup-on-failure.md @@ -1,7 +1,7 @@ # ADR-004: Transactional Cleanup on API Operation Failure **Date**: 2026-05-15 -**Status**: Decided +**Status**: Accepted **Deciders**: Kevin Adams ## Context diff --git a/.claude/cos/adrs/ADR-005-bearer-token-authentication.md b/.claude/cos/adrs/ADR-005-bearer-token-authentication.md index d83fad1..633a9fc 100644 --- a/.claude/cos/adrs/ADR-005-bearer-token-authentication.md +++ b/.claude/cos/adrs/ADR-005-bearer-token-authentication.md @@ -1,7 +1,7 @@ # ADR-005: Bearer Token Authentication as Primary Auth Method **Date**: 2026-05-15 -**Status**: Decided +**Status**: Accepted **Deciders**: Kevin Adams ## Context diff --git a/.claude/cos/adrs/ADR-006-versioning-strategy.md b/.claude/cos/adrs/ADR-006-versioning-strategy.md index 6334779..8d545f4 100644 --- a/.claude/cos/adrs/ADR-006-versioning-strategy.md +++ b/.claude/cos/adrs/ADR-006-versioning-strategy.md @@ -1,7 +1,7 @@ # ADR-006: Package Versioning Strategy **Date**: 2026-05-15 -**Status**: Decided +**Status**: Accepted **Deciders**: Kevin Adams ## Context diff --git a/.claude/cos/adrs/ADR-007-freenas-vs-truenas-naming.md b/.claude/cos/adrs/ADR-007-freenas-vs-truenas-naming.md index 4410775..f512dfa 100644 --- a/.claude/cos/adrs/ADR-007-freenas-vs-truenas-naming.md +++ b/.claude/cos/adrs/ADR-007-freenas-vs-truenas-naming.md @@ -1,7 +1,7 @@ # ADR-007: FreeNAS vs TrueNAS Module Naming **Date**: 2026-05-15 -**Status**: Decided +**Status**: Accepted **Deciders**: Kevin Adams ## Context diff --git a/.claude/cos/adrs/README.md b/.claude/cos/adrs/README.md new file mode 100644 index 0000000..abc43c2 --- /dev/null +++ b/.claude/cos/adrs/README.md @@ -0,0 +1,32 @@ +# Architecture Decision Records + +ADRs document significant decisions made about this project. They follow an RFC-style lifecycle. + +## Lifecycle + +| Status | Meaning | +|--------|---------| +| **Draft** | Being written or discussed. Not yet binding. May change freely. | +| **Accepted** | Agreed upon and in effect. Guides implementation. | +| **Superseded** | Replaced by a newer ADR. The old record is preserved as history. The header notes which ADR supersedes it. | +| **Rejected** | Proposed but explicitly decided against. Preserved so we remember why. | +| **Deprecated** | Was accepted but no longer applicable (e.g., a feature was dropped). Not replaced. | + +## Rules + +- **Never edit the Decision section of an Accepted ADR.** If the decision changes, write a new ADR and mark the old one `Superseded by ADR-XXX`. +- **Draft ADRs can be edited freely** — they are working documents. +- **Numbering is sequential and permanent.** A superseded ADR keeps its number; the new one gets the next number. +- **Context and Consequences sections** may be lightly edited for clarity even after acceptance (fix typos, add links), but the decision itself is immutable. + +## Index + +| ADR | Title | Status | +|-----|-------|--------| +| [ADR-001](ADR-001-consolidate-build-into-main-repo.md) | Consolidate Build Pipeline into Main Repo | Accepted | +| [ADR-002](ADR-002-ui-strategy.md) | UI Integration Strategy | Accepted | +| [ADR-003](ADR-003-apt-repo-hosting.md) | APT Repository Hosting | Accepted | +| [ADR-004](ADR-004-cleanup-on-failure.md) | Transactional Cleanup on API Operation Failure | Accepted | +| [ADR-005](ADR-005-bearer-token-authentication.md) | Bearer Token Authentication as Primary Auth Method | Accepted | +| [ADR-006](ADR-006-versioning-strategy.md) | Package Versioning Strategy | Accepted | +| [ADR-007](ADR-007-freenas-vs-truenas-naming.md) | FreeNAS vs TrueNAS Module Naming | Accepted | diff --git a/CLAUDE.md b/CLAUDE.md index 4cb6924..0ff3759 100644 --- a/CLAUDE.md +++ b/CLAUDE.md @@ -81,3 +81,123 @@ The plugin auto-detects v1.0 vs v2.0 API based on the TrueNAS version string and See `.claude/cos/adrs/` for Architecture Decision Records. See `.claude/cos/plans/` for implementation plans. See `.claude/cos/runbooks/` for operational runbooks. + +--- + +# KSA Workspace Standards + +> Baseline rules for all KSA Technologies Claude workspaces. +> Source of truth: `/mnt/c/Users/Kevin/OneDrive - ksatechnologies.com/workspace/claude-scaffold/CLAUDE.md` + +## Environment + +- **Shell:** WSL (Linux). Always use bash/Linux syntax — `export VAR=value`, forward slashes, `source .venv/activate`. Never PowerShell, never cmd.exe. +- **OS:** WSL2 on Windows. Paths under `/mnt/c/Users/Kevin/OneDrive - ksatechnologies.com/workspace/`. + +## Agent / Minion Rules + +- **Minions are research-only.** They search, read, and web-fetch. They return findings to main Claude. They never write files, commit, push, or delete. +- **Minions do not talk to each other.** All findings route through main Claude. +- **Main Claude does all writing, committing, and pushing.** + +## File Rules + +- **New files:** write freely. +- **Changes to existing files:** use targeted edits only — add or modify, never blank out content. +- **Total replacement of an existing file:** write the replacement as a NEW file first, explain to the user why the old file needs replacing, wait for explicit approval. Never silently overwrite. +- **Briefs and reports:** always new dated files. Never overwrite a previous brief. The historical record grows forward, never shrinks. + +## Permission Levels + +| Actor | Permissions | +|---|---| +| **User** | Full control — can do anything including delete | +| **Main Claude** | Pre-approved: read, write, edit, commit, push, gh CLI. Must ask before any delete unless user has explicitly pre-authorized it. | +| **Minions** | Research only — read, search, web-fetch. No write, commit, push, or delete. | + +## Workflow Order + +Always follow this sequence. Never skip ahead: + +1. **Open a GitHub issue** — captures the problem/feature before any code +2. **Update design/architecture docs** — ADR if warranted, roadmap, architecture +3. **Implement code** — with tests +4. **Update docs** — test-scenarios, user examples, troubleshooting callouts +5. **Close the issue** — with version, commit, and doc pointers + +## Documentation Discipline + +Every feature, breaking change, or config change ships with: +- Code + tests +- Test-scenario examples +- Troubleshooting callouts where relevant +- Architecture/design doc update if the shape changed +- ADR if a significant technology decision was made +- Roadmap `Resolved` update + +Never ship a feature without its docs. + +## Issue Lifecycle + +- Close issues when work ships — include version, commit SHA, and doc pointers +- User-filed bugs: add `fixed — awaiting-feedback` label if user confirmation needed +- Dependabot patch/minor: merge when CI is green (ad-hoc, no milestone) +- Dependabot major: open an issue, add to a milestone, test intentionally +- Dependabot CVE: link PR to the security issue, include in relevant milestone + +## SAFe Hierarchy (GitHub Issues) + +| Level | GitHub object | When to use | +|---|---|---| +| **Milestone** | GitHub Milestone | PI / sprint container, ties to a semver release | +| **Feature** | Issue (`enhancement` label + milestone) | Single deployable unit of value — this is the default issue type | +| **Epic** | Issue (`epic` label, no milestone, task list of linked features) | Only when work spans multiple milestones | +| **Story** | Sub-task within a feature | Only when multiple contributors need independently assignable units | + +Default: **milestone → feature**. Add epic and story layers only when the team size and cross-milestone scope justify the overhead. + +## Technology Governance + +Follow the original developer when a project forks due to governance or ownership breakdown. Validated examples: +- pfSense → **OPNsense** (m0n0wall founder Kasper endorsed it) +- CentOS → **Rocky Linux** (co-founder Kurtzer created it within days) +- nginx → watch **freenginx** (core developer Dounin forked over F5 governance) +- OpenOffice → **LibreOffice** (original developers moved there) + +**Avoid:** Oracle (hostile OSS track record), F5/nginx (governance broken), Bitnami (stale images since 2024 paid tier split). + +**Preferred stack:** +- Server OS: Rocky Linux, Debian +- Container base (community): `python:slim-bookworm` +- Container base (production): `python:alpine` +- Container base (enterprise/FIPS): `cgr.dev/chainguard/python` +- CNI: Cilium +- Ingress: Kubernetes Gateway API (Cilium native implementation) +- Secrets: HashiCorp Vault sidecar / CSI driver +- Postgres (single node): `postgres:16-alpine` custom subchart +- Postgres (HA): CloudNativePG operator + +## ADR Process + +ADRs follow an RFC lifecycle: **Draft → Proposed → Accepted / Rejected / Withdrawn**. When a decision changes, a new ADR is created and the old one is marked **Superseded** — the historical record is never deleted. + +See `ADR-000-process.md` in any project that uses ADRs for the full format and lifecycle definition. + +## Git Commit Style + +- Conventional commits: `feat:`, `fix:`, `docs:`, `chore:`, `ci:`, `refactor:` +- Co-author line on every commit: `Co-Authored-By: Claude Sonnet 4.6 ` +- Commit message: why, not what. The diff shows what; the message explains why. +- Never amend published commits. Create new commits instead. +- Never skip hooks (`--no-verify`) unless explicitly instructed. + +## Memory System + +Memory lives at: `.claude/projects//memory/MEMORY.md` + +On starting a new session, read `MEMORY.md` first. It indexes all project-specific memories. Update memory when: +- User corrects an approach or confirms a non-obvious one +- A significant project decision is made +- User preferences or constraints are stated + +Never save ephemeral task details to memory — use the todo list for that.