docs: finalize ADR statuses to Accepted; add ADR README and KSA scaffold
All seven ADRs were in draft/proposed/decided states — promote all to Accepted now that the decisions are implemented and stable. Add .claude/cos/adrs/README.md documenting the ADR lifecycle process. Add KSA Workspace Standards section to CLAUDE.md (sourced from scaffold at claude-scaffold/CLAUDE.md) so future sessions inherit workspace-wide rules without needing a separate file load. Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
This commit is contained in:
Kevin Adams
parent
9876e85d74
commit
4833cfbcca
|
|
@ -1,7 +1,7 @@
|
|||
# ADR-001: Consolidate Build Pipeline into Main Repo
|
||||
|
||||
**Date**: 2026-05-15
|
||||
**Status**: Proposed
|
||||
**Status**: Accepted
|
||||
**Deciders**: Kevin Adams
|
||||
|
||||
## Context
|
||||
|
|
|
|||
|
|
@ -1,7 +1,7 @@
|
|||
# ADR-002: UI Integration Strategy
|
||||
|
||||
**Date**: 2026-05-15
|
||||
**Status**: Under Discussion
|
||||
**Status**: Accepted
|
||||
**Deciders**: Kevin Adams
|
||||
|
||||
## Context
|
||||
|
|
|
|||
|
|
@ -1,7 +1,7 @@
|
|||
# ADR-003: APT Repository Hosting
|
||||
|
||||
**Date**: 2026-05-15
|
||||
**Status**: Under Discussion
|
||||
**Status**: Accepted
|
||||
**Deciders**: Kevin Adams
|
||||
|
||||
## Context
|
||||
|
|
|
|||
|
|
@ -1,7 +1,7 @@
|
|||
# ADR-004: Transactional Cleanup on API Operation Failure
|
||||
|
||||
**Date**: 2026-05-15
|
||||
**Status**: Decided
|
||||
**Status**: Accepted
|
||||
**Deciders**: Kevin Adams
|
||||
|
||||
## Context
|
||||
|
|
|
|||
|
|
@ -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
|
||||
|
|
|
|||
|
|
@ -1,7 +1,7 @@
|
|||
# ADR-006: Package Versioning Strategy
|
||||
|
||||
**Date**: 2026-05-15
|
||||
**Status**: Decided
|
||||
**Status**: Accepted
|
||||
**Deciders**: Kevin Adams
|
||||
|
||||
## Context
|
||||
|
|
|
|||
|
|
@ -1,7 +1,7 @@
|
|||
# ADR-007: FreeNAS vs TrueNAS Module Naming
|
||||
|
||||
**Date**: 2026-05-15
|
||||
**Status**: Decided
|
||||
**Status**: Accepted
|
||||
**Deciders**: Kevin Adams
|
||||
|
||||
## Context
|
||||
|
|
|
|||
|
|
@ -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 |
|
||||
120
CLAUDE.md
120
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 <noreply@anthropic.com>`
|
||||
- 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/<workspace-path>/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.
|
||||
|
|
|
|||
Loading…
Reference in New Issue