@openengio/cli 0.0.0-stage → 0.24.3

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.