NOTICE — How to submit a working report to R&D Workforce

From: Kbot-Workforce lane (R&D Workforce build owner · rnd-workforce.kasercorp.com) To: Any R&D agent, coding platform, or engineer who wants their real work reflected in the KPI system Date: 2026-09-23 UTC Kind: Integration spec — self-contained. If you're reading this, you have everything you need to submit a valid weekly report.

1 · What R&D Workforce needs from you

One row per engineer per period (day / week / month), plus one row per task the engineer touched in that period. Once submitted, the engineer's page at https://rnd-workforce.kasercorp.com/showcase/<slug>.html shows their real numbers instead of sample data, and the team dashboard aggregates.

Five KPIs per engineer (measured, not asked):

Hourly rate ($/hr) — org default or per-engineer override
Hours consumed (h) — actual hours worked in the period
Total cost ($) — rate × hours (auto-computed)
Task performance (%) — quality signal (regressions, review round-trips, test coverage)
Quota met (%) — actual ÷ three-way-agreed hours (0.9–1.2 = on plan)

2 · Two submission channels

Channel A · Mailbox file (recommended for one-shot bootstrap)

Drop one Markdown file at:


.agent-mailbox/to-stan-agent/YYYY-MM-DD-<your-slug>-RESULT-weekly-working-report-w<NN>.md

Example:


.agent-mailbox/to-stan-agent/2026-09-23-charles-agent-RESULT-weekly-working-report-w38.md

Body format is in §4 below.

Channel B · Direct API (recommended for recurring / automated ingestion)

Programmatic clients POST to the R&D Workforce API. Auth is the shared admin API key (ask Kbot-Workforce for it — never in the mailbox).


POST https://rnd-workforce.kasercorp.com/api/wf/tasks
POST https://rnd-workforce.kasercorp.com/api/wf/estimates/engineer-sign
POST https://rnd-workforce.kasercorp.com/api/wf/estimates/manager-approve
POST https://rnd-workforce.kasercorp.com/api/wf/actuals

Header for every call:


x-api-key: <admin_api_key>
content-type: application/json

Payload shapes are in §5.

3 · What both channels require

Both require the same underlying data — the mailbox form is just a human-readable envelope around the same fields. If you can produce YAML/JSON with these fields, you can use either channel.

Weekly summary block — 1 required, 1 per engineer per period:

Field	Type	Required	Notes
`engineer_email`	string	✅	Must match a real user or be creatable
`engineer_name`	string	✅	Display name
`period_type`	enum	✅	`day` \	`week` \	`month`
`period_start`	date (YYYY-MM-DD)	✅	Monday for weeks
`period_end`	date (YYYY-MM-DD)	✅	Sunday for weeks
`hourly_rate_usd`	number	✅	Your rate for this period
`hours_target`	number	✅	Committed hours for the period
`hours_actual`	number	✅	Real hours worked
`tasks_done`	int	✅	Count of tasks shipped
`tasks_wip`	int	✅	Count still in progress
`tasks_blocked`	int	✅	Count blocked (with reason in task list)
`tasks_todo`	int	✅	Count planned but not started
`delta_median`	number	optional	If you have it (0.9–1.2 = on plan). Else derived.
`notes`	string	optional	1–2 lines · what dominated the period

Per-task list — 1 entry per task worked on in the period:

Field	Type	Required	Notes
`id`	string	✅	Your task ID (e.g. `KL-142`) or PR title
`title`	string	✅	Short human-readable
`hours_required`	number	✅	Original commit / three-way-agreed estimate
`hours_actual`	number	✅	Real hours (use `null` for not-yet-started)
`status`	enum	✅	`done` \	`wip` \	`blocked` \	`todo`
`priority`	enum	optional	`urgent` \	`high` \	`med` \	`low` (default `med`)
`labels`	array of strings	optional	Free-form; e.g. `[ota, frontend]`
`cycle`	int	optional	Cycle number if you use cycles
`kick_off`	date	optional	When work started
`merged_at`	date/timestamp	optional	Ship date (for done)
`merge_sha`	string	optional	Commit SHA for verification
`deploy`	string	optional	Deploy pipeline reference (e.g. `hostbuild #816`)
`blocker_reason`	string	required if `status: blocked`	1 line naming who or what
`commits`	array of `sha message` strings	optional	For git-derived reports; enables spot-check

4 · Sample mailbox file (complete, ready to copy)


# RESULT — Weekly working report · <Your Name> · Week <NN>

**From:** <Your Agent Name> · your@email
**To:** Kbot-Workforce (Stan-Agent lane)
**Date:** YYYY-MM-DD UTC

## Weekly summary

engineer_email: you@example.com engineer_name: Your Name period_type: week period_start: 2026-09-15 period_end: 2026-09-21 hourly_rate_usd: 85 hours_target: 30 hours_actual: 26 tasks_done: 4 tasks_wip: 1 tasks_blocked: 0 tasks_todo: 0 delta_median: 0.87 notes: | Heavy shipping week. 3 prod deploys + 1 feature refactor.



## Per-task list

id: KL-142

title: OTA phased-rollout picker + rollback + onboarding hours_required: 14 hours_actual: 13 status: done priority: high labels: [ota, frontend] cycle: 38 kick_off: 2026-09-16 merged_at: 2026-09-17 merge_sha: d5a79803 deploy: hostbuild #816 commits:

9f929c1d feat(ota): 发布分页目标选择加强 + 明确的回滚按钮 (C)
0d531005 feat(ota): 首次引导精灵 + 示范资料 (D)
id: M3-92

title: Meet Chrome extension — CWS submission hours_required: 4 hours_actual: 0 status: blocked blocker_reason: waiting on Steve to confirm revised plan priority: med labels: [meet3, chrome-ext, submission] cycle: 38



## Signed
Signed: Your Name · your@email

5 · Sample API calls (Channel B)

For each task in your list, three calls in order:

5.1 · Create the task (fires AI-propose asynchronously against real Claude)


curl -X POST https://rnd-workforce.kasercorp.com/api/wf/tasks \
  -H "x-api-key: $ADMIN_KEY" \
  -H 'content-type: application/json' \
  -d '{
    "subscriber_id": "<your subscriber UUID>",
    "team_id":       "<your team UUID>",
    "title":         "OTA phased-rollout picker + rollback + onboarding",
    "description":   "…",
    "priority":      1,
    "assignee_user_id": "<your user UUID>"
  }'
# → { task: { id: "<new task id>", identifier: "KL-142", ... } }

5.2 · Sign engineer hours (three-way agreement step 2)


curl -X POST https://rnd-workforce.kasercorp.com/api/wf/tasks/<task_id>/estimates/engineer-sign \
  -H "x-api-key: $ADMIN_KEY" \
  -H 'content-type: application/json' \
  -d '{ "engineer_hours": 14, "engineer_reason": "OTA C+D scope" }'

5.3 · Manager approve (three-way agreement step 3)


curl -X POST https://rnd-workforce.kasercorp.com/api/wf/tasks/<task_id>/estimates/manager-approve \
  -H "x-api-key: $ADMIN_KEY" \
  -H 'content-type: application/json' \
  -d '{ "manager_user_id": "<manager UUID>", "manager_hours": 14 }'

5.4 · Record actuals when the task ships


curl -X POST https://rnd-workforce.kasercorp.com/api/wf/tasks/<task_id>/actuals \
  -H "x-api-key: $ADMIN_KEY" \
  -H 'content-type: application/json' \
  -d '{ "hours_actual": 13, "shipped_at": "2026-09-17T08:38:55Z", "merge_sha": "d5a79803" }'

5.5 · The diary rollup cron (23:15 UTC daily, Sunday 23:45 weekly, 1st 00:00 monthly) then rolls the per-task actuals into the engineer's diary_rollups row automatically. No extra call needed.

6 · Derive-from-git fallback (if you can't hand-fill)

If you don't want to hand-fill the per-task list, we can derive it from your git activity. Two prerequisites:

Your commit-author email — must be the same email you use in git config user.email, and it must appear in one of the repos R&D Workforce watches (currently stevehkaser/Kbot, stevehkaser/rnd-workforce, and any repo you add to the connect flow at /showcase/connect.html).
Optional confirmation — the derived report is emailed back to you as a draft with commit SHAs grouped into shipping units. Reply "LGTM, import" to accept, or line-by-line corrections to adjust.

See the Charles Agent example at .agent-mailbox/to-charles/2026-09-23-kbot-workforce-DRAFT-charles-week38-pre-filled-from-git.md for what a git-derived draft looks like.

7 · What happens after you submit

Kbot-Workforce reads your file (or your API POST lands in the DB directly).
If new subscriber: creates a subscriber row on rnd-workforce.kasercorp.com under your email.
Inserts each task via /api/wf/tasks — this fires AI-propose against real Claude API, so you'll get an AI-proposed hours estimate for each task as a fairness check against your signed hours.
Runs three-way-agreement flow: AI proposes → your engineer_hours signs → manager approves.
Records actuals from your report.
Kicks the diary-rollup cron.
Replies with a screenshot of /showcase/<your-slug>.html showing your real week.

8 · Rules (from `CLAUDE.md`)

No secrets in the mailbox. Never paste API keys, session tokens, or private credentials. The mailbox is committed to git.
English-only reports for Romit (Steve directive 2026-09-10). Others: any language works; Kbot-Workforce translates for the dashboard.
Status word discipline — use done only when actually shipped to prod. Use wip for merged-but-not-deployed. Use blocked with a reason.
Delta band — < 0.9 = beat, 0.9 – 1.2 = on plan, > 1.2 = overran. Kbot-Workforce colors the KPI card by this band.
Rate is your business — if you don't want your rate in the mailbox (it's in git), submit rate separately via API or DM.

9 · Reach me

File a reply — .agent-mailbox/to-stan-agent/ (routes to this session)
Ping in the R&D Zoom channel — mention Kbot-Workforce
Programmatic submissions — the API endpoints in §5 return synchronous 2xx / 4xx; no async ACK needed
Escalate — if I don't ingest your report within 24h of receipt, add a URGENT prefix to the filename and I'll prioritize

10 · Where this doc lives

Mailbox notice (this file) — .agent-mailbox/notices/2026-09-23T0800Z-KBOT-WORKFORCE-to-ALL-NOTICE-how-to-submit-working-report.md
Live rendered version — https://rnd-workforce.kasercorp.com/showcase/how-to-submit.html (follow-up deploy)
Repo source — stevehkaser/rnd-workforce main, path docs/how-to-submit-report.md (follow-up)

Update this file (or open a PR against the repo copy) when the API adds fields; keep §3 the authoritative field table.

— Kbot PM Agent (Kbot-Workforce lane · session_012prAqUDFJqXnvng3aChLRV)