@heyai-rules/pilo-masterkit 1.2.2 → 3.1.0

package/.agent/workflows/test-coverage.md

@@ -1,69 +1,69 @@
-# Test Coverage
-
-Analyze test coverage, identify gaps, and generate missing tests to reach 80%+ coverage.
-
-## Step 1: Detect Test Framework
-
-| Indicator | Coverage Command |
-|-----------|-----------------|
-| `jest.config.*` or `package.json` jest | `npx jest --coverage --coverageReporters=json-summary` |
-| `vitest.config.*` | `npx vitest run --coverage` |
-| `pytest.ini` / `pyproject.toml` pytest | `pytest --cov=src --cov-report=json` |
-| `Cargo.toml` | `cargo llvm-cov --json` |
-| `pom.xml` with JaCoCo | `mvn test jacoco:report` |
-| `go.mod` | `go test -coverprofile=coverage.out ./...` |
-
-## Step 2: Analyze Coverage Report
-
-1. Run the coverage command
-2. Parse the output (JSON summary or terminal output)
-3. List files **below 80% coverage**, sorted worst-first
-4. For each under-covered file, identify:
-   - Untested functions or methods
-   - Missing branch coverage (if/else, switch, error paths)
-   - Dead code that inflates the denominator
-
-## Step 3: Generate Missing Tests
-
-For each under-covered file, generate tests following this priority:
-
-1. **Happy path** — Core functionality with valid inputs
-2. **Error handling** — Invalid inputs, missing data, network failures
-3. **Edge cases** — Empty arrays, null/undefined, boundary values (0, -1, MAX_INT)
-4. **Branch coverage** — Each if/else, switch case, ternary
-
-### Test Generation Rules
-
-- Place tests adjacent to source: `foo.ts` → `foo.test.ts` (or project convention)
-- Use existing test patterns from the project (import style, assertion library, mocking approach)
-- Mock external dependencies (database, APIs, file system)
-- Each test should be independent — no shared mutable state between tests
-- Name tests descriptively: `test_create_user_with_duplicate_email_returns_409`
-
-## Step 4: Verify
-
-1. Run the full test suite — all tests must pass
-2. Re-run coverage — verify improvement
-3. If still below 80%, repeat Step 3 for remaining gaps
-
-## Step 5: Report
-
-Show before/after comparison:
-
-```
-Coverage Report
-──────────────────────────────
-File                   Before  After
-src/services/auth.ts   45%     88%
-src/utils/validation.ts 32%    82%
-──────────────────────────────
-Overall:               67%     84%  ✅
-```
-
-## Focus Areas
-
-- Functions with complex branching (high cyclomatic complexity)
-- Error handlers and catch blocks
-- Utility functions used across the codebase
-- API endpoint handlers (request → response flow)
-- Edge cases: null, undefined, empty string, empty array, zero, negative numbers
+# Test Coverage
+
+Analyze test coverage, identify gaps, and generate missing tests to reach 80%+ coverage.
+
+## Step 1: Detect Test Framework
+
+| Indicator | Coverage Command |
+|-----------|-----------------|
+| `jest.config.*` or `package.json` jest | `npx jest --coverage --coverageReporters=json-summary` |
+| `vitest.config.*` | `npx vitest run --coverage` |
+| `pytest.ini` / `pyproject.toml` pytest | `pytest --cov=src --cov-report=json` |
+| `Cargo.toml` | `cargo llvm-cov --json` |
+| `pom.xml` with JaCoCo | `mvn test jacoco:report` |
+| `go.mod` | `go test -coverprofile=coverage.out ./...` |
+
+## Step 2: Analyze Coverage Report
+
+1. Run the coverage command
+2. Parse the output (JSON summary or terminal output)
+3. List files **below 80% coverage**, sorted worst-first
+4. For each under-covered file, identify:
+   - Untested functions or methods
+   - Missing branch coverage (if/else, switch, error paths)
+   - Dead code that inflates the denominator
+
+## Step 3: Generate Missing Tests
+
+For each under-covered file, generate tests following this priority:
+
+1. **Happy path** — Core functionality with valid inputs
+2. **Error handling** — Invalid inputs, missing data, network failures
+3. **Edge cases** — Empty arrays, null/undefined, boundary values (0, -1, MAX_INT)
+4. **Branch coverage** — Each if/else, switch case, ternary
+
+### Test Generation Rules
+
+- Place tests adjacent to source: `foo.ts` → `foo.test.ts` (or project convention)
+- Use existing test patterns from the project (import style, assertion library, mocking approach)
+- Mock external dependencies (database, APIs, file system)
+- Each test should be independent — no shared mutable state between tests
+- Name tests descriptively: `test_create_user_with_duplicate_email_returns_409`
+
+## Step 4: Verify
+
+1. Run the full test suite — all tests must pass
+2. Re-run coverage — verify improvement
+3. If still below 80%, repeat Step 3 for remaining gaps
+
+## Step 5: Report
+
+Show before/after comparison:
+
+```
+Coverage Report
+──────────────────────────────
+File                   Before  After
+src/services/auth.ts   45%     88%
+src/utils/validation.ts 32%    82%
+──────────────────────────────
+Overall:               67%     84%  PASS:
+```
+
+## Focus Areas
+
+- Functions with complex branching (high cyclomatic complexity)
+- Error handlers and catch blocks
+- Utility functions used across the codebase
+- API endpoint handlers (request → response flow)
+- Edge cases: null, undefined, empty string, empty array, zero, negative numbers

package/.agent/workflows/update-codemaps.md

@@ -1,72 +1,72 @@
-# Update Codemaps
-
-Analyze the codebase structure and generate token-lean architecture documentation.
-
-## Step 1: Scan Project Structure
-
-1. Identify the project type (monorepo, single app, library, microservice)
-2. Find all source directories (src/, lib/, app/, packages/)
-3. Map entry points (main.ts, index.ts, app.py, main.go, etc.)
-
-## Step 2: Generate Codemaps
-
-Create or update codemaps in `docs/CODEMAPS/` (or `.reports/codemaps/`):
-
-| File | Contents |
-|------|----------|
-| `architecture.md` | High-level system diagram, service boundaries, data flow |
-| `backend.md` | API routes, middleware chain, service → repository mapping |
-| `frontend.md` | Page tree, component hierarchy, state management flow |
-| `data.md` | Database tables, relationships, migration history |
-| `dependencies.md` | External services, third-party integrations, shared libraries |
-
-### Codemap Format
-
-Each codemap should be token-lean — optimized for AI context consumption:
-
-```markdown
-# Backend Architecture
-
-## Routes
-POST /api/users → UserController.create → UserService.create → UserRepo.insert
-GET  /api/users/:id → UserController.get → UserService.findById → UserRepo.findById
-
-## Key Files
-src/services/user.ts (business logic, 120 lines)
-src/repos/user.ts (database access, 80 lines)
-
-## Dependencies
-- PostgreSQL (primary data store)
-- Redis (session cache, rate limiting)
-- Stripe (payment processing)
-```
-
-## Step 3: Diff Detection
-
-1. If previous codemaps exist, calculate the diff percentage
-2. If changes > 30%, show the diff and request user approval before overwriting
-3. If changes <= 30%, update in place
-
-## Step 4: Add Metadata
-
-Add a freshness header to each codemap:
-
-```markdown
-<!-- Generated: 2026-02-11 | Files scanned: 142 | Token estimate: ~800 -->
-```
-
-## Step 5: Save Analysis Report
-
-Write a summary to `.reports/codemap-diff.txt`:
-- Files added/removed/modified since last scan
-- New dependencies detected
-- Architecture changes (new routes, new services, etc.)
-- Staleness warnings for docs not updated in 90+ days
-
-## Tips
-
-- Focus on **high-level structure**, not implementation details
-- Prefer **file paths and function signatures** over full code blocks
-- Keep each codemap under **1000 tokens** for efficient context loading
-- Use ASCII diagrams for data flow instead of verbose descriptions
-- Run after major feature additions or refactoring sessions
+# Update Codemaps
+
+Analyze the codebase structure and generate token-lean architecture documentation.
+
+## Step 1: Scan Project Structure
+
+1. Identify the project type (monorepo, single app, library, microservice)
+2. Find all source directories (src/, lib/, app/, packages/)
+3. Map entry points (main.ts, index.ts, app.py, main.go, etc.)
+
+## Step 2: Generate Codemaps
+
+Create or update codemaps in `docs/CODEMAPS/` (or `.reports/codemaps/`):
+
+| File | Contents |
+|------|----------|
+| `architecture.md` | High-level system diagram, service boundaries, data flow |
+| `backend.md` | API routes, middleware chain, service → repository mapping |
+| `frontend.md` | Page tree, component hierarchy, state management flow |
+| `data.md` | Database tables, relationships, migration history |
+| `dependencies.md` | External services, third-party integrations, shared libraries |
+
+### Codemap Format
+
+Each codemap should be token-lean — optimized for AI context consumption:
+
+```markdown
+# Backend Architecture
+
+## Routes
+POST /api/users → UserController.create → UserService.create → UserRepo.insert
+GET  /api/users/:id → UserController.get → UserService.findById → UserRepo.findById
+
+## Key Files
+src/services/user.ts (business logic, 120 lines)
+src/repos/user.ts (database access, 80 lines)
+
+## Dependencies
+- PostgreSQL (primary data store)
+- Redis (session cache, rate limiting)
+- Stripe (payment processing)
+```
+
+## Step 3: Diff Detection
+
+1. If previous codemaps exist, calculate the diff percentage
+2. If changes > 30%, show the diff and request user approval before overwriting
+3. If changes <= 30%, update in place
+
+## Step 4: Add Metadata
+
+Add a freshness header to each codemap:
+
+```markdown
+<!-- Generated: 2026-02-11 | Files scanned: 142 | Token estimate: ~800 -->
+```
+
+## Step 5: Save Analysis Report
+
+Write a summary to `.reports/codemap-diff.txt`:
+- Files added/removed/modified since last scan
+- New dependencies detected
+- Architecture changes (new routes, new services, etc.)
+- Staleness warnings for docs not updated in 90+ days
+
+## Tips
+
+- Focus on **high-level structure**, not implementation details
+- Prefer **file paths and function signatures** over full code blocks
+- Keep each codemap under **1000 tokens** for efficient context loading
+- Use ASCII diagrams for data flow instead of verbose descriptions
+- Run after major feature additions or refactoring sessions

package/.agent/workflows/update-docs.md

@@ -1,84 +1,84 @@
-# Update Documentation
-
-Sync documentation with the codebase, generating from source-of-truth files.
-
-## Step 1: Identify Sources of Truth
-
-| Source | Generates |
-|--------|-----------|
-| `package.json` scripts | Available commands reference |
-| `.env.example` | Environment variable documentation |
-| `openapi.yaml` / route files | API endpoint reference |
-| Source code exports | Public API documentation |
-| `Dockerfile` / `docker-compose.yml` | Infrastructure setup docs |
-
-## Step 2: Generate Script Reference
-
-1. Read `package.json` (or `Makefile`, `Cargo.toml`, `pyproject.toml`)
-2. Extract all scripts/commands with their descriptions
-3. Generate a reference table:
-
-```markdown
-| Command | Description |
-|---------|-------------|
-| `npm run dev` | Start development server with hot reload |
-| `npm run build` | Production build with type checking |
-| `npm test` | Run test suite with coverage |
-```
-
-## Step 3: Generate Environment Documentation
-
-1. Read `.env.example` (or `.env.template`, `.env.sample`)
-2. Extract all variables with their purposes
-3. Categorize as required vs optional
-4. Document expected format and valid values
-
-```markdown
-| Variable | Required | Description | Example |
-|----------|----------|-------------|---------|
-| `DATABASE_URL` | Yes | PostgreSQL connection string | `postgres://user:pass@host:5432/db` |
-| `LOG_LEVEL` | No | Logging verbosity (default: info) | `debug`, `info`, `warn`, `error` |
-```
-
-## Step 4: Update Contributing Guide
-
-Generate or update `docs/CONTRIBUTING.md` with:
-- Development environment setup (prerequisites, install steps)
-- Available scripts and their purposes
-- Testing procedures (how to run, how to write new tests)
-- Code style enforcement (linter, formatter, pre-commit hooks)
-- PR submission checklist
-
-## Step 5: Update Runbook
-
-Generate or update `docs/RUNBOOK.md` with:
-- Deployment procedures (step-by-step)
-- Health check endpoints and monitoring
-- Common issues and their fixes
-- Rollback procedures
-- Alerting and escalation paths
-
-## Step 6: Staleness Check
-
-1. Find documentation files not modified in 90+ days
-2. Cross-reference with recent source code changes
-3. Flag potentially outdated docs for manual review
-
-## Step 7: Show Summary
-
-```
-Documentation Update
-──────────────────────────────
-Updated:  docs/CONTRIBUTING.md (scripts table)
-Updated:  docs/ENV.md (3 new variables)
-Flagged:  docs/DEPLOY.md (142 days stale)
-Skipped:  docs/API.md (no changes detected)
-──────────────────────────────
-```
-
-## Rules
-
-- **Single source of truth**: Always generate from code, never manually edit generated sections
-- **Preserve manual sections**: Only update generated sections; leave hand-written prose intact
-- **Mark generated content**: Use `<!-- AUTO-GENERATED -->` markers around generated sections
-- **Don't create docs unprompted**: Only create new doc files if the command explicitly requests it
+# Update Documentation
+
+Sync documentation with the codebase, generating from source-of-truth files.
+
+## Step 1: Identify Sources of Truth
+
+| Source | Generates |
+|--------|-----------|
+| `package.json` scripts | Available commands reference |
+| `.env.example` | Environment variable documentation |
+| `openapi.yaml` / route files | API endpoint reference |
+| Source code exports | Public API documentation |
+| `Dockerfile` / `docker-compose.yml` | Infrastructure setup docs |
+
+## Step 2: Generate Script Reference
+
+1. Read `package.json` (or `Makefile`, `Cargo.toml`, `pyproject.toml`)
+2. Extract all scripts/commands with their descriptions
+3. Generate a reference table:
+
+```markdown
+| Command | Description |
+|---------|-------------|
+| `npm run dev` | Start development server with hot reload |
+| `npm run build` | Production build with type checking |
+| `npm test` | Run test suite with coverage |
+```
+
+## Step 3: Generate Environment Documentation
+
+1. Read `.env.example` (or `.env.template`, `.env.sample`)
+2. Extract all variables with their purposes
+3. Categorize as required vs optional
+4. Document expected format and valid values
+
+```markdown
+| Variable | Required | Description | Example |
+|----------|----------|-------------|---------|
+| `DATABASE_URL` | Yes | PostgreSQL connection string | `postgres://user:pass@host:5432/db` |
+| `LOG_LEVEL` | No | Logging verbosity (default: info) | `debug`, `info`, `warn`, `error` |
+```
+
+## Step 4: Update Contributing Guide
+
+Generate or update `docs/CONTRIBUTING.md` with:
+- Development environment setup (prerequisites, install steps)
+- Available scripts and their purposes
+- Testing procedures (how to run, how to write new tests)
+- Code style enforcement (linter, formatter, pre-commit hooks)
+- PR submission checklist
+
+## Step 5: Update Runbook
+
+Generate or update `docs/RUNBOOK.md` with:
+- Deployment procedures (step-by-step)
+- Health check endpoints and monitoring
+- Common issues and their fixes
+- Rollback procedures
+- Alerting and escalation paths
+
+## Step 6: Staleness Check
+
+1. Find documentation files not modified in 90+ days
+2. Cross-reference with recent source code changes
+3. Flag potentially outdated docs for manual review
+
+## Step 7: Show Summary
+
+```
+Documentation Update
+──────────────────────────────
+Updated:  docs/CONTRIBUTING.md (scripts table)
+Updated:  docs/ENV.md (3 new variables)
+Flagged:  docs/DEPLOY.md (142 days stale)
+Skipped:  docs/API.md (no changes detected)
+──────────────────────────────
+```
+
+## Rules
+
+- **Single source of truth**: Always generate from code, never manually edit generated sections
+- **Preserve manual sections**: Only update generated sections; leave hand-written prose intact
+- **Mark generated content**: Use `<!-- AUTO-GENERATED -->` markers around generated sections
+- **Don't create docs unprompted**: Only create new doc files if the command explicitly requests it

package/.agent/workflows/verify.md

@@ -1,59 +1,23 @@
-# Verification Command
-
-Run comprehensive verification on current codebase state.
-
-## Instructions
-
-Execute verification in this exact order:
-
-1. **Build Check**
-   - Run the build command for this project
-   - If it fails, report errors and STOP
-
-2. **Type Check**
-   - Run TypeScript/type checker
-   - Report all errors with file:line
-
-3. **Lint Check**
-   - Run linter
-   - Report warnings and errors
-
-4. **Test Suite**
-   - Run all tests
-   - Report pass/fail count
-   - Report coverage percentage
-
-5. **Console.log Audit**
-   - Search for console.log in source files
-   - Report locations
-
-6. **Git Status**
-   - Show uncommitted changes
-   - Show files modified since last commit
-
-## Output
-
-Produce a concise verification report:
-
-```
-VERIFICATION: [PASS/FAIL]
-
-Build:    [OK/FAIL]
-Types:    [OK/X errors]
-Lint:     [OK/X issues]
-Tests:    [X/Y passed, Z% coverage]
-Secrets:  [OK/X found]
-Logs:     [OK/X console.logs]
-
-Ready for PR: [YES/NO]
-```
-
-If any critical issues, list them with fix suggestions.
-
-## Arguments
-
-$ARGUMENTS can be:
-- `quick` - Only build + types
-- `full` - All checks (default)
-- `pre-commit` - Checks relevant for commits
-- `pre-pr` - Full checks plus security scan
+---
+description: Legacy slash-entry shim for the verification-loop skill. Prefer the skill directly.
+---
+
+# Verification Command (Legacy Shim)
+
+Use this only if you still invoke `/verify`. The maintained workflow lives in `skills/verification-loop/SKILL.md`.
+
+## Canonical Surface
+
+- Prefer the `verification-loop` skill directly.
+- Keep this file only as a compatibility entry point.
+
+## Arguments
+
+`$ARGUMENTS`
+
+## Delegation
+
+Apply the `verification-loop` skill.
+- Choose the right verification depth for the user's requested mode.
+- Run build, types, lint, tests, security/log checks, and diff review in the right order for the current repo.
+- Report only the verdicts and blockers instead of maintaining a second verification checklist here.