Contrast-Security-OSS
diff --git a/‎.gitignore‎
Lines changed: 1 addition & 0 deletions b/‎.gitignore‎
Lines changed: 1 addition & 0 deletions
diff --git a/‎CLAUDE.md‎
Lines changed: 21 additions & 42 deletions b/‎CLAUDE.md‎
Lines changed: 21 additions & 42 deletions
diff --git a/‎WORKFLOW.md‎
Lines changed: 205 additions & 0 deletions b/‎WORKFLOW.md‎
Lines changed: 205 additions & 0 deletions
@@ -41,3 +41,4 @@ build/
 ### Beads ###
 .beads/
 test-plan-*.md
+plans/
@@ -2,8 +2,6 @@
 
 This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.
 
-**Note**: This project uses [bd (beads)](https://github.com/steveyegge/beads) for issue tracking. Use `bd` commands instead of markdown TODOs. See AGENTS.md for workflow details.
-
 ## Project Overview
 
 This is an MCP (Model Context Protocol) server for Contrast Security that enables AI agents to access and analyze vulnerability data from Contrast's security platform. It serves as a bridge between Contrast Security's API and AI tools like Claude, enabling automated vulnerability remediation and security analysis.
@@ -12,10 +10,12 @@ This is an MCP (Model Context Protocol) server for Contrast Security that enable
 
 ### Building the Project
 - **Build**: `mvn clean install` or `./mvnw clean install`
-- **Package without tests**: `mvn clean package -DskipTests`
 - **Test**: `mvn test` or `./mvnw test`
-- **Run single test**: `mvn test -Dtest=HintGeneratorTest` or `mvn test -Dtest=HintGeneratorTest#specificTestMethod`
-- **Run locally**: `java -jar target/mcp-contrast-0.0.12-SNAPSHOT.jar --CONTRAST_HOST_NAME=<host> --CONTRAST_API_KEY=<key> --CONTRAST_SERVICE_KEY=<key> --CONTRAST_USERNAME=<user> --CONTRAST_ORG_ID=<org>`
+- **Format code**: `mvn spotless:apply` - Auto-format all Java files (run before committing)
+- **Check formatting**: `mvn spotless:check` - Verify code formatting (runs automatically during build)
+- **Run locally**: `java -jar target/mcp-contrast-0.0.11.jar --CONTRAST_HOST_NAME=<host> --CONTRAST_API_KEY=<key> --CONTRAST_SERVICE_KEY=<key> --CONTRAST_USERNAME=<user> --CONTRAST_ORG_ID=<org>`
+
+**Note:** Spotless enforces Google Java Format style automatically. The `spotless:check` goal runs during the `validate` phase, so any `mvn compile`, `mvn test`, or `mvn install` will fail if code is not properly formatted. Run `mvn spotless:apply` before committing to ensure formatting is correct.
 
 ### Docker Commands
 - **Build Docker image**: `docker build -t mcp-contrast .`
@@ -32,19 +32,17 @@ This is an MCP (Model Context Protocol) server for Contrast Security that enable
 
 **Main Application**: `McpContrastApplication.java` - Spring Boot application that registers MCP tools from all service classes.
 
-**Service Layer**: Each service handles a specific aspect of Contrast Security data and exposes `@Tool` annotated methods:
+**Service Layer**: Each service handles a specific aspect of Contrast Security data:
 - `AssessService` - Vulnerability analysis and trace data
 - `SastService` - Static application security testing data
 - `SCAService` - Software composition analysis (library vulnerabilities)
 - `ADRService` - Attack detection and response events
 - `RouteCoverageService` - Route coverage analysis
+- `PromptService` - AI prompt management
 
-**SDK Extensions**: Located in `sdkexstension/` package:
-- `SDKExtension.java` - Extends Contrast SDK API with additional endpoints not in standard SDK (library observations, route details, session metadata, etc.)
-- `SDKHelper.java` - Utility methods for hostname protocol handling and common operations
-- `data/` subpackages - Enhanced data models with AI-friendly representations organized by domain (application, adr, routecoverage, sca, traces, sessionmetadata)
+**SDK Extensions**: Located in `sdkextension/` package, these extend the Contrast SDK with enhanced data models and helper methods for better AI integration.
 
-**Data Models**: Comprehensive POJOs in `data/` package representing vulnerability information, library data, applications, and attack events used by service layer.
+**Data Models**: Comprehensive POJOs in `data/` package representing vulnerability information, library data, applications, and attack events.
 
 **Hint System**: `hints/` package provides context-aware security guidance for vulnerability remediation.
 
@@ -64,29 +62,25 @@ Required environment variables/arguments:
 
 ### Technology Stack
 
-- **Framework**: Spring Boot 3.4.5 with Spring AI 1.0.1
+- **Framework**: Spring Boot 3.4.5 with Spring AI 1.0.0-RC1
 - **MCP Integration**: Spring AI MCP Server starter
 - **Contrast Integration**: Contrast SDK Java 3.4.2
-- **JSON Processing**: Gson (via Contrast SDK)
-- **Testing**: JUnit 5 with Spring Boot Test
-- **Build Tool**: Maven 3.6+ with wrapper
+- **Testing**: JUnit 5
+- **Build Tool**: Maven with wrapper
 - **Packaging**: Executable JAR and Docker container
 
 ### Development Patterns
 
-1. **MCP Tools**: Services expose methods via `@Tool` annotation for AI agent consumption. Register new services in `McpContrastApplication.tools()` bean.
-2. **SDK Extension Pattern**:
-   - Use `SDKExtension` to add new Contrast API endpoints not in the standard SDK
-   - Use `SDKHelper` for common utility operations (hostname handling, etc.)
-   - Enhanced data models in `sdkexstension/data/` provide AI-friendly JSON representations
-3. **Hint Generation**: Rule-based system in `hints/` package provides contextual security guidance for vulnerability remediation
-4. **Defensive Design**: All external API calls include proper resource management (try-with-resources), error handling, and logging
-5. **Pagination Handling**: SDK extension methods handle pagination automatically (see `getLibraryObservations` for pattern)
+1. **MCP Tools**: Services expose methods via `@Tool` annotation for AI agent consumption
+2. **SDK Extension Pattern**: Enhanced data models extend base SDK classes with AI-friendly representations
+3. **Hint Generation**: Rule-based system provides contextual security guidance
+4. **Defensive Design**: All external API calls include error handling and logging
 
 ### Coding Standards
 
 - **Prefer `var`** for local variables when the type is obvious from the right-hand side
 - **Use `isEmpty()`** instead of `size() > 0` or `size() == 0` for collection checks
+- **No wildcard imports** - All imports must be explicit. Do not use `import package.*` syntax
 
 ### Security Considerations
 
@@ -97,7 +91,6 @@ This codebase handles sensitive vulnerability data. The README contains critical
 - Default log location: `/tmp/mcp-contrast.log`
 - Debug logging: Add `--logging.level.root=DEBUG` to startup arguments
 - Console logging is minimal by design for MCP protocol compatibility
-- Debug mode buffers API responses for logging (memory impact with large datasets)
 
 ## Beads Workflow Requirements
 
@@ -136,22 +129,6 @@ Example: If B must be done after A completes, use `bd dep add B A` (not `bd dep
 
 Verify with `bd show <task-id>` - dependent tasks show "Depends on", prerequisites show "Blocks".
 
-### Testing Requirements Before Closing Beads
-### Troubleshooting
-
-For common issues (SSL certificates, proxy configuration, debug logging), see the "Common Issues" and "Proxy Configuration" sections in [README.md](README.md).
-
-### Adding New MCP Tools
-
-To add a new tool/service:
-1. Create a new `@Service` class with methods annotated with `@Tool(description="...")`
-2. Inject dependencies (ContrastSDK, SDKExtension) via constructor
-3. Register the service in `McpContrastApplication.tools()` bean method
-4. Use `SDKExtension` to add new API endpoints if needed
-5. Create enhanced data models in appropriate `sdkexstension/data/` subpackage
-
-See INTEGRATION_TESTS.md for integration test setup and credentials.
-
 ## Project Management
 
 ### Jira Issue Tracking
@@ -225,7 +202,9 @@ Promoting Stacked PR (after base PR merges):
    - Record the branch name in the bead (so it's easily found later)
    - **If this is a stacked branch** (based on another PR branch):
      - Label the bead with `stacked-branch`
-     - Create parent-child dependency: the stacked bead depends on the bead of the branch it's based on
+     - Create blocks dependency: `bd dep add <new-bead-id> <base-bead-id> --type blocks`
+       - This represents that the base bead "blocks" the new bead from being merged
+       - Example: If AIML-230 is stacked on AIML-228, use `bd dep add mcp-uuv mcp-9kr --type blocks`
 
 **3. Update Jira (if applicable):**
    - If bead has a linked Jira ticket:
@@ -580,4 +559,4 @@ This workflow is for ending the current session while preserving all state so wo
 
 **Cannot close parent beads** if they still have open children. Ensure all child beads are closed first.
 
-Beads typically remain `in_progress` (with `in-review` label) until the PR review is complete and merged. Only close beads when explicitly instructed by the user.
+Beads typically remain `in_progress` (with `in-review` label) until the PR review is complete and merged. Only close beads when explicitly instructed by the user.
@@ -0,0 +1,205 @@
+# Developer Workflow Quick Reference
+
+Personal workflow guide for Chris Edwards - how to use beads + Jira + Claude Code effectively.
+
+## Starting New Work
+
+### 1. Check for Ready Work
+```bash
+bd ready
+```
+
+### 2. Create or Pick a Bead
+
+**For Jira-tracked work:**
+- Create Jira ticket first in AIML project
+- Create bead with Jira ID in title and external_ref:
+  ```bash
+  bd create "AIML-XXX: Description" -t task -p 1 --external-ref AIML-XXX
+  ```
+
+**For discovered work during implementation:**
+- Create child bead linked to parent:
+  ```bash
+  bd create "Fix bug found in feature X" -t bug -p 1 --deps discovered-from:mcp-parent-id
+  ```
+
+### 3. Start Work with Claude Code
+
+Tell Claude to start work on the bead:
+```
+Start work on bead mcp-XXX
+```
+
+Claude will:
+- Ask which branch to base off (for stacked PRs)
+- Create feature branch (if Jira-linked): `AIML-XXX-description`
+- Update bead status to `in_progress`
+- Update Jira status to "In Progress" and assign to you
+- Present a textual plan and ask you to discuss
+- Wait for you to say "generate a plan" before proceeding
+
+**Important**: Discuss the approach BEFORE telling Claude to generate a full plan.
+
+## During Development
+
+### Working with Claude Code
+
+**Tell Claude what to do:**
+- "Implement the changes we discussed"
+- "Write tests for the new feature"
+- "Run the full test suite"
+
+**Claude follows your workflow automatically:**
+- Writes tests for all code changes
+- Runs `mvn test` and `mvn verify`
+- Builds artifacts when needed (`mvn clean package`)
+- Records branch name in bead
+
+### Managing Related Work
+
+**Creating child beads:**
+- When Claude suggests new work, it will ask if it should be a child bead
+- Child beads share the same branch as parent
+- Use for: bug fixes found during implementation, follow-up tasks, subtasks
+
+**Check dependencies:**
+```bash
+bd show mcp-XXX
+```
+
+## Moving to Review
+
+When ready for review, tell Claude:
+```
+Move to review
+```
+
+Claude will:
+1. Apply `in-review` label to all beads on the branch
+2. Push branch to remote
+3. Create or update PR with comprehensive description by researching:
+   - All beads worked on in this branch
+   - All commits and diffs
+   - Related voice notes for context
+   - Jira ticket details
+4. Write PR description with why/what/how and step-by-step walkthrough
+
+**Review the PR description** before marking ready - Claude makes it easy for reviewers.
+
+## Long Sessions: Landing the Plane
+
+When context is running low or you need to pause, tell Claude:
+```
+Let's land the plane
+```
+
+Claude will:
+1. Create child beads for any remaining work
+2. Update current bead with complete status and context
+3. Commit all WIP with descriptive message
+4. Generate continuation prompt for next session
+
+Copy the continuation prompt to resume work in a fresh session.
+
+## Closing Work
+
+**Never close beads yourself during development.** Tell Claude when you're ready:
+```
+Close bead mcp-XXX
+```
+
+Claude will:
+- Ask for confirmation
+- Check for open child beads (can't close parent with open children)
+- Only close after you explicitly confirm
+
+**Typical lifecycle:**
+1. `open` → Start work → `in_progress`
+2. `in_progress` → Move to review → `in_progress` + `in-review` label
+3. `in_progress` + `in-review` → PR merged → Ask Claude to close → `closed`
+
+## Stacked PRs Workflow
+
+When working on multiple related changes:
+
+1. **First PR**: Branch from `main`, implement, create PR
+2. **Second PR**: Tell Claude to base new branch off first PR branch
+3. **Continue stacking**: Each new branch comes off the previous one
+
+Claude will ask which branch to base off and show recent branches.
+
+## Quick Commands Reference
+
+### Beads
+```bash
+bd ready                                    # Show unblocked work
+bd list --status in_progress                # Your current work
+bd show mcp-XXX                             # Show bead details
+bd update mcp-XXX --priority 0              # Bump priority
+bd dep add mcp-child mcp-parent             # Add dependency
+```
+
+### Git
+```bash
+git log --oneline -10                       # Recent commits
+git diff main...HEAD                        # All changes in branch
+gh pr view                                  # View current PR
+gh pr checks                                # Check CI status
+```
+
+### Maven
+```bash
+mvn test -q                                 # Run unit tests (quiet)
+mvn verify -q                               # Run integration tests
+mvn clean package                           # Build JAR
+```
+
+### Log Work
+```bash
+/log-work                                   # Log work to voice notes
+```
+
+## Tips
+
+- **Always discuss the plan** with Claude before implementation
+- **Let Claude manage workflow state** (bead status, Jira status, branches)
+- **Use stacked PRs** for dependent changes to keep PRs small
+- **Land the plane** when context runs low - don't fight it
+- **Voice notes are your friend** - Claude uses them for PR descriptions
+- **Test everything** - Claude won't move to review without passing tests
+
+## Common Scenarios
+
+### "I found a bug while implementing"
+Tell Claude: "Create a child bead for this bug"
+Claude will ask if it should be a child and create it.
+
+### "This is taking too long"
+Tell Claude: "Let's land the plane"
+Resume in next session with the continuation prompt.
+
+### "I need to work on something urgent"
+Commit current work, switch branches. Return to original work by:
+```
+Continue work on bead mcp-XXX
+```
+
+### "PR got approved and merged"
+Tell Claude: "Close bead mcp-XXX" (for all beads in that branch)
+
+### "I need to update the PR description"
+Tell Claude: "Update the PR description with latest changes"
+Claude will research and regenerate.
+
+## Files to Know
+
+- `CLAUDE.md` - Instructions for Claude Code (AI workflow)
+- `AGENTS.md` - General beads usage patterns
+- `WORKFLOW.md` - This file (your reference)
+- `.beads/issues.jsonl` - Bead database (auto-synced with git)
+- `voice-notes/YYYY-MM-DD.md` - Daily work log
+
+## Remember
+
+**You focus on the work. Claude manages the workflow.**