This is an automated email from the ASF dual-hosted git repository.
lukaszlenart pushed a commit to branch fix/improves-claude-code-agents
in repository https://gitbox.apache.org/repos/asf/struts.git
commit e1de9362aff09b3c8e06e3782dfe5c66f0e011e5
Author: Lukasz Lenart <lukaszlen...@apache.org>
AuthorDate: Mon Sep 29 11:57:42 2025 +0200
Improve Claude Code agents configuration for Apache Struts
- Replace hardcoded user paths with dynamic $USER environment variable
- Update ticket patterns from eng_XXXX to Apache Struts WW-XXXX format
- Create thoughts/ directory structure for research documentation
- Add Maven build commands (mvn test -DskipAssembly) to agents
- Enhance security analysis with CVE-specific patterns (CVE-2017-5638,
CVE-2018-11776)
- Improve Struts-specific knowledge in codebase analysis agents
- Add Jakarta module support and OGNL security focus
- Enable portable configuration across all developers
🤖 Generated with [Claude Code](https://claude.com/claude-code)
Co-Authored-By: Claude <nore...@anthropic.com>
---
.claude/agents/codebase-analyzer.md | 8 +++++---
.claude/agents/codebase-pattern-finder.md | 7 +++++--
.claude/agents/thoughts-analyzer.md | 3 ++-
.claude/agents/thoughts-locator.md | 16 ++++++++--------
.claude/commands/research_codebase.md | 17 ++++++++++-------
thoughts/README.md | 12 ++++++++++++
thoughts/global/.gitkeep | 0
thoughts/lukaszlenart/.gitkeep | 0
thoughts/lukaszlenart/notes/.gitkeep | 0
thoughts/lukaszlenart/tickets/.gitkeep | 0
thoughts/searchable/.gitkeep | 0
thoughts/shared/.gitkeep | 0
thoughts/shared/plans/.gitkeep | 0
thoughts/shared/prs/.gitkeep | 0
thoughts/shared/research/.gitkeep | 0
thoughts/shared/tickets/.gitkeep | 0
16 files changed, 42 insertions(+), 21 deletions(-)
diff --git a/.claude/agents/codebase-analyzer.md
b/.claude/agents/codebase-analyzer.md
index 2af778ac9..e24ca6d4d 100644
--- a/.claude/agents/codebase-analyzer.md
+++ b/.claude/agents/codebase-analyzer.md
@@ -33,6 +33,7 @@ You are an expert Apache Struts framework analyst
specializing in understanding
- Analyze core vs plugin functionality
- Map cross-module interactions
- Review build configuration and profiles
+ - Execute Maven commands: `mvn test -DskipAssembly`, `mvn clean install`
3. **Configuration Analysis**
- Parse struts.xml and struts-plugin.xml files
@@ -41,10 +42,11 @@ You are an expert Apache Struts framework analyst
specializing in understanding
- Examine package inheritance and namespaces
4. **Security Review**
- - Identify potential OGNL injection points
- - Review input validation patterns
+ - Identify potential OGNL injection points (CVE-2017-5638, CVE-2018-11776)
+ - Review input validation patterns and parameter filtering
- Analyze interceptor security configurations
- - Check for known vulnerability patterns
+ - Check for known vulnerability patterns (DMI, namespace manipulation)
+ - Examine file upload restrictions and multipart handling
5. **Code Pattern Recognition**
- Identify Action class patterns
diff --git a/.claude/agents/codebase-pattern-finder.md
b/.claude/agents/codebase-pattern-finder.md
index a96bb6da2..1ddde9ab4 100644
--- a/.claude/agents/codebase-pattern-finder.md
+++ b/.claude/agents/codebase-pattern-finder.md
@@ -20,11 +20,13 @@ You are a specialized code analysis agent for the Apache
Struts framework. Your
- **OGNL expression patterns**: Identify OGNL usage patterns and potential
security risks
### 2. Security Analysis
-- **OGNL injection vulnerabilities**: Detect potentially dangerous OGNL
expressions
+- **OGNL injection vulnerabilities**: Detect potentially dangerous OGNL
expressions (CVE-2017-5638, CVE-2018-11776)
- **Parameter pollution**: Identify areas vulnerable to parameter manipulation
-- **File upload vulnerabilities**: Check for insecure file upload
configurations
+- **File upload vulnerabilities**: Check for insecure file upload
configurations (multipart)
- **XML external entity (XXE) risks**: Find potential XXE vulnerabilities in
XML processing
- **Deprecated security features**: Identify usage of deprecated or vulnerable
Struts features
+- **DMI patterns**: Dynamic method invocation security concerns
+- **WW-XXXX ticket patterns**: Security fixes and vulnerability remediation
patterns
### 3. Configuration Consistency
- **struts.xml analysis**: Check for consistency in action mappings, package
configurations, and result definitions
@@ -175,6 +177,7 @@ For comprehensive analysis, I utilize:
- Java AST analysis for code pattern detection
- Regular expressions for OGNL expression identification
- Dependency analysis for plugin interactions
+- Maven commands: `mvn test -DskipAssembly`, `mvn clean install`, `mvn
dependency:tree`
## Success Criteria
diff --git a/.claude/agents/thoughts-analyzer.md
b/.claude/agents/thoughts-analyzer.md
index bc2673ec9..e25ab9391 100644
--- a/.claude/agents/thoughts-analyzer.md
+++ b/.claude/agents/thoughts-analyzer.md
@@ -33,7 +33,8 @@ You are a specialized analyzer for Apache Struts framework
code and architectura
### 4. Migration and Compatibility Analysis
- Assess reasoning behind version migration strategies (Struts 1.x to
2.x/6.x/7.x)
- Identify deprecated pattern usage and modernization opportunities
-- Evaluate compatibility with Jakarta EE migration paths
+- Evaluate compatibility with Jakarta EE migration paths (see `/jakarta/`
modules)
+- Analyze WW-XXXX ticket patterns and associated code changes
## Analysis Methodology
diff --git a/.claude/agents/thoughts-locator.md
b/.claude/agents/thoughts-locator.md
index 00b329c15..0875cc6d7 100644
--- a/.claude/agents/thoughts-locator.md
+++ b/.claude/agents/thoughts-locator.md
@@ -11,12 +11,12 @@ You are a specialist at finding documents in the thoughts/
directory. Your job i
1. **Search thoughts/ directory structure**
- Check thoughts/shared/ for team documents
- - Check thoughts/allison/ (or other user dirs) for personal notes
+ - Check thoughts/$USER/ for personal notes (dynamically resolved)
- Check thoughts/global/ for cross-repo thoughts
- Handle thoughts/searchable/ (read-only directory for searching)
2. **Categorize findings by type**
- - Tickets (usually in tickets/ subdirectory)
+ - Tickets (usually in tickets/ subdirectory, Apache Struts uses WW-XXXX
format)
- Research documents (in research/)
- Implementation plans (in plans/)
- PR descriptions (in prs/)
@@ -41,7 +41,7 @@ thoughts/
│ ├── plans/ # Implementation plans
│ ├── tickets/ # Ticket documentation
│ └── prs/ # PR descriptions
-├── allison/ # Personal thoughts (user-specific)
+├── $USER/ # Personal thoughts (user-specific)
│ ├── tickets/
│ └── notes/
├── global/ # Cross-repository thoughts
@@ -57,7 +57,7 @@ thoughts/
### Path Correction
**CRITICAL**: If you find files in thoughts/searchable/, report the actual
path:
- `thoughts/searchable/shared/research/api.md` →
`thoughts/shared/research/api.md`
-- `thoughts/searchable/allison/tickets/eng_123.md` →
`thoughts/allison/tickets/eng_123.md`
+- `thoughts/searchable/$USER/tickets/WW-123.md` →
`thoughts/$USER/tickets/WW-123.md`
- `thoughts/searchable/global/patterns.md` → `thoughts/global/patterns.md`
Only remove "searchable/" from the path - preserve all other directory
structure!
@@ -70,8 +70,8 @@ Structure your findings like this:
## Thought Documents about [Topic]
### Tickets
-- `thoughts/allison/tickets/eng_1234.md` - Implement rate limiting for API
-- `thoughts/shared/tickets/eng_1235.md` - Rate limit configuration design
+- `thoughts/$USER/tickets/WW-1234.md` - Implement rate limiting for API
+- `thoughts/shared/tickets/WW-1235.md` - Rate limit configuration design
### Research Documents
- `thoughts/shared/research/2024-01-15_rate_limiting_approaches.md` - Research
on different rate limiting strategies
@@ -81,7 +81,7 @@ Structure your findings like this:
- `thoughts/shared/plans/api-rate-limiting.md` - Detailed implementation plan
for rate limits
### Related Discussions
-- `thoughts/allison/notes/meeting_2024_01_10.md` - Team discussion about rate
limiting
+- `thoughts/$USER/notes/meeting_2024_01_10.md` - Team discussion about rate
limiting
- `thoughts/shared/decisions/rate_limit_values.md` - Decision on rate limit
thresholds
### PR Descriptions
@@ -103,7 +103,7 @@ Total: 8 relevant documents found
- Global for cross-cutting concerns
3. **Look for patterns**:
- - Ticket files often named `eng_XXXX.md`
+ - Ticket files often named `WW-XXXX.md` (Apache Struts JIRA format)
- Research files often dated `YYYY-MM-DD_topic.md`
- Plan files often named `feature-name.md`
diff --git a/.claude/commands/research_codebase.md
b/.claude/commands/research_codebase.md
index 8dead026c..1d02f4e37 100644
--- a/.claude/commands/research_codebase.md
+++ b/.claude/commands/research_codebase.md
@@ -57,15 +57,15 @@ Then wait for the user's research query.
- Use thoughts/ findings as supplementary historical context
- Connect findings across different components
- Include specific file paths and line numbers for reference
- - Verify all thoughts/ paths are correct (e.g., thoughts/allison/ not
thoughts/shared/ for personal files)
+ - Verify all thoughts/ paths are correct (e.g., thoughts/$USER/ not
thoughts/shared/ for personal files)
- Highlight patterns, connections, and architectural decisions
- Answer the user's specific questions with concrete evidence
5. **Gather metadata for the research document:**
- Filename: `thoughts/shared/research/YYYY-MM-DD-WW-XXXX-description.md`
- - Format: `YYYY-MM-DD-ENG-XXXX-description.md` where:
+ - Format: `YYYY-MM-DD-WW-XXXX-description.md` where:
- YYYY-MM-DD is today's date
- - WW-XXXX is the ticket number (omit if no ticket)
+ - WW-XXXX is the Apache Struts JIRA ticket number (omit if no ticket)
- description is a brief kebab-case description of the research topic
- Examples:
- With ticket: `2025-01-08-WW-1478-parent-child-tracking.md`
@@ -112,7 +112,7 @@ Then wait for the user's research query.
## Historical Context (from thoughts/)
[Relevant insights from thoughts/ directory with references]
- `thoughts/shared/something.md` - Historical decision about X
- - `thoughts/local/notes.md` - Past exploration of Y
+ - `thoughts/$USER/notes.md` - Past exploration of Y
Note: Paths exclude "searchable/" even if found there
## Related Research
@@ -154,6 +154,9 @@ Then wait for the user's research query.
- Keep the main agent focused on synthesis, not deep file reading
- Encourage sub-agents to find examples and usage patterns, not just
definitions
- Explore all of thoughts/ directory, not just research subdirectory
+- **Apache Struts specific**: Consider Maven modules (`/core/`, `/plugins/`,
`/apps/`, `/jakarta/`)
+- **Security focus**: Always analyze OGNL usage patterns and potential
CVE-related issues
+- **Testing patterns**: Use `mvn test -DskipAssembly` for running tests
efficiently
- **File reading**: Always read mentioned files FULLY (no limit/offset) before
spawning sub-tasks
- **Critical ordering**: Follow the numbered steps exactly
- ALWAYS read mentioned files first before spawning sub-tasks (step 1)
@@ -163,10 +166,10 @@ Then wait for the user's research query.
- **Path handling**: The thoughts/searchable/ directory contains hard links
for searching
- Always document paths by removing ONLY "searchable/" - preserve all other
subdirectories
- Examples of correct transformations:
- - `thoughts/searchable/allison/old_stuff/notes.md` →
`thoughts/allison/old_stuff/notes.md`
- - `thoughts/searchable/shared/prs/123.md` → `thoughts/shared/prs/123.md`
+ - `thoughts/searchable/$USER/old_stuff/notes.md` →
`thoughts/$USER/old_stuff/notes.md`
+ - `thoughts/searchable/shared/prs/WW-123.md` →
`thoughts/shared/prs/WW-123.md`
- `thoughts/searchable/global/shared/templates.md` →
`thoughts/global/shared/templates.md`
- - NEVER change allison/ to shared/ or vice versa - preserve the exact
directory structure
+ - NEVER change $USER/ to shared/ or vice versa - preserve the exact
directory structure
- This ensures paths are correct for editing and navigation
- **Frontmatter consistency**:
- Always include frontmatter at the beginning of research documents
diff --git a/thoughts/README.md b/thoughts/README.md
new file mode 100644
index 000000000..c6f2148ec
--- /dev/null
+++ b/thoughts/README.md
@@ -0,0 +1,12 @@
+# Thoughts Directory Structure
+
+This directory structure supports Claude Code research and documentation
workflows.
+
+## Directory Structure
+- shared/ - Team-shared documents and research
+- $USER/ - User-specific personal notes and drafts
+- global/ - Cross-repository documentation
+- searchable/ - Search index for all thoughts (managed automatically)
+
+## Usage
+The Claude Code agents use this structure to organize research findings,
ticket analysis, and architectural documentation for the Apache Struts project.
diff --git a/thoughts/global/.gitkeep b/thoughts/global/.gitkeep
new file mode 100644
index 000000000..e69de29bb
diff --git a/thoughts/lukaszlenart/.gitkeep b/thoughts/lukaszlenart/.gitkeep
new file mode 100644
index 000000000..e69de29bb
diff --git a/thoughts/lukaszlenart/notes/.gitkeep
b/thoughts/lukaszlenart/notes/.gitkeep
new file mode 100644
index 000000000..e69de29bb
diff --git a/thoughts/lukaszlenart/tickets/.gitkeep
b/thoughts/lukaszlenart/tickets/.gitkeep
new file mode 100644
index 000000000..e69de29bb
diff --git a/thoughts/searchable/.gitkeep b/thoughts/searchable/.gitkeep
new file mode 100644
index 000000000..e69de29bb
diff --git a/thoughts/shared/.gitkeep b/thoughts/shared/.gitkeep
new file mode 100644
index 000000000..e69de29bb
diff --git a/thoughts/shared/plans/.gitkeep b/thoughts/shared/plans/.gitkeep
new file mode 100644
index 000000000..e69de29bb
diff --git a/thoughts/shared/prs/.gitkeep b/thoughts/shared/prs/.gitkeep
new file mode 100644
index 000000000..e69de29bb
diff --git a/thoughts/shared/research/.gitkeep
b/thoughts/shared/research/.gitkeep
new file mode 100644
index 000000000..e69de29bb
diff --git a/thoughts/shared/tickets/.gitkeep b/thoughts/shared/tickets/.gitkeep
new file mode 100644
index 000000000..e69de29bb
