@openengio/cli 0.0.0-stage → 0.23.3

package/skill/openeng/SKILL.md

@@ -0,0 +1,238 @@
+---
+name: openeng
+description: Use when you need to work with an OpenEngineering platform through its command line, `openeng`. Signing in, listing projects and types, editing object types, writing objects on a branch and submitting them for review.
+---
+
+# Working with the platform through `openeng`
+
+`openeng` is the platform's command line. Install the public npm package:
+
+```
+npm install -g @openengio/cli
+```
+
+Upgrading from `@benjaminfh/oe2`: first run the earlier package's `logout` command, so its stored
+session does not stay on this machine; then uninstall it and install `@openengio/cli`. The command
+is now `openeng`, the environment variables are
+`OPENENG_HOST`, `OPENENG_SIGN_IN_ORIGIN` and `OPENENG_SESSION_STORE`, and you sign in again once
+with `openeng login`.
+
+This skill gives the commands and their order. It gives no input shapes, because the commands print
+their own. Before you send a generated command (`objects-sdk`, `branches-sdk` and the other
+`<module> <method>` commands), run `openeng help <module> <method>`. It prints the fields, the kinds a
+field may take, the selector keys and one example input, and needs no sign-in.
+
+## Read the topic for your task
+
+- A person new to OpenEngineering who wants a tour, or has just signed in with no task of their own: `openeng skill demo`.
+
+- Designing a new use case: `openeng skill new-use-case`.
+- Building an object drawer or App view: `openeng skill build-ui`.
+- Field meanings, edge direction, trees and type versions: `openeng skill conventions`.
+- A domain model: `openeng skill playbook engineering-requirements`,
+  `openeng skill playbook product-lifecycle`, or `openeng skill playbook project-management`.
+
+## Rules that hold for every command
+
+- Add `--json` when you read the answer yourself. It prints one JSON value on standard output.
+- Exit code 0 is success. Any other exit code is a refusal or a failure, and its message says what
+  to do. Read it; do not retry the same command unchanged.
+- When you report a refusal to the person, quote its `reference:` line (the `reference` field under
+  `--json`) exactly. The line is how the platform's operators find the request. A refusal with no
+  such line was built by `openeng` itself, or the host sent no id with it.
+- A refusal of a field names the field, such as `input.correlation`, and the kinds it may take.
+  Fix that field and send the command again.
+- `openeng help` lists every command. `openeng help <command words>` prints one command's help: what it
+  does, an example and the shape of its output. `openeng help <group>` lists a group's commands.
+  `openeng --version` prints the published version.
+- `openeng` has no host built in. The production host is `https://api.openeng.io`: pass
+  `--host https://api.openeng.io`, or set `OPENENG_HOST=https://api.openeng.io` once.
+- `openeng orgs list` and `openeng organisations list` mean `openeng org list`; `openeng project list` means
+  `openeng projects list`.
+- A mutation or a branch command that needs a `correlation` mints it for you when your input has
+  none. Leave it out unless you have a reason to send your own.
+- Generated commands take `--selector <json>` for what they act on and `--input <json>`,
+  `--input -` or `--input-file <path>` for what they send. Read the ids you need from `--json`
+  output and never invent one.
+
+## 1. Sign in and orient
+
+1. `openeng help` to see what exists.
+2. `openeng login`. It opens a browser to sign in; `openeng login --no-open` prints the address instead.
+3. `openeng whoami` to confirm who you are.
+4. `openeng org list --json` prints the organisations you belong to. `openeng org attach <id>` attaches
+   your session to one. If you have no organisation, create one with
+   `openeng org create --name <name>`, then attach to the organisation it created.
+5. Until you attach, these commands run without an organisation: `openeng login`, `openeng logout`,
+   `openeng whoami`, `openeng help`, `openeng skill`, `openeng org list`, `openeng org attach <id>`,
+   `openeng org create --name <name>`, and `openeng org current`. The generated command
+   `openeng admin-sdk createOrganisation` also runs unattached. Other commands refuse with "not attached
+   to an organisation" before they send anything.
+6. `openeng projects list --json`. Note each project's id and its namespace; later steps need both.
+7. `openeng types list --project <project id>` to see the project's published types, each with its
+   published version.
+
+For a generic open-cycle gas turbine demonstration project, run `openeng demo seed --project <project id> [--size standard|full]`.
+
+### Which organisation you are in
+
+- `openeng org current` prints the organisation your session is attached to, or none.
+  `openeng org detach` removes the attachment, and the commands refuse again until you attach.
+- The CLI passes no scope for `openeng login`, `openeng logout`, `openeng whoami`, `openeng help`, `openeng skill`,
+  `openeng org list`, `openeng org attach <id>`, `openeng org create --name <name>`, `openeng org current`,
+  `openeng org detach`, and `openeng admin-sdk createOrganisation`. Other commands print their scope on
+  standard error when the platform answers them, as
+  `org: <name> (<id>)`, then `· project: <id>` and `· ref: <ref>` when you named them. Read it
+  before you trust an answer.
+- With `--json`, the one value on standard output carries the same scope as a `scope` object:
+  `{"organisation": {"id", "name"}, "project"?, "ref"?}`. An object value gains a `scope` key.
+  A value that is an array or null, such as the list from `openeng projects list`, comes wrapped as
+  `{"scope": {...}, "value": <the original value>}`. A command with no scope carries no `scope`
+  field.
+- A `not-found` in an organisation is often a project or a ref that belongs to another one. The
+  command prints "not found in organisation <name>: check that you are attached to the correct
+  organisation (openeng org current)". Run `openeng org current`; if it names the wrong organisation,
+  `openeng org list` and `openeng org attach <id>`.
+
+## 2. Define or change object types
+
+Edit a file, not the published types directly. The change is a draft that is checked, reviewed and
+then accepted.
+
+If `openeng types list` says `no published types`, start the type file from the `changes` map in the
+example input printed by `openeng help ontology-sdk reviseChangeSet`. Read `openeng help types draft revise`
+to understand each part, then design the model with the person before you draft it.
+
+1. If the project has published types, run `openeng types export --project <project id> > draft.json`;
+   it writes them as one JSON object keyed by type key, each at the next version, ready to send
+   with revise. If it has no published types, create `draft.json` from the `changes` map in the
+   example input printed by `openeng help ontology-sdk reviseChangeSet`.
+2. Make `draft.json` hold only the types you change: delete every other key, and keep each type you
+   keep whole, as the export wrote it. Accepting a type you did not change publishes an identical
+   new version of it.
+3. `openeng types draft open` opens a change set on your organisation's namespace. It prints the change
+   set id and a revision. If one is already open, `openeng types draft current` shows it.
+4. `openeng types draft revise --change-set <id> --revision <revision> --from draft.json` sends your
+   file. It prints the new revision. Use the newest revision in every later step.
+5. `openeng types draft validate --change-set <id> --revision <revision>` must report no violations.
+   It exits 0 when there are no violations, and exits 4 with the violations on standard output
+   otherwise; then edit the file and revise again.
+6. `openeng types draft show --change-set <id> --project <project id>` shows what changes against the
+   published types, per type and per field. Check that it is exactly the change you meant.
+7. `openeng types draft accept --change-set <id> --revision <revision>` publishes it. The new version
+   is now the published one: from here on, take a type's version for data writes from
+   `openeng types list`.
+
+To abandon a draft, `openeng types draft discard --change-set <id>`.
+
+`presentationBindings.typeIcon` is a Material Symbols Rounded name from the installed
+`@material-symbols/font-400` set, such as `memory` or `developer_board`, not an arbitrary label
+(for example, `cpu` is invalid). `openeng types icons <text>` lists valid names and needs no sign-in; the full list is at https://docs.openeng.io/reference/icons/.
+Publication refuses unknown or empty names. Existing unknown icons show an empty box and
+must be corrected before publishing that type again.
+
+An object type's `subscriptionRoles` field declares which roles it admits: owner, approver or watcher.
+Owner is limited to one; approver and watcher may have optional maxima. Without the field, only
+watchers are admitted; the publication validator decides whether a declaration is valid.
+
+## 3. Write data
+
+Data is written on a branch and then submitted for review.
+
+1. `openeng help objects-sdk mutate` and `openeng help branches-sdk createBranch` for the fields, the
+   selector keys and an example each.
+2. `openeng branches-sdk createBranch` makes a branch in the project. It answers the branch's ref,
+   written `<project id>/<name>`.
+3. `openeng objects-sdk mutate` creates, changes or deletes an object or an edge on that ref. A ref in
+   a selector takes one of two forms: the project's trunk is the bare `main`, with no project id;
+   a branch is its whole ref, `<project id>/<name>`, the slash and the project id included. Use
+   `main` to read what is published, and the branch's ref to read or write your own work, here and
+   for `openeng objects-sdk readObject` and `openeng objects-sdk queryObjects`.
+4. Read back what you wrote: `openeng objects-sdk readObject` for one object, or
+   `openeng objects-sdk queryObjects` for a list. Use the type key and version the project's
+   `openeng types list` showed.
+5. `openeng objects-sdk executeVerb` runs a verb a type defines. `openeng objects-sdk discoverVerbs` lists
+   the verbs available.
+6. `openeng branches-sdk submitProposal` sends the branch for review. It names the branch by its
+   `name` alone, the part of the ref after the slash.
+
+If a command is refused, the refusal names the field and its allowed kinds. Run
+`openeng help <module> <method>` again and compare.
+
+## 4. Link to a page
+
+To give the person a page, run `openeng link` and hand them the address it prints; never write a path
+or an address yourself. `openeng link <kind> --project <id> --ref <ref>` takes `explore`, `branch-diff`
+or `project`; `openeng link <kind> <identifier> --project <id> --ref <ref>` takes `object`, `type`, `proposal` or
+`app` (the app's first page); `openeng link app-page <appKey> <pageKey> --project <id> --ref <ref>` takes
+one page of an app; `openeng link app-draft <appKey> --ref <ref>` takes the app's draft screen and no
+project. `openeng link ontology --ref <ref>` and `openeng link change-set --ref <ref>` take a ref and no
+project, and `openeng link organisation-page <page>` takes neither flag. The organisation is the one
+your session is attached to.
+
+## 5. Show data to the person
+
+The CLI draws nothing. Read the `--json` output of a query or a read and draw it yourself, as a
+table or a tree in ASCII, or as a Mermaid diagram when the person's tool renders it. Draw only
+what the output holds.
+
+## 6. Connect an Onshape account
+
+The connector commands import an Onshape account's documents into a mirror project. Each
+command's help, such as `openeng help connector create` or `openeng help connector run`, names the
+capability it needs. Through the CLI you act with the signed-in person's user token, so you can do
+what that person may and nothing more.
+
+Before you create a connection, tell the person this, because create prints it on standard error
+and the person must know it: "Everyone with access to this project sees every document this
+Onshape account can see."
+
+The order, from no connection to a first imported document:
+
+1. `openeng connector create --system onshape --stack <stack> --name <text> [--company <id>]
+   [--team <id> | --owner <id>] [--label <text>]`. `--stack` is the Onshape stack label, as in
+   `cad`. At most one of `--team` and `--owner`. With neither, `--company` is required and must be the
+   company's own identifier, never a user's. It prints the connection identifier and the change
+   set it drafted for the connector's types, or the rule that stopped the drafting.
+2. `set-credential <connection>`: the command reads the access key and the secret key at a terminal
+   prompt only, with no flag and no environment variable. Do not ask for the Onshape keys, do not
+   accept them in the conversation, and do not type them on the person's behalf. Ask the person to
+   run `openeng connector set-credential <connection>` at their own terminal. Setting it again replaces
+   the stored credential. The person can cancel at either prompt with Control-C; the command then
+   says no keys were set.
+3. A person who holds `administer types` reviews the change set (`openeng types draft show
+   --change-set <id> --project <mirror project id>`) and accepts it (`openeng types draft accept
+   --change-set <id> --revision <token>`). Until then a run refuses with `types-not-approved`.
+   `openeng connector draft-types <connection>` drafts again.
+4. `openeng connector run <connection>` prints the run identifier. `openeng connector runs <connection>`
+   lists the runs newest first with state, counts and failure kind; read it until the state is
+   `succeeded` or `failed`.
+5. `openeng connector revoke <connection>` ends the connection.
+
+Mirrored objects are read-only in practice: the next import sets back a person's change to a
+mirrored property and counts it `overwritten`. The next import also creates a deleted mirrored
+object again, with a new identifier, and counts it `created`; links people made to the old object
+are gone. Do not write to a mirror project expecting the change to stay.
+
+Refusals you will meet, with what each means and what to do:
+
+- `types-not-approved`: the connector's types wait for approval by a person who holds the
+  permission to administer types. Ask such a person to review and accept the connector's change
+  set; read it with `openeng types draft current`.
+- `import-running`: a run of this connection is already running. List the connection's runs with
+  `openeng connector runs <connection>`.
+- `connection-revoked`: the connection is revoked, so it takes no further change or run. A new
+  connection makes a new mirror project.
+- `not-permitted`: the operation was refused. What the request names may not exist, or the person
+  may not have permission for it; the answer is the same either way. Check that the request names
+  something the person can reach; if it does, the person must ask an administrator for the
+  permission.
+- `credential-not-valid`: Onshape did not accept the credential, and nothing was stored. The person
+  checks the keys and runs `set-credential` again.
+- `connection-exists`: the organisation already has a live connection to this account on this
+  stack. List the connections with `openeng admin-sdk listConnections` rather than creating another.
+- `connector-template-missing`: this deployment holds no type template for the connector's system.
+  No remedy is in your reach; tell the person.
+- `change-set-open`: the organisation already has an open change set, so drafting the types
+  stopped. Read it with `openeng types draft current` and continue with it; the connection exists, and
+  `openeng connector draft-types <connection>` drafts once that change set is settled.

package/skill/playbooks/engineering-requirements.md

@@ -0,0 +1,121 @@
+# Playbook: an engineering requirements platform
+
+For a team that wants what DOORS or Jama gives it: requirements, their decomposition, how designs meet
+them, how they are verified, and the risks against them, all traced. Read `openeng skill conventions` first.
+
+## Reference products, and what sets them apart
+
+| product | organised around | what that means for a model |
+|---|---|---|
+| IBM DOORS (classic) and DOORS Next | **documents**: a module is a specification, an ordered outline of headings and "shall" statements; links run between objects in different modules | a document type and section headings, with order, become types of their own |
+| Jama Connect | **items** in a project tree organised by components (a system or subsystem), sets and folders; typed relationships with rules from an upstream item type to a downstream one; coverage from those rules | the system tree is the backbone and every item hangs off a system; a document is a view or an export, not a type |
+| SysML tools | **model elements** with «satisfy», «verify», «deriveReqt» relationships that point at the requirement | the same item model, with arrows drawn at what is proved |
+
+On this platform the item-centric shape fits best: every item is an object, every relationship an edge,
+and a specification document is a view of a system's subtree. Choose the document-centric shape only
+when the team's deliverable is the document itself and its order matters more than its traces.
+
+## The decisions that shape the model
+
+1. **Organised around systems or around documents.** Recommend systems. A document-centric model needs a
+   `document` and a `section` type, an `order` property, and one structural edge per pair of parent and
+   child types, because each edge end takes one type.
+2. **One requirement type, or one per level** (stakeholder need, system, subsystem). Recommend one type
+   whose level comes from where it sits in the system tree: one decomposition edge then serves every
+   level. One type per level gives each level its own fields, but every pair of levels needs its own
+   decomposition edge.
+3. **Requirement against specification.** The requirement is the need (what must be true); the
+   specification is the design's answer (a chosen value or standard), joined by a satisfaction edge. The
+   alternative, a specification as a stricter requirement, joins them by decomposition instead.
+4. **What a verification proves.** Recommend requirements only. Jama's design-control practice puts the
+   acceptance criteria in the requirement and links the test to it; the specification is proved through
+   the requirement it satisfies. Proving specifications directly takes a second verification edge.
+5. **How a risk relates.** Recommend the risk upstream of the requirement that mitigates it
+   (`mitigated-by`), as Jama's traceability runs "from risks to mitigation", so "a risk with no
+   mitigation" is a coverage question. The
+   alternative, a risk hanging downstream of the requirement it threatens, keeps the requirement as the
+   anchor.
+6. **The direction convention**, "flow of work" or "points at what is proved" (`openeng skill conventions`,
+   section 3). The two worked models below take one each.
+7. **Identifiers.** The platform keeps no counter, so a human-readable identifier such as `SYS-042` is a
+   string the author or agent sets, by a prefix per system or level.
+
+## Worked model A: flow of work
+
+Every edge's source is its upstream end.
+
+| object type | one object is | title | required |
+|---|---|---|---|
+| `system` | a system, subsystem or component; systems nest | `name` | `identifier`, `name`, `level` |
+| `requirement` | one "shall" statement, owned by one system | `title` | `identifier`, `title`, `statement`, `category`, `status`, `priority` |
+| `specification` | the design's answer to a requirement | `title` | `identifier`, `title`, `statement`, `status` |
+| `verification` | a planned test, analysis, inspection or demonstration | `title` | `identifier`, `title`, `method`, `status` |
+| `verification-result` | one execution of a verification | `identifier` | `identifier`, `outcome`, `runDate` |
+| `risk` | something that could go wrong | `title` | `identifier`, `title`, `severity`, `likelihood`, `status` |
+
+Enumerations: requirement `category` (functional, performance, interface, constraint, safety,
+regulatory), `status` (draft, in-review, approved, released, rejected, deprecated), `priority` (must,
+should, could), `verificationMethod` (test, analysis, inspection, demonstration); verification `status`
+(planned, ready, obsolete); result `outcome` (pass, fail, blocked, inconclusive); risk `severity`
+(negligible to catastrophic), `likelihood` (rare to almost-certain), `status` (open, mitigated, closed).
+Performance requirements carry optional `unit`, `targetValue` and `tolerance`.
+
+| edge type | source to target | kind | parent end | reads from the source / the target |
+|---|---|---|---|---|
+| `contains` | system to system | structural | source | contains / part of |
+| `has-requirement`, `has-specification`, `has-verification`, `has-risk` | system to each | structural | source | has … / … of |
+| `has-result` | verification to verification-result | structural | source | has result / result of |
+| `derives` | parent requirement to child requirement | traceability | source | derives / derived from |
+| `satisfied-by` | requirement to specification | traceability | null | satisfied by / satisfies |
+| `verified-by` | requirement to verification | traceability | null | verified by / verifies |
+| `mitigated-by` | risk to requirement | traceability | null | mitigated by / mitigates |
+
+Every edge reads `both-endpoints`. `requirement` lists `["has-requirement", "derives"]` and declares two
+views, "By system" (`has-requirement`) first and "Decomposition" (`derives`). The rail has one group,
+"Requirements management", in the order system, requirement, specification, verification, result, risk.
+The trace reads left to right: system, requirement, child requirement, specification, verification,
+result.
+
+## Worked model B: points at what is proved
+
+The platform's own agent's teaching example. The arrow points at the requirement.
+
+| edge type | source to target | kind | parent end |
+|---|---|---|---|
+| `contains` | system to system | structural | source |
+| `has-requirement`, `has-specification`, `has-verification`, `has-risk` | system to each | structural | source |
+| `derives` | child requirement to parent requirement | traceability | target |
+| `satisfies` | specification to requirement | traceability | null |
+| `verifies` | verification to requirement | traceability | null |
+| `threatens-requirement` | risk to requirement | traceability | null |
+
+Choose B for a team whose engineers read SysML or whose model will meet a SysML tool.
+
+## Questions the model answers, and how
+
+| question | how |
+|---|---|
+| which requirements have no verification | requirements with no `verified-by` edge (model A: outgoing; model B: no incoming `verifies`) |
+| which risks have no mitigation | risks with no `mitigated-by` edge |
+| what a requirement breaks down into | the "Decomposition" tree, or `derives` from it |
+| how a requirement is proved | the path requirement to verification to result |
+| what a system must do | the "By system" tree under that system |
+
+## Sensible hybrids
+
+- **Document views over the item model**: keep the system-centric types and give a system's subtree a
+  page that reads as a specification, rather than adding document and section types.
+- **Requirements beside a product structure**: where the organisation already has parts (a PLM model),
+  link requirements to the parts that meet them instead of duplicating systems as parts.
+
+## Joining an existing catalogue
+
+- Reuse an existing `system`, `part` or `component` type for the breakdown rather than add a second one.
+- Use the existing model's direction convention, even where this playbook recommends the other.
+- Follow its rail groups, naming and icons; add a "Requirements" group only when none fits.
+
+## Not on the platform today
+
+- **Suspect links**: DOORS and Jama mark a link when its upstream end changes. Nothing does this yet; a
+  team can review changes through a proposal's diff and an object's history.
+- **Coverage percentages** across levels: a count per question is a query; a roll-up is not built.

package/skill/playbooks/product-lifecycle.md

@@ -0,0 +1,115 @@
+# Playbook: a product lifecycle management platform
+
+For a team that wants what Teamcenter, Windchill or Arena gives it: parts and their revisions, the bill of
+materials a product is built from, how it is made, and how changes to all of it are requested, approved and
+released. Read `openeng skill conventions` first.
+
+## Reference products, and what sets them apart
+
+| product | organised around | what that means for a model |
+|---|---|---|
+| Siemens Teamcenter, PTC Windchill | **items and item revisions** under lifecycle states (for example Prototype, PreReleased, Released, Canceled), with structured BOMs, alternates and formal change workflows | revisions are objects of their own; state is an enumeration on the revision |
+| Arena (a PTC business) | **items and change orders** for hardware teams: an ECO lists its affected items, each with old and new revision and old and new lifecycle phase, and refers to the ECR it came from | change requests and change orders are objects; what a change does to each revision is recorded on the link |
+| Onshape, Fusion release management | **CAD documents** with versions and releases | the geometry lives in the CAD tool; the model holds the part, its revisions and a reference to the released CAD version |
+
+Across them: a **change request** (ECR) records a problem and a proposal; a **change order** (ECO) carries out
+the approved change and lists what it affects. An **EBOM** is the product as designed; an **MBOM** is the
+product as it is built, with plant, make-or-buy, alternates, routing and work instructions added.
+
+## The decisions that shape the model
+
+1. **Which BOM is the base.** This playbook takes the **MBOM** as the base case: the structure the shop floor
+   builds from, with each line's quantity and unit of measure, the operation that consumes it, and its
+   alternates. An EBOM beside it is a hybrid (below).
+2. **A revision as an object, or as the part's history.** Recommend objects. The platform keeps every object's
+   history anyway, but only an object can be pinned by a BOM line, released, or named by a change order.
+3. **A BOM line as an object, or as an edge with properties.** Recommend an object. An edge can carry quantity,
+   but a BOM line also pins a revision and is consumed by an operation, and an edge cannot point at an edge.
+4. **How change is modelled.** `change-request` and `change-order` are objects; the change itself is made on a
+   branch, submitted as a proposal, and merged; the change order links the revisions it affects, with each
+   revision's old and new state on the link. The platform's proposal alone would carry the change
+   but not the record an engineering team needs: the reason, the affected items, and their states.
+5. **Make or buy, per part or per plant.** Recommend a property on the part for a single-plant team, and on the
+   BOM line when the same part is made in one plant and bought in another.
+6. **The direction convention.** This playbook uses "flow of work" (`openeng skill conventions`, section 3): assembly to
+   line to component, request to order to revision.
+
+## Worked model: a manufacturing BOM
+
+| object type | one object is | title | required |
+|---|---|---|---|
+| `part` | a part or assembly, as identified by its part number | `name` | `partNumber`, `name`, `makeOrBuy` |
+| `revision` | one released or in-work state of a part | `revisionCode` | `revisionCode`, `lifecycleState` |
+| `mbom-line` | one placement of a component in an assembly as built | `findNumber` | `findNumber`, `quantity`, `unitOfMeasure` |
+| `operation` | one step of a part's routing | `name` | `sequence`, `name` |
+| `work-centre` | a machine, cell or station where operations run | `name` | `code`, `name` |
+| `plant` | a factory or site | `name` | `code`, `name` |
+| `change-request` | a problem and a proposed change (ECR) | `title` | `identifier`, `title`, `status` |
+| `change-order` | an approved change being carried out (ECO) | `title` | `identifier`, `title`, `status` |
+| `release` | a set of revisions released together | `name` | `identifier`, `name`, `releasedOn` |
+
+Enumerations: part `makeOrBuy` (make, buy); revision `lifecycleState` (in-work, prototyping, pre-released,
+released, obsolete); mbom-line `unitOfMeasure` (each, kg, m, l); change-request `status` (open, in-review,
+approved, rejected); change-order `status` (planned, in-work, released, cancelled). A line may carry optional
+`scrapFactor`; an operation optional `setupMinutes` and `runMinutes`. The state many PLM systems call
+"Prototype" is `prototyping` here, because the platform refuses `prototype` as an enumeration member
+(`openeng skill conventions`, section 7).
+
+| edge type | source to target | kind | parent end | reads from the source / the target |
+|---|---|---|---|---|
+| `has-revision` | part to revision | structural | source | has revision / revision of |
+| `itemises` | part (assembly) to mbom-line | traceability | source | itemises / line of |
+| `uses` | mbom-line to part (component) | traceability | source | uses / used on |
+| `pins` | mbom-line to revision | traceability | null | pins / pinned by |
+| `has-operation` | part to operation | structural | source | has operation / operation of |
+| `consumed-at` | mbom-line to operation | traceability | null | consumed at / consumes |
+| `performed-at` | operation to work-centre | traceability | null | performed at / performs |
+| `has-work-centre` | plant to work-centre | structural | source | has work centre / work centre of |
+| `alternate` | mbom-line to part | traceability | null | alternate / alternate for |
+| `raises` | change-request to change-order | traceability | null | raises / raised by |
+| `affects` | change-order to revision | traceability | null | affects / affected by |
+| `releases` | release to revision | traceability | null | releases / released by |
+
+`affects` carries the change's effect on each revision as edge properties, `fromState` and `toState`, both
+the revision's lifecycle enumeration. `alternate` carries an optional `priority`. `itemises` and `uses` are
+traceability with a parent end, so a shared component appears under every assembly that uses it.
+
+Trees and the rail: `part` declares the view "Manufacturing structure", steps `itemises` then `uses`, decorated
+with the line's find number, quantity and unit of measure, first; and "Routing", step `has-operation`. A
+`plant` tree shows its work centres. The rail group "Manufacturing" places part, change request, change order,
+release and plant; `mbom-line`, `revision`, `operation` and `work-centre` carry no `rail`, because each is
+reached through a part or a plant.
+
+## Questions the model answers, and how
+
+| question | how |
+|---|---|
+| what is this assembly built from, with quantities | the "Manufacturing structure" tree under the assembly |
+| where is this part used | the parts reached backwards through `uses` then `itemises` (`findPaths` or `queryGraph`, incoming) |
+| which revision does each line build | each line's `pins` edge |
+| how is this part made, and where | its "Routing" tree, and each operation's `performed-at` |
+| what did this change touch | the change order's `affects` edges, with old and new state |
+| which open changes affect this part | change orders with an `affects` edge to one of its revisions, status not released |
+
+## Sensible hybrids
+
+- **EBOM and MBOM together**: an `ebom-line` type beside `mbom-line`, both from `part`, and an edge from each
+  MBOM line to the EBOM line it realises; the EBOM is the design's structure, the MBOM the plant's.
+- **PLM with requirements**: link the requirements model's `specification` or `system` to the `part` that
+  realises it (`openeng skill playbook engineering-requirements`), so a change order can be traced to the requirements it
+  touches.
+- **Several plants**: make-or-buy, scrap and routing move from the part to the line or to a per-plant object.
+
+## Joining an existing catalogue
+
+- Reuse an existing `part`, `component` or `system` type for the product breakdown rather than add a second.
+- Use the existing model's direction convention.
+- Where a requirements model exists, add the realisation edge above rather than duplicating systems as parts.
+
+## Not on the platform today
+
+- **Effectivity** (a line valid from a date or a serial number): a date property is possible; nothing filters
+  a structure by it.
+- **Mass change** of many lines, and a **cost roll-up** across a structure: a count per question is a query, a
+  roll-up is not built.
+- **CAD geometry**: an object view can show an STL property (`STLViewer`); there is no live CAD link.

package/skill/playbooks/project-management.md

@@ -0,0 +1,100 @@
+# Playbook: a project management platform
+
+For a team that wants what Jira, Linear or MS Project gives it: work broken into items, grouped into projects
+and timeboxes, with dependencies between them, and, on this platform, tied to the engineering items the work
+advances. Read `openeng skill conventions` first.
+
+## Reference products, and what sets them apart
+
+| product | organised around | what that means for a model |
+|---|---|---|
+| Jira | **issues** of configurable types (epic, story, task, sub-task), each type with its own workflow, joined by issue links | one type per level, or one type with a kind; links are edges |
+| Linear | **issues** in one fixed workflow (Backlog, Unstarted, Started, Completed, Canceled), priority 0 to 4, grouped by cycles (sprints), projects with milestones that span cycles, and initiatives above projects; an issue need not belong to a project | one work-item type with a kind; cycles, projects and milestones are objects |
+| MS Project | **a schedule**: tasks with durations, dependencies of four kinds (finish-to-start, start-to-start, finish-to-finish, start-to-finish) with lag, and the critical path computed from them | dates follow from dependencies; this platform has no scheduler, so dates are properties and dependencies are edges to query |
+
+## The decisions that shape the model
+
+1. **Issue-centric or schedule-centric.** This platform computes no dates, so a model here is issue-centric:
+   start and due dates are properties, and a dependency is an edge to query, not a constraint that moves dates.
+2. **One work-item type with a kind, or a type per level.** One `work-item` type with `kind` (epic, story, task,
+   bug), as Linear does: one hierarchy edge serves every level, and a query filters by kind.
+   The
+   cost is that nothing stops a task being the parent of an epic; the playbook's hierarchy is a convention the
+   person and the agent keep. A type per level would enforce it, with one hierarchy edge per pair of levels.
+3. **Timeboxes.** Cycles as objects, so "what is in cycle 12" is a query, not a label.
+4. **Joining the engineering work.** A work item links to the engineering items it advances: a requirement, a
+   part, a verification. This is the reason to run project work on this platform rather than in
+   Jira: "which work is open against BAT-001" and "which requirements have no work planned" become queries over
+   one model.
+5. **The direction convention.** "Flow of work" (`openeng skill conventions`, section 3): container to item, earlier to
+   later, work to what it advances.
+
+## Worked model: issues tied to engineering
+
+The `advances` edges assume the requirements model's `requirement` and the PLM model's `part` exist
+in the organisation; drop the
+ones whose target type is absent.
+
+| object type | one object is | title | required |
+|---|---|---|---|
+| `initiative` | a goal several projects serve | `name` | `name`, `status` |
+| `project` | a body of work with a lead and an end | `name` | `name`, `status` |
+| `milestone` | a point a project must reach by a date | `name` | `name`, `dueOn` |
+| `work-item` | one piece of work: an epic, story, task or bug | `title` | `identifier`, `title`, `kind`, `status`, `priority` |
+| `cycle` | a timebox, such as a two-week sprint | `name` | `name`, `startsOn`, `endsOn` |
+
+Enumerations: work-item `kind` (epic, story, task, bug), `status` (backlog, unstarted, started, completed,
+cancelled), `priority` (urgent, high, medium, low, none); initiative and project `status` (planned, active,
+completed, cancelled). A work item carries optional `owner` (a person), `estimate` (a number) and `dueOn`; a
+project carries `lead` (a person).
+
+| edge type | source to target | kind | parent end | reads from the source / the target |
+|---|---|---|---|---|
+| `has-project` | initiative to project | structural | source | has project / project of |
+| `has-milestone` | project to milestone | structural | source | has milestone / milestone of |
+| `has-work-item` | project to work-item | structural | source | has work item / work item of |
+| `breaks-into` | work-item to work-item | traceability | source | breaks into / part of |
+| `targets` | work-item to milestone | traceability | null | targets / targeted by |
+| `planned-in` | cycle to work-item | traceability | null | plans / planned in |
+| `blocks` | work-item to work-item | traceability | null | blocks / blocked by |
+| `advances-requirement` | work-item to requirement | traceability | null | advances / advanced by |
+| `advances-part` | work-item to part | traceability | null | advances / advanced by |
+
+`breaks-into` is traceability with a parent end, so a story can sit under its epic while its home is its
+project. A work item outside any project has no `has-work-item` edge and is a root of its own. Each `advances`
+target is its own edge type, because an edge end takes one type.
+
+Trees and the rail: `work-item` declares "By project" (`has-work-item`) first and "Breakdown" (`breaks-into`); an
+initiative's tree shows its projects. The rail group "Planning" places initiative, project, work item and
+cycle; `milestone` is reached through its project.
+
+## Questions the model answers, and how
+
+| question | how |
+|---|---|
+| what is in this cycle | work items with a `planned-in` edge from the cycle |
+| what is blocked, and by what | work items with an incoming `blocks` edge whose source is not completed |
+| what does this epic break into | its "Breakdown" tree |
+| which work is open against a requirement | work items with an `advances-requirement` edge to it, status not completed |
+| which approved requirements have no work | requirements with no incoming `advances-requirement` edge |
+| what is due before a milestone | work items with a `targets` edge to it |
+
+## Sensible hybrids
+
+- **Type per level**: `epic`, `story` and `task` types, with `epic-has-story` and `story-has-task` edges, for a
+  team that wants each level's fields and the hierarchy enforced.
+- **A light schedule**: `dependsOn` lag and a dependency kind as properties of `blocks`, read by the person; the
+  platform still computes no dates.
+
+## Joining an existing catalogue
+
+- Add `advances` edges to whatever engineering types the organisation already has; this is the model's main
+  value.
+- Reuse an existing person or team model rather than add `assignee` objects; a `person` property names the owner.
+- Use the existing model's direction convention.
+
+## Not on the platform today
+
+- **Computed schedules**: no critical path, no dates moved by dependencies, no capacity planning.
+- **Workflow enforcement**: a status is an enumeration; nothing stops a jump from backlog to completed.
+- **Burndown and velocity**: counts per cycle are queries; charts over time are not built.