XKush · XKush · Jun 29, 2026 · Jun 29, 2026
@@ -12,6 +12,7 @@
 /docs/API-STABILITY.md @XKush
 /docs/JSON-SCHEMA.md @XKush
 /docs/RELEASE-CRITERIA.md @XKush
+/docs/rfc/ @XKush
 
 # CI & automation
 /.github/workflows/ @XKush

@@ -18,8 +18,9 @@ Questions like “should I use `health` or `doctor`?” belong in **Discussions*
 2. Keep changes focused — one problem per PR  
 3. Do **not** change the locked platform execution stack without maintainer sign-off (see `internal-docs/charter/PLATFORM-SPEC-SIGNOFF.md`)
 4. JSON / CLI changes: read [API-STABILITY.md](docs/API-STABILITY.md) and [JSON-SCHEMA.md](docs/JSON-SCHEMA.md)
-5. New features: check [MANIFESTO.md](docs/MANIFESTO.md) and [PROJECT-PRINCIPLES.md](docs/PROJECT-PRINCIPLES.md) first
-6. Maintainers cutting a release: [RELEASE-CRITERIA.md](docs/RELEASE-CRITERIA.md)
+5. New features: check [MANIFESTO.md](docs/MANIFESTO.md) and [PROJECT-PRINCIPLES.md](docs/PROJECT-PRINCIPLES.md) first  
+6. **Large ideas** (plugins, new CLI, API breaks): [RFC process](docs/rfc/README.md) — **no implementation code** until RFC Accepted  
+7. Maintainers cutting a release: [RELEASE-CRITERIA.md](docs/RELEASE-CRITERIA.md)
 
 Script layout: [`scripts/README.md`](scripts/README.md) · [Repository surface](docs/product/REPOSITORY-SURFACE.md)
 
@@ -42,6 +43,6 @@ Include: Windows version, PowerShell version (`$PSVersionTable`), `devshell heal
 
 ## v3 stabilization (current phase)
 
-We are **not** adding new public CLI commands in v3.0.x. Focus: bugfix, docs, tests, feedback. Feature ideas → Discussions first.
+We are **not** adding new public CLI commands in v3.0.x. Focus: bugfix, docs, tests, feedback. Large ideas → [RFC](docs/rfc/README.md) first; small questions → Discussions.
 
 Contract: [ROADMAP.md](docs/ROADMAP.md) · Principles: [PROJECT-PRINCIPLES.md](docs/PROJECT-PRINCIPLES.md) · [MANIFESTO.md](docs/MANIFESTO.md) · Releases: [RELEASE-CRITERIA.md](docs/RELEASE-CRITERIA.md)
@@ -144,6 +144,7 @@ Full layout: [docs/product/REPOSITORY-SURFACE.md](docs/product/REPOSITORY-SURFAC
 | [Project principles](docs/PROJECT-PRINCIPLES.md) | Engineering guardrails |
 | [Manifesto](docs/MANIFESTO.md) | Why we exist · what we never do |
 | [Release criteria](docs/RELEASE-CRITERIA.md) | Pre-tag checklist for maintainers |
+| [RFC process](docs/rfc/README.md) | Large ideas before code (plugins, API changes) |
 | [Troubleshooting](docs/TROUBLESHOOTING.md) | When doctor fails |
 | [Privacy](docs/PRIVACY.md) | Privacy configuration module |
 | [API stability](docs/API-STABILITY.md) | Frozen CLI contract (v3+) |

@@ -2,6 +2,8 @@
 
 One page on **why** this project exists and **what it refuses to become**.
 
+We optimize for **trust**, not feature count. Trust comes from consistent decisions over a long time — not from shipping the largest PowerShell toolkit.
+
 ---
 
 ## Why we exist

@@ -34,7 +34,7 @@ Engineering guardrails for contributors and future maintainers. When in doubt, p
 
 | Before you… | Read |
 |-------------|------|
-| Propose a feature | [MANIFESTO](MANIFESTO.md) · [ROADMAP](ROADMAP.md) |
+| Propose a feature | [MANIFESTO](MANIFESTO.md) · [ROADMAP](ROADMAP.md) · [RFC](rfc/README.md) if large |
 | Change JSON output | [JSON-SCHEMA](JSON-SCHEMA.md) |
 | Change architecture | New [ADR](adr/) |
 | Cut a release | [RELEASE-CRITERIA](RELEASE-CRITERIA.md) |

@@ -42,12 +42,12 @@ Explored **after** stabilization feedback — not committed dates:
 
 | Area | Notes |
 |------|--------|
-| **Plugin API** | `plugins/` — Docker, WSL, VS Code, Azure, AWS, GitHub, Rust, Go |
+| **Plugin API** | `plugins/` — see [RFC index](rfc/README.md) (Docker, WSL, …) |
 | **History** | Richer trends, export, compare |
 | **HTML reports** | Deeper styling, shareable bundles |
 | **Integrations** | GitHub Actions templates, Intune-friendly JSON |
 
-Ideas → [Discussions](https://github.com/XKush/homebase-devshell/discussions) · label `idea`
+Ideas → [RFC](rfc/README.md) (large) or [Discussions](https://github.com/XKush/homebase-devshell/discussions) (small)
 
 ---
 

@@ -0,0 +1,68 @@
+# RFC process
+
+**Request for Comments** — how large ideas enter HomeBase DevShell.
+
+> Goal shift: we are not optimizing for “the biggest PowerShell toolkit.”  
+> We are building a project **people trust** — through consistent decisions over time.
+
+## Pipeline (order matters)
+
+```
+RFC (proposal, no code)
+    ↓
+Discussion (GitHub)
+    ↓
+Feedback (community + maintainers)
+    ↓
+ADR (if architecture/policy changes)
+    ↓
+Implementation (PR + tests)
+```
+
+**Not the reverse.** No plugin code, no new frozen CLI commands, no JSON schema breaks until an RFC is **Accepted**.
+
+## When you need an RFC
+
+| Need RFC | No RFC needed |
+|----------|----------------|
+| New plugin (Docker, WSL, VS Code, …) | Doc typo, troubleshooting line |
+| New public CLI command | Bug fix in existing command |
+| Breaking JSON / API change | Additive JSON field (minor) |
+| Core health dashboard behavior change | Smoke test assertion |
+| Platform orchestrator change | Internal refactor without behavior change |
+
+Check [MANIFESTO](MANIFESTO.md) and [PROJECT-PRINCIPLES](PROJECT-PRINCIPLES.md) before drafting.
+
+## RFC states
+
+| State | Meaning |
+|-------|---------|
+| **Proposed** | Open for comment — do not implement |
+| **Accepted** | Maintainers approved — implementation may start |
+| **Rejected** | Will not pursue (reason documented) |
+| **Superseded** | Replaced by a newer RFC |
+
+## How to propose
+
+1. Copy [RFC-0000-template.md](RFC-0000-template.md) → `RFC-NNNN-short-title.md`
+2. Open a [Discussion](https://github.com/XKush/homebase-devshell/discussions) (category **Ideas**) linking the RFC
+3. PR only the RFC markdown — **no product code** in the same PR
+4. After acceptance, maintainer updates status → **Accepted**, then optional ADR, then implementation PRs
+
+## Index
+
+| RFC | Title | Status |
+|-----|-------|--------|
+| [RFC-0001](RFC-0001-docker-plugin.md) | Docker plugin | Proposed |
+| [RFC-0002](RFC-0002-wsl-plugin.md) | WSL plugin | Proposed |
+
+Accepted RFCs may reference ADRs in [../adr/](../adr/).
+
+## Relationship to other docs
+
+| Doc | Role |
+|-----|------|
+| **RFC** | *Should we?* — design proposal before code |
+| **ADR** | *Why we did* — recorded decision after consensus |
+| **ROADMAP** | *When we ship* — contract by version |
+| **API-STABILITY** | *What we must not break* |
@@ -0,0 +1,61 @@
+# RFC-0000: Template
+
+**Status:** Template (do not accept)  
+**Author:** &lt;name&gt;  
+**Created:** YYYY-MM-DD  
+**Discussion:** &lt;link to GitHub Discussion&gt;
+
+---
+
+## Summary
+
+One paragraph: what problem this solves and for whom.
+
+## Motivation
+
+- Why now?
+- Who asked for it (users, CI, enterprise)?
+- How does it align with [MANIFESTO](../MANIFESTO.md)?
+
+## User experience
+
+What does the user run or see? Prefer extending `devshell health` over new top-level commands.
+
+## Design
+
+### Scope
+
+What is in / out?
+
+### Integration
+
+- Core vs `plugins/`
+- JSON report impact (`healthSchemaVersion` / `reportSchemaVersion`)
+- Offline behavior
+
+### Security & trust
+
+- Reversible?
+- Defender / Firewall / anonymity boundaries per [PROJECT-PRINCIPLES](../PROJECT-PRINCIPLES.md)
+
+## Alternatives considered
+
+| Option | Why not |
+|--------|---------|
+| … | … |
+
+## Drawbacks
+
+What we give up; maintenance cost.
+
+## Unresolved questions
+
+- [ ] …
+
+## Implementation plan (after acceptance only)
+
+1. ADR if needed  
+2. Tests first  
+3. Minimal PR scope  
+
+**No code in the RFC PR.**
@@ -0,0 +1,83 @@
+# RFC-0001: Docker plugin
+
+**Status:** Proposed  
+**Author:** HomeBase DevShell maintainers  
+**Created:** 2026-06-29  
+**Discussion:** *(open an Ideas discussion when ready)*
+
+---
+
+## Summary
+
+Optional **Docker** plugin under `plugins/Docker/` that adds container-runtime readiness checks to `devshell health` — without new frozen CLI commands.
+
+## Motivation
+
+Developers on Windows often have broken Docker Desktop, WSL2 backend, or stale context while the rest of the workstation passes `devshell health`. Today that gap is invisible.
+
+Aligns with trust goal: **report what we can verify**, disclaim what we cannot (no image vulnerability scanning in v1).
+
+## User experience
+
+```powershell
+devshell health          # includes Docker section when plugin installed
+devshell health -Json    # plugin section in machine report
+```
+
+No `devshell docker` top-level command in v1 — health aggregation only.
+
+## Design
+
+### Scope
+
+**In**
+
+- Detect `docker` CLI on PATH
+- Docker Desktop / engine reachable (`docker info` timeout-bounded)
+- Optional: context name, WSL2 backend hint
+
+**Out**
+
+- Image CVE scanning
+- Kubernetes / compose stack validation
+- Auto-install Docker Desktop
+
+### Integration
+
+- `plugins/Docker/manifest.json` per [plugins/README.md](../../plugins/README.md)
+- `doctor.ps1` invoked by health merger (post-acceptance design)
+- JSON: new **optional** `sections.docker` object — additive only; schema minor bump if accepted
+
+### Security & trust
+
+- Read-only checks by default
+- Any `repair.ps1` must be idempotent and documented; never pull arbitrary images
+- Must pass MANIFESTO “no unverified software” rule
+
+## Alternatives considered
+
+| Option | Why not |
+|--------|---------|
+| Core built-in Docker checks | Violates v3.x “no core bloat”; Docker not universal |
+| `devshell docker` command | Frozen API expansion — prefer health section |
+| Ignore Docker | Leaves common dev pain unaddressed |
+
+## Drawbacks
+
+- Maintenance across Docker Desktop versions
+- CI needs careful mocking (no Docker required on every runner)
+
+## Unresolved questions
+
+- [ ] Should plugin ship in main repo or separate repo first?
+- [ ] Minimum checks for “PASS” vs “WARN”?
+- [ ] Windows Home without Hyper-V — graceful INFO?
+
+## Implementation plan (after acceptance only)
+
+1. ADR: plugin manifest contract  
+2. RFC acceptance → `plugins/Docker/` skeleton + manifest only  
+3. Health merger + smoke test (mocked `docker`)  
+4. No release until [RELEASE-CRITERIA](../RELEASE-CRITERIA.md) green  
+
+**Status: Proposed — no implementation code until Accepted.**
@@ -0,0 +1,85 @@
+# RFC-0002: WSL plugin
+
+**Status:** Proposed  
+**Author:** HomeBase DevShell maintainers  
+**Created:** 2026-06-29  
+**Discussion:** *(open an Ideas discussion when ready)*
+
+---
+
+## Summary
+
+Optional **WSL** plugin that reports Windows Subsystem for Linux readiness (distro installed, default version, integration with Docker backend) via `devshell health`.
+
+## Motivation
+
+WSL is a common dependency for Docker, Node, and Linux tooling on Windows. Failures are often silent until a tool fails mid-build.
+
+Supports the product goal: **trust through visible configuration state**, not promises about Linux workload performance.
+
+## User experience
+
+```powershell
+devshell health
+```
+
+Example section (illustrative):
+
+```
+WSL                    WARN
+  Default: Ubuntu — WSL2 not default kernel
+```
+
+## Design
+
+### Scope
+
+**In**
+
+- `wsl --status` / `wsl -l -v` parsing (offline, local)
+- Default distro present
+- WSL version (1 vs 2) per distro
+- Optional cross-check: Docker Desktop WSL integration flag (if Docker RFC accepted)
+
+**Out**
+
+- Installing distros or running `wsl --install`
+- Linux package audits inside guest
+- Network tests to external sites
+
+### Integration
+
+- `plugins/WSL/manifest.json`
+- Health section `wslConfiguration` (name TBD at acceptance)
+- Additive JSON only
+
+### Security & trust
+
+- No elevation required for read-only listing
+- `repair.ps1` limited to documented safe actions (e.g. suggest `wsl --set-default-version 2`) — never force reboot
+
+## Alternatives considered
+
+| Option | Why not |
+|--------|---------|
+| Fold into Docker plugin only | WSL useful without Docker |
+| Core doctor checks | Not all DevReady users use WSL — plugin keeps core small |
+
+## Drawbacks
+
+- Output varies by Windows build and locale
+- Parsing `wsl` text is fragile — prefer structured flags where available
+
+## Unresolved questions
+
+- [ ] Minimum Windows build support?
+- [ ] How to test in CI without WSL enabled on runner?
+- [ ] Merge order with RFC-0001 (Docker)?
+
+## Implementation plan (after acceptance only)
+
+1. Accept RFC-0002 (may proceed in parallel with RFC-0001 if both Accepted)
+2. Plugin skeleton + mocked unit tests
+3. Document limitations in section disclaimer (like Privacy Configuration)
+
+**Status: Proposed — no implementation code until Accepted.**
@@ -2,6 +2,8 @@
 
 HomeBase DevShell core stays small. Optional capabilities live in **plugins** without modifying frozen CLI commands.
 
+**Before any plugin code:** propose and accept an [RFC](../docs/rfc/README.md) (e.g. [RFC-0001 Docker](../docs/rfc/RFC-0001-docker-plugin.md), [RFC-0002 WSL](../docs/rfc/RFC-0002-wsl-plugin.md)).
+
 ## Planned layout
 
 ```
@@ -26,7 +28,7 @@ plugins/
 }
 ```
 
-## Integration (not implemented in v3.0.0)
+## Integration (not implemented until RFC Accepted)
 
 `devshell health` may merge plugin sections when `plugins/*/manifest.json` is present. Core health works **without** plugins.
-Original file line number
+Diff line change
@@ Expand Up / @@ -2,6 +2,8 @@ @@
     One page on **why** this project exists and **what it refuses to become**.
+    We optimize for **trust**, not feature count. Trust comes from consistent decisions over a long time — not from shipping the largest PowerShell toolkit.
     ---
     ## Why we exist
@@ Expand Down @@