docs: Community-friendly documentation and governance pass

[biglyan]

Summary

This PR implements the first documentation and governance pass to make Plumego more friendly to the Go developer community.

Scope: Documentation, examples, and governance files only. No runtime behavior changes. No public API changes.

Changes

1. STABILITY.md (269 lines)

• Full compatibility policy and maturity levels
• Stable root packages (9 packages with GA guarantees)
• Extension maturity levels: experimental, beta, GA
• SemVer expectations and breaking change policy
• Go version support policy (two most recent stable releases)
• Deprecation and removal strategy

2. COMPATIBILITY.md (431 lines)

• How Plumego integrates with stdlib and ecosystem
• Standard library compatibility patterns (handlers, middleware, response writers)
• Server lifecycle and transport compatibility
• Logger, metrics, and config neutrality
• Storage layer and testing compatibility
• Migration and exit strategies for other frameworks
• Quick compatibility checklist

3. docs/EXTENSION_MATURITY.md (229 lines)

• Human-readable maturity dashboard
• Quick reference table for maturity levels
• Characteristics and use cases for each level
• Current packages organized by maturity
• Migration paths between levels
• How to check and verify package maturity

4. docs/roadmap/go-community-friendly-iteration-plan.md (381 lines)

• Strategic iteration plan and community positioning
• Community value assessment and market positioning
• Three-phase roadmap: Phase 1 (v1.2), Phase 2 (v1.3), Phase 3 (v2.0)
• Risk mitigation strategies
• Success criteria and verification matrix
• Adoption path breakdown (5-minute, 30-minute, 1-day, production)

5. examples/ (2 working examples)

• hello/: Minimal "hello world" service

  • App initialization, routing, logging
  • Demonstrates basic patterns
  • Compiles with no external dependencies

• json-api/: REST-like JSON API with CRUD operations

  • Request/response JSON handling
  • Path parameter extraction
  • Error handling with contract errors
  • Thread-safe in-memory storage
  • Compiles and runs

6. examples/README.md (60 lines)

• Overview of all examples
• Learning path from hello → json-api → reference/standard-service
• Instructions for running examples

Positioning

This documentation pass positions Plumego as:

A standard-library-first Go HTTP toolkit for explicit, maintainable, agent-friendly services.

Key differentiators:

• Handlers are ordinary http.Handler, not framework-specific
• Middleware follow func(http.Handler) http.Handler signature
• Small stable core (9 packages)
• Optional extensions (x/*)
• Explicit wiring with no hidden magic
• Full stdlib compatibility

Verification

✅ All tests pass: go test ./...
✅ No vet warnings: go vet ./...
✅ Examples compile:

• examples/hello builds successfully
• examples/json-api builds successfully
  ✅ No runtime changes
  ✅ No public API changes
  ✅ No refactoring of packages

Files Changed

• STABILITY.md (new)
• COMPATIBILITY.md (new)
• docs/EXTENSION_MATURITY.md (new)
• docs/roadmap/go-community-friendly-iteration-plan.md (new)
• examples/README.md (new)
• examples/hello/main.go (new)
• examples/hello/go.mod (new)
• examples/hello/README.md (new)
• examples/json-api/main.go (new)
• examples/json-api/go.mod (new)
• examples/json-api/README.md (new)

Follow-up Recommendations

1. README.md refinement (v1.2.0): Emphasize stdlib-first positioning more prominently in opening section
2. Migration guides (v1.2.0): Finalize guides for migrating from Chi, Gin, Echo
3. Community engagement (v1.3.0): Announce in Go communities, gather feedback
4. Extension promotion (v2.0.0): Follow the promotion criteria in STABILITY.md to move beta extensions to GA

Test Plan

• All Go tests pass
• No vet warnings
• Examples compile and run
• Documentation is readable and accurate
• Links to existing docs are correct
• No API changes introduced

---

Generated by Claude Code