AGENTS.md · diff

git:20260910.6f565e0 to git:20261015.51c9478

42 added, 582 removed. Audit A to A.

- # SkillHub — AGENTS.md

- **SkillHub** is an **enterprise-grade, self-hosted agent skill registry** for publishing,

- discovering, and managing reusable skill packages across an organization. It provides a **REST API

- backend**, a **React web UI**, a **security scanner**, and a **ClawHub CLI compatibility layer**.

- ## Quick Reference

- | Item | Value |

- |------------|------------------------------------------------------------|

- | Backend | Spring Boot 3.2.3, Java 21, Maven multi-module (7 modules) |

- | Frontend | React 19, TypeScript, Vite, pnpm |

- | Scanner | Python (FastAPI), port 8000 |

- | Database | PostgreSQL 16 (Flyway migrations) |

- | Cache | Redis 7 (sessions, distributed locks, idempotency) |

- | Storage | LocalFile (dev) / S3/MinIO (prod) |

- | Build | `make dev-all` (dev), `make staging` (pre-PR) |

- | Docs | `docs/` (design), `docs/skillhub/` (VitePress user guide) |

- | CI | GitHub Actions (`.github/workflows/`) |

- ## Directory Map

- ```

- skillhub/

- ├── server/ # Maven multi-module Spring Boot backend

- │ ├── skillhub-app/ # Application layer: bootstrap, controllers, assembly

- │ │ ├── bootstrap/ # Bootstrap admin & local dev data initializers

- │ │ ├── compat/ # ClawHub CLI compatibility layer controllers

- │ │ ├── config/ # Spring configuration classes

- │ │ ├── controller/ # REST controllers (transport only)

- │ │ │ ├── admin/ # Admin controllers (user mgmt, labels, search)

- │ │ │ ├── portal/ # Portal controllers (skills, governance, security)

- │ │ │ └── support/ # Package extractors (zip, multipart)

- │ │ ├── dto/ # Request/response DTOs

- │ │ ├── exception/ # Exception handling

- │ │ ├── filter/ # Servlet filters (auth context, rate limiting)

- │ │ ├── listener/ # Event listeners (notification recipients, etc.)

- │ │ ├── metrics/ # Micrometer metrics

- │ │ ├── projection/ # Lifecycle projection models

- │ │ ├── ratelimit/ # Rate limiting logic

- │ │ ├── repository/ # Query repositories (read-model assembly)

- │ │ ├── security/ # Security configuration

- │ │ ├── service/ # App services (workflow orchestration)

- │ │ ├── stream/ # SSE streaming endpoints

- │ │ ├── task/ # Background task scheduling

- │ │ └── SkillhubApplication.java # Spring Boot entry point

- │ │

- │ ├── skillhub-domain/ # Domain layer: entities, rules, services (innermost)

- │ │ ├── audit/ # AuditLog entity, repository, service

- │ │ ├── auth/ # Password reset entities

- │ │ ├── event/ # Domain event classes (SkillPublishedEvent, etc.)

- │ │ ├── governance/ # Governance notification service

- │ │ ├── idempotency/ # Idempotency records

- │ │ ├── label/ # Skill label management

- │ │ ├── namespace/ # Namespace, members, roles, policies

- │ │ ├── report/ # Skill reporting/governance

- │ │ ├── review/ # Review tasks, promotion requests

- │ │ ├── security/ # Security scanning domain model

- │ │ ├── shared/ # Shared domain utilities

- │ │ │ └── exception/ # Domain exceptions (LocalizedDomainException, etc.)

- │ │ ├── skill/ # Core skill entities and services

- │ │ │ ├── metadata/ # SKILL.md frontmatter parsing

- │ │ │ ├── service/ # Skill domain services (publish, query, governance)

- │ │ │ └── validation/ # Package validation (SkillPackagePolicy, etc.)

- │ │ ├── social/ # Star, rating, subscription entities

- │ │ └── user/ # UserAccount, profile moderation

- │ │

- │ ├── skillhub-auth/ # Authentication & authorization

- │ │ ├── config/ # Spring Security configuration

- │ │ ├── device/ # OAuth Device Flow for CLI auth

- │ │ ├── identity/ # Identity binding service

- │ │ ├── local/ # Local (password) auth

- │ │ ├── merge/ # Account merging

- │ │ ├── oauth/ # OAuth2 login handlers

- │ │ ├── policy/ # Route security policies

- │ │ ├── rbac/ # RBAC service and role definitions

- │ │ ├── token/ # API token management

- │ │ └── user/ # User-related auth services

- │ │

- │ ├── skillhub-search/ # Search SPI + PostgreSQL full-text implementation

- │ │ ├── postgres/ # PostgresFullTextIndexService, QueryService

- │ │ └── service/ # Search SPI interfaces

- │ │

- │ ├── skillhub-storage/ # Object storage SPI

- │ │ ├── local/ # LocalFileStorageService

- │ │ └── s3/ # S3StorageService (AWS SDK v2)

- │ │

- │ ├── skillhub-infra/ # Infrastructure: JPA repos, utilities

- │ │ └── repository/ # Spring Data JPA repository implementations

- │ │

- │ ├── skillhub-notification/ # Notification service (SSE, email)

- │ │ ├── domain/ # Notification domain model

- │ │ ├── service/ # Notification delivery services

- │ │ └── sse/ # SSE endpoint support

- │ │

- │ ├── Dockerfile.dev # Dockerfile for staging builds

- │ ├── Dockerfile # Production multi-stage build

- │ ├── pom.xml # Parent POM (Spring Boot 3.2.3 parent)

- │ └── scripts/

- │ └── run-dev-app.sh # Local dev startup script

- │

- ├── web/ # React frontend (Vite + pnpm)

- │ ├── src/

- │ │ ├── api/ # OpenAPI-generated types + fetch client

- │ │ │ └── generated/

- │ │ │ └── schema.d.ts # Generated OpenAPI types (CHECKED IN)

- │ │ ├── app/ # Router, layout, global providers

- │ │ ├── docs/ # In-app documentation pages

- │ │ ├── entities/ # Domain entity display logic

- │ │ │ ├── skill/ # Skill card, detail components

- │ │ │ ├── user/ # User profile components

- │ │ │ └── namespace/ # Namespace display components

- │ │ ├── features/ # Business feature modules

- │ │ │ ├── admin/ # Admin panel features

- │ │ │ ├── auth/ # Login, OAuth flows

- │ │ │ ├── governance/ # Skill governance actions

- │ │ │ ├── namespace/ # Namespace management

- │ │ │ ├── notification/ # User notifications

- │ │ │ ├── promotion/ # Skill promotion workflows

- │ │ │ ├── publish/ # Skill upload/publish UI

- │ │ │ ├── report/ # Skill reporting

- │ │ │ ├── review/ # Review workflow UI

- │ │ │ ├── search/ # Skill search and filtering

- │ │ │ ├── security-audit/ # Security audit viewer

- │ │ │ ├── skill/ # Skill detail, listing

- │ │ │ ├── social/ # Stars, ratings, subscriptions

- │ │ │ └── token/ # API token management

- │ │ ├── i18n/ # Internationalization

- │ │ ├── pages/ # Route-level page components

- │ │ ├── shared/ # Shared UI, hooks, utilities

- │ │ │ ├── components/ # Reusable UI components

- │ │ │ ├── hooks/ # Custom React hooks

- │ │ │ ├── lib/

- │ │ │ │ └── utils.ts # cn() class merging utility

- │ │ │ └── ui/ # Radix UI-based primitives

- │ │ └── types/ # Additional TypeScript types

- │ ├── e2e/ # Playwright E2E tests

- │ ├── nginx.conf.template # Nginx runtime config template

- │ ├── Dockerfile # Multi-stage build (Node → Nginx)

- │ └── package.json # Dependencies (React 19, TanStack Query, Radix UI, etc.)

- │

- ├── scanner/ # Security scanner (Python/FastAPI)

- │ ├── docs/ # Scanner documentation

- │ ├── examples/ # Example scan inputs/outputs

- │ └── Dockerfile # Scanner container build

- │

- ├── docs/ # Design documents (source of truth)

- │ ├── prds/ # Product requirement documents

- │ ├── skillhub/ # VitePress user guide source

- │ └── superpowers/ # Internal tooling docs

- │

- ├── deploy/k8s/ # Kubernetes manifests (basic)

- ├── monitoring/ # Prometheus + Grafana stack

- ├── scripts/ # Build, test, and deployment scripts

- │ ├── smoke-test.sh # Basic API smoke test

- │ ├── namespace-smoke-test.sh # Namespace workflow smoke test

- │ ├── governance-smoke-test.sh # Governance flow smoke test

- │ ├── promotion-smoke-test.sh # Promotion flow smoke test

- │ ├── check-openapi-generated.sh # Verify OpenAPI SDK is not stale

- │ ├── validate-release-config.sh # Validate release env configuration

- │ ├── dev-process.sh # Local process manager (PID-based)

- │ ├── runtime.sh # Runtime deployment script

- │ ├── parallel-init.sh # Parallel worktree initialization

- │ ├── parallel-sync.sh # Merge worktrees in integration branch

- │ ├── parallel-up.sh # Merge + start dev environment

- │ ├── parallel-down.sh # Stop parallel dev environment

- │ └── prepare-pr-batch.sh # Batch PR preparation

- │

- ├── .github/

- │ ├── workflows/ # GitHub Actions CI/CD

- │ ├── ISSUE_TEMPLATE/ # Issue templates

- │ └── scripts/ # Deno scripts for triage, release notes, rewards

- │

- ├── AGENTS.md # AI agent rules (this file)

- ├── .agents/skills/ # Focused AI skill definitions

- ├── Makefile # Top-level build/test/dev orchestration

- ├── docker-compose.yml # Local dev dependency services

- ├── compose.release.yml # Production release compose file

- ├── CONTRIBUTING.md # Contribution guidelines

- ├── CODE_OF_CONDUCT.md # Community standards

- └── README.md # Project overview

- ```

- **Key Locations for Common Tasks:**

- | Task | Where to Look |

- |------|---------------|

- | Add REST endpoint | `server/skillhub-app/src/main/java/com/iflytek/skillhub/controller/` |

- | Add domain entity/service | `server/skillhub-domain/src/main/java/com/iflytek/skillhub/domain/` |

- | Add auth logic | `server/skillhub-auth/src/main/java/com/iflytek/skillhub/auth/` |

- | Add search logic | `server/skillhub-search/src/main/java/com/iflytek/skillhub/search/` |

- | Add query repository | `server/skillhub-app/src/main/java/com/iflytek/skillhub/repository/` |

- | Change RBAC/roles | `server/skillhub-auth/src/main/java/com/iflytek/skillhub/auth/rbac/` |

- | Change skill validation | `server/skillhub-domain/src/main/java/com/iflytek/skillhub/domain/skill/validation/` |

- | Add frontend page | `web/src/pages/` |

- | Add frontend feature | `web/src/features/` |

- | Add shared component | `web/src/shared/components/` |

- | Change API contract | Backend controller → run `make generate-api` → commit generated file |

- | Add smoke test | `scripts/` (new `.sh` file) |

- | Add E2E test | `web/e2e/` (Playwright) |

- | Add backend test | `server/skillhub-*/src/test/java/` (alongside source module) |

- ## Critical Rules

- ### Do Not Manually Edit Generated Files

- - `web/src/api/generated/schema.d.ts` — regenerated via `make generate-api`

- - `server/skillhub-app/src/main/java/com/iflytek/skillhub/dto/` — some DTOs may be generated

- ### After Making Changes

- **Backend changes:**

- - Edit Java code → `make dev-server-restart` (local dev)

- - Add/modify controller → `make generate-api` to regenerate frontend types

- - Add/modify domain service → `make test-backend-app` to verify tests

- **Frontend changes:**

- - Edit TypeScript/React → Vite HMR handles reload automatically

- - After `make generate-api` → commit updated `web/src/api/generated/schema.d.ts`

- **Always run before PR:**

- ```bash

- make test-backend-app # Backend tests (with dependent modules)

- make typecheck-web # Frontend type check

- make lint-web # Frontend lint

- make staging # Full staging regression + smoke test

- ```

- ### File-Specific Requirements

- - **Controllers** (`skillhub-app/controller/`) are transport only: extract auth context,

- bind request params, wrap responses. No business logic.

- - **App Services** (`skillhub-app/service/`) orchestrate workflows. Do not embed complex

- read-model assembly here — extract to query repositories.

- - **Query Repositories** (`skillhub-app/repository/`) handle read-model joins and presentation

- projection. Named like `*QueryRepository`.

- - **Domain Services** (`skillhub-domain/*/service/`) contain business rules and state transitions.

- Return domain objects, not DTOs.

- - **Repository Interfaces** are defined in `skillhub-domain`, implemented in `skillhub-infra`.

- - **Domain Exceptions** use `LocalizedDomainException` for user-facing messages with i18n keys.

- - **Package-info files** (`package-info.java`) should exist for all packages.

- ## Development Workflow

- ### Build & Start

- ```bash

- make dev-all # Start full stack: Postgres, Redis, MinIO, backend, frontend

- make dev-all-down # Stop everything

- make dev-all-reset # Full reset (clears data volumes)

- make dev-status # Check service status

- make dev-server-restart # Restart backend after Java changes

- ```

- **Access points:**

- - Web UI: `http://localhost:3000`

- - Backend API: `http://localhost:8080`

- - Scanner: `http://localhost:8000`

- **Local mock users** (no password needed):

- | 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** (password-based, local profile):

- - Username: `admin` / Password: `ChangeMe!2026`

- - Disable with `BOOTSTRAP_ADMIN_ENABLED=false`

- ### Lint & Format

- ```bash

- # Backend: enforced by Maven build (no separate lint target)

- # Frontend:

- make lint-web # ESLint check

- make typecheck-web # TypeScript check

- ```

- ### Testing

- ```bash

- make test-backend-app # Backend unit tests (skillhub-app + dependencies)

- make test-backend # All backend module tests

- make test-frontend # Frontend unit tests (Vitest)

- make test-e2e-frontend # Frontend E2E tests (Playwright)

- make test-e2e-smoke-frontend # Frontend E2E smoke tests

- ./scripts/smoke-test.sh # API smoke test

- make namespace-smoke # Namespace workflow smoke test

- ```

- ### Staging (Pre-PR Regression)

- ```bash

- make staging # Build backend Docker image + frontend static + smoke test

- make staging-down # Tear down

- SERVICE=web make staging-logs # View Nginx logs

- ```

- Staging validates the containerized deployment path:

- - Backend: built as Docker image from local source

- - Frontend: built as static files, served by Nginx

- - Dependencies: same Postgres/Redis/MinIO as local dev

- ### Parallel Agent Workflow

- For parallel development with isolated worktrees:

- ```bash

- make parallel-init TASK=feature-name

- ```

- Creates dedicated Claude, Codex, and integration worktrees as sibling directories.

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

- ## PR Submission

- ### PR Title Format

- Use conventional commit style:

- ```

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

- ```

- **Types:**

- - `feat`: New feature

- - `fix`: Bug fix

- - `docs`: Documentation changes

- - `test`: Adding or updating tests

- - `refactor`: Code restructuring (no behavior change)

- - `chore`: Build, CI, or maintenance tasks

- **Scopes:** Module or domain name (e.g., `auth`, `search`, `publish`, `review`, `namespace`)

- **Examples:**

- ```

- feat(auth): add local account login

- fix(publish): resolve null pointer in skill validation

- docs(deploy): clarify runtime image usage

- test(namespace): add membership service tests

- refactor(review): extract query repository for governance list

- chore(ci): add parallel workflow scripts

- ```

- ### Pre-PR Checklist

- - [ ] Backend tests pass: `make test-backend-app`

- - [ ] Frontend typecheck passes: `make typecheck-web`

- - [ ] If API changed: `make generate-api` was run and `web/src/api/generated/schema.d.ts` is committed

- - [ ] Smoke test passes: `make staging`

- - [ ] Follow existing module boundaries and dependency direction

- - [ ] Add/update tests for new behavior

- - [ ] Update docs when APIs, auth flows, deployment, or operator workflows change

- ## Core Concepts

- ### Backend Clean Architecture

- ```

- app → domain, auth, search, storage, infra, notification

- infra → domain # implements domain repository interfaces

- auth → domain

- search → domain

- notification → domain

- storage → (independent) # pure SPI

- ```

- **Design intent**: `skillhub-domain` is the innermost layer. It defines entities, repository

- interfaces, and domain services without depending on infra, auth, search, or storage.

- **Code reality**: `skillhub-domain` declares a Maven dependency on `skillhub-storage`, and several

- domain services (`SkillHardDeleteService`, `SkillDownloadService`, `SkillPublishService`,

- `SkillGovernanceService`, `SkillQueryService`, `SkillStorageDeletionCompensationService`) import

- `com.iflytek.skillhub.storage.ObjectStorageService`. This is an existing deviation from the ideal.

- New code should avoid adding further cross-module dependencies from domain.

- ### Repository / Query Boundary

- When adding new read logic, follow these rules:

- 1. **Domain repository ports** (`skillhub-domain`): Aggregate reads, state transitions, rule

- evaluation. Used by domain services.

- 2. **App query repositories** (`com.iflytek.skillhub.repository`): Read-model assembly that joins

- multiple sources, presentation projection. Used by controllers and app services.

- 3. **App services** (`com.iflytek.skillhub.service`): Workflow orchestration. Should express "what

- this endpoint does", not "how it assembles DTOs".

- 4. **Direct SQL / EntityManager**: Only when necessary, with class-level comment explaining why.

- **Do not** add complex read-model assembly logic inside app services. Extract it into a query

- repository when it joins multiple sources, does presentation projection, or is reused across services.

- ### Skill Lifecycle

- `SkillVersionStatus` values: `DRAFT`, `SCANNING`, `SCAN_FAILED`, `UPLOADED`, `PENDING_REVIEW`,

- `PUBLISHED`, `REJECTED`, `YANKED`.

- `SkillStatus` enum values: `ACTIVE`, `HIDDEN`, `ARCHIVED`.

- The design doc (`docs/14-skill-lifecycle.md`) specifies that `hidden` should be treated as a

- governance overlay rather than a lifecycle state. The current code still defines

- `SkillStatus.HIDDEN` in the enum. Follow the design doc's intent for new code.

- **Key transitions:**

- - Normal user first upload → `PENDING_REVIEW` (no initial DRAFT)

- - SUPER_ADMIN first upload → `PUBLISHED` (direct publish)

- - Review approve → `PENDING_REVIEW` → `PUBLISHED` (updates `latestVersionId`)

- - Review reject → `PENDING_REVIEW` → `REJECTED`

- - Withdraw review → `PENDING_REVIEW` → `UPLOADED` (also deletes pending review_task)

- - Yank → `PUBLISHED` → `YANKED` (must recalculate `latestVersionId`)

- - Hide/restore → independent `hidden` flag (governance overlay)

- - Archive/Unarchive → `ACTIVE` ↔ `ARCHIVED` (container state)

- ### Namespace Coordinate System

- SkillHub uses `@{namespace_slug}/{skill_slug}`:

- - `@global/my-skill` — Platform-level public namespace

- - `@my-team/my-skill` — Team/department namespace

- ClawHub CLI compatibility maps:

- | SkillHub | Canonical Slug |

- |----------|---------------|

- | `@global/my-skill` | `my-skill` |

- | `@team-name/my-skill` | `team-name--my-skill` |

- ### Authentication

- - Web: OAuth2 (GitHub) + local password auth

- - CLI: OAuth Device Flow (web authorization → CLI credentials)

- - Programmatic: API tokens (prefix-based secure hashing)

- - Session: Spring Session + Redis

- ### RBAC

- Platform roles: `SUPER_ADMIN`, `SKILL_ADMIN`, `USER_ADMIN`, `AUDITOR`

- Namespace roles: `OWNER`, `ADMIN`, `MEMBER`

- ### Skill Package Protocol

- - Root: `SKILL.md` with YAML frontmatter (`name`, `description` required)

- - Allowed extensions (50+ types): `.md`, `.txt`, `.json`, `.yaml`, `.yml`, `.js`, `.ts`, `.py`,

- `.sh`, `.png`, `.jpg`, `.svg`, and many more (see `SkillPackagePolicy.ALLOWED_EXTENSIONS`)

- - Limits: 10MB per file, 100MB total, 500 files max

- - File type signatures validated (PNG magic bytes, SVG content check, etc.)

- ### Frontend State Management

- - **TanStack Query** (`@tanstack/react-query`): All server state (API data)

- - **Zustand**: Local/UI state (theme, sidebar, modals)

- - **Never** use `useEffect` for data fetching

- ### Frontend Component Composition

- - **Radix UI** primitives: `@radix-ui/react-dropdown-menu`, `@radix-ui/react-select`

- - **class-variance-authority** (cva) for component variants

- - **clsx** + **tailwind-merge** for class merging

- - **`cn()` utility**: `web/src/shared/lib/utils.ts`

- - shadcn/ui is NOT used as a library — only Radix primitives + utility composition

- ## Common Patterns

- ### Code Style

- **Java:**

- - User identity type is always `String` throughout the codebase

- - Use Java 21 features (records, pattern matching, virtual threads)

- - Follow existing naming patterns in the domain layer

- - Error strings for `DomainBadRequestException`, etc. should be clear and actionable

- **TypeScript:**

- - Strict mode. No `any` types.

- - Use generated OpenAPI types for all API interactions.

- - Feature-Sliced Design: place code at the lowest appropriate layer.

- ### Testing Philosophy

- - Backend: JUnit 5 + Mockito + AssertJ

- - Frontend: Vitest for unit tests, Playwright for E2E

- - **Use `make test-backend-app`** (includes `-am` for dependent modules) — never run

- `./mvnw -pl skillhub-app clean test` directly, as it can use stale Maven cache artifacts

- - Test behaviors, not implementations

- - Use Spring Boot test slices where possible (`@WebMvcTest`, `@DataJpaTest`)

- ### Frontend Testing

- ```bash

- make test-frontend # Vitest unit tests

- make test-e2e-frontend # Playwright E2E

- make test-e2e-smoke-frontend # Playwright smoke (subset of E2E)

- ```

- ### Logging Conventions

- - **Backend**: SLF4J + Spring Boot logging. Use structured logging with MDC for request tracing.

- - **Frontend**: `console.error` for errors, `console.warn` for deprecations, avoid `console.log` in production code.

- - **Scanner**: Python logging module with structured JSON output.

- ### Security

- - API tokens are stored as prefix-based secure hashes, never in plaintext

- - OAuth2 client secrets and other secrets must not be logged or committed

- - User identity is `String` (supports external SSO/OIDC/SCIM identity sources)

- - The bootstrap admin (`BOOTSTRAP_ADMIN_ENABLED`) is for zero-config quickstart only

- ## Search Tips

- ```bash

- # Find all REST endpoints

- rg "@(Get|Post|Put|Delete|Patch)Mapping" --type java

- # Find domain services

- rg "class.*Service" server/skillhub-domain/

- # Find query repositories

- rg "QueryRepository" server/skillhub-app/

- # Find controllers

- rg "@RestController" server/skillhub-app/

- # Find RBAC role checks

- rg "@PreAuthorize" server/skillhub-app/

- # Find skill validation logic

- rg "SkillPackage" server/skillhub-domain/

+ # SkillHub — Agent Entry

- # Find frontend features

- rg "export" web/src/features/

+ SkillHub includes a Java backend, React web UI, CLI and security-scanning integration.

+ Read [README](./README.md) for setup and [CONTRIBUTING](./CONTRIBUTING.md) for contributions.

- # Find OpenAPI type generation script

- rg "generate-api" web/package.json

+ ## Read before changing code

- # Find event listeners

- rg "@EventListener" server/

- ```

+ 1. Start with [.trellis/spec/index.md](./.trellis/spec/index.md).

+ 2. Read only the applicable domain index and the topic documents selected by the change.

+ 3. Implementation and review use the same applicable contracts; add the testing guidance for verification.

+ 4. Read actual source, tests, schemas and scripts before treating documentation as implemented behavior.

+ Report conflicts and known deviations; do not silently redefine business policy.

- ## Design Philosophy

+ | Change | Entry |

+ |---|---|

+ | Frontend UI, state, requests, types | [Frontend](./.trellis/spec/frontend/index.md) |

+ | Backend modules, APIs, persistence, scanning | [Backend](./.trellis/spec/backend/index.md) |

+ | Tests, CI, acceptance | [Testing](./.trellis/spec/testing/index.md) |

+ | Configuration, containers, release, migrations | [Deployment](./.trellis/spec/deployment/index.md) |

+ | CLI | [CLI](./.trellis/spec/cli/index.md) |

+ | Development, PR, completion | [Workflow](./.trellis/spec/workflow/index.md) |

+ | Reuse or cross-layer decisions | [Thinking guides](./.trellis/spec/guides/index.md) |

- - **Hub first**: The server-side registry is the core product; CLI and agent integrations are entry capabilities

- - **Compatibility first**: Support `SKILL.md` format and common directory conventions

- - **Layered architecture**: Search and object storage must have replaceable boundaries (SPI pattern)

- - **Open authentication**: OAuth2-based, extensible to multiple providers beyond GitHub

- - **Audit first**: Enterprise distribution requires audit trails for publish, download, delete, and authorization

+ ## Work proportionately

- ## References

+ - Small edits: read relevant rules, edit and verify; do not require a task record.

+ - Multi-step work: use a task record for requirements, context, progress and verification, respecting an existing user choice not to create one.

+ - Large requirements or architecture changes: OpenSpec owns formal requirements and design; Trellis organizes execution and continuation.

+ - Reference existing authoritative documents instead of maintaining duplicate rules.

+ - Each worktree owns its task records. Tracked specs follow the checked-out branch; local template updates are explicit and must not silently overwrite them.

- ### Essential Files

- - **`Makefile`** — All build/test/dev automation targets

- - **`CONTRIBUTING.md`** — Contribution guidelines and commit style

- - **`CODE_OF_CONDUCT.md`** — Community standards

- - **`server/pom.xml`** — Maven parent POM, module definitions, dependency versions

- - **`web/package.json`** — Frontend dependencies and scripts

- - **`.github/workflows/pr-tests.yml`** — PR test pipeline

- - **`.github/workflows/publish-images.yml`** — Docker image publish to GHCR

+ ## Verification and delivery

- ### Key Directories

- - **`server/skillhub-domain/`** — Core domain (entities, services, rules)

- - **`server/skillhub-app/controller/`** — REST API endpoints

- - **`server/skillhub-app/repository/`** — Query repositories

- - **`server/skillhub-app/compat/`** — ClawHub CLI compatibility layer

- - **`server/skillhub-auth/`** — Authentication and authorization

- - **`web/src/features/`** — Frontend feature modules

- - **`web/src/api/generated/`** — Generated OpenAPI types

- - **`docs/`** — Design documents

- - **`scripts/`** — Build, test, and deployment scripts

+ Choose checks using the [change-impact matrix](./.trellis/spec/testing/index.md).

+ Start with focused feedback; broaden for shared behavior, public interfaces, configuration and integration changes.

+ Documentation-only changes require relevant document/source checks, not starting the application stack.

+ Report passed, failed, not-run and environment-blocked checks separately.

+ A build, unit test, screenshot or static configuration check is not proof of deployment or end-to-end behavior.

- ### Important Scripts

- - **`scripts/smoke-test.sh`** — Basic API smoke test

- - **`scripts/namespace-smoke-test.sh`** — Namespace workflow test

- - **`scripts/check-openapi-generated.sh`** — Verify frontend SDK is current

- - **`scripts/validate-release-config.sh`** — Validate production env config

- - **`scripts/dev-process.sh`** — Local process manager (PID-based lifecycle)

- - **`scripts/parallel-init.sh`** — Create isolated worktrees for parallel development

+ Use the existing Makefile and package tooling. Do not hand-edit generated OpenAPI types.

+ Read commands before execution: staging and schema-drift checks may start/stop services.

+ Preserve unrelated changes; do not commit, push, publish, deploy or remove worktrees without authorization.

+ Do not commit or log credentials; do not reset data to make verification pass.

- ### Design Documents

- - **`00-product-direction.md`** — Product positioning, MVP scope, coordinate system

- - **`01-system-architecture.md`** — System architecture, module structure, dependency rules

- - **`02-domain-model.md`** — Domain entities and relationships

- - **`03-authentication-design.md`** — OAuth2, CLI Device Flow, API tokens

- - **`04-search-architecture.md`** — Search SPI and implementations

- - **`05-business-flows.md`** — Business process flows

- - **`06-api-design.md`** — API contract specifications

- - **`07-skill-protocol.md`** — SKILL.md format, package structure, CLI compatibility

- - **`08-frontend-architecture.md`** — Frontend patterns and conventions

- - **`14-skill-lifecycle.md`** — Skill state model (authoritative)

- - **`dev-workflow.md`** — Local development workflow guide

+ ## Sources and maintenance

- ### External Resources

- - **SkillHub Docs**: https://iflytek.github.io/skillhub/

- - **DeepWiki**: https://deepwiki.com/iflytek/skillhub

- - **Discord**: https://discord.gg/qHYvtDNPHS

- - **OpenSkills**: https://agents.md/ (skill package format reference)

- - **OpenClaw**: https://github.com/openclaw/openclaw (CLI compatibility)

- - **AstronClaw**: https://agent.xfyun.cn/astron-claw (cloud AI assistant integration)

+ - Engineering conventions: [.trellis/spec/](./.trellis/spec/index.md).

+ - Architecture, business semantics and operations: [docs/](./docs/), including [lifecycle](./docs/14-skill-lifecycle.md).

+ - Formal changes: [OpenSpec workflow](./.trellis/spec/workflow/openspec.md).

+ - Versions, commands and current behavior: dependency manifests, Makefile, schemas, source and tests.

+ - Only `.trellis/spec/` is shared in Git. Tasks, runtime state and personal Trellis tooling remain local.

+ - Execution Skills may help run a workflow; they do not own a second copy of project conventions.

+ - Preserve and verify existing task records before authorized cleanup; see [archive requirements](./.trellis/spec/workflow/task-archive.md).