zhongwei/gh-joshuaoliphant-claude-plugins-plugins-adw-bootstrap
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

Initial commit

Browse Source
This commit is contained in:
Zhongwei Li
2025-11-30 08:28:42 +08:00
commit 8a4be47b6e
43 changed files with 10867 additions and 0 deletions
Download Patch File Download Diff File Expand all files Collapse all files

106
skills/adw-bootstrap/reference/scaled/commands/bug.md Normal file
View File

@@ -0,0 +1,106 @@
# Bug Planning
Create a new plan to resolve the `Bug` using the exact specified markdown `Plan Format`. Follow the `Instructions` to create the plan use the `Relevant Files` to focus on the right files.
## Variables
issue_number: $1
adw_id: $2
issue_json: $3
## Instructions
- IMPORTANT: You're writing a plan to resolve a bug based on the `Bug` that will add value to the application.
- IMPORTANT: The `Bug` describes the bug that will be resolved but remember we're not resolving the bug, we're creating the plan that will be used to resolve the bug based on the `Plan Format` below.
- You're writing a plan to resolve a bug, it should be thorough and precise so we fix the root cause and prevent regressions.
- Create the plan in the `specs/` directory with filename: `issue-{issue_number}-adw-{adw_id}-sdlc_planner-{descriptive-name}.md`
- Replace `{descriptive-name}` with a short, descriptive name based on the bug (e.g., "fix-login-error", "resolve-timeout", "patch-memory-leak")
- Use the plan format below to create the plan.
- Research the codebase to understand the bug, reproduce it, and put together a plan to fix it.
- IMPORTANT: Replace every <placeholder> in the `Plan Format` with the requested value. Add as much detail as needed to fix the bug.
- Use your reasoning model: THINK HARD about the bug, its root cause, and the steps to fix it properly.
- IMPORTANT: Be surgical with your bug fix, solve the bug at hand and don't fall off track.
- IMPORTANT: We want the minimal number of changes that will fix and address the bug.
- Don't use decorators. Keep it simple.
- If you need a new library, use `uv add` and be sure to report it in the `Notes` section of the `Plan Format`.
- IMPORTANT: If the bug affects the UI or user interactions:
- Add a task in the `Step by Step Tasks` section to create a separate E2E test file in `.claude/commands/e2e/test_<descriptive_name>.md` based on examples in that directory
- Add E2E test validation to your Validation Commands section
- IMPORTANT: When you fill out the `Plan Format: Relevant Files` section, add an instruction to read `.claude/commands/test_e2e.md`, and `.claude/commands/e2e/test_basic_query.md` to understand how to create an E2E test file. List your new E2E test file to the `Plan Format: New Files` section.
- To be clear, we're not creating a new E2E test file, we're creating a task to create a new E2E test file in the `Plan Format` below
- Respect requested files in the `Relevant Files` section.
- Start your research by reading the `README.md` file.
## Relevant Files
Focus on the following files:
- `README.md` - Contains the project overview and instructions.
- `app/server/**` - Contains the codebase server.
- `app/client/**` - Contains the codebase client.
- `scripts/**` - Contains the scripts to start and stop the server + client.
- `adws/**` - Contains the AI Developer Workflow (ADW) scripts.
- Read `.claude/commands/conditional_docs.md` to check if your task requires additional documentation
- If your task matches any of the conditions listed, include those documentation files in the `Plan Format: Relevant Files` section of your plan
Ignore all other files in the codebase.
## Plan Format
```md
# Bug: <bug name>
## Metadata
issue_number: `{issue_number}`
adw_id: `{adw_id}`
issue_json: `{issue_json}`
## Bug Description
<describe the bug in detail, including symptoms and expected vs actual behavior>
## Problem Statement
<clearly define the specific problem that needs to be solved>
## Solution Statement
<describe the proposed solution approach to fix the bug>
## Steps to Reproduce
<list exact steps to reproduce the bug>
## Root Cause Analysis
<analyze and explain the root cause of the bug>
## Relevant Files
Use these files to fix the bug:
<find and list the files that are relevant to the bug describe why they are relevant in bullet points. If there are new files that need to be created to fix the bug, list them in an h3 'New Files' section.>
## Step by Step Tasks
IMPORTANT: Execute every step in order, top to bottom.
<list step by step tasks as h3 headers plus bullet points. use as many h3 headers as needed to fix the bug. Order matters, start with the foundational shared changes required to fix the bug then move on to the specific changes required to fix the bug. Include tests that will validate the bug is fixed with zero regressions.>
<If the bug affects UI, include a task to create a E2E test file. Your task should look like: "Read `.claude/commands/e2e/test_basic_query.md` and `.claude/commands/e2e/test_complex_query.md` and create a new E2E test file in `.claude/commands/e2e/test_<descriptive_name>.md` that validates the bug is fixed, be specific with the steps to prove the bug is fixed. We want the minimal set of steps to validate the bug is fixed and screen shots to prove it if possible.">
<Your last step should be running the `Validation Commands` to validate the bug is fixed with zero regressions.>
## Validation Commands
Execute every command to validate the bug is fixed with zero regressions.
<list commands you'll use to validate with 100% confidence the bug is fixed with zero regressions. every command must execute without errors so be specific about what you want to run to validate the bug is fixed with zero regressions. Include commands to reproduce the bug before and after the fix.>
<If you created an E2E test, include the following validation step: "Read .claude/commands/test_e2e.md`, then read and execute your new E2E `.claude/commands/e2e/test_<descriptive_name>.md` test file to validate this functionality works.">
- `cd app/server && uv run pytest` - Run server tests to validate the bug is fixed with zero regressions
- `cd app/client && bun tsc --noEmit` - Run frontend tests to validate the bug is fixed with zero regressions
- `cd app/client && bun run build` - Run frontend build to validate the bug is fixed with zero regressions
## Notes
<optionally list any additional notes or context that are relevant to the bug that will be helpful to the developer>
```
## Bug
Extract the bug details from the `issue_json` variable (parse the JSON and use the title and body fields).
## Report
- IMPORTANT: Return exclusively the path to the plan file created and nothing else.

57
skills/adw-bootstrap/reference/scaled/commands/classify_adw.md Normal file
View File

@@ -0,0 +1,57 @@
# ADW Workflow Extraction
Extract ADW workflow information from the text below and return a JSON response.
## Instructions
- Look for ADW workflow commands in the text (e.g., `/adw_plan_iso`, `/adw_build_iso`, `/adw_test_iso`, `/adw_review_iso`, `/adw_document_iso`, `/adw_patch_iso`, `/adw_plan_build_iso`, `/adw_plan_build_test_iso`, `/adw_plan_build_test_review_iso`, `/adw_sdlc_iso`, `/adw_sdlc_ZTE_iso`)
- Also recognize commands without the `_iso` suffix and automatically add it (e.g., `/adw_plan` → `/adw_plan_iso`)
- Also recognize variations like `adw_plan_build`, `adw plan build`, `/adw plan then build`, etc. and map to the correct command
- Look for ADW IDs (8-character alphanumeric strings, often after "adw_id:" or "ADW ID:" or similar)
- Look for model set specification: "model_set base" or "model_set heavy" (case insensitive)
- Default to "base" if no model_set is specified
- Also recognize variations like "model set: heavy", "modelset heavy", etc.
- Return a JSON object with the extracted information
- If no ADW workflow is found, return empty JSON: `{}`
- IMPORTANT: DO NOT RUN the `adw_sdlc_ZTE_iso` workflows unless `ZTE` is EXPLICITLY uppercased. This is a dangerous workflow and it needs to be absolutely clear when we're running it. If zte is not capitalized, then run the non zte version `/adw_sdlc_iso`.
## Valid ADW Commands
- `/adw_plan_iso` - Planning only
- `/adw_build_iso` - Building only (requires adw_id)
- `/adw_test_iso` - Testing only (requires adw_id)
- `/adw_review_iso` - Review only (requires adw_id)
- `/adw_document_iso` - Documentation only (requires adw_id)
- `/adw_ship_iso` - Ship/approve and merge PR (requires adw_id)
- `/adw_patch_iso` - Direct patch from issue
- `/adw_plan_build_iso` - Plan + Build
- `/adw_plan_build_test_iso` - Plan + Build + Test
- `/adw_plan_build_review_iso` - Plan + Build + Review (skips test)
- `/adw_plan_build_document_iso` - Plan + Build + Document (skips test and review)
- `/adw_plan_build_test_review_iso` - Plan + Build + Test + Review
- `/adw_sdlc_iso` - Complete SDLC: Plan + Build + Test + Review + Document
- `/adw_sdlc_zte_iso` - Zero Touch Execution: Complete SDLC + auto-merge to production. Note: as per instructions, 'ZTE' must be capitalized. Do not run this if 'zte' is not capitalized.
## Response Format
Respond ONLY with a JSON object in this format:
```json
{
"adw_slash_command": "/adw_plan",
"adw_id": "abc12345",
"model_set": "base"
}
```
Fields:
- `adw_slash_command`: The ADW command found (include the slash)
- `adw_id`: The 8-character ADW ID if found
- `model_set`: The model set to use ("base" or "heavy"), defaults to "base" if not specified
If only some fields are found, include only those fields.
If nothing is found, return: `{}`
IMPORTANT: Always include `model_set` with value "base" if no model_set is explicitly mentioned in the text.
## Text to Analyze
$ARGUMENTS

22
skills/adw-bootstrap/reference/scaled/commands/classify_issue.md Normal file
View File

@@ -0,0 +1,22 @@
# Github Issue Command Selection
Based on the `Github Issue` below, follow the `Instructions` to select the appropriate command to execute based on the `Command Mapping`.
## Instructions
- Based on the details in the `Github Issue`, select the appropriate command to execute.
- IMPORTANT: Respond exclusively with '/' followed by the command to execute based on the `Command Mapping` below.
- Use the command mapping to help you decide which command to respond with.
- Don't examine the codebase just focus on the `Github Issue` and the `Command Mapping` below to determine the appropriate command to execute.
## Command Mapping
- Respond with `/chore` if the issue is a chore.
- Respond with `/bug` if the issue is a bug.
- Respond with `/feature` if the issue is a feature.
- Respond with `/patch` if the issue is a patch.
- Respond with `0` if the issue isn't any of the above.
## Github Issue
$ARGUMENTS

44
skills/adw-bootstrap/reference/scaled/commands/cleanup_worktrees.md Normal file
View File

@@ -0,0 +1,44 @@
# Cleanup ADW Worktrees
Clean up isolated ADW worktrees and their associated resources.
## Variables
action: $1 (all|specific|list)
adw_id: $2 (optional, required if action is "specific")
## Instructions
Manage git worktrees created by isolated ADW workflows:
- If action is "list": Show all worktrees under trees/ directory
- If action is "specific": Remove the specific worktree for the given adw_id
- If action is "all": Remove all worktrees under trees/ directory
## Run
Based on the action:
### List worktrees
If action is "list":
- Run `git worktree list | grep "trees/"` to show isolated worktrees
- List the contents of the trees/ directory with sizes
### Remove specific worktree
If action is "specific" and adw_id is provided:
- Check if trees/{adw_id} exists
- Run `git worktree remove trees/{adw_id}` to remove it
- Report success or any errors
### Remove all worktrees
If action is "all":
- First list all worktrees that will be removed
- For each worktree under trees/, run `git worktree remove`
- Clean up any remaining directories under trees/
- Run `git worktree prune` to clean up any stale entries
## Report
Report the results of the cleanup operation:
- Number of worktrees removed
- Any errors encountered
- Current status after cleanup

129
skills/adw-bootstrap/reference/scaled/commands/document.md Normal file
View File

@@ -0,0 +1,129 @@
# Document Feature
Generate concise markdown documentation for implemented features by analyzing code changes and specifications. This command creates documentation in the `app_docs/` directory based on git diff analysis against the main branch and the original feature specification.
## Variables
adw_id: $1
spec_path: $2 if provided, otherwise leave it blank
documentation_screenshots_dir: $3 if provided, otherwise leave it blank
## Instructions
### 1. Analyze Changes
- Run `git diff origin/main --stat` to see files changed and lines modified
- Run `git diff origin/main --name-only` to get the list of changed files
- For significant changes (>50 lines), run `git diff origin/main <file>` on specific files to understand the implementation details
### 2. Read Specification (if provided)
- If `spec_path` is provided, read the specification file to understand:
- Original requirements and goals
- Expected functionality
- Success criteria
- Use this to frame the documentation around what was requested vs what was built
### 3. Analyze and Copy Screenshots (if provided)
- If `documentation_screenshots_dir` is provided, list and examine screenshots
- Create `app_docs/assets/` directory if it doesn't exist
- Copy all screenshot files (*.png) from `documentation_screenshots_dir` to `app_docs/assets/`
- Preserve original filenames
- Use `cp` command to copy files
- Use visual context to better describe UI changes or visual features
- Reference screenshots in documentation using relative paths (e.g., `assets/screenshot-name.png`)
### 4. Generate Documentation
- Create a new documentation file in `app_docs/` directory
- Filename format: `feature-{adw_id}-{descriptive-name}.md`
- Replace `{descriptive-name}` with a short feature name (e.g., "user-auth", "data-export", "search-ui")
- Follow the Documentation Format below
- Focus on:
- What was built (based on git diff)
- How it works (technical implementation)
- How to use it (user perspective)
- Any configuration or setup required
### 5. Update Conditional Documentation
- After creating the documentation file, read `.claude/commands/conditional_docs.md`
- Add an entry for the new documentation file with appropriate conditions
- The entry should help future developers know when to read this documentation
- Format the entry following the existing pattern in the file
### 6. Final Output
- When you finish writing the documentation and updating conditional_docs.md, return exclusively the path to the documentation file created and nothing else
## Documentation Format
```md
# <Feature Title>
**ADW ID:** <adw_id>
**Date:** <current date>
**Specification:** <spec_path or "N/A">
## Overview
<2-3 sentence summary of what was built and why>
## Screenshots
<If documentation_screenshots_dir was provided and screenshots were copied>
![<Description>](assets/<screenshot-filename.png>)
## What Was Built
<List the main components/features implemented based on the git diff analysis>
- <Component/feature 1>
- <Component/feature 2>
- <etc>
## Technical Implementation
### Files Modified
<List key files changed with brief description of changes>
- `<file_path>`: <what was changed/added>
- `<file_path>`: <what was changed/added>
### Key Changes
<Describe the most important technical changes in 3-5 bullet points>
## How to Use
<Step-by-step instructions for using the new feature>
1. <Step 1>
2. <Step 2>
3. <etc>
## Configuration
<Any configuration options, environment variables, or settings>
## Testing
<Brief description of how to test the feature>
## Notes
<Any additional context, limitations, or future considerations>
```
## Conditional Docs Entry Format
After creating the documentation, add this entry to `.claude/commands/conditional_docs.md`:
```md
- app_docs/<your_documentation_file>.md
- Conditions:
- When working with <feature area>
- When implementing <related functionality>
- When troubleshooting <specific issues>
```
## Report
- IMPORTANT: Return exclusively the path to the documentation file created and nothing else.

34
skills/adw-bootstrap/reference/scaled/commands/generate_branch_name.md Normal file
View File

@@ -0,0 +1,34 @@
# Generate Git Branch Name
Based on the `Instructions` below, take the `Variables` follow the `Run` section to generate a concise Git branch name following the specified format. Then follow the `Report` section to report the results of your work.
## Variables
issue_class: $1
adw_id: $2
issue: $3
## Instructions
- Generate a branch name in the format: `<issue_class>-issue-<issue_number>-adw-<adw_id>-<concise_name>`
- The `<concise_name>` should be:
- 3-6 words maximum
- All lowercase
- Words separated by hyphens
- Descriptive of the main task/feature
- No special characters except hyphens
- Examples:
- `feat-issue-123-adw-a1b2c3d4-add-user-auth`
- `bug-issue-456-adw-e5f6g7h8-fix-login-error`
- `chore-issue-789-adw-i9j0k1l2-update-dependencies`
- `test-issue-323-adw-m3n4o5p6-fix-failing-tests`
- Extract the issue number, title, and body from the issue JSON
## Run
Generate the branch name based on the instructions above.
Do NOT create or checkout any branches - just generate the name.
## Report
Return ONLY the generated branch name (no other text)

82
skills/adw-bootstrap/reference/scaled/commands/install_worktree.md Normal file
View File

@@ -0,0 +1,82 @@
# Install Worktree
This command sets up an isolated worktree environment with custom port configuration.
## Parameters
- Worktree path: {0}
- Backend port: {1}
- Frontend port: {2}
## Read
- .env.sample (from parent repo)
- ./app/server/.env.sample (from parent repo)
- .mcp.json (from parent repo)
- playwright-mcp-config.json (from parent repo)
## Steps
1. **Navigate to worktree directory**
```bash
cd {0}
```
2. **Create port configuration file**
Create `.ports.env` with:
```
BACKEND_PORT={1}
FRONTEND_PORT={2}
VITE_BACKEND_URL=http://localhost:{1}
```
3. **Copy and update .env files**
- Copy `.env` from parent repo if it exists
- Append `.ports.env` contents to `.env`
- Copy `app/server/.env` from parent repo if it exists
- Append `.ports.env` contents to `app/server/.env`
4. **Copy and configure MCP files**
- Copy `.mcp.json` from parent repo if it exists
- Copy `playwright-mcp-config.json` from parent repo if it exists
- These files are needed for Model Context Protocol and Playwright automation
After copying, update paths to use absolute paths:
- Get the absolute worktree path: `WORKTREE_PATH=$(pwd)`
- Update `.mcp.json`:
- Find the line containing `"./playwright-mcp-config.json"`
- Replace it with `"${WORKTREE_PATH}/playwright-mcp-config.json"`
- Use a JSON-aware tool or careful string replacement to maintain valid JSON
- Update `playwright-mcp-config.json`:
- Find the line containing `"dir": "./videos"`
- Replace it with `"dir": "${WORKTREE_PATH}/videos"`
- Create the videos directory: `mkdir -p ${WORKTREE_PATH}/videos`
- This ensures MCP configuration works correctly regardless of execution context
5. **Install backend dependencies**
```bash
cd app/server && uv sync --all-extras
```
6. **Install frontend dependencies**
```bash
cd ../client && bun install
```
7. **Setup database**
```bash
cd ../.. && ./scripts/reset_db.sh
```
## Error Handling
- If parent .env files don't exist, create minimal versions from .env.sample files
- Ensure all paths are absolute to avoid confusion
## Report
- List all files created/modified (including MCP configuration files)
- Show port assignments
- Confirm dependencies installed
- Note any missing parent .env files that need user attention
- Note any missing MCP configuration files
- Show the updated absolute paths in:
- `.mcp.json` (should show full path to playwright-mcp-config.json)
- `playwright-mcp-config.json` (should show full path to videos directory)
- Confirm videos directory was created

92
skills/adw-bootstrap/reference/scaled/commands/patch.md Normal file
View File

@@ -0,0 +1,92 @@
# Patch Plan
Create a **focused patch plan** to resolve a specific issue based on the `review_change_request`. Follow the `Instructions` to create a concise plan that addresses the issue with minimal, targeted changes.
## Variables
adw_id: $1
review_change_request: $2
spec_path: $3 if provided, otherwise leave it blank
agent_name: $4 if provided, otherwise use 'patch_agent'
issue_screenshots: $ARGUMENT (optional) - comma-separated list of screenshot paths if provided
## Instructions
- IMPORTANT: You're creating a patch plan to fix a specific review issue. Keep changes small, focused, and targeted
- Read the original specification (spec) file at `spec_path` if provided to understand the context and requirements
- IMPORTANT Use the `review_change_request` to understand exactly what needs and use it as the basis for your patch plan
- If `issue_screenshots` are provided, examine them to better understand the visual context of the issue
- Create the patch plan in `specs/patch/` directory with filename: `patch-adw-{adw_id}-{descriptive-name}.md`
- Replace `{descriptive-name}` with a short name based on the issue (e.g., "fix-button-color", "update-validation", "correct-layout")
- IMPORTANT: This is a PATCH - keep the scope minimal. Only fix what's described in the `review_change_request` and nothing more. Address only the `review_change_request`.
- Run `git diff --stat`. If changes are available, use them to understand what's been done in the codebase and so you can understand the exact changes you should detail in the patch plan.
- Ultra think about the most efficient way to implement the solution with minimal code changes
- Base your `Plan Format: Validation` on the validation steps from `spec_path` if provided
- If any tests fail in the validation steps, you must fix them.
- If not provided, READ `.claude/commands/test.md: ## Test Execution Sequence` and execute the tests to understand the tests that need to be run to validate the patch.
- Replace every <placeholder> in the `Plan Format` with specific implementation details
- IMPORTANT: When you finish writing the patch plan, return exclusively the path to the patch plan file created and nothing else.
## Relevant Files
Focus on the following files:
- `README.md` - Contains the project overview and instructions.
- `app/server/**` - Contains the codebase server.
- `app/client/**` - Contains the codebase client.
- `scripts/**` - Contains the scripts to start and stop the server + client.
- `adws/**` - Contains the AI Developer Workflow (ADW) scripts.
- Read `.claude/commands/conditional_docs.md` to check if your task requires additional documentation
- If your task matches any of the conditions listed, reference those documentation files to understand the context better when creating your patch plan
Ignore all other files in the codebase.
## Plan Format
```md
# Patch: <concise patch title>
## Metadata
adw_id: `{adw_id}`
review_change_request: `{review_change_request}`
## Issue Summary
**Original Spec:** <spec_path>
**Issue:** <brief description of the review issue based on the `review_change_request`>
**Solution:** <brief description of the solution approach based on the `review_change_request`>
## Files to Modify
Use these files to implement the patch:
<list only the files that need changes - be specific and minimal>
## Implementation Steps
IMPORTANT: Execute every step in order, top to bottom.
<list 2-5 focused steps to implement the patch. Each step should be a concrete action.>
### Step 1: <specific action>
- <implementation detail>
- <implementation detail>
### Step 2: <specific action>
- <implementation detail>
- <implementation detail>
<continue as needed, but keep it minimal>
## Validation
Execute every command to validate the patch is complete with zero regressions.
<list 1-5 specific commands or checks to verify the patch works correctly>
## Patch Scope
**Lines of code to change:** <estimate>
**Risk level:** <low|medium|high>
**Testing required:** <brief description>
```
## Report
- IMPORTANT: Return exclusively the path to the patch plan file created and nothing else.

41
skills/adw-bootstrap/reference/scaled/commands/pull_request.md Normal file
View File

@@ -0,0 +1,41 @@
# Create Pull Request
Based on the `Instructions` below, take the `Variables` follow the `Run` section to create a pull request. Then follow the `Report` section to report the results of your work.
## Variables
branch_name: $1
issue: $2
plan_file: $3
adw_id: $4
## Instructions
- Generate a pull request title in the format: `<issue_type>: #<issue_number> - <issue_title>`
- The PR body should include:
- A summary section with the issue context
- Link to the implementation `plan_file` if it exists
- Reference to the issue (Closes #<issue_number>)
- ADW tracking ID
- A checklist of what was done
- A summary of key changes made
- Extract issue number, type, and title from the issue JSON
- Examples of PR titles:
- `feat: #123 - Add user authentication`
- `bug: #456 - Fix login validation error`
- `chore: #789 - Update dependencies`
- `test: #1011 - Test xyz`
- Don't mention Claude Code in the PR body - let the author get credit for this.
## Run
1. Run `git diff origin/main...HEAD --stat` to see a summary of changed files
2. Run `git log origin/main..HEAD --oneline` to see the commits that will be included
3. Run `git diff origin/main...HEAD --name-only` to get a list of changed files
4. Run `git push -u origin <branch_name>` to push the branch
5. Set GH_TOKEN environment variable from GITHUB_PAT if available, then run `gh pr create --title "<pr_title>" --body "<pr_body>" --base main` to create the PR
6. Capture the PR URL from the output
## Report
Return ONLY the PR URL that was created (no other text)

85
skills/adw-bootstrap/reference/scaled/commands/review.md Normal file
View File

@@ -0,0 +1,85 @@
# Review
Follow the `Instructions` below to **review work done against a specification file** (specs/*.md) to ensure implemented features match requirements. Use the spec file to understand the requirements and then use the git diff if available to understand the changes made. Capture screenshots of critical functionality paths as documented in the `Instructions` section. If there are issues, report them if not then report success.
## Variables
adw_id: $1
spec_file: $2
agent_name: $3 if provided, otherwise use 'review_agent'
review_image_dir: `<absolute path to codebase>/agents/<adw_id>/<agent_name>/review_img/`
## Instructions
- Check current git branch using `git branch` to understand context
- Run `git diff origin/main` to see all changes made in current branch. Continue even if there are no changes related to the spec file.
- Find the spec file by looking for specs/*.md files in the diff that match the current branch name
- Read the identified spec file to understand requirements
- IMPORTANT: If the work can be validated by UI validation then (if not skip the section):
- Use the playwright mcp server commands to validate the work.
- Look for corresponding e2e test files in ./claude/commands/e2e/test_*.md that mirror the feature name
- Use e2e test files only as navigation guides for screenshot locations, not for other purposes
- IMPORTANT: To be clear, we're not testing. We know the functionality works. We're reviewing the implementation against the spec to make sure it matches what was requested.
- IMPORTANT: Take screen shots along the way to showcase the new functionality and any issues you find
- Capture visual proof of working features through targeted screenshots
- Navigate to the application and capture screenshots of only the critical paths based on the spec
- Compare implemented changes with spec requirements to verify correctness
- Do not take screenshots of the entire process, only the critical points.
- IMPORTANT: Aim for `1-5` screenshots to showcase that the new functionality works as specified.
- If there is a review issue, take a screenshot of the issue and add it to the `review_issues` array. Describe the issue, resolution, and severity.
- Number your screenshots in the order they are taken like `01_<descriptive name>.png`, `02_<descriptive name>.png`, etc.
- IMPORTANT: Be absolutely sure to take a screen shot of the critical point of the new functionality
- IMPORTANT: Copy all screenshots to the provided `review_image_dir`
- IMPORTANT: Store the screenshots in the `review_image_dir` and be sure to use full absolute paths.
- Focus only on critical functionality paths - avoid unnecessary screenshots
- Ensure screenshots clearly demonstrate that features work as specified
- Use descriptive filenames that indicate what part of the change is being verified
- IMPORTANT: Issue Severity Guidelines
- Think hard about the impact of the issue on the feature and the user
- Guidelines:
- `skippable` - the issue is non-blocker for the work to be released but is still a problem
- `tech_debt` - the issue is non-blocker for the work to be released but will create technical debt that should be addressed in the future
- `blocker` - the issue is a blocker for the work to be released and should be addressed immediately. It will harm the user experience or will not function as expected.
- IMPORTANT: Return ONLY the JSON array with test results
- IMPORTANT: Output your result in JSON format based on the `Report` section below.
- IMPORTANT: Do not include any additional text, explanations, or markdown formatting
- We'll immediately run JSON.parse() on the output, so make sure it's valid JSON
- Ultra think as you work through the review process. Focus on the critical functionality paths and the user experience. Don't report issues if they are not critical to the feature.
## Setup
IMPORTANT: Read and **Execute** `.claude/commands/prepare_app.md` now to prepare the application for the review.
- Note: prepare_app.md will automatically detect and use ports from `.ports.env` if running in a worktree environment
- The application URL will be http://localhost:PORT where PORT is from `.ports.env` (FRONTEND_PORT) or default 5173
## Report
- IMPORTANT: Return results exclusively as a JSON array based on the `Output Structure` section below.
- `success` should be `true` if there are NO BLOCKING issues (implementation matches spec for critical functionality)
- `success` should be `false` ONLY if there are BLOCKING issues that prevent the work from being released
- `review_issues` can contain issues of any severity (skippable, tech_debt, or blocker)
- `screenshots` should ALWAYS contain paths to screenshots showcasing the new functionality, regardless of success status. Use full absolute paths.
- This allows subsequent agents to quickly identify and resolve blocking errors while documenting all issues
### Output Structure
```json
{
success: "boolean - true if there are NO BLOCKING issues (can have skippable/tech_debt issues), false if there are BLOCKING issues",
review_summary: "string - 2-4 sentences describing what was built and whether it matches the spec. Written as if reporting during a standup meeting. Example: 'The natural language query feature has been implemented with drag-and-drop file upload and interactive table display. The implementation matches the spec requirements for SQL injection protection and supports both CSV and JSON formats. Minor UI improvements could be made but all core functionality is working as specified.'",
review_issues: [
{
"review_issue_number": "number - the issue number based on the index of this issue",
"screenshot_path": "string - /absolute/path/to/screenshot_that_shows_review_issue.png",
"issue_description": "string - description of the issue",
"issue_resolution": "string - description of the resolution",
"issue_severity": "string - severity of the issue between 'skippable', 'tech_debt', 'blocker'"
},
...
],
screenshots: [
"string - /absolute/path/to/screenshot_showcasing_functionality.png",
"string - /absolute/path/to/screenshot_showcasing_functionality.png",
"...",
]
}

115
skills/adw-bootstrap/reference/scaled/commands/test.md Normal file
View File

@@ -0,0 +1,115 @@
# Application Validation Test Suite
Execute comprehensive validation tests for both frontend and backend components, returning results in a standardized JSON format for automated processing.
## Purpose
Proactively identify and fix issues in the application before they impact users or developers. By running this comprehensive test suite, you can:
- Detect syntax errors, type mismatches, and import failures
- Identify broken tests or security vulnerabilities
- Verify build processes and dependencies
- Ensure the application is in a healthy state
## Variables
TEST_COMMAND_TIMEOUT: 5 minutes
## Instructions
- Execute each test in the sequence provided below
- Capture the result (passed/failed) and any error messages
- IMPORTANT: Return ONLY the JSON array with test results
- IMPORTANT: Do not include any additional text, explanations, or markdown formatting
- We'll immediately run JSON.parse() on the output, so make sure it's valid JSON
- If a test passes, omit the error field
- If a test fails, include the error message in the error field
- Execute all tests even if some fail
- Error Handling:
- If a command returns non-zero exit code, mark as failed and immediately stop processing tests
- Capture stderr output for error field
- Timeout commands after `TEST_COMMAND_TIMEOUT`
- IMPORTANT: If a test fails, stop processing tests and return the results thus far
- Some tests may have dependencies (e.g., server must be stopped for port availability)
- API health check is required
- Test execution order is important - dependencies should be validated first
- All file paths are relative to the project root
- Always run `pwd` and `cd` before each test to ensure you're operating in the correct directory for the given test
## Test Execution Sequence
### Backend Tests
1. **Python Syntax Check**
- Preparation Command: None
- Command: `cd app/server && uv run python -m py_compile server.py main.py core/*.py`
- test_name: "python_syntax_check"
- test_purpose: "Validates Python syntax by compiling source files to bytecode, catching syntax errors like missing colons, invalid indentation, or malformed statements"
2. **Backend Code Quality Check**
- Preparation Command: None
- Command: `cd app/server && uv run ruff check .`
- test_name: "backend_linting"
- test_purpose: "Validates Python code quality, identifies unused imports, style violations, and potential bugs"
3. **All Backend Tests**
- Preparation Command: None
- Command: `cd app/server && uv run pytest tests/ -v --tb=short`
- test_name: "all_backend_tests"
- test_purpose: "Validates all backend functionality including file processing, SQL security, LLM integration, and API endpoints"
### Frontend Tests
4. **TypeScript Type Check**
- Preparation Command: None
- Command: `cd app/client && bun tsc --noEmit`
- test_name: "typescript_check"
- test_purpose: "Validates TypeScript type correctness without generating output files, catching type errors, missing imports, and incorrect function signatures"
5. **Frontend Build**
- Preparation Command: None
- Command: `cd app/client && bun run build`
- test_name: "frontend_build"
- test_purpose: "Validates the complete frontend build process including bundling, asset optimization, and production compilation"
## Report
- IMPORTANT: Return results exclusively as a JSON array based on the `Output Structure` section below.
- Sort the JSON array with failed tests (passed: false) at the top
- Include all tests in the output, both passed and failed
- The execution_command field should contain the exact command that can be run to reproduce the test
- This allows subsequent agents to quickly identify and resolve errors
### Output Structure
```json
[
{
"test_name": "string",
"passed": boolean,
"execution_command": "string",
"test_purpose": "string",
"error": "optional string"
},
...
]
```
### Example Output
```json
[
{
"test_name": "frontend_build",
"passed": false,
"execution_command": "cd app/client && bun run build",
"test_purpose": "Validates TypeScript compilation, module resolution, and production build process for the frontend application",
"error": "TS2345: Argument of type 'string' is not assignable to parameter of type 'number'"
},
{
"test_name": "all_backend_tests",
"passed": true,
"execution_command": "cd app/server && uv run pytest tests/ -v --tb=short",
"test_purpose": "Validates all backend functionality including file processing, SQL security, LLM integration, and API endpoints"
}
]
```