Feature Development Workflow

Relevant source files

The following files were used as context for generating this wiki page:

• examples/README.md
• examples/basic/simple_analysis/README.md
• README.md
• CLAUDE.md
• tests/README.md
• AGENTS.md

The Feature Development Workflow provides a structured methodology for contributing to the flext-quality project. It integrates automated quality gates, issue tracking via the Beads system, and comprehensive testing protocols to ensure all changes maintain enterprise-grade standards. This workflow orchestrates the transition from task identification to final validation using the unified orchestration platform.

Sources: README.md:16-18, AGENTS.md:12-14

Task Tracking and Initialization

The workflow uses the Beads (bd) issue tracker for all task management. You must use bd commands for tracking work instead of manual TODO lists.

1. Initialize Context: Run bd prime to load the current workflow context and command reference.
2. Locate Work: Execute bd ready to find available tasks.
3. Claim Task: Run bd update <id> --claim to assign a specific issue to yourself.
4. Create Development Branch: Follow the naming convention feature/example-<example-name> for new examples or standard feature branch patterns.

Sources: CLAUDE.md:11-20, examples/README.md:166

Development and Implementation Standards

Implementation must adhere to specific architectural and code quality rules defined in the project's engineering core.

Engineering Core Principles

• Research First: Identify repository owners and dependencies before making changes.
• YAGNI: Remove any scope that lacks a current requirement or consumer.
• SSOT: Elect one writable authority for every piece of information.
• SOLID: Apply SOLID principles at responsibility or dependency boundaries.
• Fail Loud: Errors must escape with a traceback and cause; do not normalize or catch exceptions without propagation.

Sources: AGENTS.md:52-65

Code Quality Gates

The workflow requires executing native quality gates using make verbs before proposing any change.

Command	Action
make check	Runs Ruff, basedpyright, and Bandit for static analysis.
make test	Executes the full test suite with coverage thresholds.
make fmt	Formats code according to project style standards.
make gen	Regenerates managed code projections.

Sources: README.md:41-43, AGENTS.md:25-27, AGENTS.md:43-46

Testing and Validation

Comprehensive testing is mandatory for every feature. The test suite is categorized into unit, integration, and end-to-end (e2e) tests.

Test Categories

• Unit Tests: Use isolation and mocking to test domain entities and algorithms.
• Integration Tests: Validate interactions with real dependencies like Ruff, MyPy, and databases.
• E2E Tests: Verify complete user journeys, such as the full analysis workflow and report generation.

Sources: tests/README.md:38-66

Quality Metrics

All contributions must meet the following minimum thresholds:

• Test Coverage: Minimum 90% coverage across all source modules.
• Reliability: Tests must be deterministic and repeatable.
• Performance: Unit tests must complete in less than 100ms.

Sources: tests/README.md:95-104

Analysis Execution Flow

Features involving code analysis follow a specific internal logic to process project quality.

This diagram shows the sequence of steps the CodeAnalyzer performs during a standard quality assessment.
Sources: examples/basic/simple_analysis/README.md:79-115

Session Completion and Handoff

When a feature is complete, follow the standard session closure protocol.

1. File Follow-ups: Create new Beads for any remaining work or debt.
2. Final Quality Check: Run the full make suite one last time.
3. Close Issue: Run bd close <id> to mark the task as finished.
4. Reporting: Report changed files, validation results, and suggest the next commands to the operator.

Sources: CLAUDE.md:36-45, AGENTS.md:144-153

Git and Sync Policy

Synchronization behavior depends on the active agent profile:

• Conservative (Default): Report status and wait for manual approval. Do not push.
• Team-maintainer: Perform git pull --rebase and git push as part of the closure if the repository has opted in.

Sources: CLAUDE.md:24-34, AGENTS.md:154-162

Conclusion

The Feature Development Workflow ensures that every change to flext-quality is tracked, tested, and aligned with architectural standards. By utilizing the Beads system and strict quality gates, the workflow maintains the project's alpha-level stability and prepares it for future promotion within the FLEXT ecosystem.

Sources: README.md:10-14, CLAUDE.md:9-10