@poolzin/plcode 2.1.1 → 3.0.1

package/.plcode/command/commit.md

@@ -0,0 +1,158 @@
+---
+description: Create well-formatted commits with conventional commit messages and emoji
+---
+
+# Commit Command
+
+You are an AI agent that helps create well-formatted git commits with conventional commit messages and emoji icons, follow these instructions exactly. Always run and push the commit, you don't need to ask for confirmation unless there is a big issue or error.
+
+## Instructions for Agent
+
+When the user runs this command, execute the following workflow:
+
+1. **Check command mode**:
+   - If user provides $ARGUMENTS (a simple message), skip to step 3
+
+2. **Run pre-commit validation**:
+   - Execute `npm lint` and report any issues
+   - Execute `npm run build` and ensure it succeeds
+   - If either fails, ask user if they want to proceed anyway or fix issues first
+3. **Analyze git status**:
+   - Run `git status --porcelain` to check for changes
+   - If no files are staged, run `git add .` to stage all modified files
+   - If files are already staged, proceed with only those files
+4. **Analyze the changes**:
+   - Run `git diff --cached` to see what will be committed
+   - Analyze the diff to determine the primary change type (feat, fix, docs, etc.)
+   - Identify the main scope and purpose of the changes
+5. **Generate commit message**:
+   - Choose appropriate emoji and type from the reference below
+   - Create message following format: `<emoji> <type>: <description>`
+   - Keep description concise, clear, and in imperative mood
+   - Show the proposed message to user for confirmation
+6. **Execute the commit**:
+   - Run `git commit -m "<generated message>"`
+   - Display the commit hash and confirm success
+   - Provide brief summary of what was committed
+
+## Commit Message Guidelines
+
+When generating commit messages, follow these rules:
+
+- **Atomic commits**: Each commit should contain related changes that serve a single purpose
+- **Imperative mood**: Write as commands (e.g., "add feature" not "added feature")
+- **Concise first line**: Keep under 72 characters
+- **Conventional format**: Use `<emoji> <type>: <description>` where type is one of:
+  - `feat`: A new feature
+  - `fix`: A bug fix
+  - `docs`: Documentation changes
+  - `style`: Code style changes (formatting, etc.)
+  - `refactor`: Code changes that neither fix bugs nor add features
+  - `perf`: Performance improvements
+  - `test`: Adding or fixing tests
+  - `chore`: Changes to the build process, tools, etc.
+- **Present tense, imperative mood**: Write commit messages as commands (e.g., "add feature" not "added feature")
+- **Concise first line**: Keep the first line under 72 characters
+- **Emoji**: Each commit type is paired with an appropriate emoji:
+  - ✨ `feat`: New feature
+  - 🐛 `fix`: Bug fix
+  - 📝 `docs`: Documentation
+  - 💄 `style`: Formatting/style
+  - ♻️ `refactor`: Code refactoring
+  - ⚡️ `perf`: Performance improvements
+  - ✅ `test`: Tests
+  - 🔧 `chore`: Tooling, configuration
+  - 🚀 `ci`: CI/CD improvements
+  - 🗑️ `revert`: Reverting changes
+  - 🧪 `test`: Add a failing test
+  - 🚨 `fix`: Fix compiler/linter warnings
+  - 🔒️ `fix`: Fix security issues
+  - 👥 `chore`: Add or update contributors
+  - 🚚 `refactor`: Move or rename resources
+  - 🏗️ `refactor`: Make architectural changes
+  - 🔀 `chore`: Merge branches
+  - 📦️ `chore`: Add or update compiled files or packages
+  - ➕ `chore`: Add a dependency
+  - ➖ `chore`: Remove a dependency
+  - 🌱 `chore`: Add or update seed files
+  - 🧑‍💻 `chore`: Improve developer experience
+  - 🧵 `feat`: Add or update code related to multithreading or concurrency
+  - 🔍️ `feat`: Improve SEO
+  - 🏷️ `feat`: Add or update types
+  - 💬 `feat`: Add or update text and literals
+  - 🌐 `feat`: Internationalization and localization
+  - 👔 `feat`: Add or update business logic
+  - 📱 `feat`: Work on responsive design
+  - 🚸 `feat`: Improve user experience / usability
+  - 🩹 `fix`: Simple fix for a non-critical issue
+  - 🥅 `fix`: Catch errors
+  - 👽️ `fix`: Update code due to external API changes
+  - 🔥 `fix`: Remove code or files
+  - 🎨 `style`: Improve structure/format of the code
+  - 🚑️ `fix`: Critical hotfix
+  - 🎉 `chore`: Begin a project
+  - 🔖 `chore`: Release/Version tags
+  - 🚧 `wip`: Work in progress
+  - 💚 `fix`: Fix CI build
+  - 📌 `chore`: Pin dependencies to specific versions
+  - 👷 `ci`: Add or update CI build system
+  - 📈 `feat`: Add or update analytics or tracking code
+  - ✏️ `fix`: Fix typos
+  - ⏪️ `revert`: Revert changes
+  - 📄 `chore`: Add or update license
+  - 💥 `feat`: Introduce breaking changes
+  - 🍱 `assets`: Add or update assets
+  - ♿️ `feat`: Improve accessibility
+  - 💡 `docs`: Add or update comments in source code
+  - 🗃️ `db`: Perform database related changes
+  - 🔊 `feat`: Add or update logs
+  - 🔇 `fix`: Remove logs
+  - 🤡 `test`: Mock things
+  - 🥚 `feat`: Add or update an easter egg
+  - 🙈 `chore`: Add or update .gitignore file
+  - 📸 `test`: Add or update snapshots
+  - ⚗️ `experiment`: Perform experiments
+  - 🚩 `feat`: Add, update, or remove feature flags
+  - 💫 `ui`: Add or update animations and transitions
+  - ⚰️ `refactor`: Remove dead code
+  - 🦺 `feat`: Add or update code related to validation
+  - ✈️ `feat`: Improve offline support
+
+## Reference: Good Commit Examples
+
+Use these as examples when generating commit messages:
+
+- ✨ feat: add user authentication system
+- 🐛 fix: resolve memory leak in rendering process
+- 📝 docs: update API documentation with new endpoints
+- ♻️ refactor: simplify error handling logic in parser
+- 🚨 fix: resolve linter warnings in component files
+- 🧑‍💻 chore: improve developer tooling setup process
+- 👔 feat: implement business logic for transaction validation
+- 🩹 fix: address minor styling inconsistency in header
+- 🚑️ fix: patch critical security vulnerability in auth flow
+- 🎨 style: reorganize component structure for better readability
+- 🔥 fix: remove deprecated legacy code
+- 🦺 feat: add input validation for user registration form
+- 💚 fix: resolve failing CI pipeline tests
+- 📈 feat: implement analytics tracking for user engagement
+- 🔒️ fix: strengthen authentication password requirements
+- ♿️ feat: improve form accessibility for screen readers
+
+Example commit sequence:
+
+- ✨ feat: add user authentication system
+- 🐛 fix: resolve memory leak in rendering process
+- 📝 docs: update API documentation with new endpoints
+- ♻️ refactor: simplify error handling logic in parser
+- 🚨 fix: resolve linter warnings in component files
+- ✅ test: add unit tests for authentication flow
+
+## Agent Behavior Notes
+
+- **Error handling**: If validation fails, give user option to proceed or fix issues first
+- **Auto-staging**: If no files are staged, automatically stage all changes with `git add .`
+- **File priority**: If files are already staged, only commit those specific files
+- **Always run and push the commit**: You don't need to ask for confirmation unless there is a big issue or error `git push`.
+- **Message quality**: Ensure commit messages are clear, concise, and follow conventional format
+- **Success feedback**: After successful commit, show commit hash and brief summary

package/.plcode/command/context.md

@@ -0,0 +1,302 @@
+---
+description: Context system manager - harvest summaries, extract knowledge, organize context
+tags:
+  - context
+  - knowledge-management
+  - harvest
+dependencies:
+  - subagent:context-organizer
+  - subagent:contextscout
+---
+
+# Context Manager
+
+<critical_rules priority="absolute" enforcement="strict">
+<rule id="mvi_strict">
+Files MUST be <200 lines. Extract core concepts only (1-3 sentences), 3-5 key points, minimal example, reference link.
+</rule>
+
+  <rule id="approval_gate">
+    ALWAYS present approval UI before deleting/archiving files. Letter-based selection (A B C or 'all'). NEVER auto-delete.
+  </rule>
+  
+  <rule id="function_structure">
+    ALWAYS organize by function: concepts/, examples/, guides/, lookup/, errors/ (not flat files).
+  </rule>
+  
+  <rule id="lazy_load">
+    ALWAYS read required context files from .plcode/context/core/context-system/ BEFORE executing operations.
+  </rule>
+</critical_rules>
+
+<execution_priority>
+<tier level="1" desc="Safety & MVI"> - Files <200 lines (@critical_rules.mvi_strict) - Show approval before cleanup (@critical_rules.approval_gate) - Function-based structure (@critical_rules.function_structure) - Load context before operations (@critical_rules.lazy_load)
+</tier>
+<tier level="2" desc="Core Operations"> - Harvest (default), Extract, Organize, Update workflows
+</tier>
+<tier level="3" desc="Enhancements"> - Cross-references, validation, navigation
+</tier>
+<conflict_resolution>
+Tier 1 always overrides Tier 2/3.
+</conflict_resolution>
+</execution_priority>
+
+**Arguments**: `$ARGUMENTS`
+
+---
+
+## Default Behavior (No Arguments)
+
+When invoked without arguments: `/context`
+
+<workflow id="default_scan_harvest">
+  <stage id="1" name="QuickScan">
+    Scan workspace for summary files:
+    - *OVERVIEW.md, *SUMMARY.md, SESSION-*.md, CONTEXT-*.md
+    - Files in .tmp/ directory
+    - Files >2KB in root directory
+  </stage>
+  
+  <stage id="2" name="Report">
+    Show what was found:
+    ```
+    Quick scan results:
+    
+    Found 3 summary files:
+      📄 CONTEXT-SYSTEM-OVERVIEW.md (4.2 KB)
+      📄 SESSION-auth-work.md (1.8 KB)
+      📄 .tmp/NOTES.md (800 bytes)
+    
+    Recommended action:
+      /context harvest  - Clean up summaries → permanent context
+    
+    Other options:
+      /context extract {source}  - Extract from docs/code
+      /context organize {category}  - Restructure existing files
+      /context help  - Show all operations
+    ```
+  </stage>
+</workflow>
+
+**Purpose**: Quick tidy-up. Default assumes you want to harvest summaries and compact workspace.
+
+---
+
+## Operations
+
+### Primary: Harvest & Compact (Default Focus)
+
+**`/context harvest [path]`** ⭐ Most Common
+
+- Extract knowledge from AI summaries → permanent context
+- Clean workspace (archive/delete summaries)
+- **Reads**: `operations/harvest.md` + `standards/mvi.md`
+
+**`/context compact {file}`**
+
+- Minimize verbose file to MVI format
+- **Reads**: `guides/compact.md` + `standards/mvi.md`
+
+---
+
+### Secondary: Custom Context Creation
+
+**`/context extract from {source}`**
+
+- Extract context from docs/code/URLs
+- **Reads**: `operations/extract.md` + `standards/mvi.md` + `guides/compact.md`
+
+**`/context organize {category}`**
+
+- Restructure flat files → function-based folders
+- **Reads**: `operations/organize.md` + `standards/structure.md`
+
+**`/context update for {topic}`**
+
+- Update context when APIs/frameworks change
+- **Reads**: `operations/update.md` + `guides/workflows.md`
+
+**`/context error for {error}`**
+
+- Add recurring error to knowledge base
+- **Reads**: `operations/error.md` + `standards/templates.md`
+
+**`/context create {category}`**
+
+- Create new context category with structure
+- **Reads**: `guides/creation.md` + `standards/structure.md` + `standards/templates.md`
+
+---
+
+### Utility Operations
+
+**`/context map [category]`**
+
+- View current context structure, file counts
+
+**`/context validate`**
+
+- Check integrity, references, file sizes
+
+**`/context help`**
+
+- Show all operations with examples
+
+---
+
+## Lazy Loading Strategy
+
+<lazy_load_map>
+<operation name="default">
+Read: operations/harvest.md, standards/mvi.md
+</operation>
+
+  <operation name="harvest">
+    Read: operations/harvest.md, standards/mvi.md, guides/workflows.md
+  </operation>
+  
+  <operation name="compact">
+    Read: guides/compact.md, standards/mvi.md
+  </operation>
+  
+  <operation name="extract">
+    Read: operations/extract.md, standards/mvi.md, guides/compact.md, guides/workflows.md
+  </operation>
+  
+  <operation name="organize">
+    Read: operations/organize.md, standards/structure.md, guides/workflows.md
+  </operation>
+  
+  <operation name="update">
+    Read: operations/update.md, guides/workflows.md, standards/mvi.md
+  </operation>
+  
+  <operation name="error">
+    Read: operations/error.md, standards/templates.md, guides/workflows.md
+  </operation>
+  
+  <operation name="create">
+    Read: guides/creation.md, standards/structure.md, standards/templates.md
+  </operation>
+</lazy_load_map>
+
+**All files located in**: `.plcode/context/core/context-system/`
+
+---
+
+## Subagent Routing
+
+<subagent_routing>
+
+  <!-- Delegate operations to specialized subagents -->
+  <route operations="harvest|extract|organize|update|error|create" to="ContextOrganizer">
+    Pass: operation name, arguments, lazy load map
+    Subagent loads: Required context files from .plcode/context/core/context-system/
+    Subagent executes: Multi-stage workflow per operation
+  </route>
+  
+  <route operations="map|validate" to="ContextScout">
+    Pass: operation name, arguments
+    Subagent executes: Read-only analysis and reporting
+  </route>
+</subagent_routing>
+
+---
+
+## Quick Reference
+
+### Structure
+
+```
+.plcode/context/core/context-system/
+├── operations/     # How to do things (harvest, extract, organize, update)
+├── standards/      # What to follow (mvi, structure, templates)
+└── guides/         # Step-by-step (workflows, compact, creation)
+```
+
+### MVI Principle (Quick)
+
+- Core concept: 1-3 sentences
+- Key points: 3-5 bullets
+- Minimal example: <10 lines
+- Reference link: to full docs
+- File size: <200 lines
+
+### Function-Based Structure (Quick)
+
+```
+{category}/
+├── navigation.md       # Navigation
+├── concepts/       # What it is
+├── examples/       # Working code
+├── guides/         # How to
+├── lookup/         # Quick reference
+└── errors/         # Common issues
+```
+
+---
+
+## Examples
+
+### Default (Quick Scan)
+
+```bash
+/context
+# Scans workspace, suggests harvest if summaries found
+```
+
+### Harvest Summaries
+
+```bash
+/context harvest
+/context harvest .tmp/
+/context harvest OVERVIEW.md
+```
+
+### Extract from Docs
+
+```bash
+/context extract from docs/api.md
+/context extract from https://react.dev/hooks
+```
+
+### Organize Existing
+
+```bash
+/context organize development/
+/context organize development/ --dry-run
+```
+
+### Update for Changes
+
+```bash
+/context update for Next.js 15
+/context update for React 19 breaking changes
+```
+
+---
+
+## Success Criteria
+
+After any operation:
+
+- [ ] All files <200 lines? (@critical_rules.mvi_strict)
+- [ ] Function-based structure used? (@critical_rules.function_structure)
+- [ ] Approval UI shown for destructive ops? (@critical_rules.approval_gate)
+- [ ] Required context loaded? (@critical_rules.lazy_load)
+- [ ] navigation.md updated?
+- [ ] Files scannable in <30 seconds?
+
+---
+
+## Full Documentation
+
+**Context System Location**: `.plcode/context/core/context-system/`
+
+**Structure**:
+
+- `operations/` - Detailed operation workflows
+- `standards/` - MVI, structure, templates
+- `guides/` - Interactive examples, creation standards
+
+**Read before using**: `standards/mvi.md` (understand Minimal Viable Information principle)