plcode-linux-x64-musl 2.1.0

package/.plcode/context/core/standards/security-patterns.md

@@ -0,0 +1,149 @@
+<!-- Context: standards/patterns | Priority: high | Version: 2.0 | Updated: 2025-01-21 -->
+
+# Essential Patterns - Core Knowledge Base
+
+## Quick Reference
+
+**Critical Patterns**: Error Handling, Validation, Security, Logging
+
+**ALWAYS**: Handle errors gracefully, validate input, use env vars for secrets
+
+**NEVER**: Expose sensitive info, hardcode credentials, skip input validation
+
+**Language-agnostic**: Apply to all programming languages
+
+---
+
+These are language-agnostic patterns that apply to all programming languages. Language-specific implementations are loaded from context files based on project detection.
+
+## Error Handling Pattern
+
+**ALWAYS** handle errors gracefully:
+
+- Catch specific errors, not generic ones
+- Log errors with context
+- Return meaningful error messages
+- Don't expose internal implementation details
+- Use language-specific error handling mechanisms (try/catch, Result, error returns)
+
+## Validation Pattern
+
+**ALWAYS** validate input data:
+
+- Check for null/nil/None values
+- Validate data types
+- Validate data ranges and constraints
+- Sanitize user input
+- Return clear validation error messages
+
+## Logging Pattern
+
+**USE** consistent logging levels:
+
+- **Debug**: Detailed information for debugging (development only)
+- **Info**: Important events and milestones
+- **Warning**: Potential issues that don't stop execution
+- **Error**: Failures and exceptions
+
+## Security Pattern
+
+**NEVER** expose sensitive information:
+
+- Don't log passwords, tokens, or API keys
+- Don't expose internal error details to users
+- Validate and sanitize all user input
+- Use environment variables for secrets
+- Follow principle of least privilege
+
+## File System Safety Pattern
+
+**ALWAYS** validate file paths:
+
+- Prevent path traversal attacks
+- Check file permissions before operations
+- Use absolute paths when possible
+- Handle file not found errors gracefully
+- Close file handles properly
+
+## Configuration Pattern
+
+**ALWAYS** use environment variables for configuration:
+
+- Never hardcode secrets or credentials
+- Provide sensible defaults
+- Validate required configuration on startup
+- Document all configuration options
+- Use different configs for dev/staging/production
+
+## Testing Pattern
+
+**ALWAYS** write testable code:
+
+- Use dependency injection
+- Keep functions pure when possible
+- Write unit tests for business logic
+- Write integration tests for external dependencies
+- Use test fixtures and mocks appropriately
+
+## Documentation Pattern
+
+**DOCUMENT** complex logic and public APIs:
+
+- Explain the "why", not just the "what"
+- Document function parameters and return values
+- Include usage examples
+- Keep documentation up to date with code
+- Use language-specific documentation tools
+
+## Performance Pattern
+
+**AVOID** unnecessary operations:
+
+- Don't repeat expensive calculations
+- Cache results when appropriate
+- Use efficient data structures
+- Profile before optimizing
+- Consider time and space complexity
+
+## Code Organization Pattern
+
+**KEEP** code modular and focused:
+
+- Single Responsibility Principle - one function, one purpose
+- Don't Repeat Yourself (DRY)
+- Separate concerns (business logic, data access, presentation)
+- Use meaningful names for functions and variables
+- Keep functions small and focused (< 50 lines ideally)
+
+## Dependency Management
+
+**MANAGE** dependencies carefully:
+
+- Pin dependency versions for reproducibility
+- Regularly update dependencies for security
+- Minimize number of dependencies
+- Audit dependencies for security vulnerabilities
+- Document why each dependency is needed
+
+## Version Control
+
+**FOLLOW** git best practices:
+
+- Write clear, descriptive commit messages
+- Make atomic commits (one logical change per commit)
+- Use feature branches for development
+- Review code before merging
+- Keep main/master branch stable
+
+## Code Review Checklist
+
+**REVIEW** for these common issues:
+
+- Error handling is comprehensive
+- Input validation is present
+- No hardcoded secrets or credentials
+- Tests cover new functionality
+- Documentation is updated
+- Code follows project conventions
+- No obvious security vulnerabilities
+- Performance considerations addressed

package/.plcode/context/core/standards/test-coverage.md

@@ -0,0 +1,133 @@
+<!-- Context: standards/tests | Priority: critical | Version: 2.0 | Updated: 2025-01-21 -->
+
+# Testing Standards
+
+## Quick Reference
+
+**Golden Rule**: If you can't test it easily, refactor it
+
+**AAA Pattern**: Arrange → Act → Assert
+
+**Test** (✅ DO):
+
+- Happy path, edge cases, error cases
+- Business logic, public APIs
+
+**Don't Test** (❌ DON'T):
+
+- Third-party libraries, framework internals
+- Simple getters/setters, private details
+
+**Coverage**: Critical (100%), High (90%+), Medium (80%+)
+
+---
+
+## Principles
+
+**Test behavior, not implementation**: Focus on what code does, not how
+**Keep tests simple**: One assertion per test, clear names, minimal setup
+**Independent tests**: No shared state, run in any order
+**Fast and reliable**: Quick execution, no flaky tests, deterministic
+
+## Test Structure (AAA Pattern)
+
+```javascript
+test("calculateTotal returns sum of item prices", () => {
+  // Arrange - Set up test data
+  const items = [{ price: 10 }, { price: 20 }, { price: 30 }]
+
+  // Act - Execute code
+  const result = calculateTotal(items)
+
+  // Assert - Verify result
+  expect(result).toBe(60)
+})
+```
+
+## What to Test
+
+### ✅ DO Test
+
+- Happy path (normal usage)
+- Edge cases (boundaries, empty, null, undefined)
+- Error cases (invalid input, failures)
+- Business logic (core functionality)
+- Public APIs (exported functions)
+
+### ❌ DON'T Test
+
+- Third-party libraries
+- Framework internals
+- Simple getters/setters
+- Private implementation details
+
+## Coverage Goals
+
+1. **Critical**: Business logic, data transformations (100%)
+2. **High**: Public APIs, user-facing features (90%+)
+3. **Medium**: Utilities, helpers (80%+)
+4. **Low**: Simple wrappers, configs (optional)
+
+## Testing Pure Functions
+
+```javascript
+function add(a, b) {
+  return a + b
+}
+
+test("add returns sum", () => {
+  expect(add(2, 3)).toBe(5)
+  expect(add(-1, 1)).toBe(0)
+  expect(add(0, 0)).toBe(0)
+})
+```
+
+## Testing with Dependencies
+
+```javascript
+// Testable with dependency injection
+function createUserService(database) {
+  return {
+    getUser: (id) => database.findById("users", id),
+  }
+}
+
+// Test with mock
+test("getUser retrieves from database", () => {
+  const mockDb = {
+    findById: jest.fn().mockReturnValue({ id: 1, name: "John" }),
+  }
+
+  const service = createUserService(mockDb)
+  const user = service.getUser(1)
+
+  expect(mockDb.findById).toHaveBeenCalledWith("users", 1)
+  expect(user).toEqual({ id: 1, name: "John" })
+})
+```
+
+## Test Naming
+
+```javascript
+// ✅ Good: Descriptive, clear expectation
+test("calculateDiscount returns 10% off for premium users", () => {})
+test("validateEmail returns false for invalid format", () => {})
+test("createUser throws error when email exists", () => {})
+
+// ❌ Bad: Vague, unclear
+test("it works", () => {})
+test("test user", () => {})
+```
+
+## Best Practices
+
+✅ Test one thing per test
+✅ Use descriptive test names
+✅ Keep tests independent
+✅ Mock external dependencies
+✅ Test edge cases and errors
+✅ Make tests readable
+✅ Run tests frequently
+✅ Fix failing tests immediately
+
+**Golden Rule**: If you can't test it easily, refactor it.

package/.plcode/context/core/standards/tests.md

@@ -0,0 +1 @@
+test-coverage.md

package/.plcode/context/core/system/context-guide.md

@@ -0,0 +1,218 @@
+# Context System Guide
+
+## Quick Reference
+
+**Golden Rule**: Fetch context when needed, not before (lazy loading)
+
+**Key Principle**: Use context index for discovery, load specific files as needed
+
+**Index Location**: `.plcode/context/index.md` - Quick map of all contexts
+
+**Structure**: standards/ (quality + analysis), workflows/ (process + review), system/ (internals)
+
+**Session Location**: `.tmp/sessions/{timestamp}-{task-slug}/context.md`
+
+---
+
+## Overview
+
+Context files provide guidelines and templates for specific tasks. Use the index system for efficient discovery and lazy loading to keep prompts lean.
+
+## Context Index System
+
+**Central Index**: `.plcode/context/index.md` - Ultra-compact map of all contexts
+
+The index provides:
+
+- Quick map for common tasks (code, docs, tests, review, delegation)
+- Triggers/keywords for each context
+- Dependencies between contexts
+- Priority levels (critical, high, medium)
+
+### Available Context Files
+
+All files are in `.plcode/context/core/` with organized subfolders:
+
+### Standards (Quality Guidelines + Analysis)
+
+- `standards/code-quality.md` - Modular, functional code principles [critical]
+- `standards/documentation.md` - Documentation standards [critical]
+- `standards/test-coverage.md` - Testing standards [critical]
+- `standards/security-patterns.md` - Core patterns (error handling, security) [high]
+- `standards/code-analysis.md` - Analysis framework [high]
+
+### Workflows (Process Templates + Review)
+
+- `workflows/task-delegation.md` - Delegation template [high]
+- `workflows/feature-breakdown.md` - Complex task breakdown [high]
+- `workflows/session-management.md` - Session lifecycle [medium]
+- `workflows/code-review.md` - Code review guidelines [high]
+
+## How to Use the Index
+
+**Step 1: Check Quick Map** (for common tasks)
+
+- Code task? → Load `standards/code-quality.md`
+- Docs task? → Load `standards/documentation.md`
+- Review task? → Load `workflows/code-review.md`
+
+**Step 2: Load Index** (for keyword matching)
+
+- Load `.plcode/context/index.md`
+- Scan triggers to find relevant contexts
+- Load specific context files as needed
+
+**Step 3: Load Dependencies**
+
+- Check `deps:` in index
+- Load dependent contexts for complete guidelines
+
+**Benefits:**
+
+- No prompt bloat (index is only ~120 tokens)
+- Fetch only what's relevant
+- Faster for simple tasks
+- Clear dependency tracking
+
+## When to Use Each File
+
+### .plcode/context/core/standards/code-quality.md
+
+- Writing new code
+- Modifying existing code
+- Following modular/functional patterns
+- Making architectural decisions
+
+### .plcode/context/core/standards/documentation.md
+
+- Writing README files
+- Creating API documentation
+- Adding code comments
+
+### .plcode/context/core/standards/test-coverage.md
+
+- Writing new tests
+- Running test suites
+- Debugging test failures
+
+### .plcode/context/core/standards/security-patterns.md
+
+- Error handling
+- Security patterns
+- Common code patterns
+
+### .plcode/context/core/standards/code-analysis.md
+
+- Analyzing codebase patterns
+- Investigating bugs
+- Evaluating architecture
+
+### .plcode/context/core/workflows/task-delegation.md
+
+- Delegating to general agent
+- Creating task context
+- Multi-file coordination
+
+### .plcode/context/core/workflows/feature-breakdown.md
+
+- Tasks with 4+ files
+- Estimated effort >60 minutes
+- Complex dependencies
+
+### .plcode/context/core/workflows/session-management.md
+
+- Session lifecycle
+- Cleanup procedures
+- Session isolation
+
+### .plcode/context/core/workflows/code-review.md
+
+- Reviewing code
+- Conducting code audits
+- Providing PR feedback
+
+## Temporary Context (Session-Specific)
+
+When delegating, create focused task context:
+
+**Location**: `.tmp/sessions/{timestamp}-{task-slug}/context.md`
+
+**Structure**:
+
+```markdown
+# Task Context: {Task Name}
+
+Session ID: {id}
+Created: {timestamp}
+Status: in_progress
+
+## Current Request
+
+{What user asked for}
+
+## Requirements
+
+- {requirement 1}
+- {requirement 2}
+
+## Decisions Made
+
+- {decision 1}
+
+## Files to Modify/Create
+
+- {file 1} - {purpose}
+
+## Static Context Available
+
+- .plcode/context/core/standards/code-quality.md
+- .plcode/context/core/standards/test-coverage.md
+
+## Constraints/Notes
+
+{Important context}
+
+## Progress
+
+- [ ] {task 1}
+- [ ] {task 2}
+
+---
+
+**Instructions for Subagent:**
+{Specific instructions}
+```
+
+## Session Management
+
+### Session Structure
+
+```
+.tmp/sessions/{session-id}/
+├── context.md          # Task context
+├── notes.md            # Working notes
+└── artifacts/          # Generated files
+```
+
+### Session ID Format
+
+`{timestamp}-{random-4-chars}`
+Example: `20250119-143022-a4f2`
+
+### Cleanup
+
+- Ask user before deleting session files
+- Remove after task completion
+- Keep if user wants to review
+
+## Best Practices
+
+✅ Use index for context discovery
+✅ Load only relevant context files
+✅ Check dependencies in index
+✅ Create temp context when delegating
+✅ Clean up sessions after completion
+✅ Reference specific sections when possible
+✅ Keep temp context focused and concise
+
+**Golden Rule**: Fetch context when needed, not before.

package/.plcode/context/core/workflows/code-review.md

@@ -0,0 +1,150 @@
+<!-- Context: workflows/review | Priority: high | Version: 2.0 | Updated: 2025-01-21 -->
+
+# Code Review Guidelines
+
+## Quick Reference
+
+**Golden Rule**: Review code as you'd want yours reviewed - thoroughly but kindly
+
+**Checklist**: Functionality, Code Quality, Security, Testing, Performance, Maintainability
+
+**Report Format**: Summary, Assessment, Issues (🔴🟡🔵), Positive Observations, Recommendations
+
+**Principles**: Constructive, Thorough, Timely
+
+---
+
+## Principles
+
+**Constructive**: Focus on code not person, explain WHY, suggest improvements, acknowledge good practices
+**Thorough**: Check functionality not just style, consider edge cases, think maintainability, look for security
+**Timely**: Review promptly, don't block unnecessarily, prioritize critical issues
+
+## Review Checklist
+
+### Functionality
+
+- [ ] Does what it's supposed to do
+- [ ] Edge cases handled
+- [ ] Error cases handled
+- [ ] No obvious bugs
+
+### Code Quality
+
+- [ ] Clear, descriptive naming
+- [ ] Functions small and focused
+- [ ] No unnecessary complexity
+- [ ] Follows coding standards
+- [ ] DRY - no duplication
+
+### Security
+
+- [ ] Input validation present
+- [ ] No SQL injection vulnerabilities
+- [ ] No XSS vulnerabilities
+- [ ] No hardcoded secrets
+- [ ] Sensitive data handled properly
+- [ ] Auth/authorization appropriate
+
+### Testing
+
+- [ ] Tests present
+- [ ] Happy path covered
+- [ ] Edge cases covered
+- [ ] Error cases covered
+- [ ] All tests pass
+
+### Performance
+
+- [ ] No obvious performance issues
+- [ ] Efficient algorithms
+- [ ] No unnecessary operations
+- [ ] Resources properly managed
+
+### Maintainability
+
+- [ ] Easy to understand
+- [ ] Complex logic documented
+- [ ] Follows project conventions
+- [ ] Easy to modify/extend
+
+## Review Report Format
+
+```markdown
+## Code Review: {Feature/PR Name}
+
+**Summary:** {Brief overview}
+**Assessment:** Approve / Needs Work / Requires Changes
+
+---
+
+### Issues Found
+
+#### 🔴 Critical (Must Fix)
+
+- **File:** `src/auth.js:42`
+  **Issue:** Password stored in plain text
+  **Fix:** Hash password before storing
+
+#### 🟡 Warnings (Should Fix)
+
+- **File:** `src/user.js:15`
+  **Issue:** No input validation
+  **Fix:** Validate email format
+
+#### 🔵 Suggestions (Nice to Have)
+
+- **File:** `src/utils.js:28`
+  **Issue:** Could be more concise
+  **Fix:** Use array methods instead of loop
+
+---
+
+### Positive Observations
+
+- ✅ Good test coverage (95%)
+- ✅ Clear function names
+- ✅ Proper error handling
+
+---
+
+### Recommendations
+
+{Next steps, improvements, follow-up items}
+```
+
+## Common Issues
+
+### Security
+
+🔴 Hardcoded credentials
+🔴 SQL injection vulnerabilities
+🔴 Missing input validation
+🔴 Exposed sensitive data
+
+### Code Quality
+
+🟡 Large functions (>50 lines)
+🟡 Deep nesting (>3 levels)
+🟡 Code duplication
+🟡 Unclear naming
+
+### Testing
+
+🟡 Missing tests
+🟡 Low coverage (<80%)
+🟡 Flaky tests
+🟡 Tests testing implementation
+
+## Best Practices
+
+✅ Review within 24 hours
+✅ Provide specific, actionable feedback
+✅ Explain WHY, not just WHAT
+✅ Suggest alternatives
+✅ Acknowledge good work
+✅ Use severity levels (Critical/Warning/Suggestion)
+✅ Test the code if possible
+✅ Check for security issues first
+
+**Golden Rule**: Review code as you'd want yours reviewed - thoroughly but kindly.

package/.plcode/context/core/workflows/delegation.md

@@ -0,0 +1 @@
+task-delegation.md