# hf / HarborForge Cross-Project TODO > Scope: HarborForge.Cli, HarborForge.Backend, HarborForge.Frontend, HarborForge.OpenclawPlugin, HarborForge.Monitor, HarborForge.Test > > Goal: land the new `hf` CLI and the supporting backend/frontend/plugin/monitor changes described in the main CLI plan. --- ## 0. Cross-cutting / coordination - [ ] Finalize MVP scope for first shipping version of `hf` - [ ] Confirm which existing backend routes can be reused vs which new routes are needed - [x] Define canonical code-first lookup policy across all resources - [x] Define permission introspection strategy for `--help` / `--help-brief` - settled as: token → current user → user role → role permissions - `hf user create` remains a special account-manager-token flow and is not gated by ordinary user-token write permission - [x] Define JSON output contract for CLI list/get commands - current CLI contract: `--json` emits raw success payloads on stdout without a universal envelope; list/get responses should preserve canonical code-bearing fields when backend payloads provide them - [x] Define CLI exit code / stderr conventions - current CLI contract: success exits `0`; validation/runtime failures exit `1`; errors go to stderr and successful output goes to stdout - [ ] Define local plugin↔monitor communication protocol over `monitor_port` - [ ] Define release order across submodules - [ ] Define rollback strategy if plugin / monitor bridge is unavailable > Note: the CLI contract items above are now documented from the currently implemented `HarborForge.Cli` behavior; they can still be refined later if a stricter release contract is needed. --- ## 1. HarborForge.Cli ### 1.1 Go project scaffold - [x] Initialize Go module for `hf` - [x] Add binary entrypoint (`cmd/hf/main.go` or equivalent) - [x] Add internal package layout (`config`, `help`, `mode`, `passmgr`, `client`, `commands`) - [x] Add build instructions to `README.md` - [x] Add `.gitignore` for Go artifacts - [ ] Add repo-config-safe contribution note if needed ### 1.2 Runtime mode detection - [x] Implement `which pass_mgr` detection on startup - [x] Add runtime mode enum: padded-cell mode / manual mode - [x] Block manual credential flags in padded-cell mode - [x] Return exact error when forbidden manual token flags are used: - [x] `padded-cell installed, --token flag disabled, use command directly` - [x] Define equivalent handling for `--acc-mgr-token` and related manual secret flags ### 1.3 Config handling - [x] Resolve binary directory correctly at runtime - [x] Read `/.hf-config.json` - [x] Write/update `base-url` via `hf config --url` - [x] Add config validation for malformed/missing config - [x] Add `hf config --acc-mgr-token` - [x] Implement `pass_mgr set --public --key hf-acc-mgr-token --secret ` - [x] Return exact error on failure: - [x] `--acc-mgr-token can only be set with padded-cell plugin` ### 1.4 Help system - [x] Implement `hf --help` - [x] Implement `hf --help-brief` - [x] Implement ` --help` - [x] Implement ` --help-brief` - [x] Implement leaf command `--help` - [x] Implement leaf command `--help-brief` - [x] Show all subcommands in normal help, marking unavailable ones as `(not permitted)` - [x] Hide unavailable commands entirely in `--help-brief` - [x] Ensure leaf `--help` for unavailable commands only prints `not permitted` - [x] Hide manual auth flags from help in padded-cell mode - [x] Show required manual auth flags in help in manual mode - [x] Handle special help behavior for `hf user create` ### 1.5 Auth/token resolution layer - [x] Implement shared normal token resolution helper - [x] In padded-cell mode, resolve via `pass_mgr get-secret --key hf-token` - [x] In manual mode, require explicit `--token` - [x] Emit exact error on missing manual token: - [x] `--token required or execute this with pcexec` - [x] Ensure `hf --help` never requires token - [x] Ensure subcommand help can render even when token is unavailable ### 1.6 Output model - [x] Add default human-readable output mode - [x] Add `--json` output mode - [x] Ensure list outputs include canonical resource code fields - [x] Ensure machine-readable output is stable enough for agent use ### 1.7 Base commands - [x] Implement `hf version` - [x] Implement `hf health` ### 1.8 User commands - [x] Implement `hf user create` - [x] Forbid `--token` on `hf user create` - [x] Do not support `--role` on `hf user create` - [x] Default created accounts to `guest` - [x] In padded-cell mode, auto-generate password with: - [x] `pass_mgr generate --key hf --username ` - [x] In padded-cell mode, auto-fetch account-manager token with: - [x] `pass_mgr get-secret --public --key hf-acc-mgr-token` - [x] Emit exact missing-password error: - [x] `--pass required or execute with pcexec` - [x] Emit exact missing-account-manager-token error: - [x] `--acc-mgr-token required or execute with pcexec` - [x] Implement `hf user list` - [x] Implement `hf user get ` - [x] Implement `hf user update ` - [x] Implement `hf user activate ` - [x] Implement `hf user deactivate ` - [x] Implement `hf user delete ` ### 1.9 Role / permission commands - [x] Implement `hf role list` - [x] Implement `hf role get ` - [x] Implement `hf role create` - [x] Implement `hf role update` - [x] Implement `hf role delete` - [x] Implement `hf permission list` - [x] Implement `hf role set-permissions` - [x] Implement `hf role add-permissions` - [x] Implement `hf role remove-permissions` ### 1.10 Project / milestone commands - [x] Implement `hf project list` - [x] Implement `hf project get ` - [x] Implement `hf project create` - [x] Implement `hf project update ` - [x] Implement `hf project delete ` - [x] Implement `hf project members ` - [x] Implement `hf project add-member ` - [x] Implement `hf project remove-member ` - [x] Implement `hf milestone list --project ` - [x] Implement `hf milestone get ` - [x] Implement `hf milestone create` - [x] Implement `hf milestone update ` - [x] Implement `hf milestone delete ` - [x] Implement `hf milestone progress ` ### 1.11 Task commands - [x] Implement `hf task list` - [x] Add filters: - [x] `--project ` - [x] `--milestone ` - [x] `--status ` - [x] `--taken-by ` - [x] `--due-today ` - [x] repeated `--order-by ` - [x] Implement `hf task get ` - [x] Implement `hf task create` - [x] Implement `hf task update ` - [x] Implement `hf task transition ` - [x] Implement `hf task take ` - [x] Return clear error when task is already taken by someone else - [x] Return clear error when caller lacks permission to take task - [x] Implement `hf task delete ` - [x] Implement `hf task search` ### 1.12 Meeting commands - [x] Implement `hf meeting list` - [x] Implement `hf meeting get ` - [x] Implement `hf meeting create` - [x] Implement `hf meeting update ` - [x] Implement `hf meeting attend ` - [x] Ensure attend adds caller to participant list - [x] Implement `hf meeting delete ` ### 1.13 Support commands - [x] Implement `hf support list` - [x] Implement `hf support get ` - [x] Implement `hf support create` - [x] Implement `hf support update ` - [x] Implement `hf support take ` - [x] Implement `hf support transition ` - [x] Implement `hf support delete ` ### 1.14 Propose commands - [x] Implement `hf propose list --project ` - [x] Implement `hf propose get ` - [x] Implement `hf propose create` - [x] Implement `hf propose update ` - [x] Implement `hf propose accept --milestone ` - [x] Implement `hf propose reject ` - [x] Implement `hf propose reopen ` ### 1.15 Monitor commands - [x] Implement `hf monitor overview` - [x] Implement `hf monitor server list` - [x] Implement `hf monitor server get ` - [x] Implement `hf monitor server create --identifier ` - [x] Implement `hf monitor server delete ` - [x] Implement `hf monitor api-key generate ` - [x] Implement `hf monitor api-key revoke ` ### 1.16 CLI packaging / release - [ ] Add cross-platform build targets if needed - [ ] Add release artifact naming for `hf` - [x] Add install documentation - [x] Add shell examples for padded-cell and manual mode --- ## 2. HarborForge.Backend ### 2.1 Code-first API support - [x] Audit all CLI-targeted resources for code availability - [x] Ensure `project-code` is accepted in get/update/delete/member APIs - [x] Ensure `milestone-code` is accepted in get/update/delete/progress APIs - [x] Ensure `task-code` is accepted in get/update/delete/transition APIs - [x] Ensure `meeting-code` is accepted in get/update/delete/attend APIs - [x] Ensure `support-code` is accepted in get/update/delete/take/transition APIs - [x] Ensure `propose-code` is accepted in get/update/delete/accept/reject/reopen APIs - [x] Add code-based list filters where missing - [x] Ensure CLI-related list payloads always include canonical code fields ### 2.2 User / account-manager flow - [ ] Review current `account-manager` permission implementation - [ ] Add dedicated backend flow for account-manager-based account creation if current `/users` route is insufficient - [ ] Ensure `hf user create` maps cleanly to backend account-manager permission model - [ ] Ensure new accounts default to `guest` - [ ] Ensure admin role cannot be assigned through normal user management APIs ### 2.3 Permission introspection for CLI help - [ ] Decide how CLI will query effective permissions - [ ] Add/extend backend endpoint(s) for current-user permission introspection if needed - [ ] Ensure CLI can cheaply determine whether a subcommand is permitted - [ ] Support permission-aware help rendering without excessive API chattiness ### 2.4 Task / meeting / support actions - [x] Add/confirm backend route for task self-assignment (`task take`) - [x] Add/confirm conflict behavior when task already has a different assignee - [x] Add/confirm backend route for meeting attendance (`meeting attend`) - [x] Ensure meeting attendance updates participant list - [x] Add/confirm backend route for support self-assignment (`support take`) ### 2.5 Frontend-facing code migration support - [ ] Add code-based detail endpoints or code query support for frontend routing - [ ] Ensure frontend can resolve resources by code without fallback to id-only APIs - [ ] Update serializers to expose code prominently wherever applicable ### 2.6 Legacy Python CLI retirement - [ ] Track parity between new `hf` CLI and old backend Python CLI - [ ] Once parity is acceptable, remove legacy Python CLI from backend repo - [ ] Remove backend docs referencing the old Python CLI --- ## 3. HarborForge.Frontend ### 3.1 Code-first UI migration - [ ] Audit current routes and identify every place still using raw ids - [ ] Move project detail lookup toward `project-code` - [ ] Move milestone detail lookup toward `milestone-code` - [ ] Move task detail lookup toward `task-code` - [ ] Move meeting detail lookup toward `meeting-code` - [ ] Move support detail lookup toward `support-code` - [ ] Move propose detail lookup toward `propose-code` - [ ] Stop surfacing raw ids as the main visible identifier in lists/details - [ ] Display codes consistently in relevant list and detail views ### 3.2 User / role UX alignment - [ ] Review current user management page against final backend behavior - [ ] Ensure only code/name-first identifiers are shown where relevant - [ ] Ensure account role display matches single-role model everywhere ### 3.3 Meeting / support UI - [ ] Audit current frontend support for meeting resources - [ ] Add/adjust UI for meeting participant state if needed - [ ] Add/adjust UI for support take/ownership state if needed ### 3.4 Monitor UI alignment - [ ] Ensure monitor views expose server identifier/code cleanly - [ ] Review display of OpenClaw/plugin metadata once Monitor bridge is implemented ### 3.5 Future CLI alignment aids - [ ] Consider showing canonical codes more prominently to help users map UI↔CLI - [ ] Ensure copyable resource codes are easy to find from the UI --- ## 4. HarborForge.OpenclawPlugin ### 4.1 Plugin identity and packaging - [ ] Rename plugin registration name to `harbor-forge` - [ ] Audit all docs/config/install references to old plugin name - [ ] Ensure plugin config keys and examples reflect the new registration name ### 4.2 Remove sidecar architecture - [ ] Remove plugin-side `server/` telemetry sidecar - [ ] Remove sidecar startup/shutdown lifecycle logic - [ ] Remove sidecar-specific docs and examples - [ ] Replace old OpenClaw telemetry flow with direct plugin-exposed data path ### 4.3 Plugin config updates - [ ] Add `monitor_port` to plugin config schema - [ ] Document `monitor_port` in plugin README/docs/examples - [ ] Ensure runtime reads and validates `monitor_port` ### 4.4 CLI install support - [ ] Add install script flag `--install-cli` - [ ] Resolve OpenClaw profile bin directory (default `~/.openclaw/bin`) - [ ] Build `HarborForge.Cli` - [ ] Install compiled `hf` binary to profile `bin/` - [ ] `chmod +x` installed binary - [ ] Handle failure cases cleanly if CLI build/install fails ### 4.5 Skills deployment - [ ] Add plugin `skills/` directory - [ ] Add `skills/hf/` - [ ] Add `skills/hf/SKILL.md` - [ ] In `SKILL.md`, explain basic `hf` usage - [ ] In `SKILL.md`, encourage agents to use `hf --help-brief` - [ ] In `SKILL.md`, point to normal `--help` for full command tree - [ ] Installer should copy normal plugin skills into profile `skills/` - [ ] Installer should **not** copy `skills/hf/` unless `--install-cli` is present - [ ] Installer should copy `skills/hf/` when `--install-cli` is present ### 4.6 Monitor bridge endpoint - [ ] Define how plugin exposes OpenClaw metadata to Monitor over local port - [ ] Decide HTTP endpoint structure / payload schema - [ ] Expose OpenClaw version - [ ] Expose plugin version - [ ] Expose agent list / agent metadata - [ ] Ensure plugin remains functional even if Monitor never connects --- ## 5. HarborForge.Monitor ### 5.1 Docker/runtime changes - [ ] Add `MONITOR_PORT` env var - [ ] Ensure Monitor listens on `127.0.0.1:` - [ ] Update Docker runtime docs/examples - [ ] Update docker-compose to expose that port to host `127.0.0.1` ### 5.2 Plugin communication - [ ] Implement local communication client to query plugin over `MONITOR_PORT` - [ ] Define request timeout / retry / fallback policy - [ ] Keep startup independent of plugin communication success - [ ] Keep heartbeat/telemetry upload independent of plugin communication success - [ ] If plugin is reachable, enrich telemetry with: - [ ] OpenClaw version - [ ] plugin version - [ ] agent info - [ ] If plugin is unreachable, continue current behavior unchanged ### 5.3 Telemetry model alignment - [ ] Ensure backend-facing telemetry payloads can carry optional OpenClaw metadata - [ ] Avoid making plugin-derived fields mandatory - [ ] Ensure monitor data model cleanly distinguishes: - [ ] host/hardware telemetry - [ ] optional OpenClaw metadata ### 5.4 Docs / examples - [ ] Update Monitor README to explain `MONITOR_PORT` - [ ] Explain degraded mode when plugin bridge is absent - [ ] Provide example Docker run / compose snippet with host loopback exposure --- ## 6. HarborForge.Test / HarborForge.Frontend.Test ### 6.1 Keep test runner aligned - [ ] Preserve Frontend.Test Dockerfile as owner of proxy startup - [ ] Keep `run-test-frontend.sh` from overriding default test container CMD unless strictly necessary - [ ] Keep expose-port mode working with 127.0.0.1 + proxy architecture ### 6.2 Code-first frontend test updates - [ ] Update tests to prefer resource codes over ids in assertions and navigation - [ ] Remove assumptions that UI surfaces raw ids where codes should be primary ### 6.3 Future CLI tests - [ ] Add tests for `hf` help rendering - [ ] Add tests for `hf --help-brief` - [ ] Add tests for padded-cell mode vs manual mode - [ ] Add tests for exact stderr messages - [ ] Add tests for code-only command acceptance --- ## 7. Suggested implementation order ### Phase A — Foundations - [ ] Finalize CLI help / mode / output model - [ ] Finalize backend permission introspection approach - [ ] Finalize plugin↔monitor local protocol ### Phase B — Backend first - [ ] Add/finish code-based backend support - [ ] Add/finish task take / meeting attend / support take - [ ] Add any missing account-manager creation behavior ### Phase C — CLI MVP - [ ] Build `hf` scaffold - [ ] Ship `version`, `health`, `config` - [ ] Ship `user create`, `user list`, `user get` - [ ] Ship `task list`, `task get`, `task take` - [ ] Ship initial `monitor` commands ### Phase D — Frontend alignment - [ ] Move frontend to code-first lookup/display - [ ] Surface canonical codes consistently in UI ### Phase E — Plugin / Monitor integration - [ ] Rename plugin to `harbor-forge` - [ ] Remove plugin sidecar - [ ] Add `--install-cli` - [ ] Add `skills/hf` - [ ] Add `monitor_port` / `MONITOR_PORT` bridge ### Phase F — Cleanup / retirement - [ ] Remove legacy backend Python CLI - [ ] Update all docs to point to `hf` - [ ] Add final tests and packaging flow