CompanyOS System Authoring Feature Recipe

CompanyOS System Authoring Feature Recipe

When an agent is asked to build a user-facing Brezel feature, creating a resource_module is only one part of the job. The feature is not complete until users can find it, open it, and are permitted to use it in the intended scope.

This recipe is intentionally system-generic. Brezel API core must not hardcode customer-specific module identifiers, field identifiers, or domain ontologies.

For larger features, the agent should also create or reuse a CompanyOS planning case with concrete work items before the first draft write when the work-management tools are available. For root users this case is a planning and continuity artifact, not a permission gate and not a replacement for building the system-authoring draft.

Runtime Rule

The short checklist must live in the system-authoring tool flow, not only in this wiki. The agent should see it through system_authoring_command help/reference output while drafting.

The wiki is the durable human-readable explanation. A future builder-agent skill can point to the same recipe, but the authoring tools should still expose the critical checklist because not every agent runtime will load skills.

Feature Checklist

For a user-facing module feature, draft and verify these parts:

• Planning: for larger features, create or reuse a planning case before the first draft write and add work items for the main implementation steps. Do not stop after creating the case.
• Schema: create or update the required resource_module .bake.json files.
• Layouts: create or update the regular detail and index layout JSON files for visible fields, tabs, rows, columns, components, and related-record tables.
• Navigation: update resource_menu resources so the module appears in the appropriate SPA menu.
• Roles: update role entities for the intended roles. Role permissions live in resource.fields.modules.
• Policies/Filters: add or reuse resource_policy entries when access must be scoped by ownership, organization, tenant, department, or another runtime condition.
• Preview: provision or refresh the safe preview and inspect it before requesting approval.
• Tests: run relevant system-authoring or business workflow tests before approval.
• Approval: final live merge must remain human-approved, either through a case/review flow or an explicit approval tool card.

Tool Flow

Recommended generic sequence:

1. For larger features, use find_related_work and then create or reuse a planning case when work tools are available.
2. Add work items for schema, layouts, navigation, permissions/policies, preview/tests, and approval.
3. Use system_authoring_command with command="reference" and kind="module".
4. If similar files exist, use file.list and file.read to inspect real source format.
5. Write module files with module.create, module.update, or bakery.write.
6. Write regular layout JSON files with layout.write_raw.
7. Use reference with kind="menu" before changing navigation.
8. Use reference with kind="role" before changing permission matrices.
9. Use reference with kind="policy" before adding filters or policy names referenced by roles.
10. Provision or refresh preview.
11. Run tests.
12. Request approval.

If the user already asked the agent to build the feature, the agent should continue through these steps without asking “if you want, I can continue” after every partial draft operation. It should only pause for real blockers: tool errors, missing permissions, ambiguous requirements that cannot be resolved from the system, or explicit user instruction to stop.

Permission And Governance

If the agent or acting user has system-authoring rights, the agent may create a draft and preview directly. For larger changes it may still create a planning case first, but it should continue with the draft immediately. If those tools or rights are not available, the agent should not pretend it can build the feature. It should create or propose a governance case/work item for a higher-permission department or agent, when work-management tools are available.

Draft creation and preview are safe system-authoring steps. Applying or merging into live remains human-approved.

Why Not A Customer Ontology

The agent should not be taught that a specific customer system uses a specific module name for a business concept. It should inspect the current system:

• discover modules and examples,
• read actual authoring files,
• inspect relation maps and layouts,
• then decide what to draft.

Hardcoded customer identifiers in Brezel API core create brittle behavior and leak one system’s ontology into every other system.