create-or-update-concepts

Create or Update Concepts

Scan and analyze the project codebase to populate agents-context/concepts/ with concept files that capture project-specific architecture, patterns, and domain knowledge, then keep agents-context/README.md in sync.

Concept files are general guidance, not code dumps. They describe approaches, conventions, and decision rationale so AI agents working on the project have the right context loaded for each task.

Directory layout

Concept files live in three buckets under agents-context/concepts/:

Bucket	Purpose	Example
domains/<domain>/	Business-logic concepts that span multiple source apps	domains/billing/subscription-plans-management.md
source/<app>/	Stack-specific concepts tied to a single source app	source/active_snap/rspec-patterns.md
shared/	True cross-cutting concerns (platform overview, infra, shared DB)	shared/architecture.md

A file's primary owner determines its folder; source_app[] and related[] carry the multi-axis association. Maximum two levels under concepts/ — don't nest deeper.

Frontmatter contract

Every concept file opens with YAML frontmatter:

---
title: "..."                 # quoted; matches H1
source_app: [...]            # array, even if single value
domain: <one-of>             # single value from the approved domain enum
scope: [...]                 # array from the approved scope enum
related: [...]               # other concept basenames (no path, no .md)
load_when:                   # 2–5 plain-language task triggers
  - "..."
status: current              # current | draft | deprecated
last_reviewed: YYYY-MM-DD
---

The frontmatter lets agents and tooling decide whether a concept is relevant without reading the whole file. The contract is: the README's Load-When Cheatsheet points at the file, the frontmatter confirms it's the right one, the body explains how.

agents-context/HOW_TO_CREATE_A_CONCEPT.md is the canonical authoring reference (laid down by /lead-dev-os:configure-project). If it exists in the target project, read it and defer to it when its rules diverge from this skill — it's the project's tuned authoring guide.