Agent Packs, Skills, and Profiles

Ownership Flow

Git catalog
→ validated deterministic revision
→ immutable object-store publication
→ organization profile reconciliation
→ pinned runtime hydration

Git owns built-in templates and skill content. PostgreSQL owns organization selections and pins. Object storage owns published immutable revisions. Keep the flow one-way.

Business Operating Procedures

All five profiles compose saas-business-analysis for business diagnosis, comparable metric evidence and concise decision briefs. Its references cover self-service subscription, sales-assisted B2B and usage-based API businesses. It does not add a new collector or grant action permissions. Operator diagnoses priorities, coordinates owned execution and recommends new strategic initiatives for owner selection. Chat recovers decisions and commitments, helps the owner decide, and follows through through existing work. Support, Engineering and Growth keep their distinct domain boundaries.

The shared runtime owns learning access, retained evidence, structured human handoffs, deferred work and finalization. Domain instructions explain triage, delivery, incidents and experiments within those contracts. Ordinary tasks can publish useful sanitized knowledge; daily/on-demand learning verifies broader lessons and suggestions. Catalog validation and scripted harness tests check composition and application contracts; they do not certify model judgment or guarantee a business result.

Add a Skill

Author Deterministic Instructions

Prompt-authoring skills are contributor tools, not runtime dependencies. Use the repository’s deterministic instruction-authoring process while creating or reviewing a skill, but do not add that authoring skill to commonSkillKeys, a profile, or the generated runtime instructions.

Every runtime SKILL.md must be self-contained:

1. Name its actor, trigger, scope, inputs, canonical owner, and enforcement boundary.
2. Express a finite procedure as an ordered algorithm.
3. Use decision tables for shared entrypoints; order mutually exclusive guards and include an explicit fallback.
4. Give every branch an observable result and success, waiting, blocked, failure, or no-op exit.
5. Distinguish behavior implemented by an application contract from behavior that is instructional for the agent. Label missing runtime support as proposed instead of implying it exists.
6. Use CFG or EBNF only for repeated syntax, recursive structures, valid artifact shapes, or phase composition that materially benefits from grammar notation. Do not replace a plain finite algorithm with undefined angle-bracket terms.
7. Validate direct references, run catalog tests, and audit the final rule ledger for authority, guard, vocabulary, exit, discretion, and implementation conflicts.

Runtime instructions must remain understandable without loading a separate interpreter or prompt-authoring skill.

Modify a Profile

Profiles define name, summary, kind, optional department, skill keys, static MCP keys, default run mode, tool-policy keys, and optional runtime overrides.

When profile content changes:

1. Change the Git catalog or owning AGENTS.md.
2. Validate the complete catalog.
3. Publish a new immutable revision.
4. Reconcile or reprovision organizations.
5. Verify root instructions, composed skills, memory coexistence, and missing-revision failure.

Chat profile changes invalidate reusable chat sessions. Existing database IDs survive reconciliation; deselection disables historical rows rather than deleting them.

Automatic upgrades add newly required common skills only when the saved selection exactly matches the prior published template’s composed defaults. They verify all target files and update the instruction pin and skills in one transaction. A custom selection missing a new common skill, an unavailable prior catalog, explicit pin, or custom instruction URI retains its previous instructions. Owner model settings and memory roots remain intact; a concurrent owner edit rejects the stale preview. Explicit instruction-only upgrades preserve the selected skills.

Select Profile Models

Set an exact provider model ID and reasoning effort in the profile template’s existing config.runtime object. The built-in catalog currently uses:

Keep the shared runtime model field provider-neutral. Do not add an Oblive model alias registry or silently retry with another model. An unavailable selected model should fail through the normal redacted execution error path.

Changing a model or reasoning effort creates a new catalog revision. Publish that revision for new provisioning and use the targeted migration below for existing model settings. Full re-provisioning also replaces profile configuration and department selection; reserve it for deliberate full upgrades.

Profile AGENTS.md files own role, scope, domain dispatch, and always-on public boundaries. They do not duplicate task admission, mode branching, run accounting, retries, handoffs, scheduling, output sync, or outcome submission. The shared task-runtime skill owns that complete lifecycle for Operator and department tasks. Chat remains a separate persistent-turn workflow and does not load task-runtime.

The task runtime mirrors application-enforced limits instead of pretending prose is enforcement: each task run may sync at most 100 changed output files; accepted human/action waits remain in run history but release their consumed run credit; and task agents may create future schedules only within the active objective and authority scope. The backend records those schedules as agent-originated with creator and source-execution provenance.

It also owns completion semantics for every durable profile. Planning instructions prefer formal output_file, command_exit, and integration_call criteria, permit an empty list for self-verifying work, and treat legacy semantic criteria as display-only expectations. The backend—not the profile prompt—chooses whether deterministic completion closes immediately, repairs once, asks a human, or fails. Judgment that must gate work belongs in an explicit review task. Profile instructions should state only when a domain skill applies; they must not duplicate this lifecycle.

Add Capability to a Department

Prefer adding a skill, integration grant, or tool policy to Growth, Engineering, or Support. Adding a fourth department changes shared enums, onboarding, organization configuration, profile rules, routing, persistence, UI, context structure, tests, and documentation and requires an explicit architecture decision.

Static MCP Grants

commonMcpServerKeys and profile mcpServerKeys select only keys present in the trusted agent-image registry. The catalog or database may select a registered server but never provide its command, package, path, or secrets.

Verification

bun test packages/agent-packs apps/backend
bun run --cwd apps/backend agent-packs:sync
bun run --cwd apps/backend agent-profiles:provision
bun run typecheck

Also update operator/developer documentation when a skill changes a visible workflow.

Upgrade existing model settings

Changing the catalog updates defaults for new provisioning. Existing organizations keep their persisted settings until a deliberate migration. For the Astra rollout, use the deployment command instead of re-provisioning departments, which replaces unrelated profile settings:

bun run --cwd apps/backend agent-profiles:migrate-models plan /secure/path/astra-profile-models.json
bun run --cwd apps/backend agent-profiles:migrate-models apply /secure/path/astra-profile-models.json

The plan includes every existing profile that needs a change, including disabled departments and custom model overrides. It records old/new model and reasoning settings without credentials. The report is created exclusively with mode 0600; retain it for rollback. Apply locks profiles in stable order and fails the whole transaction if a role or model setting changed after planning. Reapplying the same report is idempotent. Other configuration, department enablement, catalog pins, instructions, and historical run manifests remain unchanged. Changed Chat profiles clear saved harness sessions.

Apply during the deployment window after active chat turns are drained. Publish the updated catalog for newly provisioned profiles too. Subsequent prompt upgrades advance catalog pins through their own explicit migration; this command changes only model settings.

To restore the recorded model choices while retaining other settings:

bun run --cwd apps/backend agent-profiles:migrate-models rollback /secure/path/astra-profile-models.json

Rollback refuses newer model edits and is idempotent. Run all five role canaries against the deployed image and account before broad rollout; a successful configuration migration does not establish provider access. The requested efforts are supported by the official Astra model contract.

Human communication

The common human-communication skill is provisioned for Operator, Chat, Engineering, Growth and Support. Profile instructions route to it before any public prose, including task titles, progress notes, questions, notification presentations and approval summaries. The backend refreshes a short communication directive on every chat turn and every task mode, including resumed sessions.

These are instructional writing rules, not a claim that a schema can judge prose quality. Exact machine fields and retained evidence keep their original values. Inbox presentation and diagnostics remain separate; no post-processing rewrites user content or substitutes a guessed result for an execution receipt. Catalog composition and prompt tests cover all five profiles and all run modes.