Self-improving AI Employees for everyone
Python ai-agentsai-employeeai-employeesassistantautonomous-agentsco-employeescompanygrok-botinstinctloop-agentsmuseown-your-datapersonalself-hosted
Agent Brief - Per-Category Rollout
You are documenting and writing contract tests for one category of OpenCompany workflow nodes. Phase 1 (test infrastructure) and Phase 2 (search-node pilot) are already done. Your job is to repeat the pilot pattern for your category.
Pilot example (study before starting)
- Docs:
docs-internal/node-logic-flows/search/- 3 files (braveSearch.md,serperSearch.md,perplexitySearch.md). - Test:
server/tests/nodes/test_search.py- 15 tests across 3 classes.
- Doc template:
./_TEMPLATE.md- copy verbatim, fill every section.
Reusable infra you must use
| Path | What it gives you |
|---|---|
server/tests/nodes/_harness.py |
NodeTestHarness - drives any handler through NodeExecutor with stubbed services |
server/tests/nodes/_mocks.py |
patched_container, patched_pricing, patched_broadcaster, patched_event_waiter, patched_subprocess |
server/tests/conftest.py |
Provides harness fixture; pre-stubs core.logging, core.container, services.pricing |
What to read
- The handler file(s) for your category (paths in your prompt).
- The backend plugin at
server/nodes/<group>/<plugin>/__init__.py(the NodeSpec SSOT). - Any matching skill at
server/skills/<folder>/<skill>/SKILL.md- link to it from the doc, do not duplicate. - The pilot files above so you copy the structure exactly.
What to write
- Per-node docs: one Markdown file per node at
docs-internal/node-logic-flows/<category>/<type>.md. The filename stem must equal the registeredtypestring exactly (camelCase or snake_case, whatever the plugin declares). - One test file at
server/tests/nodes/test_<category>.pywith one test class per node, covering at minimum:- happy path (assert envelope success + payload shape)
- one validation/error short-circuit (e.g. empty required param)
- one external-error path (HTTP 4xx/5xx, missing credential, subprocess failure)
- Update the docs index: run
company docs nodesafter writing docs;company docs nodes --checkfails when a registered node has no card.
Doc style rules
- Use the Mermaid
flowchart TDsyntax shown in the search docs. - Every doc must have Side Effects listing every DB write, broadcast, subprocess spawn, file I/O, and HTTP call. Be precise (URL, table name, method).
- Every doc must have Edge cases & known limits with at least one entry. Look for swallowed exceptions, silent fallbacks, hard-coded clamps, undocumented branches.
- Cross-link sibling docs in Related.
- Do NOT use emojis anywhere (project rule).
Test style rules
- Use
respx.mockfor httpx calls (already in pyproject dev deps). - Use
patched_container(auth_api_keys={"<provider>": "tk_test"})to inject API keys without touching the encryption pipeline. - For trigger nodes, use
patched_event_waiter(canned_event={...})so the future resolves immediately. - For subprocess-based handlers (browser, shell, process_manager, code executors), use
patched_subprocess(stdout=b"..."). - Run
cd server && uv run pytest tests/nodes/test_<category>.py -vand confirm all green before reporting done.
Reporting back
After all docs are written and tests pass, report:
- Count of docs created.
- Test count + pass status.
- Any nodes you skipped + why.
- Any handler bugs you found while documenting (do NOT fix - just list).