kenmark-skills 1.0.0

package/skills/user-skills/init-brain/SKILL.md

@@ -0,0 +1,425 @@
+---
+name: init-brain
+description: |
+  Initialize brain/ and optionally sync project standards to agent config files
+  (CLAUDE.md, AGENTS.md, .cursorrules, .cursor/rules/, GEMINI.md) after asking
+  which targets the user wants. Use when applying workspace rules, creating/updating
+  project rules, initializing project standards, or enforcing team conventions.
+allowed-tools:
+  - Bash
+  - Read
+  - Write
+  - Edit
+  - Grep
+  - Glob
+  - AskUserQuestion
+triggers:
+  - init brain
+  - initialize brain
+  - apply workspace rules
+  - project standards
+  - setup cursor rules
+  - init-brain
+  - init-brain skill
+---
+
+# Init Brain Skill
+
+Bootstrap the project **brain** knowledge base, then **ask the user** which agent config files to create or update. Do not create every file by default.
+
+**Source of truth:** `brain/rules/standards.md`. Only the agent files the user selects are synced from that file.
+
+## Optional sync targets (user picks)
+
+| ID | Tool | File(s) | Role |
+| --- | --- | --- | --- |
+| `claude` | Claude Code | `CLAUDE.md` | Primary project instructions |
+| `codex` | Codex / OpenAI agents | `AGENTS.md` | Harnesses that read `AGENTS.md` |
+| `cursor-mdc` | Cursor (current) | `.cursor/rules/project-standards.mdc` | Always-on rule with frontmatter |
+| `cursor-legacy` | Cursor (legacy) | `.cursorrules` | Root rules file in older setups |
+| `gemini` | Gemini CLI | `GEMINI.md` | Gemini CLI project instructions |
+
+The user may select **one, several, or none**. If they select none, stop after Step 1 (brain only).
+
+---
+
+## Step 0 — Resolve repo root
+
+```bash
+REPO_ROOT="$(git rev-parse --show-toplevel 2>/dev/null || pwd)"
+cd "$REPO_ROOT"
+echo "REPO_ROOT=$REPO_ROOT"
+```
+
+Before writing, read only the agent files the user selected (if they already exist). Preserve content **outside** the `init-brain` merge markers.
+
+---
+
+## Step 1 — Create brain scaffold
+
+```bash
+mkdir -p brain/rules brain/issues/completed temp
+touch temp/.gitkeep
+```
+
+### `brain/INDEX.md`
+
+Create or refresh:
+
+```markdown
+# Brain Index
+
+Project knowledge base for humans and AI agents.
+
+| Path | Purpose |
+| --- | --- |
+| [rules/standards.md](rules/standards.md) | Canonical coding & workflow standards (synced to agent files) |
+| [CHANGELOG.md](CHANGELOG.md) | Versioned log of brain and standards changes |
+| [issues/INDEX.md](issues/INDEX.md) | Active/completed issue tracker (optional; use `issues-setup` skill) |
+
+## Maintenance
+
+- Update `brain/` after every meaningful code change.
+- After changing `brain/rules/standards.md`, re-run **init-brain** and choose which agent files to sync.
+- Never delete the `brain/` folder.
+```
+
+### `brain/rules/standards.md`
+
+Write the **full standards body** (see [Canonical standards content](#canonical-standards-content) below). This is the only place to edit rule bullets long-term.
+
+### `brain/CHANGELOG.md`
+
+If missing, create with a header `# CHANGELOG`. Append a new version entry (see Step 5).
+
+### `temp/`
+
+Ensure `temp/` exists for scratch scripts and downloads. Add to `.gitignore` if not already present:
+
+```gitignore
+# init-brain
+/temp/
+```
+
+---
+
+## Step 2 — Ask which agent files to sync (required)
+
+**Do not create or update any agent config file until the user chooses.**
+
+### When to skip the question
+
+Skip only if the user already named targets in the same request, for example:
+
+- "init brain for Claude and Cursor" → `claude` + `cursor-mdc` (add `cursor-legacy` only if they ask)
+- "brain only" / "just the brain folder" → **none** (Step 1 only)
+- "sync AGENTS.md" → `codex` only
+
+### When to ask
+
+If targets are unclear, use **AskUserQuestion** with `allow_multiple: true`:
+
+| Option ID | Label |
+| --- | --- |
+| `claude` | Claude Code — `CLAUDE.md` |
+| `codex` | Codex / agents — `AGENTS.md` |
+| `cursor-mdc` | Cursor — `.cursor/rules/project-standards.mdc` (recommended) |
+| `cursor-legacy` | Cursor legacy — `.cursorrules` |
+| `gemini` | Gemini CLI — `GEMINI.md` |
+
+If AskUserQuestion is unavailable, ask in chat with the same options and wait for a reply.
+
+### After selection
+
+- Record the chosen IDs (e.g. `claude`, `cursor-mdc`).
+- If the user selects **no** agent files, skip Step 3 and go to Step 4 (verify brain only) and Step 5 (changelog).
+- If the user selects both `claude` and `codex`, keep those two files in parity when syncing.
+
+---
+
+## Step 3 — Sync selected agent files (merge markers)
+
+**Only process targets chosen in Step 2.**
+
+Use **identical rule prose** inside each selected file, wrapped in merge markers so re-runs are safe:
+
+```html
+<!-- init-brain:START -->
+... synced standards markdown ...
+<!-- init-brain:END -->
+```
+
+If a file exists but has **no** markers, insert the block after any existing custom preamble (do not delete user content above the markers). If the user has heavily customized agent files, ask before replacing unmarked content.
+
+### `CLAUDE.md` — if `claude` selected
+
+Create or update. Structure:
+
+```markdown
+# Claude Code — Project Instructions
+
+Standards below are synced from `brain/rules/standards.md`. Edit the brain file, then re-run **init-brain**.
+
+- Brain index: [brain/INDEX.md](brain/INDEX.md)
+- Changelog: [brain/CHANGELOG.md](brain/CHANGELOG.md)
+
+<!-- init-brain:START -->
+
+# Project Standards
+
+(paste full content from brain/rules/standards.md)
+
+<!-- init-brain:END -->
+```
+
+### `AGENTS.md` — if `codex` selected
+
+Create or update with the **same** `init-brain` block as `CLAUDE.md` when both are selected, plus a one-line header:
+
+```markdown
+# Agent Instructions (Codex & compatible harnesses)
+
+Synced from `brain/rules/standards.md`. Keep in parity with `CLAUDE.md`.
+
+<!-- init-brain:START -->
+(same body as CLAUDE.md block)
+<!-- init-brain:END -->
+```
+
+When both `claude` and `codex` are selected, use the same standards body in both files.
+
+### `.cursor/rules/project-standards.mdc` — if `cursor-mdc` selected
+
+Create directory and file:
+
+```markdown
+---
+description: Project standards synced from brain/rules/standards.md
+alwaysApply: true
+---
+
+<!-- init-brain:START -->
+
+# Project Standards
+
+(paste full content from brain/rules/standards.md)
+
+<!-- init-brain:END -->
+```
+
+Cursor loads `.mdc` rules from `.cursor/rules/`; `alwaysApply: true` applies standards in every session.
+
+### `.cursorrules` — if `cursor-legacy` selected
+
+Create or update at repo root for older Cursor setups:
+
+```markdown
+# Cursor rules (legacy path — prefer .cursor/rules/project-standards.mdc)
+
+Synced from brain/rules/standards.md. Re-run init-brain after editing standards.
+
+<!-- init-brain:START -->
+
+(paste full content from brain/rules/standards.md)
+
+<!-- init-brain:END -->
+```
+
+### `GEMINI.md` — if `gemini` selected
+
+Mirror the same `init-brain` block with header `# Gemini CLI — Project Instructions`.
+
+---
+
+## Step 4 — Verify
+
+```bash
+# Brain scaffold (always)
+test -f brain/rules/standards.md && test -f brain/INDEX.md && echo "brain ok"
+```
+
+For each **selected** target, confirm `init-brain:START` exists in that file (e.g. `grep -l "init-brain:START" CLAUDE.md`).
+
+Report to the user:
+
+- Brain paths created vs updated
+- **Which agent files were synced** (list only selected targets)
+- Skipped targets (not chosen)
+- Whether `brain/issues/` was left untouched or created empty
+- Reminder: edit `brain/rules/standards.md`, re-run init-brain, and pick files to sync again
+
+---
+
+## Step 5 — Idempotency rules
+
+- **Re-runnable:** Safe to run multiple times; only replace content between `init-brain:START` / `init-brain:END` in **selected** files.
+- **Do not** create agent files the user did not select.
+- **Do not** remove user sections outside markers in agent config files.
+- **Do not** delete `brain/` or issue files under `brain/issues/`.
+- If `brain/rules/standards.md` already exists and differs from the skill default, **keep the repo file** unless the user asks to reset standards; still re-sync only the selected agent files from disk.
+- On re-run, **ask again** which files to sync unless the user specified targets in the request.
+
+---
+
+## Step 6 — Changelog entry
+
+Append to `brain/CHANGELOG.md`:
+
+```markdown
+## vYYYY.MM.DD-HHMM-init-brain
+- Initialized or refreshed brain/ scaffold (INDEX, rules/standards.md).
+- Synced standards to: <comma-separated list of selected files, or "none (brain only)">.
+```
+
+Use local timestamp in the version id.
+
+---
+
+## Canonical standards content
+
+When creating **new** `brain/rules/standards.md` (file does not exist yet), write the following sections exactly. When the file already exists, skip this block and sync from disk.
+
+### Model Preferences
+
+- For "Diagnose & Fix" requests, use Sequential Thinking MCP for thorough analysis
+- Prefer comprehensive analysis over quick fixes for complex issues
+
+### Parallel Processing & Sub-Agents
+
+- Use sub-agents and parallel processing whenever possible to split work and improve efficiency
+- Break down complex tasks into independent subtasks that can be executed concurrently
+- Leverage multiple tool calls simultaneously when tasks don't have dependencies
+- Use parallel file operations (reading, writing, searching) to reduce overall execution time
+- Deploy sub-agents for independent analysis, testing, and validation tasks
+- Coordinate multiple agents for different aspects of the same project (frontend, backend, testing, documentation)
+
+### Implementation Standards
+
+- Always provide complete, production-ready implementations instead of mock data or placeholder code
+- When implementing features, include proper error handling, validation, and edge cases
+- Use real data structures and realistic examples rather than "TODO" comments or mock responses
+- Implement full functionality with proper integration points, not just stubs
+- Include comprehensive logging, monitoring, and debugging capabilities in implementations
+
+### Bug Detection & Analysis
+
+- Always perform comprehensive code analysis to identify potential bugs, security vulnerabilities, and performance issues
+- Check for common programming pitfalls: null/undefined references, memory leaks, race conditions, and resource disposal
+- Analyze error handling coverage and identify unhandled exception scenarios
+- Review code for potential security issues: injection attacks, authentication bypasses, and data exposure
+- Examine performance bottlenecks, inefficient algorithms, and resource usage patterns
+- Validate input/output data flow and identify potential data corruption points
+- Check for proper cleanup of resources (files, connections, memory) and disposal patterns
+- Analyze concurrent code for thread safety and synchronization issues
+
+### Project Structure
+
+- New project files should reside in the root directory, not in a subfolder named 'app'
+- All code edits must pull previous data to avoid data loss
+- Create a `/temp` folder for temporary scripts, testing, downloads (ignored by git)
+- Never delete the `/brain` folder - it contains the project knowledge base
+- Keep `/brain` folder numbered and indexed with small, focused markdown files
+- Update brain/ after every code change
+
+### Development Workflow
+
+- For tasks affecting multiple files, create a todo list before making changes
+- When fixing specific sections/files, only make changes to that particular section
+- Check with user before making additional changes beyond the requested scope
+- Before running apps, check if already running and reuse the same instance
+- If port conflicts, kill the existing process rather than using new ports
+
+### Testing & Validation
+
+- Use Playwright MCP screenshot utility to cross-check UI changes (for web applications)
+- Test on Desktop, Tablet, and Mobile by default unless specified otherwise (for UI applications)
+- Use headless browsers for testing unless specified otherwise (for web applications)
+- Use Vision Enabled Models for compatibility with Playwright MCP Screenshot Tool
+- For non-UI applications, focus on unit tests, integration tests, and API testing
+
+### Package Management
+
+- Always use pnpm over npm (for Node.js projects)
+- For other package managers, use the appropriate tool (pip, cargo, go mod, etc.)
+- For new frameworks/packages, get latest documentation using context 7 MCP
+- Use curl with timeout to prevent hanging
+
+### Data & Knowledge Management
+
+- For "Update Brain" requests, update the knowledge base in `/brain` folder
+- Write all planned fixes, bugs, and changelog entries to `CHANGELOG.md` in `/brain` folder
+- Version every change in CHANGELOG.md to make them unique
+- For web scraping tasks, use Bright Data MCP
+
+### Documentation
+
+- Update CHANGELOG.md in brain folder for all fixes, bugs, and changes
+- Version each change uniquely
+- Keep knowledge base in `/brain` folder numbered and indexed
+
+### Performance Optimization
+
+- Choose optimal algorithms and data structures for the specific use case
+- Implement performance profiling and monitoring in applications
+- Optimize database queries, API calls, and network operations
+- Use efficient serialization/deserialization methods
+- Implement proper indexing and search optimization
+- Profile memory usage and optimize garbage collection patterns
+- Use appropriate design patterns that improve both maintainability and performance
+
+### Caching & Resource Management
+
+- Implement smart caching strategies to avoid redundant operations and computations
+- Use connection pooling and resource reuse patterns for databases and external services
+- Implement lazy loading for non-critical resources and components
+- Cache frequently accessed data, computation results, and configuration settings
+- Optimize memory usage with proper cleanup, disposal patterns, and resource management
+- Use appropriate caching layers (in-memory, disk, distributed) based on access patterns
+- Implement cache invalidation strategies and TTL (Time To Live) policies
+
+### Incremental Operations
+
+- Only process changed files, components, and data instead of entire codebases
+- Use diff-based updates instead of full rebuilds and redeployments
+- Implement incremental compilation, building, and testing
+- Track file modification times and dependencies to avoid unnecessary reprocessing
+- Use smart dependency resolution to minimize rebuild and deployment scope
+- Implement change detection mechanisms for efficient updates
+- Use incremental backup and synchronization strategies
+
+### Build & Development Optimization
+
+- Enable hot reloading, fast refresh, and live updates where possible
+- Use parallel compilation, building, and testing processes
+- Implement smart dependency resolution and conflict resolution
+- Optimize import statements, module loading, and namespace management
+- Use incremental type checking, linting, and static analysis
+- Implement build caching and artifact reuse
+- Use appropriate build tools and optimizers for the target platform
+
+### Error Recovery & Resilience
+
+- Implement fast failure detection and recovery mechanisms
+- Use graceful degradation patterns for non-critical functionality
+- Implement circuit breakers for external services and dependencies
+- Add comprehensive logging, monitoring, and alerting for performance tracking
+- Use retry mechanisms with exponential backoff and jitter
+- Implement health checks and self-healing capabilities
+- Use appropriate error handling patterns for different failure scenarios
+
+### Code Organization for Performance
+
+- Implement modular architecture with clear separation of concerns
+- Use dependency injection and inversion of control for better testability and performance
+- Optimize component composition, reusability, and coupling
+- Implement proper abstraction layers and interfaces
+- Use design patterns that improve maintainability, scalability, and performance
+- Organize code for optimal compilation and runtime performance
+- Implement proper configuration management and environment-specific optimizations
+
+---
+
+## Related skills
+
+- `issues-setup` — bootstrap `brain/issues/` when issue tracking is needed
+- `issues-check` / `issues-scan` — maintain issues after brain exists

package/skills/user-skills/issues-check/SKILL.md

@@ -0,0 +1,121 @@
+---
+name: issues-check
+preamble-tier: 2
+version: 1.0.0
+description: |
+  Check open issues in brain/issues/ against the codebase. If an issue has been
+  fully resolved by recent work, move it to brain/issues/completed/ and update
+  INDEX.md. Use when asked to "check issues", "check if issues are done",
+  "sync issues", or "update issues index".
+allowed-tools:
+  - Bash
+  - Read
+  - Write
+  - Edit
+  - Grep
+  - Glob
+  - AskUserQuestion
+triggers:
+  - check issues
+  - check if issues are done
+  - sync issues
+  - update issues index
+  - issues check
+---
+
+# Issues Check — Verify and Close Resolved Issues
+
+## Purpose
+
+Read all open issues in `brain/issues/`, check whether the described problem
+has been resolved by recent code changes, and if so move the issue to
+`brain/issues/completed/` and update `INDEX.md`.
+
+---
+
+## Step 1 — Find all open issues
+
+```bash
+ISSUES_DIR="$(git rev-parse --show-toplevel 2>/dev/null)/brain/issues"
+echo "ISSUES_DIR=$ISSUES_DIR"
+find "$ISSUES_DIR" -maxdepth 1 -name "*.md" -not -path "*/completed/*" -not -name "INDEX.md" | sort
+```
+
+Parse each issue file to get its `id`, `title`, and `status`.
+
+---
+
+## Step 2 — Check each issue against the codebase
+
+For each open issue, search the codebase for evidence that the problem described
+in the issue has been fixed. Use Grep to find relevant code patterns.
+
+Key search targets per issue type:
+
+| Issue type | What to search |
+|------------|----------------|
+| API routes | `apps/web/src/app/api/` for the route path |
+| UI components | `apps/web/src/app/(app)/` for component paths |
+| Worker package | `apps/worker/src/` for references to old model names |
+| DSL/schema | `packages/dsl/src/` for vocabulary changes |
+| Database | `packages/db/prisma/` for migration/model changes |
+| Tests | `**/*.test.ts` for test coverage |
+
+Evidence that an issue is resolved:
+- The old/buggy code no longer exists (search returns nothing)
+- The new/correct code exists and looks right
+- Tests pass that previously failed or were missing
+
+---
+
+## Step 3 — Confirm before closing
+
+For each issue that appears resolved, use AskUserQuestion:
+
+```
+D<N> — Close issue #{id}?
+Issue: {title}
+Evidence: {what you found in the codebase}
+ELI10: We think this bug is fixed. Confirm before archiving it so we don't
+lose context if it isn't actually fixed.
+Stakes if we pick wrong: A resolved-but-not-fix issue stays open — low cost.
+A not-resolved issue that gets closed loses tracking — high cost.
+Recommendation: A — close and archive if evidence is clear.
+Note: options differ in kind, not coverage — no completeness score.
+A) Close and archive (recommended)
+B) Keep open — evidence is inconclusive
+C) Skip — not enough context to decide
+```
+
+---
+
+## Step 4 — Move the issue file
+
+```bash
+ISSUES_DIR="$(git rev-parse --show-toplevel 2>/dev/null)/brain/issues"
+COMPLETED_DIR="$ISSUES_DIR/completed"
+mkdir -p "$COMPLETED_DIR"
+# Move: mv "$ISSUES_DIR/{filename}" "$COMPLETED_DIR/{filename}"
+```
+
+---
+
+## Step 5 — Update INDEX.md
+
+For each closed issue:
+
+1. Remove it from the "Active Issues" table
+2. Add it to the "Completed Issues" table with today's date
+3. Update the counts
+
+Read INDEX.md first, then edit to reflect the completed issue.
+
+---
+
+## Step 6 — Report
+
+Report:
+- How many issues checked
+- How many closed
+- How many remain open
+- Any issues where evidence was inconclusive (kept open)