generated from coulomb/repo-seed
First implementation
This commit is contained in:
206
docs/FeatureControlAdoptionGuide.md
Normal file
206
docs/FeatureControlAdoptionGuide.md
Normal file
@@ -0,0 +1,206 @@
|
||||
# Feature-Control Adoption Guide for Consuming Repositories
|
||||
|
||||
**Status:** Draft (post WP-0003 MVP)
|
||||
**Date:** 2026-06-14
|
||||
**Audience:** Developers, architects, and AI agents integrating feature-control into new or existing projects (consuming repos).
|
||||
**Based on:** FEATURE-WP-0003 MVP implementation, scored UseCaseCatalog.md, canon-mapping.md, canon-interface-card.md (modeled on info-tech-canon consumer briefs), pilot examples, PRD/INTENT boundaries.
|
||||
|
||||
This guide provides a practical, step-by-step process for adopting the feature-control framework. It ensures low-impact integration, canon alignment (EvaluationScope, ITC-ORG/ACCESS/LAND/GOV mappings), and use of the scored use cases for prioritization.
|
||||
|
||||
## 1. Prerequisites and Orientation
|
||||
Before starting:
|
||||
- Read the core docs in this repo (or the feature-control package):
|
||||
- [INTENT.md](../INTENT.md): Stable intent, boundaries (OpenFeature-first, no auth/entitlement ownership, GitOps + runtime).
|
||||
- [specs/ProductRequirementsDocument.md](../specs/ProductRequirementsDocument.md): Requirements, data models, architecture.
|
||||
- [specs/UseCaseCatalog.md](../specs/UseCaseCatalog.md): Full catalog **with scoring applied per helix-forge UseCaseScoringStandard.md**. Use the summary table, MVP/Prototype/Architecture-Driving views to prioritize (e.g., high Value + low-moderate Cost for early adoption).
|
||||
- [docs/canon-mapping.md](../docs/canon-mapping.md): Explicit mappings (e.g., Feature → ProducerCapability extension; EvaluationScope → ITC-ORG Membership + ITC-LAND dims). Avoid redefining canon terms.
|
||||
- [docs/canon-interface-card.md](../docs/canon-interface-card.md): High-level consumer view (produced concepts, consumed ITC models, purposes, scope pressure).
|
||||
- [docs/pilots/mvp_pilot.py](../docs/pilots/mvp_pilot.py) and [docs/sdk-examples/](../docs/sdk-examples/): Concrete usage examples.
|
||||
- Understand key canon-aligned concepts:
|
||||
- **EvaluationScope / TargetingScope**: Replaces bare "scope" (platform, tenant, agent, etc.). Maps to Memberships + Landscape resources.
|
||||
- **FeatureDecision**: Rich (value, reason, source, scope, etc.) for explainability.
|
||||
- **Context**: Projection from ITC-ORG (actors/agents), ITC-LAND (services/envs), ITC-ACCESS signals.
|
||||
- Check your project's alignment with INTENT boundaries (mechanism over policy; overlay before mutation; capability-aware adapters).
|
||||
|
||||
**Read the brief for the target project** (`.custodian-brief.md`) and its AGENTS.md/INTENT.md to map your features to the scored UCC.
|
||||
|
||||
## 2. High-Level Adoption Flow (Based on Scored UCC)
|
||||
Follow the recommended workflow from the helix-forge standard (capture → normalize → classify → score → select → implement). Prioritize from the UCC summary:
|
||||
|
||||
**MVP Candidates (strong for first integration, per scoring):**
|
||||
- UC-A1: Adopt in new repo (core path; high user/business/strategic/proof value).
|
||||
- UC-A2: Local/test provider (high proof/learning; low effort).
|
||||
- UC-C1: Enable for tenant (multi-tenant control).
|
||||
- UC-D3: AI agent capability (agent-first class).
|
||||
- UC-E1: Disable compute-heavy per tenant (cost governance).
|
||||
- UC-E4: Emergency kill switch (operational safety).
|
||||
- UC-G1: Register with lifecycle (governance/hygiene).
|
||||
|
||||
**Supporting/Prototype:**
|
||||
- UC-G3: Explain decision (explainability core).
|
||||
- UC-H1: Provider switch (reversibility).
|
||||
|
||||
**Later/Enhancement:** Complex self-service, full analytics (lower urgency or higher cost per scores).
|
||||
|
||||
**Architecture Drivers (implement early for understanding, even if deferred):** Those with high Architecture Score (cross-repo, canon impact, policy, reuse, compute, observability) — e.g., A1, E1, D3, G1.
|
||||
|
||||
## 3. Step-by-Step Integration (Low-Impact, per UC-A1/A2)
|
||||
1. **Add the SDK**:
|
||||
- For Python projects: Add `feature-control-sdk` as a dependency (current: local via `pip install -e` from this repo's pyproject.toml; future: PyPI).
|
||||
- Minimal: Copy `src/feature_control_sdk/` into your project initially.
|
||||
- Optional: `openfeature-sdk` for real providers (backend-agnostic per design).
|
||||
|
||||
2. **Initialize the Client** (thin wrapper):
|
||||
```python
|
||||
from feature_control_sdk import FeatureControlClient, LocalProvider, FeatureRegistry, Resolver
|
||||
|
||||
client = FeatureControlClient(domain="your-service") # Optional OF domain
|
||||
```
|
||||
|
||||
3. **Set up for Dev/Tests (LocalProvider, no backend)**:
|
||||
```python
|
||||
local_values = {
|
||||
"your.domain.capability.feature": True, # Use canonical keys
|
||||
# Simulate overrides/signals
|
||||
"tenant:acme:your.feature": False,
|
||||
"kill:your.feature": False,
|
||||
}
|
||||
client.set_provider(LocalProvider(local_values))
|
||||
|
||||
# For rich feature-control logic (MVP mode, no full OF needed):
|
||||
reg = FeatureRegistry("features.json") # Git-committed baseline
|
||||
# (Populate from registry or hardcode for pilot)
|
||||
resolver = Resolver(reg, local_values)
|
||||
client.set_resolver(resolver)
|
||||
```
|
||||
|
||||
4. **Build Evaluation Context** (canon-aligned):
|
||||
Use the `_build_context` logic or manual dict. Project from your system's facts (users, tenants, agents, services):
|
||||
```python
|
||||
context = {
|
||||
"targeting_key": "user-123", # Per OF spec
|
||||
"actor_type": "human", # or "agent"
|
||||
"tenant_id": "acme",
|
||||
"domain_id": "your-domain",
|
||||
"agent_id": "my-agent-v1" if agent else None,
|
||||
"environment": "production",
|
||||
"service": "your-service",
|
||||
"roles": ["user"],
|
||||
"plan": "premium",
|
||||
# Signals
|
||||
"entitlement": True, # From your entitlement system (ITC-ACCESS)
|
||||
}
|
||||
```
|
||||
|
||||
5. **Evaluate Features** (standard OF surface + rich control):
|
||||
```python
|
||||
enabled = client.get_boolean_value(
|
||||
"your.domain.capability.feature", # Canonical key (from registry)
|
||||
default=False,
|
||||
context=context
|
||||
)
|
||||
# For rich explain (UC-G3):
|
||||
decision = client.explain("your.domain.capability.feature", False, context)
|
||||
print(decision.reason, decision.scope) # e.g., "tenant_policy", "tenant:acme"
|
||||
```
|
||||
|
||||
6. **Register Features (Governance, per UC-G1)**:
|
||||
- Maintain a `features.json` (or registry export) in Git as declarative baseline.
|
||||
- Example definition (matches PRD/UCC):
|
||||
```json
|
||||
{
|
||||
"feature_key": "your.domain.capability.feature",
|
||||
"name": "Your Capability",
|
||||
"description": "...",
|
||||
"owner": "your-team", # ITC-ORG
|
||||
"category": "release", # ITC-Tagging
|
||||
"default_value": false,
|
||||
"safe_fallback": false,
|
||||
"lifecycle_state": "active",
|
||||
"expected_lifetime": "long_lived",
|
||||
"tenant_configurable": true,
|
||||
"documentation": "docs/features/..."
|
||||
}
|
||||
```
|
||||
- Use `FeatureRegistry` to load/validate/register (enforces owner, temp review dates).
|
||||
- In consuming code: Import or discover keys (stub scanner for UC-A3).
|
||||
|
||||
7. **Test and Adopt**:
|
||||
- Use LocalProvider for unit/integration tests (deterministic, network-free; UC-A2).
|
||||
- Pilot your features using `docs/pilots/mvp_pilot.py` as template (adapt for your UCs).
|
||||
- Measure: Adoption effort (should be <1 small task), explainability, control without redeploys.
|
||||
- For real providers: Configure OF provider (e.g., Unleash adapter) behind the client (H1 support).
|
||||
|
||||
8. **Governance and Advanced**:
|
||||
- Enforce lifecycle in your registry (temp features get Tasks per ITC-TASK).
|
||||
- Use `explain()` for support/debug (UC-G3).
|
||||
- Audit changes (stub in pilot; expand per G4).
|
||||
- For agents: Pass `actor_type: "agent"` + `agent_id` in context (D3 support; still enforce tool auth per boundaries).
|
||||
|
||||
## 4. Mapping Your Project's Features
|
||||
- Review your project's INTENT/SCOPE/UCC (or equivalent).
|
||||
- Map to feature-control UCC: E.g., "user can do X" → feature key like `your.domain.x` (per FR-3 naming).
|
||||
- Score/prioritize using the standard (or copy from our scored UCC).
|
||||
- Start with high-MVP-fit: Adoption + 2-3 core controls (tenant/agent/compute/kill).
|
||||
- Register in your Git baseline; control via context (tenant_id for multi-tenant, agent_id for AI).
|
||||
|
||||
## 5. Common Pitfalls and Boundaries (from INTENT/PRD)
|
||||
- **Do not** use features for auth (FR-8): Always pair with your authz system.
|
||||
- **Do not** confuse with entitlement: Feature control composes but doesn't own (UC-F1).
|
||||
- Client-side never enforces security.
|
||||
- Start with local provider; add real backends later (backend-agnostic).
|
||||
- Commit `features.json`/registry to Git for GitOps baseline.
|
||||
|
||||
## 6. Validation and Next Steps
|
||||
- Run the adapted pilot: End-to-end for your MVP UCs.
|
||||
- Check: Decisions explainable? Controls per scope (no cross-tenant)? Tests without backend?
|
||||
- Metrics: Adoption time, decision coverage, compute savings.
|
||||
- If it fits: Proceed to production hardening (e.g., real providers, full audit, adapter contracts).
|
||||
- Report back: Update your project's docs/brief with adoption status. Consider contributing patterns back (e.g., new UCs or canon extensions).
|
||||
|
||||
## 7. Agent/AI Support Prompts and Skills
|
||||
**Reusable Prompt Template** (for Grok, Claude, Cursor, etc.; copy-paste into your agent):
|
||||
```
|
||||
You are an expert at adopting the feature-control framework (OpenFeature-based, canon-aligned multi-scope feature availability control from the feature-control repo).
|
||||
|
||||
Follow this exact step-by-step guide from docs/FeatureControlAdoptionGuide.md:
|
||||
[PASTE THE FULL GUIDE ABOVE]
|
||||
|
||||
For the current project (describe briefly: [e.g., "a new multi-tenant SaaS app in Python with user/engine/agent actors, compute-heavy features, need for tenant/agent controls"]):
|
||||
|
||||
1. Identify 5-10 candidate features from the project's scope/intent.
|
||||
2. Map them to the scored UseCaseCatalog.md (prioritize MVP/Architecture-Driving).
|
||||
3. Propose canonical feature keys (per naming convention).
|
||||
4. Generate the integration code: client setup, context builder (using canon projections), evaluations, registry definitions (in JSON), tests with LocalProvider.
|
||||
5. Create a simple pilot script adapted from mvp_pilot.py.
|
||||
6. Note any canon gaps or custom UCs.
|
||||
7. Ensure compliance with INTENT boundaries.
|
||||
|
||||
Output: Updated code diffs, new files (e.g., feature_flags.py, features.json, tests), and a brief adoption report referencing the scoring and canon-mapping.
|
||||
```
|
||||
|
||||
**Dedicated Skill/Agent Recommendation**:
|
||||
- **Yes, create one**: A "feature-control-adopter" skill or ralph-style prompt.
|
||||
- Example skill file (add to your agent's skills dir or `docs/skills/adopt-feature-control.md`):
|
||||
- Trigger: "adopt feature-control in this project" or "/adopt-fc".
|
||||
- Behavior: Load this guide + canon-mapping + scored UCC + pilot as context. Walk user/agent through steps, generate code, validate against acceptance.
|
||||
- For ralph-workplan users: Tie a consumer workplan (e.g., "Adopt feature-control") to this prompt.
|
||||
- Enhancement: Integrate with State Hub (e.g., new workplan for consumer adoption in a target repo, using get_domain_summary for context).
|
||||
- This repo can host the canonical version; consumers copy/adapt.
|
||||
|
||||
## 8. Gaps and Future Support (from WP-0003 Open Questions)
|
||||
- Full backend providers (Unleash/Flagsmith adapters) and production config.
|
||||
- Generated constants/key discovery (beyond stub).
|
||||
- Deeper entitlement integration and tenant self-service.
|
||||
- Full adapter contracts (for non-Python or custom backends).
|
||||
- Publishing the SDK (PyPI, versioning).
|
||||
- More pilots/examples for other languages/UCS.
|
||||
|
||||
**Next Step Recommendation**:
|
||||
- If you have a specific new project/repo in mind (e.g., "my-new-app"), tell me the path or details — we can run a guided adoption session using the prompt above, generate the exact files, and create a consumer workplan (e.g., MYAPP-WP-0001-adopt-feature-control).
|
||||
- Create a new workplan here (FEATURE-WP-0004-feature-control-adoption-toolkit) to formalize the guide, skill, and consumer brief.
|
||||
- Expand the canon-interface-card.md into a full ConsumerBrief.md (per info-tech-canon templates).
|
||||
|
||||
This makes feature-control immediately usable for new projects while providing the requested guides/prompts/skills. The MVP gives a working foundation; we can iterate based on real adoption feedback.
|
||||
|
||||
Ready to proceed with a specific project or create the new artifacts? Provide details! (We'll log progress and sync via State Hub.)
|
||||
Reference in New Issue
Block a user