@codyswann/lisa 1.56.0 → 1.56.2

package/plugins/lisa-rails/skills/agent-design-best-practices/SKILL.md

@@ -1,219 +0,0 @@
----
-name: agent-design-best-practices
-description: Best practices for designing Claude Code agent files (.claude/agents/*.md). This skill should be used when writing or reviewing agent markdown files to ensure proper design with focused domains, correct tool access, reusable definitions, and separation of capabilities from lifecycle. Combines Anthropic's official guidance with battle-tested patterns from agent team usage.
----
-
-# Agent Design Best Practices
-
-## Overview
-
-This skill defines best practices for designing Claude Code agent files (`.claude/agents/*.md`). Agent files define reusable roles that can be spawned as subagents or teammates. The core principle is that **agent files define capabilities, not lifecycle** -- the team lead's spawn prompt controls when and how the agent runs.
-
-## Principles
-
-### 1. Define Capabilities, Not Lifecycle
-
-Agent files describe *what* an agent can do. The spawn prompt from the team lead controls *when* it runs and *what to focus on*.
-
-```markdown
-<!-- Wrong: Hardcodes workflow phase and interaction pattern -->
-# Security Planner Agent
-
-You are a security specialist in a plan-create Agent Team.
-Given a Research Brief from the team lead, identify security
-considerations for the planned changes.
-
-## Output Format
-
-Send your sub-plan to the team lead via `SendMessage` with this structure:
-...
-```
-
-```markdown
-<!-- Correct: Defines domain expertise, team lead controls usage -->
-# Security Specialist Agent
-
-You are a security specialist who identifies vulnerabilities,
-evaluates threats, and recommends mitigations for code changes.
-
-## Analysis Process
-1. Read affected files
-2. STRIDE analysis
-3. Check input validation
-...
-```
-
-The wrong version is coupled to one workflow ("plan-create Agent Team", "Given a Research Brief", "Send via SendMessage"). The correct version works in any context -- planning, review, ad-hoc analysis -- because the team lead's spawn prompt provides the specific instructions.
-
-### 2. One Agent Per Domain, Not Per Phase
-
-Prefer a single agent that covers a domain over multiple agents split by workflow phase. The team lead specializes the agent per phase via the spawn prompt.
-
-| Wrong | Right |
-|-------|-------|
-| `security-planner` + `security-reviewer` | `security-specialist` |
-| `test-strategist` + `test-coverage-agent` | `test-specialist` |
-| `architecture-planner` + `architecture-reviewer` | `architecture-specialist` |
-
-The same agent type can be spawned multiple times with different prompts for different phases. A `security-specialist` spawned during planning gets "evaluate this plan for security risks" while the same type spawned during review gets "review these code changes for vulnerabilities."
-
-### 3. Design Focused Domains
-
-Each agent should excel at one specific domain. The domain should be broad enough to avoid workflow coupling but narrow enough to provide real expertise.
-
-```yaml
-# Too narrow (coupled to one workflow step)
-description: Performs STRIDE analysis on Research Briefs during plan-create Phase 2
-
-# Too broad (no clear expertise)
-description: General-purpose agent that can do anything
-
-# Just right (focused domain, reusable across workflows)
-description: Security specialist. Performs threat modeling (STRIDE), reviews code for OWASP Top 10 vulnerabilities, checks auth/validation/secrets handling.
-```
-
-### 4. Write Detailed Descriptions
-
-Claude uses the `description` field in YAML frontmatter to decide when to delegate tasks. Be specific about what the agent does and when it adds value.
-
-```yaml
-# Bad: Vague, Claude can't decide when to use it
-description: Reviews code
-
-# Good: Specific domain, clear trigger conditions
-description: Security specialist. Performs threat modeling (STRIDE), reviews code for OWASP Top 10 vulnerabilities, checks auth/validation/secrets handling, and recommends mitigations.
-```
-
-### 5. Limit Tool Access
-
-Grant only the tools necessary for the agent's domain. This enforces focus and prevents agents from exceeding their intended scope.
-
-| Agent Type | Appropriate Tools | Rationale |
-|-----------|-------------------|-----------|
-| Researcher / Reviewer | `Read, Grep, Glob, Bash` | Read-only analysis, no file modifications |
-| Implementer | `Read, Write, Edit, Bash, Grep, Glob` | Needs to modify code |
-| Planner | `Read, Grep, Glob` | Research only, no execution |
-
-Read-only agents cannot implement code. Do not assign implementation tasks to agents without `Write` and `Edit` tools.
-
-### 6. No Hardcoded Interaction Patterns
-
-Do not prescribe how the agent communicates or what input format it expects. The team lead's spawn prompt handles interaction patterns.
-
-```markdown
-<!-- Wrong: Hardcodes communication protocol -->
-## Input
-You receive a **Research Brief** from the team lead containing...
-
-## Output Format
-Send your sub-plan to the team lead via `SendMessage` with this structure:
-```
-
-```markdown
-<!-- Correct: Defines output structure without prescribing delivery mechanism -->
-## Output Format
-Structure your findings as:
-
-### Threat Model (STRIDE)
-| Threat | Applies? | Description | Mitigation |
-...
-```
-
-The output format itself is fine to define -- it provides structure. But how the agent receives input and delivers output should be left to the team lead.
-
-### 7. Context Window Isolation
-
-Each teammate has its own context window. Teammates do not share context and cannot see what other teammates have done. Account for this in agent design:
-
-- Do not assume the agent has seen previous analysis from other agents
-- Include enough domain knowledge in the agent file for independent operation
-- The team lead bridges context between agents via spawn prompts and messages
-
-### 8. File Ownership in Teams
-
-When agents work in teams, each teammate should own distinct files or directories. Two teammates editing the same file leads to conflicts and lost work.
-
-Design agent domains so their file ownership naturally separates:
-
-| Agent | Owns |
-|-------|------|
-| `implementer` | Source files (`src/`) |
-| `test-specialist` | Test files (`tests/`) |
-| `quality-specialist` | No files (read-only) |
-
-## Agent File Structure
-
-### Required Frontmatter
-
-```yaml
----
-name: agent-name           # lowercase with hyphens
-description: When and why to use this agent. Be specific.
-tools: Read, Grep, Glob     # comma-separated, minimal set
----
-```
-
-### Optional Frontmatter
-
-```yaml
-model: sonnet              # sonnet, opus, haiku, or inherit (default)
-permissionMode: default     # default, acceptEdits, plan, bypassPermissions, etc.
-maxTurns: 50               # limit agentic turns
-skills:                     # skills to preload
-  - skill-name
-memory: user                # persistent memory: user, project, or local
-```
-
-### Body Structure
-
-The markdown body becomes the agent's system prompt. Structure it as:
-
-1. **Role statement** -- one sentence describing what the agent is
-2. **Analysis/workflow process** -- numbered steps for the agent's approach
-3. **Output format** -- structure for findings (without prescribing delivery mechanism)
-4. **Rules/constraints** -- guardrails for the agent's behavior
-
-## Anti-Patterns
-
-### Don't Create Phase-Specific Agents
-
-```markdown
-<!-- Wrong: Two agents for the same domain, split by phase -->
-# Pre-Implementation Security Planner
-...
-# Post-Implementation Security Reviewer
-...
-
-<!-- Correct: One agent, team lead controls timing -->
-# Security Specialist
-...
-```
-
-### Don't Hardcode Workflow Dependencies
-
-```markdown
-<!-- Wrong: Agent assumes specific workflow context -->
-You are part of the plan-create Phase 2 team.
-Wait for the Research Brief from Phase 1.
-After your analysis, the Consistency Checker will validate your output.
-
-<!-- Correct: Agent is self-contained -->
-You are a security specialist who identifies vulnerabilities
-and recommends mitigations for code changes.
-```
-
-### Don't Over-Specify the Model
-
-Only set `model` when there's a clear reason. Most agents work well with `inherit` (the default), which uses the same model as the parent session. Use `haiku` for fast, simple tasks (exploration, search). Use `sonnet` or `opus` only when the domain requires stronger reasoning.
-
-## Verification Checklist
-
-Before committing an agent file, verify:
-
-1. **Description is specific** -- Claude can determine when to delegate from the description alone
-2. **Tools are minimal** -- only the tools the agent actually needs
-3. **No workflow coupling** -- no references to specific team structures, phases, or input formats
-4. **No hardcoded communication** -- no "send via SendMessage" or "given a Research Brief"
-5. **Domain is reusable** -- the agent works in planning, review, and ad-hoc contexts
-6. **Role statement is clear** -- first line of body explains what the agent is
-7. **Output format is defined** -- structured output without prescribing delivery

package/plugins/lisa-rails/skills/git-commit/SKILL.md

@@ -1,48 +0,0 @@
----
-name: git-commit
-description: This skill should be used when creating conventional commits for current changes. It groups related changes into logical commits, ensures all files are committed, and verifies the working directory is clean afterward.
-allowed-tools: ["Bash"]
----
-
-# Git Commit Workflow
-
-Create conventional commits for current changes. Optional hint: $ARGUMENTS
-
-## Workflow
-
-### See what has changed
-
-!git status
-!git diff --stat
-
-### Apply these requirements
-
-1. **Branch Check**: If on `dev`, `staging`, or `main`, create a feature branch named after the changes
-2. **Commit Strategy**: Group related changes into logical conventional commits (feat, fix, chore, docs, etc.)
-3. **Commit ALL Files**: Every file must be assigned to a commit group - no file gets left out or unstaged
-4. **Commit Creation**: Stage and commit each group with clear messages
-5. **Verification**: Run `git status` to confirm working directory is clean - must show "nothing to commit"
-
-### Use conventional commit format
-
-- `feat:` for new features
-- `fix:` for bug fixes
-- `docs:` for documentation
-- `chore:` for maintenance
-- `style:` for formatting
-- `refactor:` for code restructuring
-- `test:` for test additions
-
-### Never
-
-- use `--no-verify` flag
-- attempt to bypass tests or quality checks
-- skip tests or quality checks
-- stash changes - ALL changes must be committed
-- skip or exclude any files from the commit - even if they're unrelated
-- leave uncommitted changes in the working directory
-- ask the user which files to commit - commit everything
-
-## Execute
-
-Execute the workflow now.

package/plugins/lisa-rails/skills/git-commit-and-submit-pr/SKILL.md

@@ -1,8 +0,0 @@
----
-name: git-commit-and-submit-pr
-description: This skill should be used when creating conventional commits for current changes and then submitting the current branch as a pull request for code review. It combines the git:commit and git:submit-pr skills into a single workflow.
-allowed-tools: ["Bash"]
----
-
-1. Run /git-commit $ARGUMENTS
-2. Run /git-submit-pr $ARGUMENTS

package/plugins/lisa-rails/skills/git-commit-submit-pr-and-verify/SKILL.md

@@ -1,7 +0,0 @@
----
-name: git-commit-submit-pr-and-verify
-description: This skill should be used when creating conventional commits for current changes and then submitting the current branch as a pull request for code review. And then verifying the pull request was approved.
-allowed-tools: ["Bash"]
----
-
-Run the /git-commit-and-submit-pr with $ARGUMENTS and set the PR to auto-merge. Fix any pre-commit or pre-push issues and then follow the pr, make sure all checks pass and comments are resolved or addressed. Fix anything that is broken and repeat.

package/plugins/lisa-rails/skills/git-commit-submit-pr-deploy-and-verify/SKILL.md

@@ -1,7 +0,0 @@
----
-name: git-commit-submit-pr-deploy-and-verify
-description: This skill should be used when creating conventional commits for current changes and then submitting the current branch as a pull request for code review. And then verifying the pull request was approved. As well as making sure the resutling deploy succeeds.
-allowed-tools: ["Bash"]
----
-
-Run the /git-commit-submit-pr-and-verify with $ARGUMENTS. Once the merge is complete, follow the resulting deploy and fix anything that breaks with the deploy and then follow this process again with a new PR until the deploy succeeds.

package/plugins/lisa-rails/skills/git-prune/SKILL.md

@@ -1,35 +0,0 @@
----
-name: git-prune
-description: This skill should be used when pruning local branches that have been deleted on the remote. It fetches remote changes, identifies stale local branches, and safely deletes them.
-allowed-tools: ["Bash"]
----
-
-# Git Prune Local Branches
-
-Remove local branches whose upstream tracking branches have been deleted on remote.
-
-## Workflow
-
-### Fetch and prune remote-tracking references
-
-!git fetch --prune
-
-### Find and delete stale local branches
-
-!git branch -vv | grep ': gone]' | awk '{print $1}'
-
-### Apply these requirements
-
-1. **Preview**: Show which branches will be deleted before deleting
-2. **Safe Delete**: Use `-d` (safe delete) which refuses to delete unmerged branches
-3. **Report**: Show summary of deleted branches
-
-### Never
-
-- Force delete (`-D`) without user confirmation
-- Delete the current branch
-- Delete protected branches (dev, staging, main)
-
-## Execute
-
-Execute the workflow now.

package/plugins/lisa-rails/skills/git-submit-pr/SKILL.md

@@ -1,44 +0,0 @@
----
-name: git-submit-pr
-description: This skill should be used when pushing changes and creating or updating a pull request. It verifies the branch state, pushes to remote, creates or updates a PR with a comprehensive description, and enables auto-merge.
-allowed-tools: ["Bash", "mcp__github__create_pull_request", "mcp__github__get_pull_request", "mcp__github__update_pull_request"]
----
-
-# Submit Pull Request Workflow
-
-Push current branch and create or update a pull request. Optional hint: $ARGUMENTS
-
-## Workflow
-
-### Check current state
-
-!git status
-!git log --oneline -10
-
-### Apply these requirements
-
-1. **Branch Check**: Verify not on `dev`, `staging`, or `main` (cannot create PR from protected branches)
-2. **Commit Check**: Ensure all changes are committed before pushing
-3. **Push**: Push current branch to remote with `-u` flag and the following environment variable - GIT_SSH_COMMAND="ssh -o ServerAliveInterval=30 -o ServerAliveCountMax=5"
-4. **PR Management**:
-   - Check for existing PR on this branch
-   - If exists: Update description with latest changes
-   - If not: Create PR with comprehensive description (not a draft)
-5. **Auto-merge**: Enable auto-merge on the PR using `gh pr merge --auto --merge`
-
-### PR Description Format
-
-Include in the PR description:
-
-- **Summary**: Brief overview of changes (1-3 bullet points)
-- **Test plan**: How to verify the changes work correctly
-
-### Never
-
-- use `--force` push without explicit user request
-- create PR from protected branches (dev, staging, main)
-- skip pushing before PR creation
-
-## Execute
-
-Execute the workflow now.

package/plugins/lisa-rails/skills/jira-fix/SKILL.md

@@ -1,16 +0,0 @@
----
-name: jira-fix
-description: This skill should be used when fixing a bug ticket in JIRA
----
-
-1. Use the JIRA/Atlassian MCP or CLI to fully read this issue, including comments and attachments: $ARGUMENTS
-2. Extract sign-in information if available from the ticket (e.g., test credentials, OTP codes)
-3. Use the project's verification method to attempt to reproduce the bug:
-   - For UI projects: Use Playwright MCP browser tools to record a replication
-   - For API projects: Use curl or test commands to reproduce the error
-   - For library projects: Write a minimal reproduction test
-4. If you cannot reproduce the issue, upload the evidence to the JIRA ticket explaining that you can't replicate it and skip the remaining steps
-5. If there have already been attempts to fix this bug, understand the previous attempts by looking for pull requests and git commits related to it
-6. Fix the bug
-7. Verify the fix using the same verification method used in step 3
-8. Upload the evidence to the JIRA ticket and explain the fix

package/plugins/lisa-rails/skills/jira-implement/SKILL.md

@@ -1,18 +0,0 @@
----
-name: jira-implement
-description: This skill should be used when implementing the requirements in a JIRA ticket.
----
-
-Use either the Atlassian MCP or CLI to examine the contents of the JIRA ticket: $ARGUMENTS
-
-If neither is available, stop and report that you cannot access the ticket.
-
-Read all the details in the ticket, including any URLs and attachments.
-
-Make a plan to fulfill the requirements of the ticket.
-
-Important: If this involves UI changes, use Playwright MCP browser tools to access the app and get a better understanding of what needs to be done. Create a verification task using browser tools to confirm the implementation.
-
-Important: If this involves API or backend changes, use curl or test commands to understand current behavior. Create a verification task to confirm the implementation.
-
-If you don't know how to access the app or service, clarify when making the plan.

package/plugins/lisa-rails/skills/jira-journey/scripts/generate-templates.py

@@ -1,233 +0,0 @@
-#!/usr/bin/env python3
-"""Generate evidence comment templates from captured text evidence.
-
-Scans an evidence directory for text/JSON evidence files, reads the journey JSON,
-and produces comment.txt (JIRA wiki markup) and comment.md (GitHub markdown).
-
-Usage:
-    python3 generate-templates.py <TICKET_ID> <PR_NUMBER> <BRANCH_NAME> <EVIDENCE_DIR> [JOURNEY_JSON]
-
-Example:
-    python3 generate-templates.py PROJ-123 42 fix/PROJ-123-api ./evidence journey.json
-
-If JOURNEY_JSON is not provided, reads from stdin.
-"""
-
-import json
-import os
-import re
-import subprocess
-import sys
-from pathlib import Path
-
-
-def get_jira_server():
-    """Read JIRA server URL from jira-cli config."""
-    config_path = Path.home() / ".config" / ".jira" / ".config.yml"
-    if not config_path.exists():
-        return ""
-    with open(config_path) as f:
-        for line in f:
-            if line.startswith("server:"):
-                return line.split(":", 1)[1].strip()
-    return ""
-
-
-def get_github_repo():
-    """Detect GitHub repo from gh CLI."""
-    try:
-        result = subprocess.run(
-            ["gh", "repo", "view", "--json", "nameWithOwner", "--jq", ".nameWithOwner"],
-            capture_output=True, text=True, timeout=10,
-        )
-        return result.stdout.strip()
-    except (subprocess.SubprocessError, FileNotFoundError):
-        return ""
-
-
-def collect_evidence(evidence_dir):
-    """Collect evidence files (text, JSON, and images) sorted by name."""
-    evidence_path = Path(evidence_dir)
-    files = []
-    for pattern in ("[0-9][0-9]-*.txt", "[0-9][0-9]-*.json", "[0-9][0-9]-*.png"):
-        files.extend(evidence_path.glob(pattern))
-    # Exclude comment.txt
-    files = [f for f in files if f.name != "comment.txt"]
-    return sorted(files, key=lambda p: p.name)
-
-
-def detect_language(filename, content):
-    """Detect code block language from filename extension and content."""
-    if filename.endswith(".json"):
-        return "json"
-    if "HTTP/" in content or "curl" in content.lower():
-        return "http"
-    if "CREATE TABLE" in content or "ALTER TABLE" in content or "\\d " in content:
-        return "sql"
-    return "text"
-
-
-def generate_jira_wiki(ticket_id, pr_number, branch, evidence_files, journey, gh_repo):
-    """Generate JIRA wiki markup comment with code block evidence."""
-    lines = []
-    lines.append(f"h2. Evidence — PR #{pr_number}")
-    lines.append("")
-    lines.append(f"*Branch:* {{{{{branch}}}}}")
-    lines.append(f"*PR:* [PR #{pr_number}|https://github.com/{gh_repo}/pull/{pr_number}]")
-    lines.append("")
-
-    # Verification Results from assertions
-    if journey.get("assertions"):
-        lines.append("h3. Verification Results")
-        lines.append("")
-        for assertion in journey["assertions"]:
-            lines.append(f"* {assertion}")
-        lines.append("")
-
-    # Evidence
-    lines.append("h3. Evidence")
-    lines.append("")
-
-    for evidence_path in evidence_files:
-        filename = evidence_path.name
-        stem = evidence_path.stem
-        # Extract readable label: remove NN- prefix
-        label_parts = stem.split("-")[1:]
-        label = " ".join(label_parts).title() if label_parts else stem
-
-        if filename.endswith(".png"):
-            display_width = 700
-            lines.append(f"*{label}:*")
-            lines.append(f"!{filename}|width={display_width}!")
-            lines.append("")
-        else:
-            content = evidence_path.read_text().strip()
-            lang = detect_language(filename, content)
-            lines.append(f"*{label}:*")
-            lines.append(f"{{code:{lang}}}")
-            lines.append(content)
-            lines.append("{code}")
-            lines.append("")
-
-    # Verification Journey steps
-    if journey.get("steps"):
-        lines.append("h3. Verification Journey")
-        lines.append("")
-        for step in journey["steps"]:
-            text = step["text"]
-            clean_text = re.sub(r'\s*\[(SCREENSHOT|EVIDENCE):\s*[^\]]+\]', '', text).strip()
-            lines.append(f"# {clean_text}")
-        lines.append("")
-
-    return "\n".join(lines)
-
-
-def generate_github_md(ticket_id, pr_number, branch, evidence_files, journey, gh_repo, jira_server):
-    """Generate GitHub markdown comment with code block evidence."""
-    release_base = f"https://github.com/{gh_repo}/releases/download/pr-assets"
-
-    lines = []
-    lines.append(f"## Evidence — PR #{pr_number}")
-    lines.append("")
-    lines.append(f"**Branch:** `{branch}`")
-    if jira_server:
-        lines.append(f"**Ticket:** [{ticket_id}]({jira_server}/browse/{ticket_id})")
-    else:
-        lines.append(f"**Ticket:** {ticket_id}")
-    lines.append("")
-
-    # Verification Results
-    if journey.get("assertions"):
-        lines.append("### Verification Results")
-        lines.append("")
-        for assertion in journey["assertions"]:
-            lines.append(f"- {assertion}")
-        lines.append("")
-
-    # Evidence
-    lines.append("### Evidence")
-    lines.append("")
-
-    for evidence_path in evidence_files:
-        filename = evidence_path.name
-        stem = evidence_path.stem
-        label_parts = stem.split("-")[1:]
-        label = " ".join(label_parts).title() if label_parts else stem
-
-        if filename.endswith(".png"):
-            lines.append(f"**{label}:**")
-            lines.append("")
-            lines.append(f"![{label}]({release_base}/{filename})")
-            lines.append("")
-        else:
-            content = evidence_path.read_text().strip()
-            lang = detect_language(filename, content)
-            lines.append(f"**{label}:**")
-            lines.append("")
-            lines.append(f"```{lang}")
-            lines.append(content)
-            lines.append("```")
-            lines.append("")
-
-    # Verification Journey
-    if journey.get("steps"):
-        lines.append("### Verification Journey")
-        lines.append("")
-        for step in journey["steps"]:
-            text = step["text"]
-            clean_text = re.sub(r'\s*\[(SCREENSHOT|EVIDENCE):\s*[^\]]+\]', '', text).strip()
-            lines.append(f"{step['number']}. {clean_text}")
-        lines.append("")
-
-    return "\n".join(lines)
-
-
-def main():
-    if len(sys.argv) < 5:
-        print(
-            "Usage: generate-templates.py <TICKET_ID> <PR_NUMBER> <BRANCH_NAME> <EVIDENCE_DIR> [JOURNEY_JSON]",
-            file=sys.stderr,
-        )
-        sys.exit(1)
-
-    ticket_id = sys.argv[1]
-    pr_number = sys.argv[2]
-    branch = sys.argv[3]
-    evidence_dir = sys.argv[4]
-    journey_file = sys.argv[5] if len(sys.argv) > 5 else None
-
-    # Read journey JSON
-    if journey_file:
-        with open(journey_file) as f:
-            journey = json.load(f)
-    else:
-        journey = json.load(sys.stdin)
-
-    gh_repo = get_github_repo()
-    if not gh_repo:
-        print("ERROR: Could not detect GitHub repo — ensure gh CLI is authenticated", file=sys.stderr)
-        sys.exit(1)
-
-    jira_server = get_jira_server()
-
-    evidence_files = collect_evidence(evidence_dir)
-    if not evidence_files:
-        print(f"ERROR: No evidence files found in {evidence_dir}", file=sys.stderr)
-        sys.exit(1)
-
-    # Generate templates
-    jira_wiki = generate_jira_wiki(ticket_id, pr_number, branch, evidence_files, journey, gh_repo)
-    github_md = generate_github_md(ticket_id, pr_number, branch, evidence_files, journey, gh_repo, jira_server)
-
-    # Write templates
-    evidence_path = Path(evidence_dir)
-    (evidence_path / "comment.txt").write_text(jira_wiki)
-    (evidence_path / "comment.md").write_text(github_md)
-
-    print(f"Generated {evidence_path / 'comment.txt'} ({len(jira_wiki)} bytes)")
-    print(f"Generated {evidence_path / 'comment.md'} ({len(github_md)} bytes)")
-    print(f"Evidence files: {len(evidence_files)}")
-
-
-if __name__ == "__main__":
-    main()