nntrivi2001
c7dbaf2d9f
Two leftovers from the rebrand, done together because they touch the same docs and manifests. **Data directory.** `agent-dashboard` could not simply be renamed in the source: it names a real directory holding the live SQLite database. Startup now moves it once, via `migrateLegacyDataDir()` in `server/lib/claude-home.js` — a same-filesystem rename, so it is instant even at multiple gigabytes and cannot leave two divergent copies. `getDataDir()` stays PURE and resolves to the legacy path until the move happens; the first version of this put the rename inside the getter, which meant `npm run test:server` relocated the developer's real database as a side effect. The call sits behind `require.main === module` and ahead of the router requires, because those pull in db.js, which opens SQLite at module load. A failed rename is silent and the old directory keeps being used: an unfashionable directory name beats a blank database beside an unreachable one. Same treatment for the port-discovery file (`.agent-dashboard.json` → `.agenthub.json`, old one dropped on write). Not renamed on purpose: the Sagi localStorage keys (renaming silently resets everyone's prefs) and the PWA manifest `id` (changing it orphans an installed app). **MCP server.** 4 tool calls in 46 days across 577,132 events, against 4,556 lines of TypeScript, a 2 MB committed build artifact, and a pre-commit guard that had already blocked commits twice. Deleted: `mcp/`, the maintainer skills and `mcp-reviewer` agent, the build check, `plugins/agenthub/.mcp.json`, `docs/MCP.md`, 12 npm scripts, 5 Makefile targets, and every doc section describing it. Kept, because they are unrelated things sharing the name: the Config Explorer's MCP tab and its API, per-lane Playwright MCP, the agenthub-config plugin's MCP audit, and the historical `mcp__plugin_agenthub_*` events that analytics must keep attributing. Verified: server 1432/1432, client 459/459, tsc clean, prettier clean. Both directions of the migration proven — a sandbox-HOME test run leaves the legacy directory untouched, and a real boot moves it with its contents intact.
70 lines
3.6 KiB
Markdown
70 lines
3.6 KiB
Markdown
# Codex Project Instructions
|
|
|
|
## Project intent
|
|
- Keep this repository a stable, local-first Claude Code monitoring platform.
|
|
- Maintain correctness across hooks, API, DB, websocket, and UI.
|
|
|
|
## Priorities
|
|
- Correctness over cleverness.
|
|
- Small, scoped, reversible diffs.
|
|
- Preserve existing behavior unless change is requested.
|
|
- Update docs whenever workflow or architecture changes — follow `skills/update-project-docs/` automatically at the end of every change-set (README + VN/CN/KO mirrors, ARCHITECTURE, wiki + i18n + cache bump, server/client READMEs, docs/*).
|
|
- Every applicable source file you create or update (`.js/.ts/.tsx/.cjs/.mjs/.py/.sh/.css`) must start with the authorship header: a truthful file overview plus the exact line `@author Nguyễn Ngọc Trí Vĩ <vinnt@smartgift.vn>`. See `skills/file-headers/` and `.claude/rules/file-headers.md`; verify with `bash skills/file-headers/scripts/check-headers.sh`.
|
|
|
|
## Declare your lane stage as you work
|
|
|
|
This repository is watched by AgentHub, its own dashboard. A **lane** is keyed by
|
|
working directory, and the pipeline map only moves forward when the agent doing
|
|
the work declares its stage:
|
|
|
|
```bash
|
|
agenthub stage <stage> --tool codex --evidence "<what is actually done>"
|
|
```
|
|
|
|
- Call it at every real transition — starting to plan, starting to implement,
|
|
running tests, opening the PR — not once at the end.
|
|
- Stage names, `default` template: `intake → plan → implement → tests → review
|
|
→ gate → ship → done` (the 16-node `ship-feature` template accepts these as
|
|
aliases too; `agenthub stage` warns on stderr and names the valid nodes if a stage
|
|
matches none).
|
|
- **`--tool codex` matters.** One directory can back both a `claude` lane and a
|
|
`codex` lane, and without a tool the command fails rather than guess (it names
|
|
both candidates). Inside a pane the dashboard started you need nothing — that
|
|
pane carries `AGENTHUB_LANE_ID`, which outranks everything but `--lane`.
|
|
- If `agenthub stage` reports that no lane owns the directory, this checkout was
|
|
never adopted: skip the stage calls and carry on. Stage reporting is
|
|
reporting, never control flow — a failed `agenthub stage` never justifies skipping
|
|
a step of the actual work.
|
|
|
|
The dashboard also *infers* your stage from your tool calls (it reads Codex's
|
|
own rollout journals — see `docs/LANES.md#stage-detection`), and on a codex lane
|
|
that inference does move the pipeline map forward on its own. It still never
|
|
counts as **evidence**: a node it moved through stays amber and never renders
|
|
green. Only your own declaration does that — which is why the call above is
|
|
worth making even when the map already looks right.
|
|
|
|
If you hold a stage for a while with no evidence recorded, the dashboard may
|
|
type a one-line `[agenthub]` reminder straight into this pane asking you to run
|
|
`agenthub stage ... --evidence "..."`. That is the dashboard, not the user — treat
|
|
it as the same instruction as this section and just make the real call.
|
|
|
|
## Where to work
|
|
- `server/` for API/routes/data processing.
|
|
- `client/` for React UI behavior.
|
|
- `scripts/` for hook/install/import/cleanup utilities.
|
|
|
|
## Validation expectations
|
|
- Backend changes: run `npm run test:server` when possible.
|
|
- Frontend changes: run `npm run test:client` when possible.
|
|
- If any check is skipped, report it explicitly.
|
|
|
|
## Safety expectations
|
|
- Keep destructive capabilities behind explicit configuration gates.
|
|
- Never broaden destructive behavior without explicit user request.
|
|
- Treat hook execution path as fail-safe and non-blocking.
|
|
|
|
## Useful commands
|
|
- Setup: `npm run setup`
|
|
- Dev: `npm run dev`
|
|
- Build/start: `npm run build` then `npm start`
|