feat: context files for Work Items and an agent knowledge base #221

Closed

ryangr0 wants to merge 0 commits from ryangr0/feat/agent-knowledge-and-context into development AGit

pull from: ryangr0/feat/agent-knowledge-and-context

merge into: webgrip:development

webgrip:development

webgrip:renovate/all-non-major

webgrip:build/ploeg-rc6

webgrip:agent/vik-1897

webgrip:main

webgrip:renovate/lock-file-maintenance

webgrip:renovate/go-1.25.x

webgrip:renovate/pin-dependencies

webgrip:agent/vik-1316

webgrip:agent/vik-1343

Conversation 0 Commits - Files changed -

ryangr0 commented 2026-10-04 10:57:29 +00:00

Owner

Copy link

What and why

People can give agents files, at the start of a Work Item and while steering it. Agents are briefed from a knowledge base exchanged as OKF.

• Decisions:
  • system ADR-0020: knowledge base, proposed until spike VIK-1859 reports
  • system ADR-0021: context files, accepted 2026-10-04
  • Vloer ADR-0038: Vloer collects files and hands them to Ploeg, accepted
• RFCs: docs/research/2026-10-04-rfc-agent-knowledge.md and docs/research/2026-10-04-rfc-context-bundles-and-steering.md. Both include the owner's decisions of 2026-10-04.
• Vloer: a Context card on the Ploeg Work Item page. The "Add context" dialog sends a file and an optional note to POST /api/ploeg/work-items/{id}/context, which forwards the bytes to Ploeg as the signed-in person. Vloer keeps no copy and its engine never reads context. The list shows size, file count, who added each file and when, an "Added while steering" chip, and which Run gets the file. The demo refuses uploads.
• knowledge/: an 8-concept OKF bundle about this repository, as the first real material for the measurement spike.

Draft: needs a Ploeg release. The upload works only against a Ploeg that has the context routes: https://github.com/ploeg-hq/ploeg/pull/60. Until a release with them is pinned, Vloer reports "This Ploeg version does not store context files yet". After that release, pin it in a ploeg-scoped commit (ADR-0019).

Verification

mise run verify    → All gates passed (vloer 7, vloer-extension 4, ploeg 3, brand, site 5, site-demo, helm 4, release 3, integration, docs)
mise run docs-check → ok
apps/vloer npm test → 744/744
gitleaks 8.30.1 on every changed file → no findings

• Real ploegd responses (201, idempotent 200, zip, list, 400 refusals) parse with parseContextItem.
• A one-off Playwright check against a fake Ploeg went end to end: sign in, open the Work Item, upload, see the chip. At 400 px nothing scrolled sideways, and there were no CSP errors.
• npm run test:browser is not part of verify, and it already fails on development (the feeds flow expects 9 Insights tiles and gets 10).

Risk and rollback

• Risk: uploads pass through Vloer, so its request size limit and timeout bound them (20 MiB).
• Rollback: revert. Vloer stores nothing.

Board: epic VIK-1858; related VIK-1836 and VIK-1847.

🤖 Generated with Claude Code

## What and why People can give agents files, at the start of a Work Item and while steering it. Agents are briefed from a knowledge base exchanged as OKF. - **Decisions:** - system ADR-0020: knowledge base, **proposed** until spike VIK-1859 reports - system ADR-0021: context files, **accepted** 2026-10-04 - Vloer ADR-0038: Vloer collects files and hands them to Ploeg, **accepted** - **RFCs:** `docs/research/2026-10-04-rfc-agent-knowledge.md` and `docs/research/2026-10-04-rfc-context-bundles-and-steering.md`. Both include the owner's decisions of 2026-10-04. - **Vloer:** a Context card on the Ploeg Work Item page. The "Add context" dialog sends a file and an optional note to `POST /api/ploeg/work-items/{id}/context`, which forwards the bytes to Ploeg as the signed-in person. Vloer keeps no copy and its engine never reads context. The list shows size, file count, who added each file and when, an "Added while steering" chip, and which Run gets the file. The demo refuses uploads. - **`knowledge/`:** an 8-concept OKF bundle about this repository, as the first real material for the measurement spike. **Draft: needs a Ploeg release.** The upload works only against a Ploeg that has the context routes: https://github.com/ploeg-hq/ploeg/pull/60. Until a release with them is pinned, Vloer reports "This Ploeg version does not store context files yet". After that release, pin it in a `ploeg`-scoped commit (ADR-0019). ## Verification ``` mise run verify → All gates passed (vloer 7, vloer-extension 4, ploeg 3, brand, site 5, site-demo, helm 4, release 3, integration, docs) mise run docs-check → ok apps/vloer npm test → 744/744 gitleaks 8.30.1 on every changed file → no findings ``` - Real ploegd responses (201, idempotent 200, zip, list, 400 refusals) parse with `parseContextItem`. - A one-off Playwright check against a fake Ploeg went end to end: sign in, open the Work Item, upload, see the chip. At 400 px nothing scrolled sideways, and there were no CSP errors. - `npm run test:browser` is not part of verify, and it already fails on `development` (the `feeds` flow expects 9 Insights tiles and gets 10). ## Risk and rollback - Risk: uploads pass through Vloer, so its request size limit and timeout bound them (20 MiB). - Rollback: revert. Vloer stores nothing. Board: epic VIK-1858; related VIK-1836 and VIK-1847. 🤖 Generated with [Claude Code](https://claude.com/claude-code)

ryangr0 added 4 commits 2026-10-04 10:57:29 +00:00

docs(adr): propose agent knowledge and context files for Work Items ... 1968e7715a

Two RFCs (agents learn from a knowledge base exchanged as OKF; people give a
Work Item context files at the start and while steering) and the decisions
they ask for: system ADR-0020 and ADR-0021 and Vloer ADR-0038, all proposed.
The context RFC fits the planned Brief Revisions and Context Items
(VIK-1835, VIK-1836, VIK-1847) and leaves the steering question to the owner.

VIK-1858
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>

feat(vloer): attach context files to a Ploeg Work Item ... 670c2cced4

The Work Item page gets a Context card: an "Add context" dialog sends a
file and an optional note to POST /api/ploeg/work-items/{id}/context, which
forwards the bytes to Ploeg's operator API as the signed-in person and keeps
no copy. The list shows each item's size, file count, who added it and when,
marks items added while steering, and says which Runs receive them. Vloer's
engine never reads context, and the demo refuses uploads.

Proposed behavior (Vloer ADR-0038); needs a Ploeg with the context routes.

VIK-1858
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>

docs(adr): accept context files for Work Items and record the owner's answers ... 18697595cf

The owner accepted ADR-0021 and Vloer ADR-0038 on 2026-10-04: a file
attached while a Shift runs is a steering input that reaches its next Run,
clients may attach to their own Work Items, Apply now exists with
confirmation, a flagged secret holds the file, and the limits stay 20 MiB
per upload and 50 MiB per Work Item. ADR-0020 stays proposed until the
measurement spike reports; its answers on Omnigraph per Tenant and on who
accepts learnings are recorded.

VIK-1858
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>

docs(knowledge): add an OKF knowledge bundle about the Unfold repository ... 2d0a3fcf88

Eight concepts (conventions, decisions, a pitfall and a layout fact) taken
from CLAUDE.md, docs/documentation.md and the system ADRs, for Ploeg's
worker to brief Runs on this repository (ADR-0020, proposed) and as
material for the measurement spike.

VIK-1858
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>

ryangr0 referenced this pull request 2026-10-04 13:06:58 +00:00

docs(adr): accept ADR-0017 with Clients, SSO groups and a default Tenant #225

ryangr0 force-pushed ryangr0/feat/agent-knowledge-and-context from 2d0a3fcf88 to 428d26e32c 2026-10-04 16:14:36 +00:00 Compare

ryangr0 force-pushed ryangr0/feat/agent-knowledge-and-context from 428d26e32c to 6ff22e0975 2026-10-04 16:31:29 +00:00 Compare

ryangr0 changed title from WIP: feat: context files for Work Items and an agent knowledge base to feat: context files for Work Items and an agent knowledge base 2026-10-04 17:06:03 +00:00

ryangr0 closed this pull request 2026-10-04 19:14:23 +00:00

Some checks failed

Hide all checks

[Workflow] On Pull Request / ploeg-pin (pull_request) Waiting to run

Details

[Workflow] On Pull Request / release-policy (pull_request) Waiting to run

Details

[Workflow] On Pull Request / checks (pull_request) Has been cancelled

Details

[Workflow] On Pull Request / warnings (pull_request) Has been cancelled

Details

Pull request closed

Please reopen this pull request to perform a merge.

Sign in to join this conversation.

Reviewers

No reviewers

Labels

Clear labels

No items

No labels

Milestone

Clear milestone

No items

No milestone

Projects

Clear projects

No items

No project

Assignees

Clear assignees

No assignees

1 participant

Notifications

Subscribe

Due date

The due date is invalid or out of range. Please use the format "yyyy-mm-dd".

No due date set.

Dependencies

No dependencies set.

Reference

webgrip/unfold!221

No description provided.