Feature-Driven-Flow (FDF)

Version: 1.2.1

Feature-Driven-Flow is a markdown-first delivery framework for non-trivial work. This package targets Codex. It runs a fixed seven-phase workflow, compiles selected policies into an Effective Rule Matrix, and supports reusable effective-instructions artifacts.

Install

1. Copy skills/* into $CODEX_HOME/skills/.
2. Copy prompts/*.md into $CODEX_HOME/prompts/.
3. Copy fdf/ into $CODEX_HOME/fdf/ to make shared FDF assets available globally.
4. Optionally copy fdf/ into a target project root as ./fdf/ when that project needs local FDF overrides.
5. Restart Codex.

Resulting runtime layout:

$CODEX_HOME/
├── skills/
│ └── feature-driven-flow/
├── prompts/
│ └── fdf-start.md
└── fdf/
├── schemas/
├── scripts/
└── skills/feature-driven-flow/
<project-root>/
└── fdf/ # optional project-local override

Quick Start

Run the conductor prompt:

/prompts:fdf-start Create a simple console Java app that prints factorial(n). Use JDK 25 and Maven. Read n from argv.

Optional profile request:

/prompts:fdf-start Build a small internal CLI tool. Use profile hardened and overlays security-overlay, operations-overlay.

Optional Effective Rule Matrix reuse:

/prompts:fdf-start Implement my feature using matrix file .codex/feature-driven-flow/effective-rule-matrix.json

Asset Resolution Rule

At runtime, shared FDF assets are resolved from the first available root in this order:

1. ./fdf/ in the target project root
2. $CODEX_HOME/fdf/

Do not resolve shared schemas or scripts from $CODEX_HOME/skills/feature-driven-flow/.

• Shared schemas: fdf/schemas/*.json
• Shared scripts: fdf/scripts/*
• Shared references, templates, settings, packs: fdf/skills/feature-driven-flow/*
• Repo-local overrides and generated artifacts only: .codex/feature-driven-flow/*

Included Assets

• Internal conductor skill implementation: skills/feature-driven-flow/SKILL.md
• Internal specialist skill implementations: skills/fdf-code-explorer/, skills/fdf-implementation-planner/, skills/fdf-change-auditor/
• Prompt entrypoint: prompts/fdf-start.md
• Utility prompts: prompts/fdf-*.md
• Shared rules, profiles, packs, templates, references: fdf/skills/feature-driven-flow/
• Schemas: fdf/schemas/*.json
• Conversion tool: fdf/scripts/convert-effective-instructions.ps1

Source Repository

Development happens in QuasarByte/feature-driven-flow. This Codex package is the runtime distribution published through QuasarByte/feature-driven-flow-codex.

Maintainer Tooling

If you use the build, deploy, validation, manifest, or conversion scripts from this repository, PowerShell 7 (pwsh) must be installed. The .sh and .cmd wrappers still delegate to pwsh.

Scripts that require pwsh:

1. tools/build-distribution-codex.ps1
2. tools/deploy-distribution-codex.ps1
3. tools/run-validation-cycle.ps1
4. tools/validate-fdf-assets.ps1
5. tools/generate-fdf-manifest.ps1
6. shared/fdf/scripts/convert-effective-instructions.ps1

Workflow Contract

FDF always runs in this order:

Scope -> Explore -> Clarify -> Architect -> Implement -> Verify -> Summarize

Core invariants:

1. Do not reorder or skip phases.
2. Do not leave Clarify with decision-critical ambiguity.
3. Do not start Implement without explicit user approval.
4. Do not close before Verify and Summarize.

Settings

Distribution defaults live at:

fdf/skills/feature-driven-flow/settings.json

Repo-local overrides can be added at:

• .codex/feature-driven-flow/settings.json
• .codex/feature-driven-flow/rules/*.md
• .codex/feature-driven-flow/profiles/*.md
• .codex/feature-driven-flow/packs/*

Default shared pack directory inside the selected runtime root:

fdf/skills/feature-driven-flow/packs

Effective Artifact Commands

Export matrix:

/prompts:fdf-export-effective-matrix .codex/feature-driven-flow/effective-rule-matrix.json

Export compiled instructions bundle:

/prompts:fdf-export-effective-instructions-bundle .codex/feature-driven-flow/effective-instructions-bundle

Export compiled instructions compact:

/prompts:fdf-export-effective-instructions-compact .codex/feature-driven-flow/effective-instructions-compact.json

Convert bundle to compact:

pwsh -NoProfile -File fdf/scripts/convert-effective-instructions.ps1 -Mode directory-to-compact -InputPath .codex/feature-driven-flow/effective-instructions-bundle -OutputPath .codex/feature-driven-flow/effective-instructions-compact.json

Convert compact to bundle:

pwsh -NoProfile -File fdf/scripts/convert-effective-instructions.ps1 -Mode compact-to-directory -InputPath .codex/feature-driven-flow/effective-instructions-compact.json -OutputPath .codex/feature-driven-flow/effective-instructions-bundle

Manifest and Schema Paths

• Combined manifest: fdf/skills/feature-driven-flow/extensions/manifest.json
• Core manifest: fdf/skills/feature-driven-flow/manifest.json
• Pack manifests: fdf/skills/feature-driven-flow/packs/<pack_id>/manifest.json
• Settings schema: fdf/schemas/fdf-settings.schema.json
• Matrix schema: fdf/schemas/fdf-effective-matrix.schema.json
• Effective-instructions schemas: fdf/schemas/fdf-effective-instructions-*.schema.json

Troubleshooting

1. Prompt missing: verify fdf-start.md exists in $CODEX_HOME/prompts/ and restart Codex.
2. Shared assets missing: verify fdf/ exists in either ./fdf/ or $CODEX_HOME/fdf/.
3. Packs not available: check packs.enabled and fdf/skills/feature-driven-flow/packs/<pack_id>/manifest.json.
4. Imported matrix rejected: validate against fdf/schemas/fdf-effective-matrix.schema.json.
5. Effective-instructions import/export rejected: validate against the relevant schema under fdf/schemas/ and review effective_instructions.* settings.

Deploy Sync

To mirror the built Codex distribution into a local checkout of your release repository:

pwsh -NoProfile -File tools/deploy-distribution-codex.ps1 -TargetRepoPath C:\path\to\feature-driven-flow-codex -Build

It uses a PowerShell-native mirror sync excluding .git, so it copies new files, updates changed files, and deletes files that no longer exist in distrib/feature-driven-flow-codex.