cal/mantimon-tcg
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

Add dev-server skill and update development ports

Browse Source 
- Add /dev-server skill with preflight checks for environment, deps,
  ports, and services before starting frontend/backend
- Add /frontend-phase skill for tracking implementation phases
- Register skills in .claude/settings.json
- Update .env.development ports (8001 for API, 3001 for frontend)

Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
This commit is contained in:
Cal Corum 2026-01-30 11:56:25 -06:00
parent 913b1e7eae
commit 09844cbf3f
5 changed files with 586 additions and 3 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

16
.claude/settings.json Normal file
View File

@ -0,0 +1,16 @@
{
"skills": {
"dev-server": {
"path": ".claude/skills/dev-server",
"description": "Start frontend and backend dev servers with pre-flight checks. Use when user says 'start dev', 'dev server', '/dev-server', or wants to run the development environment."
},
"frontend-phase": {
"path": ".claude/skills/frontend-phase",
"description": "Track and manage frontend implementation phases. Use for /frontend-phase commands."
},
"frontend-code-audit": {
"path": ".claude/skills/frontend-code-audit",
"description": "Run code audits on frontend code for anti-patterns and issues."
}
}
}

162
.claude/skills/dev-server/SKILL.md Normal file
View File

@ -0,0 +1,162 @@
# Dev Server Skill
Start both frontend and backend development servers with pre-flight checks.
## Usage
```
/dev-server [command]
```
**Commands:**
- `start` (default) - Run checks and start both servers
- `stop` - Stop all running dev servers
- `status` - Check if servers are running
## Instructions
When this skill is invoked, follow these steps:
### 1. Pre-flight Checks
Run all checks in parallel where possible:
#### Environment Variables
Check that required env files exist and have valid values:
**Frontend** (`frontend/.env.development`):
- `VITE_API_BASE_URL` - Must be a valid URL
- `VITE_WS_URL` - Must be a valid URL
- `VITE_OAUTH_REDIRECT_URI` - Must be a valid URL
**Backend** (`backend/.env` or environment):
- `DATABASE_URL` - PostgreSQL connection string
- `REDIS_URL` - Redis connection string
- `JWT_SECRET` - Must be set (check length >= 32)
#### Port Availability
Check if default ports are available:
- Frontend: 5173, 3000, 3001 (Vite will auto-increment)
- Backend: 8000, 8001
```bash
# Check port availability
lsof -i :8000 2>/dev/null | grep LISTEN
lsof -i :5173 2>/dev/null | grep LISTEN
```
#### Dependencies
Verify dependencies are installed:
```bash
# Frontend
[ -d "frontend/node_modules" ] || echo "Run: cd frontend && npm install"
# Backend
[ -f "backend/.venv/bin/activate" ] || echo "Run: cd backend && uv sync"
```
#### Database/Redis
Check if PostgreSQL and Redis are accessible:
```bash
# PostgreSQL (if DATABASE_URL is set)
pg_isready -d "$DATABASE_URL" 2>/dev/null
# Redis (if REDIS_URL is set)
redis-cli -u "$REDIS_URL" ping 2>/dev/null
```
### 2. Report Issues
If any checks fail, display a clear report:
```markdown
## Pre-flight Check Results
| Check | Status | Action Required |
|-------|--------|-----------------|
| Frontend .env | MISSING | Create frontend/.env.development |
| Port 8000 | IN USE | Kill process or use --port 8001 |
| node_modules | MISSING | Run: cd frontend && npm install |
| PostgreSQL | OK | - |
```
If there are blocking issues, ask the user how to proceed.
### 3. Start Servers
Start both servers in the background:
```bash
# Start backend first (frontend depends on it)
cd backend && uv run uvicorn app.main:app --reload --port $BACKEND_PORT 2>&1 &
# Wait for backend to be ready
sleep 3
# Start frontend
cd frontend && npm run dev 2>&1 &
```
### 4. Verify and Display Status
Wait for both servers to be ready, then display:
```markdown
## Dev Environment Ready
| Service | URL | Status |
|---------|-----|--------|
| Frontend | http://localhost:5173/ | Running |
| Backend API | http://localhost:8000/ | Running |
| Backend Docs | http://localhost:8000/docs | Running |
| PostgreSQL | localhost:5432 | Connected |
| Redis | localhost:6379 | Connected |
**Quick Links:**
- App: http://localhost:5173/
- API Docs: http://localhost:8000/docs
- Health Check: http://localhost:8000/api/health
```
### 5. Stop Command
When `stop` is requested:
```bash
pkill -f "uvicorn app.main:app"
pkill -f "vite"
```
### 6. Status Command
When `status` is requested, check running processes and display current state.
## Common Gotchas
The skill should check for and warn about:
1. **Port mismatch** - Frontend .env pointing to wrong backend port
2. **Missing OAuth config** - Google/Discord credentials not set
3. **Database not migrated** - Check if alembic migrations are pending
4. **Redis not running** - Socket.IO requires Redis for pub/sub
5. **Old processes** - Zombie uvicorn/vite processes from crashed sessions
6. **TypeScript errors** - Run `npm run typecheck` before starting
## Environment Variable Reference
### Frontend (.env.development)
```bash
VITE_API_BASE_URL=http://localhost:8000
VITE_WS_URL=http://localhost:8000
VITE_OAUTH_REDIRECT_URI=http://localhost:5173/auth/callback
```
### Backend (.env)
```bash
DATABASE_URL=postgresql+asyncpg://user:pass@localhost:5432/mantimon
REDIS_URL=redis://localhost:6379/0
JWT_SECRET=your-secret-key-at-least-32-characters
GOOGLE_CLIENT_ID=optional
GOOGLE_CLIENT_SECRET=optional
DISCORD_CLIENT_ID=optional
DISCORD_CLIENT_SECRET=optional
```

164
.claude/skills/dev-server/preflight.sh Executable file
View File

@ -0,0 +1,164 @@
#!/bin/bash
# Pre-flight checks for Mantimon TCG dev environment
# Runs validation checks before starting dev servers
PROJECT_ROOT="$(cd "$(dirname "$0")/../../.." && pwd)"
FRONTEND_DIR="$PROJECT_ROOT/frontend"
BACKEND_DIR="$PROJECT_ROOT/backend"
# Colors for output
RED='\033[0;31m'
GREEN='\033[0;32m'
YELLOW='\033[1;33m'
NC='\033[0m' # No Color
echo "Running pre-flight checks..."
echo ""
ISSUES=0
WARNINGS=0
# Check function
check() {
local name="$1"
local status="$2"
local message="$3"
if [ "$status" = "OK" ]; then
echo -e " ${GREEN}✓${NC} $name"
elif [ "$status" = "WARN" ]; then
echo -e " ${YELLOW}⚠${NC} $name: $message"
((WARNINGS++))
else
echo -e " ${RED}✗${NC} $name: $message"
((ISSUES++))
fi
}
echo "=== Environment Files ==="
# Frontend .env.development
if [ -f "$FRONTEND_DIR/.env.development" ]; then
# Check for required vars
if grep -q "VITE_API_BASE_URL" "$FRONTEND_DIR/.env.development"; then
check "Frontend .env.development" "OK"
else
check "Frontend .env.development" "FAIL" "Missing VITE_API_BASE_URL"
fi
else
check "Frontend .env.development" "FAIL" "File not found"
fi
# Backend .env (optional - might use system env)
if [ -f "$BACKEND_DIR/.env" ]; then
check "Backend .env" "OK"
else
check "Backend .env" "WARN" "No .env file (using system environment?)"
fi
echo ""
echo "=== Dependencies ==="
# Frontend node_modules
if [ -d "$FRONTEND_DIR/node_modules" ]; then
check "Frontend node_modules" "OK"
else
check "Frontend node_modules" "FAIL" "Run: cd frontend && npm install"
fi
# Backend venv
if [ -d "$BACKEND_DIR/.venv" ]; then
check "Backend .venv" "OK"
else
check "Backend .venv" "FAIL" "Run: cd backend && uv sync"
fi
echo ""
echo "=== Port Availability ==="
# Check port 8000
if lsof -i :8000 2>/dev/null | grep -q LISTEN; then
PID=$(lsof -t -i :8000 2>/dev/null | head -1)
PROC=$(ps -p $PID -o comm= 2>/dev/null || echo "unknown")
check "Port 8000" "WARN" "In use by $PROC (PID $PID)"
else
check "Port 8000" "OK"
fi
# Check port 8001
if lsof -i :8001 2>/dev/null | grep -q LISTEN; then
PID=$(lsof -t -i :8001 2>/dev/null | head -1)
PROC=$(ps -p $PID -o comm= 2>/dev/null || echo "unknown")
check "Port 8001" "WARN" "In use by $PROC (PID $PID)"
else
check "Port 8001" "OK"
fi
# Check frontend ports
for PORT in 5173 3000 3001; do
if lsof -i :$PORT 2>/dev/null | grep -q LISTEN; then
check "Port $PORT" "WARN" "In use (Vite will try next port)"
break
fi
done
check "Frontend ports" "OK"
echo ""
echo "=== Services ==="
# PostgreSQL
if command -v pg_isready &> /dev/null; then
if pg_isready -q 2>/dev/null; then
check "PostgreSQL" "OK"
else
check "PostgreSQL" "WARN" "Not running or not accessible"
fi
else
check "PostgreSQL" "WARN" "pg_isready not found"
fi
# Redis
if command -v redis-cli &> /dev/null; then
if redis-cli ping 2>/dev/null | grep -q PONG; then
check "Redis" "OK"
else
check "Redis" "WARN" "Not running"
fi
else
check "Redis" "WARN" "redis-cli not found"
fi
echo ""
echo "=== Configuration Consistency ==="
# Check if frontend API URL matches an available port
if [ -f "$FRONTEND_DIR/.env.development" ]; then
API_URL=$(grep "VITE_API_BASE_URL" "$FRONTEND_DIR/.env.development" | cut -d= -f2)
API_PORT=$(echo "$API_URL" | grep -oE '[0-9]+$')
if [ -n "$API_PORT" ]; then
if lsof -i :$API_PORT 2>/dev/null | grep -q LISTEN; then
# Check if it's our backend
if curl -s "http://localhost:$API_PORT/docs" 2>/dev/null | grep -q "swagger"; then
check "API URL -> Backend" "OK"
else
check "API URL -> Backend" "WARN" "Port $API_PORT in use but not our backend"
fi
else
check "API URL -> Backend" "WARN" "Backend not running on port $API_PORT"
fi
fi
fi
echo ""
echo "=== Summary ==="
if [ $ISSUES -gt 0 ]; then
echo -e "${RED}$ISSUES issue(s) found that need to be fixed${NC}"
exit 1
elif [ $WARNINGS -gt 0 ]; then
echo -e "${YELLOW}$WARNINGS warning(s) - servers may still start${NC}"
exit 0
else
echo -e "${GREEN}All checks passed!${NC}"
exit 0
fi

241
.claude/skills/frontend-phase/SKILL.md Normal file
View File

@ -0,0 +1,241 @@
# Frontend Phase Workflow Skill
Manage the phased frontend development workflow for Mantimon TCG.
## Usage
```
/frontend-phase # Show current phase status and next task
/frontend-phase status # Same as above
/frontend-phase next # Show detailed info about next incomplete task
/frontend-phase start <id> # Mark task as in-progress
/frontend-phase done <id> # Mark task as complete (with tests)
/frontend-phase plan # Create detailed plan for next NOT_STARTED phase
```
## Files
- **Master Plan:** `frontend/PROJECT_PLAN_FRONTEND.json`
- **Phase Plans:** `frontend/project_plans/PHASE_FN_*.json`
## Workflow
### Starting a New Phase
1. Run `/frontend-phase plan` to create the detailed plan for the next NOT_STARTED phase
2. Review and adjust the generated plan
3. Run `/frontend-phase next` to see the first task
### Working on Tasks
1. Run `/frontend-phase next` to see task details
2. Run `/frontend-phase start <task-id>` to mark it in-progress
3. Implement the task following the details in the plan
4. Write tests with docstrings explaining "what" and "why"
5. Run `/frontend-phase done <task-id>` when complete with passing tests
### Completing a Phase
When all tasks are complete:
1. Update master plan status to "COMPLETE"
2. Add completedDate
3. Increment completedPhases count
## Instructions
When `/frontend-phase` or `/frontend-phase status` is invoked:
1. **Read Master Plan**
```
frontend/PROJECT_PLAN_FRONTEND.json
```
2. **Find Current Phase**
- Look for first phase with `status: "in_progress"` or `status: "IN_PROGRESS"`
- If none, look for first phase with `status: "NOT_STARTED"`
3. **Read Phase Plan** (if exists)
```
frontend/project_plans/PHASE_FN_*.json
```
4. **Display Status**
```
## Phase FN: [Phase Name]
Status: IN_PROGRESS
Progress: X/Y tasks complete
### Completed Tasks
- [x] F0-001: Task name
- [x] F0-002: Task name
### Next Task
**F0-003: Task name**
Category: components | Priority: 3
Dependencies: [F0-001, F0-002]
[Brief description from plan]
Run `/frontend-phase next` for full details.
```
---
When `/frontend-phase next` is invoked:
1. Find the first task where `completed: false` and all dependencies are met
2. Display full task details:
```
## F0-003: Task Name
**Category:** components
**Priority:** 3
**Dependencies:** F0-001, F0-002 (all complete)
### Description
[Full description from plan]
### Implementation Details
- Detail 1
- Detail 2
- Detail 3
### Files to Create/Modify
- `src/components/Foo.vue` (create)
- `src/App.vue` (modify)
### Notes
[Any notes from the plan]
---
Run `/frontend-phase start F0-003` to begin work.
```
---
When `/frontend-phase start <task-id>` is invoked:
1. Verify task exists and dependencies are met
2. Log that work is starting (no file modification needed)
3. Display the task details for reference
4. Create Claude Code tasks using TaskCreate if task has multiple sub-items
---
When `/frontend-phase done <task-id>` is invoked:
1. Verify tests exist and pass for the task (run `npm run test`)
2. Update the phase plan JSON:
- Set `completed: true`
- Set `tested: true`
3. Update `completedTasks` count in meta
4. Check if phase is complete (all tasks done)
5. If phase complete, prompt to update master plan
---
When `/frontend-phase plan` is invoked:
1. Find next NOT_STARTED phase in master plan
2. Read existing phase plans for format reference (check `frontend/project_plans/`)
3. Generate detailed plan based on:
- Phase description and deliverables from master plan
- Architecture patterns from `frontend/CLAUDE.md`
- Existing code patterns in the codebase
- Site plan and design system from master plan
4. Create `frontend/project_plans/` directory if it doesn't exist
5. Write to `frontend/project_plans/PHASE_FN_[name].json`
6. Update master plan phase status to "in_progress"
## Task Schema
```json
{
"id": "F0-001",
"name": "Short task name",
"description": "What this task accomplishes",
"category": "setup|components|composables|stores|pages|game|tests|styling",
"priority": 1,
"completed": false,
"tested": false,
"dependencies": ["F0-000"],
"files": [
{"path": "src/components/Foo.vue", "status": "create|modify"}
],
"details": [
"Specific implementation step 1",
"Specific implementation step 2"
],
"estimatedHours": 2,
"notes": "Optional implementation notes"
}
```
## Phase Plan Schema
```json
{
"meta": {
"phaseId": "PHASE_F0",
"name": "Project Foundation",
"version": "1.0.0",
"created": "2026-01-30",
"lastUpdated": "2026-01-30",
"totalTasks": 8,
"completedTasks": 0,
"status": "in_progress"
},
"tasks": [
// Array of task objects
]
}
```
## Categories
Frontend-specific task categories:
| Category | Description |
|----------|-------------|
| `setup` | Project scaffolding, config, tooling |
| `components` | Vue components (UI, cards, game) |
| `composables` | Vue composables (useAuth, useDeck, etc.) |
| `stores` | Pinia stores |
| `pages` | Route page components |
| `game` | Phaser scenes, game objects, animations |
| `tests` | Test files and testing infrastructure |
| `styling` | Tailwind config, CSS, design system |
| `api` | API client, Socket.IO client |
## Rules
1. **Dependencies First** - Never start a task with incomplete dependencies
2. **Tests Required** - Every task must have tests before marking complete
3. **Docstrings Required** - Test docstrings explain "what" and "why"
4. **Commit Approval** - Never commit without user approval
5. **One Task at a Time** - Focus on completing current task before starting next
6. **Update Plans** - Keep plan files in sync with actual progress
7. **Mobile-First** - All UI work follows mobile-first responsive design
8. **TypeScript Strict** - No `any` types, explicit typing required
## Test Command
Before marking a task complete:
```bash
cd frontend && npm run test
cd frontend && npm run lint
cd frontend && npm run typecheck
```
## Memory Integration
After completing a task or phase, consider storing learnings:
```bash
python ~/.claude/skills/memorygraph/client.py store \
--type solution \
--title "Completed PHASE_F0 F0-003" \
--content "Implemented Vue Router with auth guards..." \
--tags "mantimon,frontend,vue-router" \
--importance 0.6
```

6
frontend/.env.development
View File

@ -2,10 +2,10 @@
# These values are used when running `npm run dev`
# Backend API base URL (FastAPI server)
VITE_API_BASE_URL=http://localhost:8000
VITE_API_BASE_URL=http://localhost:8001
# WebSocket URL (Socket.IO server - same as API in development)
VITE_WS_URL=http://localhost:8000
VITE_WS_URL=http://localhost:8001
# OAuth redirect URI (must match OAuth provider configuration)
VITE_OAUTH_REDIRECT_URI=http://localhost:5173/auth/callback
VITE_OAUTH_REDIRECT_URI=http://localhost:3001/auth/callback