feature-control/docs/prompts/adopt-feature-control.md

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