Initialize Project

Set up a new ML project from the template. User provides project name and description.

Input

$ARGUMENTS

If project name or description not provided, ask the user.

Workflow

Phase 1: Gather Info

1. Get project details from user:
   • Project name (used for WandB project, directory context)
   • Short description (one sentence)
   • WandB entity (team or username)
   • WandB launch queue name
   • Python version preference (default: current system python3)
   • Environment variables / secrets needed (e.g., Kaggle token, HuggingFace token, custom API keys)

Phase 2: Python Environment

2. Create and activate virtual environment

   python3 -m venv .venv
   source .venv/bin/activate
   

3. Install dependencies

   pip install -r requirements.txt
   

4. Verify imports work

   python -c "import wandb; import torch; print('All imports OK')"
   

Phase 3: WandB Setup

5. Check WandB login

   wandb status
   

   • If not logged in, prompt user to run

     wandb login

   • Verify the entity is accessible

6. Verify WandB Launch queue

   wandb launch-agent --help
   

   • Ask user to confirm:
     • Queue name exists and is created in WandB UI
     • At least one agent is running or will be started on GPU environment
   • Test connectivity:

     python -c "import wandb; api = wandb.Api(); print('WandB API OK')"

Phase 4: Environment Variables

7. Write

   .claude/settings.local.json

   with project secrets and env vars:

   • Ask user for any API keys / tokens they need (e.g.,

     KAGGLE_USERNAME

     ,

     KAGGLE_KEY

     ,

     HF_TOKEN

     )

   • Write secrets only to

     .claude/settings.local.json

     (gitignored, local only):

     {
       "env": {
         "WANDB_API_KEY": "<value>",
         "KAGGLE_USERNAME": "<value>",
         "KAGGLE_KEY": "<value>",
         "HF_TOKEN": "<value>"
       }
     }
     

   • Only include keys the user actually needs — omit unused ones

   • Verify

     .claude/settings.local.json

     is in

     .gitignore

     :

     git check-ignore .claude/settings.local.json

   • Non-secret project defaults go in

     .claude/settings.json

     (committed, shared):

     {
       "env": {
         "WANDB_ENTITY": "<entity>",
         "WANDB_PROJECT": "<project-name>",
         "WANDB_QUEUE": "<queue-name>"
       }
     }
     

Phase 5: CLAUDE.md — Project-Specific Notes

8. Write CLAUDE.md with project-specific content:

   # CLAUDE.md
   
   ## Project: <project-name>
   
   <description>
   
   ## Key Features
   
   - **Git controlled**: Version-controlled experiment workflow
   - **WandB based**: Experiment tracking, launch, and evaluation
   - **Python programmed**: pip + requirements.txt
   - **Claude Code managed**: Human provides ideas, Claude Code runs the loop
   
   See `.claude/rules/` for detailed workflow rules.
   
   ## WandB Config
   
   - **Entity**: <entity>
   - **Project**: <project-name>
   - **Queue**: <queue-name>
   
   ## Current Baseline
   
   Initial baseline. No experiments run yet.
   
   ## Project-Specific Notes
   
   <!-- Add notes as the project evolves -->
   

Phase 6: Baseline Documentation

9. Create initial baseline doc at

   docs/baseline-history.md

   :

   # Baseline History
   
   ## Baseline 0 — Initial
   
   - **Date**: <today>
   - **Description**: Initial project setup from template
   - **Merged branches**: None (starting point)
   - **Discarded branches**: None
   - **Key metrics**: N/A (no training run yet)
   
   ---
   

Phase 7: Git Cleanup

10. Ensure clean git state

• Verify on

  main

  branch:

  git branch --show-current

• Delete any stale local branches (except

  main

  ): list with

  git branch

  , confirm with user before deleting
• Delete any stale remote branches:

  git branch -r

  and confirm
• Stage and commit all initialization files:

  • CLAUDE.md

  • docs/baseline-history.md

  • .venv

    should be in

    .gitignore

    (create/update if needed)

11. Push to remote

    • git push origin main

Phase 8: Verify

12. Run verification checklist and print results:

    • Python venv active and dependencies installed
    • WandB logged in and API accessible
    • WandB entity and project confirmed
    • WandB launch queue name recorded
    • CLAUDE.md has project-specific config
    • docs/baseline-history.md exists
    • Git is on

      main

      , clean, no stale branches

    • .gitignore

      includes

      .venv/

      and

      .claude/settings.local.json

    • .claude/settings.json

      has non-secret project defaults

    • .claude/settings.local.json

      has secrets (not committed)
    • All changes committed and pushed
    • Next: run

      /setup-automation

      to set up GitHub labels, secrets, and automatic CI pipeline

13. Print next steps:

    • "Project initialized. Next:"
    • "1. Run

      /setup-automation

      to enable automatic result analysis (WandB → GitHub Actions → Claude Code)"
    • "2. Ensure a WandB Launch agent is running on your GPU environment"
    • "3. Use

      /new-experiment [idea]

      to create your first experiment"

Rules

• Always ask for confirmation before deleting any git branches
• Never commit

  .venv/

  or

  .claude/settings.local.json

  — ensure

  .gitignore

  covers both
• If WandB login fails, do not proceed — guide user to fix it
• All WandB config (entity, project, queue) must be recorded in CLAUDE.md