Work Operating Model
A conversation-first elicitation skill. Surface what is documented, what is tacit, and where the two disagree. Output is a structured operating model that downstream agents (architect, roadmap, orchestrator) can read.
Triggers
| Trigger Phrase |
Operation |
elicit operating model |
Start the 5-layer interview |
interview team operating model |
Start the 5-layer interview |
how does this team actually work |
Start the 5-layer interview |
resume operating model interview |
Continue from the first layer not yet captured or skipped |
validate operating model |
Run scripts/validate_operating_model.py against an output JSON |
When to Use
Use this skill when:
- You need a baseline of team practice before an ADR, retrospective, or scope decision.
- A new agent or skill needs to be customized to a team's actual cadences and decision rights.
- A planning conversation keeps getting derailed by missing context about how the team operates.
Do not use this skill when:
- The question is about code, not people-process. Use the
analyst agent.
- You need a strategic narrative for an external audience. Use the
explainer agent.
- A retrospective is what you actually need. Use the
retrospective agent.
Distinction From Adjacent Capabilities
| Capability |
Investigates |
Output |
analyst agent |
Code, repo state, bug paths |
Findings document |
explainer agent |
Concepts, decisions for a reader |
Explainer prose |
retrospective agent |
A bounded past period |
Learning matrix |
| work-operating-model |
Team operating reality (people-process) |
Structured operating model JSON |
The 5 Layers
The interview proceeds in order. Each layer answers one question and produces one section of the output JSON. Skip a layer only when the team explicitly cannot answer it; record the gap in metadata.skipped_layers.
| # |
Layer |
Question |
Output Section |
| 1 |
Rhythms |
When does work happen, and on what cadence? |
rhythms |
| 2 |
Decisions |
Who decides what, and how is the decision recorded? |
decisions |
| 3 |
Dependencies |
Who do you wait on, and who waits on you? |
dependencies |
| 4 |
Institutional Knowledge |
What lives in someone's head and not in a doc? |
institutional_knowledge |
| 5 |
Friction |
What is broken or slow that the team has accepted? |
friction |
For the full prompt list per layer, read references/layer-questions.md. For the output JSON contract, read references/entry-contract.md.
Process
The interview runs in three phases.
Phase 1: Open
- Open: Confirm scope (team name, what they own, size). Write the
team section.
Phase 2: Layer Pass
- Layer pass: For each layer 1 through 5, ask the question, capture answers, record them in the relevant output section. After each layer, summarize back to the user and confirm before moving on.
- Distinguish: For every captured item, mark it as
documented (link the doc) or tacit (note the source person). Disagreement between sources is a finding, not an error.
Phase 3: Close and Validate
- Close: Write the JSON to
<workspace>/operating-model.json (caller chooses workspace). Optionally also emit USER.md, SOUL.md, HEARTBEAT.md as human-readable views derived from the JSON. The JSON is canonical; the markdown files are projections.
- Validate: Run
python3 .claude/skills/work-operating-model/scripts/validate_operating_model.py <path-to-json>. Exit 0 means the schema holds.
Scripts
| Script |
Purpose |
Exit Codes |
scripts/validate_operating_model.py <path> |
Validate operating-model.json against schema v1.0.0 |
0 ok, 1 schema failure, 2 invalid usage |
Pass --skip-path-validation to bypass CWE-22 path containment when reading fixtures from outside the repo (tests only).
Resume Across Sessions
The interview is long. To resume:
- Read the existing
operating-model.json.
- Build a resolved-layers set: include every string in
metadata.completed_layers, plus the layer property of each object in metadata.skipped_layers (since skipped_layers stores objects like { "layer": "rhythms", "reason": "..." }, not plain strings). The next layer is the first layer (in the order of The 5 Layers table) whose key is not in this resolved-layers set. A recorded skip is a resolved disposition, not pending work, so never re-ask a layer that appears in metadata.skipped_layers.
- Continue from the start of that layer. If every layer key already appears in the resolved-layers set, there is no next layer: the interview is complete, so set
metadata.interview_status to complete instead of resuming.
Do not silently rewrite an earlier layer. If a previous answer needs to change, open the discussion, then update the section and append to metadata.revisions.
Output Contract (Summary)
The full schema is in references/entry-contract.md. The minimum valid document has:
schema_version: "1.0.0"team: object with namerhythms, decisions, dependencies, institutional_knowledge, friction: each present, each an object (may be empty if a layer was skipped)metadata: object with interview_date (YYYY-MM-DD), interview_status (in_progress or complete), completed_layers (list)
The validator (scripts/validate_operating_model.py) enforces these and returns a non-zero exit on schema failure.
Anti-Patterns
| Anti-Pattern |
Problem |
Fix |
| Treat the interview as a survey to fill in alone |
Misses tacit knowledge entirely |
Hold the conversation; capture during the talk |
Merge documented and tacit into one bucket |
Erases the gap that is the whole point |
Tag every item explicitly |
| Skip layer 4 because it is hard |
Layer 4 is where most useful findings live |
Ask anyway; if unanswered, record it in metadata.skipped_layers with a reason |
| Edit the JSON by hand without reopening the conversation |
Drift between model and reality |
Re-interview, then update |
| Run the interview once and call the model done |
Operating models drift |
Re-validate quarterly; bump metadata.interview_date |
Verification Checklist
Before declaring an operating model complete:
References
references/layer-questions.md - prompt list per layerreferences/entry-contract.md - full output JSON schemascripts/validate_operating_model.py - schema validator
1---2name: work-operating-model3description: Run a 5-layer interview to elicit how a team actually works (rhythms, decisions, dependencies, institutional knowledge, friction) and emit a structured operating model. Use when you say "elicit operating model", "interview team operating model", "how does this team actually work", or "validate operating model". Do NOT use for code analysis (use the analyst agent), external audience narratives (use the explainer agent), or retrospectives (use the retrospective agent).4license: MIT5---67# Work Operating Model89A conversation-first elicitation skill. Surface what is documented, what is tacit, and where the two disagree. Output is a structured operating model that downstream agents (`architect`, `roadmap`, `orchestrator`) can read.1011## Triggers1213| Trigger Phrase | Operation |14|----------------|-----------|15| `elicit operating model` | Start the 5-layer interview |16| `interview team operating model` | Start the 5-layer interview |17| `how does this team actually work` | Start the 5-layer interview |18| `resume operating model interview` | Continue from the first layer not yet captured or skipped |19| `validate operating model` | Run scripts/validate_operating_model.py against an output JSON |2021## When to Use2223**Use this skill when:**2425- You need a baseline of team practice before an ADR, retrospective, or scope decision.26- A new agent or skill needs to be customized to a team's actual cadences and decision rights.27- A planning conversation keeps getting derailed by missing context about how the team operates.2829**Do not use this skill when:**3031- The question is about code, not people-process. Use the `analyst` agent.32- You need a strategic narrative for an external audience. Use the `explainer` agent.33- A retrospective is what you actually need. Use the `retrospective` agent.3435## Distinction From Adjacent Capabilities3637| Capability | Investigates | Output |38|------------|--------------|--------|39| `analyst` agent | Code, repo state, bug paths | Findings document |40| `explainer` agent | Concepts, decisions for a reader | Explainer prose |41| `retrospective` agent | A bounded past period | Learning matrix |42| **work-operating-model** | **Team operating reality (people-process)** | **Structured operating model JSON** |4344## The 5 Layers4546The interview proceeds in order. Each layer answers one question and produces one section of the output JSON. Skip a layer only when the team explicitly cannot answer it; record the gap in `metadata.skipped_layers`.4748| # | Layer | Question | Output Section |49|---|-------|----------|----------------|50| 1 | Rhythms | When does work happen, and on what cadence? | `rhythms` |51| 2 | Decisions | Who decides what, and how is the decision recorded? | `decisions` |52| 3 | Dependencies | Who do you wait on, and who waits on you? | `dependencies` |53| 4 | Institutional Knowledge | What lives in someone's head and not in a doc? | `institutional_knowledge` |54| 5 | Friction | What is broken or slow that the team has accepted? | `friction` |5556For the full prompt list per layer, read `references/layer-questions.md`. For the output JSON contract, read `references/entry-contract.md`.5758## Process5960The interview runs in three phases.6162### Phase 1: Open63641. **Open**: Confirm scope (team name, what they own, size). Write the `team` section.6566### Phase 2: Layer Pass67682. **Layer pass**: For each layer 1 through 5, ask the question, capture answers, record them in the relevant output section. After each layer, summarize back to the user and confirm before moving on.693. **Distinguish**: For every captured item, mark it as `documented` (link the doc) or `tacit` (note the source person). Disagreement between sources is a finding, not an error.7071### Phase 3: Close and Validate72734. **Close**: Write the JSON to `<workspace>/operating-model.json` (caller chooses workspace). Optionally also emit `USER.md`, `SOUL.md`, `HEARTBEAT.md` as human-readable views derived from the JSON. The JSON is canonical; the markdown files are projections.745. **Validate**: Run `python3 .claude/skills/work-operating-model/scripts/validate_operating_model.py <path-to-json>`. Exit 0 means the schema holds.7576## Scripts7778| Script | Purpose | Exit Codes |79|--------|---------|------------|80| `scripts/validate_operating_model.py <path>` | Validate operating-model.json against schema v1.0.0 | 0 ok, 1 schema failure, 2 invalid usage |8182Pass `--skip-path-validation` to bypass CWE-22 path containment when reading fixtures from outside the repo (tests only).8384## Resume Across Sessions8586The interview is long. To resume:87881. Read the existing `operating-model.json`.892. Build a resolved-layers set: include every string in `metadata.completed_layers`, plus the `layer` property of each object in `metadata.skipped_layers` (since `skipped_layers` stores objects like `{ "layer": "rhythms", "reason": "..." }`, not plain strings). The next layer is the first layer (in the order of The 5 Layers table) whose key is not in this resolved-layers set. A recorded skip is a resolved disposition, not pending work, so never re-ask a layer that appears in `metadata.skipped_layers`.903. Continue from the start of that layer. If every layer key already appears in the resolved-layers set, there is no next layer: the interview is complete, so set `metadata.interview_status` to `complete` instead of resuming.9192Do not silently rewrite an earlier layer. If a previous answer needs to change, open the discussion, then update the section and append to `metadata.revisions`.9394## Output Contract (Summary)9596The full schema is in `references/entry-contract.md`. The minimum valid document has:9798- `schema_version`: `"1.0.0"`99- `team`: object with `name`100- `rhythms`, `decisions`, `dependencies`, `institutional_knowledge`, `friction`: each present, each an object (may be empty if a layer was skipped)101- `metadata`: object with `interview_date` (`YYYY-MM-DD`), `interview_status` (`in_progress` or `complete`), `completed_layers` (list)102103The validator (`scripts/validate_operating_model.py`) enforces these and returns a non-zero exit on schema failure.104105## Anti-Patterns106107| Anti-Pattern | Problem | Fix |108|--------------|---------|-----|109| Treat the interview as a survey to fill in alone | Misses tacit knowledge entirely | Hold the conversation; capture during the talk |110| Merge `documented` and `tacit` into one bucket | Erases the gap that is the whole point | Tag every item explicitly |111| Skip layer 4 because it is hard | Layer 4 is where most useful findings live | Ask anyway; if unanswered, record it in `metadata.skipped_layers` with a reason |112| Edit the JSON by hand without reopening the conversation | Drift between model and reality | Re-interview, then update |113| Run the interview once and call the model done | Operating models drift | Re-validate quarterly; bump `metadata.interview_date` |114115## Verification Checklist116117Before declaring an operating model complete:118119- [ ] All 5 layers either captured or explicitly skipped (recorded in `metadata.skipped_layers`).120- [ ] Every item in every layer marked `documented` or `tacit`.121- [ ] `metadata.interview_status` is `complete`.122- [ ] `python3 .claude/skills/work-operating-model/scripts/validate_operating_model.py operating-model.json` exits 0.123- [ ] The team representative has read the final JSON (or its `USER.md` projection) and agreed.124125## References126127- `references/layer-questions.md` - prompt list per layer128- `references/entry-contract.md` - full output JSON schema129- `scripts/validate_operating_model.py` - schema validator
rjmurillo