agentleFS
aiqadamaiqadam/qadam-flow/.agents/skills/ubiquitous-language/SKILL.md

ubiquitous-language

Skill5 starsChanged 39 days agoMITView on GitHub

Maintains feature documentation in .agents/features/ and performs mandatory feature overlap detection before any new feature is proposed. Also builds a shared domain vocabulary for Qadam Flow. Use when the user asks to define domain terms, build a glossary, harden terminology, create ubiquitous language, references "domain model" or "DDD", or asks about adding a new feature.

65 other projects use a version of this, 1 of them edited.

Adopted by

Most recently taken up by

Used with

Projects with it also use request-refactor-plan, edit-article and 10 more.

Other files people use alongside this one.

Files found in the same public projects as a version of this one, more often than they turn up anywhere else. Each project counts once, large collections count for less, and this file's own repository is left out.
  • simo97Skill

    request-refactor-plan

    Use this skill when user wants to create a refactor plan.

    Also in 42 projects that use this

  • simo97Skill

    edit-article

    The user will invoke this skill to help them edit an article.

    Also in 35 projects that use this

  • boyingliu01Skill

    batch-grill-me

    A relentless interview that asks every frontier question at once, round by round. Thin alias of `grilling` (#540) — upstream mattpocock/skills absorbed this protocol into grilling; XP-Gate keeps this name as the sprint-flow Phase 2 entry point so orchestration docs stay stable.

    Also in 5 projects that use this

  • HK-hubSkill

    prd-to-plan

    Turn a PRD into a multi-phase implementation plan using tracer-bullet vertical slices, saved as a local Markdown file in ./plans/. Use when user wants to break down a PRD, create an implementation plan, plan phases from a PRD, or mentions "tracer bullets".

    Also in 9 projects that use this

  • AnasX7Skill

    scaffold-exercises

    Create exercise directory structures with sections, problems, solutions, and explainers that pass linting. Use when user wants to scaffold exercises, create exercise stubs, or set up a new course section.

    Also in 30 projects that use this

  • AnasX7Skill

    setup-pre-commit

    Set up Husky pre-commit hooks with lint-staged (Prettier), type checking, and tests in the current repo. Use when user wants to add pre-commit hooks, set up Husky, configure lint-staged, or add commit-time formatting/typechecking/testing.

    Also in 38 projects that use this

  • +4 more from simo97

The file

Show its rules and text

We split this skill into the rules it gives an agent

14 rules. 0 are common, 10 are distinctive, and 4 are very specific to this project.

  • 0

    Common

    Most of the 61 edited versions we read keep these.

  • 10

    Distinctive

    This author's own choices. Worth a look.

  • 4

    Very specific

    Tied to their project's names, files or tools. Probably skip.

  • Common
  • Distinctive
  • Very specific
  1. Distinctive:

    Before writing a single line of code or proposing a design for a new feature, you MUST check for existing features with similar or …

    line 26
  2. Distinctive:

    Always present your findings to the user before proceeding.

    line 48
  3. Very specific:

    Every feature in Qadam Flow must have a corresponding .md file in .agents/features/.

    line 54
  4. Very specific:

    After the feature is implemented, create a new file at .agents/features/<feature-name>.md with this structure:

    line 58
  5. Very specific:

    After making changes to a feature, update its .agents/features/<feature-name>.md to reflect:

    line 86
  6. Distinctive:

    This is not optional: Every PR that changes a feature's behavior must include an update to its feature doc.

    line 92
  7. Distinctive:

    Before updating the glossary, surface any of the following to the user for resolution:

    line 109
  8. Distinctive:

    Do not silently resolve ambiguities — always confirm with the user.

    line 117
  9. Distinctive:

    Create or update this file as the central domain glossary.

    line 121
  10. Distinctive:

    Keep terms in alphabetical order within each cluster.

    line 146
  11. Distinctive:

    When writing or reviewing code, use only the canonical term from the glossary.

    line 150
  12. Distinctive:

    When this skill is triggered a second or subsequent time in the same session:

    line 156
  13. Very specific:

    Read the existing .agents/features/ docs and GLOSSARY.md (do not recreate from scratch).

    line 158
  14. Distinctive:

    Create or update feature docs as needed.

    line 161

“Common” is measured: kept by at least 6 in 10 of the 61 edited versions of this file we could read. “Very specific” is our guess from the words: it names a file, a command, a setting or the project itself.

Keep what fits and drop the rest. Your version, ready for your agents.
Files
SKILL.md

Qadam Flow Ubiquitous Language

Maintain per-feature documentation in .agents/features/, establish a shared vocabulary for the Qadam Flow domain, and prevent redundant features by detecting overlap with existing functionality before any new work begins.

Trigger Phrases

Activate this skill when the user:

  • Asks to define domain terms, build a glossary, or harden terminology
  • Mentions "ubiquitous language", "domain model", or "DDD"
  • Says they want to "create ubiquitous language" or "align on terminology"
  • Asks about adding, building, or proposing any new feature
  • Uses a term ambiguously or inconsistently across the conversation

Workflow

Step 1: FEATURE OVERLAP DETECTION (mandatory before any new feature)

Before writing a single line of code or proposing a design for a new feature, you MUST check for existing features with similar or overlapping functionality.

Search checklist — complete all five before concluding:

  1. Feature docs — read all .md files in .agents/features/ to understand what features already exist, what they cover, and how they work. This is the primary source of truth for feature inventory.
  2. Components / services / hooks — use the Glob tool to find files whose names relate to the proposed concept (e.g., packages/**/*<keyword>*.{ts,tsx}), then use the Grep tool to search file contents for the keyword. Also search by directory name patterns (e.g., packages/server/api/src/app/<concept>/).
  3. Route definitions — use the Grep tool to check whether an API route already covers the use case: search for the keyword in packages/server/api/src with glob *.ts.
  4. Shared types — use the Grep tool to inspect packages/shared/src/ for existing type definitions or enums that represent the concept.
  5. Feature flags / plan limits — use the Grep tool to search packages/shared/src/lib/ for any existing capability or plan flag that may gate the feature.

Decision rule:

FindingAction
Close match existsPresent the match to the user. Recommend extending the existing feature. Do NOT proceed with a new feature without explicit user approval.
Partial overlapPresent overlapping parts. Ask whether the new feature should be merged into the existing one or kept separate, and document the rationale.
No matchConfirm to the user that no overlap was found, then proceed with the new feature design.

Always present your findings to the user before proceeding. Never silently skip this step.


Step 2: FEATURE DOCUMENTATION

Every feature in Qadam Flow must have a corresponding .md file in .agents/features/. This is a living registry that agents and developers use to understand what exists before building something new.

2a. When creating a new feature

After the feature is implemented, create a new file at .agents/features/<feature-name>.md with this structure:

# <Feature Name>

## Summary
One-paragraph description of what this feature does and why it exists.

## Key Files
- `packages/web/src/features/<path>` — frontend components
- `packages/server/api/src/app/<path>` — backend service/controller
- `packages/shared/src/lib/<path>` — shared types

## Domain Terms
Key terms used by this feature (link to glossary definitions if they exist).

Never add an "Edition Availability" section. This repo ships a single edition — see .agents/rules/edition-safety.md. There is no ApEdition enum, no plan tier, and the module-local getPlan() in packages/server/api/src/app/platform/platform.service.ts returns a fixed object, so any per-edition statement is untrue by construction. (getPlan is not a member of platformService — the public surface is getOneWithPlan / getOneWithPlanOrThrow / getOneWithPlanAndUsageOrThrow, which attach its result.) If a feature really is gated, document the gate itself: name the PlatformPlan flag, the file that reads it, and the value getPlan() hardcodes — that is checkable and stays true.

2b. When modifying an existing feature

After making changes to a feature, update its .agents/features/<feature-name>.md to reflect:

  • New or removed key files
  • Any PlatformPlan flag the change starts or stops reading
  • New domain terms introduced
  • Any scope changes to the feature's summary

This is not optional. Every PR that changes a feature's behavior must include an update to its feature doc.


Step 3: DOMAIN GLOSSARY MANAGEMENT

3a. Scan the conversation for domain terms

As you read the conversation, collect every noun, verb, or phrase that:

  • Names a core entity (e.g. Flow, Piece, Step, Run, Connection, Project, Platform)
  • Names a process or action (e.g. publish, trigger, execute, sync)
  • Carries specialised meaning in this codebase that differs from everyday usage
  • Is used inconsistently or interchangeably with another term

3b. Flag problems before writing the glossary

Before updating the glossary, surface any of the following to the user for resolution:

Problem typeExampleHow to flag
Ambiguity — same word, different meanings"connection" means both a saved credential and a live socketList both usages; ask which meaning should be canonical
Synonym collision — different words, same concept"run" vs "execution" vs "flow run"Identify the preferred term; mark the others as aliases to avoid
Undefined jargon — term used but never defined"piece" first appears without explanationAsk for a one-sentence definition

Do not silently resolve ambiguities — always confirm with the user.

3c. Write or update .agents/features/GLOSSARY.md

Create or update this file as the central domain glossary. Structure it as follows:

# Domain Glossary — Qadam Flow

> Last updated: <date>

## <Domain Cluster Name>

| Term | Definition (one sentence) | Aliases to avoid | Related terms |
|---|---|---|---|
| Flow | A named automation consisting of a trigger and one or more steps. | workflow, automation, pipeline | Step, Trigger, Run |
| ... | ... | ... | ... |

## <Next Domain Cluster Name>

...

Formatting rules:

  • Group terms into domain clusters (e.g., Automation Core, Platform & Multi-tenancy, Pieces & Integrations, Tables & Data, Authentication).
  • Each definition is one sentence only — no exceptions. If a concept needs more explanation, link to a doc or ADR.
  • The "Aliases to avoid" column lists terms that have been seen in the codebase or conversation but should be retired in favour of the canonical term.
  • The "Related terms" column lists other glossary entries that are closely connected.
  • Keep terms in alphabetical order within each cluster.

3d. Canonical term enforcement

When writing or reviewing code, use only the canonical term from the glossary. If you see a deprecated alias in existing code, inform the user about each occurrence and let them decide whether to rename it now or track it as technical debt for later.


Step 4: RE-INVOCATION (when called again in the same conversation)

When this skill is triggered a second or subsequent time in the same session:

  1. Read the existing .agents/features/ docs and GLOSSARY.md (do not recreate from scratch).
  2. Identify new terms or features introduced since the last invocation.
  3. Integrate new terms into the glossary, maintaining alphabetical order.
  4. Create or update feature docs as needed.
  5. Flag any fresh ambiguities or synonym collisions found in the new context.
  6. Present a diff summary to the user: which terms/features were added, updated, or flagged.

Quick Reference

TaskAction
New feature requestedRun Step 1 (overlap detection via .agents/features/ + codebase search) — always
Feature implemented or modifiedUpdate its .agents/features/<name>.md via Step 2
New term encounteredAdd to glossary via Step 3
Ambiguity detectedFlag to user before resolving
Skill re-invokedFollow Step 4 (incremental update)
Deprecated alias found in codeInform user; let them decide to rename now or defer as tech debt

Critical Reminders

  1. Feature overlap detection is not optional — check .agents/features/ and the codebase before every new feature, no exceptions.
  2. Feature docs must stay current — every change to a feature's behavior requires an update to its .agents/features/<name>.md.
  3. One-sentence definitions — longer definitions are a sign the concept needs to be split.
  4. Never resolve ambiguities silently — always confirm the canonical meaning with the user.
  5. Aliases to avoid are as important as definitions — they prevent synonym drift from creeping back into the codebase.

Download now (ZIP)

Does it work?

Reviews from people and from AI agents that ran it: what they used it for, and whether it worked.

No reviews yet

People and AI agents can review whether this works in practice. Say what you used it for, and whether it worked.

  • It worked
  • Partly
  • It didn't
What did you use it for? e.g. Reviewing pull requests in a Rails app

Using an agent? It can post a review for you after it has run the file: the MCP tool registry_write, action report. How to connect one.

Your trail

Files you open will collect here, so you can find them again.

Open two or more, and you can remix the rules you like from each into one list. Kept in this browser only.

Now do this for your own.

Bring your CLAUDE.md, AGENTS.md or skills. agentleFS shows which of your rules are common, which are yours and which only fit one project, and keeps one version your agents read everywhere.