# Ff Develop

> Ff Develop is an Agent Skill for development published in the X-GenGroup/Flow-Factory repository on GitHub: a SKILL.md instruction file an AI agent can load to do this task.

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'.

- Skill name: `ff-develop`
- Category: [Development](https://www.openparable.com/skill/development/1)
- Source: https://github.com/X-GenGroup/Flow-Factory/blob/HEAD/.agents/skills/ff-develop/SKILL.md
- Repository: X-GenGroup/Flow-Factory (628 GitHub stars when collected)

## SKILL.md

# 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

1. **Establish baseline** — Run tests before making changes
2. **One at a time** — ONE structural change → update ALL callers → verify → commit
3. **Never combine** — Don't combine multiple refactoring steps in one commit

## Workflow Steps

1. **Understand scope**
   - Read relevant `abc.py` base classes
   - Identify all affected subclasses and callers
   - Read related `guidance/` docs

2. **Plan changes**
   - List all files that need modification
   - Document expected behavior changes
   - Identify test scenarios

3. **Implement methodically**
   - Make ONE change at a time
   - Update ALL callers/subclasses
   - Run tests after each change

4. **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

- [ ] Impact analysis completed for all 6 areas
- [ ] All callers/subclasses updated
- [ ] Tests pass
- [ ] Code formatted with Black and isort
- [ ] YAML configs in `examples/` updated: new fields added, renamed fields updated, removed fields cleaned up
- [ ] License header present on new files

---

Source: https://www.openparable.com/skill/development/ff-develop (OpenParable). Cite the canonical URL above.
