bttoxin-pipeline/.claude/skills/ralph-runner/SKILL.md

---
name: ralph-runner
description: "BtToxin Pipeline development with Ralph autonomous AI agent. Actions: start, monitor, stop, status, commit, push. Features: 16-task concurrency, genome/protein analysis, i18n support, Docker deployment, CRISPR-Cas预留. Domain: bttiaw.hzau.edu.cn"
---

# Ralph Runner - BtToxin Pipeline Development

Autonomous AI-powered development using Ralph for the BtToxin Pipeline project.

## Prerequisites

Check if Ralph is installed:

```bash
which ralph || ls ~/.local/bin/ralph-claude-code/ralph_loop.sh
```

If Ralph is not installed, install it:

```bash
~/.local/bin/claude-switch/tools/ralph-install-external.sh
```

Verify Ralph project files exist:

```bash
ls -la PROMPT.md @fix_plan.md specs/requirements.md
```

---

## How to Use This Skill

When user requests BtToxin Pipeline development (implement, build, fix, add, create), follow this workflow:

### Step 1: Check Current Project Status

```bash
# Check git status
git status

# Check Ralph status
ralph --status

# View current task list
cat @fix_plan.md
```

### Step 2: Start Ralph Loop

**Recommended: With monitoring dashboard**
```bash
ralph --monitor
```

**Without monitoring (background process)**
```bash
ralph
```

**With call limit**
```bash
ralph --monitor --calls 50  # Limit to 50 calls per hour
```

### Step 3: Monitor Progress

```bash
# Check status
ralph --status

# View logs
tail -f logs/ralph.log

# Check response analysis
cat status.json | jq .
```

### Step 4: Manual Operations (when needed)

**Commit changes**
```bash
git add .
git commit -m "feat(module): descriptive message"
```

**Push to remote**
```bash
git push
```

**Reset Ralph circuit breaker**
```bash
ralph --reset-circuit
```

**Check circuit breaker status**
```bash
ralph --circuit-status
```

---

## Ralph Configuration

### Environment Variables

```bash
# Set provider (glm, minimax, local, etc.)
export CLAUDE_PROVIDER=minimax

# Set model
export CLAUDE_MODEL=MiniMax-M2.1

# Set max iterations
export RALPH_MAX_ITERATIONS=20
```

### Ralph Home Directory

- **Commands**: `~/.local/bin/`
- **Templates**: `~/.ralph/templates/`
- **Scripts**: `~/.ralph/`

---

## Ralph Project Files

| File | Purpose |
|------|---------|
| `PROMPT.md` | Ralph development instructions (REQUIRED) |
| `@fix_plan.md` | Prioritized task list |
| `specs/requirements.md` | Technical specifications |
| `@AGENT.md` | Build/test/deploy commands |

---

## Common Workflows

### Workflow 1: Start New Development Session

```bash
# 1. Pull latest changes
git pull

# 2. Check Ralph status
ralph --status

# 3. Start monitoring
ralph --monitor
```

### Workflow 2: Review Completed Work

```bash
# 1. Check git log
git log --oneline -10

# 2. View changed files
git diff HEAD~1

# 3. Check @fix_plan.md progress
grep -E '^\[.\]' @fix_plan.md | wc -l
```

### Workflow 3: Continue After Interruption

```bash
# 1. Check status
ralph --status

# 2. Resume if needed
ralph  # or ralph --monitor
```

### Workflow 4: Emergency Stop

```bash
# Ctrl+C to stop monitoring
# Or kill process
pkill -f ralph_loop.sh
```

---

## Project-Specific Guidelines

### Current Development Priority

Based on @fix_plan.md, current priorities are:

1. **P0 - Frontend i18n**: ✅ Completed (vue-i18n, navigation, pages)
2. **P0 - Upload Enhancement**: ✅ Completed (single file, genome/protein toggle)
3. **P0 - Task Status**: ✅ Completed (queue status, progress)
4. **P1 - FastAPI Backend**: Next focus
5. **P1 - Concurrency Control**: Next focus
6. **P2 - Docker Deployment**: Later focus

### Completed Features

- [x] Vue 3 frontend with Element Plus
- [x] vue-i18n (Chinese/English)
- [x] Navigation bar (Home, About, Submit, Status, Tool Guide)
- [x] File upload (.fna/.fa/.fasta/.faa)
- [x] Single file restriction
- [x] Genome/Protein toggle
- [x] Task status pages
- [x] Tool Info page (Shoter methodology, no Digger mentioned)

### Pending Features

- [ ] FastAPI backend (main.py, tasks.py)
- [ ] 16 concurrent task limit
- [ ] Redis task queue
- [ ] API endpoints (/api/tasks, /api/tasks/{id})
- [ ] Docker deployment
- [ ] Traefik configuration
- [ ] CRISPR-Cas预留 (crispr_cas/ directory)

---

## Testing Guidelines

Ralph follows these testing rules:

1. **Testing effort**: ~20% of total effort
2. **Priority**: Implementation > Documentation > Tests
3. **Coverage**: 85% for new code
4. **Focus**: Core functionality first

---

## Troubleshooting

### "Prompt file 'PROMPT.md' not found"

```bash
# Ensure you're in the project directory
cd /vol1/1000/docker_server/traefik/web/zly
ls -la PROMPT.md
```

### "Ralph not installed"

```bash
# Install Ralph
~/.local/bin/claude-switch/tools/ralph-install-external.sh
```

### Ralph stuck in loop

```bash
# Reset circuit breaker
ralph --reset-circuit

# Check circuit status
ralph --circuit-status
```

### tmux session lost

```bash
# List sessions
tmux list-sessions

# Reconnect
tmux attach -t ralph-watch

# Or create new session
tmux new -s ralph-watch
ralph-monitor
```

---

## Project Structure

```
web/zly/
├── PROMPT.md              # Ralph instructions
├── @fix_plan.md           # Task list
├── @AGENT.md              # Build commands
├── specs/
│   └── requirements.md    # Tech specs
├── frontend/              # Vue 3 SPA
│   ├── src/
│   │   ├── locales/       # i18n files
│   │   ├── views/         # Pages
│   │   └── components/    # Components
│   └── package.json
├── web/backend/           # FastAPI (to be built)
├── scripts/               # Pipeline scripts
├── docker/                # Docker configs
└── external_dbs/          # BtToxin database
```

---

## Deployment Targets

| Target | URL | Status |
|--------|-----|--------|
| Development | localhost:5173/8000 | ✅ Frontend ready |
| Test | bttiaw.hzau.edu.cn | 🔄 In progress |
| Production | bttiaw.hzau.edu.cn | ⏳ Pending |

---

## Key Contacts

- **Project**: BtToxin Pipeline
- **Domain**: bttiaw.hzau.edu.cn
- **Maintainer**: Claude Code with Ralph