# 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.)