@ahmed-g-gad/apothem 0.1.1

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

@@ -0,0 +1,106 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://apothem.ahmedgad.com/schemas/agent.schema.json",
+  "title": "Agent",
+  "description": "Frontmatter schema for persistent agent definitions under src/apothem/agents/. Reconciled to the Anthropic Claude Code subagent canonical format (https://code.claude.com/docs/en/sub-agents#supported-frontmatter-fields): only `name` and `description` are required; multi-word optional fields use camelCase; unrecognized fields are accepted as metadata.",
+  "type": "object",
+  "required": ["name", "description"],
+  "additionalProperties": true,
+  "properties": {
+    "name": {
+      "type": "string",
+      "description": "Unique kebab-case identifier (lowercase letters and hyphens). The filename does not have to match.",
+      "pattern": "^[a-z0-9]+(-[a-z0-9]+)*$"
+    },
+    "description": {
+      "type": "string",
+      "description": "When Claude should delegate to this subagent (one to two sentences)."
+    },
+    "tools": {
+      "oneOf": [
+        { "type": "string" },
+        { "type": "array", "items": { "type": "string" } }
+      ],
+      "description": "Tools the subagent may invoke. Inherits all tools if omitted. Accepts a comma-separated string or a JSON array."
+    },
+    "disallowedTools": {
+      "oneOf": [
+        { "type": "string" },
+        { "type": "array", "items": { "type": "string" } }
+      ],
+      "description": "Tools to deny, removed from inherited or specified list. Accepts a comma-separated string or a JSON array."
+    },
+    "model": {
+      "type": "string",
+      "description": "Model selection: `sonnet`, `opus`, `haiku`, a full model ID (e.g. `claude-opus-4-7`), or `inherit`. Defaults to `inherit`."
+    },
+    "permissionMode": {
+      "type": "string",
+      "enum": ["default", "acceptEdits", "auto", "dontAsk", "bypassPermissions", "plan"],
+      "description": "How the subagent handles permission prompts."
+    },
+    "maxTurns": {
+      "type": "integer",
+      "minimum": 1,
+      "description": "Maximum number of agentic turns before the subagent stops."
+    },
+    "skills": {
+      "type": "array",
+      "items": { "type": "string" },
+      "description": "Skills to preload into the subagent's context at startup."
+    },
+    "mcpServers": {
+      "type": "array",
+      "description": "MCP servers available to this subagent. Each entry is either a server name (string) or an inline definition (object)."
+    },
+    "hooks": {
+      "type": "object",
+      "description": "Lifecycle hooks scoped to this subagent (PreToolUse, PostToolUse, Stop, etc.)."
+    },
+    "memory": {
+      "oneOf": [
+        { "type": "string", "enum": ["user", "project", "local"] },
+        { "type": "boolean" }
+      ],
+      "description": "Persistent memory scope: `user`, `project`, or `local`. Boolean `false` is accepted as the explicit no-memory marker; omit the field to inherit defaults."
+    },
+    "background": {
+      "type": "boolean",
+      "description": "Always run this subagent as a background task when true. Default: false."
+    },
+    "effort": {
+      "type": "string",
+      "enum": ["low", "medium", "high", "xhigh", "max"],
+      "description": "Effort level when this subagent is active. Overrides the session effort level."
+    },
+    "isolation": {
+      "type": "string",
+      "enum": ["worktree"],
+      "description": "Set to `worktree` to run the subagent in a temporary git worktree."
+    },
+    "color": {
+      "type": "string",
+      "enum": ["red", "blue", "green", "yellow", "purple", "orange", "pink", "cyan"],
+      "description": "Display color for the subagent in the task list and transcript."
+    },
+    "initialPrompt": {
+      "type": "string",
+      "description": "Auto-submitted as the first user turn when this agent runs as the main session agent."
+    },
+    "version": {
+      "type": "string",
+      "description": "Apothem extension: SemVer version of the agent definition.",
+      "pattern": "^\\d+\\.\\d+\\.\\d+$"
+    },
+    "updated": {
+      "type": "string",
+      "description": "Apothem extension: ISO 8601 date of last revision.",
+      "format": "date",
+      "pattern": "^\\d{4}-\\d{2}-\\d{2}$"
+    },
+    "portability": {
+      "type": "string",
+      "description": "Apothem extension: portability classification across harness adapters (e.g., `universal`, `claude-code-only`)."
+    }
+  }
+}

package/src/apothem/schemas/authorship-header.txt

@@ -0,0 +1 @@
+# SPDX-License-Identifier: MIT

package/src/apothem/schemas/cohort-manifest.yaml

@@ -0,0 +1,248 @@
+# SPDX-License-Identifier: MIT
+
+# Apothem cohort manifest.
+#
+# Validates against cohort.schema.json. Defines all six cohorts
+# (core, developer, security, research, ai-engineering, full) with their
+# member sets. `full` is the union of the other five.
+#
+# Every member name corresponds to a real artifact under src/apothem/
+# (skills/<name>/, agents/<name>.md, commands/<name>.md, rules/<name>.md, or a
+# hooks/ entry). Per-harness native targets are NOT restated here: a consumer
+# resolves them through per_harness_targets.source (lib/propagation-manifest.yaml)
+# per the resolution rule. See site/content/docs/architecture/cohort-packaging-contract.mdx.
+
+version: 0.2.0
+
+cohorts:
+  - id: core
+    name: Core
+    description: >-
+      The baseline cohort installed for every operator: the planning workflow,
+      the entry code review, the foundational agents, and the always-on
+      behavioral rules. The minimum coherent working set.
+    members:
+      skills:
+        - ecosystem-audit
+        - plan-suite
+      agents:
+        - codebase-explorer
+        - convention-auditor
+        - quality-gate
+        - memory-auditor
+      commands:
+        - plan-spec
+        - plan-generate
+        - plan-review
+        - plan-design
+        - plan-audit
+        - plan-execute
+        - plan-status
+        - code-review
+      rules:
+        - agent-orchestration
+        - context-management
+        - definitiveness
+        - pre-emission-gate
+      hooks:
+        - dispatch
+
+  - id: developer
+    name: Developer
+    description: >-
+      The day-to-day build loop: review, audit, refactor, test, architecture,
+      documentation, dependencies, performance, accessibility, and user
+      experience. Code-craft and quality surfaces.
+    members:
+      skills:
+        - test-authoring
+        - refactor-extract
+        - dependency-upgrade
+        - incident-runbook
+      agents:
+        - test-runner
+        - refactor-surgeon
+        - dependency-auditor
+      commands:
+        - code-review
+        - code-audit
+        - architecture-review
+        - docs-review
+        - perf-audit
+        - a11y-audit
+        - ux-review
+        - dependency-audit
+        - test-suite
+        - release-readiness
+      rules:
+        - code-craft-python
+        - code-craft-shell
+        - code-craft-markdown
+        - clean-architecture-layers
+      hooks:
+        - pretooluse-dependency-guard
+
+  - id: security
+    name: Security
+    description: >-
+      Defensive posture: security, supply-chain, and threat-model audits,
+      secret handling, vulnerability triage, and dependency risk.
+    members:
+      skills:
+        - secret-rotation
+        - vuln-triage
+        - dependency-upgrade
+        - incident-runbook
+      agents:
+        - security-scanner
+        - dependency-auditor
+      commands:
+        - security-audit
+        - supply-chain-audit
+        - threat-model-audit
+        - dependency-audit
+        - release-readiness
+      rules:
+        - production-ready-prs
+        - authority-inquiry
+      hooks:
+        - pretooluse-dependency-guard
+
+  - id: research
+    name: Research
+    description: >-
+      Multi-source investigation: research orchestration, source discovery,
+      synthesis, and adversarial fact-checking. The primary output is a cited
+      research artifact.
+    members:
+      skills:
+        - multi-source-research
+        - source-synthesis
+      agents:
+        - research-scout
+        - fact-checker
+      commands:
+        - research
+      rules:
+        - host-discovery
+        - disclosure-ledger
+      hooks: []
+
+  - id: ai-engineering
+    name: AI-Engineering
+    description: >-
+      Building on language models: prompt design, evaluation harnesses,
+      Model Context Protocol servers, and prompt-output scoring.
+    members:
+      skills:
+        - prompt-engineering
+        - eval-harness
+      agents:
+        - prompt-evaluator
+        - mcp-builder
+      commands:
+        - eval
+      rules:
+        - cognitive-identity
+        - interactive-questions
+      hooks:
+        - pretooluse-eval-guard
+
+  - id: full
+    name: Full
+    description: >-
+      The superset of every other cohort. No catalog member is excluded.
+    members:
+      skills:
+        - ecosystem-audit
+        - plan-suite
+        - test-authoring
+        - refactor-extract
+        - dependency-upgrade
+        - incident-runbook
+        - secret-rotation
+        - vuln-triage
+        - multi-source-research
+        - source-synthesis
+        - prompt-engineering
+        - eval-harness
+      agents:
+        - codebase-explorer
+        - convention-auditor
+        - quality-gate
+        - memory-auditor
+        - test-runner
+        - refactor-surgeon
+        - dependency-auditor
+        - security-scanner
+        - research-scout
+        - fact-checker
+        - prompt-evaluator
+        - mcp-builder
+      commands:
+        - plan-spec
+        - plan-generate
+        - plan-review
+        - plan-design
+        - plan-audit
+        - plan-execute
+        - plan-status
+        - code-review
+        - code-audit
+        - architecture-review
+        - docs-review
+        - perf-audit
+        - a11y-audit
+        - ux-review
+        - dependency-audit
+        - security-audit
+        - supply-chain-audit
+        - threat-model-audit
+        - research
+        - test-suite
+        - eval
+        - release-readiness
+      rules:
+        - agent-orchestration
+        - context-management
+        - definitiveness
+        - code-craft-python
+        - code-craft-shell
+        - code-craft-markdown
+        - clean-architecture-layers
+        - production-ready-prs
+        - authority-inquiry
+        - host-discovery
+        - disclosure-ledger
+        - cognitive-identity
+        - interactive-questions
+        - pre-emission-gate
+      hooks:
+        - dispatch
+        - pretooluse-dependency-guard
+        - pretooluse-eval-guard
+
+per_harness_targets:
+  source: lib/propagation-manifest.yaml
+  harnesses:
+    - antigravity
+    - claude_code
+    - codex
+    - cursor
+    - gemini_cli
+    - github_copilot
+    - hermes
+    - open_claw
+    - opencode
+    - qwen_code
+    - windsurf
+    - codebuddy
+    - kiro
+    - trae
+    - zed
+  resolution: >-
+    For a cohort member of catalog type T (skills | agents | commands | rules |
+    hooks) and a target harness H, the native plugin target is the `target`
+    field of the entry in lib/propagation-manifest.yaml under
+    harnesses.H.install whose `source` matches `T/`. The propagation manifest is
+    the single source of truth; consumers never re-derive harness targets.

package/src/apothem/schemas/cohort-metadata-vocabulary.yaml

@@ -0,0 +1,168 @@
+# SPDX-License-Identifier: MIT
+
+# Canonical cohort-metadata vocabulary.
+#
+# Single repo-controlled source of truth for the status names, severity names,
+# ownership classes, frontmatter key sets, version-field rules, output-contract
+# field shapes, and exemption markers that the ecosystem's cohort files,
+# schemas, validators, and output envelopes use. Where the repo controls a
+# vocabulary, this file names its canonical values and the artifact that owns
+# them; where a surface uses a distinct vocabulary for a distinct purpose, the
+# scope is stated explicitly so the distinction reads as intentional, not drift.
+#
+# Consumed by tests/unit/test_cohort_metadata_vocabulary.py, which asserts that
+# every live schema and validator listed under `controlled_by` agrees with the
+# values declared here. A divergence on either surface fails that test.
+
+schema_version: 1
+
+# --- Status vocabulary -------------------------------------------------------
+# Each entry is a distinct status surface with its own closed value set. They
+# are not unified into one global enum because they answer different questions
+# (a plan's lifecycle, a review's verdict, a propagation write's outcome, a
+# mechanical gate's pass/fail).
+status_vocabulary:
+  plan_lifecycle:
+    values: [draft, in-progress, converged, abandoned, superseded]
+    controlled_by: src/apothem/schemas/plan.schema.json
+    scope: the `status` field of a plan suite's frontmatter
+  review_verdict:
+    values: [pass, fail, not-run]
+    controlled_by: src/apothem/schemas/handoff-manifest.yaml
+    scope: the `plan_review.verdict` field of the handoff manifest
+  plan_design_applicability:
+    values: [architecture-bearing, non-architecture-bearing]
+    controlled_by: src/apothem/schemas/handoff-manifest.yaml
+    scope: the `plan_design.applicability` field of the handoff manifest
+  materialization_outcome:
+    values: [created, updated, unchanged, skipped, warning, error]
+    controlled_by: src/apothem/harnesses/_shared/install_driver.py
+    scope: the per-result `outcome` field of a propagation MaterializationResult
+  gate_result:
+    representation: boolean field `passed` plus process exit code
+    pass_exit_code: 0
+    fail_exit_code: 2
+    controlled_by: src/apothem/conformity/gate.py
+    scope: the mechanical pass/fail surface of every conformity validator
+
+# --- Severity vocabulary -----------------------------------------------------
+# Two distinct, orthogonal severity surfaces; neither subsumes the other.
+severity_vocabulary:
+  questionable_priority:
+    values: [p0, p1, p2]
+    controlled_by: src/apothem/schemas/handoff-manifest.yaml
+    scope: priority tier of an unresolved questionable in the handoff manifest
+  gate_finding_severity:
+    values: [error, warning]
+    controlled_by: src/apothem/conformity
+    scope: >-
+      finding tier emitted by validators that classify findings
+      (license-author-consistency, multi-surface-coherence); validators without
+      a tier surface the binary pass/fail of `gate_result` instead
+
+# --- Ownership classes -------------------------------------------------------
+# Propagation write-planning classes; gate destructive writes to operator-owned
+# and refuse vendor-reserved / immutable targets.
+ownership_classes:
+  values: [apothem-owned, generated, immutable, operator-owned, vendor-reserved]
+  controlled_by: src/apothem/lib/propagation.py
+
+# --- Frontmatter / native metadata -------------------------------------------
+# Two-tier model. The mechanical floor is the fast per-Write presence check the
+# conformity grep enforces on every cohort file; the authoritative contract is
+# the full per-cohort required-key set the JSON schema enforces at validation
+# time. The floor is a strict subset of the contract; the two tiers are
+# deliberate, not redundant.
+frontmatter:
+  mechanical_floor:
+    controlled_by: src/apothem/conformity/frontmatter_grep.py
+    required_keys:
+      rules: [alwaysApply, description, name]
+      agents: [description, name]
+      skills: [description, name]
+      commands: [description, name]
+      output-styles: [description, name]
+      hooks-messages: [description]
+  authoritative_contract:
+    required_keys:
+      agents:
+        controlled_by: src/apothem/schemas/agent.schema.json
+        keys: [description, name]
+      commands:
+        controlled_by: src/apothem/schemas/command.schema.json
+        keys:
+          [
+            allowed-tools,
+            argument-hint,
+            description,
+            disable-model-invocation,
+            name,
+            portability,
+            updated,
+            version,
+          ]
+      skills:
+        controlled_by: src/apothem/schemas/skill.schema.json
+        keys:
+          [
+            allowed-tools,
+            archetype,
+            description,
+            disable-model-invocation,
+            name,
+            updated,
+            userInvocable,
+            version,
+          ]
+      output-styles:
+        controlled_by: src/apothem/schemas/output-style.schema.json
+        # The schema's required floor is name + description (matching the
+        # mechanical floor); applies-to, id, last-reviewed, version are
+        # optional extensions the shipped styles do not carry.
+        keys: [description, name]
+  version_field_rule:
+    # SemVer `version` (`^\d+\.\d+\.\d+$`) frontmatter field.
+    required: [commands, skills]
+    # agent.schema.json and output-style.schema.json carry `version` as an
+    # optional extension; the shipped output-styles do not declare it.
+    optional: [agents, output-styles]
+    absent: [hooks-messages, plan, rules]
+
+# --- Output-contract field shapes --------------------------------------------
+# The JSON envelope shapes the repo emits. Validators and consumers bind to
+# these keys; a new emitter reuses one of these shapes rather than inventing a
+# field set.
+output_contract_fields:
+  conformity_grep_result:
+    keys: [findings, grep, passed, path]
+    controlled_by: src/apothem/conformity (every *_grep.py GrepResult)
+  hook_envelope_hook_specific:
+    keys: [hookSpecificOutput.additionalContext, hookSpecificOutput.hookEventName]
+    controlled_by: src/apothem/hooks/emit_hook_context.py
+    scope: events in HOOK_SPECIFIC_OUTPUT_EVENTS
+  hook_envelope_system_message:
+    keys: [systemMessage]
+    controlled_by: src/apothem/hooks/emit_hook_context.py
+    scope: PreCompact / PostCompact events
+  materialization_result:
+    required_keys: [message, operation, outcome, path]
+    optional_keys: [backup_path, detail, source]
+    controlled_by: src/apothem/harnesses/_shared/install_driver.py
+  materialization_run:
+    keys: [changed, counts, dry_run, files_written, harness, results]
+    controlled_by: src/apothem/harnesses/_shared/install_driver.py
+
+# --- Exemption markers -------------------------------------------------------
+exemption_markers:
+  authorship_header_exceptions:
+    controlled_by: src/apothem/schemas/header-exceptions.txt
+    scope: file classes exempt from the canonical SPDX header line
+  option_annotation_definitional_exclusions:
+    controlled_by: src/apothem/conformity/option_annotation_grep.py
+    scope: >-
+      rule and skill files that define the option-annotation convention; their
+      worked examples are specification material, not live invocations
+  propagation_destructive_gate:
+    marker: "destructive_gate: required"
+    controlled_by: src/apothem/harnesses/_shared/install_driver.py
+    scope: detail marker on a MaterializationResult for an operator-owned target

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

@@ -0,0 +1,113 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://apothem.ahmedgad.com/schemas/cohort.schema.json",
+  "title": "Cohort Manifest",
+  "description": "Schema for a cohort-manifest document per design C12. A cohort is a named, downstream-consumable grouping of catalog members (skills, agents, commands, rules, hooks) drawn from the closed cohort set (core, developer, security, research, ai-engineering, full). The manifest carries a per_harness_targets contract that lets a consumer resolve, for each cohort and harness, the native plugin target WITHOUT re-deriving the mapping: it references the propagation manifest as the single source of truth. Exhaustive membership population is owned by a later phase; this schema fixes the SHAPE.",
+  "type": "object",
+  "required": ["version", "cohorts", "per_harness_targets"],
+  "additionalProperties": false,
+  "properties": {
+    "version": {
+      "type": "string",
+      "description": "SemVer version of the cohort manifest.",
+      "pattern": "^\\d+\\.\\d+\\.\\d+$"
+    },
+    "cohorts": {
+      "type": "array",
+      "description": "The cohort entries declared by this manifest.",
+      "minItems": 1,
+      "items": { "$ref": "#/$defs/cohort" }
+    },
+    "per_harness_targets": {
+      "$ref": "#/$defs/perHarnessTargets",
+      "description": "Contract describing how a downstream consumer resolves each cohort's per-harness native plugin target. References the propagation manifest as the source of truth rather than restating the mapping."
+    }
+  },
+  "$defs": {
+    "cohort": {
+      "type": "object",
+      "required": ["id", "name", "description", "members"],
+      "additionalProperties": false,
+      "properties": {
+        "id": {
+          "type": "string",
+          "description": "Closed-set cohort identifier.",
+          "enum": ["core", "developer", "security", "research", "ai-engineering", "full"]
+        },
+        "name": {
+          "type": "string",
+          "description": "Human-readable cohort name."
+        },
+        "description": {
+          "type": "string",
+          "description": "What the cohort provides and who it targets.",
+          "maxLength": 1024
+        },
+        "members": {
+          "$ref": "#/$defs/members",
+          "description": "Member names grouped by catalog item type. Each list holds stable kebab-case member identifiers."
+        }
+      }
+    },
+    "members": {
+      "type": "object",
+      "additionalProperties": false,
+      "properties": {
+        "skills": { "$ref": "#/$defs/memberNameArray" },
+        "agents": { "$ref": "#/$defs/memberNameArray" },
+        "commands": { "$ref": "#/$defs/memberNameArray" },
+        "rules": { "$ref": "#/$defs/memberNameArray" },
+        "hooks": { "$ref": "#/$defs/memberNameArray" }
+      }
+    },
+    "memberNameArray": {
+      "type": "array",
+      "items": {
+        "type": "string",
+        "description": "Stable kebab-case member identifier corresponding to an artifact under src/apothem/.",
+        "pattern": "^[a-z0-9]+(-[a-z0-9]+)*$"
+      }
+    },
+    "perHarnessTargets": {
+      "type": "object",
+      "required": ["source", "resolution"],
+      "additionalProperties": false,
+      "properties": {
+        "source": {
+          "type": "string",
+          "description": "Relative path (from src/apothem/) to the propagation manifest that is the single source of truth for per-harness native targets. A consumer resolves a cohort member's native plugin target by looking up the member's catalog item type in this manifest's `harnesses.<harness>.install` list.",
+          "const": "lib/propagation-manifest.yaml"
+        },
+        "harnesses": {
+          "type": "array",
+          "description": "The closed harness cohort whose native targets are resolvable through the source manifest.",
+          "items": {
+            "type": "string",
+            "enum": [
+              "antigravity",
+              "claude_code",
+              "codex",
+              "cursor",
+              "gemini_cli",
+              "github_copilot",
+              "hermes",
+              "open_claw",
+              "opencode",
+              "qwen_code",
+              "windsurf",
+              "codebuddy",
+              "kiro",
+              "trae",
+              "zed"
+            ]
+          },
+          "uniqueItems": true
+        },
+        "resolution": {
+          "type": "string",
+          "description": "Human-readable note describing the resolution rule: for a given cohort member of catalog type T and a target harness H, the native plugin target is the `target` field of the entry in propagation-manifest.yaml `harnesses.H.install` whose `source` matches `T/` (e.g. `skills/`, `agents/`, `commands/`, `rules/`, `hooks/`)."
+        }
+      }
+    }
+  }
+}