OpenSearch Feature Explorer

A tool to analyze OpenSearch release notes and generate detailed feature/release reports.

Overview

graph TB
    subgraph Input
        RN[Release Notes]
        PR[Pull Requests]
        Issue[Issues]
        Docs[Docs/Blogs]
    end
    subgraph "Kiro CLI + MCP"
        Agent[Agents]
        MCP[OpenSearch Docs MCP]
    end
    subgraph Output
        FR[Feature Reports]
        RR[Release Reports]
        GH[GitHub Issues]
    end
    RN --> Agent
    PR --> Agent
    Issue --> Agent
    Docs --> MCP --> Agent
    Agent --> FR
    Agent --> RR
    Agent --> GH

Loading

Agents

Agent	Description
group-release	Group raw items into feature groups → save to groups.json
review-groups	Review and refine groups (split over-aggregated, merge related)
review-release	Review release content
planner	Create GitHub Project and Issues from groups.json
create-issues	Create individual investigation Issues from tracking Issue
investigate	Deep investigation (4 modes: Issue, PR, Feature, Interactive Q&A)
summarize	Aggregate release reports into release summary
generate-release-docs	Generate release docs from existing feature documents
refactor	Batch structural changes to existing reports
translate	Translate reports to other languages
dev	Development and maintenance of this tool itself

Note: fetch-release runs as a Python function directly (not as a Kiro agent).

Requirements

• Python 3.8+
• Kiro CLI
• GitHub CLI (gh) - authenticated via gh auth login
• Node.js (for GitHub MCP Server)

GitHub Token Scopes

Run gh auth login with required scopes:

gh auth login -s read:org,repo,workflow,project

Scope	Purpose
repo	Issue/PR operations
project	GitHub Projects (progress tracking)
workflow	GitHub Actions (MkDocs deployment)
read:org	Organization info
gist	(included by default)

Naming Conventions

Resource	Pattern	Example
GitHub Project	v{version} Investigation	v3.0.0 Investigation
Issue (group)	[{category}] {group_name}	[feature] Star Tree Index
Label (release)	release/v{version}	release/v3.0.0
Label (status)	status/{status}	status/todo, status/done
Cache directory	.cache/releases/v{version}/	.cache/releases/v3.0.0/
Data directory	data/releases/v{version}/	data/releases/v3.0.0/
Release report	docs/releases/v{version}/features/{repo}/{item-name}.md	docs/releases/v3.0.0/features/opensearch/star-tree-index.md
Feature report	docs/features/{repo}/{feature-name}.md	docs/features/opensearch/star-tree-index.md

Setup

git clone https://github.com/tkykenmt/opensearch-feature-explorer.git
cd opensearch-feature-explorer
pip install -r requirements.txt

# Authenticate GitHub CLI (required for GitHub MCP)
gh auth login

GitHub Repository Settings

Enable the following in your repository settings (Settings → General):

• Pull Requests: Enable "Automatically delete head branches" to clean up feature branches after PR merge
• Pages (Settings → Pages): Set Source to "GitHub Actions" for automatic deployment

Usage

Use Case 1: Full Release Investigation

Complete workflow for investigating a new OpenSearch release.

flowchart TB
    A[release-investigate] --> B[(Release Reports)]
    A --> C[(Feature Reports)]
    A --> D[(Release Summary)]

Loading

python run.py release-investigate 3.0.0

Manual step-by-step execution

Step 1: Fetch Release Notes

flowchart TB
    A[fetch-release] --> B[(raw-items.json)]

Loading

python run.py fetch-release 3.0.0

Step 2: Group Items

flowchart TB
    A[(raw-items.json)] --> B[group-release]
    B --> C[(groups.json)]

Loading

python run.py group-release 3.0.0 --all

Step 3: Create GitHub Project & Issues

flowchart TB
    A[(groups.json)] --> B[planner]
    B --> C[(GitHub Project)]
    B --> D[(Issues)]

Loading

python run.py planner 3.0.0

Step 4: Investigate Each Issue

flowchart TB
    A[(Issue)] --> B[investigate]
    B --> C[(Release Report)]
    B --> D[(Feature Report)]

Loading

python run.py investigate --issue 124
# Or batch process all
python run.py batch-investigate --all
# Or batch process specific version
python run.py batch-investigate 3.0.0 --all

Step 5: Create Release Summary

flowchart TB
    A[(Release Reports)] --> B[summarize]
    B --> C[(Release Summary)]

Loading

python run.py summarize 3.0.0

Use Case 2: Single Feature Investigation

Quick investigation of a specific feature without full release workflow.

flowchart TB
    A[PR Number] --> B[investigate]
    C[Feature Name] --> B
    B --> D[Feature Report]

Loading

# From a specific PR
python run.py investigate --pr 16233

# From feature name + PR
python run.py investigate --feature "Star Tree" --pr 16233

# Feature deep dive (searches all related PRs)
python run.py investigate --feature "Star Tree"

Use Case 3: Interactive Exploration

Explore features interactively with Q&A.

flowchart TB
    A[investigate] --> B[Q&A Session]
    B --> C[Import URLs]
    C --> B

Loading

python run.py investigate

Planner Options

# Ignore existing tracking Issue and create new one
python run.py planner 3.0.0 -i
python run.py planner 3.0.0 --ignore-existing

Output Structure

docs/
├── features/                          # Cumulative feature documentation
│   ├── index.md
│   ├── opensearch/
│   │   ├── star-tree-index.md
│   │   └── star-tree-index.ja.md
│   ├── neural-search/
│   │   └── semantic-highlighting.md
│   └── k-nn/
│       └── explain-api.md
└── releases/
    └── v3.0.0/
        ├── index.md                   # Release index
        ├── summary.md                 # Release summary (from summarize)
        └── features/
            ├── opensearch/
            │   ├── star-tree-enhancements.md
            │   └── grpc-transport.md
            ├── neural-search/
            │   └── semantic-highlighting.md
            └── k-nn/
                └── explain-api.md

Local Preview

mkdocs serve
# Open http://localhost:8000

Development

See DEVELOPMENT.md for:

• Project structure and conventions
• Document templates and rules
• Agent system details
• Contributing guidelines

Disclosure

This project uses generative AI to create documentation. Generated content may contain inaccuracies. Always verify information against official OpenSearch documentation and source code.