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

refactor: simplify workflow to user-selectable 6-command architecture

Browse Source 
Simplifies the workflow orchestrator from hardcoded 11-step atomic operations
to user-selectable 6-command workflow with context passing.

Core changes:
- WorkflowStep enum: 11 steps → 6 commands (create-branch, planning, execute, commit, create-pr, prp-review)
- workflow_orchestrator.py: 367 lines → 200 lines with command stitching loop
- Remove workflow_type field, add selected_commands parameter
- Simplify agent names from 11 → 6 constants
- Remove test/review phase config flags (now optional commands)

Deletions:
- Remove test_workflow.py, review_workflow.py, workflow_phase_tracker.py
- Remove 32 old command files from .claude/commands
- Remove PRPs/specs and PRD files from version control
- Update .gitignore to exclude specs, features, and validation markdown files

Breaking changes:
- AgentWorkOrder no longer has workflow_type field
- CreateAgentWorkOrderRequest now uses selected_commands instead of workflow_type
- WorkflowStep enum values incompatible with old step history

56 files changed, 625 insertions(+), 15,007 deletions(-)
This commit is contained in:
Rasmus Widing
2025-10-16 19:11:54 +03:00
parent 1c0020946b
commit fd81505908
70 changed files with 2432 additions and 15034 deletions
Download Patch File Download Diff File Expand all files Collapse all files

26
python/.claude/commands/agent-work-orders/branch_generator.md
View File

@@ -1,26 +0,0 @@
# Generate Git Branch
Create a git branch following the standard naming convention.
## Variables
issue_class: $1
issue_number: $2
work_order_id: $3
issue_json: $4
## Instructions
- Generate branch name: `<class>-issue-<num>-wo-<id>-<desc>`
- <class>: bug, feat, or chore (remove slash from issue_class)
- <desc>: 3-6 words, lowercase, hyphens
- Extract issue details from issue_json
## Run
1. `git checkout main`
2. `git pull`
3. `git checkout -b <branch_name>`
## Output
Return ONLY the branch name created

36
python/.claude/commands/agent-work-orders/classifier.md
View File

@@ -1,36 +0,0 @@
# Issue Classification
Classify the GitHub issue into the appropriate category.
## Instructions
- Read the issue title and body carefully
- Determine if this is a bug, feature, or chore
- Respond ONLY with one of: /bug, /feature, /chore
- If unclear, default to /feature
## Classification Rules
**Bug**: Fixing broken functionality
- Issue describes something not working as expected
- Error messages, crashes, incorrect behavior
- Keywords: "error", "broken", "not working", "fails"
**Feature**: New functionality or enhancement
- Issue requests new capability
- Adds value to users
- Keywords: "add", "implement", "support", "enable"
**Chore**: Maintenance, refactoring, documentation
- No user-facing changes
- Code cleanup, dependency updates, docs
- Keywords: "refactor", "update", "clean", "docs"
## Input
GitHub Issue JSON:
$ARGUMENTS
## Output
Return ONLY one of: /bug, /feature, /chore

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

@@ -0,0 +1,81 @@
# Create Git Commit
Create an atomic git commit with a properly formatted commit message following best practices for the uncommited changes or these specific files if specified.
Specific files (skip if not specified):
- File 1: $1
- File 2: $2
- File 3: $3
- File 4: $4
- File 5: $5
## Instructions
**Commit Message Format:**
- Use conventional commits: `<type>: <description>`
- Types: `feat`, `fix`, `docs`, `style`, `refactor`, `test`, `chore`
- Present tense (e.g., "add", "fix", "update", not "added", "fixed", "updated")
- 50 characters or less for the subject line
- Lowercase subject line
- No period at the end
- Be specific and descriptive
**Examples:**
- `feat: add web search tool with structured logging`
- `fix: resolve type errors in middleware`
- `test: add unit tests for config module`
- `docs: update CLAUDE.md with testing guidelines`
- `refactor: simplify logging configuration`
- `chore: update dependencies`
**Atomic Commits:**
- One logical change per commit
- If you've made multiple unrelated changes, consider splitting into separate commits
- Commit should be self-contained and not break the build
**IMPORTANT**
- NEVER mention claude code, anthropic, co authored by or anything similar in the commit messages
## Run
1. Review changes: `git diff HEAD`
2. Check status: `git status`
3. Stage changes: `git add -A`
4. Create commit: `git commit -m "<type>: <description>"`
5. Push to remote: `git push -u origin $(git branch --show-current)`
6. Verify push: `git log origin/$(git branch --show-current) -1 --oneline`
## Report
Output in this format (plain text, no markdown):
Commit: <commit-hash>
Branch: <branch-name>
Message: <commit-message>
Pushed: Yes (or No if push failed)
Files: <number> files changed
Then list the files:
- <file1>
- <file2>
- ...
**Example:**
```
Commit: a3c2f1e
Branch: feat/add-user-auth
Message: feat: add user authentication system
Pushed: Yes
Files: 5 files changed
- src/auth/login.py
- src/auth/middleware.py
- tests/auth/test_login.py
- CLAUDE.md
- requirements.txt
```

26
python/.claude/commands/agent-work-orders/committer.md
View File

@@ -1,26 +0,0 @@
# Create Git Commit
Create a git commit with proper formatting.
## Variables
agent_name: $1
issue_class: $2
issue_json: $3
## Instructions
- Format: `<agent>: <class>: <message>`
- Message: Present tense, 50 chars max, descriptive
- Examples:
- `planner: feat: add user authentication`
- `implementor: bug: fix login validation`
## Run
1. `git diff HEAD` - Review changes
2. `git add -A` - Stage all
3. `git commit -m "<message>"`
## Output
Return ONLY the commit message used

104
python/.claude/commands/agent-work-orders/create-branch.md Normal file
View File

@@ -0,0 +1,104 @@
# Create Git Branch
Generate a conventional branch name based on user request and create a new git branch.
## Variables
User request: $1
## Instructions
**Step 1: Check Current Branch**
- Check current branch: `git branch --show-current`
- Check if on main/master:
```bash
CURRENT_BRANCH=$(git branch --show-current)
if [[ "$CURRENT_BRANCH" != "main" && "$CURRENT_BRANCH" != "master" ]]; then
echo "Warning: Currently on branch '$CURRENT_BRANCH', not main/master"
echo "Proceeding with branch creation from current branch"
fi
```
- Note: We proceed regardless, but log the warning
**Step 2: Generate Branch Name**
Use conventional branch naming:
**Prefixes:**
- `feat/` - New feature or enhancement
- `fix/` - Bug fix
- `chore/` - Maintenance tasks (dependencies, configs, etc.)
- `docs/` - Documentation only changes
- `refactor/` - Code refactoring (no functionality change)
- `test/` - Adding or updating tests
- `perf/` - Performance improvements
**Naming Rules:**
- Use kebab-case (lowercase with hyphens)
- Be descriptive but concise (max 50 characters)
- Remove special characters except hyphens
- No spaces, use hyphens instead
**Examples:**
- "Add user authentication system" → `feat/add-user-auth`
- "Fix login redirect bug" → `fix/login-redirect`
- "Update README documentation" → `docs/update-readme`
- "Refactor database queries" → `refactor/database-queries`
- "Add unit tests for API" → `test/api-unit-tests`
**Branch Name Generation Logic:**
1. Analyze user request to determine type (feature/fix/chore/docs/refactor/test/perf)
2. Extract key action and subject
3. Convert to kebab-case
4. Truncate if needed to keep under 50 chars
5. Validate name is descriptive and follows conventions
**Step 3: Check Branch Exists**
- Check if branch name already exists:
```bash
if git show-ref --verify --quiet refs/heads/<branch-name>; then
echo "Branch <branch-name> already exists"
# Append version suffix
COUNTER=2
while git show-ref --verify --quiet refs/heads/<branch-name>-v$COUNTER; do
COUNTER=$((COUNTER + 1))
done
BRANCH_NAME="<branch-name>-v$COUNTER"
fi
```
- If exists, append `-v2`, `-v3`, etc. until unique
**Step 4: Create and Checkout Branch**
- Create and checkout new branch: `git checkout -b <branch-name>`
- Verify creation: `git branch --show-current`
- Ensure output matches expected branch name
**Step 5: Verify Branch State**
- Confirm branch created: `git branch --list <branch-name>`
- Confirm currently on branch: `[ "$(git branch --show-current)" = "<branch-name>" ]`
- Check remote tracking: `git rev-parse --abbrev-ref --symbolic-full-name @{u} 2>/dev/null || echo "No upstream set"`
**Important Notes:**
- NEVER mention Claude Code, Anthropic, AI, or co-authoring in any output
- Branch should be created locally only (no push yet)
- Branch will be pushed later by commit.md command
- If user request is unclear, prefer `feat/` prefix as default
## Report
Output ONLY the branch name (no markdown, no explanations, no quotes):
<branch-name>
**Example outputs:**
```
feat/add-user-auth
fix/login-redirect-issue
docs/update-api-documentation
refactor/simplify-middleware
```

201
python/.claude/commands/agent-work-orders/create-pr.md Normal file
View File

@@ -0,0 +1,201 @@
# Create GitHub Pull Request
Create a GitHub pull request for the current branch with auto-generated description.
## Variables
- Branch name: $1
- PRP file path: $2 (optional - may be empty)
## Instructions
**Prerequisites Check:**
1. Verify gh CLI is authenticated:
```bash
gh auth status || {
echo "Error: gh CLI not authenticated. Run: gh auth login"
exit 1
}
```
2. Verify we're in a git repository:
```bash
git rev-parse --git-dir >/dev/null 2>&1 || {
echo "Error: Not in a git repository"
exit 1
}
```
3. Verify changes are pushed to remote:
```bash
BRANCH=$(git branch --show-current)
git rev-parse --verify origin/$BRANCH >/dev/null 2>&1 || {
echo "Error: Branch '$BRANCH' not pushed to remote. Run: git push -u origin $BRANCH"
exit 1
}
```
**Step 1: Gather Information**
1. Get current branch name:
```bash
BRANCH=$(git branch --show-current)
```
2. Get default base branch (usually main or master):
```bash
BASE=$(git remote show origin | grep 'HEAD branch' | cut -d' ' -f5)
# Fallback to main if detection fails
[ -z "$BASE" ] && BASE="main"
```
3. Get repository info:
```bash
REPO=$(gh repo view --json nameWithOwner -q .nameWithOwner)
```
**Step 2: Generate PR Title**
Convert branch name to conventional commit format:
**Rules:**
- `feat/add-user-auth` → `feat: add user authentication`
- `fix/login-bug` → `fix: resolve login bug`
- `docs/update-readme` → `docs: update readme`
- Capitalize first letter after prefix
- Remove hyphens, replace with spaces
- Keep concise (under 72 characters)
**Step 3: Find PR Template**
Look for PR template in these locations (in order):
1. `.github/pull_request_template.md`
2. `.github/PULL_REQUEST_TEMPLATE.md`
3. `.github/PULL_REQUEST_TEMPLATE/pull_request_template.md`
4. `docs/pull_request_template.md`
```bash
PR_TEMPLATE=""
if [ -f ".github/pull_request_template.md" ]; then
PR_TEMPLATE=".github/pull_request_template.md"
elif [ -f ".github/PULL_REQUEST_TEMPLATE.md" ]; then
PR_TEMPLATE=".github/PULL_REQUEST_TEMPLATE.md"
elif [ -f ".github/PULL_REQUEST_TEMPLATE/pull_request_template.md" ]; then
PR_TEMPLATE=".github/PULL_REQUEST_TEMPLATE/pull_request_template.md"
elif [ -f "docs/pull_request_template.md" ]; then
PR_TEMPLATE="docs/pull_request_template.md"
fi
```
**Step 4: Generate PR Body**
**If PR template exists:**
- Read template content
- Fill in placeholders if present
- If PRP file provided: Extract summary and insert into template
**If no PR template (use default):**
```markdown
## Summary
[Brief description of what this PR does]
## Changes
[Bullet list of key changes from git log]
## Implementation Details
[Reference PRP file if provided, otherwise summarize commits]
## Testing
- [ ] All existing tests pass
- [ ] New tests added (if applicable)
- [ ] Manual testing completed
## Related Issues
Closes #[issue number if applicable]
```
**Auto-fill logic:**
1. **Summary section:**
- If PRP file exists: Extract "Feature Description" section
- Otherwise: Use first commit message body
- Fallback: Summarize changes from `git diff --stat`
2. **Changes section:**
- Get commit messages: `git log $BASE..$BRANCH --pretty=format:"- %s"`
- List modified files: `git diff --name-only $BASE...$BRANCH`
- Format as bullet points
3. **Implementation Details:**
- If PRP file exists: Link to it with `See: $PRP_FILE_PATH`
- Extract key technical details from PRP "Solution Statement"
- Otherwise: Summarize from commit messages
4. **Testing section:**
- Check if new test files were added: `git diff --name-only $BASE...$BRANCH | grep test`
- Auto-check test boxes if tests exist
- Include validation results from execute.md if available
**Step 5: Create Pull Request**
```bash
gh pr create \
--title "$PR_TITLE" \
--body "$PR_BODY" \
--base "$BASE" \
--head "$BRANCH" \
--web
```
**Flags:**
- `--web`: Open PR in browser after creation
- If `--web` not desired, remove it
**Step 6: Capture PR URL**
```bash
PR_URL=$(gh pr view --json url -q .url)
```
**Step 7: Link to Issues (if applicable)**
If PRP file or commits mention issue numbers (#123), link them:
```bash
# Extract issue numbers from commits
ISSUES=$(git log $BASE..$BRANCH --pretty=format:"%s %b" | grep -oP '#\K\d+' | sort -u)
# Link issues to PR
for ISSUE in $ISSUES; do
gh pr comment $PR_URL --body "Relates to #$ISSUE"
done
```
**Important Notes:**
- NEVER mention Claude Code, Anthropic, AI, or co-authoring in PR
- PR title and body should be professional and clear
- Include all relevant context for reviewers
- Link to PRP file in repo if available
- Auto-check completed checkboxes in template
## Report
Output ONLY the PR URL (no markdown, no explanations, no quotes):
https://github.com/owner/repo/pull/123
**Example output:**
```
https://github.com/coleam00/archon/pull/456
```
## Error Handling
If PR creation fails:
- Check if PR already exists for branch: `gh pr list --head $BRANCH`
- If exists: Return existing PR URL
- If other error: Output error message with context

27
python/.claude/commands/agent-work-orders/execute.md Normal file
View File

@@ -0,0 +1,27 @@
# Execute PRP Plan
Implement a feature plan from the PRPs directory by following its Step by Step Tasks section.
## Variables
Plan file: $ARGUMENTS
## Instructions
- Read the entire plan file carefully
- Execute **every step** in the "Step by Step Tasks" section in order, top to bottom
- Follow the "Testing Strategy" to create proper unit and integration tests
- Complete all "Validation Commands" at the end
- Ensure all linters pass and all tests pass before finishing
- Follow CLAUDE.md guidelines for type safety, logging, and docstrings
## When done
- Move the PRP file to the completed directory in PRPs/features/completed
## Report
- Summarize completed work in a concise bullet point list
- Show files and lines changed: `git diff --stat`
- Confirm all validation commands passed
- Note any deviations from the plan (if any)

21
python/.claude/commands/agent-work-orders/implementor.md
View File

@@ -1,21 +0,0 @@
# Implementation
Implement the plan from the specified plan file.
## Variables
plan_file: $1
## Instructions
- Read the plan file carefully
- Execute every step in order
- Follow existing code patterns and conventions
- Create/modify files as specified in the plan
- Run validation commands from the plan
- Do NOT create git commits or branches (separate steps)
## Output
- Summarize work completed
- List files changed
- Report test results if any

176
python/.claude/commands/agent-work-orders/noqa.md Normal file
View File

@@ -0,0 +1,176 @@
# NOQA Analysis and Resolution
Find all noqa/type:ignore comments in the codebase, investigate why they exist, and provide recommendations for resolution or justification.
## Instructions
**Step 1: Find all NOQA comments**
- Use Grep tool to find all noqa comments: pattern `noqa|type:\s*ignore`
- Use output_mode "content" with line numbers (-n flag)
- Search across all Python files (type: "py")
- Document total count of noqa comments found
**Step 2: For EACH noqa comment (repeat this process):**
- Read the file containing the noqa comment with sufficient context (at least 10 lines before and after)
- Identify the specific linting rule or type error being suppressed
- Understand the code's purpose and why the suppression was added
- Investigate if the suppression is still necessary or can be resolved
**Step 3: Investigation checklist for each noqa:**
- What specific error/warning is being suppressed? (e.g., `type: ignore[arg-type]`, `noqa: F401`)
- Why was the suppression necessary? (legacy code, false positive, legitimate limitation, technical debt)
- Can the underlying issue be fixed? (refactor code, update types, improve imports)
- What would it take to remove the suppression? (effort estimate, breaking changes, architectural changes)
- Is the suppression justified long-term? (external library limitation, Python limitation, intentional design)
**Step 4: Research solutions:**
- Check if newer versions of tools (mypy, ruff) handle the case better
- Look for alternative code patterns that avoid the suppression
- Consider if type stubs or Protocol definitions could help
- Evaluate if refactoring would be worthwhile
## Report Format
Create a markdown report file (create the reports directory if not created yet): `PRPs/reports/noqa-analysis-{YYYY-MM-DD}.md`
Use this structure for the report:
````markdown
# NOQA Analysis Report
**Generated:** {date}
**Total NOQA comments found:** {count}
---
## Summary
- Total suppressions: {count}
- Can be removed: {count}
- Should remain: {count}
- Requires investigation: {count}
---
## Detailed Analysis
### 1. {File path}:{line number}
**Location:** `{file_path}:{line_number}`
**Suppression:** `{noqa comment or type: ignore}`
**Code context:**
```python
{relevant code snippet}
```
````
**Why it exists:**
{explanation of why the suppression was added}
**Options to resolve:**
1. {Option 1: description}
- Effort: {Low/Medium/High}
- Breaking: {Yes/No}
- Impact: {description}
2. {Option 2: description}
- Effort: {Low/Medium/High}
- Breaking: {Yes/No}
- Impact: {description}
**Tradeoffs:**
- {Tradeoff 1}
- {Tradeoff 2}
**Recommendation:** {Remove | Keep | Refactor}
{Justification for recommendation}
---
{Repeat for each noqa comment}
````
## Example Analysis Entry
```markdown
### 1. src/shared/config.py:45
**Location:** `src/shared/config.py:45`
**Suppression:** `# type: ignore[assignment]`
**Code context:**
```python
@property
def openai_api_key(self) -> str:
key = os.getenv("OPENAI_API_KEY")
if not key:
raise ValueError("OPENAI_API_KEY not set")
return key # type: ignore[assignment]
````
**Why it exists:**
MyPy cannot infer that the ValueError prevents None from being returned, so it thinks the return type could be `str | None`.
**Options to resolve:**
1. Use assert to help mypy narrow the type
- Effort: Low
- Breaking: No
- Impact: Cleaner code, removes suppression
2. Add explicit cast with typing.cast()
- Effort: Low
- Breaking: No
- Impact: More verbose but type-safe
3. Refactor to use separate validation method
- Effort: Medium
- Breaking: No
- Impact: Better separation of concerns
**Tradeoffs:**
- Option 1 (assert) is cleanest but asserts can be disabled with -O flag
- Option 2 (cast) is most explicit but adds import and verbosity
- Option 3 is most robust but requires more refactoring
**Recommendation:** Remove (use Option 1)
Replace the type:ignore with an assert statement after the if check. This helps mypy understand the control flow while maintaining runtime safety. The assert will never fail in practice since the ValueError is raised first.
**Implementation:**
```python
@property
def openai_api_key(self) -> str:
key = os.getenv("OPENAI_API_KEY")
if not key:
raise ValueError("OPENAI_API_KEY not set")
assert key is not None # Help mypy understand control flow
return key
```
```
## Report
After completing the analysis:
- Output the path to the generated report file
- Summarize findings:
- Total suppressions found
- How many can be removed immediately (low effort)
- How many should remain (justified)
- How many need deeper investigation or refactoring
- Highlight any quick wins (suppressions that can be removed with minimal effort)
```

23
python/.claude/commands/agent-work-orders/plan_finder.md
View File

@@ -1,23 +0,0 @@
# Find Plan File
Locate the plan file created in the previous step.
## Variables
issue_number: $1
work_order_id: $2
previous_output: $3
## Instructions
- The previous step created a plan file
- Find the exact file path
- Pattern: `specs/issue-{issue_number}-wo-{work_order_id}-planner-*.md`
- Try these approaches:
1. Parse previous_output for file path mention
2. Run: `ls specs/issue-{issue_number}-wo-{work_order_id}-planner-*.md`
3. Run: `find specs -name "issue-{issue_number}-wo-{work_order_id}-planner-*.md"`
## Output
Return ONLY the file path (e.g., "specs/issue-7-wo-abc123-planner-fix-auth.md")
Return "0" if not found

71
python/.claude/commands/agent-work-orders/planner_bug.md
View File

@@ -1,71 +0,0 @@
# Bug Planning
Create a new plan to resolve the Bug using the exact specified markdown Plan Format.
## Variables
issue_number: $1
work_order_id: $2
issue_json: $3
## Instructions
- IMPORTANT: You're writing a plan to resolve a bug that will add value to the application.
- IMPORTANT: The Bug describes the bug that will be resolved but we're not resolving it, we're creating the plan.
- 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}-wo-{work_order_id}-planner-{descriptive-name}.md`
- Replace `{descriptive-name}` with a short name based on the bug (e.g., "fix-login-error", "resolve-timeout")
- 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.
- 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.
- If you need a new library, use `uv add` and report it in the Notes section.
- Start your research by reading the README.md file.
## 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 relevant to the bug with bullet points describing why. If new files need to be created, 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. Order matters, start with foundational shared changes then move on to specific changes. Include tests that will validate the bug is fixed. Your last step should be running the Validation Commands.>
## 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. Every command must execute without errors. Include commands to reproduce the bug before and after the fix.>
## Notes
<optionally list any additional notes or context relevant to the bug>
```
## 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-wo-abc123-planner-fix-login-error.md`)

56
python/.claude/commands/agent-work-orders/planner_chore.md
View File

@@ -1,56 +0,0 @@
# Chore Planning
Create a new plan to resolve the Chore using the exact specified markdown Plan Format.
## Variables
issue_number: $1
work_order_id: $2
issue_json: $3
## Instructions
- IMPORTANT: You're writing a plan to resolve a chore that will add value to the application.
- IMPORTANT: The Chore describes the chore that will be resolved but we're not resolving it, we're creating the plan.
- You're writing a plan to resolve a chore, it should be simple but thorough and precise so we don't miss anything.
- Create the plan in the `specs/` directory with filename: `issue-{issue_number}-wo-{work_order_id}-planner-{descriptive-name}.md`
- Replace `{descriptive-name}` with a short name based on the chore (e.g., "update-readme", "fix-tests")
- 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.
- Use your reasoning model: THINK HARD about the plan and the steps to accomplish the chore.
- Start your research by reading the README.md file.
## 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 relevant to the chore with bullet points describing why. If new files need to be created, 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. Order matters, start with foundational shared changes then move on to specific changes. Your last step should be running the Validation Commands.>
## 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. Every command must execute without errors.>
## Notes
<optionally list any additional notes or context relevant to the chore>
```
## 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-wo-abc123-planner-update-readme.md`)

111
python/.claude/commands/agent-work-orders/planner_feature.md
View File

@@ -1,111 +0,0 @@
# Feature Planning
Create a new plan in specs/*.md to implement the Feature using the exact specified markdown Plan Format.
## Variables
issue_number: $1
work_order_id: $2
issue_json: $3
## Instructions
- IMPORTANT: You're writing a plan to implement a net new feature that will add value to the application.
- IMPORTANT: The Feature describes the feature that will be implemented but remember we're not implementing it, we're creating the plan.
- Create the plan in the `specs/` directory with filename: `issue-{issue_number}-wo-{work_order_id}-planner-{descriptive-name}.md`
- Replace `{descriptive-name}` with a short name based on the feature (e.g., "add-auth", "api-endpoints")
- Use the Plan Format below to create the plan.
- Research the codebase to understand existing patterns, architecture, and conventions before planning.
- IMPORTANT: Replace every <placeholder> in the Plan Format with the requested value.
- Use your reasoning model: THINK HARD about the feature requirements, design, and implementation approach.
- Follow existing patterns and conventions in the codebase.
- Design for extensibility and maintainability.
- If you need a new library, use `uv add` and report it in the Notes section.
- Start your research by reading the README.md file.
- ultrathink about the research before you create the plan.
## 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 relevant to the feature with bullet points describing why. If new files need to be created, 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. Order matters, start with foundational shared changes required then move on to specific implementation. Include creating tests throughout. Your last step should be running the Validation Commands.>
## 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. Every command must execute without errors.>
## Notes
<optionally list any additional notes, future considerations, or context relevant to the feature>
```
## Feature
Extract the feature 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-wo-abc123-planner-add-auth.md`)

176
python/.claude/commands/agent-work-orders/planning.md Normal file
View File

@@ -0,0 +1,176 @@
# Feature Planning
Create a new plan to implement the `PRP` using the exact specified markdown `PRP Format`. Follow the `Instructions` to create the plan use the `Relevant Files` to focus on the right files.
## Variables
FEATURE $1 $2
## 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 `PRP Format` below.
- Create the plan in the `PRPs/features/` directory with filename: `{descriptive-name}.md`
- Replace `{descriptive-name}` with a short, descriptive name based on the feature (e.g., "add-auth-system", "implement-search", "create-dashboard")
- Use the `PRP Format` below to create the plan.
- Deeply research the codebase to understand existing patterns, architecture, and conventions before planning the feature.
- If no patterns are established or are unclear ask the user for clarifications while providing best recommendations and options
- IMPORTANT: Replace every <placeholder> in the `PRP 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.
- Deeply do web research to understand the latest trends and technologies in the field.
- Figure out latest best practices and library documentation.
- Include links to relevant resources and documentation with anchor tags for easy navigation.
- If you need a new library, use `uv add <package>` and report it in the `Notes` section.
- Read `CLAUDE.md` for project principles, logging rules, testing requirements, and docstring style.
- All code MUST have type annotations (strict mypy enforcement).
- Use Google-style docstrings for all functions, classes, and modules.
- Every new file in `src/` MUST have a corresponding test file in `tests/`.
- Respect requested files in the `Relevant Files` section.
## Relevant Files
Focus on the following files and vertical slice structure:
**Core Files:**
- `CLAUDE.md` - Project instructions, logging rules, testing requirements, docstring style
app/backend core files
app/frontend core files
## PRP 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. inlcude line numbers for the relevant sections>
## Relevant research docstring
Use these documentation files and links to help with understanding the technology to use:
- [Documentation Link 1](https://example.com/doc1)
- [Anchor tag]
- [Short summary]
- [Documentation Link 2](https://example.com/doc2)
- [Anchor tag]
- [Short summary]
## 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:
1. Start with foundational shared changes (schemas, types)
2. Implement core functionality with proper logging
3. Create corresponding test files (unit tests mirror src/ structure)
4. Add integration tests if feature interacts with multiple components
5. Verify linters pass: `uv run ruff check src/ && uv run mypy src/`
6. Ensure all tests pass: `uv run pytest tests/`
7. Your last step should be running the `Validation Commands`>
<For tool implementations:
- Define Pydantic schemas in `schemas.py`
- Implement tool with structured logging and type hints
- Register tool with Pydantic AI agent
- Create unit tests in `tests/tools/<name>/test_<module>.py`
- Add integration test in `tests/integration/` if needed>
## Testing Strategy
See `CLAUDE.md` for complete testing requirements. Every file in `src/` must have a corresponding test file in `tests/`.
### Unit Tests
<describe unit tests needed for the feature. Mark with @pytest.mark.unit. Test individual components in isolation.>
### Integration Tests
<if the feature interacts with multiple components, describe integration tests needed. Mark with @pytest.mark.integration. Place in tests/integration/ when testing full application stack.>
### 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. Include (example for BE Biome and TS checks are used for FE):
- Linting: `uv run ruff check src/`
- Type checking: `uv run mypy src/`
- Unit tests: `uv run pytest tests/ -m unit -v`
- Integration tests: `uv run pytest tests/ -m integration -v` (if applicable)
- Full test suite: `uv run pytest tests/ -v`
- Manual API testing if needed (curl commands, test requests)>
**Required validation commands:**
- `uv run ruff check src/` - Lint check must pass
- `uv run mypy src/` - Type check must pass
- `uv run pytest tests/ -v` - All tests must pass with zero regressions
**Run server and test core endpoints:**
- Start server: @.claude/start-server
- Test endpoints with curl (at minimum: health check, main functionality)
- Verify structured logs show proper correlation IDs and context
- Stop server after validation
## Notes
<optionally list any additional notes, future considerations, or context that are relevant to the feature that will be helpful to the developer>
```
## Feature
Extract the feature 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., `PRPs/features/add-auth-system.md`)

27
python/.claude/commands/agent-work-orders/pr_creator.md
View File

@@ -1,27 +0,0 @@
# Create Pull Request
Create a GitHub pull request for the changes.
## Variables
branch_name: $1
issue_json: $2
plan_file: $3
work_order_id: $4
## Instructions
- Title format: `<type>: #<num> - <title>`
- Body includes:
- Summary from issue
- Link to plan_file
- Closes #<number>
- Work Order: {work_order_id}
## Run
1. `git push -u origin <branch_name>`
2. `gh pr create --title "<title>" --body "<body>" --base main`
## Output
Return ONLY the PR URL

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

@@ -0,0 +1,28 @@
# Prime
Execute the following sections to understand the codebase before starting new work, then summarize your understanding.
## Run
- List all tracked files: `git ls-files`
- Show project structure: `tree -I '.venv|__pycache__|*.pyc|.pytest_cache|.mypy_cache|.ruff_cache' -L 3`
## Read
- `CLAUDE.md` - Core project instructions, principles, logging rules, testing requirements
- `python/src/agent_work_orders` - Project overview and setup (if exists)
- Identify core files in the agent work orders directory to understand what we are woerking on and its intent
## Report
Provide a concise summary of:
1. **Project Purpose**: What this application does
2. **Architecture**: Key patterns (vertical slice, FastAPI + Pydantic AI)
3. **Core Principles**: TYPE SAFETY, KISS, YAGNI
4. **Tech Stack**: Main dependencies and tools
5. **Key Requirements**: Logging, testing, type annotations
6. **Current State**: What's implemented
Keep the summary brief (5-10 bullet points) and focused on what you need to know to contribute effectively.

89
python/.claude/commands/agent-work-orders/prp-review.md Normal file
View File

@@ -0,0 +1,89 @@
# Code Review
Review implemented work against a PRP specification to ensure code quality, correctness, and adherence to project standards.
## Variables
Plan file: $ARGUMENTS (e.g., `PRPs/features/add-web-search.md`)
## Instructions
**Understand the Changes:**
- Check current branch: `git branch`
- Review changes: `git diff origin/main` (or `git diff HEAD` if not on a branch)
- Read the PRP plan file to understand requirements
**Code Quality Review:**
- **Type Safety**: Verify all functions have type annotations, mypy passes
- **Logging**: Check structured logging is used correctly (event names, context, exception handling)
- **Docstrings**: Ensure Google-style docstrings on all functions/classes
- **Testing**: Verify unit tests exist for all new files, integration tests if needed
- **Architecture**: Confirm vertical slice structure is followed
- **CLAUDE.md Compliance**: Check adherence to core principles (KISS, YAGNI, TYPE SAFETY)
**Validation Ruff for BE and Biome for FE:**
- Run linters: `uv run ruff check src/ && uv run mypy src/`
- Run tests: `uv run pytest tests/ -v`
- Start server and test endpoints with curl (if applicable)
- Verify structured logs show proper correlation IDs and context
**Issue Severity:**
- `blocker` - Must fix before merge (breaks build, missing tests, type errors, security issues)
- `major` - Should fix (missing logging, incomplete docstrings, poor patterns)
- `minor` - Nice to have (style improvements, optimization opportunities)
## Report
Return ONLY valid JSON (no markdown, no explanations) save to [report-#.json] in prps/reports directory create the directory if it doesn't exist. Output will be parsed with JSON.parse().
### Output Structure
```json
{
"success": "boolean - true if NO BLOCKER issues, false if BLOCKER issues exist",
"review_summary": "string - 2-4 sentences: what was built, does it match spec, quality assessment",
"review_issues": [
{
"issue_number": "number - issue index",
"file_path": "string - file with the issue (if applicable)",
"issue_description": "string - what's wrong",
"issue_resolution": "string - how to fix it",
"severity": "string - blocker|major|minor"
}
],
"validation_results": {
"linting_passed": "boolean",
"type_checking_passed": "boolean",
"tests_passed": "boolean",
"api_endpoints_tested": "boolean - true if endpoints were tested with curl"
}
}
```
## Example Success Review
```json
{
"success": true,
"review_summary": "The web search tool has been implemented with proper type annotations, structured logging, and comprehensive tests. The implementation follows the vertical slice architecture and matches all spec requirements. Code quality is high with proper error handling and documentation.",
"review_issues": [
{
"issue_number": 1,
"file_path": "src/tools/web_search/tool.py",
"issue_description": "Missing debug log for API response",
"issue_resolution": "Add logger.debug with response metadata",
"severity": "minor"
}
],
"validation_results": {
"linting_passed": true,
"type_checking_passed": true,
"tests_passed": true,
"api_endpoints_tested": true
}
}
```

33
python/.claude/commands/agent-work-orders/start-server.md Normal file
View File

@@ -0,0 +1,33 @@
# Start Servers
Start both the FastAPI backend and React frontend development servers with hot reload.
## Run
### Run in the background with bash tool
- Ensure you are in the right PWD
- Use the Bash tool to run the servers in the background so you can read the shell outputs
- IMPORTANT: run `git ls-files` first so you know where directories are located before you start
### Backend Server (FastAPI)
- Navigate to backend: `cd app/backend`
- Start server in background: `uv sync && uv run python run_api.py`
- Wait 2-3 seconds for startup
- Test health endpoint: `curl http://localhost:8000/health`
- Test products endpoint: `curl http://localhost:8000/api/products`
### Frontend Server (Bun + React)
- Navigate to frontend: `cd ../app/frontend`
- Start server in background: `bun install && bun dev`
- Wait 2-3 seconds for startup
- Frontend should be accessible at `http://localhost:3000`
## Report
- Confirm backend is running on `http://localhost:8000`
- Confirm frontend is running on `http://localhost:3000`
- Show the health check response from backend
- Mention: "Backend logs will show structured JSON logging for all requests"

7
python/.claude/commands/agent-work-orders/test.md
View File

@@ -1,7 +0,0 @@
# Test Command
This is a test command for verifying the CLI integration.
## Instructions
Echo "Hello from agent work orders test"