v1.6 to v1.6

19 added, 0 removed. Audit A to A.

---

name: new-feature-design

description: "Design and document new features with GitHub issue, low-level design (LLD), expert review, and testing plan. Creates structured documentation in .scratchpad/ with issue spec, technical design with diagrams and pseudo-code, multi-persona expert review, and a testing plan covering functional (curl and registry_management.py), backwards-compatibility, UX, ECS/terraform, and E2E API tests. Supports starting from a user description OR an existing GitHub issue URL. Folder naming: issue-{number}/ for existing issues, {feature-name}/ for new features."

license: Apache-2.0

metadata:

author: mcp-gateway-registry

version: "1.6"

---

# New Feature Design Skill

Use this skill when the user wants to design a new feature for the MCP Gateway Registry. This skill creates comprehensive design documentation that enables entry-level developers to implement the feature.

## Input Modes

This skill supports two input modes:

1. **User Description Mode** - User describes the feature they want to design

2. **GitHub Issue URL Mode** - User provides a URL to an existing GitHub issue

### Detecting Input Mode

When the user invokes this skill:

- If they provide a GitHub issue URL (e.g., `https://github.com/owner/repo/issues/123`), use **GitHub Issue URL Mode**

- Otherwise, use **User Description Mode**

## Workflow

### User Description Mode Workflow

1. **Gather Requirements** - Ask clarifying questions about the feature

2. **Quick Codebase Review** - Explore the codebase to understand structure

3. **Create Design Folder** - Create `.scratchpad/{feature-name}/` directory

4. **Write GitHub Issue** - Create `github-issue.md` for issue creation

5. **Deep Codebase Analysis** - Thoroughly explore relevant code

6. **Write Low-Level Design** - Create `lld.md` with technical details

7. **Expert Review** - Create `review.md` with multi-persona feedback

8. **Write Testing Plan** - Create `testing.md` with functional, backwards-compat, UX, ECS, and E2E tests

9. **Present Summary & Seek Guidance** - Present findings and ask for direction

### GitHub Issue URL Mode Workflow

1. **Fetch GitHub Issue** - Retrieve issue content using `gh` CLI

2. **Analyze Issue Content** - Extract requirements, design elements, and context

3. **Quick Codebase Review** - Explore the codebase to understand structure

4. **Create Design Folder** - Create `.scratchpad/issue-{number}/` directory (e.g., `issue-500` for GitHub issue #500)

5. **Summarize Existing Issue** - Create `github-issue.md` summarizing the existing issue

6. **Clarify Requirements** - Ask user about any gaps or ambiguities found

7. **Deep Codebase Analysis** - Thoroughly explore relevant code

8. **Write Low-Level Design** - Create `lld.md` with technical details

9. **Expert Review** - Create `review.md` with multi-persona feedback

10. **Write Testing Plan** - Create `testing.md` with functional, backwards-compat, UX, ECS, and E2E tests

11. **Present Summary & Seek Guidance** - Present findings and ask for direction

---

## GitHub Issue URL Mode

### Step 1: Fetch GitHub Issue

When a user provides a GitHub issue URL, fetch the issue content using the `gh` CLI:

```bash

# Extract owner, repo, and issue number from URL

# URL format: https://github.com/{owner}/{repo}/issues/{number}

# Fetch issue details

gh issue view {number} --repo {owner}/{repo} --json title,body,labels,state,assignees,comments

# For more context, also fetch related PRs if any

gh issue view {number} --repo {owner}/{repo} --json linkedPullRequests

```

### Step 2: Analyze Issue Content

After fetching the issue, analyze it for:

1. **Existing Requirements**

- Problem statement

- User stories or use cases

- Acceptance criteria

- Scope definition

2. **Existing Design Elements**

- Technical proposals in the issue body

- Architecture suggestions

- API designs mentioned

- Data model proposals

- Diagrams or pseudocode

3. **Discussion Context**

- Comments with additional requirements

- Decisions made in discussion

- Concerns raised by team members

- Alternative approaches discussed

4. **Metadata**

- Labels (indicates feature type, priority)

- Assignees (who might have context)

- Linked PRs (prior implementation attempts)

### Step 3: Create Issue Summary

Create a summary document that captures what was found:

```markdown

# GitHub Issue Analysis: #{issue_number}

*Source: {issue_url}*

*Fetched: {date}*

## Issue Overview

| Field | Value |

|-------|-------|

| Title | {title} |

| State | {state} |

| Labels | {labels} |

| Assignees | {assignees} |

## Extracted Requirements

### Problem Statement

{extracted or "Not explicitly stated - needs clarification"}

### User Stories

{extracted user stories or "None found"}

### Acceptance Criteria

{extracted criteria or "Not defined - will need to establish"}

### Scope

{inferred scope or "Not specified"}

## Existing Design Elements

### Technical Proposals

{any technical details from issue body}

### Architecture Suggestions

{any architecture mentioned}

### API Design

{any API designs proposed}

### Open Questions in Issue

{questions raised but not answered}

## Discussion Summary

### Key Decisions Made

{decisions from comments}

### Concerns Raised

{concerns from team members}

### Alternative Approaches Mentioned

{alternatives discussed}

## Gaps Identified

The following information is missing and needs clarification:

1. {gap 1}

2. {gap 2}

```

### Step 4: Clarify Requirements

Based on the analysis, ask the user only about gaps not covered in the issue:

1. **Feature name** (derive from issue title if possible, use kebab-case)

2. **Missing requirements** - Only ask about gaps identified

3. **Design decisions** - If alternatives were discussed but not decided

4. **Scope confirmation** - Verify the scope interpretation is correct

Example prompt:

```

I've analyzed GitHub issue #{number}: "{title}"

The issue provides:

- {what's available}

However, I need clarification on:

1. {gap question 1}

2. {gap question 2}

Also, the issue discusses two approaches for {topic}:

- Option A: {description}

- Option B: {description}

Which approach should we pursue in the design?

```

---

## User Description Mode

## Step 1: Gather Requirements

Before creating any files, ask the user:

1. What is the feature name? (will be used for folder name, use kebab-case)

2. What problem does this feature solve?

3. Who are the users/consumers of this feature?

4. Are there any constraints or requirements?

5. What is the expected scope (small/medium/large)?

## Step 2: Quick Codebase Review

Before creating any design documents, perform a quick exploration of the codebase to understand:

1. **Project Structure** - Use Glob to understand the overall directory layout

- Identify main source directories (`registry/`, `src/`, etc.)

- Locate existing models, routes, services, and utilities

- Find configuration files and constants

2. **Related Components** - Search for existing features similar to the one being designed

- Use Grep to find relevant keywords and patterns

- Identify existing patterns and conventions used in the codebase

3. **Entry Points** - Understand how the application is structured

- Find the main FastAPI application and router setup

- Identify middleware, dependencies, and shared utilities

This quick review should take 5-10 minutes and helps you ask better clarifying questions and avoid proposing designs that conflict with existing architecture.

## Step 3: Create Design Folder

### Folder Naming Convention

**IMPORTANT:** Use different naming conventions based on the input mode:

| Input Mode | Folder Name | Example |

|------------|-------------|---------|

| **GitHub Issue URL Mode** | `issue-{number}/` | `issue-500/` for GitHub issue #500 |

| **User Description Mode** | `{feature-name}/` | `rate-limiting/` for a rate limiting feature |

This convention makes it easy to:

- Trace design documents back to their source GitHub issue

- Avoid duplicate work on the same issue

- Organize designs consistently

### Folder Structure

Create the folder structure:

```

.scratchpad/issue-{number}/ # For GitHub Issue URL Mode

# OR

.scratchpad/{feature-name}/ # For User Description Mode

├── github-issue.md # GitHub issue specification or summary

├── lld.md # Low-level design document

├── review.md # Expert review document

└── testing.md # Testing plan (functional, backwards-compat, UX, ECS, E2E)

```

## Step 4: Write GitHub Issue (github-issue.md)

**For User Description Mode:** Create a comprehensive GitHub issue specification.

**For GitHub Issue URL Mode:** Create a summary document that consolidates the existing issue content with any clarifications gathered. Use the "Issue Summary from URL" template below instead.

### Template: New Issue Specification (User Description Mode)

```markdown

# GitHub Issue: {Feature Title}

## Title

{concise title for the issue}

## Labels

- {appropriate labels from: enhancement, feature-request, api, frontend, backend, etc.}

## Description

### Problem Statement

{What problem does this solve? Why is it needed?}

### Proposed Solution

{High-level description of the solution}

### User Stories

- As a {user type}, I want to {action} so that {benefit}

- ...

### Acceptance Criteria

- [ ] {Criterion 1}

- [ ] {Criterion 2}

- ...

### Out of Scope

- {What is explicitly NOT included}

### Dependencies

- {Any dependent issues or external dependencies}

### Related Issues

- #{issue numbers if any}

```

### Template: Issue Summary from URL (GitHub Issue URL Mode)

When working from an existing GitHub issue, create a summary document:

```markdown

# Issue Summary: {Issue Title}

*Source Issue: [{owner}/{repo}#{number}]({issue_url})*

*Fetched: {date}*

*Status: {open/closed}*

## Issue Metadata

| Field | Value |

|-------|-------|

| Labels | {labels} |

| Assignees | {assignees} |

| Created | {created_date} |

| Last Updated | {updated_date} |

## Original Problem Statement

{Copy or summarize the problem statement from the issue body}

## Requirements Extracted

### From Issue Body

{Requirements found in the original issue}

### From Discussion (Comments)

{Additional requirements or clarifications from comments}

### Clarified with User

{Any requirements clarified during our conversation}

## Existing Design Elements

{Any technical proposals, architecture suggestions, or design decisions already in the issue}

### Technical Approach

{If specified in the issue}

### API Design

{If specified in the issue}

### Data Models

{If specified in the issue}

## Acceptance Criteria

### From Issue

{Criteria from the original issue}

### Additional (Established)

{Any additional criteria we established}

## Scope

{Scope as defined or inferred from the issue}

## Out of Scope

{What is explicitly excluded}

## Key Decisions from Discussion

| Decision | Context | Decided By |

|----------|---------|------------|

| {decision} | {why} | {who/when} |

## Open Questions Resolved

| Question | Resolution |

|----------|------------|

| {question from issue} | {answer we determined} |

## Dependencies

{Any dependencies mentioned in the issue}

## Notes

{Any additional context or notes relevant to the design}

```

## Step 5: Deep Codebase Analysis

**CRITICAL:** Before writing the LLD, you MUST thoroughly understand all relevant code in the repository. This is not optional - a design that doesn't account for existing code patterns will fail during implementation.

### What to Analyze

1. **Existing Models and Data Structures**

- Read ALL relevant Pydantic models in `registry/models/`

- Understand field types, validators, and relationships

- Identify any models that need to be extended or referenced

2. **Service Layer Patterns**

- Read existing services in `registry/services/`

- Understand how business logic is organized

- Identify common patterns (error handling, logging, caching)

- Note any base classes or utility functions used

3. **Route/API Patterns**

- Read existing routes in `registry/routes/`

- Understand request/response patterns

- Identify how authentication, validation, and error responses are handled

- Note middleware and dependencies used

4. **Storage Layer**

- Read storage implementations in `registry/storage/`

- Understand how data is persisted

- Identify any abstraction layers or interfaces

5. **Configuration and Constants**

- Read configuration files and constants

- Understand environment variable patterns

- Identify feature flags or configuration options

6. **Existing Tests**

- Read relevant test files in `tests/`

- Understand testing patterns and fixtures used

- Identify how mocking is done

### How to Analyze

Use the Task tool with subagent_type=Explore for thorough investigation:

```

Task tool with prompt: "Thoroughly analyze the service layer patterns in registry/services/.

Read all service files and document: 1) Common patterns used, 2) Error handling approaches,

3) Logging conventions, 4) Any base classes or utilities, 5) How services interact with storage."

```

For each area, you should:

- Read the actual code, not just file names

- Understand the "why" behind design decisions

- Note any TODOs or known issues

- Identify code that your feature will need to integrate with

### Document Your Findings

Create a brief section in your LLD documenting:

- Key files reviewed

- Patterns identified

- Integration points for the new feature

- Any constraints or limitations discovered

## Step 6: Write Low-Level Design (lld.md)

Create a detailed technical design document. This is the most critical document - it should contain enough detail for an entry-level developer to implement the feature.

```markdown

# Low-Level Design: {Feature Name}

*Created: {date}*

*Author: Claude*

*Status: Draft*

## Table of Contents

1. [Overview](#overview)

2. [Codebase Analysis](#codebase-analysis)

3. [Architecture](#architecture)

4. [Data Models](#data-models)

5. [API Design](#api-design)

6. [Configuration Parameters](#configuration-parameters)

7. [New Dependencies](#new-dependencies)

8. [Implementation Details](#implementation-details)

9. [Observability](#observability)

10. [Scaling Considerations](#scaling-considerations)

11. [File Changes](#file-changes)

12. [Testing Strategy](#testing-strategy)

13. [Alternatives Considered](#alternatives-considered)

14. [Rollout Plan](#rollout-plan)

## Overview

### Problem Statement

{Detailed problem description}

### Goals

- {Goal 1}

- {Goal 2}

### Non-Goals

- {What this design explicitly does NOT address}

## Codebase Analysis

*Summary of the deep codebase analysis performed before writing this LLD.*

### Key Files Reviewed

| File/Directory | Purpose | Relevance to This Feature |

|----------------|---------|---------------------------|

| `registry/models/{model}.py` | {Description} | {How it relates} |

| `registry/services/{service}.py` | {Description} | {How it relates} |

| `registry/routes/{route}.py` | {Description} | {How it relates} |

### Existing Patterns Identified

1. **Pattern Name**: {Description of the pattern and where it's used}

- Files: `{file1.py}`, `{file2.py}`

- How we'll follow this: {How the new feature will use this pattern}

2. **Pattern Name**: {Description}

- Files: `{files}`

- How we'll follow this: {How we'll apply it}

### Integration Points

| Component | Integration Type | Details |

|-----------|------------------|---------|

| {Existing component} | {Extends/Uses/Depends on} | {Specific integration details} |

### Constraints and Limitations Discovered

- {Constraint 1}: {How it affects the design}

- {Constraint 2}: {How it affects the design}

### Code Snippets Reference

{Include relevant code snippets from existing codebase that the new feature will integrate with or follow patterns from}

```python

# From registry/services/example_service.py:45-60

# This shows the pattern we'll follow for...

def existing_pattern_example():

pass

```

## Architecture

### System Context Diagram

{ASCII diagram showing how this feature fits into the overall system}

```

┌─────────────────┐ ┌─────────────────┐ ┌─────────────────┐

│ │ │ │ │ │

│ Component A │────▶│ New Feature │────▶│ Component B │

│ │ │ │ │ │

└─────────────────┘ └─────────────────┘ └─────────────────┘

```

### Sequence Diagram

{Show the flow of requests/data}

```

User Frontend Backend Database

│ │ │ │

│──── Request ──▶│ │ │

│ │── API Call ──▶│ │

│ │ │── Query ────▶│

│ │ │◀── Result ───│

│ │◀── Response ─│ │

│◀── Display ───│ │ │

```

### Component Diagram

{Show internal components and their relationships}

## Data Models

### New Models

{Define any new Pydantic models with full field definitions}

```python

class NewModel(BaseModel):

"""Description of the model."""

field_name: str = Field(

...,

description="What this field represents",

min_length=1,

max_length=100

)

optional_field: Optional[int] = Field(

default=None,

description="Optional field description"

)

```

### Model Changes

{Changes to existing models}

### Database Schema Changes

{If applicable, show collection/table changes}

+ ### Data Access Plan (avoid N+1)

+ {For each read path the feature introduces, state how the data is fetched.

+ Any time you need a count or lookup over a list of items, design a single bulk

+ query or aggregation (`$group`/`$sum`/`$in`/batched fetch) rather than one

+ query per item. Do NOT design a `for` loop that awaits a repository call per

+ element. If a per-item read seems unavoidable, justify why and bound the item

+ count. Note any new repository method (e.g. a `count_*` aggregation) the design

+ needs so it does not fall back to loading and counting in Python.}

## API Design

### New Endpoints

#### POST /api/v1/{endpoint}

**Description:** {What this endpoint does}

**Request:**

```json

{

"field": "value"

}

```

**Response (200 OK):**

```json

{

"id": "123",

"status": "success"

}

```

**Error Responses:**

- 400 Bad Request: {when}

- 401 Unauthorized: {when}

- 404 Not Found: {when}

### API Changes

{Changes to existing endpoints}

## Configuration Parameters

**IMPORTANT:** Clearly document all new configuration parameters this feature requires.

### New Environment Variables

|---------------|------|---------|----------|-------------|

| `FEATURE_INTERVAL_SECONDS` | int | `30` | No | Polling interval in seconds |

### Settings Class Updates

Add to `registry/core/config.py`:

```python

# Feature-specific settings

feature_enabled: bool = Field(

default=True,

description="Enable/disable feature X"

)

feature_interval_seconds: int = Field(

default=30,

description="Interval for feature X operations"

)

```

### Configuration Validation

{Any validation rules for configuration values}

### Deployment Surface Checklist

**CRITICAL:** Every new configuration parameter must be propagated to all three deployment surfaces AND documented in the unified parameter reference. Use the checklist below and fill in the file-level details for each new parameter.

#### Unified Parameter Reference (must be updated for every new parameter)

The project maintains a single cross-surface mapping of every parameter at [`docs/unified-parameter-reference.md`](../../../docs/unified-parameter-reference.md). This is the authoritative index for how each logical parameter is named on each surface. **You must update it** whenever a parameter is added, renamed, removed, or re-scoped.

| File | What to Add | Done? |

|------|-------------|-------|

| `docs/unified-parameter-reference.md` | Add one row per new parameter to the correct logical group table: parameter name, Docker `.env` var, Terraform `.tfvars` var, Helm values path, purpose. Mark secrets with **(secret)**. If no existing group fits, add a new group section and explain why in the PR description. If a surface legitimately does not expose the parameter, leave the cell blank and note the reason in the PR. | [ ] |

Verification: `grep` the new variable name across [`.env.example`](../../../.env.example), [`terraform/aws-ecs/terraform.tfvars.example`](../../../terraform/aws-ecs/terraform.tfvars.example), [`charts/`](../../../charts/), AND `docs/unified-parameter-reference.md` — it must appear in all surfaces that the reference file claims it does.

#### Docker Deployment (5 files)

| File | What to Add | Done? |

|------|-------------|-------|

| `.env.example` | Variable with description and default value | [ ] |

| `.env` | Variable with the actual deployment value | [ ] |

| `docker-compose.yml` | Pass variable to the correct service(s) environment block | [ ] |

| `docker-compose.podman.yml` | Same as above (Podman variant) | [ ] |

| `docker-compose.prebuilt.yml` | Same as above (prebuilt-image variant) | [ ] |

#### Terraform / ECS Deployment (5+ files)

| File | What to Add | Done? |

|------|-------------|-------|

| `terraform/aws-ecs/variables.tf` | Root variable definition with description and default | [ ] |

| `terraform/aws-ecs/main.tf` | Pass the variable into the module call | [ ] |

| `terraform/aws-ecs/modules/mcp-gateway/variables.tf` | Module-level variable definition | [ ] |

| `terraform/aws-ecs/modules/mcp-gateway/ecs-services.tf` | Map variable to container environment in ECS task definition | [ ] |

| `terraform/aws-ecs/terraform.tfvars.example` | Documented example value | [ ] |

Sensitive values (tokens, private keys) must use AWS Secrets Manager references.

#### Helm / EKS Deployment (4 files)

| File | What to Add | Done? |

|------|-------------|-------|

| `charts/registry/values.yaml` (or the correct subchart) | Default value under the appropriate section | [ ] |

| `charts/mcp-gateway-registry-stack/values.yaml` | Default value (stack-level chart) | [ ] |

| `charts/<subchart>/templates/secret.yaml` | Add variable if sensitive (base64-encoded), plus support `existingSecret` / `secretKeyRef` | [ ] |

| `charts/<subchart>/templates/deployment.yaml` | Map value to container env var (plain or `secretKeyRef`) | [ ] |

Sensitive values must support `secretKeyRef` for Kubernetes secrets.

#### System Config Page (Backend API + Frontend UI)

New config params must appear on the System Config page in the UI. This requires backend and possibly frontend changes.

| File | What to Add | Done? |

|------|-------------|-------|

| `registry/api/config_routes.py` | Add field to `CONFIG_GROUPS` dict with `(field_name, display_label, is_sensitive)`. Sensitive fields must have `is_sensitive=True` so they are masked via `_mask_sensitive_value()`. | [ ] |

| Frontend (`ConfigPanel.tsx`) | Auto-renders fields from `/api/config/full`. Update only if the new parameters need special UI treatment (toggles, grouped display, color-coded status, etc.). | [ ] |

Verify after deployment: navigate to the System Config page and confirm the new parameter(s) appear with correct values and labels. Sensitive values should be masked. The same data is also available programmatically via `GET /api/config/full` (admin auth required) and can be exported via `GET /api/config/export?format={env|json|tfvars|yaml}`.

## New Dependencies

**IMPORTANT:** List all new Python packages or libraries required by this feature.

### Python Packages

|---------|---------|---------|----------|

| `package-name` | `latest` | {Why needed} | Backend |

| `another-package` | `latest` | {Why needed} | Frontend |

### Adding Dependencies

```bash

# Add to pyproject.toml

uv add package-name

```

### No New Dependencies

If no new dependencies are required, explicitly state:

- "This feature uses only existing dependencies from the project."

## Implementation Details

### Step-by-Step Implementation

#### Step 1: {First Step}

**File:** `path/to/file.py`

**Lines:** {approximate line numbers or "new file"}

```python

# Pseudo-code or actual code

def new_function(

param1: str,

param2: int

) -> dict:

"""

Description of what this function does.

Args:

param1: Description

param2: Description

Returns:

Description of return value

"""

# Step 1: Validate input

if not param1:

raise ValueError("param1 is required")

# Step 2: Process data

result = process_data(param1, param2)

# Step 3: Return response

return {"status": "success", "data": result}

```

#### Step 2: {Second Step}

{Continue with detailed steps...}

### Error Handling

{How errors should be handled}

### Logging

{What should be logged and at what level}

## Observability

### Tracing

{Define trace spans for this feature}

| Span Name | Attributes | Parent Span |

|-----------|------------|-------------|

| `feature.operation_name` | `param1`, `param2` | `http.request` |

### Metrics

{Define metrics to track for this feature}

|-------------|------|--------|-------------|

### Logging Points

{Key operations that should emit logs}

| Log Level | Event | Data to Include |

|-----------|-------|-----------------|

| INFO | Operation started | request_id, user_id |

| ERROR | Operation failed | error_type, context |

## Scaling Considerations

### Current Load Assumptions

{Expected request volume and data size}

### Horizontal Scaling

{How this feature scales across multiple instances}

### Bottlenecks

{Potential bottlenecks and mitigation strategies}

### Caching Strategy

{If applicable, what can be cached and for how long}

## File Changes

### New Files

| File Path | Description |

|-----------|-------------|

| `registry/routes/new_feature.py` | API routes for new feature |

| `registry/services/new_feature_service.py` | Business logic |

| `tests/unit/test_new_feature.py` | Unit tests |

### Modified Files

| File Path | Lines | Change Description |

|-----------|-------|-------------------|

| `registry/main.py` | ~50 | Add router import and include |

| `registry/models/domain.py` | ~100-150 | Add new model |

### API Client Updates (IMPORTANT)

**When new API endpoints are added or modified, the following files MUST also be updated:**

| File Path | Update Required |

|-----------|-----------------|

| `api/registry_client.py` | Add Pydantic response models and client methods for new endpoints |

| `api/registry_management.py` | Add CLI commands (argparse parsers) and handler functions |

| `api/openapi.json` | Regenerate OpenAPI spec if using auto-generation |

**Example additions for a new endpoint `GET /api/feature/{path}/data`:**

```python

# In api/registry_client.py:

class FeatureDataResponse(BaseModel):

"""Response model for feature data endpoint."""

path: str = Field(..., description="Feature path")

data: dict = Field(..., description="Feature data")

def get_feature_data(self, path: str) -> FeatureDataResponse:

"""Get feature data from the registry."""

response = self._make_request("GET", f"/api/feature/{path}/data")

return FeatureDataResponse(**response)

# In api/registry_management.py:

def cmd_feature_data(args: argparse.Namespace) -> None:

"""Get feature data command handler."""

client = _get_client(args)

result = client.get_feature_data(path=args.path)

# Display result...

```

This ensures the registry management CLI stays in sync with backend API capabilities.

### Estimated Lines of Code

| Category | Lines |

|----------|-------|

| New Python code | ~{X} |

| New test code | ~{X} |

| Modified code | ~{X} |

| **Total** | **~{X}** |

## Testing Strategy

**IMPORTANT:** Explicitly list all new test files and test cases required for this feature.

### New Test Files

| Test File | Type | Description |

|-----------|------|-------------|

| `tests/unit/services/test_feature_service.py` | Unit | Service layer unit tests |

| `tests/unit/repositories/test_feature_repository.py` | Unit | Repository unit tests |

| `tests/integration/test_feature_integration.py` | Integration | End-to-end integration tests |

| `tests/unit/api/test_feature_routes.py` | Unit | API route unit tests |

### Unit Tests Required

List specific unit test cases:

| Test Case | File | What It Tests |

|-----------|------|---------------|

| `test_happy_path` | `test_feature_service.py` | Normal operation with valid inputs |

| `test_error_handling` | `test_feature_service.py` | Error cases and edge conditions |

| `test_validation` | `test_feature_service.py` | Input validation logic |

Example unit test structure:

```python

class TestNewFeature:

"""Tests for new feature."""

def test_happy_path(self):

"""Test normal operation."""

# Arrange

input_data = {...}

# Act

result = function_under_test(input_data)

# Assert

assert result["status"] == "success"

def test_error_case(self):

"""Test error handling."""

with pytest.raises(ValueError):

function_under_test(None)

```

### Integration Tests Required

List specific integration test cases:

| Test Case | File | What It Tests |

|-----------|------|---------------|

| `test_end_to_end_flow` | `test_feature_integration.py` | Complete feature workflow |

| `test_database_persistence` | `test_feature_integration.py` | Data is correctly persisted |

| `test_concurrent_operations` | `test_feature_integration.py` | Concurrency handling |

### Test Coverage Requirements

- Minimum coverage for new code: 80%

- All public methods must have tests

- Error paths must be tested

### Manual Testing

{Steps for manual verification}

## Alternatives Considered

**IMPORTANT:** Document alternative approaches that were considered and why they were rejected.

### Alternative 1: {Alternative Approach Name}

**Description:** {Brief description of the alternative}

**Pros:**

- {Advantage 1}

- {Advantage 2}

**Cons:**

- {Disadvantage 1}

- {Disadvantage 2}

**Why Rejected:** {Clear explanation of why this wasn't chosen}

### Alternative 2: {Another Alternative}

**Description:** {Brief description}

**Pros:**

- {Advantage}

**Cons:**

- {Disadvantage}

**Why Rejected:** {Explanation}

### Comparison Matrix

|----------|-----------------|---------------|---------------|

## Rollout Plan

### Phase 1: Development

- [ ] Implement core functionality

- [ ] Write unit tests

- [ ] Code review

### Phase 2: Testing

- [ ] Integration testing

- [ ] Security review

- [ ] Performance testing (if applicable)

### Phase 3: Deployment

- [ ] Deploy to staging

- [ ] Verify in staging

- [ ] Deploy to production

- [ ] Monitor for issues

## Open Questions

- {Any unresolved questions that need answers}

## References

- {Links to relevant documentation}

- {Links to similar implementations}

```

## Step 7: Expert Review (review.md)

Create a review document with feedback from multiple expert personas:

```markdown

# Expert Review: {Feature Name}

*Review Date: {date}*

*LLD Version: 1.0*

## Review Panel

| Role | Reviewer | Status |

|------|----------|--------|

| Frontend Engineer | Pixel | Pending |

| Backend Engineer | Byte | Pending |

| SRE/DevOps Engineer | Circuit | Pending |

| Security Engineer | Cipher | Pending |

| SMTS (Overall) | Sage | Pending |

---

## Frontend Engineer Review

**Reviewer:** Pixel

**Focus Areas:** UI/UX, React components, state management, API integration

### Assessment

#### Strengths

- {Positive aspects of the design from frontend perspective}

#### Concerns

- {Issues or risks identified}

#### New Libraries Required

|---------|---------|---------|---------------|

| `library-name` | `latest` | {What it does} | {Why it's needed vs alternatives} |

| None | - | - | No new frontend dependencies required |

#### Better Alternatives Considered

{Are there better frontend approaches? Discuss alternatives like different state management, component libraries, etc.}

#### Recommendations

1. {Specific recommendation}

2. {Specific recommendation}

#### Questions for Author

- {Questions that need clarification}

### Verdict: {APPROVED / APPROVED WITH CHANGES / NEEDS REVISION}

---

## Backend Engineer Review

**Reviewer:** Byte

**Focus Areas:** API design, data models, business logic, database queries, performance

### Assessment

#### Strengths

- {Positive aspects from backend perspective}

+ #### N+1 Access Pattern Check (MANDATORY)

+ Inspect every data-access path in the design. Flag any pattern that reads from

+ a database or data source once per item (a `count()` / `find_one()` / `get()` /

+ `distinct()` or repository call inside a `for`/`while`/comprehension/per-item

+ callback, or a service that internally queries per element). State the fix: a

+ single bulk query or aggregation (`$group`/`$sum`/`$in`/batched fetch) outside

+ the loop. `asyncio.gather` over a per-item list is still N+1 round-trips; flag

+ it unless the item count is small and bounded.

+ - **N+1 patterns:** {None found / FLAGGED: <where + the per-item read and the bulk-query fix>}

#### Concerns

- {Issues or risks identified}

#### New Libraries Required

|---------|---------|---------|---------------|

| `library-name` | `latest` | {What it does} | {Why it's needed vs alternatives} |

| None | - | - | No new backend dependencies required |

#### Better Alternatives Considered

{Are there better backend approaches? Discuss alternatives like different algorithms, data structures, caching strategies, etc.}

#### Recommendations

1. {Specific recommendation}

2. {Specific recommendation}

#### Questions for Author

- {Questions that need clarification}

### Verdict: {APPROVED / APPROVED WITH CHANGES / NEEDS REVISION}

---

## SRE/DevOps Engineer Review

**Reviewer:** Circuit

**Focus Areas:** Deployment, monitoring, scaling, infrastructure, reliability

### Assessment

#### Strengths

- {Positive aspects from SRE perspective}

#### Concerns

- {Issues or risks identified}

#### Infrastructure Dependencies

|----------|------|---------|-------------|

| `resource-name` | AWS Service / Tool | {What it does} | {Estimated cost} |

| None | - | - | No new infrastructure required |

#### Better Alternatives Considered

{Are there better infrastructure approaches? Discuss alternatives like different AWS services, deployment strategies, monitoring tools, etc.}

#### Recommendations

1. {Specific recommendation}

2. {Specific recommendation}

#### Operational Checklist

- [ ] Monitoring/alerting considered

- [ ] Logging sufficient for debugging

- [ ] Graceful degradation planned

- [ ] Rollback strategy defined

- [ ] Resource requirements estimated

### Verdict: {APPROVED / APPROVED WITH CHANGES / NEEDS REVISION}

---

## Security Engineer Review

**Reviewer:** Cipher

**Focus Areas:** Authentication, authorization, input validation, data protection, OWASP

### Assessment

#### Strengths

- {Positive aspects from security perspective}

#### Concerns

- {Issues or risks identified}

#### Security Checklist

- [ ] Input validation adequate

- [ ] Authentication/authorization correct

- [ ] No sensitive data exposure

- [ ] No injection vulnerabilities

- [ ] Rate limiting considered

- [ ] Audit logging included

#### Recommendations

1. {Specific recommendation}

2. {Specific recommendation}

### Verdict: {APPROVED / APPROVED WITH CHANGES / NEEDS REVISION}

---

## SMTS Overall Review

**Reviewer:** Sage

**Focus Areas:** Architecture, code quality, maintainability, alignment with project goals

### Executive Summary

{2-3 sentence summary of the design and overall assessment}

### Architecture Assessment

- **Alignment with existing patterns:** {Good/Needs Work}

- **Maintainability:** {Good/Needs Work}

- **Scalability:** {Good/Needs Work}

- **Testability:** {Good/Needs Work}

### Cross-Cutting Concerns

{Issues that span multiple review areas}

### Final Recommendations

1. **Must Fix (Blockers):**

- {Critical issues that must be addressed}

2. **Should Fix (Important):**

- {Important issues to address before implementation}

3. **Consider (Nice to Have):**

- {Suggestions for improvement}

### Overall Verdict: {APPROVED / APPROVED WITH CHANGES / NEEDS REVISION}

---

## Review Summary

|----------|---------|----------|--------------|

| Frontend | {verdict} | {count} | {summary} |

| Backend | {verdict} | {count} | {summary} |

| SRE/DevOps | {verdict} | {count} | {summary} |

| Security | {verdict} | {count} | {summary} |

| SMTS | {verdict} | {count} | {summary} |

### Next Steps

1. {Action item}

2. {Action item}

3. {Action item}

### Sign-Off

- [ ] All blockers resolved

- [ ] Design updated based on feedback

- [ ] Ready for implementation

```

## Important Guidelines

### Design Principles

- Favor simple designs over unnecessary complexity

- Prefer straightforward code over clever solutions

- Design for maintainability by entry-level developers

- Add observability from the start, not as an afterthought

### Documentation Quality

1. **Be Thorough**: The LLD should be detailed enough that someone unfamiliar with the codebase can implement it

2. **Use Diagrams**: ASCII diagrams help visualize the design

3. **Include Code**: Show actual or pseudo-code for key functions

4. **Specify Files**: Always mention which files to create/modify and approximate line numbers

5. **Consider All Aspects**: Think about error handling, logging, testing, and deployment

6. **Expert Reviews**: Make the reviews realistic - identify actual issues, not just praise

## Example Usage

### Example 1: User Description Mode

User: "Design a new feature for rate limiting on tool calls"

1. Ask clarifying questions about rate limiting requirements

2. Quick codebase review to understand existing architecture

3. Create `.scratchpad/rate-limiting/`

4. Write `github-issue.md` with rate limiting requirements

5. Deep codebase analysis of relevant services

6. Write `lld.md` with:

- Architecture showing rate limiter component

- Sequence diagram for rate-limited requests

- Redis/in-memory counter data structures

- API changes for rate limit headers

- Middleware implementation details

- Configuration options

7. Write `review.md` with expert feedback on:

- Frontend: How to display rate limit info to users

- Backend: Algorithm choice, storage considerations

- SRE: Redis availability, monitoring needs

- Security: Rate limit bypass prevention

- SMTS: Overall architecture fit

8. Write `testing.md` with:

- Functional curl tests for the rate limit headers endpoint

- `registry_management.py` tests for any new CLI flags

- Backwards-compat tests confirming existing endpoints still respond identically when under limit

- UX tests for surfacing rate limit feedback in the UI

- ECS/terraform tests for any new env vars (e.g. `RATE_LIMIT_REDIS_URL`)

- E2E test exercising multiple requests to trigger and recover from a rate-limited state

9. Present summary and seek guidance on recommendations

### Example 2: GitHub Issue URL Mode

User: "https://github.com/agentic-community/mcp-gateway-registry/issues/456"

1. Fetch issue #456 using `gh issue view 456 --repo agentic-community/mcp-gateway-registry --json title,body,labels,state,comments`

2. Analyze the issue content:

- Extract: "Add support for federated registry syncing"

- Found: Problem statement, some acceptance criteria

- Missing: Specific sync frequency, conflict resolution strategy

3. Quick codebase review to understand registry architecture

4. Create `.scratchpad/issue-456/` (folder named after the GitHub issue number)

5. Ask user only about gaps:

- "The issue mentions syncing but doesn't specify frequency. What sync interval should we design for?"

- "The issue discusses conflicts but doesn't specify resolution. Should we use last-write-wins or require manual resolution?"

6. Write `github-issue.md` summarizing the issue with clarifications

7. Deep codebase analysis of registry and storage layers

8. Write `lld.md` incorporating:

- Requirements from original issue

- Design elements proposed in issue comments

- Clarifications from user

- Technical details for implementation

9. Write `review.md` with expert feedback

10. Write `testing.md` with:

- Functional curl tests for new sync endpoints and existing endpoints that now honor sync state

- `registry_management.py` tests for any new sync-related CLI commands

- Backwards-compat tests confirming non-federated deployments are unaffected

- UX tests for any UI indicators showing federated/synced resources

- ECS/terraform tests for new sync config vars (e.g. `FEDERATION_PEER_URLS`, `FEDERATION_SYNC_INTERVAL_SECONDS`)

- E2E test exercising a two-registry sync cycle and conflict resolution

11. Present summary noting:

- What came from the original issue

- What was clarified during design

- Recommendations for implementation

## Step 8: Write Testing Plan (testing.md)

Create a comprehensive testing plan document that captures **executable, copy-pasteable tests** covering every externally observable change introduced by the feature. The goal is for a reviewer or implementer to be able to walk through this document and verify the feature works end-to-end without having to invent test cases.

### When Each Test Category Applies

Include a category only when it is relevant to the feature. Mark a category "Not Applicable" with a short justification when it does not apply.

| Category | Include When |

|----------|--------------|

| Functional Tests (curl) | Feature adds/modifies any HTTP endpoint |

| Functional Tests (registry_management.py) | Feature adds/modifies anything exposed via the management CLI |

| Backwards Compatibility Tests | Feature changes an existing endpoint, schema, CLI command, config default, or data model |

| UX Tests | Feature adds/changes any UI surface (web UI, CLI output formatting, error messages shown to users) |

| Deployment Surface Tests (Docker, ECS, Helm) | Feature adds or modifies **any** config parameter (env var, setting, Terraform variable, Helm value, secret) across Docker, ECS/Terraform, or Helm/EKS deployments |

| Nginx Routing / MCP Proxy Tests | Feature touches nginx config generation (`nginx_service.py`), auth server mcp-proxy (`/mcp-proxy/`), or any proxy_pass/location-block logic |

| E2E API Tests | Feature adds a new user-visible workflow that spans multiple endpoints or services |

### CRITICAL: Nginx Routing Safety

Any change that impacts nginx routing (in `registry/core/nginx_service.py`, `auth_server/server.py` mcp-proxy, or nginx template files) MUST include an end-to-end MCP client connectivity test. This is because:

1. **Health checks do not exercise the nginx proxy path.** They call backends directly (127.0.0.1), so a broken proxy_pass goes undetected by monitoring.

2. **The REST API does not use the MCP proxy path.** UI and API tests pass even when MCP routing is broken.

3. **Only real MCP clients** (Roo Code, Claude Code, Cursor) connecting through the gateway exercise the full path: CloudFront -> ALB -> nginx location block -> auth_request -> mcp-proxy hop -> upstream backend.

**Required test for any nginx routing change:**

```bash

# Verify ai-registry-tools (mcpgw) is reachable through the full proxy chain

TOKEN="<valid JWT>"

curl -X POST \

-H "X-Authorization: Bearer $TOKEN" \

-H "Content-Type: application/json" \

-H "Accept: application/json, text/event-stream" \

-d '{"jsonrpc":"2.0","method":"initialize","params":{"protocolVersion":"2025-03-26","capabilities":{},"clientInfo":{"name":"test","version":"1.0"}},"id":1}' \

"https://<registry-url>/airegistry-tools/mcp"

# Expected: 200 OK with JSON-RPC response containing serverInfo

# Failure: 502/404/405 or "Upstream MCP server error"

```

This test must pass on all deployment surfaces (Docker Compose, ECS, EKS) before merging. The `airegistry-tools` server is the canary for MCP proxy routing because it is always registered and always healthy.

### Testing Plan Template

Use this template verbatim (fill in the placeholders, remove sections marked "Not Applicable" except to record the justification):

```markdown

# Testing Plan: {Feature Name}

*Created: {date}*

*Related LLD: `./lld.md`*

*Related Issue: `./github-issue.md`*

## Overview

### Scope of Testing

{1-2 sentences describing what is being tested and why}

### Test Environments

| Environment | Purpose | How to Reach |

|-------------|---------|--------------|

| Local (docker-compose) | Primary dev verification | `docker-compose up -d` at repo root |

| AWS ECS (terraform) | Staging/prod parity | `terraform/aws-ecs/` deployment |

### Prerequisites

- [ ] Registry and Keycloak running (`docker ps | grep -E 'registry\|keycloak'`)

- [ ] Auth tokens generated: `cd credentials-provider && ./generate_creds.sh`

- [ ] Token file exists: `ls -la .oauth-tokens/ingress.json`

- [ ] {Any feature-specific prereqs, e.g. MongoDB seeded with X}

### Shared Variables

```bash

export REGISTRY_URL="http://localhost" # or https://registry.<region>.<domain>

export TOKEN_FILE=".oauth-tokens/ingress.json"

export ACCESS_TOKEN=$(jq -r '.access_token' "$TOKEN_FILE")

```

---

## 1. Functional Tests

### 1.1 curl Tests (HTTP API)

For each new or modified endpoint, provide a copy-pasteable curl command, the expected response, and the assertion being verified.

#### Test 1.1.1: {Endpoint description, e.g. "Create resource X"}

**Endpoint:** `POST /api/v1/{path}`

**Command:**

```bash

curl -sS -X POST "$REGISTRY_URL/api/v1/{path}" \

-H "Authorization: Bearer $ACCESS_TOKEN" \

-H "Content-Type: application/json" \

-d '{

"field1": "value1",

"field2": 42

}' \

| jq

```

**Expected Status:** `200 OK` (or `201 Created`)

**Expected Response:**

```json

{

"id": "{id}",

"status": "success"

}

```

**Assertions:**

- [ ] Response contains `id` field

- [ ] `status == "success"`

- [ ] {Any side effect to verify, e.g. record exists in DB}

**Negative Case:**

```bash

# Missing required field should return 400

curl -sS -X POST "$REGISTRY_URL/api/v1/{path}" \

-H "Authorization: Bearer $ACCESS_TOKEN" \

-H "Content-Type: application/json" \

-d '{}' -w "\n%{http_code}\n"

```

Expected: `400` with validation error body.

#### Test 1.1.2: {Next endpoint}

{Repeat the structure above for each endpoint}

### 1.2 registry_management.py CLI Tests

For each new or modified CLI command exposed via `api/registry_management.py`, provide the exact invocation and expected output.

#### Test 1.2.1: {Command description, e.g. "Register a new feature resource"}

**Command:**

```bash

cd api

uv run python registry_management.py {subcommand} \

--token-file "../$TOKEN_FILE" \

--registry-url "$REGISTRY_URL" \

--{new-param} "{value}"

```

**Expected Output (key fragments):**

```

Successfully created {resource}: <id>

```

**Assertions:**

- [ ] Exit code is `0`

- [ ] Output includes the created resource id

- [ ] Follow-up `list` command shows the resource

**Follow-up Verification:**

```bash

uv run python registry_management.py list \

--token-file "../$TOKEN_FILE" \

--registry-url "$REGISTRY_URL"

```

#### Test 1.2.2: {Next command}

{Repeat the structure above}

---

## 2. Backwards Compatibility Tests

*Include this section if the feature touches any existing endpoint, schema, CLI command, default value, or data model. Otherwise replace with: "**Not Applicable** - feature introduces only net-new surface area: {justification}".*

### 2.1 Existing API Contract

Goal: confirm that existing clients continue to work without code changes.

#### Test 2.1.1: Legacy request shape still accepted

**Command (pre-feature request body):**

```bash

curl -sS -X POST "$REGISTRY_URL/api/v1/{existing-endpoint}" \

-H "Authorization: Bearer $ACCESS_TOKEN" \

-H "Content-Type: application/json" \

-d '{

"legacy_field": "value"

}' | jq

```

**Assertions:**

- [ ] Returns `200` (not `400`)

- [ ] Response contains all previously documented fields

- [ ] New optional fields either absent or have sensible defaults

### 2.2 Existing CLI Behavior

#### Test 2.2.1: CLI command without new flags behaves as before

```bash

uv run python registry_management.py {existing-command} \

--token-file "../$TOKEN_FILE" \

--registry-url "$REGISTRY_URL"

```

**Assertions:**

- [ ] Exit code `0`

- [ ] Output format unchanged (diff against pre-change baseline if available)

### 2.3 Default Behavior When New Config Unset

- [ ] Feature disabled by default (or matches prior behavior) when new env vars are unset

- [ ] No new required config parameter breaks existing deployments

---

## 3. UX Tests

*Include this section if the feature changes any user-facing surface (web UI, CLI output, error messages). Otherwise replace with: "**Not Applicable** - feature is internal only, with no UX changes."*

### 3.1 Web UI Tests

For each UI change, describe the manual test steps.

#### Test 3.1.1: {UI flow, e.g. "Display new resource in listing"}

**Steps:**

1. Log in to the registry UI at `$REGISTRY_URL`

2. Navigate to {page}

3. Verify {visible element} renders correctly

4. {Action, e.g. click "Create"}

5. Verify {expected outcome}

**Assertions:**

- [ ] Element visible at correct position

- [ ] No console errors in browser devtools

- [ ] Responsive behavior at mobile width works

- [ ] Accessible: keyboard navigation and screen-reader labels present

### 3.2 CLI Output / Error Message Tests

#### Test 3.2.1: Error message is actionable

```bash

uv run python registry_management.py {command} --invalid-flag bad-value

```

**Assertions:**

- [ ] Error clearly states what was invalid

- [ ] Error suggests the correct usage

- [ ] No stack trace leaked to user

---

## 4. Deployment Surface Tests (Docker, ECS, Helm)

*Include this section whenever the feature adds or modifies ANY config parameter (env var, setting, Terraform variable, Helm value, secret). Otherwise replace with: "**Not Applicable** - feature introduces no new config parameters. Verified by reviewing diff of `registry/core/config.py`."*

### 4.0 Unified Parameter Reference Updated

Before any surface-specific wiring tests, confirm the cross-surface index was updated.

| Check | Verification Command |

|-------|----------------------|

| New parameter row(s) added to `docs/unified-parameter-reference.md` | `grep -n "<PARAM_NAME>" docs/unified-parameter-reference.md` |

| Each cell points to a file that actually contains the variable | `grep -rn "<PARAM_NAME>" .env.example terraform/aws-ecs/terraform.tfvars.example charts/` |

**Assertions:**

- [ ] Parameter appears in `docs/unified-parameter-reference.md` in the correct group (or a new group is added with justification)

- [ ] Docker, Terraform, and Helm cells for the new row are either filled in **or** explicitly blank with a note in the PR description

- [ ] Secrets are flagged with **(secret)** in the reference

- [ ] The `/api/config/full` endpoint returns the new parameter (sensitive values masked)

### 4.1 Docker Deployment Wiring

For each new config parameter, confirm it is present in all Docker deployment files.

| Config Parameter | Env Var Name | Verification Command |

|------------------|--------------|----------------------|

| `feature_enabled` | `FEATURE_ENABLED` | `grep FEATURE_ENABLED .env.example docker-compose*.yml` |

| `feature_interval_seconds` | `FEATURE_INTERVAL_SECONDS` | `grep FEATURE_INTERVAL_SECONDS .env.example docker-compose*.yml` |

**Assertions:**

- [ ] Variable documented in `.env.example` with description and default

- [ ] Variable present in `.env` with deployment value

- [ ] Variable passed in `docker-compose.yml` environment block for the correct service(s)

- [ ] Variable passed in `docker-compose.podman.yml` environment block

- [ ] Variable passed in `docker-compose.prebuilt.yml` environment block

- [ ] `docker-compose up -d` starts successfully with the new variable

### 4.2 Terraform / ECS Variable Wiring

For each new config parameter, confirm it is plumbed through the ECS deployment.

|------------------|--------------|----------|----------------------|

**Assertions:**

- [ ] Root variable defined in `terraform/aws-ecs/variables.tf` with description and default

- [ ] Variable passed to module in `terraform/aws-ecs/main.tf`

- [ ] Module variable defined in `terraform/aws-ecs/modules/mcp-gateway/variables.tf`

- [ ] Variable mapped to container env in `terraform/aws-ecs/modules/mcp-gateway/ecs-services.tf`

- [ ] Example value in `terraform/aws-ecs/terraform.tfvars.example`

### 4.3 Terraform Plan/Apply Verification

```bash

cd terraform/aws-ecs

terraform init

terraform validate

terraform plan -var 'feature_enabled=true' -var 'feature_interval_seconds=60'

```

**Assertions:**

- [ ] `terraform validate` passes

- [ ] `terraform plan` shows the new variable in the ECS task definition env block

- [ ] No unintended changes to unrelated resources

### 4.4 Helm / EKS Variable Wiring

For each new config parameter, confirm it is plumbed through the Helm charts.

| Config Parameter | Helm Value Path | Verification Command |

|------------------|-----------------|----------------------|

| `feature_enabled` | `registry.featureEnabled` | `grep -rn FEATURE_ENABLED charts/` |

| `feature_interval_seconds` | `registry.featureIntervalSeconds` | `grep -rn FEATURE_INTERVAL_SECONDS charts/` |

**Assertions:**

- [ ] Default value in `charts/registry/values.yaml`

- [ ] Default value in `charts/mcp-gateway-registry-stack/values.yaml`

- [ ] Sensitive values added to `charts/registry/templates/secret.yaml` (base64-encoded)

- [ ] Variable mapped to container env in `charts/registry/templates/deployment.yaml`

- [ ] `helm template charts/registry` renders the new env var correctly

### 4.5 Deploy and Verify on ECS

```bash

cd terraform/aws-ecs

terraform apply -var 'feature_enabled=true' -var 'feature_interval_seconds=60'

```

**Post-Deploy Assertions:**

- [ ] ECS service reaches `RUNNING` state

- [ ] CloudWatch logs show the feature initialized with the configured values

- [ ] Health check endpoint returns `200` against the deployed ALB/CloudFront URL

- [ ] Re-run the Functional Tests from section 1 against the deployed `$REGISTRY_URL`

### 4.6 Rollback Verification

- [ ] `terraform apply` with `feature_enabled=false` disables the feature cleanly

- [ ] Reverting to the previous task definition restores prior behavior (backwards compat holds in deployed env)

---

## 5. End-to-End API Tests

*Include this section if the feature adds a user-visible workflow that spans multiple endpoints or services. Otherwise replace with: "**Not Applicable** - feature is a single-endpoint change, covered by Functional Tests section 1."*

### 5.1 E2E Scenario: {Scenario Name}

**Goal:** {business outcome being exercised, e.g. "A tenant onboards, registers a server, invokes a tool, and tears down the resources"}

**Setup:**

```bash

# Generate token, set env vars (see Shared Variables above)

export RUN_ID=$(date +%s)

```

**Steps (each step is executable):**

1. **Create prerequisite resources**

```bash

curl -sS -X POST "$REGISTRY_URL/api/v1/{pre-req}" \

-H "Authorization: Bearer $ACCESS_TOKEN" \

-d '{ "name": "e2e-'$RUN_ID'" }'

```

2. **Exercise the new feature**

```bash

curl -sS -X POST "$REGISTRY_URL/api/v1/{new-endpoint}" \

-H "Authorization: Bearer $ACCESS_TOKEN" \

-d '{ "ref": "e2e-'$RUN_ID'" }'

```

3. **Verify cross-service side effect**

```bash

curl -sS "$REGISTRY_URL/api/v1/{downstream-check}/e2e-$RUN_ID" | jq

```

4. **Teardown**

```bash

curl -sS -X DELETE "$REGISTRY_URL/api/v1/{pre-req}/e2e-$RUN_ID"

```

**Assertions:**

- [ ] All steps return expected status codes

- [ ] Final state matches expected (resource visible in listing, metrics emitted, logs present)

- [ ] Teardown leaves the system in its original state

### 5.2 Reuse of Existing E2E Harness

If `api/test-management-api-e2e.sh` already exercises adjacent flows, extend it rather than duplicating:

- [ ] Add new test phase to `api/test-management-api-e2e.sh`

- [ ] Document additions in `api/test-management-api-e2e.md`

- [ ] Run full harness locally and against the ECS deployment

```bash

cd api

./test-management-api-e2e.sh --token-file ../$TOKEN_FILE --registry-url "$REGISTRY_URL"

```

---

## 6. Test Execution Checklist

Copy this checklist into the PR description when implementing the feature:

- [ ] Section 1 (Functional) - all curl tests pass against local deployment

- [ ] Section 1 (Functional) - all `registry_management.py` commands succeed

- [ ] Section 2 (Backwards Compat) - verified or marked Not Applicable with justification

- [ ] Section 3 (UX) - verified or marked Not Applicable with justification

- [ ] Section 4 (Deployment Surfaces: Docker, ECS, Helm) - verified or marked Not Applicable with justification

- [ ] Section 5 (E2E) - verified or marked Not Applicable with justification

- [ ] Unit tests added in `tests/unit/`

- [ ] Integration tests added in `tests/integration/`

- [ ] `uv run pytest tests/ -n 8` passes with no regressions

```

### Guidance for Generating testing.md

1. **Make tests copy-pasteable.** Use the exact env var conventions (`REGISTRY_URL`, `TOKEN_FILE`, `ACCESS_TOKEN`) and match the style of `api/test-management-api-e2e.sh`.

2. **Cover every new endpoint and every new CLI command.** If the LLD adds three endpoints and two CLI commands, section 1 must have at least five subsections.

3. **Anchor ECS tests on concrete files.** Reference `terraform/aws-ecs/ecs.tf`, `variables.tf`, and any module under `terraform/aws-ecs/modules/` that the parameter flows through. Do not write generic "deploy and verify" wording - name the files.

4. **Mark Not Applicable explicitly.** Do not silently omit sections - always include the heading with a short justification, so reviewers see that the category was considered.

5. **Align with backwards-compat rules.** If the LLD introduces a schema change, the backwards-compat section must test the pre-change request/response shapes.

6. **Do not invent endpoints or flags.** Every curl URL, every `registry_management.py` flag, and every Terraform variable must exist in the LLD or the current codebase.

## Step 9: Present Summary & Seek Guidance

**IMPORTANT:** After completing the design documents and expert review, present a clear summary to the user and ask for guidance on addressing recommendations.

### Summary Format

Present the following information in a clear, tabular format:

```markdown

## Design Summary

### Documents Created

| Document | Location | Description |

|----------|----------|-------------|

| GitHub Issue | `.scratchpad/{feature}/github-issue.md` | Issue specification |

| Low-Level Design | `.scratchpad/{feature}/lld.md` | Technical design |

| Expert Review | `.scratchpad/{feature}/review.md` | Multi-persona review |

| Testing Plan | `.scratchpad/{feature}/testing.md` | Functional, backwards-compat, UX, ECS, and E2E tests |

### Review Verdicts

|----------|---------|----------|---------------------|

| Frontend (Pixel) | {verdict} | {count} | {brief summary} |

| Backend (Byte) | {verdict} | {count} | {brief summary} |

| SRE (Circuit) | {verdict} | {count} | {brief summary} |

| Security (Cipher) | {verdict} | {count} | {brief summary} |

| SMTS (Sage) | {verdict} | {count} | {brief summary} |

### Configuration Parameters

|-----------|------|---------|-------------|

| `PARAM_NAME` | type | value | {description} |

### New Dependencies

| Package/Resource | Type | Required By |

|------------------|------|-------------|

| `package-name` | Python | Backend |

| None | - | No new dependencies |

### New Tests Required

| Test File | Type | Coverage |

|-----------|------|----------|

| `tests/unit/test_feature.py` | Unit | Service layer |

| `tests/integration/test_feature.py` | Integration | End-to-end |

### Estimated Effort

| Category | Lines of Code |

|----------|---------------|

| New code | ~{X} |

| Tests | ~{X} |

| Modified | ~{X} |

| **Total** | **~{X}** |

```

### Seeking Guidance

After presenting the summary, explicitly ask the user for guidance:

```markdown

## Action Required

### Blockers (Must Address)

The following issues were identified as **blockers** and should be addressed before implementation:

1. {Blocker description from review}

2. {Blocker description from review}

**These will be incorporated into the LLD.**

### Recommendations (Need Your Input)

The following recommendations were made by reviewers. Please indicate which ones to incorporate:

|---|----------------|----------|----------|--------------|

| 1 | {recommendation} | Backend | Should Fix | ? |

| 2 | {recommendation} | SRE | Should Fix | ? |

| 3 | {recommendation} | Security | Nice to Have | ? |

### Questions for You

1. Should I update the LLD to address the blockers and your selected recommendations?

2. Are there any additional requirements or constraints I should consider?

3. Would you like me to proceed with creating the GitHub issue?

```

### Handling User Response

Based on user response:

1. **If user wants LLD updates**: Update the `lld.md` file with the agreed-upon changes

2. **If user approves as-is**: Proceed to offer GitHub issue creation

3. **If user has additional feedback**: Incorporate and regenerate affected sections

### Alternative Approaches Discussion

If reviewers identified better alternatives, explicitly call this out:

```markdown

### Alternative Approaches Identified

Reviewers suggested these alternative approaches that may be worth considering:

| Alternative | Proposed By | Trade-offs |

|-------------|-------------|------------|

| {approach} | {reviewer} | {pros/cons summary} |

Would you like me to explore any of these alternatives further?

```