agentsys 5.3.4 → 5.3.5

package/.cursor/skills/enhance-cross-file/SKILL.md

@@ -1,110 +0,0 @@
----
-name: enhance-cross-file
-description: "Use when checking cross-file consistency: tools vs frontmatter, agent references, duplicate rules, contradictions."
-version: 5.1.0
-argument-hint: "[path]"
----
-
-# enhance-cross-file
-
-Analyze cross-file semantic consistency across agents, skills, and workflows.
-
-## Parse Arguments
-
-```javascript
-const args = '$ARGUMENTS'.split(' ').filter(Boolean);
-const targetPath = args.find(a => !a.startsWith('--')) || '.';
-```
-
-## Purpose
-
-Detects issues that span multiple files - things single-file analysis misses:
-- Tools used in prompt body but not declared in frontmatter
-- Agent references that don't exist
-- Duplicate instructions across files (maintenance burden)
-- Contradictory rules (ALWAYS vs NEVER conflicts)
-- Orphaned agents not referenced by any workflow
-- Skill tool mismatches (allowed-tools vs actual usage)
-
-## Workflow
-
-1. **Run Analyzer** - Execute the JavaScript analyzer to get findings:
-   ```bash
-   node -e "const a = require('./lib/enhance/cross-file-analyzer.js'); console.log(JSON.stringify(a.analyze('.'), null, 2));"
-   ```
-   For a specific path: `a.analyze('./plugins/enhance')`
-
-2. **Parse Results** - The analyzer returns JSON with `summary` and `findings`
-3. **Report** - Return findings grouped by category
-
-The JavaScript analyzer (`lib/enhance/cross-file-analyzer.js`) implements all cross-file detection. The patterns below are reference documentation.
-
-## Detection Patterns
-
-### 1. Tool Consistency (MEDIUM Certainty)
-
-**tool_not_in_allowed_list**: Tool used in prompt body but not in frontmatter `tools:` list
-
-```yaml
-# Frontmatter declares:
-tools: Read, Grep
-
-# But body uses:
-Use Write({ file_path: "/out" })  # <- Not declared!
-```
-
-**skill_tool_mismatch**: Skill's `allowed-tools` doesn't match actual tool usage in skill body
-
-### 2. Workflow Consistency (MEDIUM Certainty)
-
-**missing_workflow_agent**: `subagent_type: "plugin:agent-name"` references non-existent agent
-
-**orphaned_prompt**: Agent file exists but no workflow references it (may be entry point - check manually)
-
-**incomplete_phase_transition**: Workflow phase mentions "Phase N" but no corresponding section
-
-### 3. Instruction Consistency (MEDIUM Certainty)
-
-**duplicate_instructions**: Same MUST/NEVER instruction in 3+ files (extract to shared location)
-
-**contradictory_rules**: One file says "ALWAYS X" while another says "NEVER X"
-
-## Output Format
-
-```markdown
-## Cross-File Analysis
-
-**Files Analyzed**: {agents} agents, {skills} skills, {commands} commands
-
-### Tool Consistency ({n})
-| Agent | Issue | Fix |
-|-------|-------|-----|
-| exploration-agent | Uses Write but not in tools list | Add Write to frontmatter |
-
-### Workflow Issues ({n})
-| Source | Issue | Fix |
-|--------|-------|-----|
-| workflow.md | References nonexistent agent | Check spelling or create agent |
-
-### Instruction Consistency ({n})
-| Instruction | Files | Fix |
-|-------------|-------|-----|
-| "NEVER push --force" | 4 files | Extract to CLAUDE.md |
-```
-
-## Constraints
-
-- All patterns are MEDIUM certainty (require context)
-- No auto-fix (cross-file changes need human review)
-- Skip content inside `<bad-example>`, `<bad_example>`, `<badexample>` tags
-- Skip content inside code blocks with "bad" in info string
-- Entry point agents (orchestrator, validator, discoverer) are not orphaned
-
-## Pattern Statistics
-
-| Category | Patterns | Auto-Fixable |
-|----------|----------|--------------|
-| Tool Consistency | 2 | 0 |
-| Workflow | 3 | 0 |
-| Consistency | 3 | 0 |
-| **Total** | **8** | **0** |

package/.cursor/skills/enhance-docs/SKILL.md

@@ -1,298 +0,0 @@
----
-name: enhance-docs
-description: "Use when improving documentation structure, accuracy, and RAG readiness."
-version: 5.1.0
-argument-hint: "[path] [--fix] [--ai]"
----
-
-# enhance-docs
-
-Analyze documentation for readability, structure, and RAG optimization.
-
-## Parse Arguments
-
-```javascript
-const args = '$ARGUMENTS'.split(' ').filter(Boolean);
-const targetPath = args.find(a => !a.startsWith('--')) || '.';
-const fix = args.includes('--fix');
-const aiMode = args.includes('--ai');
-```
-
-## Documentation Locations
-
-| Type | Location | Purpose |
-|------|----------|---------|
-| User docs | `docs/*.md`, `README.md` | Human-readable guides |
-| Agent docs | `agent-docs/*.md` | AI reference material |
-| Project memory | `CLAUDE.md`, `AGENTS.md` | AI context/instructions |
-
-## Optimization Modes
-
-### AI-Only Mode (`--ai`)
-For agent-docs and RAG-optimized documentation:
-- Aggressive token reduction
-- Dense information packing
-- Self-contained sections for retrieval
-- Optimal chunking boundaries
-
-### Both Mode (`--both`, default)
-For user-facing documentation:
-- Balance readability with AI-friendliness
-- Clear structure for both humans and retrievers
-
-## Workflow
-
-1. **Discover** - Find all .md files
-2. **Parse** - Extract structure and content
-3. **Check** - Run pattern checks based on mode
-4. **Report** - Generate markdown output
-5. **Fix** - Apply auto-fixes if --fix
-
-## Detection Patterns
-
-### 1. Link Validation (HIGH)
-
-- Broken anchor links (`[text](#missing-anchor)`)
-- Links to non-existent files
-- Malformed link syntax
-
-### 2. Structure Validation (HIGH)
-
-**Heading hierarchy:**
-- No jumps (H1 → H3 without H2)
-- Single H1 per document
-- Code blocks with language tags
-
-**Position-aware content** (based on "lost in the middle" research):
-- Critical info at START or END of document
-- Supporting details in MIDDLE
-- Flag important content buried in middle sections
-
-**Recommended structure:**
-```
-1. Overview/Purpose (START - high attention)
-2. Quick Start / TL;DR
-3. Detailed Content
-4. Reference / API
-5. Summary / Key Points (END - high attention)
-```
-
-### 3. Token Efficiency (HIGH - AI Mode)
-
-**Token estimation:** `characters / 4` or `words * 1.3`
-
-**Unnecessary prose:**
-- "In this document..."
-- "As you can see..."
-- "Let's explore..."
-- "It's important to note that..."
-
-**Verbose phrases:**
-| Verbose | Concise |
-|---------|---------|
-| "in order to" | "to" |
-| "due to the fact that" | "because" |
-| "has the ability to" | "can" |
-| "at this point in time" | "now" |
-| "for the purpose of" | "for" |
-| "in the event that" | "if" |
-
-**Target:** ~1500 tokens for project memory files, flexible for reference docs.
-
-### 4. RAG Optimization (MEDIUM - AI Mode)
-
-**Chunk size guidelines:**
-| Size | Issue |
-|------|-------|
-| >1000 tokens | Too long, split into subtopics |
-| <50 tokens | Too short, merge with related content |
-| 200-500 tokens | Optimal for retrieval |
-
-**Semantic boundaries:**
-- Single topic per section
-- Self-contained sections (avoid "It", "This" at section start)
-- Clear section titles that describe content
-
-**Context anchors:**
-```markdown
-# Bad - ambiguous start
-## Configuration
-It requires several settings...
-
-# Good - self-contained
-## Configuration
-The plugin configuration requires several settings...
-```
-
-### 5. Information Density (MEDIUM - AI Mode)
-
-**Prefer tables over prose:**
-```markdown
-# Bad - verbose
-The function accepts a path parameter which is required,
-a limit parameter which defaults to 10, and an optional
-format parameter.
-
-# Good - dense
-| Param | Required | Default | Description |
-|-------|----------|---------|-------------|
-| path | Yes | - | File path |
-| limit | No | 10 | Max results |
-| format | No | json | Output format |
-```
-
-**Prefer lists over paragraphs** for sequential items.
-
-**Use code blocks** for examples, commands, configurations.
-
-### 6. Cross-Reference Quality (MEDIUM)
-
-- Internal links should use relative paths
-- External links should be stable (avoid commit hashes)
-- Reference sections should point to canonical sources
-
-### 7. Balance Suggestions (MEDIUM - Both Mode)
-
-- Missing section headers in long content (>500 words without heading)
-- Important information buried late in document
-- Missing TL;DR or summary for long documents
-
-## Auto-Fixes
-
-| Issue | Fix |
-|-------|-----|
-| Inconsistent headings | H1 → H3 becomes H1 → H2 |
-| Verbose phrases | Replace with concise alternatives |
-| Missing code language | Add based on content detection |
-
-## Output Format
-
-```markdown
-## Documentation Analysis: {name}
-
-**File**: {path}
-**Mode**: {AI-only | Both}
-**Tokens**: ~{count}
-
-| Certainty | Count |
-|-----------|-------|
-| HIGH | {n} |
-| MEDIUM | {n} |
-
-### Link Issues
-| Line | Issue | Fix | Certainty |
-
-### Structure Issues
-| Line | Issue | Fix | Certainty |
-
-### Efficiency Issues [AI mode]
-| Line | Issue | Fix | Certainty |
-
-### RAG Issues [AI mode]
-| Line | Issue | Fix | Certainty |
-```
-
-## Pattern Statistics
-
-| Category | Patterns | Mode | Certainty |
-|----------|----------|------|-----------|
-| Links | 3 | shared | HIGH |
-| Structure | 4 | shared | HIGH |
-| Token Efficiency | 3 | ai | HIGH |
-| RAG Optimization | 3 | ai | MEDIUM |
-| Information Density | 2 | ai | MEDIUM |
-| Cross-Reference | 2 | shared | MEDIUM |
-| Balance | 3 | both | MEDIUM |
-| **Total** | **20** | - | - |
-
-<examples>
-### Verbose Phrase
-<bad_example>
-```markdown
-In order to configure the plugin, you need to...
-```
-</bad_example>
-<good_example>
-```markdown
-To configure the plugin...
-```
-</good_example>
-
-### RAG Chunking
-<bad_example>
-```markdown
-## Installation
-[2000+ tokens of mixed content covering install, config, and usage]
-```
-</bad_example>
-<good_example>
-```markdown
-## Installation
-[400 tokens - installation only]
-
-## Configuration
-[300 tokens - config only]
-
-## Usage
-[400 tokens - usage only]
-```
-</good_example>
-
-### Position-Aware Content
-<bad_example>
-```markdown
-## Introduction
-[Long background...]
-
-## History
-[More context...]
-
-## Critical Setup Steps
-[Important info buried in middle]
-```
-</bad_example>
-<good_example>
-```markdown
-## Quick Start (Critical)
-[Important setup steps at START]
-
-## Background
-[Supporting context in middle]
-
-## Reference
-[Details...]
-
-## Key Reminders
-[Critical points repeated at END]
-```
-</good_example>
-
-### Tables vs Prose
-<bad_example>
-```markdown
-The API accepts three parameters. The first is `query` which is required.
-The second is `limit` which defaults to 10. The third is `format`.
-```
-</bad_example>
-<good_example>
-```markdown
-| Param | Required | Default |
-|-------|----------|---------|
-| query | Yes | - |
-| limit | No | 10 |
-| format | No | json |
-```
-</good_example>
-</examples>
-
-## References
-
-- `agent-docs/CONTEXT-OPTIMIZATION-REFERENCE.md` - Token budgeting, position awareness, chunking
-- `agent-docs/PROMPT-ENGINEERING-REFERENCE.md` - Structure, information density
-
-## Constraints
-
-- Auto-fix only HIGH certainty issues
-- Preserve original tone and style
-- Balance AI optimization with human readability (default mode)
-- Don't remove content, only restructure or condense