From 542d7c22be8911c9ae846de5c0a2158e30ac8d53 Mon Sep 17 00:00:00 2001 From: tegwick Date: Sun, 14 Jun 2026 22:22:13 +0200 Subject: [PATCH] feat: set up new workplan FEATURE-WP-0004-feature-control-adoption-toolkit for consumer adoption support, guides, prompts, and agent/skill - Builds on completed WP-0002 (canon alignment) and WP-0003 (MVP implementation). - Tasks to formalize AdoptionGuide, reusable prompts, ConsumerBrief, initial skill/agent, repo docs updates, production path, and consumer workplan template. - Follows exact AGENTS.md / ADR-001 conventions (frontmatter, task blocks, references to prior, protocol notes). - Created per user request for next step in using feature-control for new projects. All per session protocol. --- ...P-0004-feature-control-adoption-toolkit.md | 217 ++++++++++++++++++ 1 file changed, 217 insertions(+) create mode 100644 workplans/FEATURE-WP-0004-feature-control-adoption-toolkit.md diff --git a/workplans/FEATURE-WP-0004-feature-control-adoption-toolkit.md b/workplans/FEATURE-WP-0004-feature-control-adoption-toolkit.md new file mode 100644 index 0000000..ed6bbac --- /dev/null +++ b/workplans/FEATURE-WP-0004-feature-control-adoption-toolkit.md @@ -0,0 +1,217 @@ +--- +id: FEATURE-WP-0004 +type: workplan +title: "Feature-control consumer adoption toolkit, guides, prompts, and agent/skill support" +domain: helix_forge +repo: feature-control +status: proposed +owner: codex +topic_slug: helix-forge +created: "2026-06-14" +updated: "2026-06-14" +state_hub_workstream_id: "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 + +```task +id: FEATURE-WP-0004-T01 +status: todo +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. + +Acceptance: +- Guide is comprehensive, self-contained, and usable standalone or with the prompt. +- Covers MVP UCs (A1/A2 adoption, C1 tenant, D3 agent, E1/E4 control, G1/G3 governance). +- Includes next steps for production. + +## Create and refine reusable agent prompts + +```task +id: FEATURE-WP-0004-T02 +status: todo +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). + +Acceptance: +- Prompt(s) are copy-paste ready and produce consistent, high-quality adoption output. +- References all key artifacts (guide, UCC scores, SDK, canon). +- Can drive a full session or sub-tasks. + +## Create initial agent/skill support for adoption + +```task +id: FEATURE-WP-0004-T03 +status: todo +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. + +Acceptance: +- Skill/prompt is documented and immediately usable as an "agent" for adoption. +- Includes example invocation and expected outputs (code, diffs, report, workplan tasks). +- Ties back to scored UCC and MVP for concrete results. + +## Expand ConsumerBrief and canon support artifacts + +```task +id: FEATURE-WP-0004-T04 +status: todo +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. + +Acceptance: +- Brief and card are complete, modeled correctly on canon, and usable for project briefs or new consumer workplans. +- Cross-referenced from the AdoptionGuide and prompt. + +## Update repo-level docs and add examples + +```task +id: FEATURE-WP-0004-T05 +status: todo +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. + +Acceptance: +- Repo docs (AGENTS, README) make adoption obvious for newcomers/agents. +- Examples are practical and reference the scored catalog/pilot. + +## Document production path and adapters + +```task +id: FEATURE-WP-0004-T06 +status: todo +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. + +Acceptance: +- Clear, realistic guidance on moving from MVP adoption to production. +- Identifies gaps for follow-on work (e.g., new WP for adapters). + +## Create consumer workplan template and integration examples + +```task +id: FEATURE-WP-0004-T07 +status: todo +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. + +Acceptance: +- Template is ready for copy-paste into new projects. +- Examples show how to tie adoption to the scored catalog and MVP SDK. + +## 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.