@balazsbarta/mp-skills 0.1.0

package/.agents/skills/supabase/references/storage.md

@@ -0,0 +1,182 @@
+# Supabase Storage
+
+Configure and use Supabase Storage for file uploads and downloads.
+
+## When to use this reference
+
+- Setting up file storage buckets
+- Uploading and downloading files
+- Configuring storage policies (public/private)
+- Generating signed URLs
+
+## Creating buckets
+
+### Via SQL migration
+
+```sql
+-- supabase/migrations/20250101000000_create_storage_buckets.sql
+INSERT INTO storage.buckets (id, name, public)
+VALUES ('avatars', 'avatars', true);
+
+INSERT INTO storage.buckets (id, name, public)
+VALUES ('documents', 'documents', false);
+```
+
+### Via client
+
+```typescript
+const { data, error } = await supabase.storage.createBucket('avatars', {
+  public: true,
+  fileSizeLimit: 5242880, // 5MB
+  allowedMimeTypes: ['image/png', 'image/jpeg', 'image/webp'],
+});
+```
+
+## Storage policies
+
+### Public bucket — anyone can read
+
+```sql
+CREATE POLICY "Public read access" ON storage.objects
+  FOR SELECT
+  USING (bucket_id = 'avatars');
+```
+
+### Authenticated upload to own folder
+
+```sql
+CREATE POLICY "Users can upload own avatar" ON storage.objects
+  FOR INSERT
+  TO authenticated
+  WITH CHECK (
+    bucket_id = 'avatars'
+    AND (storage.foldername(name))[1] = auth.uid()::text
+  );
+```
+
+### Users can manage own files
+
+```sql
+CREATE POLICY "Users can manage own files" ON storage.objects
+  FOR ALL
+  TO authenticated
+  USING (
+    bucket_id = 'documents'
+    AND auth.uid()::text = (storage.foldername(name))[1]
+  )
+  WITH CHECK (
+    bucket_id = 'documents'
+    AND auth.uid()::text = (storage.foldername(name))[1]
+  );
+```
+
+## Uploading files
+
+### From client (browser)
+
+```typescript
+const file = event.target.files[0];
+const filePath = `${user.id}/${file.name}`;
+
+const { data, error } = await supabase.storage
+  .from('avatars')
+  .upload(filePath, file, {
+    cacheControl: '3600',
+    upsert: true,
+  });
+```
+
+### From server
+
+```typescript
+const { data, error } = await supabase.storage
+  .from('documents')
+  .upload('reports/annual.pdf', fileBuffer, {
+    contentType: 'application/pdf',
+  });
+```
+
+## Downloading files
+
+### Public URL (public buckets)
+
+```typescript
+const { data } = supabase.storage
+  .from('avatars')
+  .getPublicUrl('user-123/avatar.png');
+
+// data.publicUrl = https://project.supabase.co/storage/v1/object/public/avatars/user-123/avatar.png
+```
+
+### Signed URL (private buckets)
+
+```typescript
+const { data, error } = await supabase.storage
+  .from('documents')
+  .createSignedUrl('reports/annual.pdf', 3600); // 1 hour expiry
+
+// data.signedUrl = https://project.supabase.co/storage/v1/object/sign/documents/reports/annual.pdf?token=...
+```
+
+### Download file
+
+```typescript
+const { data, error } = await supabase.storage
+  .from('documents')
+  .download('reports/annual.pdf');
+
+// data is a Blob
+```
+
+## Listing files
+
+```typescript
+const { data, error } = await supabase.storage
+  .from('avatars')
+  .list('user-123/', {
+    limit: 100,
+    offset: 0,
+    sortBy: { column: 'created_at', order: 'desc' },
+  });
+```
+
+## Deleting files
+
+```typescript
+const { data, error } = await supabase.storage
+  .from('avatars')
+  .remove(['user-123/old-avatar.png']);
+```
+
+## Image transformations
+
+```typescript
+const { data } = supabase.storage
+  .from('avatars')
+  .getPublicUrl('user-123/avatar.png', {
+    transform: {
+      width: 200,
+      height: 200,
+      resize: 'cover',
+    },
+  });
+```
+
+## Troubleshooting
+
+### "Bucket not found"
+
+- Verify bucket exists: check Supabase dashboard > Storage
+- Bucket names are case-sensitive
+
+### "Permission denied" on upload
+
+- Check storage policies exist for the bucket
+- Verify the file path matches policy conditions
+- Ensure user is authenticated
+
+### File uploaded but can't access
+
+- For public buckets: use `getPublicUrl()`
+- For private buckets: use `createSignedUrl()`
+- Check the bucket's `public` setting matches your intent

package/.agents/skills/task-breakdown/SKILL.md

@@ -0,0 +1,179 @@
+---
+name: task-breakdown
+description: "Task breakdown and estimation guide. Covers epic/story/task hierarchy, acceptance criteria writing, estimation techniques, and work decomposition. Use this skill when planning sprints, writing user stories, breaking down features into tasks, or estimating effort."
+license: MIT
+metadata:
+  author: Balazs Barta
+  version: "1.0.0"
+  repository: https://github.com/balazsbarta/mp-skills
+  tags:
+    - planning
+    - user-stories
+    - estimation
+    - agile
+    - task-management
+---
+
+# Task Breakdown Guide
+
+Use this skill to decompose feature requests into actionable, estimable tasks. Audience: another coding agent producing implementation-ready planning artifacts.
+
+## When to use this skill
+
+- Breaking a feature into implementable tasks
+- Writing user stories with acceptance criteria
+- Estimating effort for stories and tasks
+- Planning sprint scope
+- Converting brainstorming outputs into a backlog
+
+## Prerequisites
+
+**Before decomposing work, extract and confirm:**
+
+- **Feature goal**: What user problem does this solve?
+- **Scope boundaries**: What is explicitly out of scope?
+- **Technical context**: Existing architecture and constraints
+
+## Quick reference
+
+| Request Pattern | First Check | How To |
+| --- | --- | --- |
+| "Break this feature into tasks" | [`references/epic-story-format.md`](references/epic-story-format.md) | Epic/story/task hierarchy and templates |
+| "Write acceptance criteria" | [`references/acceptance-criteria.md`](references/acceptance-criteria.md) | Given/When/Then and checklist formats |
+| "How long will this take?" | [`references/estimation-guide.md`](references/estimation-guide.md) | T-shirt sizing, story points, time-based |
+
+## Core concepts
+
+### Work hierarchy
+
+```
+Epic (large feature, multiple sprints)
+├── Story (user-facing value, fits in 1 sprint)
+│   ├── Task (technical work, fits in 1 day)
+│   └── Task
+├── Story
+│   ├── Task
+│   └── Task
+└── Story
+```
+
+### Story format
+
+```
+As a [user role],
+I want to [action],
+So that [benefit].
+```
+
+### Task characteristics
+
+A well-defined task is:
+- **Small** — Completable in 1 day or less
+- **Specific** — Clear start and end state
+- **Testable** — Has verification criteria
+- **Independent** — Minimal dependencies on other tasks
+
+## Critical requirements
+
+### Every story must have
+
+- **Title** — Short, descriptive (imperative mood)
+- **Description** — User story format or clear problem statement
+- **Acceptance criteria** — Testable conditions for "done"
+- **Estimate** — Relative size or time estimate
+
+### Task decomposition rules
+
+- No task larger than 1 day of work
+- Each task produces a testable output
+- Tasks are ordered by dependency (what blocks what)
+- Infrastructure tasks come before feature tasks
+
+## Execution workflow
+
+### 1. Identify the epic
+
+```
+Epic: User Authentication
+Goal: Users can sign up, log in, and manage their accounts.
+```
+
+### 2. Break into stories
+
+```
+Story 1: User can sign up with email and password
+Story 2: User can log in with existing credentials
+Story 3: User can reset forgotten password
+Story 4: User can update profile information
+```
+
+### 3. Write acceptance criteria for each story
+
+```
+Story 1: User can sign up with email and password
+
+Acceptance Criteria:
+- [ ] Sign-up form validates email format
+- [ ] Password meets minimum requirements (8+ chars, 1 uppercase, 1 number)
+- [ ] Duplicate email shows clear error message
+- [ ] Successful sign-up sends verification email
+- [ ] User is redirected to onboarding after verification
+```
+
+### 4. Break stories into tasks
+
+```
+Story 1 Tasks:
+1. Create sign-up API endpoint (POST /auth/signup)
+2. Add email validation and password hashing
+3. Create sign-up form component
+4. Add form validation (client-side)
+5. Implement email verification flow
+6. Add error handling and user feedback
+7. Write integration tests for sign-up flow
+```
+
+### 5. Estimate tasks
+
+```
+1. Create sign-up API endpoint — S (2-3 hours)
+2. Add email validation and password hashing — S (2 hours)
+3. Create sign-up form component — M (4 hours)
+4. Add form validation — S (2 hours)
+5. Implement email verification flow — M (4-5 hours)
+6. Add error handling and user feedback — S (2 hours)
+7. Write integration tests — M (3-4 hours)
+
+Story total: ~20-22 hours (M t-shirt size)
+```
+
+## Error handling
+
+### Failure modes
+
+| Mistake | Symptom | Fix |
+| --- | --- | --- |
+| Stories too large | Can't finish in 1 sprint | Split by workflow step or user action |
+| Vague acceptance criteria | "Works correctly" | Use Given/When/Then format |
+| Missing edge cases | Bugs in production | Add negative test criteria |
+| No dependency order | Tasks blocked constantly | Map dependencies before starting |
+| Underestimation | Sprint overflow | Add buffer, use historical data |
+
+## Output contract
+
+Produce markdown that includes:
+- Epic with goal, scope boundaries, and non-goals
+- Stories with user-story statements and explicit acceptance criteria
+- Tasks with estimates, dependency order, and verification criteria
+- Sprint allocation summary tied to team capacity assumptions
+
+## Cross-references
+
+- **Brainstorming**: [../brainstorming/SKILL.md](../brainstorming/SKILL.md) — Generate and evaluate feature ideas before breaking down
+- **Pull Request Lifecycle**: [../pull-request-lifecycle/SKILL.md](../pull-request-lifecycle/SKILL.md) — Each story/task becomes a PR
+
+## Resources
+
+- **Epic and story format**: [`references/epic-story-format.md`](references/epic-story-format.md)
+- **Acceptance criteria**: [`references/acceptance-criteria.md`](references/acceptance-criteria.md)
+- **Estimation guide**: [`references/estimation-guide.md`](references/estimation-guide.md)

package/.agents/skills/task-breakdown/references/acceptance-criteria.md

@@ -0,0 +1,165 @@
+# Acceptance Criteria
+
+Patterns for writing clear, testable acceptance criteria for user stories.
+
+## When to use this reference
+
+- Writing acceptance criteria for a user story
+- Defining "done" for a task or feature
+- Translating requirements into testable conditions
+
+## Formats
+
+### Checklist format (simple)
+
+Best for straightforward requirements:
+
+```markdown
+### Acceptance criteria
+- [ ] Email field validates format before submission
+- [ ] Password requires minimum 8 characters
+- [ ] Success message displays after submission
+- [ ] Form data persists if page is refreshed (draft state)
+```
+
+### Given/When/Then format (BDD)
+
+Best for complex behavior with multiple scenarios:
+
+```markdown
+### Acceptance criteria
+
+**Scenario: Successful login**
+Given the user is on the login page
+And they have a registered account
+When they enter valid email and password
+And click "Log in"
+Then they are redirected to the dashboard
+And a success toast is shown
+
+**Scenario: Invalid credentials**
+Given the user is on the login page
+When they enter an incorrect password
+And click "Log in"
+Then an error message "Invalid email or password" is shown
+And the password field is cleared
+And the form remains on the login page
+```
+
+### Rule-based format
+
+Best for business rules and constraints:
+
+```markdown
+### Acceptance criteria
+
+**Rules:**
+1. Discount code must be alphanumeric, 6-12 characters
+2. Only one discount code per order
+3. Expired codes show "This code has expired"
+4. Codes are case-insensitive
+5. Valid code shows discount amount before checkout
+```
+
+## Writing good acceptance criteria
+
+### Characteristics
+
+| Good Criteria | Bad Criteria |
+| --- | --- |
+| Specific and testable | Vague ("works correctly") |
+| Focused on behavior | Focused on implementation |
+| Independent | Dependent on other criteria |
+| Written in user language | Written in technical jargon |
+
+### Examples
+
+#### Good
+
+```
+- [ ] Search results appear within 2 seconds
+- [ ] Empty search shows "No results found" message
+- [ ] Search highlights matching terms in results
+```
+
+#### Bad
+
+```
+- [ ] Search works
+- [ ] Fast response time
+- [ ] Good UX for empty state
+```
+
+## Coverage checklist
+
+For each story, ensure criteria cover:
+
+### Functional
+
+- [ ] **Happy path** — The main success scenario
+- [ ] **Validation** — Input validation and error messages
+- [ ] **Edge cases** — Empty states, max values, special characters
+- [ ] **Error handling** — Network errors, server errors, timeouts
+
+### Non-functional
+
+- [ ] **Performance** — Response time, load handling
+- [ ] **Accessibility** — Keyboard navigation, screen reader support
+- [ ] **Security** — Authentication, authorization, input sanitization
+- [ ] **Responsiveness** — Mobile, tablet, desktop behavior
+
+## Mapping to tests
+
+Each acceptance criterion should map to at least one test:
+
+```markdown
+### Acceptance criteria → Test mapping
+
+| Criterion | Test Type | Test File |
+| --- | --- | --- |
+| Email validates format | Unit test | `auth.test.ts` |
+| Success redirects to dashboard | Integration test | `login.test.ts` |
+| Error shows message | Component test | `LoginForm.test.tsx` |
+| Rate limit after 5 attempts | API test | `auth-api.test.ts` |
+```
+
+## Templates by story type
+
+### API endpoint story
+
+```markdown
+- [ ] Endpoint returns correct status code (200/201/204)
+- [ ] Response body matches schema
+- [ ] Invalid input returns 400 with error details
+- [ ] Unauthorized request returns 401
+- [ ] Rate limiting returns 429 after threshold
+```
+
+### UI component story
+
+```markdown
+- [ ] Component renders in default state
+- [ ] Component handles loading state
+- [ ] Component handles error state
+- [ ] Component handles empty state
+- [ ] Component is keyboard accessible
+- [ ] Component works on mobile viewport (375px)
+```
+
+### Data migration story
+
+```markdown
+- [ ] Migration runs without errors on staging data
+- [ ] All existing records are transformed correctly
+- [ ] Rollback script restores original state
+- [ ] Migration completes within acceptable time window
+- [ ] No data loss verified by row count comparison
+```
+
+## Tips
+
+- Write criteria before starting implementation
+- If you can't write criteria, the story needs more definition
+- Review criteria with stakeholders before starting
+- Each criterion should be independently verifiable
+- Aim for 3-8 criteria per story (fewer = too vague, more = split the story)