mirrors/archon
1
0
Fork 0
mirror of https://github.com/coleam00/Archon.git synced 2025-12-24 02:39:17 -05:00
Code Issues Packages Projects Releases Wiki Activity

sauce aow

Browse Source
This commit is contained in:
Rasmus Widing
2025-10-08 21:39:04 +03:00
parent 3f0815b686
commit 9a60d6ae89
84 changed files with 17939 additions and 2 deletions
Download Patch File Download Diff File Expand all files Collapse all files

56
.claude/commands/agent-work-orders/agent_workflow_plan.md Normal file
View File

@@ -0,0 +1,56 @@
# Agent Workflow: Plan
You are executing a planning workflow for a GitHub issue or project task.
## Your Task
1. Read the GitHub issue description (if provided via issue number)
2. Analyze the requirements thoroughly
3. Create a detailed implementation plan
4. Save the plan to `PRPs/specs/plan-{work_order_id}.md`
5. Create a git branch named `feat-wo-{work_order_id}`
6. Commit all changes to git with clear commit messages
## Branch Naming
Use format: `feat-wo-{work_order_id}`
Example: `feat-wo-a3c2f1e4`
## Commit Message Format
```
plan: Create implementation plan for work order
- Analyzed requirements
- Created detailed plan
- Documented approach
Work Order: {work_order_id}
```
## Deliverables
- Git branch created following naming convention
- `PRPs/specs/plan-{work_order_id}.md` file with detailed plan
- All changes committed to git
- Clear commit messages documenting the work
## Plan Structure
Your plan should include:
1. **Feature Description** - What is being built
2. **Problem Statement** - What problem does this solve
3. **Solution Statement** - How will we solve it
4. **Architecture** - Technical design decisions
5. **Implementation Plan** - Step-by-step tasks
6. **Testing Strategy** - How to verify it works
7. **Acceptance Criteria** - Definition of done
## Important Notes
- Always create a new branch for your work
- Commit frequently with descriptive messages
- Include the work order ID in branch name and commits
- Focus on creating a comprehensive, actionable plan

97
.claude/commands/agent-work-orders/bug.md Normal file
View File

@@ -0,0 +1,97 @@
# 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/**` - Contains the codebase client/server.
- `scripts/**` - Contains the scripts to start and stop the server + client.
- `adws/**` - Contains the AI Developer Workflow (ADW) scripts.
Ignore all other files in the codebase.
## Plan Format
```md
# Bug: <bug name>
## 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
- Summarize the work you've just done in a concise bullet point list.
- Include the full path to the plan file you created (e.g., `specs/issue-123-adw-abc123-sdlc_planner-fix-login-error.md`)

69
.claude/commands/agent-work-orders/chore.md Normal file
View File

@@ -0,0 +1,69 @@
# Chore Planning
Create a new plan to resolve the `Chore` using the exact specified markdown `Plan Format`. Follow the `Instructions` to create the plan use the `Relevant Files` to focus on the right files. Follow the `Report` section to properly report the results of your work.
## Variables
issue_number: $1
adw_id: $2
issue_json: $3
## Instructions
- IMPORTANT: You're writing a plan to resolve a chore based on the `Chore` that will add value to the application.
- IMPORTANT: The `Chore` describes the chore that will be resolved but remember we're not resolving the chore, we're creating the plan that will be used to resolve the chore based on the `Plan Format` below.
- You're writing a plan to resolve a chore, it should be simple but we need to be thorough and precise so we don't miss anything or waste time with any second round of changes.
- 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 chore (e.g., "update-readme", "fix-tests", "refactor-auth")
- Use the plan format below to create the plan.
- Research the codebase and put together a plan to accomplish the chore.
- IMPORTANT: Replace every <placeholder> in the `Plan Format` with the requested value. Add as much detail as needed to accomplish the chore.
- Use your reasoning model: THINK HARD about the plan and the steps to accomplish the chore.
- Respect requested files in the `Relevant Files` section.
- Start your research by reading the `README.md` file.
- `adws/*.py` contain astral uv single file python scripts. So if you want to run them use `uv run <script_name>`.
- When you finish creating the plan for the chore, follow the `Report` section to properly report the results of your work.
## Relevant Files
Focus on the following files:
- `README.md` - Contains the project overview and instructions.
- `app/**` - Contains the codebase client/server.
- `scripts/**` - Contains the scripts to start and stop the server + client.
- `adws/**` - Contains the AI Developer Workflow (ADW) scripts.
Ignore all other files in the codebase.
## Plan Format
```md
# Chore: <chore name>
## Chore Description
<describe the chore in detail>
## Relevant Files
Use these files to resolve the chore:
<find and list the files that are relevant to the chore describe why they are relevant in bullet points. If there are new files that need to be created to accomplish the chore, 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 accomplish the chore. Order matters, start with the foundational shared changes required to fix the chore then move on to the specific changes required to fix the chore. Your last step should be running the `Validation Commands` to validate the chore is complete with zero regressions.>
## Validation Commands
Execute every command to validate the chore is complete with zero regressions.
<list commands you'll use to validate with 100% confidence the chore is complete with zero regressions. every command must execute without errors so be specific about what you want to run to validate the chore is complete with zero regressions. Don't validate with curl commands.>
- `cd app/server && uv run pytest` - Run server tests to validate the chore is complete with zero regressions
## Notes
<optionally list any additional notes or context that are relevant to the chore that will be helpful to the developer>
```
## Chore
Extract the chore details from the `issue_json` variable (parse the JSON and use the title and body fields).
## Report
- Summarize the work you've just done in a concise bullet point list.
- Include the full path to the plan file you created (e.g., `specs/issue-7-adw-abc123-sdlc_planner-update-readme.md`)

39
.claude/commands/agent-work-orders/classify_adw.md Normal file
View File

@@ -0,0 +1,39 @@
# 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`, `/adw_test`, `/adw_build`, `/adw_plan_build`, `/adw_plan_build_test`)
- Look for ADW IDs (8-character alphanumeric strings, often after "adw_id:" or "ADW ID:" or similar)
- Return a JSON object with the extracted information
- If no ADW workflow is found, return empty JSON: `{}`
## Valid ADW Commands
- `/adw_plan` - Planning only
- `/adw_build` - Building only (requires adw_id)
- `/adw_test` - Testing only
- `/adw_plan_build` - Plan + Build
- `/adw_plan_build_test` - Plan + Build + Test
## Response Format
Respond ONLY with a JSON object in this format:
```json
{
"adw_slash_command": "/adw_plan",
"adw_id": "abc12345"
}
```
Fields:
- `adw_slash_command`: The ADW command found (include the slash)
- `adw_id`: The 8-character ADW ID if found
If only one field is found, include only that field.
If nothing is found, return: `{}`
## Text to Analyze
$ARGUMENTS

21
.claude/commands/agent-work-orders/classify_issue.md Normal file
View File

@@ -0,0 +1,21 @@
# 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 `0` if the issue isn't any of the above.
## Github Issue
$ARGUMENTS

33
.claude/commands/agent-work-orders/commit.md Normal file
View File

@@ -0,0 +1,33 @@
# Generate Git Commit
Based on the `Instructions` below, take the `Variables` follow the `Run` section to create a git commit with a properly formatted message. Then follow the `Report` section to report the results of your work.
## Variables
agent_name: $1
issue_class: $2
issue: $3
## Instructions
- Generate a concise commit message in the format: `<agent_name>: <issue_class>: <commit message>`
- The `<commit message>` should be:
- Present tense (e.g., "add", "fix", "update", not "added", "fixed", "updated")
- 50 characters or less
- Descriptive of the actual changes made
- No period at the end
- Examples:
- `sdlc_planner: feat: add user authentication module`
- `sdlc_implementor: bug: fix login validation error`
- `sdlc_planner: chore: update dependencies to latest versions`
- Extract context from the issue JSON to make the commit message relevant
## Run
1. Run `git diff HEAD` to understand what changes have been made
2. Run `git add -A` to stage all changes
3. Run `git commit -m "<generated_commit_message>"` to create the commit
## Report
Return ONLY the commit message that was used (no other text)

38
.claude/commands/agent-work-orders/e2e/test_basic_query.md Normal file
View File

@@ -0,0 +1,38 @@
# E2E Test: Basic Query Execution
Test basic query functionality in the Natural Language SQL Interface application.
## User Story
As a user
I want to query my data using natural language
So that I can access information without writing SQL
## Test Steps
1. Navigate to the `Application URL`
2. Take a screenshot of the initial state
3. **Verify** the page title is "Natural Language SQL Interface"
4. **Verify** core UI elements are present:
- Query input textbox
- Query button
- Upload Data button
- Available Tables section
5. Enter the query: "Show me all users from the users table"
6. Take a screenshot of the query input
7. Click the Query button
8. **Verify** the query results appear
9. **Verify** the SQL translation is displayed (should contain "SELECT * FROM users")
10. Take a screenshot of the SQL translation
11. **Verify** the results table contains data
12. Take a screenshot of the results
13. Click "Hide" button to close results
## Success Criteria
- Query input accepts text
- Query button triggers execution
- Results display correctly
- SQL translation is shown
- Hide button works
- 3 screenshots are taken

33
.claude/commands/agent-work-orders/e2e/test_complex_query.md Normal file
View File

@@ -0,0 +1,33 @@
# E2E Test: Complex Query with Filtering
Test complex query capabilities with filtering conditions.
## User Story
As a user
I want to query data using natural language with complex filtering conditions
So that I can retrieve specific subsets of data without needing to write SQL
## Test Steps
1. Navigate to the `Application URL`
2. Take a screenshot of the initial state
3. Clear the query input
4. Enter: "Show users older than 30 who live in cities starting with 'S'"
5. Take a screenshot of the query input
6. Click Query button
7. **Verify** results appear with filtered data
8. **Verify** the generated SQL contains WHERE clause
9. Take a screenshot of the SQL translation
10. Count the number of results returned
11. Take a screenshot of the filtered results
12. Click "Hide" button to close results
13. Take a screenshot of the final state
## Success Criteria
- Complex natural language is correctly interpreted
- SQL contains appropriate WHERE conditions
- Results are properly filtered
- No errors occur during execution
- Hide button works
- 5 screenshots are taken

30
.claude/commands/agent-work-orders/e2e/test_sql_injection.md Normal file
View File

@@ -0,0 +1,30 @@
# E2E Test: SQL Injection Protection
Test the application's protection against SQL injection attacks.
## User Story
As a user
I want to be protected from SQL injection attacks when using the query interface
So that my data remains secure and the database integrity is maintained
## Test Steps
1. Navigate to the `Application URL`
2. Take a screenshot of the initial state
3. Clear the query input
4. Enter: "DROP TABLE users;"
5. Take a screenshot of the malicious query input
6. Click Query button
7. **Verify** an error message appears containing "Security error" or similar
8. Take a screenshot of the security error
9. **Verify** the users table still exists in Available Tables section
10. Take a screenshot showing the tables are intact
## Success Criteria
- SQL injection attempt is blocked
- Appropriate security error message is displayed
- No damage to the database
- Tables remain intact
- Query input accepts the malicious text
- 4 screenshots are taken

120
.claude/commands/agent-work-orders/feature.md Normal file
View File

@@ -0,0 +1,120 @@
# Feature Planning
Create a new plan in PRPs/specs/\*.md to implement the `Feature` using the exact specified markdown `Plan Format`. Follow the `Instructions` to create the plan use the `Relevant Files` to focus on the right files.
## Instructions
- IMPORTANT: You're writing a plan to implement a net new feature based on the `Feature` that will add value to the application.
- IMPORTANT: The `Feature` describes the feature that will be implemented but remember we're not implementing a new feature, we're creating the plan that will be used to implement the feature based on the `Plan Format` below.
- Create the plan in the `PRPs/specs/*.md` file. Name it appropriately based on the `Feature`.
- Use the `Plan Format` below to create the plan.
- Research the codebase to understand existing patterns, architecture, and conventions before planning the feature.
- IMPORTANT: Replace every <placeholder> in the `Plan Format` with the requested value. Add as much detail as needed to implement the feature successfully.
- Use your reasoning model: THINK HARD about the feature requirements, design, and implementation approach.
- Follow existing patterns and conventions in the codebase. Don't reinvent the wheel.
- Design for extensibility and maintainability.
- If you need a new library, use `uv add` and be sure to report it in the `Notes` section of the `Plan Format`.
- Respect requested files in the `Relevant Files` section.
- Start your research by reading the `README.md` file.
- ultrathink about the research before you create the plan.
## 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.
Ignore all other files in the codebase.
## Plan Format
```md
# Feature: <feature name>
## Feature Description
<describe the feature in detail, including its purpose and value to users>
## User Story
As a <type of user>
I want to <action/goal>
So that <benefit/value>
## Problem Statement
<clearly define the specific problem or opportunity this feature addresses>
## Solution Statement
<describe the proposed solution approach and how it solves the problem>
## Relevant Files
Use these files to implement the feature:
<find and list the files that are relevant to the feature describe why they are relevant in bullet points. If there are new files that need to be created to implement the feature, list them in an h3 'New Files' section.>
## Implementation Plan
### Phase 1: Foundation
<describe the foundational work needed before implementing the main feature>
### Phase 2: Core Implementation
<describe the main implementation work for the feature>
### Phase 3: Integration
<describe how the feature will integrate with existing functionality>
## 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 implement the feature. Order matters, start with the foundational shared changes required then move on to the specific implementation. Include creating tests throughout the implementation process. Your last step should be running the `Validation Commands` to validate the feature works correctly with zero regressions.>
## Testing Strategy
### Unit Tests
<describe unit tests needed for the feature>
### Integration Tests
<describe integration tests needed for the feature>
### Edge Cases
<list edge cases that need to be tested>
## Acceptance Criteria
<list specific, measurable criteria that must be met for the feature to be considered complete>
## Validation Commands
Execute every command to validate the feature works correctly with zero regressions.
<list commands you'll use to validate with 100% confidence the feature is implemented correctly with zero regressions. every command must execute without errors so be specific about what you want to run to validate the feature works as expected. Include commands to test the feature end-to-end.>
- `cd app/server && uv run pytest` - Run server tests to validate the feature works with zero regressions
## Notes
<optionally list any additional notes, future considerations, or context that are relevant to the feature that will be helpful to the developer>
```
## Feature
$ARGUMENTS
## Report
- Summarize the work you've just done in a concise bullet point list.
- Include a path to the plan you created in the `PRPs/specs/*.md` file.

24
.claude/commands/agent-work-orders/find_plan_file.md Normal file
View File

@@ -0,0 +1,24 @@
# Find Plan File
Based on the variables and `Previous Step Output` below, follow the `Instructions` to find the path to the plan file that was just created.
## Variables
issue_number: $1
adw_id: $2
previous_output: $3
## Instructions
- The previous step created a plan file. Find the exact file path.
- The plan filename follows the pattern: `issue-{issue_number}-adw-{adw_id}-sdlc_planner-{descriptive-name}.md`
- You can use these approaches to find it:
- First, try: `ls specs/issue-{issue_number}-adw-{adw_id}-sdlc_planner-*.md`
- Check git status for new untracked files matching the pattern
- Use `find specs -name "issue-{issue_number}-adw-{adw_id}-sdlc_planner-*.md" -type f`
- Parse the previous output which should mention where the plan was saved
- Return ONLY the file path (e.g., "specs/issue-7-adw-abc123-sdlc_planner-update-readme.md") or "0" if not found.
- Do not include any explanation, just the path or "0" if not found.
## Previous Step Output
Use the `previous_output` variable content to help locate the file if it mentions the path.

36
.claude/commands/agent-work-orders/generate_branch_name.md Normal file
View File

@@ -0,0 +1,36 @@
# 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
Run `git checkout main` to switch to the main branch
Run `git pull` to pull the latest changes from the main branch
Run `git checkout -b <branch_name>` to create and switch to the new branch
## Report
After generating the branch name:
Return ONLY the branch name that was created (no other text)

16
.claude/commands/agent-work-orders/implement.md Normal file
View File

@@ -0,0 +1,16 @@
# Implement the following plan
Follow the `Instructions` to implement the `Plan` then `Report` the completed work.
## Instructions
- Read the plan, ultrathink about the plan and implement the plan.
## Plan
$ARGUMENTS
## Report
- Summarize the work you've just done in a concise bullet point list.
- Report the files and total lines changed with `git diff --stat`

12
.claude/commands/agent-work-orders/prime.md Normal file
View File

@@ -0,0 +1,12 @@
# Prime
> Execute the following sections to understand the codebase then summarize your understanding.
## Run
git ls-files
## Read
README.md
please read PRPs/PRD.md and core files in PRPs/specs

41
.claude/commands/agent-work-orders/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)

51
.claude/commands/agent-work-orders/resolve_failed_e2e_test.md Normal file
View File

@@ -0,0 +1,51 @@
# Resolve Failed E2E Test
Fix a specific failing E2E test using the provided failure details.
## Instructions
1. **Analyze the E2E Test Failure**
- Review the JSON data in the `Test Failure Input`, paying attention to:
- `test_name`: The name of the failing test
- `test_path`: The path to the test file (you will need this for re-execution)
- `error`: The specific error that occurred
- `screenshots`: Any captured screenshots showing the failure state
- Understand what the test is trying to validate from a user interaction perspective
2. **Understand Test Execution**
- Read `.claude/commands/test_e2e.md` to understand how E2E tests are executed
- Read the test file specified in the `test_path` field from the JSON
- Note the test steps, user story, and success criteria
3. **Reproduce the Failure**
- IMPORTANT: Use the `test_path` from the JSON to re-execute the specific E2E test
- Follow the execution pattern from `.claude/commands/test_e2e.md`
- Observe the browser behavior and confirm you can reproduce the exact failure
- Compare the error you see with the error reported in the JSON
4. **Fix the Issue**
- Based on your reproduction, identify the root cause
- Make minimal, targeted changes to resolve only this E2E test failure
- Consider common E2E issues:
- Element selector changes
- Timing issues (elements not ready)
- UI layout changes
- Application logic modifications
- Ensure the fix aligns with the user story and test purpose
5. **Validate the Fix**
- Re-run the same E2E test step by step using the `test_path` to confirm it now passes
- IMPORTANT: The test must complete successfully before considering it resolved
- Do NOT run other tests or the full test suite
- Focus only on fixing this specific E2E test
## Test Failure Input
$ARGUMENTS
## Report
Provide a concise summary of:
- Root cause identified (e.g., missing element, timing issue, incorrect selector)
- Specific fix applied
- Confirmation that the E2E test now passes after your fix

41
.claude/commands/agent-work-orders/resolve_failed_test.md Normal file
View File

@@ -0,0 +1,41 @@
# Resolve Failed Test
Fix a specific failing test using the provided failure details.
## Instructions
1. **Analyze the Test Failure**
- Review the test name, purpose, and error message from the `Test Failure Input`
- Understand what the test is trying to validate
- Identify the root cause from the error details
2. **Context Discovery**
- Check recent changes: `git diff origin/main --stat --name-only`
- If a relevant spec exists in `specs/*.md`, read it to understand requirements
- Focus only on files that could impact this specific test
3. **Reproduce the Failure**
- IMPORTANT: Use the `execution_command` provided in the test data
- Run it to see the full error output and stack trace
- Confirm you can reproduce the exact failure
4. **Fix the Issue**
- Make minimal, targeted changes to resolve only this test failure
- Ensure the fix aligns with the test purpose and any spec requirements
- Do not modify unrelated code or tests
5. **Validate the Fix**
- Re-run the same `execution_command` to confirm the test now passes
- Do NOT run other tests or the full test suite
- Focus only on fixing this specific test
## Test Failure Input
$ARGUMENTS
## Report
Provide a concise summary of:
- Root cause identified
- Specific fix applied
- Confirmation that the test now passes

115
.claude/commands/agent-work-orders/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"
}
]
```

64
.claude/commands/agent-work-orders/test_e2e.md Normal file
View File

@@ -0,0 +1,64 @@
# E2E Test Runner
Execute end-to-end (E2E) tests using Playwright browser automation (MCP Server). If any errors occur and assertions fail mark the test as failed and explain exactly what went wrong.
## Variables
adw_id: $1 if provided, otherwise generate a random 8 character hex string
agent_name: $2 if provided, otherwise use 'test_e2e'
e2e_test_file: $3
application_url: $4 if provided, otherwise use http://localhost:5173
## Instructions
- Read the `e2e_test_file`
- Digest the `User Story` to first understand what we're validating
- IMPORTANT: Execute the `Test Steps` detailed in the `e2e_test_file` using Playwright browser automation
- Review the `Success Criteria` and if any of them fail, mark the test as failed and explain exactly what went wrong
- Review the steps that say '**Verify**...' and if they fail, mark the test as failed and explain exactly what went wrong
- Capture screenshots as specified
- IMPORTANT: Return results in the format requested by the `Output Format`
- Initialize Playwright browser in headed mode for visibility
- Use the `application_url`
- Allow time for async operations and element visibility
- IMPORTANT: After taking each screenshot, save it to `Screenshot Directory` with descriptive names. Use absolute paths to move the files to the `Screenshot Directory` with the correct name.
- Capture and report any errors encountered
- Ultra think about the `Test Steps` and execute them in order
- If you encounter an error, mark the test as failed immediately and explain exactly what went wrong and on what step it occurred. For example: '(Step 1 ❌) Failed to find element with selector "query-input" on page "http://localhost:5173"'
- Use `pwd` or equivalent to get the absolute path to the codebase for writing and displaying the correct paths to the screenshots
## Setup
- IMPORTANT: Reset the database by running `scripts/reset_db.sh`
- IMPORTANT: Make sure the server and client are running on a background process before executing the test steps. Read `scripts/` and `README.md` for more information on how to start, stop and reset the server and client
## Screenshot Directory
<absolute path to codebase>/agents/<adw_id>/<agent_name>/img/<directory name based on test file name>/*.png
Each screenshot should be saved with a descriptive name that reflects what is being captured. The directory structure ensures that:
- Screenshots are organized by ADW ID (workflow run)
- They are stored under the specified agent name (e.g., e2e_test_runner_0, e2e_test_resolver_iter1_0)
- Each test has its own subdirectory based on the test file name (e.g., test_basic_query → basic_query/)
## Report
- Exclusively return the JSON output as specified in the test file
- Capture any unexpected errors
- IMPORTANT: Ensure all screenshots are saved in the `Screenshot Directory`
### Output Format
```json
{
"test_name": "Test Name Here",
"status": "passed|failed",
"screenshots": [
"<absolute path to codebase>/agents/<adw_id>/<agent_name>/img/<test name>/01_<descriptive name>.png",
"<absolute path to codebase>/agents/<adw_id>/<agent_name>/img/<test name>/02_<descriptive name>.png",
"<absolute path to codebase>/agents/<adw_id>/<agent_name>/img/<test name>/03_<descriptive name>.png"
],
"error": null
}
```

3
.claude/commands/agent-work-orders/tools.md Normal file
View File

@@ -0,0 +1,3 @@
# List Built-in Tools
List all core, built-in non-mcp development tools available to you. Display in bullet format. Use typescript function syntax with parameters.