HarborForge/plans/hf-cross-project-todo.md

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
• Define canonical code-first lookup policy across all resources
• 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
• 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
• 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

• Initialize Go module for hf
• Add binary entrypoint (cmd/hf/main.go or equivalent)
• Add internal package layout (config, help, mode, passmgr, client, commands)
• Add build instructions to README.md
• Add .gitignore for Go artifacts
• Add repo-config-safe contribution note if needed

1.2 Runtime mode detection

• Implement which pass_mgr detection on startup
• Add runtime mode enum: padded-cell mode / manual mode
• Block manual credential flags in padded-cell mode
• Return exact error when forbidden manual token flags are used:
  • padded-cell installed, --token flag disabled, use command directly
• Define equivalent handling for --acc-mgr-token and related manual secret flags

1.3 Config handling

• Resolve binary directory correctly at runtime
• Read <binary-dir>/.hf-config.json
• Write/update base-url via hf config --url
• Add config validation for malformed/missing config
• Add hf config --acc-mgr-token
• Implement pass_mgr set --public --key hf-acc-mgr-token --secret <token>
• Return exact error on failure:
  • --acc-mgr-token can only be set with padded-cell plugin

1.4 Help system

• Implement hf --help
• Implement hf --help-brief
• Implement <group> --help
• Implement <group> --help-brief
• Implement leaf command --help
• Implement leaf command --help-brief
• Show all subcommands in normal help, marking unavailable ones as (not permitted)
• Hide unavailable commands entirely in --help-brief
• Ensure leaf --help for unavailable commands only prints not permitted
• Hide manual auth flags from help in padded-cell mode
• Show required manual auth flags in help in manual mode
• Handle special help behavior for hf user create

1.5 Auth/token resolution layer

• Implement shared normal token resolution helper
• In padded-cell mode, resolve via pass_mgr get-secret --key hf-token
• In manual mode, require explicit --token
• Emit exact error on missing manual token:
  • --token <token> required or execute this with pcexec
• Ensure hf --help never requires token
• Ensure subcommand help can render even when token is unavailable

1.6 Output model

• Add default human-readable output mode
• Add --json output mode
• Ensure list outputs include canonical resource code fields
• Ensure machine-readable output is stable enough for agent use

1.7 Base commands

• Implement hf version
• Implement hf health

1.8 User commands

• Implement hf user create
• Forbid --token on hf user create
• Do not support --role on hf user create
• Default created accounts to guest
• In padded-cell mode, auto-generate password with:
  • pass_mgr generate --key hf --username <username>
• In padded-cell mode, auto-fetch account-manager token with:
  • pass_mgr get-secret --public --key hf-acc-mgr-token
• Emit exact missing-password error:
  • --pass <password> required or execute with pcexec
• Emit exact missing-account-manager-token error:
  • --acc-mgr-token <token> required or execute with pcexec
• Implement hf user list
• Implement hf user get <username>
• Implement hf user update <username>
• Implement hf user activate <username>
• Implement hf user deactivate <username>
• Implement hf user delete <username>

1.9 Role / permission commands

• Implement hf role list
• Implement hf role get <role-name>
• Implement hf role create
• Implement hf role update
• Implement hf role delete
• Implement hf permission list
• Implement hf role set-permissions
• Implement hf role add-permissions
• Implement hf role remove-permissions

1.10 Project / milestone commands

• Implement hf project list
• Implement hf project get <project-code>
• Implement hf project create
• Implement hf project update <project-code>
• Implement hf project delete <project-code>
• Implement hf project members <project-code>
• Implement hf project add-member <project-code>
• Implement hf project remove-member <project-code>
• Implement hf milestone list --project <project-code>
• Implement hf milestone get <milestone-code>
• Implement hf milestone create
• Implement hf milestone update <milestone-code>
• Implement hf milestone delete <milestone-code>
• Implement hf milestone progress <milestone-code>

1.11 Task commands

• Implement hf task list
• Add filters:
  • --project <project-code>
  • --milestone <milestone-code>
  • --status <status>
  • --taken-by <me|null|username>
  • --due-today <true|false>
  • repeated --order-by <due-date|priority|created|name>
• Implement hf task get <task-code>
• Implement hf task create
• Implement hf task update <task-code>
• Implement hf task transition <task-code> <status>
• Implement hf task take <task-code>
• Return clear error when task is already taken by someone else
• Return clear error when caller lacks permission to take task
• Implement hf task delete <task-code>
• Implement hf task search

1.12 Meeting commands

• Implement hf meeting list
• Implement hf meeting get <meeting-code>
• Implement hf meeting create
• Implement hf meeting update <meeting-code>
• Implement hf meeting attend <meeting-code>
• Ensure attend adds caller to participant list
• Implement hf meeting delete <meeting-code>

1.13 Support commands

• Implement hf support list
• Implement hf support get <support-code>
• Implement hf support create
• Implement hf support update <support-code>
• Implement hf support take <support-code>
• Implement hf support transition <support-code> <status>
• Implement hf support delete <support-code>

1.14 Propose commands

• Implement hf propose list --project <project-code>
• Implement hf propose get <propose-code>
• Implement hf propose create
• Implement hf propose update <propose-code>
• Implement hf propose accept <propose-code> --milestone <milestone-code>
• Implement hf propose reject <propose-code>
• Implement hf propose reopen <propose-code>

1.15 Monitor commands

• Implement hf monitor overview
• Implement hf monitor server list
• Implement hf monitor server get <identifier>
• Implement hf monitor server create --identifier <identifier>
• Implement hf monitor server delete <identifier>
• Implement hf monitor api-key generate <identifier>
• Implement hf monitor api-key revoke <identifier>

1.16 CLI packaging / release

• Add cross-platform build targets if needed
• Add release artifact naming for hf
• Add install documentation
• Add shell examples for padded-cell and manual mode

---

2. HarborForge.Backend

2.1 Code-first API support

• Audit all CLI-targeted resources for code availability
• Ensure project-code is accepted in get/update/delete/member APIs
• Ensure milestone-code is accepted in get/update/delete/progress APIs
• Ensure task-code is accepted in get/update/delete/transition APIs
• Ensure meeting-code is accepted in get/update/delete/attend APIs
• Ensure support-code is accepted in get/update/delete/take/transition APIs
• Ensure propose-code is accepted in get/update/delete/accept/reject/reopen APIs
• Add code-based list filters where missing
• 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

• Add/confirm backend route for task self-assignment (task take)
• Add/confirm conflict behavior when task already has a different assignee
• Add/confirm backend route for meeting attendance (meeting attend)
• Ensure meeting attendance updates participant list
• 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:<MONITOR_PORT>
• 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