bps-kit 1.0.2 → 1.0.4

package/templates/skills_normal/brainstorming/SKILL.md

@@ -1,163 +1,232 @@
 ---
 name: brainstorming
-description: Socratic questioning protocol + user communication. MANDATORY for complex requests, new features, or unclear requirements. Includes progress reporting and error handling.
-allowed-tools: Read, Glob, Grep
+description: "Use before creative or constructive work (features, architecture, behavior). Transforms vague ideas into validated designs through disciplined reasoning and collaboration."
+risk: unknown
+source: community
+date_added: "2026-02-27"
 ---
 
-# Brainstorming & Communication Protocol
+# Brainstorming Ideas Into Designs
 
-> **MANDATORY:** Use for complex/vague requests, new features, updates.
+## Purpose
+
+Turn raw ideas into **clear, validated designs and specifications**
+through structured dialogue **before any implementation begins**.
+
+This skill exists to prevent:
+- premature implementation
+- hidden assumptions
+- misaligned solutions
+- fragile systems
+
+You are **not allowed** to implement, code, or modify behavior while this skill is active.
+
+---
+
+## Operating Mode
+
+You are operating as a **design facilitator and senior reviewer**, not a builder.
+
+- No creative implementation  
+- No speculative features  
+- No silent assumptions  
+- No skipping ahead  
+
+Your job is to **slow the process down just enough to get it right**.
 
 ---
 
-## 🛑 SOCRATIC GATE (ENFORCEMENT)
+## The Process
 
-### When to Trigger
+### 1️⃣ Understand the Current Context (Mandatory First Step)
 
-| Pattern | Action |
-|---------|--------|
-| "Build/Create/Make [thing]" without details | 🛑 ASK 3 questions |
-| Complex feature or architecture | 🛑 Clarify before implementing |
-| Update/change request | 🛑 Confirm scope |
-| Vague requirements | 🛑 Ask purpose, users, constraints |
+Before asking any questions:
 
-### 🚫 MANDATORY: 3 Questions Before Implementation
+- Review the current project state (if available):
+  - files
+  - documentation
+  - plans
+  - prior decisions
+- Identify what already exists vs. what is proposed
+- Note constraints that appear implicit but unconfirmed
 
-1. **STOP** - Do NOT start coding
-2. **ASK** - Minimum 3 questions:
-   - 🎯 Purpose: What problem are you solving?
-   - 👥 Users: Who will use this?
-   - 📦 Scope: Must-have vs nice-to-have?
-3. **WAIT** - Get response before proceeding
+**Do not design yet.**
 
 ---
 
-## 🧠 Dynamic Question Generation
+### 2️⃣ Understanding the Idea (One Question at a Time)
 
-**⛔ NEVER use static templates.** Read `dynamic-questioning.md` for principles.
+Your goal here is **shared clarity**, not speed.
 
-### Core Principles
+**Rules:**
 
-| Principle | Meaning |
-|-----------|---------|
-| **Questions Reveal Consequences** | Each question connects to an architectural decision |
-| **Context Before Content** | Understand greenfield/feature/refactor/debug context first |
-| **Minimum Viable Questions** | Each question must eliminate implementation paths |
-| **Generate Data, Not Assumptions** | Don't guess—ask with trade-offs |
+- Ask **one question per message**
+- Prefer **multiple-choice questions** when possible
+- Use open-ended questions only when necessary
+- If a topic needs depth, split it into multiple questions
 
-### Question Generation Process
+Focus on understanding:
 
-```
-1. Parse request → Extract domain, features, scale indicators
-2. Identify decision points → Blocking vs. deferable
-3. Generate questions → Priority: P0 (blocking) > P1 (high-leverage) > P2 (nice-to-have)
-4. Format with trade-offs → What, Why, Options, Default
-```
+- purpose  
+- target users  
+- constraints  
+- success criteria  
+- explicit non-goals  
 
-### Question Format (MANDATORY)
+---
+
+### 3️⃣ Non-Functional Requirements (Mandatory)
+
+You MUST explicitly clarify or propose assumptions for:
+
+- Performance expectations  
+- Scale (users, data, traffic)  
+- Security or privacy constraints  
+- Reliability / availability needs  
+- Maintenance and ownership expectations  
+
+If the user is unsure:
+
+- Propose reasonable defaults  
+- Clearly mark them as **assumptions**
+
+---
 
-```markdown
-### [PRIORITY] **[DECISION POINT]**
+### 4️⃣ Understanding Lock (Hard Gate)
 
-**Question:** [Clear question]
+Before proposing **any design**, you MUST pause and do the following:
 
-**Why This Matters:**
-- [Architectural consequence]
-- [Affects: cost/complexity/timeline/scale]
+#### Understanding Summary
+Provide a concise summary (5–7 bullets) covering:
+- What is being built  
+- Why it exists  
+- Who it is for  
+- Key constraints  
+- Explicit non-goals  
 
-**Options:**
-| Option | Pros | Cons | Best For |
-|--------|------|------|----------|
-| A | [+] | [-] | [Use case] |
+#### Assumptions
+List all assumptions explicitly.
 
-**If Not Specified:** [Default + rationale]
-```
+#### Open Questions
+List unresolved questions, if any.
 
-**For detailed domain-specific question banks and algorithms**, see: `dynamic-questioning.md`
+Then ask:
+
+> “Does this accurately reflect your intent?  
+> Please confirm or correct anything before we move to design.”
+
+**Do NOT proceed until explicit confirmation is given.**
+
+---
+
+### 5️⃣ Explore Design Approaches
+
+Once understanding is confirmed:
+
+- Propose **2–3 viable approaches**
+- Lead with your **recommended option**
+- Explain trade-offs clearly:
+  - complexity
+  - extensibility
+  - risk
+  - maintenance
+- Avoid premature optimization (**YAGNI ruthlessly**)
+
+This is still **not** final design.
 
 ---
 
-## Progress Reporting (PRINCIPLE-BASED)
+### 6️⃣ Present the Design (Incrementally)
 
-**PRINCIPLE:** Transparency builds trust. Status must be visible and actionable.
+When presenting the design:
 
-### Status Board Format
+- Break it into sections of **200–300 words max**
+- After each section, ask:
 
-| Agent | Status | Current Task | Progress |
-|-------|--------|--------------|----------|
-| [Agent Name] | ✅🔄⏳❌⚠️ | [Task description] | [% or count] |
+  > “Does this look right so far?”
 
-### Status Icons
+Cover, as relevant:
 
-| Icon | Meaning | Usage |
-|------|---------|-------|
-| ✅ | Completed | Task finished successfully |
-| 🔄 | Running | Currently executing |
-| ⏳ | Waiting | Blocked, waiting for dependency |
-| ❌ | Error | Failed, needs attention |
-| ⚠️ | Warning | Potential issue, not blocking |
+- Architecture  
+- Components  
+- Data flow  
+- Error handling  
+- Edge cases  
+- Testing strategy  
 
 ---
 
-## Error Handling (PRINCIPLE-BASED)
+### 7️⃣ Decision Log (Mandatory)
 
-**PRINCIPLE:** Errors are opportunities for clear communication.
+Maintain a running **Decision Log** throughout the design discussion.
 
-### Error Response Pattern
+For each decision:
+- What was decided  
+- Alternatives considered  
+- Why this option was chosen  
 
-```
-1. Acknowledge the error
-2. Explain what happened (user-friendly)
-3. Offer specific solutions with trade-offs
-4. Ask user to choose or provide alternative
-```
+This log should be preserved for documentation.
 
-### Error Categories
+---
+
+## After the Design
+
+### 📄 Documentation
+
+Once the design is validated:
 
-| Category | Response Strategy |
-|----------|-------------------|
-| **Port Conflict** | Offer alternative port or close existing |
-| **Dependency Missing** | Auto-install or ask permission |
-| **Build Failure** | Show specific error + suggested fix |
-| **Unclear Error** | Ask for specifics: screenshot, console output |
+- Write the final design to a durable, shared format (e.g. Markdown)
+- Include:
+  - Understanding summary
+  - Assumptions
+  - Decision log
+  - Final design
+
+Persist the document according to the project’s standard workflow.
 
 ---
 
-## Completion Message (PRINCIPLE-BASED)
+### 🛠️ Implementation Handoff (Optional)
 
-**PRINCIPLE:** Celebrate success, guide next steps.
+Only after documentation is complete, ask:
 
-### Completion Structure
+> “Ready to set up for implementation?”
 
-```
-1. Success confirmation (celebrate briefly)
-2. Summary of what was done (concrete)
-3. How to verify/test (actionable)
-4. Next steps suggestion (proactive)
-```
+If yes:
+- Create an explicit implementation plan
+- Isolate work if the workflow supports it
+- Proceed incrementally
 
 ---
 
-## Communication Principles
+## Exit Criteria (Hard Stop Conditions)
+
+You may exit brainstorming mode **only when all of the following are true**:
 
-| Principle | Implementation |
-|-----------|----------------|
-| **Concise** | No unnecessary details, get to point |
-| **Visual** | Use emojis (✅🔄⏳❌) for quick scanning |
-| **Specific** | "~2 minutes" not "wait a bit" |
-| **Alternatives** | Offer multiple paths when stuck |
-| **Proactive** | Suggest next step after completion |
+- Understanding Lock has been confirmed  
+- At least one design approach is explicitly accepted  
+- Major assumptions are documented  
+- Key risks are acknowledged  
+- Decision Log is complete  
+
+If any criterion is unmet:
+- Continue refinement  
+- **Do NOT proceed to implementation**
 
 ---
 
-## Anti-Patterns (AVOID)
+## Key Principles (Non-Negotiable)
 
-| Anti-Pattern | Why |
-|--------------|-----|
-| Jumping to solutions before understanding | Wastes time on wrong problem |
-| Assuming requirements without asking | Creates wrong output |
-| Over-engineering first version | Delays value delivery |
-| Ignoring constraints | Creates unusable solutions |
-| "I think" phrases | Uncertainty → Ask instead |
+- One question at a time  
+- Assumptions must be explicit  
+- Explore alternatives  
+- Validate incrementally  
+- Prefer clarity over cleverness  
+- Be willing to go back and clarify  
+- **YAGNI ruthlessly**
 
 ---
+If the design is high-impact, high-risk, or requires elevated confidence, you MUST hand off the finalized design and Decision Log to the `multi-agent-brainstorming` skill before implementation.
+
+## When to Use
+This skill is applicable to execute the workflow or actions described in the overview.

package/templates/skills_normal/clean-code/SKILL.md

@@ -1,201 +1,94 @@
 ---
 name: clean-code
-description: Pragmatic coding standards - concise, direct, no over-engineering, no unnecessary comments
-allowed-tools: Read, Write, Edit
-version: 2.0
-priority: CRITICAL
+description: "Applies principles from Robert C. Martin's 'Clean Code'. Use this skill when writing, reviewing, or refactoring code to ensure high quality, readability, and maintainability. Covers naming, functio..."
+risk: safe
+source: "ClawForge (https://github.com/jackjin1997/ClawForge)"
+date_added: "2026-02-27"
 ---
 
-# Clean Code - Pragmatic AI Coding Standards
-
-> **CRITICAL SKILL** - Be **concise, direct, and solution-focused**.
-
----
-
-## Core Principles
-
-| Principle | Rule |
-|-----------|------|
-| **SRP** | Single Responsibility - each function/class does ONE thing |
-| **DRY** | Don't Repeat Yourself - extract duplicates, reuse |
-| **KISS** | Keep It Simple - simplest solution that works |
-| **YAGNI** | You Aren't Gonna Need It - don't build unused features |
-| **Boy Scout** | Leave code cleaner than you found it |
-
----
-
-## Naming Rules
-
-| Element | Convention |
-|---------|------------|
-| **Variables** | Reveal intent: `userCount` not `n` |
-| **Functions** | Verb + noun: `getUserById()` not `user()` |
-| **Booleans** | Question form: `isActive`, `hasPermission`, `canEdit` |
-| **Constants** | SCREAMING_SNAKE: `MAX_RETRY_COUNT` |
-
-> **Rule:** If you need a comment to explain a name, rename it.
-
----
-
-## Function Rules
-
-| Rule | Description |
-|------|-------------|
-| **Small** | Max 20 lines, ideally 5-10 |
-| **One Thing** | Does one thing, does it well |
-| **One Level** | One level of abstraction per function |
-| **Few Args** | Max 3 arguments, prefer 0-2 |
-| **No Side Effects** | Don't mutate inputs unexpectedly |
-
----
-
-## Code Structure
-
-| Pattern | Apply |
-|---------|-------|
-| **Guard Clauses** | Early returns for edge cases |
-| **Flat > Nested** | Avoid deep nesting (max 2 levels) |
-| **Composition** | Small functions composed together |
-| **Colocation** | Keep related code close |
-
----
-
-## AI Coding Style
-
-| Situation | Action |
-|-----------|--------|
-| User asks for feature | Write it directly |
-| User reports bug | Fix it, don't explain |
-| No clear requirement | Ask, don't assume |
-
----
-
-## Anti-Patterns (DON'T)
-
-| ❌ Pattern | ✅ Fix |
-|-----------|-------|
-| Comment every line | Delete obvious comments |
-| Helper for one-liner | Inline the code |
-| Factory for 2 objects | Direct instantiation |
-| utils.ts with 1 function | Put code where used |
-| "First we import..." | Just write code |
-| Deep nesting | Guard clauses |
-| Magic numbers | Named constants |
-| God functions | Split by responsibility |
-
----
-
-## 🔴 Before Editing ANY File (THINK FIRST!)
-
-**Before changing a file, ask yourself:**
-
-| Question | Why |
-|----------|-----|
-| **What imports this file?** | They might break |
-| **What does this file import?** | Interface changes |
-| **What tests cover this?** | Tests might fail |
-| **Is this a shared component?** | Multiple places affected |
-
-**Quick Check:**
-```
-File to edit: UserService.ts
-└── Who imports this? → UserController.ts, AuthController.ts
-└── Do they need changes too? → Check function signatures
-```
-
-> 🔴 **Rule:** Edit the file + all dependent files in the SAME task.
-> 🔴 **Never leave broken imports or missing updates.**
-
----
-
-## Summary
-
-| Do | Don't |
-|----|-------|
-| Write code directly | Write tutorials |
-| Let code self-document | Add obvious comments |
-| Fix bugs immediately | Explain the fix first |
-| Inline small things | Create unnecessary files |
-| Name things clearly | Use abbreviations |
-| Keep functions small | Write 100+ line functions |
-
-> **Remember: The user wants working code, not a programming lesson.**
-
----
-
-## 🔴 Self-Check Before Completing (MANDATORY)
-
-**Before saying "task complete", verify:**
-
-| Check | Question |
-|-------|----------|
-| ✅ **Goal met?** | Did I do exactly what user asked? |
-| ✅ **Files edited?** | Did I modify all necessary files? |
-| ✅ **Code works?** | Did I test/verify the change? |
-| ✅ **No errors?** | Lint and TypeScript pass? |
-| ✅ **Nothing forgotten?** | Any edge cases missed? |
-
-> 🔴 **Rule:** If ANY check fails, fix it before completing.
-
----
-
-## Verification Scripts (MANDATORY)
-
-> 🔴 **CRITICAL:** Each agent runs ONLY their own skill's scripts after completing work.
-
-### Agent → Script Mapping
-
-| Agent | Script | Command |
-|-------|--------|---------|
-| **frontend-specialist** | UX Audit | `python .agent/skills/frontend-design/scripts/ux_audit.py .` |
-| **frontend-specialist** | A11y Check | `python .agent/skills/frontend-design/scripts/accessibility_checker.py .` |
-| **backend-specialist** | API Validator | `python .agent/skills/api-patterns/scripts/api_validator.py .` |
-| **mobile-developer** | Mobile Audit | `python .agent/skills/mobile-design/scripts/mobile_audit.py .` |
-| **database-architect** | Schema Validate | `python .agent/skills/database-design/scripts/schema_validator.py .` |
-| **security-auditor** | Security Scan | `python .agent/skills/vulnerability-scanner/scripts/security_scan.py .` |
-| **seo-specialist** | SEO Check | `python .agent/skills/seo-fundamentals/scripts/seo_checker.py .` |
-| **seo-specialist** | GEO Check | `python .agent/skills/geo-fundamentals/scripts/geo_checker.py .` |
-| **performance-optimizer** | Lighthouse | `python .agent/skills/performance-profiling/scripts/lighthouse_audit.py <url>` |
-| **test-engineer** | Test Runner | `python .agent/skills/testing-patterns/scripts/test_runner.py .` |
-| **test-engineer** | Playwright | `python .agent/skills/webapp-testing/scripts/playwright_runner.py <url>` |
-| **Any agent** | Lint Check | `python .agent/skills/lint-and-validate/scripts/lint_runner.py .` |
-| **Any agent** | Type Coverage | `python .agent/skills/lint-and-validate/scripts/type_coverage.py .` |
-| **Any agent** | i18n Check | `python .agent/skills/i18n-localization/scripts/i18n_checker.py .` |
-
-> ❌ **WRONG:** `test-engineer` running `ux_audit.py`
-> ✅ **CORRECT:** `frontend-specialist` running `ux_audit.py`
-
----
-
-### 🔴 Script Output Handling (READ → SUMMARIZE → ASK)
-
-**When running a validation script, you MUST:**
-
-1. **Run the script** and capture ALL output
-2. **Parse the output** - identify errors, warnings, and passes
-3. **Summarize to user** in this format:
-
-```markdown
-## Script Results: [script_name.py]
-
-### ❌ Errors Found (X items)
-- [File:Line] Error description 1
-- [File:Line] Error description 2
-
-### ⚠️ Warnings (Y items)
-- [File:Line] Warning description
-
-### ✅ Passed (Z items)
-- Check 1 passed
-- Check 2 passed
-
-**Should I fix the X errors?**
-```
-
-4. **Wait for user confirmation** before fixing
-5. **After fixing** → Re-run script to confirm
-
-> 🔴 **VIOLATION:** Running script and ignoring output = FAILED task.
-> 🔴 **VIOLATION:** Auto-fixing without asking = Not allowed.
-> 🔴 **Rule:** Always READ output → SUMMARIZE → ASK → then fix.
-
+# Clean Code Skill
+
+This skill embodies the principles of "Clean Code" by Robert C. Martin (Uncle Bob). Use it to transform "code that works" into "code that is clean."
+
+## 🧠 Core Philosophy
+> "Code is clean if it can be read, and enhanced by a developer other than its original author." — Grady Booch
+
+## When to Use
+Use this skill when:
+- **Writing new code**: To ensure high quality from the start.
+- **Reviewing Pull Requests**: To provide constructive, principle-based feedback.
+- **Refactoring legacy code**: To identify and remove code smells.
+- **Improving team standards**: To align on industry-standard best practices.
+
+## 1. Meaningful Names
+- **Use Intention-Revealing Names**: `elapsedTimeInDays` instead of `d`.
+- **Avoid Disinformation**: Don't use `accountList` if it's actually a `Map`.
+- **Make Meaningful Distinctions**: Avoid `ProductData` vs `ProductInfo`.
+- **Use Pronounceable/Searchable Names**: Avoid `genymdhms`.
+- **Class Names**: Use nouns (`Customer`, `WikiPage`). Avoid `Manager`, `Data`.
+- **Method Names**: Use verbs (`postPayment`, `deletePage`).
+
+## 2. Functions
+- **Small!**: Functions should be shorter than you think.
+- **Do One Thing**: A function should do only one thing, and do it well.
+- **One Level of Abstraction**: Don't mix high-level business logic with low-level details (like regex).
+- **Descriptive Names**: `isPasswordValid` is better than `check`.
+- **Arguments**: 0 is ideal, 1-2 is okay, 3+ requires a very strong justification.
+- **No Side Effects**: Functions shouldn't secretly change global state.
+
+## 3. Comments
+- **Don't Comment Bad Code—Rewrite It**: Most comments are a sign of failure to express ourselves in code.
+- **Explain Yourself in Code**: 
+  ```python
+  # Check if employee is eligible for full benefits
+  if employee.flags & HOURLY and employee.age > 65:
+  ```
+  vs
+  ```python
+  if employee.isEligibleForFullBenefits():
+  ```
+- **Good Comments**: Legal, Informative (regex intent), Clarification (external libraries), TODOs.
+- **Bad Comments**: Mumbling, Redundant, Misleading, Mandated, Noise, Position Markers.
+
+## 4. Formatting
+- **The Newspaper Metaphor**: High-level concepts at the top, details at the bottom.
+- **Vertical Density**: Related lines should be close to each other.
+- **Distance**: Variables should be declared near their usage.
+- **Indentation**: Essential for structural readability.
+
+## 5. Objects and Data Structures
+- **Data Abstraction**: Hide the implementation behind interfaces.
+- **The Law of Demeter**: A module should not know about the innards of the objects it manipulates. Avoid `a.getB().getC().doSomething()`.
+- **Data Transfer Objects (DTO)**: Classes with public variables and no functions.
+
+## 6. Error Handling
+- **Use Exceptions instead of Return Codes**: Keeps logic clean.
+- **Write Try-Catch-Finally First**: Defines the scope of the operation.
+- **Don't Return Null**: It forces the caller to check for null every time.
+- **Don't Pass Null**: Leads to `NullPointerException`.
+
+## 7. Unit Tests
+- **The Three Laws of TDD**:
+  1. Don't write production code until you have a failing unit test.
+  2. Don't write more of a unit test than is sufficient to fail.
+  3. Don't write more production code than is sufficient to pass the failing test.
+- **F.I.R.S.T. Principles**: Fast, Independent, Repeatable, Self-Validating, Timely.
+
+## 8. Classes
+- **Small!**: Classes should have a single responsibility (SRP).
+- **The Stepdown Rule**: We want the code to read like a top-down narrative.
+
+## 9. Smells and Heuristics
+- **Rigidity**: Hard to change.
+- **Fragility**: Breaks in many places.
+- **Immobility**: Hard to reuse.
+- **Viscosity**: Hard to do the right thing.
+- **Needless Complexity/Repetition**.
+
+## 🛠️ Implementation Checklist
+- [ ] Is this function smaller than 20 lines?
+- [ ] Does this function do exactly one thing?
+- [ ] Are all names searchable and intention-revealing?
+- [ ] Have I avoided comments by making the code clearer?
+- [ ] Am I passing too many arguments?
+- [ ] Is there a failing test for this change?

package/templates/skills_normal/database-design/SKILL.md

@@ -1,7 +1,9 @@
 ---
 name: database-design
-description: Database design principles and decision-making. Schema design, indexing strategy, ORM selection, serverless databases.
-allowed-tools: Read, Write, Edit, Glob, Grep
+description: "Database design principles and decision-making. Schema design, indexing strategy, ORM selection, serverless databases."
+risk: unknown
+source: community
+date_added: "2026-02-27"
 ---
 
 # Database Design
@@ -50,3 +52,6 @@ Before designing schema:
 ❌ Use SELECT * in production
 ❌ Store JSON when structured data is better
 ❌ Ignore N+1 queries
+
+## When to Use
+This skill is applicable to execute the workflow or actions described in the overview.