@ahmed-g-gad/apothem 0.1.1

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

@@ -0,0 +1,51 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://apothem.ahmedgad.com/schemas/plan.schema.json",
+  "title": "Plan",
+  "description": "Frontmatter schema for downstream-project plan files (per spec §3.3). Consumed by /plan-spec --quick to validate plan-frontmatter at authoring time.",
+  "type": "object",
+  "required": ["title", "project", "created", "updated", "status", "tags", "supersedes", "promotes-to"],
+  "additionalProperties": true,
+  "properties": {
+    "title": {
+      "type": "string",
+      "description": "Human-readable plan title."
+    },
+    "project": {
+      "type": "string",
+      "description": "Project identifier the plan belongs to."
+    },
+    "created": {
+      "type": "string",
+      "description": "ISO 8601 date the plan was created.",
+      "format": "date",
+      "pattern": "^\\d{4}-\\d{2}-\\d{2}$"
+    },
+    "updated": {
+      "type": "string",
+      "description": "ISO 8601 date of the plan's last update.",
+      "format": "date",
+      "pattern": "^\\d{4}-\\d{2}-\\d{2}$"
+    },
+    "status": {
+      "type": "string",
+      "description": "Lifecycle state of the plan.",
+      "enum": ["draft", "in-progress", "converged", "abandoned", "superseded"]
+    },
+    "tags": {
+      "type": "array",
+      "items": { "type": "string" },
+      "description": "Discovery tags."
+    },
+    "supersedes": {
+      "type": "array",
+      "items": { "type": "string" },
+      "description": "Identifiers of prior plans this plan supersedes."
+    },
+    "promotes-to": {
+      "type": "array",
+      "items": { "type": "string" },
+      "description": "Identifiers of downstream artifacts (typically ADRs) this plan promotes to on convergence."
+    }
+  }
+}

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

@@ -0,0 +1,83 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://apothem.ahmedgad.com/schemas/plugin.schema.json",
+  "title": "Plugin Manifest",
+  "description": "Schema for a Claude Code plugin manifest (.claude-plugin/plugin.json). Component fields carry plugin-root-relative paths beginning with './': 'commands' and 'agents' enumerate explicit markdown files so documentation files beside them are never registered as components; 'skills' names directories whose immediate children each carry a SKILL.md entry point.",
+  "type": "object",
+  "required": ["name", "version", "description"],
+  "additionalProperties": false,
+  "properties": {
+    "name": {
+      "type": "string",
+      "description": "Unique kebab-case plugin identifier.",
+      "pattern": "^[a-z0-9]+(-[a-z0-9]+)*$"
+    },
+    "version": {
+      "type": "string",
+      "description": "SemVer version of the plugin. Pins the plugin so consumers receive updates only when it changes.",
+      "pattern": "^\\d+\\.\\d+\\.\\d+$"
+    },
+    "description": {
+      "type": "string",
+      "description": "Capability-led description of what the plugin provides.",
+      "maxLength": 1024
+    },
+    "author": {
+      "type": "object",
+      "required": ["name"],
+      "additionalProperties": false,
+      "properties": {
+        "name": { "type": "string" },
+        "email": { "type": "string", "format": "email" },
+        "url": { "type": "string", "format": "uri" }
+      }
+    },
+    "homepage": {
+      "type": "string",
+      "format": "uri",
+      "description": "Plugin homepage or documentation URL."
+    },
+    "repository": {
+      "type": "string",
+      "format": "uri",
+      "description": "Source repository URL."
+    },
+    "license": {
+      "type": "string",
+      "description": "SPDX license identifier."
+    },
+    "keywords": {
+      "type": "array",
+      "items": { "type": "string" },
+      "description": "Tags for plugin discovery."
+    },
+    "commands": {
+      "$ref": "#/$defs/componentPathArray",
+      "description": "Explicit plugin-root-relative paths to command markdown files."
+    },
+    "agents": {
+      "$ref": "#/$defs/componentPathArray",
+      "description": "Explicit plugin-root-relative paths to agent markdown files."
+    },
+    "skills": {
+      "$ref": "#/$defs/componentPathArray",
+      "description": "Plugin-root-relative skill directories containing <name>/SKILL.md entries."
+    },
+    "hooks": {
+      "type": "string",
+      "pattern": "^\\./",
+      "description": "Plugin-root-relative path to a hooks.json configuration."
+    }
+  },
+  "$defs": {
+    "componentPathArray": {
+      "type": "array",
+      "minItems": 1,
+      "items": {
+        "type": "string",
+        "pattern": "^\\./",
+        "description": "Plugin-root-relative path beginning with './'."
+      }
+    }
+  }
+}

package/src/apothem/schemas/profile.example.yaml

@@ -0,0 +1,70 @@
+# SPDX-License-Identifier: MIT
+
+# Apothem shared profile example.
+# Copy to ~/.config/apothem/profile.yaml and edit local values.
+# Schema: src/apothem/schemas/profile.schema.json
+
+# Optional profile-schema version; defaults to the current version (1) when
+# omitted. Version-less profiles remain valid.
+schema_version: 1
+
+identity:
+  name: "Example User"
+  role: "senior software engineer"
+  email: "dev@example.invalid"
+  website: "https://example.invalid"
+  github: "example-user"
+
+preferences:
+  language: "python"
+  style: "concise"
+  formatter: "ruff"
+  test_framework: "pytest"
+
+seriousness: PERSONAL_USE
+
+# Opt-in toggles for shipped behaviors. Every flag is default-off; a clean
+# install imposes none of them. Set a flag true to opt into that behavior;
+# omit the block entirely to keep every behavior off.
+enforcement:
+  sprints: false
+  agent_teams: false
+  multitasking: false
+  continuous_execution: false
+  learning_loop: false
+
+rules:
+  - "Prefer explicit decisions over guessed product behavior."
+  - "Validate external input before writing files."
+  - "Keep generated harness output deterministic."
+
+# MCP server inventory: the cross-harness portability surface. Keyed by server
+# name. stdio servers carry command (+ optional args/env); http/sse/
+# streamable-http servers carry url. Apothem materializes these into the three
+# harnesses whose native config it renders directly (opencode, qwen-code,
+# hermes) and lists them as instruction-context reference (an "MCP Servers"
+# section in the managed block) for every other harness.
+mcp_servers:
+  filesystem:
+    transport: stdio
+    command: "npx"
+    args: ["-y", "@modelcontextprotocol/server-filesystem", "."]
+  docs:
+    transport: streamable-http
+    url: "https://mcp.example.invalid/docs"
+
+harnesses:
+  claude-code:
+    seriousness: SHARED
+  cursor:
+    preferences:
+      style: "verbose"
+    # Per-harness MCP overrides union with the shared inventory by server name.
+    mcp_servers:
+      search:
+        transport: http
+        url: "https://mcp.example.invalid/search"
+
+exclude_harnesses:
+  - antigravity
+  - open-claw

package/src/apothem/schemas/profile.minimal.yaml

@@ -0,0 +1,6 @@
+# SPDX-License-Identifier: MIT
+
+identity:
+  name: "Example User"
+  email: "dev@example.invalid"
+  github: "example-user"

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

@@ -0,0 +1,396 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://apothem.ahmedgad.com/schemas/profile.schema.json",
+  "title": "Apothem Shared Profile",
+  "description": "Canonical YAML profile consumed by Apothem before harness-native configuration is materialized.",
+  "type": "object",
+  "additionalProperties": false,
+  "required": ["identity"],
+  "properties": {
+    "schema_version": {
+      "type": "integer",
+      "minimum": 1,
+      "description": "Optional profile-schema version; defaults to the current version (1) when absent. Version-less profiles remain valid. A profile stamped with a version greater than the engine supports is rejected with an upgrade-the-engine diagnostic before validation."
+    },
+    "identity": {
+      "$ref": "#/$defs/identity"
+    },
+    "preferences": {
+      "$ref": "#/$defs/preferences"
+    },
+    "rules": {
+      "$ref": "#/$defs/rules",
+      "default": []
+    },
+    "seriousness": {
+      "$ref": "#/$defs/seriousness",
+      "default": "PERSONAL_USE"
+    },
+    "enforcement": {
+      "$ref": "#/$defs/enforcement",
+      "default": {}
+    },
+    "mcp_servers": {
+      "$ref": "#/$defs/mcpInventory",
+      "default": {}
+    },
+    "harnesses": {
+      "type": "object",
+      "description": "Per-harness overrides keyed by supported public harness id.",
+      "additionalProperties": false,
+      "default": {},
+      "properties": {
+        "antigravity": {
+          "$ref": "#/$defs/harnessOverride"
+        },
+        "claude-code": {
+          "$ref": "#/$defs/harnessOverride"
+        },
+        "codex": {
+          "$ref": "#/$defs/harnessOverride"
+        },
+        "cursor": {
+          "$ref": "#/$defs/harnessOverride"
+        },
+        "gemini-cli": {
+          "$ref": "#/$defs/harnessOverride"
+        },
+        "github-copilot": {
+          "$ref": "#/$defs/harnessOverride"
+        },
+        "hermes": {
+          "$ref": "#/$defs/harnessOverride"
+        },
+        "kimi-code": {
+          "$ref": "#/$defs/harnessOverride"
+        },
+        "open-claw": {
+          "$ref": "#/$defs/harnessOverride"
+        },
+        "opencode": {
+          "$ref": "#/$defs/harnessOverride"
+        },
+        "qwen-code": {
+          "$ref": "#/$defs/harnessOverride"
+        },
+        "windsurf": {
+          "$ref": "#/$defs/harnessOverride"
+        },
+        "codebuddy": {
+          "$ref": "#/$defs/harnessOverride"
+        },
+        "kiro": {
+          "$ref": "#/$defs/harnessOverride"
+        },
+        "trae": {
+          "$ref": "#/$defs/harnessOverride"
+        },
+        "zed": {
+          "$ref": "#/$defs/harnessOverride"
+        },
+        "glm": {
+          "$ref": "#/$defs/harnessOverride"
+        }
+      }
+    },
+    "exclude_harnesses": {
+      "type": "array",
+      "description": "Supported public harness ids skipped by batch lifecycle commands.",
+      "default": [],
+      "items": {
+        "$ref": "#/$defs/harnessId"
+      },
+      "uniqueItems": true
+    },
+    "workspace": {
+      "$ref": "#/$defs/workspace",
+      "default": {}
+    }
+  },
+  "$defs": {
+    "identity": {
+      "type": "object",
+      "description": "Operator identity fields shared across harnesses.",
+      "required": ["name"],
+      "additionalProperties": false,
+      "properties": {
+        "name": {
+          "type": "string",
+          "minLength": 1,
+          "description": "Operator display name."
+        },
+        "role": {
+          "type": "string",
+          "minLength": 1,
+          "default": "senior software engineer",
+          "description": "Operator role presented to capable harnesses."
+        },
+        "email": {
+          "type": "string",
+          "format": "email",
+          "description": "Operator email address."
+        },
+        "website": {
+          "type": "string",
+          "format": "uri",
+          "description": "Operator personal or project website URL."
+        },
+        "github": {
+          "type": "string",
+          "minLength": 1,
+          "description": "GitHub username without @."
+        }
+      }
+    },
+    "identityOverride": {
+      "type": "object",
+      "description": "Optional identity fields overridden for one harness.",
+      "additionalProperties": false,
+      "properties": {
+        "name": {
+          "type": "string",
+          "minLength": 1
+        },
+        "role": {
+          "type": "string",
+          "minLength": 1
+        },
+        "email": {
+          "type": "string",
+          "format": "email"
+        },
+        "website": {
+          "type": "string",
+          "format": "uri"
+        },
+        "github": {
+          "type": "string",
+          "minLength": 1
+        }
+      }
+    },
+    "preferences": {
+      "type": "object",
+      "description": "Workflow and interaction preferences shared across harnesses.",
+      "additionalProperties": false,
+      "default": {},
+      "properties": {
+        "language": {
+          "type": "string",
+          "minLength": 1,
+          "default": "python",
+          "description": "Primary programming language in lower-case semantic form."
+        },
+        "style": {
+          "type": "string",
+          "enum": ["concise", "verbose", "balanced"],
+          "default": "concise",
+          "description": "Preferred AI response style."
+        },
+        "formatter": {
+          "type": "string",
+          "minLength": 1,
+          "description": "Preferred code formatter."
+        },
+        "test_framework": {
+          "type": "string",
+          "minLength": 1,
+          "description": "Preferred test framework."
+        }
+      }
+    },
+    "rules": {
+      "type": "array",
+      "description": "Additional rules shared with capable harnesses.",
+      "items": {
+        "type": "string",
+        "minLength": 1
+      },
+      "uniqueItems": true
+    },
+    "seriousness": {
+      "type": "string",
+      "enum": ["EXPLORING", "PERSONAL_USE", "SHARED", "PUBLIC_LAUNCH"],
+      "description": "Governance seriousness tier."
+    },
+    "enforcement": {
+      "type": "object",
+      "description": "Opt-in toggles for shipped behaviors that ship default-off; every flag defaults false and a clean install imposes none of them.",
+      "additionalProperties": false,
+      "default": {},
+      "properties": {
+        "sprints": {
+          "type": "boolean",
+          "default": false,
+          "description": "Opt in to the sprint apparatus for non-trivial multi-step work."
+        },
+        "agent_teams": {
+          "type": "boolean",
+          "default": false,
+          "description": "Opt in to parallel agent-team dispatch for parallelizable work."
+        },
+        "multitasking": {
+          "type": "boolean",
+          "default": false,
+          "description": "Opt in to parallel multi-task execution."
+        },
+        "continuous_execution": {
+          "type": "boolean",
+          "default": false,
+          "description": "Opt in to continuous multi-step advancement across natural boundaries."
+        },
+        "learning_loop": {
+          "type": "boolean",
+          "default": false,
+          "description": "Opt in to continuous-learning capture and pattern promotion."
+        }
+      }
+    },
+    "workspace": {
+      "type": "object",
+      "description": "Where Apothem keeps its shared, gitignored working directory (plans, memory, learning, contexts). One directory shared across every harness; never per-harness.",
+      "additionalProperties": false,
+      "default": {},
+      "properties": {
+        "directory_name": {
+          "type": "string",
+          "minLength": 1,
+          "pattern": "^[^/\\\\:]+$",
+          "default": ".apothem",
+          "description": "Name of the shared working directory. A single path component (no separator, no drive specifier). Defaults to '.apothem'."
+        },
+        "scope": {
+          "type": "string",
+          "enum": ["project-local", "user-home"],
+          "default": "project-local",
+          "description": "Where the working directory is rooted. 'project-local' places <project-root>/<directory_name>/ (default); 'user-home' places ~/<directory_name>/."
+        }
+      }
+    },
+    "harnessId": {
+      "type": "string",
+      "enum": [
+        "antigravity",
+        "claude-code",
+        "codex",
+        "cursor",
+        "gemini-cli",
+        "github-copilot",
+        "hermes",
+        "kimi-code",
+        "open-claw",
+        "opencode",
+        "qwen-code",
+        "windsurf",
+        "codebuddy",
+        "kiro",
+        "trae",
+        "zed",
+        "glm"
+      ]
+    },
+    "harnessOverride": {
+      "type": "object",
+      "description": "Canonical profile fields overridden for one harness.",
+      "additionalProperties": false,
+      "properties": {
+        "identity": {
+          "$ref": "#/$defs/identityOverride"
+        },
+        "preferences": {
+          "$ref": "#/$defs/preferences"
+        },
+        "rules": {
+          "$ref": "#/$defs/rules"
+        },
+        "seriousness": {
+          "$ref": "#/$defs/seriousness"
+        },
+        "enforcement": {
+          "$ref": "#/$defs/enforcement"
+        },
+        "mcp_servers": {
+          "$ref": "#/$defs/mcpInventory"
+        }
+      }
+    },
+    "mcpInventory": {
+      "type": "object",
+      "description": "MCP server inventory keyed by server name: the canonical cross-harness portability surface for Model Context Protocol servers.",
+      "propertyNames": {
+        "pattern": "^\\S(.*\\S)?$"
+      },
+      "additionalProperties": {
+        "$ref": "#/$defs/mcpServer"
+      },
+      "default": {}
+    },
+    "mcpServer": {
+      "type": "object",
+      "description": "One MCP server. stdio servers carry command (+ args); http/sse/streamable-http servers carry url.",
+      "additionalProperties": false,
+      "required": ["transport"],
+      "properties": {
+        "transport": {
+          "type": "string",
+          "enum": ["stdio", "http", "sse", "streamable-http"],
+          "description": "MCP transport; streamable-http is the modern replacement for sse."
+        },
+        "command": {
+          "type": "string",
+          "minLength": 1,
+          "description": "Executable launched for a stdio server."
+        },
+        "args": {
+          "type": "array",
+          "items": {
+            "type": "string"
+          },
+          "default": [],
+          "description": "Arguments passed to the stdio command."
+        },
+        "env": {
+          "type": "object",
+          "additionalProperties": {
+            "type": "string"
+          },
+          "default": {},
+          "description": "Environment variables passed to the server process."
+        },
+        "url": {
+          "type": "string",
+          "format": "uri",
+          "description": "Endpoint URL for an http/sse/streamable-http server."
+        }
+      },
+      "allOf": [
+        {
+          "if": {
+            "properties": {
+              "transport": {
+                "const": "stdio"
+              }
+            },
+            "required": ["transport"]
+          },
+          "then": {
+            "required": ["command"]
+          }
+        },
+        {
+          "if": {
+            "properties": {
+              "transport": {
+                "enum": ["http", "sse", "streamable-http"]
+              }
+            },
+            "required": ["transport"]
+          },
+          "then": {
+            "required": ["url"]
+          }
+        }
+      ]
+    }
+  }
+}

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

@@ -0,0 +1,25 @@
+# SPDX-License-Identifier: MIT
+#
+# Reference-token denylist loaded by reference_token_grep.
+#
+# Apothem reimplements a peer platform's feature-set in its own voice with
+# zero branding leak. This file enumerates the reference platform's slug and
+# brand variants so the mechanical sweep can prove no in-scope authored
+# surface leaks them. The matcher loads every non-empty, non-comment line as
+# a forbidden token and asserts zero hits across the authored surface set.
+#
+# This data file is OUT of the sweep's in-scope set (it lives under
+# src/apothem/schemas/, which the matcher exempts), so it safely contains the
+# tokens it forbids elsewhere.
+#
+# One token per line. '#' begins a comment line. Pure-alpha slugs are matched
+# at word boundaries; punctuation-bearing tokens are matched as escaped
+# literals. All matching is case-insensitive.
+ECC
+ecc.tools
+ecc-tools
+affaan
+agentshield
+ecc-agentshield
+ecc-universal
+ecc-install