Development Workflow Skill

Trigger

Use this skill when:

• Starting local development
• Running tests or validation
• Preparing a pull request
• Setting up the development environment
• Working with parallel agent worktrees

Prerequisites

• Java 21+ (java -version)
• Maven wrapper (./mvnw in server/)
• Node.js + pnpm
• Docker + docker compose
• gh CLI (for PR creation)
• curl (for smoke tests and health checks)

Workflow Stages

Stage 1: Local Development (fast iteration)

One-command start:

make dev-all          # Start full stack: Postgres, Redis, MinIO, scanner, backend, frontend
make dev-all-down     # Stop everything
make dev-all-reset    # Full reset (clears data volumes)
make dev-status       # Check service status

Access points:

• Web UI: http://localhost:3000
• Backend API: http://localhost:8080
• Scanner: http://localhost:8000

Individual components:

make dev              # Start dependency services only (Postgres, Redis, MinIO, scanner)
make dev-server       # Start backend in foreground (blocking)
make dev-web          # Start Vite dev server (HMR enabled)
make dev-server-restart # Restart backend process
make dev-down         # Stop dependency services
make dev-logs         # View backend logs (use SERVICE=frontend for frontend logs)

Backend development: After editing Java code, run make dev-server-restart.

Frontend development: Vite HMR enabled — save a file for instant browser updates.

Scanner: The security scanner is enabled by default in dev. Health checked at http://localhost:8000/health.

Stage 2: Testing

Command	Scope	Notes
make test-backend-app	Backend unit tests	skillhub-app + dependencies (-am)
make test-backend	All backend modules	All modules via ./mvnw test
make test-frontend	Frontend unit tests	Vitest (pnpm run test)
make test-e2e-frontend	Frontend E2E tests	Playwright
make test-e2e-smoke-frontend	Frontend E2E smoke	Playwright subset
make typecheck-web	TypeScript type check	tsc --noEmit
make lint-web	ESLint check	Frontend linting

Important: Never run ./mvnw -pl skillhub-app clean test directly under server/. Use -am or Makefile targets to include dependent modules.

Stage 3: Staging Regression (pre-PR validation)

make staging          # Build backend Docker image + frontend static + smoke test
make staging-down     # Tear down
make staging-logs     # View backend logs
SERVICE=web make staging-logs  # View Nginx logs

Staging validates the containerized deployment path:

• Backend: built as Docker image from local source (Dockerfile.dev)
• Frontend: built as static files (pnpm build), served by Nginx
• Dependencies: same Postgres/Redis/MinIO as local dev
• Smoke test runs against staging via scripts/smoke-test.sh

Staging URLs:

• Web UI: http://localhost
• Backend API: http://localhost:8080

Staging credentials (for bootstrap admin):

• Username: admin
• Password: Admin@staging2026

Stage 4: Pull Request

make pr               # Push branch + create PR (requires gh CLI)

Requirements:

• gh CLI installed and authenticated
• Not on main/master branch
• All changes committed (will prompt if uncommitted changes exist)

Useful Commands

Command	Description
make generate-api	Regenerate OpenAPI types from running backend
make namespace-smoke	Namespace workflow smoke test
make db-reset	Reset database only (Flyway migrate)
make validate-release-config	Validate release env vars (.env.release)
./scripts/smoke-test.sh	Basic API smoke test (health, auth, labels)
./scripts/namespace-smoke-test.sh	Namespace CRUD + membership smoke test
./scripts/check-openapi-generated.sh	Verify OpenAPI types are not stale
make parallel-init TASK=name	Create parallel worktree for agent

Mock Auth Users

User ID	Role	Header
local-user	Regular user	X-Mock-User-Id: local-user
local-admin	Super admin	X-Mock-User-Id: local-admin

Bootstrap admin (local profile):

• Username: admin
• Password: ChangeMe!2026

Smoke Test Coverage

scripts/smoke-test.sh validates:

1. Health endpoint (/actuator/health → 200)
2. Prometheus metrics (/actuator/prometheus → 200)
3. Namespaces API (/api/v1/namespaces → 200)
4. Auth required (/api/v1/auth/me → 401 without session)
5. User registration flow (with CSRF)
6. Auth me with session
7. Password change
8. Logout + verify 401 after
9. Admin login
10. Label CRUD (admin only)

Additional smoke tests:

• scripts/namespace-smoke-test.sh — Namespace creation, membership, publishing
• scripts/governance-smoke-test.sh — Governance and moderation
• scripts/promotion-smoke-test.sh — Skill promotion between scopes

Parallel Agent Workflow

For parallel agent development with isolated worktrees:

make parallel-init TASK=feature-name           # Create worktree
make parallel-sync SOURCES="feat1 feat2"       # Merge feature branches
make parallel-up SOURCES="feat1 feat2"         # Merge + start dev environment
make parallel-down                             # Stop parallel environment

See docs/13-parallel-workflow.md for full details.

Commit Style

Use conventional commit format:

<type>(<scope>): <description>

Examples:

feat(auth): add local account login
fix(publish): resolve null pointer when skill metadata is missing name
docs(deploy): clarify runtime image usage
test(namespace): add membership service edge case tests
refactor(review): extract query repository for governance list
chore(ci): add parallel workflow scripts

Common Issues

Issue	Solution
Backend won't start	Check Java version (java -version), must be 21+
Port 8080 in use	lsof -i :8080 to find and kill the process
Maven download timeout	Configure mirror in ~/.m2/settings.xml
Frontend won't start	Run make web-deps to ensure node_modules exist
Staging build fails	Check Dockerfile.dev and ensure Maven build succeeds first
CSRF errors in tests	Ensure cookie jar is shared and CSRF token refreshed after login