@heyai-rules/pilo-masterkit 2.1.0 → 3.1.0

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,23 +1,23 @@
----
-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.
+---
+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.