Add Studio glossary of terms (draft v0.2.32)#10
Conversation
📝 WalkthroughWalkthroughUpdates ChangesStudio Glossary
Estimated code review effort: 2 (Simple) | ~10 minutes Possibly related PRs
🚥 Pre-merge checks | ✅ 5✅ Passed checks (5 passed)
✨ Finishing Touches🧪 Generate unit tests (beta)
Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out. Comment |
There was a problem hiding this comment.
Actionable comments posted: 2
🤖 Prompt for all review comments with AI agents
Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.
Inline comments:
In `@STUDIO_GLOSSARY.md`:
- Around line 4-5: The glossary uses two different version labels, with the
frontmatter status and the heading appearing to reference separate releases.
Update the document so the same version string is used consistently throughout,
or make the meaning of each field explicit if they represent different concepts;
check the frontmatter fields and the heading text in STUDIO_GLOSSARY.md and
align them with one versioning scheme.
- Line 46: The glossary table is using status values that are not part of the
documented legend, so normalize the entries to the existing status vocabulary or
expand the legend to explicitly include the new statuses. Update the affected
rows in STUDIO_GLOSSARY.md, including the Universal 5-step loop entry and the
other referenced rows, so the table and legend use the same consistent set of
status labels throughout.
🪄 Autofix (Beta)
Fix all unresolved CodeRabbit comments on this PR:
- Push a commit to this branch (recommended)
- Create a new PR with the fixes
| | **Plan / Build / Operate** | The 3 high-level lifecycle phases. | — | proposed | | ||
| | **Stage** | A step within a phase. Reference set = 14: Intent → Vision → Discovery → Strategy → Definition → Design → Construction → Validation → Release → Operation → Support → Intelligence → Optimization → Evolution. | lifecycle stage | proposed | | ||
| | **Activity** | Work an actor performs at a stage, with defined Inputs and Outputs. | — | proposed | | ||
| | **Universal 5-step loop** | Collect Knowledge → Build Domain Graph → Generate Hypotheses → Produce Artifacts → Execute Workflows (the cross-domain pattern shared by software / research / M&A). | Hypothesis approach | review/discuss | |
There was a problem hiding this comment.
📐 Maintainability & Code Quality | 🟡 Minor | ⚡ Quick win
Keep status values within the documented set.
review/discuss and target introduce a second status vocabulary that the legend does not define. Please normalize those rows to the existing enum, or extend the legend explicitly so the table stays consistent.
Also applies to: 134-139
🤖 Prompt for AI Agents
Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.
In `@STUDIO_GLOSSARY.md` at line 46, The glossary table is using status values
that are not part of the documented legend, so normalize the entries to the
existing status vocabulary or expand the legend to explicitly include the new
statuses. Update the affected rows in STUDIO_GLOSSARY.md, including the
Universal 5-step loop entry and the other referenced rows, so the table and
legend use the same consistent set of status labels throughout.
f7a79e9 to
1bfee69
Compare
|
Please rebase with main |
1bfee69 to
ad37423
Compare
Foundation artifact: canonical Studio terminology (Canonical · Definition · Source · Aliases · Status). Companion to STUDIO_VISION.md, which the glossary declares as its primary source of truth. Draft — every active term is 'proposed' pending ratification. Signed-off-by: maxvydrin <max.vydrin@gmail.com>
ad37423 to
2fb4fc8
Compare
There was a problem hiding this comment.
Actionable comments posted: 5
🤖 Prompt for all review comments with AI agents
Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.
Inline comments:
In `@STUDIO_GLOSSARY.md`:
- Line 334: Update the World Model definition to use the canonical “Project
Graph” term instead of “SDLC graph,” matching the terminology established by the
relevant glossary entry.
- Line 141: Correct the future-dated rename note in the Project Graph glossary
entry by changing the “Renamed from SDLC Graph” date to July 9, 2026, or update
the document date if July 10 is the intended artifact date.
- Line 223: Update the EPSVS entry in STUDIO_GLOSSARY.md so the Source field is
blank or explicitly identifies ISO/IEC 25010 as inspiration, not authoritative
source; only retain the citation as a source if a formal mapping is documented.
- Line 164: The definitions of “Write-back (Controlled write-back)” at the
referenced glossary entries contradict each other on approval requirements.
Choose a single approval policy—either require human approval universally or
allow policy-governed auto-execution—and update both definitions consistently,
including the corresponding trust-level/sign-off language.
- Around line 62-66: Update the Role definition in the Roles & functions table
to state that a Role is assigned to a Member or Team, matching the
role-assignment contract and Team definition while preserving the existing scope
and RBAC/ABAC details.
🪄 Autofix (Beta)
Fix all unresolved CodeRabbit comments on this PR:
- Push a commit to this branch (recommended)
- Create a new PR with the fixes
|
|
||
| | Canonical | Definition | Source | Aliases | Status | | ||
| | -------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------- | ----------------------------------------------------------- | ------------------ | | ||
| | **Project Graph** | Studio's **mirror / shadow copy** of a Project's SDLC objects, attributes, relationships, states, history and evidence — tracked from source-of-record tools (Jira / Git / CI…), which Studio governs but does **not** own. **One per Project; the system's spine.** *Renamed from "SDLC Graph" (2026-07-10)* to drop the SCLC/SDLC collision. | Vision §13 | SDLC Graph, Shadow SDLC Graph, Delivery Graph, shadow graph | proposed | |
There was a problem hiding this comment.
📐 Maintainability & Code Quality | 🟡 Minor | ⚡ Quick win
Correct the rename date or artifact date.
The document is dated July 9, 2026, but this row says Project Graph was renamed on July 10, 2026. Align the dates so the glossary’s change history is not future-dated.
🤖 Prompt for AI Agents
Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.
In `@STUDIO_GLOSSARY.md` at line 141, Correct the future-dated rename note in the
Project Graph glossary entry by changing the “Renamed from SDLC Graph” date to
July 9, 2026, or update the document date if July 10 is the intended artifact
date.
| |---|---|---|---|---| | ||
| | **Action** | An executable **edge** over the graph — a transformation that turns object(s) into candidate object(s). | Vision "Actions Are Executable Edges" | Method, Job, executable edge | proposed (canonical: Action; *Method* = engine-side alias) | | ||
| | **Transition type** | How an action runs: **deterministic script** / **AI-assisted transformation** / **human task**. | Vision "Core Ideas" | — | proposed | | ||
| | **Write-back (Controlled write-back)** | Studio committing an **approved** change back into the source-of-record tool — create ticket, update doc, open PR, run CI, assign owner. Always human-approved first. | Vision §13 | write-back | proposed | |
There was a problem hiding this comment.
🔒 Security & Privacy | 🟠 Major | 🏗️ Heavy lift
Resolve the write-back approval contradiction.
Line 164 says write-back is “always human-approved first,” while line 312 permits auto-execution within policy and says trust level determines whether sign-off is needed. Choose one approval guarantee and state it consistently in both definitions.
Also applies to: 312-312
🤖 Prompt for AI Agents
Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.
In `@STUDIO_GLOSSARY.md` at line 164, The definitions of “Write-back (Controlled
write-back)” at the referenced glossary entries contradict each other on
approval requirements. Choose a single approval policy—either require human
approval universally or allow policy-governed auto-execution—and update both
definitions consistently, including the corresponding trust-level/sign-off
language.
| | **Comparison matrix** | The quarterly-comparison output Artifact — side-by-side competitors across product & functionality + scale & traction, versioned per quarter. | | quarterly comparison | proposed | | ||
| | **Pricing benchmark** | The pricing-analysis output Artifact — our price vs competitors per geography × tier (normalised), with trend, versioned. | | pricing benchmark grid | proposed | | ||
| | **CEP (Customer Experience Program)** | Weekly practice of analysing our own users' experience (usage + VoC) to find friction → improvement work. | | continuous discovery | proposed | | ||
| | **EPSVS** | Internal 5-dimension quality framework: Efficiency, Performance, Scalability, Versatility, Security. Team-defined, not an industry standard. | ISO/IEC 25010 | — | proposed | |
There was a problem hiding this comment.
🗄️ Data Integrity & Integration | 🟡 Minor | ⚡ Quick win
Fix the EPSVS source attribution.
The definition says EPSVS is internal and not an industry standard, but Source cites ISO/IEC 25010 as authoritative. Leave Source blank or describe ISO/IEC 25010 as inspiration rather than the source unless a formal mapping is documented.
🤖 Prompt for AI Agents
Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.
In `@STUDIO_GLOSSARY.md` at line 223, Update the EPSVS entry in STUDIO_GLOSSARY.md
so the Source field is blank or explicitly identifies ISO/IEC 25010 as
inspiration, not authoritative source; only retain the citation as a source if a
formal mapping is documented.
| | ------------------------ | ------------------------------------------------------------------------------------------------------------------------------------ | -------------------------------------- | -------- | -------- | | ||
| | **Actor** | Anything that performs a transformation in the Software Construction Lifecycle. | Vision §7.1 | — | proposed | | ||
| | ↳ **Human** | A person acting in Studio — today the majority of actors. | Vision §7.1 | person | proposed | | ||
| | ↳ **AI Agent** | An actor (runtime entity) that performs lifecycle work autonomously; it **runs the Skills** a kit ships (§6). Today built on Claude. | Vision §7.1 | agent | proposed | |
There was a problem hiding this comment.
suggestion: Map to DM: AI Agent ≈ Worker (runtime: llm) (DM §4). "It runs the Skills a kit ships" — kits ship Workers, not Skills (see L192). "Today built on Claude" is an implementation detail; drop from a canonical definition.
There was a problem hiding this comment.
In business terms: AI Agent is a one of runtime for Automation
| | ------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -------------------------------------------------------- | --------------------- | -------- | | ||
| | **Role** | An **access / permission set** (RBAC / ABAC), **defined once** in the Organization catalog and **granted** to a **Member** (or **Team**) at a **scope** — Workspace or a specific Project (so the same person can be Editor in Project A, Viewer in Project B) — *never* baked into the Member. Distinct from **Function** (the 8 org functions — see the Functions & Roles table below). An Actor may hold one or many Roles (possibly different per Workspace / Project). | Vision §7.1–7.2 · NIST RBAC (INCITS 359) / ABAC (SP 800-162) | permission set | proposed | | ||
| | **Access Control** | Who can see / do what — the **enforcement of Roles** as RBAC / ABAC rules. (Org-wide constraints live in Governance ▸ Access-control policy.) | Vision §14.3 · NIST RBAC (INCITS 359) / ABAC (SP 800-162) | RBAC / ABAC, permissions | proposed | | ||
| | **Function** | One of the **8 org functions** Studio serves (Product Management · Product Marketing · UX · R&D · QA · DevOps/DCO · GTM · Customer Success); each groups a set of Roles and owns a purpose across the lifecycle — enumerated in the **Functions & Roles** table below. | Vision §7.2 | function set, role set | proposed | |
There was a problem hiding this comment.
Glossary lists 8 functions; DM Role.metadata.functionalGroup has 7 (product_management, product_marketing, ux, rd, operations, gtm, customer_success) — QA and DevOps/DCO are merged into operations. One of the two must change;
| | Canonical | Definition | Source | Aliases | Status | | ||
| | ----------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------ | ------------------------- | -------- | | ||
| | **Organization** | The company's account — owns the **user directory** and the **billing account**; holds one or more Workspaces. One identity per person lives here (SSO). Auto-created & invisible for a single-workspace company; shown once there are several. | | account, org | proposed | | ||
| | **Workspace** | A billed **isolation + configuration unit** under an Organization: holds Projects, installed Kits, Settings, shared standards (guardrails, templates), Teams. Scoped per company or per product-line / portfolio; an Organization may run several. | Vision §9 | — | proposed | |
There was a problem hiding this comment.
Any user can create Workspace for his needs and invite some people. I don't think that Single workspace is good even for small company, even for one person.
| | ----------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------ | ------------------------- | -------- | | ||
| | **Organization** | The company's account — owns the **user directory** and the **billing account**; holds one or more Workspaces. One identity per person lives here (SSO). Auto-created & invisible for a single-workspace company; shown once there are several. | | account, org | proposed | | ||
| | **Workspace** | A billed **isolation + configuration unit** under an Organization: holds Projects, installed Kits, Settings, shared standards (guardrails, templates), Teams. Scoped per company or per product-line / portfolio; an Organization may run several. | Vision §9 | — | proposed | | ||
| | **Project** | The working scope inside a Workspace — its own **Project Graph**, **Documents**, **Workflows**, **Dashboards**. Navigation is **Organization → Workspace → Project** (Organization hidden when there's one). | Vision §9 | — | proposed | |
There was a problem hiding this comment.
Project can be applied as a Filters, but I don't think that it is a good idea to restrict users to see and work only with one Project on the graph
There was a problem hiding this comment.
Different projects can be also connected and it should be visible
| | Canonical | Definition | Source | Aliases | Status | | ||
| | -------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------- | ------------------ | ------------------- | | ||
| | **Collaboration** | The cross-cutting layer itself (sharing + coordination — reviews · comments · handoffs · activity feed). | Vision §9 | — | proposed | | ||
| | ↳ **Activity Feed** | A chronological stream of changes / events. | | feed | proposed *(target)* | |
|
|
||
| | Canonical | Definition | Source | Aliases | Status | | ||
| | -------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------- | ----------------------------------------------------------- | ------------------ | | ||
| | **Project Graph** | Studio's **mirror / shadow copy** of a Project's SDLC objects, attributes, relationships, states, history and evidence — tracked from source-of-record tools (Jira / Git / CI…), which Studio governs but does **not** own. **One per Project; the system's spine.** *Renamed from "SDLC Graph" (2026-07-10)* to drop the SCLC/SDLC collision. | Vision §13 | SDLC Graph, Shadow SDLC Graph, Delivery Graph, shadow graph | proposed | |
There was a problem hiding this comment.
Why Project Graph? I would say Work Items Graph
| | -------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------- | ----------------------------------------------------------- | ------------------ | | ||
| | **Project Graph** | Studio's **mirror / shadow copy** of a Project's SDLC objects, attributes, relationships, states, history and evidence — tracked from source-of-record tools (Jira / Git / CI…), which Studio governs but does **not** own. **One per Project; the system's spine.** *Renamed from "SDLC Graph" (2026-07-10)* to drop the SCLC/SDLC collision. | Vision §13 | SDLC Graph, Shadow SDLC Graph, Delivery Graph, shadow graph | proposed | | ||
| | **Source of record** | The external tool that **owns the truth** for an object; Studio mirrors it and does not replace it. | Vision §13 | system of record | proposed | | ||
| | **Object** | A node in the graph (Requirement, PRD, Design, ADR, Task, Epic, Bug, **Decision**, Repo, File, Branch, Commit, PR, Test, Build, Release, Deployment, Alert, Incident, Runbook, Postmortem, Person, Team, Role, Approval). | Vision "Shadow SDLC Graph" | Node | proposed | |
There was a problem hiding this comment.
Too technical maybe, my suggestion is - Work Item
| | **Project Graph** | Studio's **mirror / shadow copy** of a Project's SDLC objects, attributes, relationships, states, history and evidence — tracked from source-of-record tools (Jira / Git / CI…), which Studio governs but does **not** own. **One per Project; the system's spine.** *Renamed from "SDLC Graph" (2026-07-10)* to drop the SCLC/SDLC collision. | Vision §13 | SDLC Graph, Shadow SDLC Graph, Delivery Graph, shadow graph | proposed | | ||
| | **Source of record** | The external tool that **owns the truth** for an object; Studio mirrors it and does not replace it. | Vision §13 | system of record | proposed | | ||
| | **Object** | A node in the graph (Requirement, PRD, Design, ADR, Task, Epic, Bug, **Decision**, Repo, File, Branch, Commit, PR, Test, Build, Release, Deployment, Alert, Incident, Runbook, Postmortem, Person, Team, Role, Approval). | Vision "Shadow SDLC Graph" | Node | proposed | | ||
| | **Object type** | A class of graph object; browsable / filterable in the Object Browser. | Vision "Shadow SDLC Graph" | node type | proposed | |
| | **Step** | A single step in a running workflow instance — distinct from a lifecycle **Stage** (§3). | Vision "First Killer Workflow" | workflow step | proposed | | ||
| | **Workflow run (Run)** | One execution of a **Workflow** — the instance that **produces Work Artifacts** (run → produced artifacts + gate status); status & history live in Workflows ▸ Runs and history. Distinct from **Workflow** (the pipeline) and **Step** (one step within a run). | Vision "First Killer Workflow" | run | proposed | | ||
| | **Workflow** | A repeatable pipeline of actions + validators + conditions/loops, with its own model settings and quality gates. | Vision "Killer Workflow(s)" | Flow | proposed (canonical: Workflow; *Flow* used loosely) | | ||
| | **Flow Catalog** | Catalog of predefined, reusable workflows / blueprints a user can pick and orchestrate. | Vision "Studio Flow Library" | Flow Library | proposed | |
There was a problem hiding this comment.
Need to decide one paradigm - Flow vs Workflow
| | **Workflow** | A repeatable pipeline of actions + validators + conditions/loops, with its own model settings and quality gates. | Vision "Killer Workflow(s)" | Flow | proposed (canonical: Workflow; *Flow* used loosely) | | ||
| | **Flow Catalog** | Catalog of predefined, reusable workflows / blueprints a user can pick and orchestrate. | Vision "Studio Flow Library" | Flow Library | proposed | | ||
| | **Blueprint** | A reusable workflow **template** you clone to create a workflow (the pattern, not a run). | Vision "Expansion Roadmap" | — | proposed | | ||
| | **Predefined flow** | A **shipped, ready-to-run** analysis workflow (vs Blueprint = template): gap, traceability, contradiction, bloat, stale-artifact, ownership-gap, duplicate-work, architecture-drift, security-impact, test-gap, release-readiness, incident→postmortem, ops-metrics, AI-cost. | Vision "Studio Flow Library" | smart flow | proposed | |
There was a problem hiding this comment.
What is a diff between Blueprint and Predefined flow?
|
|
||
| | Canonical | Definition | Source | Aliases | Status | | ||
| | --------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | --------------------------------- | ------------------------------------------------------- | -------- | | ||
| | **Kit** | A packaged, reusable body of delivery knowledge for a domain: **reference architecture** + ontology + templates & examples + **sample data** + actions + validators + rules/policies + **Kit Workflows** + **deployment patterns** + Gears. | Vision "SaaS Development Kits" | Domain Kit, SaaS Development Kit | proposed | |
| | Canonical | Definition | Source | Aliases | Status | | ||
| | --------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | --------------------------------- | ------------------------------------------------------- | -------- | | ||
| | **Kit** | A packaged, reusable body of delivery knowledge for a domain: **reference architecture** + ontology + templates & examples + **sample data** + actions + validators + rules/policies + **Kit Workflows** + **deployment patterns** + Gears. | Vision "SaaS Development Kits" | Domain Kit, SaaS Development Kit | proposed | | ||
| | **Kit package** *(IA node)* | The IA node under **Kits** that shows a kit's **anatomy** — its contents are listed under **Kit** (above). (Map node: "Kit (package / anatomy)".) | Vision "SaaS Development Kits" | kit contents, kit anatomy | proposed | |
| | **Sample data** | Seed / demo data a kit ships to **populate the Project Graph** — so a project shows the product working out of the box (PM Kit: sample competitors + a sample PRD; DevOps Kit: sample incidents / runbooks). Part of the **Kit package** (next to Templates & examples); loaded into a Project's graph at setup. | Vision "SaaS Development Kits" | seed data, demo data, examples | proposed | | ||
| | **Kit Workflows** | The recommended flows a kit ships; they populate the Flow Catalog and can be run inside a project. | Vision "SaaS Development Kits" | kit flows, recommended flows | proposed | | ||
| | **Gears** | Reusable building-block modules used to assemble the final application (Identity, Authorization, Events, Serverless, GenAI, Platform); supplied by **Constructor Gears** (§0). *Impl. note:* some delivered as pre-generated / auto-compiled libraries for basic, rarely-changing pieces, to save tokens — this is *how* they're built, not a competing meaning. | Vision "Gears Building Blocks" | building blocks | proposed | | ||
| | **Skill** | The **code** (Python scripts) that implements a kit's domain logic / workflow — what an **AI Agent** (§1) actually runs. Distinct from Gears (reusable app modules); this is where the domain work lives. | | Claude Skill, Python agent | proposed | |
There was a problem hiding this comment.
Skill is not a python script, skill is a prompt for LLM structured following specific format. In the Studio v2 we will not have skills, we will have AI Agents inside of Automations (tech: workers)
|
|
||
| --- | ||
|
|
||
| ## 8. Dashboards, Recommendations, Settings & Notifications |
There was a problem hiding this comment.
I would say it should be totally supported by Insights
What
Adds STUDIO_GLOSSARY.md — a foundation artifact defining canonical Studio
terminology (Canonical · Definition · Aliases / also-called · Status).
Companion to STUDIO_VISION.md, which the glossary declares as its source of truth.
Status
Draft v0.2.x — nothing ratified yet. Every term is
proposedpending the Factorysync; see the "Open naming questions" section at the bottom.
Notes
Summary by CodeRabbit