retestkit 1.4.1

package/openspec/changes/refactor-webtest-naming/design.md

@@ -0,0 +1,95 @@
+## Context
+
+The testing-mcp server provides tools for AI-powered web application testing. The current naming has evolved organically and lacks consistency:
+
+1. `webtest_analyze_app` does two things: identifies app structure AND identifies flows
+2. `webtest_run_tests` (plural) only runs one test at a time
+3. Terminology in prompts/outputs mixes "analysis", "flows", "entities" inconsistently
+4. File structure uses `analysis/` directory which doesn't reflect new "features" terminology
+
+This refactor establishes a consistent vocabulary and separates concerns for better discoverability.
+
+## Goals / Non-Goals
+
+### Goals
+- Establish consistent naming convention across all user-facing surfaces
+- Separate feature discovery from flow discovery for flexibility
+- Make tool names match their actual behavior (singular vs plural)
+- Create intuitive file structure that reflects the discovery hierarchy
+
+### Non-Goals
+- Backward compatibility (pre-1.0, breaking changes acceptable)
+- Changing core functionality/algorithms
+- Adding new test capabilities beyond naming
+
+## Decisions
+
+### Decision 1: Two-phase discovery (features then flows)
+
+**What**: Split `analyze_app` into `discover_features` and `discover_flows`
+
+**Why**:
+- Features are coarse-grained (Auth, Cart, Search)
+- Flows are fine-grained within features (Login, Register, Password Reset within Auth)
+- Users may want to discover flows for just one feature
+- Better sampling efficiency (smaller prompts per call)
+
+**Alternatives considered**:
+- Keep single tool with `mode` parameter - rejected (less intuitive)
+- Keep current name but add `discover_flows` - rejected (inconsistent naming)
+
+### Decision 2: Feature-based directory structure
+
+**What**: Move from `analysis/{app-analysis,flows}.md` to `features.md` + `features/<slug>/flows.md`
+
+**Why**:
+- Reflects the hierarchical relationship (features contain flows)
+- Enables per-feature flow files (better for large apps)
+- Natural organization for humans browsing workspace
+
+**Structure**:
+```
+webtest-workspaces/{analysisId}/
+  index.md                    # Workspace metadata
+  features.md                 # Discovered features
+  features/
+    authentication/
+      flows.md               # Flows for authentication feature
+    shopping-cart/
+      flows.md               # Flows for cart feature
+  tests/
+    tests.md                 # Generated test cases
+  runs/
+    {runId}/
+      report.md              # Test run results
+```
+
+### Decision 3: Singular `run_test` vs plural `run_tests`
+
+**What**: Rename `webtest_run_tests` to `webtest_run_test`
+
+**Why**: The tool executes ONE test case per invocation. Plural name suggests batch execution which doesn't exist.
+
+### Decision 4: Orchestrator prompt `webtest-discover`
+
+**What**: Rename `webtest-analyze` prompt to `webtest-discover`, which orchestrates both feature and flow discovery.
+
+**Why**:
+- "Discover" is the unified verb for this phase
+- Prompt can call `discover_features`, then `discover_flows` for each feature
+- User still has simple one-command workflow for full discovery
+
+## Risks / Trade-offs
+
+### Risk: Breaking existing integrations
+**Mitigation**: Clear changelog, version bump, documentation update
+
+### Risk: Increased complexity with two discovery tools
+**Mitigation**: `webtest-discover` prompt abstracts this; power users benefit from granularity
+
+### Trade-off: More files in workspace
+**Accepted**: Better organization outweighs slightly more files
+
+## Open Questions
+
+None - all decisions finalized for this proposal.

package/openspec/changes/refactor-webtest-naming/proposal.md

@@ -0,0 +1,66 @@
+# Change: Refactor WebTest Naming for Consistency and Clarity
+
+## Why
+
+The current naming across the MCP server is inconsistent and confusing. `webtest_analyze_app` produces both app analysis and flows in one step, but the mental model should separate **feature discovery** from **flow discovery**. Additionally, `webtest_run_tests` (plural) only runs a single test, which is misleading. A consistent, intuitive naming convention will improve discoverability and user experience.
+
+## What Changes
+
+### Tools (MCP `tools/list`)
+
+| Current | New | Rationale |
+|---------|-----|-----------|
+| `webtest_init` | `webtest_init` | No change - already clear |
+| `webtest_crawl_app` | `webtest_crawl_app` | No change - already clear |
+| `webtest_analyze_app` | `webtest_discover_features` | **BREAKING** - Renamed to reflect actual output: features discovery. Now outputs `features.md` |
+| *(new)* | `webtest_discover_flows` | **NEW** - Discovers flows for a specific feature/module, outputs `features/<feature-slug>/flows.md` |
+| `webtest_generate_tests` | `webtest_generate_tests` | No change - already clear |
+| `webtest_run_tests` | `webtest_run_test` | **BREAKING** - Singular form matches behavior (runs ONE test) |
+
+### Prompts (MCP `prompts/list`)
+
+| Current | New | Rationale |
+|---------|-----|-----------|
+| `webtest-start` | `webtest-start` | No change |
+| `webtest-crawl` | `webtest-crawl` | No change |
+| `webtest-analyze` | `webtest-discover` | **BREAKING** - Orchestrates both feature and flow discovery |
+| `webtest-generate-tests` | `webtest-generate-tests` | No change |
+| `webtest-run-test` | `webtest-run-test` | No change (already singular) |
+| `webtest-full-workflow` | `webtest-full-workflow` | No change |
+
+### Resources (file/URI structure)
+
+| Current | New | Rationale |
+|---------|-----|-----------|
+| `analysis/app-analysis.md` | `features.md` | Renamed to match tool output |
+| `analysis/flows.md` | `features/<slug>/flows.md` | Moved under feature structure |
+| All other paths | *(unchanged)* | - |
+
+### Vocabulary Standardization
+
+Throughout prompts, notifications, logs, and output messages:
+
+| Term | Meaning |
+|------|---------|
+| **feature** | A distinct capability/module of the app (e.g., "Authentication", "Shopping Cart") |
+| **flow** | A user journey within a feature (e.g., "Login with email", "Add item to cart") |
+| **crawl** | Automated exploration of the app |
+| **discover** | AI-powered analysis to identify features or flows |
+| **test** | A single executable test case |
+| **run** | Execution of a single test |
+
+## Impact
+
+- Affected specs: `webtest-tools`, `webtest-prompts`, `webtest-resources`, `webtest-sampling`
+- Affected code:
+  - `src/tools/webtest/analyze-app.ts` -> `discover-features.ts`
+  - `src/tools/webtest/run-test-case.ts` (tool name change)
+  - `src/prompts/index.ts`
+  - `src/resources/index.ts`
+  - `src/workspace/index.ts` (new feature/flow directory structure)
+  - `src/sampling/prompts.ts` (vocabulary updates)
+  - All test files referencing renamed tools
+
+## Migration
+
+This is a breaking change for existing clients. No backward compatibility is provided since this is a pre-1.0 release.

package/openspec/changes/refactor-webtest-naming/specs/webtest-prompts/spec.md

@@ -0,0 +1,79 @@
+## MODIFIED Requirements
+
+### Requirement: Prompt Template Registration
+
+The system SHALL register prompt templates with the MCP server for client discovery.
+
+#### Scenario: Prompts are listed on prompts/list
+
+- **GIVEN** a client calls `prompts/list`
+- **WHEN** the response is returned
+- **THEN** it SHALL include prompts:
+  - `webtest-start` (Start web testing analysis)
+  - `webtest-crawl` (Crawl to satisfy focus)
+  - `webtest-discover` (Discover features and flows)
+  - `webtest-generate-tests` (Generate test cases)
+  - `webtest-run-test` (Run a test case)
+
+## RENAMED Requirements
+
+- FROM: `### Requirement: Analyze Prompt`
+- TO: `### Requirement: Discover Prompt`
+
+## MODIFIED Requirements
+
+### Requirement: Discover Prompt
+
+The system SHALL provide a prompt template to discover features and flows from crawled data.
+
+#### Scenario: Discover prompt is invoked
+
+- **GIVEN** client invokes `prompts/get` with name `webtest-discover`
+- **WHEN** the prompt is returned
+- **THEN** it SHALL include:
+  - Description: "Discover features and flows from crawled web application data"
+  - Arguments: `analysisId` (required), `crawlId` (optional), `featureSlug` (optional)
+
+#### Scenario: Discover prompt orchestrates full discovery
+
+- **GIVEN** client invokes discover prompt with only `analysisId`
+- **WHEN** the prompt messages are returned
+- **THEN** it SHALL instruct to:
+  - First call `webtest_discover_features` to identify features
+  - Then call `webtest_discover_flows` for each discovered feature
+
+#### Scenario: Discover prompt supports single feature mode
+
+- **GIVEN** client invokes discover prompt with `analysisId` and `featureSlug`
+- **WHEN** the prompt messages are returned
+- **THEN** it SHALL instruct to call `webtest_discover_flows` only for the specified feature
+
+## MODIFIED Requirements
+
+### Requirement: Prompt Chaining Guidance
+
+The system SHALL include guidance in prompt outputs for the recommended workflow sequence.
+
+#### Scenario: Start analysis prompt suggests next step
+
+- **GIVEN** client uses start analysis prompt
+- **WHEN** the prompt messages are returned
+- **THEN** they SHALL include guidance: "After initialization, use webtest-crawl to explore the application"
+
+#### Scenario: Crawl prompt suggests next step
+
+- **GIVEN** client uses crawl prompt
+- **WHEN** the prompt messages are returned
+- **THEN** they SHALL include guidance: "After crawl completes, use webtest-discover to identify features and flows"
+
+#### Scenario: Discover prompt suggests next step
+
+- **GIVEN** client uses discover prompt
+- **WHEN** the prompt messages are returned
+- **THEN** they SHALL include guidance: "After discovery, use webtest-generate-tests to create test cases"
+
+#### Scenario: Generate tests prompt suggests next step
+
+- **GIVEN** client uses generate tests prompt
+- **WHEN** the prompt messages are returned
+- **THEN** they SHALL include guidance: "After test generation, use webtest-run-test to execute individual test cases"

package/openspec/changes/refactor-webtest-naming/specs/webtest-resources/spec.md

@@ -0,0 +1,80 @@
+## MODIFIED Requirements
+
+### Requirement: Resource URI Scheme
+
+The system SHALL expose all webtest artifacts using a `webtest://` URI scheme with hierarchical paths, using markdown format for all human-readable artifacts.
+
+#### Scenario: Analysis root resource is accessible
+
+- **GIVEN** an analysis has been started with analysisId "abc123"
+- **WHEN** client requests resource `webtest://abc123/`
+- **THEN** it SHALL return the analysis `index.md` metadata as markdown with YAML frontmatter
+
+#### Scenario: Features resource is accessible
+
+- **GIVEN** feature discovery has completed
+- **WHEN** client requests `webtest://abc123/features.md`
+- **THEN** it SHALL return the features list as markdown with YAML frontmatter containing structured feature definitions
+
+#### Scenario: Feature-specific flows are accessible
+
+- **GIVEN** flow discovery has completed for feature "authentication"
+- **WHEN** client requests `webtest://abc123/features/authentication/flows.md`
+- **THEN** it SHALL return user flows for that feature as markdown with YAML frontmatter
+
+#### Scenario: Crawl index resource is accessible
+
+- **GIVEN** a crawl has completed with crawlId "crawl-001"
+- **WHEN** client requests resource `webtest://abc123/crawls/crawl-001/index.md`
+- **THEN** it SHALL return the crawl index as markdown with YAML frontmatter containing page list and metadata
+
+#### Scenario: Page artifacts are accessible by type
+
+- **GIVEN** a page was captured with pageId "page-001"
+- **WHEN** client requests `webtest://abc123/crawls/crawl-001/pages/page-001/screenshot.png`
+- **THEN** it SHALL return the screenshot image
+- **AND** `snapshot.md` returns accessibility tree as formatted markdown with YAML frontmatter
+- **AND** `dom.html` returns HTML content
+
+#### Scenario: Tests are accessible
+
+- **GIVEN** generate_tests has completed
+- **WHEN** client requests `webtest://abc123/tests/tests.md`
+- **THEN** it SHALL return the test cases as markdown with YAML frontmatter containing structured test definitions
+
+#### Scenario: Test run report is accessible
+
+- **GIVEN** a test run has completed with runId "run-001"
+- **WHEN** client requests `webtest://abc123/runs/run-001/report.md`
+- **THEN** it SHALL return the test execution report as markdown with YAML frontmatter containing structured results
+
+## MODIFIED Requirements
+
+### Requirement: Resource Template Registration
+
+The system SHALL register resource templates with the MCP server for discovery, using markdown extensions for all index and report resources.
+
+#### Scenario: Templates are listed on resources/list
+
+- **GIVEN** a client calls `resources/list`
+- **WHEN** the response is returned
+- **THEN** it SHALL include templates for:
+  - `webtest://{analysisId}/index.md` (Analysis index)
+  - `webtest://{analysisId}/features.md` (Discovered features)
+  - `webtest://{analysisId}/features/{featureSlug}/flows.md` (Feature flows)
+  - `webtest://{analysisId}/crawls/{crawlId}/index.md` (Crawl index)
+  - `webtest://{analysisId}/crawls/{crawlId}/checkpoint.md` (Crawl checkpoint)
+  - `webtest://{analysisId}/crawls/{crawlId}/pages/{pageId}/snapshot.md` (Page snapshot)
+  - `webtest://{analysisId}/crawls/{crawlId}/pages/{pageId}/screenshot.png` (Page screenshot)
+  - `webtest://{analysisId}/crawls/{crawlId}/pages/{pageId}/dom.html` (Page DOM)
+  - `webtest://{analysisId}/tests/tests.md` (Test definitions)
+  - `webtest://{analysisId}/runs/{runId}/report.md` (Test run report)
+  - `webtest://{analysisId}/runs/{runId}/steps/{stepNumber}/snapshot.md` (Step snapshot)
+  - `webtest://{analysisId}/runs/{runId}/steps/{stepNumber}/screenshot.png` (Step screenshot)
+
+## REMOVED Requirements
+
+### Requirement: Legacy Analysis Resource Paths
+
+**Reason**: Replaced by feature-based structure
+**Migration**: Use `features.md` instead of `analysis/app-analysis.md`, use `features/<slug>/flows.md` instead of `analysis/flows.md`

package/openspec/changes/refactor-webtest-naming/specs/webtest-sampling/spec.md

@@ -0,0 +1,122 @@
+## RENAMED Requirements
+
+- FROM: `### Requirement: Analysis Sampling`
+- TO: `### Requirement: Feature Discovery Sampling`
+
+## MODIFIED Requirements
+
+### Requirement: Feature Discovery Sampling
+
+The system SHALL use sampling to discover application features from crawled pages.
+
+#### Scenario: Feature discovery sampling prompt is constructed
+
+- **GIVEN** `webtest_discover_features` tool is invoked
+- **WHEN** the sampling prompt is built
+- **THEN** it SHALL include the crawl summary
+- **AND** page snapshots from key pages
+- **AND** instructions to identify app purpose, type, and distinct features/modules
+
+#### Scenario: Feature discovery sampling returns structured features
+
+- **GIVEN** a feature discovery sampling request completes
+- **WHEN** the response is parsed
+- **THEN** it SHALL conform to the features schema:
+  ```json
+  {
+    "appPurpose": "string",
+    "appType": "string",
+    "features": [{
+      "slug": "string",
+      "name": "string",
+      "description": "string",
+      "entities": ["string"],
+      "entryPoints": ["string"]
+    }],
+    "securityObservations": ["string"],
+    "accessibilityObservations": ["string"]
+  }
+  ```
+
+## ADDED Requirements
+
+### Requirement: Flow Discovery Sampling
+
+The system SHALL use sampling to discover user flows within a specific feature.
+
+#### Scenario: Flow discovery sampling prompt is constructed
+
+- **GIVEN** `webtest_discover_flows` tool is invoked with a feature slug
+- **WHEN** the sampling prompt is built
+- **THEN** it SHALL include the feature definition from `features.md`
+- **AND** page snapshots relevant to that feature
+- **AND** instructions to identify user flows within the feature
+
+#### Scenario: Flow discovery sampling returns structured flows
+
+- **GIVEN** a flow discovery sampling request completes
+- **WHEN** the response is parsed
+- **THEN** it SHALL conform to the flows schema:
+  ```json
+  {
+    "featureSlug": "string",
+    "flows": [{
+      "id": "string",
+      "name": "string",
+      "description": "string",
+      "entryPoint": "string",
+      "steps": ["string"]
+    }],
+    "suggestedAssertions": ["string"]
+  }
+  ```
+
+#### Scenario: Flow discovery uses feature context
+
+- **GIVEN** flow discovery is scoped to feature "authentication"
+- **WHEN** the sampling prompt is built
+- **THEN** it SHALL explicitly scope the AI to only identify flows within that feature
+- **AND** reference the feature's entities and entry points
+
+## MODIFIED Requirements
+
+### Requirement: Test Generation Sampling
+
+The system SHALL use sampling to generate test cases from discovered features and flows.
+
+#### Scenario: Test generation sampling prompt is constructed
+
+- **GIVEN** `webtest_generate_tests` tool is invoked
+- **WHEN** the sampling prompt is built
+- **THEN** it SHALL include the features definition from `features.md`
+- **AND** flow definitions from `features/<slug>/flows.md` files
+- **AND** test strategy preferences (count, types)
+
+#### Scenario: Test generation sampling returns test cases
+
+- **GIVEN** a test generation sampling request completes
+- **WHEN** the response is parsed
+- **THEN** it SHALL conform to the test case schema:
+  ```json
+  {
+    "tests": [{
+      "id": "string",
+      "name": "string",
+      "purpose": "string",
+      "featureSlug": "string",
+      "flowId": "string",
+      "preconditions": ["string"],
+      "steps": [{
+        "action": "string",
+        "expected": "string"
+      }],
+      "priority": "string"
+    }]
+  }
+  ```
+
+#### Scenario: Test generation references features and flows
+
+- **GIVEN** test cases are generated
+- **WHEN** the output is structured
+- **THEN** each test case SHALL include `featureSlug` and `flowId` to trace its origin

package/openspec/changes/refactor-webtest-naming/specs/webtest-tools/spec.md

@@ -0,0 +1,113 @@
+## RENAMED Requirements
+
+- FROM: `### Requirement: webtest_analyze_app Tool`
+- TO: `### Requirement: webtest_discover_features Tool`
+
+## MODIFIED Requirements
+
+### Requirement: webtest_discover_features Tool
+
+The system SHALL provide a `webtest_discover_features` tool that identifies application features/modules from crawl data, outputting results in markdown format.
+
+#### Scenario: Discover features writes features.md
+
+- **GIVEN** feature discovery is complete
+- **WHEN** output is generated
+- **THEN** it SHALL write `features.md` resource to workspace root
+- **AND** the file SHALL contain markdown with YAML frontmatter listing discovered features
+
+#### Scenario: Discover features identifies app structure
+
+- **GIVEN** crawl data is available
+- **WHEN** `webtest_discover_features` is called
+- **THEN** it SHALL identify:
+  - Application purpose and type
+  - Distinct features/modules (e.g., Authentication, Shopping Cart, Search)
+  - Entities and data models per feature
+  - Security and accessibility observations
+
+#### Scenario: Discover features outputs URIs
+
+- **GIVEN** feature discovery is complete
+- **WHEN** tool returns
+- **THEN** it SHALL include `featuresFilePath`, `featuresUri` pointing to `features.md`
+
+#### Scenario: Discover features suggests next steps
+
+- **GIVEN** feature discovery is complete
+- **WHEN** tool returns
+- **THEN** it SHALL include `nextSteps` array suggesting to run `webtest_discover_flows` for each feature
+
+## ADDED Requirements
+
+### Requirement: webtest_discover_flows Tool
+
+The system SHALL provide a `webtest_discover_flows` tool that identifies user flows within a specific feature, outputting results in markdown format.
+
+#### Scenario: Discover flows requires feature parameter
+
+- **GIVEN** the tool is called
+- **WHEN** parameters are validated
+- **THEN** it SHALL require `analysisId` and `featureSlug` parameters
+- **AND** `featureSlug` SHALL match a feature from `features.md`
+
+#### Scenario: Discover flows writes feature-specific flows.md
+
+- **GIVEN** flow discovery is complete for feature "authentication"
+- **WHEN** output is generated
+- **THEN** it SHALL write to `features/authentication/flows.md`
+- **AND** the file SHALL contain markdown with YAML frontmatter listing flows for that feature
+
+#### Scenario: Discover flows identifies user journeys
+
+- **GIVEN** crawl data and feature context are available
+- **WHEN** `webtest_discover_flows` is called
+- **THEN** it SHALL identify:
+  - User flows within the feature (e.g., Login, Register, Password Reset)
+  - Entry points for each flow
+  - Step sequences for each flow
+  - Assertions that should hold
+
+#### Scenario: Discover flows outputs URIs
+
+- **GIVEN** flow discovery is complete
+- **WHEN** tool returns
+- **THEN** it SHALL include `flowsFilePath`, `flowsUri` pointing to `features/<slug>/flows.md`
+
+#### Scenario: Discover flows handles unknown feature
+
+- **GIVEN** the tool is called with a `featureSlug` not in `features.md`
+- **WHEN** validation occurs
+- **THEN** it SHALL return an error listing available features
+
+## RENAMED Requirements
+
+- FROM: `### Requirement: webtest_run_tests Tool`
+- TO: `### Requirement: webtest_run_test Tool`
+
+## MODIFIED Requirements
+
+### Requirement: webtest_run_test Tool
+
+The system SHALL provide a `webtest_run_test` tool that executes a single test case with evidence capture, storing all results in markdown format.
+
+#### Scenario: Run test captures evidence
+
+- **GIVEN** a step is executed
+- **WHEN** evidence is captured
+- **THEN** it SHALL take screenshot after action (stored as PNG)
+- **AND** capture accessibility snapshot (stored as `snapshot.md` with formatted tree and YAML frontmatter)
+- **AND** store with step identifier
+
+#### Scenario: Run test outputs report
+
+- **GIVEN** test execution completes
+- **WHEN** output is generated
+- **THEN** it SHALL write `report.md` with pass/fail summary, step details, evidence links, and YAML frontmatter containing structured run data
+- **AND** there SHALL NOT be a separate `index.json` or `artifacts.json` file
+
+#### Scenario: Run test returns URIs
+
+- **GIVEN** execution is complete
+- **WHEN** tool returns
+- **THEN** it SHALL include `testRunId`, `reportFilePath`, `reportUri` pointing to `report.md`

package/openspec/changes/refactor-webtest-naming/tasks.md

@@ -0,0 +1,119 @@
+## 1. Workspace Structure Changes
+
+- [ ] 1.1 Update `WorkspaceManager` types for new feature structure
+  - Add `features: Feature[]` to workspace index
+  - Add `saveFeatures()` method
+  - Add `saveFlows(featureSlug)` method
+  - Remove `saveAnalysis()` method (replaced by above)
+
+- [ ] 1.2 Create feature directory structure in workspace
+  - `features.md` at workspace root
+  - `features/<slug>/flows.md` per feature
+  - Update `getWorkspacePath()` to support feature paths
+
+- [ ] 1.3 Update workspace markdown generation
+  - Implement `generateFeaturesMarkdown()`
+  - Implement `generateFlowsMarkdown(featureSlug)`
+  - Update YAML frontmatter schemas
+
+## 2. Tool Renaming and Implementation
+
+- [ ] 2.1 Rename `analyze-app.ts` to `discover-features.ts`
+  - Rename tool from `webtest_analyze_app` to `webtest_discover_features`
+  - Update description to reflect feature discovery focus
+  - Update output to reference `features.md` instead of `app-analysis.md`
+  - Remove flow generation (moved to separate tool)
+  - Add `nextSteps` suggesting `webtest_discover_flows` calls
+
+- [ ] 2.2 Create new `discover-flows.ts` tool
+  - Implement `webtest_discover_flows` tool
+  - Accept `analysisId` and `featureSlug` parameters
+  - Validate feature exists in `features.md`
+  - Output to `features/<slug>/flows.md`
+  - Build sampling prompt with feature context
+
+- [ ] 2.3 Rename tool in `run-test-case.ts`
+  - Change tool name from `webtest_run_tests` to `webtest_run_test`
+  - Update description (singular)
+  - No functional changes
+
+- [ ] 2.4 Update `src/tools/webtest/index.ts` exports
+  - Export `discover-features.ts`
+  - Export `discover-flows.ts`
+  - Remove `analyze-app.ts` export
+
+## 3. Sampling Prompt Updates
+
+- [ ] 3.1 Rename and update `buildAnalysisPrompt` in `sampling/prompts.ts`
+  - Rename to `buildFeatureDiscoveryPrompt`
+  - Update prompt text to focus on features/modules
+  - Update expected output schema
+
+- [ ] 3.2 Create `buildFlowDiscoveryPrompt` in `sampling/prompts.ts`
+  - Accept feature context as parameter
+  - Scope prompt to single feature
+  - Define flows schema for output
+
+- [ ] 3.3 Update `buildTestGenerationPrompt`
+  - Reference `features.md` and `flows.md` in prompt
+  - Add `featureSlug` and `flowId` to expected test output
+
+## 4. Schema Updates
+
+- [ ] 4.1 Update `schemas.ts` for new data structures
+  - Add `FeatureSchema` (slug, name, description, entities, entryPoints)
+  - Add `FeaturesOutputSchema` (array of features)
+  - Add `FlowDiscoveryOutputSchema` (scoped to feature)
+  - Deprecate `AppAnalysisSchema`
+
+## 5. Prompt Template Updates
+
+- [ ] 5.1 Rename `webtest-analyze` prompt to `webtest-discover` in `prompts/index.ts`
+  - Update prompt name and description
+  - Update message to orchestrate feature+flow discovery
+  - Support optional `featureSlug` for single-feature mode
+
+- [ ] 5.2 Update prompt chaining guidance
+  - Crawl -> Discover (not Analyze)
+  - Discover -> Generate Tests
+  - Update vocabulary in all prompt messages
+
+- [ ] 5.3 Update tool references in all prompts
+  - `webtest_analyze_app` -> `webtest_discover_features`
+  - `webtest_run_tests` -> `webtest_run_test`
+
+## 6. Resource Manager Updates
+
+- [ ] 6.1 Update resource listing in `resources/index.ts`
+  - Add `features.md` resource
+  - Add `features/<slug>/flows.md` resources per feature
+  - Remove `analysis/app-analysis.md` and `analysis/flows.md` references
+
+- [ ] 6.2 Update resource descriptions
+  - Use consistent "feature" and "flow" vocabulary
+
+## 7. Test Updates
+
+- [ ] 7.1 Rename test file `analyze-app.test.ts` to `discover-features.test.ts`
+  - Update all test descriptions
+  - Update tool name references
+
+- [ ] 7.2 Create `discover-flows.test.ts`
+  - Test feature validation
+  - Test flow output structure
+  - Test missing feature error handling
+
+- [ ] 7.3 Update `run-test-case.test.ts`
+  - Update tool name in tests
+  - No functional test changes needed
+
+- [ ] 7.4 Update integration tests
+  - Update tool names in `integration.test.ts`
+  - Test full workflow with new tool names
+
+## 8. Documentation and Validation
+
+- [ ] 8.1 Run all unit tests and fix failures
+- [ ] 8.2 Run integration tests and fix failures
+- [ ] 8.3 Verify build succeeds
+- [ ] 8.4 Update specs after implementation (archive step)