feature-control/docs/ConsumerBrief-FeatureControl.md

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.