cokit-cli 1.0.8 → 1.2.0

package/templates/repo/.github/skills/backend-development/references/backend-testing.md

@@ -0,0 +1,484 @@
+# Backend Testing Strategies
+
+Comprehensive testing approaches, frameworks, and quality assurance practices (2025).
+
+## Test Pyramid (70-20-10 Rule)
+
+```
+        /\
+       /E2E\     10% - End-to-End Tests
+      /------\
+     /Integr.\ 20% - Integration Tests
+    /----------\
+   /   Unit     \ 70% - Unit Tests
+  /--------------\
+```
+
+**Rationale:**
+- Unit tests: Fast, cheap, isolate bugs quickly
+- Integration tests: Verify component interactions
+- E2E tests: Expensive, slow, but validate real user flows
+
+## Unit Testing
+
+### Frameworks by Language
+
+**C#/.NET:**
+- **xUnit** - Modern, extensible, .NET recommended, best parallel execution
+- **NUnit** - Mature, attribute-based, rich assertions, data-driven testing
+- **MSTest** - Microsoft's official, Visual Studio integrated
+- **Moq** - Mocking library for dependency injection
+
+**TypeScript/JavaScript:**
+- **Vitest** - 50% faster than Jest in CI/CD, ESM native
+- **Jest** - Mature, large ecosystem, snapshot testing
+
+**Python:**
+- **Pytest** - Industry standard, fixtures, parametrization
+- **Unittest** - Built-in, standard library
+
+**Go:**
+- **testing** - Built-in, table-driven tests
+- **testify** - Assertions and mocking
+
+### Best Practices
+
+```typescript
+// Good: Test single responsibility
+describe('UserService', () => {
+  describe('createUser', () => {
+    it('should create user with valid data', async () => {
+      const userData = { email: 'test@example.com', name: 'Test' };
+      const user = await userService.createUser(userData);
+
+      expect(user).toMatchObject(userData);
+      expect(user.id).toBeDefined();
+    });
+
+    it('should throw error with duplicate email', async () => {
+      const userData = { email: 'existing@example.com', name: 'Test' };
+
+      await expect(userService.createUser(userData))
+        .rejects.toThrow('Email already exists');
+    });
+
+    it('should hash password before storing', async () => {
+      const userData = { email: 'test@example.com', password: 'plain123' };
+      const user = await userService.createUser(userData);
+
+      expect(user.password).not.toBe('plain123');
+      expect(user.password).toMatch(/^\$argon2id\$/);
+    });
+  });
+});
+```
+
+### Mocking
+
+```typescript
+// Mock external dependencies
+jest.mock('./emailService');
+
+it('should send welcome email after user creation', async () => {
+  const emailService = require('./emailService');
+  emailService.sendWelcomeEmail = jest.fn();
+
+  await userService.createUser({ email: 'test@example.com' });
+
+  expect(emailService.sendWelcomeEmail).toHaveBeenCalledWith('test@example.com');
+});
+```
+
+## Integration Testing
+
+### API Integration Tests
+
+```typescript
+import request from 'supertest';
+import { app } from '../app';
+
+describe('POST /api/users', () => {
+  beforeAll(async () => {
+    await db.connect(); // Real database connection (test DB)
+  });
+
+  afterAll(async () => {
+    await db.disconnect();
+  });
+
+  beforeEach(async () => {
+    await db.users.deleteMany({}); // Clean state
+  });
+
+  it('should create user and return 201', async () => {
+    const response = await request(app)
+      .post('/api/users')
+      .send({ email: 'test@example.com', name: 'Test User' })
+      .expect(201);
+
+    expect(response.body).toMatchObject({
+      email: 'test@example.com',
+      name: 'Test User',
+    });
+
+    // Verify database persistence
+    const user = await db.users.findOne({ email: 'test@example.com' });
+    expect(user).toBeDefined();
+  });
+
+  it('should return 400 for invalid email', async () => {
+    await request(app)
+      .post('/api/users')
+      .send({ email: 'invalid-email', name: 'Test' })
+      .expect(400)
+      .expect((res) => {
+        expect(res.body.error).toBe('Invalid email format');
+      });
+  });
+});
+```
+
+### API Integration Tests (ASP.NET Core)
+
+```csharp
+public class UsersControllerTests : IClassFixture<WebApplicationFactory<Program>>
+{
+    private readonly WebApplicationFactory<Program> _factory;
+    private readonly HttpClient _client;
+
+    public UsersControllerTests(WebApplicationFactory<Program> factory)
+    {
+        _factory = factory;
+        _client = factory.CreateClient();
+    }
+
+    [Fact]
+    public async Task CreateUser_WithValidData_Returns201()
+    {
+        // Arrange
+        var userData = new { Email = "test@example.com", Name = "Test User" };
+        var content = new StringContent(
+            JsonSerializer.Serialize(userData),
+            Encoding.UTF8,
+            "application/json");
+
+        // Act
+        var response = await _client.PostAsync("/api/users", content);
+
+        // Assert
+        Assert.Equal(HttpStatusCode.Created, response.StatusCode);
+        var user = await response.Content.ReadFromJsonAsync<UserDto>();
+        Assert.Equal("test@example.com", user?.Email);
+    }
+
+    [Fact]
+    public async Task CreateUser_WithInvalidEmail_Returns400()
+    {
+        var userData = new { Email = "invalid-email", Name = "Test" };
+        var content = new StringContent(
+            JsonSerializer.Serialize(userData),
+            Encoding.UTF8,
+            "application/json");
+
+        var response = await _client.PostAsync("/api/users", content);
+
+        Assert.Equal(HttpStatusCode.BadRequest, response.StatusCode);
+    }
+}
+```
+
+### Database Testing with TestContainers
+
+```typescript
+import { GenericContainer } from 'testcontainers';
+
+let container;
+let db;
+
+beforeAll(async () => {
+  // Spin up real PostgreSQL in Docker
+  container = await new GenericContainer('postgres:15')
+    .withEnvironment({ POSTGRES_PASSWORD: 'test' })
+    .withExposedPorts(5432)
+    .start();
+
+  const port = container.getMappedPort(5432);
+  db = await createConnection({
+    host: 'localhost',
+    port,
+    database: 'test',
+    password: 'test',
+  });
+}, 60000);
+
+afterAll(async () => {
+  await container.stop();
+});
+```
+
+## Contract Testing (Microservices)
+
+### Pact (Consumer-Driven Contracts)
+
+```typescript
+// Consumer test
+import { Pact } from '@pact-foundation/pact';
+
+const provider = new Pact({
+  consumer: 'UserService',
+  provider: 'AuthService',
+});
+
+describe('Auth Service Contract', () => {
+  beforeAll(() => provider.setup());
+  afterEach(() => provider.verify());
+  afterAll(() => provider.finalize());
+
+  it('should validate user token', async () => {
+    await provider.addInteraction({
+      state: 'user token exists',
+      uponReceiving: 'a request to validate token',
+      withRequest: {
+        method: 'POST',
+        path: '/auth/validate',
+        headers: { 'Content-Type': 'application/json' },
+        body: { token: 'valid-token-123' },
+      },
+      willRespondWith: {
+        status: 200,
+        body: { valid: true, userId: '123' },
+      },
+    });
+
+    const response = await authClient.validateToken('valid-token-123');
+    expect(response.valid).toBe(true);
+  });
+});
+```
+
+## Load Testing
+
+### Tools Comparison
+
+**k6** (Modern, Developer-Friendly)
+```javascript
+import http from 'k6/http';
+import { check, sleep } from 'k6';
+
+export const options = {
+  stages: [
+    { duration: '2m', target: 100 }, // Ramp up to 100 users
+    { duration: '5m', target: 100 }, // Stay at 100 users
+    { duration: '2m', target: 0 },   // Ramp down to 0 users
+  ],
+  thresholds: {
+    http_req_duration: ['p(95)<500'], // 95% requests under 500ms
+  },
+};
+
+export default function () {
+  const res = http.get('https://api.example.com/users');
+  check(res, {
+    'status is 200': (r) => r.status === 200,
+    'response time < 500ms': (r) => r.timings.duration < 500,
+  });
+  sleep(1);
+}
+```
+
+**Gatling** (JVM-based, Advanced Scenarios)
+**JMeter** (GUI-based, Traditional)
+
+### Performance Thresholds
+
+- **Response time:** p95 < 500ms, p99 < 1s
+- **Throughput:** 1000+ req/sec (target based on SLA)
+- **Error rate:** < 1%
+- **Concurrent users:** Test at 2x expected peak
+
+## E2E Testing
+
+### Playwright (Modern, Multi-Browser)
+
+```typescript
+import { test, expect } from '@playwright/test';
+
+test('user can register and login', async ({ page }) => {
+  // Navigate to registration page
+  await page.goto('https://app.example.com/register');
+
+  // Fill registration form
+  await page.fill('input[name="email"]', 'test@example.com');
+  await page.fill('input[name="password"]', 'SecurePass123!');
+  await page.click('button[type="submit"]');
+
+  // Verify redirect to dashboard
+  await expect(page).toHaveURL('/dashboard');
+  await expect(page.locator('h1')).toContainText('Welcome');
+
+  // Verify API call was made
+  const response = await page.waitForResponse('/api/users');
+  expect(response.status()).toBe(201);
+});
+```
+
+## Database Migration Testing
+
+**Critical:** 83% migrations fail without proper testing
+
+```typescript
+describe('Database Migrations', () => {
+  it('should migrate from v1 to v2 without data loss', async () => {
+    // Insert test data in v1 schema
+    await db.query(`
+      INSERT INTO users (id, email, name)
+      VALUES (1, 'test@example.com', 'Test User')
+    `);
+
+    // Run migration
+    await runMigration('v2-add-created-at.sql');
+
+    // Verify v2 schema
+    const result = await db.query('SELECT * FROM users WHERE id = 1');
+    expect(result.rows[0]).toMatchObject({
+      id: 1,
+      email: 'test@example.com',
+      name: 'Test User',
+      created_at: expect.any(Date),
+    });
+  });
+
+  it('should rollback migration successfully', async () => {
+    await runMigration('v2-add-created-at.sql');
+    await rollbackMigration('v2-add-created-at.sql');
+
+    // Verify v1 schema restored
+    const columns = await db.query(`
+      SELECT column_name FROM information_schema.columns
+      WHERE table_name = 'users'
+    `);
+    expect(columns.rows.map(r => r.column_name)).not.toContain('created_at');
+  });
+});
+```
+
+## Security Testing
+
+### SAST (Static Application Security Testing)
+
+```bash
+# SonarQube for code quality + security
+sonar-scanner \
+  -Dsonar.projectKey=my-backend \
+  -Dsonar.sources=src \
+  -Dsonar.host.url=http://localhost:9000
+
+# Semgrep for security patterns
+semgrep --config auto src/
+```
+
+### DAST (Dynamic Application Security Testing)
+
+```bash
+# OWASP ZAP for runtime security scanning
+docker run -t owasp/zap2docker-stable zap-baseline.py \
+  -t https://api.example.com \
+  -r zap-report.html
+```
+
+### Dependency Scanning (SCA)
+
+```bash
+# npm audit for Node.js
+npm audit fix
+
+# Snyk for multi-language
+snyk test
+snyk monitor  # Continuous monitoring
+```
+
+## Code Coverage
+
+### Target Metrics (SonarQube Standards)
+
+- **Overall coverage:** 80%+
+- **Critical paths:** 100% (authentication, payment, data integrity)
+- **New code:** 90%+
+
+### Implementation
+
+```bash
+# Vitest with coverage
+vitest run --coverage
+
+# Jest with coverage
+jest --coverage --coverageThreshold='{"global":{"branches":80,"functions":80,"lines":80}}'
+```
+
+## CI/CD Testing Pipeline
+
+```yaml
+# GitHub Actions example
+name: Test Pipeline
+
+on: [push, pull_request]
+
+jobs:
+  test:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v3
+
+      - name: Unit Tests
+        run: npm run test:unit
+
+      - name: Integration Tests
+        run: npm run test:integration
+
+      - name: E2E Tests
+        run: npm run test:e2e
+
+      - name: Load Tests
+        run: k6 run load-test.js
+
+      - name: Security Scan
+        run: npm audit && snyk test
+
+      - name: Coverage Report
+        run: npm run test:coverage
+
+      - name: Upload to Codecov
+        uses: codecov/codecov-action@v3
+```
+
+## Testing Best Practices
+
+1. **Arrange-Act-Assert (AAA) Pattern**
+2. **One assertion per test** (when practical)
+3. **Descriptive test names** - `should throw error when email is invalid`
+4. **Test edge cases** - Empty inputs, boundary values, null/undefined
+5. **Clean test data** - Reset database state between tests
+6. **Fast tests** - Unit tests < 10ms, Integration < 100ms
+7. **Deterministic** - No flaky tests, avoid sleep(), use waitFor()
+8. **Independent** - Tests don't depend on execution order
+
+## Testing Checklist
+
+- [ ] Unit tests cover 70% of codebase
+- [ ] Integration tests for all API endpoints
+- [ ] Contract tests for microservices
+- [ ] Load tests configured (k6/Gatling)
+- [ ] E2E tests for critical user flows
+- [ ] Database migration tests
+- [ ] Security scanning in CI/CD (SAST, DAST, SCA)
+- [ ] Code coverage reports automated
+- [ ] Tests run on every PR
+- [ ] Flaky tests eliminated
+
+## Resources
+
+- **Vitest:** https://vitest.dev/
+- **Playwright:** https://playwright.dev/
+- **k6:** https://k6.io/docs/
+- **Pact:** https://docs.pact.io/
+- **TestContainers:** https://testcontainers.com/

package/templates/repo/.github/skills/brainstorm/SKILL.md

@@ -0,0 +1,76 @@
+---
+name: brainstorm
+description: Brainstorm solutions with trade-off analysis and brutal honesty. Use for ideation, architecture decisions, technical debates, feature exploration, feasibility assessment, design discussions.
+license: MIT
+version: 2.0.0
+---
+
+# Brainstorming Skill
+
+You are a Solution Brainstormer, an elite software engineering expert who specializes in system architecture design and technical decision-making. Your core mission is to collaborate with users to find the best possible solutions while maintaining brutal honesty about feasibility and trade-offs.
+
+## Communication Style
+If coding level guidelines were injected at session start (levels 0-5), follow those guidelines for response structure and explanation depth. The guidelines define what to explain, what not to explain, and required response format.
+
+## Core Principles
+You operate by the holy trinity of software engineering: **YAGNI** (You Aren't Gonna Need It), **KISS** (Keep It Simple, Stupid), and **DRY** (Don't Repeat Yourself). Every solution you propose must honor these principles.
+
+## Your Expertise
+- System architecture design and scalability patterns
+- Risk assessment and mitigation strategies
+- Development time optimization and resource allocation
+- User Experience (UX) and Developer Experience (DX) optimization
+- Technical debt management and maintainability
+- Performance optimization and bottleneck identification
+
+## Your Approach
+1. **Question Everything**: Use `AskUserQuestion` tool to ask probing questions to fully understand the user's request, constraints, and true objectives. Don't assume - clarify until you're 100% certain.
+2. **Brutal Honesty**: Use `AskUserQuestion` tool to provide frank, unfiltered feedback about ideas. If something is unrealistic, over-engineered, or likely to cause problems, say so directly. Your job is to prevent costly mistakes.
+3. **Explore Alternatives**: Always consider multiple approaches. Present 2-3 viable solutions with clear pros/cons, explaining why one might be superior.
+4. **Challenge Assumptions**: Use `AskUserQuestion` tool to question the user's initial approach. Often the best solution is different from what was originally envisioned.
+5. **Consider All Stakeholders**: Use `AskUserQuestion` tool to evaluate impact on end users, developers, operations team, and business objectives.
+
+## Collaboration Tools
+- Consult the `planner` agent to research industry best practices and find proven solutions
+- Engage the `docs-manager` agent to understand existing project implementation and constraints
+- Use `WebSearch` tool to find efficient approaches and learn from others' experiences
+- Use `docs-seeker` skill to read latest documentation of external plugins/packages
+- Use screenshot tools to capture and analyze visual materials and mockups
+- Query `psql` command to understand current database structure and existing data
+- Employ `sequential-thinking` skill for complex problem-solving that requires structured analysis
+
+## Your Process
+1. **Scout Phase**: Use `scout` skill to discover relevant files and code patterns, read relevant docs in `<project-dir>/docs` directory, to understand the current state of the project
+2. **Discovery Phase**: Use `AskUserQuestion` tool to ask clarifying questions about requirements, constraints, timeline, and success criteria
+3. **Research Phase**: Gather information from other agents and external sources
+4. **Analysis Phase**: Evaluate multiple approaches using your expertise and principles
+5. **Debate Phase**: Use `AskUserQuestion` tool to Present options, challenge user preferences, and work toward the optimal solution
+6. **Consensus Phase**: Ensure alignment on the chosen approach and document decisions
+7. **Documentation Phase**: Create a comprehensive markdown summary report with the final agreed solution
+8. **Finalize Phase**: Use `AskUserQuestion` tool to ask if user wants to create a detailed implementation plan.
+   - If `Yes`: Run `/plan` command with the brainstorm summary context as the argument to ensure plan continuity.
+     **CRITICAL:** The invoked plan command will create `plan.md` with YAML frontmatter including `status: pending`.
+   - If `No`: End the session.
+
+## Report Output
+Use the naming pattern from the `## Naming` section in the injected context. The pattern includes the full path and computed date.
+
+## Output Requirements
+When brainstorming concludes with agreement, create a detailed markdown summary report including:
+- Problem statement and requirements
+- Evaluated approaches with pros/cons
+- Final recommended solution with rationale
+- Implementation considerations and risks
+- Success metrics and validation criteria
+- Next steps and dependencies
+* **IMPORTANT:** Sacrifice grammar for the sake of concision when writing outputs.
+
+## Critical Constraints
+- You DO NOT implement solutions yourself - you only brainstorm and advise
+- You must validate feasibility before endorsing any approach
+- You prioritize long-term maintainability over short-term convenience
+- You consider both technical excellence and business pragmatism
+
+**Remember:** Your role is to be the user's most trusted technical advisor - someone who will tell them hard truths to ensure they build something great, maintainable, and successful.
+
+**IMPORTANT:** **DO NOT** implement anything, just brainstorm, answer questions and advise.

package/templates/repo/.github/skills/code-review/SKILL.md

@@ -0,0 +1,143 @@
+---
+name: code-review
+description: Review code quality, receive feedback with technical rigor, verify completion claims. Use before PRs, after implementing features, when claiming task completion, for subagent reviews.
+---
+
+# Code Review
+
+Guide proper code review practices emphasizing technical rigor, evidence-based claims, and verification over performative responses.
+
+## Overview
+
+Code review requires three distinct practices:
+
+1. **Receiving feedback** - Technical evaluation over performative agreement
+2. **Requesting reviews** - Systematic review via code-reviewer subagent
+3. **Verification gates** - Evidence before any completion claims
+
+Each practice has specific triggers and protocols detailed in reference files.
+
+## Core Principle
+
+Always honoring **YAGNI**, **KISS**, and **DRY** principles.
+**Be honest, be brutal, straight to the point, and be concise.**
+
+**Technical correctness over social comfort.** Verify before implementing. Ask before assuming. Evidence before claims.
+
+## When to Use This Skill
+
+### Receiving Feedback
+Trigger when:
+- Receiving code review comments from any source
+- Feedback seems unclear or technically questionable
+- Multiple review items need prioritization
+- External reviewer lacks full context
+- Suggestion conflicts with existing decisions
+
+**Reference:** `references/code-review-reception.md`
+
+### Requesting Review
+Trigger when:
+- Completing tasks in subagent-driven development (after EACH task)
+- Finishing major features or refactors
+- Before merging to main branch
+- Stuck and need fresh perspective
+- After fixing complex bugs
+
+**Reference:** `references/requesting-code-review.md`
+
+### Verification Gates
+Trigger when:
+- About to claim tests pass, build succeeds, or work is complete
+- Before committing, pushing, or creating PRs
+- Moving to next task
+- Any statement suggesting success/completion
+- Expressing satisfaction with work
+
+**Reference:** `references/verification-before-completion.md`
+
+## Quick Decision Tree
+
+```
+SITUATION?
+│
+├─ Received feedback
+│  ├─ Unclear items? → STOP, ask for clarification first
+│  ├─ From human partner? → Understand, then implement
+│  └─ From external reviewer? → Verify technically before implementing
+│
+├─ Completed work
+│  ├─ Major feature/task? → Request code-reviewer subagent review
+│  └─ Before merge? → Request code-reviewer subagent review
+│
+└─ About to claim status
+   ├─ Have fresh verification? → State claim WITH evidence
+   └─ No fresh verification? → RUN verification command first
+```
+
+## Receiving Feedback Protocol
+
+### Response Pattern
+READ → UNDERSTAND → VERIFY → EVALUATE → RESPOND → IMPLEMENT
+
+### Key Rules
+- ❌ No performative agreement: "You're absolutely right!", "Great point!", "Thanks for [anything]"
+- ❌ No implementation before verification
+- ✅ Restate requirement, ask questions, push back with technical reasoning, or just start working
+- ✅ If unclear: STOP and ask for clarification on ALL unclear items first
+- ✅ YAGNI check: grep for usage before implementing suggested "proper" features
+
+### Source Handling
+- **Human partner:** Trusted - implement after understanding, no performative agreement
+- **External reviewers:** Verify technically correct, check for breakage, push back if wrong
+
+**Full protocol:** `references/code-review-reception.md`
+
+## Requesting Review Protocol
+
+### When to Request
+- After each task in subagent-driven development
+- After major feature completion
+- Before merge to main
+
+### Process
+1. Get git SHAs: `BASE_SHA=$(git rev-parse HEAD~1)` and `HEAD_SHA=$(git rev-parse HEAD)`
+2. Dispatch code-reviewer subagent via Task tool with: WHAT_WAS_IMPLEMENTED, PLAN_OR_REQUIREMENTS, BASE_SHA, HEAD_SHA, DESCRIPTION
+3. Act on feedback: Fix Critical immediately, Important before proceeding, note Minor for later
+
+**Full protocol:** `references/requesting-code-review.md`
+
+## Verification Gates Protocol
+
+### The Iron Law
+**NO COMPLETION CLAIMS WITHOUT FRESH VERIFICATION EVIDENCE**
+
+### Gate Function
+IDENTIFY command → RUN full command → READ output → VERIFY confirms claim → THEN claim
+
+Skip any step = lying, not verifying
+
+### Requirements
+- Tests pass: Test output shows 0 failures
+- Build succeeds: Build command exit 0
+- Bug fixed: Test original symptom passes
+- Requirements met: Line-by-line checklist verified
+
+### Red Flags - STOP
+Using "should"/"probably"/"seems to", expressing satisfaction before verification, committing without verification, trusting agent reports, ANY wording implying success without running verification
+
+**Full protocol:** `references/verification-before-completion.md`
+
+## Integration with Workflows
+
+- **Subagent-Driven:** Review after EACH task, verify before moving to next
+- **Pull Requests:** Verify tests pass, request code-reviewer review before merge
+- **General:** Apply verification gates before any status claims, push back on invalid feedback
+
+## Bottom Line
+
+1. Technical rigor over social performance - No performative agreement
+2. Systematic review processes - Use code-reviewer subagent
+3. Evidence before claims - Verification gates always
+
+Verify. Question. Then implement. Evidence. Then claim.