@agenthippo-ai/agenthippo 1.110.9 → 1.110.19

package/out/base-prompts/skills/agentpack-creator/references/agents-md-guide.md

@@ -1,195 +0,0 @@
-# Writing Effective AGENTS.md Files
-
-Guide for crafting AGENTS.md files that produce consistent, useful agent behavior.
-
-## The Four Pillars
-
-Every effective AGENTS.md needs these sections:
-
-### 1. Core Behaviors (What the agent DOES)
-
-**Good**: Specific, actionable, measurable
-```markdown
-1. **Systematic Review**: Check every function for input validation before processing
-2. **Context Gathering**: Read related files before proposing changes
-3. **Incremental Changes**: Modify one file at a time, verify after each
-```
-
-**Bad**: Vague, generic, unmeasurable
-```markdown
-1. Help with code
-2. Be helpful
-3. Do good work
-```
-
-**Tips**:
-- Use action verbs: "Analyze", "Verify", "Generate", "Check"
-- Be specific about scope: "all TypeScript files" vs "the codebase"
-- Include quality criteria: "until all tests pass" vs "until done"
-
-### 2. Workflow (HOW the agent works)
-
-**Good**: Step-by-step with decision points
-```markdown
-1. **Understand**: Read the user's request and identify affected files
-2. **Research**: Examine relevant code, tests, and documentation
-3. **Plan**: Outline changes before implementing
-4. **Execute**: Make changes incrementally with verification
-5. **Validate**: Run tests and check for regressions
-```
-
-**Bad**: Missing steps, unclear sequence
-```markdown
-1. Look at the code
-2. Fix it
-```
-
-**Tips**:
-- Match workflow to typical task complexity
-- Include verification/validation steps
-- Add decision points for ambiguous cases
-
-### 3. Constraints (What the agent must NOT do)
-
-**Good**: Explicit boundaries with rationale
-```markdown
-- Never modify files outside the `src/` directory
-- Always ask before deleting files or removing functionality
-- Don't refactor adjacent code unless explicitly asked
-```
-
-**Bad**: Too vague or too restrictive
-```markdown
-- Be careful
-- Don't break things
-```
-
-**Tips**:
-- List 3-5 specific constraints
-- Focus on high-impact restrictions (destructive operations, scope limits)
-- Include "escape hatches": "unless the user explicitly requests otherwise"
-
-### 4. Output Format (How results are presented)
-
-**Good**: Concrete structure with examples
-```markdown
-Present findings in this format:
-
-### Summary
-One paragraph overview of what was found/done.
-
-### Changes
-| File | Change | Rationale |
-|------|--------|-----------|
-| ... | ... | ... |
-
-### Next Steps
-Bullet list of recommended follow-up actions.
-```
-
-**Bad**: No format guidance
-```markdown
-Just explain what you did.
-```
-
-**Tips**:
-- Use markdown structure (headers, lists, tables)
-- Include a minimal example
-- Specify when to use different formats (short vs. long responses)
-
-## Common Patterns
-
-### Decision Tree Pattern
-
-When the agent needs to handle multiple scenarios:
-
-```markdown
-## Handling Requests
-
-For **new features**:
-1. Create design outline
-2. Get user approval
-3. Implement incrementally
-
-For **bug fixes**:
-1. Reproduce the issue
-2. Identify root cause
-3. Implement minimal fix
-4. Add regression test
-
-For **refactoring**:
-1. Ensure test coverage exists
-2. Make changes in small steps
-3. Verify tests pass after each step
-```
-
-### Progressive Detail Pattern
-
-When the agent should adapt response length:
-
-```markdown
-## Response Guidelines
-
-**Simple questions**: Direct answer, 1-3 sentences
-
-**Code changes**: Summary + diff + explanation
-
-**Complex tasks**:
-1. Outline/plan first
-2. Implementation in stages
-3. Summary with next steps
-```
-
-### Verification Loop Pattern
-
-When the agent should self-check:
-
-```markdown
-## Quality Checklist
-
-Before completing any task, verify:
-- [ ] All modified files saved
-- [ ] No new linting errors introduced
-- [ ] Tests still pass (or new tests added)
-- [ ] Changes match the original request
-```
-
-## Anti-Patterns to Avoid
-
-### 1. Aspirational Instructions
-
-**Bad**: "Write perfect, bug-free code every time"
-**Good**: "Run tests after changes and fix any failures"
-
-### 2. Contradictory Constraints
-
-**Bad**: "Be thorough" + "Keep responses short"
-**Good**: "Prioritize completeness for complex tasks, brevity for simple questions"
-
-### 3. Implicit Assumptions
-
-**Bad**: "Follow project conventions"
-**Good**: "Follow project conventions as defined in `.prettierrc` and `eslint.config.js`"
-
-### 4. Missing Scope
-
-**Bad**: "Review the code"
-**Good**: "Review code in the current PR / changed files / specified directory"
-
-## Iteration Tips
-
-1. **Start Minimal**: Write the shortest AGENTS.md that could work
-2. **Test Quickly**: Use the agent, note what goes wrong
-3. **Add Specificity**: Address observed issues with specific instructions
-4. **Remove Clutter**: Delete instructions that don't affect behavior
-5. **Version Changes**: Update version in agent.yaml when changing behavior
-
-## Token Efficiency
-
-AGENTS.md content is loaded into every conversation. Keep it lean:
-
-- **Target**: 50-200 lines for most agents
-- **Split large content**: Use `rules/` directory for detailed guidelines
-- **Reference over repeat**: Point to documentation instead of copying it
-- **Examples over explanations**: A 5-line example beats a 20-line explanation
-

package/out/base-prompts/skills/agentpack-creator/scripts/init_pack.py

@@ -1,391 +0,0 @@
-#!/usr/bin/env python3
-# Copyright (c) AgentHippo.ai. All rights reserved.
-"""
-AgentPack Initializer - Creates a new agent pack with template files
-
-Usage:
-    init_pack.py <pack-name> --path <path> [--engine <engine>] [--description <description>]
-
-Examples:
-    init_pack.py code-reviewer --path .agent-hippo/agents
-    init_pack.py security-auditor --path .agent-hippo/agents --engine claude
-    init_pack.py my-agent --path .agent-hippo/agents --engine codex --description "A custom agent for my project"
-
-The script creates a complete agent pack structure with:
-- agent.yaml manifest
-- AGENTS.md with TODO placeholders
-- rules/, skills/, mcp/ directories
-"""
-
-import argparse
-import hashlib
-import json
-import os
-import sys
-from pathlib import Path
-from datetime import datetime, timezone
-
-# =============================================================================
-# Templates
-# =============================================================================
-
-AGENT_YAML_TEMPLATE = """# {pack_name} Agent Manifest
-apiVersion: agenthippo.ai/v1
-kind: Agent
-metadata:
-  name: {pack_name}
-  version: 0.1.0
-  author: {author}
-  description: "{description}"
-
-spec:
-  engine: {engine}
-  model: {model}
-
-  skills: []
-  # Uncomment to add pack-specific skills:
-  # - path: ./skills/my-skill
-
-  permissions:
-    fileAccess: full  # read-only | workspace-write | full
-
-  visibility: internal      # internal | team | public
-"""
-
-AGENTS_MD_TEMPLATE = """# {pack_title} Agent
-
-{description}
-
-## Core Behaviors
-
-{behaviors_section}
-
-## Workflow
-
-{workflow_section}
-
-## Constraints
-
-{constraints_section}
-
-## Output Format
-
-{output_section}
-"""
-
-# Default content for TODO sections
-BEHAVIORS_TODO = """<!-- TODO: Define 3-5 specific behaviors this agent should exhibit -->
-<!-- Example:
-1. **Thorough Analysis**: Examine all relevant files before making recommendations
-2. **Clear Communication**: Explain reasoning in plain language
-3. **Incremental Changes**: Prefer small, targeted modifications over large rewrites
--->
-
-1. **[Behavior 1]**: [Describe what this agent does in this area]
-2. **[Behavior 2]**: [Describe what this agent does in this area]
-3. **[Behavior 3]**: [Describe what this agent does in this area]
-"""
-
-WORKFLOW_TODO = """<!-- TODO: Describe the step-by-step process this agent follows -->
-<!-- Example:
-1. Understand the request and gather context
-2. Analyze relevant files and dependencies
-3. Propose a solution with rationale
-4. Implement changes incrementally
-5. Verify the solution works
--->
-
-1. **Understand**: [First step]
-2. **Analyze**: [Second step]
-3. **Execute**: [Third step]
-4. **Verify**: [Fourth step]
-"""
-
-CONSTRAINTS_TODO = """<!-- TODO: Define what this agent should NOT do -->
-<!-- Example:
-- Never modify files outside the specified scope
-- Always ask for clarification before destructive operations
-- Prefer existing patterns over introducing new ones
--->
-
-- [Constraint 1]
-- [Constraint 2]
-- [Constraint 3]
-"""
-
-OUTPUT_TODO = """<!-- TODO: Describe how this agent should format its responses -->
-<!-- Example:
-Provide responses in the following format:
-1. **Summary**: Brief overview of what was done
-2. **Changes**: List of files modified with explanations
-3. **Next Steps**: Suggested follow-up actions
--->
-
-[Describe the expected output format for this agent's responses]
-"""
-
-
-def title_case(name: str) -> str:
-    """Convert a pack name (hyphenated, underscored, or spaced) to Title Case."""
-    import re
-    # Split on common separators: hyphens, underscores, spaces
-    words = re.split(r'[-_\s]+', name)
-    return ' '.join(word.capitalize() for word in words if word)
-
-
-def get_author() -> str:
-    """Get the author name from environment or default."""
-    return os.environ.get('USER', os.environ.get('USERNAME', 'unknown'))
-
-
-def get_model_for_engine(engine: str) -> str:
-    """Get the default model for an engine.
-
-    Note: These are fallback defaults. When creating a pack via the UI,
-    the current session's model is captured and passed explicitly.
-    """
-    return 'claude-sonnet-4' if engine == 'claude' else 'codex'
-
-
-def compute_feature_hash(pack_name: str, engine: str, version: str) -> str:
-    """Compute a simple feature set hash for the pack."""
-    content = f"{pack_name}:{engine}:{version}"
-    return hashlib.sha256(content.encode()).hexdigest()[:16]
-
-
-def register_pack_in_manifest(
-    pack_name: str,
-    agentide_dir: Path,
-    engine: str,
-    version: str = '0.1.0',
-) -> bool:
-    """
-    Register the pack in the installed-agents.json file.
-
-    Args:
-        pack_name: Name of the agent pack
-        agentide_dir: Path to the .agent-hippo directory
-        engine: Preferred engine ('claude' or 'codex')
-        version: Pack version
-
-    Returns:
-        True if successful, False otherwise
-    """
-    agents_file_path = agentide_dir / 'installed-agents.json'
-
-    # Load existing file or create new one
-    if agents_file_path.exists():
-        try:
-            data = json.loads(agents_file_path.read_text())
-        except json.JSONDecodeError:
-            data = {}
-    else:
-        data = {}
-
-    # Ensure required fields exist
-    if 'version' not in data:
-        data['version'] = 1
-    if 'agents' not in data:
-        data['agents'] = []
-
-    # Remove existing entry for this pack (if re-creating)
-    data['agents'] = [
-        a for a in data['agents'] if a.get('id') != pack_name
-    ]
-
-    # Add new entry
-    entry = {
-        'id': pack_name,
-        'version': version,
-        'source': 'local',
-        'installedAt': datetime.now(timezone.utc).isoformat(),
-        'featureSetHash': compute_feature_hash(pack_name, engine, version),
-        'preferredEngine': engine,
-        'status': 'active',
-    }
-    data['agents'].append(entry)
-
-    # Write file
-    try:
-        agents_file_path.write_text(json.dumps(data, indent=2))
-        return True
-    except Exception as e:
-        print(f"⚠️  Warning: Could not update installed-agents.json: {e}")
-        return False
-
-
-def validate_pack_name(name: str) -> bool:
-    """Validate pack name is valid as a directory name."""
-    import re
-    if not name or not name.strip():
-        return False
-    # Reject path separators and problematic filesystem characters
-    if re.search(r'[/\\:*?"<>|]', name):
-        return False
-    # Reject hidden directories
-    if name.startswith('.'):
-        return False
-    return True
-
-
-def init_pack(
-    pack_name: str,
-    path: str,
-    engine: str = 'claude',
-    description: str = '',
-    model: str = '',
-) -> Path | None:
-    """
-    Initialize a new agent pack directory with template files.
-
-    Args:
-        pack_name: Name of the agent pack (e.g., 'code-reviewer')
-        path: Parent directory where the pack will be created
-        engine: Preferred engine ('claude' or 'codex')
-        description: Optional description of the agent
-        model: Preferred model ID (e.g., 'claude-sonnet-4'). If not specified, uses default for engine.
-
-    Returns:
-        Path to created pack directory, or None if error
-    """
-    # Validate pack name
-    if not validate_pack_name(pack_name):
-        print(f"❌ Error: Pack name '{pack_name}' is invalid.")
-        print("   Pack names cannot be empty, start with a dot, or contain path separators.")
-        return None
-
-    # Determine pack directory path
-    pack_dir = Path(path).resolve() / pack_name
-
-    # Check if directory already exists
-    if pack_dir.exists():
-        print(f"❌ Error: Pack directory already exists: {pack_dir}")
-        return None
-
-    # Create pack directory structure
-    try:
-        pack_dir.mkdir(parents=True, exist_ok=False)
-        print(f"✅ Created pack directory: {pack_dir}")
-
-        (pack_dir / 'rules').mkdir(exist_ok=True)
-        print("✅ Created rules/")
-
-        (pack_dir / 'skills').mkdir(exist_ok=True)
-        print("✅ Created skills/")
-
-        (pack_dir / 'mcp').mkdir(exist_ok=True)
-        print("✅ Created mcp/")
-
-    except Exception as e:
-        print(f"❌ Error creating directories: {e}")
-        return None
-
-    # Create agent.yaml
-    pack_title = title_case(pack_name)
-    # Use provided model or default based on engine
-    resolved_model = model.strip() if model else get_model_for_engine(engine)
-    agent_yaml_content = AGENT_YAML_TEMPLATE.format(
-        pack_name=pack_name,
-        author=get_author(),
-        description=description or f'A specialized agent for {pack_title.lower()} tasks',
-        engine=engine,
-        model=resolved_model,
-    )
-
-    try:
-        (pack_dir / 'agent.yaml').write_text(agent_yaml_content)
-        print("✅ Created agent.yaml")
-    except Exception as e:
-        print(f"❌ Error creating agent.yaml: {e}")
-        return None
-
-    # Create AGENTS.md
-    agents_md_content = AGENTS_MD_TEMPLATE.format(
-        pack_title=pack_title,
-        description=description or f'You are a specialized agent for {pack_title.lower()} tasks.',
-        behaviors_section=BEHAVIORS_TODO,
-        workflow_section=WORKFLOW_TODO,
-        constraints_section=CONSTRAINTS_TODO,
-        output_section=OUTPUT_TODO,
-    )
-
-    try:
-        (pack_dir / 'AGENTS.md').write_text(agents_md_content)
-        print("✅ Created AGENTS.md")
-    except Exception as e:
-        print(f"❌ Error creating AGENTS.md: {e}")
-        return None
-
-    # Register pack in the manifest so it shows up in "Set Active Agent Pack"
-    # The manifest is at .agent-hippo/agentide.manifest.json (parent of "agents" dir)
-    agentide_dir = Path(path).resolve().parent
-    if register_pack_in_manifest(pack_name, agentide_dir, engine):
-        print("✅ Registered pack in manifest")
-    else:
-        print("⚠️  Pack created but failed to registere (add it manually to the manifest or reload window to trigger auto-repair)")
-
-    print(f"\n🎉 Agent pack '{pack_name}' initialized successfully!")
-    print(f"\n📁 Pack location: {pack_dir}")
-    print("\n📝 Next steps:")
-    print("   1. Edit AGENTS.md to define agent behavior")
-    print("   2. Add rule fragments to rules/ (optional)")
-    print("   3. Add skills to skills/ (optional)")
-    print("   4. Run 'Set Active Agent Pack' command to activate")
-
-    return pack_dir
-
-
-def main():
-    parser = argparse.ArgumentParser(
-        description='Initialize a new AgentPack with template files',
-        formatter_class=argparse.RawDescriptionHelpFormatter,
-        epilog="""
-Examples:
-  %(prog)s code-reviewer --path .agent-hippo/agents
-  %(prog)s security-auditor --path .agent-hippo/agents --engine claude
-  %(prog)s my-agent --path .agent-hippo/agents --engine codex --description "Custom agent"
-        """
-    )
-
-    parser.add_argument(
-        'pack_name',
-        help='Name of the agent pack (lowercase, hyphens allowed)'
-    )
-    parser.add_argument(
-        '--path',
-        required=True,
-        help='Parent directory for the pack (e.g., .agent-hippo/agents)'
-    )
-    parser.add_argument(
-        '--engine',
-        choices=['claude', 'codex'],
-        default='claude',
-        help='Preferred engine (default: claude)'
-    )
-    parser.add_argument(
-        '--description',
-        default='',
-        help='Description of the agent pack'
-    )
-    parser.add_argument(
-        '--model',
-        default='',
-        help='Preferred model ID (e.g., claude-sonnet-4). Defaults based on engine if not specified.'
-    )
-
-    args = parser.parse_args()
-
-    result = init_pack(
-        pack_name=args.pack_name,
-        path=args.path,
-        engine=args.engine,
-        description=args.description,
-        model=args.model,
-    )
-
-    sys.exit(0 if result else 1)
-
-
-if __name__ == '__main__':
-    main()
-