generated from coulomb/repo-seed
76 lines
4.7 KiB
Markdown
76 lines
4.7 KiB
Markdown
# 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. |