9.2 KiB
spec, created, status
| spec | created | status |
|---|---|---|
| docs/specs/office/requirements/agents.md | 2026-07-22 | implemented |
Implementation Plan: Office Agent Project Management
Overview
Make the default Office setup task executable by giving authorized Office agents a run-scoped project list/create surface, exposing it through $KANDEV_CLI, and allowing created follow-up tasks to carry project_id. Separately replace the generic Kanban tool inventory injected into Office turns with an exact Office capability context. This plan does not add workspace creation or expose Kanban completion tools to Office.
Corrective follow-up: an Office-only prompt and CLI must never be launched without the scheduler-created signed runtime environment. Generic task/session start paths fail closed for Office-owned tasks when that context is absent, and the CLI/public docs explain that its API URL and key are automatic Office run credentials rather than user configuration.
Backend
Run-scoped project capability
Files:
apps/backend/internal/office/shared/permissions.goapps/backend/internal/office/runtime/capabilities.goapps/backend/internal/office/runtime/actions.goapps/backend/internal/office/runtime/handler.goapps/backend/internal/office/routes.goapps/backend/internal/office/agents/service.goapps/backend/internal/office/service/agents.go
Changes:
- Add
can_create_projects, defaulting to true only for the CEO role. - Add stable
list_projectsandcreate_projectruntime capability keys; listing is available to Office roles, while creation derives fromcan_create_projects. - Add
GET /api/v1/office/runtime/projectsandPOST /api/v1/office/runtime/projectsthroughruntime.Handler. - Add
create_taskplusPOST /api/v1/office/runtime/tasks, derived fromcan_create_tasks; force caller/workspace from the run token and validate project, parent, and assignee ownership before persistence. - Reuse
projects.ProjectServicethrough a narrow runtime dependency interface. Forceworkspace_idfrom the validated run context; never accept it from the request body. - Emit the existing
runtime.action/runtime.deniedaudit events.
Agent CLI
Files:
apps/backend/cmd/agentctl/kandev.goapps/backend/cmd/agentctl/kandev_projects.goapps/backend/cmd/agentctl/kandev_task.goapps/backend/cmd/agentctl/kandev_test.go
Changes:
- Add
projects listandprojects createcommand dispatch. projects createrequires--name; supports repeatable--repositoryplus optional description, lead profile, color, budget, and executor JSON; sends the run token to the runtime endpoint.- Add
--descriptionand--projecttotask create, serialize them through the authenticated Office runtime endpoint, and preserve parent/assignee assignment. Unsupported priority, blocker, and workspace-policy fields fail explicitly. - Keep workspace creation absent: every mutation is scoped by the signed run token;
KANDEV_WORKSPACE_IDis context only and is never trusted for authorization.
Office capability context and skill
Files:
apps/backend/config/prompts/office-context.mdapps/backend/internal/sysprompt/sysprompt.goapps/backend/internal/sysprompt/sysprompt_test.goapps/backend/internal/orchestrator/task_operations.goapps/backend/internal/mcp/server/sysprompt_sync_test.goapps/backend/internal/office/configloader/skills/kandev-projects/SKILL.mdapps/backend/internal/office/skills/system_sync_test.go
Changes:
- Add an Office-specific first-turn context containing exactly the nine
ModeOfficetools and directing Office mutations to$KANDEV_CLI. - Select that context before launching an Office MCP session; keep the existing task context for
ModeTask. - Add a
kandev-projectssystem skill, default for CEOs, documenting list/create and task-project assignment. - Cross-check advertised Office tool names against the registered
ModeOfficeinventory. Assert thatstep_complete_kandevis absent.
Office launch-context invariant
Files:
apps/backend/internal/orchestrator/task_operations.goapps/backend/internal/orchestrator/task_operations_test.go
Changes:
- Validate the minimum, task-bound Office runtime environment before any
LaunchPreparedSessioncall selectsModeOffice. - Fail before starting the agent when a generic/manual/workflow path reaches an
Office-owned task without scheduler-provided
KANDEV_CLI,KANDEV_API_URL,KANDEV_API_KEY, agent/workspace identity, and run ID. - Reject generic Office resume and prepared-workspace relaunch paths; Office recovery must return to the scheduler so it can mint fresh runtime context.
- Preserve scheduler launches through
StartTaskWithEnvand keep regular task-mode launches unchanged.
CLI context diagnostics
Files:
apps/backend/cmd/agentctl/kandev_client.goapps/backend/cmd/agentctl/kandev_test.go
Changes:
- Replace the bare missing-variable error with an actionable explanation that the values are injected automatically for Office runs.
- Direct regular task sessions to their Kandev MCP tools without suggesting users manufacture or persist an Office JWT.
Frontend
No UI behavior changes. The existing onboarding wizard, project pages, and permission metadata renderer consume the backend contracts. The new permission must appear automatically through the existing permission metadata response.
Tests
- What: CEO runtime context can list/create projects; a worker is denied creation; request workspace input cannot escape the token workspace.
File:
apps/backend/internal/office/runtime/actions_test.go,apps/backend/internal/office/runtime/handler_test.goHow: table-driven action tests and HTTP handler tests with signed runtime JWTs. - What: role defaults and overrides include
can_create_projectswithout changing existing permissions. File:apps/backend/internal/office/shared/permissions_test.goHow: table-driven permission resolution tests. - What: CLI commands use the runtime endpoints, serialize repeatable repositories, reject missing names, and include
project_idand the established Office assignee identifier on task creation without trusting caller-selected workspace scope. File:apps/backend/cmd/agentctl/kandev_test.goHow: in-memory request capture plus signed runtime/SQLite persistence tests for relation ownership and runner assignment. - What: Office prompt inventory equals
ModeOfficeregistration and excludes all Kanban/config tools, especiallystep_complete_kandev. File:apps/backend/internal/mcp/server/sysprompt_sync_test.goHow: extract_kandevreferences and compare exact sets. - What: the default CEO receives the project skill after system-skill synchronization.
File:
apps/backend/internal/office/skills/system_sync_test.goHow: sync embedded skills into SQLite and assert role defaults/content. - What: onboarding's default setup brief is executable through the advertised Office CLI/tool surface.
File:
apps/backend/internal/office/onboarding/service_test.goHow: contract test against required setup mutations and capability catalog. - What: Office-owned tasks cannot start in
ModeOfficewithout a complete scheduler-provided runtime environment, while scheduler and regular task-mode launches retain their existing behavior. File:apps/backend/internal/orchestrator/task_operations_test.goHow: focused orchestrator launch tests with captured executor requests. - What: invoking the CLI outside an Office run returns actionable,
non-secret-bearing guidance.
File:
apps/backend/cmd/agentctl/kandev_test.goHow: run the command with the two required variables unset and assert the structured error and zero HTTP dispatch.
E2E Tests
No new browser interaction is introduced. The runtime handler integration and CLI request-capture tests exercise the user-visible agent path without adding a brittle model-driven E2E.
Implementation Waves
Wave 1 (parallel):
Wave 2:
Wave 3:
Wave 4 (parallel):
Wave 5:
Verification Commands
rtk make -C apps/backend fmt
cd apps/backend && rtk go test ./internal/office/runtime ./internal/office/shared ./internal/office/skills ./internal/office/onboarding
cd apps/backend && rtk go test ./cmd/agentctl ./internal/mcp/server ./internal/sysprompt ./internal/orchestrator
rtk make -C apps/backend lint
rtk make -C apps/backend test
node --test scripts/validate-public-docs.test.mjs
node scripts/validate-public-docs.mjs
Open Questions
None. The approved corrective contract fails generic manual/workflow Office launches before process start instead of minting a second, unaudited credential class or silently granting the broader task-mode MCP surface.