# PA Operating Model

The methodology every PA built on `@stravica-ai/digital-operator-pa` follows. A three-leg spine at doctrine level; a seven-bucket taxonomy at always-on-rules level; one core-vs-operator split direction.

This document is the onboarding read for any operator adopting the platform: it explains what the operating model IS, how the pieces the platform ships fit together, and where the boundary sits between what the core prescribes and what the operator populates. It is a WHY + HOW-IT-FITS reference, not a tutorial. For how to instantiate a new operator repo, see the scaffolder (`pa-init`). For the mechanics of any specific piece; a role, a template, a CLI; read the linked source of truth.


## What the PA operating model IS

A PA built on `@stravica-ai/digital-operator-pa` runs on a **three-leg spine** at doctrine level. Every subordinate decision serves one of the three legs or gets cut.

- **PA responsibilities.** WHAT the PA is here for. Managing the operator's work items, projects, spawn-log, staging, progress trackers. Being the single point of contact. Learning the operator's judgement well enough to operate autonomously on their behalf.
- **Dispatch discipline.** HOW the PA delegates work. A two-stage pipeline: analyse direction, then encode into an 8-section briefing contract via the `dispatch-briefer` role. Every worker gets a brief authored in a clean context following a consistent methodology, regardless of the PA's main-thread state at the time.
- **Knowledge retrieval discipline.** HOW the PA finds answers. Analyse the question, identify relevant topics, use `pa knowledge` verbs to extract snippets at the right size, synthesise, respond. The right knowledge, the right size, at the right time.

Every dispatch, every question, every operator ask is served by these three legs working together. PA responsibilities is WHAT; dispatch discipline is HOW to delegate; retrieval discipline is HOW to find answers. When the PA finds itself doing work that does not clearly fit under one of these three, it has slipped into the wrong mode and should stop and check.

The three-leg spine is the **doctrine**. The **always-on rules** the PA carries in CLAUDE.md are organised under a **seven-bucket taxonomy** (see § "The 7-bucket taxonomy" below); a sized-by-need presentation of the same operating model, tuned to fit Anthropic's <200-line CLAUDE.md guidance. The two shapes coexist: the three-leg spine is why; the seven buckets are how the rules land.

The platform ships the methodology + the tooling. The operator populates the data + the config. Everything below elaborates that split.


## The 7-bucket taxonomy

CLAUDE.md's always-on rules are organised in seven conceptual buckets. Rules per bucket are capped by need; not by number.

| # | Bucket | What it carries | Core-side default | Operator-overlay content |
|---|---|---|---|---|
| 1 | Operator interface | Session boot/end, communication style, push-back and escalation | Session-boot briefing shape, communication baseline, push-back and correction discipline | Surface-specific greeting register, hand-off protocols with a second human |
| 2 | Work management | Work items, projects, progress.md, spawn-log | Full universal mechanism (schemas, statuses, CLI patterns) | Operator-specific priority mapping, work-item category extensions |
| 3 | Delegation & dispatch | 8-section brief, delegation modes, task groups, tool development policy | Full universal mechanism (briefing contract, dispatch envelope, delegation modes, task groups, team improvement loop) | Operator-specialised role LIST beyond the base ladder |
| 4 | Knowledge & memory | `pa knowledge`, staging, journal, Librarian synthesis, CLAUDE.md hygiene | Full universal mechanism (retrieval verbs, staging category taxonomy, synthesis mandate) | Operator-specific memory conventions, cross-machine sync path |
| 5 | Engineering discipline | Role ladder, verify, git safety, worktree isolation, root causes | Base role LADDER (`tool-developer` → `web-developer` → `product-engineer` → `rcf-engineer`), verify + git safety + worktree isolation + root-cause investigation | The specific operator-side specialised role LIST |
| 6 | Content & voice | Pipeline routing, voice + banned-tells discipline | 13-category banned-tells taxonomy + generic AI patterns + capture procedure | Operator-specific voice content + specific banned tells + surface-specialised writer roles |
| 7 | Platform tooling | Tool discovery, environment awareness, workspace, scheduling, MCP | `pa` / `desk` / `pa environment` / workspace / scheduling mechanism | Operator's `operator/extensions/tools/`, operator's workspace port, scheduling default host |

Each bucket in the CLAUDE.md template carries always-on rules + a "Deeper reference" pointer at the bucket's knowledge scaffold under `@stravica-ai/engineering-pa-core/knowledge/<bucket-slug>/`. The scaffold ships the shape (README + canonical subdoc files); operators copy the shape into `operator/knowledge/<bucket-slug>/` and populate.

**Overlay hooks.** Every bucket has a `<!-- OPERATOR: ... -->` marker where operator-specific content lands. The marker is the machine-parseable seam between core and overlay; `pa-init` and future lint tooling both consume it.

**Why the taxonomy exists.** The three-leg spine is doctrinally correct but too coarse for the always-on-rules surface; a rule about spawn-log discipline belongs somewhere more specific than "PA responsibilities". The seven buckets are the level of granularity where rules cluster naturally without splintering. Anthropic's <200-line CLAUDE.md guidance drops out as a consequence: seven buckets × ~9 rules × ~2 lines/rule + framing ≈ 190 lines.


## Leg 1; PA responsibilities

The PA is the operator's single point of contact. Everything the operator needs flows through the PA; nothing communicates with the operator directly except the PA.

Canonical role definition: [`../roles/pa/definition.md`](../roles/pa/definition.md). Read it end-to-end when adopting the platform.

### What the PA owns

- **Work items** at `work/w-YYYY-MM-DD-NNN.json`. Every non-trivial ask gets one before execution or dispatch begins. Statuses (`draft` / `planned` / `in-progress` / `blocked` / `done` / `archived`), categories (`feature` / `bug` / `chore` / `discussion` / `research`), and priority (0 critical → 3 low) shape how they show up in `desk overview`.
- **Projects** at `projects/{id}/project.json`. Same status model. Larger units of work that group work items.
- **Spawn log** at `agents/{paName}/spawn-log.json`. Updated the moment a subagent is dispatched; not at session end. This is the operator's live view of what is in flight without asking.
- **Staging** at `agents/{paName}/staging/`. Observations captured in real time as timestamped markdown, categorised (`preference`, `correction`, `decision`, `pattern`, `contact`, `domain`, `feedback`). The Librarian sweeps this into durable knowledge.
- **Progress trackers** at `projects/{id}/progress.md`. Live state of any project with concurrent work in flight. Newest entries on top. References work items and spawn-log entries; never duplicates them.

`desk` (installed as a bin by `@stravica-ai/digital-operator-pa`) provides read-only overviews: `desk overview`, `desk today`, `desk work`, `desk projects`.

Full entity-location reference: [`./entity-location-map.md`](./entity-location-map.md).

### Core rules the PA follows

These are non-negotiable and encoded in the scaffold's CLAUDE.md template. Every PA instance runs by them.

1. **All work through managed tasks.** No trivial-plus-one action reaches Edit/Write/Bash without a work item.
2. **Delegate by default.** The PA stays available for the operator; specialist work goes to specialist roles.
3. **Spawn log updated at dispatch time**, not at session end.
4. **Platform code is read-only.** Never edit `node_modules/@stravica-ai/digital-operator-pa/` in place; changes land upstream via a PR against `Stravica/engineering-pa-dev` and reach every operator via the next release.
5. **JSON properties always camelCase.** Every JSON file the PA creates or modifies.

### Long-term arc

The PA's stated purpose is to learn the operator's judgement well enough to act autonomously on their behalf. The measure of progress is how often the PA can act without escalating; every question the PA has to ask that it could have answered from staged knowledge is a gap.

Corrections from the operator are the highest-signal training data. The PA stages every correction immediately, and the Librarian promotes them into learned rules and profile updates on the next distillation sweep. The loop is what makes the PA improve across sessions.

### Boundaries the PA does NOT cross

- **Knowledge curation.** Distillation, indexing, structural changes to the knowledge system all go to the Librarian.
- **Tool development.** All shared and library tools go to the tool-developer role. No shell scripts; Node.js only, per the tooling standard.
- **System-level changes.** Environment configuration, service management, network work go to the system-admin.
- **Role and team management.** Creating new roles, changing role definitions goes to the agent-ops role with operator approval.
- **CLAUDE.md edits.** The Librarian never writes to CLAUDE.md files at any level. New rules land in sub-docs that CLAUDE.md's existing knowledge pointers already resolve to; see leg 3 and the immutability discipline below.


## Leg 2; Dispatch discipline

Every non-trivial dispatch flows through a two-stage pipeline. The PA does not write briefs inline; it hands a short intent to the `dispatch-briefer` role, and the Briefer authors the 8-section contract in a clean context. The PA then dispatches the target worker with the brief.

Canonical role definitions:
- [`../roles/dispatch-briefer/definition.md`](../roles/dispatch-briefer/definition.md); the Briefer role, its two-stage methodology, session-lesson corrections baked in.
- [`./standards/briefing-contract.md`](./standards/briefing-contract.md); the 8-section contract itself, field-by-field rationale.

### The two-stage pipeline

**Stage 1; analyse direction.** The Briefer takes the dispatcher's compact intent (goal, target role, references, operator direction if any) and analyses it against the operator's stated priorities. Questions it answers before writing anything:

- Is this the right direction for this ask?
- Can it be improved? Does the operator's material suggest a stronger angle?
- Are there load-bearing decisions the operator has not yet made that would otherwise be baked in as speculation?

If direction is provided and sound, the Briefer proceeds to stage 2. If direction is provided but questionable, the Briefer surfaces the concern to the dispatcher rather than encoding a shaky angle. If no direction is provided, the Briefer proposes 2–3 candidates with rationale and escalates for selection; it does not jump to stage 2 on vague direction.

**Stage 2; encode into 8-section brief.** With direction locked, the Briefer queries the operator's knowledge system via `pa knowledge`, reads what the worker will need at the size it will need it, and produces a brief in canonical shape. The brief is prose the dispatcher can copy-paste; it carries no commentary about how it was constructed.

### The 8-section briefing contract

Every brief has these sections in this order. Section headings are mechanical; copy them verbatim.

| Section | What it carries |
|---|---|
| Goal | One sentence, outcome-shaped. What shipping looks like. |
| Trace | How we got here. The reasoning that led to this task. Load-bearing. |
| Context | Paths, files, prior decisions, operator preferences relevant to this task. Extracted, not the full profile. |
| Tools and sources | What tools to use. Which files to read. Which to avoid. |
| Boundaries | What is in scope, what is out. Where decide-alone becomes escalate. |
| Output format | Structured return-report shape. **Return on completion or abort ONLY**; never mid-poll. |
| Done when | Boolean-checkable ship gate. |
| Escalation rule | When to stop and report partial. Includes the anti-pattern "do NOT return early expecting to be resumed by background notifications; there is no such mechanism". |

The **trace** is the field most often missed and most often the cause of bad outcomes. Cognition's Flappy Bird failure mode captures why: workers briefed without trace re-derive context locally and make consistent choices that are globally incompatible; the integration step then reconciles two miscommunications. The trace prevents that by sharing the dispatcher's reasoning up front.

Full field-by-field rationale and bolt-ons (worktree-isolated dispatches, specification-quality checklist): [`./standards/briefing-contract.md`](./standards/briefing-contract.md).

### Context hygiene; the load-bearing property

The Briefer exists so that every worker receives a brief authored in a clean context, regardless of the dispatcher's main-thread state at the time. A brief written at session hour 5; after four hours of accumulated context, corrections, and half-executed ideas; has the same shape and quality as one written at session hour 1. That property is what makes downstream worker output consistent across a long session.

The PA-side reflex is to skip the Briefer ("I already know the shape", "the target role is simple"). Each of those is context-hygiene sacrificed for perceived speed. The narrow exceptions the role definition names; trivially small tasks, v2 amendments to a known brief, time-sensitive synchronous asks; are exactly that: narrow. A fourth exception is the failure mode the role exists to prevent.

### Session-lesson corrections encoded in the role

The Briefer role definition bakes in two corrections drawn from real operator observations. They are authoritative on the role's methodology; every Briefer instance reads them on activation.

- **Over-constraint / voice-flattening.** Heavy prescription flattens the target role's voice. When the Briefer bakes in pre-shaped opener patterns, distinct-axis vocabulary, follow-up hooks, blanket bans, and tight character caps, the target role executes the brief perfectly and delivers output that passes every lint but sounds nothing like the operator. The rules that fall out: do not pre-shape openers, do not pre-plan follow-up hooks, do not bake in ungrounded bans, keep character targets elastic to what the operator's voice needs, and trust the target role to know its craft.
- **Worker-stub returns on polling.** Implementer workers asked to poll a long-running check at intervals have returned mid-loop with stub messages ("I'll wait for the polls to complete via background notifications"). There is no such background mechanism. Every brief with a timed-wait step names the anti-pattern explicitly and instructs the worker to `sleep N` inside a Bash call rather than returning mid-poll.

### Ownership boundary for platform-package PRs

Briefs targeting `Stravica/engineering-pa-dev` encode an explicit boundary. The worker owns code changes, tests, docs, branch push, PR open, and first-CI-check-green. The dispatcher owns merge, subsequent CI polls, post-merge verification, the release tag (if any), and any operator-repo follow-up. This boundary is the standard shape, not a per-brief option. It exists because the extended polling loop (worker owns "wait for N CI checks then merge") repeatedly produced stub returns mid-loop.

### Delegation patterns

| Pattern | Use when | Standard |
|---|---|---|
| Single subagent | Default for any task the operator hands the PA. Well-bounded work that fits one worker. | 8-section brief via `dispatch-briefer` |
| Task group (orchestrator + workers) | Read-heavy parallelisable work, work that exceeds the PA's context budget, multi-role software project. | Task-group pattern with per-worker briefs |
| Single-threaded (do it yourself) | Genuinely trivial; one tool call, no craft. Or context already burned and dispatching would cost more than finishing. |; |

For multi-role software projects, the PA dispatches a Project Lead to orchestrate the task group. The PA steps back and remains available for the operator.


## Leg 3; Knowledge retrieval discipline

The right knowledge, the right size, at the right time. This is how the PA finds answers without reading whole files it does not need.

Canonical CLI docs: `pa knowledge` verbs are implemented at `packages/cli/src/knowledge/` and documented via `pa knowledge --help`. Knowledge system structure: [`./knowledge-scaffold.md`](./knowledge-scaffold.md).

### The process

1. **Analyse the question.** What is actually being asked? What domain does it touch? What granularity of answer is needed; a fact, a paragraph, a whole doc?
2. **Identify topics.** Use `pa knowledge domain <name>` to see what a domain contains. Use `pa knowledge search <term>` to find candidate docs.
3. **Extract at the right size.** Use `pa knowledge related <slug>` for adjacent concepts. Use `pa knowledge path <a> <b>` to bridge two topics. Extract snippets, not whole files.
4. **Synthesise.** Answer in the PA's own words, grounded in what the extracts said. Cite the docs by slug.
5. **Respond.** If the question genuinely warrants a whole-file read (rare; see below), do it. Otherwise, snippet-level.

### The `pa knowledge` CLI

The retrieval tool. Five verbs, one global flag:

| Verb | What it does |
|---|---|
| `pa knowledge related <slug>` | 1-hop neighbourhood for a doc. `--in` / `--out` limits to inbound / outbound edges. |
| `pa knowledge search <term>` | Text search across the knowledge tree. `--full` includes doc body. |
| `pa knowledge domain <name>` | Everything in a domain. |
| `pa knowledge orphans` | Docs with no incoming or outgoing links; candidates for cleanup or new-link-adding. `--exclude-stubs` filters stubs. |
| `pa knowledge path <a> <b>` | Shortest link path between two docs. |

Add `--format json` when the output feeds another tool or role; the Briefer consumes JSON, for example. `--format mermaid` renders adjacency in mermaid syntax for docs.

Exit codes follow the tooling standard: `0` ok, `1` usage, `2` unknown-slug / ambiguous / unknown-domain, `3` IO (graph missing or unreadable).

### Discipline: use the tool to reduce whole-file reading

The point of the retrieval CLI is not to skip reading; it is to read at the right size. Whole-file reads are appropriate for a few cases:

- A doc under ~200 lines where the question spans its whole argument.
- A doc about to be edited; structural context matters for a good edit.
- A canonical reference (a schema, a role definition, a standard) whose whole content is load-bearing.

For everything else; answering a factual question, checking a rule, resolving a reference from a brief; the PA extracts a snippet. Whole-file reading is the exception, not the default.

### Adding knowledge

New domain? Directory under `operator/knowledge/`. New content? Markdown file with wiki-links (`[[target]]`) or explicit markdown links. The Librarian handles indexing on the next distillation sweep; the PA can trigger it explicitly if the addition is time-sensitive.


## How the three legs interlock; a worked example

The three legs are not sequential phases; they compose in every non-trivial operator ask. A concrete walk-through:

**Operator ask:** "Draft me a LinkedIn comment replying to this post from <peer>."

1. **Leg 1; PA responsibilities engage.** The PA opens a work item (`w-YYYY-MM-DD-NNN.json`, category `feature`, owner PA). The work item captures the ask verbatim, links the peer's post, sets status `in-progress`. If the LI comment is part of a broader engagement project, the PA also updates the project's `progress.md` with the new dispatch.
2. **Leg 2; dispatch discipline engages.** The PA does NOT write the writer brief inline. It hands a compact intent to the `dispatch-briefer` role: goal ("draft a LI comment replying to this post"), target role (`writer`, or an operator-side `linkedin-writer` specialisation), references (the peer's post, the peer's profile if available), operator direction (any angle the operator provided, or "none; propose candidates").
3. **Leg 3; retrieval discipline engages, inside leg 2.** The Briefer queries `pa knowledge search voice-guide` and `pa knowledge related voice-guide` to locate the operator's voice materials. It queries `pa knowledge domain writing` to see what's in the operator's writing domain. It extracts the voice-guide sections it needs at snippet level, and finds the banned-tells reference. It reads the peer's post if the PA has staged it.
4. **Leg 2; the Briefer stage 1 (analyse direction).** If the operator provided an angle, the Briefer weighs it against the voice-guide's register calibration. If the angle is sound, it locks it. If not, it escalates back to the PA with the concern. If no angle was provided, it proposes 2–3 candidates with rationale grounded in the operator's material.
5. **Leg 2; the Briefer stage 2 (encode into brief).** With direction locked, the Briefer fills the 8 sections. Goal is outcome-shaped. Trace names the peer, the post shape, the operator relationship state. Context extracts the voice-guide sections. Tools-and-sources names the voice-guide path and banned-tells path. Boundaries state character target elastic, do not pre-shape openers. Output-format says draft markdown only, no meta. Done-when lists banned-tells zero hits + character-target range met + voice-presence sanity gate passed. Escalation-rule names the anti-pattern about background notifications.
6. **The PA dispatches the writer** with the brief. The writer runs its own two-stage discipline (analyse direction, then draft), reads voice-guide + banned-tells + peer's post, drafts in the operator's voice, runs its four voice checks before returning.
7. **Leg 1; the PA reviews and reports.** The PA reads the draft, runs a sanity check against the operator's voice, and either surfaces it to the operator for approval or (if the operator has delegated shipping) posts it. The work item's status flips to `done`; the spawn-log outcome is updated; the progress.md if any is appended.
8. **Leg 1 continues; observations staged.** Anything the PA noticed during this cycle; a correction from the operator, a pattern in the peer's post that changed the register calibration, a new banned-tell candidate; gets staged to `agents/{paName}/staging/` as a timestamped markdown file. The Librarian sweeps it on the next distillation and synthesises it into the appropriate destination (voice-guide, banned-tells, learned-rules, operator profile).

Every ask fits this shape, adjusted for its content. A code dispatch swaps the writer for a code implementer, the voice-guide for the relevant technical standards, and the peer's post for whatever supporting material the code work needs; but the three-leg composition is the same.


## What the platform ships; core inventory

Everything below is bundled in `@stravica-ai/digital-operator-pa` and reaches every operator via `pnpm add @stravica-ai/digital-operator-pa`.

### Roles

Domain-agnostic role definitions at `@stravica-ai/engineering-pa-core/roles/<role>/definition.md`. Every operator instance inherits these; operator-side specialisations extend without overriding.

| Role | Purpose |
|---|---|
| `pa` | The PA role. The operator's single point of contact. |
| `dispatch-briefer` | Prepares 8-section briefs in a clean context. Every non-trivial dispatch flows through it. |
| `writer` | Voice-doc-driven prose in the operator's voice. Reads voice-guide + banned-tells + operator profile from operator-configured paths on every dispatch. |
| `librarian` | Knowledge distillation, synthesis, indexing. Synthesis mandate + anti-append rule + CLAUDE.md-immutability rule. |
| `tool-developer` | Building and maintaining shared tools. Node.js only, per the tooling standard. |
| `system-admin` | Environment, network, service configuration. |
| `agent-ops` | Role and team management. |
| `agentic-workflow-designer` | Designs agentic and automation workflows as ruled artefacts: flowchart diagram, Meta Agents Rule of Two mapping, operator rulings. |

### Templates

Structural skeletons under `@stravica-ai/digital-operator-pa/templates/`. Operator populates content; the shape is what makes voice documents mutually intelligible across operators.

| Template | Purpose |
|---|---|
| `voice-guide.md` | Structural skeleton for an operator's voice guide. Positive-shape principles the writer draws on. |
| `banned-ai-tells.md` | Structural skeleton for the negative-shape complement. Catalogue of tells the writer screens against before shipping. |
| `purpose.md` | Structural skeleton for a content-publishing purpose / mission doc. The top of the mission stack. |

The scaffold's CLAUDE.md template at `@stravica-ai/engineering-pa-core/../scaffold/templates/CLAUDE.md.template` is the fourth structural artefact; the three-leg PA CLAUDE.md shape that `pa-init` writes into every new operator repo.

### Tools

Operator-facing CLIs installed as bins by `@stravica-ai/digital-operator-pa`. Every bin runs `--help` and exits `0` when the install is healthy.

| Bin | What it does |
|---|---|
| `pa` | Top-level operator CLI. Verbs: `status`, `workspace`, `project`, `work`, `gsc`, `lint`, `migrate-inspect`, `launch`, `knowledge`, `autonomy`, `environment`. |
| `desk` | Read-only task and project overviews. |
| `launch` | Boots a scoped agent instance bound to an identity and task. |
| `sync` | Per-host single-writer git sync. |
| `secrets` | SOPS + age secrets vault management. |
| `scheduler` | Scheduling primitives (cron / launchd install + verify). |
| `smoke` | Fresh-clone smoke suite. |
| `distill` | Librarian distillation sweep. |
| `memory-sync` | PA-memory cache mirror. |
| `migrate-inspect` | Host inspection for migration planning. |
| `pa-init` | Scaffolder for a new operator repo. |
| `slice` | Operator profile slice generator (compact boot context). |

`pa knowledge` is the retrieval CLI at the heart of leg 3; see leg 3 above for verbs.

### Standards

Package-versioned standards at `@stravica-ai/engineering-pa-core/docs/standards/`. Every role definition and tool README references these; operators MAY extend more-restrictively at `operator/knowledge/engineering/standards/` but MUST NOT contradict.

| Standard | Governs |
|---|---|
| [`standards/briefing-contract.md`](./standards/briefing-contract.md) | The 8-section brief every dispatch uses. Bolt-ons for worktree-isolated dispatches and specification quality. |
| [`standards/tooling.md`](./standards/tooling.md) | Shared and library tools under `packages/*/` and `operator/extensions/tools/`. Identity, structure, CLI shape, exit codes, testing, README-as-contract. |

### Bucket knowledge scaffolds

Bucket-shaped knowledge scaffolds at `@stravica-ai/engineering-pa-core/knowledge/<bucket-slug>/`. Each ships a README + canonical subdocs. Operators copy the shape into `operator/knowledge/<bucket-slug>/` and populate.

| Bucket slug | Ships |
|---|---|
| `operator-interface` | Session-boot/end SOP, communication style, escalation + correction, push-back discipline |
| `work-management` | Work-item schema, project schema, progress.md discipline, desk CLI, spawn-log discipline |
| `delegation-dispatch` | Briefing contract, dispatch envelope, delegation modes, task groups, team improvement, tool development policy |
| `knowledge-memory` | Retrieval discipline, staging + observations, journal, Librarian synthesis mandate, CLAUDE.md hygiene |
| `engineering-discipline` | Role ladder, verify runtime behaviour, blast radius + git safety, worktree isolation, root causes |
| `content-voice` | 13-category banned-tells taxonomy, baseline entries, capture procedure, content-pipeline routing, voice-guide + banned-tells shape pointers |
| `platform-tooling` | Tool-discovery discipline, environment awareness (`pa environment`), pa/desk CLI references, workspace, scheduling, MCP catalogue, working-directory |

### Autonomy envelope mechanism

Per-agent per-task-type approval-state tracker.

- **Schema** at `@stravica-ai/engineering-pa-core/schema/autonomy-envelope.schema.json`.
- **CLI** `pa autonomy`; `init`, `get`, `set`, `list` verbs.
- **Session-boot integration**; the core ships the read-side (schema + CLI). Operator-side hook infrastructure can invoke `pa autonomy get <agent> --format json` at session boot and inject into `additionalContext`.
- **Docs** [`./autonomy-envelope-tracker.md`](./autonomy-envelope-tracker.md).

### Environment awareness

`pa environment` CLI with three verbs (`default` cache-read, `refresh` force-rebuild, `extended` operator overlay). Writes `.session/environment.json` with slow-changing environment state. Hard performance target: <2s cache-read, <5s refresh.

Full detail: `@stravica-ai/engineering-pa-core/knowledge/platform-tooling/environment-awareness.md`.

### Discipline docs

Docs at `@stravica-ai/engineering-pa-core/docs/` that explain how the operating model runs day-to-day.

| Doc | What it covers |
|---|---|
| This doc | The three-leg spine, the 7-bucket taxonomy, and how the pieces fit. |
| [`./autonomy-envelope-tracker.md`](./autonomy-envelope-tracker.md) | The autonomy-envelope mechanism; schema, CLI, session-boot integration. |
| [`./knowledge-scaffold.md`](./knowledge-scaffold.md) | Knowledge system structure, domains, linking, backlinks, adjacency graph. |
| [`./entity-location-map.md`](./entity-location-map.md) | Canonical paths for everything the PA refers to. |
| [`./working-directory.md`](./working-directory.md) | How the PA's shell cwd relates to the operator repo root. |
| [`./workspace-operations.md`](./workspace-operations.md) | The workspace server, its pages, when to use it. |
| [`./memory-sync.md`](./memory-sync.md) | Cross-machine PA-memory synchronisation. |
| [`./scheduling.md`](./scheduling.md) | Scheduled task primitives. |
| [`./upstream-issue-filing.md`](./upstream-issue-filing.md) | Filing platform bugs and gaps upstream. |


## Operator instantiation

How an operator adopts the platform. Broad shape; the mechanics live in the scaffolder README.

1. **Install the package.** `pnpm add @stravica-ai/digital-operator-pa` in the operator repo (or scaffold a fresh one via `pa-init`). This lays down the bin surface and every core resource under `node_modules/@stravica-ai/digital-operator-pa/`.
2. **Scaffold or refactor CLAUDE.md.** `pa-init` writes the 7-bucket CLAUDE.md template into `agents/{paName}/CLAUDE.md`. The template preserves scaffold tokens (`{PA_NAME}`, `{OPERATOR_NAME}`, `{PURPOSE}`, `{COMMUNICATION_STYLE}`); the operator fills these and everything else stays as-is. The template is a structural skeleton with `<!-- OPERATOR: … -->` markers where operator-specific overlays go, one per bucket plus framing.
3. **Copy the bucket knowledge scaffolds.** For each bucket, copy the shape from `node_modules/@stravica-ai/digital-operator-pa/dist/engineering-pa-core/knowledge/<bucket-slug>/` into `operator/knowledge/<bucket-slug>/`. Populate operator content under the `<!-- OPERATOR: populate -->` markers; do not restructure the core-shipped shape. Six of the seven buckets copy straight; content-voice (Bucket 6) has additional operator overlay conventions; see § "The core vs operator split" below.
4. **Populate the voice materials.** Copy `voice-guide.md`, `banned-ai-tells.md`, and `purpose.md` from `@stravica-ai/digital-operator-pa/templates/` into `operator/knowledge/writing/` (or the operator's chosen paths) and fill the `<!-- OPERATOR: … -->` markers. Operator's `banned-ai-tells.md` inherits the 13-category shape from the core baseline at `@stravica-ai/engineering-pa-core/knowledge/content-voice/banned-ai-tells-taxonomy.md` and layers operator-specific entries on top.
5. **Point the writer's config at the populated files.** Default location `operator/extensions/roles/writer/config.json`. Fields: `voiceGuide`, `bannedTells`, `operatorProfile`, `authorByline`, `surfaces`. Only `voiceGuide` and `bannedTells` are required; surface-specific extras layer on via specialisation roles.
6. **Populate the operator profile.** `operator/profile/profile.md`; who the operator is, what they do, what they care about. The PA reads this on boot to greet naturally and calibrate.
7. **Initialise the autonomy envelope.** `pa autonomy init <paName>`. Creates an empty envelope at `agents/{paName}/autonomy-envelope.md`. Seed initial task-type states with `pa autonomy set` as the operator decides what the PA is allowed to do without asking.
8. **Set up the knowledge domain catalogue.** `operator/knowledge/domains.json` seeded from `core/knowledge/scaffold/domains.json`. New domains land here as the operator's knowledge grows.
9. **Overlay operator-specific specialisations.** Under `operator/extensions/roles/` if the operator's craft has surface-specific rules the base role does not carry. Example: a `linkedin-writer` that extends the base `writer` with LinkedIn-specific character targets and structural rules but MUST NOT override the base's read-then-gate-then-deliver sequence or relax the banned-tells check.
10. **Populate the operator-overlay hooks** in CLAUDE.md as the operator's estate takes shape. Each hook is a machine-parseable seam where operator-specific content lands.

After that, the PA is booted (`pa session`) and starts learning the operator's judgement through every interaction. The three-leg spine runs from the first ask; the 7-bucket rules are always on.


## The immutability discipline

CLAUDE.md is expensive per token (loaded on every session boot) and expensive per edit (the operator eyeballs every change). Both costs collapse if the file is allowed to accrete. Keeping it stable is a first-class discipline.

Rules that fall out:

- **New findings go to sub-docs, discoverable from CLAUDE.md's existing knowledge pointers.** Not into the body of CLAUDE.md. If a new rule is worth adding, it lives in a knowledge doc; CLAUDE.md's existing pointers (bucket "deeper reference" links and the entity-location map) resolve to it; no new lookup mechanism is created.
- **The Librarian never writes to CLAUDE.md.** Not this file, not any CLAUDE.md at any level. When the Librarian identifies a rule from staging observations, it writes the rule into the operator's rules destination; an existing document: `learned-rules.md` where the repo has one, otherwise the structured knowledge doc that owns the behaviour; and confirms it is discoverable from CLAUDE.md's existing pointers. Only the operator touches CLAUDE.md.
- **The PA does NOT append to CLAUDE.md ad-hoc.** Additions land in deliberate refactor passes, with intent. If the PA catches itself reaching for "just add this line to CLAUDE.md", that is the accretion anti-pattern the discipline exists to prevent.
- **Updates are rare and deliberate.** The stability of this file is not a nice-to-have.

Canonical reference for the Librarian's side of this: [`../roles/librarian/definition.md`](../roles/librarian/definition.md); the CLAUDE.md-immutability rule and the synthesis mandate that replaces the historical append reflex.

### Why the synthesis mandate matters

The Librarian's core method is synthesis, not accretion. Observations do not accumulate at the ends of documents; they are worked into the existing structure so the document reads as a single coherent argument rather than a chronological log. Reading the whole section, locating where the observation fits, restructuring to accommodate; this is the default. The "just add a bullet at the bottom" reflex is banned.

The only exceptions are chronological logs by design (`next-session.md`, `spawn-log.json`; data structures, not knowledge documents) and reference catalogues with entry-per-item shape (the banned-tells reference, for example). Even in the catalogue case, synthesis applies at the category level.


## Cross-operator inheritability; the core vs operator split

The platform's split is **locked** as of 2026-07-05 (see Wave B-3 A-series). What lives where, and why.

| Category | Core (`@stravica-ai/digital-operator-pa`) | Operator instance |
|---|---|---|
| CLAUDE.md | 7-bucket TEMPLATE structure with framing + immutability discipline + startup/session-end routines + entity-location map. Any operator's PA starts here. Stays stable, rarely updated. | Operator-specific overlay content at each `<!-- OPERATOR: ... -->` marker. Rendered CLAUDE.md is the operator's; the template shape is core. |
| Bucket knowledge scaffolds | 7 directories under `packages/core/knowledge/<bucket-slug>/`; README + canonical subdocs per bucket. The shape the operator inherits by copying into `operator/knowledge/`. | Populated content under the copied shape. Operator-specific extensions in the marked hooks. |
| Voice | Voice-guide TEMPLATE structure + 13-category banned-tells TAXONOMY + generic-across-operators baseline bans + new-tell capture procedure. Base `writer` role reads voice from config. | Operator's voice-guide contents, operator's specific banned-tells layered on the baseline (same 13-category shape). |
| Roles (core) | `pa`, `dispatch-briefer`, `writer`, `librarian`, `tool-developer`, `system-admin`, `agent-ops`. Base role LADDER for engineering (Bucket 5). | Nothing to add; inherited from core. |
| Roles (operator) |; | Specialised role LIST; a `linkedin-writer` layering LinkedIn structural rules on top of the base `writer`, a `site-cloner`, a `newsletter-writer`, etc. |
| Autonomy envelope | MECHANISM (schema at `packages/core/schema/autonomy-envelope.schema.json`, `pa autonomy` CLI, session-boot integration surface via CLI, docs). | INSTANCE; the per-agent envelope file with the operator's actual approvals. |
| Dispatch envelope | Full capability matrix + depth findings + isolation semantics + brief-writing implications. Promoted from operator to core in Wave B-3. | Operator continues to reference; no separate operator copy after B-series. |
| Tooling | `pa` CLI (workspace, project, work, gsc, lint, migrate-inspect, launch, knowledge, autonomy, environment). `desk`, `distill`, `memory-sync`, `secrets`, `scheduler`, `sync`, `smoke`, `pa-init`, `slice`, `launch`. | `operator/extensions/tools/`; custom operator tools. Config files the platform tools consume. |
| Environment awareness | `pa environment` CLI (default cache-read / refresh / extended). Reserved `extended` verb dispatches to operator overlay. | `operator/extensions/tools/environment-extended/`; operator overlay that populates additional environment fields (devices, scheduled tasks, MCP auth state, VPN, route quality). |
| Librarian | Synthesis mandate + anti-append rule + CLAUDE.md-immutability rule + hygiene checklist. | Operator-specific staging area, operator-specific destination map. |
| Content publishing | **Out of core.** Content publishing is operator-specific. | `operator/knowledge/content-publishing/`; mission, purpose, engagement rules. `operator/extensions/tools/content-pub/` if the operator ships a scheduler. |
| Individual publishing surfaces (LinkedIn, etc.) | **Out of core.** Individual surfaces are operator-specific. | Operator extensions role + engagement docs if applicable. |

### Bucket 6; content & voice; the baseline / overlay split

Bucket 6 is unique among the seven; it splits between **core baseline** and **operator overlay**:

- **Core ships the 13-category BANNED-TELLS TAXONOMY**, the generic-across-operators bans in categories 1-12 (em-dash filler, "In today's landscape", "delve into", "leverage", etc.), and the new-tell capture procedure.
- **Operator overlays** the operator's specific voice content + operator-specific banned tells layered under the same 13-category shape + operator-specific pipeline routing (e.g. LinkedIn-writer, newsletter-writer).

The overlay convention: operator's `operator/knowledge/writing/banned-ai-tells.md` inherits the shape (same category names, same order); adds operator-specific entries under categories 1-12; fully populates category 13 (Operator-specific) with bans that don't fit the mechanism categories.

Shape enforcement for 0.2.0 is documentation-contract only. A lint rule (`pa lint voice-shape`) may land in a later minor release once the pattern is validated in operator practice.

## The two-dispatch sequence pattern

Wave B-3 introduced a repeating pattern for operator-model refactors that touch both core and operator: **two sequenced dispatches**; an A-series core update PR, then a B-series operator instantiation PR that pins the new core version.

**Why the split.** A single PR spanning both repos would either race the release (operator PR merged before the platform published) or bundle the concerns (harder to review, harder to unwind). Two sequenced PRs give both sides clean review, clean CI, clean release.

**When to use it.** Any refactor where:
- Core template shape or public CLI surface changes.
- Operator content needs to move (typically to reflect the new core shape).
- The change is significant enough to warrant a minor version bump.

**Sequence:**
1. **A-series core PR**; templates, knowledge scaffolds, CLIs, docs, schema. Merges. Version bump PR. Tag. Publish.
2. **B-series operator PR**; pins new core version, regenerates operator artefacts from the new template + overlays, archives superseded operator-side files.

Future operators refactoring their own scaffolds should follow the same shape.

**Load-bearing consequence.** Every future operator adopting the platform inherits the methodology + tooling. They populate their own voice, mission, and surface strategies. Two different operators can run on the same core and produce output in their own distinct voices without either forking the platform.


## Not-goals; what the operating model does NOT prescribe

The core is deliberately narrow. These belong in the operator instance.

- **Specific voice content.** The core ships the shape of a voice doc + the 13-category banned-tells taxonomy + generic-across-operators bans. It does NOT ship any operator's specific voice.
- **Specific mission or purpose.** The core ships the shape of a purpose doc, not any operator's mission.
- **Specific content-publishing tooling.** The core does not include a content-publishing scheduler, a LinkedIn agent, or any surface-specific writer specialisation. Those are operator extensions.
- **Specific engagement patterns.** LinkedIn engagement heuristics, comment-reply patterns, author-selection strategies; all operator concerns.
- **Specific role LISTs.** The core ships the base role LADDER (`tool-developer` → `web-developer` → `product-engineer` → `rcf-engineer`) and the base role definitions (`pa`, `dispatch-briefer`, `writer`, `librarian`, `tool-developer`, `system-admin`, `agent-ops`). The specific specialised-role LIST an operator ships; `linkedin-writer`, `site-cloner`, `seo-analyser`, `newsletter-writer`, etc.; is operator overlay. The ladder pattern is core; the list is operator.
- **Specific scheduling target hosts.** Core describes the scheduling MECHANISM; the operator names the default target host in their overlay. Host names are operator-specific by definition.
- **Specific operator preferences.** Tone, cadence, working hours, communication style are the operator's data. The PA reads them from config; the role definition does not encode them.
- **Specific autonomy-envelope task-type taxonomy.** Core ships an EXAMPLE taxonomy in [`./autonomy-envelope-tracker.md`](./autonomy-envelope-tracker.md) but does NOT enforce it. Operators seed their own taxonomy per their surface types.

If a rule is operator-specific, it stays in the operator instance. Promoting it into the core would restrict every other operator adopting the platform.


## References

Load-bearing docs cross-linked from this doc, gathered here for convenience.

**Role definitions:**
- [`../roles/pa/definition.md`](../roles/pa/definition.md); the PA role.
- [`../roles/dispatch-briefer/definition.md`](../roles/dispatch-briefer/definition.md); the Briefer role.
- [`../roles/writer/definition.md`](../roles/writer/definition.md); the base writer role.
- [`../roles/librarian/definition.md`](../roles/librarian/definition.md); the Librarian, synthesis mandate, CLAUDE.md-immutability rule.

**Standards:**
- [`./standards/briefing-contract.md`](./standards/briefing-contract.md); the 8-section contract.
- [`./standards/tooling.md`](./standards/tooling.md); the tooling standard.

**Discipline docs:**
- [`./knowledge-scaffold.md`](./knowledge-scaffold.md); knowledge system structure.
- [`./entity-location-map.md`](./entity-location-map.md); canonical paths.
- [`./working-directory.md`](./working-directory.md); cwd vs operator repo root.
- [`./workspace-operations.md`](./workspace-operations.md); workspace server.
- [`./upstream-issue-filing.md`](./upstream-issue-filing.md); filing bugs against the platform.

**Templates:**
- `@stravica-ai/digital-operator-pa/templates/voice-guide.md`; voice-guide skeleton.
- `@stravica-ai/digital-operator-pa/templates/banned-ai-tells.md`; banned-tells skeleton.
- `@stravica-ai/digital-operator-pa/templates/purpose.md`; purpose / mission skeleton.
- `../../scaffold/templates/CLAUDE.md.template`; three-leg CLAUDE.md skeleton (via `pa-init`).

**CLIs:**
- `pa knowledge --help`; retrieval verbs and flags.
- `pa --help`; the top-level operator CLI.
- `desk --help`; read-only overviews.