FeatureFlow (CDE Companion)
A VS Code extension that tracks which stage each feature is in under Context Driven Engineering (CDE). Stages are derived from file existence and markdown content checkpoints — never from git ahead/merge state.
Quick start
- Open a git repository.
- Run FeatureFlow: Initialize FeatureFlow (or the welcome CTA) to write
featureflow.config.json, scaffold features/, and host dirs (e.g. .github/skills).
- Run FeatureFlow: New Feature to create
features/<slug>/ + feat/<slug>.
Stages (diagram FSM)
| Stage |
Default entry checkpoints (existence + headings) |
| Context Ingestion |
README.md — Context, Links |
| Shaping |
shaping.md — Outcome, Constraints, Out of scope, Success signals |
| Discovery |
discovery.md — Findings, Stakeholders, Risks, Open questions |
| Exploration |
exploration.md — Options, Trade-offs, Recommendation |
| Specification |
Shared docs/cde/requirement.md + docs/cde/architecture.md (configurable) |
| Implementation Planning |
implementation.md — Settled choices, Plan, Risks, Test approach |
| Build & Test |
test-report.md — Results, Coverage, Gaps |
| Verification |
summary.md — What got built, Deviations, Follow-ups |
| Weekly / Merge / Release Check |
verdict docs with **Verdict:** match\|enhance\|change-note |
| Released |
released.md — Notes, Context returned |
| Change Revision |
open change/change-note.md (What changed, Reopens) |
Paths and MD rules live in featureflow.config.json. Per-feature files use {{featureDir}}/…; shared docs can point anywhere in the workspace (or a submodule listed in contextRoots).
In the Flow view: dynamic HTML diagram (current stage highlighted), click a stage → gate checklist with change path, plus ⚙ Settings / Edit gates.
Manual skip / bypass: On a stage zoom, Skip to this stage (create templates)… (or FeatureFlow: Bypass Flow: Set Stage…).
- Forward: confirms, then creates missing gate templates for every stage after the gate-derived stage through the target (stub files with required headings). Stage advances because the files exist. Clears any manual override.
- Backward: keeps later files and writes
features/<name>/.featureflow-stage.json override (clear when you want file-driven stage again).
Artifact version sync
Feature and architecture docs own a semver in YAML frontmatter; later artifacts declare which versions they were written for:
# requirement.md
---
version: 1.0.0
---
# architecture.md
---
version: 1.0.0
forFeature: 1.0.0
---
# implementation.md (and later gates)
---
forFeature: 1.0.0
forArchitecture: 1.0.0
---
If you bump version on requirement or architecture, dependents whose forFeature / forArchitecture do not match are marked incomplete (checkpoint fail) so the stage retreats until you update them. Rules live in versionSync in featureflow.config.json. Sync is inactive until a source declares a parseable x.y.z version.
Progression is ordered: a stage is current when its checkpoints (and all prior stages') pass and the next stage's do not. An open change note routes to Change Revision. Paths and MD rules are configurable in featureflow.config.json.
Git is still used to discover feat/* branches, dirty flags, and checkout — not as stage gates.
UI (left activity bar)
- Features — tree with stage badges and artifact status
- Flow — holistic FSM board; click a stage to zoom into checkpoints + mapped agents/skills
- Agents & Skills — search builtins + skills.sh; install; materialize for the active feature stage
Optional setting featureflow.openOnStartup (default true) focuses the FeatureFlow activity-bar icon when the extension activates. Run FeatureFlow: Show FeatureFlow anytime to open it.
Agents & skills
Packages are cached under the extension global storage (and optionally .featureflow-cache/). On active feature/stage change they are materialized to host paths:
| Host |
Paths |
| Copilot (primary default) |
.github/skills/, .github/agents/, pointers in .github/copilot-instructions.md |
| Claude Code |
.claude/skills/, .claude/agents/ |
| Cursor |
.cursor/skills/, .cursor/agents/, .agents/skills/ |
Enable additional hosts via hosts.also in featureflow.config.json.
Defaults (baked in)
- Per-stage agents for Context → Released (plus Reviewer / Engineering).
- Build & Test engineering agent (
agent:cde-engineering) with skills: Helm charts, Java, Spring Boot, Spring Data MongoDB, JPA+Postgres, OAuth2.
- Engineering skills prefer a skills.sh remote install (
npx skills add …); offline installs use local bodies.
Search in the Agents & Skills view queries skills.sh and merges hits with builtins.
Install skill/agent from disk: Command Palette → FeatureFlow: Install Skill/Agent from Disk, or Install local… in the Agents view. Pick a folder with SKILL.md / *.agent.md, or a parent of several skill folders. Packages land in the plugin store as local:skill:… / local:agent:… — map them in agentSkillMap, then Reconcile.
Settings
| Setting |
Default |
Meaning |
featureflow.featuresDir |
features |
Feature folders (overridden by config file) |
featureflow.branchPrefix |
feat/ |
Feature branch prefix |
featureflow.baseBranch |
"" |
Base for scaffolding / discovery only |
featureflow.sidebarLocation |
left |
Activity bar vs secondary sidebar |
Development
npm install
npm test
npm run compile
npm run install:local # package .vsix and install into VS Code (`code`)
Press F5 to launch the Extension Development Host without installing.
install:local runs a production build, creates featureflow-<version>.vsix, then code --install-extension … (Insiders as fallback). Reload the VS Code window after install. To install into Cursor instead: FEATUREFLOW_INSTALL_HOST=cursor npm run install:local.
