diff --git a/.github/workflows/agentics/repo-ask.config.md b/.github/workflows/agentics/repo-ask.config.md new file mode 100644 index 0000000..7f9a1e0 --- /dev/null +++ b/.github/workflows/agentics/repo-ask.config.md @@ -0,0 +1,73 @@ +# Repo Ask Configuration + +This file is a **template** for configuring the repo-ask workflow behavior. The current `.github/workflows/repo-ask.yml` workflow does **not** yet read or apply this file, and `gh aw compile` is not wired up in this repository, so edits here will not affect runtime behavior until that integration is implemented. + +## Research Settings + +```yaml +# Maximum depth for repository exploration +max_depth: 3 + +# File types to analyze +file_types: + - "*.py" + - "*.js" + - "*.ts" + - "*.md" + - "*.yml" + - "*.yaml" + - "*.json" + +# Directories to exclude from analysis +exclude_dirs: + - node_modules + - .git + - __pycache__ + - dist + - build +``` + +## Response Settings + +```yaml +# Response format (markdown, plain) +format: markdown + +# Include code snippets in responses +include_code: true + +# Maximum response length (characters) +max_length: 4000 +``` + +## Tool Permissions + +```yaml +# Allowed bash commands +allowed_commands: + - find + - grep + - ls + - cat + - head + - tail + - wc + +# Allow web search +web_search: true + +# Allow API calls to external services +external_apis: false +``` + +## Custom Instructions + +Add any custom instructions for the AI agent below: + +``` +When answering questions: +1. Always provide code examples when relevant +2. Reference specific files in the repository +3. Include links to relevant documentation +4. Suggest follow-up actions when appropriate +``` diff --git a/.github/workflows/repo-ask.yml b/.github/workflows/repo-ask.yml new file mode 100644 index 0000000..6a4376c --- /dev/null +++ b/.github/workflows/repo-ask.yml @@ -0,0 +1,153 @@ +name: Repo Ask + +# Intelligent research assistant triggered by /repo-ask command +# Documentation: docs/workflows/repo-ask.md + +on: + issue_comment: + types: [created] + +jobs: + repo-ask: + name: Research and Answer + # Only run if comment starts with /repo-ask and user has write permissions + if: | + github.event.issue && + startsWith(github.event.comment.body, '/repo-ask') && + ( + github.event.comment.author_association == 'OWNER' || + github.event.comment.author_association == 'MEMBER' || + github.event.comment.author_association == 'COLLABORATOR' + ) + runs-on: ubuntu-latest + permissions: + contents: read + issues: write + pull-requests: write + steps: + - name: Checkout repository + uses: actions/checkout@v4 + with: + fetch-depth: 0 + + - name: Parse question from comment + id: parse + env: + COMMENT_BODY: ${{ github.event.comment.body }} + run: | + # Extract the question from the comment (everything after /repo-ask) + QUESTION=$(echo "$COMMENT_BODY" | sed 's|^/repo-ask[[:space:]]*||') + + # If no question provided, use a default prompt + if [ -z "$QUESTION" ]; then + QUESTION="Please provide an overview of this repository and its main features." + fi + + # Write the question to GITHUB_OUTPUT using multiline syntax + { + echo 'question<> "$GITHUB_OUTPUT" + echo "Parsed question: $QUESTION" + + - name: Add reaction to acknowledge command + uses: actions/github-script@v7 + with: + script: | + await github.rest.reactions.createForIssueComment({ + owner: context.repo.owner, + repo: context.repo.repo, + comment_id: context.payload.comment.id, + content: 'eyes' + }); + + - name: Gather repository information + id: repo-info + run: | + echo "## Repository Analysis" > /tmp/repo-analysis.md + echo "" >> /tmp/repo-analysis.md + + echo "### Structure" >> /tmp/repo-analysis.md + echo "\`\`\`" >> /tmp/repo-analysis.md + find . -maxdepth 2 -type f \( -name "*.md" -o -name "*.py" -o -name "*.js" -o -name "*.ts" \) | head -50 >> /tmp/repo-analysis.md + echo "\`\`\`" >> /tmp/repo-analysis.md + echo "" >> /tmp/repo-analysis.md + + echo "### README Preview" >> /tmp/repo-analysis.md + if [ -f "README.md" ]; then + echo "\`\`\`" >> /tmp/repo-analysis.md + head -50 README.md >> /tmp/repo-analysis.md + echo "\`\`\`" >> /tmp/repo-analysis.md + fi + + # Store file list for context + find . -type f \( -name "*.py" -o -name "*.js" -o -name "*.ts" -o -name "*.md" \) | head -100 > /tmp/file-list.txt + + - name: Post processing message + uses: actions/github-script@v7 + env: + QUESTION: ${{ steps.parse.outputs.question }} + with: + script: | + const question = process.env.QUESTION; + + await github.rest.issues.createComment({ + owner: context.repo.owner, + repo: context.repo.repo, + issue_number: context.issue.number, + body: `🔍 **Repo Ask** is researching your question...\n\n> ${question}\n\n_This may take a moment. I'll be back with my findings soon._` + }); + + - name: Research complete notification + uses: actions/github-script@v7 + env: + QUESTION: ${{ steps.parse.outputs.question }} + with: + script: | + const fs = require('fs'); + const question = process.env.QUESTION; + + // Read repository analysis + let repoAnalysis = ''; + try { + repoAnalysis = fs.readFileSync('/tmp/repo-analysis.md', 'utf8'); + } catch (e) { + repoAnalysis = 'Repository analysis not available.'; + } + + // For now, provide a basic response template + // In a full implementation, this would be replaced with AI agent processing + const response = [ + '## 🔍 Repo Ask Response', + '', + '**Question:** ' + question, + '', + '### Repository Context', + '', + repoAnalysis, + '', + '---', + '', + '⚠️ **Note:** This is a basic response from the repo-ask workflow. For full AI-powered research capabilities, configure an AI agent as described in the [workflow documentation](docs/workflows/repo-ask.md).', + '', + '_To configure an AI agent, see [choosing a coding agent](https://githubnext.github.io/gh-aw/reference/engines/)._' + ].join('\n'); + + await github.rest.issues.createComment({ + owner: context.repo.owner, + repo: context.repo.repo, + issue_number: context.issue.number, + body: response + }); + + - name: Add completion reaction + uses: actions/github-script@v7 + with: + script: | + await github.rest.reactions.createForIssueComment({ + owner: context.repo.owner, + repo: context.repo.repo, + comment_id: context.payload.comment.id, + content: 'rocket' + }); diff --git a/README.md b/README.md index 81997fc..c090c3e 100644 --- a/README.md +++ b/README.md @@ -33,4 +33,18 @@ Open http://localhost:8080/health to verify the API is running. ## Development -The workspace includes a **DevContainer** definition – simply open the folder in VS Code or Cursor and choose *Reopen in Container* to get an IDE connected to the running services. \ No newline at end of file +The workspace includes a **DevContainer** definition – simply open the folder in VS Code or Cursor and choose *Reopen in Container* to get an IDE connected to the running services. + +## Agentic Workflows + +This repository includes agentic workflow definitions designed to integrate with AI agents to automate development tasks. Note that the current Repo Ask workflow returns a static/template response and does not yet invoke an AI agent engine. See [docs/workflows/README.md](docs/workflows/README.md) for available workflows. + +### Repo Ask + +A repository research assistant workflow (currently implemented as a template-based response workflow). Trigger it by adding a comment to any issue or PR: + +``` +/repo-ask How does the authentication system work? +``` + +See [Repo Ask documentation](docs/workflows/repo-ask.md) for more details. diff --git a/docs/workflows/README.md b/docs/workflows/README.md new file mode 100644 index 0000000..a4d141c --- /dev/null +++ b/docs/workflows/README.md @@ -0,0 +1,55 @@ +# Agentic Workflows + +This directory contains documentation for agentic workflows that can be added to your repository. These workflows are designed to integrate with AI agents to automate common development tasks. Note that the current Repo Ask workflow returns a template-based response and does not yet invoke an AI agent engine. + +## Available Workflows + +| Workflow | Description | Trigger | +|----------|-------------|---------| +| [Repo Ask](./repo-ask.md) | Repository research assistant (template-based response) | `/repo-ask` command | + +## How Workflows Work + +Agentic workflows are GitHub Actions workflows that are triggered by commands in issue or pull request comments. When you add a comment with a supported command (e.g., `/repo-ask`), the workflow is triggered and processes your request. + +## Installation + +To install a workflow, use the `gh aw` extension: + +```bash +# Install the gh aw extension +gh extension install githubnext/gh-aw + +# Add a workflow to your repository +gh aw add githubnext/agentics/ --pr +``` + +This creates a pull request to add the workflow to your repository. + +## Configuration + +Each workflow can be customized via configuration files in `.github/workflows/agentics/`. After editing configuration files, run `gh aw compile` to update the workflow. + +## Security Considerations + +⚠️ **Important Security Notes:** + +1. **Permissions**: Workflows run with the permissions specified in the workflow file. Review permissions carefully before enabling. + +2. **Network Access**: Some workflows may have network access to perform web searches or API calls. + +3. **Code Execution**: Workflows may execute bash commands within the GitHub Actions VM. + +4. **Triggering**: Only repository admins, maintainers, or users with write permissions should trigger workflows. + +## Adding New Workflows + +To add documentation for a new workflow: + +1. Create a new markdown file in this directory (e.g., `my-workflow.md`) +2. Follow the format of existing workflow documentation +3. Update this README to include the new workflow in the table + +## Support + +For issues with the `gh aw` extension, visit [githubnext/gh-aw](https://github.com/githubnext/gh-aw). diff --git a/docs/workflows/repo-ask.md b/docs/workflows/repo-ask.md new file mode 100644 index 0000000..c8f046e --- /dev/null +++ b/docs/workflows/repo-ask.md @@ -0,0 +1,112 @@ +# 🔍 Repo Ask + +> For an overview of all available workflows, see the [main README](../../README.md). + +The [repo-ask workflow](../../.github/workflows/repo-ask.yml) is a command-triggered workflow that posts a templated response summarizing your repository, such as a file listing and README preview, when invoked with the `repo-ask` command. + +You can trigger the workflow by adding a comment to any issue or pull request with the command: + +``` +/repo-ask +``` + +or by writing a comment with a specific question: + +``` +/repo-ask How does the authentication system work in this project? +``` + +## Installation + +```bash +# Install the 'gh aw' extension +gh extension install githubnext/gh-aw + +# Add the Repo Ask workflow to your repository +gh aw add githubnext/agentics/repo-ask --pr +``` + +This creates a pull request to add the workflow to your repository. + +You must also [choose a coding agent](https://githubnext.github.io/gh-aw/reference/engines/) and add an API key secret for the agent to your repository. + +You can't start a run of this workflow directly as it is triggered in the context of an issue or pull request comment. + +To trigger the workflow on a specific issue or pull request, add a comment with the command: + +``` +/repo-ask [your question here] +``` + +**Mandatory Checklist** + +* [ ] I have read the notes on coding tasks in the [main README](../../README.md) and understand the implications. + +* [ ] I understand that this workflow will generate and run bash commands within the confines of the GitHub Actions VM, with network access. + +* [ ] I am a repository admin, maintainer, or have write permissions to trigger this workflow. + +* [ ] If in a fork, I have enabled "GitHub Actions" and "GitHub Issues" in the fork repository settings. + +## Configuration + +This workflow requires no configuration and works out of the box. You can customize research behavior, response format, and allowed tools. Local configuration can be done in `.github/workflows/agentics/repo-ask.config.md`. + +After editing run `gh aw compile` to update the workflow and commit all changes to the default branch. + +## What it reads from GitHub + +- Repository contents and file structure +- Issue or pull request context where the command was triggered +- Pull requests and their metadata +- Actions workflow runs and results +- Repository documentation and code files +- Project configuration files + +## What it creates + +- Adds detailed research-based comments to issues or pull requests +- Requires `issues: write` permission + +## What web searches it performs + +- Searches for relevant documentation and resources online +- Looks up technical information related to the repository's technologies +- Researches best practices and solutions for specific questions +- May search for community discussions and expert opinions + +## What bash commands it runs + +- Repository analysis commands (e.g., `find`, `grep`, `ls`) +- Code inspection commands to understand project structure +- Test execution to verify functionality +- Build commands to understand the development workflow +- Any other repository exploration commands needed to answer questions + +## Use Cases + +- **Documentation Research**: Ask about how specific features work or are implemented +- **Code Analysis**: Get explanations of complex code patterns or architectures +- **Troubleshooting**: Research solutions for build issues or configuration problems +- **Best Practices**: Get recommendations for improving code or project structure +- **Feature Investigation**: Understand what features exist and how they're used +- **Dependency Analysis**: Learn about project dependencies and their purposes + +## Example Commands + +``` +/repo-ask Has anyone reported similar issues in the past? +/repo-ask Is this bug related to any known issues in the codebase? +/repo-ask What are the testing requirements for this type of change? +/repo-ask How does this PR affect the existing authentication flow? +/repo-ask Are there similar implementations I should look at for reference? +/repo-ask What's the best way to test this feature locally? +/repo-ask Does this change require any documentation updates? +/repo-ask What are the performance implications of this approach? +``` + +## Human in the loop + +- Review research findings and answers provided by the workflow +- Ask follow-up questions or request clarification as needed +- Validate technical recommendations before implementing them