Skip to content
OpenAgentSkill
Browsing is open · Catalog captured 2026-11-21 · Automatic updates and account services are paused.
Design & UI

night-market-architecture-contract

States load-bearing decisions, invariants, and weak points. Use when judging a design change. Do not use for gating; use night-market-change-control.

athola · AI review on file

Installation

Read the source and dependencies before running a command. Copying does not install or execute anything.

npx skills add athola/claude-night-market --skill night-market-architecture-contract

About this skill


name: night-market-architecture-contract description: States load-bearing decisions, invariants, and weak points. Use when judging a design change. Do not use for gating; use night-market-change-control.

Night Market Architecture Contract

This skill records the design decisions that hold claude-night-market together, the invariants that enforcement code keeps true, and the weak points that are known and accepted. Read it before proposing a change that crosses a plugin boundary, touches a hook, adds a skill, or bumps a version. Every claim cites in-repo evidence: an ADR (Architecture Decision Record, in docs/adr/), a commit hash, or a checked-in enforcement file. Verify a citation before relying on it:

git log --oneline -1 <hash>
rg -n "Status" docs/adr/<file>.md

Load-bearing decisions

1. Plugins are self-contained deployables

Each of the 23 plugins under plugins/ must install and run alone. There is no shared registry and no root-level shared library that plugins import at runtime (ADR-0001, Accepted). Plugins detect each other at runtime via filesystem checks and must degrade gracefully when a sibling is absent.

Cross-plugin DRY is an anti-pattern here, and that is settled by experiment, not taste. Commit 054e2679 consolidated 1164 lines of duplicated tasks_manager.py from attune, sanctum, and spec-kit into a shared root script. It broke plugin self-containment and was reverted in 29961cd2. The durable fix, d89a55c7, made the copies per-plugin and intentionally different. docs/dependency-audit.md records the per-plugin copies as the approved state. Do not re-propose the consolidation.

Practical test before you extract shared code: if a user installs only one plugin from the marketplace, does your change still work? If not, duplicate the code into each plugin instead.

2. Hooks run under host Python from a cache directory

Claude Code copies an installed plugin into a cache directory and runs its hooks under the host system Python, which can be as old as 3.9. The repo itself is Python 3.12 (root pyproject.toml, requires-python >= 3.12). Only hook scripts and their transitive import chains carry the 3.9 constraint. Five contract rules follow, each purchased with an outage:

RuleWhy (evidence)
Hook code and every transitive import must be Python 3.9 compatibledatetime.UTC (a 3.11+ alias) broke the whole hook import chain repeatedly. ruff kept auto-reverting the fix until UP017 was globally ignored (pyproject.toml line 165) and an AST scan test held the line (plugins/leyline/tests/test_python39_compat.py)
Read the hook payload as JSON on stdin, never from CLAUDE_TOOL_* env varsClaude Code does not set those env vars, so env-reading hooks were silent no-ops for months (full record: night-market-failure-archaeology SB9). Canonical reader: read_hook_payload() in plugins/abstract/hooks/shared/hook_io.py
No relative paths in hooksThe cache directory is not the repo checkout. conserve's session-start hook broke on a relative path and now inlines its JSON utilities (CHANGELOG)
Hook entrypoints must import safely under a bare interpreterAn eager import yaml in gauntlet made every git commit emit ModuleNotFoundError. Guarded in 45dd77ef (#518), anthropic deferred in 9bfc0a7a
Subprocess timeouts must sit below the budget registered in hooks.jsonherald's LLM call once outlived its registered Stop-hook budget, so the harness killed the hook with no verdict at all (full record: night-market-failure-archaeology SB7). Guard test: plugins/herald/tests/unit/test_double_shot_latte.py

CI enforcement: .github/workflows/python39-compat.yml runs two gates with uneven coverage. Gate 1 (ruff UP007, flags 3.10+ union syntax) covers 12 plugins' hooks/ dirs. Gate 2 (hook test suites inside a real Python 3.9 venv) covers only 7 plugins: abstract, conserve, egregore, imbue, leyline, memory-palace, sanctum. herald ships a Stop hook yet appears in neither gate.

3. One ecosystem version, fanned out to every manifest

.claude-plugin/marketplace.json is the version source of truth (1.9.15 as of 2026-07-02). Each plugin carries three manifests that must stay in sync with it and with each other:

  • .claude-plugin/plugin.json (name, version, component arrays)
  • .claude-plugin/metadata.json (version plus dependency hints)
  • openpackage.yml (cross-framework manifest)

Plus pyproject.toml and any __init__.py carrying __version__. Never hand-edit versions across files. Use the bumper, which finds and rewrites all of them:

uv run python plugins/sanctum/scripts/update_versions.py <version>

One trap: metadata.json dependencies (for example imbue declaring "abstract": ">=2.0.0") is a separate semver namespace for capability compatibility. It does not track the marketplace version and a 2.0.0 there does not mean marketplace 2.0.0 exists.

4. Skill discovery budget is finite and overflow is silent

Claude Code loads every installed skill's description into context at 2% of the context window, with a 16,000-character fallback (ADR-0004, Accepted, updated 2026-05-21). Descriptions that exceed the budget make skills invisible with no error anywhere. That is why:

  • Each description is capped at 160 characters (docs/skill-description-guide.md), enforced by the validate-description-budget pre-commit hook backed by plugins/abstract/scripts/validate_budget.py.
  • The ecosystem-wide validator ceiling is 90,000 characters (DEFAULT_BUDGET in plugins/abstract/scripts/validate_budget.py, overridable via SLASH_COMMAND_TOOL_CHAR_BUDGET). ADR-0004 and docs/skill-description-guide.md still cite a stale 60,000 figure; the script is the enforcer. Flag the ADR for an update through change control.

When adding a skill, spend the 160 characters on trigger phrases, not on restating the name.

5. Collective memory and trus

Read the complete source ↗