agcel 1.0.1

package/.agent/workflows/fix.md

@@ -0,0 +1,323 @@
+# /fix - Bug Fix Workflow
+
+## Purpose
+
+Smart debugging and bug fixing workflow that analyzes errors, identifies root causes, implements fixes, and adds regression tests.
+
+## Usage
+
+```
+/fix [error message, bug description, or issue reference]
+```
+
+## Arguments
+
+- `$ARGUMENTS`: Error message, stack trace, bug description, or issue number
+
+---
+
+Analyze and fix the following issue: **$ARGUMENTS**
+
+## Workflow
+
+### Phase 1: Error Analysis
+
+1. **Parse Error Information**
+   - Extract error type and message
+   - Parse stack trace if available
+   - Identify the failing location
+
+2. **Gather Context**
+   - When does this error occur?
+   - What triggers it?
+   - Is it reproducible?
+   - When did it start happening?
+
+3. **Check for Known Patterns**
+   - Common error patterns
+   - Similar issues in codebase
+   - Recent changes that might have caused it
+
+### Phase 2: Root Cause Investigation
+
+1. **Trace Execution**
+   - Follow the code path to the error
+   - Identify state at each step
+   - Find where expectations diverge
+
+2. **Form Hypotheses**
+   - List possible causes ranked by likelihood
+   - Identify minimal tests to validate each
+
+3. **Validate Hypothesis**
+   - Test the most likely cause first
+   - Confirm root cause before fixing
+   - Don't fix symptoms only
+
+### Phase 3: Search Related Code
+
+1. **Find Similar Code**
+   - Search for similar patterns
+   - Check if same bug exists elsewhere
+   - Identify shared code that might be affected
+
+2. **Review Recent Changes**
+   ```bash
+   git log --oneline -20
+   git blame [file]
+   ```
+
+### Phase 4: Implement Fix
+
+1. **Develop Minimal Fix**
+   - Fix the root cause, not symptoms
+   - Keep changes minimal and focused
+   - Consider edge cases
+
+2. **Add Defensive Code** (if appropriate)
+   - Input validation
+   - Null checks
+   - Error handling
+
+3. **Update Related Code** (if needed)
+   - Fix same issue in similar code
+   - Update shared utilities
+
+### Phase 5: Verification
+
+1. **Test the Fix**
+   - Verify original error is resolved
+   - Check related functionality
+   - Run existing test suite
+
+2. **Add Regression Test**
+   - Write test that would have caught this bug
+   - Include edge cases discovered
+   - Ensure test fails without fix
+
+3. **Run Full Test Suite**
+   ```bash
+   # Python
+   pytest -v
+
+   # TypeScript
+   pnpm test
+   ```
+
+### Phase 6: Documentation
+
+1. **Document the Fix**
+   - What was the issue
+   - What caused it
+   - How it was fixed
+
+2. **Update Comments** (if needed)
+   - Add clarifying comments
+   - Document non-obvious behavior
+
+## Output
+
+### Bug Fix Summary
+
+```markdown
+## Bug Fix Complete
+
+### Issue
+[Original error/bug description]
+
+### Root Cause
+[Explanation of what caused the bug]
+
+### Location
+`path/to/file.ts:42` - [function/method name]
+
+### Fix Applied
+
+**Before:**
+```typescript
+// Problematic code
+```
+
+**After:**
+```typescript
+// Fixed code
+```
+
+### Explanation
+[Why this fix resolves the issue]
+
+### Regression Test Added
+`path/to/test.ts` - `test_[scenario]`
+
+### Verification
+- [x] Original error no longer occurs
+- [x] Existing tests pass
+- [x] New regression test passes
+- [x] No new issues introduced
+
+### Related Areas Checked
+- [x] `path/to/similar.ts` - No similar issue
+
+### Commands to Verify
+```bash
+pytest tests/test_file.py -v
+# or
+pnpm test path/to/file.test.ts
+```
+```
+
+## Common Fix Patterns
+
+### Null/Undefined Access
+
+```typescript
+// Before
+const name = user.profile.name;
+
+// After
+const name = user?.profile?.name ?? 'Unknown';
+```
+
+### Missing Error Handling
+
+```python
+# Before
+data = json.loads(response.text)
+
+# After
+try:
+    data = json.loads(response.text)
+except json.JSONDecodeError as e:
+    logger.error(f"Invalid JSON response: {e}")
+    raise InvalidResponseError("Failed to parse response")
+```
+
+### Race Condition
+
+```typescript
+// Before
+const data = await fetchData();
+setState(data); // May be unmounted
+
+// After
+useEffect(() => {
+  let cancelled = false;
+  fetchData().then(data => {
+    if (!cancelled) setState(data);
+  });
+  return () => { cancelled = true; };
+}, []);
+```
+
+### Off-by-One Error
+
+```python
+# Before
+for i in range(len(items) + 1):  # IndexError
+    process(items[i])
+
+# After
+for i in range(len(items)):
+    process(items[i])
+# or
+for item in items:
+    process(item)
+```
+
+## Example
+
+**Input**: `/fix TypeError: Cannot read property 'email' of undefined in UserService.ts:45`
+
+**Output**:
+1. Analysis: User object is undefined when accessed
+2. Root cause: async fetch didn't await, user not loaded yet
+3. Fix: Add null check and proper async handling
+4. Regression test: Test for case when user is not loaded
+
+## Flags
+
+| Flag | Description | Example |
+|------|-------------|---------|
+| `--mode=[mode]` | Use specific behavioral mode | `--mode=deep-research` |
+| `--persona=[type]` | Apply persona expertise | `--persona=security` |
+| `--depth=[1-5]` | Investigation thoroughness | `--depth=4` |
+| `--format=[fmt]` | Output format (concise/detailed) | `--format=concise` |
+| `--skip-regression` | Skip regression test creation | `--skip-regression` |
+| `--checkpoint` | Create checkpoint before fixing | `--checkpoint` |
+
+### Flag Usage Examples
+
+```bash
+/fix --mode=deep-research "intermittent timeout error"
+/fix --persona=security "SQL injection vulnerability"
+/fix --depth=5 "race condition in auth flow"
+/fix --format=concise "typo in error message"
+```
+
+### Persona Options
+
+| Persona | Focus Area |
+|---------|------------|
+| `security` | Security vulnerabilities, OWASP |
+| `performance` | Speed, memory, efficiency |
+| `reliability` | Error handling, edge cases |
+
+## MCP Integration
+
+This command leverages MCP servers for enhanced debugging:
+
+### Reasoning - Root Cause Analysis (Primary)
+```
+ALWAYS use Reasoning for debugging:
+- Trace execution path step-by-step
+- Form and test hypotheses systematically
+- Track confidence in each potential cause
+- Revise understanding as evidence emerges
+```
+
+### Memory - Bug Context
+```
+Store and recall debugging context:
+- Remember similar bugs from previous sessions
+- Recall fix patterns that worked before
+- Store root cause analysis for future reference
+- Create relations between bugs and affected components
+```
+
+### Browser tools - Browser Testing
+```
+For UI/frontend bugs:
+- Reproduce the bug in browser environment
+- Test fix across different browsers
+- Verify visual regressions are resolved
+- Automate regression test for the fix
+```
+
+### Web Search - Library Issues
+```
+When debugging library-related issues:
+- Fetch current documentation for correct usage
+- Check for known issues or breaking changes
+- Find correct patterns and examples
+```
+
+### Filesystem - Code Search
+```
+For tracing bug across codebase:
+- Use grep_search to find related code
+- Use view_file to examine suspicious areas
+- Track changes with file history
+```
+
+<!-- CUSTOMIZATION POINT -->
+## Variations
+
+Modify behavior via CLAUDE.md:
+- Set required test coverage for fixes
+- Define severity levels for bugs
+- Configure error reporting format
+- Set required review process
+
+
+## Gap Analysis Rule
+Always identify gaps and suggest next steps to users. In case there is no gaps anymore, then AI should clearly state that there is no gap left.

package/.agent/workflows/help.md

@@ -0,0 +1,63 @@
+# /help - Help Command
+
+## Purpose
+
+Display available commands and their usage.
+
+## Usage
+
+```
+/help [command name]
+```
+
+---
+
+Show help for: **$ARGUMENTS**
+
+## Available Commands
+
+### Development Workflow
+| Command | Description |
+|---------|-------------|
+| `/feature` | Full feature development workflow |
+| `/fix` | Debug and fix bugs |
+| `/review` | Code review |
+| `/test` | Generate tests |
+| `/tdd` | Test-driven development |
+| `/refactor` | Improve code structure |
+
+### Git & Deployment
+| Command | Description |
+|---------|-------------|
+| `/commit` | Create commit with message |
+| `/ship` | Commit + PR workflow |
+| `/pr` | Create pull request |
+| `/deploy` | Deploy to environment |
+
+### Documentation
+| Command | Description |
+|---------|-------------|
+| `/doc` | Generate documentation |
+| `/plan` | Create implementation plan |
+
+### Security & Quality
+| Command | Description |
+|---------|-------------|
+| `/security-scan` | Scan for vulnerabilities |
+| `/api-gen` | Generate API code |
+
+## Getting Help
+
+For detailed help on a specific command:
+```
+/help [command-name]
+```
+
+For general Claude Code help:
+```
+/help
+```
+
+
+## Gap Analysis Rule
+Always identify gaps and suggest next steps to users. In case there is no gaps anymore, then AI should clearly state that there is no gap left.

package/.agent/workflows/index.md

@@ -0,0 +1,148 @@
+# /index
+
+## Purpose
+
+Generate a comprehensive project structure index for faster navigation and context loading. Creates a `PROJECT_INDEX.md` file mapping the codebase structure.
+
+---
+
+Analyze the current project and generate a comprehensive index.
+
+## Index Generation
+
+### Step 1: Scan Project Structure
+
+Scan the entire project directory structure, excluding:
+- `node_modules/`
+- `.git/`
+- `__pycache__/`
+- `dist/`, `build/`, `.next/`
+- `venv/`, `.venv/`
+- Coverage and cache directories
+
+### Step 2: Identify Key Components
+
+Categorize files by type:
+- **Entry Points**: Main files, index files, app entry
+- **API/Routes**: Endpoint definitions
+- **Models/Types**: Data structures, schemas
+- **Services**: Business logic
+- **Utilities**: Helper functions
+- **Tests**: Test files
+- **Configuration**: Config files, env templates
+- **Documentation**: README, docs
+
+### Step 3: Map Dependencies
+
+Identify:
+- Package managers and dependencies (package.json, requirements.txt, etc.)
+- Internal import relationships between key files
+- External service integrations
+
+### Step 4: Generate Index
+
+Create `PROJECT_INDEX.md` with this structure:
+
+```markdown
+# Project Index: [Project Name]
+
+Generated: [timestamp]
+
+## Quick Navigation
+
+| Category | Key Files |
+|----------|-----------|
+| Entry Points | [list] |
+| API Routes | [list] |
+| Core Services | [list] |
+| Models | [list] |
+
+## Directory Structure
+
+```
+[tree view]
+```
+
+## Key Files
+
+### Entry Points
+- `[path]` - [description]
+
+### API/Routes
+- `[path]` - [description]
+
+### Services
+- `[path]` - [description]
+
+### Models/Types
+- `[path]` - [description]
+
+## Dependencies
+
+### External
+- [package]: [purpose]
+
+### Internal
+- [module] → [depends on]
+
+## Architecture Notes
+[Brief description of patterns observed]
+```
+
+## Flags
+
+| Flag | Description |
+|------|-------------|
+| `--depth=[N]` | Limit directory depth (default: 5) |
+| `--include=[pattern]` | Include additional patterns |
+| `--exclude=[pattern]` | Exclude additional patterns |
+| `--output=[path]` | Custom output path |
+
+## Usage Examples
+
+```bash
+/index                           # Standard index
+/index --depth=3                 # Shallow index
+/index --include="*.graphql"     # Include GraphQL files
+/index --output=docs/INDEX.md    # Custom output location
+```
+
+## Arguments
+
+$ARGUMENTS
+
+If no arguments provided, generate standard index with default settings.
+
+---
+
+After generating the index, inform the user:
+1. Index file location
+2. Number of files indexed
+3. Key components discovered
+4. Suggest using `/load` to load specific components into context
+
+## MCP Integration
+
+This command leverages MCP servers for enhanced indexing:
+
+### Filesystem - Project Scanning (Primary)
+```
+ALWAYS use Filesystem for project scanning:
+- Use list_dir for full structure view
+- Use list_directory for targeted exploration
+- Use grep_search to find specific patterns
+- Use get_file_info for file metadata
+```
+
+### Memory - Project Knowledge
+```
+Store project structure in knowledge graph:
+- Create entities for key modules
+- Store component relationships
+- Recall structure in future sessions
+- Build project understanding over time
+```
+
+
+## Gap Analysis Rule
+Always identify gaps and suggest next steps to users. In case there is no gaps anymore, then AI should clearly state that there is no gap left.

package/.agent/workflows/load.md

@@ -0,0 +1,112 @@
+# /load
+
+## Purpose
+
+Load specific project components into context for focused work. Uses the project index to efficiently load relevant files.
+
+---
+
+Load the requested component(s) into context.
+
+## Loading Process
+
+### Step 1: Check for Index
+
+First, check if `PROJECT_INDEX.md` exists:
+- If exists: Use index for efficient loading
+- If not: Suggest running `/index` first, or do quick scan
+
+### Step 2: Identify Component
+
+Parse the requested component:
+
+| Request Type | Action |
+|--------------|--------|
+| Category name | Load all files in category |
+| File path | Load specific file |
+| Pattern | Load matching files |
+| `--all` | Load key files from all categories |
+
+### Step 3: Load Files
+
+Read the identified files and summarize:
+- File purposes
+- Key exports/functions
+- Dependencies
+- Current state
+
+### Step 4: Context Summary
+
+Provide a brief summary:
+```markdown
+## Loaded Context
+
+### Files Loaded (N)
+- `path/to/file1.ts` - [purpose]
+- `path/to/file2.ts` - [purpose]
+
+### Key Components
+- [Component]: [description]
+
+### Ready For
+- [Suggested actions based on loaded context]
+```
+
+## Component Categories
+
+| Category | What It Loads |
+|----------|---------------|
+| `api` | API routes and endpoints |
+| `models` | Data models and types |
+| `services` | Business logic services |
+| `utils` | Utility functions |
+| `tests` | Test files |
+| `config` | Configuration files |
+| `auth` | Authentication related |
+| `db` | Database related |
+
+## Flags
+
+| Flag | Description |
+|------|-------------|
+| `--all` | Load all key components |
+| `--shallow` | Load only file summaries |
+| `--deep` | Load full file contents |
+| `--related` | Include related files |
+
+## Usage Examples
+
+```bash
+/load api                    # Load all API routes
+/load models                 # Load all data models
+/load src/services/user.ts   # Load specific file
+/load auth --related         # Load auth + related files
+/load --all                  # Load all key components
+/load --all --shallow        # Quick overview of everything
+```
+
+## Arguments
+
+$ARGUMENTS
+
+If no arguments, show available components from index.
+
+---
+
+## Best Practices
+
+1. **Start Narrow**: Load specific components first
+2. **Expand as Needed**: Use `--related` when you need more context
+3. **Check Index**: Run `/index` if loading seems slow
+4. **Use Categories**: Category names are faster than patterns
+
+## After Loading
+
+Suggest next actions:
+- "Ready to work on [component]. What would you like to do?"
+- "I see [patterns/issues]. Want me to address them?"
+- "Related files that might be relevant: [list]"
+
+
+## Gap Analysis Rule
+Always identify gaps and suggest next steps to users. In case there is no gaps anymore, then AI should clearly state that there is no gap left.