@phi-code-admin/phi-code 0.56.3 → 0.56.5

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@phi-code-admin/phi-code",
-	"version": "0.56.3",
+	"version": "0.56.5",
 	"description": "Coding agent CLI with read, bash, edit, write tools and session management",
 	"type": "module",
 	"piConfig": {
@@ -24,6 +24,7 @@
 	},
 	"files": [
 		"dist",
+		"skills",
 		"extensions",
 		"README.md",
 		"LICENSE",

package/skills/api-design/SKILL.md

@@ -0,0 +1,44 @@
+# API Design Skill
+
+## When to use
+Designing REST APIs, GraphQL schemas, or any HTTP endpoints.
+
+## REST Conventions
+- `GET /users` — List users
+- `GET /users/:id` — Get user by ID
+- `POST /users` — Create user
+- `PUT /users/:id` — Replace user
+- `PATCH /users/:id` — Update user fields
+- `DELETE /users/:id` — Delete user
+
+## Status Codes
+- `200` OK — Success
+- `201` Created — Resource created
+- `204` No Content — Success, no body
+- `400` Bad Request — Invalid input
+- `401` Unauthorized — No/invalid auth
+- `403` Forbidden — Auth OK but no permission
+- `404` Not Found — Resource doesn't exist
+- `409` Conflict — Duplicate/conflict
+- `422` Unprocessable — Validation failed
+- `429` Too Many Requests — Rate limited
+- `500` Internal Error — Server bug
+
+## Response Format
+```json
+{
+  "data": { ... },
+  "meta": { "page": 1, "total": 42 },
+  "errors": [{ "code": "VALIDATION", "message": "Email required", "field": "email" }]
+}
+```
+
+## Best Practices
+- Version your API: `/api/v1/users`
+- Use pagination: `?page=1&limit=20`
+- Filter: `?status=active&role=admin`
+- Sort: `?sort=-created_at` (prefix `-` for descending)
+- Rate limit all endpoints
+- Validate all inputs with schemas (Zod, Joi)
+- Use CORS properly
+- Document with OpenAPI/Swagger

package/skills/coding-standards/SKILL.md

@@ -0,0 +1,37 @@
+# Coding Standards Skill
+
+## When to use
+When writing, reviewing, or refactoring code in any language.
+
+## TypeScript/JavaScript
+- Use `const` by default, `let` when reassignment needed, never `var`
+- Prefer `async/await` over raw Promises
+- Use TypeScript strict mode
+- Naming: `camelCase` variables/functions, `PascalCase` types/classes, `UPPER_SNAKE` constants
+- Prefer named exports over default exports
+- Handle errors: never swallow exceptions silently
+- Validate inputs at API boundaries
+
+## Python
+- Follow PEP 8
+- Type hints on all functions
+- Use dataclasses or Pydantic for structured data
+- `with` statements for resource management
+- List comprehensions over map/filter where readable
+
+## General Principles
+- DRY but don't over-abstract (Rule of Three)
+- Functions: single responsibility, <30 lines ideally
+- Comments: explain WHY, not WHAT
+- No magic numbers: use named constants
+- Fail fast: validate early, return early
+- Prefer composition over inheritance
+
+## Code Review Checklist
+- [ ] Types are correct and complete
+- [ ] Error handling is proper
+- [ ] No security vulnerabilities (injection, XSS, etc.)
+- [ ] Tests cover the changes
+- [ ] No unnecessary complexity
+- [ ] Names are clear and descriptive
+- [ ] No hardcoded secrets or credentials

package/skills/database/SKILL.md

@@ -0,0 +1,52 @@
+# Database Skill
+
+## When to use
+SQL queries, schema design, migrations, query optimization.
+
+## Schema Design
+- Use UUIDs for public-facing IDs, integers for internal
+- Always add `created_at` and `updated_at` timestamps
+- Use `NOT NULL` by default, allow NULL only when needed
+- Index foreign keys and frequently queried columns
+- Use enums or lookup tables for fixed sets of values
+
+## PostgreSQL
+```sql
+-- Create table with best practices
+CREATE TABLE users (
+  id UUID PRIMARY KEY DEFAULT gen_random_uuid(),
+  email VARCHAR(255) UNIQUE NOT NULL,
+  name VARCHAR(255) NOT NULL,
+  role VARCHAR(50) NOT NULL DEFAULT 'user',
+  created_at TIMESTAMPTZ NOT NULL DEFAULT NOW(),
+  updated_at TIMESTAMPTZ NOT NULL DEFAULT NOW()
+);
+
+-- Index for common queries
+CREATE INDEX idx_users_email ON users(email);
+CREATE INDEX idx_users_role ON users(role);
+
+-- Trigger for updated_at
+CREATE OR REPLACE FUNCTION update_updated_at()
+RETURNS TRIGGER AS $$
+BEGIN NEW.updated_at = NOW(); RETURN NEW; END;
+$$ LANGUAGE plpgsql;
+
+CREATE TRIGGER users_updated_at
+  BEFORE UPDATE ON users
+  FOR EACH ROW EXECUTE FUNCTION update_updated_at();
+```
+
+## Query Optimization
+- Use `EXPLAIN ANALYZE` to understand query plans
+- Index columns used in WHERE, JOIN, ORDER BY
+- Avoid `SELECT *` — select only needed columns
+- Use pagination (LIMIT/OFFSET or cursor-based)
+- Use `pg_trgm` for fuzzy text search
+- Use connection pooling (PgBouncer)
+
+## Migrations
+- Always write both up and down migrations
+- Never modify a deployed migration — create a new one
+- Test migrations on a copy of production data
+- Backup before running migrations in production

package/skills/devops/SKILL.md

@@ -0,0 +1,36 @@
+# DevOps Skill
+
+## When to use
+Docker, CI/CD, deployment, monitoring, infrastructure tasks.
+
+## Docker
+- Always use multi-stage builds for production
+- Pin image versions (never use `latest` in production)
+- Use `.dockerignore` to reduce context
+- Health checks: `HEALTHCHECK CMD curl -f http://localhost:PORT/health`
+- Non-root user: `USER node` or `USER 1000`
+- Use named volumes for persistence
+- Compose: separate dev and prod configs
+
+## CI/CD
+- GitHub Actions: `.github/workflows/`
+- Pipeline: lint → test → build → deploy
+- Cache dependencies between runs
+- Use environment secrets, never hardcode
+- Branch protection rules on main
+
+## Monitoring
+- Health endpoint: `GET /health` → `{ status: "ok", uptime: ... }`
+- Structured logging (JSON)
+- Error tracking (Sentry, etc.)
+- Resource monitoring (CPU, memory, disk)
+
+## Troubleshooting
+```bash
+docker compose logs -f <service>   # Live logs
+docker stats                        # Resource usage
+docker system df                    # Disk usage
+docker exec -it <container> sh      # Shell access
+ss -tlnp                            # Open ports
+journalctl -u <service> -f          # Systemd logs
+```

package/skills/docker-ops/SKILL.md

@@ -0,0 +1,55 @@
+# Docker Operations Skill
+
+## When to use
+Writing Dockerfiles, docker-compose configs, debugging containers.
+
+## Dockerfile Best Practices
+```dockerfile
+# Multi-stage build
+FROM node:22-alpine AS builder
+WORKDIR /app
+COPY package*.json ./
+RUN npm ci --only=production
+COPY . .
+RUN npm run build
+
+FROM node:22-alpine
+WORKDIR /app
+COPY --from=builder /app/dist ./dist
+COPY --from=builder /app/node_modules ./node_modules
+USER node
+EXPOSE 3000
+HEALTHCHECK CMD wget -qO- http://localhost:3000/health || exit 1
+CMD ["node", "dist/index.js"]
+```
+
+## Docker Compose
+```yaml
+services:
+  app:
+    build: .
+    ports: ["3000:3000"]
+    environment:
+      - NODE_ENV=production
+    volumes:
+      - app-data:/app/data
+    restart: unless-stopped
+    healthcheck:
+      test: ["CMD", "wget", "-qO-", "http://localhost:3000/health"]
+      interval: 30s
+      timeout: 10s
+      retries: 3
+
+volumes:
+  app-data:
+```
+
+## Debugging
+```bash
+docker compose logs -f <service>     # Follow logs
+docker compose exec <svc> sh         # Shell into container
+docker compose ps                     # Status
+docker compose restart <service>      # Restart
+docker system prune -af               # Clean everything
+docker volume ls                      # List volumes
+```

package/skills/git-workflow/SKILL.md

@@ -0,0 +1,37 @@
+# Git Workflow Skill
+
+## When to use
+Any git operations: branching, committing, merging, rebasing.
+
+## Branch Strategy
+- `main` — Production, always stable
+- `feat/<name>` — New features
+- `fix/<name>` — Bug fixes
+- `chore/<name>` — Maintenance tasks
+
+## Conventional Commits
+```
+feat: add user authentication
+fix: resolve memory leak in cache
+docs: update API documentation
+chore: upgrade dependencies
+refactor: simplify error handling
+test: add integration tests for auth
+perf: optimize database queries
+ci: add GitHub Actions workflow
+```
+
+## Workflow
+1. `git checkout -b feat/<name>` from main
+2. Make focused, atomic commits
+3. `git push origin feat/<name>`
+4. Create PR with description
+5. Review, approve, squash merge into main
+6. Delete feature branch
+
+## Recovery
+- Undo last commit (keep changes): `git reset --soft HEAD~1`
+- Undo last commit (discard): `git reset --hard HEAD~1`
+- Stash changes: `git stash` / `git stash pop`
+- Cherry-pick: `git cherry-pick <hash>`
+- Interactive rebase: `git rebase -i HEAD~N`

package/skills/github/SKILL.md

@@ -0,0 +1,33 @@
+# GitHub Workflow Skill
+
+## When to use
+When working with GitHub repositories: creating repos, managing branches, pull requests, issues, releases, and GitHub Actions.
+
+## Best Practices
+- Always create feature branches: `git checkout -b feat/<name>`
+- Use conventional commits: `feat:`, `fix:`, `docs:`, `chore:`, `refactor:`, `test:`
+- Write descriptive PR titles and bodies
+- Link issues in PR descriptions: `Closes #123`
+- Use GitHub Actions for CI/CD
+- Keep commits atomic and focused
+- Squash merge for cleaner history
+
+## PR Template
+```markdown
+## What
+Brief description of changes
+
+## Why
+Motivation and context
+
+## How
+Implementation approach
+
+## Testing
+How this was tested
+
+## Checklist
+- [ ] Tests pass
+- [ ] Documentation updated
+- [ ] No breaking changes
+```

package/skills/performance/SKILL.md

@@ -0,0 +1,57 @@
+# Performance Optimization Skill
+
+## When to use
+Profiling, optimizing, caching, reducing latency or resource usage.
+
+## Profiling First
+- Never optimize without profiling first
+- Measure before and after every change
+- Focus on the bottleneck (Amdahl's Law)
+
+## Node.js
+```bash
+# CPU profiling
+node --prof app.js
+node --prof-process isolate-*.log > profile.txt
+
+# Memory profiling
+node --inspect app.js
+# Then use Chrome DevTools → Memory tab
+
+# Benchmarking
+hyperfine 'node script.js'
+```
+
+## Common Optimizations
+### Caching
+- In-memory: LRU cache for hot data
+- Redis/Memcached for distributed cache
+- HTTP caching: `Cache-Control`, `ETag`, `Last-Modified`
+- CDN for static assets
+
+### Database
+- Add missing indexes (check `EXPLAIN ANALYZE`)
+- Connection pooling
+- Batch operations instead of N+1 queries
+- Denormalize for read-heavy tables
+- Use materialized views for complex aggregations
+
+### Network
+- Enable compression (gzip/brotli)
+- Minimize payload size
+- Use HTTP/2 or HTTP/3
+- Connection keep-alive
+- Lazy loading for non-critical resources
+
+### Code
+- Avoid unnecessary allocations in hot paths
+- Use streams for large data processing
+- Parallelize independent I/O operations (`Promise.all`)
+- Debounce/throttle high-frequency operations
+- Use worker threads for CPU-intensive tasks
+
+## Benchmarking Rules
+- Warm up before measuring
+- Run multiple iterations
+- Report median, not mean (avoid outlier influence)
+- Control for external factors (other processes, network)

package/skills/prompt-architect/SKILL.md

@@ -0,0 +1,37 @@
+# Prompt Architect Skill
+
+## When to use
+Crafting structured prompts for LLMs, especially for sub-agents and automated workflows.
+
+## Prompt Structure
+```
+[ROLE] Who the model should be
+[CONTEXT] Background information
+[TASK] What to do (specific, measurable)
+[FORMAT] Expected output format
+[CONSTRAINTS] Rules and limitations
+[EXAMPLES] Few-shot examples if needed
+```
+
+## Best Practices
+- Be specific: "Write a TypeScript function" > "Write code"
+- Set constraints: max length, format, language
+- Use delimiters: `---`, `###`, XML tags for sections
+- Chain of thought: "Think step by step" for complex reasoning
+- Few-shot: provide 2-3 examples for consistent output
+- Negative examples: "Do NOT include..." for clarity
+
+## For Sub-Agents
+When creating prompts for sub-agent tasks:
+- Include ALL necessary context (the sub-agent has no memory)
+- Specify the exact output format expected
+- Set clear success criteria
+- Include relevant file paths and code snippets
+- Limit scope: one clear task per sub-agent
+
+## Anti-Patterns
+- ❌ Vague instructions ("make it better")
+- ❌ Missing context (assuming the model knows your codebase)
+- ❌ No output format (getting inconsistent results)
+- ❌ Too many tasks in one prompt (losing focus)
+- ❌ Contradictory instructions

package/skills/security/SKILL.md

@@ -0,0 +1,46 @@
+# Security Skill
+
+## When to use
+Code review for security, implementing auth, handling sensitive data.
+
+## OWASP Top 10 Checks
+1. **Injection** — Parameterized queries, never string concatenation for SQL
+2. **Broken Auth** — Strong passwords, MFA, secure session management
+3. **Sensitive Data** — Encrypt at rest and in transit, never log secrets
+4. **XXE** — Disable external entity processing in XML parsers
+5. **Broken Access Control** — Check permissions on every request
+6. **Misconfig** — No default credentials, disable debug in production
+7. **XSS** — Sanitize output, use CSP headers
+8. **Insecure Deserialization** — Validate before deserializing
+9. **Known Vulnerabilities** — Keep dependencies updated
+10. **Insufficient Logging** — Log security events, monitor anomalies
+
+## Secrets Management
+- NEVER commit secrets to git
+- Use environment variables or secret managers
+- Rotate keys regularly
+- Use `.env` files locally, secrets manager in production
+- Add `.env` to `.gitignore`
+
+## Auth Patterns
+```typescript
+// Hash passwords (never store plain text)
+const hash = await bcrypt.hash(password, 12);
+
+// JWT with short expiry
+const token = jwt.sign({ userId }, SECRET, { expiresIn: "15m" });
+
+// Always validate input
+const schema = z.object({
+  email: z.string().email(),
+  password: z.string().min(8),
+});
+```
+
+## Headers
+```
+Strict-Transport-Security: max-age=31536000; includeSubDomains
+Content-Security-Policy: default-src 'self'
+X-Content-Type-Options: nosniff
+X-Frame-Options: DENY
+```

package/skills/self-improving/SKILL.md

@@ -0,0 +1,36 @@
+# Self-Improving Agent Skill
+
+## When to use
+After any error, correction, or learning moment. Also before major tasks to review past learnings.
+
+## Protocol
+
+### On Error
+1. Document the error in `~/.phi/memory/learnings.md`
+2. Note: what happened, why, how to prevent it
+3. If it's a recurring pattern, create a rule
+
+### On Correction
+When the user corrects you:
+1. Acknowledge the correction
+2. Write to memory: what was wrong, what's right
+3. Apply immediately
+
+### On Success
+When a complex task succeeds:
+1. Note the approach that worked
+2. If novel, document for future reference
+
+### Before Major Tasks
+1. Read `~/.phi/memory/learnings.md`
+2. Check for relevant past mistakes
+3. Apply learned rules
+
+## Memory Format
+```markdown
+## YYYY-MM-DD — Learning
+**Context:** What was happening
+**Error/Insight:** What went wrong or what was learned
+**Rule:** What to do differently
+**Category:** [code|config|workflow|communication]
+```

package/skills/testing/SKILL.md

@@ -0,0 +1,40 @@
+# Testing Skill
+
+## When to use
+Writing tests, designing test strategies, debugging test failures.
+
+## Test Pyramid
+1. **Unit tests** (70%) — Fast, isolated, test single functions
+2. **Integration tests** (20%) — Test component interactions
+3. **E2E tests** (10%) — Test full user flows
+
+## Best Practices
+- Test behavior, not implementation details
+- One assertion per test (ideally)
+- Arrange → Act → Assert pattern
+- Use descriptive test names: `should return 404 when user not found`
+- Mock external dependencies, not internal logic
+- Test edge cases: empty, null, boundary values, errors
+- Don't test library code
+
+## TypeScript (Vitest/Jest)
+```typescript
+describe("UserService", () => {
+  it("should create a user with valid data", async () => {
+    const user = await createUser({ name: "Test", email: "test@example.com" });
+    expect(user.id).toBeDefined();
+    expect(user.name).toBe("Test");
+  });
+
+  it("should throw on duplicate email", async () => {
+    await createUser({ name: "A", email: "dup@example.com" });
+    await expect(createUser({ name: "B", email: "dup@example.com" }))
+      .rejects.toThrow("Email already exists");
+  });
+});
+```
+
+## Test Coverage
+- Aim for 80%+ on critical paths
+- 100% on business logic
+- Don't chase 100% everywhere (diminishing returns)