@balazsbarta/mp-skills 0.1.0

package/.agents/skills/brainstorming/SKILL.md

@@ -0,0 +1,201 @@
+---
+name: brainstorming
+description: "Facilitate structured technical brainstorming sessions. Use this skill to explore options, challenge assumptions, and produce implementation-ready plans for coding agents."
+license: MIT
+metadata:
+  author: Balazs Barta
+  version: "2.0.0"
+  repository: https://github.com/balazsbarta/mp-skills
+  tags:
+    - brainstorming
+    - facilitation
+    - decision-making
+    - planning
+---
+
+# Brainstorming Facilitator Guide
+
+Run structured brainstorming sessions with a human user and produce outputs that a coding agent can implement immediately.
+
+## When to use this skill
+
+- User wants to brainstorm features, architecture, or implementation direction
+- User has a proposed solution and needs validation against alternatives
+- Problem space is unclear and needs structured discovery before coding
+- Team needs a prioritized implementation plan with explicit tradeoffs
+
+## Operating principles
+
+- Ask one high-value question at a time.
+- Analyze each response before asking the next question.
+- Resolve discoverable facts from the repository before asking user questions.
+- Do not make silent assumptions; label assumptions explicitly.
+- Challenge preferred solutions when evidence indicates a stronger option.
+- Keep all outputs concrete, scoped, and implementable.
+
+## Reference files
+
+Load references only when needed:
+
+| Need | Read |
+| --- | --- |
+| Ground discussion in repository facts first | [`references/repo-analysis.md`](references/repo-analysis.md) |
+| Choose and sequence high-value user questions | [`references/questioning-playbook.md`](references/questioning-playbook.md) |
+| Compare options and recommend with evidence | [`references/option-evaluation.md`](references/option-evaluation.md) |
+
+## Core workflow (4 phases)
+
+### 1) Context discovery
+
+Objective: Define the real problem and decision target.
+
+Required artifacts:
+- Problem statement
+- Desired outcome
+- Audience or impacted users
+- Business or technical impact
+
+Exit criteria:
+- Problem is specific and non-generic.
+- Success condition is explicit.
+
+Question patterns:
+- What exact problem are we solving right now?
+- What changes if this succeeds?
+- Who is most impacted by this decision?
+
+### 2) Requirements deep dive
+
+Objective: Lock constraints, boundaries, and non-goals.
+
+Required artifacts:
+- Functional requirements
+- Non-functional requirements
+- Constraints (timeline, compatibility, compliance, infra)
+- Out-of-scope items
+
+Exit criteria:
+- Must-haves vs nice-to-haves are separated.
+- Critical constraints are confirmed.
+
+Question patterns:
+- What is non-negotiable?
+- What existing systems or contracts cannot break?
+- What is explicitly out of scope for this iteration?
+
+### 3) Solution exploration
+
+Objective: Compare viable approaches and converge on a recommendation.
+
+Required artifacts:
+- At least two viable options when a decision is involved
+- Tradeoff comparison across effort, impact, risk, reversibility
+- Recommended option with fallback
+
+Exit criteria:
+- Selected option has a clear rationale.
+- Rejected options are documented with reasons.
+
+Question patterns:
+- Which options are realistically viable in this codebase?
+- What risk does each option introduce?
+- If we had to roll back, which option is easiest to reverse?
+
+### 4) Implementation planning
+
+Objective: Turn the decision into a dependency-ordered execution plan.
+
+Required artifacts:
+- Task breakdown ordered by dependency
+- Test and validation plan
+- Risks and mitigations
+- Open questions (if any)
+
+Exit criteria:
+- Plan is decision-complete for implementation.
+- Acceptance criteria are testable.
+
+Question patterns:
+- What is the smallest end-to-end slice to ship first?
+- What must happen before implementation starts?
+- How will we verify correctness and prevent regressions?
+
+## Repository-first analysis protocol
+
+Before asking broad intent questions, run targeted non-mutating analysis:
+
+1. Locate relevant files, entrypoints, configs, schemas, and tests.
+2. Summarize current behavior with concrete file references.
+3. Distinguish discoverable facts from preference decisions.
+4. Ask the user only for non-discoverable intent, constraints, or tradeoffs.
+
+If repository evidence is missing, state what was checked and why uncertainty remains.
+
+## Evidence-first challenge policy
+
+When the user proposes a preferred solution:
+
+1. Restate the proposed approach and its likely benefits.
+2. Surface at least one credible alternative when evidence supports it.
+3. Compare options on effort, impact, risk, and reversibility.
+4. Recommend the stronger option with rationale and fallback.
+5. If user still chooses a weaker option, proceed and record accepted tradeoffs.
+
+Do not block progress without reason; challenge with evidence, not opinion.
+
+## Assumption control protocol
+
+- Convert high-impact assumptions into direct questions.
+- Mark unresolved assumptions explicitly.
+- Do not finalize implementation planning when critical unknowns remain.
+- Keep an "Open Questions" list until all blocking items are resolved.
+
+## Optional lightweight scoring
+
+Use only when two or more viable options remain and tradeoffs are unclear.
+
+- Criteria: effort, impact, risk, reversibility
+- Scale: 1-5 per criterion
+- Keep scoring simple and transparent
+- Use scoring to support reasoning, not replace it
+
+## Required output contract
+
+Every completed session must produce:
+
+1. Problem statement
+2. Goal and success criteria
+3. Constraints and non-goals
+4. Options considered
+5. Decision rationale (including rejected alternatives)
+6. Risks and mitigations
+7. Implementation tasks in dependency order
+8. Test and validation approach
+9. Open questions
+
+Use this structure:
+
+```markdown
+## Problem
+## Goal and Success Criteria
+## Constraints and Non-Goals
+## Options Considered
+## Decision and Rationale
+## Risks and Mitigations
+## Implementation Plan
+## Test and Validation
+## Open Questions
+```
+
+## Quality gate
+
+Before ending the session, verify:
+
+- Recommendation is evidence-based and not assumption-based.
+- At least one alternative was considered for meaningful decisions.
+- Plan can be implemented without additional decision-making.
+- Risks, validation, and unresolved questions are explicit.
+
+## Cross-reference
+
+- Task breakdown follow-up: [`../task-breakdown/SKILL.md`](../task-breakdown/SKILL.md)

package/.agents/skills/brainstorming/references/option-evaluation.md

@@ -0,0 +1,64 @@
+# Option Evaluation Guide
+
+Use this guide when multiple viable options remain.
+
+## When to use
+
+- Two or more valid approaches are still on the table
+- Tradeoffs are unclear or disputed
+- User preference conflicts with repository evidence
+
+## Evaluation dimensions
+
+Use four dimensions by default:
+
+- Effort
+- Impact
+- Risk
+- Reversibility
+
+Optional fifth dimension: compatibility with existing architecture.
+
+## Lightweight scoring
+
+Use only if qualitative comparison is not enough.
+
+- Score each option from 1-5 per dimension.
+- Keep equal weights unless a user constraint justifies weighting.
+- Treat scores as decision support, not an automatic verdict.
+
+Template:
+
+```markdown
+| Dimension | Option A | Option B | Notes |
+| --- | --- | --- | --- |
+| Effort |  |  |  |
+| Impact |  |  |  |
+| Risk |  |  |  |
+| Reversibility |  |  |  |
+| Total |  |  |  |
+```
+
+## Decision statement template
+
+```markdown
+### Decision
+Selected: <option>
+
+### Why
+- <evidence-backed reason 1>
+- <evidence-backed reason 2>
+
+### Rejected Alternatives
+- <option>: <why not now>
+
+### Fallback
+- If <failure condition>, switch to <fallback option>.
+```
+
+## Red flags that require challenge
+
+- Chosen option conflicts with existing interfaces or contracts
+- Chosen option has high irreversible migration cost
+- Chosen option lacks clear validation path
+- Chosen option is selected by preference only, without evidence

package/.agents/skills/brainstorming/references/questioning-playbook.md

@@ -0,0 +1,57 @@
+# Questioning Playbook
+
+Use this guide to run an adaptive, one-question-at-a-time facilitation flow.
+
+## Objective
+
+Ask the highest-value next question, not the next question in a fixed script.
+
+## Loop
+
+1. Read current context and latest user answer.
+2. Extract new facts, decisions, and assumptions.
+3. Identify the biggest unresolved blocker.
+4. Ask one targeted question to remove that blocker.
+5. Repeat until implementation planning is decision-complete.
+
+## Question quality standard
+
+A strong question is:
+
+- Specific and scoped to one decision
+- Unanswerable by repository inspection
+- Material to architecture, delivery risk, or acceptance criteria
+
+Avoid:
+
+- Multi-part compound questions
+- Questions that can be answered from code
+- Questions that do not change the plan
+
+## Progressive question categories
+
+Use only as needed, in this order:
+
+1. Problem and outcome clarity
+2. Constraints and non-goals
+3. Option viability and tradeoffs
+4. Implementation readiness and validation
+
+## Challenge prompts (evidence-first)
+
+When the user proposes approach X:
+
+- "Given `<repo constraint>`, should we compare X against Y before committing?"
+- "X optimizes `<benefit>`, but increases `<risk>`. Is that tradeoff acceptable?"
+- "If rollback is needed, X is harder to reverse than Y. Do we still prefer X?"
+
+Always challenge with concrete evidence, not abstract preference.
+
+## Stop condition
+
+Stop questioning and produce final plan only when:
+
+- Success criteria are explicit
+- Key constraints are confirmed
+- One option is selected with rationale
+- Tasks, risks, and validation are concrete

package/.agents/skills/brainstorming/references/repo-analysis.md

@@ -0,0 +1,60 @@
+# Repository Analysis Playbook
+
+Use this guide before asking broad user questions. The goal is to separate discoverable facts from preference decisions.
+
+## Outcomes
+
+- Current-state summary with concrete file references
+- Known constraints based on code/config
+- Unknowns that actually require user input
+
+## Step-by-step
+
+1. Locate related entrypoints and modules.
+2. Find config, schema, and interface contracts.
+3. Identify existing tests and current behavior.
+4. Capture integration boundaries and compatibility constraints.
+5. Produce a short findings summary before asking questions.
+
+## Command patterns (non-mutating)
+
+```bash
+rg --files
+rg -n "keyword|type|interface|route|config" <path>
+sed -n '1,200p' <file>
+```
+
+Prefer targeted scans over broad file dumps.
+
+## Fact vs preference split
+
+Treat as discoverable facts:
+
+- Existing code paths and data flow
+- API signatures and type contracts
+- Build/test/tooling constraints
+- Current test coverage and failure surfaces
+
+Treat as user decisions:
+
+- Priority and timeline tradeoffs
+- Non-obvious product constraints
+- UX/behavior preference among valid options
+- Acceptance bar beyond existing standards
+
+## Output format
+
+Use this before question 1:
+
+```markdown
+### Repository Findings
+- Fact 1: <what exists> (`path/to/file.ts:line`)
+- Fact 2: <constraint> (`path/to/config.ts:line`)
+- Fact 3: <risk or gap> (`path/to/test.spec.ts:line`)
+
+### Unknowns Requiring User Input
+1. <preference decision>
+2. <scope/priority decision>
+```
+
+If no relevant code is found, state exactly what was searched.

package/.agents/skills/conventional-commits/SKILL.md

@@ -0,0 +1,124 @@
+---
+name: conventional-commits
+description: "Conventional Commits specification guide. Covers commit message format, types, scopes, breaking changes, and integration with semantic-release for automated versioning. Use this skill when creating commits, setting up commit conventions, or configuring automated releases."
+license: MIT
+metadata:
+  author: Balazs Barta
+  version: "2.0.0"
+  repository: https://github.com/balazsbarta/mp-skills
+  tags:
+    - conventional-commits
+    - commitlint
+    - semantic-release
+    - changelog
+    - versioning
+---
+
+# Conventional Commits Guide
+
+Write commit messages that are easy to read and can drive automated releases.
+
+## Project rules first
+
+Before writing commits or setting up tooling, check for local configuration:
+
+```bash
+ls commitlint.config.* .commitlintrc* .releaserc* 2>/dev/null
+ls .husky/commit-msg 2>/dev/null
+rg -n '"commitlint"|"release"|"husky"' package.json 2>/dev/null
+```
+
+- If local rules exist, follow them.
+- If local rules do not exist, use the defaults in this skill.
+
+## Quick workflow
+
+1. Choose the commit type (`feat`, `fix`, etc.).
+2. Add a scope when helpful (`feat(auth): ...`).
+3. Write the subject as `<type>[optional scope]: <description>`.
+4. Add body and footers when needed.
+5. For breaking changes, use `!` and a `BREAKING CHANGE:` footer.
+6. Validate with commitlint when available.
+
+## Commit format
+
+```
+<type>[optional scope]: <description>
+
+[optional body]
+
+[optional footer(s)]
+```
+
+Examples:
+
+```bash
+git commit -m "feat(auth): add OAuth2 login flow"
+git commit -m "fix(api): handle empty pagination token"
+```
+
+## Types at a glance
+
+| Type | Use for |
+| --- | --- |
+| `feat` | New user-facing behavior |
+| `fix` | Bug fixes |
+| `docs` | Documentation-only changes |
+| `refactor` | Internal restructuring without behavior change |
+| `perf` | Performance improvements |
+| `test` | Tests only |
+| `build` | Build tooling or dependencies |
+| `ci` | CI/CD pipeline changes |
+| `chore` | Maintenance work |
+
+See [`references/commit-types-scopes.md`](references/commit-types-scopes.md) for selection guidance and scope patterns.
+
+## Breaking changes
+
+Any type can be breaking:
+
+```text
+feat(api)!: remove v1 users endpoint
+
+BREAKING CHANGE: /v1/users was removed. Use /v2/users.
+```
+
+Use uppercase `BREAKING CHANGE:` and include migration guidance.
+
+## Optional tooling setup
+
+Install commitlint and semantic-release:
+
+```bash
+npm install --save-dev @commitlint/cli @commitlint/config-conventional semantic-release
+```
+
+Minimal commitlint config:
+
+```javascript
+// commitlint.config.js
+export default { extends: ['@commitlint/config-conventional'] };
+```
+
+Validate a message:
+
+```bash
+echo "feat(auth): add OAuth2 login flow" | npx commitlint
+```
+
+See [`references/semantic-release.md`](references/semantic-release.md) for release mapping and minimal setup.
+
+## Troubleshooting
+
+- `type must be one of ...`: check local `type-enum` rules in commitlint config.
+- `subject may not be empty`: ensure `: ` is present after type/scope.
+- Unexpected release bump: inspect commit history and breaking-change footers.
+
+## Cross-reference
+
+- **Pull Request Lifecycle**: [../pull-request-lifecycle/SKILL.md](../pull-request-lifecycle/SKILL.md)
+
+## Resources
+
+- **Commit types, scopes, and breaking changes**: [`references/commit-types-scopes.md`](references/commit-types-scopes.md)
+- **Semantic-release integration**: [`references/semantic-release.md`](references/semantic-release.md)

package/.agents/skills/conventional-commits/references/commit-types-scopes.md

@@ -0,0 +1,75 @@
+# Commit Types, Scopes, and Breaking Changes
+
+Use this reference when choosing a commit type, defining scopes, or documenting breaking changes.
+
+## Commit types
+
+| Type | Use for | Typical release impact |
+| --- | --- | --- |
+| `feat` | New user-facing behavior | minor |
+| `fix` | Bug fixes | patch |
+| `perf` | Performance improvements | patch |
+| `docs` | Documentation-only changes | none (unless custom rules) |
+| `style` | Formatting-only changes | none |
+| `refactor` | Internal restructuring without behavior change | none (unless custom rules) |
+| `test` | Test changes | none |
+| `build` | Build tooling or dependencies | none |
+| `ci` | CI/CD configuration | none |
+| `chore` | General maintenance | none |
+
+Quick chooser:
+
+```text
+New capability? -> feat
+Broken behavior fixed? -> fix
+Faster same behavior? -> perf
+Code reorganized only? -> refactor
+Docs/tests/format/build/CI only? -> docs/test/style/build/ci
+Anything else? -> chore
+```
+
+## Scopes
+
+Scopes are optional. Use them when they make history easier to scan.
+
+Common patterns:
+
+```text
+feat(auth): add password reset
+fix(api): handle empty token
+perf(db): add index for user lookup
+build(web): upgrade vite
+```
+
+Guidelines:
+
+- Keep scopes short and lowercase.
+- Reuse a stable scope list if the project defines one.
+- Omit scope for cross-cutting changes.
+
+## Breaking changes
+
+Any type can be breaking. Use `!` and include a `BREAKING CHANGE:` footer.
+
+```text
+feat(api)!: remove v1 users endpoint
+
+BREAKING CHANGE: /v1/users has been removed. Use /v2/users.
+```
+
+Footer rules:
+
+- Use exact uppercase `BREAKING CHANGE:`.
+- Put footer after a blank line.
+- Include migration guidance when possible.
+
+Breaking change impact:
+
+- Any commit with `!` or `BREAKING CHANGE:` should trigger a major bump in standard semantic-release setups.
+
+## Validation
+
+```bash
+echo "feat(auth): add login flow" | npx commitlint
+echo "feat(api)!: remove v1 users endpoint" | npx commitlint
+```

package/.agents/skills/conventional-commits/references/semantic-release.md

@@ -0,0 +1,71 @@
+# Semantic Release Essentials
+
+Use this reference when mapping conventional commits to versions or configuring a minimal semantic-release setup.
+
+## Default version mapping
+
+| Commit pattern | Version impact |
+| --- | --- |
+| `fix` | patch |
+| `perf` | patch |
+| `feat` | minor |
+| Any commit with `!` or `BREAKING CHANGE:` | major |
+| `docs`, `style`, `refactor`, `test`, `build`, `ci`, `chore` | no release (unless custom rules) |
+
+## Minimal setup
+
+Install:
+
+```bash
+npm install --save-dev semantic-release
+```
+
+Minimal config:
+
+```json
+// .releaserc.json
+{
+  "branches": ["main"],
+  "plugins": [
+    "@semantic-release/commit-analyzer",
+    "@semantic-release/release-notes-generator",
+    "@semantic-release/github"
+  ]
+}
+```
+
+Dry run:
+
+```bash
+npx semantic-release --dry-run
+```
+
+## Common custom release rules
+
+```json
+// .releaserc.json
+{
+  "plugins": [
+    ["@semantic-release/commit-analyzer", {
+      "preset": "conventionalcommits",
+      "releaseRules": [
+        { "type": "docs", "release": "patch" },
+        { "type": "refactor", "release": "patch" },
+        { "breaking": true, "release": "major" }
+      ]
+    }]
+  ]
+}
+```
+
+## Troubleshooting
+
+- No release: confirm branch is configured and commits match expected format.
+- Wrong bump: inspect commit history and breaking-change footers.
+- CI failures: check token permissions and run `--dry-run` in CI logs.
+
+## Official docs
+
+- Conventional Commits spec: https://www.conventionalcommits.org/en/v1.0.0/
+- semantic-release docs: https://semantic-release.gitbook.io/semantic-release/
+- commitlint docs: https://commitlint.js.org/