Huabu

# GitHub Copilot Instructions

- **Docs-First Workflow**: `docs/architecture/` is the source of truth for how each subsystem works. **Before implementing a feature or refactor, read the relevant `docs/architecture/*.md`** (start from `docs/README.md`) to understand the current design, then act. **After changing architecture, behaviour, or a documented contract, update the matching doc in the same change** — fold shipped behavior into `docs/architecture/`, keep formally reviewed designs under `docs/proposals/` with a lifecycle `Status:` header, keep uncommitted ideas under `docs/backlog/`, and reserve `docs/archive/` for abandoned or superseded designs. Never leave a doc describing code that no longer exists.
- **Tracked File Moves**: Always use `git mv` when moving or renaming files already tracked by Git. Do not recreate a tracked file at a new path and delete the original as separate filesystem operations.
- **Code Comments**: Always use English for all code comments and documentation, regardless of the user's language.
- **Documentation**: Ensure all generated documentation strings (JSDoc, TSDoc, etc.) are in English.
- **Markdown Formatting**: In Markdown files (docs, prompts, READMEs) write **one line per paragraph** (soft-wrap) — do not hard-wrap prose at ~80 columns. Let the editor wrap; only insert a real line break to start a new paragraph or list item. Tables, code blocks, and ASCII diagrams are exempt.
- **Common UI Primitives**: Before creating UI elements, inspect `apps/web/src/components/Common` and use or extend a suitable component. Treat each component's exported props and implementation as its current contract. Always use `<Button>` instead of a custom native `<button>`; use `<TextInput>` for styled text-like form controls; reserve the low-level `<Input>` for intentionally caller-styled inputs. Native inputs remain appropriate for non-text controls such as checkbox, radio, range, color, and file inputs. Keep feature-specific UI colocated when it is only used by that feature.
- **Reuse Before Implementing**: Before adding or changing hooks, helpers, services, business logic, or non-trivial components, search for existing similar implementations first. Prefer reusing, extending, or extracting shared code over creating parallel implementations with slightly different behavior. For implementation tasks, briefly mention what was reused or why a new canonical implementation was necessary.
- **Filesystem Path Safety**: Resolve untrusted path segments with `resolveDirectChildPath()` or `safeJoin()` from `apps/server/src/utils/fs.ts`; never rely on filename sanitization, direct path construction, or ad hoc checks. These helpers use CodeQL-recognized `path.resolve` and root-prefix validation.
- **Pre-PR CI Checks**: Before handing a pull request off for review, run the repository-level `pnpm typecheck`, `pnpm format`, and `pnpm lint:fix` scripts. Review and commit any formatter or linter changes, then rerun validation affected by those changes.
- **API Endpoints**: When adding or modifying any HTTP / SSE endpoint (route file, web `api/*.ts` helper, or shared wire type), follow the rules in `docs/architecture/api-design.md`. In particular: define the contract once in `packages/shared/src/types/api/*` (zod schema + `z.infer` type), validate every server input via `safeParse`, never define wire types inside `apps/server` or `apps/web`, and keep the web bundle zod-free by importing schemas as `import type` only.
- **Color Usage**: Always use the semantic design tokens defined in `apps/web/src/index.css` — never use raw hex values, Tailwind default palette colors (e.g., `gray-500`, `blue-600`), or ShadCN aliases (`bg-card`, `text-muted-foreground`) in new components. Use `text-fg-default` / `text-fg-muted` / `text-fg-subtle` for text, `bg-surface` / `bg-bg-default` / `bg-hover` / `bg-inverse` for backgrounds, `text-fg-inverse` for text on dark surfaces, `border-edge-default` for borders, and status tokens (`text-info`, `text-danger`, `text-success`, `text-warning`) for semantic states. Treat the token declarations in `apps/web/src/index.css` as the source of truth.
- **External Subtree Commits**: `external/agentlet/` and `external/agenetes/` are git subtrees that are pushed back to their own upstream repositories (remotes `agentlet-upstream` and `agenetes-upstream`). When a change touches a subtree and Huabu-only files, always create **separate commits** — one per subtree (so it can be cleanly pushed upstream) and another for the rest.