Skip to content

Commit a7812f6

Browse files
ChrisEdwardsChrisEdwards
committed
Convert wildcard imports to explicit imports (AIML-230)
Replace all wildcard imports with explicit imports in main source files per CLAUDE.md coding standards. Static wildcard imports in test files remain unchanged as they follow standard test code conventions. Changes: - SDKExtension.java: 1 wildcard → 5 explicit imports - AssessService.java: 3 wildcards → 19 explicit imports - VulnerabilityFilterParams.java: 1 wildcard → 6 explicit imports Verified: mvn test passes (218 tests, 0 failures)
1 parent cc85cf9 commit a7812f6

15 files changed

+5941
-5
lines changed

‎AGENTS.md‎

Lines changed: 131 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,131 @@
1+
# AI Agent Guidelines
2+
3+
## Issue Tracking with bd (beads)
4+
5+
**IMPORTANT**: This project uses **bd (beads)** for ALL issue tracking. Do NOT use markdown TODOs, task lists, or other tracking methods.
6+
7+
### Why bd?
8+
9+
- Dependency-aware: Track blockers and relationships between issues
10+
- Git-friendly: Auto-syncs to JSONL for version control
11+
- Agent-optimized: JSON output, ready work detection, discovered-from links
12+
- Prevents duplicate tracking systems and confusion
13+
14+
### Quick Start
15+
16+
**Check for ready work:**
17+
```bash
18+
bd ready --json
19+
```
20+
21+
**Create new issues:**
22+
```bash
23+
bd create "Issue title" -t bug|feature|task -p 0-4 --json
24+
bd create "Issue title" -p 1 --deps discovered-from:bd-123 --json
25+
```
26+
27+
**Claim and update:**
28+
```bash
29+
bd update bd-42 --status in_progress --json
30+
bd update bd-42 --priority 1 --json
31+
```
32+
33+
**Complete work:**
34+
```bash
35+
bd close bd-42 --reason "Completed" --json
36+
```
37+
38+
### Issue Types
39+
40+
- `bug` - Something broken
41+
- `feature` - New functionality
42+
- `task` - Work item (tests, docs, refactoring)
43+
- `epic` - Large feature with subtasks
44+
- `chore` - Maintenance (dependencies, tooling)
45+
46+
### Priorities
47+
48+
- `0` - Critical (security, data loss, broken builds)
49+
- `1` - High (major features, important bugs)
50+
- `2` - Medium (default, nice-to-have)
51+
- `3` - Low (polish, optimization)
52+
- `4` - Backlog (future ideas)
53+
54+
### Workflow for AI Agents
55+
56+
1. **Check ready work**: `bd ready` shows unblocked issues
57+
2. **Claim your task**: `bd update <id> --status in_progress`
58+
3. **Work on it**: Implement, test, document
59+
4. **Discover new work?** Create linked issue:
60+
- `bd create "Found bug" -p 1 --deps discovered-from:<parent-id>`
61+
5. **Complete**: `bd close <id> --reason "Done"`
62+
6. **Commit together**: Always commit the `.beads/issues.jsonl` file together with the code changes so issue state stays in sync with code state
63+
64+
### Auto-Sync
65+
66+
bd automatically syncs with git:
67+
- Exports to `.beads/issues.jsonl` after changes (5s debounce)
68+
- Imports from JSONL when newer (e.g., after `git pull`)
69+
- No manual export/import needed!
70+
71+
### MCP Server (Recommended)
72+
73+
If using Claude or MCP-compatible clients, install the beads MCP server:
74+
75+
```bash
76+
pip install beads-mcp
77+
```
78+
79+
Add to MCP config (e.g., `~/.config/claude/config.json`):
80+
```json
81+
{
82+
"beads": {
83+
"command": "beads-mcp",
84+
"args": []
85+
}
86+
}
87+
```
88+
89+
Then use `mcp__beads__*` functions instead of CLI commands.
90+
91+
### Managing AI-Generated Planning Documents
92+
93+
AI assistants often create planning and design documents during development:
94+
- PLAN.md, IMPLEMENTATION.md, ARCHITECTURE.md
95+
- DESIGN.md, CODEBASE_SUMMARY.md, INTEGRATION_PLAN.md
96+
- TESTING_GUIDE.md, TECHNICAL_DESIGN.md, and similar files
97+
98+
**Best Practice: Use a dedicated directory for these ephemeral files**
99+
100+
**Recommended approach:**
101+
- Create a `history/` directory in the project root
102+
- Store ALL AI-generated planning/design docs in `history/`
103+
- Keep the repository root clean and focused on permanent project files
104+
- Only access `history/` when explicitly asked to review past planning
105+
106+
**Example .gitignore entry (optional):**
107+
```
108+
# AI planning documents (ephemeral)
109+
history/
110+
```
111+
112+
**Benefits:**
113+
- ✅ Clean repository root
114+
- ✅ Clear separation between ephemeral and permanent documentation
115+
- ✅ Easy to exclude from version control if desired
116+
- ✅ Preserves planning history for archeological research
117+
- ✅ Reduces noise when browsing the project
118+
119+
### Important Rules
120+
121+
- ✅ Use bd for ALL task tracking
122+
- ✅ Always use `--json` flag for programmatic use
123+
- ✅ Link discovered work with `discovered-from` dependencies
124+
- ✅ Check `bd ready` before asking "what should I work on?"
125+
- ✅ Store AI planning docs in `history/` directory
126+
- ❌ Do NOT create markdown TODO lists
127+
- ❌ Do NOT use external issue trackers
128+
- ❌ Do NOT duplicate tracking systems
129+
- ❌ Do NOT clutter repo root with planning documents
130+
131+
For more details, see README.md and QUICKSTART.md.

‎WORKFLOW.md‎

Lines changed: 205 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,205 @@
1+
# Developer Workflow Quick Reference
2+
3+
Personal workflow guide for Chris Edwards - how to use beads + Jira + Claude Code effectively.
4+
5+
## Starting New Work
6+
7+
### 1. Check for Ready Work
8+
```bash
9+
bd ready
10+
```
11+
12+
### 2. Create or Pick a Bead
13+
14+
**For Jira-tracked work:**
15+
- Create Jira ticket first in AIML project
16+
- Create bead with Jira ID in title and external_ref:
17+
```bash
18+
bd create "AIML-XXX: Description" -t task -p 1 --external-ref AIML-XXX
19+
```
20+
21+
**For discovered work during implementation:**
22+
- Create child bead linked to parent:
23+
```bash
24+
bd create "Fix bug found in feature X" -t bug -p 1 --deps discovered-from:mcp-parent-id
25+
```
26+
27+
### 3. Start Work with Claude Code
28+
29+
Tell Claude to start work on the bead:
30+
```
31+
Start work on bead mcp-XXX
32+
```
33+
34+
Claude will:
35+
- Ask which branch to base off (for stacked PRs)
36+
- Create feature branch (if Jira-linked): `AIML-XXX-description`
37+
- Update bead status to `in_progress`
38+
- Update Jira status to "In Progress" and assign to you
39+
- Present a textual plan and ask you to discuss
40+
- Wait for you to say "generate a plan" before proceeding
41+
42+
**Important**: Discuss the approach BEFORE telling Claude to generate a full plan.
43+
44+
## During Development
45+
46+
### Working with Claude Code
47+
48+
**Tell Claude what to do:**
49+
- "Implement the changes we discussed"
50+
- "Write tests for the new feature"
51+
- "Run the full test suite"
52+
53+
**Claude follows your workflow automatically:**
54+
- Writes tests for all code changes
55+
- Runs `mvn test` and `mvn verify`
56+
- Builds artifacts when needed (`mvn clean package`)
57+
- Records branch name in bead
58+
59+
### Managing Related Work
60+
61+
**Creating child beads:**
62+
- When Claude suggests new work, it will ask if it should be a child bead
63+
- Child beads share the same branch as parent
64+
- Use for: bug fixes found during implementation, follow-up tasks, subtasks
65+
66+
**Check dependencies:**
67+
```bash
68+
bd show mcp-XXX
69+
```
70+
71+
## Moving to Review
72+
73+
When ready for review, tell Claude:
74+
```
75+
Move to review
76+
```
77+
78+
Claude will:
79+
1. Apply `in-review` label to all beads on the branch
80+
2. Push branch to remote
81+
3. Create or update PR with comprehensive description by researching:
82+
- All beads worked on in this branch
83+
- All commits and diffs
84+
- Related voice notes for context
85+
- Jira ticket details
86+
4. Write PR description with why/what/how and step-by-step walkthrough
87+
88+
**Review the PR description** before marking ready - Claude makes it easy for reviewers.
89+
90+
## Long Sessions: Landing the Plane
91+
92+
When context is running low or you need to pause, tell Claude:
93+
```
94+
Let's land the plane
95+
```
96+
97+
Claude will:
98+
1. Create child beads for any remaining work
99+
2. Update current bead with complete status and context
100+
3. Commit all WIP with descriptive message
101+
4. Generate continuation prompt for next session
102+
103+
Copy the continuation prompt to resume work in a fresh session.
104+
105+
## Closing Work
106+
107+
**Never close beads yourself during development.** Tell Claude when you're ready:
108+
```
109+
Close bead mcp-XXX
110+
```
111+
112+
Claude will:
113+
- Ask for confirmation
114+
- Check for open child beads (can't close parent with open children)
115+
- Only close after you explicitly confirm
116+
117+
**Typical lifecycle:**
118+
1. `open` → Start work → `in_progress`
119+
2. `in_progress` → Move to review → `in_progress` + `in-review` label
120+
3. `in_progress` + `in-review` → PR merged → Ask Claude to close → `closed`
121+
122+
## Stacked PRs Workflow
123+
124+
When working on multiple related changes:
125+
126+
1. **First PR**: Branch from `main`, implement, create PR
127+
2. **Second PR**: Tell Claude to base new branch off first PR branch
128+
3. **Continue stacking**: Each new branch comes off the previous one
129+
130+
Claude will ask which branch to base off and show recent branches.
131+
132+
## Quick Commands Reference
133+
134+
### Beads
135+
```bash
136+
bd ready # Show unblocked work
137+
bd list --status in_progress # Your current work
138+
bd show mcp-XXX # Show bead details
139+
bd update mcp-XXX --priority 0 # Bump priority
140+
bd dep add mcp-child mcp-parent # Add dependency
141+
```
142+
143+
### Git
144+
```bash
145+
git log --oneline -10 # Recent commits
146+
git diff main...HEAD # All changes in branch
147+
gh pr view # View current PR
148+
gh pr checks # Check CI status
149+
```
150+
151+
### Maven
152+
```bash
153+
mvn test -q # Run unit tests (quiet)
154+
mvn verify -q # Run integration tests
155+
mvn clean package # Build JAR
156+
```
157+
158+
### Log Work
159+
```bash
160+
/log-work # Log work to voice notes
161+
```
162+
163+
## Tips
164+
165+
- **Always discuss the plan** with Claude before implementation
166+
- **Let Claude manage workflow state** (bead status, Jira status, branches)
167+
- **Use stacked PRs** for dependent changes to keep PRs small
168+
- **Land the plane** when context runs low - don't fight it
169+
- **Voice notes are your friend** - Claude uses them for PR descriptions
170+
- **Test everything** - Claude won't move to review without passing tests
171+
172+
## Common Scenarios
173+
174+
### "I found a bug while implementing"
175+
Tell Claude: "Create a child bead for this bug"
176+
Claude will ask if it should be a child and create it.
177+
178+
### "This is taking too long"
179+
Tell Claude: "Let's land the plane"
180+
Resume in next session with the continuation prompt.
181+
182+
### "I need to work on something urgent"
183+
Commit current work, switch branches. Return to original work by:
184+
```
185+
Continue work on bead mcp-XXX
186+
```
187+
188+
### "PR got approved and merged"
189+
Tell Claude: "Close bead mcp-XXX" (for all beads in that branch)
190+
191+
### "I need to update the PR description"
192+
Tell Claude: "Update the PR description with latest changes"
193+
Claude will research and regenerate.
194+
195+
## Files to Know
196+
197+
- `CLAUDE.md` - Instructions for Claude Code (AI workflow)
198+
- `AGENTS.md` - General beads usage patterns
199+
- `WORKFLOW.md` - This file (your reference)
200+
- `.beads/issues.jsonl` - Bead database (auto-synced with git)
201+
- `voice-notes/YYYY-MM-DD.md` - Daily work log
202+
203+
## Remember
204+
205+
**You focus on the work. Claude manages the workflow.**

0 commit comments

Comments
 (0)