Development Workflow

The development workflow for flext-web is a standardized process designed to maintain high code quality and architectural consistency across the FLEXT platform. It leverages a monorepo structure where contributions follow a rigorous cycle of environment setup, feature branching, and mandatory quality gates. The workflow is strictly governed by "Engineering Law" defined in the project's governance documentation and enforced through canonical make targets.

Sources: guides/development.md:1-122, index.md:27-38, development.md:1-48

Environment Setup and Initialization

Before contributing, developers must establish a standardized local environment. The project requires Python 3.13+, Poetry for dependency management, and Git for version control. Verification of the environment is performed using the make setup and make val commands to ensure all dependencies and pre-commit hooks are correctly installed.

Verification Commands

Sources: guides/development.md:46-70, development/README.md:24-30

Core Development Cycle

The development cycle follows a standard feature-branching strategy. Developers are required to use the provided make targets exclusively for operational tasks to ensure consistency with the CI/CD environment.

Workflow Stages

1. Branching: Create a feature branch (e.g., feature/amazing-feature).
2. Implementation: Follow FLEXT standards, including Clean Architecture and strict type safety.
3. Validation: Run quality gates locally before committing.
4. Submission: Push changes and submit a Pull Request.

The following diagram illustrates the transition through these development stages:

The diagram shows the sequence from initial repository setup to the final submission of a Pull Request, highlighting the mandatory validation steps.

Sources: guides/development.md:89-106, development.md:26-31

Code Standards and Patterns

flext-web enforces specific coding patterns that must be followed during implementation. These are non-negotiable and are checked during the quality gate phase.

Railway-Oriented Programming (ROP)

All operations should utilize the r[T] result pattern rather than exception-based error handling. This ensures that functions return a consistent Result object that can be chained using map or flat_map.

Type Safety

The project maintains a "Zero Tolerance" policy toward missing type annotations. All code must pass MyPy strict mode and Pyrefly validation.

# ✅ CORRECT - Complete type annotations and Result return
def process_data(data: t.JsonMapping) -> p.Result[ProcessedData]:
    if not data:
        return r[ProcessedData].fail("Data required")
    return r[ProcessedData].ok(ProcessedData(**data))

Sources: guides/development.md:110-134, guides/testing.md:16-24

Testing and Quality Gates

Changes are not considered complete until they pass the canonical quality gates. The project uses a tiered testing strategy including unit, integration, and end-to-end (e2e) tests.

The sequence diagram details the interaction between the developer and the automated quality gate systems both locally and in CI.

Testing Commands

• Unit Tests: pytest tests/unit/
• Integration Tests: pytest tests/integration/
• Full Suite: make test PROJECT=flext-web

Sources: guides/testing.md:112-135, development.md:45-48

Skill Automation Pattern

For future automation, the project utilizes a "Skill Automation Pattern." Each automation family must deliver a skill folder containing a SKILL.md document, detection rules (ast-grep/ripgrep), and a violation baseline.

# Validate a specific skill
python3 scripts/core/skill_validate.py --skill flext-strict-typing

Sources: guides/skill-automation-pattern.md:12-45

Conclusion

The flext-web development workflow prioritizes architectural integrity through strict adherence to the Result pattern, comprehensive type safety, and automated quality gates. By utilizing the unified make contract and standardized project structures, developers ensure that the platform remains stable and maintainable during its alpha phase and beyond.