[{"data":1,"prerenderedAt":-1},["ShallowReactive",2],{"skill:01M7AJRN1MZRR432KCFQZJCSHB":3,"skill-same:01M7AJRN1MZRR432KCFQZJCSHB":49},{"skillNo":4,"name":5,"nameZh":6,"description":7,"descriptionZh":6,"repositoryFullName":8,"ownerLogin":9,"ownerAvatarUrl":10,"ownerAccountNo":11,"ownerDisplayName":12,"repositoryNo":13,"starsCount":14,"licenseSpdxId":15,"licenseFileUrl":6,"sourceHtmlUrl":16,"categories":17,"keywords":18,"publishedAt":19,"linkOnly":20,"markdownContent":21,"markdownBody":22,"frontMatter":23,"refName":25,"commitSha":26,"skillDirectory":27,"forksCount":28,"repositoryHtmlUrl":29,"repositoryHomepageUrl":30,"ownerHtmlUrl":31,"ownerBlogUrl":32,"ownerDescription":33,"updatedAt":34,"install":35,"resources":48},"01M7AJRN1MZRR432KCFQZJCSHB","vibey-architecture",null,"Onion layers for vibey (domain, application, infrastructure, cli, tui), import-linter, where new code belongs, the workspace tenants, and how to file a sub-doctrine. Use before adding a module under src\u002F or writing a standing rule.","the-vibey-project\u002Fvibey","the-vibey-project","https:\u002F\u002Favatars.githubusercontent.com\u002Fu\u002F329298758?v=4","01M7AJHGZ9722CTJ4JNQZVRH0Q","the vibey project","01M7AJHGZVMG2K7TGXQ6XFHVG3",5,"MIT","https:\u002F\u002Fgithub.com\u002Fthe-vibey-project\u002Fvibey\u002Fblob\u002Fdevelop\u002F.claude\u002Fskills\u002Fvibey-architecture\u002FSKILL.md",[],[],"2026-11-15 14:19:17",false,"---\nname: vibey-architecture\ndescription: Onion layers for vibey (domain, application, infrastructure, cli, tui), import-linter, where new code belongs, the workspace tenants, and how to file a sub-doctrine. Use before adding a module under src\u002F or writing a standing rule.\nallowed-tools: Read Grep Glob Bash(lint-imports)\n---\n\n# vibey architecture\n\nDependencies point inward. `import-linter` enforces this in CI via four\ncontracts: onion-layers, domain-independence, application-independence, and\ninterfaces-declare-only.\n\n```\nsrc\u002Fvibey\u002F\n├── domain\u002F            # PURE. stdlib only. No I\u002FO, no async, no third-party.\n├── application\u002F       # Protocol ports + use cases. Imports domain + stdlib.\n├── infrastructure\u002F    # Adapters. ONLY layer that may import asyncpg, httpx, etc.\n├── cli\u002F               # Typer. Calls application via bootstrap.\n├── tui\u002F               # Textual. Calls application via bootstrap.\n└── bootstrap.py       # Composition root — the ONE module that sees every layer.\n```\n\n## Where does new code go?\n\n1. **Touches FS, network, clock, database, or an SDK?** → `infrastructure\u002F`,\n   behind a `Protocol` in `application\u002Finterfaces\u002F\u003Carea>.py` (`azure`, `build`,\n   `design`, `engines`, `gates`, `ledger`, `observability`, `projects`, `queue`,\n   `review`, `system`, `visual`). `application\u002Fports.py` is a compatibility\n   re-export shim of seven names — never add to it. Never `import asyncpg` or\n   vendor SDKs elsewhere.\n2. **Pure decision, zero I\u002FO?** → `domain\u002F`. Examples: `phase.py`,\n   `rotation.py`, `noloss.py`, `circuit.py`, `effort.py`.\n3. **Orchestration (port → domain → port)?** → `application\u002F`.\n4. **Argument parsing \u002F terminal formatting?** → `cli\u002F` or `tui\u002F`.\n5. **Wiring concrete implementations to Protocols?** → `bootstrap.py` ONLY.\n\nWhen in doubt, push logic inward. `lint-imports` names the broken contract\nwhen you violate the onion.\n\n## Shape: classes, behind interfaces\n\nCode lives in **class objects**. A module-level function is the method of last\nresort — a package's `__all__` façade, a `__main__` entry point, a bare function\nsome library contract requires — and where you use one, write the reason at the\ndefinition. \"It is only a few lines\" is not a reason.\n\n**Every class has an interface beside it**, in a mirrored `interfaces\u002F` directory\n(illustrative paths — there is no `services\u002F` package):\n\n```\nsrc\u002Fvibey\u002Fservices\u002Fgithub_service.py\nsrc\u002Fvibey\u002Fservices\u002Finterfaces\u002Fgithub_service_interface.py\n```\n\nThis is the target shape, not the current one. Today's interfaces packages\n(`application\u002Finterfaces\u002F`, `cli\u002Finterfaces\u002F`, and the empty\n`infrastructure\u002Finterfaces\u002F`) are mostly organised by area; `cli\u002Finterfaces\u002Fearly_signals_interface.py`\nis the one module that already follows the `\u003Cmodule>_interface.py` mirror.\n\nThe mapping is mechanical: the directory gains an `interfaces\u002F` child, the module\ngains an `_interface` suffix. Interfaces **declare**; they never consume — an\ninterface module imports the standard library and other interfaces, nothing else\nfrom its own tree. The rule applies to every `interfaces\u002F` package; the\n`interfaces-declare-only` contract in `.importlinter` enforces part of it today, for\n`application\u002Finterfaces` only (it forbids imports of `vibey.infrastructure`,\n`vibey.cli`, `vibey.tui` and `vibey.bootstrap`).\n\nWhy: a class behind an interface is substituted at its seam. The caller takes the\ninterface, the test passes a double, and nothing is patched — so the test depends\non the contract, which is meant to be stable, rather than on the import graph,\nwhich is not. With a 100% branch floor that is not a style preference: a branch\nreachable only by `monkeypatch.setattr` is a branch whose test breaks for reasons\nunrelated to its subject.\n\nThis applies to **new and changed code**. The existing tree (289 module-level\nfunctions, and 278 module-level classes outside an `interfaces\u002F` package, 277 of\nthem with no mirrored `_interface` module — AST walk of `src\u002Fvibey\u002F**\u002F*.py`,\ntop-level definitions only, measured 2026-09-15) converges module by module,\nand the absorbed subtrees under `src\u002Fvibey_runners\u002F` and `src\u002Fvibey_tools\u002F`\nconverge as they are touched — rewriting them on import would destroy the\nproperty their import exists to create. `domain\u002F` gets no exemption: a pure\nfunction becomes a method on a stateless class, and purity is preserved, because\npurity was never about the absence of a class.\n\nSee ADR-0016 and sub-doctrine 9.b (the declared seam).\n\n## Dogfood the family first\n\nIf a capability exists inside this family, use it. Do not reimplement it, and do\nnot reach for a third-party equivalent. The bar is not \"is ours better\" — it is\n\"does ours do this at all\".\n\nBetween `vibey_bootstrap`'s retry and a retry loop, use theirs. Between its\ndead-letter routing and a hand-rolled failure path, use its. Between its\ncorrelation scope and threading a request id by hand, use its. When the choice is\nbetween using a family feature and not using it, **always prefer using it**.\n\nThe shape is the one this codebase already uses: a Protocol in\n`application\u002Finterfaces\u002F`, an adapter in `infrastructure\u002F` that satisfies it with\nthe family package, and a line in `bootstrap.py`. Dogfooding is not a new pattern\nhere — it is the existing one, applied to ourselves.\n\nA new implementation of something the family already ships needs a written reason\nat the call site, and the reason must be a capability gap. If ours is missing\nsomething, the fix is to add it to ours.\n\nMeasured 2026-09-15: `src\u002Fvibey` imports **zero** family packages. See ADR-0017\n(and sub-doctrine 10.e) for the parity backlog.\n\n## The workspace tenants\n\nThis repository is a uv workspace (`[tool.uv.workspace] members =\n[\"src\u002Fvibey_runners\u002F*\", \"src\u002Fvibey_tools\u002F*\"]`, ADR-0021). `vibey` is the root\npackage; the tenants are absorbed packages that ship inside the one `vibey`\ndistribution rather than under their own PyPI names (ADR-0037). Their former\nGitHub repositories (`the-vibey-project\u002Fclaudeloop`, `vibey-gh`, and the rest)\nand their former PyPI projects no longer exist — never link either; link the\ndirectory in this repository instead.\n\n| Directory | Package | Python floor | Own checks |\n|---|---|---|---|\n| `src\u002Fvibey_runners\u002Fclaude` | `claudeloop` | 3.12 | pytest, ruff, mypy, import-linter |\n| `src\u002Fvibey_runners\u002Fcodex` | `codexloop` | 3.12 | pytest, ruff, mypy, import-linter |\n| `src\u002Fvibey_runners\u002Fqwen` | `qwenloop` | 3.12 | pytest, ruff, mypy, import-linter |\n| `src\u002Fvibey_runners\u002Fcommon` | `vibey-runners-common` | 3.12 | ruff, mypy, import-linter (no test directory yet) |\n| `src\u002Fvibey_tools\u002Fgh` | `vibey-gh` | 3.12 | pytest (100% branch), black, isort, mypy, bandit |\n| `src\u002Fvibey_tools\u002Fskills` | `vibey-skills` | 3.12 | manifest\u002Flink validators, unittest |\n| `src\u002Fvibey_tools\u002Fbootstrap` | `vibey-bootstrap` | 3.12 | pytest (100% line), black, isort, mypy, bandit |\n\nRules for working inside a tenant:\n\n- **Its own configuration governs it.** Each tenant's `pyproject.toml` carries its\n  own tool sections and test directory (`test\u002F` for `gh` and `bootstrap`, `tests\u002F`\n  for the rest). Run its checks from its own directory; the root `pytest`\n  (`testpaths = [\"tests\"]`) and the root `mypy`\u002F`bandit`\u002Fcoverage gates never\n  reach it. Root `ruff check .` and `ruff format --check .` do (`include =\n  [\"src\u002F**\u002F*.py\", \"tests\u002F**\u002F*.py\"]`). Absorbed packages keep the gates they\n  arrived with (ADR-0022); see the `vibey-quality-gates` skill for the commands.\n- **Converge as touched.** ADR-0016 and ADR-0017 apply to tenants only as their\n  code is changed. Do not restyle or restructure a tenant on import.\n- **The root layers do not import tenants,** except the dependency-free family\n  packages `domain\u002F` may use (below) and adapters in `infrastructure\u002F`.\n\n## Everything-as-code, and never less of it\n\nIf a thing can be declared in the repository and reconciled from it, that is how\nit is done. Branch protection and the repository profile live in `.vibey-gh.toml`\n(`[rulesets]`, `[repository_profile]`) and are reconciled by `vibey-gh`; pipelines\nare rendered from templates; policy is `.importlinter` and the coverage gates. No\nsettings page, no one-off `gh api`, no runbook step that says \"then set X\".\n\nAnd **everything that can be generic and configurable must be.** A hard-coded\nvalue that could have been a key, a special case that could have been a rule, a\npath that could have been discovered — each takes a decision away from whoever\nadopts this next, silently. Never change anything to a state that is less generic\nor less configurable. A default is fine; a default is configurability with an\nopinion. A constant is not.\n\nWorked example: `find_root` walked to `.git`, which broke the moment a project\nlived inside a repository belonging to something else. The fix was not an\nexplicit root at the two call sites that noticed — it was that a directory\ncarrying its own `.vibey-gh.toml` stops the walk. Same work, aimed at the general\nshape. See ADR-0018.\n\n## Convergence-Driven Development is the delivery loop\n\nEvery change uses Specification-Driven Development (SDD) for intent and\nacceptance criteria, Test-Driven Development (TDD) for executable checks, and\nConvergence-Driven Development (CDD) above them to ground, implement, test,\nreview and repair against the actual tracked repository. At every iteration,\nclassify the trajectory as converging, neutral or diverging against the\nremaining criteria and failing checks. A divergence is allowed only when it is\nsmall, bounded and has a concrete path to reconvergence; large or pathless\ndivergence is abandoned. Never treat activity, a marker or a generated file as\ncompletion evidence. See sub-doctrine 9.c and ADR-0039.\nProject atoms can compose chemical structures, and a suite of suites can be\nalive in the digital realm as a software organism when identity, feedback,\nadaptation, repair and exchange are evidenced; inspect that higher-order\ntrajectory whenever the change participates in it.\n\n## A standing rule goes in the canon\n\nThis project has law, not just decision records: the constitutional cluster in\n`src\u002Fvibey_tools\u002Fgh\u002Fdocs\u002F` — the Constitution, the Twelve Doctrines, the Ten\nCommandments, the Bill of Rights, SD-01 — indexed by `vibey-gh corpus-index` so\ndrift between published law and its index is one hash comparison.\n\nThe Twelve are **sealed**. Anything new files as a **sub-doctrine** under one of\nthem, in the established form, and is ratified by the operator's merge (Article\nII.3). The ratchet applies: a refinement may strengthen, never weaken.\n\nSo if what you are writing binds future decisions, survives a rewrite, and is\nabout conduct rather than mechanism — it is a sub-doctrine, and writing it only as\nan ADR leaves it with no ratification, no ratchet protection and no chunk in the\ncorpus. Write both: the sub-doctrine states the rule, the ADR argues it.\n\n\"PostgreSQL, not SQLite\" is a mechanism and stays an ADR. \"Dogfood the family\" is\na rule and belongs in the canon. See ADR-0020 and sub-doctrine 12.b.\n\n### Filing a sub-doctrine\n\n1. **Pick the parent.** Find the one of the twelve `## N — title` headings in\n   `src\u002Fvibey_tools\u002Fgh\u002Fdocs\u002Fdoctrines.md` the rule stands under. Use the next free\n   letter (existing entries: 2.a–2.b, 4.a, 7.a, 8.a, 9.a–9.b, 10.a–10.e, 12.a–12.c).\n2. **Write it in the established form** — one bold run-in paragraph under the parent\n   heading:\n\n   ```\n   **9.c — short title** *(ratified by the merge that carried this entry)*: the rule,\n   stated as conduct, in present tense.\n   ```\n\n   The ratification note becomes a date only after the fact; do not pre-date it.\n3. **Write the ADR** that argues it and cite the sub-doctrine by number (ADR-0016\n   through ADR-0020 pair with 9.b, 10.e, 12.c, 2.b and 12.b).\n4. **Regenerate and check the corpus index** from the tenant directory:\n\n   ```bash\n   cd src\u002Fvibey_tools\u002Fgh\n   uv run vibey-gh corpus-index          # rewrites corpus-index.json\n   uv run vibey-gh corpus-index --check  # \"corpus intact: N chunk(s)\"\n   ```\n\n   The index lives at `src\u002Fvibey_tools\u002Fgh\u002Fcorpus-index.json` (32 chunks on\n   2026-09-15); there is no root copy. Commit it with the doctrine change.\n5. **Ratify by human merge.** Article II.3: the doctrines' sub-entries are ratified\n   by humans through reviewed pull requests — a machine may draft, a human\n   ratifies. Article IV.2 (the ratchet): a change may clarify, strengthen or\n   extend; it may never weaken.\n6. **Know the blast radius.** Article V.4: a ratified change to the canon yanks\n   every prior release of the code. A sub-doctrine merge is a release-level event.\n\nA standing subdoctrine carried verbatim in agent files (such as SD-01 in\n`CLAUDE.md`) is amended only by the operator, with a version bump — never edited\nin passing.\n\n## The forbidden imports\n\n`domain\u002F` must never import:\n- Any layer: `vibey.application`, `vibey.infrastructure`, `vibey.cli`, `vibey.tui`\n- Third-party: `asyncpg`, `psycopg`, `httpx`, `typer`, `structlog`, `pydantic`, `textual`\n- `vibey_bootstrap` — named rather than categorised: it carries the Azure SDK and\n  OpenTelemetry, so importing it here pulls a third-party graph in transitively\n- I\u002FO, async and wall-clock from stdlib: `tests\u002Fdomain\u002Ftest_domain_purity.py` walks\n  the AST and rejects imports of `asyncio`, `asyncpg`, `subprocess`, `socket` and\n  `pathlib` (plus the third-party names above), calls to `open()`, `os.environ`,\n  `os.getenv`, `datetime.now()`\u002F`today()`, `time.time()`, and any `async def`,\n  `await`, `async with` or `async for`\n\n`domain\u002F` **may** import a family package that is itself dependency-free —\n`vibey_gh`, `vibey_skills`, `vibey_runners.common` all declare `dependencies = []`,\nso they add nothing to the graph that stdlib-only did not already allow. This is the\nADR-0017 caveat to the stdlib-only rule: a first-party package is not third-party.\n\n`application\u002F` must never import:\n- `vibey.infrastructure`, `vibey.cli`, `vibey.tui`\n\n## Verify before committing\n\n```bash\nuv run lint-imports\n```\n\nIf it fails, the error names the contract and the violating import. Fix it by\nmoving the offending code to a layer that can legally import the dependency,\nor by abstracting the dependency behind a Protocol in\n`application\u002Finterfaces\u002F\u003Carea>.py` (`ports.py` is a compatibility re-export shim —\nnever add to it).\n\nThe onion layering has no ADR of its own: its authority is `.importlinter` and\n`docs\u002Fplans\u002Farchitecture-and-roadmap.md`. ADR-0016 governs the class\u002Finterface\nshape; ADR-0021 records the monorepo layout.\n","# vibey architecture\n\nDependencies point inward. `import-linter` enforces this in CI via four\ncontracts: onion-layers, domain-independence, application-independence, and\ninterfaces-declare-only.\n\n```\nsrc\u002Fvibey\u002F\n├── domain\u002F            # PURE. stdlib only. No I\u002FO, no async, no third-party.\n├── application\u002F       # Protocol ports + use cases. Imports domain + stdlib.\n├── infrastructure\u002F    # Adapters. ONLY layer that may import asyncpg, httpx, etc.\n├── cli\u002F               # Typer. Calls application via bootstrap.\n├── tui\u002F               # Textual. Calls application via bootstrap.\n└── bootstrap.py       # Composition root — the ONE module that sees every layer.\n```\n\n## Where does new code go?\n\n1. **Touches FS, network, clock, database, or an SDK?** → `infrastructure\u002F`,\n   behind a `Protocol` in `application\u002Finterfaces\u002F\u003Carea>.py` (`azure`, `build`,\n   `design`, `engines`, `gates`, `ledger`, `observability`, `projects`, `queue`,\n   `review`, `system`, `visual`). `application\u002Fports.py` is a compatibility\n   re-export shim of seven names — never add to it. Never `import asyncpg` or\n   vendor SDKs elsewhere.\n2. **Pure decision, zero I\u002FO?** → `domain\u002F`. Examples: `phase.py`,\n   `rotation.py`, `noloss.py`, `circuit.py`, `effort.py`.\n3. **Orchestration (port → domain → port)?** → `application\u002F`.\n4. **Argument parsing \u002F terminal formatting?** → `cli\u002F` or `tui\u002F`.\n5. **Wiring concrete implementations to Protocols?** → `bootstrap.py` ONLY.\n\nWhen in doubt, push logic inward. `lint-imports` names the broken contract\nwhen you violate the onion.\n\n## Shape: classes, behind interfaces\n\nCode lives in **class objects**. A module-level function is the method of last\nresort — a package's `__all__` façade, a `__main__` entry point, a bare function\nsome library contract requires — and where you use one, write the reason at the\ndefinition. \"It is only a few lines\" is not a reason.\n\n**Every class has an interface beside it**, in a mirrored `interfaces\u002F` directory\n(illustrative paths — there is no `services\u002F` package):\n\n```\nsrc\u002Fvibey\u002Fservices\u002Fgithub_service.py\nsrc\u002Fvibey\u002Fservices\u002Finterfaces\u002Fgithub_service_interface.py\n```\n\nThis is the target shape, not the current one. Today's interfaces packages\n(`application\u002Finterfaces\u002F`, `cli\u002Finterfaces\u002F`, and the empty\n`infrastructure\u002Finterfaces\u002F`) are mostly organised by area; `cli\u002Finterfaces\u002Fearly_signals_interface.py`\nis the one module that already follows the `\u003Cmodule>_interface.py` mirror.\n\nThe mapping is mechanical: the directory gains an `interfaces\u002F` child, the module\ngains an `_interface` suffix. Interfaces **declare**; they never consume — an\ninterface module imports the standard library and other interfaces, nothing else\nfrom its own tree. The rule applies to every `interfaces\u002F` package; the\n`interfaces-declare-only` contract in `.importlinter` enforces part of it today, for\n`application\u002Finterfaces` only (it forbids imports of `vibey.infrastructure`,\n`vibey.cli`, `vibey.tui` and `vibey.bootstrap`).\n\nWhy: a class behind an interface is substituted at its seam. The caller takes the\ninterface, the test passes a double, and nothing is patched — so the test depends\non the contract, which is meant to be stable, rather than on the import graph,\nwhich is not. With a 100% branch floor that is not a style preference: a branch\nreachable only by `monkeypatch.setattr` is a branch whose test breaks for reasons\nunrelated to its subject.\n\nThis applies to **new and changed code**. The existing tree (289 module-level\nfunctions, and 278 module-level classes outside an `interfaces\u002F` package, 277 of\nthem with no mirrored `_interface` module — AST walk of `src\u002Fvibey\u002F**\u002F*.py`,\ntop-level definitions only, measured 2026-09-15) converges module by module,\nand the absorbed subtrees under `src\u002Fvibey_runners\u002F` and `src\u002Fvibey_tools\u002F`\nconverge as they are touched — rewriting them on import would destroy the\nproperty their import exists to create. `domain\u002F` gets no exemption: a pure\nfunction becomes a method on a stateless class, and purity is preserved, because\npurity was never about the absence of a class.\n\nSee ADR-0016 and sub-doctrine 9.b (the declared seam).\n\n## Dogfood the family first\n\nIf a capability exists inside this family, use it. Do not reimplement it, and do\nnot reach for a third-party equivalent. The bar is not \"is ours better\" — it is\n\"does ours do this at all\".\n\nBetween `vibey_bootstrap`'s retry and a retry loop, use theirs. Between its\ndead-letter routing and a hand-rolled failure path, use its. Between its\ncorrelation scope and threading a request id by hand, use its. When the choice is\nbetween using a family feature and not using it, **always prefer using it**.\n\nThe shape is the one this codebase already uses: a Protocol in\n`application\u002Finterfaces\u002F`, an adapter in `infrastructure\u002F` that satisfies it with\nthe family package, and a line in `bootstrap.py`. Dogfooding is not a new pattern\nhere — it is the existing one, applied to ourselves.\n\nA new implementation of something the family already ships needs a written reason\nat the call site, and the reason must be a capability gap. If ours is missing\nsomething, the fix is to add it to ours.\n\nMeasured 2026-09-15: `src\u002Fvibey` imports **zero** family packages. See ADR-0017\n(and sub-doctrine 10.e) for the parity backlog.\n\n## The workspace tenants\n\nThis repository is a uv workspace (`[tool.uv.workspace] members =\n[\"src\u002Fvibey_runners\u002F*\", \"src\u002Fvibey_tools\u002F*\"]`, ADR-0021). `vibey` is the root\npackage; the tenants are absorbed packages that ship inside the one `vibey`\ndistribution rather than under their own PyPI names (ADR-0037). Their former\nGitHub repositories (`the-vibey-project\u002Fclaudeloop`, `vibey-gh`, and the rest)\nand their former PyPI projects no longer exist — never link either; link the\ndirectory in this repository instead.\n\n| Directory | Package | Python floor | Own checks |\n|---|---|---|---|\n| `src\u002Fvibey_runners\u002Fclaude` | `claudeloop` | 3.12 | pytest, ruff, mypy, import-linter |\n| `src\u002Fvibey_runners\u002Fcodex` | `codexloop` | 3.12 | pytest, ruff, mypy, import-linter |\n| `src\u002Fvibey_runners\u002Fqwen` | `qwenloop` | 3.12 | pytest, ruff, mypy, import-linter |\n| `src\u002Fvibey_runners\u002Fcommon` | `vibey-runners-common` | 3.12 | ruff, mypy, import-linter (no test directory yet) |\n| `src\u002Fvibey_tools\u002Fgh` | `vibey-gh` | 3.12 | pytest (100% branch), black, isort, mypy, bandit |\n| `src\u002Fvibey_tools\u002Fskills` | `vibey-skills` | 3.12 | manifest\u002Flink validators, unittest |\n| `src\u002Fvibey_tools\u002Fbootstrap` | `vibey-bootstrap` | 3.12 | pytest (100% line), black, isort, mypy, bandit |\n\nRules for working inside a tenant:\n\n- **Its own configuration governs it.** Each tenant's `pyproject.toml` carries its\n  own tool sections and test directory (`test\u002F` for `gh` and `bootstrap`, `tests\u002F`\n  for the rest). Run its checks from its own directory; the root `pytest`\n  (`testpaths = [\"tests\"]`) and the root `mypy`\u002F`bandit`\u002Fcoverage gates never\n  reach it. Root `ruff check .` and `ruff format --check .` do (`include =\n  [\"src\u002F**\u002F*.py\", \"tests\u002F**\u002F*.py\"]`). Absorbed packages keep the gates they\n  arrived with (ADR-0022); see the `vibey-quality-gates` skill for the commands.\n- **Converge as touched.** ADR-0016 and ADR-0017 apply to tenants only as their\n  code is changed. Do not restyle or restructure a tenant on import.\n- **The root layers do not import tenants,** except the dependency-free family\n  packages `domain\u002F` may use (below) and adapters in `infrastructure\u002F`.\n\n## Everything-as-code, and never less of it\n\nIf a thing can be declared in the repository and reconciled from it, that is how\nit is done. Branch protection and the repository profile live in `.vibey-gh.toml`\n(`[rulesets]`, `[repository_profile]`) and are reconciled by `vibey-gh`; pipelines\nare rendered from templates; policy is `.importlinter` and the coverage gates. No\nsettings page, no one-off `gh api`, no runbook step that says \"then set X\".\n\nAnd **everything that can be generic and configurable must be.** A hard-coded\nvalue that could have been a key, a special case that could have been a rule, a\npath that could have been discovered — each takes a decision away from whoever\nadopts this next, silently. Never change anything to a state that is less generic\nor less configurable. A default is fine; a default is configurability with an\nopinion. A constant is not.\n\nWorked example: `find_root` walked to `.git`, which broke the moment a project\nlived inside a repository belonging to something else. The fix was not an\nexplicit root at the two call sites that noticed — it was that a directory\ncarrying its own `.vibey-gh.toml` stops the walk. Same work, aimed at the general\nshape. See ADR-0018.\n\n## Convergence-Driven Development is the delivery loop\n\nEvery change uses Specification-Driven Development (SDD) for intent and\nacceptance criteria, Test-Driven Development (TDD) for executable checks, and\nConvergence-Driven Development (CDD) above them to ground, implement, test,\nreview and repair against the actual tracked repository. At every iteration,\nclassify the trajectory as converging, neutral or diverging against the\nremaining criteria and failing checks. A divergence is allowed only when it is\nsmall, bounded and has a concrete path to reconvergence; large or pathless\ndivergence is abandoned. Never treat activity, a marker or a generated file as\ncompletion evidence. See sub-doctrine 9.c and ADR-0039.\nProject atoms can compose chemical structures, and a suite of suites can be\nalive in the digital realm as a software organism when identity, feedback,\nadaptation, repair and exchange are evidenced; inspect that higher-order\ntrajectory whenever the change participates in it.\n\n## A standing rule goes in the canon\n\nThis project has law, not just decision records: the constitutional cluster in\n`src\u002Fvibey_tools\u002Fgh\u002Fdocs\u002F` — the Constitution, the Twelve Doctrines, the Ten\nCommandments, the Bill of Rights, SD-01 — indexed by `vibey-gh corpus-index` so\ndrift between published law and its index is one hash comparison.\n\nThe Twelve are **sealed**. Anything new files as a **sub-doctrine** under one of\nthem, in the established form, and is ratified by the operator's merge (Article\nII.3). The ratchet applies: a refinement may strengthen, never weaken.\n\nSo if what you are writing binds future decisions, survives a rewrite, and is\nabout conduct rather than mechanism — it is a sub-doctrine, and writing it only as\nan ADR leaves it with no ratification, no ratchet protection and no chunk in the\ncorpus. Write both: the sub-doctrine states the rule, the ADR argues it.\n\n\"PostgreSQL, not SQLite\" is a mechanism and stays an ADR. \"Dogfood the family\" is\na rule and belongs in the canon. See ADR-0020 and sub-doctrine 12.b.\n\n### Filing a sub-doctrine\n\n1. **Pick the parent.** Find the one of the twelve `## N — title` headings in\n   `src\u002Fvibey_tools\u002Fgh\u002Fdocs\u002Fdoctrines.md` the rule stands under. Use the next free\n   letter (existing entries: 2.a–2.b, 4.a, 7.a, 8.a, 9.a–9.b, 10.a–10.e, 12.a–12.c).\n2. **Write it in the established form** — one bold run-in paragraph under the parent\n   heading:\n\n   ```\n   **9.c — short title** *(ratified by the merge that carried this entry)*: the rule,\n   stated as conduct, in present tense.\n   ```\n\n   The ratification note becomes a date only after the fact; do not pre-date it.\n3. **Write the ADR** that argues it and cite the sub-doctrine by number (ADR-0016\n   through ADR-0020 pair with 9.b, 10.e, 12.c, 2.b and 12.b).\n4. **Regenerate and check the corpus index** from the tenant directory:\n\n   ```bash\n   cd src\u002Fvibey_tools\u002Fgh\n   uv run vibey-gh corpus-index          # rewrites corpus-index.json\n   uv run vibey-gh corpus-index --check  # \"corpus intact: N chunk(s)\"\n   ```\n\n   The index lives at `src\u002Fvibey_tools\u002Fgh\u002Fcorpus-index.json` (32 chunks on\n   2026-09-15); there is no root copy. Commit it with the doctrine change.\n5. **Ratify by human merge.** Article II.3: the doctrines' sub-entries are ratified\n   by humans through reviewed pull requests — a machine may draft, a human\n   ratifies. Article IV.2 (the ratchet): a change may clarify, strengthen or\n   extend; it may never weaken.\n6. **Know the blast radius.** Article V.4: a ratified change to the canon yanks\n   every prior release of the code. A sub-doctrine merge is a release-level event.\n\nA standing subdoctrine carried verbatim in agent files (such as SD-01 in\n`CLAUDE.md`) is amended only by the operator, with a version bump — never edited\nin passing.\n\n## The forbidden imports\n\n`domain\u002F` must never import:\n- Any layer: `vibey.application`, `vibey.infrastructure`, `vibey.cli`, `vibey.tui`\n- Third-party: `asyncpg`, `psycopg`, `httpx`, `typer`, `structlog`, `pydantic`, `textual`\n- `vibey_bootstrap` — named rather than categorised: it carries the Azure SDK and\n  OpenTelemetry, so importing it here pulls a third-party graph in transitively\n- I\u002FO, async and wall-clock from stdlib: `tests\u002Fdomain\u002Ftest_domain_purity.py` walks\n  the AST and rejects imports of `asyncio`, `asyncpg`, `subprocess`, `socket` and\n  `pathlib` (plus the third-party names above), calls to `open()`, `os.environ`,\n  `os.getenv`, `datetime.now()`\u002F`today()`, `time.time()`, and any `async def`,\n  `await`, `async with` or `async for`\n\n`domain\u002F` **may** import a family package that is itself dependency-free —\n`vibey_gh`, `vibey_skills`, `vibey_runners.common` all declare `dependencies = []`,\nso they add nothing to the graph that stdlib-only did not already allow. This is the\nADR-0017 caveat to the stdlib-only rule: a first-party package is not third-party.\n\n`application\u002F` must never import:\n- `vibey.infrastructure`, `vibey.cli`, `vibey.tui`\n\n## Verify before committing\n\n```bash\nuv run lint-imports\n```\n\nIf it fails, the error names the contract and the violating import. Fix it by\nmoving the offending code to a layer that can legally import the dependency,\nor by abstracting the dependency behind a Protocol in\n`application\u002Finterfaces\u002F\u003Carea>.py` (`ports.py` is a compatibility re-export shim —\nnever add to it).\n\nThe onion layering has no ADR of its own: its authority is `.importlinter` and\n`docs\u002Fplans\u002Farchitecture-and-roadmap.md`. ADR-0016 governs the class\u002Finterface\nshape; ADR-0021 records the monorepo layout.\n",{"name":5,"description":7,"allowed-tools":24},"Read Grep Glob Bash(lint-imports)","develop","ae32736a1aabddabca5d2c96d665aa0ebc7d8700",".claude\u002Fskills\u002Fvibey-architecture",3,"https:\u002F\u002Fgithub.com\u002Fthe-vibey-project\u002Fvibey","https:\u002F\u002Fthe-vibey-project.github.io\u002Fvibey\u002F","https:\u002F\u002Fgithub.com\u002Fthe-vibey-project","https:\u002F\u002Fvibewithadam.matthewsteinberger.com","freedom for software engineers","2026-11-15 05:47:42",{"source":8,"skillName":5,"commands":36,"prompt":46,"zipAvailable":47},[37,40,43],{"tool":38,"command":39},"npx","npx skills add the-vibey-project\u002Fvibey --skill vibey-architecture",{"tool":41,"command":42},"bunx","bunx skills add the-vibey-project\u002Fvibey --skill vibey-architecture",{"tool":44,"command":45},"pnpm","pnpm dlx skills add the-vibey-project\u002Fvibey --skill vibey-architecture","安装技能，技能地址：https:\u002F\u002Fgithub.com\u002Fthe-vibey-project\u002Fvibey\u002Fblob\u002Fdevelop\u002F.claude\u002Fskills\u002Fvibey-architecture\u002FSKILL.md",true,[],[50,57,64,71,78,85],{"skillNo":51,"name":52,"nameZh":6,"description":53,"descriptionZh":6,"repositoryFullName":8,"ownerLogin":9,"ownerAvatarUrl":10,"ownerAccountNo":11,"ownerDisplayName":12,"repositoryNo":13,"starsCount":14,"licenseSpdxId":15,"licenseFileUrl":6,"sourceHtmlUrl":54,"categories":55,"keywords":56,"publishedAt":19},"01M7AT1FQJAE1FQYAMDTF490Y4","white-paper-writing","Use when writing white papers, technical reports, policy documents, thought leadership pieces, or any long-form authoritative document. Triggers on requests to write, structure, outline, or review white papers, technical reports, position papers, policy briefs, or evidence-driven arguments. Also use for B2B content marketing strategy, technical documentation requiring authority, academic-style reports, or any document that must educate while persuading. Use when someone asks \"how should I structure this\" for a long-form document.","https:\u002F\u002Fgithub.com\u002Fthe-vibey-project\u002Fvibey\u002Fblob\u002Fdevelop\u002Fsrc\u002Fvibey_tools\u002Fskills\u002Fplugins\u002Fwriting-craft\u002Fskills\u002Fwhite-paper-writing\u002FSKILL.md",[],[],{"skillNo":58,"name":59,"nameZh":6,"description":60,"descriptionZh":6,"repositoryFullName":8,"ownerLogin":9,"ownerAvatarUrl":10,"ownerAccountNo":11,"ownerDisplayName":12,"repositoryNo":13,"starsCount":14,"licenseSpdxId":15,"licenseFileUrl":6,"sourceHtmlUrl":61,"categories":62,"keywords":63,"publishedAt":19},"01M7AT16BJRJJKK2MASXRZS76G","prose-technical-mechanics","Use when editing or writing prose at a technical\u002Fmechanical level: choosing between Anglo-Saxon and Latinate diction, placing information in topic vs stress positions, writing periodic vs cumulative sentences, handling sentence rhythm, punctuation as logic, transitions, paragraph structure, or phonesthetics. Use when someone wants to understand WHY prose works or doesn't, not just surface-level style advice. Triggers on word choice, sentence structure, emphasis, rhythm, diction, or any deep writing mechanics question.","https:\u002F\u002Fgithub.com\u002Fthe-vibey-project\u002Fvibey\u002Fblob\u002Fdevelop\u002Fsrc\u002Fvibey_tools\u002Fskills\u002Fplugins\u002Fwriting-craft\u002Fskills\u002Fprose-technical-mechanics\u002FSKILL.md",[],[],{"skillNo":65,"name":66,"nameZh":6,"description":67,"descriptionZh":6,"repositoryFullName":8,"ownerLogin":9,"ownerAvatarUrl":10,"ownerAccountNo":11,"ownerDisplayName":12,"repositoryNo":13,"starsCount":14,"licenseSpdxId":15,"licenseFileUrl":6,"sourceHtmlUrl":68,"categories":69,"keywords":70,"publishedAt":19},"01M7AT0W9HT0ZZ9Y287NW99MR3","prose-mechanics","Use when writing, editing, or analyzing prose style; when trying to avoid generic AI-sounding writing; when applying specific prose styles such as journalistic, academic, narrative, KJV biblical, Hemingway plain, Latinate\u002FJamesian, Orwellian, Augustan, Victorian, Early Modern (Bacon, Browne, Milton), or free indirect discourse; or when coaching someone on writing voice and mechanics. Triggers on any request to improve, analyze, or write in a specific prose style, to fix \"AI-sounding\" writing, to make prose more vivid or concrete, to vary sentence rhythm, or to understand how a particular writer achieves their effects.","https:\u002F\u002Fgithub.com\u002Fthe-vibey-project\u002Fvibey\u002Fblob\u002Fdevelop\u002Fsrc\u002Fvibey_tools\u002Fskills\u002Fplugins\u002Fwriting-craft\u002Fskills\u002Fprose-mechanics\u002FSKILL.md",[],[],{"skillNo":72,"name":73,"nameZh":6,"description":74,"descriptionZh":6,"repositoryFullName":8,"ownerLogin":9,"ownerAvatarUrl":10,"ownerAccountNo":11,"ownerDisplayName":12,"repositoryNo":13,"starsCount":14,"licenseSpdxId":15,"licenseFileUrl":6,"sourceHtmlUrl":75,"categories":76,"keywords":77,"publishedAt":19},"01M7AT0KR635JX66X2X6F3E2CP","narrative-structure","Use when structuring stories, pitches, presentations, white papers, or any persuasive narrative; analyzing the hero's journey in fiction or non-fiction; applying StoryBrand for business communication; designing narrative arcs for thought leadership; or understanding Vogler, Snyder, Propp, or Campbell frameworks. Triggers on any narrative structure, storytelling, pitch structure, StoryBrand, hero's journey, three-act structure, Freytag, Save the Cat, narrative arc, or \"how should I structure this story\u002Fpitch\u002Fpresentation\" request.","https:\u002F\u002Fgithub.com\u002Fthe-vibey-project\u002Fvibey\u002Fblob\u002Fdevelop\u002Fsrc\u002Fvibey_tools\u002Fskills\u002Fplugins\u002Fwriting-craft\u002Fskills\u002Fnarrative-structure\u002FSKILL.md",[],[],{"skillNo":79,"name":80,"nameZh":6,"description":81,"descriptionZh":6,"repositoryFullName":8,"ownerLogin":9,"ownerAvatarUrl":10,"ownerAccountNo":11,"ownerDisplayName":12,"repositoryNo":13,"starsCount":14,"licenseSpdxId":15,"licenseFileUrl":6,"sourceHtmlUrl":82,"categories":83,"keywords":84,"publishedAt":19},"01M7AT0AKGW09NKKZDYBT8VRDE","legal-brief-writing","Use when writing legal briefs, motions, or any court filing; when analyzing judicial cognition and persuasion; when applying elite brief-writing techniques from Roberts, Clement, Kagan, Garner; or when structuring legal arguments for maximum persuasion. Also use for autistic\u002Fneurodivergent advocates who need to understand how their natural communication style maps to elite legal advocacy. Triggers on any legal writing, brief drafting, motion preparation, or legal argument structuring request.","https:\u002F\u002Fgithub.com\u002Fthe-vibey-project\u002Fvibey\u002Fblob\u002Fdevelop\u002Fsrc\u002Fvibey_tools\u002Fskills\u002Fplugins\u002Fwriting-craft\u002Fskills\u002Flegal-brief-writing\u002FSKILL.md",[],[],{"skillNo":86,"name":87,"nameZh":6,"description":88,"descriptionZh":6,"repositoryFullName":8,"ownerLogin":9,"ownerAvatarUrl":10,"ownerAccountNo":11,"ownerDisplayName":12,"repositoryNo":13,"starsCount":14,"licenseSpdxId":15,"licenseFileUrl":6,"sourceHtmlUrl":89,"categories":90,"keywords":91,"publishedAt":19},"01M7AT00VWPS4Q8B5VEMXX9NQT","journal-publishability-criteria","Use whenever a research paper, article or preprint is being written, revised, reviewed or published, and specifically before every publication of docs\u002Fpaper.md. Covers what legitimate journals actually gate on, in order of gating — the editor's desk screen (scope, novelty, package problems), what reviewers judge (methodological soundness, claims the evidence can carry, statistical and qualitative reporting), EQUATOR reporting guidelines, the ICMJE authorship criteria, COPE's view of text recycling, the near-universal generative-AI policy (no AI author, disclosure, author responsibility), TOP 2025 transparency standards, how to verify a journal is legitimate, submitting without an institution, and a pre-submission checklist. Triggers on requests to evaluate, review, prepare or submit a paper, to judge publishability, to write a declarations or data-availability section, to disclose AI use, or to check a journal.","https:\u002F\u002Fgithub.com\u002Fthe-vibey-project\u002Fvibey\u002Fblob\u002Fdevelop\u002Fsrc\u002Fvibey_tools\u002Fskills\u002Fplugins\u002Fwriting-craft\u002Fskills\u002Fjournal-publishability-criteria\u002FSKILL.md",[],[]]