@twentylabs/ai-os-registry 1.0.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Twenty Labs
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,14 @@
+# @twentylabs/ai-os-registry
+
+The content of the Twenty Labs AI OS: roles, skills, policies, knowledge slots and profiles (`software`,
+`marketing`). Data only — nothing in this package is executed. Use it through
+[`@twentylabs/ai-os`](https://www.npmjs.com/package/@twentylabs/ai-os); projects pin an exact version in `ai-os.yaml`.
+
+Versioning follows content semver: tightening a policy, changing a gate, or removing/renaming an id is a major
+release; new roles, skills or profiles are minor; wording is a patch. Renames ship in `migrations.json`, and
+`ai-os upgrade` applies them.
+
+External skills (e.g. the marketing pack from coreyhaines31/marketingskills, MIT) are referenced by commit and content
+hash, not copied.
+
+Source: https://github.com/twenty-labs/ai-os

package/knowledge-slots/audience-icp.yaml

@@ -0,0 +1,26 @@
+apiVersion: ai-os.twentylabs.dev/v1
+kind: KnowledgeSlot
+metadata:
+  id: audience-icp
+  title: Audience and ICP
+  description: "Who the marketing targets — segments, jobs, objections, where they gather."
+spec:
+  purpose: "Who marketing is aimed at — the ideal customer and secondary segments, the job they hire the product for, their objections, and where they can be reached."
+  template: |
+    ## Ideal customer
+    The specific person (not a demographic blur): situation, goal, what they have tried, and why now.
+
+    ## Secondary segments
+    Each with what differs and whether it is pursued on purpose.
+
+    ## Jobs and outcomes
+    The job the product is hired for, in the customer's own words, and the outcome they would pay for.
+
+    ## Objections
+    The top reasons a good-fit prospect does not convert, each with the answer and its evidence.
+
+    ## Where they are
+    Channels, communities, searches, influencers and partners where this audience can be reached.
+
+    ## Who we do not target
+    Segments deliberately excluded, and why.

package/knowledge-slots/brand-voice.yaml

@@ -0,0 +1,24 @@
+apiVersion: ai-os.twentylabs.dev/v1
+kind: KnowledgeSlot
+metadata:
+  id: brand-voice
+  title: Brand voice
+  description: "How the brand sounds — voice, vocabulary, claims allowed and forbidden, per channel."
+spec:
+  purpose: "How the brand sounds and what it may claim — voice, vocabulary, approved and forbidden claims, and per-channel adjustments — so every piece of copy reads as one brand and promises only what the product does."
+  template: |
+    ## Voice
+    Three to five traits, each with a "this, not that" pair of example sentences.
+
+    ## Vocabulary
+    Words the brand uses, words it avoids, how it refers to the product, its users and its features. Spelling and capitalization of names.
+
+    ## Claims
+    - **Allowed** — claims the product can back today, with the evidence.
+    - **Forbidden** — claims it must never make (capabilities it lacks, regulated claims, unverifiable superlatives), each with the reason.
+
+    ## Per channel
+    How tone, length and format change for store listings, ads, short video, email and push, social posts, and partner messages.
+
+    ## Languages
+    Which languages the brand publishes in, which is primary, and who reviews each.

package/knowledge-slots/budget.yaml

@@ -0,0 +1,18 @@
+apiVersion: ai-os.twentylabs.dev/v1
+kind: KnowledgeSlot
+metadata:
+  id: budget
+  title: Budget
+  description: "Marketing budget by channel and period, with the reason for every reallocation."
+spec:
+  purpose: "The marketing budget — total and per channel, per period — with the reason and date for every reallocation, and the rules for increasing spend."
+  template: |
+    ## Current allocation
+    | Period | Channel | Budget | Currency | Reason |
+    | --- | --- | --- | --- | --- |
+
+    ## Rules
+    Who approves changes, the maximum change without approval (normally none), and the conditions that must hold before total spend increases (for example: the paid conversion step is measured and not leaking).
+
+    ## History
+    Dated reallocations, newest first: before, after, reason, and the readout that justified it.

package/knowledge-slots/channel-registry.yaml

@@ -0,0 +1,20 @@
+apiVersion: ai-os.twentylabs.dev/v1
+kind: KnowledgeSlot
+metadata:
+  id: channel-registry
+  title: Channel registry
+  description: "Every marketing channel in use — accounts, owners, status, folders and cadence."
+spec:
+  purpose: "Every marketing channel this team runs or has tried — platform, account, owner, status, where its decisions are logged, and its review cadence."
+  template: |
+    | Channel | Platform / account | Owner | Status (planned / live / paused / stopped) | Repository folder | Review cadence |
+    | --- | --- | --- | --- | --- | --- |
+
+    ## Access
+    How each platform is reached (console, API, export), who has access, and where credentials live — never the values. Agents never sign in to a platform on anyone's behalf.
+
+    ## Naming conventions
+    Campaign, ad set, creative and link naming, so exports can be joined.
+
+    ## Stopped channels
+    Channels tried and stopped, with the date, the result and the reason — so they are not restarted blind.

package/knowledge-slots/data-access.yaml

@@ -0,0 +1,26 @@
+apiVersion: ai-os.twentylabs.dev/v1
+kind: KnowledgeSlot
+metadata:
+  id: data-access
+  title: Data access
+  description: "How to query this project's analytics and production data, read-only, and the known counting traps."
+spec:
+  purpose: "How to get numbers in this project, read-only — the analytics store, the production database, the join between them, and the traps that have already produced wrong numbers. No production number is quoted before this is filled."
+  template: |
+    Commands are written with credentials sourced from the environment — never secrets in arguments, output, or this file.
+
+    ## Analytics store
+    - The tool and project, where read-capable credentials live, and the query shape that works.
+    - How internal and test users are filtered, exactly, and the failure mode of getting the filter backwards.
+    - Events emitted from more than one side (client and server): how to tell them apart, and the query that regenerates the current list.
+
+    ## Production database
+    - Read paths, best first (stored procedures, a read replica, a console), and what each cannot express.
+    - The tables that hold money, users, sessions and content.
+    - Ready-made queries and dashboards that already answer common questions — reuse keeps numbers consistent with what the team sees.
+
+    ## Joining the two
+    The key between analytics identity and database identity, and its gaps (pre-signup activity, unidentified events).
+
+    ## Known counting traps
+    Mistakes that have already produced a wrong headline number here, each with the guard query.

package/knowledge-slots/design-surface.yaml

@@ -0,0 +1,37 @@
+apiVersion: ai-os.twentylabs.dev/v1
+kind: KnowledgeSlot
+metadata:
+  id: design-surface
+  title: Design surface
+  description: "The design system as it actually exists — tokens, brand canon, typography, components, capture tooling."
+spec:
+  purpose: "The product's design system as it actually exists: token sources of truth, brand canon, typography traps, component inventory, capture tooling, and decided norms."
+  template: |
+    Stale by design: entries describe the surface as of their date.
+
+    ## Brand canon
+    The accent color, the neutral family, the canvas, and the brand's named identity if it has one.
+
+    ## Token sources of truth
+    The canonical token file first, then each surface's mirror (app theme, web CSS variables), in rank order. Record the call-site rule if there is one (for example "no raw hex outside token files").
+
+    ## Scales
+    Spacing base unit and named steps; radius scale, including deliberate off-scale values.
+
+    ## Typography
+    Families as registered (exact strings), glyph gaps, test-environment font gotchas.
+
+    ## Component inventory
+    Where shared components live — point at directories rather than copying lists that go stale.
+
+    ## Capture tooling
+    How to screenshot and screen-record each platform, deep-link tricks, what does not work.
+
+    ## Store and marketing surfaces
+    Where store metadata and marketing assets live, and which surfaces deploy on merge.
+
+    ## Decided norms
+    Design decisions made on purpose that a review must not re-litigate.
+
+    ## Worked examples
+    Finished specs and reviews (path and one line each), so the next engagement starts from precedent.

package/knowledge-slots/domain-playbook.yaml

@@ -0,0 +1,23 @@
+apiVersion: ai-os.twentylabs.dev/v1
+kind: KnowledgeSlot
+metadata:
+  id: domain-playbook
+  title: Domain playbook
+  description: "How this product's category and market behave — value chain, what converts, unit economics, the local market, benchmarks."
+spec:
+  purpose: "The domain reasoning generic playbooks cannot know: how this product's category and market behave — the value chain, what converts, unit economics, the local market, and benchmarks worth holding."
+  template: |
+    ## The value chain in this category
+    The ordered steps from first contact to long-term paying customer, and the step products in this category most often lose.
+
+    ## What converts here
+    Which limits and gates drive upgrades in this category versus merely punish, and where the strong paywall or upgrade moments sit.
+
+    ## Unit economics
+    What serving one active user costs, and the constraint that puts on free tiers.
+
+    ## The local market
+    Willingness to pay, payment methods, pricing anchors, cultural traps — whatever "local" means for this product's users.
+
+    ## Benchmarks worth holding
+    Category reference numbers (activation, retention, trial-to-paid) with sources and dates — context, never targets.

package/knowledge-slots/flow-map.yaml

@@ -0,0 +1,22 @@
+apiVersion: ai-os.twentylabs.dev/v1
+kind: KnowledgeSlot
+metadata:
+  id: flow-map
+  title: Flow map
+  description: "Where each major product flow lives — code, state, contracts and gotchas."
+spec:
+  purpose: "Where each major product flow lives — the code that implements it, the state that persists it, and the contract it sits inside. A map, not a source of truth: the code and tables win."
+  template: |
+    One row per flow the product actually has (sign-up, the core usage loop, purchase and entitlement, notifications, version gates, and the product's own feature flows):
+
+    | Flow | Repositories / directories | Key code and docs | State (tables, stores) | Contract / gotchas |
+    | --- | --- | --- | --- | --- |
+
+    ## Deliberately removed behaviour
+    Features taken out on purpose, with the reason — so an as-is analysis does not resurrect them as gaps.
+
+    ## Display-only versus enforced
+    Rules whose user-interface half and server half have drifted, and which side is authoritative.
+
+    ## Cross-repository contracts
+    Where the contracts between repositories are documented (payloads, enums, feature flags shared across sides), or "single repository, none".

package/knowledge-slots/market-landscape.yaml

@@ -0,0 +1,20 @@
+apiVersion: ai-os.twentylabs.dev/v1
+kind: KnowledgeSlot
+metadata:
+  id: market-landscape
+  title: Market landscape
+  description: "The competitor roster and what is known about each, dated."
+spec:
+  purpose: "The competitor roster — who matters to this product and why. Every fact carries a date and an evidence tier; a dated fact expires to unverified after about 90 days."
+  template: |
+    ## Direct competitors
+    Same job, same user. Per product: why it matters, what to watch.
+
+    ## Category leaders
+    Different method, same time or money budget. Which of their mechanics depend on their scale and which travel to a product this size.
+
+    ## Adjacent products and substitutes
+    Including the free or general-purpose substitute a motivated user already has — it sets the bar for "why pay".
+
+    ## Standing questions
+    Comparisons the team keeps asking (free-tier limits, pricing, recurring review complaints — a competitor's recurring complaint is this product's opportunity list).

package/knowledge-slots/measurement-plan.yaml

@@ -0,0 +1,28 @@
+apiVersion: ai-os.twentylabs.dev/v1
+kind: KnowledgeSlot
+metadata:
+  id: measurement-plan
+  title: Measurement plan
+  description: "How marketing results are measured — attribution, funnel events, sources of truth, readout rules."
+spec:
+  purpose: "How marketing results are measured — the attribution source of truth, the funnel and its events, which numbers come from where, and the rules for reading a result."
+  template: |
+    ## Source of truth per question
+    | Question | Source of truth | Do not use |
+    | --- | --- | --- |
+    | Who paid, how much | | |
+    | Which channel an install or signup came from | | |
+    | Spend and cost per result | | |
+    | Which channel is worth more | | |
+
+    ## Funnel
+    The ordered steps from impression to retained paying customer, with the event or table that observes each step, and the steps that are not yet measurable.
+
+    ## Attribution
+    The arbiter between platforms (each platform credits itself), tracking links and parameters, and known gaps (privacy frameworks, untracked organic).
+
+    ## Readout rules
+    Default windows, minimum sample before a result is read, how holdouts are built, and how long to wait after a change.
+
+    ## Missing measurement
+    Links in the funnel that cannot be measured yet, each with the issue that would fix it.

package/knowledge-slots/metrics-catalog.yaml

@@ -0,0 +1,28 @@
+apiVersion: ai-os.twentylabs.dev/v1
+kind: KnowledgeSlot
+metadata:
+  id: metrics-catalog
+  title: Metrics catalog
+  description: "Canonical metric definitions and each metric's source of truth."
+spec:
+  purpose: "Canonical definitions so the same question asked twice returns the same number — per metric: definition, source of truth, and how it lies."
+  template: |
+    One row per metric: **definition · source of truth · how it lies**. Committed definitions (a dashboard tile, a stored query, an admin page) outrank hand-derived ones. Name proxies as proxies.
+
+    ## Engagement
+    Active users as defined here (daily, weekly, monthly), sessions, and the unit of value the product delivers.
+
+    ## Activation
+    The funnel to first real value, and the true activation event.
+
+    ## Retention
+    Cohort definitions and day-bucketing choices (by install date, not calendar date).
+
+    ## Money
+    The revenue source of truth (almost never client events), how paid, trial and promotional are separated, and how refunds and sandbox purchases are excluded.
+
+    ## Product-specific surfaces
+    The two or three feature areas whose metrics are asked about most often.
+
+    ## Segmentation axes
+    The standard cuts (platform, plan, acquisition source, lifecycle stage) and where each field's truth lives.

package/knowledge-slots/offer-catalog.yaml

@@ -0,0 +1,23 @@
+apiVersion: ai-os.twentylabs.dev/v1
+kind: KnowledgeSlot
+metadata:
+  id: offer-catalog
+  title: Offer catalog
+  description: "What can be offered — plans, prices, trials, discounts, codes, gifts — and their live sources."
+spec:
+  purpose: "What marketing may offer — plans, prices, trials, discount codes, gifts, referral rewards — where each is configured live, and the rules for using them."
+  template: |
+    Quote prices and limits from their live source, not from this file; this file records where the live source is.
+
+    ## Plans and prices
+    | Plan | Price per market | Billing period | Trial | Live source (store, billing tool, table) |
+    | --- | --- | --- | --- | --- |
+
+    ## Promotions
+    Discount codes, introductory and win-back offers, gifts and referral rewards: what exists, where each is configured, who can create one, and how redemptions are measured.
+
+    ## Rules
+    Who may receive what (never offer a discount to someone in a trial, never send paid users an upsell they cannot use), stacking rules, and the cost of each giveaway against its paid equivalent.
+
+    ## Product capabilities that may be promised
+    The features that exist in the current release, and where to check before a claim is made.

package/knowledge-slots/prior-findings.yaml

@@ -0,0 +1,21 @@
+apiVersion: ai-os.twentylabs.dev/v1
+kind: KnowledgeSlot
+metadata:
+  id: prior-findings
+  title: Prior findings
+  description: "What has been measured, tried, reverted or deliberately decided — dated."
+spec:
+  purpose: "What has already been measured, tried, reverted or deliberately decided, so no one rediscovers it, contradicts it unknowingly, or re-proposes what was rejected. Every entry is dated; whoever proves an entry wrong fixes it in the same engagement."
+  template: |
+    One entry per finding:
+
+    ```
+    ## <short title>  (<YYYY-MM-DD>)
+    What was measured or decided, the number or decision, the source, and what would invalidate it.
+    If something was removed or disabled on purpose, say so and link the reason.
+    ```
+
+    ## Standing lists
+    - Events that have never fired.
+    - Names that appear in docs but do not exist.
+    - Numbers commonly quoted from memory that drift (prices, plan limits).

package/knowledge-slots/product-strategy.yaml

@@ -0,0 +1,25 @@
+apiVersion: ai-os.twentylabs.dev/v1
+kind: KnowledgeSlot
+metadata:
+  id: product-strategy
+  title: Product strategy
+  description: "North star, ideal customer, moat, hard constraints and standing risks."
+spec:
+  purpose: "The strategy every product verdict applies — north star, ideal customer, moat, hard constraints and standing risks, as stated by the owner. Until it is filled, no build verdict can be a GO."
+  template: |
+    Recorded from the owner, not invented. Where the owner has not decided something, write "undecided".
+
+    ## North star
+    The one outcome the product optimizes, and what it deliberately does not optimize.
+
+    ## Ideal customer
+    The specific user (not a demographic), the problem they have, and who the product accepts losing.
+
+    ## Moat
+    The bet competitors cannot easily copy, and the observation that would falsify it.
+
+    ## Hard constraints
+    Budget, team, platforms, cost-of-service realities — the walls every verdict respects.
+
+    ## Standing risks
+    Risks weighed in every verdict (not automatic vetoes), each with the sign that it is materializing.

package/knowledge-slots/store-review.yaml

@@ -0,0 +1,37 @@
+apiVersion: ai-os.twentylabs.dev/v1
+kind: KnowledgeSlot
+metadata:
+  id: store-review
+  title: Store review surface
+  description: "What app store review meets: app records, config paths, reviewer access, monetization and deletion seams, rejection history."
+spec:
+  purpose: "What app store review will meet when it opens this product — app records, where platform config lives, reviewer access, monetization and account-deletion seams, SDK inventory, over-the-air update policy, and the rejection history."
+  template: |
+    Stale by design. If the project ships no store app, write "not applicable" and stop.
+
+    ## App records
+    Bundle or package identifier per environment, store app names, primary category, age rating, which builds go to review.
+
+    ## Where platform config lives
+    The real paths for this stack: Info.plist, entitlements, privacy manifest, Android manifest, permission strings, and where generated config comes from.
+
+    ## Reviewer access
+    The demo or reviewer account and how it is kept alive, or the demo mode; where previous review notes are kept. Credentials are named by location, never pasted.
+
+    ## Monetization seams
+    Product identifiers, which component validates purchases and receives store notifications, where restore lives on the client.
+
+    ## Account lifecycle seams
+    The in-app deletion entry point and the backend handler behind it, what deletion removes and retains, and sign-in token revocation where applicable.
+
+    ## SDK inventory
+    Third-party SDKs that collect data or need privacy declarations, and where the store privacy answers are recorded.
+
+    ## Over-the-air update policy
+    This project's line between what may ship as an over-the-air update and what needs a store build.
+
+    ## Rejection history
+    Dated: build, guideline cited, the store's wording, the fix, and the build that passed.
+
+    ## Decided positions
+    Review stances taken on purpose, with the reasoning or the thread that settled them.

package/knowledge-slots/test-surface.yaml

@@ -0,0 +1,29 @@
+apiVersion: ai-os.twentylabs.dev/v1
+kind: KnowledgeSlot
+metadata:
+  id: test-surface
+  title: Test surface
+  description: "Test suites, environments, test accounts and known gaps."
+spec:
+  purpose: "What test infrastructure exists, how to run it, which environments are safe to write to, and where the known holes are."
+  template: |
+    Stale by design: entries describe the surface as of their date; update an entry when an engagement finds it has moved.
+
+    ## Suites
+    | Area / package | Run command | What it covers | Runs in CI on PR |
+    | --- | --- | --- | --- |
+
+    ## Environments and test accounts
+    Which environments are safe to write to (development, staging) and which are read-only (production, always). Test accounts per tier, with where their credentials live — never the values.
+
+    ## Suite landmines
+    Pre-existing failures that are not regressions (named, so a red run can be read), flaky tests, mock-only areas, tooling traps such as a filtered run that executes zero tests and still exits 0.
+
+    ## Simulator and device divergence
+    What an emulator, simulator or headless browser cannot genuinely test here (sensors, native dialogs, purchases, push), so the human/agent split has a factual basis.
+
+    ## Evidence tools
+    The error tracker and logs used for bug reproduction, and version-specific traps.
+
+    ## Known gaps and their triggers
+    Automation the project lacks, each with the condition under which adopting it should be proposed.

package/knowledge-slots/tracker-surface.yaml

@@ -0,0 +1,32 @@
+apiVersion: ai-os.twentylabs.dev/v1
+kind: KnowledgeSlot
+metadata:
+  id: tracker-surface
+  title: Tracker surface
+  description: "Where work items live, how to reach them, and the conventions that make the tracker readable."
+spec:
+  purpose: "Where this project's work items live, how to reach the tracker, and the conventions — fields, labels, definition of done, cadence — without which a wrong board cannot be told from an unfamiliar one."
+  template: |
+    ## Access
+    The tracker (issue tracker, project board) and the account commands run as. For GitHub: the expected login and the per-command token prefix (`GH_TOKEN=$(gh auth token --user <login>)`), and the scopes the token needs. Never record a token value.
+
+    ## Boards — or the absence of one
+    Whether a project board exists at all. Many projects run on issues, milestones and labels alone; record that as a configuration. With a board: which one is authoritative, and the field and option identifiers that writes need.
+
+    | Field | Field ID | Option | Option ID |
+    | --- | --- | --- | --- |
+
+    ## Repositories with their own issues
+    | Repository | Issues used | On the board | Notes |
+    | --- | --- | --- | --- |
+
+    ## Conventions
+    - **Field meanings** — what each status, priority and size value means here.
+    - **Labels** — the vocabulary, and which labels automation depends on.
+    - **Definition of done** — merged or released, and who closes.
+    - **Stale threshold** — days without activity before an in-progress item counts as stalled.
+    - **Cadence** — cycle length, review rhythm, milestone naming.
+    - **Scale** — roughly how many open and closed items exist, so reads are scoped.
+
+    ## Known traps
+    Dated: items nobody will close, a second tracker some work lives in, work that routinely happens with no issue.

package/migrations.json

@@ -0,0 +1,7 @@
+{
+  "renames": [],
+  "aliases": [
+    { "kind": "Skill", "alias": "app-store-reviewer", "to": "app-store-compliance" },
+    { "kind": "Role", "alias": "contract-reviewer", "to": "code-reviewer" }
+  ]
+}

package/package.json

@@ -0,0 +1,33 @@
+{
+  "name": "@twentylabs/ai-os-registry",
+  "version": "1.0.0",
+  "description": "Twenty Labs AI OS registry: roles, skills, policies, knowledge slots and profiles. Data only.",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/twenty-labs/ai-os.git",
+    "directory": "packages/registry"
+  },
+  "homepage": "https://github.com/twenty-labs/ai-os#readme",
+  "files": [
+    "taxonomy.yaml",
+    "profiles",
+    "roles",
+    "skills",
+    "policies",
+    "knowledge-slots",
+    "migrations.json",
+    "README.md",
+    "LICENSE"
+  ],
+  "aiOs": {
+    "contentFormat": 1,
+    "cli": ">=0.1.0 <1.0.0"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "scripts": {
+    "validate": "node ../cli/dist/bin.mjs registry validate ."
+  }
+}

package/policies/decision-log.yaml

@@ -0,0 +1,16 @@
+apiVersion: ai-os.twentylabs.dev/v1
+kind: Policy
+metadata:
+  id: decision-log
+  title: Decision log for external platforms
+  description: Every change made on an external platform gets a dated changelog line in the repository with its reason and readout date.
+spec:
+  enforcement: default
+  appliesTo:
+    profiles: [marketing]
+  instruction: |
+    The platform keeps the numbers; this repository keeps the decisions. Every change on an external platform — ad accounts, store listings, CRM, email or push tools, analytics flags — gets a changelog line in this repository, newest first, in the folder of the channel it belongs to:
+
+    `YYYY-MM-DD · platform · object · before → after · reason · readout date`
+
+    The reason is mandatory, and so is the readout date: the day the effect will be read and judged. Log deliberate non-changes too ("left X alone because …") when someone would otherwise undo them. If the repository disagrees with the live platform, fix the repository to match the platform and record why they drifted.

package/policies/english-identifiers.yaml

@@ -0,0 +1,10 @@
+apiVersion: ai-os.twentylabs.dev/v1
+kind: Policy
+metadata:
+  id: english-identifiers
+  title: English identifiers
+  description: Identifiers, file names, branch names, commit titles and PR titles are written in English.
+spec:
+  enforcement: default
+  instruction: |
+    Write identifiers (code symbols, config keys, event and metric names), file and folder names, branch names, commit titles and pull-request titles in English, whatever language the project's prose uses. Bodies of commits, PRs and issues follow the project's locale.

package/policies/github-account.yaml

@@ -0,0 +1,19 @@
+apiVersion: ai-os.twentylabs.dev/v1
+kind: Policy
+metadata:
+  id: github-account
+  title: GitHub account for this repository
+  description: Names the GitHub account this repository's gh and git-remote operations run as, selected per command.
+spec:
+  enforcement: optional
+  params:
+    account:
+      description: the GitHub login that owns this repository's remote
+  instruction: |
+    This repository's GitHub operations run as `{{account}}`. Prefix every `gh` command, and every git command that talks to the remote (`git push`, `git fetch`, `git pull`, `git ls-remote`), with the token for that account:
+
+    ```sh
+    GH_TOKEN=$(gh auth token --user {{account}}) gh pr create ...
+    ```
+
+    Git picks the token up only when `gh` is its credential helper (`gh auth setup-git`); otherwise git uses its own credentials. A bare `gh` runs as whichever account happens to be active on this machine and does not say so. If `gh auth token --user {{account}}` fails, stop and tell the owner; do not log in or switch accounts.

package/policies/mcp-env-only.yaml

@@ -0,0 +1,12 @@
+apiVersion: ai-os.twentylabs.dev/v1
+kind: Policy
+metadata:
+  id: mcp-env-only
+  title: Secrets in MCP config come from the environment
+  description: MCP and tool-server configs reference secrets only through environment variables, never as literal values.
+spec:
+  enforcement: locked
+  instruction: |
+    MCP and tool-server configuration (`.mcp.json`, `.codex/config.toml`, `.cursor/mcp.json`, `.vscode/mcp.json`) references every secret through an environment variable — `${VAR}` or the runtime's env-var field — and never contains a literal token, key or password. The variable is supplied by the developer's environment (for example a git-ignored `.envrc`), never committed. When a server needs a new secret, add the variable reference and tell the owner which variable to set; do not paste the value anywhere in the repository, and never print it.
+  gate:
+    enforcement: ci

package/policies/no-gh-auth-switch.yaml

@@ -0,0 +1,23 @@
+apiVersion: ai-os.twentylabs.dev/v1
+kind: Policy
+metadata:
+  id: no-gh-auth-switch
+  title: Never switch the GitHub account
+  description: Never switch the machine-wide active GitHub account; select the account per command instead.
+spec:
+  enforcement: locked
+  instruction: |
+    Never run `gh auth switch`. The active GitHub account is machine-global state: switching it silently changes the account every other session on this machine runs as. Select the account per command instead:
+
+    ```sh
+    GH_TOKEN=$(gh auth token --user <account>) gh <command>
+    ```
+
+    Do not run `gh auth login`, `gh auth logout` or `gh auth refresh` either, even when `gh` suggests it. Report a missing login or scope to the owner and stop. Never print a token value.
+  permissions:
+    - tool: shell
+      command: [gh, auth, switch]
+      decision: deny
+      reason: switching the active account rewrites machine-global state and breaks sessions in other repositories
+  gate:
+    enforcement: permission

package/policies/no-product-code-edits.yaml

@@ -0,0 +1,12 @@
+apiVersion: ai-os.twentylabs.dev/v1
+kind: Policy
+metadata:
+  id: no-product-code-edits
+  title: No product code edits
+  description: Marketing work never edits product code; a needed product change becomes an issue in the code repository.
+spec:
+  enforcement: default
+  appliesTo:
+    profiles: [marketing]
+  instruction: |
+    Never edit, commit to, or open pull requests against product code — the app, backend or website repositories — even for a one-line fix. When marketing work shows that the product must change (a missing event, a broken deep link, a paywall bug, copy that ships in the app), open an issue in the code repository instead. The issue carries the evidence that led to it (the numbers, the screenshot, the file and line you read) and how the fix will be measured. Reading product code to understand behaviour is fine.