@agenthippo-ai/agenthippo 0.1.0

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

@@ -0,0 +1,195 @@
+# 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

@@ -0,0 +1,391 @@
+#!/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()
+