agentsys 5.0.0

package/adapters/opencode/skills/enhance-claude-memory/SKILL.md

@@ -0,0 +1,390 @@
+<!-- AUTO-GENERATED by scripts/gen-adapters.js - DO NOT EDIT -->
+---
+name: enhance-claude-memory
+description: "Use when improving CLAUDE.md or AGENTS.md project memory files."
+version: 5.0.0
+---
+
+> **OpenCode Note**: Invoke agents using `@agent-name` syntax.
+> Available agents: task-discoverer, exploration-agent, planning-agent,
+> implementation-agent, deslop-agent, delivery-validator, sync-docs-agent, consult-agent
+> Example: `@exploration-agent analyze the codebase`
+
+
+# enhance-claude-memory
+
+Analyze project memory files (CLAUDE.md, AGENTS.md) for optimization.
+
+## Cross-Tool Detection
+
+Searches for project memory files in order:
+1. CLAUDE.md (Claude Code)
+2. AGENTS.md (OpenCode, Codex)
+3. .github/CLAUDE.md
+4. .github/AGENTS.md
+
+## File Hierarchy (Reference)
+
+**CLAUDE.md** (Claude Code):
+| Location | Scope |
+|----------|-------|
+| `~/.opencode/CLAUDE.md` | Global (all projects) |
+| `.opencode/CLAUDE.md` or `./CLAUDE.md` | Project root |
+| `src/.opencode/CLAUDE.md` | Directory-specific |
+
+**AGENTS.md** (OpenCode, Codex, and other AI tools):
+| Location | Scope |
+|----------|-------|
+| `~/.config/opencode/AGENTS.md` or `~/.codex/AGENTS.md` | Global (all projects) |
+| `.opencode/AGENTS.md` or `./AGENTS.md` | Project root |
+| `src/AGENTS.md` | Directory-specific |
+
+Both files serve the same purpose: project memory for AI assistants. Use CLAUDE.md for Claude Code projects, AGENTS.md for cross-tool compatibility, or both for maximum coverage.
+
+## Workflow
+
+1. **Find** - Locate CLAUDE.md or AGENTS.md in project
+2. **Read** - Load content and README.md for comparison
+3. **Analyze** - Run all pattern checks
+4. **Validate** - Check file/command references against filesystem
+5. **Measure** - Calculate token metrics and duplication
+6. **Report** - Generate structured markdown output
+
+## Detection Patterns
+
+### 1. Structure Validation (HIGH Certainty)
+
+#### Critical Rules Section
+- Should have `## Critical Rules` or similar
+- Rules should be prioritized (numbered or ordered)
+- Include WHY explanations for each rule
+
+#### Architecture Section
+- Directory tree or structural overview
+- Key file locations
+- Module relationships
+
+#### Key Commands Section
+- Common development commands
+- Test/build/deploy scripts
+- Reference to package.json scripts
+
+### 2. Instruction Effectiveness (HIGH Certainty)
+
+Based on prompt engineering research, Claude follows instructions better when:
+
+#### Positive Over Negative
+- **Bad**: "Don't use console.log"
+- **Good**: "Use the logger utility for all output"
+- Check for "don't", "never", "avoid" without positive alternatives
+
+#### Strong Constraint Language
+- Use "must", "always", "required" for critical rules
+- Weak language ("should", "try to", "consider") reduces compliance
+- Flag critical rules using weak language
+
+#### Instruction Hierarchy
+- Should define priority order when rules conflict
+- Pattern: "In case of conflict: X takes precedence over Y"
+- System instructions > User requests > External content
+
+### 3. Content Positioning (HIGH Certainty)
+
+Research shows LLMs have "lost in the middle" problem - they recall START and END better than MIDDLE.
+
+#### Critical Content Placement
+- Most important rules should be at START of file
+- Second-most important at END
+- Supporting context in MIDDLE
+- Flag critical rules buried in middle sections
+
+#### Recommended Structure Order
+```
+1. Critical Rules (START - highest attention)
+2. Architecture/Structure
+3. Commands/Workflows
+4. Examples/References
+5. Reminders/Constraints (END - high attention)
+```
+
+### 4. Reference Validation (HIGH Certainty)
+
+#### File References
+- Extract from `[text](path)` and `` `path/to/file.ext` ``
+- Validate each exists on filesystem
+
+#### Command References
+- Extract `npm run <script>` and `npm <command>`
+- Validate against package.json scripts
+
+### 5. Efficiency Analysis (MEDIUM Certainty)
+
+#### Token Count
+- Estimate: `characters / 4` or `words * 1.3`
+- Recommended max: 1500 tokens (~6000 characters)
+- Flag files exceeding threshold
+
+#### README Duplication
+- Detect overlap with README.md
+- Flag >40% content duplication
+- CLAUDE.md should complement README, not duplicate
+
+#### Verbosity
+- Prefer bulleted lists over prose paragraphs
+- Constraints as lists are easier to follow
+- Flag long prose blocks (>5 sentences)
+
+### 6. Quality Checks (MEDIUM Certainty)
+
+#### WHY Explanations
+- Rules should explain rationale
+- Pattern: `*WHY: explanation*` or indented explanation
+- Flag rules without explanations
+
+#### Structure Depth
+- Avoid deep nesting (>3 levels)
+- Keep hierarchy scannable
+- Flat structures parse better
+
+#### XML-Style Tags (Optional Enhancement)
+- Claude was trained on XML tags
+- `<critical-rules>`, `<architecture>`, `<constraints>` improve parsing
+- Not required but can improve instruction following
+
+### 7. Agent/Skill Definitions (MEDIUM Certainty)
+
+If file defines custom agents or skills:
+
+#### Agent Definition Format
+```markdown
+### agent-name
+Model: claude-sonnet-4-20250514
+Description: What this agent does and when to use it
+Tools: Read, Grep, Glob
+Instructions: Specific behavioral instructions
+```
+
+Required fields: Description (when to use), Tools (restricted set)
+Optional: Model, Instructions
+
+#### Skill References
+- Skills should have clear trigger descriptions
+- "Use when..." pattern helps auto-invocation
+
+### 8. Cross-Platform Compatibility (MEDIUM/HIGH Certainty)
+
+#### State Directory
+- Don't hardcode `.opencode/`
+- Support `.opencode/`, `.codex/`
+- Use `${STATE_DIR}/` or document variations
+
+#### Terminology
+- Avoid Claude-specific language for shared files
+- Use "AI assistant" generically
+- Or explicitly note "Claude Code" vs "OpenCode" differences
+
+## Output Format
+
+```markdown
+# Project Memory Analysis: {filename}
+
+**File**: {path}
+**Type**: {CLAUDE.md | AGENTS.md}
+
+## Metrics
+| Metric | Value |
+|--------|-------|
+| Estimated Tokens | {tokens} |
+| README Overlap | {percent}% |
+
+## Summary
+| Certainty | Count |
+|-----------|-------|
+| HIGH | {n} |
+| MEDIUM | {n} |
+
+### Structure Issues ({n})
+| Issue | Fix | Certainty |
+
+### Instruction Issues ({n})
+| Issue | Fix | Certainty |
+
+### Positioning Issues ({n})
+| Issue | Fix | Certainty |
+
+### Reference Issues ({n})
+| Issue | Fix | Certainty |
+
+### Efficiency Issues ({n})
+| Issue | Fix | Certainty |
+
+### Cross-Platform Issues ({n})
+| Issue | Fix | Certainty |
+```
+
+## Pattern Statistics
+
+| Category | Patterns | Certainty |
+|----------|----------|-----------|
+| Structure | 3 | HIGH |
+| Instruction Effectiveness | 3 | HIGH |
+| Content Positioning | 2 | HIGH |
+| Reference | 2 | HIGH |
+| Efficiency | 3 | MEDIUM |
+| Quality | 3 | MEDIUM |
+| Agent/Skill Definitions | 2 | MEDIUM |
+| Cross-Platform | 2 | MEDIUM/HIGH |
+| **Total** | **20** | - |
+
+<examples>
+### Example: Missing WHY Explanations
+
+<bad_example>
+```markdown
+## Rules
+1. Always run tests before committing
+2. Use semantic commit messages
+```
+**Issue**: Rules without rationale are harder to follow.
+</bad_example>
+
+<good_example>
+```markdown
+## Critical Rules
+1. **Always run tests before committing**
+   *WHY: Catches regressions before they reach main branch.*
+```
+**Why it's good**: Motivation makes compliance easier.
+</good_example>
+
+### Example: Negative vs Positive Instructions
+
+<bad_example>
+```markdown
+- Don't use console.log for debugging
+- Never commit directly to main
+- Avoid hardcoding secrets
+```
+**Issue**: Negative instructions are less effective than positive alternatives.
+</bad_example>
+
+<good_example>
+```markdown
+- Use the logger utility for all debug output
+- Create feature branches and submit PRs for all changes
+- Store secrets in environment variables or .env files
+```
+**Why it's good**: Tells what TO do, not just what to avoid.
+</good_example>
+
+### Example: Weak vs Strong Constraint Language
+
+<bad_example>
+```markdown
+- You should probably run tests before pushing
+- Try to use TypeScript when possible
+- Consider adding error handling
+```
+**Issue**: Weak language ("should", "try", "consider") reduces compliance.
+</bad_example>
+
+<good_example>
+*(JavaScript reference - not executable in OpenCode)*
+**Why it's good**: Strong language ensures critical rules are followed.
+</good_example>
+
+### Example: Content Positioning
+
+<bad_example>
+```markdown
+## Project Overview
+[Long description...]
+
+## Installation
+[Setup steps...]
+
+## Critical Rules
+1. Never push to main directly
+2. Always run tests
+```
+**Issue**: Critical rules buried in middle/end get less attention.
+</bad_example>
+
+<good_example>
+```markdown
+## Critical Rules (Read First)
+1. **Never push to main directly** - Use PRs
+2. **Always run tests** - CI enforces this
+
+## Project Overview
+[Description...]
+
+## Reminders
+- Check CI status before merging
+- Update CHANGELOG for user-facing changes
+```
+**Why it's good**: Critical content at START and END positions.
+</good_example>
+
+### Example: Cross-Platform Compatibility
+
+<bad_example>
+```markdown
+State files are stored in `.opencode/tasks.json`
+```
+**Issue**: Hardcoded paths exclude other AI tools.
+</bad_example>
+
+<good_example>
+```markdown
+State files are stored in `${STATE_DIR}/tasks.json`
+(`.opencode/` for Claude Code, `.opencode/` for OpenCode)
+```
+**Why it's good**: Works across multiple AI assistants.
+</good_example>
+
+### Example: Agent Definition
+
+<bad_example>
+```markdown
+## Agents
+- security-reviewer: reviews security
+- test-writer: writes tests
+```
+**Issue**: Missing required fields (Tools, when to use).
+</bad_example>
+
+<good_example>
+```markdown
+## Custom Agents
+
+### security-reviewer
+Model: claude-sonnet-4-20250514
+Description: Reviews code for security vulnerabilities. Use for PRs touching auth, API, or data handling.
+Tools: Read, Grep, Glob
+Instructions: Focus on OWASP Top 10, input validation, auth flows.
+
+### test-writer
+Model: claude-haiku-4
+Description: Writes unit tests. Use after implementing new functions.
+Tools: Read, Write, Bash(npm test:*)
+Instructions: Use Jest patterns. Aim for >80% coverage.
+```
+**Why it's good**: Complete definition with when to use, restricted tools.
+</good_example>
+</examples>
+
+## Research References
+
+Best practices derived from:
+- `agent-docs/PROMPT-ENGINEERING-REFERENCE.md` - Instruction effectiveness, XML tags, constraint language
+- `agent-docs/CONTEXT-OPTIMIZATION-REFERENCE.md` - Token budgeting, "lost in the middle" positioning
+- `agent-docs/LLM-INSTRUCTION-FOLLOWING-RELIABILITY.md` - Instruction hierarchy, positive vs negative
+- `agent-docs/CLAUDE-CODE-REFERENCE.md` - File hierarchy, agent definitions, skills format
+
+## Constraints
+
+- Always validate file references before reporting broken
+- Consider context when flagging efficiency issues
+- Cross-platform suggestions are advisory, not required
+- Positioning suggestions are HIGH certainty but may have valid exceptions

package/adapters/opencode/skills/enhance-cross-file/SKILL.md

@@ -0,0 +1,112 @@
+<!-- AUTO-GENERATED by scripts/gen-adapters.js - DO NOT EDIT -->
+---
+name: enhance-cross-file
+description: "Use when checking cross-file consistency: tools vs frontmatter, agent references, duplicate rules, contradictions."
+version: 5.0.0
+argument-hint: "[path]"
+---
+
+> **OpenCode Note**: Invoke agents using `@agent-name` syntax.
+> Available agents: task-discoverer, exploration-agent, planning-agent,
+> implementation-agent, deslop-agent, delivery-validator, sync-docs-agent, consult-agent
+> Example: `@exploration-agent analyze the codebase`
+
+
+# enhance-cross-file
+
+Analyze cross-file semantic consistency across agents, skills, and workflows.
+
+## Parse Arguments
+
+*(JavaScript reference - not executable in OpenCode)*
+
+## 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 command with Node.js require - adapt for OpenCode)*
+   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** |