Agent Skills › iflytek/skillhub › dev-workflow

dev-workflow

GitHub

提供 SkillHub 项目的完整开发工作流，涵盖本地环境搭建、测试执行、预发布验证及 PR 创建。通过 Makefile 命令标准化前后端开发、调试和部署流程，确保贡献者遵循正确步骤。

.agents/skills/dev-workflow/SKILL.md iflytek/skillhub

Trigger Scenarios

启动本地开发环境运行单元测试或 E2E 测试准备提交 Pull Request 设置开发依赖和工具链

Install

npx skills add iflytek/skillhub --skill dev-workflow -g -y

More Options

Non-standard path

npx skills add https://github.com/iflytek/skillhub/tree/main/.agents/skills/dev-workflow -g -y

Use without installing

npx skills use iflytek/skillhub@dev-workflow

指定 Agent (Claude Code)

npx skills add iflytek/skillhub --skill dev-workflow -a claude-code -g -y

安装 repo 全部 skill

npx skills add iflytek/skillhub --all -g -y

预览 repo 内 skill

npx skills add iflytek/skillhub --list

SKILL.md

Frontmatter

{
    "name": "dev-workflow",
    "license": "Apache-2.0",
    "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."
}

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:

Health endpoint (/actuator/health → 200)
Prometheus metrics (/actuator/prometheus → 200)
Namespaces API (/api/v1/namespaces → 200)
Auth required (/api/v1/auth/me → 401 without session)
User registration flow (with CSRF)
Auth me with session
Password change
Logout + verify 401 after
Admin login
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