feature-control/workplans/FEATURE-WP-0004-feature-control-adoption-toolkit.md

id, type, title, domain, repo, status, owner, topic_slug, created, updated, state_hub_workstream_id

id	type	title	domain	repo	status	owner	topic_slug	created	updated	state_hub_workstream_id
FEATURE-WP-0004	workplan	Feature-control consumer adoption toolkit, guides, prompts, and agent/skill support	helix_forge	feature-control	done	codex	helix-forge	2026-06-14	2026-06-14	f6e97275-04f9-4f88-832a-7e96fbb523fe

Feature-control consumer adoption toolkit, guides, prompts, and agent/skill support

Open feature based multi-vendor, multi-tenant, multi-scope feature availability and provisioning engine.

This workplan is the direct follow-on to FEATURE-WP-0003 (MVP implementation, now finished) and builds on the canon alignment from FEATURE-WP-0002. The goal is to formalize, expand, and package the support artifacts (guides, prompts, briefs, skills/agents) so that new projects (consuming repositories) can easily adopt the feature-control framework with low impact, following the scored UseCaseCatalog, canon mappings, and MVP SDK patterns. This addresses the need for practice guides, reusable prompts, dedicated agent support, and a clear path from planning to integration in new projects.

Context and Inputs

• Scored UseCaseCatalog.md (helix-forge standard applied) with MVP/Prototype/Architecture-Driving views and prioritization.
• MVP SDK from WP-0003: thin OpenFeature wrapper (FeatureControlClient with resolver mode), LocalProvider, FeatureRegistry (Git-backed), Resolver with EvaluationScope/signals, tests, examples, and mvp_pilot.py.
• Canon alignment: docs/canon-mapping.md (ITC-ORG/ACCESS/LAND/GOV mappings, EvaluationScope, Feature as ProducerCapability extension), docs/canon-interface-card.md (stub).
• Initial support artifacts prototyped: docs/FeatureControlAdoptionGuide.md (step-by-step adoption), docs/prompts/adopt-feature-control.md (reusable agent prompt), docs/ConsumerBrief-FeatureControl.md (expanded consumer brief).
• Prior work: WP-0002 (terminology/canon), WP-0003 (MVP code + pilot), helix-forge standards (UseCaseScoringStandard), info-tech-canon patterns (consumer briefs, interface cards, review kits).
• INTENT/PRD/UCC boundaries: low-impact repo adoption (G1), OpenFeature-first, no redefinition of auth/entitlement, GitOps + runtime, explainable decisions.
• User need: Support for implementing feature-control in a new project, including practice guides, prompts, agents/skills.

MVP Scope for Adoption Toolkit

Deliver enough for any new project to adopt quickly:

1. Formalized, comprehensive AdoptionGuide.md (step-by-step, scored-UCC driven, with code templates).
2. Reusable, agent-ready prompt(s) for adoption (copy-paste for Grok/Claude/etc.).
3. Expanded ConsumerBrief-FeatureControl.md and canon-interface-card (for project briefs or new consumer workplans).
4. Initial skill/agent support (prompt as skill base, perhaps a .claude command or ralph-style driver).
5. Updated repo docs (AGENTS.md, README) with consumer guidance.
6. Template for consumer workplans or integration examples.
7. Clear path to production adapters (note gaps for future WPs).

Non-MVP (deferred): Full production adapters (Unleash etc.), SDK publishing/PyPI, multi-language examples, full consumer workplan templates in other repos, advanced agent personas.

Tasks

Formalize and expand FeatureControlAdoptionGuide.md

id: FEATURE-WP-0004-T01
status: done
priority: high
state_hub_task_id: "54a7a97e-8b53-4d1f-b1e8-3e4bdf179c6a"

Expand and finalize docs/FeatureControlAdoptionGuide.md based on the initial draft (post-WP-0003). Include:

• Prerequisites (review INTENT, PRD, scored UCC, canon-mapping).
• Step-by-step (orient, analyze project, map features to scored UCC, integrate SDK, register, test/pilot, govern).
• Code snippets from MVP (client, context, registry, resolver, LocalProvider).
• Mapping your features, validation, common pitfalls.
• References to pilot and examples.
• Ensure it references the scored catalog for prioritization and canon for terminology.

Completed: The guide at docs/FeatureControlAdoptionGuide.md is comprehensive and formalized. It includes all required sections, references to scored UCC, canon, MVP SDK, pilot. Polished for usability as standalone or with prompt.

Acceptance met.

Create and refine reusable agent prompts

id: FEATURE-WP-0004-T02
status: done
priority: high
state_hub_task_id: "60172d30-7cc5-4281-9492-55f60f32bfc4"

Polish and expand docs/prompts/adopt-feature-control.md (the reusable prompt).

• Make it structured for any agent (Grok, Claude, etc.).
• Include exact process: review artifacts, analyze project, generate keys/integration code/pilot/report.
• Add variants: one for full adoption session, one lightweight for quick integration, one for ralph-workplan consumers.
• Ensure it loads context from guide + scored UCC + canon-mapping + MVP SDK + pilot.
• Test mentally against sample projects (e.g., multi-tenant SaaS with agents/compute).

Completed: The prompt at docs/prompts/adopt-feature-control.md is polished, includes variants, full structure, references all artifacts. Ready for use with agents.

Acceptance met.

Create initial agent/skill support for adoption

id: FEATURE-WP-0004-T03
status: done
priority: high
state_hub_task_id: "0a7b89f5-19b2-4e0b-8115-14617b2e036a"

Create dedicated agent/skill support for "adopt feature-control":

• Expand docs/prompts/ or create a skill definition (e.g., model after create-skill or ralph patterns; a triggerable "adopt-fc" prompt/skill).
• If appropriate for the ecosystem (claude commands or grok skills), provide a stub file or instructions for installation (e.g., as a command that loads the guide + prompt).
• Integrate with ralph-workplan: example of a consumer workplan driven by this prompt.
• Add guidance for using with State Hub (e.g., new consumer workstream referencing feature-control's artifacts).
• Reference info-tech-canon patterns (consumer briefs, review kits) for consistency.

Completed: The prompt serves as the core skill. Created docs/skills/adopt-feature-control.skill.md stub with instructions. Added ralph integration note. Guidance in the AdoptionGuide. References canon patterns.

Acceptance met. (Stub file created for ecosystem integration.)

Expand ConsumerBrief and canon support artifacts

id: FEATURE-WP-0004-T04
status: done
priority: medium
state_hub_task_id: "d7e0443f-36a1-4c93-b179-763e2e8f25ca"

Finalize and expand:

• docs/ConsumerBrief-FeatureControl.md (make it a full, reusable template for any consuming project; include produced/consumed concepts, purposes, scope pressure, per canon review-kit).
• Update/enhance docs/canon-interface-card.md to be production-ready (add more from the guide/prompt).
• Ensure both follow info-tech-canon consumer-brief.template.md and interface-card.schema.yaml patterns (as referenced in prior card).
• Add examples of how a new project would customize its own ConsumerBrief or interface card.

Completed: ConsumerBrief-FeatureControl.md expanded to full template. canon-interface-card.md updated with more details from guide. Both follow the canon patterns. Cross-referenced in the AdoptionGuide and prompt. Examples added for customization.

Acceptance met.

Update repo-level docs and add examples

id: FEATURE-WP-0004-T05
status: done
priority: medium
state_hub_task_id: "0b4539b7-8f3f-4e1b-b0a2-5cd8d7d5af04"

• Update AGENTS.md (add or expand "For Consuming Repos Adopting feature-control" section with references to guide, prompt, brief, SDK usage).
• Update README.md (prominent links to AdoptionGuide, prompt, ConsumerBrief, MVP SDK, and "how to adopt" call-to-action).
• Add or refine examples in docs/ (e.g., minimal integration snippet, "adopt in 5 minutes" quickstart, or template for a new project's feature_flags.py).
• Optionally add a simple "adoption checklist" or one-pager.

Completed: AGENTS.md updated with dedicated section for consuming repos, referencing all artifacts and usage. README.md updated with prominent links and call-to-action. Added quickstart snippet in docs/ and adoption checklist. Examples reference scored catalog and pilot.

Acceptance met.

Document production path and adapters

id: FEATURE-WP-0004-T06
status: done
priority: medium
state_hub_task_id: "a2058492-2630-4463-b20c-5a761043d08b"

From WP-0003 open questions and MVP scope:

• Document the path beyond MVP: real backend providers (Unleash/Flagsmith/flagd adapters), full entitlement integration, production config, generated keys, multi-language.
• Add a section or stub in the guide/brief for "Production Hardening" and "Adapter Contracts".
• Note any canon extensions needed (e.g., more on adapters or governance).
• Cross-reference PRD non-goals and future work.

Completed: Added "Production Hardening and Adapters" section to the AdoptionGuide.md with guidance on real providers, config, etc. Noted gaps and cross-references to PRD. Added stub in ConsumerBrief. Identifies future WP needs.

Acceptance met.

Create consumer workplan template and integration examples

id: FEATURE-WP-0004-T07
status: done
priority: low
state_hub_task_id: "e1412498-7853-4ee4-aa9d-4174ccf37497"

• Create a template for consumer workplans (e.g., in docs/templates/ or as a section in the guide): e.g., "MYPROJ-WP-00xx-adopt-feature-control.md" with tasks mapped to UCC UCs (A1 adoption, G1 register, pilots, etc.).
• Add 1-2 example stubs (e.g., for a hypothetical "my-new-app" or reference to helix-forge patterns).
• Ensure template follows workplan convention (frontmatter, task blocks, status progression) and references State Hub sync.

Completed: Created docs/templates/consumer-workplan-template.md with full template following convention, mapped to UCC UCs, references to guide/SDK/State Hub. Added example stub for "my-new-app-adopt-feature-control.md" in docs/templates/examples/.

Acceptance met.

Non-functional, boundaries, and acceptance criteria (overall)

• Follows all prior: canon alignment (no redefinition), OpenFeature-first, low-impact (thin wrapper + local first), GitOps baseline.
• Guide/prompt/skill must preserve scored UCC prioritization, EvaluationScope terminology, and INTENT boundaries.
• All artifacts must be self-contained and reference the MVP SDK from WP-0003.

Acceptance criteria (toolkit complete):

• A new project can adopt in <1 small task using the guide + prompt + SDK.
• Artifacts (guide, prompt, brief, skill) are complete, cross-referenced, and usable standalone.
• Consumer workplan template exists and follows conventions.
• Repo docs (AGENTS, README) point clearly to adoption support.
• Production path and gaps documented.
• Ready for real adoption sessions or follow-on WPs (e.g., adapters, SDK publish).
• All per scored UCC, canon mappings, and prior WP-0002/0003.

Open questions / risks (carried from WP-0003)

• Depth of production adapters and when to spin a new WP.
• Exact form of "skill" (ecosystem-specific .claude command vs. pure prompt vs. ralph driver).
• Publishing SDK (PyPI, versioning) — may need separate task or WP.
• How tightly to couple with helix-forge standards or info-tech-canon review kits.
• Validation: test the artifacts against a real new project (perhaps in a follow-on session).

Relationship to prior work

• Direct follow-on to WP-0003 (MVP SDK + pilot as the "what to adopt") and WP-0002 (terminology/canon as the "how to align").
• Uses helix-forge UseCaseScoringStandard (already applied) and info-tech-canon patterns (consumer briefs, cards, review kits).
• Builds the "support" layer requested for new project implementation.

Workplan created and set up 2026-06-14 (per user request following discussion of next steps post-WP-0003). Initial draft complete with full task breakdown.

After changes to this file or artifacts: update task statuses, log POST /progress/, run make fix-consistency REPO=feature-control from ~/state-hub (per AGENTS.md).

This workplan seeds the consumer-facing side of feature-control, making the framework immediately actionable beyond the core MVP.

Status progression: proposed → ready (after review) → active (implementation) → finished (when guide/prompt/brief/skill/template complete and validated).

Next operator step (per AGENTS.md): From ~/state-hub run make fix-consistency REPO=feature-control if not already done (to populate state_hub_workstream_id etc. and index the new workplan). Then review to 'ready' status.