sepehr/Keep
1
0
Fork 0
Code Issues Pull Requests 1 Actions Packages Projects Releases Wiki Activity

refactor(ux): consolidate BMAD skills, update design system, and clean up Prisma generated client

Browse Source
This commit is contained in:
Sepehr Ramezani
2026-04-19 19:21:27 +02:00
parent 5296c4da2c
commit 25529a24b8
2476 changed files with 127934 additions and 101962 deletions
Download Patch File Download Diff File Expand all files Collapse all files

83
.agent/skills/bmad-agent-builder/references/skill-best-practices.md
View File

@@ -10,11 +10,11 @@ Skills should describe **what to achieve**, not **how to achieve it**. The LLM i
### Outcome vs Prescriptive
| Prescriptive (avoid) | Outcome-based (prefer) |
|---|---|
| "Step 1: Ask about goals. Step 2: Ask about constraints. Step 3: Summarize and confirm." | "Ensure the user's vision is fully captured — goals, constraints, and edge cases — before proceeding." |
| "Load config. Read user_name. Read communication_language. Greet the user by name in their language." | "Load available config and greet the user appropriately." |
| "Create a file. Write the header. Write section 1. Write section 2. Save." | "Produce a report covering X, Y, and Z." |
| Prescriptive (avoid) | Outcome-based (prefer) |
| ----------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------ |
| "Step 1: Ask about goals. Step 2: Ask about constraints. Step 3: Summarize and confirm." | "Ensure the user's vision is fully captured — goals, constraints, and edge cases — before proceeding." |
| "Load config. Read user_name. Read communication_language. Greet the user by name in their language." | "Load available config and greet the user appropriately." |
| "Create a file. Write the header. Write section 1. Write section 2. Save." | "Produce a report covering X, Y, and Z." |
The prescriptive versions miss requirements the author didn't think of. The outcome-based versions let the LLM adapt to the actual situation.
@@ -29,11 +29,11 @@ The prescriptive versions miss requirements the author didn't think of. The outc
Reserve exact steps for **fragile operations** where getting it wrong has consequences — script invocations, exact file paths, specific CLI commands, API calls with precise parameters. These need low freedom because there's one right way to do them.
| Freedom | When | Example |
|---------|------|---------|
| **High** (outcomes) | Multiple valid approaches, LLM judgment adds value | "Ensure the user's requirements are complete" |
| **Medium** (guided) | Preferred approach exists, some variation OK | "Present findings in a structured report with an executive summary" |
| **Low** (exact) | Fragile, one right way, consequences for deviation | `python3 scripts/scan-path-standards.py {skill-path}` |
| Freedom | When | Example |
| ------------------- | -------------------------------------------------- | ------------------------------------------------------------------- |
| **High** (outcomes) | Multiple valid approaches, LLM judgment adds value | "Ensure the user's requirements are complete" |
| **Medium** (guided) | Preferred approach exists, some variation OK | "Present findings in a structured report with an executive summary" |
| **Low** (exact) | Fragile, one right way, consequences for deviation | `uv run ./scripts/scan-path-standards.py {skill-path}` |
## Patterns
@@ -63,10 +63,10 @@ Before finalizing significant artifacts, fan out reviewers with different perspe
Consider whether the skill benefits from multiple execution modes:
| Mode | When | Behavior |
|------|------|----------|
| **Guided** | Default | Conversational discovery with soft gates |
| **Yolo** | "just draft it" | Ingest everything, draft complete artifact, then refine |
| Mode | When | Behavior |
| ------------ | ------------------- | ------------------------------------------------------------- |
| **Guided** | Default | Conversational discovery with soft gates |
| **Yolo** | "just draft it" | Ingest everything, draft complete artifact, then refine |
| **Headless** | `--headless` / `-H` | Complete the task without user input, using sensible defaults |
Not all skills need all three. But considering them during design prevents locking into a single interaction model.
@@ -90,16 +90,51 @@ For complex tasks with consequences: plan → validate → execute → verify. C
## Anti-Patterns
| Anti-Pattern | Fix |
|---|---|
| Numbered steps for things the LLM would figure out | Describe the outcome and why it matters |
| Explaining how to load config (the mechanic) | List the config keys and their defaults (the outcome) |
| Prescribing exact greeting/menu format | "Greet the user and present capabilities" |
| Spelling out headless mode in detail | "If headless, complete without user input" |
| Too many options upfront | One default with escape hatch |
| Deep reference nesting (A→B→C) | Keep references 1 level from SKILL.md |
| Inconsistent terminology | Choose one term per concept |
| Scripts that classify meaning via regex | Intelligence belongs in prompts, not scripts |
| Anti-Pattern | Fix |
| -------------------------------------------------- | ----------------------------------------------------- |
| Numbered steps for things the LLM would figure out | Describe the outcome and why it matters |
| Explaining how to load config (the mechanic) | List the config keys and their defaults (the outcome) |
| Prescribing exact greeting/menu format | "Greet the user and present capabilities" |
| Spelling out headless mode in detail | "If headless, complete without user input" |
| Too many options upfront | One default with escape hatch |
| Deep reference nesting (A→B→C) | Keep references 1 level from SKILL.md |
| Inconsistent terminology | Choose one term per concept |
| Scripts that classify meaning via regex | Intelligence belongs in prompts, not scripts |
## Bootloader SKILL.md (Memory Agents)
Memory agents use a lean bootloader SKILL.md that carries ONLY the essential DNA. Everything else lives in the sanctum (loaded on rebirth) or references (loaded on demand).
**What belongs in the bootloader (~30 lines of content):**
- Identity seed (2-3 sentences of personality DNA)
- The Three Laws
- Sacred Truth
- Species-level mission
- Activation routing (3 paths: no sanctum, headless, rebirth)
- Sanctum location
**What does NOT belong in the bootloader:**
- Communication style (goes in PERSONA-template.md)
- Detailed principles (go in CREED-template.md)
- Capability menus/tables (go in CAPABILITIES-template.md, auto-generated by init script)
- Session close behavior (emerges from persona)
- Overview section (the bootloader IS the overview)
- Extensive activation instructions (the three paths are enough)
**The test:** If the bootloader is over 40 lines of content, something belongs in a sanctum template instead.
## Capability Prompts for Memory Agents
Memory agent capability prompts follow the same outcome-focused philosophy but include memory integration. The pattern:
- **What Success Looks Like** — the outcome, not the process
- **Your Approach** — philosophy and principles, not step-by-step. Reference technique libraries if they exist.
- **Memory Integration** — how to use MEMORY.md and BOND.md to personalize the interaction. Surface past work, reference preferences.
- **After the Session** — what to capture in the session log. What patterns to note for BOND.md. What to flag for PULSE curation.
Stateless agent prompts omit Memory Integration and After the Session sections.
When a capability has substantial domain knowledge (frameworks, methodologies, technique catalogs), separate it into a lean capability prompt + a technique library loaded on demand. This keeps prompts focused while making deep knowledge available.
## Scripts in Skills