Add repo-ask workflow for repository research

.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
+```

.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<<EOF_QUESTION'
+            echo "$QUESTION"
+            echo 'EOF_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'
+            });

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. 
+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.

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/<workflow-name> --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).