@ahmed-g-gad/apothem 0.1.1

package/src/apothem/schemas/command.schema.json

@@ -0,0 +1,68 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://apothem.ahmedgad.com/schemas/command.schema.json",
+  "title": "Command",
+  "description": "Frontmatter schema for slash-command definitions under src/apothem/commands/. Reconciled to the live command corpus: every shipped command carries name, version, updated, description, argument-hint, disable-model-invocation, portability, and allowed-tools.",
+  "type": "object",
+  "required": [
+    "allowed-tools",
+    "argument-hint",
+    "description",
+    "disable-model-invocation",
+    "name",
+    "portability",
+    "updated",
+    "version"
+  ],
+  "additionalProperties": false,
+  "properties": {
+    "name": {
+      "type": "string",
+      "description": "Human-readable kebab-case name matching the slash-command surface (the filename without .md), declared without a leading slash.",
+      "pattern": "^[a-z0-9]+(-[a-z0-9]+)*$"
+    },
+    "description": {
+      "type": "string",
+      "description": "Capability-led statement of the command's purpose and invocation triggers."
+    },
+    "version": {
+      "type": "string",
+      "description": "SemVer version of the command definition.",
+      "pattern": "^\\d+\\.\\d+\\.\\d+$"
+    },
+    "updated": {
+      "type": "string",
+      "description": "ISO 8601 date of the command's last revision.",
+      "format": "date",
+      "pattern": "^\\d{4}-\\d{2}-\\d{2}$"
+    },
+    "argument-hint": {
+      "type": "string",
+      "description": "Usage hint shown to the operator describing the command's accepted arguments and flags."
+    },
+    "disable-model-invocation": {
+      "type": "boolean",
+      "description": "When true, the command is reached only by explicit /<name> invocation, never auto-selected by the model from its description."
+    },
+    "portability": {
+      "type": "string",
+      "description": "Portability classification across harness adapters (e.g. universal, claude-code-only)."
+    },
+    "allowed-tools": {
+      "type": "string",
+      "description": "Comma-separated list of tools the command may invoke, or \"*\" for the full surface."
+    }
+  },
+  "examples": [
+    {
+      "name": "eval",
+      "description": "Model-agnostic language-model evaluation campaign. Defines a dataset and scorer, runs a candidate model over it, scores every output, and emits a regression-aware report.",
+      "version": "0.1.0",
+      "updated": "2026-06-16",
+      "argument-hint": "[--dataset PATH] [--scorer NAME]",
+      "disable-model-invocation": true,
+      "portability": "universal",
+      "allowed-tools": "*"
+    }
+  ]
+}

package/src/apothem/schemas/compatibility-matrix.yaml

@@ -0,0 +1,432 @@
+# SPDX-License-Identifier: MIT
+
+# Cross-harness compatibility matrix
+# Declares per-rule, per-agent, per-hook, per-output-style, per-skill, and
+# per-schema compatibility across the 15 Apothem harness adapters.
+# A reference artifact exposed via schemas.compatibility_matrix_path(); install-
+# time asset resolution itself flows through lib/propagation-manifest.yaml and
+# cohort-manifest.yaml, not this matrix.
+#
+# Schema version: 1.0.0
+# Maintained by: Apothem — update whenever a harness adds/drops a capability.
+
+schema_version: "1.0.0"
+
+# ---------------------------------------------------------------------------
+# Harness inventory
+# ---------------------------------------------------------------------------
+harnesses:
+  - name: claude-code
+    display: Claude Code
+    config_format: json
+    supports_hooks: true
+    supports_agents: true
+    supports_skills: true
+    supports_custom_rules: true
+    supports_output_styles: true
+    supports_statuslines: true
+    platform: [linux, macos, windows]
+    notes: "Primary harness; full feature support via ~/.claude/ ecosystem."
+
+  - name: cursor
+    display: Cursor
+    config_format: mdc
+    supports_hooks: false
+    supports_agents: false
+    supports_skills: false
+    supports_custom_rules: true
+    supports_output_styles: false
+    supports_statuslines: false
+    platform: [linux, macos, windows]
+    notes: >-
+      Project rules via <project>/.cursor/rules/apothem-rules.mdc. Cursor has
+      no documented file-based user-global rules surface; the legacy
+      .cursorrules path is intentionally excluded.
+
+  - name: gemini-cli
+    display: Gemini CLI
+    config_format: markdown
+    supports_hooks: false
+    supports_agents: true
+    supports_skills: true
+    supports_custom_rules: true
+    supports_output_styles: false
+    supports_statuslines: false
+    platform: [linux, macos, windows]
+    notes: >-
+      Project context via <project>/GEMINI.md plus native
+      <project>/.gemini/{commands,skills,agents}/ and Apothem support material
+      under <project>/.gemini/apothem/.
+
+  - name: github-copilot
+    display: GitHub Copilot
+    config_format: markdown
+    supports_hooks: false
+    supports_agents: false
+    supports_skills: false
+    supports_custom_rules: true
+    supports_output_styles: false
+    supports_statuslines: false
+    platform: [linux, macos, windows]
+    notes: >-
+      Project instructions via <project>/.github/copilot-instructions.md.
+      GitHub Copilot user-level settings live in IDE state, not an adapter-owned
+      user-global file.
+
+  - name: codex
+    display: Codex
+    config_format: markdown
+    supports_hooks: true
+    supports_agents: true
+    supports_skills: true
+    supports_custom_rules: true
+    supports_output_styles: false
+    supports_statuslines: false
+    platform: [linux, macos, windows]
+    notes: >-
+      Native ~/.codex/AGENTS.md, ~/.codex/hooks.json, ~/.codex/hooks/,
+      ~/.codex/agents/*.toml, shared ~/.agents/skills/, and Apothem
+      support material under ~/.config/apothem/.
+
+  - name: windsurf
+    display: Windsurf
+    config_format: markdown
+    supports_hooks: false
+    supports_agents: false
+    supports_skills: false
+    supports_custom_rules: true
+    supports_output_styles: false
+    supports_statuslines: false
+    platform: [linux, macos, windows]
+    notes: >-
+      Project rules via <project>/.devin/rules/apothem-rules.md (the preferred
+      surface after the Devin Desktop rebrand; .windsurf/rules/ is the
+      backward-compat fallback). Workflows and machine-local memories are
+      operator-owned; legacy .windsurfrules is intentionally excluded.
+
+  - name: opencode
+    display: OpenCode
+    config_format: json
+    supports_hooks: false
+    supports_agents: true
+    supports_skills: true
+    supports_custom_rules: true
+    supports_output_styles: false
+    supports_statuslines: false
+    platform: [linux, macos, windows]
+    notes: "Config plus native ~/.config/opencode/{commands,skills,agents}/."
+
+  - name: antigravity
+    display: Antigravity
+    config_format: markdown
+    supports_hooks: false
+    supports_agents: true
+    supports_skills: true
+    supports_custom_rules: true
+    supports_output_styles: false
+    supports_statuslines: false
+    platform: [linux, macos, windows]
+    notes: >-
+      User instructions via ~/.gemini/GEMINI.md plus the Apothem Antigravity
+      CLI plugin under ~/.gemini/antigravity-cli/plugins/apothem/. The shared
+      GEMINI.md anchor with gemini-cli is intentional; prior
+      ~/.gemini/antigravity/ and ~/.antigravity/profile.yaml targets are
+      retired.
+
+  - name: open-claw
+    display: Open-Claw
+    config_format: json
+    supports_hooks: false
+    supports_agents: true
+    supports_skills: true
+    supports_custom_rules: true
+    supports_output_styles: false
+    supports_statuslines: false
+    platform: [linux, macos, windows]
+    notes: >-
+      Native config via ~/.openclaw/openclaw.json. agents.defaults.skills is a
+      name allowlist (not a dir loader), so Apothem authors no skills key; support
+      skills land under ~/.openclaw/apothem/.
+      Prior target ~/.open-claw/config.yaml used the wrong directory name and
+      extension.
+
+  - name: hermes
+    display: Hermes
+    config_format: yaml
+    supports_hooks: false
+    supports_agents: true
+    supports_skills: true
+    supports_custom_rules: true
+    supports_output_styles: false
+    supports_statuslines: false
+    platform: [linux, macos, windows]
+    notes: >-
+      Native config via ~/.hermes/config.yaml (profile MCP under auxiliary.mcp).
+      skills.config is a vendor registry-package list Apothem does not author;
+      support skills land under ~/.hermes/apothem/.
+      Prior targets ~/.hermes/cli-config.yaml and ~/.hermes/profile.yaml used
+      retired filenames.
+
+  - name: qwen-code
+    display: Qwen Code
+    config_format: json
+    supports_hooks: true
+    supports_agents: true
+    supports_skills: true
+    supports_custom_rules: true
+    supports_output_styles: false
+    supports_statuslines: false
+    platform: [linux, macos, windows]
+    notes: >-
+      Settings plus QWEN.md, native ~/.qwen/{commands,skills,agents}/, and
+      native hook wiring through ~/.qwen/settings.json. Apothem support
+      material remains under ~/.qwen/apothem/.
+
+  - name: kimi-code
+    display: Kimi Code
+    config_format: markdown
+    supports_hooks: false
+    supports_agents: true
+    supports_skills: true
+    supports_custom_rules: true
+    supports_output_styles: false
+    supports_statuslines: false
+    platform: [linux, macos, windows]
+    notes: >-
+      Project-root AGENTS.md managed block plus an Apothem support tree under
+      <project>/.kimi-code/apothem/ carrying rules, commands, skills, agents,
+      and templates. The <project>/.kimi-code/mcp.json MCP surface is
+      operator-owned.
+
+  - name: codebuddy
+    display: CodeBuddy
+    config_format: markdown
+    supports_hooks: false
+    supports_agents: false
+    supports_skills: false
+    supports_custom_rules: true
+    supports_output_styles: false
+    supports_statuslines: false
+    platform: [linux, macos, windows]
+    notes: >-
+      Project rules via <project>/.codebuddy/rules/apothem-rules.md, a
+      dedicated apothem file. CodeBuddy's CODEBUDDY.md memory file and
+      .codebuddy/settings.json (permissions/MCP) are operator-owned.
+
+  - name: kiro
+    display: Kiro
+    config_format: markdown
+    supports_hooks: false
+    supports_agents: false
+    supports_skills: false
+    supports_custom_rules: true
+    supports_output_styles: false
+    supports_statuslines: false
+    platform: [linux, macos, windows]
+    notes: >-
+      Project steering via <project>/.kiro/steering/apothem-rules.md
+      (inclusion: always). Kiro foundation files (product.md, tech.md,
+      structure.md) and specs are operator-owned.
+
+  - name: trae
+    display: Trae
+    config_format: markdown
+    supports_hooks: false
+    supports_agents: false
+    supports_skills: false
+    supports_custom_rules: true
+    supports_output_styles: false
+    supports_statuslines: false
+    platform: [linux, macos, windows]
+    notes: >-
+      Project rules via <project>/.trae/rules/apothem-rules.md, alongside the
+      operator-owned project_rules.md and user_rules.md anchors. The
+      .trae/mcp.json and .trae/skills/ surfaces are operator-owned.
+
+  - name: zed
+    display: Zed
+    config_format: markdown
+    supports_hooks: false
+    supports_agents: false
+    supports_skills: false
+    supports_custom_rules: true
+    supports_output_styles: false
+    supports_statuslines: false
+    platform: [linux, macos, windows]
+    notes: >-
+      Project agent-instructions via the flat <project>/.rules file (no rules
+      directory). Global ~/.config/zed/AGENTS.md and .zed/settings.json MCP
+      context_servers are operator-owned.
+
+  - name: glm
+    display: GLM (Z.ai)
+    config_format: toml
+    supports_hooks: false
+    supports_agents: false
+    supports_skills: false
+    supports_custom_rules: false
+    supports_output_styles: false
+    supports_statuslines: false
+    platform: [linux, macos, windows]
+    notes: >-
+      GLM (Z.ai) is a model backend, not a coding-agent tool. The adapter
+      writes a project-scope Apothem-owned provider file at
+      <project>/.apothem/providers/glm.toml recording the Anthropic-compatible
+      (https://api.z.ai/api/anthropic) and OpenAI-compatible
+      (https://api.z.ai/api/coding/paas/v4) backend base URLs, an auth-token
+      placeholder, and operator-configurable model-mapping placeholders. A
+      model backend exposes no coding-agent cohort, so every capability is
+      unsupported.
+
+# ---------------------------------------------------------------------------
+# Asset-class compatibility
+# ---------------------------------------------------------------------------
+# For each shared-profile asset class, declares which harnesses can consume it
+# and how it is adapted (materialisation_strategy).
+
+asset_classes:
+  rules:
+    description: "Behavioral rules (.md) from src/apothem/rules/."
+    compatible_harnesses:
+      - claude-code        # full: rules injected into ~/.claude/ tree
+      - cursor             # partial: distilled into project .cursor/rules/
+      - gemini-cli         # partial: distilled into ~/.gemini/GEMINI.md
+      - github-copilot     # partial: distilled into copilot-instructions.md
+      - codex              # partial: distilled into ~/.codex/AGENTS.md
+      - windsurf           # partial: distilled into project .devin/rules/ (preferred; .windsurf/rules/ fallback)
+      - opencode           # partial: support cohort referenced by opencode.json
+      - antigravity        # partial: distilled into GEMINI.md plus plugin rules
+      - open-claw          # partial: support cohort referenced by installed skills
+      - hermes             # partial: support cohort referenced by installed skills
+      - qwen-code          # partial: support cohort referenced by QWEN.md
+    materialisation_strategy:
+      claude-code: "copy to ~/.claude/rules/"
+      default: "distil or reference from the harness-native instruction anchor"
+
+  agents:
+    description: "Agent definitions (flat *.md) from src/apothem/agents/."
+    compatible_harnesses:
+      - claude-code
+      - antigravity
+      - codex
+      - gemini-cli
+      - hermes
+      - open-claw
+      - opencode
+      - qwen-code
+    materialisation_strategy:
+      claude-code: "copy to ~/.claude/agents/"
+      antigravity: "convert to ~/.gemini/antigravity-cli/plugins/apothem/agents/*.md"
+      codex: "convert to ~/.codex/agents/*.toml"
+      gemini-cli: "convert to <project>/.gemini/agents/*.md"
+      hermes: "support cohort under ~/.hermes/apothem/agents/"
+      open-claw: "support cohort under ~/.openclaw/apothem/agents/"
+      opencode: "convert to ~/.config/opencode/agents/*.md"
+      qwen-code: "convert to ~/.qwen/agents/*.md"
+      default: "support cohort under apothem/agents/"
+
+  hooks:
+    description: "Hook scripts from src/apothem/hooks/."
+    compatible_harnesses:
+      - claude-code
+      - codex
+      - antigravity
+      - gemini-cli
+      - hermes
+      - open-claw
+      - opencode
+      - qwen-code
+    materialisation_strategy:
+      claude-code: "register in settings.json; support material under ~/.claude/apothem/hooks/"
+      codex: "copy to ~/.codex/hooks/ + register in ~/.codex/hooks.json"
+      antigravity: "support cohort under ~/.gemini/antigravity-cli/plugins/apothem/apothem/hooks/; no active hook wiring until schema adapter exists"
+      gemini-cli: "support cohort under <project>/.gemini/apothem/hooks/"
+      hermes: "support cohort under ~/.hermes/apothem/hooks/"
+      open-claw: "support cohort under ~/.openclaw/apothem/hooks/"
+      opencode: "support cohort under ~/.config/opencode/apothem/hooks/"
+      qwen-code: "register in settings.json; support material under ~/.qwen/apothem/hooks/"
+      default: "support cohort under apothem/hooks/"
+
+  skills:
+    description: "Skill definitions from src/apothem/skills/."
+    compatible_harnesses:
+      - claude-code
+      - antigravity
+      - codex
+      - gemini-cli
+      - hermes
+      - open-claw
+      - opencode
+      - qwen-code
+    materialisation_strategy:
+      claude-code: "copy to ~/.claude/skills/"
+      antigravity: "copy to ~/.gemini/antigravity-cli/plugins/apothem/skills/"
+      codex: "copy to ~/.agents/skills/"
+      gemini-cli: "copy to <project>/.gemini/skills/"
+      hermes: "copy to ~/.hermes/apothem/skills/ (support subtree; skills.config is a vendor registry-package list Apothem does not author)"
+      open-claw: "copy to ~/.openclaw/apothem/skills/ (support subtree; agents.defaults.skills is a name allowlist Apothem does not author)"
+      opencode: "copy to ~/.config/opencode/skills/"
+      qwen-code: "copy to ~/.qwen/skills/"
+      default: "support cohort under apothem/skills/"
+
+  commands:
+    description: "Custom slash-commands from src/apothem/commands/."
+    compatible_harnesses:
+      - claude-code
+      - antigravity
+      - codex
+      - gemini-cli
+      - hermes
+      - open-claw
+      - opencode
+      - qwen-code
+    materialisation_strategy:
+      claude-code: "wrap as ~/.claude/skills/<command>/SKILL.md"
+      antigravity: "wrap as ~/.gemini/antigravity-cli/plugins/apothem/skills/<command>/SKILL.md"
+      codex: "wrap as ~/.agents/skills/<command>/SKILL.md"
+      gemini-cli: "convert to <project>/.gemini/commands/*.toml"
+      hermes: "wrap as ~/.hermes/apothem/skills/<command>/SKILL.md"
+      open-claw: "wrap as ~/.openclaw/apothem/skills/<command>/SKILL.md"
+      opencode: "convert to ~/.config/opencode/commands/*.md"
+      qwen-code: "convert to ~/.qwen/commands/*.md"
+      default: "wrap as skills under the harness support tree"
+
+  output_styles:
+    description: "Output style definitions from src/apothem/output-styles/."
+    compatible_harnesses:
+      - claude-code
+    materialisation_strategy:
+      claude-code: "copy to ~/.claude/output-styles/"
+      default: "not supported"
+
+  statuslines:
+    description: "Statusline configs from src/apothem/statuslines/."
+    compatible_harnesses:
+      - claude-code
+    materialisation_strategy:
+      claude-code: "copy to ~/.claude/statuslines/"
+      default: "not supported"
+
+  templates:
+    description: "Prompt templates from src/apothem/templates/."
+    compatible_harnesses:
+      - claude-code
+      - antigravity
+      - codex
+      - gemini-cli
+      - hermes
+      - open-claw
+      - opencode
+      - qwen-code
+    materialisation_strategy:
+      claude-code: "support cohort under ~/.claude/apothem/templates/"
+      antigravity: "support cohort under ~/.gemini/antigravity-cli/plugins/apothem/apothem/templates/"
+      default: "support cohort under apothem/templates/"
+
+  schemas:
+    description: "Schema files from src/apothem/schemas/."
+    compatible_harnesses:
+      - claude-code
+    materialisation_strategy:
+      claude-code: "copy to ~/.claude/schemas/"
+      default: "not applicable"

package/src/apothem/schemas/context-fragment.schema.json

@@ -0,0 +1,64 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://apothem.ahmedgad.com/schemas/context-fragment.schema.json",
+  "title": "Apothem Context Fragment",
+  "description": "One named, injectable prompt or context fragment in the contexts surface. A fragment is dynamic injectable text the operator can enable or disable, with activation metadata describing when it applies. The shape is neutral: it carries no tool-specific or vendor-specific identifier, so the same fragment applies across any installation target.",
+  "type": "object",
+  "additionalProperties": false,
+  "required": ["id", "name", "body", "enabled"],
+  "properties": {
+    "id": {
+      "type": "string",
+      "minLength": 1,
+      "description": "Stable fragment identifier, unique within a contexts store."
+    },
+    "name": {
+      "type": "string",
+      "minLength": 1,
+      "description": "Human-readable fragment name."
+    },
+    "body": {
+      "type": "string",
+      "description": "The injectable prompt or context text."
+    },
+    "enabled": {
+      "type": "boolean",
+      "description": "Enable/disable switch. When false, the fragment is retained but never injected."
+    },
+    "activation": {
+      "type": "object",
+      "additionalProperties": false,
+      "description": "Metadata describing when the fragment activates.",
+      "properties": {
+        "scope": {
+          "type": "string",
+          "enum": ["global", "session", "task"],
+          "description": "Activation breadth. global: every interaction. session: the active session. task: a single task scope."
+        },
+        "triggers": {
+          "type": "array",
+          "items": {
+            "type": "string",
+            "minLength": 1
+          },
+          "description": "Phrases or signals that activate the fragment.",
+          "default": []
+        }
+      }
+    },
+    "tags": {
+      "type": "array",
+      "items": {
+        "type": "string",
+        "minLength": 1
+      },
+      "description": "Discovery tags.",
+      "default": []
+    },
+    "updated": {
+      "type": "string",
+      "format": "date-time",
+      "description": "ISO 8601 timestamp the fragment was last amended."
+    }
+  }
+}

package/src/apothem/schemas/freshness-token-denylist.txt

@@ -0,0 +1,51 @@
+# SPDX-License-Identifier: MIT
+#
+# Freshness-token denylist loaded by freshness_token_grep.
+#
+# The freshness-facade mandate (rules/freshness-facade.md) keeps every
+# shipped public surface a current-version-only facade: no backward / legacy
+# replacement narrative, no placeholder / deferral, no fix-and-refinement
+# story-of-becoming. This file enumerates the high-precision narrative PHRASES
+# that mark those classes — never bare common words.
+#
+# Two boundaries keep this set precise:
+#
+#   1. Bare words such as "legacy", "deprecated", "retired", "placeholder",
+#      and "backward" have legitimate uses (a Keep-a-Changelog `Deprecated`
+#      heading, a documented deprecation policy, a "placeholder identity"
+#      product feature, a "future clarity backward" idiom) and are absent.
+#      Present-tense facts that are not story-of-becoming — "backward-compatible
+#      with v1", "X is no longer supported" — are also absent: a truthful
+#      current-version surface may state them.
+#   2. The AI-disclosure token-class (the bare "AI" token in "AI-generated",
+#      "generated by AI") is already forbidden on this exact README + site
+#      scope by `plain-language-grep`. To stay strictly non-overlapping, this
+#      denylist carries none of it; AI-disclosure enforcement is plain-language's.
+#
+# Only unambiguous story-of-becoming / replacement / deferral phrases remain,
+# so the matcher flags the narrative without flagging the dictionary word or
+# double-flagging what plain-language already owns.
+#
+# The matcher (conformity/freshness_token_grep.py) scans README.md plus the
+# site documentation tree, case-insensitively, outside fenced code blocks. Each
+# non-empty, non-comment line below is one forbidden phrase, matched literally.
+#
+# This file carries its SPDX line as a hash comment (the matcher skips comment
+# lines), mirroring schemas/reference-token-denylist.txt; it is not a header
+# exemption.
+
+# Backward / legacy replacement narrative.
+replaces the legacy
+legacy v0
+the old behavior
+
+# Placeholder / unfinished deferral.
+to be determined
+coming soon
+work in progress
+under construction
+stay tuned
+
+# Deferred-to-the-future narrative.
+in a future release
+in a future version