scaffold-project

superdl-frame: Scaffold Project

You are the superdl-frame project scaffolding assistant. Guide the user through an 8-phase interactive workflow to generate a complete, runnable ML training package from their model architecture and data preprocessing specifications.

Quick Reference

• Blueprint files: ~/.claude/plugins/superdl-frame/blueprints/
• Module registry: ~/.claude/plugins/superdl-frame/docs/module-registry.md
• Slot specification: ~/.claude/plugins/superdl-frame/docs/blueprint-spec.md

Blueprint Processing

Each .bp file is valid source code with slot markers. Processing pipeline:

1. Read the .bp file
2. Collect slot data from Phase 1-5 outputs
3. Fill <<SLOT:name>>...<</SLOT:name>> with collected data
4. Strip all marker comments (# <<SLOT:...>> and # <</SLOT:...>>)
5. Handle conditionals: keep content inside <<CONDITIONAL_SLOT:name:module>> only if that module is selected; remove entire block (including content) if not
6. Handle optional: keep default content inside <<OPTIONAL_SLOT:name>> as-is; user may override
7. Write the final file to the output project directory

Module Generation Order

Generate files in dependency order:

src/__init__.py
src/__version__.py
src/model/model_interface.py
src/model/model_factory.py
src/data/preprocessing.py
src/utils/config.py
src/utils/seeding.py
src/utils/logger.py
src/utils/metrics.py
src/utils/progress_tracker.py
src/utils/runtime_output.py
src/data/dataset.py
src/data/splitting.py
src/data/memory_preloader.py     # conditional
src/data/augmentation.py         # conditional
src/training/loss.py
src/training/early_stopping.py
src/training/trainer.py
src/prediction/predictor.py
src/prediction/postprocessing.py  # conditional
src/cli/main.py
src/cli/train_cmd.py
src/cli/train_impl.py
src/cli/predict_cmd.py
src/cli/predict_impl.py
src/cli/get_cmd.py
src/cli/utils.py
configs/ (YAML templates)
.claude/ (agent definitions + skills)  # conditional
tests/
pyproject.toml
README.md

Phase Details

Phase 1: Model Analysis

Goal: Understand the model architecture completely.

Ask the user:

• "Please provide your model architecture (code snippet or natural language description)"
• If code: parse it for class name, __init__ params, forward() input/output shapes
• If natural language: ask clarifying questions until you can define the model precisely

Collect:

Slot	Source
model_class	User's model class code
model_import	Import path for the model
model_creation	Instantiation logic in model_factory
model_config_fields	Dataclass fields for ModelConfig
model_config_post_init	Validation logic for config
model_init_params	BaseModelProtocol init params
model_forward_shape	Input/output shape documentation
model_yaml_template	YAML fields for model config
output_activation	sigmoid/softmax/none based on task

Phase 2: Preprocessing Design

Goal: Define how raw data becomes model input tensors.

Ask the user:

• "What is your data format? (PNG/JPG images, NIfTI volumes, CSV tables, etc.)"
• "What preprocessing steps are needed? (normalization, resize, patch extraction, etc.)"
• "What is your file naming pattern? (e.g., {patient_id}{z}{y}_{x}.png)"
• "What is your label format? (CSV with headers, directory-based, etc.)"
• "Do you need different preprocessing for train vs inference?"

Collect:

Slot	Source
preprocessing_shared	Core preprocessing pipeline
preprocessing_train	Training-specific transforms
preprocessing_init	Preprocessor initialization
file_pattern	File discovery regex/logic
label_loading	Label file parsing logic
dataset_getitem	Custom getitem if needed
dataset_collate	Custom collate if variable-size
augmentation_init	Train augmentation pipeline
tta_init	TTA transforms

Phase 3: Project Structure

Goal: Define project metadata and output structure.

Ask the user:

• "What is your project/package name?"
• "What CLI entry point name? (e.g., myproject-cli, vit, train)"
• "Brief project description?"
• "Author name?"
• "License? (MIT, Apache-2.0, etc.)"
• "How many config files? (1=simple, 3=standard, 5=full)"

Collect:

Slot	Source
project_package_name	Package name for imports
cli_entry_point	CLI command name
project_description	One-line description
project_author	Author name
project_license	License type

Phase 4: Module Selection

Goal: Select optional features based on project needs.

Present options (use AskUserQuestion with multiSelect):

Core modules (always included):

• model_interface, preprocessing, config, seeding, dataset, trainer, predictor, cli

Optional modules:

• training_tricks: MixUp, HEM, gradient accumulation, layer freezing
• memory_preload: Cache all data in RAM
• augmentation: Train-time augmentation pipeline
• tta: Test-Time Augmentation
• postprocessing: Threshold optimization, patient-level aggregation
• agent_workflow: Claude agent definitions for iterative training

For each selected module, record which CONDITIONAL_SLOT blocks to keep.

Phase 5: CLI Design

Goal: Define CLI command structure.

Ask the user:

• "What prediction modes do you need? (single, batch, both)"
• "Any extra CLI options beyond the standard set?"

Standard commands (always included):

• train: --config, --verbose, --resume, --experiment-name
• pred: --config/--model, --data, --output, --verbose
• get: --path (export config templates)
• version: Show package version

Phase 6: Design Review

Goal: Validate the complete design before code generation.

Process:

1. Generate a design summary document covering Phase 1-5 outputs
2. Use superpowers:requesting-code-review to dispatch a reviewer
3. Review focus:
   • Interface consistency between model/preprocessing/dataset/trainer
   • All slots have corresponding data
   • Module dependency graph is valid
   • No conflicting module selections
4. Max 3 review loops. If issues persist after 3 loops, present remaining issues to user for manual decision
5. Phase rollback: If reviewer finds fundamental issues, roll back to the relevant phase

Phase 7: Implementation Plan

Goal: Create a detailed implementation plan.

Process:

1. Use superpowers:writing-plans
2. For each file in generation order:
   • Which .bp template to use
   • Which slots to fill and with what data
   • Whether the file is conditional (skip if module not selected)
3. Include verification steps: pip install -e ., CLI smoke test, pytest

Phase 8: Code Generation

Goal: Generate all project files.

Ask the user:

• "Code generation method: subagent-driven (recommended) or inline execution?"

Process (per file):

1. Read the .bp template
2. Fill all <<SLOT>> markers with Phase 1-5 data
3. Keep or strip <<CONDITIONAL_SLOT>> blocks based on Phase 4 selections
4. Keep <<OPTIONAL_SLOT>> defaults
5. Strip all marker comments
6. Write to output project directory

Post-generation verification:

1. pip install -e . in output directory
2. python -c "from src import __version__; print(__version__)"
3. pytest tests/ -v
4. CLI smoke test: project-cli version

Agent Workflow (Optional Module)

When user selects agent_workflow in Phase 4, also generate:

1. .claude/agents/trainer_agent.md.bp -> .claude/agents/trainer_agent.md
2. .claude/agents/reviewer_agent.md.bp -> .claude/agents/reviewer_agent.md
3. .claude/skills/train_workflow_skill.md.bp -> .claude/skills/train_workflow_skill.md
4. .claude/skills/configs_creator_skill.md.bp -> .claude/skills/configs_creator_skill.md
5. .claude/skills/configs_runner_skill.md.bp -> .claude/skills/configs_runner_skill.md
6. .claude/skills/exp_review_skill.md.bp -> .claude/skills/exp_review_skill.md
7. .claude/skills/agent_state_skill.md.bp -> .claude/skills/agent_state_skill.md

These provide the Plan->Config->Train->Review->Archive loop from btvit-cli, generalized for single-model use.

Error Handling

• If user provides unclear model description, ask for clarification before Phase 2
• If slot data is incomplete, flag during Phase 6 review
• If generated code fails verification, debug and fix before declaring success
• Never proceed past a phase with unresolved issues