Artifact Schema Specification

Per-class YAML frontmatter templates and required fields for all Apothem ecosystem artifacts.

Source of truth. The machine-readable, gate-enforced contract is the per-class JSON Schemas under src/apothem/schemas/ (agent.schema.json, command.schema.json, skill.schema.json, …). The skill and command schemas declare additionalProperties: false, so they reject unknown keys; the agent, output-style, and plan schemas declare additionalProperties: true. This page and frontmatter-schema.mdx are the two human-readable projections of those schemas — this page carries the per-class templates and worked examples, frontmatter-schema the terse required-key index. Where a page disagrees with the JSON Schemas, the schemas win.

OverviewCopy Anchor Link

All artifacts in the Apothem source tree (under src/apothem/ and the root configuration surface) must include a YAML frontmatter block (between --- delimiters) with mandatory and optional fields specific to their artifact type. This document defines the canonical schema for each type.

Universal Rules:

• Frontmatter is YAML 1.2 compliant
• All string values use double quotes, and an empty string is written ""
• Field order: mandatory fields first, optional fields grouped by relevance
• Comments in frontmatter use # with space: # comment
• Path values must be relative (no leading /) and use forward slashes (/) for cross-platform compatibility

Versioning Convention (versioned artifact classes — commands, helpers, skills, CLAUDE.md):

• version is semantic (MAJOR.MINOR.PATCH). Bump MAJOR for breaking schema or contract changes; MINOR for additive non-breaking changes (new optional fields, additional sections, additional anti-patterns); PATCH for a behavioral change that corrects an existing directive without breaking the contract.
• Typo fixes, link fixes, formatting, and comment-only or documentation-only edits leave version unchanged. Only a behavioral change bumps it.
• updated is the ISO 8601 date (YYYY-MM-DD) of the most recent edit. It must change with every version bump, and it changes on a non-version-bumping typo or link fix as well.
• New artifacts seed at v0.Y.Z. Promotion to vX.Y.Z indicates the artifact's contract is stable enough to be a public commitment.
• Plan suites are outside this convention. A typo fix to a plan suite bumps the PATCH number of the suite's version (vX.Y.Z to vX.Y.(Z+1)) and appends a Revision History row. The developer guide describes the plan-suite rule in its plan-suite revisions section.

Schema: RulesCopy Anchor Link

Path pattern: src/apothem/rules/*.md

Purpose: Behavioral mandates and operational directives.

Mandatory FieldsCopy Anchor Link

---
name: "kebab-case-identifier"
description: "One-line description"
pathFilter: "**/*.py, **/*.toml"
alwaysApply: true | false
---

Optional FieldsCopy Anchor Link

Rules carry no optional frontmatter fields, and — unlike other artifact classes — no version / updated / scope / portability fields either. The four mandatory fields above are the complete rule frontmatter contract enforced by frontmatter_grep.

ExampleCopy Anchor Link

---
name: "operational-mandates"
description: "Behavioral definitions for CM-1 through CM-10: violation indicators and recovery actions"
pathFilter: ""
alwaysApply: true
---

# Rule: Operational Mandates
...

Schema: CommandsCopy Anchor Link

Path pattern: src/apothem/commands/*.md

Purpose: Slash command definitions (/plan-execute, /freshify, etc.).

Mandatory FieldsCopy Anchor Link

---
name: "command-name"
version: "MAJOR.MINOR.PATCH"
updated: "YYYY-MM-DD"
description: "What this command does"
argument-hint: "[argument-pattern]"
disable-model-invocation: true | false
portability: "universal"
allowed-tools: "Read, Glob, Grep"
---

Optional FieldsCopy Anchor Link

Commands carry no optional frontmatter fields — the eight mandatory fields above are the complete command frontmatter contract enforced by command.schema.json (additionalProperties: false).

ExampleCopy Anchor Link

---
name: "plan-execute"
version: "X.Y.Z"
updated: "2026-04-20"
description: "Executes a specific phase from a Master Plan Suite with conformity checking and quality gates"
argument-hint: "[path/to/plan-suite/] [phase-id] [--dry-run]"
disable-model-invocation: true
portability: "universal"
allowed-tools: "Read, Glob, Grep"
---

# /plan-execute — Execute a Specific Phase
...

Schema: HelpersCopy Anchor Link

Path pattern:

src/apothem/agents/*.md

Purpose: Persistent helper definitions (also called delegated workers) for parallel exploration, auditing, and quality gates.

Mandatory FieldsCopy Anchor Link

---
name: "agent-name"
version: "MAJOR.MINOR.PATCH"
updated: "YYYY-MM-DD"
description: "What this agent specializes in"
tools: "Tool1, Tool2, Tool3"
disallowedTools: "Write, Edit"
maxTurns: 20
effort: "high" | "medium" | "low"
---

Optional FieldsCopy Anchor Link

permissionMode: "default"       # Permission handling
memory: user | project | local  # Persistent-memory scope; omit for none
pattern: "Research" | "Audit" | "Implementation" | "Quality"  # Agent team pattern
portability: "universal"

ExampleCopy Anchor Link

---
name: "codebase-explorer"
version: "X.Y.Z"
updated: "2026-04-20"
description: "Deep codebase exploration — find patterns, trace dependencies, discover conventions, map architecture"
tools: "Read, Glob, Grep, Bash"
disallowedTools: "Write, Edit, TodoWrite"
maxTurns: 20
effort: "high"
permissionMode: "default"
portability: "universal"
---

You are a codebase exploration specialist...

Schema: SkillsCopy Anchor Link

Path pattern: src/apothem/skills/*/SKILL.md

Purpose: Reusable technique definitions with detection signals and execution procedures.

Mandatory FieldsCopy Anchor Link

---
name: "skill-name"
version: "MAJOR.MINOR.PATCH"
updated: "YYYY-MM-DD"
description: "What this skill teaches"
archetype: "workflow-template"
userInvocable: true | false
disable-model-invocation: true | false
allowed-tools: "Read, Glob, Grep"
---

Optional FieldsCopy Anchor Link

argument-hint: "[args...]"                           # Usage pattern if userInvocable

ExampleCopy Anchor Link

---
name: "ecosystem-audit"
version: "X.Y.Z"
updated: "2026-04-20"
description: "Comprehensive blind audit of the apothem ecosystem"
archetype: "audit-template"
userInvocable: true
disable-model-invocation: false
allowed-tools: "Read, Glob, Grep, Agent, TodoWrite"
argument-hint: "[--focus area] [--fix]"
---

## Purpose
...

Schema: HooksCopy Anchor Link

Path pattern: settings.json hooks block plus the Python implementations under src/apothem/hooks/.

Purpose: Declare event-triggered validators and state-management handlers that the host invokes at well-defined lifecycle points.

Settings-File SchemaCopy Anchor Link

The hooks top-level key maps event names to arrays of matcher blocks:

"hooks": {
  "<EventName>": [
    {
      "matcher": "<pattern>",
      "hooks": [
        {
          "type": "command",
          "command": "${PYTHON_BIN}",
          "args": ["${HARNESS_ROOT}/.apothem/support/hooks/dispatch.py", "<EventName>", "<message-name>"],
          "timeout": <seconds>,
          "statusMessage": "<short human-readable label>"
        }
      ]
    }
  ]
}

The -m apothem.hooks.dispatch form is for development from a source checkout with PYTHONPATH=src.

Required EventsCopy Anchor Link

The Claude Code template registers four events: SessionStart, PreToolUse, PostToolUse and Stop. scripts/dev/validate_hooks.py checks settings.json for the five events in the table below, a different set, and reports each one it does not find as a warning, not a failure. PostToolUse is registered but is not one of the five. PreCompact and PostCompact are among the five but are not registered on Claude Code (hooks reference), so the checker warns about both there.

Timeout values mirror the canonical hook-event budgets — the table below reproduces them for reader convenience; the canonical source governs.

dispatch.py also accepts UserPromptSubmit and Notification on its event whitelist for forward compatibility; neither is wired in the shipped templates. Add a matcher block with the same exec-form pattern to enable.

Python LayerCopy Anchor Link

Every hook command routes through the same Python dispatcher:

ValidationCopy Anchor Link

scripts/dev/validate_hooks.py enforces the hook contract:

• settings.json parses as JSON and declares each of the five events in the table; a missing event is a warning, not a failure.
• All three Python scripts exist and parse as valid Python.
• All message files referenced by --context-file arguments exist.
• No hardcoded absolute user paths (C:\Users\... etc.) appear in src/apothem/hooks/**.py.
• Shell artifacts under src/apothem/hooks/ and scripts/ are limited to the approved locator / bootstrap stubs.

Schema: CLAUDE.mdCopy Anchor Link

Path: CLAUDE.md (root)

Purpose: Project-scoped Claude Code instructions.

Mandatory YAML FrontmatterCopy Anchor Link

---
name: "CLAUDE"
version: "MAJOR.MINOR.PATCH"
updated: "YYYY-MM-DD"
description: "Project-scoped Claude Code instructions for the Apothem source repository"
scope: "project"
portability: "project-local"
---

SectionsCopy Anchor Link

CLAUDE.md is authored in prose sections, described at CLAUDE.md. No validator requires a fixed section list: scripts/dev/validate_ecosystem.py checks the frontmatter keys above.

Validation ChecklistCopy Anchor Link

Every artifact must satisfy these checks:

Frontmatter ValidationCopy Anchor Link

• YAML is syntactically valid (no parsing errors)
• All mandatory fields present for artifact type
• name follows kebab-case convention
• version is semantic (MAJOR.MINOR.PATCH)
• updated is ISO 8601 date format (YYYY-MM-DD)
• description is non-empty string, single line
• Optional fields match expected enum values (if applicable)
• No typos in field names (use canonical names from schema)
• No extra whitespace or formatting issues

Content ValidationCopy Anchor Link

• Content begins on a new line after the closing ---; on Markdown-family files the canonical SPDX header line is the first content after it
• No plan-internal references (CM-7 compliance)
• Cross-references resolve (if listing other artifacts)
• Links use relative paths with forward slashes

Portability ValidationCopy Anchor Link

• No hardcoded absolute paths (use relative)
• No Windows-specific syntax in universal-scope artifacts
• Path separators use forward slashes
• Environment variables use platform-agnostic format (${VAR} or tool-native)

NotesCopy Anchor Link

• Consistency as Security: Canonical frontmatter enables automated validation, tooling, and cross-artifact verification. Deviations compound quickly.
• Portability Declaration: Not all artifacts can be universal. Declare constraints explicitly — better to document a caveat than ship a silent bug.
• Kebab-case for Names: Easy to use in URLs, scripts, and command-line contexts. Avoid spaces, underscores, and camelCase for names.
• Version Bump Hygiene: Every behavior-changing edit must bump version and updated together. Typo fixes, link fixes, and formatting changes leave the version unchanged; new optional sections or anti-patterns bump MINOR; structural reorganization or contract changes bump MAJOR.