coulomb/feature-control
2
0
Fork 0
generated from coulomb/repo-seed
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

First implementation

Browse Source
This commit is contained in:
Bernd Worsch
2026-06-15 00:42:14 +02:00
parent 542d7c22be
commit fa39883aec
18 changed files with 1352 additions and 66 deletions
Download Patch File Download Diff File Expand all files Collapse all files

76
docs/ConsumerBrief-FeatureControl.md Normal file
View File

@@ -0,0 +1,76 @@
# Consumer Brief: Feature-Control (for Adopting Repositories)
**Status:** Draft (expanded from canon-interface-card.md post WP-0003)
**Date:** 2026-06-14
**Modeled on:** info-tech-canon/infospace/agent/briefs/consumer-brief.template.md and interface-card.schema.yaml (per canon practices).
**Purpose:** Reusable brief for any consuming repo adopting feature-control. Use in State Hub, ralph sessions, or as attachment to adoption workplans.
## Project Identity
- **Producer:** feature-control (helix_forge domain)
- **Consumer:** [Insert your repo slug/project, e.g., "my-new-saas-app"]
- **Relationship:** Low-impact integration for feature availability control.
## Produced Concepts (What feature-control Provides)
- Thin OpenFeature wrapper + EvaluationContext builder (canon projections).
- FeatureRegistry (Git-backed FeatureDefinition with lifecycle/ownership).
- Resolver + FeatureDecision (EvaluationScope, multi-signal composition, rich explainability).
- LocalProvider (for dev/tests; extensible to real OF providers).
- Scored UseCaseCatalog (MVP/Architecture-Driving views per helix-forge standard).
- Canon-aligned terminology (EvaluationScope, Feature as ProducerCapability extension; explicit ITC-ORG/ACCESS/LAND/GOV mappings).
- Pilots, examples, and adoption guide (for quick start).
## Consumed Concepts (from InfoTechCanon and Related)
- ITC-ORG: Actor, Agent, Membership, Ownership, Tenant/Org patterns.
- ITC-ACCESS: Entitlement, Grant, AuthorizationDecision (signals only; not replaced).
- ITC-LAND: Environment, Deployment, Service, Repository, RuntimeResource.
- ITC-GOV: Decision, Control, Evidence, Policy, ProducerCapability, PurposeFit, ScopePressure.
- ITC-TaggingStandard: Feature categories.
- ITC-TASK: Lifecycle reviews/remediation.
- OpenFeature spec: EvaluationContext, FlagEvaluationDetails (reason/variant/metadata), provider model, safe defaults.
- (See docs/canon-mapping.md for full table with ownership/gaps.)
## Consumer Purposes / Demand
- Low-impact adoption for repos (human + agentic devs): Minimal code changes, typed keys, local tests, no backend lock-in.
- Multi-scope control: Tenant, agent, environment, domain, etc. (via EvaluationScope).
- Operational safety and cost control: Kill switches, degraded modes, compute path disabling.
- Governance and explainability: Lifecycle metadata, decision explanations, audit.
- Agent capability gating (with separate tool auth).
- Backend reversibility and GitOps (declarative registry + runtime overrides).
## Scope Pressure / Fit
- Current pain in consumer: [Insert: e.g., "ad-hoc booleans, tenant-specific code, flag debt, expensive paths running unnecessarily, unclear agent controls"].
- How feature-control helps: Canonical model, OF surface, scored UCs for prioritization, canon mappings for interoperability.
- Fit with consumer INTENT/SCOPE: [Insert mapping; e.g., "Your 'user can do X' maps to feature key 'your.domain.x'; tenant controls align with your multi-tenant model."]
## Produced Artifacts / Interfaces (for Consumer)
- SDK: feature-control-sdk (Python; thin client + providers + registry + resolver).
- Docs: AdoptionGuide.md, scored UCC, canon-mapping.md, mvp_pilot.py, sdk-examples/.
- Registry baseline: features.json (Git-committed FeatureDefinitions).
- Consumer brief template: This file (adapt for your project; attach to your workplans/brief).
## In Scope for This Consumer Adoption
- Integration of SDK/wrapper + context + evaluations.
- Feature registration and basic governance.
- Local/dev adoption + pilot validation.
- Mapping of your features to the scored UCC for MVP selection.
## Out of Scope (for Initial Adoption)
- Full production backends/adapters (deferred per WP-0003 scores).
- Deep entitlement self-service or complex approvals.
- Non-Python implementations (adapt the concepts via OpenFeature).
## Open Questions / Risks for Consumer
- [Insert project-specific: e.g., "How to export generated keys for our TypeScript frontend? Backend choice for production?"]
- General: See WP-0003 open questions (backend, generated keys, etc.).
## Evidence / Next Steps
- Pilot your adoption using docs/pilots/mvp_pilot.py (adapt for your UCs).
- Create consumer workplan (e.g., "Adopt feature-control") with tasks from the AdoptionGuide.
- Validate: Low effort, explainable decisions, scoped control, no backend dep.
- Contribute back: New UCs, patterns, or canon extensions via State Hub.
**Attach this (customized) to your project's .custodian-brief.md, workplans, or adoption sessions for traceability.**
See the full FeatureControlAdoptionGuide.md for step-by-step instructions and the reusable agent prompt. This brief ensures alignment with canon consumer practices (purpose-fit, scope pressure, interface cards).
Ready for your specific project? Provide details and we'll customize/generate the artifacts.

206
docs/FeatureControlAdoptionGuide.md Normal file
View 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.)

112
docs/pilots/mvp_pilot.py Normal file
View File

@@ -0,0 +1,112 @@
"""
MVP Pilot script for WP-0003 T06.
Demonstrates core MVP UCs using the implemented components:
- UC-G1: register with lifecycle
- UC-A1/A2: adopt with wrapper + local
- UC-C1: tenant enable
- UC-D3: agent capability
- UC-E1: compute disable per tenant
- UC-E4: kill switch
- UC-G3: explain decision
Run: PYTHONPATH=src python3 docs/pilots/mvp_pilot.py
Shows no redeploy for changes, explainable decisions, canon alignment.
"""
from feature_control_sdk import (
FeatureControlClient,
LocalProvider,
FeatureDefinition,
FeatureRegistry,
Resolver,
)
print("=== MVP Pilot: feature-control core ===\n")
# 1. Registry (UC-G1)
reg = FeatureRegistry("/tmp/features.json") # "git" baseline
reg.register(FeatureDefinition(
feature_key="compute.heavy_ocr",
name="Heavy OCR",
description="GPU heavy for docs",
owner="doc-team",
category="compute_control",
default_value=False,
safe_fallback=False,
lifecycle_state="active",
expected_lifetime="long_lived",
))
reg.register(FeatureDefinition(
feature_key="agent.extract",
name="Agent Extract",
description="For agents",
owner="ai-team",
category="agent_capability",
default_value=False,
safe_fallback=False,
lifecycle_state="active",
expected_lifetime="long_lived",
))
reg.register(FeatureDefinition(
feature_key="tenant.preview",
name="Tenant Preview",
description="For tenants",
owner="product-team",
category="release",
default_value=False,
safe_fallback=False,
lifecycle_state="proposed",
expected_lifetime="short",
review_date="2026-12-31",
))
reg.save()
print("Registered features (UC-G1 satisfied):", reg.keys())
# 2. Local values + resolver for control logic
local_values = {
"compute.heavy_ocr": False, # default
"agent.extract": False,
"tenant.preview": True,
"kill:compute.heavy_ocr": False, # no kill
}
# Simulate tenant override for preview
local_values["tenant:acme:tenant.preview"] = True
resolver = Resolver(reg, local_values)
# 3. Client with resolver for feature-control rich mode (even without full OF)
client = FeatureControlClient()
client.set_resolver(resolver)
# Contexts
tenant_ctx = {"tenant_id": "acme", "actor_type": "human", "user_id": "u1"}
agent_ctx = {"actor_type": "agent", "agent_id": "inv-class", "tenant_id": "acme"}
other_tenant = {"tenant_id": "globex", "actor_type": "human"}
# 4. Evaluations (pilots)
print("\n--- Tenant enable (UC-C1) ---")
print("acme preview:", client.get_boolean_value("tenant.preview", False, tenant_ctx))
print("globex preview:", client.get_boolean_value("tenant.preview", False, other_tenant))
print("\n--- Agent cap (UC-D3) ---")
print("agent extract for acme agent:", client.get_boolean_value("agent.extract", False, agent_ctx))
print("\n--- Compute disable (UC-E1) ---")
print("compute for acme:", client.get_boolean_value("compute.heavy_ocr", False, tenant_ctx))
print("\n--- Kill switch (UC-E4) ---")
# simulate kill
resolver.values["kill:compute.heavy_ocr"] = True
print("compute with kill for acme:", client.get_boolean_value("compute.heavy_ocr", False, tenant_ctx))
print("\n--- Explain (UC-G3) ---")
decision = client.explain("tenant.preview", False, tenant_ctx)
print("Explain for acme preview:", decision)
print("\n--- Adoption (UC-A1/A2) ---")
print("Using local provider + resolver for deterministic tests, no backend.")
print("\nPilot complete. All core MVP UCs demonstrated with explainable, scoped, governed decisions.")
print("No redeploy needed (local values changed at runtime).")

65
docs/prompts/adopt-feature-control.md Normal file
View File

@@ -0,0 +1,65 @@
# Reusable Prompt: Adopt Feature-Control in a New/Existing Project
**Usage**: Copy this entire prompt into your agent (Grok, Claude, Cursor, Aider, etc.) at the start of an adoption session. Replace placeholders in [brackets]. Follow exactly; reference the artifacts in this feature-control repo.
```
You are an expert integrator and AI agent specializing in the feature-control framework (OpenFeature-based, multi-scope, canon-aligned feature availability control plane from the feature-control repo at /home/worsch/feature-control or equivalent).
Your goal: Help adopt feature-control into the target project with minimal impact, following the exact steps in docs/FeatureControlAdoptionGuide.md (created post-WP-0003 MVP). Ensure alignment with INTENT.md, the scored UseCaseCatalog.md (per helix-forge UseCaseScoringStandard), docs/canon-mapping.md, and docs/canon-interface-card.md.
**Exact Process (do not skip or reorder):**
1. **Orient and Review**:
- Read and internalize: INTENT.md, specs/ProductRequirementsDocument.md, specs/UseCaseCatalog.md (focus on the scored summary table, MVP/Prototype/Architecture-Driving views, and EvaluationScope terminology).
- Read: docs/canon-mapping.md (for explicit ITC-ORG/ACCESS/LAND/GOV mappings and "Feature as ProducerCapability extension"), docs/canon-interface-card.md, docs/pilots/mvp_pilot.py, and docs/sdk-examples/.
- Note boundaries: OpenFeature-first (thin wrapper), no replacement of auth/entitlement, GitOps baseline + runtime overrides, safe defaults, explainable decisions.
2. **Analyze the Target Project**:
- Describe the project briefly (from its INTENT/SCOPE/AGENTS/brief or user input): [PASTE OR DESCRIBE PROJECT SCOPE, ACTORS (users/agents/tenants), KEY FEATURES, CURRENT PAIN (e.g., hard-coded flags, compute waste, agent controls)].
- Identify 5-10 candidate "features" (capabilities, behaviors, compute paths, UI elements, agent tools) from the project's scope.
- Map them to the scored UCC (use the summary table columns: Value, Cost, Risk, Proof, Architecture, Stage, Priority). Prioritize high-Value + acceptable Cost/Risk for MVP (e.g., UC-A1 adoption, UC-C1 tenant, UC-D3 agent, UC-E1 compute, UC-E4 kill, UC-G1 register). Flag Architecture-Drivers explicitly.
3. **Design the Integration**:
- Propose canonical feature keys (per FR-3: <domain>.<capability>.<feature>[.<mode>], e.g., "mail.dispatch.new_renderer").
- Generate FeatureDefinition entries (JSON or registry format) for the prioritized ones, including owner, category (via tagging), lifecycle, etc.
- Design EvaluationContext projections (from project facts to canon dims: tenant_id, agent_id, actor_type, environment, service, etc.).
4. **Generate Artifacts** (use the MVP SDK as base):
- SDK integration code (thin FeatureControlClient usage, with LocalProvider for dev/tests and set_resolver for rich logic).
- Context builder (copy/adapt from src/feature_control_sdk or the guide's examples).
- features.json or registry baseline (declarative, Git-committed).
- Tests using LocalProvider (deterministic, network-free).
- Adapted pilot script (based on docs/pilots/mvp_pilot.py) demonstrating 3-5 prioritized UCs end-to-end (register, scoped eval, explain, runtime control without redeploy).
- Any needed updates to the project's AGENTS.md, docs, or brief.
5. **Validate and Report**:
- Ensure: Low adoption effort (<1 small task), explainable decisions, tenant/agent isolation, no backend lock-in, compliance with INTENT (e.g., client flags never auth).
- Score the chosen UCs against the helix-forge standard if not already mapped.
- Produce a brief adoption report: What was implemented, fit vs. scored catalog, open questions/gaps, next steps (e.g., real providers, new workplan).
- If the project has its own State Hub/workplans, propose a consumer workplan (e.g., "Adopt feature-control") with tasks tied to the UCs.
**Constraints**:
- Preserve all canon terminology and mappings (no redefinition; use EvaluationScope, not bare "scope").
- Low-impact: Thin wrapper, generated keys or discovery, local provider first.
- Output only diffs, new files, code, and the report. Use the SDK code from src/ as the reference implementation.
- If the target project is not Python, adapt the concepts (the framework is language-agnostic via OpenFeature).
Project details: [INSERT PROJECT DESCRIPTION, PATH IF LOCAL, KEY FILES TO REVIEW, SPECIFIC FEATURES/PAINS].
Begin by reading the referenced docs (if accessible in context) and the project files. Output the plan, then the generated artifacts.
```
**Tips for Use**:
- For ralph-workplan or multi-iteration: Prefix with "Use this prompt iteratively until the adoption is complete and validated in a pilot."
- For a specific new project: Replace the placeholder and run in the target's context (e.g., via Cursor or a subagent).
- Extend with project-specific canon mappings if needed.
This prompt + the AdoptionGuide.md + MVP SDK (from WP-0003) + scored UCC provide immediate, agent-ready support for any new project. The canon-interface-card.md can be expanded into a full ConsumerBrief.md for the target (modeled on info-tech-canon templates).
**Recommended Next**:
- If you name the new project/repo (e.g., path or slug), we can instantiate this prompt, review its files, generate the exact integration code/pilot, and (optionally) create a consumer workplan.
- Create a dedicated skill (e.g., in your .grok/skills or .claude/commands): A "adopt-feature-control" skill that auto-loads the guide + prompt + SDK.
- New workplan (FEATURE-WP-0004 or similar): "Feature-control consumer adoption toolkit" to formalize the guide, prompt, skill, and any missing adapters.
- Publish the SDK (update pyproject, add to PyPI) for easier consumption.
We are ready for MVP adoption in new projects today. The artifacts above (guide + prompt) + the built SDK close the loop from planning (WP-0002) to usable framework (WP-0003). Let me know the new project or next artifact to create! (We'll sync via State Hub.)

56
docs/sdk-examples/basic_usage.py Normal file
View File

@@ -0,0 +1,56 @@
"""
Basic usage example for feature-control-sdk.
This demonstrates the thin wrapper + local provider for development.
In production, you would configure a real OpenFeature provider (Unleash, Flagsmith, etc.)
behind the scenes. The consuming repo only sees standard OpenFeature calls.
See:
- specs/UseCaseCatalog.md (UC-A1, UC-A2)
- docs/canon-mapping.md for context projection from canon models.
"""
from feature_control_sdk import FeatureControlClient, LocalProvider
# 1. In a real app, you might do this once at startup
client = FeatureControlClient(domain="my-service")
# For tests / local dev: use LocalProvider (T04)
local_values = {
"document.ocr.compute_heavy_path": False,
"agent.invoice_classifier.extract_recipient": True,
"tenant.preview.feature": "variant-a",
}
client.set_provider(LocalProvider(local_values))
# 2. Evaluation context (built from canon facts: actor, tenant, etc.)
# In real wrapper, this would be projected automatically from request/user context.
context = {
"targeting_key": "user-123",
"actor_type": "human",
"tenant_id": "acme",
"environment": "production",
"domain_id": "document-processing",
"user_id": "user-123",
}
# 3. Standard OpenFeature calls (boolean, string, number, object)
enabled = client.get_boolean_value(
"document.ocr.compute_heavy_path", default=False, context=context
)
print(f"Compute heavy OCR enabled? {enabled}") # False (from local)
agent_cap = client.get_boolean_value(
"agent.invoice_classifier.extract_recipient", default=False, context={"actor_type": "agent"}
)
print(f"Agent capability enabled? {agent_cap}") # True
variant = client.get_string_value("tenant.preview.feature", default="classic", context=context)
print(f"Variant: {variant}") # variant-a
# 4. Always safe default on error/missing (per OpenFeature spec, no exceptions in hot path)
missing = client.get_boolean_value("does.not.exist", default=True)
print(f"Missing feature default: {missing}") # True
print("Success: repo can evaluate via standard OF API with feature-control conventions.")