generated from coulomb/repo-seed
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.
This commit is contained in:
217
workplans/FEATURE-WP-0004-feature-control-adoption-toolkit.md
Normal file
217
workplans/FEATURE-WP-0004-feature-control-adoption-toolkit.md
Normal file
@@ -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.
|
||||
Reference in New Issue
Block a user