// The complete development workflow for SkillHub contributors including local dev, staging validation, testing, and PR creation. Ensures agents follow the correct sequence of steps.
API design conventions, namespace coordinate system, RBAC roles, ClawHub compatibility layer, OpenAPI contract sync rules, and CSRF/session handling.
Rules for the SkillHub backend Maven multi-module clean architecture. Ensures agents place new code in the correct module and respect dependency direction.
Code style, logging, and testing conventions for SkillHub backend (Java) and frontend (TypeScript). Use when writing or reviewing code.
Coding conventions, architecture patterns, and testing rules for the SkillHub React frontend. Ensures agents follow Feature-Sliced Design and use the generated OpenAPI types.
PR title format, commit conventions, and pre-PR checklist for SkillHub. Use when preparing or reviewing pull requests.
The authoritative skill lifecycle state model including container states, version states, review workflow states, visibility overlay, and governance actions. Ensures agents don't introduce invalid states or transitions.
| name | dev-workflow |
| description | The complete development workflow for SkillHub contributors including local dev, staging validation, testing, and PR creation. Ensures agents follow the correct sequence of steps. |
| license | Apache-2.0 |
Use this skill when:
java -version)./mvnw in server/)gh CLI (for PR creation)curl (for smoke tests and health checks)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:
http://localhost:3000http://localhost:8080http://localhost:8000Individual 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.
| 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.
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:
Dockerfile.dev)pnpm build), served by Nginxscripts/smoke-test.shStaging URLs:
http://localhosthttp://localhost:8080Staging credentials (for bootstrap admin):
adminAdmin@staging2026make pr # Push branch + create PR (requires gh CLI)
Requirements:
gh CLI installed and authenticated| 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 |
| 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):
adminChangeMe!2026scripts/smoke-test.sh validates:
/actuator/health → 200)/actuator/prometheus → 200)/api/v1/namespaces → 200)/api/v1/auth/me → 401 without session)Additional smoke tests:
scripts/namespace-smoke-test.sh — Namespace creation, membership, publishingscripts/governance-smoke-test.sh — Governance and moderationscripts/promotion-smoke-test.sh — Skill promotion between scopesFor 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.
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
| 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 |