feature-control/docs/FeatureControlAdoptionGuide.md

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: Stable intent, boundaries (OpenFeature-first, no auth/entitlement ownership, GitOps + runtime).
  • specs/ProductRequirementsDocument.md: Requirements, data models, architecture.
  • 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: Explicit mappings (e.g., Feature → ProducerCapability extension; EvaluationScope → ITC-ORG Membership + ITC-LAND dims). Avoid redefining canon terms.
  • docs/canon-interface-card.md: High-level consumer view (produced concepts, consumed ITC models, purposes, scope pressure).
  • docs/pilots/mvp_pilot.py and 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):

   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):

   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):

   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):

   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):

     {
       "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.)