Skills and rules

This repository maintains agent behavioural rules and local skills that guide AI agents working in this codebase. They live under .agents/ and are installed via the init command from the canonical source at cmd/assets/.

Agent rules

Located in .agents/RULES.md, the single source of truth for agent behavioural directives.

To add a new rule, load the rules-management skill, it will load existing rules, check for duplicates, and append with the correct format.

Local skills

Local helper skills live under .context/plugins/pantheon-org/<domain>/<skill>/ (managed via
tessl.json, source: file:.context/plugins/...), grouped into four domains:

context-mgmt

• context-file: create .context/ files (plans, findings, analysis, known-issues) with
  standard YAML frontmatter, appropriate sections, and correct placement in plans/,
  findings/, analysis/, or known-issues/. Prompts for the value benefit-of-action
  grade (HIGH/MEDIUM/LOW) on PLAN/FINDING/KNOWN_ISSUE, graded against
  value-rubric.md,
  and the themes subject-area list (ordered, primary-first) drawn from
  theme-vocabulary.md.
• context-index: regenerate .context/index.yaml
  from all .context/**/*.md frontmatter and validate that all files carry the required
  frontmatter block. validate-context-frontmatter.sh requires value and a non-empty
  themes list on PLAN/FINDING/KNOWN_ISSUE while status is DRAFT/ACTIVE/DEFERRED
  (DONE/SUPERSEDED exempt); the index emits effort, severity, value, themes, and
  deferred_until so the “what’s next” read protocol works from the index alone: DRAFT/ACTIVE
  form tier 1 and DEFERRED (real but not actionable yet — date-gated or externally blocked) a
  strict tier 2 below it, and within a tier it sorts by value descending, then effort
  ascending, then themes[0] to break ties. A DEFERRED item whose deferred_until date is
  still in the future is not listed until that date passes. A companion Go check,
  skill-auditor validate context, compiles the JSON schemas and enforces
  additionalProperties:false (catching typo’d/unknown keys the shell script cannot),
  running alongside it; generated remediation plans validate against a dedicated
  remediation-plan.schema.json selected by their skill_name signature.

governance

• adr-capture: capture Architecture Decision Records (ADRs) from .context/ plans,
  findings, and analyses. Extracts binding decisions into docs/ADR/ and maintains the
  machine-readable index. regenerate-adr-index.sh has a --check mode (regenerate in
  memory and diff the committed docs/ADR/index.yaml) so a stale ADR index fails CI,
  not just a missing one. check-undocumented-decisions.sh scans for binding-decision
  headings (## Decision, **Decision:**, Adopt Option) not covered by an ADR, it
  deliberately does not match finding-recommendation headings, since findings recommend
  while plans decide. Heading markers are anchored to line start and code spans/fences are
  stripped before matching, so a doc that merely quotes a marker in prose does not
  false-positive. Also runs post-merge status sync: after a PR merges,
  merge-status-sync.sh detects plans/ADRs left ACTIVE/proposed when the merge should
  have closed them out, auto-flipping single-phase plans and flagging the rest for a human.
  ADR immutability begins at acceptance (ADR-061): a proposed/unmerged ADR may be
  edited in place; once accepted, its body is frozen and only status/superseded_by
  change, otherwise supersede.
• rules-management: manage the agent behavioural rules in .agents/RULES.md, load
  existing rules, check for duplicates, and append new rules in the standard format with
  directive and rationale.

planning

• plan-create: create .context/plans/*.md files with standard frontmatter and
  phases/tasks/waves decomposition, inferring section conventions from existing plans.
  Requires effort (cost), value (benefit), and a themes subject-area list
  (ordered, primary-first) in frontmatter.
• design-debate: stress-test an unwritten idea by spawning independent subagents in
  genuinely opposing roles (advocate, skeptic, migration/risk), grounded in real repo
  investigation, concluding in a synthesized verdict, used before a plan exists. The
  verdict decides how it’s recorded: a finding if proceeding, a known-issue if not.
• plan-review: review a plan using three independent subagent reviewers (Technical,
  Strategic, Risk), consolidate their feedback, then resolve it: editorial fixes land
  directly, genuine tradeoffs go through a one-question-at-a-time interview and are
  recorded in the plan’s ## Decisions section. The Risk and Strategic lenses also
  assess execution-location/coverage: whether a stated invocation path (a hook, a CI
  job, a trigger) actually reaches far enough to meet the plan’s goal (ADR-058).

workshop

• docs-check: validate the GitHub Pages documentation site built by docmd, orphan
  detection, ADR index freshness, build verification, and LLM output audit.
• external-source-fit: assess whether an external GitHub repo, file, or project fits
  this project, mapping overlap against existing capability (D1-D9, validate, duplication,
  eval runner, helper skills), rendering a Good/Partial/No-fit verdict, and writing the
  result up as a house-standard finding. Each finding embeds a machine-readable
  fit-assessment block (assets/templates/ + assets/schemas/) checked by a pure-bash
  validator (scripts/validate-fit-finding.sh) so verdicts stay consistent.
• guided-interview: conduct a structured, one-question-at-a-time interview with
  concrete mutually-exclusive options plus a free-text path, adapting later questions to
  prior answers, ending in a user-confirmed recap.
• pr-author: create and maintain GitHub PRs with live descriptions, template
  discovery, intelligent filling, and lifecycle updates.
• session-reflection: conduct a two-question session-end reflection to catch blind
  spots and under-investigated areas before concluding. Verified-but-deferred gaps become
  .context/known-issues/ entries rather than evaporating in chat.
• socratic-method: refine vague, complex, or high-stakes prompts through Socratic
  dialogue before committing to an implementation.

Registry plugins

Skills installed from the Tessl registry (not authored in this repo) live under
.tessl/plugins/<org>/<skill>/:

• pantheon-ai/markdown-authoring: author high-quality Markdown with deterministic
  structure, lint compliance, and CI integration.
• pantheon-ai/skill-quality-auditor: the registry-distributed copy of this repo’s own
  tile (evaluate, score, and remediate skill collections against the 9-dimension framework).
• pantheon-ai/software-design-principles: apply SOLID principles, detect design
  anti-patterns, and evaluate architectural trade-offs.
• pantheon-ai/research/google-scholar-search: search Google Scholar for academic
  papers and author profiles.
• tessl-labs/eval-setup: generate eval scenarios from repo commits, configure
  multi-agent runs, execute baseline and with-context evals, and compare results.
• tessl-labs/eval-improve: analyse eval results, diagnose failures, apply targeted
  fixes, and re-run to verify improvements.

How skills are installed

The init command installs the canonical skill from cmd/assets/SKILL.md into agent harness directories. The agent registry in agents/registry.go maps each supported agent to its skill install path:

.context/plugins/  → local skills (tessl-managed, file: source)
.claude/skills/    → claude-code

See adding an agent for the full agent list and how to add a new one.