ARCHITECTURE.md

This file is the short, stable architecture entrypoint for the feature-driven-flow repository.

Use the detailed architecture reference for full layout and packaging details: docs/fdf-cross-agent-architecture.md

Purpose

This repository develops one framework for multiple AI coding runtimes.

Current supported runtimes:

The design goal is behavioral parity with thin runtime-specific wrappers.

The repository is organized in three layers:

shared/fdf/ Canonical runtime assets: settings, schemas, rules, profiles, packs, references, templates, manifests, and shared scripts.
codex/ Codex-specific prompts, skills, and packaging wrapper.
claude-code/ Claude Code plugin sources, slash commands, skills, and packaging wrapper.

Shared framework behavior belongs in shared/fdf/, not in runtime wrappers.
Codex and Claude wrappers may differ in entrypoint format and local conventions, but should preserve the same seven-phase FDF behavior.
Build outputs in distrib/ are generated artifacts, not source of truth.
Runtime-specific maintainer guidance belongs in wrappers only when it cannot be expressed as cross-agent policy in AGENTS.md.

FDF always runs the same seven phases in the same order:

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