@_brenosiqueira/claude-skills 1.0.0

package/README.md

@@ -0,0 +1,86 @@
+# claude-skills
+
+> Claude AI skills for software project documentation and sprint planning.
+
+## Install
+
+```bash
+npm install -g @claudeskills/core
+```
+
+## Usage
+
+### Initialize skills in your project
+
+```bash
+cd your-project
+claude-skills init
+```
+
+This creates `.claude/skills/` with all available skills:
+
+```
+your-project/
+└── .claude/
+    └── skills/
+        ├── project-docs/
+        │   ├── SKILL.md
+        │   └── references/
+        └── github-sprint/
+            ├── SKILL.md
+            └── references/
+```
+
+### Commands
+
+```bash
+claude-skills init                   # Copy all skills to .claude/skills/
+claude-skills init -s project-docs   # Copy only one skill
+claude-skills list                   # Show available skills and install status
+claude-skills add github-sprint      # Add a specific skill
+claude-skills show project-docs      # Print SKILL.md to stdout
+```
+
+### Use in Claude
+
+After running `init`, reference the skills in your Claude conversation:
+
+1. **Upload the files** from `.claude/skills/<skill-name>/` at the start of a conversation
+2. **Or mention** the skill by name — Claude will follow the instructions automatically
+
+## Available skills
+
+### `project-docs`
+Generates standardized documentation for software projects:
+- `PROJETO.md` — product vision, roadmap, business model
+- `ARQUITETURA.md` — technical decisions, stack, ADRs
+- `README.md` — overview and setup instructions
+- `API.md` — endpoint contracts and examples
+- `ONBOARDING.md` — guide for new developers
+- `SPRINTS.md` — sprint history and planning
+
+### `github-sprint`
+Generates sprint planning files and automates GitHub issue creation:
+- `sprints/sprint-N.yml` — structured sprint plan
+- `.github/workflows/create-issues.yml` — GitHub Action
+- `.github/scripts/create-sprint-issues.js` — Action script
+
+Commit `sprint-N.yml` → GitHub Action creates milestone, labels and issues automatically.
+
+## Adding to .gitignore
+
+The `.claude/` folder contains AI instructions, not secrets. We recommend
+**committing it** so your whole team has access to the same skills.
+
+If you prefer not to commit it:
+
+```gitignore
+.claude/
+```
+
+## Publishing a new skill
+
+1. Add your skill folder to `skills/`
+2. Add metadata to `src/commands/list.js` (`SKILL_META`)
+3. Bump version in `package.json`
+4. `npm publish --access public`

package/package.json

@@ -0,0 +1,28 @@
+{
+  "name": "@_brenosiqueira/claude-skills",
+  "version": "1.0.0",
+  "description": "Claude AI skills for software project documentation and sprint planning",
+  "keywords": ["claude", "ai", "skills", "documentation", "sprint", "github"],
+  "author": "your-name",
+  "license": "MIT",
+  "type": "module",
+  "bin": {
+    "claude-skills": "./src/cli.js"
+  },
+  "files": [
+    "src/",
+    "skills/"
+  ],
+  "dependencies": {
+    "chalk": "^5.3.0",
+    "commander": "^12.0.0",
+    "fs-extra": "^11.2.0"
+  },
+  "engines": {
+    "node": ">=18.0.0"
+  },
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/your-username/claude-skills"
+  }
+}

package/skills/github-sprint/SKILL.md

@@ -0,0 +1,88 @@
+---
+name: github-sprint
+description: >
+  Generates sprint planning files and GitHub automation for any software project.
+  Use this skill whenever the user wants to plan a sprint, create GitHub issues,
+  break down tasks into issues, generate a sprint backlog, set up GitHub milestones,
+  or automate issue creation from a project plan. Triggers on phrases like "plan sprint",
+  "create issues", "break down sprint", "generate backlog", "create GitHub tasks",
+  "automate issues", or any request to turn a project plan into GitHub issues.
+  Always use this skill when the conversation involves sprints, GitHub issues, or
+  project task breakdown — even if the user doesn't say "skill" explicitly.
+---
+
+# GitHub Sprint Skill
+
+Generates structured sprint YAML files and the GitHub Action workflow that
+automatically creates milestones, labels and issues when the YAML is committed.
+
+## Overview
+
+This skill produces two types of output:
+
+1. **`sprints/sprint-N.yml`** — structured sprint plan (committed to the repo)
+2. **`.github/workflows/create-issues.yml`** — GitHub Action (one-time setup)
+
+When the user commits `sprint-N.yml`, the Action triggers automatically and
+creates everything in GitHub: milestone, labels, and all issues with full
+descriptions and acceptance criteria.
+
+---
+
+## Workflow
+
+### Step 1 — Understand the sprint
+
+Extract from the conversation (or ask if missing):
+
+- Sprint number and name
+- Duration (default: 2 weeks)
+- Which apps/services are involved (api, mobile, web, etc.)
+- What needs to be built — features, setup tasks, integrations
+
+Do NOT ask for more than necessary. If the conversation already has the
+sprint details, go straight to generating.
+
+### Step 2 — Generate the YAML
+
+Read `references/yaml-schema.md` for the full schema and rules.
+Read `references/issue-templates.md` for issue body templates by type.
+
+Key rules:
+- Every issue needs: title, description, acceptance criteria (3+ items), app label
+- Setup/config tasks use type `chore`, new functionality uses `feature`
+- Group issues by app in the YAML (api, passenger, driver, admin, shared)
+- Sprint label is always `sprint-N` (e.g. `sprint-1`)
+- Title format: `[app] Short imperative description`
+
+Save to `/mnt/user-data/outputs/sprints/sprint-N.yml`
+
+### Step 3 — Generate the GitHub Action (first sprint only)
+
+Check if `.github/workflows/create-issues.yml` was already generated in this
+conversation. If not, read `references/github-action.md` and generate it.
+
+Save to `/mnt/user-data/outputs/.github/workflows/create-issues.yml`
+
+### Step 4 — Present files and instructions
+
+Present both files. Then show the user exactly what to do:
+
+```
+1. Copy sprints/ and .github/ to your repository root
+2. Set the secret GH_TOKEN in repo Settings → Secrets → Actions
+   (token needs: issues, milestones, labels permissions)
+3. git add . && git commit -m "chore: add sprint-N plan" && git push
+4. Watch the Action run at github.com/OWNER/REPO/actions
+```
+
+---
+
+## Quality checklist before presenting
+
+- [ ] Every issue has at least 3 acceptance criteria
+- [ ] No issue title is vague ("setup things", "implement feature")
+- [ ] API contracts documented on endpoint issues (method, path, body, response)
+- [ ] Each app has at least one setup/chore issue in sprint 1
+- [ ] Sprint label matches sprint number (sprint-1, sprint-2, etc.)
+- [ ] YAML is valid (no tabs, consistent indentation)

package/skills/github-sprint/references/github-action.md

@@ -0,0 +1,194 @@
+# GitHub Action — create-issues.yml
+
+## What it does
+
+Triggers when a `sprints/sprint-*.yml` file is pushed to `main` or `dev`.
+Reads the YAML and creates:
+1. Labels (skips if already exists)
+2. Milestone with due date = push date + duration_weeks
+3. Issues with full body, labels and milestone
+
+## The action file
+
+Save to `.github/workflows/create-issues.yml` in the repository.
+
+```yaml
+name: Create sprint issues
+
+on:
+  push:
+    branches: [main, dev]
+    paths:
+      - 'sprints/sprint-*.yml'
+
+jobs:
+  create-issues:
+    runs-on: ubuntu-latest
+    permissions:
+      issues: write
+
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v4
+        with:
+          fetch-depth: 2
+
+      - name: Setup Node.js
+        uses: actions/setup-node@v4
+        with:
+          node-version: '20'
+
+      - name: Install dependencies
+        run: npm install js-yaml @octokit/rest
+
+      - name: Find changed sprint files
+        id: changed
+        run: |
+          FILES=$(git diff --name-only HEAD~1 HEAD -- 'sprints/sprint-*.yml' | tr '\n' ' ')
+          echo "files=$FILES" >> $GITHUB_OUTPUT
+
+      - name: Create issues from sprint YAML
+        if: steps.changed.outputs.files != ''
+        env:
+          GH_TOKEN: ${{ secrets.GH_TOKEN }}
+          REPO: ${{ github.repository }}
+        run: |
+          node .github/scripts/create-sprint-issues.js ${{ steps.changed.outputs.files }}
+```
+
+## The Node.js script
+
+Save to `.github/scripts/create-sprint-issues.js` in the repository.
+
+```javascript
+const fs = require('fs');
+const yaml = require('js-yaml');
+const { Octokit } = require('@octokit/rest');
+
+const octokit = new Octokit({ auth: process.env.GH_TOKEN });
+const [owner, repo] = process.env.REPO.split('/');
+const files = process.argv.slice(2);
+
+async function run() {
+  for (const file of files) {
+    if (!fs.existsSync(file)) continue;
+    console.log(`\nProcessing ${file}...`);
+    const data = yaml.load(fs.readFileSync(file, 'utf8'));
+    await processSprint(data);
+  }
+}
+
+async function processSprint(data) {
+  const { sprint, labels, issues } = data;
+
+  // 1. Create labels
+  const allLabels = [
+    ...(labels.apps || []),
+    ...(labels.types || []),
+    ...(labels.sprint || []),
+  ];
+
+  for (const label of allLabels) {
+    try {
+      await octokit.issues.createLabel({
+        owner, repo,
+        name: label.name,
+        color: label.color,
+        description: label.description || '',
+      });
+      console.log(`  ✓ Label: ${label.name}`);
+    } catch (e) {
+      if (e.status === 422) {
+        console.log(`  ~ Label already exists: ${label.name}`);
+      } else {
+        console.error(`  ✗ Label error ${label.name}:`, e.message);
+      }
+    }
+  }
+
+  // 2. Create milestone
+  const dueDate = new Date();
+  dueDate.setDate(dueDate.getDate() + (sprint.duration_weeks || 2) * 7);
+
+  let milestoneNumber;
+  try {
+    const { data: ms } = await octokit.issues.createMilestone({
+      owner, repo,
+      title: `Sprint ${sprint.number} — ${sprint.name}`,
+      description: sprint.milestone_description || '',
+      due_on: dueDate.toISOString(),
+    });
+    milestoneNumber = ms.number;
+    console.log(`  ✓ Milestone: Sprint ${sprint.number} (#${milestoneNumber})`);
+  } catch (e) {
+    // Milestone may already exist — find it
+    const { data: milestones } = await octokit.issues.listMilestones({ owner, repo });
+    const existing = milestones.find(m => m.title.startsWith(`Sprint ${sprint.number}`));
+    if (existing) {
+      milestoneNumber = existing.number;
+      console.log(`  ~ Milestone already exists: #${milestoneNumber}`);
+    } else {
+      throw e;
+    }
+  }
+
+  // 3. Create issues
+  for (const issue of issues) {
+    const issueLabels = [
+      issue.app,
+      issue.type,
+      `sprint-${sprint.number}`,
+    ].filter(Boolean);
+
+    try {
+      const { data: created } = await octokit.issues.create({
+        owner, repo,
+        title: issue.title,
+        body: issue.body,
+        labels: issueLabels,
+        milestone: milestoneNumber,
+      });
+      console.log(`  ✓ Issue #${created.number}: ${issue.title}`);
+    } catch (e) {
+      console.error(`  ✗ Issue error "${issue.title}":`, e.message);
+    }
+  }
+
+  console.log(`\n✅ Sprint ${sprint.number} created successfully!`);
+}
+
+run().catch(err => {
+  console.error('Fatal error:', err);
+  process.exit(1);
+});
+```
+
+## Setup instructions (one time)
+
+1. Create a GitHub Personal Access Token:
+   - Go to github.com → Settings → Developer settings → Personal access tokens → Fine-grained tokens
+   - Permissions needed: **Issues** (read/write), **Pull requests** (read)
+   - Repository access: only the transport repo
+
+2. Add the token as a secret:
+   - Go to repo → Settings → Secrets and variables → Actions
+   - New repository secret: name `GH_TOKEN`, value = the token
+
+3. Commit both files to the repository:
+   ```
+   .github/
+   ├── workflows/
+   │   └── create-issues.yml
+   └── scripts/
+       └── create-sprint-issues.js
+   ```
+
+4. From now on, committing any `sprints/sprint-N.yml` triggers the Action automatically.
+
+## Idempotency
+
+The script is safe to run multiple times:
+- Labels: skips if already exists (422 response)
+- Milestones: finds existing if create fails
+- Issues: always creates new (GitHub doesn't deduplicate issues)
+  → To avoid duplicates, only commit each sprint YAML once

package/skills/github-sprint/references/issue-templates.md

@@ -0,0 +1,125 @@
+# Issue Body Templates
+
+Use these templates as base for generating issue bodies.
+Adapt the sections and content to the specific task.
+
+## Template: Setup / Chore
+
+```markdown
+## Descrição
+[2-3 sentences: what needs to be configured and why it's needed before other tasks]
+
+## O que configurar
+- [ ] Install/configure item 1
+- [ ] Install/configure item 2
+- [ ] Create folder structure
+- [ ] Add environment variables to .env.example
+
+## Critérios de aceite
+- [ ] `npm run dev` starts without errors
+- [ ] TypeScript compiles without errors
+- [ ] [specific tool] connects successfully on startup
+- [ ] Health check endpoint returns 200
+
+## Referências
+- ARQUITETURA.md — Section X
+```
+
+## Template: API Endpoint (feature)
+
+```markdown
+## Descrição
+[What this endpoint does, who calls it and when]
+
+## Comportamento esperado
+1. Receives [input]
+2. Validates [what]
+3. Does [action]
+4. Returns [output]
+
+## O que implementar
+- [ ] Request validation (zod schema)
+- [ ] Business logic
+- [ ] Database query / update
+- [ ] Error handling
+
+## Critérios de aceite
+- [ ] Returns correct status code for success
+- [ ] Returns 400 for invalid input with descriptive error
+- [ ] Returns 401 without valid JWT
+- [ ] [Business rule criterion]
+- [ ] [Edge case criterion]
+
+## Contrato
+\`\`\`
+METHOD /path
+Headers: Authorization: Bearer {token}
+Body: { field: type }
+Response 200: { field: type }
+Response 400: { error: string }
+Response 401: { error: string }
+\`\`\`
+
+## Referências
+- ARQUITETURA.md — relevant section
+```
+
+## Template: Mobile Screen (feature)
+
+```markdown
+## Descrição
+[What this screen shows and what the user can do on it]
+
+## Comportamento esperado
+1. [First thing that happens when user arrives]
+2. [Main interaction]
+3. [What happens on success]
+4. [What happens on error]
+
+## O que implementar
+- [ ] Screen layout and components
+- [ ] API integration (which endpoint)
+- [ ] State management (Zustand store update or TanStack Query)
+- [ ] Navigation on success/error
+- [ ] Loading and error states
+
+## Critérios de aceite
+- [ ] [Visual/layout criterion]
+- [ ] [Data criterion — what is displayed]
+- [ ] [Interaction criterion — what happens on tap/submit]
+- [ ] Loading state shown during API call
+- [ ] Error message shown on failure
+- [ ] [Navigation criterion — where does it go next]
+
+## Referências
+- ARQUITETURA.md — Section 5 or 6
+```
+
+## Template: Admin Screen (feature)
+
+```markdown
+## Descrição
+[What this admin screen manages]
+
+## Comportamento esperado
+1. Data loaded via [endpoint]
+2. [Main admin action]
+3. Feedback shown after action
+
+## O que implementar
+- [ ] Table/list component with data
+- [ ] Filter/search if applicable
+- [ ] Action buttons with confirmation
+- [ ] API calls for each action
+- [ ] Toast feedback on success/error
+
+## Critérios de aceite
+- [ ] Data loads correctly from API
+- [ ] [Action] calls correct endpoint
+- [ ] Success feedback shown (toast)
+- [ ] List refreshes after action
+- [ ] Accessible only with admin JWT
+
+## Referências
+- ARQUITETURA.md — Section 7
+```

package/skills/github-sprint/references/yaml-schema.md

@@ -0,0 +1,146 @@
+# YAML Schema — Sprint Plan
+
+## Full structure
+
+```yaml
+sprint:
+  number: 1
+  name: "Autenticação e Perfis"
+  duration_weeks: 2
+  milestone_description: "One sentence describing the sprint goal"
+
+labels:
+  apps:
+    - name: api
+      color: "0075ca"
+      description: "Backend Node.js"
+    - name: passenger
+      color: "1D9E75"
+      description: "App passageiro"
+    # add/remove app labels as needed for the project
+  types:
+    - name: feature
+      color: "0e8a16"
+      description: "Nova funcionalidade"
+    - name: chore
+      color: "e4e669"
+      description: "Configuração e infra"
+    - name: bug
+      color: "d73a4a"
+      description: "Correção de bug"
+  sprint:
+    - name: sprint-1
+      color: "f9d0c4"
+      description: "Sprint 1"
+
+issues:
+  - title: "[api] Configurar projeto base"
+    type: chore           # feature | chore | bug
+    app: api              # must match a label name above
+    body: |
+      ## Descrição
+      Text describing what needs to be done and why.
+
+      ## O que implementar
+      - [ ] Item 1
+      - [ ] Item 2
+
+      ## Critérios de aceite
+      - [ ] Criterion 1
+      - [ ] Criterion 2
+      - [ ] Criterion 3
+
+      ## Referências
+      - Link or doc reference
+```
+
+## Rules
+
+### Title
+- Format: `[app] Short imperative verb phrase`
+- Good: `[api] Endpoint POST /auth/send-otp`
+- Bad: `[api] Auth stuff`, `[api] Implement authentication endpoint for sending OTP via SMS`
+- Max 60 characters
+
+### Body sections
+Every issue MUST have all four sections:
+1. `## Descrição` — what and why (2-4 sentences)
+2. `## O que implementar` — checklist of sub-tasks
+3. `## Critérios de aceite` — minimum 3 verifiable items
+4. `## Referências` — doc or architecture section reference
+
+### Endpoint issues (api features)
+Add a `## Contrato` section with the full API contract:
+
+```markdown
+## Contrato
+\`\`\`
+POST /auth/send-otp
+Body: { phone: string }
+Response 200: { message: string }
+Response 400: { error: string }
+Response 429: { error: 'Too many requests' }
+\`\`\`
+```
+
+### Type rules
+- `chore`: project setup, config, infrastructure, CI, dependencies
+- `feature`: new user-facing or system functionality
+- `bug`: fix for broken behaviour (usually not in sprint planning)
+
+### Labels applied per issue
+The Action automatically applies: `[app label]`, `[type label]`, `[sprint label]`
+You do NOT need to list labels in the YAML per issue — they are inferred from
+`app` and `type` fields plus the sprint number.
+
+## Minimal valid example
+
+```yaml
+sprint:
+  number: 2
+  name: "Mapas e Geolocalização"
+  duration_weeks: 2
+  milestone_description: "Integração de mapas, rastreamento em tempo real e estimativa de corrida."
+
+labels:
+  apps:
+    - { name: api,       color: "0075ca", description: "Backend" }
+    - { name: passenger, color: "1D9E75", description: "App passageiro" }
+    - { name: driver,    color: "378ADD", description: "App motorista" }
+  types:
+    - { name: feature, color: "0e8a16", description: "Nova funcionalidade" }
+    - { name: chore,   color: "e4e669", description: "Configuração e infra" }
+  sprint:
+    - { name: sprint-2, color: "c5def5", description: "Sprint 2" }
+
+issues:
+  - title: "[api] Integrar Google Maps Directions API"
+    type: feature
+    app: api
+    body: |
+      ## Descrição
+      Integrar a Google Maps Directions API para calcular distância e
+      duração estimada entre origem e destino de uma corrida.
+
+      ## O que implementar
+      - [ ] Instalar SDK `@googlemaps/google-maps-services-js`
+      - [ ] Criar serviço `MapsService` com método `getRoute(origin, destination)`
+      - [ ] Usar resultado para popular `distanceKm` e `durationMin` na corrida
+
+      ## Critérios de aceite
+      - [ ] `getRoute` retorna distância em km e duração em minutos
+      - [ ] Erros da API do Google tratados e logados
+      - [ ] Chave de API carregada via variável de ambiente
+      - [ ] Teste unitário com mock da API
+
+      ## Contrato
+      ```
+      POST /rides/estimate
+      Body: { originLat, originLng, destinationLat, destinationLng }
+      Response 200: { distanceKm, durationMin, priceMin, priceMax }
+      Response 400: { error: string }
+      ```
+
+      ## Referências
+      - ARQUITETURA.md — Seção 4 (Engine de precificação)
+```