concept-skills

Give functionality boundaries. Make coordination visible.

Adding a share feature can touch posting, authorization, and notification code. When the connections are scattered, the effects of a change are hard to see.

concept-design supports software design and AI coding with Daniel Jackson’s concepts and synchronizations. Start from a user’s need, define independent modules and explicit coordination rules, then use them for specifications, implementation, review, and Mermaid maps. Adapts ideas from WYSIWID (Meng & Jackson, MIT).

🧩 How it works

• Concepts provide independent functionality with their own state and actions; concepts do not call one another or read one another’s state.
• Synchronizations make coordination explicit: what happened, which conditions hold, and which actions follow.
• LLMs and the CLI have separate roles: an LLM generates or changes code from specifications, the CLI checks specification structure, and review and tests check behavior.

For example: comment created → query the post’s author → send a notification. The synchronization holds the coordination; Comment need not depend on Notification.

✨ What it helps with

Locate functionality, change concepts independently, and read coordination rules directly. Before adding a feature, consider reusing concepts or changing a few synchronizations, then check that existing behavior is preserved. The goal is more modular, transparent, and understandable software. See the MIT report for background. See sources for theory and local choices.

Get started

From this repository, install one language edition:

npx --yes skills add . --skill concept-design --agent codex --copy --yes
npx --yes skills add . --skill concept-design-cn --agent codex --copy --yes

Invoke explicitly; only the workflow needed for the task is read:

$concept-design design Define concepts and synchronizations for reservations.
$concept-design build Implement the confirmed specifications.
$concept-design review src/orders Inspect concept boundaries and code, read-only.
$concept-design guard map src Generate a concept and synchronization diagram.

Also supports settle, prd, guard, refine, and explain; Chinese uses $concept-design-cn.

What concept-lint checks

Read-only, with no third-party dependencies. Checks the skill’s local CONCEPT/SYNCS notation:

python3 skills/en/concept-design/scripts/concept_lint.py CONCEPT.md SYNCS.md --json

Checks declarations and core sections, when/then completion and invocation shapes, top-level named fields, and rule-name uniqueness for each app across the supplied files.