ai-readiness-assessment

# Project Conventions

These conventions are synced from HARNESS.md. Do not edit this file
directly — run `/convention-sync` to regenerate.

## Stack

- **Primary languages**: Markdown (content), JSON (plugin manifest). No
  programming language is compiled or executed; the plugin's entire
  product is the prose inside the command and skill files.
- **Build system**: None for the plugin artifact — a plugin distribution
  layout (`.claude-plugin/plugin.json` + `commands/` + `skills/`)
  consumed directly by Claude Code, Copilot, Cursor, and Windsurf, with
  no compilation, bundling, or packaging. The one build step is the docs
  site (`mkdocs build --strict`, see CI/CD).
- **Test framework**: TDAB (Test-Driven Agentic Behaviours). The A-tier
  (structural) assertions are automated in `tests/run.py` (stdlib only)
  and CI-enforced on every PR by
  `.github/workflows/agentic-behaviours.yml`. B-tier (behavioural) and
  C-tier (semantic) assertions in each fixture's `expected.md` are run
  manually — see `tests/README.md`.
- **CI/CD**: GitHub Actions. On every PR to a branch-protected `main`,
  four required checks run — `A-tier structural assertions` (the TDAB
  suite, `agentic-behaviours.yml`), `Changelog gate`
  (`changelog-gate.yml`), `Spec-first gate` (`spec-first-gate.yml`) and
  `Onboarding gate` (`onboarding-gate.yml`). On a version bump,
  `release.yml` publishes a GitHub Release from `CHANGELOG.md`; on docs
  changes, `pages.yml` builds and deploys the MkDocs site.
- **Container strategy**: N/A. No runtime, no container.

## Conventions

- **Dual-surface sync**: The framework content embedded in
  `commands/ai-readiness-assess.md` must be identical to the same content
  in `skills/ai-readiness-assessment/SKILL.md`. Editing one without
  updating the other is forbidden.
- **Self-contained**: Neither `commands/ai-readiness-assess.md` nor
  `skills/ai-readiness-assessment/SKILL.md` may reference, invoke, or
  depend on any other plugin, skill, agent, MCP server, or external
  service. The `dependencies` field in `.claude-plugin/plugin.json` must
  remain absent or empty.
- **Single CTA**: The assessment's recommendation output must propose
  exactly one specific TechTalk engagement. Multi-option menus,
  "consider one of…", or "you might want…" lists are forbidden.
- **Frontmatter shape**: Every file in `commands/` and every `SKILL.md`
  under `skills/` must carry YAML frontmatter with `name` and
  `description`. For commands, `name` equals the filename without `.md`;
  for skills, `name` equals the parent directory name.
- **Plain-text output**: The optional rendered output (HTML, printable
  PDF, or other) must use print-friendly typography. No emojis appear in
  any rendering template the skill emits.
- **Spec-first for substantive changes**: Substantive, behaviour-changing
  work (the assessment instrument, the model or scoring, a new workflow)
  is captured as a spec under `specs/` — at minimum a one-paragraph intent
  — written or updated with the change and referenced in the PR. Docs,
  chore, surface-sync, dependency, and pure-fix PRs are exempt. Each spec
  carries a "Risks / what could go wrong" section (a lightweight
  adversarial review). Enforced — see the Spec-first constraint.

## Constraints

### Consistent formatting

- Rule: All source files must pass the project's configured formatter
  without changes
- Enforcement: unverified
- Scope: commit

### Tests must pass

- Rule: The project's test suite must pass with zero failures before any
  code is merged
- Enforcement: deterministic
- Scope: pr

### Dual-surface sync (command ≡ skill)

- Rule: The embedded framework content (the model, the cognitive read,
  the scoring heuristic, and the assessment process) in
  `commands/ai-readiness-assess.md` must match the same content in
  `skills/ai-readiness-assessment/SKILL.md`. Editing one without
  updating the other is forbidden.
- Enforcement: agent
- Scope: pr

### Spec-first

- Rule: A PR that changes the instrument (commands/ or skills/) or the
  model/scoring must reference a spec under `specs/` (a changed
  `specs/NNNN-*.md`), unless labelled chore/fix/docs. Each substantive
  spec carries an adjudicated Adversarial review.
- Enforcement: deterministic (ordering) + agent (review adjudication)
- Scope: pr

### No direct pushes to main

- Rule: All changes must be committed on a feature branch and merged via
  a pull request — direct pushes to `main` are not permitted, including
  for administrators
- Enforcement: deterministic
- Scope: pr

### No secrets in source

- Rule: No API keys, tokens, passwords, or private keys may appear in
  committed source files
- Enforcement: deterministic
- Scope: commit