| name | ff-develop |
| description | Feature development with cross-module impact analysis. Covers trainer hierarchy, model adapters, reward pipeline, config system, sample dataclasses, and distributed training paths. Trigger: 'add feature', 'implement', 'refactor', 'reorganize', 'new capability'. |
Feature Development Workflow
Related Topics (read if your change touches these areas)
- Adapter changes ->
topics/adapter_conventions.md
- Trainer/scheduler changes ->
topics/train_inference_consistency.md
- Trainer
optimize() loop, autocast scope, ref/EMA/named param swaps -> topics/autocast_param_swap.md
- Precision changes ->
topics/dtype_precision.md
Impact Analysis Checklist
Before implementing features or refactoring, analyze impacts across these areas:
1. Trainer Hierarchy (constraints.md #11)
- Changes to
BaseTrainer affect all 9 concrete trainers (grpo, grpo-guard, dppo, nft, awm, dgpo, dpo, crd, diffusion-opd); changed abstract methods must be implemented on every one
- Changes to
AdvantageProcessor affect all reward-based trainers (architecture.md "Advantage Computation"; diffusion-opd skips it)
- Check: Does your change alter
_initialization(), _init_reward_model(), or _init_dataloader()?
2. Model Adapter Hierarchy (constraints.md #12)
- Changes to
BaseAdapter affect ALL model adapters
- Check: Does your change modify component management, LoRA logic, or mode switching?
- Adding a new modality (e.g. audio): prefer non-abstract no-op default + opt-in override (R7 pattern). Don't add
@abstractmethod to a new encoder; that forces stub edits on every existing concrete adapter. The 4 abstract methods (load_pipeline, decode_latents, forward, inference) are intentionally minimal — encoders are opt-in by modality.
3. Reward Pipeline (constraints.md #13)
- Changes to
BaseRewardModel or RewardProcessor affect all reward models
- Check: Does your change alter the Pointwise/Groupwise dispatch?
4. Configuration System (constraints.md #15–17)
- Check: Did you rename, remove, or add fields? ALL configs in
examples/ must be updated
5. Sample Dataclasses (constraints.md #14)
- Changes to
BaseSample or its subclasses affect data flow through all 6 stages
- Check: Did you change
_shared_fields or add new fields?
6. Distributed Training Paths (constraints.md #9, #18–20)
- Changes may behave differently under Accelerate vs DeepSpeed
- Check: Does your change involve
accelerator.prepare(), gradient accumulation, or model sharding?
Refactoring Safety Rules
- Establish baseline — Run tests before making changes
- One at a time — ONE structural change → update ALL callers → verify → commit
- Never combine — Don't combine multiple refactoring steps in one commit
Workflow Steps
-
Understand scope
- Read relevant
abc.py base classes
- Identify all affected subclasses and callers
- Read related
guidance/ docs
-
Plan changes
- List all files that need modification
- Document expected behavior changes
- Identify test scenarios
-
Implement methodically
- Make ONE change at a time
- Update ALL callers/subclasses
- Run tests after each change
-
Cross-algorithm verification
- Test with GRPO (coupled paradigm; also covers GRPO-Guard / DPPO variants)
- Test with NFT or AWM (decoupled paradigm; also DGPO / CRD / DPO)
- If the change touches the sample/optimize path, also test
diffusion-opd (distillation; no reward/advantage stage)
- Verify with at least two different model adapters
Documentation
Before committing, check if the change requires documentation updates:
- New/changed API -> update relevant
guidance/ doc
- New/changed config fields -> update ALL example configs in
examples/
- Architecture change -> update
.agents/knowledge/architecture.md
- New constraint discovered -> add to
.agents/knowledge/constraints.md
- Bug fix experience? -> follow
.agents/knowledge/topics/fix_patterns.md archival process
When to Delegate
- Adding a new model →
/ff-new-model
- Adding a new reward →
/ff-new-reward
- Adding a new algorithm →
/ff-new-algorithm
- Debugging a bug →
/ff-debug
- Pre-commit review →
/ff-review
Pre-Commit Checks
