title: "Contributing to apothem — Developer Guide" version: "0.1.0" updated: "2026-04-20"

Contributing to apothem — Developer Guide¶

This guide helps developers maintain and extend the apothem ecosystem with SOTA quality standards.

Quick Reference: Artifact Types¶

The apothem ecosystem contains five artifact types, each with specific purposes and frontmatter requirements.

Before You Write: The Canonical Schema¶

All artifacts must follow the schema in docs/artifact-schema.md. This is non-negotiable.

• Read docs/artifact-schema.md § "Schema" for your artifact type
• Copy the required fields
• Fill in mandatory values
• Add optional fields as needed

Frontmatter Quick-Check¶

Every artifact frontmatter must pass these checks:

✓ Valid YAML syntax (use tools: `yamllint` or PowerShell `ConvertFrom-Yaml` where available)
✓ All mandatory fields present (per schema for artifact type)
✓ name: uses kebab-case
✓ version: semantic MAJOR.MINOR.PATCH
✓ updated: ISO 8601 date (YYYY-MM-DD)
✓ description: single-line, non-empty
✓ scope: valid enum (always-on|path-filtered|other)
✓ portability: valid enum (`universal` | `universal-with-windows-caveats` | `unix-only` | `windows-only`)
✓ No typos in field names — must match canonical schema exactly
✓ Optional fields use correct enum values

Naming Conventions¶

Artifact Names (kebab-case)¶

• Rules: operational-mandates, clean-room-generation, context-management
• Commands: plan-execute, plan-spec, plan-generate
• Agents: codebase-explorer, convention-auditor, quality-gate
• Skills: plan-suite, ecosystem-audit

Pattern: lowercase, hyphens between words, no spaces or underscores.

File Naming¶

• Rules: {name}.md
• Commands: {name}.md
• Agents: {name}.md
• Skills: Inside folder src/apothem/skills/{name}/SKILL.md (exact case: SKILL.md)
• Hooks: Inside folder src/apothem/hooks/. All event handlers are Python. Every settings.json / settings-unix.json hook command invokes the matching src/apothem/hooks/lib/bootstrap.{ps1,sh} wrapper, which resolves the ecosystem root (CLAUDE_PROJECT_DIR → LLM_PROJECT_DIR → $HOME/.claude), sources the matching src/apothem/hooks/lib/find-python.{ps1,sh} locator for a real CPython 3.10+, and execs src/apothem/hooks/dispatch.py --event-name <event> [--context-file <path>]. dispatch.py routes SessionStart to session_start_bootstrap.main() and every other whitelisted event to emit_hook_context.main(). The only shell stubs permitted under src/apothem/hooks/ or scripts/ are the four locator + bootstrap files (find-python.{ps1,sh}, bootstrap.{ps1,sh}); any other .ps1 / .sh file fails the scripts/dev/validate_hooks.py hygiene check.

Cross-References¶

When referencing other artifacts, use exact names:

• Rules: "operational-mandates" (name field value)
• Commands: /plan-execute (with slash for human docs; without in code)
• Agents: codebase-explorer (name field value)
• Skills: plan-suite (name field value)

Never use file paths or truncated names in prose.

Portability: Windows vs. Unix¶

Every artifact must explicitly declare its portability status.

Universal (Default)¶

• Works identically on Windows, macOS, and Linux
• No shell assumptions
• Paths use forward slashes (/)
• No hardcoded absolute paths
• No Windows-specific PowerShell syntax

portability: "universal"

Universal with Windows Caveats¶

• Universal across POSIX hosts; the named caveat applies on the Windows platform variant declared in the content
• Document the caveat explicitly in content
• Example: "Symlinks not supported on Windows before Win 10"

portability: "universal-with-windows-caveats"

Document the caveat in a note immediately after the title.

Unix-Only / Windows-Only¶

• Explicitly restricted to one platform
• Rare in apothem — most should be universal
• Use only if platform-specific features are essential

portability: "unix-only"

Document the reason in the rule's first section.

Scope: Always-On vs. Path-Filtered¶

Always-On¶

Rule applies everywhere.

scope: "always-on"

Path-Filtered¶

Rule applies conditionally based on file path.

scope: "path-filtered"
pathFilter: "**/*.py, **/*.toml"

The pathFilter uses glob patterns (same format as .gitignore). When a file matches the filter, the rule activates.

Version Semantics¶

Every artifact carries its own semantic version (MAJOR.MINOR.PATCH):

• PATCH — typo fixes, formatting, link refresh, comment-only edits. Behavior unchanged.
• MINOR — additive non-breaking changes: new optional sections, additional anti-patterns, new optional frontmatter fields, new examples. Existing consumers continue to work without change.
• MAJOR — breaking schema or contract changes: removed sections, renamed fields, altered behavior of an existing directive, changes that require downstream artifacts to adapt.

Examples:

• 0.1.0 → 0.1.1 (PATCH: typo fix)
• 0.1.1 → 0.2.0 (MINOR: added new Anti-Patterns entry)
• 0.2.0 → 1.0.0 (MAJOR: declared contract stable)
• 1.0.0 → 2.0.0 (MAJOR: removed mandatory frontmatter field)

Bump version and updated together on every behavior-changing edit. Append a matching row to the ecosystem-level CHANGELOG.md for releases that bundle artifact changes.

When to Edit an Artifact¶

Rules¶

• Treat the Mandatory/Optional structure as load-bearing — restructuring it ripples through every dependent artifact (MAJOR bump required).
• Refine Anti-Patterns, Seriousness Scaling examples, and citations as understanding deepens (MINOR bump).
• Capture the rationale for any structural change in the relevant memory topic file.

Commands¶

• Argument shape is part of the public contract — break it only with explicit intent and propagate the change to every caller (MAJOR bump).
• Keep workflow steps and return contracts tight and current.
• Document non-obvious step sequencing inline.

Agents¶

• Keep disallowedTools minimal-but-adequate; document the rationale when it changes.
• Refine Operating Principles and Return Contracts as the agent's role matures (MINOR bump).
• Track capability shifts inline so callers can recalibrate expectations.

Skills¶

• Keep Procedure steps and Examples synchronized with reality.
• Detection signals must reflect actual user phrasing in current usage.
• Split a skill once it crosses ~150 lines (see auto-memory.md § Topic File Management).

Step-by-Step: Adding a New Rule¶

1. Assess Orthogonality¶

Does this rule overlap with existing rules? Search src/apothem/rules/ for related content.

If overlap >50%, consider extending an existing rule instead. See persistent-conventions-vigilance.md § Artifact Evolution.

2. Write Content¶

Follow the structure:

• Title: # Rule: {Title}
• Purpose section
• Obligations / Core directives (numbered, linked)
• Seriousness Scaling table (always required)
• Anti-Patterns section
• Enforcement section

3. Create Frontmatter¶

Use the schema from docs/artifact-schema.md § Schema: Rules. Set:

• name: kebab-case identifier
• version: "0.1.0" (initial)
• updated: today's date in ISO 8601
• scope: always-on or path-filtered
• portability: universal (or with caveats if needed)
• implements: List CM/TM/CP mandates this rule covers

Example:

---
name: "my-new-rule"
version: "0.1.0"
updated: "2026-04-20"
description: "Brief one-liner"
scope: "always-on"
portability: "universal"
implements: ["CM-5", "CM-21"]
---

4. Update CLAUDE.md¶

Add entry to §7.2 Rules registry table:

| My New Rule | `src/apothem/rules/my-new-rule.md` | Always-on | CM-5/CM-21 |

Maintain alphabetical order within the table.

5. Append to CHANGELOG.md¶

Add a row under [Unreleased] § Added describing the new rule.

6. Run Validation¶

Invoke the ecosystem-audit skill to verify the new rule, focusing on the rules area:

Invoke the ecosystem-audit skill with --focus rules --fix

Verify no errors reported for your new rule.

Step-by-Step: Adding a New Command¶

Commands are slash commands like /plan-execute, /plan-spec, etc.

1. Determine Role¶

Commands are never meant to be called by the LLM in isolation. They are user-triggered workflows. Ask:

• Is this a workflow the user types /command-name?
• Does it orchestrate multiple steps?
• Could it timeout or require user input mid-execution?

If "no" to any of these, it's probably a skill, not a command.

2. Create File¶

Path: src/apothem/commands/{name}.md

Frontmatter (from docs/artifact-schema.md § Schema: Commands):

---
name: "my-command"
version: "0.1.0"
updated: "2026-04-20"
description: "What this command does"
argument-hint: "[path/to/input] [--flag VALUE]"
disable-model-invocation: true
portability: "universal"
---

Always set disable-model-invocation: true for commands.

3. Write Content¶

Structure:

• Title: # /{name} — Human-Readable Title
• Role section (who executes this)
• High-level instructions
• Workflow section with steps
• Return contract / output format

4. Update CLAUDE.md and CHANGELOG.md¶

Registry row in §7.1 Commands; CHANGELOG row under [Unreleased] § Added.

5. Validate¶

Invoke the ecosystem-audit skill, focusing on commands:

Invoke the ecosystem-audit skill with --focus commands --fix

Step-by-Step: Adding a New Agent¶

Agents are persistent agent definitions for parallel work.

1. Identify Pattern¶

Does this agent fit one of the team patterns from agent-orchestration.md § Team Patterns?

• Research Team: read-only, information gathering
• Audit Team: verification, consistency checks
• Implementation Team: parallel code changes
• Quality Team: lint, test, type-check, security
• Documentation Team: doc updates
• Other: specialized task

2. Create File¶

Path: src/apothem/agents/{name}.md

Frontmatter:

---
name: "my-agent"
version: "0.1.0"
updated: "2026-04-20"
description: "What this agent specializes in"
tools: "Read, Glob, Grep, Bash"
disallowedTools: "Write, Edit"
maxTurns: 15
effort: "high"
permissionMode: "ask"
memory: false
portability: "universal"
---

3. Write Content¶

Sections:

• Operating Principles (read-only, evidence-based, binary verdicts, exhaustive)
• Workflow (numbered steps)
• Return Contract (max tokens, structure, required fields)

4. Update CLAUDE.md and CHANGELOG.md¶

Registry row in §7.3 Agents; CHANGELOG row under [Unreleased] § Added.

5. Test¶

Deploy the agent in a real scenario and verify it works as documented.

Step-by-Step: Adding a New Skill¶

Skills are reusable, detectable techniques.

1. Identify Reusability¶

Before writing a skill:

• Have you seen this problem/technique 3+ times?
• Is it detectable? (Does a user request pattern signal it?)
• Can you codify it reproducibly?

If all three are yes, write a skill.

2. Create Structure¶

%%{ init: { "theme": "neutral" } }%%
%% verified: 2026-04-27 %%
%% provenance: docs/artifact-schema.md (skill artifact schema) %%
%% cross-reference: src/apothem/skills/plan-suite/SKILL.md (canonical example) %%
flowchart TD
    accTitle: New harness adapter directory structure
    accDescr: Top-down flowchart of the canonical directory and file structure for a new apothem harness adapter under src/apothem/harnesses including init, install, uninstall, update, verify modules and the templates subdirectory.
    SKILLS["src/apothem/skills/"]
    SKILLS --> NAME["{skill-name}/"]
    NAME --> SKILLMD["SKILL.md<br/>(main definition · required)"]
    NAME --> EX["examples/<br/>(optional · example workflows)"]
    NAME --> TPL["templates/<br/>(optional · reusable templates)"]

3. Write SKILL.md¶

Frontmatter:

---
name: "skill-name"
version: "0.1.0"
updated: "2026-04-20"
description: "What this skill teaches"
user-invocable: true | false
argument-hint: "[args]"               # if user-invocable
disable-model-invocation: false
portability: "universal"
detection-signals: ["user says X", "user says Y"]  # if user-invocable
---

Content structure:

• Purpose
• When to Use This Skill
• Prerequisites
• Step-by-Step Procedure
• Common Mistakes
• Examples

4. Update CLAUDE.md and CHANGELOG.md¶

Registry row in §7.5 Skills; CHANGELOG row under [Unreleased] § Added.

5. Validate¶

Invoke the ecosystem-audit skill, focusing on skills:

Invoke the ecosystem-audit skill with --focus skills --fix

Validation Checklist Before Committing¶

• Frontmatter passes YAML syntax check
• All mandatory fields present per schema
• name field uses kebab-case
• version is semantic (MAJOR.MINOR.PATCH) and was bumped if behavior changed
• updated matches today's date for any artifact you touched
• portability field set and valid
• CHANGELOG.md [Unreleased] section reflects the change in the appropriate category
• No plan-internal references (CM-7 compliance)
• Cross-references are consistent with other artifacts
• New artifact registered in CLAUDE.md registry
• Artifact tested (if applicable)
• ecosystem-audit skill runs with no errors
• Content follows structural conventions (title format, sections, etc.)

Referencing Other Artifacts¶

Use these exact conventions:

Reference a Rule¶

See `src/apothem/rules/operational-mandates.md` or shorthand: the Operational Mandates rule.
In prose: ... per CM-1–10 (Operational Mandates rule) ...

Reference a Command¶

See `/plan-execute` command. Or: Run `/plan-execute`.
In prose: The `/plan-execute` command handles phase execution.

Reference an Agent¶

Deploy the `codebase-explorer` agent.
In prose: The codebase-explorer agent finds patterns.

Reference a Skill¶

Use the `plan-suite` skill.
In prose: The plan-suite skill provides the Master Plan Suite template.

Reference CLAUDE.md Sections¶

See CLAUDE.md § 7.2 (Rules registry).
Or: Section 4 (Seriousness-Scaled Governance).

Linting and Format¶

All artifacts use:

• Markdown: GFM (GitHub Flavored Markdown)
• YAML: YAML 1.2 compliant
• Line endings: LF (Unix-style)
• Encoding: UTF-8
• Line width: Soft wrap at 100 characters for content (no hard breaks)

Use the Ruff formatter / linter for Python files. For Markdown, use prettier or equivalent.

Ecosystem Audit: Running Validation¶

Two complementary validation surfaces cover the ecosystem:

Machine-checkable (Python validators) — run before every commit:

python scripts/dev/validate_hooks.py       # Hook structure + Python-only hygiene
python scripts/dev/validate_ecosystem.py   # Full tree + frontmatter + delegated hook checks
python scripts/dev/chaos_pass.py           # Adversarial sweep across configured hooks
pytest tests                                    # Unit tests for the hook runtime

LLM-driven — for cross-reference, narrative, and convention audits:

/ecosystem-audit --focus all --fix

This runs in parallel:

• Structure audit: Registry accuracy, file existence, frontmatter validity
• Artifact audit: Cross-references, mandate coverage, pipeline ordering
• Memory audit: Memory file claims vs. filesystem state

Expected output: PASS with zero findings from both surfaces.

If FINDINGS reported:

• Review each finding's severity (Critical / Important / Advisory)
• Address Critical items immediately
• Plan Important items for next cycle
• Consider Advisory items for next iteration

Questions?¶

Refer to:

• Frontmatter schema: docs/artifact-schema.md
• Artifact lifecycle: src/apothem/rules/persistent-conventions-vigilance.md § Artifact Evolution
• Operational mandates: src/apothem/rules/operational-mandates.md CM-1–10
• Plan suite reference: src/apothem/skills/plan-suite/master_template.md
• Release notes: CHANGELOG.md