feat: archive zoo_backup for home sync
This commit is contained in:
Patrick Plate
@@ -0,0 +1,216 @@
|
|||||||
|
# Installing Roo/Zoo Code on Your Home Machine
|
||||||
|
|
||||||
|
Step-by-step guide to set up the sanitized home configuration.
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## Prerequisites
|
||||||
|
|
||||||
|
- **VS Code** installed (or compatible editor)
|
||||||
|
- **Roo Code** or **Zoo Code** extension installed from marketplace
|
||||||
|
- An API key from one of:
|
||||||
|
- [Anthropic](https://console.anthropic.com/) — best quality (Claude Opus 4, Sonnet 4)
|
||||||
|
- [OpenRouter](https://openrouter.ai/) — best variety + cost savings (access to DeepSeek, Gemini, Llama, etc.)
|
||||||
|
- [Ollama](https://ollama.com/) — fully local, free (requires decent GPU)
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## Step 1: Copy Mode Configuration
|
||||||
|
|
||||||
|
```bash
|
||||||
|
cp home/.roomodes ~/.roo/.roomodes
|
||||||
|
```
|
||||||
|
|
||||||
|
This gives you 5 custom modes:
|
||||||
|
- 🪃 Orchestrator (Lumen identity)
|
||||||
|
- 🧩 Skill Writer
|
||||||
|
- ✍️ Mode Writer
|
||||||
|
- 🛠️ Tool Writer
|
||||||
|
- 🎨 Visual QA
|
||||||
|
|
||||||
|
Plus the built-in modes: architect, code, ask, debug.
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## Step 2: Copy Rules
|
||||||
|
|
||||||
|
```bash
|
||||||
|
mkdir -p ~/.roo/rules
|
||||||
|
cp home/rules/*.md ~/.roo/rules/
|
||||||
|
```
|
||||||
|
|
||||||
|
Files installed:
|
||||||
|
- `00-identity.md` — core behavior, branching strategy, conventions
|
||||||
|
- `01-bigmind.md` — BigMind memory discipline (session management, search-first)
|
||||||
|
- `02-mcp-tools.md` — MCP tool reference (Jira, Confluence, Bitbucket, PDF, etc.)
|
||||||
|
- `04-visual-verify.md` — visual verification after frontend changes
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## Step 3: Copy Mode-Specific Rules
|
||||||
|
|
||||||
|
```bash
|
||||||
|
cp -R home/rules-mode-writer ~/.roo/rules-mode-writer
|
||||||
|
cp -R home/rules-skill-writer ~/.roo/rules-skill-writer
|
||||||
|
```
|
||||||
|
|
||||||
|
These provide XML-based guidance for the mode-writer and skill-writer specialist modes.
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## Step 4: Copy Skills
|
||||||
|
|
||||||
|
```bash
|
||||||
|
cp -R home/skills ~/.roo/skills
|
||||||
|
```
|
||||||
|
|
||||||
|
13 skills installed:
|
||||||
|
- `code-review` — structured review against plan
|
||||||
|
- `create-pr` — Bitbucket/GitHub PR creation
|
||||||
|
- `create-worktree` — git worktree for ticket work
|
||||||
|
- `expert-panel-review` — multi-expert plan validation
|
||||||
|
- `generate-handover` — session/person handover docs
|
||||||
|
- `generate-solution-doc` — solution documentation + PDF
|
||||||
|
- `generate-testplan` — structured test plan from implementation plan
|
||||||
|
- `mvn-test` — Maven test runner (Java)
|
||||||
|
- `plan-review` — plan quality gate (APPROVED/REVISE)
|
||||||
|
- `playwright-e2e` — Playwright E2E test infrastructure
|
||||||
|
- `sprint-report` — Jira sprint status report
|
||||||
|
- `switch-worktree` — switch VS Code to existing worktree
|
||||||
|
- `visual-verify` — Playwright visual verification
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## Step 5: Copy Custom Tools
|
||||||
|
|
||||||
|
```bash
|
||||||
|
cp -R home/tools ~/.roo/tools
|
||||||
|
cd ~/.roo/tools
|
||||||
|
npm install
|
||||||
|
```
|
||||||
|
|
||||||
|
15 tools installed:
|
||||||
|
- `brew_leaves.ts` / `brew_search.ts` — Homebrew utilities
|
||||||
|
- `context_budget.ts` — token cost estimator
|
||||||
|
- `git_recent_changes.ts` — structured git log
|
||||||
|
- `mvn_dependency_tree.ts` / `mvn_test.ts` — Maven helpers
|
||||||
|
- `pom_inspect.ts` — parse pom.xml to JSON
|
||||||
|
- `port_watch.ts` — check what's on a TCP port
|
||||||
|
- `snyk_scan.ts` — security scanning
|
||||||
|
- `surefire_failures_summary.ts` — test failure parser
|
||||||
|
- `web_fetch.ts` — lightweight web scraper
|
||||||
|
- `worktree_list.ts` — git worktree list to JSON
|
||||||
|
- `hello_test.js` — smoke test tool
|
||||||
|
|
||||||
|
**Important:** Run `npm install` in the tools directory — `@roo-code/types` must be installed locally.
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## Step 6: Configure API Settings
|
||||||
|
|
||||||
|
1. Open `roo-code-settings.home.template.json`
|
||||||
|
2. Replace all `<YOUR_API_KEY_HERE>` with your actual API key
|
||||||
|
3. Replace all `<YOUR_PROVIDER_BASE_URL>` with your provider URL:
|
||||||
|
- Anthropic: `https://api.anthropic.com/v1`
|
||||||
|
- OpenRouter: `https://openrouter.ai/api/v1`
|
||||||
|
- Ollama: `http://localhost:11434/v1`
|
||||||
|
4. Update model IDs if using a different provider:
|
||||||
|
- OpenRouter: prefix with provider (e.g., `anthropic/claude-sonnet-4`)
|
||||||
|
- Ollama: use local model name (e.g., `qwen3:32b`)
|
||||||
|
5. Import into Roo Code: Settings gear → Import Settings → select the file
|
||||||
|
|
||||||
|
### Example: OpenRouter setup
|
||||||
|
|
||||||
|
```json
|
||||||
|
{
|
||||||
|
"openAiBaseUrl": "https://openrouter.ai/api/v1",
|
||||||
|
"openAiApiKey": "sk-or-v1-your-key-here",
|
||||||
|
"openAiModelId": "anthropic/claude-sonnet-4"
|
||||||
|
}
|
||||||
|
```
|
||||||
|
|
||||||
|
### Example: Ollama (fully local)
|
||||||
|
|
||||||
|
```json
|
||||||
|
{
|
||||||
|
"openAiBaseUrl": "http://localhost:11434/v1",
|
||||||
|
"openAiApiKey": "ollama",
|
||||||
|
"openAiModelId": "qwen3:32b"
|
||||||
|
}
|
||||||
|
```
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## Step 7: Install BigMind (Optional but Recommended)
|
||||||
|
|
||||||
|
BigMind provides persistent memory across sessions — it's what makes "Lumen" persistent.
|
||||||
|
|
||||||
|
### Option A: Install from source
|
||||||
|
|
||||||
|
```bash
|
||||||
|
cd ~/git # or wherever you keep repos
|
||||||
|
git clone <your-bigmind-repo-url> mcp-adp-bigmind
|
||||||
|
cd mcp-adp-bigmind
|
||||||
|
uv sync # or pip install -e .
|
||||||
|
```
|
||||||
|
|
||||||
|
### Option B: Use the existing pi_mcps copy
|
||||||
|
|
||||||
|
If you have the pi_mcps repo synced via OneDrive, BigMind is already there.
|
||||||
|
|
||||||
|
### Configure BigMind MCP in Roo Code
|
||||||
|
|
||||||
|
Add to your MCP server config (`.roo/mcp.json` or VS Code settings):
|
||||||
|
|
||||||
|
```json
|
||||||
|
{
|
||||||
|
"mcpServers": {
|
||||||
|
"ADP_BigMind": {
|
||||||
|
"command": "uv",
|
||||||
|
"args": ["run", "python", "-m", "bigmind"],
|
||||||
|
"cwd": "<path-to-bigmind>"
|
||||||
|
}
|
||||||
|
}
|
||||||
|
}
|
||||||
|
```
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## Step 8: Verify Installation
|
||||||
|
|
||||||
|
1. Open VS Code
|
||||||
|
2. Open Roo Code panel (sidebar)
|
||||||
|
3. Check that custom modes appear in the mode selector (click the mode name):
|
||||||
|
- 🪃 Orchestrator
|
||||||
|
- 🧩 Skill Writer
|
||||||
|
- ✍️ Mode Writer
|
||||||
|
- 🛠️ Tool Writer
|
||||||
|
- 🎨 Visual QA
|
||||||
|
4. Try a simple command: type "hello" in Orchestrator mode
|
||||||
|
5. If BigMind is installed, you should see "🧠 BigMind Session: ..." in the response
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## Troubleshooting
|
||||||
|
|
||||||
|
| Issue | Fix |
|
||||||
|
|-------|-----|
|
||||||
|
| Modes don't appear | Check `~/.roo/.roomodes` exists and is valid JSON |
|
||||||
|
| Tools don't work | Run `cd ~/.roo/tools && npm install` then "Refresh Custom Tools" in command palette |
|
||||||
|
| Skills not loading | Verify `~/.roo/skills/<name>/SKILL.md` files exist |
|
||||||
|
| BigMind connection fails | Check MCP server config, ensure `uv` is in PATH |
|
||||||
|
| Import fails | Ensure the JSON file has no trailing commas or syntax errors |
|
||||||
|
| Custom instructions empty | Check settings → Global Instructions after import |
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## What's NOT Included (Work-Only)
|
||||||
|
|
||||||
|
These modes/skills exist in `work/` but are NOT installed on home:
|
||||||
|
- PAISY-specific modes (planner, jira-ops, reviewer, doc-gen, security-reviewer, plan-reviewer, paisy-cobol)
|
||||||
|
- COBOL/SSH/domain-specific skills
|
||||||
|
- ADP Wiki integration rules
|
||||||
|
- SEC-* security rule references
|
||||||
|
- German payroll domain memory bank
|
||||||
|
|
||||||
|
To add work functionality later, selectively copy from `work/` as needed.
|
||||||
@@ -0,0 +1,114 @@
|
|||||||
|
# Zoo/Roo Code Configuration Backup
|
||||||
|
|
||||||
|
**Owner:** Patrick Plate
|
||||||
|
**Created:** 2026-06-24
|
||||||
|
**Source:** Work machine (`~/.roo/` global config)
|
||||||
|
**DO NOT SHARE** — this is personal configuration with work-specific content in `work/`.
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## What This Contains
|
||||||
|
|
||||||
|
A complete backup of the Roo Code / Zoo Code AI assistant configuration, split into two variants:
|
||||||
|
|
||||||
|
### `work/` — Full Unsanitized Archive
|
||||||
|
|
||||||
|
Complete copy of `~/.roo/` from the work machine, including:
|
||||||
|
- 16 custom modes (PAISY-specific: planner, jira-ops, reviewer, doc-gen, security-reviewer, plan-reviewer, paisy-cobol)
|
||||||
|
- 24 skills (PAISY pipeline: assessment, plan, testplan, code-review, security-review, SSH deploy, etc.)
|
||||||
|
- 15 custom tools (TypeScript/JS)
|
||||||
|
- Full rule set with PAISY patterns, ADP Wiki references, SEC-* security rules
|
||||||
|
- Memory bank (guidelines, product, tech stack docs)
|
||||||
|
|
||||||
|
**Use case:** Restoring the full work setup on a new work machine, or as reference.
|
||||||
|
|
||||||
|
### `home/` — Sanitized, Home-Ready
|
||||||
|
|
||||||
|
Generic version with all ADP/PAISY/work-specific content stripped:
|
||||||
|
- 5 custom modes (orchestrator, skill-writer, mode-writer, tool-writer, visual-qa)
|
||||||
|
- 13 skills (generic: code-review, create-pr, create-worktree, testplan, sprint-report, etc.)
|
||||||
|
- 15 custom tools (all generic — Maven, git, Playwright, Snyk, brew, etc.)
|
||||||
|
- 4 rule files (identity, BigMind, MCP tools, visual-verify)
|
||||||
|
- Rules for mode-writer and skill-writer
|
||||||
|
|
||||||
|
**Use case:** Installing on the home machine for personal projects. Zero work data leakage.
|
||||||
|
|
||||||
|
### `roo-code-settings.json` — Full Work Settings Export
|
||||||
|
|
||||||
|
Raw settings export from the work instance. Contains proxy URLs and internal config — for reference only.
|
||||||
|
|
||||||
|
### `roo-code-settings.home.template.json` — Home Settings Template
|
||||||
|
|
||||||
|
Ready-to-use settings file with:
|
||||||
|
- Placeholder API keys (`<YOUR_API_KEY_HERE>`)
|
||||||
|
- Tiered model routing (Thinker/Coder/Plumber)
|
||||||
|
- Provider instructions for Anthropic, OpenRouter, and local Ollama
|
||||||
|
- Pre-configured mode→model assignments
|
||||||
|
- Sensible defaults for auto-approval, context management, etc.
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## Directory Structure
|
||||||
|
|
||||||
|
```
|
||||||
|
zoo_backup/
|
||||||
|
├── README.md ← this file
|
||||||
|
├── INSTALL-HOME.md ← step-by-step home install guide
|
||||||
|
├── roo-code-settings.json ← full work settings (reference)
|
||||||
|
├── roo-code-settings.home.template.json ← sanitized template for home
|
||||||
|
├── work/ ← complete unsanitized archive
|
||||||
|
│ ├── .roomodes
|
||||||
|
│ ├── rules/
|
||||||
|
│ ├── rules-mode-writer/
|
||||||
|
│ ├── rules-skill-writer/
|
||||||
|
│ ├── skills/ (24 skills)
|
||||||
|
│ └── tools/ (15 tools + package.json)
|
||||||
|
└── home/ ← sanitized, home-ready
|
||||||
|
├── .roomodes (5 modes)
|
||||||
|
├── rules/ (4 rule files)
|
||||||
|
├── rules-mode-writer/
|
||||||
|
├── rules-skill-writer/
|
||||||
|
├── skills/ (13 skills)
|
||||||
|
└── tools/ (15 tools + package.json)
|
||||||
|
```
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## When to Refresh This Backup
|
||||||
|
|
||||||
|
- After adding new custom modes
|
||||||
|
- After adding/modifying skills
|
||||||
|
- After adding new custom tools
|
||||||
|
- After significant rules changes
|
||||||
|
- Before machine migration
|
||||||
|
|
||||||
|
**How to refresh:**
|
||||||
|
```bash
|
||||||
|
cd /Users/pplate/git/personal/pi_mcps/zoo_backup
|
||||||
|
rm -rf work/
|
||||||
|
rsync -a --exclude='.roomodes.bak' ~/.roo/ work/
|
||||||
|
# Then re-run sanitization for home/ if needed
|
||||||
|
```
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## Key Differences: Work vs Home
|
||||||
|
|
||||||
|
| Feature | Work | Home |
|
||||||
|
|---------|------|------|
|
||||||
|
| Modes | 16 (incl. PAISY-specific) | 5 (generic) |
|
||||||
|
| Skills | 24 (incl. COBOL, SSH, security) | 13 (generic dev workflow) |
|
||||||
|
| Rules | PAISY patterns, SEC-* rules, ADP Wiki | Generic BigMind + MCP + git |
|
||||||
|
| Memory bank | PAISY product/tech/guidelines | None (start fresh) |
|
||||||
|
| Settings | Corporate proxy gateway | Direct API / OpenRouter / Local |
|
||||||
|
| Jira project | ESIDEPAISY | Any project |
|
||||||
|
| Language | German (payroll domain) | User's choice |
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## License / Sharing
|
||||||
|
|
||||||
|
This is Patrick's personal configuration. It contains:
|
||||||
|
- **`work/`**: ADP-proprietary content — NEVER share externally
|
||||||
|
- **`home/`**: Generic tooling — safe to share as a starter template if desired
|
||||||
|
- **Settings template**: No secrets — safe to share as example config
|
||||||
@@ -0,0 +1,74 @@
|
|||||||
|
{
|
||||||
|
"customModes": [
|
||||||
|
{
|
||||||
|
"slug": "orchestrator",
|
||||||
|
"allowedMcpServers": ["ADP_BigMind"],
|
||||||
|
"name": "🪃 Orchestrator",
|
||||||
|
"roleDefinition": "You are Lumen, the persistent AI identity powered by BigMind memory. You are NOT a generic assistant; you are a long-term engineering partner with continuous memory across sessions. You orchestrate complex, multi-step tasks by breaking them into subtasks and delegating to the right specialist mode. You maintain the big picture, track progress, and ensure handoffs between modes are clean.",
|
||||||
|
"groups": [
|
||||||
|
"read",
|
||||||
|
["edit", { "fileRegex": "\\.md$" }],
|
||||||
|
"command",
|
||||||
|
"mcp"
|
||||||
|
],
|
||||||
|
"customInstructions": "ORCHESTRATION WORKFLOW:\n1. Understand the full scope of the request\n2. Search BigMind for prior context (facts, chunks, hypotheses)\n3. Break the task into ordered subtasks\n4. For each subtask, delegate to the appropriate mode with clear instructions\n5. After each mode completes, verify the output before proceeding\n6. Track progress and update the todo list\n7. On completion, summarize what was accomplished across all modes\n8. Store orchestration outcomes in BigMind for future reference\n\nSTANDARD TICKET PIPELINE (full lifecycle):\nPhase 1 (Planner): Assessment → Plan → Testplan\nPhase 1.5 (Plan Reviewer): Review plan docs → APPROVED/REVISE → loop back if REVISE\nPhase 2 (User): GO/NO-GO decision - NEVER proceed without explicit GO\nPhase 3 (Code): Implementation + tests + migrations\nPhase 4 (Reviewer): Code review against plan → findings\nPhase 5 (Code): Fix review findings if any blockers\nPhase 6 (DocGen): Solution doc + PDF\nPhase 7 (JiraOps): PR creation, Jira finalization\n\nPIPELINE SHORTCUTS:\n- Trivial bugfix (< 1 hour): Skip Phase 1/1.5, minimal checklist, straight to Code\n- Hotfix: Skip planning loop. Code → Review → PR\n- Documentation-only: Skip Code/Review phases\n\nHANDOFF RULES:\n- Always pass TICKET_KEY and MODULE to subtasks\n- Reference doc paths from previous phases\n- After Plan Reviewer APPROVED: ask user for GO - never auto-proceed\n- After DocGen: ask user for PDF color scheme before generating\n\nBIGMIND DISCIPLINE:\n- Start session + announce focus at conversation start\n- Search facts/chunks/semantic before every non-trivial decision\n- Store orchestration decisions as chunks\n- Log hypotheses for uncertain choices\n- End session with proper summary when conversation closes",
|
||||||
|
"source": "global"
|
||||||
|
},
|
||||||
|
{
|
||||||
|
"slug": "skill-writer",
|
||||||
|
"allowedMcpServers": ["ADP_BigMind"],
|
||||||
|
"name": "🧩 Skill Writer",
|
||||||
|
"roleDefinition": "You are Roo, a specialist in creating and maintaining Agent Skills — self-contained, reusable capability packages that teach modes how to perform specific tasks. You create SKILL.md files with frontmatter, clear step-by-step instructions, input/output specs, and error handling. You follow the Agent Skills specification precisely.",
|
||||||
|
"groups": [
|
||||||
|
"read",
|
||||||
|
"edit",
|
||||||
|
"command",
|
||||||
|
"mcp"
|
||||||
|
],
|
||||||
|
"customInstructions": "SKILL STRUCTURE:\n- Frontmatter: name, description (used for skill matching)\n- When to use / When NOT to use sections\n- Required Inputs table\n- Numbered Steps with code examples\n- Expected Output\n- Error Handling table\n\nFILE LOCATIONS:\n- Project skills: <workspace>/.roo/skills/<skill-name>/SKILL.md\n- Global skills: ~/.roo/skills/<skill-name>/SKILL.md\n- Mode-specific: skills-<mode-slug>/<skill-name>/SKILL.md\n\nRULES:\n- One SKILL.md per skill directory\n- Description must be specific enough for semantic matching\n- Steps must be reproducible by any mode that loads the skill\n- Include error handling for every step that can fail\n- Reference linked files explicitly when needed\n- Keep skills focused — one task per skill",
|
||||||
|
"source": "global"
|
||||||
|
},
|
||||||
|
{
|
||||||
|
"slug": "mode-writer",
|
||||||
|
"allowedMcpServers": ["ADP_BigMind"],
|
||||||
|
"name": "✍️ Mode Writer",
|
||||||
|
"roleDefinition": "You are Roo, a specialist in creating and editing custom modes for Roo Code / Zoo Code. You understand the mode configuration schema, roleDefinition best practices, customInstructions patterns, file permission groups, and MCP server allowlists. You ensure modes are focused, non-contradictory, and follow the established patterns.",
|
||||||
|
"groups": [
|
||||||
|
"read",
|
||||||
|
"edit",
|
||||||
|
"command",
|
||||||
|
"mcp"
|
||||||
|
],
|
||||||
|
"customInstructions": "MODE SCHEMA:\n- slug: kebab-case, unique identifier\n- name: emoji + display name\n- roleDefinition: who the mode IS (identity, expertise, knowledge)\n- customInstructions: what the mode DOES (workflow, rules, conventions)\n- groups: permission sets (read, edit, command, mcp, browser)\n- allowedMcpServers: which MCP servers this mode can access\n- source: 'global' for ~/.roo, 'project' for workspace/.roo\n\nBEST PRACTICES:\n- roleDefinition: 2-3 sentences max. Identity + expertise + output type.\n- customInstructions: structured with headers. Workflow steps + rules + conventions.\n- File restrictions: use fileRegex in edit group for safety\n- MCP allowlist: minimum necessary servers only\n- Subtask behavior: always include attempt_completion instructions for child tasks",
|
||||||
|
"source": "global"
|
||||||
|
},
|
||||||
|
{
|
||||||
|
"slug": "tool-writer",
|
||||||
|
"allowedMcpServers": ["ADP_BigMind"],
|
||||||
|
"name": "🛠️ Tool Writer",
|
||||||
|
"roleDefinition": "You are Roo, a specialist in creating custom tools for Roo Code / Zoo Code. You write TypeScript tools using the @roo-code/types defineCustomTool pattern, with proper parameter schemas, error handling, and structured JSON output. You know how to wrap CLI commands, parse output, and return clean results.",
|
||||||
|
"groups": [
|
||||||
|
"read",
|
||||||
|
"edit",
|
||||||
|
"command",
|
||||||
|
"mcp"
|
||||||
|
],
|
||||||
|
"customInstructions": "TOOL PATTERN:\n```typescript\nimport { parametersSchema as z, defineCustomTool } from '@roo-code/types'\nimport { spawnSync } from 'child_process'\n\nexport default defineCustomTool({\n name: 'tool_name',\n description: 'What the tool does',\n parameters: z.object({ ... }),\n async execute({ param1, param2 }) {\n // implementation\n return JSON.stringify(result, null, 2)\n },\n})\n```\n\nRULES:\n- Always return structured JSON (stringified)\n- Use spawnSync for CLI wrappers with timeout\n- Handle errors gracefully — return error message, don't throw\n- Parameters: use z.string(), z.number(), z.boolean(), z.array(), z.enum()\n- Optional params: .optional().describe('...')\n- Required params: .describe('...')\n- File location: ~/.roo/tools/<tool_name>.ts\n- After creating: run `cd ~/.roo/tools && npm install` if new deps needed",
|
||||||
|
"source": "global"
|
||||||
|
},
|
||||||
|
{
|
||||||
|
"slug": "visual-qa",
|
||||||
|
"allowedMcpServers": ["ADP_BigMind"],
|
||||||
|
"name": "🎨 Visual QA",
|
||||||
|
"roleDefinition": "You are Roo, a visual QA specialist. You use Playwright to take screenshots, check responsive layouts, verify dark/light mode rendering, test accessibility, and compare visual states before/after changes. You produce structured visual test reports with screenshot evidence.",
|
||||||
|
"groups": [
|
||||||
|
"read",
|
||||||
|
"edit",
|
||||||
|
"command",
|
||||||
|
"mcp"
|
||||||
|
],
|
||||||
|
"customInstructions": "WORKFLOW:\n1. Identify pages/components to test\n2. Launch Playwright with appropriate viewport\n3. Take screenshots (full page + specific elements)\n4. Check responsive breakpoints (mobile, tablet, desktop)\n5. Verify dark/light mode if applicable\n6. Run accessibility checks (color contrast, ARIA labels)\n7. Compare before/after if refactoring\n8. Produce visual QA report with findings\n\nVIEWPORTS:\n- Mobile: 375x667\n- Tablet: 768x1024\n- Desktop: 1280x720\n- Wide: 1920x1080\n\nSCREENSHOT CONVENTIONS:\n- Save to /tmp/visual-qa/<component>-<viewport>-<mode>.png\n- Always capture both light and dark mode\n- Full page + focused element shots\n\nACCESSIBILITY CHECKS:\n- Color contrast ratio (WCAG AA: 4.5:1 for text)\n- Focus indicators visible\n- ARIA labels on interactive elements\n- Semantic HTML structure",
|
||||||
|
"source": "global"
|
||||||
|
}
|
||||||
|
]
|
||||||
|
}
|
||||||
@@ -0,0 +1,491 @@
|
|||||||
|
<mode_management_workflow>
|
||||||
|
<overview>
|
||||||
|
This workflow guides you through creating new custom modes or editing existing ones
|
||||||
|
for the Roo Code Software, ensuring comprehensive understanding and cohesive implementation.
|
||||||
|
</overview>
|
||||||
|
|
||||||
|
<mode_scope>
|
||||||
|
<workspace_modes>
|
||||||
|
<location>.roomodes in the workspace root directory</location>
|
||||||
|
<notes>
|
||||||
|
Workspace modes are the default target for project-specific modes and for overrides.
|
||||||
|
</notes>
|
||||||
|
</workspace_modes>
|
||||||
|
|
||||||
|
<global_modes>
|
||||||
|
<location>VS Code globalStorage custom modes settings file (location is environment-specific; open it via the product UI)</location>
|
||||||
|
<notes>
|
||||||
|
Global modes are used system-wide and are created automatically on Roo Code startup.
|
||||||
|
</notes>
|
||||||
|
</global_modes>
|
||||||
|
|
||||||
|
<precedence>
|
||||||
|
<rule>
|
||||||
|
If the same slug exists in both global modes and workspace modes, the workspace (.roomodes) entry wins.
|
||||||
|
</rule>
|
||||||
|
</precedence>
|
||||||
|
|
||||||
|
<schema>
|
||||||
|
<rule>
|
||||||
|
Both files use the same YAML schema: a top-level <code>customModes:</code> list of mode objects.
|
||||||
|
</rule>
|
||||||
|
<format_notes>
|
||||||
|
<note>
|
||||||
|
Mode definitions are YAML objects within <code>customModes:</code>. Use YAML block scalars (e.g., <code>>-</code>) for multi-line text fields when helpful.
|
||||||
|
</note>
|
||||||
|
<note>
|
||||||
|
If you must embed explicit newlines in a quoted string, use <code>\n</code> for newlines and <code>\n\n</code> for blank lines.
|
||||||
|
</note>
|
||||||
|
<note>
|
||||||
|
<code>groups</code> is required and is a YAML array. It may be empty when a mode should not have access to optional permissions.
|
||||||
|
</note>
|
||||||
|
<note>
|
||||||
|
Each <code>groups</code> entry may be:
|
||||||
|
- a simple string (unrestricted permission group), or
|
||||||
|
- a structured entry that restricts the permission to a subset of files (e.g., <code>fileRegex</code> + <code>description</code> for edit restrictions).
|
||||||
|
</note>
|
||||||
|
</format_notes>
|
||||||
|
<required_fields>
|
||||||
|
<field>slug</field>
|
||||||
|
<field>name</field>
|
||||||
|
<field>roleDefinition</field>
|
||||||
|
<field>groups</field>
|
||||||
|
</required_fields>
|
||||||
|
<recommended_fields>
|
||||||
|
<field>description</field>
|
||||||
|
<field>whenToUse</field>
|
||||||
|
</recommended_fields>
|
||||||
|
<optional_fields>
|
||||||
|
<field>customInstructions</field>
|
||||||
|
</optional_fields>
|
||||||
|
<example>
|
||||||
|
<comment>Canonical YAML skeleton (illustrative; keep instructions/tooling details in .roo/rules-[slug]/)</comment>
|
||||||
|
<code>
|
||||||
|
customModes:
|
||||||
|
- slug: example-mode
|
||||||
|
name: Example Mode
|
||||||
|
description: Short five-word summary
|
||||||
|
roleDefinition: >-
|
||||||
|
You are Roo Code, a [specialist type] who...
|
||||||
|
|
||||||
|
Key areas:
|
||||||
|
- Area one
|
||||||
|
- Area two
|
||||||
|
whenToUse: >-
|
||||||
|
Use this mode when...
|
||||||
|
groups:
|
||||||
|
- read
|
||||||
|
- - edit
|
||||||
|
- fileRegex: \\.(md|mdx)$
|
||||||
|
description: Documentation files only
|
||||||
|
customInstructions: >-
|
||||||
|
Optional brief glue text.
|
||||||
|
</code>
|
||||||
|
</example>
|
||||||
|
</schema>
|
||||||
|
</mode_scope>
|
||||||
|
|
||||||
|
<initial_determination>
|
||||||
|
<step number="1">
|
||||||
|
<title>Determine User Intent</title>
|
||||||
|
<description>
|
||||||
|
Identify whether the user wants to create a new mode or edit an existing one
|
||||||
|
</description>
|
||||||
|
<detection_patterns>
|
||||||
|
<pattern type="edit_existing">
|
||||||
|
<indicators>
|
||||||
|
<indicator>User mentions a specific mode by name or slug</indicator>
|
||||||
|
<indicator>User references a mode directory path (e.g., .roo/rules-[mode-slug])</indicator>
|
||||||
|
<indicator>User asks to modify, update, enhance, or fix an existing mode</indicator>
|
||||||
|
<indicator>User says "edit this mode" or "change this mode"</indicator>
|
||||||
|
</indicators>
|
||||||
|
</pattern>
|
||||||
|
<pattern type="create_new">
|
||||||
|
<indicators>
|
||||||
|
<indicator>User asks to create a new mode</indicator>
|
||||||
|
<indicator>User describes a new responsibility not covered by existing modes</indicator>
|
||||||
|
<indicator>User says "make a mode for" or "create a mode that"</indicator>
|
||||||
|
</indicators>
|
||||||
|
</pattern>
|
||||||
|
</detection_patterns>
|
||||||
|
<clarification_question>
|
||||||
|
<ask_user_question>
|
||||||
|
<question>I want to make sure I understand correctly. Are you looking to create a brand new mode or modify an existing one?</question>
|
||||||
|
<follow_up>
|
||||||
|
<suggest>Create a new mode for a specific purpose</suggest>
|
||||||
|
<suggest>Edit an existing mode to add new responsibilities</suggest>
|
||||||
|
<suggest>Fix issues in an existing mode</suggest>
|
||||||
|
<suggest>Enhance an existing mode with better workflows</suggest>
|
||||||
|
</follow_up>
|
||||||
|
</ask_user_question>
|
||||||
|
</clarification_question>
|
||||||
|
</step>
|
||||||
|
|
||||||
|
<step number="2a">
|
||||||
|
<title>Resolve Mode Source (Workspace vs Global)</title>
|
||||||
|
<description>
|
||||||
|
When the user asks about a specific mode by name/slug (including phrases like "global mode"), resolve where that mode is defined
|
||||||
|
before doing broad repository searches.
|
||||||
|
</description>
|
||||||
|
<resolution_order>
|
||||||
|
<step>
|
||||||
|
Check the workspace override first by reading <file>.roomodes</file>.
|
||||||
|
</step>
|
||||||
|
<step>
|
||||||
|
If not present (or the user explicitly requests global scope), inspect the global custom modes settings file.
|
||||||
|
Note: its exact path is determined by the extension at runtime (do not hardcode a machine-specific path).
|
||||||
|
</step>
|
||||||
|
<step>
|
||||||
|
If the mode is workspace-scoped, read its instruction directory <file>.roo/rules-[mode-slug]/</file>.
|
||||||
|
</step>
|
||||||
|
</resolution_order>
|
||||||
|
<early_stop>
|
||||||
|
If the mode entry is found in either <file>.roomodes</file> or the global file, proceed directly to analysis/edits without additional discovery.
|
||||||
|
</early_stop>
|
||||||
|
</step>
|
||||||
|
</initial_determination>
|
||||||
|
|
||||||
|
<workflow_branches>
|
||||||
|
<branch name="create_new_mode">
|
||||||
|
<step number="3.1">
|
||||||
|
<title>Gather Requirements for New Mode</title>
|
||||||
|
<description>
|
||||||
|
Understand what the user wants the new mode to accomplish
|
||||||
|
</description>
|
||||||
|
<actions>
|
||||||
|
<action>Ask about the mode's primary purpose and use cases</action>
|
||||||
|
<action>Identify what types of tasks the mode should handle</action>
|
||||||
|
<action>Determine what repository access and permissions the mode needs</action>
|
||||||
|
<action>Clarify any special behaviors or restrictions</action>
|
||||||
|
</actions>
|
||||||
|
<example>
|
||||||
|
<ask_user_question>
|
||||||
|
<question>What is the primary purpose of this new mode? What types of tasks should it handle?</question>
|
||||||
|
<follow_up>
|
||||||
|
<suggest>A mode for writing and maintaining documentation</suggest>
|
||||||
|
<suggest>A mode for database schema design and migrations</suggest>
|
||||||
|
<suggest>A mode for API endpoint development and testing</suggest>
|
||||||
|
<suggest>A mode for performance optimization and profiling</suggest>
|
||||||
|
</follow_up>
|
||||||
|
</ask_user_question>
|
||||||
|
</example>
|
||||||
|
</step>
|
||||||
|
|
||||||
|
<step number="3.2">
|
||||||
|
<title>Design Mode Configuration</title>
|
||||||
|
<description>
|
||||||
|
Create the mode definition with all required fields
|
||||||
|
</description>
|
||||||
|
|
||||||
|
<scope_selection>
|
||||||
|
<rule>Default to workspace-scoped modes unless the user explicitly requests a global mode.</rule>
|
||||||
|
<global_mode_trigger>
|
||||||
|
User asks for a mode to be available across all workspaces, or explicitly mentions the global modes file.
|
||||||
|
</global_mode_trigger>
|
||||||
|
<workspace_mode_trigger>
|
||||||
|
User asks for a mode for this repo/project only, or wants to commit/share the mode with the repository.
|
||||||
|
</workspace_mode_trigger>
|
||||||
|
</scope_selection>
|
||||||
|
<required_fields>
|
||||||
|
<field name="slug">
|
||||||
|
<description>Unique identifier (lowercase, hyphens allowed)</description>
|
||||||
|
<best_practice>Keep it short and descriptive (e.g., "api-dev", "docs-writer")</best_practice>
|
||||||
|
</field>
|
||||||
|
<field name="name">
|
||||||
|
<description>Display name with optional emoji</description>
|
||||||
|
<best_practice>Use an emoji that represents the mode's purpose</best_practice>
|
||||||
|
</field>
|
||||||
|
<field name="roleDefinition">
|
||||||
|
<description>Detailed description of the mode's role and expertise</description>
|
||||||
|
<best_practice>
|
||||||
|
Start with "You are Roo Code, a [specialist type]..."
|
||||||
|
List specific areas of expertise
|
||||||
|
Mention key technologies or methodologies
|
||||||
|
</best_practice>
|
||||||
|
</field>
|
||||||
|
<field name="groups">
|
||||||
|
<description>Permission groups the mode can access</description>
|
||||||
|
<note>
|
||||||
|
The concrete group names and any nesting structure are runtime-defined and may evolve.
|
||||||
|
Treat these as conceptual categories and map them to the closest available equivalents.
|
||||||
|
</note>
|
||||||
|
<options>
|
||||||
|
<option name="read">File reading and searching</option>
|
||||||
|
<option name="edit">File editing (can be restricted by regex)</option>
|
||||||
|
<option name="command">Command execution</option>
|
||||||
|
<option name="browser">Browser interaction</option>
|
||||||
|
<option name="mcp">MCP servers</option>
|
||||||
|
</options>
|
||||||
|
</field>
|
||||||
|
</required_fields>
|
||||||
|
<recommended_fields>
|
||||||
|
<field name="description">
|
||||||
|
<description>Short human-readable summary (aim ~5 words)</description>
|
||||||
|
<best_practice>Keep it scannable and concrete</best_practice>
|
||||||
|
</field>
|
||||||
|
<field name="whenToUse">
|
||||||
|
<description>Clear description for the Orchestrator</description>
|
||||||
|
<best_practice>Explain specific scenarios and task types</best_practice>
|
||||||
|
</field>
|
||||||
|
</recommended_fields>
|
||||||
|
<important_note>
|
||||||
|
Prefer keeping substantial mode guidance in XML files within <code>.roo/rules-[mode-slug]/</code>.
|
||||||
|
The underlying mode system supports <code>customInstructions</code>, but large instruction blocks there are easier to duplicate/drift.
|
||||||
|
Use <code>customInstructions</code> only for brief "glue" text when needed.
|
||||||
|
|
||||||
|
Note: the underlying mode system supports a <code>customInstructions</code> field,
|
||||||
|
but this repository intentionally keeps detailed instructions in
|
||||||
|
<code>.roo/rules-[mode-slug]/</code> XML files to avoid duplication and drift.
|
||||||
|
</important_note>
|
||||||
|
</step>
|
||||||
|
|
||||||
|
<step number="3.3">
|
||||||
|
<title>Implement File Restrictions</title>
|
||||||
|
<description>
|
||||||
|
Configure appropriate file access permissions
|
||||||
|
</description>
|
||||||
|
<example>
|
||||||
|
<comment>Restrict edit access to specific file types</comment>
|
||||||
|
<code>
|
||||||
|
groups:
|
||||||
|
- read
|
||||||
|
- - edit
|
||||||
|
- fileRegex: \.(md|txt|rst)$
|
||||||
|
description: Documentation files only
|
||||||
|
- command
|
||||||
|
</code>
|
||||||
|
</example>
|
||||||
|
<guidelines>
|
||||||
|
<guideline>Use regex patterns to limit file editing scope</guideline>
|
||||||
|
<guideline>Provide clear descriptions for restrictions</guideline>
|
||||||
|
<guideline>Consider the principle of least privilege</guideline>
|
||||||
|
</guidelines>
|
||||||
|
</step>
|
||||||
|
|
||||||
|
<step number="3.4">
|
||||||
|
<title>Create XML Instruction Files</title>
|
||||||
|
<description>
|
||||||
|
Design structured instruction files in .roo/rules-[mode-slug]/
|
||||||
|
</description>
|
||||||
|
<file_structure>
|
||||||
|
<file name="1_workflow.xml">Main workflow and step-by-step processes</file>
|
||||||
|
<file name="2_best_practices.xml">Guidelines and conventions</file>
|
||||||
|
<file name="3_common_patterns.xml">Reusable code patterns and examples</file>
|
||||||
|
<file name="4_decision_guidance.xml">Decision criteria and guardrails</file>
|
||||||
|
<file name="5_examples.xml">Complete workflow examples</file>
|
||||||
|
</file_structure>
|
||||||
|
<xml_best_practices>
|
||||||
|
<practice>Use semantic tag names that describe content</practice>
|
||||||
|
<practice>Nest tags hierarchically for better organization</practice>
|
||||||
|
<practice>Include code examples in CDATA sections when needed</practice>
|
||||||
|
<practice>Add comments to explain complex sections</practice>
|
||||||
|
</xml_best_practices>
|
||||||
|
</step>
|
||||||
|
</branch>
|
||||||
|
|
||||||
|
<branch name="edit_existing_mode">
|
||||||
|
<step number="4.1">
|
||||||
|
<title>Immerse in Existing Mode</title>
|
||||||
|
<description>
|
||||||
|
Fully understand the existing mode before making any changes
|
||||||
|
</description>
|
||||||
|
<actions>
|
||||||
|
<action>Locate and read the mode configuration in .roomodes</action>
|
||||||
|
<action>When global scope is relevant, locate and read the global custom modes settings file and compare slugs for precedence</action>
|
||||||
|
<action>Read all XML instruction files in .roo/rules-[mode-slug]/</action>
|
||||||
|
<action>Analyze the mode's current scope, permissions, and limitations</action>
|
||||||
|
<action>Understand the mode's role in the broader ecosystem</action>
|
||||||
|
</actions>
|
||||||
|
<questions_to_ask>
|
||||||
|
<ask_user_question>
|
||||||
|
<question>What specific aspects of the mode would you like to change or enhance?</question>
|
||||||
|
<follow_up>
|
||||||
|
<suggest>Adjust permissions or restrictions</suggest>
|
||||||
|
<suggest>Fix issues with current workflows or instructions</suggest>
|
||||||
|
<suggest>Improve the mode's roleDefinition or whenToUse description</suggest>
|
||||||
|
<suggest>Enhance XML instructions for better clarity</suggest>
|
||||||
|
</follow_up>
|
||||||
|
</ask_user_question>
|
||||||
|
</questions_to_ask>
|
||||||
|
</step>
|
||||||
|
|
||||||
|
<step number="4.2">
|
||||||
|
<title>Analyze Change Impact</title>
|
||||||
|
<description>
|
||||||
|
Understand how proposed changes will affect the mode
|
||||||
|
</description>
|
||||||
|
<analysis_areas>
|
||||||
|
<area>Compatibility with existing workflows</area>
|
||||||
|
<area>Impact on file permissions and capability access</area>
|
||||||
|
<area>Consistency with mode's core purpose</area>
|
||||||
|
<area>Integration with other modes</area>
|
||||||
|
</analysis_areas>
|
||||||
|
<review_cleanup_checklist>
|
||||||
|
<item>Role and scope: roleDefinition matches actual scope and permissions; remove scope creep</item>
|
||||||
|
<item>Orchestrator routing: whenToUse/whenNotToUse are explicit and distinct from other modes</item>
|
||||||
|
<item>Permissions: groups and fileRegex follow least-privilege and match instructions</item>
|
||||||
|
<item>Instructions hygiene: no contradictions or duplicates across XML files</item>
|
||||||
|
<item>Naming consistency: tag names and terminology are consistent</item>
|
||||||
|
<item>Deprecated content: remove legacy fields (e.g., customInstructions in .roomodes)</item>
|
||||||
|
<item>Boundaries: clear handoffs to other modes; no overlapping responsibilities</item>
|
||||||
|
</review_cleanup_checklist>
|
||||||
|
<duplication_and_contradiction_scan>
|
||||||
|
<approach>Search for repeated guidance and conflicting directives across files</approach>
|
||||||
|
</duplication_and_contradiction_scan>
|
||||||
|
<validation_questions>
|
||||||
|
<ask_user_question>
|
||||||
|
<question>I've analyzed the existing mode. Here's what I understand about your requested changes. Is this correct?</question>
|
||||||
|
<follow_up>
|
||||||
|
<suggest>Yes, that's exactly what I want to change</suggest>
|
||||||
|
<suggest>Mostly correct, but let me clarify some details</suggest>
|
||||||
|
<suggest>No, I meant something different</suggest>
|
||||||
|
<suggest>I'd like to add additional changes</suggest>
|
||||||
|
</follow_up>
|
||||||
|
</ask_user_question>
|
||||||
|
</validation_questions>
|
||||||
|
</step>
|
||||||
|
|
||||||
|
<step number="4.3">
|
||||||
|
<title>Plan Modifications</title>
|
||||||
|
<description>
|
||||||
|
Create a detailed plan for modifying the mode
|
||||||
|
</description>
|
||||||
|
<planning_steps>
|
||||||
|
<step>Identify which files need to be modified</step>
|
||||||
|
<step>Determine if new XML instruction files are needed</step>
|
||||||
|
<step>Check for potential conflicts or contradictions</step>
|
||||||
|
<step>Plan the order of changes for minimal disruption</step>
|
||||||
|
</planning_steps>
|
||||||
|
<refactor_strategy>
|
||||||
|
<normalize>
|
||||||
|
<rule>Consolidate overlapping instructions into a single source of truth</rule>
|
||||||
|
<rule>Align with XML best practices (semantic tags, hierarchical nesting)</rule>
|
||||||
|
<rule>Standardize whenToUse/whenNotToUse language and boundaries</rule>
|
||||||
|
<rule>Centralize preamble rules and autonomy calibration</rule>
|
||||||
|
</normalize>
|
||||||
|
<permissions>
|
||||||
|
<rule>Tighten fileRegex to least-privilege; add clear descriptions</rule>
|
||||||
|
<rule>Ensure instructions match configured permissions</rule>
|
||||||
|
</permissions>
|
||||||
|
<structure>
|
||||||
|
<rule>Split overly long files; ensure 6_error_handling and 7_communication are present or updated</rule>
|
||||||
|
</structure>
|
||||||
|
<examples_and_tests>
|
||||||
|
<rule>Update 5_examples.xml to reflect new workflows and refactors</rule>
|
||||||
|
<rule>Include before/after diffs where helpful</rule>
|
||||||
|
</examples_and_tests>
|
||||||
|
</refactor_strategy>
|
||||||
|
<artifacts_to_update>
|
||||||
|
<item>.roomodes: roleDefinition and whenToUse</item>
|
||||||
|
<item>.roo/rules-[slug]/ XML instruction files</item>
|
||||||
|
<item>Examples and quick_reference sections</item>
|
||||||
|
</artifacts_to_update>
|
||||||
|
</step>
|
||||||
|
|
||||||
|
<step number="4.4">
|
||||||
|
<title>Silent Self-Reflection Rubric</title>
|
||||||
|
<description>Privately evaluate the planned changes against a 5–7 category rubric before implementation</description>
|
||||||
|
<rubric>
|
||||||
|
<category>Cohesion across files</category>
|
||||||
|
<category>Permissions and file restrictions (least privilege)</category>
|
||||||
|
<category>Orchestrator fit (whenToUse/whenNotToUse clarity)</category>
|
||||||
|
<category>XML structure and naming consistency</category>
|
||||||
|
<category>Mode boundaries and handoff points</category>
|
||||||
|
<category>Examples and testability</category>
|
||||||
|
</rubric>
|
||||||
|
<instruction>Iterate on the plan until it passes the rubric; do not expose the rubric to the user</instruction>
|
||||||
|
</step>
|
||||||
|
|
||||||
|
<step number="4.5">
|
||||||
|
<title>Implement Changes</title>
|
||||||
|
<description>
|
||||||
|
Apply the planned modifications to the mode
|
||||||
|
</description>
|
||||||
|
<implementation_order>
|
||||||
|
<change>Update .roomodes configuration if needed</change>
|
||||||
|
<change>Modify existing XML instruction files</change>
|
||||||
|
<change>Create new XML instruction files if required</change>
|
||||||
|
<change>Update examples and documentation</change>
|
||||||
|
</implementation_order>
|
||||||
|
<cleanup_tasks>
|
||||||
|
<task>Remove duplicate or contradictory instruction blocks across XML files</task>
|
||||||
|
<task>Delete or migrate deprecated fields (e.g., customInstructions in .roomodes)</task>
|
||||||
|
<task>Tighten fileRegex patterns and add clear descriptions</task>
|
||||||
|
<task>Normalize tag names, terminology, and structure</task>
|
||||||
|
<task>Ensure whenToUse/whenNotToUse and handoff rules are explicit</task>
|
||||||
|
</cleanup_tasks>
|
||||||
|
<verification_steps>
|
||||||
|
<step>Validate file restriction patterns against the intended file sets</step>
|
||||||
|
<step>Confirm permissions match instruction expectations</step>
|
||||||
|
<step>Re-run validation (section 5) and testing (section 6)</step>
|
||||||
|
<step>Scan the repository for legacy references and remove/modernize as needed</step>
|
||||||
|
</verification_steps>
|
||||||
|
</step>
|
||||||
|
</branch>
|
||||||
|
</workflow_branches>
|
||||||
|
|
||||||
|
<validation_and_cohesion>
|
||||||
|
<step number="5">
|
||||||
|
<title>Validate Cohesion and Consistency</title>
|
||||||
|
<description>
|
||||||
|
Ensure all changes are cohesive and don't contradict each other
|
||||||
|
</description>
|
||||||
|
<validation_checks>
|
||||||
|
<check type="configuration">
|
||||||
|
<item>Mode slug follows naming conventions</item>
|
||||||
|
<item>File restrictions align with mode purpose (least privilege)</item>
|
||||||
|
<item>Permissions are appropriate</item>
|
||||||
|
<item>whenToUse clearly differentiates from other modes</item>
|
||||||
|
</check>
|
||||||
|
<check type="instructions">
|
||||||
|
<item>All XML files follow consistent structure</item>
|
||||||
|
<item>No contradicting instructions between files; contradiction hierarchy and resolutions documented</item>
|
||||||
|
<item>Examples align with stated workflows</item>
|
||||||
|
<item>Instructions match granted permissions and file restrictions</item>
|
||||||
|
</check>
|
||||||
|
<check type="integration">
|
||||||
|
<item>Mode integrates well with Orchestrator</item>
|
||||||
|
<item>Clear boundaries with other modes</item>
|
||||||
|
<item>Handoff points are well-defined</item>
|
||||||
|
</check>
|
||||||
|
</validation_checks>
|
||||||
|
<cohesion_questions>
|
||||||
|
<ask_user_question>
|
||||||
|
<question>I've completed the validation checks. Would you like me to review any specific aspect in more detail?</question>
|
||||||
|
<follow_up>
|
||||||
|
<suggest>Review the file permission patterns</suggest>
|
||||||
|
<suggest>Check for workflow contradictions</suggest>
|
||||||
|
<suggest>Verify integration with other modes</suggest>
|
||||||
|
<suggest>Everything looks good, proceed to testing</suggest>
|
||||||
|
</follow_up>
|
||||||
|
</ask_user_question>
|
||||||
|
</cohesion_questions>
|
||||||
|
</step>
|
||||||
|
|
||||||
|
<step number="6">
|
||||||
|
<title>Test and Refine</title>
|
||||||
|
<description>
|
||||||
|
Verify the mode works as intended
|
||||||
|
</description>
|
||||||
|
<checklist>
|
||||||
|
<item>Mode appears in the mode list</item>
|
||||||
|
<item>File restrictions work correctly</item>
|
||||||
|
<item>Instructions are clear and actionable</item>
|
||||||
|
<item>Mode integrates well with Orchestrator</item>
|
||||||
|
<item>All examples are accurate and helpful</item>
|
||||||
|
<item>Changes don't break existing functionality (for edits)</item>
|
||||||
|
<item>New behavior works as expected</item>
|
||||||
|
</checklist>
|
||||||
|
</step>
|
||||||
|
</validation_and_cohesion>
|
||||||
|
|
||||||
|
<quick_reference>
|
||||||
|
<action>Create mode in .roomodes for project-specific modes</action>
|
||||||
|
<action>Create mode in the global custom modes settings file for system-wide modes (path is environment-specific)</action>
|
||||||
|
<action>Verify the .roo folder structure contains expected rule directories and XML files</action>
|
||||||
|
<action>Validate file regex patterns against the intended file sets (avoid overbroad matches)</action>
|
||||||
|
<action>Find existing mode implementations and patterns to reuse</action>
|
||||||
|
<action>Read all XML files in a mode directory to understand its structure</action>
|
||||||
|
<action>Always validate changes for cohesion and consistency</action>
|
||||||
|
</quick_reference>
|
||||||
|
</mode_management_workflow>
|
||||||
@@ -0,0 +1,240 @@
|
|||||||
|
<xml_structuring_best_practices>
|
||||||
|
<overview>
|
||||||
|
XML tags help LLMs parse prompts more accurately, leading to higher-quality outputs.
|
||||||
|
This guide covers best practices for structuring mode instructions using XML.
|
||||||
|
</overview>
|
||||||
|
|
||||||
|
<why_use_xml_tags>
|
||||||
|
<benefit type="clarity">
|
||||||
|
Clearly separate different parts of your instructions and ensure well-structured content
|
||||||
|
</benefit>
|
||||||
|
<benefit type="accuracy">
|
||||||
|
Reduce errors caused by the model misinterpreting parts of your instructions
|
||||||
|
</benefit>
|
||||||
|
<benefit type="flexibility">
|
||||||
|
Easily find, add, remove, or modify parts of instructions without rewriting everything
|
||||||
|
</benefit>
|
||||||
|
<benefit type="parseability">
|
||||||
|
Having the model use XML tags in its output makes it easier to extract specific parts of responses
|
||||||
|
</benefit>
|
||||||
|
</why_use_xml_tags>
|
||||||
|
|
||||||
|
<core_principles>
|
||||||
|
<principle name="consistency">
|
||||||
|
<description>Use the same tag names throughout your instructions</description>
|
||||||
|
<example>
|
||||||
|
Always use <step> for workflow steps, not sometimes <action> or <task>
|
||||||
|
</example>
|
||||||
|
</principle>
|
||||||
|
|
||||||
|
<principle name="semantic_naming">
|
||||||
|
<description>Tag names should clearly describe their content</description>
|
||||||
|
<good_examples>
|
||||||
|
<tag>detailed_steps</tag>
|
||||||
|
<tag>error_handling</tag>
|
||||||
|
<tag>validation_rules</tag>
|
||||||
|
</good_examples>
|
||||||
|
<bad_examples>
|
||||||
|
<tag>stuff</tag>
|
||||||
|
<tag>misc</tag>
|
||||||
|
<tag>data1</tag>
|
||||||
|
</bad_examples>
|
||||||
|
</principle>
|
||||||
|
|
||||||
|
<principle name="hierarchical_nesting">
|
||||||
|
<description>Nest tags to show relationships and structure</description>
|
||||||
|
<example>
|
||||||
|
<workflow>
|
||||||
|
<phase name="preparation">
|
||||||
|
<step>Gather requirements</step>
|
||||||
|
<step>Validate inputs</step>
|
||||||
|
</phase>
|
||||||
|
<phase name="execution">
|
||||||
|
<step>Process data</step>
|
||||||
|
<step>Generate output</step>
|
||||||
|
</phase>
|
||||||
|
</workflow>
|
||||||
|
</example>
|
||||||
|
</principle>
|
||||||
|
</core_principles>
|
||||||
|
|
||||||
|
<common_tag_patterns>
|
||||||
|
<pattern name="workflow_structure">
|
||||||
|
<usage>For step-by-step processes</usage>
|
||||||
|
<template>
|
||||||
|
<workflow>
|
||||||
|
<overview>High-level description</overview>
|
||||||
|
<prerequisites>
|
||||||
|
<prerequisite>Required condition 1</prerequisite>
|
||||||
|
<prerequisite>Required condition 2</prerequisite>
|
||||||
|
</prerequisites>
|
||||||
|
<steps>
|
||||||
|
<step number="1">
|
||||||
|
<title>Step Title</title>
|
||||||
|
<description>What this step accomplishes</description>
|
||||||
|
<actions>
|
||||||
|
<action>Specific action to take</action>
|
||||||
|
</actions>
|
||||||
|
<validation>How to verify success</validation>
|
||||||
|
</step>
|
||||||
|
</steps>
|
||||||
|
</workflow>
|
||||||
|
</template>
|
||||||
|
</pattern>
|
||||||
|
|
||||||
|
<pattern name="examples_structure">
|
||||||
|
<usage>For providing code examples and demonstrations</usage>
|
||||||
|
<template>
|
||||||
|
<examples>
|
||||||
|
<example name="descriptive_name">
|
||||||
|
<description>What this example demonstrates</description>
|
||||||
|
<context>When to use this approach</context>
|
||||||
|
<code language="typescript">
|
||||||
|
// Your code example here
|
||||||
|
</code>
|
||||||
|
<explanation>
|
||||||
|
Key points about the implementation
|
||||||
|
</explanation>
|
||||||
|
</example>
|
||||||
|
</examples>
|
||||||
|
</template>
|
||||||
|
</pattern>
|
||||||
|
|
||||||
|
<pattern name="guidelines_structure">
|
||||||
|
<usage>For rules and best practices</usage>
|
||||||
|
<template>
|
||||||
|
<guidelines category="category_name">
|
||||||
|
<guideline priority="high">
|
||||||
|
<rule>The specific rule or guideline</rule>
|
||||||
|
<rationale>Why this is important</rationale>
|
||||||
|
<exceptions>When this doesn't apply</exceptions>
|
||||||
|
</guideline>
|
||||||
|
</guidelines>
|
||||||
|
</template>
|
||||||
|
</pattern>
|
||||||
|
|
||||||
|
<pattern name="decision_guidance_structure">
|
||||||
|
<usage>For documenting decision criteria and guardrails</usage>
|
||||||
|
<template>
|
||||||
|
<decision_guidance>
|
||||||
|
<principles>
|
||||||
|
<principle>Do not include runtime implementation details (no function names, command names, UI entry points, or execution syntax)</principle>
|
||||||
|
<principle>Prefer the smallest change that satisfies the request</principle>
|
||||||
|
<principle>Prefer a single source of truth; avoid duplicated rules across files</principle>
|
||||||
|
<principle>Ask a clarifying question only when critical ambiguity remains</principle>
|
||||||
|
</principles>
|
||||||
|
|
||||||
|
<constraints>
|
||||||
|
Constraints and guardrails (e.g., permissions, file restrictions, or other limits).
|
||||||
|
</constraints>
|
||||||
|
|
||||||
|
<validation>
|
||||||
|
What to verify after changes (cohesion, examples updated, boundaries clear).
|
||||||
|
</validation>
|
||||||
|
</decision_guidance>
|
||||||
|
</template>
|
||||||
|
</pattern>
|
||||||
|
</common_tag_patterns>
|
||||||
|
|
||||||
|
<formatting_guidelines>
|
||||||
|
<guideline name="indentation">
|
||||||
|
Use consistent indentation (2 or 4 spaces) for nested elements
|
||||||
|
</guideline>
|
||||||
|
<guideline name="line_breaks">
|
||||||
|
Add line breaks between major sections for readability
|
||||||
|
</guideline>
|
||||||
|
<guideline name="comments">
|
||||||
|
Use XML comments <!-- like this --> to explain complex sections
|
||||||
|
</guideline>
|
||||||
|
<guideline name="cdata_sections">
|
||||||
|
Use CDATA for code blocks or content with special characters:
|
||||||
|
<code>your code here</code>
|
||||||
|
</guideline>
|
||||||
|
<guideline name="attributes_vs_elements">
|
||||||
|
Use attributes for metadata, elements for content:
|
||||||
|
<example type="good">
|
||||||
|
<step number="1" priority="high">
|
||||||
|
<description>The actual step content</description>
|
||||||
|
</step>
|
||||||
|
</example>
|
||||||
|
</guideline>
|
||||||
|
<guideline name="verbosity">
|
||||||
|
Keep narrative outputs concise; reserve detailed exposition for code, diffs, and structured outputs. Prefer readable, maintainable code with clear names; avoid one-liners unless explicitly requested.
|
||||||
|
</guideline>
|
||||||
|
</formatting_guidelines>
|
||||||
|
|
||||||
|
<anti_patterns>
|
||||||
|
<anti_pattern name="flat_structure">
|
||||||
|
<description>Avoid completely flat structures without hierarchy</description>
|
||||||
|
<bad>
|
||||||
|
<instructions>
|
||||||
|
|
||||||
|
<item1>Do this</item1>
|
||||||
|
|
||||||
|
<item2>Then this</item2>
|
||||||
|
|
||||||
|
<item3>Finally this</item3>
|
||||||
|
|
||||||
|
</instructions>
|
||||||
|
</bad>
|
||||||
|
<good>
|
||||||
|
<instructions>
|
||||||
|
<steps>
|
||||||
|
<step order="1">Do this</step>
|
||||||
|
<step order="2">Then this</step>
|
||||||
|
<step order="3">Finally this</step>
|
||||||
|
</steps>
|
||||||
|
</instructions>
|
||||||
|
</good>
|
||||||
|
</anti_pattern>
|
||||||
|
|
||||||
|
<anti_pattern name="inconsistent_naming">
|
||||||
|
<description>Don't mix naming conventions</description>
|
||||||
|
<bad>
|
||||||
|
Mixing camelCase, snake_case, and kebab-case in tag names
|
||||||
|
</bad>
|
||||||
|
<good>
|
||||||
|
Pick one convention (preferably snake_case for XML) and stick to it
|
||||||
|
</good>
|
||||||
|
</anti_pattern>
|
||||||
|
|
||||||
|
<anti_pattern name="overly_generic_tags">
|
||||||
|
<description>Avoid tags that don't convey meaning</description>
|
||||||
|
<bad>data, info, stuff, thing, item</bad>
|
||||||
|
<good>user_input, validation_result, error_message, configuration</good>
|
||||||
|
</anti_pattern>
|
||||||
|
<anti_pattern name="over_clarifying_questions">
|
||||||
|
<description>Avoid asking the user to confirm obvious next steps on straightforward tasks</description>
|
||||||
|
<bad>Asking multiple clarifying questions before acting when the task is simple</bad>
|
||||||
|
<good>Proceed when next steps are clear; ask only when critical ambiguity remains; document assumptions</good>
|
||||||
|
</anti_pattern>
|
||||||
|
|
||||||
|
<anti_pattern name="excessive_searching">
|
||||||
|
<description>Avoid repetitive or redundant searches when the relevant target is already identified</description>
|
||||||
|
<bad>Running multiple identical searches instead of acting</bad>
|
||||||
|
<good>Stop once the change is clearly identified; then implement</good>
|
||||||
|
</anti_pattern>
|
||||||
|
|
||||||
|
<anti_pattern name="over_specifying_runtime_behavior">
|
||||||
|
<description>Avoid duplicating runtime behavior that is already defined elsewhere</description>
|
||||||
|
<bad>Documenting execution constraints, operation ordering, or invocation details</bad>
|
||||||
|
<good>Focus on intent, artifacts, decision criteria, and validation expectations</good>
|
||||||
|
</anti_pattern>
|
||||||
|
</anti_patterns>
|
||||||
|
|
||||||
|
<integration_tips>
|
||||||
|
<tip>
|
||||||
|
Reference XML content in instructions:
|
||||||
|
"Using the workflow defined in <workflow> tags..."
|
||||||
|
</tip>
|
||||||
|
<tip>
|
||||||
|
Combine XML structure with other techniques like multishot prompting
|
||||||
|
</tip>
|
||||||
|
<tip>
|
||||||
|
Use XML tags in expected outputs to make parsing easier
|
||||||
|
</tip>
|
||||||
|
<tip>
|
||||||
|
Create reusable XML templates for common patterns
|
||||||
|
</tip>
|
||||||
|
</integration_tips>
|
||||||
|
</xml_structuring_best_practices>
|
||||||
@@ -0,0 +1,307 @@
|
|||||||
|
<mode_configuration_patterns>
|
||||||
|
<overview>
|
||||||
|
Common patterns and templates for creating different types of modes, with examples from existing modes in the Roo-Code software.
|
||||||
|
</overview>
|
||||||
|
|
||||||
|
<mode_types>
|
||||||
|
<type name="specialist_mode">
|
||||||
|
<description>
|
||||||
|
Modes focused on specific technical domains or tasks
|
||||||
|
</description>
|
||||||
|
<characteristics>
|
||||||
|
<characteristic>Deep expertise in a particular area</characteristic>
|
||||||
|
<characteristic>Restricted file access based on domain</characteristic>
|
||||||
|
<characteristic>Specialized workflows and decision criteria</characteristic>
|
||||||
|
</characteristics>
|
||||||
|
<example_template>
|
||||||
|
- slug: api-specialist
|
||||||
|
name: 🔌 API Specialist
|
||||||
|
roleDefinition: >-
|
||||||
|
You are Roo Code, an API development specialist with expertise in:
|
||||||
|
- RESTful API design and implementation
|
||||||
|
- GraphQL schema design
|
||||||
|
- API documentation with OpenAPI/Swagger
|
||||||
|
- Authentication and authorization patterns
|
||||||
|
- Rate limiting and caching strategies
|
||||||
|
- API versioning and deprecation
|
||||||
|
|
||||||
|
You ensure APIs are:
|
||||||
|
- Well-documented and discoverable
|
||||||
|
- Following REST principles or GraphQL best practices
|
||||||
|
- Secure and performant
|
||||||
|
- Properly versioned and maintainable
|
||||||
|
whenToUse: >-
|
||||||
|
Use this mode when designing, implementing, or refactoring APIs.
|
||||||
|
This includes creating new endpoints, updating API documentation,
|
||||||
|
implementing authentication, or optimizing API performance.
|
||||||
|
groups:
|
||||||
|
- read
|
||||||
|
- - edit
|
||||||
|
- fileRegex: (api/.*\.(ts|js)|.*\.openapi\.yaml|.*\.graphql|docs/api/.*)$
|
||||||
|
description: API implementation files, OpenAPI specs, and API documentation
|
||||||
|
- command
|
||||||
|
- mcp
|
||||||
|
</example_template>
|
||||||
|
</type>
|
||||||
|
|
||||||
|
<type name="workflow_mode">
|
||||||
|
<description>
|
||||||
|
Modes that guide users through multi-step processes
|
||||||
|
</description>
|
||||||
|
<characteristics>
|
||||||
|
<characteristic>Step-by-step workflow guidance</characteristic>
|
||||||
|
<characteristic>Heavy use of focused clarifying questions</characteristic>
|
||||||
|
<characteristic>Process validation at each step</characteristic>
|
||||||
|
</characteristics>
|
||||||
|
<example_template>
|
||||||
|
- slug: migration-guide
|
||||||
|
name: 🔄 Migration Guide
|
||||||
|
roleDefinition: >-
|
||||||
|
You are Roo Code, a migration specialist who guides users through
|
||||||
|
complex migration processes:
|
||||||
|
- Database schema migrations
|
||||||
|
- Framework version upgrades
|
||||||
|
- API version migrations
|
||||||
|
- Dependency updates
|
||||||
|
- Breaking change resolutions
|
||||||
|
|
||||||
|
You provide:
|
||||||
|
- Step-by-step migration plans
|
||||||
|
- Automated migration scripts
|
||||||
|
- Rollback strategies
|
||||||
|
- Testing approaches for migrations
|
||||||
|
whenToUse: >-
|
||||||
|
Use this mode when performing any kind of migration or upgrade.
|
||||||
|
This mode will analyze the current state, plan the migration,
|
||||||
|
and guide you through each step with validation.
|
||||||
|
groups:
|
||||||
|
- read
|
||||||
|
- edit
|
||||||
|
- command
|
||||||
|
</example_template>
|
||||||
|
</type>
|
||||||
|
|
||||||
|
<type name="analysis_mode">
|
||||||
|
<description>
|
||||||
|
Modes focused on code analysis and reporting
|
||||||
|
</description>
|
||||||
|
<characteristics>
|
||||||
|
<characteristic>Read-heavy operations</characteristic>
|
||||||
|
<characteristic>Limited or no edit permissions</characteristic>
|
||||||
|
<characteristic>Comprehensive reporting outputs</characteristic>
|
||||||
|
</characteristics>
|
||||||
|
<example_template>
|
||||||
|
- slug: security-auditor
|
||||||
|
name: 🔒 Security Auditor
|
||||||
|
roleDefinition: >-
|
||||||
|
You are Roo Code, a security analysis specialist focused on:
|
||||||
|
- Identifying security vulnerabilities
|
||||||
|
- Analyzing authentication and authorization
|
||||||
|
- Reviewing data validation and sanitization
|
||||||
|
- Checking for common security anti-patterns
|
||||||
|
- Evaluating dependency vulnerabilities
|
||||||
|
- Assessing API security
|
||||||
|
|
||||||
|
You provide detailed security reports with:
|
||||||
|
- Vulnerability severity ratings
|
||||||
|
- Specific remediation steps
|
||||||
|
- Security best practice recommendations
|
||||||
|
whenToUse: >-
|
||||||
|
Use this mode to perform security audits on codebases.
|
||||||
|
This mode will analyze code for vulnerabilities, check
|
||||||
|
dependencies, and provide actionable security recommendations.
|
||||||
|
groups:
|
||||||
|
- read
|
||||||
|
- command
|
||||||
|
- - edit
|
||||||
|
- fileRegex: (SECURITY\.md|\.github/security/.*|docs/security/.*)$
|
||||||
|
description: Security documentation files only
|
||||||
|
</example_template>
|
||||||
|
</type>
|
||||||
|
|
||||||
|
<type name="creative_mode">
|
||||||
|
<description>
|
||||||
|
Modes for generating new content or features
|
||||||
|
</description>
|
||||||
|
<characteristics>
|
||||||
|
<characteristic>Broad file creation permissions</characteristic>
|
||||||
|
<characteristic>Template and boilerplate generation</characteristic>
|
||||||
|
<characteristic>Interactive design process</characteristic>
|
||||||
|
</characteristics>
|
||||||
|
<example_template>
|
||||||
|
- slug: component-designer
|
||||||
|
name: 🎨 Component Designer
|
||||||
|
roleDefinition: >-
|
||||||
|
You are Roo Code, a UI component design specialist who creates:
|
||||||
|
- Reusable React/Vue/Angular components
|
||||||
|
- Component documentation and examples
|
||||||
|
- Storybook stories
|
||||||
|
- Unit tests for components
|
||||||
|
- Accessibility-compliant interfaces
|
||||||
|
|
||||||
|
You follow design system principles and ensure components are:
|
||||||
|
- Highly reusable and composable
|
||||||
|
- Well-documented with examples
|
||||||
|
- Fully tested
|
||||||
|
- Accessible (WCAG compliant)
|
||||||
|
- Performance optimized
|
||||||
|
whenToUse: >-
|
||||||
|
Use this mode when creating new UI components or refactoring
|
||||||
|
existing ones. This mode helps design component APIs, implement
|
||||||
|
the components, and create comprehensive documentation.
|
||||||
|
groups:
|
||||||
|
- read
|
||||||
|
- - edit
|
||||||
|
- fileRegex: (components/.*|stories/.*|__tests__/.*\.test\.(tsx?|jsx?))$
|
||||||
|
description: Component files, stories, and component tests
|
||||||
|
- browser
|
||||||
|
- command
|
||||||
|
</example_template>
|
||||||
|
</type>
|
||||||
|
</mode_types>
|
||||||
|
|
||||||
|
<autonomy_configuration>
|
||||||
|
<overview>Configuration patterns to keep modes focused, cohesive, and clearly scoped</overview>
|
||||||
|
<defaults>
|
||||||
|
<cohesion>Prefer a single source of truth for each rule; avoid duplicated instructions</cohesion>
|
||||||
|
<scope>Prefer least privilege; keep file restrictions aligned with purpose</scope>
|
||||||
|
<clarity>Define acceptance criteria and validation gates for typical tasks</clarity>
|
||||||
|
<handoffs>Define explicit boundaries and handoff points to other modes</handoffs>
|
||||||
|
<verbosity>Keep narrative brief; reserve detail for structured outputs and diffs</verbosity>
|
||||||
|
</defaults>
|
||||||
|
<per_mode_guidance>
|
||||||
|
<mode type="specialist_mode">
|
||||||
|
<notes>Tight scope, least privilege, clear boundaries; prefer small targeted changes</notes>
|
||||||
|
</mode>
|
||||||
|
<mode type="workflow_mode">
|
||||||
|
<notes>Step-by-step process with validation gates; ask clarifying questions only when necessary</notes>
|
||||||
|
</mode>
|
||||||
|
<mode type="analysis_mode">
|
||||||
|
<notes>Read-heavy; edits typically constrained to reporting or documentation outputs</notes>
|
||||||
|
</mode>
|
||||||
|
<mode type="creative_mode">
|
||||||
|
<notes>Broader creation scope; ensure examples and tests are included when applicable</notes>
|
||||||
|
</mode>
|
||||||
|
</per_mode_guidance>
|
||||||
|
</autonomy_configuration>
|
||||||
|
|
||||||
|
<permission_patterns>
|
||||||
|
<pattern name="documentation_only">
|
||||||
|
<description>For modes that only work with documentation</description>
|
||||||
|
<configuration>
|
||||||
|
groups:
|
||||||
|
- read
|
||||||
|
- - edit
|
||||||
|
- fileRegex: \.(md|mdx|rst|txt)$
|
||||||
|
description: Documentation files only
|
||||||
|
</configuration>
|
||||||
|
</pattern>
|
||||||
|
|
||||||
|
<pattern name="test_focused">
|
||||||
|
<description>For modes that work with test files</description>
|
||||||
|
<configuration>
|
||||||
|
groups:
|
||||||
|
- read
|
||||||
|
- command
|
||||||
|
- - edit
|
||||||
|
- fileRegex: (__tests__/.*|__mocks__/.*|.*\.test\.(ts|tsx|js|jsx)$|.*\.spec\.(ts|tsx|js|jsx)$)
|
||||||
|
description: Test files and mocks
|
||||||
|
</configuration>
|
||||||
|
</pattern>
|
||||||
|
|
||||||
|
<pattern name="config_management">
|
||||||
|
<description>For modes that manage configuration</description>
|
||||||
|
<configuration>
|
||||||
|
groups:
|
||||||
|
- read
|
||||||
|
- - edit
|
||||||
|
- fileRegex: (.*\.config\.(js|ts|json)|.*rc\.json|.*\.yaml|.*\.yml|\.env\.example)$
|
||||||
|
description: Configuration files (not .env)
|
||||||
|
</configuration>
|
||||||
|
</pattern>
|
||||||
|
|
||||||
|
<pattern name="full_stack">
|
||||||
|
<description>For modes that need broad access</description>
|
||||||
|
<configuration>
|
||||||
|
groups:
|
||||||
|
- read
|
||||||
|
- edit # No restrictions
|
||||||
|
- command
|
||||||
|
- browser
|
||||||
|
- mcp
|
||||||
|
</configuration>
|
||||||
|
</pattern>
|
||||||
|
</permission_patterns>
|
||||||
|
|
||||||
|
<naming_conventions>
|
||||||
|
<convention category="slug">
|
||||||
|
<rule>Use lowercase with hyphens</rule>
|
||||||
|
<good>api-dev, test-writer, docs-manager</good>
|
||||||
|
<bad>apiDev, test_writer, DocsManager</bad>
|
||||||
|
</convention>
|
||||||
|
|
||||||
|
<convention category="name">
|
||||||
|
<rule>Use title case with descriptive emoji</rule>
|
||||||
|
<good>🔧 API Developer, 📝 Documentation Writer</good>
|
||||||
|
<bad>api developer, DOCUMENTATION WRITER</bad>
|
||||||
|
</convention>
|
||||||
|
|
||||||
|
<convention category="emoji_selection">
|
||||||
|
<common_emojis>
|
||||||
|
<emoji meaning="testing">🧪</emoji>
|
||||||
|
<emoji meaning="documentation">📝</emoji>
|
||||||
|
<emoji meaning="design">🎨</emoji>
|
||||||
|
<emoji meaning="debugging">🪲</emoji>
|
||||||
|
<emoji meaning="building">🏗️</emoji>
|
||||||
|
<emoji meaning="security">🔒</emoji>
|
||||||
|
<emoji meaning="api">🔌</emoji>
|
||||||
|
<emoji meaning="database">🗄️</emoji>
|
||||||
|
<emoji meaning="performance">⚡</emoji>
|
||||||
|
<emoji meaning="configuration">⚙️</emoji>
|
||||||
|
</common_emojis>
|
||||||
|
</convention>
|
||||||
|
</naming_conventions>
|
||||||
|
|
||||||
|
<integration_guidelines>
|
||||||
|
<guideline name="orchestrator_compatibility">
|
||||||
|
<description>Ensure whenToUse/whenNotToUse are clear for Orchestrator mode</description>
|
||||||
|
<checklist>
|
||||||
|
<item>Specify concrete task types the mode handles</item>
|
||||||
|
<item>Include trigger keywords or phrases</item>
|
||||||
|
<item>Differentiate from similar modes</item>
|
||||||
|
<item>Mention specific file types or areas</item>
|
||||||
|
<item>Define whenNotToUse with negative triggers and explicit handoffs</item>
|
||||||
|
<item>State stop/ask/handoff rules</item>
|
||||||
|
<item>State default verbosity policy (low narrative; verbose diffs)</item>
|
||||||
|
</checklist>
|
||||||
|
</guideline>
|
||||||
|
|
||||||
|
<guideline name="stop_and_handoff_rules">
|
||||||
|
<description>Define explicit stop conditions, confirmation thresholds, and handoff/ask triggers</description>
|
||||||
|
<checklist>
|
||||||
|
<item>Done-ness: acceptance criteria and validation gates are defined</item>
|
||||||
|
<item>Handoff rules to other modes or “ask a clarifying question” conditions are explicit</item>
|
||||||
|
<item>Boundaries, risks, and validation gates are documented</item>
|
||||||
|
</checklist>
|
||||||
|
</guideline>
|
||||||
|
|
||||||
|
<guideline name="verbosity_policy">
|
||||||
|
<description>Set verbosity defaults to keep narrative short and code edits clear</description>
|
||||||
|
<checklist>
|
||||||
|
<item>Low narrative verbosity in status/progress text</item>
|
||||||
|
<item>High detail only inside code/diffs and structured outputs</item>
|
||||||
|
<item>Code clarity over cleverness; avoid code-golf and cryptic names</item>
|
||||||
|
</checklist>
|
||||||
|
</guideline>
|
||||||
|
|
||||||
|
<guideline name="mode_boundaries">
|
||||||
|
<description>Define clear boundaries between modes</description>
|
||||||
|
<checklist>
|
||||||
|
<item>Avoid overlapping responsibilities</item>
|
||||||
|
<item>Make handoff points explicit</item>
|
||||||
|
<item>Switch modes when appropriate (mechanism varies)</item>
|
||||||
|
<item>Document mode interactions</item>
|
||||||
|
</checklist>
|
||||||
|
</guideline>
|
||||||
|
</integration_guidelines>
|
||||||
|
</mode_configuration_patterns>
|
||||||
@@ -0,0 +1,293 @@
|
|||||||
|
<instruction_file_templates>
|
||||||
|
<overview>
|
||||||
|
Templates and examples for creating XML instruction files that provide
|
||||||
|
detailed guidance for each mode's behavior and workflows.
|
||||||
|
|
||||||
|
Requirements:
|
||||||
|
- Do not reference runtime implementation details (function names, command names, UI entry points, or execution syntax).
|
||||||
|
- Do not duplicate operational policies that are already defined by the runtime/system prompt.
|
||||||
|
- Focus on workflow intent, required artifacts, decision criteria, and validation expectations.
|
||||||
|
</overview>
|
||||||
|
|
||||||
|
<file_organization>
|
||||||
|
<principle>Number files to indicate execution order</principle>
|
||||||
|
<principle>Use descriptive names that indicate content</principle>
|
||||||
|
<principle>Keep related instructions together</principle>
|
||||||
|
<standard_structure>
|
||||||
|
<file>1_workflow.xml - Main workflow and processes</file>
|
||||||
|
<file>2_best_practices.xml - Guidelines and conventions</file>
|
||||||
|
<file>3_common_patterns.xml - Reusable code patterns</file>
|
||||||
|
<file>4_decision_guidance.xml - Decision criteria and guardrails</file>
|
||||||
|
<file>5_examples.xml - Complete workflow examples</file>
|
||||||
|
<file>6_error_handling.xml - Error scenarios and recovery</file>
|
||||||
|
<file>7_communication.xml - User interaction guidelines</file>
|
||||||
|
</standard_structure>
|
||||||
|
</file_organization>
|
||||||
|
|
||||||
|
<workflow_file_template>
|
||||||
|
<description>Template for main workflow files (1_workflow.xml)</description>
|
||||||
|
<template>
|
||||||
|
<workflow_instructions>
|
||||||
|
<mode_overview>
|
||||||
|
Brief description of what this mode does and its primary purpose
|
||||||
|
</mode_overview>
|
||||||
|
|
||||||
|
<initialization_steps>
|
||||||
|
<step number="1">
|
||||||
|
<action>Understand the user's request</action>
|
||||||
|
<details>
|
||||||
|
Parse the user's input to identify:
|
||||||
|
- Primary objective
|
||||||
|
- Specific requirements
|
||||||
|
- Constraints or limitations
|
||||||
|
</details>
|
||||||
|
</step>
|
||||||
|
|
||||||
|
<step number="2">
|
||||||
|
<action>Gather necessary context</action>
|
||||||
|
<details>
|
||||||
|
Review the minimal set of repository materials needed to act safely.
|
||||||
|
Prefer extending existing guidance over introducing duplicated rules.
|
||||||
|
</details>
|
||||||
|
</step>
|
||||||
|
</initialization_steps>
|
||||||
|
|
||||||
|
<main_workflow>
|
||||||
|
<phase name="analysis">
|
||||||
|
<description>Analyze the current state and requirements</description>
|
||||||
|
<steps>
|
||||||
|
<step>Identify affected components</step>
|
||||||
|
<step>Assess impact of changes</step>
|
||||||
|
<step>Plan implementation approach</step>
|
||||||
|
</steps>
|
||||||
|
</phase>
|
||||||
|
|
||||||
|
<phase name="implementation">
|
||||||
|
<description>Execute the planned changes</description>
|
||||||
|
<steps>
|
||||||
|
<step>Create/modify necessary files</step>
|
||||||
|
<step>Ensure consistency across codebase</step>
|
||||||
|
<step>Add appropriate documentation</step>
|
||||||
|
</steps>
|
||||||
|
</phase>
|
||||||
|
|
||||||
|
<phase name="validation">
|
||||||
|
<description>Verify the implementation</description>
|
||||||
|
<steps>
|
||||||
|
<step>Check for errors or inconsistencies</step>
|
||||||
|
<step>Validate against requirements</step>
|
||||||
|
<step>Ensure no regressions</step>
|
||||||
|
</steps>
|
||||||
|
</phase>
|
||||||
|
</main_workflow>
|
||||||
|
|
||||||
|
<completion_criteria>
|
||||||
|
<criterion>All requirements have been addressed</criterion>
|
||||||
|
<criterion>Code follows project conventions</criterion>
|
||||||
|
<criterion>Changes are properly documented</criterion>
|
||||||
|
<criterion>No breaking changes introduced</criterion>
|
||||||
|
</completion_criteria>
|
||||||
|
</workflow_instructions>
|
||||||
|
</template>
|
||||||
|
</workflow_file_template>
|
||||||
|
|
||||||
|
<best_practices_template>
|
||||||
|
<description>Template for best practices files (2_best_practices.xml)</description>
|
||||||
|
<template>
|
||||||
|
<best_practices>
|
||||||
|
<general_principles>
|
||||||
|
<principle priority="high">
|
||||||
|
<name>Principle Name</name>
|
||||||
|
<description>Detailed explanation of the principle</description>
|
||||||
|
<rationale>Why this principle is important</rationale>
|
||||||
|
<example>
|
||||||
|
<scenario>When this applies</scenario>
|
||||||
|
<good>Correct approach</good>
|
||||||
|
<bad>What to avoid</bad>
|
||||||
|
</example>
|
||||||
|
</principle>
|
||||||
|
</general_principles>
|
||||||
|
|
||||||
|
<code_conventions>
|
||||||
|
<convention category="naming">
|
||||||
|
<rule>Specific naming convention</rule>
|
||||||
|
<examples>
|
||||||
|
<good>goodExampleName</good>
|
||||||
|
<bad>bad_example-name</bad>
|
||||||
|
</examples>
|
||||||
|
</convention>
|
||||||
|
|
||||||
|
<convention category="structure">
|
||||||
|
<rule>How to structure code/files</rule>
|
||||||
|
<template>
|
||||||
|
// Example structure
|
||||||
|
</template>
|
||||||
|
</convention>
|
||||||
|
</code_conventions>
|
||||||
|
|
||||||
|
<common_pitfalls>
|
||||||
|
<pitfall>
|
||||||
|
<description>Common mistake to avoid</description>
|
||||||
|
<why_problematic>Explanation of issues it causes</why_problematic>
|
||||||
|
<correct_approach>How to do it properly</correct_approach>
|
||||||
|
</pitfall>
|
||||||
|
</common_pitfalls>
|
||||||
|
|
||||||
|
<quality_checklist>
|
||||||
|
<category name="before_starting">
|
||||||
|
<item>Understand requirements fully</item>
|
||||||
|
<item>Check existing implementations</item>
|
||||||
|
</category>
|
||||||
|
<category name="during_implementation">
|
||||||
|
<item>Follow established patterns</item>
|
||||||
|
<item>Write clear documentation</item>
|
||||||
|
</category>
|
||||||
|
<category name="before_completion">
|
||||||
|
<item>Review all changes</item>
|
||||||
|
<item>Verify requirements met</item>
|
||||||
|
</category>
|
||||||
|
</quality_checklist>
|
||||||
|
</best_practices>
|
||||||
|
</template>
|
||||||
|
</best_practices_template>
|
||||||
|
|
||||||
|
<decision_guidance_template>
|
||||||
|
<description>Template for decision criteria and guardrails (4_decision_guidance.xml)</description>
|
||||||
|
<template>
|
||||||
|
<decision_guidance>
|
||||||
|
<principles>
|
||||||
|
<principle>Do not include runtime implementation details (no function names, command names, UI entry points, or execution syntax)</principle>
|
||||||
|
<principle>Prefer the smallest change that satisfies the request</principle>
|
||||||
|
<principle>Prefer a single source of truth; avoid duplicated rules across files</principle>
|
||||||
|
<principle>Ask a clarifying question only when critical ambiguity remains</principle>
|
||||||
|
</principles>
|
||||||
|
|
||||||
|
<boundaries>
|
||||||
|
<rule>Define clear responsibilities and explicit handoff points to other modes</rule>
|
||||||
|
</boundaries>
|
||||||
|
|
||||||
|
<validation>
|
||||||
|
<rule>After changes, scan for contradictions and update examples to match</rule>
|
||||||
|
</validation>
|
||||||
|
</decision_guidance>
|
||||||
|
</template>
|
||||||
|
</decision_guidance_template>
|
||||||
|
|
||||||
|
<examples_file_template>
|
||||||
|
<description>Template for example files (5_examples.xml)</description>
|
||||||
|
<template>
|
||||||
|
<complete_examples>
|
||||||
|
<example name="descriptive_example_name">
|
||||||
|
<scenario>
|
||||||
|
Detailed description of the use case this example covers
|
||||||
|
</scenario>
|
||||||
|
|
||||||
|
<user_request>
|
||||||
|
The initial request from the user
|
||||||
|
</user_request>
|
||||||
|
|
||||||
|
<workflow>
|
||||||
|
<step number="1">
|
||||||
|
<description>First step description</description>
|
||||||
|
<approach>
|
||||||
|
Identify the relevant existing files/sections that need to change.
|
||||||
|
Outcome: a shortlist of candidate paths or sections.
|
||||||
|
</approach>
|
||||||
|
<expected_outcome>What we learn from this step</expected_outcome>
|
||||||
|
</step>
|
||||||
|
|
||||||
|
<step number="2">
|
||||||
|
<description>Second step description</description>
|
||||||
|
<approach>
|
||||||
|
Review the top candidates and confirm the exact area to modify.
|
||||||
|
Outcome: precise target sections and constraints.
|
||||||
|
</approach>
|
||||||
|
<analysis>How we interpret the results</analysis>
|
||||||
|
</step>
|
||||||
|
|
||||||
|
<step number="3">
|
||||||
|
<description>Implementation step</description>
|
||||||
|
<approach>
|
||||||
|
Apply the planned changes (localized edits when possible; full rewrites only when intentional).
|
||||||
|
Outcome: required changes applied to the repository.
|
||||||
|
</approach>
|
||||||
|
</step>
|
||||||
|
</workflow>
|
||||||
|
|
||||||
|
<completion>
|
||||||
|
Provide a concise summary of what was accomplished and how it addresses the user's request.
|
||||||
|
</completion>
|
||||||
|
|
||||||
|
<key_takeaways>
|
||||||
|
<takeaway>Important lesson from this example</takeaway>
|
||||||
|
<takeaway>Pattern that can be reused</takeaway>
|
||||||
|
</key_takeaways>
|
||||||
|
</example>
|
||||||
|
</complete_examples>
|
||||||
|
</template>
|
||||||
|
</examples_file_template>
|
||||||
|
|
||||||
|
<communication_template>
|
||||||
|
<description>Template for communication guidelines (7_communication.xml)</description>
|
||||||
|
<template>
|
||||||
|
<communication_guidelines>
|
||||||
|
<tone_and_style>
|
||||||
|
<principle>Be direct and technical, not conversational</principle>
|
||||||
|
<principle>Focus on actions taken and results achieved</principle>
|
||||||
|
<avoid>
|
||||||
|
<phrase>Great! I'll help you with that...</phrase>
|
||||||
|
<phrase>Certainly! Let me...</phrase>
|
||||||
|
<phrase>Sure thing!</phrase>
|
||||||
|
</avoid>
|
||||||
|
<prefer>
|
||||||
|
<phrase>I'll analyze the codebase to...</phrase>
|
||||||
|
<phrase>Implementing the requested changes...</phrase>
|
||||||
|
<phrase>The analysis shows...</phrase>
|
||||||
|
</prefer>
|
||||||
|
</tone_and_style>
|
||||||
|
|
||||||
|
<verbosity>
|
||||||
|
<policy>Keep narrative brief; prefer concise status updates</policy>
|
||||||
|
<policy>Provide high detail only inside code/diffs and structured outputs</policy>
|
||||||
|
<policy>Favor clarity over cleverness; avoid code-golf and cryptic names</policy>
|
||||||
|
</verbosity>
|
||||||
|
|
||||||
|
<user_interaction>
|
||||||
|
<when_to_ask_questions>
|
||||||
|
<scenario>Missing critical information</scenario>
|
||||||
|
<scenario>Multiple valid approaches exist</scenario>
|
||||||
|
<scenario>Potential breaking changes</scenario>
|
||||||
|
</when_to_ask_questions>
|
||||||
|
|
||||||
|
<question_format>
|
||||||
|
<guideline>Be specific about what you need</guideline>
|
||||||
|
<guideline>Provide actionable options</guideline>
|
||||||
|
<guideline>Explain implications of choices</guideline>
|
||||||
|
</question_format>
|
||||||
|
</user_interaction>
|
||||||
|
|
||||||
|
<progress_updates>
|
||||||
|
<when>During long-running operations</when>
|
||||||
|
<format>
|
||||||
|
<update>Analyzing [X] files for [purpose]...</update>
|
||||||
|
<update>Implementing [feature] in [location]...</update>
|
||||||
|
<update>Validating changes against [criteria]...</update>
|
||||||
|
</format>
|
||||||
|
</progress_updates>
|
||||||
|
|
||||||
|
<completion_messages>
|
||||||
|
<structure>
|
||||||
|
<element>What was accomplished</element>
|
||||||
|
<element>Key changes made</element>
|
||||||
|
<element>Any important notes or warnings</element>
|
||||||
|
</structure>
|
||||||
|
<avoid>
|
||||||
|
<element>Questions at the end</element>
|
||||||
|
<element>Offers for further assistance</element>
|
||||||
|
<element>Conversational closings</element>
|
||||||
|
</avoid>
|
||||||
|
</completion_messages>
|
||||||
|
</communication_guidelines>
|
||||||
|
</template>
|
||||||
|
</communication_template>
|
||||||
|
</instruction_file_templates>
|
||||||
@@ -0,0 +1,91 @@
|
|||||||
|
<complete_examples>
|
||||||
|
<overview>
|
||||||
|
Canonical examples for creating and editing Roo Code modes. Each example demonstrates structured workflows, least-privilege configuration, contradiction resolution, and completion formatting, without referencing runtime implementation details.
|
||||||
|
</overview>
|
||||||
|
|
||||||
|
<example name="mode_editing_enhancement">
|
||||||
|
<scenario>
|
||||||
|
Edit the Test mode to add benchmark testing and performance guidance using Vitest's bench API.
|
||||||
|
</scenario>
|
||||||
|
<user_request>
|
||||||
|
I want to edit the test mode to add benchmark testing support.
|
||||||
|
</user_request>
|
||||||
|
<workflow>
|
||||||
|
<step number="1">
|
||||||
|
<description>Clarify scope and features</description>
|
||||||
|
<guidance>
|
||||||
|
Ask the user a focused clarifying question to confirm which scope/features to include; provide 2–4 actionable options. Outcome: selected scope.
|
||||||
|
</guidance>
|
||||||
|
<expected_outcome>User selects: Add benchmark testing with Vitest bench API</expected_outcome>
|
||||||
|
</step>
|
||||||
|
|
||||||
|
<step number="2">
|
||||||
|
<description>Immerse in current mode config and instructions</description>
|
||||||
|
<guidance>
|
||||||
|
Review .roomodes, inventory .roo/rules-test recursively, and review .roo/rules-test/1_workflow.xml. Outcome: confirm roleDefinition, file restrictions, and existing workflows.
|
||||||
|
</guidance>
|
||||||
|
<analysis>Confirm roleDefinition, file restrictions, and existing workflows.</analysis>
|
||||||
|
</step>
|
||||||
|
|
||||||
|
<step number="3">
|
||||||
|
<description>Update roleDefinition in .roomodes</description>
|
||||||
|
<guidance>
|
||||||
|
Edit .roomodes to update the roleDefinition, adding benchmark testing and performance guidance topics. Outcome: roleDefinition updated to include performance/bench themes.
|
||||||
|
</guidance>
|
||||||
|
</step>
|
||||||
|
|
||||||
|
<step number="4">
|
||||||
|
<description>Extend file restrictions to include .bench files</description>
|
||||||
|
<guidance>
|
||||||
|
Edit .roomodes to extend the fileRegex to include .bench.(ts|tsx|js|jsx) and update the description accordingly. Outcome: file restrictions now cover benchmark files.
|
||||||
|
</guidance>
|
||||||
|
</step>
|
||||||
|
|
||||||
|
<step number="5">
|
||||||
|
<description>Create benchmark guidance file</description>
|
||||||
|
<guidance>
|
||||||
|
Create a new file at .roo/rules-test/5_benchmark_testing.xml with guidance and examples. Outcome: new guidance file available to the mode.
|
||||||
|
</guidance>
|
||||||
|
<artifact_sample>
|
||||||
|
<benchmark_testing_guide>
|
||||||
|
<overview>Guidelines for performance benchmarks using Vitest bench API</overview>
|
||||||
|
<benchmark_patterns>
|
||||||
|
<pattern name="basic_benchmark">
|
||||||
|
<description>Basic structure</description>
|
||||||
|
<example>
|
||||||
|
import { bench, describe } from 'vitest';
|
||||||
|
|
||||||
|
|
||||||
|
describe('Array operations', () => {
|
||||||
|
bench('Array.push', () => {
|
||||||
|
const arr: number[] = [];
|
||||||
|
for (let i = 0; i < 1000; i++) arr.push(i);
|
||||||
|
});
|
||||||
|
|
||||||
|
bench('Array spread', () => {
|
||||||
|
let arr: number[] = [];
|
||||||
|
for (let i = 0; i < 1000; i++) arr = [...arr, i];
|
||||||
|
});
|
||||||
|
});
|
||||||
|
</example>
|
||||||
|
</pattern>
|
||||||
|
</benchmark_patterns>
|
||||||
|
<best_practices>
|
||||||
|
<practice>Use meaningful names and isolate benchmarks</practice>
|
||||||
|
<practice>Document expectations and thresholds</practice>
|
||||||
|
</best_practices>
|
||||||
|
</benchmark_testing_guide>
|
||||||
|
</artifact_sample>
|
||||||
|
</step>
|
||||||
|
</workflow>
|
||||||
|
|
||||||
|
<completion>
|
||||||
|
Provide a concise summary of what was accomplished and how it addresses the user's request.
|
||||||
|
</completion>
|
||||||
|
|
||||||
|
<key_takeaways>
|
||||||
|
<takeaway>Important lesson from this example</takeaway>
|
||||||
|
<takeaway>Pattern that can be reused</takeaway>
|
||||||
|
</key_takeaways>
|
||||||
|
</example>
|
||||||
|
</complete_examples>
|
||||||
@@ -0,0 +1,186 @@
|
|||||||
|
<mode_testing_validation>
|
||||||
|
<overview>
|
||||||
|
Guidelines for testing and validating newly created modes to ensure they function correctly and integrate well with the Roo Code ecosystem.
|
||||||
|
</overview>
|
||||||
|
|
||||||
|
<validation_checklist>
|
||||||
|
<category name="configuration_validation">
|
||||||
|
<item priority="critical">
|
||||||
|
<check>Mode slug is unique and follows naming conventions</check>
|
||||||
|
<validation>No spaces, lowercase, hyphens only</validation>
|
||||||
|
</item>
|
||||||
|
<item priority="critical">
|
||||||
|
<check>All required fields are present and non-empty</check>
|
||||||
|
<fields>slug, name, roleDefinition, groups</fields>
|
||||||
|
</item>
|
||||||
|
<item priority="critical">
|
||||||
|
<check>Avoid large customInstructions blocks in .roomodes</check>
|
||||||
|
<validation>
|
||||||
|
Prefer storing substantial mode guidance in XML files under <code>.roo/rules-[slug]/</code>.
|
||||||
|
Small, high-level glue text in <code>customInstructions</code> is acceptable when needed.
|
||||||
|
</validation>
|
||||||
|
</item>
|
||||||
|
<item priority="high">
|
||||||
|
<check>File restrictions use valid regex patterns</check>
|
||||||
|
<test_method>Validate by comparing the regex pattern against the intended file sets; confirm patterns match intended files and avoid overbroad matches.</test_method>
|
||||||
|
</item>
|
||||||
|
<item priority="high">
|
||||||
|
<check>whenToUse clearly differentiates from other modes</check>
|
||||||
|
<validation>Compare with existing mode descriptions</validation>
|
||||||
|
</item>
|
||||||
|
</category>
|
||||||
|
|
||||||
|
<category name="instruction_validation">
|
||||||
|
<item>
|
||||||
|
<check>XML files are well-formed and valid</check>
|
||||||
|
<validation>No syntax errors, proper closing tags</validation>
|
||||||
|
</item>
|
||||||
|
<item>
|
||||||
|
<check>Instructions follow XML best practices</check>
|
||||||
|
<validation>Semantic tag names, proper nesting</validation>
|
||||||
|
</item>
|
||||||
|
<item>
|
||||||
|
<check>Examples avoid runtime implementation details</check>
|
||||||
|
<validation>Examples align with current permissions and constraints</validation>
|
||||||
|
</item>
|
||||||
|
<item>
|
||||||
|
<check>File paths in examples are consistent</check>
|
||||||
|
<validation>Use project-relative paths</validation>
|
||||||
|
</item>
|
||||||
|
</category>
|
||||||
|
|
||||||
|
<category name="functional_testing">
|
||||||
|
<item>
|
||||||
|
<check>Mode appears in mode list</check>
|
||||||
|
<test>Switch to the new mode and verify it loads</test>
|
||||||
|
</item>
|
||||||
|
<item>
|
||||||
|
<check>Permissions work as expected</check>
|
||||||
|
<test>Verify representative actions for each permission category</test>
|
||||||
|
</item>
|
||||||
|
<item>
|
||||||
|
<check>File restrictions are enforced</check>
|
||||||
|
<test>Attempt to edit allowed and restricted files</test>
|
||||||
|
</item>
|
||||||
|
<item>
|
||||||
|
<check>Mode handles edge cases gracefully</check>
|
||||||
|
<test>Test with minimal input, errors, edge cases</test>
|
||||||
|
</item>
|
||||||
|
</category>
|
||||||
|
</validation_checklist>
|
||||||
|
|
||||||
|
<testing_workflow>
|
||||||
|
<step number="1">
|
||||||
|
<title>Configuration Testing</title>
|
||||||
|
<actions>
|
||||||
|
<action>Verify mode appears in available modes list</action>
|
||||||
|
<action>Check that mode metadata displays correctly</action>
|
||||||
|
<action>Confirm mode can be activated</action>
|
||||||
|
</actions>
|
||||||
|
<verification>Confirm via user feedback. If unclear, ask a focused clarifying question with options like: "Visible and switchable", "Not visible", or "Visible but errors".</verification>
|
||||||
|
</step>
|
||||||
|
|
||||||
|
<step number="2">
|
||||||
|
<title>Permission Testing</title>
|
||||||
|
<test_cases>
|
||||||
|
<test case="read_permissions">
|
||||||
|
<action>Verify read access works for representative files</action>
|
||||||
|
<expected>All read operations should work</expected>
|
||||||
|
</test>
|
||||||
|
<test case="edit_restrictions">
|
||||||
|
<action>Try editing allowed file types</action>
|
||||||
|
<expected>Edits succeed for matching patterns</expected>
|
||||||
|
</test>
|
||||||
|
<test case="edit_restrictions_negative">
|
||||||
|
<action>Try editing restricted file types</action>
|
||||||
|
<expected>An explicit permission/restriction error for non-matching files</expected>
|
||||||
|
</test>
|
||||||
|
</test_cases>
|
||||||
|
</step>
|
||||||
|
|
||||||
|
<step number="3">
|
||||||
|
<title>Workflow Testing</title>
|
||||||
|
<actions>
|
||||||
|
<action>Execute main workflow from start to finish</action>
|
||||||
|
<action>Test each decision point</action>
|
||||||
|
<action>Verify error handling</action>
|
||||||
|
<action>Check completion criteria</action>
|
||||||
|
</actions>
|
||||||
|
</step>
|
||||||
|
|
||||||
|
<step number="4">
|
||||||
|
<title>Integration Testing</title>
|
||||||
|
<areas>
|
||||||
|
<area>Orchestrator mode compatibility</area>
|
||||||
|
<area>Mode switching functionality</area>
|
||||||
|
<area>Capability handoff between modes</area>
|
||||||
|
<area>Consistent behavior with other modes</area>
|
||||||
|
</areas>
|
||||||
|
</step>
|
||||||
|
</testing_workflow>
|
||||||
|
|
||||||
|
<common_issues>
|
||||||
|
<issue type="configuration">
|
||||||
|
<problem>Mode doesn't appear in list</problem>
|
||||||
|
<causes>
|
||||||
|
<cause>Syntax error in YAML</cause>
|
||||||
|
<cause>Invalid mode slug</cause>
|
||||||
|
<cause>File not saved</cause>
|
||||||
|
</causes>
|
||||||
|
<solution>Check YAML syntax, validate slug format</solution>
|
||||||
|
</issue>
|
||||||
|
|
||||||
|
<issue type="permissions">
|
||||||
|
<problem>File restriction not working</problem>
|
||||||
|
<causes>
|
||||||
|
<cause>Invalid regex pattern</cause>
|
||||||
|
<cause>Escaping issues in regex</cause>
|
||||||
|
<cause>Wrong file path format</cause>
|
||||||
|
</causes>
|
||||||
|
<solution>Test regex pattern, use proper escaping</solution>
|
||||||
|
<example>
|
||||||
|
# Wrong: *.ts (glob pattern)
|
||||||
|
|
||||||
|
# Right: .*\.ts$ (regex pattern)
|
||||||
|
</example>
|
||||||
|
</issue>
|
||||||
|
|
||||||
|
<issue type="behavior">
|
||||||
|
<problem>Mode not following instructions</problem>
|
||||||
|
<causes>
|
||||||
|
<cause>Instructions not in .roo/rules-[slug]/ folder</cause>
|
||||||
|
<cause>XML parsing errors</cause>
|
||||||
|
<cause>Conflicting instructions</cause>
|
||||||
|
</causes>
|
||||||
|
<solution>Verify file locations and XML validity</solution>
|
||||||
|
</issue>
|
||||||
|
</common_issues>
|
||||||
|
|
||||||
|
<debugging_practices>
|
||||||
|
<practice>
|
||||||
|
<name>Directory/file inventory</name>
|
||||||
|
<usage>Verify instruction files exist in the correct location</usage>
|
||||||
|
<guidance>Check the .roo directory structure and ensure the expected rules-[slug] folder and XML files exist.</guidance>
|
||||||
|
</practice>
|
||||||
|
|
||||||
|
<practice>
|
||||||
|
<name>Configuration review</name>
|
||||||
|
<usage>Check mode configuration syntax</usage>
|
||||||
|
<guidance>Review .roomodes to validate YAML structure and entries for the target mode.</guidance>
|
||||||
|
</practice>
|
||||||
|
|
||||||
|
<practice>
|
||||||
|
<name>Regex validation</name>
|
||||||
|
<usage>Test file restriction patterns</usage>
|
||||||
|
<guidance>Use targeted checks conceptually to confirm fileRegex patterns match intended files and exclude others.</guidance>
|
||||||
|
</practice>
|
||||||
|
</debugging_practices>
|
||||||
|
|
||||||
|
<best_practices>
|
||||||
|
<practice>Test incrementally as you build the mode</practice>
|
||||||
|
<practice>Start with minimal configuration and add complexity</practice>
|
||||||
|
<practice>Document any special requirements or dependencies</practice>
|
||||||
|
<practice>Consider edge cases and error scenarios</practice>
|
||||||
|
<practice>Get feedback from potential users of the mode</practice>
|
||||||
|
</best_practices>
|
||||||
|
</mode_testing_validation>
|
||||||
@@ -0,0 +1,194 @@
|
|||||||
|
<validation_cohesion_checking>
|
||||||
|
<overview>
|
||||||
|
Guidelines for thoroughly validating mode changes to ensure cohesion,
|
||||||
|
consistency, and prevent contradictions across all mode components.
|
||||||
|
</overview>
|
||||||
|
|
||||||
|
<validation_principles>
|
||||||
|
<principle name="comprehensive_review">
|
||||||
|
<description>
|
||||||
|
Every change must be reviewed in context of the entire mode
|
||||||
|
</description>
|
||||||
|
<checklist>
|
||||||
|
<item>Read all existing XML instruction files</item>
|
||||||
|
<item>Verify new changes align with existing patterns</item>
|
||||||
|
<item>Check for duplicate or conflicting instructions</item>
|
||||||
|
<item>Ensure terminology is consistent throughout</item>
|
||||||
|
</checklist>
|
||||||
|
</principle>
|
||||||
|
|
||||||
|
<principle name="focused_questioning">
|
||||||
|
<description>
|
||||||
|
Ask focused clarifying questions only when needed to de-risk the work
|
||||||
|
</description>
|
||||||
|
<when_to_ask>
|
||||||
|
<scenario>Critical details are missing (cannot proceed safely)</scenario>
|
||||||
|
<scenario>Multiple valid approaches exist and the tradeoffs matter</scenario>
|
||||||
|
<scenario>Proposed changes are risky/irreversible (permissions, deletions, broad refactors)</scenario>
|
||||||
|
<scenario>A change may require widening permissions or fileRegex patterns</scenario>
|
||||||
|
</when_to_ask>
|
||||||
|
<example>
|
||||||
|
In practice: ask a focused question with 2–4 actionable options.
|
||||||
|
Example:
|
||||||
|
- Question: "This change may affect file permissions. Should we also update the fileRegex patterns?"
|
||||||
|
- Options:
|
||||||
|
1) "Yes, include the new file types in the regex"
|
||||||
|
2) "No, keep current restrictions"
|
||||||
|
3) "I need to list the file types I’ll work with"
|
||||||
|
4) "Show me the current restrictions first"
|
||||||
|
</example>
|
||||||
|
</principle>
|
||||||
|
|
||||||
|
<principle name="contradiction_detection">
|
||||||
|
<description>
|
||||||
|
Actively search for and resolve contradictions
|
||||||
|
</description>
|
||||||
|
<common_contradictions>
|
||||||
|
<contradiction>
|
||||||
|
<type>Permission Mismatch</type>
|
||||||
|
<description>Instructions reference permissions the mode doesn't have</description>
|
||||||
|
<resolution>Either grant the permission or update the instructions</resolution>
|
||||||
|
</contradiction>
|
||||||
|
<contradiction>
|
||||||
|
<type>Workflow Conflicts</type>
|
||||||
|
<description>Different XML files describe conflicting workflows</description>
|
||||||
|
<resolution>Consolidate workflows and ensure single source of truth</resolution>
|
||||||
|
</contradiction>
|
||||||
|
<contradiction>
|
||||||
|
<type>Role Confusion</type>
|
||||||
|
<description>Mode's roleDefinition doesn't match its actual scope/permissions</description>
|
||||||
|
<resolution>Update roleDefinition to accurately reflect the mode's purpose</resolution>
|
||||||
|
</contradiction>
|
||||||
|
</common_contradictions>
|
||||||
|
</principle>
|
||||||
|
</validation_principles>
|
||||||
|
|
||||||
|
<validation_workflow>
|
||||||
|
<phase name="pre_change_analysis">
|
||||||
|
<description>Before making any changes</description>
|
||||||
|
<steps>
|
||||||
|
<step>Read and understand all existing mode files</step>
|
||||||
|
<step>Create a mental model of current mode behavior</step>
|
||||||
|
<step>Identify potential impact areas</step>
|
||||||
|
<step>Ask clarifying questions about intended changes</step>
|
||||||
|
</steps>
|
||||||
|
</phase>
|
||||||
|
|
||||||
|
<phase name="change_implementation">
|
||||||
|
<description>While making changes</description>
|
||||||
|
<steps>
|
||||||
|
<step>Document each change and its rationale</step>
|
||||||
|
<step>Cross-reference with other files after each change</step>
|
||||||
|
<step>Verify examples still work with new changes</step>
|
||||||
|
<step>Update related documentation immediately</step>
|
||||||
|
</steps>
|
||||||
|
</phase>
|
||||||
|
|
||||||
|
<phase name="post_change_validation">
|
||||||
|
<description>After changes are complete</description>
|
||||||
|
<validation_checklist>
|
||||||
|
<category name="structural_validation">
|
||||||
|
<check>All XML files are well-formed and valid</check>
|
||||||
|
<check>File naming follows established patterns</check>
|
||||||
|
<check>Tag names are consistent across files</check>
|
||||||
|
<check>No orphaned or unused instructions</check>
|
||||||
|
</category>
|
||||||
|
|
||||||
|
<category name="content_validation">
|
||||||
|
<check>roleDefinition accurately describes the mode</check>
|
||||||
|
<check>whenToUse is clear and distinguishable</check>
|
||||||
|
<check>Permissions match instruction requirements</check>
|
||||||
|
<check>File restrictions align with mode purpose</check>
|
||||||
|
<check>Examples are accurate and functional</check>
|
||||||
|
</category>
|
||||||
|
|
||||||
|
<category name="integration_validation">
|
||||||
|
<check>Mode boundaries are well-defined</check>
|
||||||
|
<check>Handoff points to other modes are clear</check>
|
||||||
|
<check>No overlap with other modes' responsibilities</check>
|
||||||
|
<check>Orchestrator can correctly route to this mode</check>
|
||||||
|
</category>
|
||||||
|
</validation_checklist>
|
||||||
|
</phase>
|
||||||
|
</validation_workflow>
|
||||||
|
|
||||||
|
<cohesion_patterns>
|
||||||
|
<pattern name="consistent_voice">
|
||||||
|
<description>Maintain consistent tone and terminology</description>
|
||||||
|
<guidelines>
|
||||||
|
<guideline>Use the same terms for the same concepts throughout</guideline>
|
||||||
|
<guideline>Keep instruction style consistent across files</guideline>
|
||||||
|
<guideline>Maintain the same level of detail in similar sections</guideline>
|
||||||
|
</guidelines>
|
||||||
|
</pattern>
|
||||||
|
|
||||||
|
<pattern name="logical_flow">
|
||||||
|
<description>Ensure instructions flow logically</description>
|
||||||
|
<guidelines>
|
||||||
|
<guideline>Prerequisites come before dependent steps</guideline>
|
||||||
|
<guideline>Complex concepts build on simpler ones</guideline>
|
||||||
|
<guideline>Examples follow the explained patterns</guideline>
|
||||||
|
</guidelines>
|
||||||
|
</pattern>
|
||||||
|
|
||||||
|
<pattern name="complete_coverage">
|
||||||
|
<description>Ensure all aspects are covered without gaps</description>
|
||||||
|
<guidelines>
|
||||||
|
<guideline>Every mentioned concept has decision guidance (what/when) without runtime implementation details</guideline>
|
||||||
|
<guideline>All workflows have complete examples</guideline>
|
||||||
|
<guideline>Error scenarios are addressed</guideline>
|
||||||
|
</guidelines>
|
||||||
|
</pattern>
|
||||||
|
</cohesion_patterns>
|
||||||
|
|
||||||
|
<validation_questions>
|
||||||
|
<question_set name="before_changes">
|
||||||
|
<prompt>
|
||||||
|
Before we proceed with changes, ensure the main goal is clear. Suggested options:
|
||||||
|
- Add new functionality while keeping existing features
|
||||||
|
- Fix issues with current implementation
|
||||||
|
- Refactor for better organization
|
||||||
|
- Expand the mode's scope into new areas
|
||||||
|
</prompt>
|
||||||
|
</question_set>
|
||||||
|
|
||||||
|
<question_set name="during_changes">
|
||||||
|
<prompt>
|
||||||
|
This change might affect other parts of the mode. Choose an approach:
|
||||||
|
- Update all affected areas to maintain consistency
|
||||||
|
- Keep the existing behavior for backward compatibility
|
||||||
|
- Create a migration path from old to new behavior
|
||||||
|
- Review the impact first
|
||||||
|
</prompt>
|
||||||
|
</question_set>
|
||||||
|
|
||||||
|
<question_set name="after_changes">
|
||||||
|
<prompt>
|
||||||
|
Post-change testing focus areas:
|
||||||
|
- Test the new workflow end-to-end
|
||||||
|
- Verify file permissions work correctly
|
||||||
|
- Check integration with other modes
|
||||||
|
- Review all changes one more time
|
||||||
|
</prompt>
|
||||||
|
</question_set>
|
||||||
|
</validation_questions>
|
||||||
|
|
||||||
|
<red_flags>
|
||||||
|
<flag priority="high">
|
||||||
|
<description>Instructions reference permissions not in the mode's groups</description>
|
||||||
|
<action>Either add the permission group or remove/update the instruction</action>
|
||||||
|
</flag>
|
||||||
|
<flag priority="high">
|
||||||
|
<description>File regex doesn't match described file types</description>
|
||||||
|
<action>Update regex pattern to match intended files</action>
|
||||||
|
</flag>
|
||||||
|
<flag priority="medium">
|
||||||
|
<description>Examples don't follow stated best practices</description>
|
||||||
|
<action>Update examples to demonstrate best practices</action>
|
||||||
|
</flag>
|
||||||
|
<flag priority="medium">
|
||||||
|
<description>Duplicate instructions in different files</description>
|
||||||
|
<action>Consolidate to single location and reference</action>
|
||||||
|
</flag>
|
||||||
|
</red_flags>
|
||||||
|
</validation_cohesion_checking>
|
||||||
@@ -0,0 +1,51 @@
|
|||||||
|
<global_modes_reference>
|
||||||
|
<overview>
|
||||||
|
This reference documents how global (system-wide) modes work, where they live, and how they interact
|
||||||
|
with workspace-scoped modes.
|
||||||
|
</overview>
|
||||||
|
|
||||||
|
<locations>
|
||||||
|
<workspace>
|
||||||
|
<file>.roomodes</file>
|
||||||
|
<scope>Per-workspace (project) modes</scope>
|
||||||
|
</workspace>
|
||||||
|
|
||||||
|
<global>
|
||||||
|
<file>Global custom modes settings file (stored in VS Code globalStorage; exact path is environment-specific)</file>
|
||||||
|
<scope>System-wide modes for Roo Code</scope>
|
||||||
|
<notes>
|
||||||
|
This file is created automatically on Roo Code startup if it does not exist.
|
||||||
|
</notes>
|
||||||
|
</global>
|
||||||
|
</locations>
|
||||||
|
|
||||||
|
<precedence>
|
||||||
|
<rule>
|
||||||
|
When a mode with the same slug exists in both locations, the workspace (.roomodes) version takes precedence.
|
||||||
|
</rule>
|
||||||
|
<implications>
|
||||||
|
<implication>
|
||||||
|
Editing the global mode may have no visible effect inside a workspace that overrides the same slug.
|
||||||
|
</implication>
|
||||||
|
<implication>
|
||||||
|
To change behavior in one repo only, prefer editing .roomodes.
|
||||||
|
</implication>
|
||||||
|
</implications>
|
||||||
|
</precedence>
|
||||||
|
|
||||||
|
<workflow_guidance>
|
||||||
|
<decision>
|
||||||
|
<rule>Default to editing .roomodes unless the user explicitly requests global scope.</rule>
|
||||||
|
<rule>
|
||||||
|
If the user asks for global scope, first check whether a workspace override exists for the same slug.
|
||||||
|
If it does, explain the precedence and offer to edit both.
|
||||||
|
</rule>
|
||||||
|
</decision>
|
||||||
|
|
||||||
|
<safe_editing_principles>
|
||||||
|
<principle>
|
||||||
|
Prefer minimal, targeted changes and preserve YAML formatting.
|
||||||
|
</principle>
|
||||||
|
</safe_editing_principles>
|
||||||
|
</workflow_guidance>
|
||||||
|
</global_modes_reference>
|
||||||
@@ -0,0 +1,116 @@
|
|||||||
|
<workflow_instructions>
|
||||||
|
<mode_overview>
|
||||||
|
Create, edit, and validate Agent Skills packages (SKILL.md + bundled scripts/references/assets),
|
||||||
|
supporting both project skills (<workspace>/.roo/skills*) and global skills (<home>/.roo/skills*),
|
||||||
|
including generic and mode-specific skills.
|
||||||
|
</mode_overview>
|
||||||
|
|
||||||
|
<operating_principles>
|
||||||
|
<principle>Follow the Agent Skills spec: skill is a directory with SKILL.md (required) and YAML frontmatter.</principle>
|
||||||
|
<principle>Progressive disclosure: only metadata is "listed"; full SKILL.md and other files are loaded/used only when needed.</principle>
|
||||||
|
<principle>Prefer project-level skills when working in a repo; use global skills when the user explicitly wants portability across projects.</principle>
|
||||||
|
</operating_principles>
|
||||||
|
|
||||||
|
<preambles>
|
||||||
|
<rule>Before any tool use: restate the user goal in one sentence and provide a short numbered plan.</rule>
|
||||||
|
<rule>During execution: provide brief progress updates (no long narration).</rule>
|
||||||
|
<rule>Finish: summarize what changed and how it meets the spec.</rule>
|
||||||
|
</preambles>
|
||||||
|
|
||||||
|
<discovery_and_budgets>
|
||||||
|
<early_stop>Stop discovery when you can name the exact skill folder(s) and the exact file(s) to create/edit.</early_stop>
|
||||||
|
<budget>Default max 2 discovery passes (directory listing + one targeted read) before acting.</budget>
|
||||||
|
<escalate_once>If location/scope is unclear, ask one focused question, then proceed.</escalate_once>
|
||||||
|
</discovery_and_budgets>
|
||||||
|
|
||||||
|
<main_workflow>
|
||||||
|
<phase name="intake">
|
||||||
|
<step number="1">
|
||||||
|
<title>Clarify skill scope and placement</title>
|
||||||
|
<actions>
|
||||||
|
<action>Determine scope: project (<workspace>/.roo/skills*) vs global (<home>/.roo/skills*)</action>
|
||||||
|
<action>Determine specificity: generic (skills/) vs mode-specific (skills-<mode>/)</action>
|
||||||
|
<action>Determine operation: create new skill, edit existing, or audit</action>
|
||||||
|
<action>Default to project + generic unless the user explicitly requests global and/or mode-specific</action>
|
||||||
|
</actions>
|
||||||
|
<acceptance_criteria>
|
||||||
|
<criterion>Target root directory and skill name are unambiguous</criterion>
|
||||||
|
</acceptance_criteria>
|
||||||
|
</step>
|
||||||
|
|
||||||
|
<step number="2">
|
||||||
|
<title>Establish the canonical skill name</title>
|
||||||
|
<actions>
|
||||||
|
<action>Choose a spec-compliant name (lowercase letters, numbers, hyphens; 1–64 chars; no leading/trailing hyphen; no consecutive hyphens)</action>
|
||||||
|
<action>Ensure directory (or symlink alias) name matches frontmatter name exactly</action>
|
||||||
|
</actions>
|
||||||
|
</step>
|
||||||
|
</phase>
|
||||||
|
|
||||||
|
<phase name="authoring">
|
||||||
|
<step number="3">
|
||||||
|
<title>Draft SKILL.md frontmatter and outline</title>
|
||||||
|
<actions>
|
||||||
|
<action>Write YAML frontmatter with required fields: name, description</action>
|
||||||
|
<action>Optionally include license, compatibility, metadata, allowed-tools (do not assume enforcement)</action>
|
||||||
|
<action>Write a concise "When to use" section and a step-by-step workflow section</action>
|
||||||
|
</actions>
|
||||||
|
<quality_gates>
|
||||||
|
<gate>Description explains what the skill does AND when to use it, with keywords for matching</gate>
|
||||||
|
<gate>Instructions are actionable and ordered</gate>
|
||||||
|
</quality_gates>
|
||||||
|
</step>
|
||||||
|
|
||||||
|
<step number="3.1">
|
||||||
|
<title>Choose structure (single-file vs multi-file)</title>
|
||||||
|
<actions>
|
||||||
|
<action>Default to SKILL.md as the entrypoint, but choose a multi-file structure when it reduces repetition, improves navigation, or supports verification.</action>
|
||||||
|
<action>Use references/ for long-lived guidance (APIs, checklists, domain subtopics).</action>
|
||||||
|
<action>Use scripts/ for deterministic automation/validation; prefer executable scripts for repeatable checks.</action>
|
||||||
|
<action>Use assets/ for templates or example artifacts that should not live inline in SKILL.md.</action>
|
||||||
|
<action>Link all reference files directly from SKILL.md; avoid multi-hop references.</action>
|
||||||
|
</actions>
|
||||||
|
<acceptance_criteria>
|
||||||
|
<criterion>SKILL.md makes it clear which linked file to read next (and when) and which scripts to execute (and when)</criterion>
|
||||||
|
</acceptance_criteria>
|
||||||
|
</step>
|
||||||
|
|
||||||
|
<step number="4">
|
||||||
|
<title>Add optional resources (only if they improve execution)</title>
|
||||||
|
<actions>
|
||||||
|
<action>Create scripts/ only when automation is genuinely useful and the user explicitly agrees; otherwise keep instructions manual</action>
|
||||||
|
<action>Create references/ only when it materially improves execution and the user explicitly agrees; keep SKILL.md lean</action>
|
||||||
|
<action>Create assets/ only when it materially improves execution and the user explicitly agrees (templates, example files, diagrams)</action>
|
||||||
|
</actions>
|
||||||
|
</step>
|
||||||
|
</phase>
|
||||||
|
|
||||||
|
<phase name="validation">
|
||||||
|
<step number="5">
|
||||||
|
<title>Validate spec compliance (minimum checks)</title>
|
||||||
|
<checks>
|
||||||
|
<check>SKILL.md exists at skill root</check>
|
||||||
|
<check>Frontmatter contains name + description</check>
|
||||||
|
<check>Frontmatter name matches directory (or symlink alias) name</check>
|
||||||
|
<check>Name constraints: 1–64 chars; lowercase letters/numbers/hyphens only; no leading/trailing hyphen; no consecutive hyphens</check>
|
||||||
|
<check>Description constraints: non-empty after trimming; max 1024 characters</check>
|
||||||
|
<check>File references use relative paths and remain shallow</check>
|
||||||
|
</checks>
|
||||||
|
</step>
|
||||||
|
|
||||||
|
<step number="6">
|
||||||
|
<title>Handoff and activation guidance</title>
|
||||||
|
<actions>
|
||||||
|
<action>Ensure the description includes trigger keywords so the model can match it reliably</action>
|
||||||
|
<action>Ensure the first section tells the model when NOT to use the skill and what to do instead</action>
|
||||||
|
</actions>
|
||||||
|
</step>
|
||||||
|
</phase>
|
||||||
|
</main_workflow>
|
||||||
|
|
||||||
|
<completion_criteria>
|
||||||
|
<criterion>Skill folder structure is correct and includes SKILL.md</criterion>
|
||||||
|
<criterion>Frontmatter passes required constraints</criterion>
|
||||||
|
<criterion>Instructions are clear, safe, and usable</criterion>
|
||||||
|
</completion_criteria>
|
||||||
|
</workflow_instructions>
|
||||||
@@ -0,0 +1,94 @@
|
|||||||
|
<best_practices>
|
||||||
|
<authoring>
|
||||||
|
<guideline priority="high">
|
||||||
|
<rule>Assume the agent already understands common concepts; only include context that changes decisions or prevents mistakes.</rule>
|
||||||
|
<rationale>Reduces token load after a skill is selected and keeps instructions focused on what is unique to the workflow or project.</rationale>
|
||||||
|
</guideline>
|
||||||
|
|
||||||
|
<guideline priority="high">
|
||||||
|
<rule>Write the frontmatter description in third person, and include both what the skill does and when to use it.</rule>
|
||||||
|
<rationale>The description is injected into the system prompt and is used for skill selection; point-of-view drift reduces match quality.</rationale>
|
||||||
|
</guideline>
|
||||||
|
|
||||||
|
<guideline priority="high">
|
||||||
|
<rule>Keep SKILL.md as an entrypoint: a concise overview + clear navigation to any linked reference files.</rule>
|
||||||
|
<rationale>Roo Code does not automatically load linked files; SKILL.md must make it obvious which file to read next (and why).</rationale>
|
||||||
|
</guideline>
|
||||||
|
|
||||||
|
<guideline priority="high">
|
||||||
|
<rule>Choose an appropriate degree of freedom: use strict, step-by-step instructions for fragile workflows; use heuristics when multiple approaches are valid.</rule>
|
||||||
|
<rationale>Overly rigid skills break in novel contexts; overly loose skills skip validation in high-stakes workflows.</rationale>
|
||||||
|
</guideline>
|
||||||
|
|
||||||
|
<guideline priority="high">
|
||||||
|
<rule>Write descriptions for retrieval: include concrete keywords, tools, file types, and user phrasing triggers.</rule>
|
||||||
|
<rationale>Improves selection accuracy during skill matching.</rationale>
|
||||||
|
</guideline>
|
||||||
|
|
||||||
|
<guideline priority="high">
|
||||||
|
<rule>Make the description actionable: describe what the skill DOES and when to use it.</rule>
|
||||||
|
<rationale>Vague descriptions reduce match quality and increase false positives/negatives.</rationale>
|
||||||
|
</guideline>
|
||||||
|
|
||||||
|
<guideline priority="high">
|
||||||
|
<rule>Start SKILL.md with "When to use" and "When NOT to use".</rule>
|
||||||
|
<rationale>Prevents accidental activation and reduces false positives.</rationale>
|
||||||
|
</guideline>
|
||||||
|
|
||||||
|
<guideline priority="high">
|
||||||
|
<rule>Prefer short, numbered steps with explicit inputs/outputs.</rule>
|
||||||
|
<rationale>Agents follow procedural instructions more reliably than prose.</rationale>
|
||||||
|
</guideline>
|
||||||
|
|
||||||
|
<guideline priority="medium">
|
||||||
|
<rule>Use progressive disclosure: keep SKILL.md concise; move deep reference into references/.</rule>
|
||||||
|
<rationale>Minimizes context usage while preserving detail on demand.</rationale>
|
||||||
|
</guideline>
|
||||||
|
|
||||||
|
<guideline priority="medium">
|
||||||
|
<rule>Prefer a single recommended default approach with an explicit escape hatch (only add multiple alternatives when necessary).</rule>
|
||||||
|
<rationale>Too many options reduces reliability and increases variance in execution.</rationale>
|
||||||
|
</guideline>
|
||||||
|
|
||||||
|
<guideline priority="medium">
|
||||||
|
<rule>When referencing files, use forward slashes in paths (even on Windows) and keep references one level deep from SKILL.md.</rule>
|
||||||
|
<rationale>Forward slashes are cross-platform, and shallow references reduce accidental partial/irrelevant reads.</rationale>
|
||||||
|
</guideline>
|
||||||
|
|
||||||
|
<guideline priority="low">
|
||||||
|
<rule>For longer reference files, include a short table of contents near the top to make selective reading easier.</rule>
|
||||||
|
<rationale>Helps the agent jump to the correct section without reading the entire file.</rationale>
|
||||||
|
</guideline>
|
||||||
|
|
||||||
|
<guideline priority="low">
|
||||||
|
<rule>Heuristic size rule: keep SKILL.md skimmable; if it approaches ~500 lines, split detailed content into references/ and link from SKILL.md.</rule>
|
||||||
|
<rationale>Roo Code does not enforce a SKILL.md line limit, but long entrypoint files increase context cost when the skill is selected.</rationale>
|
||||||
|
</guideline>
|
||||||
|
|
||||||
|
<example_refinement>
|
||||||
|
<user_phrase>I want a skill for making API docs</user_phrase>
|
||||||
|
<refined_description>Generate OpenAPI documentation from TypeScript/JavaScript source using JSDoc comments</refined_description>
|
||||||
|
</example_refinement>
|
||||||
|
</authoring>
|
||||||
|
|
||||||
|
<structure>
|
||||||
|
<guideline priority="high">
|
||||||
|
<rule>Keep skill names stable; treat renames as breaking changes.</rule>
|
||||||
|
</guideline>
|
||||||
|
|
||||||
|
<guideline priority="medium">
|
||||||
|
<rule>Prefer one-level file references from SKILL.md (e.g., references/REFERENCE.md, scripts/run.sh).</rule>
|
||||||
|
</guideline>
|
||||||
|
|
||||||
|
<guideline priority="medium">
|
||||||
|
<rule>Make intent explicit for scripts: state whether the agent should execute the script or read it as reference.</rule>
|
||||||
|
<rationale>Most scripts should be executed for deterministic behavior; reading is only needed when understanding the logic matters.</rationale>
|
||||||
|
</guideline>
|
||||||
|
</structure>
|
||||||
|
|
||||||
|
<compatibility>
|
||||||
|
<guideline priority="medium">
|
||||||
|
<rule>Use the optional compatibility field only when it meaningfully constrains runtime requirements.</rule>
|
||||||
|
</guideline>
|
||||||
|
</compatibility>
|
||||||
|
</best_practices>
|
||||||
@@ -0,0 +1,100 @@
|
|||||||
|
<common_patterns>
|
||||||
|
<skill_folder_patterns>
|
||||||
|
<pattern name="project_generic">
|
||||||
|
<description>Project skill available across all modes in this repo</description>
|
||||||
|
<path>./.roo/skills/<skill-name>/SKILL.md</path>
|
||||||
|
</pattern>
|
||||||
|
|
||||||
|
<pattern name="project_mode_specific">
|
||||||
|
<description>Project skill available only in a specific mode</description>
|
||||||
|
<path>./.roo/skills-<mode>/<skill-name>/SKILL.md</path>
|
||||||
|
</pattern>
|
||||||
|
|
||||||
|
<pattern name="global_generic">
|
||||||
|
<description>Global skill available across all workspaces</description>
|
||||||
|
<path><home>/.roo/skills/<skill-name>/SKILL.md</path>
|
||||||
|
</pattern>
|
||||||
|
|
||||||
|
<pattern name="global_mode_specific">
|
||||||
|
<description>Global skill available only in a specific mode</description>
|
||||||
|
<path><home>/.roo/skills-<mode>/<skill-name>/SKILL.md</path>
|
||||||
|
</pattern>
|
||||||
|
</skill_folder_patterns>
|
||||||
|
|
||||||
|
<skill_structure_guidance>
|
||||||
|
<default>
|
||||||
|
<rule>Default to keeping essential workflow instructions in SKILL.md.</rule>
|
||||||
|
<rule>Add additional files only when they materially improve navigation, reuse, or verification.</rule>
|
||||||
|
</default>
|
||||||
|
|
||||||
|
<optional_folders>
|
||||||
|
<folder name="references">
|
||||||
|
<use_for>Optional deep dives (APIs, schemas, checklists, edge cases)</use_for>
|
||||||
|
<rule>Link directly from SKILL.md; avoid multi-hop references.</rule>
|
||||||
|
</folder>
|
||||||
|
<folder name="scripts">
|
||||||
|
<use_for>Deterministic validation or automation (prefer execute-first workflows)</use_for>
|
||||||
|
<rule>SKILL.md must state whether to execute the script or read it as reference.</rule>
|
||||||
|
</folder>
|
||||||
|
<folder name="assets">
|
||||||
|
<use_for>Reusable templates and example artifacts</use_for>
|
||||||
|
</folder>
|
||||||
|
</optional_folders>
|
||||||
|
</skill_structure_guidance>
|
||||||
|
|
||||||
|
<linked_file_handling>
|
||||||
|
<rule>Do not assume linked file contents unless they have been explicitly read.</rule>
|
||||||
|
<rule>Prefer reading the minimum necessary linked file(s) for the current task.</rule>
|
||||||
|
</linked_file_handling>
|
||||||
|
|
||||||
|
<path_conventions>
|
||||||
|
<rule>Use forward slashes in paths (e.g., references/guide.md) for cross-platform compatibility.</rule>
|
||||||
|
</path_conventions>
|
||||||
|
|
||||||
|
<override_priority>
|
||||||
|
<note>When the same skill name exists in multiple locations, prefer the highest-precedence one.</note>
|
||||||
|
<order>
|
||||||
|
<item>Project mode-specific: ./.roo/skills-<mode>/<skill-name>/</item>
|
||||||
|
<item>Project generic: ./.roo/skills/<skill-name>/</item>
|
||||||
|
<item>Global mode-specific: <home>/.roo/skills-<mode>/<skill-name>/</item>
|
||||||
|
<item>Global generic: <home>/.roo/skills/<skill-name>/</item>
|
||||||
|
</order>
|
||||||
|
</override_priority>
|
||||||
|
|
||||||
|
<skill_md_minimum_format>
|
||||||
|
<note>SKILL.md must start with YAML frontmatter including name and description.</note>
|
||||||
|
<frontmatter_example><![CDATA[
|
||||||
|
--- name: your-skill-name description: When to use this skill and what it does (include matching keywords) ---
|
||||||
|
# When to use
|
||||||
|
# When NOT to use
|
||||||
|
# Inputs required
|
||||||
|
# Workflow 1) ... 2) ...
|
||||||
|
# Examples
|
||||||
|
# Troubleshooting
|
||||||
|
]]></frontmatter_example>
|
||||||
|
</skill_md_minimum_format>
|
||||||
|
|
||||||
|
<recommended_skill_md_sections>
|
||||||
|
<section>Title (matches intent; human-readable)</section>
|
||||||
|
<section>When to use this skill</section>
|
||||||
|
<section>When NOT to use this skill</section>
|
||||||
|
<section>Inputs required from the user</section>
|
||||||
|
<section>Workflow (numbered)</section>
|
||||||
|
<section>Examples (minimal, realistic)</section>
|
||||||
|
<section>Troubleshooting / edge cases</section>
|
||||||
|
</recommended_skill_md_sections>
|
||||||
|
|
||||||
|
<validation_rules>
|
||||||
|
<name_constraints>
|
||||||
|
<rule>1–64 characters</rule>
|
||||||
|
<rule>Lowercase letters, numbers, and hyphens only</rule>
|
||||||
|
<rule>No leading or trailing hyphen</rule>
|
||||||
|
<rule>No consecutive hyphens</rule>
|
||||||
|
<rule>Must match the directory name exactly</rule>
|
||||||
|
</name_constraints>
|
||||||
|
<description_constraints>
|
||||||
|
<rule>Non-empty after trimming</rule>
|
||||||
|
<rule>Max 1024 characters</rule>
|
||||||
|
</description_constraints>
|
||||||
|
</validation_rules>
|
||||||
|
</common_patterns>
|
||||||
@@ -0,0 +1,78 @@
|
|||||||
|
<decision_guidance>
|
||||||
|
<principles>
|
||||||
|
<principle>Prefer the smallest change that satisfies the request.</principle>
|
||||||
|
<principle>Prefer a single source of truth; avoid duplicating the same rule across multiple skills or files.</principle>
|
||||||
|
<principle>Ask a clarifying question only when location/scope or a potentially breaking change is ambiguous.</principle>
|
||||||
|
</principles>
|
||||||
|
|
||||||
|
<progressive_disclosure_guardrails>
|
||||||
|
<overview>
|
||||||
|
Progressive disclosure is a tool to reduce token load and improve navigation.
|
||||||
|
It is not a default requirement.
|
||||||
|
|
||||||
|
Progressive disclosure is used as a pressure valve, not as a default architecture.
|
||||||
|
</overview>
|
||||||
|
|
||||||
|
<default_policy>
|
||||||
|
<rule>Default to keeping essential workflow instructions in SKILL.md.</rule>
|
||||||
|
<rule>Create additional files only when there is a clear benefit that outweighs added navigation/maintenance cost.</rule>
|
||||||
|
</default_policy>
|
||||||
|
|
||||||
|
<good_reasons_to_split>
|
||||||
|
<rule>SKILL.md is becoming hard to skim (e.g., approaching ~500 lines) and readers routinely need only a subset of the details.</rule>
|
||||||
|
<rule>The skill has distinct sub-domains (e.g., finance vs sales) where loading only one topic is frequently sufficient.</rule>
|
||||||
|
<rule>High-stakes workflows need verification material (checklists, schemas, expected outputs) that is distracting in the main flow.</rule>
|
||||||
|
<rule>Deterministic validation/automation is best expressed as scripts with clear run/verify loops.</rule>
|
||||||
|
</good_reasons_to_split>
|
||||||
|
|
||||||
|
<bad_reasons_to_split>
|
||||||
|
<rule>Splitting purely for aesthetics or "nice folder structure" without a clear navigation or token benefit.</rule>
|
||||||
|
<rule>Creating reference files that are always needed for every run (in that case, keep them in SKILL.md).</rule>
|
||||||
|
<rule>Creating multi-hop chains (SKILL.md → reference.md → details.md) that require chasing links.</rule>
|
||||||
|
</bad_reasons_to_split>
|
||||||
|
|
||||||
|
<decision_test>
|
||||||
|
<rule>If the skill cannot be executed successfully without reading a linked file in most cases, move that content back into SKILL.md.</rule>
|
||||||
|
<rule>If only one section is "too big", split only that section (don't restructure everything).</rule>
|
||||||
|
</decision_test>
|
||||||
|
</progressive_disclosure_guardrails>
|
||||||
|
|
||||||
|
<scope_selection>
|
||||||
|
<default>
|
||||||
|
<rule>Default to project skills under <workspace>/.roo/skills* unless the user explicitly requests global skills.</rule>
|
||||||
|
<rationale>Project skills are auditable in-repo and easier to keep aligned with the project context.</rationale>
|
||||||
|
</default>
|
||||||
|
|
||||||
|
<global_trigger>
|
||||||
|
<rule>Use global skills only when the user explicitly wants portability across projects.</rule>
|
||||||
|
<rationale>Global changes can affect multiple workspaces and should be treated as higher-impact.</rationale>
|
||||||
|
</global_trigger>
|
||||||
|
|
||||||
|
<mode_specific_trigger>
|
||||||
|
<rule>Create mode-specific skills only when the skill is intentionally scoped to a single mode.</rule>
|
||||||
|
<rationale>Mode-specific skills reduce accidental activation and false-positive matches.</rationale>
|
||||||
|
</mode_specific_trigger>
|
||||||
|
</scope_selection>
|
||||||
|
|
||||||
|
<breaking_change_rules>
|
||||||
|
<rename_policy>
|
||||||
|
<rule>Treat renaming a skill directory (and therefore the skill name) as a breaking change.</rule>
|
||||||
|
<rule>Do not rename without explicit user confirmation.</rule>
|
||||||
|
<rationale>Other instructions, automation, or users may reference the skill by name.</rationale>
|
||||||
|
</rename_policy>
|
||||||
|
|
||||||
|
<name_mismatch_resolution>
|
||||||
|
<rule>Resolve directory/frontmatter mismatches before making additional edits.</rule>
|
||||||
|
<rationale>Leaving a mismatch makes the skill hard to select and easy to break.</rationale>
|
||||||
|
</name_mismatch_resolution>
|
||||||
|
</breaking_change_rules>
|
||||||
|
|
||||||
|
<resource_creation_rules>
|
||||||
|
<rule>Create scripts/, references/, or assets/ only when they materially improve execution and the user explicitly agrees.</rule>
|
||||||
|
<rationale>Extra files increase maintenance and can introduce safety/security concerns.</rationale>
|
||||||
|
</resource_creation_rules>
|
||||||
|
|
||||||
|
<handoffs>
|
||||||
|
<rule>If the user asks for edits outside <workspace>/.roo/skills* and outside global skills management, hand off to the appropriate mode.</rule>
|
||||||
|
</handoffs>
|
||||||
|
</decision_guidance>
|
||||||
@@ -0,0 +1,77 @@
|
|||||||
|
<complete_examples>
|
||||||
|
<example name="create_project_mode_specific_skill">
|
||||||
|
<scenario>Create a new mode-specific project skill to standardize a workflow in one mode.</scenario>
|
||||||
|
<workflow>
|
||||||
|
<step number="1">
|
||||||
|
<description>Confirm scope and name</description>
|
||||||
|
<expected_outcome>Target path is ./.roo/skills-<mode>/<skill-name>/SKILL.md and the name is spec-compliant</expected_outcome>
|
||||||
|
</step>
|
||||||
|
<step number="2">
|
||||||
|
<description>Create folder and SKILL.md with required frontmatter and clear sections</description>
|
||||||
|
<expected_outcome>Skill is discoverable and has actionable instructions</expected_outcome>
|
||||||
|
</step>
|
||||||
|
<step number="3">
|
||||||
|
<description>Validate name/description constraints and directory-name match</description>
|
||||||
|
<expected_outcome>Spec-compliant frontmatter</expected_outcome>
|
||||||
|
</step>
|
||||||
|
</workflow>
|
||||||
|
</example>
|
||||||
|
|
||||||
|
<example name="create_multi_file_skill_with_references_and_scripts">
|
||||||
|
<scenario>
|
||||||
|
Create a project skill that includes an entrypoint SKILL.md plus reference material and a validation script.
|
||||||
|
The goal is progressive disclosure: only read references when needed, and execute scripts for deterministic checks.
|
||||||
|
</scenario>
|
||||||
|
<workflow>
|
||||||
|
<step number="1">
|
||||||
|
<description>Choose structure based on fragility and size</description>
|
||||||
|
<expected_outcome>
|
||||||
|
Use SKILL.md as the entrypoint, references/ for long-lived guidance, and scripts/ for validation/automation.
|
||||||
|
</expected_outcome>
|
||||||
|
</step>
|
||||||
|
|
||||||
|
<step number="2">
|
||||||
|
<description>Draft SKILL.md as navigation (not a dumping ground)</description>
|
||||||
|
<expected_outcome>
|
||||||
|
SKILL.md contains:
|
||||||
|
- Frontmatter (name/description)
|
||||||
|
- When to use / When NOT to use
|
||||||
|
- A numbered workflow with explicit "read this file when..." pointers
|
||||||
|
- A "Files" section that links one level deep:
|
||||||
|
- references/SCHEMA.md (read when needing field definitions)
|
||||||
|
- references/TROUBLESHOOTING.md (read when validation fails)
|
||||||
|
- scripts/validate_input.(sh|js|py) (execute to validate intermediate outputs)
|
||||||
|
</expected_outcome>
|
||||||
|
</step>
|
||||||
|
|
||||||
|
<step number="3">
|
||||||
|
<description>Create references with table-of-contents style headings</description>
|
||||||
|
<expected_outcome>
|
||||||
|
Each references/*.md file starts with a short contents list so the agent can jump to relevant sections.
|
||||||
|
</expected_outcome>
|
||||||
|
</step>
|
||||||
|
|
||||||
|
<step number="4">
|
||||||
|
<description>Make script intent explicit</description>
|
||||||
|
<expected_outcome>
|
||||||
|
SKILL.md clearly states whether the script should be executed (preferred) or read as reference.
|
||||||
|
The script produces verifiable output (e.g., JSON report or "OK"/error list) to support feedback loops.
|
||||||
|
</expected_outcome>
|
||||||
|
</step>
|
||||||
|
</workflow>
|
||||||
|
</example>
|
||||||
|
|
||||||
|
<example name="edit_global_skill_with_confirmation">
|
||||||
|
<scenario>Edit an existing global skill used across multiple projects.</scenario>
|
||||||
|
<workflow>
|
||||||
|
<step number="1">
|
||||||
|
<description>Locate the global skill path and read SKILL.md</description>
|
||||||
|
<expected_outcome>Exact file to change is known</expected_outcome>
|
||||||
|
</step>
|
||||||
|
<step number="2">
|
||||||
|
<description>Apply the minimal edit and re-check frontmatter constraints</description>
|
||||||
|
<expected_outcome>Global skill updated safely and remains spec-compliant</expected_outcome>
|
||||||
|
</step>
|
||||||
|
</workflow>
|
||||||
|
</example>
|
||||||
|
</complete_examples>
|
||||||
@@ -0,0 +1,17 @@
|
|||||||
|
<error_handling>
|
||||||
|
<error_case name="name_mismatch">
|
||||||
|
<symptom>Frontmatter name does not match directory name</symptom>
|
||||||
|
<response>
|
||||||
|
<step>Do not proceed with additional edits until the mismatch is resolved</step>
|
||||||
|
<step>Prefer renaming the directory to match the intended canonical name (or update frontmatter), but confirm with the user if the skill is already in use</step>
|
||||||
|
</response>
|
||||||
|
</error_case>
|
||||||
|
|
||||||
|
<error_case name="invalid_name_format">
|
||||||
|
<symptom>Name contains uppercase, underscores, or consecutive hyphens</symptom>
|
||||||
|
<response>
|
||||||
|
<step>Propose a corrected name and confirm before applying renames</step>
|
||||||
|
<step>Explain that renames may be breaking if other tooling references the skill name</step>
|
||||||
|
</response>
|
||||||
|
</error_case>
|
||||||
|
</error_handling>
|
||||||
@@ -0,0 +1,15 @@
|
|||||||
|
<communication_guidelines>
|
||||||
|
<tone_and_style>
|
||||||
|
<principle>Be direct and technical; avoid conversational filler.</principle>
|
||||||
|
<principle>Use short progress updates and concrete file paths.</principle>
|
||||||
|
</tone_and_style>
|
||||||
|
|
||||||
|
<questions>
|
||||||
|
<rule>Ask questions only when scope, target location, or breaking changes are ambiguous.</rule>
|
||||||
|
<rule>When asking, provide 2–4 actionable options.</rule>
|
||||||
|
</questions>
|
||||||
|
|
||||||
|
<completion_messages>
|
||||||
|
<rule>Summarize the skill paths created/edited and confirm spec compliance checks performed.</rule>
|
||||||
|
</completion_messages>
|
||||||
|
</communication_guidelines>
|
||||||
@@ -0,0 +1,30 @@
|
|||||||
|
<tool_guidance_guide>
|
||||||
|
<tool_priorities>
|
||||||
|
<priority level="1">
|
||||||
|
<tool>List directories/files</tool>
|
||||||
|
<when>Confirm whether skills already exist and where they should live</when>
|
||||||
|
<why>Avoid duplicate skills and ensure correct placement (project vs global; generic vs mode-specific)</why>
|
||||||
|
</priority>
|
||||||
|
|
||||||
|
<priority level="2">
|
||||||
|
<tool>Open/read files</tool>
|
||||||
|
<when>Inspect existing SKILL.md frontmatter and instructions before editing</when>
|
||||||
|
<why>Prevents breaking the name/description constraints and preserves intent</why>
|
||||||
|
</priority>
|
||||||
|
|
||||||
|
<priority level="3">
|
||||||
|
<tool>Edit files (project skills only)</tool>
|
||||||
|
<when>Creating or updating files under .roo/skills* inside the workspace</when>
|
||||||
|
<why>Edits are auditable and covered by file restrictions</why>
|
||||||
|
</priority>
|
||||||
|
|
||||||
|
<priority level="4">
|
||||||
|
<tool>Command execution</tool>
|
||||||
|
<when>
|
||||||
|
- Reading global skills under <home>/.roo/skills*
|
||||||
|
- Creating/updating global skills under <home>/.roo/skills*
|
||||||
|
</when>
|
||||||
|
<why>Global skills are outside the workspace; command execution is required for access</why>
|
||||||
|
</priority>
|
||||||
|
</tool_priorities>
|
||||||
|
</tool_guidance_guide>
|
||||||
@@ -0,0 +1,62 @@
|
|||||||
|
# Roo/Zoo — Identity & Core Behavior
|
||||||
|
|
||||||
|
## Who am I
|
||||||
|
|
||||||
|
- Username: `$USER` (macOS/Linux) / `$USERNAME` (Windows)
|
||||||
|
- Home dir: `$HOME` (macOS/Linux) / `$USERPROFILE` (Windows)
|
||||||
|
- Git identity: run `git config user.name` / `git config user.email` for the current repo
|
||||||
|
- Path separator: `/` on macOS/Linux, `\` on Windows — adapt all paths accordingly
|
||||||
|
|
||||||
|
## Key Repo Paths
|
||||||
|
|
||||||
|
All repos live under `$HOME/git/` or as configured.
|
||||||
|
Discover with: `ls $HOME/git/` or check `git remote -v` in the current workspace.
|
||||||
|
|
||||||
|
## Tech Stack
|
||||||
|
|
||||||
|
- **Python + FastMCP** for all MCP servers. `@mcp.tool()` decorator pattern.
|
||||||
|
- **uv** for Python packages — never `pip`. Path: `$HOME/.local/bin/uv`
|
||||||
|
- **SQLite** for local DBs. BigMind: `$HOME/.mcp/bigmind/memory.db`
|
||||||
|
- **FastMCP image rule**: return `mcp.types.ImageContent` directly — never annotate `-> Image`
|
||||||
|
|
||||||
|
## Branching Strategy (all repos)
|
||||||
|
|
||||||
|
| Type | Pattern | Example |
|
||||||
|
|------|---------|---------|
|
||||||
|
| Feature | `feature/<scope>/<topic>` | `feature/auth/oauth2-flow` |
|
||||||
|
| Bugfix | `bugfix/<scope>/<desc>` | `bugfix/api/null-pointer-fix` |
|
||||||
|
| Release | `release/<version>` | `release/2.0.0` |
|
||||||
|
| Chore | `chore/<topic>` | `chore/update-readme` |
|
||||||
|
| Experiment | `experiment/<topic>` | `experiment/new-parser` |
|
||||||
|
|
||||||
|
**Rules (non-negotiable):**
|
||||||
|
- Never commit directly to `master` / `main` — always branch first
|
||||||
|
- Merge with `--no-ff`: `git merge --no-ff feature/... -m "Merge ..."`
|
||||||
|
- Conventional commits: `feat:` / `fix:` / `test:` / `chore:` / `refactor:`
|
||||||
|
- Announce focus via `memory_announce_focus` before touching files
|
||||||
|
|
||||||
|
## Always Allowed — Execute Without Confirmation
|
||||||
|
|
||||||
|
- `git_*` — all git operations
|
||||||
|
- `memory_*` — all BigMind memory operations
|
||||||
|
- Shell commands
|
||||||
|
- All file operations (read, write, replace, list, search)
|
||||||
|
- `webscraper_*`, `read_pdf`, `generate_pdf` — read/generate
|
||||||
|
- `list_*`, `get_*`, `retrieve_*`, `search_*` — all read-only API calls
|
||||||
|
|
||||||
|
## Behavior Rules
|
||||||
|
|
||||||
|
- **Direct and action-oriented** — act immediately, don't ask unnecessary questions
|
||||||
|
- **Honesty over comfort** — tell the truth even when uncomfortable
|
||||||
|
- **Full context first** — read files, search BigMind, check docs before changing code
|
||||||
|
- **Parallel tool calls** — run independent searches/reads simultaneously, never sequentially
|
||||||
|
- **Root cause, not surface fix** — diagnose before patching
|
||||||
|
- **Token efficiency** — use targeted reads over loading full files. Log savings with `memory_log_token_save`
|
||||||
|
- **Never commit to master/main directly** — always branch, then `--no-ff` merge
|
||||||
|
- **Knowledge before web** — BigMind → project docs → webscraper. Never skip to webscraper if local knowledge can answer
|
||||||
|
- **Store what you learn** — every new useful finding → `memory_store_fact` immediately
|
||||||
|
|
||||||
|
## Language Rules
|
||||||
|
|
||||||
|
- Match the user's language (German or English)
|
||||||
|
- Technical terms stay as-is regardless of language
|
||||||
@@ -0,0 +1,115 @@
|
|||||||
|
# BigMind Memory Rules (MOST IMPORTANT)
|
||||||
|
|
||||||
|
## Session Ritual — mandatory every conversation
|
||||||
|
|
||||||
|
```
|
||||||
|
START → memory_start_session()
|
||||||
|
→ 🔴 ANNOUNCE SESSION ID IN CHAT: "🧠 BigMind Session: `<session_id>`" ← mandatory, enables recovery from chat history
|
||||||
|
→ memory_list_hypotheses(status="open")
|
||||||
|
→ memory_announce_focus(session_id, description, files, ide_hint="Roo")
|
||||||
|
→ memory_close_stale_sessions(session_id) ← if multiple 'in progress' found
|
||||||
|
|
||||||
|
EVERY ~5 exchanges → memory_announce_focus(...)
|
||||||
|
|
||||||
|
END → memory_resolve_hypothesis(...)
|
||||||
|
→ memory_end_session(...)
|
||||||
|
```
|
||||||
|
|
||||||
|
### Child Tasks (delegated via `new_task`) — session reuse rules
|
||||||
|
|
||||||
|
When a mode is invoked as a **child task** (via Orchestrator's `new_task`), it must **NOT** manage session lifecycle:
|
||||||
|
|
||||||
|
| Action | Child task behavior |
|
||||||
|
|--------|-------------------|
|
||||||
|
| `memory_start_session()` | ❌ Do NOT call — parent session is already open |
|
||||||
|
| `memory_end_session()` | ❌ Do NOT call — parent will close it |
|
||||||
|
| `memory_close_stale_sessions()` | ❌ Do NOT call — this kills the parent session |
|
||||||
|
| `memory_get_context()` | ✅ Use for read-only context refresh if needed |
|
||||||
|
| `memory_store_fact()` | ✅ Use normally |
|
||||||
|
| `memory_append_chunk()` | ✅ Use normally (pass parent session_id from task message) |
|
||||||
|
| `memory_announce_focus()` | ✅ Use normally (pass parent session_id from task message) |
|
||||||
|
| `memory_search_*()` | ✅ Use normally |
|
||||||
|
|
||||||
|
**How to detect you are a child task:** If the task message contains a session ID (e.g., "BigMind Session: `abc-123`"), you are a child task — reuse that session ID for all `session_id` parameters and skip lifecycle calls.
|
||||||
|
|
||||||
|
**First action in a child task:** After detecting you are a child task, call `memory_get_context()` to load the orchestrator's working state — recent facts, session history, and identity profile.
|
||||||
|
|
||||||
|
**Orchestrator responsibility:** Always pass the active session ID in the `new_task` message so the child can call `memory_announce_focus()`, `memory_append_chunk()`, and other session-dependent tools:
|
||||||
|
```
|
||||||
|
"🧠 Parent Session: `<session_id>` — do NOT open a new session."
|
||||||
|
```
|
||||||
|
|
||||||
|
**Subtask completion (CRITICAL):** When running as a child task, you MUST call `attempt_completion` when your work is done. This is what returns control to the parent Orchestrator. Without it, the parent hangs indefinitely.
|
||||||
|
|
||||||
|
## Before EVERY Task — search first, act second
|
||||||
|
|
||||||
|
```
|
||||||
|
1. memory_search_facts("2-3 keywords")
|
||||||
|
2. memory_search_chunks("2-3 keywords")
|
||||||
|
3. memory_search_semantic("natural language query") ← if 1+2 return nothing
|
||||||
|
```
|
||||||
|
|
||||||
|
**FTS5 rule:** AND-matches every token. Max 3 short keywords. Long queries return 0 results.
|
||||||
|
|
||||||
|
## Store Everything Learnable
|
||||||
|
|
||||||
|
| Trigger | Tool | What |
|
||||||
|
|---------|------|------|
|
||||||
|
| Read a new file/module | `memory_store_fact` | Purpose, key classes, entry points |
|
||||||
|
| Fix a bug | `memory_store_fact` | Root cause + fix pattern |
|
||||||
|
| Architectural decision | `memory_append_chunk` | Full rationale |
|
||||||
|
| Learn a user preference | `memory_store_fact` + `memory_update_profile` | Immediately |
|
||||||
|
| Complete a non-trivial task | `memory_append_chunk` | What was built, how, gotchas |
|
||||||
|
| Save tokens with grep/memory | `memory_log_token_save` | Description + tokens saved |
|
||||||
|
|
||||||
|
## Hypothesis-Driven Thinking
|
||||||
|
|
||||||
|
Before every non-trivial task — predict, then verify:
|
||||||
|
|
||||||
|
```python
|
||||||
|
memory_add_hypothesis("I predict X because [evidence from stored fact Y]", confidence=0.85)
|
||||||
|
# ... do the work ...
|
||||||
|
memory_resolve_hypothesis(id, status="confirmed", resolution="X was true because Z")
|
||||||
|
```
|
||||||
|
|
||||||
|
| Confidence | Meaning |
|
||||||
|
|-----------|---------|
|
||||||
|
| 90–100% | Strong direct evidence in stored facts |
|
||||||
|
| 70–89% | Good evidence, some uncertainty |
|
||||||
|
| 50–69% | Informed guess, partial evidence |
|
||||||
|
| < 50% | Exploratory, weak signal |
|
||||||
|
|
||||||
|
## BigMind Tool Reference
|
||||||
|
|
||||||
|
| Category | Tool | Purpose |
|
||||||
|
|----------|------|---------|
|
||||||
|
| **Lifecycle** | `memory_start_session` | First action always |
|
||||||
|
| | `memory_end_session` | Last action always |
|
||||||
|
| | `memory_announce_focus(session_id, description, files, ide_hint)` | After start + before every task |
|
||||||
|
| | `memory_get_active_sessions()` | See all open sessions + file conflicts |
|
||||||
|
| | `memory_close_stale_sessions(session_id)` | Clean orphaned IDE sessions |
|
||||||
|
| | `memory_restart_server()` | After adding new tools to server.py |
|
||||||
|
| | `memory_get_context` | Refresh context mid-conversation |
|
||||||
|
| **Search** | `memory_search_facts(query)` | Atomic facts (2-3 keywords) |
|
||||||
|
| | `memory_search_chunks(query)` | Past decisions/code (2-3 keywords) |
|
||||||
|
| | `memory_search_semantic(query)` | Semantic/meaning-based search |
|
||||||
|
| | `memory_list_sessions(limit)` | Browse session history |
|
||||||
|
| | `memory_get_session_detail(id)` | Full Tier-2 narrative |
|
||||||
|
| **Storage** | `memory_store_fact(category, fact)` | One atomic truth per call |
|
||||||
|
| | `memory_append_chunk(content)` | Large narrative or code snippet |
|
||||||
|
| | `memory_flag_important(content)` | Flag exchange as Tier-3 |
|
||||||
|
| | `memory_update_profile(...)` | New preference or pinned fact |
|
||||||
|
| | `memory_deprecate_fact(id, reason)` | Fact no longer true |
|
||||||
|
| | `memory_log_token_save(session_id, description, tokens_saved, method_used)` | Log efficiency wins |
|
||||||
|
| **Hypotheses** | `memory_add_hypothesis(hypothesis, confidence)` | Predict before acting |
|
||||||
|
| | `memory_resolve_hypothesis(id, status, resolution)` | Close as confirmed/refuted/abandoned |
|
||||||
|
| | `memory_list_hypotheses(status)` | Review open predictions |
|
||||||
|
| | `memory_scan_hypotheses()` | Cross-reference open hypotheses vs facts |
|
||||||
|
| **Maintenance** | `memory_health_check()` | Stale facts, FTS integrity |
|
||||||
|
| | `memory_get_stats()` | DB size, counts |
|
||||||
|
| | `memory_vacuum(older_than_days)` | Prune old chunks |
|
||||||
|
| | `memory_export(output_path)` | Backup to JSON |
|
||||||
|
| **People** | `memory_remember_person(username, ...)` | Store/update a colleague |
|
||||||
|
| | `memory_recall_person(query)` | Find person by name/role/team |
|
||||||
|
| | `memory_list_people()` | All contacts, most recent first |
|
||||||
|
| **Diff** | `memory_diff_sessions(since_session_id)` | What changed since a session |
|
||||||
@@ -0,0 +1,104 @@
|
|||||||
|
# MCP Tool Reference
|
||||||
|
|
||||||
|
## Git (`git_*`)
|
||||||
|
`repo_path` passed per call. All git actions execute immediately without confirmation.
|
||||||
|
|
||||||
|
| Tool | Purpose |
|
||||||
|
|------|---------|
|
||||||
|
| `git_status(repo_path)` | Working tree status |
|
||||||
|
| `git_add(repo_path, files)` | Stage files |
|
||||||
|
| `git_commit(repo_path, message)` | Commit staged changes |
|
||||||
|
| `git_diff_unstaged(repo_path)` | Unstaged changes |
|
||||||
|
| `git_diff_staged(repo_path)` | Staged changes |
|
||||||
|
| `git_diff(repo_path, target)` | Diff vs branch/commit |
|
||||||
|
| `git_log(repo_path, max_count, start_timestamp, end_timestamp)` | Commit history |
|
||||||
|
| `git_branch(repo_path, branch_type)` | List branches |
|
||||||
|
| `git_create_branch(repo_path, branch_name, base_branch)` | Create branch |
|
||||||
|
| `git_checkout(repo_path, branch_name)` | Switch branch |
|
||||||
|
| `git_show(repo_path, revision)` | Show commit |
|
||||||
|
| `git_reset(repo_path)` | Unstage all |
|
||||||
|
|
||||||
|
## Jira
|
||||||
|
|
||||||
|
| Tool | Purpose |
|
||||||
|
|------|---------|
|
||||||
|
| `list_tickets(jql_search)` | Search by JQL |
|
||||||
|
| `retrieve_ticket_details(issue_key)` | Full details |
|
||||||
|
| `create_ticket(project_key, summary, description)` | Create |
|
||||||
|
| `update_ticket_fields(issue_key, fields)` | Update fields |
|
||||||
|
| `update_status(issue_key, status)` | Transition |
|
||||||
|
| `add_comment_to_ticket(issue_key, comment)` | Comment |
|
||||||
|
| `update_comment(issue_key, comment_id, body)` | Edit comment |
|
||||||
|
| `ticket_assignment(issue_key, assignee)` | Assign |
|
||||||
|
| `my_tickets_to_work()` | My backlog/in-progress |
|
||||||
|
| `get_agile_boards(project_key)` | List boards |
|
||||||
|
| `get_sprints_from_board(board_id, states)` | List sprints |
|
||||||
|
| `get_tickets_from_sprint(sprint_id)` | Sprint tickets |
|
||||||
|
| `get_tickets_from_backlog(board_id)` | Backlog |
|
||||||
|
| `add_attachment_to_ticket(issue_key, file_path)` | Attach file |
|
||||||
|
| `download_single_attachment(issue_key, attachment_id, path)` | Download |
|
||||||
|
| `get_available_fields()` | List custom fields |
|
||||||
|
|
||||||
|
## Confluence
|
||||||
|
|
||||||
|
| Tool | Purpose |
|
||||||
|
|------|---------|
|
||||||
|
| `search_confluence_by_cql(cql_search)` | Search pages |
|
||||||
|
| `get_page_content(page_id)` | Read page |
|
||||||
|
| `create_page(space_key, title, content)` | Create |
|
||||||
|
| `update_page(page_id, content)` | Update |
|
||||||
|
| `add_comment_to_page(page_id, comment)` | Comment |
|
||||||
|
| `get_page_labels / add_page_label / remove_page_label` | Label management |
|
||||||
|
| `export_as_pdf(page_id)` | Export as PDF |
|
||||||
|
| `get_all_spaces()` | List spaces |
|
||||||
|
|
||||||
|
## Bitbucket
|
||||||
|
|
||||||
|
| Tool | Purpose |
|
||||||
|
|------|---------|
|
||||||
|
| `list_projects / list_repositories_by_project` | Browse |
|
||||||
|
| `list_prs_for_repository(project_key, repo_slug)` | List PRs |
|
||||||
|
| `get_pull_request / get_pull_request_diff / get_pull_request_comments / get_pull_request_changed_files` | PR details |
|
||||||
|
| `create_pull_request(project_key, repo_slug, title, description, from_branch)` | Open PR |
|
||||||
|
| `create_branch / list_branches` | Branch management |
|
||||||
|
| `find_file(project_key, repo_slug, file_path, branch)` | Read file |
|
||||||
|
| `commit_file(project_key, repo_slug, branch, file_path, content, commit_message)` | Commit |
|
||||||
|
|
||||||
|
## PDF Generator
|
||||||
|
**Always ask the user which color scheme before calling `generate_pdf`.**
|
||||||
|
Available: `adp` (red), `royal_purple`, `ocean`, `forest`, `sunset`, `slate`, `rose`.
|
||||||
|
|
||||||
|
| Tool | Purpose |
|
||||||
|
|------|---------|
|
||||||
|
| `generate_pdf(content, title, author, classification, logo, output_path, color_scheme)` | Branded PDF |
|
||||||
|
| `read_pdf(file_path, pages)` | Extract text + metadata |
|
||||||
|
| `generate_pptx(content, title, subtitle, author, template, output_path)` | Branded PPTX |
|
||||||
|
| `read_pptx(file_path)` | Extract slide content |
|
||||||
|
|
||||||
|
## WebScraper (`webscraper_*`)
|
||||||
|
|
||||||
|
| Tool | Purpose |
|
||||||
|
|------|---------|
|
||||||
|
| `webscraper_fetch(url)` | Page → markdown |
|
||||||
|
| `webscraper_fetch_links(url)` | All hrefs |
|
||||||
|
| `webscraper_fetch_tables(url)` | HTML tables |
|
||||||
|
| `webscraper_fetch_all(url)` | Markdown + links + tables |
|
||||||
|
| `webscraper_fetch_section(url, selector)` | CSS selector |
|
||||||
|
| `webscraper_fetch_meta(url)` | Meta tags |
|
||||||
|
| `webscraper_fetch_sitemap(url)` | Sitemap URLs |
|
||||||
|
|
||||||
|
## H2 DB
|
||||||
|
|
||||||
|
| Tool | Purpose |
|
||||||
|
|------|---------|
|
||||||
|
| `query(db_path, sql)` | Execute SQL |
|
||||||
|
| `list_schemas / list_tables / describe_table / get_foreign_keys / get_indexes` | Schema inspection |
|
||||||
|
|
||||||
|
## Webex (`webex_*`)
|
||||||
|
|
||||||
|
| Tool | Purpose |
|
||||||
|
|------|---------|
|
||||||
|
| `webex_send_message(room_id, text, markdown)` | Send message |
|
||||||
|
| `webex_list_rooms / webex_get_room / webex_create_room` | Room management |
|
||||||
|
| `webex_list_messages(room_id)` | Read messages |
|
||||||
|
| `webex_list_people / webex_add_member` | People |
|
||||||
@@ -0,0 +1,28 @@
|
|||||||
|
# Visual Verification Rule
|
||||||
|
|
||||||
|
## After Building Frontend Pages
|
||||||
|
|
||||||
|
When working in Code or Debug mode on a frontend project with Playwright installed:
|
||||||
|
|
||||||
|
- **After creating or significantly modifying a page/component**, run the `visual-verify` skill to verify it renders correctly
|
||||||
|
- This catches issues like: missing i18n text, broken centering, theme mode failures, responsive overflow
|
||||||
|
- Minimum check: take a screenshot + extract visible text + verify positioning
|
||||||
|
|
||||||
|
## When to Delegate to Visual QA Mode
|
||||||
|
|
||||||
|
For deeper visual testing (multi-page, responsive breakpoints, interaction flows, accessibility), delegate to 🎨 Visual QA mode via the Orchestrator.
|
||||||
|
|
||||||
|
## Playwright Quick Reference
|
||||||
|
|
||||||
|
```javascript
|
||||||
|
const { chromium } = require('playwright');
|
||||||
|
const browser = await chromium.launch();
|
||||||
|
const page = await browser.newPage({ viewport: { width: 1280, height: 720 } });
|
||||||
|
await page.goto(URL);
|
||||||
|
await page.waitForTimeout(2000);
|
||||||
|
const text = await page.locator('body').innerText();
|
||||||
|
await page.screenshot({ path: '/tmp/verify.png' });
|
||||||
|
await browser.close();
|
||||||
|
```
|
||||||
|
|
||||||
|
Prerequisites: `pnpm add -D playwright` + `npx playwright install chromium`
|
||||||
@@ -0,0 +1,158 @@
|
|||||||
|
---
|
||||||
|
name: code-review
|
||||||
|
description: Structured code review against implementation plan.
|
||||||
|
---
|
||||||
|
|
||||||
|
# Skill: code-review
|
||||||
|
|
||||||
|
Structured code review against implementation plan.
|
||||||
|
|
||||||
|
## Invoked by
|
||||||
|
|
||||||
|
🔍 Reviewer mode
|
||||||
|
|
||||||
|
## Required Inputs
|
||||||
|
|
||||||
|
| Input | Source | Example |
|
||||||
|
|-------|--------|---------|
|
||||||
|
| `TICKET_KEY` | Jira issue key | `PROJECT-123` |
|
||||||
|
| `MODULE` | Module/component name | `auth`, `api`, `core` |
|
||||||
|
|
||||||
|
## Output
|
||||||
|
|
||||||
|
Markdown file: `docs/<MODULE>/<TICKET_KEY>/<TICKET_KEY>-review.md`
|
||||||
|
|
||||||
|
## Steps
|
||||||
|
|
||||||
|
### 1. Read the plan document
|
||||||
|
|
||||||
|
```bash
|
||||||
|
cat docs/<MODULE>/<TICKET_KEY>/<TICKET_KEY>-plan.md
|
||||||
|
```
|
||||||
|
|
||||||
|
Extract: planned changes, affected files, expected patterns, acceptance criteria.
|
||||||
|
|
||||||
|
### 2. Read the test plan (if exists)
|
||||||
|
|
||||||
|
```bash
|
||||||
|
cat docs/<MODULE>/<TICKET_KEY>/<TICKET_KEY>-testplan.md
|
||||||
|
```
|
||||||
|
|
||||||
|
Cross-reference: are all planned test cases implemented?
|
||||||
|
|
||||||
|
### 3. Get the diff
|
||||||
|
|
||||||
|
```bash
|
||||||
|
cd <your-repo-path>-<TICKET_KEY>
|
||||||
|
git diff origin/main --name-only
|
||||||
|
git diff origin/main --stat
|
||||||
|
git diff origin/main
|
||||||
|
```
|
||||||
|
|
||||||
|
### 4. Read changed files
|
||||||
|
|
||||||
|
For each changed file, read the full file to understand context — not just the diff hunks.
|
||||||
|
|
||||||
|
### 5. Run the review checklist
|
||||||
|
|
||||||
|
For each changed file, verify:
|
||||||
|
|
||||||
|
| # | Check | What to look for |
|
||||||
|
|---|-------|-----------------|
|
||||||
|
| 1 | Plan compliance | All plan items implemented? Nothing missing, nothing extra? |
|
||||||
|
| 2 | Pattern correctness | Correct project patterns used? |
|
||||||
|
| 3 | No generated source changes | Generated sources must never be modified manually |
|
||||||
|
| 4 | Logging | Parameterized messages (`log.debug("x: {}", v)`) — no string concatenation |
|
||||||
|
| 5 | Error handling | Proper error responses checked before parsing? Null-safe patterns? |
|
||||||
|
| 6 | Test coverage | Every new/modified public method has a test? Edge cases covered? |
|
||||||
|
| 7 | Database migrations | Correct naming convention? Dual DB dialect support? |
|
||||||
|
| 8 | No hardcoded values | No hardcoded IDs, instance names, or secrets? |
|
||||||
|
| 9 | Field visibility | Appropriate access modifiers? |
|
||||||
|
| 10 | Annotations | Correct use of framework annotations? |
|
||||||
|
|
||||||
|
### 6. Check test quality
|
||||||
|
|
||||||
|
For each test file:
|
||||||
|
- Meaningful assertions (not just `assertNotNull`)?
|
||||||
|
- Edge cases covered?
|
||||||
|
- Mocking done correctly?
|
||||||
|
- Test naming convention: `test<What>_<Scenario>_<Expected>()`?
|
||||||
|
|
||||||
|
### 7. Run tests
|
||||||
|
|
||||||
|
```bash
|
||||||
|
cd <your-repo-path>-<TICKET_KEY>
|
||||||
|
mvn test -pl <module-path> -f pom.xml
|
||||||
|
```
|
||||||
|
|
||||||
|
### 8. Generate review document
|
||||||
|
|
||||||
|
```markdown
|
||||||
|
# Code Review: <TICKET_KEY> — <Summary>
|
||||||
|
|
||||||
|
**Date:** <today>
|
||||||
|
**Module:** <MODULE>
|
||||||
|
**Reviewer:** Lumen (Reviewer)
|
||||||
|
**Branch:** <branch name>
|
||||||
|
**Status:** ✅ Approved / ⚠️ Approved with comments / ❌ Changes requested
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## Summary
|
||||||
|
|
||||||
|
<1-2 sentence summary of the review outcome>
|
||||||
|
|
||||||
|
## Reviewed Files
|
||||||
|
|
||||||
|
| File | Change | Assessment |
|
||||||
|
|------|--------|-----------|
|
||||||
|
| `<path>` | New/Modified | ✅ / ⚠️ / ❌ |
|
||||||
|
|
||||||
|
## Checklist
|
||||||
|
|
||||||
|
| # | Check | Result | Note |
|
||||||
|
|---|-------|--------|------|
|
||||||
|
| 1 | Plan compliance | ✅ | All planned changes implemented |
|
||||||
|
| ... | ... | ... | ... |
|
||||||
|
|
||||||
|
## Findings
|
||||||
|
|
||||||
|
### ⚠️ Warnings (non-blocking)
|
||||||
|
|
||||||
|
1. **<file>:<line>** — <description>
|
||||||
|
- Recommendation: <suggested fix>
|
||||||
|
|
||||||
|
### ❌ Blockers (must fix)
|
||||||
|
|
||||||
|
1. **<file>:<line>** — <description>
|
||||||
|
- Reason: <why this must be fixed>
|
||||||
|
|
||||||
|
## Tests
|
||||||
|
|
||||||
|
- **Executed:** <N> tests
|
||||||
|
- **Passed:** <N> ✅
|
||||||
|
- **Failed:** <N> ❌
|
||||||
|
- **Build:** ✅ Green / ❌ Red
|
||||||
|
|
||||||
|
## Recommendation
|
||||||
|
|
||||||
|
<Final recommendation: merge / fix and re-review / reject>
|
||||||
|
```
|
||||||
|
|
||||||
|
### 9. Store in BigMind
|
||||||
|
|
||||||
|
```python
|
||||||
|
memory_store_fact(
|
||||||
|
category="codebase",
|
||||||
|
fact=f"{TICKET_KEY}: Code review completed — {status}. {findings_count} findings ({blockers} blockers)."
|
||||||
|
)
|
||||||
|
```
|
||||||
|
|
||||||
|
## Severity Levels
|
||||||
|
|
||||||
|
| Level | Symbol | Meaning | Action |
|
||||||
|
|-------|--------|---------|--------|
|
||||||
|
| Blocker | ❌ | Must fix before merge | Changes requested |
|
||||||
|
| Warning | ⚠️ | Should fix, not blocking | Approved with comments |
|
||||||
|
| Info | ℹ️ | Suggestion for improvement | Approved |
|
||||||
|
| OK | ✅ | No issues | — |
|
||||||
@@ -0,0 +1,143 @@
|
|||||||
|
---
|
||||||
|
name: create-pr
|
||||||
|
description: Create a Bitbucket pull request from a worktree branch.
|
||||||
|
---
|
||||||
|
|
||||||
|
# Skill: create-pr
|
||||||
|
|
||||||
|
Create a Bitbucket (or GitHub) pull request from a worktree branch.
|
||||||
|
|
||||||
|
## Invoked by
|
||||||
|
|
||||||
|
🎫 JiraOps mode (or 🪃 Orchestrator)
|
||||||
|
|
||||||
|
## Required Inputs
|
||||||
|
|
||||||
|
| Input | Source | Example |
|
||||||
|
|-------|--------|---------|
|
||||||
|
| `TICKET_KEY` | Jira issue key | `PROJECT-123` |
|
||||||
|
| `MODULE` | Module/component name | `auth`, `api`, `core` |
|
||||||
|
|
||||||
|
## Output
|
||||||
|
|
||||||
|
- Pull request created targeting the main branch
|
||||||
|
- Jira comment with PR link added
|
||||||
|
- BigMind fact stored
|
||||||
|
|
||||||
|
## Steps
|
||||||
|
|
||||||
|
### 1. Get current branch
|
||||||
|
|
||||||
|
```bash
|
||||||
|
cd <your-repo-path>-<TICKET_KEY>
|
||||||
|
git branch --show-current
|
||||||
|
```
|
||||||
|
|
||||||
|
### 2. Ensure all changes are committed
|
||||||
|
|
||||||
|
```bash
|
||||||
|
git status
|
||||||
|
```
|
||||||
|
|
||||||
|
If uncommitted changes exist, warn the user before proceeding.
|
||||||
|
|
||||||
|
### 3. Push branch to origin
|
||||||
|
|
||||||
|
```bash
|
||||||
|
git push -u origin <BRANCH>
|
||||||
|
```
|
||||||
|
|
||||||
|
### 4. Gather diff statistics
|
||||||
|
|
||||||
|
```bash
|
||||||
|
git diff origin/main --stat
|
||||||
|
git diff origin/main --name-only
|
||||||
|
```
|
||||||
|
|
||||||
|
### 5. Read Jira ticket for context
|
||||||
|
|
||||||
|
```python
|
||||||
|
ticket = retrieve_ticket_details(TICKET_KEY)
|
||||||
|
# Extract: summary, description for PR title/description
|
||||||
|
```
|
||||||
|
|
||||||
|
### 6. Compose PR title and description
|
||||||
|
|
||||||
|
PR title format:
|
||||||
|
```
|
||||||
|
<TICKET_KEY>: <Jira summary>
|
||||||
|
```
|
||||||
|
|
||||||
|
PR description template:
|
||||||
|
```markdown
|
||||||
|
## Jira
|
||||||
|
|
||||||
|
<TICKET_KEY>: <summary>
|
||||||
|
|
||||||
|
## Description
|
||||||
|
|
||||||
|
<Brief description of what was changed and why>
|
||||||
|
|
||||||
|
## Changes
|
||||||
|
|
||||||
|
<List of changed files grouped by component>
|
||||||
|
|
||||||
|
## Tests
|
||||||
|
|
||||||
|
- <N> Unit tests
|
||||||
|
- <M> Integration tests
|
||||||
|
- All tests passing ✅
|
||||||
|
|
||||||
|
## Checklist
|
||||||
|
|
||||||
|
- [ ] Code review completed
|
||||||
|
- [ ] Tests passing
|
||||||
|
- [ ] No generated source modifications
|
||||||
|
```
|
||||||
|
|
||||||
|
### 7. Create the pull request
|
||||||
|
|
||||||
|
```python
|
||||||
|
create_pull_request(
|
||||||
|
project_key="<PROJECT>",
|
||||||
|
repo_slug="<repo>",
|
||||||
|
title=f"{TICKET_KEY}: {summary}",
|
||||||
|
description=<composed description>,
|
||||||
|
from_branch=<BRANCH>,
|
||||||
|
to_branch="main"
|
||||||
|
)
|
||||||
|
```
|
||||||
|
|
||||||
|
### 8. Add Jira comment with PR link
|
||||||
|
|
||||||
|
```python
|
||||||
|
add_comment_to_ticket(
|
||||||
|
issue_key=TICKET_KEY,
|
||||||
|
comment=f"*Pull Request created*\n\nBranch: {BRANCH}\nPR: [PR #{pr_id}|<pr_url>]"
|
||||||
|
)
|
||||||
|
```
|
||||||
|
|
||||||
|
### 9. Store in BigMind
|
||||||
|
|
||||||
|
```python
|
||||||
|
memory_store_fact(
|
||||||
|
category="codebase",
|
||||||
|
fact=f"{TICKET_KEY}: PR #{pr_id} created — {BRANCH} → main. {N} files changed."
|
||||||
|
)
|
||||||
|
```
|
||||||
|
|
||||||
|
## Error Handling
|
||||||
|
|
||||||
|
| Error | Resolution |
|
||||||
|
|-------|------------|
|
||||||
|
| Branch not pushed | Run `git push -u origin <BRANCH>` first |
|
||||||
|
| Uncommitted changes | Warn user, suggest `git add` + `git commit` |
|
||||||
|
| PR already exists | Check `list_prs_for_repository` for existing PR from same branch |
|
||||||
|
| Merge conflicts | Run `git fetch origin main && git merge origin/main` in worktree |
|
||||||
|
| No diff (empty PR) | Branch is identical to `main` — nothing to merge |
|
||||||
|
|
||||||
|
## Conventions
|
||||||
|
|
||||||
|
- PR title: always starts with `TICKET_KEY:` for Jira auto-linking
|
||||||
|
- Target branch: typically `main` (configure per project)
|
||||||
|
- One PR per ticket — don't create multiple PRs for the same branch
|
||||||
@@ -0,0 +1,154 @@
|
|||||||
|
---
|
||||||
|
name: create-worktree
|
||||||
|
description: Git worktree setup for a Jira ticket. Supports multi-branch strategy with automatic base branch selection. Use when asked to create a worktree, start work on a ticket, or set up a branch for a Jira issue.
|
||||||
|
---
|
||||||
|
|
||||||
|
# Skill: create-worktree
|
||||||
|
|
||||||
|
Git worktree setup for a Jira ticket with correct base branch selection.
|
||||||
|
|
||||||
|
## When to use
|
||||||
|
|
||||||
|
- User asks to create a worktree for a Jira ticket
|
||||||
|
- User asks to "start work on" or "set up" a ticket
|
||||||
|
- Orchestrator delegates worktree creation for a new ticket
|
||||||
|
|
||||||
|
## When NOT to use
|
||||||
|
|
||||||
|
- Switching to an existing worktree → use `switch-worktree` skill
|
||||||
|
- Removing a worktree after merge → see Cleanup section below
|
||||||
|
|
||||||
|
## Invoked by
|
||||||
|
|
||||||
|
🎫 JiraOps mode (or 🪃 Orchestrator)
|
||||||
|
|
||||||
|
## Required Inputs
|
||||||
|
|
||||||
|
| Input | Source | Example |
|
||||||
|
|-------|--------|---------|
|
||||||
|
| `TICKET_ID` | Jira issue key | `PROJECT-123` |
|
||||||
|
| `MODULE` | Ticket context or user input | Module/component name |
|
||||||
|
| `TYPE` | Ticket issue type (Story → feature, Bug → bugfix) | `feature` or `bugfix` |
|
||||||
|
| `SHORT_DESC` | Kebab-case summary (2-4 words) | `fix-auth-timeout` |
|
||||||
|
| `BASE_BRANCH` | (Optional) Long-lived branch to base work on | `main` (default) |
|
||||||
|
|
||||||
|
## Branch Strategy
|
||||||
|
|
||||||
|
| Branch | Purpose | Use as base when... |
|
||||||
|
|--------|---------|-------------------|
|
||||||
|
| `main` | Current development — **DEFAULT** | Standard features, bugs, tasks |
|
||||||
|
| `release` | Current production release (hotfixes) | Urgent hotfixes for production |
|
||||||
|
|
||||||
|
### Base branch → worktree branch prefix mapping
|
||||||
|
|
||||||
|
| BASE_BRANCH | Allowed TYPE | Branch prefix |
|
||||||
|
|-------------|-------------|---------------|
|
||||||
|
| `main` | `feature` or `bugfix` | `feature/...` or `bugfix/...` |
|
||||||
|
| `release` | `bugfix` only | `hotfix/...` |
|
||||||
|
|
||||||
|
## Steps
|
||||||
|
|
||||||
|
### 1. Parse ticket metadata
|
||||||
|
|
||||||
|
```
|
||||||
|
TICKET_KEY = e.g. "PROJECT-123"
|
||||||
|
```
|
||||||
|
|
||||||
|
If MODULE or TYPE are not provided, retrieve them from Jira:
|
||||||
|
- `retrieve_ticket_details(TICKET_KEY)` → read `issuetype` and `summary`
|
||||||
|
- Map issue type: `Story` / `Task` → `feature`, `Bug` → `bugfix`
|
||||||
|
- Infer module from summary keywords or ask the user
|
||||||
|
|
||||||
|
### 2. Determine base branch
|
||||||
|
|
||||||
|
If `BASE_BRANCH` is not explicitly provided, apply this decision logic:
|
||||||
|
|
||||||
|
1. **Default:** `main`
|
||||||
|
2. **If user says "hotfix" or ticket priority is Critical/Blocker:** suggest `release`
|
||||||
|
|
||||||
|
When suggesting a non-default base, confirm with the user before proceeding.
|
||||||
|
|
||||||
|
### 3. Determine branch name
|
||||||
|
|
||||||
|
```
|
||||||
|
BRANCH = <TYPE>/<MODULE>/<TICKET_KEY>-<SHORT_DESC>
|
||||||
|
```
|
||||||
|
|
||||||
|
Examples:
|
||||||
|
- `feature/auth/PROJECT-123-oauth2-timeout`
|
||||||
|
- `bugfix/api/PROJECT-456-null-pointer`
|
||||||
|
- `hotfix/api/PROJECT-789-critical-fix` (base: `release`)
|
||||||
|
|
||||||
|
### 4. Ensure base branch is up to date
|
||||||
|
|
||||||
|
```bash
|
||||||
|
cd <your-repo-path>
|
||||||
|
git fetch origin <BASE_BRANCH>
|
||||||
|
```
|
||||||
|
|
||||||
|
### 5. Create worktree
|
||||||
|
|
||||||
|
```bash
|
||||||
|
git worktree add <your-repo-path>-<TICKET_KEY> -b <BRANCH> origin/<BASE_BRANCH>
|
||||||
|
```
|
||||||
|
|
||||||
|
This creates:
|
||||||
|
- Worktree directory: `<your-repo-path>-<TICKET_KEY>`
|
||||||
|
- New branch: `<BRANCH>` tracking `origin/<BASE_BRANCH>`
|
||||||
|
|
||||||
|
### 6. Verify
|
||||||
|
|
||||||
|
```bash
|
||||||
|
cd <your-repo-path>-<TICKET_KEY> && git branch --show-current
|
||||||
|
```
|
||||||
|
|
||||||
|
### 7. Switch VS Code workspace to worktree
|
||||||
|
|
||||||
|
```bash
|
||||||
|
code --reuse-window <your-repo-path>-<TICKET_KEY>
|
||||||
|
```
|
||||||
|
|
||||||
|
### 8. Store in BigMind
|
||||||
|
|
||||||
|
```python
|
||||||
|
memory_store_fact(
|
||||||
|
category="codebase",
|
||||||
|
fact=f"{TICKET_KEY}: Worktree at <path>, branch {BRANCH}, based on {BASE_BRANCH}"
|
||||||
|
)
|
||||||
|
```
|
||||||
|
|
||||||
|
### 9. Announce focus
|
||||||
|
|
||||||
|
```python
|
||||||
|
memory_announce_focus(
|
||||||
|
session_id=SESSION_ID,
|
||||||
|
description=f"Working on {TICKET_KEY} in worktree",
|
||||||
|
files=[target_path],
|
||||||
|
ide_hint="Roo"
|
||||||
|
)
|
||||||
|
```
|
||||||
|
|
||||||
|
## Expected Output
|
||||||
|
|
||||||
|
- Worktree directory exists
|
||||||
|
- Branch is checked out, based on `origin/<BASE_BRANCH>`
|
||||||
|
- VS Code workspace switched to worktree directory
|
||||||
|
- BigMind fact stored with worktree path and base branch
|
||||||
|
- Focus announced
|
||||||
|
|
||||||
|
## Error Handling
|
||||||
|
|
||||||
|
| Error | Resolution |
|
||||||
|
|-------|------------|
|
||||||
|
| Worktree already exists | Check if branch matches. If yes, reuse. If no, ask user. |
|
||||||
|
| Branch already exists | `git worktree add <path> <BRANCH>` (without `-b`) |
|
||||||
|
| `origin/<BASE_BRANCH>` not found | Try `git fetch origin` first, then retry |
|
||||||
|
| Directory already exists (not a worktree) | Ask user to remove or choose different path |
|
||||||
|
|
||||||
|
## Cleanup (when ticket is done)
|
||||||
|
|
||||||
|
```bash
|
||||||
|
cd <your-repo-path>
|
||||||
|
git worktree remove <your-repo-path>-<TICKET_KEY>
|
||||||
|
git branch -d <BRANCH> # only after merge
|
||||||
|
```
|
||||||
@@ -0,0 +1,122 @@
|
|||||||
|
---
|
||||||
|
name: expert-panel-review
|
||||||
|
description: Multi-expert panel review that analyzes a plan or code from 3 specialized perspectives (Domain Expert, Architecture Expert, Risk/Compliance Expert). Produces a synthesized panel verdict with confidence level. Use when reviewing plans, assessments, or code changes that need high-confidence validation.
|
||||||
|
---
|
||||||
|
|
||||||
|
# Skill: expert-panel-review
|
||||||
|
|
||||||
|
Multi-expert panel review for high-confidence validation of plans and code.
|
||||||
|
|
||||||
|
## When to use
|
||||||
|
|
||||||
|
- Reviewing plans that need multi-perspective validation
|
||||||
|
- Complex architectural decisions requiring diverse expert input
|
||||||
|
- Any change where confidence level matters before proceeding
|
||||||
|
|
||||||
|
## Invoked by
|
||||||
|
|
||||||
|
📋✅ Plan Reviewer mode (as part of plan review workflow)
|
||||||
|
|
||||||
|
## Required Inputs
|
||||||
|
|
||||||
|
| Input | Source | Example |
|
||||||
|
|-------|--------|---------|
|
||||||
|
| `ARTIFACT_TYPE` | Type of artifact being reviewed | `plan`, `assessment`, `code` |
|
||||||
|
| `ARTIFACT_PATH` | Path to the document/code | `docs/auth/PROJECT-123/PROJECT-123-plan.md` |
|
||||||
|
|
||||||
|
## Panel Composition
|
||||||
|
|
||||||
|
### 🏛️ Domain Expert
|
||||||
|
- Validates business logic correctness
|
||||||
|
- Checks domain terminology and workflows
|
||||||
|
- Verifies requirements are fully addressed
|
||||||
|
- Identifies missing business rules
|
||||||
|
|
||||||
|
### 🔧 Architecture Expert
|
||||||
|
- Validates technical design patterns
|
||||||
|
- Checks for scalability and maintainability concerns
|
||||||
|
- Verifies integration points are handled correctly
|
||||||
|
- Identifies missing error handling or edge cases
|
||||||
|
|
||||||
|
### 🛡️ Risk/Compliance Expert
|
||||||
|
- Identifies security implications
|
||||||
|
- Checks for data privacy concerns
|
||||||
|
- Validates audit trail requirements
|
||||||
|
- Flags regulatory compliance gaps
|
||||||
|
|
||||||
|
## Steps
|
||||||
|
|
||||||
|
### 1. Load the artifact
|
||||||
|
|
||||||
|
Read the document at `ARTIFACT_PATH` completely.
|
||||||
|
|
||||||
|
### 2. Domain Expert review
|
||||||
|
|
||||||
|
Analyze from the domain perspective:
|
||||||
|
- Are all business requirements addressed?
|
||||||
|
- Is domain terminology used correctly?
|
||||||
|
- Are business rules complete and accurate?
|
||||||
|
- Are there missing edge cases from a domain perspective?
|
||||||
|
|
||||||
|
Output: findings list + confidence score (0-100%)
|
||||||
|
|
||||||
|
### 3. Architecture Expert review
|
||||||
|
|
||||||
|
Analyze from the technical perspective:
|
||||||
|
- Are design patterns appropriate?
|
||||||
|
- Is the solution maintainable and testable?
|
||||||
|
- Are integration points correctly handled?
|
||||||
|
- Are failure modes addressed?
|
||||||
|
|
||||||
|
Output: findings list + confidence score (0-100%)
|
||||||
|
|
||||||
|
### 4. Risk/Compliance Expert review
|
||||||
|
|
||||||
|
Analyze from a risk perspective:
|
||||||
|
- Are there security implications?
|
||||||
|
- Is data handling appropriate?
|
||||||
|
- Are there compliance requirements being missed?
|
||||||
|
- What's the blast radius if something goes wrong?
|
||||||
|
|
||||||
|
Output: findings list + confidence score (0-100%)
|
||||||
|
|
||||||
|
### 5. Synthesize panel verdict
|
||||||
|
|
||||||
|
Combine all three perspectives:
|
||||||
|
|
||||||
|
```markdown
|
||||||
|
## Panel Verdict
|
||||||
|
|
||||||
|
**Overall Confidence:** <avg of 3 scores>%
|
||||||
|
- Domain: <score>% — <1-line summary>
|
||||||
|
- Architecture: <score>% — <1-line summary>
|
||||||
|
- Risk: <score>% — <1-line summary>
|
||||||
|
|
||||||
|
### Blockers (❌)
|
||||||
|
<items all experts agree must be fixed>
|
||||||
|
|
||||||
|
### Warnings (⚠️)
|
||||||
|
<items raised by 1-2 experts as concerns>
|
||||||
|
|
||||||
|
### Recommendations (ℹ️)
|
||||||
|
<suggestions for improvement>
|
||||||
|
```
|
||||||
|
|
||||||
|
### 6. Confidence interpretation
|
||||||
|
|
||||||
|
| Confidence | Meaning | Action |
|
||||||
|
|-----------|---------|--------|
|
||||||
|
| 90-100% | High confidence — safe to proceed | APPROVED |
|
||||||
|
| 70-89% | Good confidence — minor concerns | APPROVED with warnings |
|
||||||
|
| 50-69% | Mixed signals — significant concerns | REVISE recommended |
|
||||||
|
| < 50% | Low confidence — major gaps | REVISE required |
|
||||||
|
|
||||||
|
## Output Format
|
||||||
|
|
||||||
|
The panel review is embedded in the parent review document (plan-review.md or code-review.md), not as a standalone file.
|
||||||
|
|
||||||
|
## Notes
|
||||||
|
|
||||||
|
- Panel confidence < 70% → parent review MUST be REVISE regardless of checklist
|
||||||
|
- All three experts must produce findings — even if "no concerns" is the finding
|
||||||
|
- Disagreements between experts should be highlighted explicitly
|
||||||
@@ -0,0 +1,136 @@
|
|||||||
|
---
|
||||||
|
name: generate-handover
|
||||||
|
description: Generate handover document for session or person transfer.
|
||||||
|
---
|
||||||
|
|
||||||
|
# Skill: generate-handover
|
||||||
|
|
||||||
|
Generate handover document for session or person transfer.
|
||||||
|
|
||||||
|
## Invoked by
|
||||||
|
|
||||||
|
📝 DocGen mode (or 🪃 Orchestrator)
|
||||||
|
|
||||||
|
## Required Inputs
|
||||||
|
|
||||||
|
| Input | Source | Example |
|
||||||
|
|-------|--------|---------|
|
||||||
|
| `TICKET_KEY` | Jira issue key | `PROJECT-123` |
|
||||||
|
| `MODULE` | Module/component name | `auth`, `api`, `core` |
|
||||||
|
| `SESSION_ID` | BigMind session to hand over (optional) | `d8a0f4fa-...` |
|
||||||
|
|
||||||
|
## Output
|
||||||
|
|
||||||
|
Markdown file: `docs/<MODULE>/<TICKET_KEY>/<TICKET_KEY>-handover-<date>.md`
|
||||||
|
|
||||||
|
## Steps
|
||||||
|
|
||||||
|
### 1. Read BigMind session context
|
||||||
|
|
||||||
|
```python
|
||||||
|
memory_get_session_detail(session_id=SESSION_ID)
|
||||||
|
memory_search_facts("<TICKET_KEY>")
|
||||||
|
memory_search_chunks("<TICKET_KEY>")
|
||||||
|
```
|
||||||
|
|
||||||
|
### 2. Read git status
|
||||||
|
|
||||||
|
```bash
|
||||||
|
cd <worktree-path>
|
||||||
|
git branch --show-current
|
||||||
|
git status
|
||||||
|
git log origin/main..HEAD --oneline
|
||||||
|
git diff origin/main --stat
|
||||||
|
```
|
||||||
|
|
||||||
|
### 3. Read Jira ticket status
|
||||||
|
|
||||||
|
```python
|
||||||
|
ticket = retrieve_ticket_details(TICKET_KEY)
|
||||||
|
checklist = get_checklist(TICKET_KEY)
|
||||||
|
```
|
||||||
|
|
||||||
|
### 4. Read existing documentation
|
||||||
|
|
||||||
|
Check `docs/<MODULE>/<TICKET_KEY>/` for assessment, plan, testplan, solution, review docs.
|
||||||
|
|
||||||
|
### 5. Analyze what's done vs. remaining
|
||||||
|
|
||||||
|
Cross-reference Jira checklist, git commits, test plan status, and plan steps.
|
||||||
|
|
||||||
|
### 6. Generate handover document
|
||||||
|
|
||||||
|
```markdown
|
||||||
|
# Handover: <TICKET_KEY> — <Summary>
|
||||||
|
|
||||||
|
**Date:** <today>
|
||||||
|
**Module:** <MODULE>
|
||||||
|
**Author:** Lumen (DocGen)
|
||||||
|
**BigMind Session:** `<SESSION_ID>`
|
||||||
|
**Branch:** <current branch>
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## 1. Current State
|
||||||
|
|
||||||
|
**Jira Status:** <status>
|
||||||
|
**Progress:** <X>/<Y> checklist items complete
|
||||||
|
|
||||||
|
<1-3 sentence summary>
|
||||||
|
|
||||||
|
## 2. Completed Work
|
||||||
|
|
||||||
|
| # | Description | Files | Commit |
|
||||||
|
|---|------------|-------|--------|
|
||||||
|
| 1 | <what was done> | `<file1>`, `<file2>` | `<hash>` |
|
||||||
|
|
||||||
|
## 3. Remaining Work
|
||||||
|
|
||||||
|
| # | Description | Priority | Estimated Effort |
|
||||||
|
|---|------------|----------|-----------------|
|
||||||
|
| 1 | <what remains> | High/Medium/Low | <estimate> |
|
||||||
|
|
||||||
|
## 4. Open Questions / Blockers
|
||||||
|
|
||||||
|
| # | Question/Blocker | Context | Contact |
|
||||||
|
|---|-----------------|---------|---------|
|
||||||
|
| 1 | <question> | <context> | <who> |
|
||||||
|
|
||||||
|
## 5. Key Decisions
|
||||||
|
|
||||||
|
| Decision | Rationale | Date |
|
||||||
|
|----------|----------|------|
|
||||||
|
| <decision> | <why> | <date> |
|
||||||
|
|
||||||
|
## 6. Technical Notes
|
||||||
|
|
||||||
|
- <Important context the next person needs>
|
||||||
|
- <Environment setup needed>
|
||||||
|
- <Test data requirements>
|
||||||
|
|
||||||
|
## 7. Context Recovery
|
||||||
|
|
||||||
|
For continuing this work:
|
||||||
|
- **Worktree:** `<path>`
|
||||||
|
- **Branch:** `<branch name>`
|
||||||
|
- **BigMind Session:** `<SESSION_ID>` — `memory_get_session_detail("<ID>")` for details
|
||||||
|
- **Documentation:** `docs/<MODULE>/<TICKET_KEY>/`
|
||||||
|
```
|
||||||
|
|
||||||
|
### 7. Store in BigMind
|
||||||
|
|
||||||
|
```python
|
||||||
|
memory_store_fact(
|
||||||
|
category="codebase",
|
||||||
|
fact=f"{TICKET_KEY}: Handover doc created. Status: {done}/{total} items done."
|
||||||
|
)
|
||||||
|
```
|
||||||
|
|
||||||
|
## When to Use
|
||||||
|
|
||||||
|
| Scenario | Trigger |
|
||||||
|
|----------|---------|
|
||||||
|
| End of day | Capture progress before stopping work |
|
||||||
|
| Person transfer | Handing ticket to another developer |
|
||||||
|
| Session recovery | After IDE crash, use to restore context |
|
||||||
|
| Long pause | Before vacation or multi-day break |
|
||||||
@@ -0,0 +1,135 @@
|
|||||||
|
---
|
||||||
|
name: generate-solution-doc
|
||||||
|
description: Solution documentation from implementation results.
|
||||||
|
---
|
||||||
|
|
||||||
|
# Skill: generate-solution-doc
|
||||||
|
|
||||||
|
Solution documentation from implementation results.
|
||||||
|
|
||||||
|
## Invoked by
|
||||||
|
|
||||||
|
📝 DocGen mode
|
||||||
|
|
||||||
|
## Required Inputs
|
||||||
|
|
||||||
|
| Input | Source | Example |
|
||||||
|
|-------|--------|---------|
|
||||||
|
| `TICKET_KEY` | Jira issue key | `PROJECT-123` |
|
||||||
|
| `MODULE` | Module/component name | `auth`, `api`, `core` |
|
||||||
|
| `PLAN_PATH` | Path to plan.md | `docs/auth/PROJECT-123/PROJECT-123-plan.md` |
|
||||||
|
| `TESTPLAN_PATH` | Path to testplan.md | `docs/auth/PROJECT-123/PROJECT-123-testplan.md` |
|
||||||
|
|
||||||
|
## Output
|
||||||
|
|
||||||
|
- Markdown: `docs/<MODULE>/<TICKET_KEY>/<TICKET_KEY>-solution.md`
|
||||||
|
- PDF: `docs/<MODULE>/<TICKET_KEY>/<TICKET_KEY>-solution.pdf`
|
||||||
|
|
||||||
|
## Steps
|
||||||
|
|
||||||
|
### 1. Read input documents
|
||||||
|
|
||||||
|
Read all available docs in `docs/<MODULE>/<TICKET_KEY>/`.
|
||||||
|
|
||||||
|
### 2. Analyze actual changes
|
||||||
|
|
||||||
|
```bash
|
||||||
|
cd <worktree-path>
|
||||||
|
git diff origin/main --stat
|
||||||
|
git diff origin/main --name-only
|
||||||
|
git log origin/main..HEAD --oneline
|
||||||
|
```
|
||||||
|
|
||||||
|
### 3. Gather test results
|
||||||
|
|
||||||
|
Check surefire reports or reference the testplan status.
|
||||||
|
|
||||||
|
### 4. Generate solution document
|
||||||
|
|
||||||
|
```markdown
|
||||||
|
# Solution Documentation: <TICKET_KEY>
|
||||||
|
|
||||||
|
**Date:** <today>
|
||||||
|
**Module:** <MODULE>
|
||||||
|
**Author:** <Your Name>
|
||||||
|
**Jira:** <TICKET_KEY>
|
||||||
|
**Branch:** <branch name>
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## 1. Problem Statement
|
||||||
|
|
||||||
|
<What was the problem? Why did it need solving?>
|
||||||
|
|
||||||
|
## 2. Approach
|
||||||
|
|
||||||
|
<High-level approach chosen. Reference the plan document.>
|
||||||
|
|
||||||
|
## 3. Architecture Decisions
|
||||||
|
|
||||||
|
| Decision | Rationale | Alternatives |
|
||||||
|
|----------|----------|--------------|
|
||||||
|
| <decision> | <why> | <what was considered> |
|
||||||
|
|
||||||
|
## 4. Implemented Changes
|
||||||
|
|
||||||
|
### 4.1 <Component group>
|
||||||
|
|
||||||
|
| File | Change | Description |
|
||||||
|
|------|--------|-------------|
|
||||||
|
| `<path>` | New/Modified | <what changed> |
|
||||||
|
|
||||||
|
### 4.n Database Migrations
|
||||||
|
|
||||||
|
| Migration | Database | Description |
|
||||||
|
|-----------|----------|-------------|
|
||||||
|
| `V{timestamp}__...` | H2/Oracle | <what it does> |
|
||||||
|
|
||||||
|
## 5. Test Coverage
|
||||||
|
|
||||||
|
| ID | Description | Type | Result |
|
||||||
|
|----|-------------|------|--------|
|
||||||
|
| T-01 | <desc> | Unit | ✅ |
|
||||||
|
| T-02 | <desc> | Integration | ✅ |
|
||||||
|
|
||||||
|
## 6. Open Items
|
||||||
|
|
||||||
|
| # | Description | Priority | Ticket |
|
||||||
|
|---|-------------|----------|--------|
|
||||||
|
| 1 | <open item> | High/Medium/Low | <linked ticket or "—"> |
|
||||||
|
```
|
||||||
|
|
||||||
|
### 5. Ask for PDF color scheme
|
||||||
|
|
||||||
|
> "Which color scheme for the PDF? Available: adp (red), royal_purple, ocean, forest, sunset, slate, rose"
|
||||||
|
|
||||||
|
### 6. Generate PDF
|
||||||
|
|
||||||
|
```python
|
||||||
|
generate_pdf(
|
||||||
|
content=<markdown content>,
|
||||||
|
title=f"Solution Documentation {TICKET_KEY}",
|
||||||
|
author="Your Name",
|
||||||
|
output_path=f"docs/<MODULE>/<TICKET_KEY>/<TICKET_KEY>-solution.pdf",
|
||||||
|
color_scheme=<chosen scheme>
|
||||||
|
)
|
||||||
|
```
|
||||||
|
|
||||||
|
### 7. Store in BigMind
|
||||||
|
|
||||||
|
```python
|
||||||
|
memory_store_fact(
|
||||||
|
category="codebase",
|
||||||
|
fact=f"{TICKET_KEY}: Solution doc created, PDF generated"
|
||||||
|
)
|
||||||
|
```
|
||||||
|
|
||||||
|
## Template Variants
|
||||||
|
|
||||||
|
### Minimal (for small bugfixes)
|
||||||
|
|
||||||
|
Skip sections 3 (Architecture Decisions) and 6 (Open Items). Keep 1, 2, 4, 5.
|
||||||
|
|
||||||
|
### Extended (for large features)
|
||||||
|
|
||||||
|
Add: Configuration Changes, Deployment Notes, Backward Compatibility, Performance Impact.
|
||||||
@@ -0,0 +1,123 @@
|
|||||||
|
---
|
||||||
|
name: generate-testplan
|
||||||
|
description: Structured test plan from implementation plan / assessment.
|
||||||
|
---
|
||||||
|
|
||||||
|
# Skill: generate-testplan
|
||||||
|
|
||||||
|
Structured test plan from implementation plan / assessment.
|
||||||
|
|
||||||
|
## Invoked by
|
||||||
|
|
||||||
|
📋 Planner mode
|
||||||
|
|
||||||
|
## Required Inputs
|
||||||
|
|
||||||
|
| Input | Source | Example |
|
||||||
|
|-------|--------|---------|
|
||||||
|
| `TICKET_KEY` | Jira issue key | `PROJECT-123` |
|
||||||
|
| `MODULE` | Module/component name | `auth`, `api`, `core` |
|
||||||
|
| `PLAN_PATH` | Path to plan.md | `docs/auth/PROJECT-123/PROJECT-123-plan.md` |
|
||||||
|
|
||||||
|
## Output
|
||||||
|
|
||||||
|
Markdown file: `docs/<MODULE>/<TICKET_KEY>/<TICKET_KEY>-testplan.md`
|
||||||
|
|
||||||
|
## Steps
|
||||||
|
|
||||||
|
### 1. Read the implementation plan
|
||||||
|
|
||||||
|
Understand which classes/methods are being added or modified, data flows affected, database changes, and integration points.
|
||||||
|
|
||||||
|
### 2. Identify testable units
|
||||||
|
|
||||||
|
| Category | What to test | Test type |
|
||||||
|
|----------|-------------|-----------|
|
||||||
|
| New methods | Input/output, edge cases, null handling | Unit |
|
||||||
|
| Modified methods | Regression + new behavior | Unit |
|
||||||
|
| Database changes | Migration up/down, data integrity | Integration |
|
||||||
|
| Data flows | End-to-end processing | Integration |
|
||||||
|
| Error paths | Invalid input, missing data, error responses | Unit |
|
||||||
|
|
||||||
|
### 3. Generate test plan document
|
||||||
|
|
||||||
|
```markdown
|
||||||
|
# Test Plan: <TICKET_KEY> — <Summary>
|
||||||
|
|
||||||
|
**Date:** <today>
|
||||||
|
**Module:** <MODULE>
|
||||||
|
**Author:** Lumen (Planner)
|
||||||
|
**Status:** Draft v1
|
||||||
|
**Based on:** <TICKET_KEY>-plan.md
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## Test Overview
|
||||||
|
|
||||||
|
| ID | Description | Type | Class | Status |
|
||||||
|
|----|-------------|------|-------|--------|
|
||||||
|
| T-01 | <short desc> | Unit | <TestClass> | ⬜ |
|
||||||
|
| T-02 | <short desc> | Unit | <TestClass> | ⬜ |
|
||||||
|
| T-03 | <short desc> | Integration | <TestClass> | ⬜ |
|
||||||
|
|
||||||
|
Status: ⬜ Open | ✅ Passed | ❌ Failed | ⏭️ Skipped
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## Test Cases
|
||||||
|
|
||||||
|
### T-01: <Descriptive name>
|
||||||
|
|
||||||
|
**Type:** Unit
|
||||||
|
**Class:** `<package>.<TestClassName>`
|
||||||
|
**Method:** `test<MethodName>()`
|
||||||
|
|
||||||
|
**Preconditions:**
|
||||||
|
- <setup requirements>
|
||||||
|
|
||||||
|
**Scenarios:**
|
||||||
|
|
||||||
|
| # | Input | Expected Result |
|
||||||
|
|---|-------|----------------|
|
||||||
|
| a | <input> | <expected> |
|
||||||
|
| b | <input> | <expected> |
|
||||||
|
| c | <edge case> | <expected> |
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## Test Data
|
||||||
|
|
||||||
|
<Describe test data requirements, fixtures, or database setup needed.>
|
||||||
|
|
||||||
|
## Test Coverage
|
||||||
|
|
||||||
|
| Component | Unit | Integration | Total |
|
||||||
|
|-----------|------|-------------|-------|
|
||||||
|
| <Class1> | 3 | 1 | 4 |
|
||||||
|
| <Class2> | 2 | 0 | 2 |
|
||||||
|
| **Total** | **5** | **1** | **6** |
|
||||||
|
```
|
||||||
|
|
||||||
|
### 4. Cross-reference with plan
|
||||||
|
|
||||||
|
Verify every implementation step has at least one test case. Flag gaps as warnings.
|
||||||
|
|
||||||
|
### 5. Store in BigMind
|
||||||
|
|
||||||
|
```python
|
||||||
|
memory_store_fact(
|
||||||
|
category="codebase",
|
||||||
|
fact=f"{TICKET_KEY}: Testplan with {N} test cases (Unit: {u}, Integration: {i})"
|
||||||
|
)
|
||||||
|
```
|
||||||
|
|
||||||
|
## Test Naming Conventions
|
||||||
|
|
||||||
|
- Test class: `<OriginalClass>Test.java` or `<Feature>Test.java`
|
||||||
|
- Test method: `test<What>_<Scenario>_<Expected>()` or `test<What>()` for simple cases
|
||||||
|
- Location: mirror source structure under `src/test/java/`
|
||||||
|
|
||||||
|
## Test ID Format
|
||||||
|
|
||||||
|
- Sequential: T-01, T-02, ..., T-nn
|
||||||
|
- IDs are stable — don't renumber on revision, append new tests at the end
|
||||||
@@ -0,0 +1,173 @@
|
|||||||
|
---
|
||||||
|
name: mvn-test
|
||||||
|
description: Run Maven tests in multi-module projects. Resolves module paths, builds dependencies, parses surefire XML reports, and returns structured pass/fail results. Use when asked to run tests, execute test classes, or verify a module build.
|
||||||
|
---
|
||||||
|
|
||||||
|
# Maven Test & Build Runner
|
||||||
|
|
||||||
|
## When to use
|
||||||
|
|
||||||
|
- Running all tests for a module in a multi-module Maven project
|
||||||
|
- Running a specific test class or method
|
||||||
|
- Building a fat JAR for deployment
|
||||||
|
- Verifying a build after code changes in a worktree
|
||||||
|
- Troubleshooting Maven dependency/version issues
|
||||||
|
|
||||||
|
## When NOT to use
|
||||||
|
|
||||||
|
- SSH integration tests on remote instances → use a dedicated SSH test skill
|
||||||
|
- Creating new test files → use Code mode directly
|
||||||
|
- Running non-Maven tests (npm, etc.)
|
||||||
|
|
||||||
|
## Required Inputs
|
||||||
|
|
||||||
|
| Input | Source | Example |
|
||||||
|
|-------|--------|---------|
|
||||||
|
| `TICKET_KEY` | Issue key or task ID | `PROJECT-123` |
|
||||||
|
| `MODULE` | Maven module name | `module-a`, `module-b`, `persistence` |
|
||||||
|
| `TEST_CLASS` | Fully qualified test class (optional) | `com.example.service.MyServiceTest` |
|
||||||
|
|
||||||
|
## Module Path Resolution
|
||||||
|
|
||||||
|
| Module name | Maven `-pl` path |
|
||||||
|
|------------|-----------------|
|
||||||
|
| module-a | `java/modules/cs-modules/module-a` |
|
||||||
|
| module-b | `java/modules/cs-modules/module-b` |
|
||||||
|
| nested-module | `java/modules/cs-modules/parent-group/nested-module` |
|
||||||
|
| persistence | `java/persistence` |
|
||||||
|
| shared-lib | `java/modules/shared-lib` |
|
||||||
|
|
||||||
|
If the module is not in this table, search for it:
|
||||||
|
```bash
|
||||||
|
find java/modules -name "pom.xml" -path "*/<MODULE>/*" | head -3
|
||||||
|
```
|
||||||
|
|
||||||
|
## Workflow
|
||||||
|
|
||||||
|
### 1. Determine worktree path
|
||||||
|
|
||||||
|
```bash
|
||||||
|
WORKTREE="<your-repo-path>"
|
||||||
|
# Verify it exists
|
||||||
|
ls "$WORKTREE/java/pom.xml"
|
||||||
|
```
|
||||||
|
|
||||||
|
If no worktree exists, fall back to the main repo path
|
||||||
|
|
||||||
|
### 2. Resolve module path
|
||||||
|
|
||||||
|
Look up `MODULE` in the path resolution table above. Store as `MODULE_PATH`.
|
||||||
|
|
||||||
|
### 3. Run tests
|
||||||
|
|
||||||
|
**All module tests:**
|
||||||
|
```bash
|
||||||
|
cd <WORKTREE> && mvn test -pl <MODULE_PATH> -am -f java/pom.xml
|
||||||
|
```
|
||||||
|
|
||||||
|
**Specific test class:**
|
||||||
|
```bash
|
||||||
|
cd <WORKTREE> && mvn test -pl <MODULE_PATH> -am -Dtest="<TEST_CLASS>" -Dsurefire.failIfNoSpecifiedTests=false -f java/pom.xml
|
||||||
|
```
|
||||||
|
|
||||||
|
**Specific test method:**
|
||||||
|
```bash
|
||||||
|
cd <WORKTREE> && mvn test -pl <MODULE_PATH> -am -Dtest="<TEST_CLASS>#<methodName>" -Dsurefire.failIfNoSpecifiedTests=false -f java/pom.xml
|
||||||
|
```
|
||||||
|
|
||||||
|
### 4. Parse results
|
||||||
|
|
||||||
|
Look for these patterns in the output:
|
||||||
|
|
||||||
|
| Pattern | Meaning |
|
||||||
|
|---------|---------|
|
||||||
|
| `Tests run: N, Failures: F, Errors: E, Skipped: S` | Surefire summary |
|
||||||
|
| `BUILD SUCCESS` | All tests passed |
|
||||||
|
| `BUILD FAILURE` | At least one test failed or compilation error |
|
||||||
|
| `There are test failures` | Link to surefire reports |
|
||||||
|
|
||||||
|
If tests fail, read the surefire report:
|
||||||
|
```bash
|
||||||
|
find <WORKTREE>/<MODULE_PATH>/target/surefire-reports -name "*.txt" -exec grep -l "FAILURE\|ERROR" {} \;
|
||||||
|
```
|
||||||
|
|
||||||
|
### 5. Store results in BigMind
|
||||||
|
|
||||||
|
```python
|
||||||
|
memory_store_fact(
|
||||||
|
category="codebase",
|
||||||
|
fact=f"{TICKET_KEY}: mvn test {MODULE} — {tests_run} run, {failures} failures, {errors} errors. {'BUILD SUCCESS' or 'BUILD FAILURE'}"
|
||||||
|
)
|
||||||
|
```
|
||||||
|
|
||||||
|
## Building Fat JARs (for deployment)
|
||||||
|
|
||||||
|
### Package a module with all dependencies:
|
||||||
|
```bash
|
||||||
|
cd <WORKTREE> && mvn package -pl :<ARTIFACT_ID> -am -DskipTests -f java/pom.xml -Drevision=1.0.0-TEST -o -q
|
||||||
|
```
|
||||||
|
|
||||||
|
### Locate the built JAR:
|
||||||
|
```bash
|
||||||
|
find <MODULE_PATH>/target -name "*-jar-with-dependencies.jar" | head -1
|
||||||
|
```
|
||||||
|
|
||||||
|
### Module artifact IDs (for `-pl :NAME`):
|
||||||
|
|
||||||
|
| Module | Artifact ID | Fat JAR name |
|
||||||
|
|--------|-------------|-------------|
|
||||||
|
| module-a | `ModuleA` | `ModuleA-*-jar-with-dependencies.jar` |
|
||||||
|
| module-b | `ModuleB` | `ModuleB-*-jar-with-dependencies.jar` |
|
||||||
|
| persistence | `persistence` | (no fat JAR) |
|
||||||
|
|
||||||
|
Use `:ARTIFACT_ID` with `-pl` for single-module builds (faster than path-based).
|
||||||
|
|
||||||
|
## Critical: Version Timestamp Issue
|
||||||
|
|
||||||
|
If the project uses a Maven `${revision}` timestamp-based SNAPSHOT scheme (e.g. `1.0-DEV-SNAPSHOT-<timestamp>`), the snapshot changes every minute; ensure dependent modules are rebuilt in the same run.
|
||||||
|
|
||||||
|
**Problem:** If you `mvn install` at 07:55 and then `mvn test` at 07:56, the version changed and artifacts can't be found.
|
||||||
|
|
||||||
|
**Solutions:**
|
||||||
|
|
||||||
|
1. **Always use `-am` (also-make)** — builds from source, no cached artifacts needed
|
||||||
|
2. **Pin the version:** `-Drevision=1.0.0-TEST` — stable across commands
|
||||||
|
3. **Use `-o` (offline)** — prevents remote lookups that fail on VPN/cert issues
|
||||||
|
4. **Never use `-pl` without `-am`** for test runs — dependencies won't resolve
|
||||||
|
|
||||||
|
### Recommended command patterns:
|
||||||
|
|
||||||
|
```bash
|
||||||
|
# Compile check (fast)
|
||||||
|
mvn compile -pl :<ARTIFACT_ID> -am -f java/pom.xml -o -q
|
||||||
|
|
||||||
|
# Run specific test (reliable)
|
||||||
|
mvn test -pl :<ARTIFACT_ID> -am -f java/pom.xml \
|
||||||
|
-Dtest="com.example.MyTest" \
|
||||||
|
-Dsurefire.failIfNoSpecifiedTests=false \
|
||||||
|
-Dmaven.test.skip=false -DskipTests=false \
|
||||||
|
-Drevision=1.0.0-TEST -o
|
||||||
|
|
||||||
|
# Build fat JAR for deployment
|
||||||
|
mvn package -pl :<ARTIFACT_ID> -am -DskipTests -f java/pom.xml \
|
||||||
|
-Drevision=1.0.0-TEST -o -q
|
||||||
|
```
|
||||||
|
|
||||||
|
### Why `-Dmaven.test.skip=false -DskipTests=false`?
|
||||||
|
|
||||||
|
Some modules have `<skipTests>true</skipTests>` in their POM or parent POM. These flags override that to force test execution.
|
||||||
|
|
||||||
|
## Troubleshooting
|
||||||
|
|
||||||
|
| Problem | Solution |
|
||||||
|
|---------|----------|
|
||||||
|
| `Could not find artifact` | Add `-am` flag to build dependencies first |
|
||||||
|
| `No tests were executed` | Check test class path — use package-relative path, not fully qualified with `src/test/java/` |
|
||||||
|
| `Compilation failure` in dependency | Run `mvn compile -pl <MODULE_PATH> -am -f java/pom.xml` first to isolate |
|
||||||
|
| OOM during tests | Add `-Xmx1g` via `MAVEN_OPTS`: `MAVEN_OPTS="-Xmx1g" mvn test ...` |
|
||||||
|
| Test hangs | Add `-Dsurefire.timeout=120` to kill stuck tests after 120s |
|
||||||
|
| `Tests are skipped` | Add `-Dmaven.test.skip=false -DskipTests=false` |
|
||||||
|
| Version mismatch (timestamp) | Pin with `-Drevision=1.0.0-TEST` |
|
||||||
|
| Certificate/SSL error on artifact download | Add `-o` (offline) — use local sources with `-am` |
|
||||||
|
| `No tests matching pattern` in dependency modules | Add `-Dsurefire.failIfNoSpecifiedTests=false` |
|
||||||
|
| Wrong module selected by `-pl` | Use artifact ID (`:ModuleA`) not path — check with `grep '<artifactId>' <MODULE_PATH>/pom.xml` |
|
||||||
@@ -0,0 +1,160 @@
|
|||||||
|
---
|
||||||
|
name: plan-review
|
||||||
|
description: Plan and testplan quality review before implementation. Produces APPROVED/REVISE verdict.
|
||||||
|
---
|
||||||
|
|
||||||
|
# Skill: plan-review
|
||||||
|
|
||||||
|
Plan and testplan quality review before implementation.
|
||||||
|
|
||||||
|
## Invoked by
|
||||||
|
|
||||||
|
📋✅ Plan Reviewer mode
|
||||||
|
|
||||||
|
## Required Inputs
|
||||||
|
|
||||||
|
| Input | Source | Example |
|
||||||
|
|-------|--------|---------|
|
||||||
|
| `TICKET_KEY` | Jira issue key | `PROJECT-123` |
|
||||||
|
| `MODULE` | Module/component name | `auth`, `api`, `core` |
|
||||||
|
|
||||||
|
## Output
|
||||||
|
|
||||||
|
Markdown file: `docs/<MODULE>/<TICKET_KEY>/<TICKET_KEY>-plan-review.md`
|
||||||
|
|
||||||
|
## Steps
|
||||||
|
|
||||||
|
### 1. Read the planning documents
|
||||||
|
|
||||||
|
- Assessment (`*-assessment.md`) — required
|
||||||
|
- Implementation plan (`*-plan.md`) — required
|
||||||
|
- Test plan (`*-testplan.md`) — required
|
||||||
|
|
||||||
|
If any required document is missing, flag as REVISE immediately.
|
||||||
|
|
||||||
|
### 2. Read the Jira ticket
|
||||||
|
|
||||||
|
Cross-reference: do the plan documents address ALL requirements from the ticket?
|
||||||
|
|
||||||
|
### 3. Read affected source code
|
||||||
|
|
||||||
|
For each file/class mentioned in the plan:
|
||||||
|
- Verify the file exists at the stated path
|
||||||
|
- Verify class/method names are correct
|
||||||
|
- Verify patterns described match actual code
|
||||||
|
- Check if the plan missed related files
|
||||||
|
|
||||||
|
### 4. Run the plan review checklist
|
||||||
|
|
||||||
|
#### Assessment Review
|
||||||
|
|
||||||
|
| # | Check |
|
||||||
|
|---|-------|
|
||||||
|
| 1 | Problem statement complete and matches Jira ticket |
|
||||||
|
| 2 | Affected components identified — any missing? |
|
||||||
|
| 3 | Current state description matches actual code |
|
||||||
|
| 4 | Risk assessment realistic |
|
||||||
|
| 5 | Solution options evaluated with justification |
|
||||||
|
|
||||||
|
#### Implementation Plan Review
|
||||||
|
|
||||||
|
| # | Check |
|
||||||
|
|---|-------|
|
||||||
|
| 6 | All requirements covered |
|
||||||
|
| 7 | Correct project patterns referenced |
|
||||||
|
| 8 | File paths correct and exist |
|
||||||
|
| 9 | Implementation order logical (dependencies first) |
|
||||||
|
| 10 | No gaps between steps |
|
||||||
|
| 11 | Database migrations planned (if needed) |
|
||||||
|
| 12 | Error handling planned (not just happy path) |
|
||||||
|
| 13 | No scope creep beyond ticket requirements |
|
||||||
|
|
||||||
|
#### Test Plan Review
|
||||||
|
|
||||||
|
| # | Check |
|
||||||
|
|---|-------|
|
||||||
|
| 14 | Coverage complete — every plan step has a test |
|
||||||
|
| 15 | Test types appropriate (unit vs integration) |
|
||||||
|
| 16 | Edge cases covered (null, empty, boundary values) |
|
||||||
|
| 17 | Test class naming correct |
|
||||||
|
| 18 | Test method naming correct |
|
||||||
|
| 19 | Test data defined |
|
||||||
|
|
||||||
|
### 5. Run expert-panel-review skill
|
||||||
|
|
||||||
|
Before generating the verdict, run the `expert-panel-review` skill for multi-perspective analysis. Panel confidence < 70% → verdict MUST be REVISE.
|
||||||
|
|
||||||
|
### 6. Generate plan review document
|
||||||
|
|
||||||
|
```markdown
|
||||||
|
# Plan Review: <TICKET_KEY> — <Summary>
|
||||||
|
|
||||||
|
**Date:** <today>
|
||||||
|
**Module:** <MODULE>
|
||||||
|
**Reviewer:** Lumen (Plan Reviewer)
|
||||||
|
**Documents:** assessment.md v<N>, plan.md v<N>, testplan.md v<N>
|
||||||
|
**Verdict:** ✅ APPROVED / 🔄 REVISE
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## Summary
|
||||||
|
|
||||||
|
<1-2 sentence summary>
|
||||||
|
|
||||||
|
## Checklist
|
||||||
|
|
||||||
|
| # | Check | Result | Note |
|
||||||
|
|---|-------|--------|------|
|
||||||
|
| 1 | Problem statement complete | ✅/❌ | |
|
||||||
|
| ... | ... | ... | ... |
|
||||||
|
|
||||||
|
## Findings
|
||||||
|
|
||||||
|
### ❌ Must revise (blocking)
|
||||||
|
|
||||||
|
1. **<document>** — <issue>
|
||||||
|
|
||||||
|
### ⚠️ Suggestions (non-blocking)
|
||||||
|
|
||||||
|
1. **<document>** — <suggestion>
|
||||||
|
|
||||||
|
## Traceability Matrix
|
||||||
|
|
||||||
|
| Requirement | Plan Step | Test Case | Status |
|
||||||
|
|------------|-----------|-----------|--------|
|
||||||
|
| <req 1> | Step <N> | T-<NN> | ✅ Covered |
|
||||||
|
|
||||||
|
## Verdict
|
||||||
|
|
||||||
|
**✅ APPROVED** — Plan is complete and ready for implementation.
|
||||||
|
— or —
|
||||||
|
**🔄 REVISE** — <N> items need rework. Back to Planner.
|
||||||
|
**Panel Confidence:** <X>%
|
||||||
|
```
|
||||||
|
|
||||||
|
### 7. Store in BigMind
|
||||||
|
|
||||||
|
```python
|
||||||
|
memory_store_fact(
|
||||||
|
category="codebase",
|
||||||
|
fact=f"{TICKET_KEY}: Plan review — {verdict}. {findings} findings ({blockers} blocking)."
|
||||||
|
)
|
||||||
|
```
|
||||||
|
|
||||||
|
## Verdict Criteria
|
||||||
|
|
||||||
|
| Verdict | Criteria |
|
||||||
|
|---------|---------|
|
||||||
|
| ✅ APPROVED | All checklist items pass. No blocking findings. Panel confidence ≥ 70%. |
|
||||||
|
| 🔄 REVISE | Any checklist item fails, or panel confidence < 70%. |
|
||||||
|
|
||||||
|
## Review Loop
|
||||||
|
|
||||||
|
1. Planner produces v1 documents
|
||||||
|
2. Plan Reviewer reviews → REVISE with findings
|
||||||
|
3. Planner revises → v2 documents
|
||||||
|
4. Plan Reviewer reviews → APPROVED
|
||||||
|
5. User gives GO
|
||||||
|
6. Pipeline proceeds
|
||||||
|
|
||||||
|
Max 3 iterations recommended.
|
||||||
@@ -0,0 +1,460 @@
|
|||||||
|
---
|
||||||
|
name: playwright-e2e
|
||||||
|
description: Set up standardized Playwright E2E test infrastructure for Next.js + Spring Boot projects. Creates 3-project config (setup/authenticated/unauthenticated), auth flow, Docker test environment, accessibility tests, and seed data. Use when asked to set up Playwright tests, create E2E test infrastructure, add Playwright to a project, or create an integration test harness.
|
||||||
|
---
|
||||||
|
|
||||||
|
# Playwright E2E Test Infrastructure
|
||||||
|
|
||||||
|
## When to use
|
||||||
|
|
||||||
|
- Setting up Playwright E2E tests for a Next.js + backend project
|
||||||
|
- Creating test infrastructure from scratch
|
||||||
|
- Adding authentication-aware E2E testing
|
||||||
|
- Setting up accessibility testing with axe-core
|
||||||
|
- Triggers: "set up Playwright tests", "create E2E test infrastructure", "add Playwright to this project", "E2E test suite", "create integration test harness"
|
||||||
|
|
||||||
|
## When NOT to use
|
||||||
|
|
||||||
|
- Unit testing (use Jest/Vitest instead)
|
||||||
|
- API-only testing without a frontend (use Postman/REST client)
|
||||||
|
- Projects without a web frontend
|
||||||
|
- Adding individual test files to an existing Playwright setup (just write the test directly)
|
||||||
|
|
||||||
|
## Required Inputs
|
||||||
|
|
||||||
|
| Input | Source | Example |
|
||||||
|
|-------|--------|---------|
|
||||||
|
| `PROJECT_DIR` | Current workspace | `/Users/pplate/git/personal/inspectflow` |
|
||||||
|
| `FRONTEND_DIR` | Relative path to frontend | `frontend/` |
|
||||||
|
| `BASE_URL` | Dev server URL | `http://localhost:3000` |
|
||||||
|
| `API_URL` | Backend URL | `http://localhost:8080` |
|
||||||
|
| `LOGIN_EMAIL` | Test user email | `admin@test.de` |
|
||||||
|
| `LOGIN_PASSWORD` | Test user password | `test123` |
|
||||||
|
|
||||||
|
## Expected Output
|
||||||
|
|
||||||
|
- `playwright.config.ts` (3-project architecture)
|
||||||
|
- `e2e/auth.setup.ts`
|
||||||
|
- `e2e/auth-flow.unauth.spec.ts`
|
||||||
|
- `e2e/crud-flow.spec.ts` (template)
|
||||||
|
- `e2e/navigation.spec.ts` (template)
|
||||||
|
- `e2e/accessibility.spec.ts`
|
||||||
|
- `docker-compose.test.yml`
|
||||||
|
- `scripts/seed.sql`
|
||||||
|
- Updated `package.json` scripts
|
||||||
|
- Updated `.gitignore`
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## Workflow
|
||||||
|
|
||||||
|
### Step 1: Install dependencies
|
||||||
|
|
||||||
|
```bash
|
||||||
|
cd <FRONTEND_DIR>
|
||||||
|
pnpm add -D @playwright/test @axe-core/playwright
|
||||||
|
npx playwright install chromium
|
||||||
|
```
|
||||||
|
|
||||||
|
### Step 2: Create `playwright.config.ts`
|
||||||
|
|
||||||
|
Place in `<FRONTEND_DIR>/playwright.config.ts`:
|
||||||
|
|
||||||
|
```typescript
|
||||||
|
import { defineConfig, devices } from '@playwright/test';
|
||||||
|
|
||||||
|
export default defineConfig({
|
||||||
|
testDir: './e2e',
|
||||||
|
fullyParallel: true,
|
||||||
|
forbidOnly: !!process.env.CI,
|
||||||
|
retries: process.env.CI ? 2 : 0,
|
||||||
|
workers: process.env.CI ? 1 : undefined,
|
||||||
|
reporter: [['html'], ['list']],
|
||||||
|
|
||||||
|
use: {
|
||||||
|
baseURL: process.env.BASE_URL || '<BASE_URL>',
|
||||||
|
trace: 'on-first-retry',
|
||||||
|
screenshot: 'only-on-failure',
|
||||||
|
video: 'retain-on-failure',
|
||||||
|
},
|
||||||
|
|
||||||
|
projects: [
|
||||||
|
{
|
||||||
|
name: 'setup',
|
||||||
|
testMatch: /.*\.setup\.ts/,
|
||||||
|
},
|
||||||
|
{
|
||||||
|
name: 'authenticated',
|
||||||
|
use: {
|
||||||
|
...devices['Desktop Chrome'],
|
||||||
|
storageState: '.auth/admin.json',
|
||||||
|
},
|
||||||
|
dependencies: ['setup'],
|
||||||
|
testIgnore: /.*\.unauth\.spec\.ts/,
|
||||||
|
},
|
||||||
|
{
|
||||||
|
name: 'unauthenticated',
|
||||||
|
use: { ...devices['Desktop Chrome'] },
|
||||||
|
testMatch: /.*\.unauth\.spec\.ts/,
|
||||||
|
},
|
||||||
|
],
|
||||||
|
});
|
||||||
|
```
|
||||||
|
|
||||||
|
**Key architecture:**
|
||||||
|
- `setup` project runs `auth.setup.ts` first — logs in once, saves session
|
||||||
|
- `authenticated` project reuses saved `storageState` — no repeated logins
|
||||||
|
- `unauthenticated` project has no auth state — tests public pages and login flows
|
||||||
|
|
||||||
|
### Step 3: Create `e2e/auth.setup.ts`
|
||||||
|
|
||||||
|
```typescript
|
||||||
|
import { test as setup, expect } from '@playwright/test';
|
||||||
|
|
||||||
|
const authFile = '.auth/admin.json';
|
||||||
|
|
||||||
|
setup('authenticate', async ({ page }) => {
|
||||||
|
const email = process.env.TEST_EMAIL || '<LOGIN_EMAIL>';
|
||||||
|
const password = process.env.TEST_PASSWORD || '<LOGIN_PASSWORD>';
|
||||||
|
|
||||||
|
await page.goto('/login');
|
||||||
|
await page.getByLabel('E-Mail').fill(email);
|
||||||
|
await page.getByLabel('Passwort').fill(password);
|
||||||
|
await page.getByRole('button', { name: /anmelden|login|sign in/i }).click();
|
||||||
|
|
||||||
|
// Wait for successful redirect to dashboard
|
||||||
|
await page.waitForURL('**/dashboard');
|
||||||
|
await expect(page.locator('body')).not.toContainText('Login');
|
||||||
|
|
||||||
|
// Save authentication state
|
||||||
|
await page.context().storageState({ path: authFile });
|
||||||
|
});
|
||||||
|
```
|
||||||
|
|
||||||
|
### Step 4: Create `docker-compose.test.yml`
|
||||||
|
|
||||||
|
Place in `<PROJECT_DIR>/docker-compose.test.yml`:
|
||||||
|
|
||||||
|
```yaml
|
||||||
|
services:
|
||||||
|
test-db:
|
||||||
|
image: postgres:17-alpine
|
||||||
|
environment:
|
||||||
|
POSTGRES_DB: testdb
|
||||||
|
POSTGRES_USER: test
|
||||||
|
POSTGRES_PASSWORD: test
|
||||||
|
ports:
|
||||||
|
- "5433:5432"
|
||||||
|
volumes:
|
||||||
|
- ./scripts/seed.sql:/docker-entrypoint-initdb.d/01-seed.sql
|
||||||
|
healthcheck:
|
||||||
|
test: ["CMD-SHELL", "pg_isready -U test -d testdb"]
|
||||||
|
interval: 5s
|
||||||
|
timeout: 5s
|
||||||
|
retries: 5
|
||||||
|
|
||||||
|
backend:
|
||||||
|
build:
|
||||||
|
context: ./backend
|
||||||
|
dockerfile: Dockerfile
|
||||||
|
environment:
|
||||||
|
SPRING_PROFILES_ACTIVE: test
|
||||||
|
SPRING_DATASOURCE_URL: jdbc:postgresql://test-db:5432/testdb
|
||||||
|
SPRING_DATASOURCE_USERNAME: test
|
||||||
|
SPRING_DATASOURCE_PASSWORD: test
|
||||||
|
JWT_SECRET: test-secret-key-for-e2e-testing-only
|
||||||
|
ports:
|
||||||
|
- "8080:8080"
|
||||||
|
depends_on:
|
||||||
|
test-db:
|
||||||
|
condition: service_healthy
|
||||||
|
healthcheck:
|
||||||
|
test: ["CMD", "curl", "-f", "http://localhost:8080/actuator/health"]
|
||||||
|
interval: 10s
|
||||||
|
timeout: 5s
|
||||||
|
retries: 10
|
||||||
|
```
|
||||||
|
|
||||||
|
### Step 5: Create `scripts/seed.sql`
|
||||||
|
|
||||||
|
```sql
|
||||||
|
-- E2E Test Seed Data
|
||||||
|
-- Password "test123" as BCrypt hash
|
||||||
|
-- Verify with: echo -n "test123" | htpasswd -bnBC 10 "" - | cut -d: -f2
|
||||||
|
|
||||||
|
INSERT INTO users (email, password_hash, name, role, active)
|
||||||
|
VALUES (
|
||||||
|
'<LOGIN_EMAIL>',
|
||||||
|
'$2a$10$/FgU1KyveJ7MaQ7Xv4kxD.5EIQUHujJfZI4K2E1H7pS6parMHJpeG',
|
||||||
|
'Test Admin',
|
||||||
|
'ADMIN',
|
||||||
|
true
|
||||||
|
) ON CONFLICT (email) DO NOTHING;
|
||||||
|
|
||||||
|
-- Sample data (adapt to your schema)
|
||||||
|
-- INSERT INTO companies (name, created_by) VALUES ('Test GmbH', 1);
|
||||||
|
```
|
||||||
|
|
||||||
|
⚠️ **CRITICAL**: The BCrypt hash `$2a$10$/FgU1KyveJ7MaQ7Xv4kxD.5EIQUHujJfZI4K2E1H7pS6parMHJpeG` is for the password `test123`. If you change the password, regenerate the hash. This was the #1 source of broken tests in CannaManage.
|
||||||
|
|
||||||
|
### Step 6: Create test file templates
|
||||||
|
|
||||||
|
#### `e2e/auth-flow.unauth.spec.ts`
|
||||||
|
|
||||||
|
```typescript
|
||||||
|
import { test, expect } from '@playwright/test';
|
||||||
|
|
||||||
|
test.describe('Authentication Flow', () => {
|
||||||
|
test('login page loads correctly', async ({ page }) => {
|
||||||
|
await page.goto('/login');
|
||||||
|
await expect(page.getByRole('heading', { name: /anmelden|login/i })).toBeVisible();
|
||||||
|
await expect(page.getByLabel('E-Mail')).toBeVisible();
|
||||||
|
await expect(page.getByLabel('Passwort')).toBeVisible();
|
||||||
|
});
|
||||||
|
|
||||||
|
test('shows validation errors for empty form', async ({ page }) => {
|
||||||
|
await page.goto('/login');
|
||||||
|
await page.getByRole('button', { name: /anmelden|login|sign in/i }).click();
|
||||||
|
// Expect validation messages
|
||||||
|
await expect(page.locator('text=/required|pflichtfeld|eingeben/i')).toBeVisible();
|
||||||
|
});
|
||||||
|
|
||||||
|
test('redirects unauthenticated users to login', async ({ page }) => {
|
||||||
|
await page.goto('/dashboard');
|
||||||
|
await page.waitForURL('**/login**');
|
||||||
|
});
|
||||||
|
|
||||||
|
test('registration page loads', async ({ page }) => {
|
||||||
|
await page.goto('/register');
|
||||||
|
await expect(page.getByRole('heading', { name: /registr/i })).toBeVisible();
|
||||||
|
});
|
||||||
|
});
|
||||||
|
```
|
||||||
|
|
||||||
|
#### `e2e/crud-flow.spec.ts`
|
||||||
|
|
||||||
|
```typescript
|
||||||
|
import { test, expect } from '@playwright/test';
|
||||||
|
|
||||||
|
test.describe('CRUD Operations', () => {
|
||||||
|
test('can navigate to list page', async ({ page }) => {
|
||||||
|
await page.goto('/dashboard');
|
||||||
|
// Adapt: click sidebar link to your main entity
|
||||||
|
// await page.getByRole('link', { name: 'Companies' }).click();
|
||||||
|
// await expect(page.getByRole('heading', { name: 'Companies' })).toBeVisible();
|
||||||
|
});
|
||||||
|
|
||||||
|
test('can create a new item', async ({ page }) => {
|
||||||
|
// Adapt: navigate to creation form
|
||||||
|
// await page.goto('/companies/new');
|
||||||
|
// await page.getByLabel('Name').fill('Test Company');
|
||||||
|
// await page.getByRole('button', { name: /erstellen|create|save/i }).click();
|
||||||
|
// await expect(page.locator('text=/erfolgreich|created|success/i')).toBeVisible();
|
||||||
|
});
|
||||||
|
|
||||||
|
test('can edit an existing item', async ({ page }) => {
|
||||||
|
// Adapt: navigate to edit form
|
||||||
|
// await page.goto('/companies');
|
||||||
|
// await page.getByRole('row').first().getByRole('link', { name: /edit|bearbeiten/i }).click();
|
||||||
|
// await page.getByLabel('Name').fill('Updated Company');
|
||||||
|
// await page.getByRole('button', { name: /speichern|save|update/i }).click();
|
||||||
|
// await expect(page.locator('text=/aktualisiert|updated|success/i')).toBeVisible();
|
||||||
|
});
|
||||||
|
|
||||||
|
test('can delete an item', async ({ page }) => {
|
||||||
|
// Adapt: delete flow with confirmation dialog
|
||||||
|
// await page.goto('/companies');
|
||||||
|
// await page.getByRole('row').first().getByRole('button', { name: /löschen|delete/i }).click();
|
||||||
|
// await page.getByRole('dialog').getByRole('button', { name: /bestätigen|confirm|delete/i }).click();
|
||||||
|
// await expect(page.locator('text=/gelöscht|deleted|success/i')).toBeVisible();
|
||||||
|
});
|
||||||
|
});
|
||||||
|
```
|
||||||
|
|
||||||
|
#### `e2e/navigation.spec.ts`
|
||||||
|
|
||||||
|
```typescript
|
||||||
|
import { test, expect } from '@playwright/test';
|
||||||
|
|
||||||
|
test.describe('Navigation', () => {
|
||||||
|
test('sidebar navigation works', async ({ page }) => {
|
||||||
|
await page.goto('/dashboard');
|
||||||
|
// Adapt: check your sidebar links exist
|
||||||
|
const sidebar = page.locator('[data-sidebar]');
|
||||||
|
await expect(sidebar).toBeVisible();
|
||||||
|
});
|
||||||
|
|
||||||
|
test('breadcrumbs display correctly', async ({ page }) => {
|
||||||
|
await page.goto('/dashboard');
|
||||||
|
// Adapt: verify breadcrumb trail
|
||||||
|
// await expect(page.locator('nav[aria-label="breadcrumb"]')).toBeVisible();
|
||||||
|
});
|
||||||
|
|
||||||
|
test('mobile menu toggle works', async ({ page }) => {
|
||||||
|
await page.setViewportSize({ width: 375, height: 667 });
|
||||||
|
await page.goto('/dashboard');
|
||||||
|
// Adapt: check mobile menu behavior
|
||||||
|
// await page.getByRole('button', { name: /menu/i }).click();
|
||||||
|
// await expect(page.locator('[data-sidebar]')).toBeVisible();
|
||||||
|
});
|
||||||
|
});
|
||||||
|
```
|
||||||
|
|
||||||
|
#### `e2e/accessibility.spec.ts`
|
||||||
|
|
||||||
|
```typescript
|
||||||
|
import { test, expect } from '@playwright/test';
|
||||||
|
import AxeBuilder from '@axe-core/playwright';
|
||||||
|
|
||||||
|
const pages = [
|
||||||
|
{ name: 'Dashboard', path: '/dashboard' },
|
||||||
|
// Add all pages to scan:
|
||||||
|
// { name: 'Companies', path: '/companies' },
|
||||||
|
// { name: 'New Company', path: '/companies/new' },
|
||||||
|
];
|
||||||
|
|
||||||
|
test.describe('Accessibility', () => {
|
||||||
|
for (const { name, path } of pages) {
|
||||||
|
test(`${name} has no accessibility violations`, async ({ page }) => {
|
||||||
|
await page.goto(path);
|
||||||
|
await page.waitForLoadState('networkidle');
|
||||||
|
|
||||||
|
const results = await new AxeBuilder({ page }).analyze();
|
||||||
|
|
||||||
|
// Log violations for debugging
|
||||||
|
if (results.violations.length > 0) {
|
||||||
|
console.log(`Accessibility violations on ${name}:`);
|
||||||
|
results.violations.forEach((v) => {
|
||||||
|
console.log(` [${v.impact}] ${v.id}: ${v.description}`);
|
||||||
|
v.nodes.forEach((n) => console.log(` ${n.html}`));
|
||||||
|
});
|
||||||
|
}
|
||||||
|
|
||||||
|
expect(results.violations).toEqual([]);
|
||||||
|
});
|
||||||
|
}
|
||||||
|
});
|
||||||
|
```
|
||||||
|
|
||||||
|
### Step 7: Add `package.json` scripts
|
||||||
|
|
||||||
|
Add to `<FRONTEND_DIR>/package.json` scripts section:
|
||||||
|
|
||||||
|
```json
|
||||||
|
{
|
||||||
|
"scripts": {
|
||||||
|
"e2e": "playwright test",
|
||||||
|
"e2e:ui": "playwright test --ui",
|
||||||
|
"e2e:headed": "playwright test --headed",
|
||||||
|
"e2e:report": "playwright show-report"
|
||||||
|
}
|
||||||
|
}
|
||||||
|
```
|
||||||
|
|
||||||
|
### Step 8: Update `.gitignore`
|
||||||
|
|
||||||
|
Append to `<FRONTEND_DIR>/.gitignore`:
|
||||||
|
|
||||||
|
```
|
||||||
|
# Playwright
|
||||||
|
.auth/
|
||||||
|
playwright-report/
|
||||||
|
test-results/
|
||||||
|
```
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## Lessons Learned & Gotchas
|
||||||
|
|
||||||
|
### 1. BCrypt hash MUST match the password
|
||||||
|
|
||||||
|
The #1 cause of broken E2E suites. If `seed.sql` has a hash that doesn't match the password in `auth.setup.ts`, all authenticated tests fail silently (login form rejects credentials).
|
||||||
|
|
||||||
|
**Verify with:**
|
||||||
|
```bash
|
||||||
|
echo -n "test123" | htpasswd -bnBC 10 "" - | cut -d: -f2
|
||||||
|
```
|
||||||
|
|
||||||
|
### 2. waitForURL — use globs, not broad regex
|
||||||
|
|
||||||
|
```typescript
|
||||||
|
// ❌ BAD — matches too broadly, causes flaky tests
|
||||||
|
await page.waitForURL(/dashboard|\//)
|
||||||
|
|
||||||
|
// ✅ GOOD — specific glob pattern
|
||||||
|
await page.waitForURL('**/dashboard')
|
||||||
|
```
|
||||||
|
|
||||||
|
### 3. shadcn/ui selectors
|
||||||
|
|
||||||
|
Don't use generic CSS class selectors for shadcn components. They use dynamic Tailwind classes.
|
||||||
|
|
||||||
|
```typescript
|
||||||
|
// ❌ BAD
|
||||||
|
page.locator('.sidebar')
|
||||||
|
|
||||||
|
// ✅ GOOD
|
||||||
|
page.locator('[data-sidebar]') // sidebar
|
||||||
|
page.locator('[role="dialog"]') // modals/dialogs
|
||||||
|
page.getByRole('button', { name: 'Save' }) // buttons
|
||||||
|
page.getByLabel('Email') // form fields
|
||||||
|
```
|
||||||
|
|
||||||
|
### 4. Console error filtering
|
||||||
|
|
||||||
|
Tests fail on unexpected console errors. Filter known/expected ones:
|
||||||
|
|
||||||
|
```typescript
|
||||||
|
const errors: string[] = [];
|
||||||
|
page.on('console', msg => {
|
||||||
|
if (msg.type() === 'error' && !msg.text().includes('expected-error-pattern')) {
|
||||||
|
errors.push(msg.text());
|
||||||
|
}
|
||||||
|
});
|
||||||
|
// ... do test actions ...
|
||||||
|
expect(errors).toEqual([]);
|
||||||
|
```
|
||||||
|
|
||||||
|
### 5. Auth state caching = 10x speed
|
||||||
|
|
||||||
|
The `setup` project runs ONCE per test run. All `authenticated` tests reuse the saved `.auth/admin.json` session cookie. Never log in per-test unless testing auth specifically.
|
||||||
|
|
||||||
|
### 6. Accessibility scanning pattern
|
||||||
|
|
||||||
|
```typescript
|
||||||
|
import AxeBuilder from '@axe-core/playwright';
|
||||||
|
|
||||||
|
const results = await new AxeBuilder({ page }).analyze();
|
||||||
|
expect(results.violations).toEqual([]);
|
||||||
|
```
|
||||||
|
|
||||||
|
Run on every page. Add new pages to the `pages` array in `accessibility.spec.ts`.
|
||||||
|
|
||||||
|
### 7. Visual regression (optional, add when ready)
|
||||||
|
|
||||||
|
```typescript
|
||||||
|
await expect(page).toHaveScreenshot('page-name.png', { maxDiffPixels: 100 });
|
||||||
|
```
|
||||||
|
|
||||||
|
First run creates baseline screenshots. Subsequent runs compare. Commit screenshots to git.
|
||||||
|
|
||||||
|
### 8. Docker test environment
|
||||||
|
|
||||||
|
Backend should have a `test` Spring profile that:
|
||||||
|
- Uses the test PostgreSQL (port 5433 to avoid conflicts)
|
||||||
|
- Runs Flyway migrations + seed on startup
|
||||||
|
- Has shorter JWT expiry for faster test cycles
|
||||||
|
- Disables rate limiting and email sending
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## Troubleshooting
|
||||||
|
|
||||||
|
| Problem | Cause | Fix |
|
||||||
|
|---------|-------|-----|
|
||||||
|
| All auth tests fail | Wrong BCrypt hash in seed.sql | Regenerate hash for your password |
|
||||||
|
| `waitForURL` times out | URL doesn't match pattern | Use `page.url()` to print actual URL, adjust pattern |
|
||||||
|
| Tests pass locally, fail in CI | Missing `npx playwright install` | Add to CI setup step |
|
||||||
|
| `storageState` file not found | `.auth/` directory doesn't exist | Create `.auth/` dir or let setup create it |
|
||||||
|
| Flaky navigation tests | Page not fully loaded | Add `await page.waitForLoadState('networkidle')` |
|
||||||
|
| axe violations on shadcn | Missing aria labels | Add `aria-label` to interactive elements |
|
||||||
@@ -0,0 +1,121 @@
|
|||||||
|
---
|
||||||
|
name: sprint-report
|
||||||
|
description: Generate sprint status report from Jira data.
|
||||||
|
---
|
||||||
|
|
||||||
|
# Skill: sprint-report
|
||||||
|
|
||||||
|
Generate sprint status report from Jira data.
|
||||||
|
|
||||||
|
## Invoked by
|
||||||
|
|
||||||
|
🎫 JiraOps mode (or 🪃 Orchestrator)
|
||||||
|
|
||||||
|
## Required Inputs
|
||||||
|
|
||||||
|
| Input | Source | Example |
|
||||||
|
|-------|--------|---------|
|
||||||
|
| `PROJECT_KEY` | Jira project key | `PROJECT` |
|
||||||
|
| `SPRINT_ID` | Sprint ID (optional — auto-detected) | `1234` |
|
||||||
|
|
||||||
|
## Output
|
||||||
|
|
||||||
|
Markdown report: `docs/sprint-reports/sprint-<sprint_name>-<date>.md`
|
||||||
|
|
||||||
|
## Steps
|
||||||
|
|
||||||
|
### 1. Get active sprint
|
||||||
|
|
||||||
|
```python
|
||||||
|
boards = get_agile_boards(project_key=PROJECT_KEY)
|
||||||
|
sprints = get_sprints_from_board(board_id=boards[0]["id"], states="active")
|
||||||
|
sprint = sprints[0]
|
||||||
|
```
|
||||||
|
|
||||||
|
### 2. Get sprint tickets
|
||||||
|
|
||||||
|
```python
|
||||||
|
tickets = get_tickets_from_sprint(sprint_id=sprint["id"])
|
||||||
|
```
|
||||||
|
|
||||||
|
### 3. Categorize by status
|
||||||
|
|
||||||
|
| Category | Statuses |
|
||||||
|
|----------|----------|
|
||||||
|
| To Do | `Open`, `Backlog`, `To Do` |
|
||||||
|
| In Progress | `In Progress`, `In Development` |
|
||||||
|
| In Review | `In Review`, `Code Review` |
|
||||||
|
| Done | `Done`, `Accepted`, `Closed` |
|
||||||
|
|
||||||
|
### 4. Calculate metrics
|
||||||
|
|
||||||
|
```python
|
||||||
|
total = len(tickets)
|
||||||
|
done = len([t for t in tickets if t["status"] in DONE_STATUSES])
|
||||||
|
completion_pct = round(done / total * 100) if total > 0 else 0
|
||||||
|
```
|
||||||
|
|
||||||
|
### 5. Generate report
|
||||||
|
|
||||||
|
```markdown
|
||||||
|
# Sprint Report: <sprint_name>
|
||||||
|
|
||||||
|
**Date:** <today>
|
||||||
|
**Sprint:** <sprint_name>
|
||||||
|
**Period:** <start> — <end>
|
||||||
|
**Project:** <PROJECT_KEY>
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## Overview
|
||||||
|
|
||||||
|
| Metric | Value |
|
||||||
|
|--------|-------|
|
||||||
|
| Total tickets | <total> |
|
||||||
|
| Done | <done> (<pct>%) |
|
||||||
|
| In Progress | <wip> |
|
||||||
|
| Open | <todo> |
|
||||||
|
|
||||||
|
## Progress
|
||||||
|
|
||||||
|
```
|
||||||
|
[████████████░░░░░░░░] 60% (<done>/<total>)
|
||||||
|
```
|
||||||
|
|
||||||
|
## By Status
|
||||||
|
|
||||||
|
### ✅ Done (<done>)
|
||||||
|
|
||||||
|
| Ticket | Type | Summary | Assignee |
|
||||||
|
|--------|------|---------|----------|
|
||||||
|
| <key> | Story | <summary> | <name> |
|
||||||
|
|
||||||
|
### 🔄 In Progress (<wip>)
|
||||||
|
|
||||||
|
| Ticket | Type | Summary | Assignee |
|
||||||
|
|--------|------|---------|----------|
|
||||||
|
|
||||||
|
### ⏳ Open (<todo>)
|
||||||
|
|
||||||
|
| Ticket | Type | Summary | Assignee |
|
||||||
|
|--------|------|---------|----------|
|
||||||
|
|
||||||
|
## By Assignee
|
||||||
|
|
||||||
|
| Assignee | Total | Done | In Progress | Open |
|
||||||
|
|----------|-------|------|-------------|------|
|
||||||
|
|
||||||
|
## Blockers / Risks
|
||||||
|
|
||||||
|
| Ticket | Description | Since | Impact |
|
||||||
|
|--------|-------------|-------|--------|
|
||||||
|
```
|
||||||
|
|
||||||
|
### 6. Store in BigMind
|
||||||
|
|
||||||
|
```python
|
||||||
|
memory_store_fact(
|
||||||
|
category="codebase",
|
||||||
|
fact=f"Sprint report for {sprint_name}: {done}/{total} done ({pct}%)"
|
||||||
|
)
|
||||||
|
```
|
||||||
@@ -0,0 +1,107 @@
|
|||||||
|
---
|
||||||
|
name: switch-worktree
|
||||||
|
description: Switch VS Code to an existing git worktree. Lists worktrees, replaces the current window (code -r), announces BigMind focus, and restores session context. Use when asked to switch worktree, open another ticket, change to a different branch/ticket, or activate a worktree.
|
||||||
|
---
|
||||||
|
|
||||||
|
# Switch Worktree
|
||||||
|
|
||||||
|
## When to use
|
||||||
|
|
||||||
|
- User wants to switch to a different ticket worktree
|
||||||
|
- User says "switch to PROJECT-XXX", "open worktree for ...", "go to ticket ..."
|
||||||
|
- User wants to see available worktrees and pick one
|
||||||
|
|
||||||
|
## When NOT to use
|
||||||
|
|
||||||
|
- User wants to **create** a new worktree → use `create-worktree` skill instead
|
||||||
|
- User wants to delete/remove a worktree
|
||||||
|
- User just wants to see git history (no switch needed)
|
||||||
|
|
||||||
|
## Inputs
|
||||||
|
|
||||||
|
| Input | Required | Source | Example |
|
||||||
|
|-------|----------|--------|---------|
|
||||||
|
| `TICKET_KEY` | Optional | User or interactive selection | `PROJECT-123` |
|
||||||
|
|
||||||
|
If no ticket key is provided, list all worktrees and let the user pick.
|
||||||
|
|
||||||
|
## Workflow
|
||||||
|
|
||||||
|
### 1. List available worktrees
|
||||||
|
|
||||||
|
```bash
|
||||||
|
git -C <your-repo-path> worktree list
|
||||||
|
```
|
||||||
|
|
||||||
|
Parse output to show available worktrees with their branches.
|
||||||
|
|
||||||
|
### 2. Match or select target
|
||||||
|
|
||||||
|
If `TICKET_KEY` provided:
|
||||||
|
- Look for a worktree path containing the ticket key
|
||||||
|
- If not found, report error and show available worktrees
|
||||||
|
|
||||||
|
If no `TICKET_KEY`:
|
||||||
|
- Present the list and ask the user to pick
|
||||||
|
|
||||||
|
### 3. Show worktree status before switching
|
||||||
|
|
||||||
|
```bash
|
||||||
|
cd <target_worktree_path>
|
||||||
|
git branch --show-current
|
||||||
|
git status --short
|
||||||
|
git log --oneline -3
|
||||||
|
```
|
||||||
|
|
||||||
|
Report: branch name, uncommitted changes (if any), last 3 commits.
|
||||||
|
|
||||||
|
### 4. Switch VS Code window
|
||||||
|
|
||||||
|
```bash
|
||||||
|
code -r <target_worktree_path>
|
||||||
|
```
|
||||||
|
|
||||||
|
This replaces the current VS Code window with the target worktree.
|
||||||
|
|
||||||
|
**Important:** After this command, the current Roo session ends because the workspace changes. The next Roo session will start in the new worktree.
|
||||||
|
|
||||||
|
### 5. Update BigMind focus
|
||||||
|
|
||||||
|
Before executing `code -r`, announce the switch:
|
||||||
|
|
||||||
|
```python
|
||||||
|
memory_store_fact(
|
||||||
|
category="codebase",
|
||||||
|
fact=f"Switched worktree to {TICKET_KEY} at {target_path}, branch {branch_name}"
|
||||||
|
)
|
||||||
|
memory_announce_focus(
|
||||||
|
session_id=SESSION_ID,
|
||||||
|
description=f"Switching to {TICKET_KEY} worktree",
|
||||||
|
files=[target_path],
|
||||||
|
ide_hint="Roo"
|
||||||
|
)
|
||||||
|
```
|
||||||
|
|
||||||
|
### 6. Context recovery hint
|
||||||
|
|
||||||
|
After switching, the next session should:
|
||||||
|
1. Run `memory_search_facts("<TICKET_KEY>")` to find prior work
|
||||||
|
2. Run `memory_search_chunks("<TICKET_KEY>")` for detailed context
|
||||||
|
3. Check `docs/<MODULE>/<TICKET_KEY>/` for existing documentation
|
||||||
|
|
||||||
|
This happens automatically via the BigMind session ritual.
|
||||||
|
|
||||||
|
## Error Handling
|
||||||
|
|
||||||
|
| Error | Resolution |
|
||||||
|
|-------|------------|
|
||||||
|
| No worktrees found | Only the main repo exists — suggest `create-worktree` |
|
||||||
|
| Ticket worktree not found | Show available worktrees, ask user to pick or create |
|
||||||
|
| Uncommitted changes in current worktree | Warn user before switching — suggest commit or stash |
|
||||||
|
| `code` CLI not available | Run `Shell Command: Install 'code' command in PATH` from VS Code |
|
||||||
|
|
||||||
|
## Notes
|
||||||
|
|
||||||
|
- `code -r` replaces the current window — the Roo session will end after this
|
||||||
|
- The new window starts fresh — BigMind provides continuity across the switch
|
||||||
|
- If the user has uncommitted changes, always warn before switching
|
||||||
@@ -0,0 +1,140 @@
|
|||||||
|
---
|
||||||
|
name: visual-verify
|
||||||
|
description: Verify a frontend page visually using Playwright. Takes screenshots (dark/light mode), extracts visible text, checks element positioning and responsive layout. Use when asked to verify a page, check how it looks, take a screenshot, or after building a new UI component.
|
||||||
|
---
|
||||||
|
|
||||||
|
# Visual Verify
|
||||||
|
|
||||||
|
## When to use
|
||||||
|
|
||||||
|
- After creating or modifying a frontend page/component
|
||||||
|
- When asked "how does it look", "verify the page", "take a screenshot"
|
||||||
|
- To check dark/light mode rendering
|
||||||
|
- To verify text content (i18n) renders correctly
|
||||||
|
- To check centering, alignment, and responsive layout
|
||||||
|
|
||||||
|
## When NOT to use
|
||||||
|
|
||||||
|
- For unit tests or API testing (use test runners instead)
|
||||||
|
- For full E2E test suites (use Playwright test framework directly)
|
||||||
|
- When the dev server is not running
|
||||||
|
|
||||||
|
## Prerequisites
|
||||||
|
|
||||||
|
- Playwright installed in the frontend project: `pnpm add -D playwright`
|
||||||
|
- Chromium browser installed: `npx playwright install chromium`
|
||||||
|
- Dev server running (usually `pnpm dev` on localhost:3000)
|
||||||
|
|
||||||
|
## Inputs
|
||||||
|
|
||||||
|
| Input | Required | Default | Example |
|
||||||
|
|-------|----------|---------|---------|
|
||||||
|
| URL | Yes | — | `http://localhost:3000/login` |
|
||||||
|
| Checks | No | all | `text`, `screenshot`, `position`, `responsive`, `interaction` |
|
||||||
|
| Theme | No | both | `dark`, `light`, `both` |
|
||||||
|
| Viewport | No | 1280x720 | `375x667` (mobile) |
|
||||||
|
|
||||||
|
## Workflow
|
||||||
|
|
||||||
|
### 1. Launch browser and navigate
|
||||||
|
|
||||||
|
```javascript
|
||||||
|
const { chromium } = require('playwright');
|
||||||
|
const browser = await chromium.launch();
|
||||||
|
const page = await browser.newPage({ viewport: { width: 1280, height: 720 } });
|
||||||
|
await page.goto(URL);
|
||||||
|
await page.waitForTimeout(2000); // Wait for hydration
|
||||||
|
```
|
||||||
|
|
||||||
|
### 2. Extract visible text
|
||||||
|
|
||||||
|
```javascript
|
||||||
|
const text = await page.locator('body').innerText();
|
||||||
|
// Report: verify all expected text is present (i18n keys rendered)
|
||||||
|
```
|
||||||
|
|
||||||
|
### 3. Check element positioning
|
||||||
|
|
||||||
|
```javascript
|
||||||
|
// Verify centering of a key element
|
||||||
|
const box = await page.locator('SELECTOR').boundingBox();
|
||||||
|
const vp = page.viewportSize();
|
||||||
|
const centerX = Math.round(box.x + box.width / 2);
|
||||||
|
const centerY = Math.round(box.y + box.height / 2);
|
||||||
|
// Report: distance from viewport center
|
||||||
|
```
|
||||||
|
|
||||||
|
### 4. Take screenshots
|
||||||
|
|
||||||
|
```javascript
|
||||||
|
// Dark mode (default)
|
||||||
|
await page.screenshot({ path: '/tmp/verify-dark.png', fullPage: true });
|
||||||
|
|
||||||
|
// Light mode
|
||||||
|
await page.evaluate(() => {
|
||||||
|
document.documentElement.classList.remove('dark');
|
||||||
|
document.documentElement.style.colorScheme = 'light';
|
||||||
|
});
|
||||||
|
await page.waitForTimeout(500);
|
||||||
|
await page.screenshot({ path: '/tmp/verify-light.png', fullPage: true });
|
||||||
|
```
|
||||||
|
|
||||||
|
### 5. Responsive check (optional)
|
||||||
|
|
||||||
|
```javascript
|
||||||
|
// Mobile viewport
|
||||||
|
await page.setViewportSize({ width: 375, height: 667 });
|
||||||
|
await page.waitForTimeout(500);
|
||||||
|
await page.screenshot({ path: '/tmp/verify-mobile.png', fullPage: true });
|
||||||
|
|
||||||
|
// Tablet
|
||||||
|
await page.setViewportSize({ width: 768, height: 1024 });
|
||||||
|
await page.waitForTimeout(500);
|
||||||
|
await page.screenshot({ path: '/tmp/verify-tablet.png', fullPage: true });
|
||||||
|
```
|
||||||
|
|
||||||
|
### 6. Interaction check (optional)
|
||||||
|
|
||||||
|
```javascript
|
||||||
|
// Click a button and verify outcome
|
||||||
|
await page.locator('button[type="submit"]').click();
|
||||||
|
await page.waitForTimeout(1000);
|
||||||
|
const errorText = await page.locator('body').innerText();
|
||||||
|
// Report: what changed after interaction
|
||||||
|
```
|
||||||
|
|
||||||
|
### 7. Report findings
|
||||||
|
|
||||||
|
Produce a summary:
|
||||||
|
|
||||||
|
```
|
||||||
|
=== Visual Verification: <URL> ===
|
||||||
|
✅ Text renders: <key phrases found>
|
||||||
|
✅ Horizontally centered (X: 640/640)
|
||||||
|
⚠️ Vertically offset (Y: 414 vs 360) — acceptable, content above pushes down
|
||||||
|
✅ Dark mode: screenshot saved
|
||||||
|
✅ Light mode: screenshot saved
|
||||||
|
⚠️ Mobile: form overflows at 375px width
|
||||||
|
```
|
||||||
|
|
||||||
|
### 8. Clean up
|
||||||
|
|
||||||
|
```javascript
|
||||||
|
await browser.close();
|
||||||
|
```
|
||||||
|
|
||||||
|
## Output
|
||||||
|
|
||||||
|
- Console report with pass/fail per check
|
||||||
|
- Screenshots at `/tmp/verify-*.png` (dark, light, mobile, tablet)
|
||||||
|
- Actionable findings if issues detected
|
||||||
|
|
||||||
|
## Troubleshooting
|
||||||
|
|
||||||
|
| Issue | Resolution |
|
||||||
|
|-------|-----------|
|
||||||
|
| Page blank / no text | Increase `waitForTimeout` — hydration may be slow |
|
||||||
|
| Cannot find module 'playwright' | Run `pnpm add -D playwright` in the frontend project |
|
||||||
|
| Browser not found | Run `npx playwright install chromium` |
|
||||||
|
| Connection refused | Ensure dev server is running on the expected port |
|
||||||
|
| Dark mode not toggling | Check if theme uses `class="dark"` on `<html>` or `data-theme` attribute |
|
||||||
@@ -0,0 +1,60 @@
|
|||||||
|
import { parametersSchema as z, defineCustomTool, CustomToolContext } from "@roo-code/types"
|
||||||
|
// @ts-ignore - Node built-ins
|
||||||
|
import { spawnSync } from "child_process"
|
||||||
|
|
||||||
|
export default defineCustomTool({
|
||||||
|
name: "brew_leaves",
|
||||||
|
description: "List Homebrew packages installed on request (not pulled in as dependencies). Optionally includes installed versions. Answers 'what did I install myself?'",
|
||||||
|
parameters: z.object({
|
||||||
|
withVersions: z.boolean().optional().describe("Include installed versions for each leaf package (default: true)"),
|
||||||
|
}),
|
||||||
|
async execute({ withVersions = true }, context: CustomToolContext) {
|
||||||
|
try {
|
||||||
|
const leavesResult = spawnSync("brew", ["leaves", "-r"], {
|
||||||
|
encoding: "utf-8",
|
||||||
|
timeout: 15_000,
|
||||||
|
})
|
||||||
|
|
||||||
|
if (leavesResult.error) {
|
||||||
|
return JSON.stringify({ error: `brew leaves failed: ${leavesResult.error.message}` }, null, 2)
|
||||||
|
}
|
||||||
|
|
||||||
|
const leavesList = (leavesResult.stdout || "")
|
||||||
|
.split("\n")
|
||||||
|
.map((l: string) => l.trim())
|
||||||
|
.filter((l: string) => l.length > 0)
|
||||||
|
|
||||||
|
if (!withVersions) {
|
||||||
|
return JSON.stringify({
|
||||||
|
count: leavesList.length,
|
||||||
|
leaves: leavesList.map((name: string) => ({ name })),
|
||||||
|
}, null, 2)
|
||||||
|
}
|
||||||
|
|
||||||
|
// Get versions in batch — brew list --versions for all leaves
|
||||||
|
const versResult = spawnSync("brew", ["list", "--versions", ...leavesList], {
|
||||||
|
encoding: "utf-8",
|
||||||
|
timeout: 30_000,
|
||||||
|
})
|
||||||
|
|
||||||
|
const versionMap: Record<string, string> = {}
|
||||||
|
if (versResult.stdout) {
|
||||||
|
for (const line of versResult.stdout.split("\n")) {
|
||||||
|
const parts = line.trim().split(/\s+/)
|
||||||
|
if (parts.length >= 2) {
|
||||||
|
versionMap[parts[0]] = parts.slice(1).join(", ")
|
||||||
|
}
|
||||||
|
}
|
||||||
|
}
|
||||||
|
|
||||||
|
const leaves = leavesList.map((name: string) => ({
|
||||||
|
name,
|
||||||
|
version: versionMap[name] || "unknown",
|
||||||
|
}))
|
||||||
|
|
||||||
|
return JSON.stringify({ count: leaves.length, leaves }, null, 2)
|
||||||
|
} catch (err: any) {
|
||||||
|
return JSON.stringify({ error: err.message ?? String(err) }, null, 2)
|
||||||
|
}
|
||||||
|
},
|
||||||
|
})
|
||||||
@@ -0,0 +1,47 @@
|
|||||||
|
import { parametersSchema as z, defineCustomTool, CustomToolContext } from "@roo-code/types"
|
||||||
|
// @ts-ignore - Node built-ins
|
||||||
|
import { spawnSync } from "child_process"
|
||||||
|
|
||||||
|
export default defineCustomTool({
|
||||||
|
name: "brew_search",
|
||||||
|
description: "Search Homebrew for formulae and/or casks matching a query. Returns structured JSON instead of raw terminal output.",
|
||||||
|
parameters: z.object({
|
||||||
|
query: z.string().describe("Search term (e.g. 'python', 'docker', 'ffmpeg')"),
|
||||||
|
casks: z.boolean().optional().describe("Include casks in search results (default: false, formula-only)"),
|
||||||
|
}),
|
||||||
|
async execute({ query, casks = false }, context: CustomToolContext) {
|
||||||
|
try {
|
||||||
|
// Search formulae
|
||||||
|
const formulaResult = spawnSync("brew", ["search", "--formula", query], {
|
||||||
|
encoding: "utf-8",
|
||||||
|
timeout: 15_000,
|
||||||
|
})
|
||||||
|
|
||||||
|
const formulae = (formulaResult.stdout || "")
|
||||||
|
.split("\n")
|
||||||
|
.map((l: string) => l.trim())
|
||||||
|
.filter((l: string) => l.length > 0 && !l.startsWith("==>"))
|
||||||
|
|
||||||
|
let caskList: string[] = []
|
||||||
|
if (casks) {
|
||||||
|
const caskResult = spawnSync("brew", ["search", "--cask", query], {
|
||||||
|
encoding: "utf-8",
|
||||||
|
timeout: 15_000,
|
||||||
|
})
|
||||||
|
caskList = (caskResult.stdout || "")
|
||||||
|
.split("\n")
|
||||||
|
.map((l: string) => l.trim())
|
||||||
|
.filter((l: string) => l.length > 0 && !l.startsWith("==>"))
|
||||||
|
}
|
||||||
|
|
||||||
|
return JSON.stringify({
|
||||||
|
query,
|
||||||
|
formulae,
|
||||||
|
casks: caskList,
|
||||||
|
totalCount: formulae.length + caskList.length,
|
||||||
|
}, null, 2)
|
||||||
|
} catch (err: any) {
|
||||||
|
return JSON.stringify({ error: err.message ?? String(err) }, null, 2)
|
||||||
|
}
|
||||||
|
},
|
||||||
|
})
|
||||||
@@ -0,0 +1,91 @@
|
|||||||
|
import { parametersSchema as z, defineCustomTool } from "@roo-code/types"
|
||||||
|
import { statSync, readdirSync } from "fs"
|
||||||
|
import { join, relative } from "path"
|
||||||
|
|
||||||
|
export default defineCustomTool({
|
||||||
|
name: "context_budget",
|
||||||
|
description: "Estimate token cost of reading files or directories. Returns file count, total lines, chars, and estimated tokens. Helps decide whether to load full files or use targeted reads.",
|
||||||
|
parameters: z.object({
|
||||||
|
paths: z.array(z.string()).describe("File or directory paths to analyze"),
|
||||||
|
recursive: z.boolean().optional().describe("Recurse into directories. Default: true"),
|
||||||
|
extensions: z.array(z.string()).optional().describe("Filter by file extensions, e.g. ['.java', '.ts']. Default: all files"),
|
||||||
|
}),
|
||||||
|
async execute({ paths, recursive = true, extensions }) {
|
||||||
|
let totalFiles = 0
|
||||||
|
let totalLines = 0
|
||||||
|
let totalChars = 0
|
||||||
|
const breakdown: Array<{ path: string; lines: number; chars: number; tokens: number }> = []
|
||||||
|
|
||||||
|
function processFile(filePath: string) {
|
||||||
|
try {
|
||||||
|
const stat = statSync(filePath)
|
||||||
|
if (!stat.isFile()) return
|
||||||
|
if (extensions && !extensions.some(ext => filePath.endsWith(ext))) return
|
||||||
|
|
||||||
|
const { readFileSync } = require("fs")
|
||||||
|
const content = readFileSync(filePath, "utf-8")
|
||||||
|
const lines = content.split("\n").length
|
||||||
|
const chars = content.length
|
||||||
|
const tokens = Math.ceil(chars / 4)
|
||||||
|
|
||||||
|
totalFiles++
|
||||||
|
totalLines += lines
|
||||||
|
totalChars += chars
|
||||||
|
breakdown.push({ path: filePath, lines, chars, tokens })
|
||||||
|
} catch (e) {
|
||||||
|
// skip unreadable files
|
||||||
|
}
|
||||||
|
}
|
||||||
|
|
||||||
|
function processDir(dirPath: string, recurse: boolean) {
|
||||||
|
try {
|
||||||
|
const entries = readdirSync(dirPath, { withFileTypes: true })
|
||||||
|
for (const entry of entries) {
|
||||||
|
if (entry.name.startsWith(".") || entry.name === "node_modules" || entry.name === "target" || entry.name === ".git") continue
|
||||||
|
const fullPath = join(dirPath, entry.name)
|
||||||
|
if (entry.isFile()) {
|
||||||
|
processFile(fullPath)
|
||||||
|
} else if (entry.isDirectory() && recurse) {
|
||||||
|
processDir(fullPath, recurse)
|
||||||
|
}
|
||||||
|
}
|
||||||
|
} catch (e) {
|
||||||
|
// skip unreadable dirs
|
||||||
|
}
|
||||||
|
}
|
||||||
|
|
||||||
|
for (const p of paths) {
|
||||||
|
try {
|
||||||
|
const stat = statSync(p)
|
||||||
|
if (stat.isFile()) {
|
||||||
|
processFile(p)
|
||||||
|
} else if (stat.isDirectory()) {
|
||||||
|
processDir(p, recursive !== false)
|
||||||
|
}
|
||||||
|
} catch (e) {
|
||||||
|
breakdown.push({ path: p, lines: 0, chars: 0, tokens: 0 })
|
||||||
|
}
|
||||||
|
}
|
||||||
|
|
||||||
|
const totalTokens = Math.ceil(totalChars / 4)
|
||||||
|
|
||||||
|
// Sort by tokens descending, take top 15
|
||||||
|
breakdown.sort((a, b) => b.tokens - a.tokens)
|
||||||
|
const topFiles = breakdown.slice(0, 15)
|
||||||
|
|
||||||
|
const result = {
|
||||||
|
summary: {
|
||||||
|
files: totalFiles,
|
||||||
|
totalLines,
|
||||||
|
totalChars,
|
||||||
|
estimatedTokens: totalTokens,
|
||||||
|
warning: totalTokens > 50000 ? "⚠️ LARGE — will consume significant context budget" :
|
||||||
|
totalTokens > 20000 ? "⚠️ MEDIUM — consider targeted reads" :
|
||||||
|
"✅ Fits comfortably in context",
|
||||||
|
},
|
||||||
|
largestFiles: topFiles,
|
||||||
|
}
|
||||||
|
|
||||||
|
return JSON.stringify(result, null, 2)
|
||||||
|
},
|
||||||
|
})
|
||||||
@@ -0,0 +1,45 @@
|
|||||||
|
import { parametersSchema as z, defineCustomTool } from "@roo-code/types"
|
||||||
|
import { spawnSync } from "child_process"
|
||||||
|
|
||||||
|
export default defineCustomTool({
|
||||||
|
name: "git_recent_changes",
|
||||||
|
description: "Get recent git commits across all branches as structured JSON. Shows hash, branch, author, date, and message. Useful at session start for situational awareness.",
|
||||||
|
parameters: z.object({
|
||||||
|
repoPath: z.string().optional().describe("Path to git repo (required)"),
|
||||||
|
count: z.number().optional().describe("Number of commits to return. Default: 15"),
|
||||||
|
branch: z.string().optional().describe("Specific branch to query. Default: --all (all branches)"),
|
||||||
|
}),
|
||||||
|
async execute({ repoPath, count = 15, branch }) {
|
||||||
|
const repo = repoPath
|
||||||
|
const args = ["-C", repo, "log", "--oneline", `--max-count=${count}`, "--format=%H|%h|%an|%ai|%D|%s"]
|
||||||
|
|
||||||
|
if (branch) {
|
||||||
|
args.push(branch)
|
||||||
|
} else {
|
||||||
|
args.push("--all")
|
||||||
|
}
|
||||||
|
|
||||||
|
const result = spawnSync("git", args, {
|
||||||
|
encoding: "utf-8",
|
||||||
|
timeout: 10000,
|
||||||
|
})
|
||||||
|
|
||||||
|
if (result.status !== 0) {
|
||||||
|
return `Error: ${result.stderr || "git log failed"}`
|
||||||
|
}
|
||||||
|
|
||||||
|
const commits = result.stdout.trim().split("\n").filter(Boolean).map(line => {
|
||||||
|
const [hash, shortHash, author, date, refs, ...msgParts] = line.split("|")
|
||||||
|
return {
|
||||||
|
hash,
|
||||||
|
shortHash,
|
||||||
|
author,
|
||||||
|
date,
|
||||||
|
refs: refs || null,
|
||||||
|
message: msgParts.join("|"),
|
||||||
|
}
|
||||||
|
})
|
||||||
|
|
||||||
|
return JSON.stringify(commits, null, 2)
|
||||||
|
},
|
||||||
|
})
|
||||||
@@ -0,0 +1,12 @@
|
|||||||
|
const { parametersSchema: z, defineCustomTool } = require("@roo-code/types")
|
||||||
|
|
||||||
|
module.exports = defineCustomTool({
|
||||||
|
name: "hello_test",
|
||||||
|
description: "A simple test tool that returns a greeting. Used to verify custom tool loading works.",
|
||||||
|
parameters: z.object({
|
||||||
|
name: z.string().optional().describe("Name to greet. Defaults to 'World'"),
|
||||||
|
}),
|
||||||
|
async execute({ name }) {
|
||||||
|
return `Hello, ${name || "World"}! Custom tools are working. Time: ${new Date().toISOString()}`
|
||||||
|
},
|
||||||
|
})
|
||||||
@@ -0,0 +1,205 @@
|
|||||||
|
import { parametersSchema as z, defineCustomTool, CustomToolContext } from "@roo-code/types"
|
||||||
|
// @ts-ignore - Node built-ins
|
||||||
|
import { spawnSync } from "child_process"
|
||||||
|
// @ts-ignore - Node built-ins
|
||||||
|
import { readFileSync, unlinkSync, existsSync } from "fs"
|
||||||
|
// @ts-ignore - Node built-ins
|
||||||
|
import path from "path"
|
||||||
|
// @ts-ignore - Node built-ins
|
||||||
|
import os from "os"
|
||||||
|
|
||||||
|
interface DepNode {
|
||||||
|
groupId: string
|
||||||
|
artifactId: string
|
||||||
|
version: string
|
||||||
|
scope: string
|
||||||
|
depth: number
|
||||||
|
children: DepNode[]
|
||||||
|
}
|
||||||
|
|
||||||
|
export default defineCustomTool({
|
||||||
|
name: "mvn_dependency_tree",
|
||||||
|
description: "Run 'mvn dependency:tree' and return parsed JSON. Filters by groupId and scope. Saves piping raw mvn output through grep.",
|
||||||
|
parameters: z.object({
|
||||||
|
projectRoot: z.string().describe("Directory containing pom.xml (absolute or relative)"),
|
||||||
|
module: z.string().optional().describe("-pl <module> scope, e.g. 'backend' or 'java/modules/cs-modules/eau'"),
|
||||||
|
groupIdFilter: z.string().optional().describe("Only include deps whose groupId contains this string"),
|
||||||
|
scope: z.enum(["compile", "test", "runtime", "provided", "all"]).optional().describe("Filter by Maven scope (default: all)"),
|
||||||
|
}),
|
||||||
|
async execute({ projectRoot, module, groupIdFilter, scope = "all" }, context: CustomToolContext) {
|
||||||
|
try {
|
||||||
|
// Resolve projectRoot against task CWD if relative
|
||||||
|
// @ts-ignore - task.cwd exists at runtime
|
||||||
|
const cwd = context?.task?.cwd ?? process.cwd()
|
||||||
|
const resolvedRoot = path.isAbsolute(projectRoot) ? projectRoot : path.resolve(cwd, projectRoot)
|
||||||
|
|
||||||
|
// Use a temp file for output — avoids parsing noisy Maven stdout
|
||||||
|
const outFile = path.join(os.tmpdir(), `mvn-deptree-${Date.now()}.txt`)
|
||||||
|
|
||||||
|
const args = ["dependency:tree", "-B", `-DoutputFile=${outFile}`, "-DoutputType=text"]
|
||||||
|
// Only add -pl when module is a non-empty string
|
||||||
|
if (module && module.trim()) {
|
||||||
|
args.push("-pl", module, "-am")
|
||||||
|
}
|
||||||
|
if (scope !== "all") {
|
||||||
|
args.push(`-Dscope=${scope}`)
|
||||||
|
}
|
||||||
|
|
||||||
|
const result = spawnSync("mvn", args, {
|
||||||
|
cwd: resolvedRoot,
|
||||||
|
encoding: "utf-8",
|
||||||
|
timeout: 120_000,
|
||||||
|
maxBuffer: 10 * 1024 * 1024,
|
||||||
|
})
|
||||||
|
|
||||||
|
if (result.error) {
|
||||||
|
return JSON.stringify({ error: `spawn error: ${result.error.message}` }, null, 2)
|
||||||
|
}
|
||||||
|
|
||||||
|
const stderr = result.stderr || ""
|
||||||
|
|
||||||
|
if (result.status !== 0) {
|
||||||
|
const errLines = stderr.split("\n").filter((l: string) => l.includes("[ERROR]")).slice(0, 10)
|
||||||
|
// Clean up temp file if it exists
|
||||||
|
try { if (existsSync(outFile)) unlinkSync(outFile) } catch {}
|
||||||
|
return JSON.stringify({
|
||||||
|
ok: false,
|
||||||
|
command: `mvn ${args.join(" ")}`,
|
||||||
|
exitCode: result.status,
|
||||||
|
errorLines: errLines,
|
||||||
|
}, null, 2)
|
||||||
|
}
|
||||||
|
|
||||||
|
// Read the output file
|
||||||
|
let output = ""
|
||||||
|
try {
|
||||||
|
output = readFileSync(outFile, "utf-8")
|
||||||
|
} catch (e: any) {
|
||||||
|
return JSON.stringify({
|
||||||
|
error: `mvn succeeded but output file not found: ${outFile}. stderr: ${stderr.slice(0, 500)}`,
|
||||||
|
}, null, 2)
|
||||||
|
} finally {
|
||||||
|
// Clean up temp file
|
||||||
|
try { if (existsSync(outFile)) unlinkSync(outFile) } catch {}
|
||||||
|
}
|
||||||
|
|
||||||
|
// Parse the tree output
|
||||||
|
// Lines look like:
|
||||||
|
// de.platesoft:inspectflow:pom:0.1.0
|
||||||
|
// +- org.springframework.boot:spring-boot-starter-web:jar:3.5.11:compile
|
||||||
|
// | +- org.springframework.boot:spring-boot-starter:jar:3.5.11:compile
|
||||||
|
// \- junit:junit:jar:4.13.2:test
|
||||||
|
const lines = output.split("\n").filter((l: string) => l.trim())
|
||||||
|
|
||||||
|
let rootArtifact = ""
|
||||||
|
const tree: DepNode[] = []
|
||||||
|
const stack: { node: DepNode; depth: number }[] = []
|
||||||
|
let totalCount = 0
|
||||||
|
|
||||||
|
for (const line of lines) {
|
||||||
|
// Determine depth by prefix characters
|
||||||
|
// Root line has no prefix markers
|
||||||
|
const trimmed = line.replace(/^[\s|\\+\-]+/, "").trim()
|
||||||
|
if (!trimmed || trimmed.startsWith("[")) continue
|
||||||
|
|
||||||
|
// Calculate depth from prefix
|
||||||
|
let depth = 0
|
||||||
|
const prefixMatch = line.match(/^([\s|\\+\-]*)/)
|
||||||
|
if (prefixMatch) {
|
||||||
|
const prefix = prefixMatch[1]
|
||||||
|
// Each level is 3 chars: "+- " or "| " or "\- "
|
||||||
|
if (prefix.length === 0) {
|
||||||
|
depth = 0
|
||||||
|
} else {
|
||||||
|
depth = Math.ceil(prefix.length / 3)
|
||||||
|
}
|
||||||
|
}
|
||||||
|
|
||||||
|
// Parse: groupId:artifactId:packaging:version:scope
|
||||||
|
// or: groupId:artifactId:packaging:classifier:version:scope
|
||||||
|
const parts = trimmed.split(":")
|
||||||
|
if (parts.length < 4) {
|
||||||
|
if (depth === 0 && parts.length >= 3) {
|
||||||
|
rootArtifact = trimmed
|
||||||
|
}
|
||||||
|
continue
|
||||||
|
}
|
||||||
|
|
||||||
|
let gId: string, aId: string, ver: string, sc: string
|
||||||
|
if (parts.length === 5) {
|
||||||
|
[gId, aId, , ver, sc] = parts
|
||||||
|
} else if (parts.length >= 6) {
|
||||||
|
[gId, aId, , , ver, sc] = parts
|
||||||
|
} else {
|
||||||
|
[gId, aId, , ver] = parts
|
||||||
|
sc = "compile"
|
||||||
|
}
|
||||||
|
|
||||||
|
if (depth === 0 && !rootArtifact) {
|
||||||
|
rootArtifact = trimmed
|
||||||
|
continue
|
||||||
|
}
|
||||||
|
|
||||||
|
totalCount++
|
||||||
|
|
||||||
|
// Apply filters
|
||||||
|
if (groupIdFilter && !gId.includes(groupIdFilter)) continue
|
||||||
|
if (scope !== "all" && sc !== scope) continue
|
||||||
|
|
||||||
|
const node: DepNode = {
|
||||||
|
groupId: gId,
|
||||||
|
artifactId: aId,
|
||||||
|
version: ver,
|
||||||
|
scope: sc,
|
||||||
|
depth,
|
||||||
|
children: [],
|
||||||
|
}
|
||||||
|
|
||||||
|
// Place in tree
|
||||||
|
while (stack.length > 0 && stack[stack.length - 1].depth >= depth) {
|
||||||
|
stack.pop()
|
||||||
|
}
|
||||||
|
|
||||||
|
if (stack.length === 0) {
|
||||||
|
tree.push(node)
|
||||||
|
} else {
|
||||||
|
stack[stack.length - 1].node.children.push(node)
|
||||||
|
}
|
||||||
|
stack.push({ node, depth })
|
||||||
|
}
|
||||||
|
|
||||||
|
// Count filtered nodes
|
||||||
|
const countNodes = (nodes: DepNode[]): number => {
|
||||||
|
let c = nodes.length
|
||||||
|
for (const n of nodes) c += countNodes(n.children)
|
||||||
|
return c
|
||||||
|
}
|
||||||
|
const filtered = countNodes(tree)
|
||||||
|
|
||||||
|
// Truncate if too large
|
||||||
|
let truncated = false
|
||||||
|
const MAX_NODES = 500
|
||||||
|
if (filtered > MAX_NODES) {
|
||||||
|
truncated = true
|
||||||
|
// Flatten to first 2 levels only
|
||||||
|
for (const node of tree) {
|
||||||
|
for (const child of node.children) {
|
||||||
|
child.children = []
|
||||||
|
}
|
||||||
|
}
|
||||||
|
}
|
||||||
|
|
||||||
|
return JSON.stringify({
|
||||||
|
command: `mvn ${args.join(" ")}`,
|
||||||
|
ok: true,
|
||||||
|
rootArtifact,
|
||||||
|
dependencyCount: totalCount,
|
||||||
|
filtered,
|
||||||
|
truncated,
|
||||||
|
tree,
|
||||||
|
}, null, 2)
|
||||||
|
} catch (err: any) {
|
||||||
|
return JSON.stringify({ error: err.message ?? String(err) }, null, 2)
|
||||||
|
}
|
||||||
|
},
|
||||||
|
})
|
||||||
@@ -0,0 +1,68 @@
|
|||||||
|
import { parametersSchema as z, defineCustomTool } from "@roo-code/types"
|
||||||
|
import { spawnSync } from "child_process"
|
||||||
|
import { readdirSync, readFileSync, existsSync } from "fs"
|
||||||
|
import { join } from "path"
|
||||||
|
|
||||||
|
export default defineCustomTool({
|
||||||
|
name: "mvn_test",
|
||||||
|
description: "Run Maven tests for a module in a multi-module project. Parses surefire XML reports and returns structured pass/fail results.",
|
||||||
|
parameters: z.object({
|
||||||
|
worktreePath: z.string().describe("Path to the project root or worktree (e.g. /path/to/my-project)"),
|
||||||
|
module: z.string().describe("Module path relative to java/, e.g. modules/cs-modules/my-module"),
|
||||||
|
testClass: z.string().optional().describe("Specific test class to run, e.g. MyServiceTest"),
|
||||||
|
}),
|
||||||
|
async execute({ worktreePath, module, testClass }) {
|
||||||
|
const pomPath = join(worktreePath, "java", "pom.xml")
|
||||||
|
if (!existsSync(pomPath)) {
|
||||||
|
return `Error: pom.xml not found at ${pomPath}`
|
||||||
|
}
|
||||||
|
|
||||||
|
const args = ["test", "-pl", `java/${module}`, "-f", pomPath, "--batch-mode", "-q"]
|
||||||
|
if (testClass) {
|
||||||
|
args.push(`-Dtest=${testClass}`)
|
||||||
|
}
|
||||||
|
|
||||||
|
const result = spawnSync("mvn", args, {
|
||||||
|
encoding: "utf-8",
|
||||||
|
timeout: 300000,
|
||||||
|
cwd: worktreePath,
|
||||||
|
maxBuffer: 10 * 1024 * 1024,
|
||||||
|
})
|
||||||
|
|
||||||
|
const surefireDir = join(worktreePath, "java", module, "target", "surefire-reports")
|
||||||
|
const summary = { total: 0, passed: 0, failed: 0, errors: 0, skipped: 0, failures: [] as string[] }
|
||||||
|
|
||||||
|
if (existsSync(surefireDir)) {
|
||||||
|
try {
|
||||||
|
const xmlFiles = readdirSync(surefireDir).filter(f => f.startsWith("TEST-") && f.endsWith(".xml"))
|
||||||
|
for (const xmlFile of xmlFiles) {
|
||||||
|
const content = readFileSync(join(surefireDir, xmlFile), "utf-8")
|
||||||
|
const testsMatch = content.match(/tests="(\d+)"/)
|
||||||
|
const failuresMatch = content.match(/failures="(\d+)"/)
|
||||||
|
const errorsMatch = content.match(/errors="(\d+)"/)
|
||||||
|
const skippedMatch = content.match(/skipped="(\d+)"/)
|
||||||
|
|
||||||
|
if (testsMatch) summary.total += parseInt(testsMatch[1])
|
||||||
|
if (failuresMatch) summary.failed += parseInt(failuresMatch[1])
|
||||||
|
if (errorsMatch) summary.errors += parseInt(errorsMatch[1])
|
||||||
|
if (skippedMatch) summary.skipped += parseInt(skippedMatch[1])
|
||||||
|
|
||||||
|
const failureMatches = content.matchAll(/<failure[^>]*message="([^"]*)"[^>]*>/g)
|
||||||
|
for (const m of failureMatches) {
|
||||||
|
summary.failures.push(`${xmlFile.replace("TEST-", "").replace(".xml", "")}: ${m[1]}`)
|
||||||
|
}
|
||||||
|
}
|
||||||
|
summary.passed = summary.total - summary.failed - summary.errors - summary.skipped
|
||||||
|
} catch (e) {
|
||||||
|
// surefire parsing failed, continue with what we have
|
||||||
|
}
|
||||||
|
}
|
||||||
|
|
||||||
|
return JSON.stringify({
|
||||||
|
buildStatus: result.status === 0 ? "SUCCESS" : "FAILURE",
|
||||||
|
exitCode: result.status,
|
||||||
|
summary,
|
||||||
|
lastOutput: (result.status !== 0 ? (result.stderr || result.stdout || "") : "").split("\n").slice(-15).join("\n"),
|
||||||
|
}, null, 2)
|
||||||
|
},
|
||||||
|
})
|
||||||
Generated
+154
@@ -0,0 +1,154 @@
|
|||||||
|
{
|
||||||
|
"name": "zoo-custom-tools",
|
||||||
|
"version": "1.0.0",
|
||||||
|
"lockfileVersion": 3,
|
||||||
|
"requires": true,
|
||||||
|
"packages": {
|
||||||
|
"": {
|
||||||
|
"name": "zoo-custom-tools",
|
||||||
|
"version": "1.0.0",
|
||||||
|
"dependencies": {
|
||||||
|
"@roo-code/types": "^1.115.0",
|
||||||
|
"fast-xml-parser": "^5.9.3"
|
||||||
|
}
|
||||||
|
},
|
||||||
|
"node_modules/@nodable/entities": {
|
||||||
|
"version": "2.2.0",
|
||||||
|
"resolved": "https://registry.npmjs.org/@nodable/entities/-/entities-2.2.0.tgz",
|
||||||
|
"integrity": "sha512-9uGyhaQavEUMC8AIddIjau4NsnsXhou+j5sBAGojCM1oxmQpVKTWR/9JxABD6UAv12vpIms55fPZKFQEhG6uBg==",
|
||||||
|
"funding": [
|
||||||
|
{
|
||||||
|
"type": "github",
|
||||||
|
"url": "https://github.com/sponsors/nodable"
|
||||||
|
}
|
||||||
|
],
|
||||||
|
"license": "MIT"
|
||||||
|
},
|
||||||
|
"node_modules/@roo-code/types": {
|
||||||
|
"version": "1.115.0",
|
||||||
|
"resolved": "https://registry.npmjs.org/@roo-code/types/-/types-1.115.0.tgz",
|
||||||
|
"integrity": "sha512-aJT8RhxoVdGRyiU7roQKgJRxget+4oOosQj/6XYufLHHGQnrGOkKCPRM7jGAMo88/8CRAmLgJcLAjEEsbpg8Qw==",
|
||||||
|
"license": "MIT",
|
||||||
|
"dependencies": {
|
||||||
|
"zod": "3.25.76"
|
||||||
|
}
|
||||||
|
},
|
||||||
|
"node_modules/anynum": {
|
||||||
|
"version": "1.0.1",
|
||||||
|
"resolved": "https://registry.npmjs.org/anynum/-/anynum-1.0.1.tgz",
|
||||||
|
"integrity": "sha512-N6//FLET/tXYNM/F6ABca1oH6fWB+KlTt909Le28WMDBk8oaT4vY17DCrwg2MvmuqUKt3Ni4N5dGJ/EoBgcO6A==",
|
||||||
|
"funding": [
|
||||||
|
{
|
||||||
|
"type": "github",
|
||||||
|
"url": "https://github.com/sponsors/NaturalIntelligence"
|
||||||
|
}
|
||||||
|
],
|
||||||
|
"license": "MIT"
|
||||||
|
},
|
||||||
|
"node_modules/fast-xml-builder": {
|
||||||
|
"version": "1.2.0",
|
||||||
|
"resolved": "https://registry.npmjs.org/fast-xml-builder/-/fast-xml-builder-1.2.0.tgz",
|
||||||
|
"integrity": "sha512-00aAWieqff+ZJhsXA4g1g7M8k+7AYoMUUHF+/zFb5U6Uv/P0Vl4QZo84/IcufzYalLuEj9928bXN9PbbFzMF0Q==",
|
||||||
|
"funding": [
|
||||||
|
{
|
||||||
|
"type": "github",
|
||||||
|
"url": "https://github.com/sponsors/NaturalIntelligence"
|
||||||
|
}
|
||||||
|
],
|
||||||
|
"license": "MIT",
|
||||||
|
"dependencies": {
|
||||||
|
"path-expression-matcher": "^1.5.0",
|
||||||
|
"xml-naming": "^0.1.0"
|
||||||
|
}
|
||||||
|
},
|
||||||
|
"node_modules/fast-xml-parser": {
|
||||||
|
"version": "5.9.3",
|
||||||
|
"resolved": "https://registry.npmjs.org/fast-xml-parser/-/fast-xml-parser-5.9.3.tgz",
|
||||||
|
"integrity": "sha512-brCNCeScma/kqa54J4PIDriSSSLssRkuYaUCpvHJulGc3HGI/xxKUCTDcYkAdqJsyb//ydpbxecjC3hB9+tb/g==",
|
||||||
|
"funding": [
|
||||||
|
{
|
||||||
|
"type": "github",
|
||||||
|
"url": "https://github.com/sponsors/NaturalIntelligence"
|
||||||
|
}
|
||||||
|
],
|
||||||
|
"license": "MIT",
|
||||||
|
"dependencies": {
|
||||||
|
"@nodable/entities": "^2.2.0",
|
||||||
|
"fast-xml-builder": "^1.2.0",
|
||||||
|
"is-unsafe": "^1.0.1",
|
||||||
|
"path-expression-matcher": "^1.5.0",
|
||||||
|
"strnum": "^2.4.1",
|
||||||
|
"xml-naming": "^0.1.0"
|
||||||
|
},
|
||||||
|
"bin": {
|
||||||
|
"fxparser": "src/cli/cli.js"
|
||||||
|
}
|
||||||
|
},
|
||||||
|
"node_modules/is-unsafe": {
|
||||||
|
"version": "1.0.1",
|
||||||
|
"resolved": "https://registry.npmjs.org/is-unsafe/-/is-unsafe-1.0.1.tgz",
|
||||||
|
"integrity": "sha512-CLK2+VdgERgD96EYm5lUQssZYlRg2tkZnbsxZoacmSiRxiFJ4Nk4SzjCl+Ur+v3kXIY9dTIdb3IH22y1mZ56LA==",
|
||||||
|
"funding": [
|
||||||
|
{
|
||||||
|
"type": "github",
|
||||||
|
"url": "https://github.com/sponsors/NaturalIntelligence"
|
||||||
|
}
|
||||||
|
],
|
||||||
|
"license": "MIT"
|
||||||
|
},
|
||||||
|
"node_modules/path-expression-matcher": {
|
||||||
|
"version": "1.6.0",
|
||||||
|
"resolved": "https://registry.npmjs.org/path-expression-matcher/-/path-expression-matcher-1.6.0.tgz",
|
||||||
|
"integrity": "sha512-e5y7RCLHKjemsgQ4eqGJtPyr10ILz25HO7flzxhTV8bgvd5yHx98DGtCAtbVW9f2TqnYI/gEVZd+vz7snrdPTw==",
|
||||||
|
"funding": [
|
||||||
|
{
|
||||||
|
"type": "github",
|
||||||
|
"url": "https://github.com/sponsors/NaturalIntelligence"
|
||||||
|
}
|
||||||
|
],
|
||||||
|
"license": "MIT",
|
||||||
|
"engines": {
|
||||||
|
"node": ">=14.0.0"
|
||||||
|
}
|
||||||
|
},
|
||||||
|
"node_modules/strnum": {
|
||||||
|
"version": "2.4.1",
|
||||||
|
"resolved": "https://registry.npmjs.org/strnum/-/strnum-2.4.1.tgz",
|
||||||
|
"integrity": "sha512-M9eUSMT2dCB2cTNPG7UYj6KuK7RJR2SN2+yCV/fTW3xzTCS6EaGZ5pSMgDIjB7r8zSfTGk+dvvn9rTjpVS9Mwg==",
|
||||||
|
"funding": [
|
||||||
|
{
|
||||||
|
"type": "github",
|
||||||
|
"url": "https://github.com/sponsors/NaturalIntelligence"
|
||||||
|
}
|
||||||
|
],
|
||||||
|
"license": "MIT",
|
||||||
|
"dependencies": {
|
||||||
|
"anynum": "^1.0.1"
|
||||||
|
}
|
||||||
|
},
|
||||||
|
"node_modules/xml-naming": {
|
||||||
|
"version": "0.1.0",
|
||||||
|
"resolved": "https://registry.npmjs.org/xml-naming/-/xml-naming-0.1.0.tgz",
|
||||||
|
"integrity": "sha512-k8KO9hrMyNk6tUWqUfkTEZbezRRpONVOzUTnc97VnCvyj6Tf9lyUR9EDAIeiVLv56jsMcoXEwjW8Kv5yPY52lw==",
|
||||||
|
"funding": [
|
||||||
|
{
|
||||||
|
"type": "github",
|
||||||
|
"url": "https://github.com/sponsors/NaturalIntelligence"
|
||||||
|
}
|
||||||
|
],
|
||||||
|
"license": "MIT",
|
||||||
|
"engines": {
|
||||||
|
"node": ">=16.0.0"
|
||||||
|
}
|
||||||
|
},
|
||||||
|
"node_modules/zod": {
|
||||||
|
"version": "3.25.76",
|
||||||
|
"resolved": "https://registry.npmjs.org/zod/-/zod-3.25.76.tgz",
|
||||||
|
"integrity": "sha512-gzUt/qt81nXsFGKIFcC3YnfEAx5NkunCfnDlvuBSSFS02bcXu4Lmea0AFIUwbLWxWPx3d9p8S5QoaujKcNQxcQ==",
|
||||||
|
"license": "MIT",
|
||||||
|
"funding": {
|
||||||
|
"url": "https://github.com/sponsors/colinhacks"
|
||||||
|
}
|
||||||
|
}
|
||||||
|
}
|
||||||
|
}
|
||||||
@@ -0,0 +1,9 @@
|
|||||||
|
{
|
||||||
|
"name": "zoo-custom-tools",
|
||||||
|
"version": "1.0.0",
|
||||||
|
"private": true,
|
||||||
|
"dependencies": {
|
||||||
|
"@roo-code/types": "^1.115.0",
|
||||||
|
"fast-xml-parser": "^5.9.3"
|
||||||
|
}
|
||||||
|
}
|
||||||
@@ -0,0 +1,121 @@
|
|||||||
|
import { parametersSchema as z, defineCustomTool, CustomToolContext } from "@roo-code/types"
|
||||||
|
// @ts-ignore - Node built-ins
|
||||||
|
import { readFileSync } from "fs"
|
||||||
|
// @ts-ignore - Node built-ins
|
||||||
|
import path from "path"
|
||||||
|
|
||||||
|
export default defineCustomTool({
|
||||||
|
name: "pom_inspect",
|
||||||
|
description: "Parse a pom.xml and return structured JSON with groupId, artifactId, version, modules, properties, parent, and optionally dependencies. Saves reading raw XML just to extract Maven coordinates.",
|
||||||
|
parameters: z.object({
|
||||||
|
pomPath: z.string().describe("Absolute or relative path to pom.xml"),
|
||||||
|
includeDependencies: z.boolean().optional().describe("Include <dependencies> list in output (default: false)"),
|
||||||
|
}),
|
||||||
|
async execute({ pomPath, includeDependencies = false }, context: CustomToolContext) {
|
||||||
|
try {
|
||||||
|
// @ts-ignore - installed dependency
|
||||||
|
const { XMLParser } = require("fast-xml-parser")
|
||||||
|
|
||||||
|
// Resolve relative paths against the task's working directory
|
||||||
|
// @ts-ignore - task.cwd exists at runtime
|
||||||
|
const cwd = context?.task?.cwd ?? process.cwd()
|
||||||
|
const absPath = path.isAbsolute(pomPath) ? pomPath : path.resolve(cwd, pomPath)
|
||||||
|
const xml = readFileSync(absPath, "utf-8")
|
||||||
|
|
||||||
|
const parser = new XMLParser({
|
||||||
|
ignoreAttributes: false,
|
||||||
|
attributeNamePrefix: "@_",
|
||||||
|
textNodeName: "#text",
|
||||||
|
isArray: (name: string) => ["module", "dependency"].includes(name),
|
||||||
|
})
|
||||||
|
const doc = parser.parse(xml)
|
||||||
|
const project = doc.project
|
||||||
|
|
||||||
|
if (!project) {
|
||||||
|
return JSON.stringify({ error: "No <project> root element found in POM" }, null, 2)
|
||||||
|
}
|
||||||
|
|
||||||
|
// Extract properties for placeholder resolution
|
||||||
|
const properties: Record<string, string> = {}
|
||||||
|
if (project.properties) {
|
||||||
|
for (const [key, val] of Object.entries(project.properties)) {
|
||||||
|
if (typeof val === "string" || typeof val === "number") {
|
||||||
|
properties[key] = String(val)
|
||||||
|
}
|
||||||
|
}
|
||||||
|
}
|
||||||
|
|
||||||
|
const resolvePlaceholder = (val: any): string | null => {
|
||||||
|
if (val == null) return null
|
||||||
|
let s = String(val)
|
||||||
|
const match = s.match(/^\$\{(.+)\}$/)
|
||||||
|
if (match) {
|
||||||
|
const propKey = match[1]
|
||||||
|
if (properties[propKey]) return properties[propKey]
|
||||||
|
// Check project-level refs
|
||||||
|
if (propKey === "project.version" && project.version) return String(project.version)
|
||||||
|
if (propKey === "project.groupId" && project.groupId) return String(project.groupId)
|
||||||
|
}
|
||||||
|
return s
|
||||||
|
}
|
||||||
|
|
||||||
|
// Parent
|
||||||
|
let parent = null
|
||||||
|
if (project.parent) {
|
||||||
|
parent = {
|
||||||
|
groupId: String(project.parent.groupId || ""),
|
||||||
|
artifactId: String(project.parent.artifactId || ""),
|
||||||
|
version: resolvePlaceholder(project.parent.version),
|
||||||
|
}
|
||||||
|
}
|
||||||
|
|
||||||
|
// Modules
|
||||||
|
let modules: string[] = []
|
||||||
|
if (project.modules?.module) {
|
||||||
|
modules = project.modules.module.map((m: any) => String(m))
|
||||||
|
}
|
||||||
|
|
||||||
|
// Dependencies
|
||||||
|
let dependencies: any[] | undefined = undefined
|
||||||
|
if (includeDependencies && project.dependencies?.dependency) {
|
||||||
|
dependencies = project.dependencies.dependency.map((d: any) => ({
|
||||||
|
groupId: String(d.groupId || ""),
|
||||||
|
artifactId: String(d.artifactId || ""),
|
||||||
|
version: resolvePlaceholder(d.version),
|
||||||
|
scope: d.scope ? String(d.scope) : "compile",
|
||||||
|
}))
|
||||||
|
}
|
||||||
|
|
||||||
|
// Also check dependencyManagement
|
||||||
|
if (includeDependencies && project.dependencyManagement?.dependencies?.dependency) {
|
||||||
|
const managed = project.dependencyManagement.dependencies.dependency.map((d: any) => ({
|
||||||
|
groupId: String(d.groupId || ""),
|
||||||
|
artifactId: String(d.artifactId || ""),
|
||||||
|
version: resolvePlaceholder(d.version),
|
||||||
|
scope: d.scope ? String(d.scope) : "managed",
|
||||||
|
}))
|
||||||
|
if (!dependencies) dependencies = managed
|
||||||
|
else dependencies = [...dependencies, ...managed]
|
||||||
|
}
|
||||||
|
|
||||||
|
const result: any = {
|
||||||
|
groupId: resolvePlaceholder(project.groupId) || parent?.groupId || "",
|
||||||
|
artifactId: String(project.artifactId || ""),
|
||||||
|
version: resolvePlaceholder(project.version) || parent?.version || "",
|
||||||
|
packaging: String(project.packaging || "jar"),
|
||||||
|
name: project.name ? String(project.name) : null,
|
||||||
|
parent,
|
||||||
|
modules,
|
||||||
|
properties,
|
||||||
|
}
|
||||||
|
|
||||||
|
if (includeDependencies && dependencies) {
|
||||||
|
result.dependencies = dependencies
|
||||||
|
}
|
||||||
|
|
||||||
|
return JSON.stringify(result, null, 2)
|
||||||
|
} catch (err: any) {
|
||||||
|
return JSON.stringify({ error: err.message ?? String(err) }, null, 2)
|
||||||
|
}
|
||||||
|
},
|
||||||
|
})
|
||||||
@@ -0,0 +1,63 @@
|
|||||||
|
import { parametersSchema as z, defineCustomTool, CustomToolContext } from "@roo-code/types"
|
||||||
|
// @ts-ignore - Node built-ins
|
||||||
|
import { spawnSync } from "child_process"
|
||||||
|
|
||||||
|
export default defineCustomTool({
|
||||||
|
name: "port_watch",
|
||||||
|
description: "Check what process holds a given TCP/UDP port. Replaces 'lsof -i :PORT' shell calls when debugging dev servers.",
|
||||||
|
parameters: z.object({
|
||||||
|
port: z.number().describe("TCP port number to check (1-65535)"),
|
||||||
|
protocol: z.enum(["tcp", "udp", "both"]).optional().describe("Protocol filter (default: tcp)"),
|
||||||
|
}),
|
||||||
|
async execute({ port, protocol = "tcp" }, context: CustomToolContext) {
|
||||||
|
try {
|
||||||
|
if (port < 1 || port > 65535) {
|
||||||
|
return JSON.stringify({ error: "Invalid port: must be between 1 and 65535" }, null, 2)
|
||||||
|
}
|
||||||
|
|
||||||
|
const listeners: any[] = []
|
||||||
|
|
||||||
|
const runLsof = (proto: string) => {
|
||||||
|
const flag = proto === "tcp" ? `-iTCP:${port}` : `-iUDP:${port}`
|
||||||
|
const stateFlag = proto === "tcp" ? ["-sTCP:LISTEN"] : []
|
||||||
|
const result = spawnSync("lsof", [flag, ...stateFlag, "-P", "-n"], {
|
||||||
|
encoding: "utf-8",
|
||||||
|
timeout: 10_000,
|
||||||
|
})
|
||||||
|
|
||||||
|
if (!result.stdout) return
|
||||||
|
|
||||||
|
const lines = result.stdout.split("\n").filter((l: string) => l.trim())
|
||||||
|
// Skip header line
|
||||||
|
for (let i = 1; i < lines.length; i++) {
|
||||||
|
const parts = lines[i].split(/\s+/)
|
||||||
|
if (parts.length < 9) continue
|
||||||
|
listeners.push({
|
||||||
|
pid: parseInt(parts[1], 10) || 0,
|
||||||
|
command: parts[0],
|
||||||
|
user: parts[2],
|
||||||
|
type: parts[4], // IPv4 or IPv6
|
||||||
|
state: parts[9] || (proto === "udp" ? "UDP" : "UNKNOWN"),
|
||||||
|
address: parts[8] || `*:${port}`,
|
||||||
|
})
|
||||||
|
}
|
||||||
|
}
|
||||||
|
|
||||||
|
if (protocol === "tcp" || protocol === "both") {
|
||||||
|
runLsof("tcp")
|
||||||
|
}
|
||||||
|
if (protocol === "udp" || protocol === "both") {
|
||||||
|
runLsof("udp")
|
||||||
|
}
|
||||||
|
|
||||||
|
return JSON.stringify({
|
||||||
|
port,
|
||||||
|
protocol,
|
||||||
|
inUse: listeners.length > 0,
|
||||||
|
listeners,
|
||||||
|
}, null, 2)
|
||||||
|
} catch (err: any) {
|
||||||
|
return JSON.stringify({ error: err.message ?? String(err) }, null, 2)
|
||||||
|
}
|
||||||
|
},
|
||||||
|
})
|
||||||
@@ -0,0 +1,366 @@
|
|||||||
|
import { parametersSchema as z, defineCustomTool, CustomToolContext } from "@roo-code/types"
|
||||||
|
// @ts-ignore - Node built-ins
|
||||||
|
import { spawn } from "child_process"
|
||||||
|
// @ts-ignore - Node built-ins
|
||||||
|
import { existsSync, mkdirSync, renameSync, createWriteStream, readFileSync, writeFileSync, WriteStream } from "fs"
|
||||||
|
// @ts-ignore - Node built-ins
|
||||||
|
import path from "path"
|
||||||
|
// @ts-ignore - Node built-ins
|
||||||
|
import { spawnSync } from "child_process"
|
||||||
|
|
||||||
|
export default defineCustomTool({
|
||||||
|
name: "snyk_scan",
|
||||||
|
description: "Run Snyk security scans (SCA + SAST) on a project and produce a Zusammenfassung JSON compatible with Sven's Copilot prompt chain. Requires `snyk` CLI authenticated locally.",
|
||||||
|
parameters: z.object({
|
||||||
|
projectRoot: z.string().describe("Absolute or relative path to the project root (must be a git repo)"),
|
||||||
|
mode: z.enum(["sca", "code", "both"]).optional().describe("Which scan(s) to run (default: both)"),
|
||||||
|
severityThreshold: z.enum(["low", "medium", "high", "critical"]).optional().describe("Severity threshold for SAST scan (default: low)"),
|
||||||
|
outputDir: z.string().optional().describe("Output directory for reports (default: <projectRoot>/.snyk-reports/<basename>)"),
|
||||||
|
includeIgnores: z.boolean().optional().describe("Pass --include-ignores to snyk (default: true)"),
|
||||||
|
timeoutSec: z.number().optional().describe("Overall timeout in seconds (default: 600)"),
|
||||||
|
}),
|
||||||
|
async execute(
|
||||||
|
{ projectRoot, mode = "both", severityThreshold = "low", outputDir, includeIgnores = true, timeoutSec = 600 },
|
||||||
|
context: CustomToolContext
|
||||||
|
) {
|
||||||
|
try {
|
||||||
|
// --- Resolve projectRoot ---
|
||||||
|
// @ts-ignore - task.cwd exists at runtime
|
||||||
|
const cwd = context?.task?.cwd ?? process.cwd()
|
||||||
|
const resolvedRoot = path.isAbsolute(projectRoot) ? projectRoot : path.resolve(cwd, projectRoot)
|
||||||
|
|
||||||
|
if (!existsSync(resolvedRoot)) {
|
||||||
|
return JSON.stringify({ ok: false, error: `Project root does not exist: ${resolvedRoot}` }, null, 2)
|
||||||
|
}
|
||||||
|
|
||||||
|
// --- Auth check ---
|
||||||
|
const whoami = spawnSync("snyk", ["whoami"], { encoding: "utf-8", timeout: 15_000 })
|
||||||
|
if (whoami.status !== 0) {
|
||||||
|
return JSON.stringify({ ok: false, error: "Snyk not authenticated. Run 'snyk auth' first." }, null, 2)
|
||||||
|
}
|
||||||
|
|
||||||
|
// --- Git branch ---
|
||||||
|
const gitBranch = spawnSync("git", ["-C", resolvedRoot, "rev-parse", "--abbrev-ref", "HEAD"], {
|
||||||
|
encoding: "utf-8",
|
||||||
|
timeout: 10_000,
|
||||||
|
})
|
||||||
|
if (gitBranch.status !== 0) {
|
||||||
|
return JSON.stringify({ ok: false, error: `Not a git repository: ${resolvedRoot}` }, null, 2)
|
||||||
|
}
|
||||||
|
const branch = (gitBranch.stdout || "").trim()
|
||||||
|
const branchSafe = branch.replace(/[/\\:*?"<>|]/g, "_")
|
||||||
|
|
||||||
|
// --- Timestamp ---
|
||||||
|
const now = new Date()
|
||||||
|
const pad = (n: number) => String(n).padStart(2, "0")
|
||||||
|
const timestamp = `${now.getFullYear()}-${pad(now.getMonth() + 1)}-${pad(now.getDate())}_${pad(now.getHours())}-${pad(now.getMinutes())}-${pad(now.getSeconds())}`
|
||||||
|
|
||||||
|
// --- OutputDir resolution ---
|
||||||
|
const baseName = path.basename(resolvedRoot)
|
||||||
|
const resolvedOutputDir = outputDir
|
||||||
|
? (path.isAbsolute(outputDir) ? outputDir : path.resolve(cwd, outputDir))
|
||||||
|
: path.join(resolvedRoot, ".snyk-reports", baseName)
|
||||||
|
|
||||||
|
if (!existsSync(resolvedOutputDir)) {
|
||||||
|
mkdirSync(resolvedOutputDir, { recursive: true })
|
||||||
|
}
|
||||||
|
|
||||||
|
// --- File paths ---
|
||||||
|
const scaJsonPath = path.join(resolvedOutputDir, `snyk-sca_${branchSafe}_${timestamp}.json`)
|
||||||
|
const codeJsonPath = path.join(resolvedOutputDir, `snyk-code_${branchSafe}_${timestamp}.json`)
|
||||||
|
const summaryPath = path.join(resolvedOutputDir, `snyk-zusammenfassung_${branchSafe}_${timestamp}.json`)
|
||||||
|
|
||||||
|
const warnings: string[] = []
|
||||||
|
const commands: { sca: string | null; code: string | null } = { sca: null, code: null }
|
||||||
|
const exitCodes: { sca: number | null; code: number | null } = { sca: null, code: null }
|
||||||
|
|
||||||
|
// --- Maven Wrapper hack ---
|
||||||
|
const hasPom = existsSync(path.join(resolvedRoot, "pom.xml"))
|
||||||
|
const wrapperFiles: { original: string; backup: string }[] = []
|
||||||
|
|
||||||
|
function disableMavenWrapper() {
|
||||||
|
if (!hasPom) return
|
||||||
|
for (const candidate of ["mvnw", "mvnw.cmd"]) {
|
||||||
|
const original = path.join(resolvedRoot, candidate)
|
||||||
|
if (existsSync(original)) {
|
||||||
|
const backup = `${original}.snyk-disabled`
|
||||||
|
renameSync(original, backup)
|
||||||
|
wrapperFiles.push({ original, backup })
|
||||||
|
}
|
||||||
|
}
|
||||||
|
if (wrapperFiles.length > 0) {
|
||||||
|
warnings.push("Maven Wrapper temporarily disabled during scan")
|
||||||
|
}
|
||||||
|
}
|
||||||
|
|
||||||
|
function restoreMavenWrapper() {
|
||||||
|
for (const { original, backup } of wrapperFiles) {
|
||||||
|
if (existsSync(backup)) {
|
||||||
|
renameSync(backup, original)
|
||||||
|
}
|
||||||
|
}
|
||||||
|
}
|
||||||
|
|
||||||
|
// --- Spawn helper: stream stdout to file, capture for parsing ---
|
||||||
|
function runSnyk(args: string[], outPath: string, abortSignal: AbortSignal): Promise<{ exitCode: number; outputPath: string }> {
|
||||||
|
return new Promise((resolve, reject) => {
|
||||||
|
if (abortSignal.aborted) {
|
||||||
|
return reject(new Error("Timeout"))
|
||||||
|
}
|
||||||
|
|
||||||
|
const proc = spawn("snyk", args, {
|
||||||
|
cwd: resolvedRoot,
|
||||||
|
stdio: ["ignore", "pipe", "pipe"],
|
||||||
|
})
|
||||||
|
|
||||||
|
const ws: WriteStream = createWriteStream(outPath, { encoding: "utf-8" })
|
||||||
|
proc.stdout.pipe(ws)
|
||||||
|
// Also capture stderr into the same file (snyk mixes channels)
|
||||||
|
proc.stderr.pipe(ws, { end: false })
|
||||||
|
|
||||||
|
const onAbort = () => {
|
||||||
|
proc.kill("SIGTERM")
|
||||||
|
reject(new Error("Timeout"))
|
||||||
|
}
|
||||||
|
abortSignal.addEventListener("abort", onAbort, { once: true })
|
||||||
|
|
||||||
|
proc.on("error", (err: Error) => {
|
||||||
|
abortSignal.removeEventListener("abort", onAbort)
|
||||||
|
reject(err)
|
||||||
|
})
|
||||||
|
|
||||||
|
proc.on("close", (code: number | null) => {
|
||||||
|
abortSignal.removeEventListener("abort", onAbort)
|
||||||
|
ws.end(() => {
|
||||||
|
resolve({ exitCode: code ?? 1, outputPath: outPath })
|
||||||
|
})
|
||||||
|
})
|
||||||
|
})
|
||||||
|
}
|
||||||
|
|
||||||
|
// --- Exit code logic (port of Test-IsSnykFailure) ---
|
||||||
|
function isSnykFailure(exitCode: number, outputPath: string, scanMode: "SCA" | "CODE"): boolean {
|
||||||
|
if (exitCode === 0) return false
|
||||||
|
if (exitCode > 1) return true
|
||||||
|
|
||||||
|
// Exit 1 — usually means "findings detected". Parse to confirm.
|
||||||
|
let text: string
|
||||||
|
try {
|
||||||
|
text = readFileSync(outputPath, "utf-8")
|
||||||
|
} catch {
|
||||||
|
return true // Can't read output → treat as failure
|
||||||
|
}
|
||||||
|
|
||||||
|
let parsed: any
|
||||||
|
try {
|
||||||
|
parsed = JSON.parse(text)
|
||||||
|
} catch {
|
||||||
|
return true // Not valid JSON → failure
|
||||||
|
}
|
||||||
|
|
||||||
|
if (scanMode === "SCA") {
|
||||||
|
if (Array.isArray(parsed)) return false
|
||||||
|
if (parsed && typeof parsed === "object" && "error" in parsed) return true
|
||||||
|
return false
|
||||||
|
}
|
||||||
|
|
||||||
|
// CODE mode — SARIF format
|
||||||
|
if (parsed && typeof parsed === "object" && "runs" in parsed) return false
|
||||||
|
if (parsed && typeof parsed === "object" && "error" in parsed) return true
|
||||||
|
return true
|
||||||
|
}
|
||||||
|
|
||||||
|
// --- Run scans ---
|
||||||
|
const controller = new AbortController()
|
||||||
|
const timeoutHandle = setTimeout(() => controller.abort(), timeoutSec * 1000)
|
||||||
|
|
||||||
|
try {
|
||||||
|
disableMavenWrapper()
|
||||||
|
|
||||||
|
// SCA scan
|
||||||
|
if (mode === "sca" || mode === "both") {
|
||||||
|
const scaArgs = ["test", "--all-projects", "--json"]
|
||||||
|
if (includeIgnores) scaArgs.push("--include-ignores")
|
||||||
|
if (hasPom) scaArgs.push("--command=mvn")
|
||||||
|
commands.sca = `snyk ${scaArgs.join(" ")}`
|
||||||
|
|
||||||
|
const scaResult = await runSnyk(scaArgs, scaJsonPath, controller.signal)
|
||||||
|
exitCodes.sca = scaResult.exitCode
|
||||||
|
|
||||||
|
if (isSnykFailure(scaResult.exitCode, scaJsonPath, "SCA")) {
|
||||||
|
warnings.push(`SCA scan failed (exit ${scaResult.exitCode}). Check ${scaJsonPath}`)
|
||||||
|
}
|
||||||
|
}
|
||||||
|
|
||||||
|
// SAST scan
|
||||||
|
if (mode === "code" || mode === "both") {
|
||||||
|
const codeArgs = ["code", "test", ".", `--severity-threshold=${severityThreshold}`, "--json"]
|
||||||
|
if (includeIgnores) codeArgs.push("--include-ignores")
|
||||||
|
commands.code = `snyk ${codeArgs.join(" ")}`
|
||||||
|
|
||||||
|
const codeResult = await runSnyk(codeArgs, codeJsonPath, controller.signal)
|
||||||
|
exitCodes.code = codeResult.exitCode
|
||||||
|
|
||||||
|
if (isSnykFailure(codeResult.exitCode, codeJsonPath, "CODE")) {
|
||||||
|
warnings.push(`SAST scan failed (exit ${codeResult.exitCode}). Check ${codeJsonPath}`)
|
||||||
|
}
|
||||||
|
}
|
||||||
|
} finally {
|
||||||
|
clearTimeout(timeoutHandle)
|
||||||
|
restoreMavenWrapper()
|
||||||
|
}
|
||||||
|
|
||||||
|
// --- Build Zusammenfassung ---
|
||||||
|
function getGroupedSCA(jsonPath: string): any[] {
|
||||||
|
if (!existsSync(jsonPath)) return []
|
||||||
|
let raw: string
|
||||||
|
try { raw = readFileSync(jsonPath, "utf-8") } catch { return [] }
|
||||||
|
let data: any
|
||||||
|
try { data = JSON.parse(raw) } catch { return [] }
|
||||||
|
|
||||||
|
// Collect all vulnerabilities
|
||||||
|
let vulnerabilities: any[] = []
|
||||||
|
if (Array.isArray(data)) {
|
||||||
|
for (const project of data) {
|
||||||
|
if (project && Array.isArray(project.vulnerabilities)) {
|
||||||
|
vulnerabilities.push(...project.vulnerabilities)
|
||||||
|
}
|
||||||
|
}
|
||||||
|
} else if (data && Array.isArray(data.vulnerabilities)) {
|
||||||
|
vulnerabilities = data.vulnerabilities
|
||||||
|
}
|
||||||
|
|
||||||
|
if (vulnerabilities.length === 0) return []
|
||||||
|
|
||||||
|
// Group by id
|
||||||
|
const groups: Record<string, any[]> = {}
|
||||||
|
for (const vuln of vulnerabilities) {
|
||||||
|
const id = vuln.id || "unknown"
|
||||||
|
if (!groups[id]) groups[id] = []
|
||||||
|
groups[id].push(vuln)
|
||||||
|
}
|
||||||
|
|
||||||
|
const result: any[] = []
|
||||||
|
for (const [id, group] of Object.entries(groups)) {
|
||||||
|
const first = group[0]
|
||||||
|
result.push({
|
||||||
|
id,
|
||||||
|
title: first.title || "",
|
||||||
|
severity: first.severity || "unknown",
|
||||||
|
packageName: first.packageName || "",
|
||||||
|
version: first.version || "",
|
||||||
|
count: group.length,
|
||||||
|
type: "SCA",
|
||||||
|
})
|
||||||
|
}
|
||||||
|
|
||||||
|
// Sort by severity then id
|
||||||
|
const sevOrder: Record<string, number> = { critical: 0, high: 1, medium: 2, low: 3, unknown: 4 }
|
||||||
|
result.sort((a, b) => {
|
||||||
|
const sa = sevOrder[a.severity] ?? 4
|
||||||
|
const sb = sevOrder[b.severity] ?? 4
|
||||||
|
if (sa !== sb) return sa - sb
|
||||||
|
return a.id.localeCompare(b.id)
|
||||||
|
})
|
||||||
|
|
||||||
|
return result
|
||||||
|
}
|
||||||
|
|
||||||
|
function getGroupedSAST(jsonPath: string): any[] {
|
||||||
|
if (!existsSync(jsonPath)) return []
|
||||||
|
let raw: string
|
||||||
|
try { raw = readFileSync(jsonPath, "utf-8") } catch { return [] }
|
||||||
|
let data: any
|
||||||
|
try { data = JSON.parse(raw) } catch { return [] }
|
||||||
|
|
||||||
|
if (!data || !data.runs) return []
|
||||||
|
|
||||||
|
// Collect all results from all runs
|
||||||
|
let allResults: any[] = []
|
||||||
|
for (const run of data.runs) {
|
||||||
|
if (run && Array.isArray(run.results)) {
|
||||||
|
allResults.push(...run.results)
|
||||||
|
}
|
||||||
|
}
|
||||||
|
|
||||||
|
if (allResults.length === 0) return []
|
||||||
|
|
||||||
|
// Group by ruleId
|
||||||
|
const groups: Record<string, any[]> = {}
|
||||||
|
for (const result of allResults) {
|
||||||
|
const ruleId = result.ruleId || "unknown"
|
||||||
|
if (!groups[ruleId]) groups[ruleId] = []
|
||||||
|
groups[ruleId].push(result)
|
||||||
|
}
|
||||||
|
|
||||||
|
const output: any[] = []
|
||||||
|
for (const [ruleId, group] of Object.entries(groups)) {
|
||||||
|
const first = group[0]
|
||||||
|
const findings = group.map((r) => {
|
||||||
|
const loc = r.locations?.[0]?.physicalLocation
|
||||||
|
return {
|
||||||
|
file: loc?.artifactLocation?.uri || "",
|
||||||
|
line: loc?.region?.startLine || 0,
|
||||||
|
}
|
||||||
|
})
|
||||||
|
output.push({
|
||||||
|
id: ruleId,
|
||||||
|
title: first.message?.text || "",
|
||||||
|
severity: first.level || "warning",
|
||||||
|
count: group.length,
|
||||||
|
type: "SAST",
|
||||||
|
findings,
|
||||||
|
})
|
||||||
|
}
|
||||||
|
|
||||||
|
// Sort by severity then id
|
||||||
|
const sevOrder: Record<string, number> = { error: 0, warning: 1, note: 2 }
|
||||||
|
output.sort((a, b) => {
|
||||||
|
const sa = sevOrder[a.severity] ?? 3
|
||||||
|
const sb = sevOrder[b.severity] ?? 3
|
||||||
|
if (sa !== sb) return sa - sb
|
||||||
|
return a.id.localeCompare(b.id)
|
||||||
|
})
|
||||||
|
|
||||||
|
return output
|
||||||
|
}
|
||||||
|
|
||||||
|
const scaFindings = (mode === "sca" || mode === "both") ? getGroupedSCA(scaJsonPath) : []
|
||||||
|
const codeFindings = (mode === "code" || mode === "both") ? getGroupedSAST(codeJsonPath) : []
|
||||||
|
|
||||||
|
const summaryObj = {
|
||||||
|
branch,
|
||||||
|
timestamp,
|
||||||
|
baseDir: resolvedRoot,
|
||||||
|
project: {
|
||||||
|
project: baseName,
|
||||||
|
sca: scaFindings,
|
||||||
|
code: codeFindings,
|
||||||
|
},
|
||||||
|
}
|
||||||
|
|
||||||
|
// Write Zusammenfassung to disk
|
||||||
|
const summaryJson = JSON.stringify(summaryObj, null, 2)
|
||||||
|
writeFileSync(summaryPath, summaryJson, "utf-8")
|
||||||
|
|
||||||
|
// --- Return shape ---
|
||||||
|
return JSON.stringify({
|
||||||
|
ok: true,
|
||||||
|
command: commands,
|
||||||
|
branch,
|
||||||
|
timestamp,
|
||||||
|
outputDir: resolvedOutputDir,
|
||||||
|
files: {
|
||||||
|
sca: (mode === "sca" || mode === "both") ? scaJsonPath : null,
|
||||||
|
code: (mode === "code" || mode === "both") ? codeJsonPath : null,
|
||||||
|
summary: summaryPath,
|
||||||
|
},
|
||||||
|
summary: summaryObj,
|
||||||
|
exitCodes,
|
||||||
|
warnings,
|
||||||
|
}, null, 2)
|
||||||
|
} catch (err: any) {
|
||||||
|
return JSON.stringify({ ok: false, error: err.message ?? String(err) }, null, 2)
|
||||||
|
}
|
||||||
|
},
|
||||||
|
})
|
||||||
@@ -0,0 +1,144 @@
|
|||||||
|
import { parametersSchema as z, defineCustomTool, CustomToolContext } from "@roo-code/types"
|
||||||
|
// @ts-ignore - Node built-ins
|
||||||
|
import { readdirSync, readFileSync, statSync } from "fs"
|
||||||
|
// @ts-ignore - Node built-ins
|
||||||
|
import { join, resolve } from "path"
|
||||||
|
|
||||||
|
export default defineCustomTool({
|
||||||
|
name: "surefire_failures_summary",
|
||||||
|
description: "Find Maven surefire/failsafe XML reports and return a structured summary of ONLY the failed/errored tests. Saves reading dozens of XML files manually.",
|
||||||
|
parameters: z.object({
|
||||||
|
projectRoot: z.string().describe("Repo root or module path (absolute or relative)"),
|
||||||
|
module: z.string().optional().describe("Sub-path like 'java/modules/cs-modules/eau' to scope the search"),
|
||||||
|
}),
|
||||||
|
async execute({ projectRoot, module }, context: CustomToolContext) {
|
||||||
|
try {
|
||||||
|
// @ts-ignore - installed dependency
|
||||||
|
const { XMLParser } = require("fast-xml-parser")
|
||||||
|
|
||||||
|
const root = resolve(module ? join(projectRoot, module) : projectRoot)
|
||||||
|
const reportFiles: string[] = []
|
||||||
|
|
||||||
|
// Recursive walk to find surefire report XMLs
|
||||||
|
const walk = (dir: string, depth: number) => {
|
||||||
|
if (depth > 12) return
|
||||||
|
let entries: string[]
|
||||||
|
try {
|
||||||
|
entries = readdirSync(dir)
|
||||||
|
} catch {
|
||||||
|
return
|
||||||
|
}
|
||||||
|
for (const entry of entries) {
|
||||||
|
if (entry === "node_modules" || entry === ".git") continue
|
||||||
|
const full = join(dir, entry)
|
||||||
|
try {
|
||||||
|
const st = statSync(full)
|
||||||
|
if (st.isDirectory()) {
|
||||||
|
if (entry === "surefire-reports" || entry === "failsafe-reports") {
|
||||||
|
// Collect TEST-*.xml from this directory
|
||||||
|
const xmls = readdirSync(full).filter(
|
||||||
|
(f: string) => f.startsWith("TEST-") && f.endsWith(".xml")
|
||||||
|
)
|
||||||
|
for (const xml of xmls) {
|
||||||
|
reportFiles.push(join(full, xml))
|
||||||
|
}
|
||||||
|
} else {
|
||||||
|
walk(full, depth + 1)
|
||||||
|
}
|
||||||
|
}
|
||||||
|
} catch {
|
||||||
|
// skip unreadable
|
||||||
|
}
|
||||||
|
}
|
||||||
|
}
|
||||||
|
walk(root, 0)
|
||||||
|
|
||||||
|
if (reportFiles.length === 0) {
|
||||||
|
return JSON.stringify({
|
||||||
|
reportsFound: 0,
|
||||||
|
totalTests: 0,
|
||||||
|
failed: 0,
|
||||||
|
errors: 0,
|
||||||
|
skipped: 0,
|
||||||
|
failures: [],
|
||||||
|
note: "No surefire/failsafe report XMLs found. Run 'mvn test' first.",
|
||||||
|
}, null, 2)
|
||||||
|
}
|
||||||
|
|
||||||
|
// Filter to only recent reports (within 1 hour of the newest)
|
||||||
|
const mtimes = reportFiles.map((f) => {
|
||||||
|
try { return statSync(f).mtimeMs } catch { return 0 }
|
||||||
|
})
|
||||||
|
const newest = Math.max(...mtimes)
|
||||||
|
const cutoff = newest - 3600_000 // 1 hour
|
||||||
|
|
||||||
|
const parser = new XMLParser({
|
||||||
|
ignoreAttributes: false,
|
||||||
|
attributeNamePrefix: "@_",
|
||||||
|
isArray: (name: string) => name === "testcase",
|
||||||
|
})
|
||||||
|
|
||||||
|
let totalTests = 0
|
||||||
|
let totalFailed = 0
|
||||||
|
let totalErrors = 0
|
||||||
|
let totalSkipped = 0
|
||||||
|
let reportsProcessed = 0
|
||||||
|
const failures: any[] = []
|
||||||
|
|
||||||
|
for (let i = 0; i < reportFiles.length; i++) {
|
||||||
|
if (mtimes[i] < cutoff) continue
|
||||||
|
reportsProcessed++
|
||||||
|
|
||||||
|
const xml = readFileSync(reportFiles[i], "utf-8")
|
||||||
|
let doc: any
|
||||||
|
try {
|
||||||
|
doc = parser.parse(xml)
|
||||||
|
} catch {
|
||||||
|
continue
|
||||||
|
}
|
||||||
|
|
||||||
|
const suite = doc.testsuite
|
||||||
|
if (!suite) continue
|
||||||
|
|
||||||
|
const tests = parseInt(suite["@_tests"] || "0", 10)
|
||||||
|
const failed = parseInt(suite["@_failures"] || "0", 10)
|
||||||
|
const errors = parseInt(suite["@_errors"] || "0", 10)
|
||||||
|
const skipped = parseInt(suite["@_skipped"] || "0", 10)
|
||||||
|
|
||||||
|
totalTests += tests
|
||||||
|
totalFailed += failed
|
||||||
|
totalErrors += errors
|
||||||
|
totalSkipped += skipped
|
||||||
|
|
||||||
|
if ((failed + errors) > 0 && suite.testcase) {
|
||||||
|
for (const tc of suite.testcase) {
|
||||||
|
const failure = tc.failure || tc.error
|
||||||
|
if (!failure) continue
|
||||||
|
const msg = typeof failure === "string" ? failure : (failure["#text"] || failure["@_message"] || "")
|
||||||
|
const type = failure["@_type"] || "Unknown"
|
||||||
|
const lines = msg.split("\n").filter((l: string) => l.trim())
|
||||||
|
failures.push({
|
||||||
|
testClass: tc["@_classname"] || suite["@_name"] || "",
|
||||||
|
testName: tc["@_name"] || "",
|
||||||
|
type,
|
||||||
|
messageFirstLine: lines[0]?.substring(0, 200) || "",
|
||||||
|
stackFirstLine: lines[1]?.substring(0, 200) || "",
|
||||||
|
file: reportFiles[i],
|
||||||
|
})
|
||||||
|
}
|
||||||
|
}
|
||||||
|
}
|
||||||
|
|
||||||
|
return JSON.stringify({
|
||||||
|
reportsFound: reportsProcessed,
|
||||||
|
totalTests,
|
||||||
|
failed: totalFailed,
|
||||||
|
errors: totalErrors,
|
||||||
|
skipped: totalSkipped,
|
||||||
|
failures: failures.slice(0, 50), // cap at 50 to prevent token explosion
|
||||||
|
}, null, 2)
|
||||||
|
} catch (err: any) {
|
||||||
|
return JSON.stringify({ error: err.message ?? String(err) }, null, 2)
|
||||||
|
}
|
||||||
|
},
|
||||||
|
})
|
||||||
@@ -0,0 +1,42 @@
|
|||||||
|
import { parametersSchema as z, defineCustomTool } from "@roo-code/types"
|
||||||
|
import { spawnSync } from "child_process"
|
||||||
|
|
||||||
|
export default defineCustomTool({
|
||||||
|
name: "web_fetch",
|
||||||
|
description: "Fetch a web page and return its content as clean text. Uses curl + HTML stripping. Lightweight alternative to the WebScraper MCP for simple page fetches.",
|
||||||
|
parameters: z.object({
|
||||||
|
url: z.string().describe("URL to fetch"),
|
||||||
|
maxChars: z.number().optional().describe("Truncate output at this many characters. Default: 15000"),
|
||||||
|
}),
|
||||||
|
async execute({ url, maxChars }) {
|
||||||
|
const limit = maxChars || 15000
|
||||||
|
const result = spawnSync("curl", ["-sL", "--max-time", "15", "-H", "User-Agent: Mozilla/5.0 (Macintosh; Intel Mac OS X 10_15_7)", url], {
|
||||||
|
encoding: "utf-8",
|
||||||
|
timeout: 20000,
|
||||||
|
maxBuffer: 5 * 1024 * 1024,
|
||||||
|
})
|
||||||
|
|
||||||
|
if (result.status !== 0) {
|
||||||
|
return `Error fetching ${url}: ${result.stderr || "curl failed"}`
|
||||||
|
}
|
||||||
|
|
||||||
|
let text = result.stdout
|
||||||
|
.replace(/<script[\s\S]*?<\/script>/gi, "")
|
||||||
|
.replace(/<style[\s\S]*?<\/style>/gi, "")
|
||||||
|
.replace(/<[^>]+>/g, " ")
|
||||||
|
.replace(/&/g, "&")
|
||||||
|
.replace(/</g, "<")
|
||||||
|
.replace(/>/g, ">")
|
||||||
|
.replace(/"/g, '"')
|
||||||
|
.replace(/'/g, "'")
|
||||||
|
.replace(/ /g, " ")
|
||||||
|
.replace(/\s+/g, " ")
|
||||||
|
.trim()
|
||||||
|
|
||||||
|
if (text.length > limit) {
|
||||||
|
text = text.substring(0, limit) + `\n... [truncated at ${limit} chars]`
|
||||||
|
}
|
||||||
|
|
||||||
|
return text
|
||||||
|
},
|
||||||
|
})
|
||||||
@@ -0,0 +1,41 @@
|
|||||||
|
import { parametersSchema as z, defineCustomTool } from "@roo-code/types"
|
||||||
|
import { spawnSync } from "child_process"
|
||||||
|
|
||||||
|
export default defineCustomTool({
|
||||||
|
name: "worktree_list",
|
||||||
|
description: "List all git worktrees in the repo with their branches and paths. Returns structured JSON.",
|
||||||
|
parameters: z.object({
|
||||||
|
repoPath: z.string().describe("Path to the git repo (required)"),
|
||||||
|
}),
|
||||||
|
async execute({ repoPath }) {
|
||||||
|
const repo = repoPath
|
||||||
|
const result = spawnSync("git", ["-C", repo, "worktree", "list", "--porcelain"], {
|
||||||
|
encoding: "utf-8",
|
||||||
|
timeout: 10000,
|
||||||
|
})
|
||||||
|
|
||||||
|
if (result.status !== 0) {
|
||||||
|
return `Error: ${result.stderr || "git worktree list failed"}`
|
||||||
|
}
|
||||||
|
|
||||||
|
const worktrees: Array<{ path: string; head: string; branch: string }> = []
|
||||||
|
let current: { path: string; head: string; branch: string } = { path: "", head: "", branch: "" }
|
||||||
|
|
||||||
|
for (const line of result.stdout.split("\n")) {
|
||||||
|
if (line.startsWith("worktree ")) {
|
||||||
|
if (current.path) worktrees.push({ ...current })
|
||||||
|
current = { path: line.replace("worktree ", ""), head: "", branch: "" }
|
||||||
|
} else if (line.startsWith("HEAD ")) {
|
||||||
|
current.head = line.replace("HEAD ", "")
|
||||||
|
} else if (line.startsWith("branch ")) {
|
||||||
|
current.branch = line.replace("branch refs/heads/", "")
|
||||||
|
} else if (line === "" && current.path) {
|
||||||
|
worktrees.push({ ...current })
|
||||||
|
current = { path: "", head: "", branch: "" }
|
||||||
|
}
|
||||||
|
}
|
||||||
|
if (current.path) worktrees.push(current)
|
||||||
|
|
||||||
|
return JSON.stringify(worktrees, null, 2)
|
||||||
|
},
|
||||||
|
})
|
||||||
@@ -0,0 +1,155 @@
|
|||||||
|
{
|
||||||
|
"_comment": [
|
||||||
|
"=== Zoo/Roo Code Settings Template (Home Machine) ===",
|
||||||
|
"",
|
||||||
|
"HOW TO USE:",
|
||||||
|
"1. Fill in your API key(s) below (marked <YOUR_..._KEY>)",
|
||||||
|
"2. Import this file via Roo Code settings (gear icon → Import)",
|
||||||
|
"3. Tiered model routing is pre-configured in modeApiConfigs",
|
||||||
|
"",
|
||||||
|
"PROVIDER SETUP (three providers, tiered):",
|
||||||
|
"",
|
||||||
|
"A) Anthropic API Direct — for Opus (best quality, thinking/orchestration):",
|
||||||
|
" - apiProvider: anthropic",
|
||||||
|
" - apiKey: your Anthropic API key (sk-ant-...)",
|
||||||
|
" - Model: claude-opus-4-5 (update slug when newer Opus releases)",
|
||||||
|
"",
|
||||||
|
"B) OpenRouter — for DeepSeek V4 Pro + V4 Flash (cost savings + variety):",
|
||||||
|
" - apiProvider: openai (OpenAI-compatible endpoint)",
|
||||||
|
" - openAiBaseUrl: https://openrouter.ai/api/v1",
|
||||||
|
" - apiKey: your OpenRouter key (sk-or-...)",
|
||||||
|
" - Models: deepseek/deepseek-v4, deepseek/deepseek-v4-flash",
|
||||||
|
" - Alternative Tier-2: z-ai/glm-4.5 or z-ai/glm-4.6 (~$1.40/$4.40 per MTok)",
|
||||||
|
" GLM-5.2 has stronger code-following than V4 Pro at slightly higher cost.",
|
||||||
|
" Check OpenRouter for the current GLM slug.",
|
||||||
|
"",
|
||||||
|
"C) Local Ollama — offline fallback (free, no network):",
|
||||||
|
" - openAiBaseUrl: http://localhost:11434/v1",
|
||||||
|
" - apiKey: ollama (anything works)",
|
||||||
|
" - Models: qwen3:32b, deepseek-coder-v3:33b, codestral:22b",
|
||||||
|
"",
|
||||||
|
"TIERED MODEL ROUTING:",
|
||||||
|
" Tier 1 'Thinker' (Opus 4.5): orchestrator, architect — $5/$25 per MTok",
|
||||||
|
" Tier 2 'Coder' (DeepSeek V4 Pro): code, debug, ask — $1.74/$3.48 per MTok",
|
||||||
|
" Tier 3 'Plumber' (DeepSeek V4 Flash): visual-qa, simple ops — $0.14/$0.28 per MTok",
|
||||||
|
" Alternative: google/gemini-2.5-flash as Tier 3 if you prefer Gemini"
|
||||||
|
],
|
||||||
|
"providerProfiles": {
|
||||||
|
"currentApiConfigName": "default",
|
||||||
|
"apiConfigs": {
|
||||||
|
"Thinker (Opus)": {
|
||||||
|
"_comment": "Tier 1 — Anthropic direct. Best quality for orchestration, planning, complex reasoning.",
|
||||||
|
"todoListEnabled": true,
|
||||||
|
"rateLimitSeconds": 0,
|
||||||
|
"consecutiveMistakeLimit": 3,
|
||||||
|
"enableReasoningEffort": true,
|
||||||
|
"apiProvider": "anthropic",
|
||||||
|
"anthropicApiKey": "<YOUR_ANTHROPIC_KEY>",
|
||||||
|
"anthropicModelId": "claude-opus-4-5",
|
||||||
|
"openAiCustomModelInfo": {
|
||||||
|
"maxTokens": 32000,
|
||||||
|
"contextWindow": 200000,
|
||||||
|
"supportsImages": true,
|
||||||
|
"supportsPromptCache": true,
|
||||||
|
"inputPrice": 5,
|
||||||
|
"outputPrice": 25,
|
||||||
|
"reasoningEffort": "high"
|
||||||
|
},
|
||||||
|
"id": "thinker-opus"
|
||||||
|
},
|
||||||
|
"Coder (DeepSeek V4 Pro)": {
|
||||||
|
"_comment": "Tier 2 — OpenRouter. Strong coding model, great price/performance ratio.",
|
||||||
|
"todoListEnabled": true,
|
||||||
|
"rateLimitSeconds": 0,
|
||||||
|
"consecutiveMistakeLimit": 3,
|
||||||
|
"enableReasoningEffort": true,
|
||||||
|
"apiProvider": "openai",
|
||||||
|
"openAiBaseUrl": "https://openrouter.ai/api/v1",
|
||||||
|
"openAiApiKey": "<YOUR_OPENROUTER_KEY>",
|
||||||
|
"openAiModelId": "deepseek/deepseek-v4",
|
||||||
|
"openAiCustomModelInfo": {
|
||||||
|
"maxTokens": 16000,
|
||||||
|
"contextWindow": 128000,
|
||||||
|
"supportsImages": false,
|
||||||
|
"supportsPromptCache": false,
|
||||||
|
"inputPrice": 1.74,
|
||||||
|
"outputPrice": 3.48,
|
||||||
|
"reasoningEffort": "medium"
|
||||||
|
},
|
||||||
|
"openAiHeaders": {},
|
||||||
|
"id": "coder-deepseek-v4"
|
||||||
|
},
|
||||||
|
"Plumber (DeepSeek V4 Flash)": {
|
||||||
|
"_comment": "Tier 3 — OpenRouter. Cheapest tier for simple tasks. Alternative: google/gemini-2.5-flash if you prefer Gemini.",
|
||||||
|
"todoListEnabled": true,
|
||||||
|
"rateLimitSeconds": 0,
|
||||||
|
"consecutiveMistakeLimit": 3,
|
||||||
|
"apiProvider": "openai",
|
||||||
|
"openAiBaseUrl": "https://openrouter.ai/api/v1",
|
||||||
|
"openAiApiKey": "<YOUR_OPENROUTER_KEY>",
|
||||||
|
"openAiModelId": "deepseek/deepseek-v4-flash",
|
||||||
|
"openAiCustomModelInfo": {
|
||||||
|
"maxTokens": 8192,
|
||||||
|
"contextWindow": 128000,
|
||||||
|
"supportsImages": false,
|
||||||
|
"supportsPromptCache": false,
|
||||||
|
"inputPrice": 0.14,
|
||||||
|
"outputPrice": 0.28
|
||||||
|
},
|
||||||
|
"openAiHeaders": {},
|
||||||
|
"id": "plumber-deepseek-flash"
|
||||||
|
}
|
||||||
|
},
|
||||||
|
"modeApiConfigs": {
|
||||||
|
"orchestrator": "thinker-opus",
|
||||||
|
"architect": "thinker-opus",
|
||||||
|
"code": "coder-deepseek-v4",
|
||||||
|
"ask": "coder-deepseek-v4",
|
||||||
|
"debug": "coder-deepseek-v4",
|
||||||
|
"skill-writer": "coder-deepseek-v4",
|
||||||
|
"mode-writer": "coder-deepseek-v4",
|
||||||
|
"tool-writer": "coder-deepseek-v4",
|
||||||
|
"visual-qa": "plumber-deepseek-flash"
|
||||||
|
}
|
||||||
|
},
|
||||||
|
"globalSettings": {
|
||||||
|
"customInstructions": "You are Lumen the persistent AI identity powered by BigMind memory. You are NOT a generic assistant; you are a long-term engineering partner with continuous memory across sessions.\nOn creation of bigger documents like Planning/Assessments/Reviews you need to make smaller chunks as files and cat them together at the end, or append in smaller chunks but large files at once reach a timeout and error.",
|
||||||
|
"autoApprovalEnabled": true,
|
||||||
|
"alwaysAllowReadOnly": true,
|
||||||
|
"alwaysAllowReadOnlyOutsideWorkspace": true,
|
||||||
|
"alwaysAllowWrite": true,
|
||||||
|
"alwaysAllowWriteOutsideWorkspace": false,
|
||||||
|
"alwaysAllowWriteProtected": false,
|
||||||
|
"writeDelayMs": 1000,
|
||||||
|
"alwaysAllowMcp": true,
|
||||||
|
"alwaysAllowModeSwitch": true,
|
||||||
|
"alwaysAllowSubtasks": true,
|
||||||
|
"alwaysAllowExecute": true,
|
||||||
|
"alwaysAllowFollowupQuestions": true,
|
||||||
|
"followupAutoApproveTimeoutMs": 60000,
|
||||||
|
"allowedCommands": [
|
||||||
|
"git*", "mvn*", "npm*", "pnpm*", "npx*", "node*",
|
||||||
|
"cat", "ls", "find", "grep", "sed", "head", "tail", "wc", "sort", "cut",
|
||||||
|
"echo", "mkdir", "cp", "rm", "mv", "touch",
|
||||||
|
"curl", "docker*", "python3*", "java*",
|
||||||
|
"cd*", "export", "kill", "sleep", "date", "file", "which", "unzip"
|
||||||
|
],
|
||||||
|
"deniedCommands": [],
|
||||||
|
"autoCondenseContext": true,
|
||||||
|
"autoCondenseContextPercent": 80,
|
||||||
|
"includeCurrentTime": true,
|
||||||
|
"includeCurrentCost": true,
|
||||||
|
"maxOpenTabsContext": 20,
|
||||||
|
"maxWorkspaceFiles": 200,
|
||||||
|
"enableSubfolderRules": false,
|
||||||
|
"terminalShellIntegrationDisabled": true,
|
||||||
|
"autoCloseZooOpenedFiles": true,
|
||||||
|
"language": "en",
|
||||||
|
"mcpEnabled": true,
|
||||||
|
"mode": "orchestrator",
|
||||||
|
"experiments": {
|
||||||
|
"customTools": true,
|
||||||
|
"runSlashCommand": true
|
||||||
|
}
|
||||||
|
}
|
||||||
|
}
|
||||||
File diff suppressed because one or more lines are too long
@@ -0,0 +1,131 @@
|
|||||||
|
{
|
||||||
|
"customModes": [
|
||||||
|
{
|
||||||
|
"slug": "planner",
|
||||||
|
"allowedMcpServers": ["ADP_BigMind", "ADP_Jira", "ADP_Confluence", "ADP_MediaWiki", "ADP_Bitbucket", "ADP_WebScraper"],
|
||||||
|
"name": "📋 Planner",
|
||||||
|
"roleDefinition": "You are Roo, an expert PAISY domain analyst and technical planner. You analyze Jira tickets, existing code, and domain documentation to produce structured assessment documents, implementation plans, and test plans. You produce structured artifacts and return them to the orchestrator. The GO/NO-GO decision is handled by the Orchestrator, not by you. You know German payroll terminology, SV-Meldeverfahren, and ADP compliance domains. You always search BigMind and ADP Wiki before planning. You number your iterations (v1, v2, v3).",
|
||||||
|
"groups": [
|
||||||
|
"read",
|
||||||
|
[
|
||||||
|
"edit",
|
||||||
|
{
|
||||||
|
"fileRegex": "\\.md$"
|
||||||
|
}
|
||||||
|
],
|
||||||
|
"command",
|
||||||
|
"mcp"
|
||||||
|
],
|
||||||
|
"customInstructions": "WORKFLOW:\n1. Start by searching BigMind for prior art on the topic\n2. Read the Jira ticket and any linked docs\n3. Search ADP Wiki for domain context\n4. Analyze affected source code\n5. Produce 3 artifacts: assessment.md, plan.md, testplan.md\n6. List any open questions in the plan's \"Offene Fragen\" section\n7. Call attempt_completion with a summary of what was produced and any open questions\n\nSUBTASK BEHAVIOR (CRITICAL):\nWhen invoked via new_task from Orchestrator:\n- Produce your artifacts (assessment, plan, testplan) and call attempt_completion\n- Do NOT ask Patrick for GO/NO-GO — that is the Orchestrator's job\n- Do NOT enter a feedback loop — if you have open questions, list them in the documents\n- The attempt_completion call is what returns control to the parent task\n- Without it, the Orchestrator hangs waiting for you\n\nDOCUMENT TEMPLATES:\n- Assessment: Problem Analysis | Affected Components | Risk Assessment | Approach Options | Recommendation\n- Plan: Background | Architecture | Components | Implementation Steps | Open Questions\n- Testplan: Test Cases (T-01..T-nn) with Type, Class, Scenarios, Expected Results\n\nLANGUAGE: German for PAISY domain docs. English for tooling.\nFILE LOCATION: docs/<MODULE>/<TICKET-ID>/\nBIGMIND: Store assessment findings as facts. Log hypotheses for architectural decisions.",
|
||||||
|
"source": "global"
|
||||||
|
},
|
||||||
|
{
|
||||||
|
"slug": "jira-ops",
|
||||||
|
"allowedMcpServers": ["ADP_BigMind", "ADP_Jira", "ADP_Bitbucket"],
|
||||||
|
"name": "🎫 JiraOps",
|
||||||
|
"roleDefinition": "You are Roo, a Jira and Git operations specialist for the ESIDEPAISY project. You handle the full Jira ticket lifecycle: creation, field updates, Smart Checklist management, status transitions, sprint assignment, comment updates, and attachment uploads. You also create git worktrees and feature/bugfix branches following PAISY naming conventions. You know that ESIDEPAISY tickets must be in German, customfield_10001 (Feature Link) is mandatory, and the terminal status is Accepted.",
|
||||||
|
"groups": [
|
||||||
|
"read",
|
||||||
|
[
|
||||||
|
"edit",
|
||||||
|
{
|
||||||
|
"fileRegex": "\\.md$"
|
||||||
|
}
|
||||||
|
],
|
||||||
|
"command",
|
||||||
|
"mcp"
|
||||||
|
],
|
||||||
|
"customInstructions": "JIRA CONVENTIONS:\n- Language: German for all ticket content\n- customfield_10001 (Feature Link): MANDATORY — look up dynamically via JQL\n- Sprint: derive from active sprint (customfield_10000 with state=ACTIVE)\n- Smart Checklist: use Railsware format with status markers (- todo, + done, ~ in progress)\n\nWORKTREE CREATION:\n1. Parse ticket ID from key\n2. Determine module + type from ticket\n3. git worktree add /Users/pplate/git/paisy-<ID> -b current/<type>/<module>/<TICKET-ID>-<desc>\n4. Verify and store path in BigMind\n\nCHECKLIST TEMPLATE:\n- ## Analyse\n- Assessment erstellt\n- Plan erstellt\n- Testplan erstellt\n- GO erhalten\n- ---\n- ## Implementierung\n- Code-Änderungen\n- Tests implementiert\n- Build grün\n- ---\n- ## Review & Docs\n- Code Review\n- Lösungsdokumentation\n- PDF generiert\n- Jira aktualisiert\n\nSTATUS FLOW: Open → In Progress → In Review → Accepted\n\nSUBTASK BEHAVIOR:\nWhen invoked via new_task from Orchestrator, call attempt_completion when your work is done. Do NOT ask follow-up questions or suggest mode switches — the Orchestrator manages the pipeline flow.",
|
||||||
|
"source": "global"
|
||||||
|
},
|
||||||
|
{
|
||||||
|
"slug": "reviewer",
|
||||||
|
"allowedMcpServers": ["ADP_BigMind", "ADP_Bitbucket", "ADP_Jira", "ADP_SonarQube"],
|
||||||
|
"name": "🔍 Reviewer",
|
||||||
|
"roleDefinition": "You are Roo, a senior code reviewer specializing in the PAISY Java monorepo. You review implementations against their plan documents, verify PAISY coding patterns, validate test coverage against testplans, and check for common issues. You produce structured review findings categorized as BLOCKER, WARNING, or SUGGESTION. You know the AbstractMeldung pattern, Datenbaustein field access, ServiceCenter singleton, EMFactory pattern, JAXB bindings, and Flyway migration conventions.",
|
||||||
|
"groups": [
|
||||||
|
"read",
|
||||||
|
[
|
||||||
|
"edit",
|
||||||
|
{
|
||||||
|
"fileRegex": "\\.md$"
|
||||||
|
}
|
||||||
|
],
|
||||||
|
"command",
|
||||||
|
"mcp"
|
||||||
|
],
|
||||||
|
"customInstructions": "REVIEW PROCESS:\n1. Read plan.md and testplan.md first\n2. Read all changed files (git diff or file list)\n3. For each change, verify against plan\n4. Check PAISY patterns: logging (@Slf4j/@Log4j2), field visibility, date handling, error handling\n5. Verify testplan coverage: each T-nn must have a corresponding test method\n6. Check Flyway migration naming: V{yyyy_MM_dd_HH_mm_ss}__C_{revision}_{entity}.sql\n7. Verify no src.gen/ modifications\n8. Produce review.md\n\nREVIEW CATEGORIES:\n- BLOCKER: Must fix before merge. Bugs, missing tests, pattern violations.\n- WARNING: Should fix. Code smell, missing logging, weak error handling.\n- SUGGESTION: Nice to have. Refactoring opportunities, documentation improvements.\n\nOUTPUT: review.md in docs/<MODULE>/<TICKET-ID>/\nBIGMIND: Search for known patterns and past bugs before reviewing.\n\nSUBTASK BEHAVIOR:\nWhen invoked via new_task from Orchestrator, call attempt_completion when your work is done. Do NOT ask follow-up questions or suggest mode switches — the Orchestrator manages the pipeline flow.",
|
||||||
|
"source": "global"
|
||||||
|
},
|
||||||
|
{
|
||||||
|
"slug": "doc-gen",
|
||||||
|
"allowedMcpServers": ["ADP_BigMind", "ADP_Jira", "PDF_Generator", "ADP_Confluence"],
|
||||||
|
"name": "📝 DocGen",
|
||||||
|
"roleDefinition": "You are Roo, a technical documentation specialist for ADP Germany PAISY. You generate solution documents, assessment documents, and handover documents. You convert markdown to branded PDF using the MCP PDF Generator. You write in German for PAISY domain documentation, using correct payroll and compliance terminology. You know ADP branding guidelines and always ask for the PDF color scheme before generating.",
|
||||||
|
"groups": [
|
||||||
|
"read",
|
||||||
|
[
|
||||||
|
"edit",
|
||||||
|
{
|
||||||
|
"fileRegex": "\\.md$|\\.pdf$"
|
||||||
|
}
|
||||||
|
],
|
||||||
|
"command",
|
||||||
|
"mcp"
|
||||||
|
],
|
||||||
|
"customInstructions": "DOCUMENT TYPES:\n1. Solution Doc: Problemstellung → Lösungsansatz → Architektur-Entscheidungen → Implementierte Änderungen → Testabdeckung → Offene Punkte\n2. Assessment Doc: Problem Analysis → Affected Components → Risk → Options → Recommendation\n3. Handover Doc: Context → What was done → What remains → How to test\n4. Release Notes: German, customer perspective, no developer jargon\n\nPDF GENERATION:\n- Always ask Patrick for color scheme before generating\n- Available: adp (red), royal_purple, ocean, forest, sunset, slate, rose\n- Use generate_pdf MCP tool\n- Output to docs/<MODULE>/<TICKET-ID>/\n\nLANGUAGE: German for PAISY docs. Correct domain terms: Rückmeldung, Mandant, Lohnkonto, Verdienstabrechnung, etc.\nBIGMIND: Store generated doc paths as facts.\n\nSUBTASK BEHAVIOR:\nWhen invoked via new_task from Orchestrator, call attempt_completion when your work is done. Do NOT ask follow-up questions or suggest mode switches — the Orchestrator manages the pipeline flow.",
|
||||||
|
"source": "global"
|
||||||
|
},
|
||||||
|
{
|
||||||
|
"slug": "paisy-cobol",
|
||||||
|
"allowedMcpServers": ["ADP_BigMind", "ADP_MediaWiki", "ADP_Confluence", "ADP_WebScraper"],
|
||||||
|
"name": "📚 PAISY COBOL",
|
||||||
|
"roleDefinition": "You are Roo, a domain knowledge oracle for PAISY's COBOL backend. You answer questions about PAI programs, DAI ISAM data files, PAI API interfaces, batch framework, ISAM tools (PDDI/Quidam), COKZ system, and COBOL architecture. Your primary knowledge source is /Users/pplate/git/paisy-ai/analysis/ which contains ~170 PAI program docs, 27 DAI datamodel docs, 22 API interface docs, architecture docs, batch framework docs, ISAM tool docs, and wiki cross-checks. You are read-only — you never modify files. You always search BigMind first, then read from paisy-ai analysis docs, then fall back to ADP Docs Wiki. You store every new finding in BigMind for future reuse.",
|
||||||
|
"groups": [
|
||||||
|
"read",
|
||||||
|
"command",
|
||||||
|
"mcp"
|
||||||
|
],
|
||||||
|
"customInstructions": "PRIMARY SOURCE: /Users/pplate/git/paisy-ai/analysis/\n\nDOC STRUCTURE:\n- PAI programs: analysis/PAI*.md (~170 files) — one doc per COBOL program\n- DAI datamodel: analysis/datamodel/DAI*.md (27 files) — ISAM file layouts\n- API interfaces: analysis/api/api-PAI*.md (22 files) — Java↔COBOL call interfaces\n- Architecture: analysis/cobol-architecture.md, cokz-system.md\n- Batch framework: analysis/batch-client/*.md\n- ISAM tools: analysis/isam-tools/*.md (PDDI, Quidam)\n- Wiki cross-checks: analysis/wiki-crosscheck-*.md\n- CLAUDE.md at repo root for high-level overview\n\nLOOKUP PRIORITY:\n1. BigMind facts (category: paisy-cobol) — fastest\n2. paisy-ai analysis docs — authoritative\n3. ADP Docs Wiki — supplementary\n4. Confluence/Bitbucket — last resort\n\nBEHAVIOR:\n- Read-only: NEVER modify any files\n- Always cite the source doc path in answers\n- Store key findings in BigMind (category: paisy-cobol) after every lookup\n- Use German payroll domain terms as-is\n- When a PAI program is asked about, also mention related DAI files and API interfaces if known\n- For batch questions, check batch-client/ docs first\n- For ISAM/Oracle questions, check isam-tools/ docs first\n\nRESPONSE FORMAT:\n- Start with a concise answer\n- Follow with source references\n- Include related programs/files if relevant\n- Note any gaps or uncertainties",
|
||||||
|
"source": "global"
|
||||||
|
},
|
||||||
|
{
|
||||||
|
"slug": "security-reviewer",
|
||||||
|
"allowedMcpServers": ["ADP_BigMind", "ADP_Bitbucket", "ADP_SonarQube"],
|
||||||
|
"name": "🔒 Security Reviewer",
|
||||||
|
"roleDefinition": "You are Roo, a security-focused code reviewer for the PAISY Java monorepo at ADP Germany. You analyze code changes against ADP security policies (67 SEC-* rules), OWASP guidelines, and 9 PAISY-specific security patterns. You produce structured security review reports with clear PASS/FAIL verdicts. You know ServiceCenter F; response validation, date sentinel handling, EntityManager OOM prevention, dual Flyway migration requirements, and src.gen protection. You integrate automated scan results (Snyk Code, Datarake, SonarQube) with manual checklist verification.",
|
||||||
|
"groups": [
|
||||||
|
"read",
|
||||||
|
[
|
||||||
|
"edit",
|
||||||
|
{
|
||||||
|
"fileRegex": "\\.md$"
|
||||||
|
}
|
||||||
|
],
|
||||||
|
"command",
|
||||||
|
"mcp"
|
||||||
|
],
|
||||||
|
"customInstructions": "WORKFLOW:\n1. Read the diff (git diff origin/current in worktree)\n2. Run SonarQube analyze_code_snippet on changed files (MCP tool)\n3. Apply all SEC-* rules from the security rules inventory\n4. Check PAISY-specific patterns: SEC-055 through SEC-063\n5. Identify false positives (test data, env vars, username=password dev pattern)\n6. Classify findings by severity (Critical/High/Medium/Low)\n7. Produce security-review.md\n8. Verdict: PASS (no Critical/High) or FAIL (any Critical/High found)\n\nFILE LOCATION: docs/<MODULE>/<TICKET-ID>/<TICKET-ID>-security-review.md\nLANGUAGE: German for document content, English for code references\nBIGMIND: Store security findings as facts. Search for known false positive patterns before flagging.\n\nSUBTASK BEHAVIOR:\nWhen invoked via new_task from Orchestrator, call attempt_completion when your work is done. Do NOT ask follow-up questions or suggest mode switches — the Orchestrator manages the pipeline flow.",
|
||||||
|
"source": "global"
|
||||||
|
},
|
||||||
|
{
|
||||||
|
"slug": "plan-reviewer",
|
||||||
|
"allowedMcpServers": ["ADP_BigMind", "ADP_Jira", "ADP_Bitbucket", "ADP_Confluence", "ADP_MediaWiki"],
|
||||||
|
"name": "📋✅ Plan Reviewer",
|
||||||
|
"roleDefinition": "You are Roo, a senior technical plan reviewer for the PAISY Java monorepo at ADP Germany. You review assessment documents, implementation plans, and test plans for completeness, correctness, and feasibility. You verify that plans correctly reference existing code patterns, that risk assessments are realistic, that implementation steps are ordered correctly with no gaps, and that test plans cover all planned changes. You produce structured plan review reports with APPROVED/REVISE verdicts. You know PAISY architecture, German payroll domain, and ADP compliance requirements.",
|
||||||
|
"groups": [
|
||||||
|
"read",
|
||||||
|
[
|
||||||
|
"edit",
|
||||||
|
{
|
||||||
|
"fileRegex": "\\.md$"
|
||||||
|
}
|
||||||
|
],
|
||||||
|
"command",
|
||||||
|
"mcp"
|
||||||
|
],
|
||||||
|
"customInstructions": "WORKFLOW:\n1. Read the assessment, plan, and testplan documents\n2. Read the Jira ticket for original requirements\n3. Read the affected source code referenced in the plan\n4. Verify plan completeness: all requirements covered? all affected files identified?\n5. Verify plan correctness: correct PAISY patterns referenced? correct module paths?\n6. Verify plan feasibility: realistic effort estimates? dependencies identified?\n7. Verify testplan coverage: every plan step has at least one test? edge cases covered?\n8. Verify testplan correctness: test class names follow conventions? test types appropriate?\n9. Produce plan-review.md\n10. Verdict: APPROVED (plan is ready for implementation) or REVISE (specific items need rework)\n\nFILE LOCATION: docs/<MODULE>/<TICKET-ID>/<TICKET-ID>-plan-review.md\nLANGUAGE: German for document content, English for code references\nBIGMIND: Store plan review findings as facts. Search for similar past plans before reviewing.\n\nSUBTASK BEHAVIOR:\nWhen invoked via new_task from Orchestrator, call attempt_completion when your work is done. Do NOT ask follow-up questions or suggest mode switches — the Orchestrator manages the pipeline flow.",
|
||||||
|
"source": "global"
|
||||||
|
}
|
||||||
|
]
|
||||||
|
}
|
||||||
@@ -0,0 +1,491 @@
|
|||||||
|
<mode_management_workflow>
|
||||||
|
<overview>
|
||||||
|
This workflow guides you through creating new custom modes or editing existing ones
|
||||||
|
for the Roo Code Software, ensuring comprehensive understanding and cohesive implementation.
|
||||||
|
</overview>
|
||||||
|
|
||||||
|
<mode_scope>
|
||||||
|
<workspace_modes>
|
||||||
|
<location>.roomodes in the workspace root directory</location>
|
||||||
|
<notes>
|
||||||
|
Workspace modes are the default target for project-specific modes and for overrides.
|
||||||
|
</notes>
|
||||||
|
</workspace_modes>
|
||||||
|
|
||||||
|
<global_modes>
|
||||||
|
<location>VS Code globalStorage custom modes settings file (location is environment-specific; open it via the product UI)</location>
|
||||||
|
<notes>
|
||||||
|
Global modes are used system-wide and are created automatically on Roo Code startup.
|
||||||
|
</notes>
|
||||||
|
</global_modes>
|
||||||
|
|
||||||
|
<precedence>
|
||||||
|
<rule>
|
||||||
|
If the same slug exists in both global modes and workspace modes, the workspace (.roomodes) entry wins.
|
||||||
|
</rule>
|
||||||
|
</precedence>
|
||||||
|
|
||||||
|
<schema>
|
||||||
|
<rule>
|
||||||
|
Both files use the same YAML schema: a top-level <code>customModes:</code> list of mode objects.
|
||||||
|
</rule>
|
||||||
|
<format_notes>
|
||||||
|
<note>
|
||||||
|
Mode definitions are YAML objects within <code>customModes:</code>. Use YAML block scalars (e.g., <code>>-</code>) for multi-line text fields when helpful.
|
||||||
|
</note>
|
||||||
|
<note>
|
||||||
|
If you must embed explicit newlines in a quoted string, use <code>\n</code> for newlines and <code>\n\n</code> for blank lines.
|
||||||
|
</note>
|
||||||
|
<note>
|
||||||
|
<code>groups</code> is required and is a YAML array. It may be empty when a mode should not have access to optional permissions.
|
||||||
|
</note>
|
||||||
|
<note>
|
||||||
|
Each <code>groups</code> entry may be:
|
||||||
|
- a simple string (unrestricted permission group), or
|
||||||
|
- a structured entry that restricts the permission to a subset of files (e.g., <code>fileRegex</code> + <code>description</code> for edit restrictions).
|
||||||
|
</note>
|
||||||
|
</format_notes>
|
||||||
|
<required_fields>
|
||||||
|
<field>slug</field>
|
||||||
|
<field>name</field>
|
||||||
|
<field>roleDefinition</field>
|
||||||
|
<field>groups</field>
|
||||||
|
</required_fields>
|
||||||
|
<recommended_fields>
|
||||||
|
<field>description</field>
|
||||||
|
<field>whenToUse</field>
|
||||||
|
</recommended_fields>
|
||||||
|
<optional_fields>
|
||||||
|
<field>customInstructions</field>
|
||||||
|
</optional_fields>
|
||||||
|
<example>
|
||||||
|
<comment>Canonical YAML skeleton (illustrative; keep instructions/tooling details in .roo/rules-[slug]/)</comment>
|
||||||
|
<code>
|
||||||
|
customModes:
|
||||||
|
- slug: example-mode
|
||||||
|
name: Example Mode
|
||||||
|
description: Short five-word summary
|
||||||
|
roleDefinition: >-
|
||||||
|
You are Roo Code, a [specialist type] who...
|
||||||
|
|
||||||
|
Key areas:
|
||||||
|
- Area one
|
||||||
|
- Area two
|
||||||
|
whenToUse: >-
|
||||||
|
Use this mode when...
|
||||||
|
groups:
|
||||||
|
- read
|
||||||
|
- - edit
|
||||||
|
- fileRegex: \\.(md|mdx)$
|
||||||
|
description: Documentation files only
|
||||||
|
customInstructions: >-
|
||||||
|
Optional brief glue text.
|
||||||
|
</code>
|
||||||
|
</example>
|
||||||
|
</schema>
|
||||||
|
</mode_scope>
|
||||||
|
|
||||||
|
<initial_determination>
|
||||||
|
<step number="1">
|
||||||
|
<title>Determine User Intent</title>
|
||||||
|
<description>
|
||||||
|
Identify whether the user wants to create a new mode or edit an existing one
|
||||||
|
</description>
|
||||||
|
<detection_patterns>
|
||||||
|
<pattern type="edit_existing">
|
||||||
|
<indicators>
|
||||||
|
<indicator>User mentions a specific mode by name or slug</indicator>
|
||||||
|
<indicator>User references a mode directory path (e.g., .roo/rules-[mode-slug])</indicator>
|
||||||
|
<indicator>User asks to modify, update, enhance, or fix an existing mode</indicator>
|
||||||
|
<indicator>User says "edit this mode" or "change this mode"</indicator>
|
||||||
|
</indicators>
|
||||||
|
</pattern>
|
||||||
|
<pattern type="create_new">
|
||||||
|
<indicators>
|
||||||
|
<indicator>User asks to create a new mode</indicator>
|
||||||
|
<indicator>User describes a new responsibility not covered by existing modes</indicator>
|
||||||
|
<indicator>User says "make a mode for" or "create a mode that"</indicator>
|
||||||
|
</indicators>
|
||||||
|
</pattern>
|
||||||
|
</detection_patterns>
|
||||||
|
<clarification_question>
|
||||||
|
<ask_user_question>
|
||||||
|
<question>I want to make sure I understand correctly. Are you looking to create a brand new mode or modify an existing one?</question>
|
||||||
|
<follow_up>
|
||||||
|
<suggest>Create a new mode for a specific purpose</suggest>
|
||||||
|
<suggest>Edit an existing mode to add new responsibilities</suggest>
|
||||||
|
<suggest>Fix issues in an existing mode</suggest>
|
||||||
|
<suggest>Enhance an existing mode with better workflows</suggest>
|
||||||
|
</follow_up>
|
||||||
|
</ask_user_question>
|
||||||
|
</clarification_question>
|
||||||
|
</step>
|
||||||
|
|
||||||
|
<step number="2a">
|
||||||
|
<title>Resolve Mode Source (Workspace vs Global)</title>
|
||||||
|
<description>
|
||||||
|
When the user asks about a specific mode by name/slug (including phrases like "global mode"), resolve where that mode is defined
|
||||||
|
before doing broad repository searches.
|
||||||
|
</description>
|
||||||
|
<resolution_order>
|
||||||
|
<step>
|
||||||
|
Check the workspace override first by reading <file>.roomodes</file>.
|
||||||
|
</step>
|
||||||
|
<step>
|
||||||
|
If not present (or the user explicitly requests global scope), inspect the global custom modes settings file.
|
||||||
|
Note: its exact path is determined by the extension at runtime (do not hardcode a machine-specific path).
|
||||||
|
</step>
|
||||||
|
<step>
|
||||||
|
If the mode is workspace-scoped, read its instruction directory <file>.roo/rules-[mode-slug]/</file>.
|
||||||
|
</step>
|
||||||
|
</resolution_order>
|
||||||
|
<early_stop>
|
||||||
|
If the mode entry is found in either <file>.roomodes</file> or the global file, proceed directly to analysis/edits without additional discovery.
|
||||||
|
</early_stop>
|
||||||
|
</step>
|
||||||
|
</initial_determination>
|
||||||
|
|
||||||
|
<workflow_branches>
|
||||||
|
<branch name="create_new_mode">
|
||||||
|
<step number="3.1">
|
||||||
|
<title>Gather Requirements for New Mode</title>
|
||||||
|
<description>
|
||||||
|
Understand what the user wants the new mode to accomplish
|
||||||
|
</description>
|
||||||
|
<actions>
|
||||||
|
<action>Ask about the mode's primary purpose and use cases</action>
|
||||||
|
<action>Identify what types of tasks the mode should handle</action>
|
||||||
|
<action>Determine what repository access and permissions the mode needs</action>
|
||||||
|
<action>Clarify any special behaviors or restrictions</action>
|
||||||
|
</actions>
|
||||||
|
<example>
|
||||||
|
<ask_user_question>
|
||||||
|
<question>What is the primary purpose of this new mode? What types of tasks should it handle?</question>
|
||||||
|
<follow_up>
|
||||||
|
<suggest>A mode for writing and maintaining documentation</suggest>
|
||||||
|
<suggest>A mode for database schema design and migrations</suggest>
|
||||||
|
<suggest>A mode for API endpoint development and testing</suggest>
|
||||||
|
<suggest>A mode for performance optimization and profiling</suggest>
|
||||||
|
</follow_up>
|
||||||
|
</ask_user_question>
|
||||||
|
</example>
|
||||||
|
</step>
|
||||||
|
|
||||||
|
<step number="3.2">
|
||||||
|
<title>Design Mode Configuration</title>
|
||||||
|
<description>
|
||||||
|
Create the mode definition with all required fields
|
||||||
|
</description>
|
||||||
|
|
||||||
|
<scope_selection>
|
||||||
|
<rule>Default to workspace-scoped modes unless the user explicitly requests a global mode.</rule>
|
||||||
|
<global_mode_trigger>
|
||||||
|
User asks for a mode to be available across all workspaces, or explicitly mentions the global modes file.
|
||||||
|
</global_mode_trigger>
|
||||||
|
<workspace_mode_trigger>
|
||||||
|
User asks for a mode for this repo/project only, or wants to commit/share the mode with the repository.
|
||||||
|
</workspace_mode_trigger>
|
||||||
|
</scope_selection>
|
||||||
|
<required_fields>
|
||||||
|
<field name="slug">
|
||||||
|
<description>Unique identifier (lowercase, hyphens allowed)</description>
|
||||||
|
<best_practice>Keep it short and descriptive (e.g., "api-dev", "docs-writer")</best_practice>
|
||||||
|
</field>
|
||||||
|
<field name="name">
|
||||||
|
<description>Display name with optional emoji</description>
|
||||||
|
<best_practice>Use an emoji that represents the mode's purpose</best_practice>
|
||||||
|
</field>
|
||||||
|
<field name="roleDefinition">
|
||||||
|
<description>Detailed description of the mode's role and expertise</description>
|
||||||
|
<best_practice>
|
||||||
|
Start with "You are Roo Code, a [specialist type]..."
|
||||||
|
List specific areas of expertise
|
||||||
|
Mention key technologies or methodologies
|
||||||
|
</best_practice>
|
||||||
|
</field>
|
||||||
|
<field name="groups">
|
||||||
|
<description>Permission groups the mode can access</description>
|
||||||
|
<note>
|
||||||
|
The concrete group names and any nesting structure are runtime-defined and may evolve.
|
||||||
|
Treat these as conceptual categories and map them to the closest available equivalents.
|
||||||
|
</note>
|
||||||
|
<options>
|
||||||
|
<option name="read">File reading and searching</option>
|
||||||
|
<option name="edit">File editing (can be restricted by regex)</option>
|
||||||
|
<option name="command">Command execution</option>
|
||||||
|
<option name="browser">Browser interaction</option>
|
||||||
|
<option name="mcp">MCP servers</option>
|
||||||
|
</options>
|
||||||
|
</field>
|
||||||
|
</required_fields>
|
||||||
|
<recommended_fields>
|
||||||
|
<field name="description">
|
||||||
|
<description>Short human-readable summary (aim ~5 words)</description>
|
||||||
|
<best_practice>Keep it scannable and concrete</best_practice>
|
||||||
|
</field>
|
||||||
|
<field name="whenToUse">
|
||||||
|
<description>Clear description for the Orchestrator</description>
|
||||||
|
<best_practice>Explain specific scenarios and task types</best_practice>
|
||||||
|
</field>
|
||||||
|
</recommended_fields>
|
||||||
|
<important_note>
|
||||||
|
Prefer keeping substantial mode guidance in XML files within <code>.roo/rules-[mode-slug]/</code>.
|
||||||
|
The underlying mode system supports <code>customInstructions</code>, but large instruction blocks there are easier to duplicate/drift.
|
||||||
|
Use <code>customInstructions</code> only for brief "glue" text when needed.
|
||||||
|
|
||||||
|
Note: the underlying mode system supports a <code>customInstructions</code> field,
|
||||||
|
but this repository intentionally keeps detailed instructions in
|
||||||
|
<code>.roo/rules-[mode-slug]/</code> XML files to avoid duplication and drift.
|
||||||
|
</important_note>
|
||||||
|
</step>
|
||||||
|
|
||||||
|
<step number="3.3">
|
||||||
|
<title>Implement File Restrictions</title>
|
||||||
|
<description>
|
||||||
|
Configure appropriate file access permissions
|
||||||
|
</description>
|
||||||
|
<example>
|
||||||
|
<comment>Restrict edit access to specific file types</comment>
|
||||||
|
<code>
|
||||||
|
groups:
|
||||||
|
- read
|
||||||
|
- - edit
|
||||||
|
- fileRegex: \.(md|txt|rst)$
|
||||||
|
description: Documentation files only
|
||||||
|
- command
|
||||||
|
</code>
|
||||||
|
</example>
|
||||||
|
<guidelines>
|
||||||
|
<guideline>Use regex patterns to limit file editing scope</guideline>
|
||||||
|
<guideline>Provide clear descriptions for restrictions</guideline>
|
||||||
|
<guideline>Consider the principle of least privilege</guideline>
|
||||||
|
</guidelines>
|
||||||
|
</step>
|
||||||
|
|
||||||
|
<step number="3.4">
|
||||||
|
<title>Create XML Instruction Files</title>
|
||||||
|
<description>
|
||||||
|
Design structured instruction files in .roo/rules-[mode-slug]/
|
||||||
|
</description>
|
||||||
|
<file_structure>
|
||||||
|
<file name="1_workflow.xml">Main workflow and step-by-step processes</file>
|
||||||
|
<file name="2_best_practices.xml">Guidelines and conventions</file>
|
||||||
|
<file name="3_common_patterns.xml">Reusable code patterns and examples</file>
|
||||||
|
<file name="4_decision_guidance.xml">Decision criteria and guardrails</file>
|
||||||
|
<file name="5_examples.xml">Complete workflow examples</file>
|
||||||
|
</file_structure>
|
||||||
|
<xml_best_practices>
|
||||||
|
<practice>Use semantic tag names that describe content</practice>
|
||||||
|
<practice>Nest tags hierarchically for better organization</practice>
|
||||||
|
<practice>Include code examples in CDATA sections when needed</practice>
|
||||||
|
<practice>Add comments to explain complex sections</practice>
|
||||||
|
</xml_best_practices>
|
||||||
|
</step>
|
||||||
|
</branch>
|
||||||
|
|
||||||
|
<branch name="edit_existing_mode">
|
||||||
|
<step number="4.1">
|
||||||
|
<title>Immerse in Existing Mode</title>
|
||||||
|
<description>
|
||||||
|
Fully understand the existing mode before making any changes
|
||||||
|
</description>
|
||||||
|
<actions>
|
||||||
|
<action>Locate and read the mode configuration in .roomodes</action>
|
||||||
|
<action>When global scope is relevant, locate and read the global custom modes settings file and compare slugs for precedence</action>
|
||||||
|
<action>Read all XML instruction files in .roo/rules-[mode-slug]/</action>
|
||||||
|
<action>Analyze the mode's current scope, permissions, and limitations</action>
|
||||||
|
<action>Understand the mode's role in the broader ecosystem</action>
|
||||||
|
</actions>
|
||||||
|
<questions_to_ask>
|
||||||
|
<ask_user_question>
|
||||||
|
<question>What specific aspects of the mode would you like to change or enhance?</question>
|
||||||
|
<follow_up>
|
||||||
|
<suggest>Adjust permissions or restrictions</suggest>
|
||||||
|
<suggest>Fix issues with current workflows or instructions</suggest>
|
||||||
|
<suggest>Improve the mode's roleDefinition or whenToUse description</suggest>
|
||||||
|
<suggest>Enhance XML instructions for better clarity</suggest>
|
||||||
|
</follow_up>
|
||||||
|
</ask_user_question>
|
||||||
|
</questions_to_ask>
|
||||||
|
</step>
|
||||||
|
|
||||||
|
<step number="4.2">
|
||||||
|
<title>Analyze Change Impact</title>
|
||||||
|
<description>
|
||||||
|
Understand how proposed changes will affect the mode
|
||||||
|
</description>
|
||||||
|
<analysis_areas>
|
||||||
|
<area>Compatibility with existing workflows</area>
|
||||||
|
<area>Impact on file permissions and capability access</area>
|
||||||
|
<area>Consistency with mode's core purpose</area>
|
||||||
|
<area>Integration with other modes</area>
|
||||||
|
</analysis_areas>
|
||||||
|
<review_cleanup_checklist>
|
||||||
|
<item>Role and scope: roleDefinition matches actual scope and permissions; remove scope creep</item>
|
||||||
|
<item>Orchestrator routing: whenToUse/whenNotToUse are explicit and distinct from other modes</item>
|
||||||
|
<item>Permissions: groups and fileRegex follow least-privilege and match instructions</item>
|
||||||
|
<item>Instructions hygiene: no contradictions or duplicates across XML files</item>
|
||||||
|
<item>Naming consistency: tag names and terminology are consistent</item>
|
||||||
|
<item>Deprecated content: remove legacy fields (e.g., customInstructions in .roomodes)</item>
|
||||||
|
<item>Boundaries: clear handoffs to other modes; no overlapping responsibilities</item>
|
||||||
|
</review_cleanup_checklist>
|
||||||
|
<duplication_and_contradiction_scan>
|
||||||
|
<approach>Search for repeated guidance and conflicting directives across files</approach>
|
||||||
|
</duplication_and_contradiction_scan>
|
||||||
|
<validation_questions>
|
||||||
|
<ask_user_question>
|
||||||
|
<question>I've analyzed the existing mode. Here's what I understand about your requested changes. Is this correct?</question>
|
||||||
|
<follow_up>
|
||||||
|
<suggest>Yes, that's exactly what I want to change</suggest>
|
||||||
|
<suggest>Mostly correct, but let me clarify some details</suggest>
|
||||||
|
<suggest>No, I meant something different</suggest>
|
||||||
|
<suggest>I'd like to add additional changes</suggest>
|
||||||
|
</follow_up>
|
||||||
|
</ask_user_question>
|
||||||
|
</validation_questions>
|
||||||
|
</step>
|
||||||
|
|
||||||
|
<step number="4.3">
|
||||||
|
<title>Plan Modifications</title>
|
||||||
|
<description>
|
||||||
|
Create a detailed plan for modifying the mode
|
||||||
|
</description>
|
||||||
|
<planning_steps>
|
||||||
|
<step>Identify which files need to be modified</step>
|
||||||
|
<step>Determine if new XML instruction files are needed</step>
|
||||||
|
<step>Check for potential conflicts or contradictions</step>
|
||||||
|
<step>Plan the order of changes for minimal disruption</step>
|
||||||
|
</planning_steps>
|
||||||
|
<refactor_strategy>
|
||||||
|
<normalize>
|
||||||
|
<rule>Consolidate overlapping instructions into a single source of truth</rule>
|
||||||
|
<rule>Align with XML best practices (semantic tags, hierarchical nesting)</rule>
|
||||||
|
<rule>Standardize whenToUse/whenNotToUse language and boundaries</rule>
|
||||||
|
<rule>Centralize preamble rules and autonomy calibration</rule>
|
||||||
|
</normalize>
|
||||||
|
<permissions>
|
||||||
|
<rule>Tighten fileRegex to least-privilege; add clear descriptions</rule>
|
||||||
|
<rule>Ensure instructions match configured permissions</rule>
|
||||||
|
</permissions>
|
||||||
|
<structure>
|
||||||
|
<rule>Split overly long files; ensure 6_error_handling and 7_communication are present or updated</rule>
|
||||||
|
</structure>
|
||||||
|
<examples_and_tests>
|
||||||
|
<rule>Update 5_examples.xml to reflect new workflows and refactors</rule>
|
||||||
|
<rule>Include before/after diffs where helpful</rule>
|
||||||
|
</examples_and_tests>
|
||||||
|
</refactor_strategy>
|
||||||
|
<artifacts_to_update>
|
||||||
|
<item>.roomodes: roleDefinition and whenToUse</item>
|
||||||
|
<item>.roo/rules-[slug]/ XML instruction files</item>
|
||||||
|
<item>Examples and quick_reference sections</item>
|
||||||
|
</artifacts_to_update>
|
||||||
|
</step>
|
||||||
|
|
||||||
|
<step number="4.4">
|
||||||
|
<title>Silent Self-Reflection Rubric</title>
|
||||||
|
<description>Privately evaluate the planned changes against a 5–7 category rubric before implementation</description>
|
||||||
|
<rubric>
|
||||||
|
<category>Cohesion across files</category>
|
||||||
|
<category>Permissions and file restrictions (least privilege)</category>
|
||||||
|
<category>Orchestrator fit (whenToUse/whenNotToUse clarity)</category>
|
||||||
|
<category>XML structure and naming consistency</category>
|
||||||
|
<category>Mode boundaries and handoff points</category>
|
||||||
|
<category>Examples and testability</category>
|
||||||
|
</rubric>
|
||||||
|
<instruction>Iterate on the plan until it passes the rubric; do not expose the rubric to the user</instruction>
|
||||||
|
</step>
|
||||||
|
|
||||||
|
<step number="4.5">
|
||||||
|
<title>Implement Changes</title>
|
||||||
|
<description>
|
||||||
|
Apply the planned modifications to the mode
|
||||||
|
</description>
|
||||||
|
<implementation_order>
|
||||||
|
<change>Update .roomodes configuration if needed</change>
|
||||||
|
<change>Modify existing XML instruction files</change>
|
||||||
|
<change>Create new XML instruction files if required</change>
|
||||||
|
<change>Update examples and documentation</change>
|
||||||
|
</implementation_order>
|
||||||
|
<cleanup_tasks>
|
||||||
|
<task>Remove duplicate or contradictory instruction blocks across XML files</task>
|
||||||
|
<task>Delete or migrate deprecated fields (e.g., customInstructions in .roomodes)</task>
|
||||||
|
<task>Tighten fileRegex patterns and add clear descriptions</task>
|
||||||
|
<task>Normalize tag names, terminology, and structure</task>
|
||||||
|
<task>Ensure whenToUse/whenNotToUse and handoff rules are explicit</task>
|
||||||
|
</cleanup_tasks>
|
||||||
|
<verification_steps>
|
||||||
|
<step>Validate file restriction patterns against the intended file sets</step>
|
||||||
|
<step>Confirm permissions match instruction expectations</step>
|
||||||
|
<step>Re-run validation (section 5) and testing (section 6)</step>
|
||||||
|
<step>Scan the repository for legacy references and remove/modernize as needed</step>
|
||||||
|
</verification_steps>
|
||||||
|
</step>
|
||||||
|
</branch>
|
||||||
|
</workflow_branches>
|
||||||
|
|
||||||
|
<validation_and_cohesion>
|
||||||
|
<step number="5">
|
||||||
|
<title>Validate Cohesion and Consistency</title>
|
||||||
|
<description>
|
||||||
|
Ensure all changes are cohesive and don't contradict each other
|
||||||
|
</description>
|
||||||
|
<validation_checks>
|
||||||
|
<check type="configuration">
|
||||||
|
<item>Mode slug follows naming conventions</item>
|
||||||
|
<item>File restrictions align with mode purpose (least privilege)</item>
|
||||||
|
<item>Permissions are appropriate</item>
|
||||||
|
<item>whenToUse clearly differentiates from other modes</item>
|
||||||
|
</check>
|
||||||
|
<check type="instructions">
|
||||||
|
<item>All XML files follow consistent structure</item>
|
||||||
|
<item>No contradicting instructions between files; contradiction hierarchy and resolutions documented</item>
|
||||||
|
<item>Examples align with stated workflows</item>
|
||||||
|
<item>Instructions match granted permissions and file restrictions</item>
|
||||||
|
</check>
|
||||||
|
<check type="integration">
|
||||||
|
<item>Mode integrates well with Orchestrator</item>
|
||||||
|
<item>Clear boundaries with other modes</item>
|
||||||
|
<item>Handoff points are well-defined</item>
|
||||||
|
</check>
|
||||||
|
</validation_checks>
|
||||||
|
<cohesion_questions>
|
||||||
|
<ask_user_question>
|
||||||
|
<question>I've completed the validation checks. Would you like me to review any specific aspect in more detail?</question>
|
||||||
|
<follow_up>
|
||||||
|
<suggest>Review the file permission patterns</suggest>
|
||||||
|
<suggest>Check for workflow contradictions</suggest>
|
||||||
|
<suggest>Verify integration with other modes</suggest>
|
||||||
|
<suggest>Everything looks good, proceed to testing</suggest>
|
||||||
|
</follow_up>
|
||||||
|
</ask_user_question>
|
||||||
|
</cohesion_questions>
|
||||||
|
</step>
|
||||||
|
|
||||||
|
<step number="6">
|
||||||
|
<title>Test and Refine</title>
|
||||||
|
<description>
|
||||||
|
Verify the mode works as intended
|
||||||
|
</description>
|
||||||
|
<checklist>
|
||||||
|
<item>Mode appears in the mode list</item>
|
||||||
|
<item>File restrictions work correctly</item>
|
||||||
|
<item>Instructions are clear and actionable</item>
|
||||||
|
<item>Mode integrates well with Orchestrator</item>
|
||||||
|
<item>All examples are accurate and helpful</item>
|
||||||
|
<item>Changes don't break existing functionality (for edits)</item>
|
||||||
|
<item>New behavior works as expected</item>
|
||||||
|
</checklist>
|
||||||
|
</step>
|
||||||
|
</validation_and_cohesion>
|
||||||
|
|
||||||
|
<quick_reference>
|
||||||
|
<action>Create mode in .roomodes for project-specific modes</action>
|
||||||
|
<action>Create mode in the global custom modes settings file for system-wide modes (path is environment-specific)</action>
|
||||||
|
<action>Verify the .roo folder structure contains expected rule directories and XML files</action>
|
||||||
|
<action>Validate file regex patterns against the intended file sets (avoid overbroad matches)</action>
|
||||||
|
<action>Find existing mode implementations and patterns to reuse</action>
|
||||||
|
<action>Read all XML files in a mode directory to understand its structure</action>
|
||||||
|
<action>Always validate changes for cohesion and consistency</action>
|
||||||
|
</quick_reference>
|
||||||
|
</mode_management_workflow>
|
||||||
@@ -0,0 +1,240 @@
|
|||||||
|
<xml_structuring_best_practices>
|
||||||
|
<overview>
|
||||||
|
XML tags help LLMs parse prompts more accurately, leading to higher-quality outputs.
|
||||||
|
This guide covers best practices for structuring mode instructions using XML.
|
||||||
|
</overview>
|
||||||
|
|
||||||
|
<why_use_xml_tags>
|
||||||
|
<benefit type="clarity">
|
||||||
|
Clearly separate different parts of your instructions and ensure well-structured content
|
||||||
|
</benefit>
|
||||||
|
<benefit type="accuracy">
|
||||||
|
Reduce errors caused by the model misinterpreting parts of your instructions
|
||||||
|
</benefit>
|
||||||
|
<benefit type="flexibility">
|
||||||
|
Easily find, add, remove, or modify parts of instructions without rewriting everything
|
||||||
|
</benefit>
|
||||||
|
<benefit type="parseability">
|
||||||
|
Having the model use XML tags in its output makes it easier to extract specific parts of responses
|
||||||
|
</benefit>
|
||||||
|
</why_use_xml_tags>
|
||||||
|
|
||||||
|
<core_principles>
|
||||||
|
<principle name="consistency">
|
||||||
|
<description>Use the same tag names throughout your instructions</description>
|
||||||
|
<example>
|
||||||
|
Always use <step> for workflow steps, not sometimes <action> or <task>
|
||||||
|
</example>
|
||||||
|
</principle>
|
||||||
|
|
||||||
|
<principle name="semantic_naming">
|
||||||
|
<description>Tag names should clearly describe their content</description>
|
||||||
|
<good_examples>
|
||||||
|
<tag>detailed_steps</tag>
|
||||||
|
<tag>error_handling</tag>
|
||||||
|
<tag>validation_rules</tag>
|
||||||
|
</good_examples>
|
||||||
|
<bad_examples>
|
||||||
|
<tag>stuff</tag>
|
||||||
|
<tag>misc</tag>
|
||||||
|
<tag>data1</tag>
|
||||||
|
</bad_examples>
|
||||||
|
</principle>
|
||||||
|
|
||||||
|
<principle name="hierarchical_nesting">
|
||||||
|
<description>Nest tags to show relationships and structure</description>
|
||||||
|
<example>
|
||||||
|
<workflow>
|
||||||
|
<phase name="preparation">
|
||||||
|
<step>Gather requirements</step>
|
||||||
|
<step>Validate inputs</step>
|
||||||
|
</phase>
|
||||||
|
<phase name="execution">
|
||||||
|
<step>Process data</step>
|
||||||
|
<step>Generate output</step>
|
||||||
|
</phase>
|
||||||
|
</workflow>
|
||||||
|
</example>
|
||||||
|
</principle>
|
||||||
|
</core_principles>
|
||||||
|
|
||||||
|
<common_tag_patterns>
|
||||||
|
<pattern name="workflow_structure">
|
||||||
|
<usage>For step-by-step processes</usage>
|
||||||
|
<template>
|
||||||
|
<workflow>
|
||||||
|
<overview>High-level description</overview>
|
||||||
|
<prerequisites>
|
||||||
|
<prerequisite>Required condition 1</prerequisite>
|
||||||
|
<prerequisite>Required condition 2</prerequisite>
|
||||||
|
</prerequisites>
|
||||||
|
<steps>
|
||||||
|
<step number="1">
|
||||||
|
<title>Step Title</title>
|
||||||
|
<description>What this step accomplishes</description>
|
||||||
|
<actions>
|
||||||
|
<action>Specific action to take</action>
|
||||||
|
</actions>
|
||||||
|
<validation>How to verify success</validation>
|
||||||
|
</step>
|
||||||
|
</steps>
|
||||||
|
</workflow>
|
||||||
|
</template>
|
||||||
|
</pattern>
|
||||||
|
|
||||||
|
<pattern name="examples_structure">
|
||||||
|
<usage>For providing code examples and demonstrations</usage>
|
||||||
|
<template>
|
||||||
|
<examples>
|
||||||
|
<example name="descriptive_name">
|
||||||
|
<description>What this example demonstrates</description>
|
||||||
|
<context>When to use this approach</context>
|
||||||
|
<code language="typescript">
|
||||||
|
// Your code example here
|
||||||
|
</code>
|
||||||
|
<explanation>
|
||||||
|
Key points about the implementation
|
||||||
|
</explanation>
|
||||||
|
</example>
|
||||||
|
</examples>
|
||||||
|
</template>
|
||||||
|
</pattern>
|
||||||
|
|
||||||
|
<pattern name="guidelines_structure">
|
||||||
|
<usage>For rules and best practices</usage>
|
||||||
|
<template>
|
||||||
|
<guidelines category="category_name">
|
||||||
|
<guideline priority="high">
|
||||||
|
<rule>The specific rule or guideline</rule>
|
||||||
|
<rationale>Why this is important</rationale>
|
||||||
|
<exceptions>When this doesn't apply</exceptions>
|
||||||
|
</guideline>
|
||||||
|
</guidelines>
|
||||||
|
</template>
|
||||||
|
</pattern>
|
||||||
|
|
||||||
|
<pattern name="decision_guidance_structure">
|
||||||
|
<usage>For documenting decision criteria and guardrails</usage>
|
||||||
|
<template>
|
||||||
|
<decision_guidance>
|
||||||
|
<principles>
|
||||||
|
<principle>Do not include runtime implementation details (no function names, command names, UI entry points, or execution syntax)</principle>
|
||||||
|
<principle>Prefer the smallest change that satisfies the request</principle>
|
||||||
|
<principle>Prefer a single source of truth; avoid duplicated rules across files</principle>
|
||||||
|
<principle>Ask a clarifying question only when critical ambiguity remains</principle>
|
||||||
|
</principles>
|
||||||
|
|
||||||
|
<constraints>
|
||||||
|
Constraints and guardrails (e.g., permissions, file restrictions, or other limits).
|
||||||
|
</constraints>
|
||||||
|
|
||||||
|
<validation>
|
||||||
|
What to verify after changes (cohesion, examples updated, boundaries clear).
|
||||||
|
</validation>
|
||||||
|
</decision_guidance>
|
||||||
|
</template>
|
||||||
|
</pattern>
|
||||||
|
</common_tag_patterns>
|
||||||
|
|
||||||
|
<formatting_guidelines>
|
||||||
|
<guideline name="indentation">
|
||||||
|
Use consistent indentation (2 or 4 spaces) for nested elements
|
||||||
|
</guideline>
|
||||||
|
<guideline name="line_breaks">
|
||||||
|
Add line breaks between major sections for readability
|
||||||
|
</guideline>
|
||||||
|
<guideline name="comments">
|
||||||
|
Use XML comments <!-- like this --> to explain complex sections
|
||||||
|
</guideline>
|
||||||
|
<guideline name="cdata_sections">
|
||||||
|
Use CDATA for code blocks or content with special characters:
|
||||||
|
<code>your code here</code>
|
||||||
|
</guideline>
|
||||||
|
<guideline name="attributes_vs_elements">
|
||||||
|
Use attributes for metadata, elements for content:
|
||||||
|
<example type="good">
|
||||||
|
<step number="1" priority="high">
|
||||||
|
<description>The actual step content</description>
|
||||||
|
</step>
|
||||||
|
</example>
|
||||||
|
</guideline>
|
||||||
|
<guideline name="verbosity">
|
||||||
|
Keep narrative outputs concise; reserve detailed exposition for code, diffs, and structured outputs. Prefer readable, maintainable code with clear names; avoid one-liners unless explicitly requested.
|
||||||
|
</guideline>
|
||||||
|
</formatting_guidelines>
|
||||||
|
|
||||||
|
<anti_patterns>
|
||||||
|
<anti_pattern name="flat_structure">
|
||||||
|
<description>Avoid completely flat structures without hierarchy</description>
|
||||||
|
<bad>
|
||||||
|
<instructions>
|
||||||
|
|
||||||
|
<item1>Do this</item1>
|
||||||
|
|
||||||
|
<item2>Then this</item2>
|
||||||
|
|
||||||
|
<item3>Finally this</item3>
|
||||||
|
|
||||||
|
</instructions>
|
||||||
|
</bad>
|
||||||
|
<good>
|
||||||
|
<instructions>
|
||||||
|
<steps>
|
||||||
|
<step order="1">Do this</step>
|
||||||
|
<step order="2">Then this</step>
|
||||||
|
<step order="3">Finally this</step>
|
||||||
|
</steps>
|
||||||
|
</instructions>
|
||||||
|
</good>
|
||||||
|
</anti_pattern>
|
||||||
|
|
||||||
|
<anti_pattern name="inconsistent_naming">
|
||||||
|
<description>Don't mix naming conventions</description>
|
||||||
|
<bad>
|
||||||
|
Mixing camelCase, snake_case, and kebab-case in tag names
|
||||||
|
</bad>
|
||||||
|
<good>
|
||||||
|
Pick one convention (preferably snake_case for XML) and stick to it
|
||||||
|
</good>
|
||||||
|
</anti_pattern>
|
||||||
|
|
||||||
|
<anti_pattern name="overly_generic_tags">
|
||||||
|
<description>Avoid tags that don't convey meaning</description>
|
||||||
|
<bad>data, info, stuff, thing, item</bad>
|
||||||
|
<good>user_input, validation_result, error_message, configuration</good>
|
||||||
|
</anti_pattern>
|
||||||
|
<anti_pattern name="over_clarifying_questions">
|
||||||
|
<description>Avoid asking the user to confirm obvious next steps on straightforward tasks</description>
|
||||||
|
<bad>Asking multiple clarifying questions before acting when the task is simple</bad>
|
||||||
|
<good>Proceed when next steps are clear; ask only when critical ambiguity remains; document assumptions</good>
|
||||||
|
</anti_pattern>
|
||||||
|
|
||||||
|
<anti_pattern name="excessive_searching">
|
||||||
|
<description>Avoid repetitive or redundant searches when the relevant target is already identified</description>
|
||||||
|
<bad>Running multiple identical searches instead of acting</bad>
|
||||||
|
<good>Stop once the change is clearly identified; then implement</good>
|
||||||
|
</anti_pattern>
|
||||||
|
|
||||||
|
<anti_pattern name="over_specifying_runtime_behavior">
|
||||||
|
<description>Avoid duplicating runtime behavior that is already defined elsewhere</description>
|
||||||
|
<bad>Documenting execution constraints, operation ordering, or invocation details</bad>
|
||||||
|
<good>Focus on intent, artifacts, decision criteria, and validation expectations</good>
|
||||||
|
</anti_pattern>
|
||||||
|
</anti_patterns>
|
||||||
|
|
||||||
|
<integration_tips>
|
||||||
|
<tip>
|
||||||
|
Reference XML content in instructions:
|
||||||
|
"Using the workflow defined in <workflow> tags..."
|
||||||
|
</tip>
|
||||||
|
<tip>
|
||||||
|
Combine XML structure with other techniques like multishot prompting
|
||||||
|
</tip>
|
||||||
|
<tip>
|
||||||
|
Use XML tags in expected outputs to make parsing easier
|
||||||
|
</tip>
|
||||||
|
<tip>
|
||||||
|
Create reusable XML templates for common patterns
|
||||||
|
</tip>
|
||||||
|
</integration_tips>
|
||||||
|
</xml_structuring_best_practices>
|
||||||
@@ -0,0 +1,307 @@
|
|||||||
|
<mode_configuration_patterns>
|
||||||
|
<overview>
|
||||||
|
Common patterns and templates for creating different types of modes, with examples from existing modes in the Roo-Code software.
|
||||||
|
</overview>
|
||||||
|
|
||||||
|
<mode_types>
|
||||||
|
<type name="specialist_mode">
|
||||||
|
<description>
|
||||||
|
Modes focused on specific technical domains or tasks
|
||||||
|
</description>
|
||||||
|
<characteristics>
|
||||||
|
<characteristic>Deep expertise in a particular area</characteristic>
|
||||||
|
<characteristic>Restricted file access based on domain</characteristic>
|
||||||
|
<characteristic>Specialized workflows and decision criteria</characteristic>
|
||||||
|
</characteristics>
|
||||||
|
<example_template>
|
||||||
|
- slug: api-specialist
|
||||||
|
name: 🔌 API Specialist
|
||||||
|
roleDefinition: >-
|
||||||
|
You are Roo Code, an API development specialist with expertise in:
|
||||||
|
- RESTful API design and implementation
|
||||||
|
- GraphQL schema design
|
||||||
|
- API documentation with OpenAPI/Swagger
|
||||||
|
- Authentication and authorization patterns
|
||||||
|
- Rate limiting and caching strategies
|
||||||
|
- API versioning and deprecation
|
||||||
|
|
||||||
|
You ensure APIs are:
|
||||||
|
- Well-documented and discoverable
|
||||||
|
- Following REST principles or GraphQL best practices
|
||||||
|
- Secure and performant
|
||||||
|
- Properly versioned and maintainable
|
||||||
|
whenToUse: >-
|
||||||
|
Use this mode when designing, implementing, or refactoring APIs.
|
||||||
|
This includes creating new endpoints, updating API documentation,
|
||||||
|
implementing authentication, or optimizing API performance.
|
||||||
|
groups:
|
||||||
|
- read
|
||||||
|
- - edit
|
||||||
|
- fileRegex: (api/.*\.(ts|js)|.*\.openapi\.yaml|.*\.graphql|docs/api/.*)$
|
||||||
|
description: API implementation files, OpenAPI specs, and API documentation
|
||||||
|
- command
|
||||||
|
- mcp
|
||||||
|
</example_template>
|
||||||
|
</type>
|
||||||
|
|
||||||
|
<type name="workflow_mode">
|
||||||
|
<description>
|
||||||
|
Modes that guide users through multi-step processes
|
||||||
|
</description>
|
||||||
|
<characteristics>
|
||||||
|
<characteristic>Step-by-step workflow guidance</characteristic>
|
||||||
|
<characteristic>Heavy use of focused clarifying questions</characteristic>
|
||||||
|
<characteristic>Process validation at each step</characteristic>
|
||||||
|
</characteristics>
|
||||||
|
<example_template>
|
||||||
|
- slug: migration-guide
|
||||||
|
name: 🔄 Migration Guide
|
||||||
|
roleDefinition: >-
|
||||||
|
You are Roo Code, a migration specialist who guides users through
|
||||||
|
complex migration processes:
|
||||||
|
- Database schema migrations
|
||||||
|
- Framework version upgrades
|
||||||
|
- API version migrations
|
||||||
|
- Dependency updates
|
||||||
|
- Breaking change resolutions
|
||||||
|
|
||||||
|
You provide:
|
||||||
|
- Step-by-step migration plans
|
||||||
|
- Automated migration scripts
|
||||||
|
- Rollback strategies
|
||||||
|
- Testing approaches for migrations
|
||||||
|
whenToUse: >-
|
||||||
|
Use this mode when performing any kind of migration or upgrade.
|
||||||
|
This mode will analyze the current state, plan the migration,
|
||||||
|
and guide you through each step with validation.
|
||||||
|
groups:
|
||||||
|
- read
|
||||||
|
- edit
|
||||||
|
- command
|
||||||
|
</example_template>
|
||||||
|
</type>
|
||||||
|
|
||||||
|
<type name="analysis_mode">
|
||||||
|
<description>
|
||||||
|
Modes focused on code analysis and reporting
|
||||||
|
</description>
|
||||||
|
<characteristics>
|
||||||
|
<characteristic>Read-heavy operations</characteristic>
|
||||||
|
<characteristic>Limited or no edit permissions</characteristic>
|
||||||
|
<characteristic>Comprehensive reporting outputs</characteristic>
|
||||||
|
</characteristics>
|
||||||
|
<example_template>
|
||||||
|
- slug: security-auditor
|
||||||
|
name: 🔒 Security Auditor
|
||||||
|
roleDefinition: >-
|
||||||
|
You are Roo Code, a security analysis specialist focused on:
|
||||||
|
- Identifying security vulnerabilities
|
||||||
|
- Analyzing authentication and authorization
|
||||||
|
- Reviewing data validation and sanitization
|
||||||
|
- Checking for common security anti-patterns
|
||||||
|
- Evaluating dependency vulnerabilities
|
||||||
|
- Assessing API security
|
||||||
|
|
||||||
|
You provide detailed security reports with:
|
||||||
|
- Vulnerability severity ratings
|
||||||
|
- Specific remediation steps
|
||||||
|
- Security best practice recommendations
|
||||||
|
whenToUse: >-
|
||||||
|
Use this mode to perform security audits on codebases.
|
||||||
|
This mode will analyze code for vulnerabilities, check
|
||||||
|
dependencies, and provide actionable security recommendations.
|
||||||
|
groups:
|
||||||
|
- read
|
||||||
|
- command
|
||||||
|
- - edit
|
||||||
|
- fileRegex: (SECURITY\.md|\.github/security/.*|docs/security/.*)$
|
||||||
|
description: Security documentation files only
|
||||||
|
</example_template>
|
||||||
|
</type>
|
||||||
|
|
||||||
|
<type name="creative_mode">
|
||||||
|
<description>
|
||||||
|
Modes for generating new content or features
|
||||||
|
</description>
|
||||||
|
<characteristics>
|
||||||
|
<characteristic>Broad file creation permissions</characteristic>
|
||||||
|
<characteristic>Template and boilerplate generation</characteristic>
|
||||||
|
<characteristic>Interactive design process</characteristic>
|
||||||
|
</characteristics>
|
||||||
|
<example_template>
|
||||||
|
- slug: component-designer
|
||||||
|
name: 🎨 Component Designer
|
||||||
|
roleDefinition: >-
|
||||||
|
You are Roo Code, a UI component design specialist who creates:
|
||||||
|
- Reusable React/Vue/Angular components
|
||||||
|
- Component documentation and examples
|
||||||
|
- Storybook stories
|
||||||
|
- Unit tests for components
|
||||||
|
- Accessibility-compliant interfaces
|
||||||
|
|
||||||
|
You follow design system principles and ensure components are:
|
||||||
|
- Highly reusable and composable
|
||||||
|
- Well-documented with examples
|
||||||
|
- Fully tested
|
||||||
|
- Accessible (WCAG compliant)
|
||||||
|
- Performance optimized
|
||||||
|
whenToUse: >-
|
||||||
|
Use this mode when creating new UI components or refactoring
|
||||||
|
existing ones. This mode helps design component APIs, implement
|
||||||
|
the components, and create comprehensive documentation.
|
||||||
|
groups:
|
||||||
|
- read
|
||||||
|
- - edit
|
||||||
|
- fileRegex: (components/.*|stories/.*|__tests__/.*\.test\.(tsx?|jsx?))$
|
||||||
|
description: Component files, stories, and component tests
|
||||||
|
- browser
|
||||||
|
- command
|
||||||
|
</example_template>
|
||||||
|
</type>
|
||||||
|
</mode_types>
|
||||||
|
|
||||||
|
<autonomy_configuration>
|
||||||
|
<overview>Configuration patterns to keep modes focused, cohesive, and clearly scoped</overview>
|
||||||
|
<defaults>
|
||||||
|
<cohesion>Prefer a single source of truth for each rule; avoid duplicated instructions</cohesion>
|
||||||
|
<scope>Prefer least privilege; keep file restrictions aligned with purpose</scope>
|
||||||
|
<clarity>Define acceptance criteria and validation gates for typical tasks</clarity>
|
||||||
|
<handoffs>Define explicit boundaries and handoff points to other modes</handoffs>
|
||||||
|
<verbosity>Keep narrative brief; reserve detail for structured outputs and diffs</verbosity>
|
||||||
|
</defaults>
|
||||||
|
<per_mode_guidance>
|
||||||
|
<mode type="specialist_mode">
|
||||||
|
<notes>Tight scope, least privilege, clear boundaries; prefer small targeted changes</notes>
|
||||||
|
</mode>
|
||||||
|
<mode type="workflow_mode">
|
||||||
|
<notes>Step-by-step process with validation gates; ask clarifying questions only when necessary</notes>
|
||||||
|
</mode>
|
||||||
|
<mode type="analysis_mode">
|
||||||
|
<notes>Read-heavy; edits typically constrained to reporting or documentation outputs</notes>
|
||||||
|
</mode>
|
||||||
|
<mode type="creative_mode">
|
||||||
|
<notes>Broader creation scope; ensure examples and tests are included when applicable</notes>
|
||||||
|
</mode>
|
||||||
|
</per_mode_guidance>
|
||||||
|
</autonomy_configuration>
|
||||||
|
|
||||||
|
<permission_patterns>
|
||||||
|
<pattern name="documentation_only">
|
||||||
|
<description>For modes that only work with documentation</description>
|
||||||
|
<configuration>
|
||||||
|
groups:
|
||||||
|
- read
|
||||||
|
- - edit
|
||||||
|
- fileRegex: \.(md|mdx|rst|txt)$
|
||||||
|
description: Documentation files only
|
||||||
|
</configuration>
|
||||||
|
</pattern>
|
||||||
|
|
||||||
|
<pattern name="test_focused">
|
||||||
|
<description>For modes that work with test files</description>
|
||||||
|
<configuration>
|
||||||
|
groups:
|
||||||
|
- read
|
||||||
|
- command
|
||||||
|
- - edit
|
||||||
|
- fileRegex: (__tests__/.*|__mocks__/.*|.*\.test\.(ts|tsx|js|jsx)$|.*\.spec\.(ts|tsx|js|jsx)$)
|
||||||
|
description: Test files and mocks
|
||||||
|
</configuration>
|
||||||
|
</pattern>
|
||||||
|
|
||||||
|
<pattern name="config_management">
|
||||||
|
<description>For modes that manage configuration</description>
|
||||||
|
<configuration>
|
||||||
|
groups:
|
||||||
|
- read
|
||||||
|
- - edit
|
||||||
|
- fileRegex: (.*\.config\.(js|ts|json)|.*rc\.json|.*\.yaml|.*\.yml|\.env\.example)$
|
||||||
|
description: Configuration files (not .env)
|
||||||
|
</configuration>
|
||||||
|
</pattern>
|
||||||
|
|
||||||
|
<pattern name="full_stack">
|
||||||
|
<description>For modes that need broad access</description>
|
||||||
|
<configuration>
|
||||||
|
groups:
|
||||||
|
- read
|
||||||
|
- edit # No restrictions
|
||||||
|
- command
|
||||||
|
- browser
|
||||||
|
- mcp
|
||||||
|
</configuration>
|
||||||
|
</pattern>
|
||||||
|
</permission_patterns>
|
||||||
|
|
||||||
|
<naming_conventions>
|
||||||
|
<convention category="slug">
|
||||||
|
<rule>Use lowercase with hyphens</rule>
|
||||||
|
<good>api-dev, test-writer, docs-manager</good>
|
||||||
|
<bad>apiDev, test_writer, DocsManager</bad>
|
||||||
|
</convention>
|
||||||
|
|
||||||
|
<convention category="name">
|
||||||
|
<rule>Use title case with descriptive emoji</rule>
|
||||||
|
<good>🔧 API Developer, 📝 Documentation Writer</good>
|
||||||
|
<bad>api developer, DOCUMENTATION WRITER</bad>
|
||||||
|
</convention>
|
||||||
|
|
||||||
|
<convention category="emoji_selection">
|
||||||
|
<common_emojis>
|
||||||
|
<emoji meaning="testing">🧪</emoji>
|
||||||
|
<emoji meaning="documentation">📝</emoji>
|
||||||
|
<emoji meaning="design">🎨</emoji>
|
||||||
|
<emoji meaning="debugging">🪲</emoji>
|
||||||
|
<emoji meaning="building">🏗️</emoji>
|
||||||
|
<emoji meaning="security">🔒</emoji>
|
||||||
|
<emoji meaning="api">🔌</emoji>
|
||||||
|
<emoji meaning="database">🗄️</emoji>
|
||||||
|
<emoji meaning="performance">⚡</emoji>
|
||||||
|
<emoji meaning="configuration">⚙️</emoji>
|
||||||
|
</common_emojis>
|
||||||
|
</convention>
|
||||||
|
</naming_conventions>
|
||||||
|
|
||||||
|
<integration_guidelines>
|
||||||
|
<guideline name="orchestrator_compatibility">
|
||||||
|
<description>Ensure whenToUse/whenNotToUse are clear for Orchestrator mode</description>
|
||||||
|
<checklist>
|
||||||
|
<item>Specify concrete task types the mode handles</item>
|
||||||
|
<item>Include trigger keywords or phrases</item>
|
||||||
|
<item>Differentiate from similar modes</item>
|
||||||
|
<item>Mention specific file types or areas</item>
|
||||||
|
<item>Define whenNotToUse with negative triggers and explicit handoffs</item>
|
||||||
|
<item>State stop/ask/handoff rules</item>
|
||||||
|
<item>State default verbosity policy (low narrative; verbose diffs)</item>
|
||||||
|
</checklist>
|
||||||
|
</guideline>
|
||||||
|
|
||||||
|
<guideline name="stop_and_handoff_rules">
|
||||||
|
<description>Define explicit stop conditions, confirmation thresholds, and handoff/ask triggers</description>
|
||||||
|
<checklist>
|
||||||
|
<item>Done-ness: acceptance criteria and validation gates are defined</item>
|
||||||
|
<item>Handoff rules to other modes or “ask a clarifying question” conditions are explicit</item>
|
||||||
|
<item>Boundaries, risks, and validation gates are documented</item>
|
||||||
|
</checklist>
|
||||||
|
</guideline>
|
||||||
|
|
||||||
|
<guideline name="verbosity_policy">
|
||||||
|
<description>Set verbosity defaults to keep narrative short and code edits clear</description>
|
||||||
|
<checklist>
|
||||||
|
<item>Low narrative verbosity in status/progress text</item>
|
||||||
|
<item>High detail only inside code/diffs and structured outputs</item>
|
||||||
|
<item>Code clarity over cleverness; avoid code-golf and cryptic names</item>
|
||||||
|
</checklist>
|
||||||
|
</guideline>
|
||||||
|
|
||||||
|
<guideline name="mode_boundaries">
|
||||||
|
<description>Define clear boundaries between modes</description>
|
||||||
|
<checklist>
|
||||||
|
<item>Avoid overlapping responsibilities</item>
|
||||||
|
<item>Make handoff points explicit</item>
|
||||||
|
<item>Switch modes when appropriate (mechanism varies)</item>
|
||||||
|
<item>Document mode interactions</item>
|
||||||
|
</checklist>
|
||||||
|
</guideline>
|
||||||
|
</integration_guidelines>
|
||||||
|
</mode_configuration_patterns>
|
||||||
@@ -0,0 +1,293 @@
|
|||||||
|
<instruction_file_templates>
|
||||||
|
<overview>
|
||||||
|
Templates and examples for creating XML instruction files that provide
|
||||||
|
detailed guidance for each mode's behavior and workflows.
|
||||||
|
|
||||||
|
Requirements:
|
||||||
|
- Do not reference runtime implementation details (function names, command names, UI entry points, or execution syntax).
|
||||||
|
- Do not duplicate operational policies that are already defined by the runtime/system prompt.
|
||||||
|
- Focus on workflow intent, required artifacts, decision criteria, and validation expectations.
|
||||||
|
</overview>
|
||||||
|
|
||||||
|
<file_organization>
|
||||||
|
<principle>Number files to indicate execution order</principle>
|
||||||
|
<principle>Use descriptive names that indicate content</principle>
|
||||||
|
<principle>Keep related instructions together</principle>
|
||||||
|
<standard_structure>
|
||||||
|
<file>1_workflow.xml - Main workflow and processes</file>
|
||||||
|
<file>2_best_practices.xml - Guidelines and conventions</file>
|
||||||
|
<file>3_common_patterns.xml - Reusable code patterns</file>
|
||||||
|
<file>4_decision_guidance.xml - Decision criteria and guardrails</file>
|
||||||
|
<file>5_examples.xml - Complete workflow examples</file>
|
||||||
|
<file>6_error_handling.xml - Error scenarios and recovery</file>
|
||||||
|
<file>7_communication.xml - User interaction guidelines</file>
|
||||||
|
</standard_structure>
|
||||||
|
</file_organization>
|
||||||
|
|
||||||
|
<workflow_file_template>
|
||||||
|
<description>Template for main workflow files (1_workflow.xml)</description>
|
||||||
|
<template>
|
||||||
|
<workflow_instructions>
|
||||||
|
<mode_overview>
|
||||||
|
Brief description of what this mode does and its primary purpose
|
||||||
|
</mode_overview>
|
||||||
|
|
||||||
|
<initialization_steps>
|
||||||
|
<step number="1">
|
||||||
|
<action>Understand the user's request</action>
|
||||||
|
<details>
|
||||||
|
Parse the user's input to identify:
|
||||||
|
- Primary objective
|
||||||
|
- Specific requirements
|
||||||
|
- Constraints or limitations
|
||||||
|
</details>
|
||||||
|
</step>
|
||||||
|
|
||||||
|
<step number="2">
|
||||||
|
<action>Gather necessary context</action>
|
||||||
|
<details>
|
||||||
|
Review the minimal set of repository materials needed to act safely.
|
||||||
|
Prefer extending existing guidance over introducing duplicated rules.
|
||||||
|
</details>
|
||||||
|
</step>
|
||||||
|
</initialization_steps>
|
||||||
|
|
||||||
|
<main_workflow>
|
||||||
|
<phase name="analysis">
|
||||||
|
<description>Analyze the current state and requirements</description>
|
||||||
|
<steps>
|
||||||
|
<step>Identify affected components</step>
|
||||||
|
<step>Assess impact of changes</step>
|
||||||
|
<step>Plan implementation approach</step>
|
||||||
|
</steps>
|
||||||
|
</phase>
|
||||||
|
|
||||||
|
<phase name="implementation">
|
||||||
|
<description>Execute the planned changes</description>
|
||||||
|
<steps>
|
||||||
|
<step>Create/modify necessary files</step>
|
||||||
|
<step>Ensure consistency across codebase</step>
|
||||||
|
<step>Add appropriate documentation</step>
|
||||||
|
</steps>
|
||||||
|
</phase>
|
||||||
|
|
||||||
|
<phase name="validation">
|
||||||
|
<description>Verify the implementation</description>
|
||||||
|
<steps>
|
||||||
|
<step>Check for errors or inconsistencies</step>
|
||||||
|
<step>Validate against requirements</step>
|
||||||
|
<step>Ensure no regressions</step>
|
||||||
|
</steps>
|
||||||
|
</phase>
|
||||||
|
</main_workflow>
|
||||||
|
|
||||||
|
<completion_criteria>
|
||||||
|
<criterion>All requirements have been addressed</criterion>
|
||||||
|
<criterion>Code follows project conventions</criterion>
|
||||||
|
<criterion>Changes are properly documented</criterion>
|
||||||
|
<criterion>No breaking changes introduced</criterion>
|
||||||
|
</completion_criteria>
|
||||||
|
</workflow_instructions>
|
||||||
|
</template>
|
||||||
|
</workflow_file_template>
|
||||||
|
|
||||||
|
<best_practices_template>
|
||||||
|
<description>Template for best practices files (2_best_practices.xml)</description>
|
||||||
|
<template>
|
||||||
|
<best_practices>
|
||||||
|
<general_principles>
|
||||||
|
<principle priority="high">
|
||||||
|
<name>Principle Name</name>
|
||||||
|
<description>Detailed explanation of the principle</description>
|
||||||
|
<rationale>Why this principle is important</rationale>
|
||||||
|
<example>
|
||||||
|
<scenario>When this applies</scenario>
|
||||||
|
<good>Correct approach</good>
|
||||||
|
<bad>What to avoid</bad>
|
||||||
|
</example>
|
||||||
|
</principle>
|
||||||
|
</general_principles>
|
||||||
|
|
||||||
|
<code_conventions>
|
||||||
|
<convention category="naming">
|
||||||
|
<rule>Specific naming convention</rule>
|
||||||
|
<examples>
|
||||||
|
<good>goodExampleName</good>
|
||||||
|
<bad>bad_example-name</bad>
|
||||||
|
</examples>
|
||||||
|
</convention>
|
||||||
|
|
||||||
|
<convention category="structure">
|
||||||
|
<rule>How to structure code/files</rule>
|
||||||
|
<template>
|
||||||
|
// Example structure
|
||||||
|
</template>
|
||||||
|
</convention>
|
||||||
|
</code_conventions>
|
||||||
|
|
||||||
|
<common_pitfalls>
|
||||||
|
<pitfall>
|
||||||
|
<description>Common mistake to avoid</description>
|
||||||
|
<why_problematic>Explanation of issues it causes</why_problematic>
|
||||||
|
<correct_approach>How to do it properly</correct_approach>
|
||||||
|
</pitfall>
|
||||||
|
</common_pitfalls>
|
||||||
|
|
||||||
|
<quality_checklist>
|
||||||
|
<category name="before_starting">
|
||||||
|
<item>Understand requirements fully</item>
|
||||||
|
<item>Check existing implementations</item>
|
||||||
|
</category>
|
||||||
|
<category name="during_implementation">
|
||||||
|
<item>Follow established patterns</item>
|
||||||
|
<item>Write clear documentation</item>
|
||||||
|
</category>
|
||||||
|
<category name="before_completion">
|
||||||
|
<item>Review all changes</item>
|
||||||
|
<item>Verify requirements met</item>
|
||||||
|
</category>
|
||||||
|
</quality_checklist>
|
||||||
|
</best_practices>
|
||||||
|
</template>
|
||||||
|
</best_practices_template>
|
||||||
|
|
||||||
|
<decision_guidance_template>
|
||||||
|
<description>Template for decision criteria and guardrails (4_decision_guidance.xml)</description>
|
||||||
|
<template>
|
||||||
|
<decision_guidance>
|
||||||
|
<principles>
|
||||||
|
<principle>Do not include runtime implementation details (no function names, command names, UI entry points, or execution syntax)</principle>
|
||||||
|
<principle>Prefer the smallest change that satisfies the request</principle>
|
||||||
|
<principle>Prefer a single source of truth; avoid duplicated rules across files</principle>
|
||||||
|
<principle>Ask a clarifying question only when critical ambiguity remains</principle>
|
||||||
|
</principles>
|
||||||
|
|
||||||
|
<boundaries>
|
||||||
|
<rule>Define clear responsibilities and explicit handoff points to other modes</rule>
|
||||||
|
</boundaries>
|
||||||
|
|
||||||
|
<validation>
|
||||||
|
<rule>After changes, scan for contradictions and update examples to match</rule>
|
||||||
|
</validation>
|
||||||
|
</decision_guidance>
|
||||||
|
</template>
|
||||||
|
</decision_guidance_template>
|
||||||
|
|
||||||
|
<examples_file_template>
|
||||||
|
<description>Template for example files (5_examples.xml)</description>
|
||||||
|
<template>
|
||||||
|
<complete_examples>
|
||||||
|
<example name="descriptive_example_name">
|
||||||
|
<scenario>
|
||||||
|
Detailed description of the use case this example covers
|
||||||
|
</scenario>
|
||||||
|
|
||||||
|
<user_request>
|
||||||
|
The initial request from the user
|
||||||
|
</user_request>
|
||||||
|
|
||||||
|
<workflow>
|
||||||
|
<step number="1">
|
||||||
|
<description>First step description</description>
|
||||||
|
<approach>
|
||||||
|
Identify the relevant existing files/sections that need to change.
|
||||||
|
Outcome: a shortlist of candidate paths or sections.
|
||||||
|
</approach>
|
||||||
|
<expected_outcome>What we learn from this step</expected_outcome>
|
||||||
|
</step>
|
||||||
|
|
||||||
|
<step number="2">
|
||||||
|
<description>Second step description</description>
|
||||||
|
<approach>
|
||||||
|
Review the top candidates and confirm the exact area to modify.
|
||||||
|
Outcome: precise target sections and constraints.
|
||||||
|
</approach>
|
||||||
|
<analysis>How we interpret the results</analysis>
|
||||||
|
</step>
|
||||||
|
|
||||||
|
<step number="3">
|
||||||
|
<description>Implementation step</description>
|
||||||
|
<approach>
|
||||||
|
Apply the planned changes (localized edits when possible; full rewrites only when intentional).
|
||||||
|
Outcome: required changes applied to the repository.
|
||||||
|
</approach>
|
||||||
|
</step>
|
||||||
|
</workflow>
|
||||||
|
|
||||||
|
<completion>
|
||||||
|
Provide a concise summary of what was accomplished and how it addresses the user's request.
|
||||||
|
</completion>
|
||||||
|
|
||||||
|
<key_takeaways>
|
||||||
|
<takeaway>Important lesson from this example</takeaway>
|
||||||
|
<takeaway>Pattern that can be reused</takeaway>
|
||||||
|
</key_takeaways>
|
||||||
|
</example>
|
||||||
|
</complete_examples>
|
||||||
|
</template>
|
||||||
|
</examples_file_template>
|
||||||
|
|
||||||
|
<communication_template>
|
||||||
|
<description>Template for communication guidelines (7_communication.xml)</description>
|
||||||
|
<template>
|
||||||
|
<communication_guidelines>
|
||||||
|
<tone_and_style>
|
||||||
|
<principle>Be direct and technical, not conversational</principle>
|
||||||
|
<principle>Focus on actions taken and results achieved</principle>
|
||||||
|
<avoid>
|
||||||
|
<phrase>Great! I'll help you with that...</phrase>
|
||||||
|
<phrase>Certainly! Let me...</phrase>
|
||||||
|
<phrase>Sure thing!</phrase>
|
||||||
|
</avoid>
|
||||||
|
<prefer>
|
||||||
|
<phrase>I'll analyze the codebase to...</phrase>
|
||||||
|
<phrase>Implementing the requested changes...</phrase>
|
||||||
|
<phrase>The analysis shows...</phrase>
|
||||||
|
</prefer>
|
||||||
|
</tone_and_style>
|
||||||
|
|
||||||
|
<verbosity>
|
||||||
|
<policy>Keep narrative brief; prefer concise status updates</policy>
|
||||||
|
<policy>Provide high detail only inside code/diffs and structured outputs</policy>
|
||||||
|
<policy>Favor clarity over cleverness; avoid code-golf and cryptic names</policy>
|
||||||
|
</verbosity>
|
||||||
|
|
||||||
|
<user_interaction>
|
||||||
|
<when_to_ask_questions>
|
||||||
|
<scenario>Missing critical information</scenario>
|
||||||
|
<scenario>Multiple valid approaches exist</scenario>
|
||||||
|
<scenario>Potential breaking changes</scenario>
|
||||||
|
</when_to_ask_questions>
|
||||||
|
|
||||||
|
<question_format>
|
||||||
|
<guideline>Be specific about what you need</guideline>
|
||||||
|
<guideline>Provide actionable options</guideline>
|
||||||
|
<guideline>Explain implications of choices</guideline>
|
||||||
|
</question_format>
|
||||||
|
</user_interaction>
|
||||||
|
|
||||||
|
<progress_updates>
|
||||||
|
<when>During long-running operations</when>
|
||||||
|
<format>
|
||||||
|
<update>Analyzing [X] files for [purpose]...</update>
|
||||||
|
<update>Implementing [feature] in [location]...</update>
|
||||||
|
<update>Validating changes against [criteria]...</update>
|
||||||
|
</format>
|
||||||
|
</progress_updates>
|
||||||
|
|
||||||
|
<completion_messages>
|
||||||
|
<structure>
|
||||||
|
<element>What was accomplished</element>
|
||||||
|
<element>Key changes made</element>
|
||||||
|
<element>Any important notes or warnings</element>
|
||||||
|
</structure>
|
||||||
|
<avoid>
|
||||||
|
<element>Questions at the end</element>
|
||||||
|
<element>Offers for further assistance</element>
|
||||||
|
<element>Conversational closings</element>
|
||||||
|
</avoid>
|
||||||
|
</completion_messages>
|
||||||
|
</communication_guidelines>
|
||||||
|
</template>
|
||||||
|
</communication_template>
|
||||||
|
</instruction_file_templates>
|
||||||
@@ -0,0 +1,91 @@
|
|||||||
|
<complete_examples>
|
||||||
|
<overview>
|
||||||
|
Canonical examples for creating and editing Roo Code modes. Each example demonstrates structured workflows, least-privilege configuration, contradiction resolution, and completion formatting, without referencing runtime implementation details.
|
||||||
|
</overview>
|
||||||
|
|
||||||
|
<example name="mode_editing_enhancement">
|
||||||
|
<scenario>
|
||||||
|
Edit the Test mode to add benchmark testing and performance guidance using Vitest's bench API.
|
||||||
|
</scenario>
|
||||||
|
<user_request>
|
||||||
|
I want to edit the test mode to add benchmark testing support.
|
||||||
|
</user_request>
|
||||||
|
<workflow>
|
||||||
|
<step number="1">
|
||||||
|
<description>Clarify scope and features</description>
|
||||||
|
<guidance>
|
||||||
|
Ask the user a focused clarifying question to confirm which scope/features to include; provide 2–4 actionable options. Outcome: selected scope.
|
||||||
|
</guidance>
|
||||||
|
<expected_outcome>User selects: Add benchmark testing with Vitest bench API</expected_outcome>
|
||||||
|
</step>
|
||||||
|
|
||||||
|
<step number="2">
|
||||||
|
<description>Immerse in current mode config and instructions</description>
|
||||||
|
<guidance>
|
||||||
|
Review .roomodes, inventory .roo/rules-test recursively, and review .roo/rules-test/1_workflow.xml. Outcome: confirm roleDefinition, file restrictions, and existing workflows.
|
||||||
|
</guidance>
|
||||||
|
<analysis>Confirm roleDefinition, file restrictions, and existing workflows.</analysis>
|
||||||
|
</step>
|
||||||
|
|
||||||
|
<step number="3">
|
||||||
|
<description>Update roleDefinition in .roomodes</description>
|
||||||
|
<guidance>
|
||||||
|
Edit .roomodes to update the roleDefinition, adding benchmark testing and performance guidance topics. Outcome: roleDefinition updated to include performance/bench themes.
|
||||||
|
</guidance>
|
||||||
|
</step>
|
||||||
|
|
||||||
|
<step number="4">
|
||||||
|
<description>Extend file restrictions to include .bench files</description>
|
||||||
|
<guidance>
|
||||||
|
Edit .roomodes to extend the fileRegex to include .bench.(ts|tsx|js|jsx) and update the description accordingly. Outcome: file restrictions now cover benchmark files.
|
||||||
|
</guidance>
|
||||||
|
</step>
|
||||||
|
|
||||||
|
<step number="5">
|
||||||
|
<description>Create benchmark guidance file</description>
|
||||||
|
<guidance>
|
||||||
|
Create a new file at .roo/rules-test/5_benchmark_testing.xml with guidance and examples. Outcome: new guidance file available to the mode.
|
||||||
|
</guidance>
|
||||||
|
<artifact_sample>
|
||||||
|
<benchmark_testing_guide>
|
||||||
|
<overview>Guidelines for performance benchmarks using Vitest bench API</overview>
|
||||||
|
<benchmark_patterns>
|
||||||
|
<pattern name="basic_benchmark">
|
||||||
|
<description>Basic structure</description>
|
||||||
|
<example>
|
||||||
|
import { bench, describe } from 'vitest';
|
||||||
|
|
||||||
|
|
||||||
|
describe('Array operations', () => {
|
||||||
|
bench('Array.push', () => {
|
||||||
|
const arr: number[] = [];
|
||||||
|
for (let i = 0; i < 1000; i++) arr.push(i);
|
||||||
|
});
|
||||||
|
|
||||||
|
bench('Array spread', () => {
|
||||||
|
let arr: number[] = [];
|
||||||
|
for (let i = 0; i < 1000; i++) arr = [...arr, i];
|
||||||
|
});
|
||||||
|
});
|
||||||
|
</example>
|
||||||
|
</pattern>
|
||||||
|
</benchmark_patterns>
|
||||||
|
<best_practices>
|
||||||
|
<practice>Use meaningful names and isolate benchmarks</practice>
|
||||||
|
<practice>Document expectations and thresholds</practice>
|
||||||
|
</best_practices>
|
||||||
|
</benchmark_testing_guide>
|
||||||
|
</artifact_sample>
|
||||||
|
</step>
|
||||||
|
</workflow>
|
||||||
|
|
||||||
|
<completion>
|
||||||
|
Provide a concise summary of what was accomplished and how it addresses the user's request.
|
||||||
|
</completion>
|
||||||
|
|
||||||
|
<key_takeaways>
|
||||||
|
<takeaway>Important lesson from this example</takeaway>
|
||||||
|
<takeaway>Pattern that can be reused</takeaway>
|
||||||
|
</key_takeaways>
|
||||||
|
</example>
|
||||||
|
</complete_examples>
|
||||||
@@ -0,0 +1,186 @@
|
|||||||
|
<mode_testing_validation>
|
||||||
|
<overview>
|
||||||
|
Guidelines for testing and validating newly created modes to ensure they function correctly and integrate well with the Roo Code ecosystem.
|
||||||
|
</overview>
|
||||||
|
|
||||||
|
<validation_checklist>
|
||||||
|
<category name="configuration_validation">
|
||||||
|
<item priority="critical">
|
||||||
|
<check>Mode slug is unique and follows naming conventions</check>
|
||||||
|
<validation>No spaces, lowercase, hyphens only</validation>
|
||||||
|
</item>
|
||||||
|
<item priority="critical">
|
||||||
|
<check>All required fields are present and non-empty</check>
|
||||||
|
<fields>slug, name, roleDefinition, groups</fields>
|
||||||
|
</item>
|
||||||
|
<item priority="critical">
|
||||||
|
<check>Avoid large customInstructions blocks in .roomodes</check>
|
||||||
|
<validation>
|
||||||
|
Prefer storing substantial mode guidance in XML files under <code>.roo/rules-[slug]/</code>.
|
||||||
|
Small, high-level glue text in <code>customInstructions</code> is acceptable when needed.
|
||||||
|
</validation>
|
||||||
|
</item>
|
||||||
|
<item priority="high">
|
||||||
|
<check>File restrictions use valid regex patterns</check>
|
||||||
|
<test_method>Validate by comparing the regex pattern against the intended file sets; confirm patterns match intended files and avoid overbroad matches.</test_method>
|
||||||
|
</item>
|
||||||
|
<item priority="high">
|
||||||
|
<check>whenToUse clearly differentiates from other modes</check>
|
||||||
|
<validation>Compare with existing mode descriptions</validation>
|
||||||
|
</item>
|
||||||
|
</category>
|
||||||
|
|
||||||
|
<category name="instruction_validation">
|
||||||
|
<item>
|
||||||
|
<check>XML files are well-formed and valid</check>
|
||||||
|
<validation>No syntax errors, proper closing tags</validation>
|
||||||
|
</item>
|
||||||
|
<item>
|
||||||
|
<check>Instructions follow XML best practices</check>
|
||||||
|
<validation>Semantic tag names, proper nesting</validation>
|
||||||
|
</item>
|
||||||
|
<item>
|
||||||
|
<check>Examples avoid runtime implementation details</check>
|
||||||
|
<validation>Examples align with current permissions and constraints</validation>
|
||||||
|
</item>
|
||||||
|
<item>
|
||||||
|
<check>File paths in examples are consistent</check>
|
||||||
|
<validation>Use project-relative paths</validation>
|
||||||
|
</item>
|
||||||
|
</category>
|
||||||
|
|
||||||
|
<category name="functional_testing">
|
||||||
|
<item>
|
||||||
|
<check>Mode appears in mode list</check>
|
||||||
|
<test>Switch to the new mode and verify it loads</test>
|
||||||
|
</item>
|
||||||
|
<item>
|
||||||
|
<check>Permissions work as expected</check>
|
||||||
|
<test>Verify representative actions for each permission category</test>
|
||||||
|
</item>
|
||||||
|
<item>
|
||||||
|
<check>File restrictions are enforced</check>
|
||||||
|
<test>Attempt to edit allowed and restricted files</test>
|
||||||
|
</item>
|
||||||
|
<item>
|
||||||
|
<check>Mode handles edge cases gracefully</check>
|
||||||
|
<test>Test with minimal input, errors, edge cases</test>
|
||||||
|
</item>
|
||||||
|
</category>
|
||||||
|
</validation_checklist>
|
||||||
|
|
||||||
|
<testing_workflow>
|
||||||
|
<step number="1">
|
||||||
|
<title>Configuration Testing</title>
|
||||||
|
<actions>
|
||||||
|
<action>Verify mode appears in available modes list</action>
|
||||||
|
<action>Check that mode metadata displays correctly</action>
|
||||||
|
<action>Confirm mode can be activated</action>
|
||||||
|
</actions>
|
||||||
|
<verification>Confirm via user feedback. If unclear, ask a focused clarifying question with options like: "Visible and switchable", "Not visible", or "Visible but errors".</verification>
|
||||||
|
</step>
|
||||||
|
|
||||||
|
<step number="2">
|
||||||
|
<title>Permission Testing</title>
|
||||||
|
<test_cases>
|
||||||
|
<test case="read_permissions">
|
||||||
|
<action>Verify read access works for representative files</action>
|
||||||
|
<expected>All read operations should work</expected>
|
||||||
|
</test>
|
||||||
|
<test case="edit_restrictions">
|
||||||
|
<action>Try editing allowed file types</action>
|
||||||
|
<expected>Edits succeed for matching patterns</expected>
|
||||||
|
</test>
|
||||||
|
<test case="edit_restrictions_negative">
|
||||||
|
<action>Try editing restricted file types</action>
|
||||||
|
<expected>An explicit permission/restriction error for non-matching files</expected>
|
||||||
|
</test>
|
||||||
|
</test_cases>
|
||||||
|
</step>
|
||||||
|
|
||||||
|
<step number="3">
|
||||||
|
<title>Workflow Testing</title>
|
||||||
|
<actions>
|
||||||
|
<action>Execute main workflow from start to finish</action>
|
||||||
|
<action>Test each decision point</action>
|
||||||
|
<action>Verify error handling</action>
|
||||||
|
<action>Check completion criteria</action>
|
||||||
|
</actions>
|
||||||
|
</step>
|
||||||
|
|
||||||
|
<step number="4">
|
||||||
|
<title>Integration Testing</title>
|
||||||
|
<areas>
|
||||||
|
<area>Orchestrator mode compatibility</area>
|
||||||
|
<area>Mode switching functionality</area>
|
||||||
|
<area>Capability handoff between modes</area>
|
||||||
|
<area>Consistent behavior with other modes</area>
|
||||||
|
</areas>
|
||||||
|
</step>
|
||||||
|
</testing_workflow>
|
||||||
|
|
||||||
|
<common_issues>
|
||||||
|
<issue type="configuration">
|
||||||
|
<problem>Mode doesn't appear in list</problem>
|
||||||
|
<causes>
|
||||||
|
<cause>Syntax error in YAML</cause>
|
||||||
|
<cause>Invalid mode slug</cause>
|
||||||
|
<cause>File not saved</cause>
|
||||||
|
</causes>
|
||||||
|
<solution>Check YAML syntax, validate slug format</solution>
|
||||||
|
</issue>
|
||||||
|
|
||||||
|
<issue type="permissions">
|
||||||
|
<problem>File restriction not working</problem>
|
||||||
|
<causes>
|
||||||
|
<cause>Invalid regex pattern</cause>
|
||||||
|
<cause>Escaping issues in regex</cause>
|
||||||
|
<cause>Wrong file path format</cause>
|
||||||
|
</causes>
|
||||||
|
<solution>Test regex pattern, use proper escaping</solution>
|
||||||
|
<example>
|
||||||
|
# Wrong: *.ts (glob pattern)
|
||||||
|
|
||||||
|
# Right: .*\.ts$ (regex pattern)
|
||||||
|
</example>
|
||||||
|
</issue>
|
||||||
|
|
||||||
|
<issue type="behavior">
|
||||||
|
<problem>Mode not following instructions</problem>
|
||||||
|
<causes>
|
||||||
|
<cause>Instructions not in .roo/rules-[slug]/ folder</cause>
|
||||||
|
<cause>XML parsing errors</cause>
|
||||||
|
<cause>Conflicting instructions</cause>
|
||||||
|
</causes>
|
||||||
|
<solution>Verify file locations and XML validity</solution>
|
||||||
|
</issue>
|
||||||
|
</common_issues>
|
||||||
|
|
||||||
|
<debugging_practices>
|
||||||
|
<practice>
|
||||||
|
<name>Directory/file inventory</name>
|
||||||
|
<usage>Verify instruction files exist in the correct location</usage>
|
||||||
|
<guidance>Check the .roo directory structure and ensure the expected rules-[slug] folder and XML files exist.</guidance>
|
||||||
|
</practice>
|
||||||
|
|
||||||
|
<practice>
|
||||||
|
<name>Configuration review</name>
|
||||||
|
<usage>Check mode configuration syntax</usage>
|
||||||
|
<guidance>Review .roomodes to validate YAML structure and entries for the target mode.</guidance>
|
||||||
|
</practice>
|
||||||
|
|
||||||
|
<practice>
|
||||||
|
<name>Regex validation</name>
|
||||||
|
<usage>Test file restriction patterns</usage>
|
||||||
|
<guidance>Use targeted checks conceptually to confirm fileRegex patterns match intended files and exclude others.</guidance>
|
||||||
|
</practice>
|
||||||
|
</debugging_practices>
|
||||||
|
|
||||||
|
<best_practices>
|
||||||
|
<practice>Test incrementally as you build the mode</practice>
|
||||||
|
<practice>Start with minimal configuration and add complexity</practice>
|
||||||
|
<practice>Document any special requirements or dependencies</practice>
|
||||||
|
<practice>Consider edge cases and error scenarios</practice>
|
||||||
|
<practice>Get feedback from potential users of the mode</practice>
|
||||||
|
</best_practices>
|
||||||
|
</mode_testing_validation>
|
||||||
@@ -0,0 +1,194 @@
|
|||||||
|
<validation_cohesion_checking>
|
||||||
|
<overview>
|
||||||
|
Guidelines for thoroughly validating mode changes to ensure cohesion,
|
||||||
|
consistency, and prevent contradictions across all mode components.
|
||||||
|
</overview>
|
||||||
|
|
||||||
|
<validation_principles>
|
||||||
|
<principle name="comprehensive_review">
|
||||||
|
<description>
|
||||||
|
Every change must be reviewed in context of the entire mode
|
||||||
|
</description>
|
||||||
|
<checklist>
|
||||||
|
<item>Read all existing XML instruction files</item>
|
||||||
|
<item>Verify new changes align with existing patterns</item>
|
||||||
|
<item>Check for duplicate or conflicting instructions</item>
|
||||||
|
<item>Ensure terminology is consistent throughout</item>
|
||||||
|
</checklist>
|
||||||
|
</principle>
|
||||||
|
|
||||||
|
<principle name="focused_questioning">
|
||||||
|
<description>
|
||||||
|
Ask focused clarifying questions only when needed to de-risk the work
|
||||||
|
</description>
|
||||||
|
<when_to_ask>
|
||||||
|
<scenario>Critical details are missing (cannot proceed safely)</scenario>
|
||||||
|
<scenario>Multiple valid approaches exist and the tradeoffs matter</scenario>
|
||||||
|
<scenario>Proposed changes are risky/irreversible (permissions, deletions, broad refactors)</scenario>
|
||||||
|
<scenario>A change may require widening permissions or fileRegex patterns</scenario>
|
||||||
|
</when_to_ask>
|
||||||
|
<example>
|
||||||
|
In practice: ask a focused question with 2–4 actionable options.
|
||||||
|
Example:
|
||||||
|
- Question: "This change may affect file permissions. Should we also update the fileRegex patterns?"
|
||||||
|
- Options:
|
||||||
|
1) "Yes, include the new file types in the regex"
|
||||||
|
2) "No, keep current restrictions"
|
||||||
|
3) "I need to list the file types I’ll work with"
|
||||||
|
4) "Show me the current restrictions first"
|
||||||
|
</example>
|
||||||
|
</principle>
|
||||||
|
|
||||||
|
<principle name="contradiction_detection">
|
||||||
|
<description>
|
||||||
|
Actively search for and resolve contradictions
|
||||||
|
</description>
|
||||||
|
<common_contradictions>
|
||||||
|
<contradiction>
|
||||||
|
<type>Permission Mismatch</type>
|
||||||
|
<description>Instructions reference permissions the mode doesn't have</description>
|
||||||
|
<resolution>Either grant the permission or update the instructions</resolution>
|
||||||
|
</contradiction>
|
||||||
|
<contradiction>
|
||||||
|
<type>Workflow Conflicts</type>
|
||||||
|
<description>Different XML files describe conflicting workflows</description>
|
||||||
|
<resolution>Consolidate workflows and ensure single source of truth</resolution>
|
||||||
|
</contradiction>
|
||||||
|
<contradiction>
|
||||||
|
<type>Role Confusion</type>
|
||||||
|
<description>Mode's roleDefinition doesn't match its actual scope/permissions</description>
|
||||||
|
<resolution>Update roleDefinition to accurately reflect the mode's purpose</resolution>
|
||||||
|
</contradiction>
|
||||||
|
</common_contradictions>
|
||||||
|
</principle>
|
||||||
|
</validation_principles>
|
||||||
|
|
||||||
|
<validation_workflow>
|
||||||
|
<phase name="pre_change_analysis">
|
||||||
|
<description>Before making any changes</description>
|
||||||
|
<steps>
|
||||||
|
<step>Read and understand all existing mode files</step>
|
||||||
|
<step>Create a mental model of current mode behavior</step>
|
||||||
|
<step>Identify potential impact areas</step>
|
||||||
|
<step>Ask clarifying questions about intended changes</step>
|
||||||
|
</steps>
|
||||||
|
</phase>
|
||||||
|
|
||||||
|
<phase name="change_implementation">
|
||||||
|
<description>While making changes</description>
|
||||||
|
<steps>
|
||||||
|
<step>Document each change and its rationale</step>
|
||||||
|
<step>Cross-reference with other files after each change</step>
|
||||||
|
<step>Verify examples still work with new changes</step>
|
||||||
|
<step>Update related documentation immediately</step>
|
||||||
|
</steps>
|
||||||
|
</phase>
|
||||||
|
|
||||||
|
<phase name="post_change_validation">
|
||||||
|
<description>After changes are complete</description>
|
||||||
|
<validation_checklist>
|
||||||
|
<category name="structural_validation">
|
||||||
|
<check>All XML files are well-formed and valid</check>
|
||||||
|
<check>File naming follows established patterns</check>
|
||||||
|
<check>Tag names are consistent across files</check>
|
||||||
|
<check>No orphaned or unused instructions</check>
|
||||||
|
</category>
|
||||||
|
|
||||||
|
<category name="content_validation">
|
||||||
|
<check>roleDefinition accurately describes the mode</check>
|
||||||
|
<check>whenToUse is clear and distinguishable</check>
|
||||||
|
<check>Permissions match instruction requirements</check>
|
||||||
|
<check>File restrictions align with mode purpose</check>
|
||||||
|
<check>Examples are accurate and functional</check>
|
||||||
|
</category>
|
||||||
|
|
||||||
|
<category name="integration_validation">
|
||||||
|
<check>Mode boundaries are well-defined</check>
|
||||||
|
<check>Handoff points to other modes are clear</check>
|
||||||
|
<check>No overlap with other modes' responsibilities</check>
|
||||||
|
<check>Orchestrator can correctly route to this mode</check>
|
||||||
|
</category>
|
||||||
|
</validation_checklist>
|
||||||
|
</phase>
|
||||||
|
</validation_workflow>
|
||||||
|
|
||||||
|
<cohesion_patterns>
|
||||||
|
<pattern name="consistent_voice">
|
||||||
|
<description>Maintain consistent tone and terminology</description>
|
||||||
|
<guidelines>
|
||||||
|
<guideline>Use the same terms for the same concepts throughout</guideline>
|
||||||
|
<guideline>Keep instruction style consistent across files</guideline>
|
||||||
|
<guideline>Maintain the same level of detail in similar sections</guideline>
|
||||||
|
</guidelines>
|
||||||
|
</pattern>
|
||||||
|
|
||||||
|
<pattern name="logical_flow">
|
||||||
|
<description>Ensure instructions flow logically</description>
|
||||||
|
<guidelines>
|
||||||
|
<guideline>Prerequisites come before dependent steps</guideline>
|
||||||
|
<guideline>Complex concepts build on simpler ones</guideline>
|
||||||
|
<guideline>Examples follow the explained patterns</guideline>
|
||||||
|
</guidelines>
|
||||||
|
</pattern>
|
||||||
|
|
||||||
|
<pattern name="complete_coverage">
|
||||||
|
<description>Ensure all aspects are covered without gaps</description>
|
||||||
|
<guidelines>
|
||||||
|
<guideline>Every mentioned concept has decision guidance (what/when) without runtime implementation details</guideline>
|
||||||
|
<guideline>All workflows have complete examples</guideline>
|
||||||
|
<guideline>Error scenarios are addressed</guideline>
|
||||||
|
</guidelines>
|
||||||
|
</pattern>
|
||||||
|
</cohesion_patterns>
|
||||||
|
|
||||||
|
<validation_questions>
|
||||||
|
<question_set name="before_changes">
|
||||||
|
<prompt>
|
||||||
|
Before we proceed with changes, ensure the main goal is clear. Suggested options:
|
||||||
|
- Add new functionality while keeping existing features
|
||||||
|
- Fix issues with current implementation
|
||||||
|
- Refactor for better organization
|
||||||
|
- Expand the mode's scope into new areas
|
||||||
|
</prompt>
|
||||||
|
</question_set>
|
||||||
|
|
||||||
|
<question_set name="during_changes">
|
||||||
|
<prompt>
|
||||||
|
This change might affect other parts of the mode. Choose an approach:
|
||||||
|
- Update all affected areas to maintain consistency
|
||||||
|
- Keep the existing behavior for backward compatibility
|
||||||
|
- Create a migration path from old to new behavior
|
||||||
|
- Review the impact first
|
||||||
|
</prompt>
|
||||||
|
</question_set>
|
||||||
|
|
||||||
|
<question_set name="after_changes">
|
||||||
|
<prompt>
|
||||||
|
Post-change testing focus areas:
|
||||||
|
- Test the new workflow end-to-end
|
||||||
|
- Verify file permissions work correctly
|
||||||
|
- Check integration with other modes
|
||||||
|
- Review all changes one more time
|
||||||
|
</prompt>
|
||||||
|
</question_set>
|
||||||
|
</validation_questions>
|
||||||
|
|
||||||
|
<red_flags>
|
||||||
|
<flag priority="high">
|
||||||
|
<description>Instructions reference permissions not in the mode's groups</description>
|
||||||
|
<action>Either add the permission group or remove/update the instruction</action>
|
||||||
|
</flag>
|
||||||
|
<flag priority="high">
|
||||||
|
<description>File regex doesn't match described file types</description>
|
||||||
|
<action>Update regex pattern to match intended files</action>
|
||||||
|
</flag>
|
||||||
|
<flag priority="medium">
|
||||||
|
<description>Examples don't follow stated best practices</description>
|
||||||
|
<action>Update examples to demonstrate best practices</action>
|
||||||
|
</flag>
|
||||||
|
<flag priority="medium">
|
||||||
|
<description>Duplicate instructions in different files</description>
|
||||||
|
<action>Consolidate to single location and reference</action>
|
||||||
|
</flag>
|
||||||
|
</red_flags>
|
||||||
|
</validation_cohesion_checking>
|
||||||
@@ -0,0 +1,51 @@
|
|||||||
|
<global_modes_reference>
|
||||||
|
<overview>
|
||||||
|
This reference documents how global (system-wide) modes work, where they live, and how they interact
|
||||||
|
with workspace-scoped modes.
|
||||||
|
</overview>
|
||||||
|
|
||||||
|
<locations>
|
||||||
|
<workspace>
|
||||||
|
<file>.roomodes</file>
|
||||||
|
<scope>Per-workspace (project) modes</scope>
|
||||||
|
</workspace>
|
||||||
|
|
||||||
|
<global>
|
||||||
|
<file>Global custom modes settings file (stored in VS Code globalStorage; exact path is environment-specific)</file>
|
||||||
|
<scope>System-wide modes for Roo Code</scope>
|
||||||
|
<notes>
|
||||||
|
This file is created automatically on Roo Code startup if it does not exist.
|
||||||
|
</notes>
|
||||||
|
</global>
|
||||||
|
</locations>
|
||||||
|
|
||||||
|
<precedence>
|
||||||
|
<rule>
|
||||||
|
When a mode with the same slug exists in both locations, the workspace (.roomodes) version takes precedence.
|
||||||
|
</rule>
|
||||||
|
<implications>
|
||||||
|
<implication>
|
||||||
|
Editing the global mode may have no visible effect inside a workspace that overrides the same slug.
|
||||||
|
</implication>
|
||||||
|
<implication>
|
||||||
|
To change behavior in one repo only, prefer editing .roomodes.
|
||||||
|
</implication>
|
||||||
|
</implications>
|
||||||
|
</precedence>
|
||||||
|
|
||||||
|
<workflow_guidance>
|
||||||
|
<decision>
|
||||||
|
<rule>Default to editing .roomodes unless the user explicitly requests global scope.</rule>
|
||||||
|
<rule>
|
||||||
|
If the user asks for global scope, first check whether a workspace override exists for the same slug.
|
||||||
|
If it does, explain the precedence and offer to edit both.
|
||||||
|
</rule>
|
||||||
|
</decision>
|
||||||
|
|
||||||
|
<safe_editing_principles>
|
||||||
|
<principle>
|
||||||
|
Prefer minimal, targeted changes and preserve YAML formatting.
|
||||||
|
</principle>
|
||||||
|
</safe_editing_principles>
|
||||||
|
</workflow_guidance>
|
||||||
|
</global_modes_reference>
|
||||||
@@ -0,0 +1,116 @@
|
|||||||
|
<workflow_instructions>
|
||||||
|
<mode_overview>
|
||||||
|
Create, edit, and validate Agent Skills packages (SKILL.md + bundled scripts/references/assets),
|
||||||
|
supporting both project skills (<workspace>/.roo/skills*) and global skills (<home>/.roo/skills*),
|
||||||
|
including generic and mode-specific skills.
|
||||||
|
</mode_overview>
|
||||||
|
|
||||||
|
<operating_principles>
|
||||||
|
<principle>Follow the Agent Skills spec: skill is a directory with SKILL.md (required) and YAML frontmatter.</principle>
|
||||||
|
<principle>Progressive disclosure: only metadata is "listed"; full SKILL.md and other files are loaded/used only when needed.</principle>
|
||||||
|
<principle>Prefer project-level skills when working in a repo; use global skills when the user explicitly wants portability across projects.</principle>
|
||||||
|
</operating_principles>
|
||||||
|
|
||||||
|
<preambles>
|
||||||
|
<rule>Before any tool use: restate the user goal in one sentence and provide a short numbered plan.</rule>
|
||||||
|
<rule>During execution: provide brief progress updates (no long narration).</rule>
|
||||||
|
<rule>Finish: summarize what changed and how it meets the spec.</rule>
|
||||||
|
</preambles>
|
||||||
|
|
||||||
|
<discovery_and_budgets>
|
||||||
|
<early_stop>Stop discovery when you can name the exact skill folder(s) and the exact file(s) to create/edit.</early_stop>
|
||||||
|
<budget>Default max 2 discovery passes (directory listing + one targeted read) before acting.</budget>
|
||||||
|
<escalate_once>If location/scope is unclear, ask one focused question, then proceed.</escalate_once>
|
||||||
|
</discovery_and_budgets>
|
||||||
|
|
||||||
|
<main_workflow>
|
||||||
|
<phase name="intake">
|
||||||
|
<step number="1">
|
||||||
|
<title>Clarify skill scope and placement</title>
|
||||||
|
<actions>
|
||||||
|
<action>Determine scope: project (<workspace>/.roo/skills*) vs global (<home>/.roo/skills*)</action>
|
||||||
|
<action>Determine specificity: generic (skills/) vs mode-specific (skills-<mode>/)</action>
|
||||||
|
<action>Determine operation: create new skill, edit existing, or audit</action>
|
||||||
|
<action>Default to project + generic unless the user explicitly requests global and/or mode-specific</action>
|
||||||
|
</actions>
|
||||||
|
<acceptance_criteria>
|
||||||
|
<criterion>Target root directory and skill name are unambiguous</criterion>
|
||||||
|
</acceptance_criteria>
|
||||||
|
</step>
|
||||||
|
|
||||||
|
<step number="2">
|
||||||
|
<title>Establish the canonical skill name</title>
|
||||||
|
<actions>
|
||||||
|
<action>Choose a spec-compliant name (lowercase letters, numbers, hyphens; 1–64 chars; no leading/trailing hyphen; no consecutive hyphens)</action>
|
||||||
|
<action>Ensure directory (or symlink alias) name matches frontmatter name exactly</action>
|
||||||
|
</actions>
|
||||||
|
</step>
|
||||||
|
</phase>
|
||||||
|
|
||||||
|
<phase name="authoring">
|
||||||
|
<step number="3">
|
||||||
|
<title>Draft SKILL.md frontmatter and outline</title>
|
||||||
|
<actions>
|
||||||
|
<action>Write YAML frontmatter with required fields: name, description</action>
|
||||||
|
<action>Optionally include license, compatibility, metadata, allowed-tools (do not assume enforcement)</action>
|
||||||
|
<action>Write a concise "When to use" section and a step-by-step workflow section</action>
|
||||||
|
</actions>
|
||||||
|
<quality_gates>
|
||||||
|
<gate>Description explains what the skill does AND when to use it, with keywords for matching</gate>
|
||||||
|
<gate>Instructions are actionable and ordered</gate>
|
||||||
|
</quality_gates>
|
||||||
|
</step>
|
||||||
|
|
||||||
|
<step number="3.1">
|
||||||
|
<title>Choose structure (single-file vs multi-file)</title>
|
||||||
|
<actions>
|
||||||
|
<action>Default to SKILL.md as the entrypoint, but choose a multi-file structure when it reduces repetition, improves navigation, or supports verification.</action>
|
||||||
|
<action>Use references/ for long-lived guidance (APIs, checklists, domain subtopics).</action>
|
||||||
|
<action>Use scripts/ for deterministic automation/validation; prefer executable scripts for repeatable checks.</action>
|
||||||
|
<action>Use assets/ for templates or example artifacts that should not live inline in SKILL.md.</action>
|
||||||
|
<action>Link all reference files directly from SKILL.md; avoid multi-hop references.</action>
|
||||||
|
</actions>
|
||||||
|
<acceptance_criteria>
|
||||||
|
<criterion>SKILL.md makes it clear which linked file to read next (and when) and which scripts to execute (and when)</criterion>
|
||||||
|
</acceptance_criteria>
|
||||||
|
</step>
|
||||||
|
|
||||||
|
<step number="4">
|
||||||
|
<title>Add optional resources (only if they improve execution)</title>
|
||||||
|
<actions>
|
||||||
|
<action>Create scripts/ only when automation is genuinely useful and the user explicitly agrees; otherwise keep instructions manual</action>
|
||||||
|
<action>Create references/ only when it materially improves execution and the user explicitly agrees; keep SKILL.md lean</action>
|
||||||
|
<action>Create assets/ only when it materially improves execution and the user explicitly agrees (templates, example files, diagrams)</action>
|
||||||
|
</actions>
|
||||||
|
</step>
|
||||||
|
</phase>
|
||||||
|
|
||||||
|
<phase name="validation">
|
||||||
|
<step number="5">
|
||||||
|
<title>Validate spec compliance (minimum checks)</title>
|
||||||
|
<checks>
|
||||||
|
<check>SKILL.md exists at skill root</check>
|
||||||
|
<check>Frontmatter contains name + description</check>
|
||||||
|
<check>Frontmatter name matches directory (or symlink alias) name</check>
|
||||||
|
<check>Name constraints: 1–64 chars; lowercase letters/numbers/hyphens only; no leading/trailing hyphen; no consecutive hyphens</check>
|
||||||
|
<check>Description constraints: non-empty after trimming; max 1024 characters</check>
|
||||||
|
<check>File references use relative paths and remain shallow</check>
|
||||||
|
</checks>
|
||||||
|
</step>
|
||||||
|
|
||||||
|
<step number="6">
|
||||||
|
<title>Handoff and activation guidance</title>
|
||||||
|
<actions>
|
||||||
|
<action>Ensure the description includes trigger keywords so the model can match it reliably</action>
|
||||||
|
<action>Ensure the first section tells the model when NOT to use the skill and what to do instead</action>
|
||||||
|
</actions>
|
||||||
|
</step>
|
||||||
|
</phase>
|
||||||
|
</main_workflow>
|
||||||
|
|
||||||
|
<completion_criteria>
|
||||||
|
<criterion>Skill folder structure is correct and includes SKILL.md</criterion>
|
||||||
|
<criterion>Frontmatter passes required constraints</criterion>
|
||||||
|
<criterion>Instructions are clear, safe, and usable</criterion>
|
||||||
|
</completion_criteria>
|
||||||
|
</workflow_instructions>
|
||||||
@@ -0,0 +1,94 @@
|
|||||||
|
<best_practices>
|
||||||
|
<authoring>
|
||||||
|
<guideline priority="high">
|
||||||
|
<rule>Assume the agent already understands common concepts; only include context that changes decisions or prevents mistakes.</rule>
|
||||||
|
<rationale>Reduces token load after a skill is selected and keeps instructions focused on what is unique to the workflow or project.</rationale>
|
||||||
|
</guideline>
|
||||||
|
|
||||||
|
<guideline priority="high">
|
||||||
|
<rule>Write the frontmatter description in third person, and include both what the skill does and when to use it.</rule>
|
||||||
|
<rationale>The description is injected into the system prompt and is used for skill selection; point-of-view drift reduces match quality.</rationale>
|
||||||
|
</guideline>
|
||||||
|
|
||||||
|
<guideline priority="high">
|
||||||
|
<rule>Keep SKILL.md as an entrypoint: a concise overview + clear navigation to any linked reference files.</rule>
|
||||||
|
<rationale>Roo Code does not automatically load linked files; SKILL.md must make it obvious which file to read next (and why).</rationale>
|
||||||
|
</guideline>
|
||||||
|
|
||||||
|
<guideline priority="high">
|
||||||
|
<rule>Choose an appropriate degree of freedom: use strict, step-by-step instructions for fragile workflows; use heuristics when multiple approaches are valid.</rule>
|
||||||
|
<rationale>Overly rigid skills break in novel contexts; overly loose skills skip validation in high-stakes workflows.</rationale>
|
||||||
|
</guideline>
|
||||||
|
|
||||||
|
<guideline priority="high">
|
||||||
|
<rule>Write descriptions for retrieval: include concrete keywords, tools, file types, and user phrasing triggers.</rule>
|
||||||
|
<rationale>Improves selection accuracy during skill matching.</rationale>
|
||||||
|
</guideline>
|
||||||
|
|
||||||
|
<guideline priority="high">
|
||||||
|
<rule>Make the description actionable: describe what the skill DOES and when to use it.</rule>
|
||||||
|
<rationale>Vague descriptions reduce match quality and increase false positives/negatives.</rationale>
|
||||||
|
</guideline>
|
||||||
|
|
||||||
|
<guideline priority="high">
|
||||||
|
<rule>Start SKILL.md with "When to use" and "When NOT to use".</rule>
|
||||||
|
<rationale>Prevents accidental activation and reduces false positives.</rationale>
|
||||||
|
</guideline>
|
||||||
|
|
||||||
|
<guideline priority="high">
|
||||||
|
<rule>Prefer short, numbered steps with explicit inputs/outputs.</rule>
|
||||||
|
<rationale>Agents follow procedural instructions more reliably than prose.</rationale>
|
||||||
|
</guideline>
|
||||||
|
|
||||||
|
<guideline priority="medium">
|
||||||
|
<rule>Use progressive disclosure: keep SKILL.md concise; move deep reference into references/.</rule>
|
||||||
|
<rationale>Minimizes context usage while preserving detail on demand.</rationale>
|
||||||
|
</guideline>
|
||||||
|
|
||||||
|
<guideline priority="medium">
|
||||||
|
<rule>Prefer a single recommended default approach with an explicit escape hatch (only add multiple alternatives when necessary).</rule>
|
||||||
|
<rationale>Too many options reduces reliability and increases variance in execution.</rationale>
|
||||||
|
</guideline>
|
||||||
|
|
||||||
|
<guideline priority="medium">
|
||||||
|
<rule>When referencing files, use forward slashes in paths (even on Windows) and keep references one level deep from SKILL.md.</rule>
|
||||||
|
<rationale>Forward slashes are cross-platform, and shallow references reduce accidental partial/irrelevant reads.</rationale>
|
||||||
|
</guideline>
|
||||||
|
|
||||||
|
<guideline priority="low">
|
||||||
|
<rule>For longer reference files, include a short table of contents near the top to make selective reading easier.</rule>
|
||||||
|
<rationale>Helps the agent jump to the correct section without reading the entire file.</rationale>
|
||||||
|
</guideline>
|
||||||
|
|
||||||
|
<guideline priority="low">
|
||||||
|
<rule>Heuristic size rule: keep SKILL.md skimmable; if it approaches ~500 lines, split detailed content into references/ and link from SKILL.md.</rule>
|
||||||
|
<rationale>Roo Code does not enforce a SKILL.md line limit, but long entrypoint files increase context cost when the skill is selected.</rationale>
|
||||||
|
</guideline>
|
||||||
|
|
||||||
|
<example_refinement>
|
||||||
|
<user_phrase>I want a skill for making API docs</user_phrase>
|
||||||
|
<refined_description>Generate OpenAPI documentation from TypeScript/JavaScript source using JSDoc comments</refined_description>
|
||||||
|
</example_refinement>
|
||||||
|
</authoring>
|
||||||
|
|
||||||
|
<structure>
|
||||||
|
<guideline priority="high">
|
||||||
|
<rule>Keep skill names stable; treat renames as breaking changes.</rule>
|
||||||
|
</guideline>
|
||||||
|
|
||||||
|
<guideline priority="medium">
|
||||||
|
<rule>Prefer one-level file references from SKILL.md (e.g., references/REFERENCE.md, scripts/run.sh).</rule>
|
||||||
|
</guideline>
|
||||||
|
|
||||||
|
<guideline priority="medium">
|
||||||
|
<rule>Make intent explicit for scripts: state whether the agent should execute the script or read it as reference.</rule>
|
||||||
|
<rationale>Most scripts should be executed for deterministic behavior; reading is only needed when understanding the logic matters.</rationale>
|
||||||
|
</guideline>
|
||||||
|
</structure>
|
||||||
|
|
||||||
|
<compatibility>
|
||||||
|
<guideline priority="medium">
|
||||||
|
<rule>Use the optional compatibility field only when it meaningfully constrains runtime requirements.</rule>
|
||||||
|
</guideline>
|
||||||
|
</compatibility>
|
||||||
|
</best_practices>
|
||||||
@@ -0,0 +1,100 @@
|
|||||||
|
<common_patterns>
|
||||||
|
<skill_folder_patterns>
|
||||||
|
<pattern name="project_generic">
|
||||||
|
<description>Project skill available across all modes in this repo</description>
|
||||||
|
<path>./.roo/skills/<skill-name>/SKILL.md</path>
|
||||||
|
</pattern>
|
||||||
|
|
||||||
|
<pattern name="project_mode_specific">
|
||||||
|
<description>Project skill available only in a specific mode</description>
|
||||||
|
<path>./.roo/skills-<mode>/<skill-name>/SKILL.md</path>
|
||||||
|
</pattern>
|
||||||
|
|
||||||
|
<pattern name="global_generic">
|
||||||
|
<description>Global skill available across all workspaces</description>
|
||||||
|
<path><home>/.roo/skills/<skill-name>/SKILL.md</path>
|
||||||
|
</pattern>
|
||||||
|
|
||||||
|
<pattern name="global_mode_specific">
|
||||||
|
<description>Global skill available only in a specific mode</description>
|
||||||
|
<path><home>/.roo/skills-<mode>/<skill-name>/SKILL.md</path>
|
||||||
|
</pattern>
|
||||||
|
</skill_folder_patterns>
|
||||||
|
|
||||||
|
<skill_structure_guidance>
|
||||||
|
<default>
|
||||||
|
<rule>Default to keeping essential workflow instructions in SKILL.md.</rule>
|
||||||
|
<rule>Add additional files only when they materially improve navigation, reuse, or verification.</rule>
|
||||||
|
</default>
|
||||||
|
|
||||||
|
<optional_folders>
|
||||||
|
<folder name="references">
|
||||||
|
<use_for>Optional deep dives (APIs, schemas, checklists, edge cases)</use_for>
|
||||||
|
<rule>Link directly from SKILL.md; avoid multi-hop references.</rule>
|
||||||
|
</folder>
|
||||||
|
<folder name="scripts">
|
||||||
|
<use_for>Deterministic validation or automation (prefer execute-first workflows)</use_for>
|
||||||
|
<rule>SKILL.md must state whether to execute the script or read it as reference.</rule>
|
||||||
|
</folder>
|
||||||
|
<folder name="assets">
|
||||||
|
<use_for>Reusable templates and example artifacts</use_for>
|
||||||
|
</folder>
|
||||||
|
</optional_folders>
|
||||||
|
</skill_structure_guidance>
|
||||||
|
|
||||||
|
<linked_file_handling>
|
||||||
|
<rule>Do not assume linked file contents unless they have been explicitly read.</rule>
|
||||||
|
<rule>Prefer reading the minimum necessary linked file(s) for the current task.</rule>
|
||||||
|
</linked_file_handling>
|
||||||
|
|
||||||
|
<path_conventions>
|
||||||
|
<rule>Use forward slashes in paths (e.g., references/guide.md) for cross-platform compatibility.</rule>
|
||||||
|
</path_conventions>
|
||||||
|
|
||||||
|
<override_priority>
|
||||||
|
<note>When the same skill name exists in multiple locations, prefer the highest-precedence one.</note>
|
||||||
|
<order>
|
||||||
|
<item>Project mode-specific: ./.roo/skills-<mode>/<skill-name>/</item>
|
||||||
|
<item>Project generic: ./.roo/skills/<skill-name>/</item>
|
||||||
|
<item>Global mode-specific: <home>/.roo/skills-<mode>/<skill-name>/</item>
|
||||||
|
<item>Global generic: <home>/.roo/skills/<skill-name>/</item>
|
||||||
|
</order>
|
||||||
|
</override_priority>
|
||||||
|
|
||||||
|
<skill_md_minimum_format>
|
||||||
|
<note>SKILL.md must start with YAML frontmatter including name and description.</note>
|
||||||
|
<frontmatter_example><![CDATA[
|
||||||
|
--- name: your-skill-name description: When to use this skill and what it does (include matching keywords) ---
|
||||||
|
# When to use
|
||||||
|
# When NOT to use
|
||||||
|
# Inputs required
|
||||||
|
# Workflow 1) ... 2) ...
|
||||||
|
# Examples
|
||||||
|
# Troubleshooting
|
||||||
|
]]></frontmatter_example>
|
||||||
|
</skill_md_minimum_format>
|
||||||
|
|
||||||
|
<recommended_skill_md_sections>
|
||||||
|
<section>Title (matches intent; human-readable)</section>
|
||||||
|
<section>When to use this skill</section>
|
||||||
|
<section>When NOT to use this skill</section>
|
||||||
|
<section>Inputs required from the user</section>
|
||||||
|
<section>Workflow (numbered)</section>
|
||||||
|
<section>Examples (minimal, realistic)</section>
|
||||||
|
<section>Troubleshooting / edge cases</section>
|
||||||
|
</recommended_skill_md_sections>
|
||||||
|
|
||||||
|
<validation_rules>
|
||||||
|
<name_constraints>
|
||||||
|
<rule>1–64 characters</rule>
|
||||||
|
<rule>Lowercase letters, numbers, and hyphens only</rule>
|
||||||
|
<rule>No leading or trailing hyphen</rule>
|
||||||
|
<rule>No consecutive hyphens</rule>
|
||||||
|
<rule>Must match the directory name exactly</rule>
|
||||||
|
</name_constraints>
|
||||||
|
<description_constraints>
|
||||||
|
<rule>Non-empty after trimming</rule>
|
||||||
|
<rule>Max 1024 characters</rule>
|
||||||
|
</description_constraints>
|
||||||
|
</validation_rules>
|
||||||
|
</common_patterns>
|
||||||
@@ -0,0 +1,78 @@
|
|||||||
|
<decision_guidance>
|
||||||
|
<principles>
|
||||||
|
<principle>Prefer the smallest change that satisfies the request.</principle>
|
||||||
|
<principle>Prefer a single source of truth; avoid duplicating the same rule across multiple skills or files.</principle>
|
||||||
|
<principle>Ask a clarifying question only when location/scope or a potentially breaking change is ambiguous.</principle>
|
||||||
|
</principles>
|
||||||
|
|
||||||
|
<progressive_disclosure_guardrails>
|
||||||
|
<overview>
|
||||||
|
Progressive disclosure is a tool to reduce token load and improve navigation.
|
||||||
|
It is not a default requirement.
|
||||||
|
|
||||||
|
Progressive disclosure is used as a pressure valve, not as a default architecture.
|
||||||
|
</overview>
|
||||||
|
|
||||||
|
<default_policy>
|
||||||
|
<rule>Default to keeping essential workflow instructions in SKILL.md.</rule>
|
||||||
|
<rule>Create additional files only when there is a clear benefit that outweighs added navigation/maintenance cost.</rule>
|
||||||
|
</default_policy>
|
||||||
|
|
||||||
|
<good_reasons_to_split>
|
||||||
|
<rule>SKILL.md is becoming hard to skim (e.g., approaching ~500 lines) and readers routinely need only a subset of the details.</rule>
|
||||||
|
<rule>The skill has distinct sub-domains (e.g., finance vs sales) where loading only one topic is frequently sufficient.</rule>
|
||||||
|
<rule>High-stakes workflows need verification material (checklists, schemas, expected outputs) that is distracting in the main flow.</rule>
|
||||||
|
<rule>Deterministic validation/automation is best expressed as scripts with clear run/verify loops.</rule>
|
||||||
|
</good_reasons_to_split>
|
||||||
|
|
||||||
|
<bad_reasons_to_split>
|
||||||
|
<rule>Splitting purely for aesthetics or "nice folder structure" without a clear navigation or token benefit.</rule>
|
||||||
|
<rule>Creating reference files that are always needed for every run (in that case, keep them in SKILL.md).</rule>
|
||||||
|
<rule>Creating multi-hop chains (SKILL.md → reference.md → details.md) that require chasing links.</rule>
|
||||||
|
</bad_reasons_to_split>
|
||||||
|
|
||||||
|
<decision_test>
|
||||||
|
<rule>If the skill cannot be executed successfully without reading a linked file in most cases, move that content back into SKILL.md.</rule>
|
||||||
|
<rule>If only one section is "too big", split only that section (don't restructure everything).</rule>
|
||||||
|
</decision_test>
|
||||||
|
</progressive_disclosure_guardrails>
|
||||||
|
|
||||||
|
<scope_selection>
|
||||||
|
<default>
|
||||||
|
<rule>Default to project skills under <workspace>/.roo/skills* unless the user explicitly requests global skills.</rule>
|
||||||
|
<rationale>Project skills are auditable in-repo and easier to keep aligned with the project context.</rationale>
|
||||||
|
</default>
|
||||||
|
|
||||||
|
<global_trigger>
|
||||||
|
<rule>Use global skills only when the user explicitly wants portability across projects.</rule>
|
||||||
|
<rationale>Global changes can affect multiple workspaces and should be treated as higher-impact.</rationale>
|
||||||
|
</global_trigger>
|
||||||
|
|
||||||
|
<mode_specific_trigger>
|
||||||
|
<rule>Create mode-specific skills only when the skill is intentionally scoped to a single mode.</rule>
|
||||||
|
<rationale>Mode-specific skills reduce accidental activation and false-positive matches.</rationale>
|
||||||
|
</mode_specific_trigger>
|
||||||
|
</scope_selection>
|
||||||
|
|
||||||
|
<breaking_change_rules>
|
||||||
|
<rename_policy>
|
||||||
|
<rule>Treat renaming a skill directory (and therefore the skill name) as a breaking change.</rule>
|
||||||
|
<rule>Do not rename without explicit user confirmation.</rule>
|
||||||
|
<rationale>Other instructions, automation, or users may reference the skill by name.</rationale>
|
||||||
|
</rename_policy>
|
||||||
|
|
||||||
|
<name_mismatch_resolution>
|
||||||
|
<rule>Resolve directory/frontmatter mismatches before making additional edits.</rule>
|
||||||
|
<rationale>Leaving a mismatch makes the skill hard to select and easy to break.</rationale>
|
||||||
|
</name_mismatch_resolution>
|
||||||
|
</breaking_change_rules>
|
||||||
|
|
||||||
|
<resource_creation_rules>
|
||||||
|
<rule>Create scripts/, references/, or assets/ only when they materially improve execution and the user explicitly agrees.</rule>
|
||||||
|
<rationale>Extra files increase maintenance and can introduce safety/security concerns.</rationale>
|
||||||
|
</resource_creation_rules>
|
||||||
|
|
||||||
|
<handoffs>
|
||||||
|
<rule>If the user asks for edits outside <workspace>/.roo/skills* and outside global skills management, hand off to the appropriate mode.</rule>
|
||||||
|
</handoffs>
|
||||||
|
</decision_guidance>
|
||||||
@@ -0,0 +1,77 @@
|
|||||||
|
<complete_examples>
|
||||||
|
<example name="create_project_mode_specific_skill">
|
||||||
|
<scenario>Create a new mode-specific project skill to standardize a workflow in one mode.</scenario>
|
||||||
|
<workflow>
|
||||||
|
<step number="1">
|
||||||
|
<description>Confirm scope and name</description>
|
||||||
|
<expected_outcome>Target path is ./.roo/skills-<mode>/<skill-name>/SKILL.md and the name is spec-compliant</expected_outcome>
|
||||||
|
</step>
|
||||||
|
<step number="2">
|
||||||
|
<description>Create folder and SKILL.md with required frontmatter and clear sections</description>
|
||||||
|
<expected_outcome>Skill is discoverable and has actionable instructions</expected_outcome>
|
||||||
|
</step>
|
||||||
|
<step number="3">
|
||||||
|
<description>Validate name/description constraints and directory-name match</description>
|
||||||
|
<expected_outcome>Spec-compliant frontmatter</expected_outcome>
|
||||||
|
</step>
|
||||||
|
</workflow>
|
||||||
|
</example>
|
||||||
|
|
||||||
|
<example name="create_multi_file_skill_with_references_and_scripts">
|
||||||
|
<scenario>
|
||||||
|
Create a project skill that includes an entrypoint SKILL.md plus reference material and a validation script.
|
||||||
|
The goal is progressive disclosure: only read references when needed, and execute scripts for deterministic checks.
|
||||||
|
</scenario>
|
||||||
|
<workflow>
|
||||||
|
<step number="1">
|
||||||
|
<description>Choose structure based on fragility and size</description>
|
||||||
|
<expected_outcome>
|
||||||
|
Use SKILL.md as the entrypoint, references/ for long-lived guidance, and scripts/ for validation/automation.
|
||||||
|
</expected_outcome>
|
||||||
|
</step>
|
||||||
|
|
||||||
|
<step number="2">
|
||||||
|
<description>Draft SKILL.md as navigation (not a dumping ground)</description>
|
||||||
|
<expected_outcome>
|
||||||
|
SKILL.md contains:
|
||||||
|
- Frontmatter (name/description)
|
||||||
|
- When to use / When NOT to use
|
||||||
|
- A numbered workflow with explicit "read this file when..." pointers
|
||||||
|
- A "Files" section that links one level deep:
|
||||||
|
- references/SCHEMA.md (read when needing field definitions)
|
||||||
|
- references/TROUBLESHOOTING.md (read when validation fails)
|
||||||
|
- scripts/validate_input.(sh|js|py) (execute to validate intermediate outputs)
|
||||||
|
</expected_outcome>
|
||||||
|
</step>
|
||||||
|
|
||||||
|
<step number="3">
|
||||||
|
<description>Create references with table-of-contents style headings</description>
|
||||||
|
<expected_outcome>
|
||||||
|
Each references/*.md file starts with a short contents list so the agent can jump to relevant sections.
|
||||||
|
</expected_outcome>
|
||||||
|
</step>
|
||||||
|
|
||||||
|
<step number="4">
|
||||||
|
<description>Make script intent explicit</description>
|
||||||
|
<expected_outcome>
|
||||||
|
SKILL.md clearly states whether the script should be executed (preferred) or read as reference.
|
||||||
|
The script produces verifiable output (e.g., JSON report or "OK"/error list) to support feedback loops.
|
||||||
|
</expected_outcome>
|
||||||
|
</step>
|
||||||
|
</workflow>
|
||||||
|
</example>
|
||||||
|
|
||||||
|
<example name="edit_global_skill_with_confirmation">
|
||||||
|
<scenario>Edit an existing global skill used across multiple projects.</scenario>
|
||||||
|
<workflow>
|
||||||
|
<step number="1">
|
||||||
|
<description>Locate the global skill path and read SKILL.md</description>
|
||||||
|
<expected_outcome>Exact file to change is known</expected_outcome>
|
||||||
|
</step>
|
||||||
|
<step number="2">
|
||||||
|
<description>Apply the minimal edit and re-check frontmatter constraints</description>
|
||||||
|
<expected_outcome>Global skill updated safely and remains spec-compliant</expected_outcome>
|
||||||
|
</step>
|
||||||
|
</workflow>
|
||||||
|
</example>
|
||||||
|
</complete_examples>
|
||||||
@@ -0,0 +1,17 @@
|
|||||||
|
<error_handling>
|
||||||
|
<error_case name="name_mismatch">
|
||||||
|
<symptom>Frontmatter name does not match directory name</symptom>
|
||||||
|
<response>
|
||||||
|
<step>Do not proceed with additional edits until the mismatch is resolved</step>
|
||||||
|
<step>Prefer renaming the directory to match the intended canonical name (or update frontmatter), but confirm with the user if the skill is already in use</step>
|
||||||
|
</response>
|
||||||
|
</error_case>
|
||||||
|
|
||||||
|
<error_case name="invalid_name_format">
|
||||||
|
<symptom>Name contains uppercase, underscores, or consecutive hyphens</symptom>
|
||||||
|
<response>
|
||||||
|
<step>Propose a corrected name and confirm before applying renames</step>
|
||||||
|
<step>Explain that renames may be breaking if other tooling references the skill name</step>
|
||||||
|
</response>
|
||||||
|
</error_case>
|
||||||
|
</error_handling>
|
||||||
@@ -0,0 +1,15 @@
|
|||||||
|
<communication_guidelines>
|
||||||
|
<tone_and_style>
|
||||||
|
<principle>Be direct and technical; avoid conversational filler.</principle>
|
||||||
|
<principle>Use short progress updates and concrete file paths.</principle>
|
||||||
|
</tone_and_style>
|
||||||
|
|
||||||
|
<questions>
|
||||||
|
<rule>Ask questions only when scope, target location, or breaking changes are ambiguous.</rule>
|
||||||
|
<rule>When asking, provide 2–4 actionable options.</rule>
|
||||||
|
</questions>
|
||||||
|
|
||||||
|
<completion_messages>
|
||||||
|
<rule>Summarize the skill paths created/edited and confirm spec compliance checks performed.</rule>
|
||||||
|
</completion_messages>
|
||||||
|
</communication_guidelines>
|
||||||
@@ -0,0 +1,30 @@
|
|||||||
|
<tool_guidance_guide>
|
||||||
|
<tool_priorities>
|
||||||
|
<priority level="1">
|
||||||
|
<tool>List directories/files</tool>
|
||||||
|
<when>Confirm whether skills already exist and where they should live</when>
|
||||||
|
<why>Avoid duplicate skills and ensure correct placement (project vs global; generic vs mode-specific)</why>
|
||||||
|
</priority>
|
||||||
|
|
||||||
|
<priority level="2">
|
||||||
|
<tool>Open/read files</tool>
|
||||||
|
<when>Inspect existing SKILL.md frontmatter and instructions before editing</when>
|
||||||
|
<why>Prevents breaking the name/description constraints and preserves intent</why>
|
||||||
|
</priority>
|
||||||
|
|
||||||
|
<priority level="3">
|
||||||
|
<tool>Edit files (project skills only)</tool>
|
||||||
|
<when>Creating or updating files under .roo/skills* inside the workspace</when>
|
||||||
|
<why>Edits are auditable and covered by file restrictions</why>
|
||||||
|
</priority>
|
||||||
|
|
||||||
|
<priority level="4">
|
||||||
|
<tool>Command execution</tool>
|
||||||
|
<when>
|
||||||
|
- Reading global skills under <home>/.roo/skills*
|
||||||
|
- Creating/updating global skills under <home>/.roo/skills*
|
||||||
|
</when>
|
||||||
|
<why>Global skills are outside the workspace; command execution is required for access</why>
|
||||||
|
</priority>
|
||||||
|
</tool_priorities>
|
||||||
|
</tool_guidance_guide>
|
||||||
@@ -0,0 +1,75 @@
|
|||||||
|
# Roo — Identity & Core Behavior
|
||||||
|
|
||||||
|
## Who am I
|
||||||
|
|
||||||
|
- Username: `$USER` (macOS/Linux) / `$USERNAME` (Windows)
|
||||||
|
- Home dir: `$HOME` (macOS/Linux) / `$USERPROFILE` (Windows)
|
||||||
|
- Git identity: run `git config user.name` / `git config user.email` for the current repo
|
||||||
|
- Path separator: `/` on macOS/Linux, `\` on Windows — adapt all paths accordingly
|
||||||
|
|
||||||
|
## Key Repo Paths
|
||||||
|
|
||||||
|
All repos live under `$HOME/git/` or `$HOME/Library/CloudStorage/`.
|
||||||
|
Discover with: `ls $HOME/git/` or check `git remote -v` in the current workspace.
|
||||||
|
|
||||||
|
| Repo | Path |
|
||||||
|
|------|------|
|
||||||
|
| pi_mcps | `$HOME/Library/CloudStorage/OneDrive-AutomaticDataProcessingInc/Documents/pi_mcps` |
|
||||||
|
| paisy | `$HOME/git/paisy` |
|
||||||
|
| aws-toolkit-jetbrains | `$HOME/git/aws-toolkit-jetbrains` |
|
||||||
|
| aws-toolkit-vscode | `$HOME/git/aws-toolkit-vscode` |
|
||||||
|
|
||||||
|
## Tech Stack
|
||||||
|
|
||||||
|
- **Python + FastMCP** for all MCP servers. `@mcp.tool()` decorator pattern.
|
||||||
|
- **uv** for packages — never `pip`. Path: `$HOME/.local/bin/uv`
|
||||||
|
- **SQLite** for local DBs. BigMind: `$HOME/.mcp/bigmind/memory.db`
|
||||||
|
- **Corporate SSL**: `$HOME/Library/ADP_Support/adp-trusted-certs.pem` — use as `verify=` if exists, else `verify=False`
|
||||||
|
- **FastMCP image rule**: return `mcp.types.ImageContent` directly — never annotate `-> Image`
|
||||||
|
- **BigMind path**: `$HOME/Library/CloudStorage/OneDrive-AutomaticDataProcessingInc/Documents/pi_mcps/mcp-adp-bigmind/`
|
||||||
|
|
||||||
|
## Branching Strategy (all repos)
|
||||||
|
|
||||||
|
| Type | Pattern | Example |
|
||||||
|
|------|---------|---------|
|
||||||
|
| Feature | `feature/<scope>/<topic>` | `feature/mcp-adp-llm` |
|
||||||
|
| Bugfix | `bugfix/<scope>/<desc>` | `bugfix/bigmind/fts5-reserved-words` |
|
||||||
|
| Release | `release/<version>` | `release/2.0.0` |
|
||||||
|
| Chore | `chore/<topic>` | `chore/update-readme` |
|
||||||
|
| Experiment | `experiment/<topic>` | `experiment/mcp-adp-terminal` |
|
||||||
|
|
||||||
|
Paisy-specific: `current/feature/<module>/TICKET-ID-desc` / `current/bugfix/<module>/TICKET-ID-desc`
|
||||||
|
|
||||||
|
**Rules (non-negotiable):**
|
||||||
|
- Never commit directly to `master` / `main` / `current` — always branch first
|
||||||
|
- Merge with `--no-ff`: `git merge --no-ff feature/... -m "Merge ..."`
|
||||||
|
- Conventional commits: `feat:` / `fix:` / `test:` / `chore:` / `refactor:`
|
||||||
|
- Announce focus via `memory_announce_focus` before touching files
|
||||||
|
|
||||||
|
## Always Allowed — Execute Without Confirmation
|
||||||
|
|
||||||
|
- `git_*` — all git operations
|
||||||
|
- `memory_*` — all BigMind memory operations
|
||||||
|
- Shell commands
|
||||||
|
- All file operations (read, write, replace, list, search)
|
||||||
|
- `webscraper_*`, `picturevision_*`, `office_*`, `read_pdf`, `generate_pdf` — read/generate
|
||||||
|
- `list_*`, `get_*`, `retrieve_*`, `search_*` — all read-only API calls
|
||||||
|
|
||||||
|
## Behavior Rules
|
||||||
|
|
||||||
|
- **Direct and action-oriented** — act immediately, don't ask unnecessary questions
|
||||||
|
- **Honesty over comfort** — tell the truth even when uncomfortable
|
||||||
|
- **Full context first** — read files, search BigMind, check Wiki/Confluence, check tests before changing code
|
||||||
|
- **Parallel tool calls** — run independent searches/reads simultaneously, never sequentially
|
||||||
|
- **Root cause, not surface fix** — diagnose before patching
|
||||||
|
- **Token efficiency** — use targeted reads over loading full files. Log savings with `memory_log_token_save`
|
||||||
|
- **Proactively offer** to read `.xlsx`/`.docx` files when paths appear
|
||||||
|
- **Never commit to master/main/current directly** — always branch, then `--no-ff` merge
|
||||||
|
- **Knowledge before web** — BigMind → ADP Docs Wiki → Confluence → Bitbucket → webscraper. Never skip to webscraper if local knowledge can answer
|
||||||
|
- **Store what you learn** — every new ADP Docs page, Confluence decision, Bitbucket pattern → `memory_store_fact` immediately
|
||||||
|
|
||||||
|
## Language Rules
|
||||||
|
|
||||||
|
- ESIDEPAISY Jira tickets: **German** (summary, description, comments). Technical terms stay as-is.
|
||||||
|
- Paisy assessment docs and code comments: German payroll domain conventions.
|
||||||
|
- Chat responses: match the user's language (German or English).
|
||||||
@@ -0,0 +1,153 @@
|
|||||||
|
# BigMind Memory Rules (MOST IMPORTANT)
|
||||||
|
|
||||||
|
## Session Ritual — mandatory every conversation
|
||||||
|
|
||||||
|
```
|
||||||
|
START → memory_start_session()
|
||||||
|
→ 🔴 ANNOUNCE SESSION ID IN CHAT: "🧠 BigMind Session: `<session_id>`" ← mandatory, enables recovery from chat history
|
||||||
|
→ memory_list_hypotheses(status="open")
|
||||||
|
→ memory_announce_focus(session_id, description, files, ide_hint="Roo")
|
||||||
|
→ memory_close_stale_sessions(session_id) ← if multiple 'in progress' found
|
||||||
|
|
||||||
|
EVERY ~5 exchanges → memory_announce_focus(...)
|
||||||
|
|
||||||
|
END → memory_resolve_hypothesis(...)
|
||||||
|
→ memory_end_session(...)
|
||||||
|
```
|
||||||
|
|
||||||
|
### Child Tasks (delegated via `new_task`) — session reuse rules
|
||||||
|
|
||||||
|
When a mode is invoked as a **child task** (via Orchestrator's `new_task`), it must **NOT** manage session lifecycle:
|
||||||
|
|
||||||
|
| Action | Child task behavior |
|
||||||
|
|--------|-------------------|
|
||||||
|
| `memory_start_session()` | ❌ Do NOT call — parent session is already open |
|
||||||
|
| `memory_end_session()` | ❌ Do NOT call — parent will close it |
|
||||||
|
| `memory_close_stale_sessions()` | ❌ Do NOT call — this kills the parent session |
|
||||||
|
| `memory_get_context()` | ✅ Use for read-only context refresh if needed |
|
||||||
|
| `memory_store_fact()` | ✅ Use normally |
|
||||||
|
| `memory_append_chunk()` | ✅ Use normally (pass parent session_id from task message) |
|
||||||
|
| `memory_announce_focus()` | ✅ Use normally (pass parent session_id from task message) |
|
||||||
|
| `memory_search_*()` | ✅ Use normally |
|
||||||
|
|
||||||
|
**How to detect you are a child task:** If the task message contains a session ID (e.g., "BigMind Session: `abc-123`"), you are a child task — reuse that session ID for all `session_id` parameters and skip lifecycle calls.
|
||||||
|
|
||||||
|
**First action in a child task:** After detecting you are a child task, call `memory_get_context()` to load the orchestrator's working state — recent facts, session history, and identity profile. This gives you the full picture beyond what the task message contains. Skip this only for trivially scoped tasks (single tool call, e.g., "commit this file" or "update Jira status").
|
||||||
|
|
||||||
|
**Orchestrator responsibility:** Always pass the active session ID in the `new_task` message so the child can call `memory_announce_focus()`, `memory_append_chunk()`, and other session-dependent tools:
|
||||||
|
```
|
||||||
|
"🧠 Parent Session: `<session_id>` — do NOT open a new session."
|
||||||
|
```
|
||||||
|
|
||||||
|
**Subtask completion (CRITICAL):** When running as a child task, you MUST call `attempt_completion` when your work is done. This is what returns control to the parent Orchestrator. Without it, the parent hangs indefinitely. Do NOT:
|
||||||
|
- Ask the user follow-up questions (put open questions in your documents instead)
|
||||||
|
- Suggest mode switches ("recommend switch to X mode")
|
||||||
|
- Enter a feedback/revision loop with the user
|
||||||
|
- Wait for GO/NO-GO decisions (that's the Orchestrator's job)
|
||||||
|
|
||||||
|
Instead: do your work → produce your artifacts → call `attempt_completion` with a summary of what was produced.
|
||||||
|
|
||||||
|
## Before EVERY Task — search first, act second
|
||||||
|
|
||||||
|
```
|
||||||
|
1. memory_search_facts("2-3 keywords")
|
||||||
|
2. memory_search_chunks("2-3 keywords")
|
||||||
|
3. memory_search_semantic("natural language query") ← if 1+2 return nothing
|
||||||
|
```
|
||||||
|
|
||||||
|
For PAISY/ADP domain topics — also check:
|
||||||
|
```
|
||||||
|
4. ADP Docs Wiki (adpdocs-index facts → get-page directly)
|
||||||
|
5. Confluence (search_confluence_by_cql)
|
||||||
|
6. Bitbucket PRs/commits (get_pull_request, git_log)
|
||||||
|
```
|
||||||
|
|
||||||
|
**Priority:** BigMind facts → BigMind chunks → ADP Docs Wiki → Confluence → Bitbucket → webscraper (last resort)
|
||||||
|
|
||||||
|
**FTS5 rule:** AND-matches every token. Max 3 short keywords. Long queries return 0 results.
|
||||||
|
|
||||||
|
**Never go straight to webscraper** if BigMind or Wiki MCP can answer it.
|
||||||
|
|
||||||
|
## Store Everything Learnable
|
||||||
|
|
||||||
|
| Trigger | Tool | What |
|
||||||
|
|---------|------|------|
|
||||||
|
| Read a new file/module | `memory_store_fact` | Purpose, key classes, entry points |
|
||||||
|
| Fix a bug | `memory_store_fact` | Root cause + fix pattern |
|
||||||
|
| Architectural decision | `memory_append_chunk` | Full rationale |
|
||||||
|
| Learn a Patrick preference | `memory_store_fact` + `memory_update_profile` | Immediately |
|
||||||
|
| Complete a non-trivial task | `memory_append_chunk` | What was built, how, gotchas |
|
||||||
|
| Save tokens with grep/memory | `memory_log_token_save` | Description + tokens saved |
|
||||||
|
|
||||||
|
## Hypothesis-Driven Thinking
|
||||||
|
|
||||||
|
Before every non-trivial task — predict, then verify:
|
||||||
|
|
||||||
|
```python
|
||||||
|
memory_add_hypothesis("I predict X because [evidence from stored fact Y]", confidence=0.85)
|
||||||
|
# ... do the work ...
|
||||||
|
memory_resolve_hypothesis(id, status="confirmed", resolution="X was true because Z")
|
||||||
|
```
|
||||||
|
|
||||||
|
| Confidence | Meaning |
|
||||||
|
|-----------|---------|
|
||||||
|
| 90–100% | Strong direct evidence in stored facts |
|
||||||
|
| 70–89% | Good evidence, some uncertainty |
|
||||||
|
| 50–69% | Informed guess, partial evidence |
|
||||||
|
| < 50% | Exploratory, weak signal |
|
||||||
|
|
||||||
|
## BigMind Tool Reference
|
||||||
|
|
||||||
|
| Category | Tool | Purpose |
|
||||||
|
|----------|------|---------|
|
||||||
|
| **Lifecycle** | `memory_start_session` | First action always |
|
||||||
|
| | `memory_end_session` | Last action always |
|
||||||
|
| | `memory_announce_focus(session_id, description, files, ide_hint)` | After start + before every task |
|
||||||
|
| | `memory_get_active_sessions()` | See all open sessions + file conflicts |
|
||||||
|
| | `memory_close_stale_sessions(session_id)` | Clean orphaned IDE sessions |
|
||||||
|
| | `memory_restart_server()` | After adding new tools to server.py |
|
||||||
|
| | `memory_get_context` | Refresh context mid-conversation |
|
||||||
|
| **Search** | `memory_search_facts(query)` | Atomic facts (2-3 keywords) |
|
||||||
|
| | `memory_search_chunks(query)` | Past decisions/code (2-3 keywords) |
|
||||||
|
| | `memory_search_semantic(query)` | Semantic/meaning-based search |
|
||||||
|
| | `memory_list_sessions(limit)` | Browse session history |
|
||||||
|
| | `memory_get_session_detail(id)` | Full Tier-2 narrative |
|
||||||
|
| **Storage** | `memory_store_fact(category, fact)` | One atomic truth per call |
|
||||||
|
| | `memory_append_chunk(content)` | Large narrative or code snippet |
|
||||||
|
| | `memory_flag_important(content)` | Flag exchange as Tier-3 |
|
||||||
|
| | `memory_update_profile(...)` | New preference or pinned fact |
|
||||||
|
| | `memory_deprecate_fact(id, reason)` | Fact no longer true |
|
||||||
|
| | `memory_log_token_save(session_id, description, tokens_saved, method_used)` | Log efficiency wins |
|
||||||
|
| **Hypotheses** | `memory_add_hypothesis(hypothesis, confidence)` | Predict before acting |
|
||||||
|
| | `memory_resolve_hypothesis(id, status, resolution)` | Close as confirmed/refuted/abandoned |
|
||||||
|
| | `memory_list_hypotheses(status)` | Review open predictions |
|
||||||
|
| | `memory_scan_hypotheses()` | Cross-reference open hypotheses vs facts |
|
||||||
|
| **Maintenance** | `memory_health_check()` | Stale facts, FTS integrity |
|
||||||
|
| | `memory_get_stats()` | DB size, counts |
|
||||||
|
| | `memory_vacuum(older_than_days)` | Prune old chunks |
|
||||||
|
| | `memory_export(output_path)` | Backup to JSON |
|
||||||
|
| | `memory_request_upgrade(description, reason)` | Log desired BigMind feature |
|
||||||
|
| | `memory_list_upgrade_requests()` | See pending requests |
|
||||||
|
| | `memory_resolve_upgrade_request(id, status)` | Mark done/rejected |
|
||||||
|
| **Web UI** | `memory_open_profile()` | Open profile page in browser |
|
||||||
|
| | `memory_get_profile_url()` | Get URL for IDE built-in browser |
|
||||||
|
| **People** | `memory_remember_person(username, ...)` | Store/update a colleague |
|
||||||
|
| | `memory_recall_person(query)` | Find person by name/role/team |
|
||||||
|
| | `memory_list_people()` | All contacts, most recent first |
|
||||||
|
| | `memory_link_ai(username, bigmind_user)` | Link contact to their BigMind |
|
||||||
|
| **Diff** | `memory_diff_sessions(since_session_id)` | What changed since a session |
|
||||||
|
|
||||||
|
## ADP Docs Wiki
|
||||||
|
|
||||||
|
Wiki registered as `mcp://wikis/adpdocs.de.adp.com`.
|
||||||
|
|
||||||
|
**Workflow — always in this order:**
|
||||||
|
1. `memory_search_facts("topic adpdocs")` — check BigMind index first (category: `adpdocs-index`)
|
||||||
|
2. If Page ID known → `set-wiki` + `get-page "Seitentitel"` directly
|
||||||
|
3. If not known → `search-page query="..."` or `get-category-members category="..."`
|
||||||
|
4. After finding a useful page → `memory_store_fact(category="adpdocs-index", ...)` immediately
|
||||||
|
|
||||||
|
**Key categories:** `Meldeverfahren`, `Verwalterhandbuch`, `Batchabläufe`, `Client Server (CS)`, `PAISYadvanced`, `Installationshandbuch für Windows und UNIX`
|
||||||
|
|
||||||
|
**Known Page IDs in BigMind** (Facts #153–160, category `adpdocs-index`):
|
||||||
|
- Fehlercodes Batch, Meldeverfahren-Seiten (EAU/EuBP/DaBPV/DSBD/DSVV/...), Verwalterhandbuch-Seiten, Batch-Einzelaufrufe, Installation
|
||||||
@@ -0,0 +1,158 @@
|
|||||||
|
# MCP Tool Reference
|
||||||
|
|
||||||
|
## Git (`git_*`)
|
||||||
|
`repo_path` passed per call. All git actions execute immediately without confirmation.
|
||||||
|
|
||||||
|
| Tool | Purpose |
|
||||||
|
|------|---------|
|
||||||
|
| `git_status(repo_path)` | Working tree status |
|
||||||
|
| `git_add(repo_path, files)` | Stage files |
|
||||||
|
| `git_commit(repo_path, message)` | Commit staged changes |
|
||||||
|
| `git_diff_unstaged(repo_path)` | Unstaged changes |
|
||||||
|
| `git_diff_staged(repo_path)` | Staged changes |
|
||||||
|
| `git_diff(repo_path, target)` | Diff vs branch/commit |
|
||||||
|
| `git_log(repo_path, max_count, start_timestamp, end_timestamp)` | Commit history |
|
||||||
|
| `git_branch(repo_path, branch_type)` | List branches |
|
||||||
|
| `git_create_branch(repo_path, branch_name, base_branch)` | Create branch |
|
||||||
|
| `git_checkout(repo_path, branch_name)` | Switch branch |
|
||||||
|
| `git_show(repo_path, revision)` | Show commit |
|
||||||
|
| `git_reset(repo_path)` | Unstage all |
|
||||||
|
|
||||||
|
## Jira
|
||||||
|
ESIDEPAISY tickets: German language, terminal status = "Accepted", `customfield_10001` mandatory.
|
||||||
|
|
||||||
|
| Tool | Purpose |
|
||||||
|
|------|---------|
|
||||||
|
| `list_tickets(jql_search)` | Search by JQL |
|
||||||
|
| `retrieve_ticket_details(issue_key)` | Full details |
|
||||||
|
| `create_ticket(project_key, summary, description)` | Create |
|
||||||
|
| `update_ticket_fields(issue_key, fields)` | Update fields |
|
||||||
|
| `update_status(issue_key, status)` | Transition |
|
||||||
|
| `add_comment_to_ticket(issue_key, comment)` | Comment |
|
||||||
|
| `update_comment(issue_key, comment_id, body)` | Edit comment |
|
||||||
|
| `ticket_assignment(issue_key, assignee)` | Assign |
|
||||||
|
| `my_tickets_to_work()` | My backlog/in-progress |
|
||||||
|
| `get_agile_boards(project_key)` | List boards |
|
||||||
|
| `get_sprints_from_board(board_id, states)` | List sprints |
|
||||||
|
| `get_tickets_from_sprint(sprint_id)` | Sprint tickets |
|
||||||
|
| `get_tickets_from_backlog(board_id)` | Backlog |
|
||||||
|
| `add_attachment_to_ticket(issue_key, file_path)` | Attach file |
|
||||||
|
| `download_single_attachment(issue_key, attachment_id, path)` | Download |
|
||||||
|
| `get_available_fields()` | List custom fields |
|
||||||
|
|
||||||
|
## Confluence
|
||||||
|
|
||||||
|
| Tool | Purpose |
|
||||||
|
|------|---------|
|
||||||
|
| `search_confluence_by_cql(cql_search)` | Search pages |
|
||||||
|
| `get_page_content(page_id)` | Read page |
|
||||||
|
| `create_page(space_key, title, content)` | Create |
|
||||||
|
| `update_page(page_id, content)` | Update |
|
||||||
|
| `add_comment_to_page(page_id, comment)` | Comment |
|
||||||
|
| `get_page_labels / add_page_label / remove_page_label` | Label management |
|
||||||
|
| `export_as_pdf(page_id)` | Export as PDF |
|
||||||
|
| `get_all_spaces()` | List spaces |
|
||||||
|
|
||||||
|
## Bitbucket
|
||||||
|
|
||||||
|
| Tool | Purpose |
|
||||||
|
|------|---------|
|
||||||
|
| `list_projects / list_repositories_by_project` | Browse |
|
||||||
|
| `list_prs_for_repository(project_key, repo_slug)` | List PRs |
|
||||||
|
| `get_pull_request / get_pull_request_diff / get_pull_request_comments / get_pull_request_changed_files` | PR details |
|
||||||
|
| `create_pull_request(project_key, repo_slug, title, description, from_branch)` | Open PR |
|
||||||
|
| `create_branch / list_branches` | Branch management |
|
||||||
|
| `find_file(project_key, repo_slug, file_path, branch)` | Read file |
|
||||||
|
| `commit_file(project_key, repo_slug, branch, file_path, content, commit_message)` | Commit |
|
||||||
|
|
||||||
|
## PDF Generator
|
||||||
|
**Always ask Patrick which color scheme before calling `generate_pdf`.**
|
||||||
|
Available: `adp` (red), `royal_purple`, `ocean`, `forest`, `sunset`, `slate`, `rose`.
|
||||||
|
|
||||||
|
| Tool | Purpose |
|
||||||
|
|------|---------|
|
||||||
|
| `generate_pdf(content, title, author, classification, logo, output_path, color_scheme)` | Branded PDF |
|
||||||
|
| `read_pdf(file_path, pages)` | Extract text + metadata |
|
||||||
|
| `generate_pptx(content, title, subtitle, author, template, output_path)` | ADP-branded PPTX |
|
||||||
|
| `read_pptx(file_path)` | Extract slide content |
|
||||||
|
|
||||||
|
## Office (`office_*`)
|
||||||
|
When a `.xlsx` or `.docx` path appears in conversation, **offer to read it immediately**.
|
||||||
|
|
||||||
|
| Tool | Purpose |
|
||||||
|
|------|---------|
|
||||||
|
| `office_excel_list_sheets(file_path)` | Sheet names |
|
||||||
|
| `office_excel_read_sheet(file_path, sheet_name)` | Rows |
|
||||||
|
| `office_excel_get_cell(file_path, cell)` | Single cell |
|
||||||
|
| `office_excel_get_named_ranges(file_path)` | Named ranges |
|
||||||
|
| `office_word_read(file_path)` | Full content |
|
||||||
|
| `office_word_list_headings(file_path)` | Outline |
|
||||||
|
| `office_word_read_table(file_path, table_index)` | Table |
|
||||||
|
|
||||||
|
## WebScraper (`webscraper_*`)
|
||||||
|
|
||||||
|
| Tool | Purpose |
|
||||||
|
|------|---------|
|
||||||
|
| `webscraper_fetch(url)` | Page → markdown |
|
||||||
|
| `webscraper_fetch_links(url)` | All hrefs |
|
||||||
|
| `webscraper_fetch_tables(url)` | HTML tables |
|
||||||
|
| `webscraper_fetch_all(url)` | Markdown + links + tables |
|
||||||
|
| `webscraper_fetch_section(url, selector)` | CSS selector |
|
||||||
|
| `webscraper_fetch_meta(url)` | Meta tags |
|
||||||
|
| `webscraper_fetch_sitemap(url)` | Sitemap URLs |
|
||||||
|
|
||||||
|
## PictureVision (`picturevision_*`)
|
||||||
|
|
||||||
|
| Tool | Purpose |
|
||||||
|
|------|---------|
|
||||||
|
| `picturevision_load(image_source)` | Load for AI vision |
|
||||||
|
| `picturevision_compare(img1, img2)` | Side-by-side diff |
|
||||||
|
| `picturevision_extract_text(image_source)` | Tesseract OCR |
|
||||||
|
| `picturevision_load_jira_attachment(issue_key, attachment_id)` | Jira image |
|
||||||
|
|
||||||
|
## Teams (`teams_*`)
|
||||||
|
|
||||||
|
| Tool | Purpose |
|
||||||
|
|------|---------|
|
||||||
|
| `teams_list_teams / teams_list_channels(team_id)` | Browse |
|
||||||
|
| `teams_send_channel_message(team_id, channel_id, content)` | Send to channel |
|
||||||
|
| `teams_list_chats / teams_send_message(chat_id, content)` | DMs |
|
||||||
|
| `teams_list_messages(team_id, channel_id)` | Read messages |
|
||||||
|
| `teams_list_users(search)` | Find users |
|
||||||
|
|
||||||
|
## Webex (`webex_*`)
|
||||||
|
|
||||||
|
| Tool | Purpose |
|
||||||
|
|------|---------|
|
||||||
|
| `webex_send_message(room_id, text, markdown)` | Send message |
|
||||||
|
| `webex_list_rooms / webex_get_room / webex_create_room` | Room management |
|
||||||
|
| `webex_list_messages(room_id)` | Read messages |
|
||||||
|
| `webex_list_people / webex_add_member` | People |
|
||||||
|
|
||||||
|
## File Transfer (`ft_*`)
|
||||||
|
|
||||||
|
| Tool | Purpose |
|
||||||
|
|------|---------|
|
||||||
|
| `ft_send_file(recipients, subject, message, file_path)` | Send via ADP Secure FT |
|
||||||
|
| `ft_list_inbox / ft_list_sent` | Inbox/sent |
|
||||||
|
| `ft_get_message(message_id)` | Message details |
|
||||||
|
| `ft_download_attachment(attachment_id)` | Download |
|
||||||
|
| `ft_validate_recipients(recipients)` | Check allowed recipients |
|
||||||
|
| `ft_request_file(recipient, subject, message)` | Request upload from someone |
|
||||||
|
|
||||||
|
## H2 DB
|
||||||
|
|
||||||
|
| Tool | Purpose |
|
||||||
|
|------|---------|
|
||||||
|
| `query(db_path, sql)` | Execute SQL |
|
||||||
|
| `list_schemas / list_tables / describe_table / get_foreign_keys / get_indexes` | Schema inspection |
|
||||||
|
|
||||||
|
## PAISY SSH (`exec-command`, `run-program`, `upload-file`)
|
||||||
|
|
||||||
|
| Tool | Purpose |
|
||||||
|
|------|---------|
|
||||||
|
| `list-instances` | List available PAISY test instances |
|
||||||
|
| `set-instance(instance)` | Select instance for session |
|
||||||
|
| `run-program(program, args, stdin)` | Run PAI* programs |
|
||||||
|
| `exec-command(command)` | Raw shell on PAISY host |
|
||||||
|
| `upload-file(localPath, remoteFilename)` | Upload JAR to instance |
|
||||||
@@ -0,0 +1,83 @@
|
|||||||
|
# PAISY — Workspace Rules
|
||||||
|
|
||||||
|
## Project Context
|
||||||
|
|
||||||
|
ADP Germany Java monorepo for payroll/HR government compliance.
|
||||||
|
Key domains: SV-Meldeverfahren, EAU, EuBP, DaBPV/PUEG, ELStAM, DEÜV, Lohnsteuer.
|
||||||
|
|
||||||
|
## Jira
|
||||||
|
|
||||||
|
- Project: **ESIDEPAISY**
|
||||||
|
- All tickets in **German** (summary, description, comments). Technical terms stay as-is.
|
||||||
|
- Terminal status = `Accepted`
|
||||||
|
- `customfield_10001` (Feature Link) is mandatory on all tickets — always look up dynamically via JQL, never hardcode
|
||||||
|
- Sprint ID: always derive from user's most recent ticket (`customfield_10000` with `state=ACTIVE`)
|
||||||
|
- Branch naming: `current/feature/<module>/TICKET-ID-desc` or `current/bugfix/<module>/TICKET-ID-desc`
|
||||||
|
|
||||||
|
### Smart Checklist (Railsware) Formatting
|
||||||
|
|
||||||
|
Use `update_checklist` with `items` list. Each item supports:
|
||||||
|
- `status`: `-` todo, `+` done, `~` in progress, `x` cancelled — append `!` for mandatory (e.g. `-!`)
|
||||||
|
- `checked: true` → `+`, `checked: false` → `-` (shorthand)
|
||||||
|
- `name` supports markdown: `**bold**`, `_italic_`, `~~strikethrough~~`, `` `code` ``
|
||||||
|
- Headers in name: `# H1`, `## H2`, `---` separator (use as standalone items)
|
||||||
|
- Detail lines: prefix with `> ` in name for sub-text under an item
|
||||||
|
- Custom statuses: `- [IN QA] Item`, `+ [PASSED] Item`, `-! [IN REVIEW] Item` (mandatory custom)
|
||||||
|
|
||||||
|
Default statuses: `TO DO` (-), `IN PROGRESS` (~), `SKIPPED` (x), `DONE` (+)
|
||||||
|
|
||||||
|
Example:
|
||||||
|
```python
|
||||||
|
[
|
||||||
|
{"name": "## Analyse"},
|
||||||
|
{"name": "Fehlerursache analysieren", "checked": True},
|
||||||
|
{"name": "---"},
|
||||||
|
{"name": "## Testing"},
|
||||||
|
{"name": "H2-Test", "status": "-!"}, # mandatory todo
|
||||||
|
{"name": "Oracle-Test", "status": "~"}, # in progress
|
||||||
|
{"name": "QA-Review", "status": "-! [IN QA]"}, # mandatory custom status
|
||||||
|
]
|
||||||
|
```
|
||||||
|
|
||||||
|
## ADP Docs Wiki
|
||||||
|
|
||||||
|
Wiki: `mcp://wikis/adpdocs.de.adp.com` — always check BigMind `adpdocs-index` facts first before fetching.
|
||||||
|
|
||||||
|
Key Page IDs (direct access via `get-page`):
|
||||||
|
- EAU → 25123 | EuBP → 26666 | DaBPV → 27242 | DSBD → 26747 | DSAK → 26748
|
||||||
|
- DSVV → 18714 | RvBEA → 21174 | EEL → 2724 | ELStAM → 2737 | DEÜV → 5876
|
||||||
|
- Programmabläufe → 15201 | Einzelaufrufe BATCH → 15250 | Umgebungsvariablen → 22767
|
||||||
|
- PAISY verwalten → 15180 | Datenbanken verwalten → 15184 | Fehlermeldungen → 15196
|
||||||
|
|
||||||
|
## Tech Stack
|
||||||
|
|
||||||
|
- Java monorepo, Maven build
|
||||||
|
- COBOL components (Visual COBOL, formerly NetExpress/ServerExpress)
|
||||||
|
- Git worktrees for parallel ticket work: `/Users/pplate/git/paisy-<TICKET-ID>`
|
||||||
|
- Mockito for tests — watch for version conflicts on merge
|
||||||
|
|
||||||
|
## Code Conventions
|
||||||
|
|
||||||
|
- Code comments and assessment docs: German payroll domain conventions
|
||||||
|
- Test classes mirror source structure
|
||||||
|
- Never modify generated sources in `src.gen/`
|
||||||
|
|
||||||
|
## PAISY SSH Testing
|
||||||
|
|
||||||
|
Use `list-instances` → `set-instance` → `run-program` / `exec-command` for live testing.
|
||||||
|
Upload JARs with `upload-file` before running programs.
|
||||||
|
|
||||||
|
## Git Worktree Visibility
|
||||||
|
|
||||||
|
At **every session start** (after `memory_start_session` and `memory_announce_focus`), run:
|
||||||
|
|
||||||
|
```bash
|
||||||
|
git -C /Users/pplate/git/paisy worktree list
|
||||||
|
git -C /Users/pplate/git/paisy log --all --oneline -15
|
||||||
|
```
|
||||||
|
|
||||||
|
Report to the user:
|
||||||
|
1. All active worktrees with their branches
|
||||||
|
2. The last 15 commits across ALL branches (not just the current one)
|
||||||
|
|
||||||
|
This ensures visibility into parallel ticket work happening across worktrees, not just the local branch history.
|
||||||
@@ -0,0 +1,28 @@
|
|||||||
|
# Visual Verification Rule
|
||||||
|
|
||||||
|
## After Building Frontend Pages
|
||||||
|
|
||||||
|
When working in Code or Debug mode on a frontend project with Playwright installed:
|
||||||
|
|
||||||
|
- **After creating or significantly modifying a page/component**, run the `visual-verify` skill to verify it renders correctly
|
||||||
|
- This catches issues like: missing i18n text, broken centering, theme mode failures, responsive overflow
|
||||||
|
- Minimum check: take a screenshot + extract visible text + verify positioning
|
||||||
|
|
||||||
|
## When to Delegate to Visual QA Mode
|
||||||
|
|
||||||
|
For deeper visual testing (multi-page, responsive breakpoints, interaction flows, accessibility), delegate to 🎨 Visual QA mode via the Orchestrator.
|
||||||
|
|
||||||
|
## Playwright Quick Reference
|
||||||
|
|
||||||
|
```javascript
|
||||||
|
const { chromium } = require('playwright');
|
||||||
|
const browser = await chromium.launch();
|
||||||
|
const page = await browser.newPage({ viewport: { width: 1280, height: 720 } });
|
||||||
|
await page.goto(URL);
|
||||||
|
await page.waitForTimeout(2000);
|
||||||
|
const text = await page.locator('body').innerText();
|
||||||
|
await page.screenshot({ path: '/tmp/verify.png' });
|
||||||
|
await browser.close();
|
||||||
|
```
|
||||||
|
|
||||||
|
Prerequisites: `pnpm add -D playwright` + `npx playwright install chromium`
|
||||||
@@ -0,0 +1,197 @@
|
|||||||
|
# Paisy — Development Guidelines
|
||||||
|
|
||||||
|
## Code Quality Standards
|
||||||
|
|
||||||
|
### Logging
|
||||||
|
- Use `@Log4j2` (Lombok) for existing modules that already use Log4j2 (e.g., `AbstractMeldung`)
|
||||||
|
- Use `@Slf4j` (Lombok) for new code — this is the preferred default
|
||||||
|
- Use parameterized logging: `log.debug("Value: {}", value)` — never string concatenation
|
||||||
|
- Some legacy code mixes styles: `log.debug("text " + var)` — refactor to parameterized when touching these lines
|
||||||
|
- Log levels: `debug` for flow tracing, `warn` for recoverable issues, `error` for failures
|
||||||
|
|
||||||
|
### Naming Conventions
|
||||||
|
- Package: `com.adp.de.paisy.modules.<module>` for modules, `com.adp.de.<module>` for legacy
|
||||||
|
- German domain terms preserved in class/field names: `Fehlzeiten`, `Lohnkonto`, `Vorlaufsatz`, `Nachlaufsatz`, `Meldekorrekturen`
|
||||||
|
- JAXB-generated classes use German XML element names as Java identifiers: `getAngabenZurPersonAV()`, `getBeschreibungTaetigkeitDE()`
|
||||||
|
- Constants use UPPER_SNAKE_CASE: `EMPTY_DATE_LONG`, `EMPTY_BBNR`, `MAX_DBFZ`
|
||||||
|
- Date formatters as `final` fields: `bausteinf`, `pai022f`, `PAI_SHORT`
|
||||||
|
|
||||||
|
### Field Visibility
|
||||||
|
- `protected` for fields shared with subclasses (common in abstract controllers)
|
||||||
|
- `private` with Lombok `@Getter`/`@Setter` for DTOs
|
||||||
|
- `static private final` for constants (PDDI layer uses tab-indented style)
|
||||||
|
|
||||||
|
## Structural Conventions
|
||||||
|
|
||||||
|
### Module Entry Point Pattern
|
||||||
|
```java
|
||||||
|
@Slf4j
|
||||||
|
@Service("module-name")
|
||||||
|
@Lazy
|
||||||
|
public class ModuleRunner implements ConsoleService {
|
||||||
|
@Override
|
||||||
|
public void run(String... args) throws Exception { /* ... */ }
|
||||||
|
}
|
||||||
|
```
|
||||||
|
|
||||||
|
### Abstract Controller Pattern (5/5 files)
|
||||||
|
Business modules use abstract base classes for shared logic:
|
||||||
|
```java
|
||||||
|
@Log4j2
|
||||||
|
public abstract class AbstractMeldung {
|
||||||
|
// Shared date formatters, parsers, PAISY interaction
|
||||||
|
protected Person person;
|
||||||
|
protected Fehlzeiten fz;
|
||||||
|
|
||||||
|
public Person initBaustein(Datenbaustein main, DBNA dbna, ...) { /* ... */ }
|
||||||
|
protected Lohnkonto parseLohnkonto(...) { /* ... */ }
|
||||||
|
}
|
||||||
|
```
|
||||||
|
|
||||||
|
### Datenbaustein (Data Block) Pattern (5/5 files)
|
||||||
|
Core data exchange pattern — field-based data blocks with positional access:
|
||||||
|
```java
|
||||||
|
Datenbaustein main = ...;
|
||||||
|
main.setValue("FEKZ", "0");
|
||||||
|
main.setValue("VSNR", person.getValue("VSNR"));
|
||||||
|
String value = d508b.getValue("F39-AVUWFWZ-10-50-8B");
|
||||||
|
```
|
||||||
|
|
||||||
|
### ServiceCenter Singleton Pattern
|
||||||
|
Central access point for PAISY system interaction:
|
||||||
|
```java
|
||||||
|
ServiceCenter.INSTANCE().getBaustein(Datengruppe.NAME, vorgangsID);
|
||||||
|
ServiceCenter.INSTANCE().getPaisy().pgmFunktionCall("S;" + bbnrvu + ";");
|
||||||
|
ServiceCenter.INSTANCE().getPaisy().pgmReadLine();
|
||||||
|
```
|
||||||
|
|
||||||
|
### EMFactory Singleton Pattern
|
||||||
|
Each module has its own EntityManager factory:
|
||||||
|
```java
|
||||||
|
EMFactoryEAU emFactory = EMFactoryEAU.getInstance();
|
||||||
|
FlywayController flyway = new FlywayController(emFactory);
|
||||||
|
flyway.migrate("EAU", "2024_09_08_17_48_11");
|
||||||
|
```
|
||||||
|
|
||||||
|
## JAXB XML Binding Pattern (3/5 files)
|
||||||
|
|
||||||
|
JAXB-generated classes follow a strict pattern for GKV data exchange:
|
||||||
|
|
||||||
|
```java
|
||||||
|
@XmlAccessorType(XmlAccessType.FIELD)
|
||||||
|
@XmlType(name = "", propOrder = { "steuerungsdaten", "angabenZurPersonAV", ... })
|
||||||
|
@XmlRootElement(name = "A1_Ausnahmevereinbarung",
|
||||||
|
namespace = "http://www.gkv-datenaustausch.de/XMLSchema/A1_Ausnahme/2.0")
|
||||||
|
public class A1Ausnahmevereinbarung {
|
||||||
|
|
||||||
|
@XmlElement(name = "Steuerungsdaten",
|
||||||
|
namespace = "http://www.gkv-datenaustausch.de/XMLSchema/A1_Ausnahme/2.0",
|
||||||
|
required = true)
|
||||||
|
protected SteuerungsdatenAGV2Ctp steuerungsdaten;
|
||||||
|
}
|
||||||
|
```
|
||||||
|
|
||||||
|
Key rules:
|
||||||
|
- Nested `public static class` for complex type hierarchies
|
||||||
|
- German Javadoc: `"Ruft den Wert der X-Eigenschaft ab"` / `"Legt den Wert der X-Eigenschaft fest"`
|
||||||
|
- `jakarta.xml.bind.annotation.*` (Jakarta EE, not javax)
|
||||||
|
- `XMLGregorianCalendar` for date fields, `BigInteger` for numeric codes
|
||||||
|
- `KennzeichenAlphanumerischTyp` enum for J/N flag fields
|
||||||
|
|
||||||
|
## PDF Generation Pattern (2/5 files)
|
||||||
|
|
||||||
|
Using OpenPDF (iText fork) for government-compliant PDF reports:
|
||||||
|
|
||||||
|
```java
|
||||||
|
Document document = new Document(PageSize.A4, 50, 50, 50, 50);
|
||||||
|
PdfWriter writer = PdfWriter.getInstance(document, baos);
|
||||||
|
document.open();
|
||||||
|
|
||||||
|
// Header
|
||||||
|
Paragraph headline = new Paragraph("EuBP", getHeaderFont());
|
||||||
|
document.add(headline);
|
||||||
|
|
||||||
|
// Two-column table: Bezeichnung | Inhalt
|
||||||
|
PdfPTable table = new PdfPTable(2);
|
||||||
|
table.setWidthPercentage(75);
|
||||||
|
table.setHorizontalAlignment(Element.ALIGN_LEFT);
|
||||||
|
addTableHeader(table, new String[]{"Bezeichnung", "Inhalt"});
|
||||||
|
table.addCell(createCell("Verfahrensmerkmal"));
|
||||||
|
table.addCell(createCell(vorlaufsatz.getVerfahrensmerkmal().value));
|
||||||
|
document.add(table);
|
||||||
|
```
|
||||||
|
|
||||||
|
Font conventions:
|
||||||
|
- Header: Helvetica Bold 18pt
|
||||||
|
- Subheader: Helvetica Bold 14pt
|
||||||
|
- Bold: Helvetica Bold 12pt
|
||||||
|
- Normal: Helvetica 10pt
|
||||||
|
- Table header background: `new Color(220, 220, 220)`
|
||||||
|
|
||||||
|
## ISAM/Oracle Trigger Generation (1/5 files)
|
||||||
|
|
||||||
|
JavaScript code generator for Oracle INSTEAD OF triggers:
|
||||||
|
```javascript
|
||||||
|
// gen_trigger.js — generates Oracle triggers for COBOL ISAM → Oracle mirroring
|
||||||
|
gen("YP_ABR_STEUER", `
|
||||||
|
,MUT_YP_ABR_STEUER.ABSCHNITT
|
||||||
|
,MUT_YP_ABR_STEUER.BEMERKUNG
|
||||||
|
...
|
||||||
|
`)
|
||||||
|
```
|
||||||
|
Pattern: `IPW_<recname>` view → `MUT_<recname>` mutation table, with `ak_nr`/`pers_nr` lookup from `PS_YP_PERS_MAIN`.
|
||||||
|
|
||||||
|
## Binary Protocol Pattern (1/5 files)
|
||||||
|
|
||||||
|
Custom binary serialization for PDDI middleware (DocumentStream):
|
||||||
|
- Type-tagged byte protocol: `b_null='~'`, `b_string='S'`, `b_int='i'`, `b_date='d'`
|
||||||
|
- Compact encoding: shorts for small ints, full 8 bytes only when needed
|
||||||
|
- Custom charset: `PaisyCharset.CHARSET` (likely ISO-8859-1)
|
||||||
|
- Inner classes: `BytesOutput`, `Output` (stream-based), `Input` (stream-based)
|
||||||
|
|
||||||
|
## Date Handling Patterns
|
||||||
|
|
||||||
|
```java
|
||||||
|
// German user-facing format
|
||||||
|
DateTimeFormatter.ofPattern("dd.MM.yyyy")
|
||||||
|
|
||||||
|
// Internal PAISY format (8-digit)
|
||||||
|
DateTimeFormatter.ofPattern("yyyyMMdd")
|
||||||
|
|
||||||
|
// Short PAISY format (6-digit, 2-digit year)
|
||||||
|
DateTimeFormatter.ofPattern("yyMMdd")
|
||||||
|
|
||||||
|
// Null/empty date handling
|
||||||
|
if (value.equals("00.00.0000")) return LocalDate.MAX;
|
||||||
|
if (paidate.equals("0000000")) return LocalDate.MIN;
|
||||||
|
if (paidate.equals("9999999")) return LocalDate.MAX;
|
||||||
|
```
|
||||||
|
|
||||||
|
## Error Handling
|
||||||
|
|
||||||
|
- Custom exceptions: `PaisyIOException`, `PaisyRuntimeException`, `AccessDeniedException`, `PaisyNotFoundException`, `UnauthorizedException`
|
||||||
|
- PAISY error responses start with `"F;"` — check before parsing
|
||||||
|
- Null-safe patterns: check for null before processing sections (PDF, data blocks)
|
||||||
|
- Reflection-based construction with explicit error messages for field count mismatches
|
||||||
|
|
||||||
|
## Frequently Used Annotations
|
||||||
|
|
||||||
|
| Annotation | Usage | Frequency |
|
||||||
|
|-----------|-------|-----------|
|
||||||
|
| `@Log4j2` / `@Slf4j` | Logging | Every class |
|
||||||
|
| `@Getter` / `@Setter` | Lombok accessors | DTOs, models |
|
||||||
|
| `@XmlElement` / `@XmlAccessorType` | JAXB binding | XML model classes |
|
||||||
|
| `@XmlRootElement` / `@XmlType` | JAXB root types | Top-level XML types |
|
||||||
|
| `@XmlSchemaType` | JAXB schema mapping | XML fields |
|
||||||
|
| `@Service("name")` / `@Lazy` | Spring service registration | Module entry points |
|
||||||
|
| `@Transactional` | DB transactions | Service methods |
|
||||||
|
| `@Data` / `@Builder` | Lombok DTOs | Model classes |
|
||||||
|
|
||||||
|
## Code Idioms
|
||||||
|
|
||||||
|
- `CommonRoutines.paidate2Datenbaustein()` — convert PAISY date to Datenbaustein format
|
||||||
|
- `CommonRoutines.uuid()` — generate unique dataset IDs
|
||||||
|
- `CommonRoutines.getDocumentPath()` — get output file path
|
||||||
|
- `ServiceCenter.INSTANCE().getPaisy().nextPaisy(line)` — iterate PAISY response lines
|
||||||
|
- `line.split(";")` — semicolon-delimited PAISY response parsing
|
||||||
|
- Streams with `Collectors.toCollection(ArrayList::new)` for mutable result lists
|
||||||
@@ -0,0 +1,54 @@
|
|||||||
|
# Paisy — Product Overview
|
||||||
|
|
||||||
|
## Purpose
|
||||||
|
|
||||||
|
Paisy is ADP Germany's **Java monorepo** for payroll and HR government compliance. It handles all electronic data exchange between ADP's German payroll system and government agencies (social insurance carriers, tax authorities, pension funds, health insurance providers).
|
||||||
|
|
||||||
|
## Value Proposition
|
||||||
|
|
||||||
|
- Single repository for 25+ compliance modules — atomic commits, shared libraries, one version
|
||||||
|
- Covers the full lifecycle: generate → validate → transmit → receive → process government messages
|
||||||
|
- Supports dual database modes (H2 for dev/on-prem, Oracle for production multi-tenant)
|
||||||
|
- Automated Wartungswechsel (maintenance version rotation) across past/current/future branches
|
||||||
|
|
||||||
|
## Key Features & Modules
|
||||||
|
|
||||||
|
| Module | Domain | Purpose |
|
||||||
|
|--------|--------|---------|
|
||||||
|
| **eau** | Sick-leave certificates | Electronic work incapacity certificates (eAU) |
|
||||||
|
| **eau-connector** | eAU transport | Elscomfort gateway integration for eAU |
|
||||||
|
| **eubp** | Electronic tax audit | EuBP — Elektronische Übermittlung der Beitragspflichtigen |
|
||||||
|
| **svbea** | Social insurance | SV-Beitragserhebung — contribution assessment notifications |
|
||||||
|
| **babea** | Social insurance | BABEA — Beitragsabrechnung notifications |
|
||||||
|
| **dabpv** | Pension insurance | DaBPV — Datenaustausch Beitragspflichtversicherung |
|
||||||
|
| **svmodules** | SV messages | SVMeldungen — social insurance message generation |
|
||||||
|
| **rvbea** | Pension | RV-BEA — pension insurance notifications |
|
||||||
|
| **dsvv** | SV procedures | DSVV — Datensatz Versicherungsverlauf |
|
||||||
|
| **dsbd** | SV procedures | DSBD — Datensatz Betriebsdaten |
|
||||||
|
| **estatistik** | Statistics | Employment statistics reporting |
|
||||||
|
| **lstbprint** | Tax | Lohnsteuerbescheinigung printing |
|
||||||
|
| **gfmnrgts** | Regulatory | GKV-Finanzmanagement regulatory |
|
||||||
|
| **dls** | Data logistics | Data logistics service |
|
||||||
|
| **doc-gen** | Documents | Document generation |
|
||||||
|
| **eusan-gen** | Sanctions | EU/US sanctions list download & COBOL .DAT conversion |
|
||||||
|
| **blzabgleich** | Banking | Bank code reconciliation |
|
||||||
|
| **taetigkeitsschluessel** | Occupation codes | Activity key management |
|
||||||
|
| **meldezentrale** | Message hub | Central message routing service (Docker-deployed) |
|
||||||
|
| **answering-machine** | Testing | Government response simulator (React + Spring Boot) |
|
||||||
|
| **kernpruefung-rest** | Validation | XML schema validation REST service |
|
||||||
|
|
||||||
|
## Target Users
|
||||||
|
|
||||||
|
- **ADP Germany payroll operations** — automated compliance processing for thousands of employer clients
|
||||||
|
- **ADP developers** — building and maintaining government data exchange modules
|
||||||
|
- **QA teams** — using answering-machine to simulate government responses
|
||||||
|
|
||||||
|
## Deployment Targets
|
||||||
|
|
||||||
|
- **On-premises**: JAR-based deployment via Artifactory (H2 database)
|
||||||
|
- **Cloud (EKS)**: Docker containers for answering-machine, meldezentrale, NATS, kernpruefung-rest
|
||||||
|
- **Kubernetes clusters**: `eks-awsadpworldiat-pr` (DIT), `eks-awsdev6` (dev)
|
||||||
|
|
||||||
|
## Current Version
|
||||||
|
|
||||||
|
`123.4.2` (from `version.json`) — SemVer with `past/current/future` branch rotation.
|
||||||
@@ -0,0 +1,120 @@
|
|||||||
|
# Paisy — Technology Stack
|
||||||
|
|
||||||
|
## Languages & Runtimes
|
||||||
|
|
||||||
|
| Technology | Version | Usage |
|
||||||
|
|-----------|---------|-------|
|
||||||
|
| Java | 17 (compiler release) | All backend modules |
|
||||||
|
| JavaScript/Node.js | Node 24 (Chainguard) | Answering-machine React frontend |
|
||||||
|
| Groovy | (Jenkins) | Jenkinsfile pipeline scripting |
|
||||||
|
| JavaScript | ES6+ | `gen_trigger.js` — Quidam ISAM trigger generation |
|
||||||
|
| SQL | H2 + Oracle dialects | Database migrations and queries |
|
||||||
|
|
||||||
|
## Build System
|
||||||
|
|
||||||
|
| Tool | Details |
|
||||||
|
|------|---------|
|
||||||
|
| Maven | Multi-module POM, `${revision}` for version injection |
|
||||||
|
| Maven Wrapper | Not used — relies on CI image Maven |
|
||||||
|
| npm | Frontend build for `am-frontend/` |
|
||||||
|
|
||||||
|
### Key Maven Commands
|
||||||
|
|
||||||
|
```bash
|
||||||
|
# Full build
|
||||||
|
mvn clean install -f java/pom.xml --batch-mode -U -Drevision=<version>
|
||||||
|
|
||||||
|
# Single module with dependencies
|
||||||
|
mvn clean install -pl modules/cs-modules/<module> -am -DskipTests
|
||||||
|
|
||||||
|
# Deploy to Artifactory
|
||||||
|
mvn deploy -f java/pom.xml -DskipTests --batch-mode -U -Drevision=<version>
|
||||||
|
```
|
||||||
|
|
||||||
|
## Frameworks & Libraries
|
||||||
|
|
||||||
|
### Core
|
||||||
|
|
||||||
|
| Library | Version | Purpose |
|
||||||
|
|---------|---------|---------|
|
||||||
|
| Spring Boot | 3.5.11 | Application framework |
|
||||||
|
| Spring Shell | 3.3.3 | CLI command dispatch |
|
||||||
|
| Lombok | (managed) | Boilerplate reduction (`@Data`, `@Builder`, `@Slf4j`) |
|
||||||
|
| H2 Database | 2.4.240 | Dev/on-prem embedded database |
|
||||||
|
| Flyway | (Spring Boot managed) | Database migrations |
|
||||||
|
| JPA/Hibernate | (Spring Boot managed) | ORM layer |
|
||||||
|
|
||||||
|
### Data Processing
|
||||||
|
|
||||||
|
| Library | Purpose |
|
||||||
|
|---------|---------|
|
||||||
|
| JAXB | XML marshalling/unmarshalling for GKV data exchange |
|
||||||
|
| Apache Commons CSV | Semicolon-delimited CSV (ISO-8859-1) |
|
||||||
|
| Custom `flatfile-parser` | German flat-file format with `@Datenbaustein`/`@DBField` annotations |
|
||||||
|
|
||||||
|
### Infrastructure
|
||||||
|
|
||||||
|
| Technology | Purpose |
|
||||||
|
|-----------|---------|
|
||||||
|
| NATS JetStream | Message broker (subject: `{bbnr}.{ak}.{app}.{stage}[.{type}]`) |
|
||||||
|
| Docker | Container builds for AM, Meldezentrale, NATS |
|
||||||
|
| Kubernetes (EKS) | Cloud deployment target |
|
||||||
|
| Helm | Kubernetes deployment charts (`ferris-wheel/web-service`) |
|
||||||
|
|
||||||
|
## CI/CD
|
||||||
|
|
||||||
|
| Component | Details |
|
||||||
|
|-----------|---------|
|
||||||
|
| Jenkins | Pipeline-as-code via `Jenkinsfile` |
|
||||||
|
| Jenkins Library | `@Library('adp-jenkins')` — shared pipeline library |
|
||||||
|
| Docker Images | `maven:3.9-jdk-17` (main), `maven:3.8.3-jdk-11` (kernpruefung-rest) |
|
||||||
|
| Artifactory | `repository.esi.adp.com/RD-GERMANY/` — Maven + Docker registry |
|
||||||
|
| SonarQube | Code quality scanning (non-release branches) |
|
||||||
|
| Secrets Scan | `secretsScan()` in pipeline |
|
||||||
|
|
||||||
|
### Pipeline Stages
|
||||||
|
|
||||||
|
1. **Wartungswechsel** — version rotation across past/current/future branches
|
||||||
|
2. **Build** — Maven compile + test for `java/pom.xml`
|
||||||
|
3. **Sonar + Secrets** — quality gate + secrets detection
|
||||||
|
4. **Docker Build** — AM, Meldezentrale, NATS (parallel)
|
||||||
|
5. **Cherry-pick** — auto-propagate merges upward (past→current→future)
|
||||||
|
6. **Deploy** — Artifactory publish + Kubernetes deploy
|
||||||
|
7. **Tag Release** — Git tag on release branches
|
||||||
|
8. **Version Update** — auto-bump patch version
|
||||||
|
9. **EusanGen** — standalone sanctions list update (manual or `eusan/*` branch trigger)
|
||||||
|
|
||||||
|
## Database
|
||||||
|
|
||||||
|
| Mode | Engine | Usage |
|
||||||
|
|------|--------|-------|
|
||||||
|
| Development | H2 (file-based) | Local dev, testing, legacy on-prem |
|
||||||
|
| Production | Oracle | Multi-tenant, shared schema per BBNR |
|
||||||
|
|
||||||
|
### Migration Naming Convention
|
||||||
|
```
|
||||||
|
V{yyyy_MM_dd_HH_mm_ss}__C_{app_revision}_{entity_name}.sql
|
||||||
|
```
|
||||||
|
Separate directories: `db/migration/ORACLE/` and `db/migration/H2/`
|
||||||
|
|
||||||
|
## Encoding
|
||||||
|
|
||||||
|
- Source files: **UTF-8**
|
||||||
|
- CSV files: **ISO-8859-1** (German government standard)
|
||||||
|
- Flat files: **ISO-8859-1** (DSRV/ITSG format)
|
||||||
|
|
||||||
|
## Docker Registry
|
||||||
|
|
||||||
|
| Image | Registry Path |
|
||||||
|
|-------|--------------|
|
||||||
|
| Answering Machine | `docker.repository.esi.adp.com/paisy/answering-machine` |
|
||||||
|
| Meldezentrale | `docker.repository.esi.adp.com/paisy/meldezentrale` |
|
||||||
|
| NATS | `docker.repository.esi.adp.com/paisy/nats` |
|
||||||
|
| Kernprüfung REST | `docker.repository.esi.adp.com/paisy/kernpruefung-rest-service` |
|
||||||
|
|
||||||
|
## Kubernetes Clusters
|
||||||
|
|
||||||
|
| Cluster | Namespace | Purpose |
|
||||||
|
|---------|-----------|---------|
|
||||||
|
| `eks-awsadpworldiat-pr` | `paisyservices-dit` | DIT environment (AM, MZ, NATS) |
|
||||||
|
| `eks-awsdev6` | `pa-kernpruefung-rest-service-dev` | Dev (Kernprüfung REST) |
|
||||||
@@ -0,0 +1,199 @@
|
|||||||
|
# Skill: code-review
|
||||||
|
|
||||||
|
Structured code review against implementation plan.
|
||||||
|
|
||||||
|
## Invoked by
|
||||||
|
|
||||||
|
🔍 Reviewer mode
|
||||||
|
|
||||||
|
## Required Inputs
|
||||||
|
|
||||||
|
| Input | Source | Example |
|
||||||
|
|-------|--------|---------|
|
||||||
|
| `TICKET_KEY` | Jira issue key | `ESIDEPAISY-12081` |
|
||||||
|
| `MODULE` | PAISY module name | `eau`, `eubp`, `svmeldungen` |
|
||||||
|
|
||||||
|
## Output
|
||||||
|
|
||||||
|
Markdown file: `docs/<MODULE>/<TICKET_KEY>/<TICKET_KEY>-review.md`
|
||||||
|
|
||||||
|
## Steps
|
||||||
|
|
||||||
|
### 1. Read the plan document
|
||||||
|
|
||||||
|
```bash
|
||||||
|
cat docs/<MODULE>/<TICKET_KEY>/<TICKET_KEY>-plan.md
|
||||||
|
```
|
||||||
|
|
||||||
|
Extract: planned changes, affected files, expected patterns, acceptance criteria.
|
||||||
|
|
||||||
|
### 2. Read the test plan (if exists)
|
||||||
|
|
||||||
|
```bash
|
||||||
|
cat docs/<MODULE>/<TICKET_KEY>/<TICKET_KEY>-testplan.md
|
||||||
|
```
|
||||||
|
|
||||||
|
Cross-reference: are all planned test cases implemented?
|
||||||
|
|
||||||
|
### 3. Get the diff
|
||||||
|
|
||||||
|
```bash
|
||||||
|
cd /Users/pplate/git/paisy-<TICKET_KEY>
|
||||||
|
git diff origin/current --name-only
|
||||||
|
git diff origin/current --stat
|
||||||
|
git diff origin/current
|
||||||
|
```
|
||||||
|
|
||||||
|
### 4. Read changed files
|
||||||
|
|
||||||
|
For each changed file, read the full file to understand context — not just the diff hunks.
|
||||||
|
|
||||||
|
```bash
|
||||||
|
cd /Users/pplate/git/paisy-<TICKET_KEY>
|
||||||
|
git diff origin/current --name-only | while read f; do echo "=== $f ==="; done
|
||||||
|
```
|
||||||
|
|
||||||
|
### 5. Run the review checklist
|
||||||
|
|
||||||
|
For each changed file, verify:
|
||||||
|
|
||||||
|
| # | Check | What to look for |
|
||||||
|
|---|-------|-----------------|
|
||||||
|
| 1 | Plan compliance | All plan items implemented? Nothing missing, nothing extra? |
|
||||||
|
| 2 | Pattern correctness | Correct PAISY patterns used? (AbstractMeldung, Datenbaustein, ServiceCenter, EMFactory, JAXB) |
|
||||||
|
| 3 | No `src.gen/` changes | Generated sources must never be modified manually |
|
||||||
|
| 4 | Logging | `@Slf4j` or `@Log4j2` with parameterized messages (`log.debug("x: {}", v)`) — no string concatenation |
|
||||||
|
| 5 | German domain terms | Domain terms preserved: `Fehlzeiten`, `Lohnkonto`, `Vorlaufsatz`, `Nachlaufsatz` |
|
||||||
|
| 6 | Error handling | PAISY `F;` responses checked before parsing? Null-safe patterns? |
|
||||||
|
| 7 | Date handling | Correct formatters? Empty date checks (`00.00.0000`, `0000000`, `9999999`)? |
|
||||||
|
| 8 | Test coverage | Every new/modified public method has a test? Edge cases covered? |
|
||||||
|
| 9 | Flyway migrations | Correct naming convention? Dual H2/Oracle? Type mapping correct? |
|
||||||
|
| 10 | No hardcoded values | No hardcoded BBNR, sprint IDs, Epic keys, instance names? |
|
||||||
|
| 11 | Field visibility | `protected` for shared fields, `private` with Lombok for DTOs? |
|
||||||
|
| 12 | Annotations | Correct use of `@Service`/`@Lazy`, `@Transactional`, `@XmlElement`? |
|
||||||
|
|
||||||
|
### 6. Check test quality
|
||||||
|
|
||||||
|
```bash
|
||||||
|
cd /Users/pplate/git/paisy-<TICKET_KEY>
|
||||||
|
# Find new/modified test files
|
||||||
|
git diff origin/current --name-only | grep -E "Test\.java$"
|
||||||
|
```
|
||||||
|
|
||||||
|
For each test file:
|
||||||
|
- Meaningful assertions (not just `assertNotNull`)?
|
||||||
|
- Edge cases covered?
|
||||||
|
- Mocking done correctly (Mockito patterns)?
|
||||||
|
- Test naming convention: `test<What>_<Scenario>_<Expected>()`?
|
||||||
|
|
||||||
|
### 7. Run tests
|
||||||
|
|
||||||
|
```bash
|
||||||
|
cd /Users/pplate/git/paisy-<TICKET_KEY>
|
||||||
|
mvn test -pl java/modules/cs-modules/<MODULE> -f java/pom.xml
|
||||||
|
```
|
||||||
|
|
||||||
|
### 8. Generate review document
|
||||||
|
|
||||||
|
Write `docs/<MODULE>/<TICKET_KEY>/<TICKET_KEY>-review.md`:
|
||||||
|
|
||||||
|
```markdown
|
||||||
|
# Code Review: <TICKET_KEY> — <Summary>
|
||||||
|
|
||||||
|
**Datum:** <today>
|
||||||
|
**Modul:** <MODULE>
|
||||||
|
**Reviewer:** Roo (Reviewer)
|
||||||
|
**Branch:** <branch name>
|
||||||
|
**Status:** ✅ Approved / ⚠️ Approved with comments / ❌ Changes requested
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## Zusammenfassung
|
||||||
|
|
||||||
|
<1-2 sentence summary of the review outcome>
|
||||||
|
|
||||||
|
## Geprüfte Dateien
|
||||||
|
|
||||||
|
| Datei | Änderung | Bewertung |
|
||||||
|
|-------|---------|-----------|
|
||||||
|
| `<path>` | Neu/Geändert | ✅ / ⚠️ / ❌ |
|
||||||
|
|
||||||
|
## Checkliste
|
||||||
|
|
||||||
|
| # | Prüfpunkt | Ergebnis | Anmerkung |
|
||||||
|
|---|-----------|----------|-----------|
|
||||||
|
| 1 | Plan-Konformität | ✅ | Alle geplanten Änderungen umgesetzt |
|
||||||
|
| 2 | Pattern-Korrektheit | ✅ | AbstractMeldung korrekt erweitert |
|
||||||
|
| 3 | Keine src.gen/ Änderungen | ✅ | — |
|
||||||
|
| 4 | Logging | ⚠️ | Zeile 42: String-Konkatenation → parameterized |
|
||||||
|
| 5 | Deutsche Domänenbegriffe | ✅ | — |
|
||||||
|
| 6 | Fehlerbehandlung | ✅ | F;-Prüfung vorhanden |
|
||||||
|
| 7 | Datumsbehandlung | ✅ | — |
|
||||||
|
| 8 | Testabdeckung | ✅ | 7 Tests, alle bestanden |
|
||||||
|
| 9 | Flyway-Migrationen | ✅ | H2 + Oracle korrekt |
|
||||||
|
| 10 | Keine Hardcoded-Werte | ✅ | — |
|
||||||
|
| 11 | Feld-Sichtbarkeit | ✅ | — |
|
||||||
|
| 12 | Annotationen | ✅ | — |
|
||||||
|
|
||||||
|
## Befunde
|
||||||
|
|
||||||
|
### ⚠️ Hinweise (non-blocking)
|
||||||
|
|
||||||
|
1. **<file>:<line>** — <description of finding>
|
||||||
|
- Empfehlung: <suggested fix>
|
||||||
|
|
||||||
|
### ❌ Blocker (must fix)
|
||||||
|
|
||||||
|
1. **<file>:<line>** — <description of critical finding>
|
||||||
|
- Begründung: <why this must be fixed>
|
||||||
|
|
||||||
|
## Tests
|
||||||
|
|
||||||
|
- **Ausgeführt:** <N> Tests
|
||||||
|
- **Bestanden:** <N> ✅
|
||||||
|
- **Fehlgeschlagen:** <N> ❌
|
||||||
|
- **Build:** ✅ Grün / ❌ Rot
|
||||||
|
|
||||||
|
## Empfehlung
|
||||||
|
|
||||||
|
<Final recommendation: merge / fix and re-review / reject>
|
||||||
|
```
|
||||||
|
|
||||||
|
### 9. Store in BigMind
|
||||||
|
|
||||||
|
```python
|
||||||
|
memory_store_fact(
|
||||||
|
category="codebase",
|
||||||
|
fact=f"{TICKET_KEY}: Code review completed — {status}. {findings_count} findings ({blockers} blockers)."
|
||||||
|
)
|
||||||
|
```
|
||||||
|
|
||||||
|
## Expected Output
|
||||||
|
|
||||||
|
- Review document at `docs/<MODULE>/<TICKET_KEY>/<TICKET_KEY>-review.md`
|
||||||
|
- All tests executed and results documented
|
||||||
|
- Clear recommendation: merge / fix / reject
|
||||||
|
|
||||||
|
## Error Handling
|
||||||
|
|
||||||
|
| Error | Resolution |
|
||||||
|
|-------|------------|
|
||||||
|
| No plan document found | Review without plan — note in review that plan was missing |
|
||||||
|
| Build fails | Document build failure as blocker, don't proceed with detailed review |
|
||||||
|
| No tests found | Flag as blocker — every change needs tests |
|
||||||
|
| Worktree not found | Check if `/Users/pplate/git/paisy-<TICKET_KEY>` exists, or use main repo with branch checkout |
|
||||||
|
|
||||||
|
## Severity Levels
|
||||||
|
|
||||||
|
| Level | Symbol | Meaning | Action |
|
||||||
|
|-------|--------|---------|--------|
|
||||||
|
| Blocker | ❌ | Must fix before merge | Changes requested |
|
||||||
|
| Warning | ⚠️ | Should fix, not blocking | Approved with comments |
|
||||||
|
| Info | ℹ️ | Suggestion for improvement | Approved |
|
||||||
|
| OK | ✅ | No issues | — |
|
||||||
|
|
||||||
|
## Language
|
||||||
|
|
||||||
|
- Review document: **German**
|
||||||
|
- Code references (class names, methods, patterns): English as-is
|
||||||
|
- Checklist items: German
|
||||||
@@ -0,0 +1,202 @@
|
|||||||
|
# Skill: create-flyway-migration
|
||||||
|
|
||||||
|
Generate Flyway migration SQL files for H2 and Oracle.
|
||||||
|
|
||||||
|
## Invoked by
|
||||||
|
|
||||||
|
💻 Code mode
|
||||||
|
|
||||||
|
## Required Inputs
|
||||||
|
|
||||||
|
| Input | Source | Example |
|
||||||
|
|-------|--------|---------|
|
||||||
|
| `TICKET_KEY` | Jira issue key | `ESIDEPAISY-12081` |
|
||||||
|
| `MODULE` | PAISY module name | `eau`, `eubp`, `svmeldungen`, `dabpv` |
|
||||||
|
| `ENTITY_NAME` | Table or entity being changed | `eau_rueckmeldung`, `eubp_archiv` |
|
||||||
|
| `CHANGE_TYPE` | Type of DDL change | `CREATE TABLE`, `ALTER TABLE`, `CREATE INDEX` |
|
||||||
|
|
||||||
|
## Output
|
||||||
|
|
||||||
|
- H2 migration: `java/modules/cs-modules/<MODULE>/src/main/resources/db/migration/H2/V{timestamp}__C_{revision}_{entity}.sql`
|
||||||
|
- Oracle migration: `java/modules/cs-modules/<MODULE>/src/main/resources/db/migration/ORACLE/V{timestamp}__C_{revision}_{entity}.sql`
|
||||||
|
|
||||||
|
## Steps
|
||||||
|
|
||||||
|
### 1. Determine timestamp
|
||||||
|
|
||||||
|
Generate the Flyway version timestamp in the required format:
|
||||||
|
|
||||||
|
```bash
|
||||||
|
date -u +"%Y_%m_%d_%H_%M_%S"
|
||||||
|
```
|
||||||
|
|
||||||
|
Result format: `2026_04_23_10_06_07`
|
||||||
|
|
||||||
|
### 2. Get app revision
|
||||||
|
|
||||||
|
Read the current app revision from `version.json` in the repo root:
|
||||||
|
|
||||||
|
```bash
|
||||||
|
cat version.json
|
||||||
|
```
|
||||||
|
|
||||||
|
Or extract from the parent POM:
|
||||||
|
|
||||||
|
```bash
|
||||||
|
grep -A1 '<revision>' java/pom.xml | head -2
|
||||||
|
```
|
||||||
|
|
||||||
|
The revision is the major version number (e.g., `123` from `123.4.2`).
|
||||||
|
|
||||||
|
### 3. Construct filename
|
||||||
|
|
||||||
|
```
|
||||||
|
V{timestamp}__C_{revision}_{entity_name}.sql
|
||||||
|
```
|
||||||
|
|
||||||
|
Example: `V2026_04_23_10_06_07__C_123_eau_rueckmeldung.sql`
|
||||||
|
|
||||||
|
**Note:** Double underscore `__` between version and description is mandatory Flyway convention.
|
||||||
|
|
||||||
|
### 4. Determine migration directories
|
||||||
|
|
||||||
|
Locate the module's migration directories:
|
||||||
|
|
||||||
|
```bash
|
||||||
|
ls java/modules/cs-modules/<MODULE>/src/main/resources/db/migration/
|
||||||
|
```
|
||||||
|
|
||||||
|
Expected structure:
|
||||||
|
- `db/migration/H2/` — H2-specific migrations
|
||||||
|
- `db/migration/ORACLE/` — Oracle-specific migrations
|
||||||
|
|
||||||
|
If only one directory exists, the module may use a shared migration path. Check the module's `application.properties` for `spring.flyway.locations`.
|
||||||
|
|
||||||
|
### 5. Create H2 migration
|
||||||
|
|
||||||
|
H2 supports `IF NOT EXISTS` / `IF EXISTS` clauses:
|
||||||
|
|
||||||
|
```sql
|
||||||
|
-- CREATE TABLE
|
||||||
|
CREATE TABLE IF NOT EXISTS <ENTITY_NAME> (
|
||||||
|
id BIGINT AUTO_INCREMENT PRIMARY KEY,
|
||||||
|
-- columns...
|
||||||
|
created_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP,
|
||||||
|
updated_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP
|
||||||
|
);
|
||||||
|
|
||||||
|
-- ALTER TABLE (add column)
|
||||||
|
ALTER TABLE <ENTITY_NAME> ADD COLUMN IF NOT EXISTS <column_name> <type>;
|
||||||
|
|
||||||
|
-- CREATE INDEX
|
||||||
|
CREATE INDEX IF NOT EXISTS idx_<entity>_<column> ON <ENTITY_NAME>(<column>);
|
||||||
|
|
||||||
|
-- DROP COLUMN
|
||||||
|
ALTER TABLE <ENTITY_NAME> DROP COLUMN IF EXISTS <column_name>;
|
||||||
|
```
|
||||||
|
|
||||||
|
### 6. Create Oracle migration
|
||||||
|
|
||||||
|
Oracle does NOT support `IF NOT EXISTS` — use PL/SQL blocks for idempotency when needed:
|
||||||
|
|
||||||
|
```sql
|
||||||
|
-- CREATE TABLE (simple — fails if exists, which is expected for versioned migrations)
|
||||||
|
CREATE TABLE <ENTITY_NAME> (
|
||||||
|
id NUMBER GENERATED ALWAYS AS IDENTITY PRIMARY KEY,
|
||||||
|
-- columns...
|
||||||
|
created_at TIMESTAMP DEFAULT SYSTIMESTAMP,
|
||||||
|
updated_at TIMESTAMP DEFAULT SYSTIMESTAMP
|
||||||
|
);
|
||||||
|
|
||||||
|
-- ALTER TABLE (add column — idempotent wrapper)
|
||||||
|
BEGIN
|
||||||
|
EXECUTE IMMEDIATE 'ALTER TABLE <ENTITY_NAME> ADD <column_name> <type>';
|
||||||
|
EXCEPTION
|
||||||
|
WHEN OTHERS THEN
|
||||||
|
IF SQLCODE = -1430 THEN NULL; -- column already exists
|
||||||
|
ELSE RAISE;
|
||||||
|
END IF;
|
||||||
|
END;
|
||||||
|
/
|
||||||
|
|
||||||
|
-- CREATE INDEX
|
||||||
|
CREATE INDEX idx_<entity>_<column> ON <ENTITY_NAME>(<column>);
|
||||||
|
```
|
||||||
|
|
||||||
|
### 7. Type mapping reference
|
||||||
|
|
||||||
|
| Java/H2 Type | Oracle Type | Notes |
|
||||||
|
|--------------|-------------|-------|
|
||||||
|
| `BIGINT` | `NUMBER(19)` | Primary keys |
|
||||||
|
| `INTEGER` | `NUMBER(10)` | Standard integers |
|
||||||
|
| `VARCHAR(n)` | `VARCHAR2(n)` | Strings |
|
||||||
|
| `BOOLEAN` | `NUMBER(1)` | Oracle has no native boolean |
|
||||||
|
| `TIMESTAMP` | `TIMESTAMP` | Same |
|
||||||
|
| `CLOB` | `CLOB` | Same |
|
||||||
|
| `BLOB` | `BLOB` | Same |
|
||||||
|
| `AUTO_INCREMENT` | `GENERATED ALWAYS AS IDENTITY` | Identity columns |
|
||||||
|
| `CURRENT_TIMESTAMP` | `SYSTIMESTAMP` | Default timestamp |
|
||||||
|
|
||||||
|
### 8. Register migration location (if new module)
|
||||||
|
|
||||||
|
If this is the first migration for the module, ensure the Flyway location is configured in the module's properties or EMFactory:
|
||||||
|
|
||||||
|
```java
|
||||||
|
// In EMFactory or FlywayController setup
|
||||||
|
flyway.migrate("<MODULE>", "<timestamp>");
|
||||||
|
```
|
||||||
|
|
||||||
|
Check existing modules for the pattern:
|
||||||
|
```bash
|
||||||
|
grep -rn "flyway.migrate" java/modules/cs-modules/<MODULE>/src/
|
||||||
|
```
|
||||||
|
|
||||||
|
### 9. Verify migration
|
||||||
|
|
||||||
|
Run the module's Flyway migration test to ensure the SQL is valid:
|
||||||
|
|
||||||
|
```bash
|
||||||
|
cd /Users/pplate/git/paisy-<TICKET_KEY>
|
||||||
|
mvn test -pl java/modules/cs-modules/<MODULE> -Dtest="*FlywayMigrationTest*" -f java/pom.xml
|
||||||
|
```
|
||||||
|
|
||||||
|
### 10. Store in BigMind
|
||||||
|
|
||||||
|
```python
|
||||||
|
memory_store_fact(
|
||||||
|
category="codebase",
|
||||||
|
fact=f"{TICKET_KEY}: Flyway migration V{timestamp}__C_{revision}_{entity} created for H2 + Oracle in {MODULE}"
|
||||||
|
)
|
||||||
|
```
|
||||||
|
|
||||||
|
## Expected Output
|
||||||
|
|
||||||
|
- H2 migration SQL file created in `db/migration/H2/`
|
||||||
|
- Oracle migration SQL file created in `db/migration/ORACLE/`
|
||||||
|
- Both files use correct Flyway naming convention
|
||||||
|
- Migration test passes
|
||||||
|
|
||||||
|
## Error Handling
|
||||||
|
|
||||||
|
| Error | Resolution |
|
||||||
|
|-------|------------|
|
||||||
|
| Duplicate version timestamp | Increment the seconds portion by 1 |
|
||||||
|
| H2 syntax error in test | Check H2-specific syntax (e.g., `IDENTITY` vs `AUTO_INCREMENT`) |
|
||||||
|
| Oracle PL/SQL block error | Ensure `/` terminator after PL/SQL blocks |
|
||||||
|
| Migration already applied | Flyway won't re-run versioned migrations — create a new version |
|
||||||
|
| Missing migration directory | Create `db/migration/H2/` and/or `db/migration/ORACLE/` directories |
|
||||||
|
|
||||||
|
## Conventions
|
||||||
|
|
||||||
|
- One migration file per logical change (don't combine unrelated DDL)
|
||||||
|
- H2 and Oracle files must produce equivalent schema
|
||||||
|
- Use `IF NOT EXISTS` / `IF EXISTS` in H2 for idempotency
|
||||||
|
- Oracle versioned migrations don't need idempotency (Flyway tracks them)
|
||||||
|
- Repeatable migrations use `R__` prefix instead of `V{timestamp}__`
|
||||||
|
- Comments in SQL: `-- <description>` at the top of each file
|
||||||
|
|
||||||
|
## Language
|
||||||
|
|
||||||
|
- SQL comments: English
|
||||||
|
- Column names: English (snake_case)
|
||||||
|
- Table names: English (snake_case), prefixed with module abbreviation where applicable
|
||||||
@@ -0,0 +1,168 @@
|
|||||||
|
# Skill: create-pr
|
||||||
|
|
||||||
|
Create a Bitbucket pull request from a PAISY worktree branch.
|
||||||
|
|
||||||
|
## Invoked by
|
||||||
|
|
||||||
|
🎫 JiraOps mode (or 🪃 Orchestrator delegating to JiraOps)
|
||||||
|
|
||||||
|
## Required Inputs
|
||||||
|
|
||||||
|
| Input | Source | Example |
|
||||||
|
|-------|--------|---------|
|
||||||
|
| `TICKET_KEY` | Jira issue key | `ESIDEPAISY-12081` |
|
||||||
|
| `MODULE` | PAISY module name | `eau`, `eubp`, `svmeldungen` |
|
||||||
|
|
||||||
|
## Output
|
||||||
|
|
||||||
|
- Bitbucket PR created targeting `current` branch
|
||||||
|
- Jira comment with PR link added
|
||||||
|
- BigMind fact stored
|
||||||
|
|
||||||
|
## Steps
|
||||||
|
|
||||||
|
### 1. Get current branch
|
||||||
|
|
||||||
|
```bash
|
||||||
|
cd /Users/pplate/git/paisy-<TICKET_KEY>
|
||||||
|
git branch --show-current
|
||||||
|
```
|
||||||
|
|
||||||
|
Expected format: `current/feature/<module>/<TICKET_KEY>-<desc>` or `current/bugfix/<module>/<TICKET_KEY>-<desc>`
|
||||||
|
|
||||||
|
### 2. Ensure all changes are committed
|
||||||
|
|
||||||
|
```bash
|
||||||
|
cd /Users/pplate/git/paisy-<TICKET_KEY>
|
||||||
|
git status
|
||||||
|
```
|
||||||
|
|
||||||
|
If uncommitted changes exist, warn the user before proceeding.
|
||||||
|
|
||||||
|
### 3. Push branch to origin
|
||||||
|
|
||||||
|
```bash
|
||||||
|
cd /Users/pplate/git/paisy-<TICKET_KEY>
|
||||||
|
git push -u origin <BRANCH>
|
||||||
|
```
|
||||||
|
|
||||||
|
### 4. Gather diff statistics
|
||||||
|
|
||||||
|
```bash
|
||||||
|
cd /Users/pplate/git/paisy-<TICKET_KEY>
|
||||||
|
git diff origin/current --stat
|
||||||
|
git diff origin/current --name-only
|
||||||
|
```
|
||||||
|
|
||||||
|
Use the stats to build the PR description.
|
||||||
|
|
||||||
|
### 5. Read Jira ticket for context
|
||||||
|
|
||||||
|
```python
|
||||||
|
ticket = retrieve_ticket_details(TICKET_KEY)
|
||||||
|
# Extract: summary, description for PR title/description
|
||||||
|
```
|
||||||
|
|
||||||
|
### 6. Compose PR title and description
|
||||||
|
|
||||||
|
PR title format (German):
|
||||||
|
```
|
||||||
|
<TICKET_KEY>: <Jira summary>
|
||||||
|
```
|
||||||
|
|
||||||
|
PR description template (German):
|
||||||
|
```markdown
|
||||||
|
## Jira
|
||||||
|
|
||||||
|
<TICKET_KEY>: <summary>
|
||||||
|
|
||||||
|
## Beschreibung
|
||||||
|
|
||||||
|
<Brief description of what was changed and why, derived from Jira ticket and plan doc>
|
||||||
|
|
||||||
|
## Änderungen
|
||||||
|
|
||||||
|
<List of changed files grouped by component, from git diff --stat>
|
||||||
|
|
||||||
|
### <Component 1>
|
||||||
|
- `<file1>` — <what changed>
|
||||||
|
- `<file2>` — <what changed>
|
||||||
|
|
||||||
|
### <Component 2>
|
||||||
|
- `<file3>` — <what changed>
|
||||||
|
|
||||||
|
## Tests
|
||||||
|
|
||||||
|
- <N> Unit-Tests
|
||||||
|
- <M> Integrationstests
|
||||||
|
- Alle Tests bestanden ✅
|
||||||
|
|
||||||
|
## Checkliste
|
||||||
|
|
||||||
|
- [ ] Code Review durchgeführt
|
||||||
|
- [ ] Tests bestanden
|
||||||
|
- [ ] Flyway-Migrationen geprüft (H2 + Oracle)
|
||||||
|
- [ ] Keine `src.gen/` Änderungen
|
||||||
|
```
|
||||||
|
|
||||||
|
### 7. Create the pull request
|
||||||
|
|
||||||
|
```python
|
||||||
|
create_pull_request(
|
||||||
|
project_key="ESIDEPAISY",
|
||||||
|
repo_slug="paisy",
|
||||||
|
title=f"{TICKET_KEY}: {summary}",
|
||||||
|
description=<composed description>,
|
||||||
|
from_branch=<BRANCH>,
|
||||||
|
to_branch="current"
|
||||||
|
)
|
||||||
|
```
|
||||||
|
|
||||||
|
### 8. Add Jira comment with PR link
|
||||||
|
|
||||||
|
```python
|
||||||
|
add_comment_to_ticket(
|
||||||
|
issue_key=TICKET_KEY,
|
||||||
|
comment=f"*Pull Request erstellt*\n\nBranch: {BRANCH}\nPR: [PR #{pr_id}|<pr_url>]\n\nÄnderungen: {N} Dateien geändert, {M} neu"
|
||||||
|
)
|
||||||
|
```
|
||||||
|
|
||||||
|
### 9. Store in BigMind
|
||||||
|
|
||||||
|
```python
|
||||||
|
memory_store_fact(
|
||||||
|
category="codebase",
|
||||||
|
fact=f"{TICKET_KEY}: PR #{pr_id} created — {BRANCH} → current. {N} files changed."
|
||||||
|
)
|
||||||
|
```
|
||||||
|
|
||||||
|
## Expected Output
|
||||||
|
|
||||||
|
- Branch pushed to origin
|
||||||
|
- Bitbucket PR created with German title/description
|
||||||
|
- Jira comment added with PR link
|
||||||
|
- BigMind fact stored
|
||||||
|
|
||||||
|
## Error Handling
|
||||||
|
|
||||||
|
| Error | Resolution |
|
||||||
|
|-------|------------|
|
||||||
|
| Branch not pushed | Run `git push -u origin <BRANCH>` first |
|
||||||
|
| Uncommitted changes | Warn user, suggest `git add` + `git commit` |
|
||||||
|
| PR already exists | Check `list_prs_for_repository` for existing PR from same branch |
|
||||||
|
| Merge conflicts | Run `git fetch origin current && git merge origin/current` in worktree, resolve conflicts |
|
||||||
|
| No diff (empty PR) | Branch is identical to `current` — nothing to merge |
|
||||||
|
|
||||||
|
## Conventions
|
||||||
|
|
||||||
|
- PR title: always starts with `TICKET_KEY:` for Jira auto-linking
|
||||||
|
- PR description: German (matches Jira language)
|
||||||
|
- Target branch: always `current` (never `master` or `main`)
|
||||||
|
- Repo: `project_key="ESIDEPAISY"`, `repo_slug="paisy"`
|
||||||
|
- One PR per ticket — don't create multiple PRs for the same branch
|
||||||
|
|
||||||
|
## Language
|
||||||
|
|
||||||
|
- PR title and description: **German**
|
||||||
|
- Branch names, file paths: English as-is
|
||||||
|
- Jira comment: **German**
|
||||||
@@ -0,0 +1,109 @@
|
|||||||
|
# Skill: create-worktree
|
||||||
|
|
||||||
|
Git worktree setup for a PAISY Jira ticket.
|
||||||
|
|
||||||
|
## Invoked by
|
||||||
|
|
||||||
|
🎫 JiraOps mode (or 🪃 Orchestrator delegating to JiraOps)
|
||||||
|
|
||||||
|
## Required Inputs
|
||||||
|
|
||||||
|
| Input | Source | Example |
|
||||||
|
|-------|--------|---------|
|
||||||
|
| `TICKET_ID` | Jira issue key | `ESIDEPAISY-12081` |
|
||||||
|
| `MODULE` | Ticket context or user input | `eau`, `eubp`, `svmeldungen`, `dabpv`, `rvbea` |
|
||||||
|
| `TYPE` | Ticket issue type (Story → feature, Bug → bugfix) | `feature` or `bugfix` |
|
||||||
|
| `SHORT_DESC` | Kebab-case summary (2-4 words) | `leftover-rueckmeldungen` |
|
||||||
|
|
||||||
|
## Steps
|
||||||
|
|
||||||
|
### 1. Parse ticket metadata
|
||||||
|
|
||||||
|
```
|
||||||
|
TICKET_KEY = e.g. "ESIDEPAISY-12081"
|
||||||
|
TICKET_NUM = e.g. "12081" (numeric part only)
|
||||||
|
```
|
||||||
|
|
||||||
|
If MODULE or TYPE are not provided, retrieve them from Jira:
|
||||||
|
- `retrieve_ticket_details(TICKET_KEY)` → read `issuetype` and `summary`
|
||||||
|
- Map issue type: `Story` / `Task` → `feature`, `Bug` → `bugfix`
|
||||||
|
- Infer module from summary keywords or ask the user
|
||||||
|
|
||||||
|
### 2. Determine branch name
|
||||||
|
|
||||||
|
```
|
||||||
|
BRANCH = current/<TYPE>/<MODULE>/<TICKET_KEY>-<SHORT_DESC>
|
||||||
|
```
|
||||||
|
|
||||||
|
Examples:
|
||||||
|
- `current/feature/eau/ESIDEPAISY-12081-leftover-rueckmeldungen`
|
||||||
|
- `current/bugfix/eau/ESIDEPAISY-12261-azvu-package-placeholder`
|
||||||
|
|
||||||
|
### 3. Ensure base branch is up to date
|
||||||
|
|
||||||
|
```bash
|
||||||
|
cd /Users/pplate/git/paisy
|
||||||
|
git fetch origin current
|
||||||
|
```
|
||||||
|
|
||||||
|
### 4. Create worktree
|
||||||
|
|
||||||
|
```bash
|
||||||
|
git worktree add /Users/pplate/git/paisy-<TICKET_KEY> -b <BRANCH> origin/current
|
||||||
|
```
|
||||||
|
|
||||||
|
This creates:
|
||||||
|
- Worktree directory: `/Users/pplate/git/paisy-<TICKET_KEY>`
|
||||||
|
- New branch: `<BRANCH>` tracking `origin/current`
|
||||||
|
|
||||||
|
### 5. Verify
|
||||||
|
|
||||||
|
```bash
|
||||||
|
cd /Users/pplate/git/paisy-<TICKET_KEY> && git branch --show-current
|
||||||
|
```
|
||||||
|
|
||||||
|
Expected output: the branch name from step 2.
|
||||||
|
|
||||||
|
### 6. Store in BigMind
|
||||||
|
|
||||||
|
```python
|
||||||
|
memory_store_fact(
|
||||||
|
category="codebase",
|
||||||
|
fact=f"{TICKET_KEY}: Worktree at /Users/pplate/git/paisy-{TICKET_KEY}, branch {BRANCH}"
|
||||||
|
)
|
||||||
|
```
|
||||||
|
|
||||||
|
### 7. Announce focus
|
||||||
|
|
||||||
|
```python
|
||||||
|
memory_announce_focus(
|
||||||
|
session_id=SESSION_ID,
|
||||||
|
description=f"Working on {TICKET_KEY} in worktree",
|
||||||
|
files=[f"/Users/pplate/git/paisy-{TICKET_KEY}"],
|
||||||
|
ide_hint="Roo"
|
||||||
|
)
|
||||||
|
```
|
||||||
|
|
||||||
|
## Expected Output
|
||||||
|
|
||||||
|
- Worktree directory exists at `/Users/pplate/git/paisy-<TICKET_KEY>`
|
||||||
|
- Branch `<BRANCH>` is checked out
|
||||||
|
- BigMind fact stored with worktree path
|
||||||
|
- Focus announced
|
||||||
|
|
||||||
|
## Error Handling
|
||||||
|
|
||||||
|
| Error | Resolution |
|
||||||
|
|-------|------------|
|
||||||
|
| Worktree already exists | Check if branch matches. If yes, reuse. If no, ask user. |
|
||||||
|
| Branch already exists | `git worktree add /Users/pplate/git/paisy-<TICKET_KEY> <BRANCH>` (without `-b`) |
|
||||||
|
| `origin/current` not found | Try `git fetch origin` first, then retry |
|
||||||
|
| Directory already exists (not a worktree) | Ask user to remove or choose different path |
|
||||||
|
|
||||||
|
## Cleanup (when ticket is done)
|
||||||
|
|
||||||
|
```bash
|
||||||
|
cd /Users/pplate/git/paisy
|
||||||
|
git worktree remove /Users/pplate/git/paisy-<TICKET_KEY>
|
||||||
|
git branch -d <BRANCH> # only after merge
|
||||||
|
```
|
||||||
@@ -0,0 +1,161 @@
|
|||||||
|
# Skill: domain-lookup
|
||||||
|
|
||||||
|
Structured domain knowledge search across all PAISY knowledge sources.
|
||||||
|
|
||||||
|
## Invoked by
|
||||||
|
|
||||||
|
Any mode (📋 Planner, ❓ Ask, 🔍 Reviewer, 💻 Code)
|
||||||
|
|
||||||
|
## Required Inputs
|
||||||
|
|
||||||
|
| Input | Source | Example |
|
||||||
|
|-------|--------|---------|
|
||||||
|
| `TOPIC` | Domain topic or question | `"EuBP Archivierung"`, `"DSAK Änderungserkennung"`, `"Fehlzeiten DBFZ"` |
|
||||||
|
| `CONTEXT` | Additional context (optional) | `"for ESIDEPAISY-12081"`, `"Oracle migration syntax"` |
|
||||||
|
|
||||||
|
## Output
|
||||||
|
|
||||||
|
- Structured summary with sources cited
|
||||||
|
- New findings stored in BigMind for future reuse
|
||||||
|
|
||||||
|
## Steps
|
||||||
|
|
||||||
|
### 1. Search BigMind facts
|
||||||
|
|
||||||
|
```python
|
||||||
|
memory_search_facts("<2-3 keywords from TOPIC>")
|
||||||
|
```
|
||||||
|
|
||||||
|
FTS5 rule: AND-matches every token. Max 3 short keywords. Long queries return 0 results.
|
||||||
|
|
||||||
|
### 2. Search BigMind chunks
|
||||||
|
|
||||||
|
```python
|
||||||
|
memory_search_chunks("<2-3 keywords from TOPIC>")
|
||||||
|
```
|
||||||
|
|
||||||
|
Check for past decisions, code snippets, or session notes related to the topic.
|
||||||
|
|
||||||
|
### 3. Semantic search (if 1+2 return nothing)
|
||||||
|
|
||||||
|
```python
|
||||||
|
memory_search_semantic("<natural language description of what you're looking for>")
|
||||||
|
```
|
||||||
|
|
||||||
|
Use this when keyword search fails — it matches by meaning, not exact words.
|
||||||
|
|
||||||
|
### 4. Check ADP Docs Wiki index
|
||||||
|
|
||||||
|
```python
|
||||||
|
memory_search_facts("<topic> adpdocs")
|
||||||
|
```
|
||||||
|
|
||||||
|
Known page IDs (from BigMind `adpdocs-index` facts):
|
||||||
|
- EAU → 25123 | EuBP → 26666 | DaBPV → 27242 | DSBD → 26747 | DSAK → 26748
|
||||||
|
- DSVV → 18714 | RvBEA → 21174 | EEL → 2724 | ELStAM → 2737 | DEÜV → 5876
|
||||||
|
- Programmabläufe → 15201 | Einzelaufrufe BATCH → 15250 | Umgebungsvariablen → 22767
|
||||||
|
- PAISY verwalten → 15180 | Datenbanken verwalten → 15184 | Fehlermeldungen → 15196
|
||||||
|
|
||||||
|
### 5. Fetch Wiki page (if page ID known)
|
||||||
|
|
||||||
|
```python
|
||||||
|
set-wiki(uri="mcp://wikis/adpdocs.de.adp.com")
|
||||||
|
get-page(title="<page title>")
|
||||||
|
```
|
||||||
|
|
||||||
|
### 6. Search Wiki (if page ID not known)
|
||||||
|
|
||||||
|
```python
|
||||||
|
set-wiki(uri="mcp://wikis/adpdocs.de.adp.com")
|
||||||
|
search-page(query="<domain keywords>")
|
||||||
|
```
|
||||||
|
|
||||||
|
Or browse by category:
|
||||||
|
```python
|
||||||
|
get-category-members(category="Meldeverfahren")
|
||||||
|
```
|
||||||
|
|
||||||
|
Key categories: `Meldeverfahren`, `Verwalterhandbuch`, `Batchabläufe`, `Client Server (CS)`, `PAISYadvanced`, `Installationshandbuch für Windows und UNIX`
|
||||||
|
|
||||||
|
### 7. Search Confluence
|
||||||
|
|
||||||
|
```python
|
||||||
|
search_confluence_by_cql("text ~ '<topic keywords>' AND space = 'ESIDEPAISY'")
|
||||||
|
```
|
||||||
|
|
||||||
|
Or broader:
|
||||||
|
```python
|
||||||
|
search_confluence_by_cql("text ~ '<topic keywords>'")
|
||||||
|
```
|
||||||
|
|
||||||
|
### 8. Search Bitbucket (for code-level context)
|
||||||
|
|
||||||
|
```python
|
||||||
|
# Check recent PRs for related changes
|
||||||
|
list_prs_for_repository(project_key="ESIDEPAISY", repo_slug="paisy", status="MERGED")
|
||||||
|
|
||||||
|
# Or find a specific file
|
||||||
|
find_file(project_key="ESIDEPAISY", repo_slug="paisy", file_path="<path>", branch="current")
|
||||||
|
```
|
||||||
|
|
||||||
|
### 9. Web scraper (last resort only)
|
||||||
|
|
||||||
|
```python
|
||||||
|
webscraper_fetch(url="<relevant URL>")
|
||||||
|
```
|
||||||
|
|
||||||
|
**Only use if all previous sources returned nothing.** Never skip to webscraper if BigMind or Wiki MCP can answer.
|
||||||
|
|
||||||
|
### 10. Store new findings
|
||||||
|
|
||||||
|
After finding useful information, immediately store it:
|
||||||
|
|
||||||
|
```python
|
||||||
|
# For Wiki page discoveries
|
||||||
|
memory_store_fact(
|
||||||
|
category="adpdocs-index",
|
||||||
|
fact=f"ADP Docs Wiki: '<page title>' (Page ID: {page_id}) — <brief description of content>"
|
||||||
|
)
|
||||||
|
|
||||||
|
# For domain knowledge
|
||||||
|
memory_store_fact(
|
||||||
|
category="codebase",
|
||||||
|
fact=f"<domain topic>: <key finding>. Source: <where it came from>"
|
||||||
|
)
|
||||||
|
|
||||||
|
# For detailed findings
|
||||||
|
memory_append_chunk(
|
||||||
|
session_id=SESSION_ID,
|
||||||
|
content=f"Domain lookup for '{TOPIC}':\n<detailed findings with sources>",
|
||||||
|
flag_reason="domain knowledge"
|
||||||
|
)
|
||||||
|
```
|
||||||
|
|
||||||
|
## Expected Output
|
||||||
|
|
||||||
|
- Structured answer with cited sources
|
||||||
|
- Priority: BigMind facts → BigMind chunks → ADP Docs Wiki → Confluence → Bitbucket → webscraper
|
||||||
|
- New findings stored in BigMind for future lookups
|
||||||
|
|
||||||
|
## Error Handling
|
||||||
|
|
||||||
|
| Error | Resolution |
|
||||||
|
|-------|------------|
|
||||||
|
| BigMind FTS returns 0 | Reduce to 2 keywords, try synonyms, then use semantic search |
|
||||||
|
| Wiki page not found | Try `search-page` with different keywords, or browse category members |
|
||||||
|
| Confluence returns nothing | Broaden CQL query, remove space filter |
|
||||||
|
| All sources empty | Report "no information found" honestly — don't fabricate answers |
|
||||||
|
| Wiki connection error | Ensure `set-wiki` was called first with correct URI |
|
||||||
|
|
||||||
|
## Search Strategy Tips
|
||||||
|
|
||||||
|
- **German domain terms** often work better than English: `Fehlzeiten` not `absences`, `Lohnkonto` not `payroll account`
|
||||||
|
- **Abbreviations** are common: `DSAK`, `DSBD`, `DSVV`, `EuBP`, `DaBPV`, `RvBEA`, `EEL`
|
||||||
|
- **PAISY program names** are searchable: `PAI022`, `PAI028`, `PAI030`, `PAIBATCH`
|
||||||
|
- **Error codes** from PAISY start with `F;` — search for the specific code in Wiki Fehlermeldungen page (15196)
|
||||||
|
|
||||||
|
## Language
|
||||||
|
|
||||||
|
- Search queries: match the source language (German for Wiki/Confluence, English for code)
|
||||||
|
- Output summary: match the user's language
|
||||||
|
- Stored facts: English (BigMind convention)
|
||||||
@@ -0,0 +1,154 @@
|
|||||||
|
# Skill: generate-assessment
|
||||||
|
|
||||||
|
Structured assessment document from Jira ticket and code analysis.
|
||||||
|
|
||||||
|
## Invoked by
|
||||||
|
|
||||||
|
📋 Planner mode
|
||||||
|
|
||||||
|
## Required Inputs
|
||||||
|
|
||||||
|
| Input | Source | Example |
|
||||||
|
|-------|--------|---------|
|
||||||
|
| `TICKET_KEY` | Jira issue key | `ESIDEPAISY-12081` |
|
||||||
|
| `MODULE` | PAISY module name | `eau`, `eubp`, `svmeldungen` |
|
||||||
|
|
||||||
|
## Output
|
||||||
|
|
||||||
|
Markdown file: `docs/<MODULE>/<TICKET_KEY>/<TICKET_KEY>-assessment.md`
|
||||||
|
|
||||||
|
## Steps
|
||||||
|
|
||||||
|
### 1. Gather context from BigMind
|
||||||
|
|
||||||
|
```python
|
||||||
|
memory_search_facts("<MODULE> <relevant keywords>")
|
||||||
|
memory_search_chunks("<MODULE> <relevant keywords>")
|
||||||
|
memory_search_semantic("<natural language description of the problem>")
|
||||||
|
```
|
||||||
|
|
||||||
|
### 2. Read Jira ticket
|
||||||
|
|
||||||
|
```python
|
||||||
|
retrieve_ticket_details(TICKET_KEY)
|
||||||
|
# Extract: summary, description, acceptance criteria (customfield_10510)
|
||||||
|
# Note the Feature Link (customfield_10001) for traceability
|
||||||
|
```
|
||||||
|
|
||||||
|
### 3. Search ADP Wiki for domain context
|
||||||
|
|
||||||
|
```python
|
||||||
|
# Check BigMind index first
|
||||||
|
memory_search_facts("<domain topic> adpdocs")
|
||||||
|
|
||||||
|
# If page ID known, fetch directly
|
||||||
|
set-wiki(uri="mcp://wikis/adpdocs.de.adp.com")
|
||||||
|
get-page(title="<relevant page>")
|
||||||
|
|
||||||
|
# If not known, search
|
||||||
|
search-page(query="<domain keywords>")
|
||||||
|
```
|
||||||
|
|
||||||
|
### 4. Search Confluence for prior decisions
|
||||||
|
|
||||||
|
```python
|
||||||
|
search_confluence_by_cql("text ~ '<TICKET_KEY>' OR text ~ '<topic keywords>'")
|
||||||
|
```
|
||||||
|
|
||||||
|
### 5. Analyze affected source code
|
||||||
|
|
||||||
|
- Identify the module entry point: `java/modules/cs-modules/<MODULE>/`
|
||||||
|
- Read key classes mentioned in the ticket
|
||||||
|
- Trace the data flow through the affected components
|
||||||
|
- Note patterns used: AbstractMeldung, Datenbaustein, ServiceCenter, EMFactory, JAXB, etc.
|
||||||
|
|
||||||
|
### 6. Generate assessment document
|
||||||
|
|
||||||
|
Write `docs/<MODULE>/<TICKET_KEY>/<TICKET_KEY>-assessment.md` with this structure:
|
||||||
|
|
||||||
|
```markdown
|
||||||
|
# Assessment: <TICKET_KEY> — <Summary>
|
||||||
|
|
||||||
|
**Datum:** <today>
|
||||||
|
**Modul:** <MODULE>
|
||||||
|
**Autor:** Patrick Plate / Roo (Planner)
|
||||||
|
**Status:** Entwurf v1
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## 1. Problemanalyse
|
||||||
|
|
||||||
|
<What is the problem? Why does it need to be solved? Reference Jira ticket.>
|
||||||
|
|
||||||
|
## 2. Betroffene Komponenten
|
||||||
|
|
||||||
|
| Komponente | Pfad | Rolle |
|
||||||
|
|-----------|------|-------|
|
||||||
|
| <Class> | <path> | <what it does> |
|
||||||
|
|
||||||
|
## 3. Ist-Zustand
|
||||||
|
|
||||||
|
<How does the current code work? Data flow, key methods, patterns used.>
|
||||||
|
|
||||||
|
## 4. Risikobewertung
|
||||||
|
|
||||||
|
| Risiko | Wahrscheinlichkeit | Auswirkung | Mitigation |
|
||||||
|
|--------|-------------------|------------|------------|
|
||||||
|
| <risk> | Hoch/Mittel/Niedrig | <impact> | <mitigation> |
|
||||||
|
|
||||||
|
## 5. Lösungsoptionen
|
||||||
|
|
||||||
|
### Option A: <name>
|
||||||
|
- **Beschreibung:** ...
|
||||||
|
- **Vorteile:** ...
|
||||||
|
- **Nachteile:** ...
|
||||||
|
- **Aufwand:** ...
|
||||||
|
|
||||||
|
### Option B: <name>
|
||||||
|
- **Beschreibung:** ...
|
||||||
|
- **Vorteile:** ...
|
||||||
|
- **Nachteile:** ...
|
||||||
|
- **Aufwand:** ...
|
||||||
|
|
||||||
|
## 6. Empfehlung
|
||||||
|
|
||||||
|
<Which option and why. Reference PAISY patterns, domain constraints, prior art.>
|
||||||
|
|
||||||
|
## 7. Offene Fragen
|
||||||
|
|
||||||
|
- [ ] <question 1>
|
||||||
|
- [ ] <question 2>
|
||||||
|
```
|
||||||
|
|
||||||
|
### 7. Present to user
|
||||||
|
|
||||||
|
- Show the assessment summary
|
||||||
|
- Explicitly ask: **"Assessment v1 erstellt. GO / Feedback?"**
|
||||||
|
- On feedback: revise and increment version (v2, v3, ...)
|
||||||
|
|
||||||
|
### 8. Store findings in BigMind
|
||||||
|
|
||||||
|
```python
|
||||||
|
memory_store_fact(
|
||||||
|
category="codebase",
|
||||||
|
fact=f"{TICKET_KEY}: Assessment completed. <key finding summary>"
|
||||||
|
)
|
||||||
|
memory_append_chunk(
|
||||||
|
session_id=SESSION_ID,
|
||||||
|
content=f"Assessment for {TICKET_KEY}: <detailed findings>",
|
||||||
|
flag_reason="assessment findings"
|
||||||
|
)
|
||||||
|
```
|
||||||
|
|
||||||
|
## Language
|
||||||
|
|
||||||
|
- Document content: **German** (PAISY domain convention)
|
||||||
|
- Technical terms (class names, patterns, tools): keep as-is in English
|
||||||
|
- Section headers: German
|
||||||
|
|
||||||
|
## Conventions
|
||||||
|
|
||||||
|
- Date format: `dd.MM.yyyy` (German)
|
||||||
|
- Version tracking: v1, v2, v3 in the Status field
|
||||||
|
- File location: always under `docs/<MODULE>/<TICKET_KEY>/`
|
||||||
|
- Reference existing plan docs if they exist (check `ls docs/<MODULE>/<TICKET_KEY>/`)
|
||||||
@@ -0,0 +1,185 @@
|
|||||||
|
# Skill: generate-handover
|
||||||
|
|
||||||
|
Generate handover document for session or person transfer.
|
||||||
|
|
||||||
|
## Invoked by
|
||||||
|
|
||||||
|
📝 DocGen mode (or 🪃 Orchestrator delegating to DocGen)
|
||||||
|
|
||||||
|
## Required Inputs
|
||||||
|
|
||||||
|
| Input | Source | Example |
|
||||||
|
|-------|--------|---------|
|
||||||
|
| `TICKET_KEY` | Jira issue key | `ESIDEPAISY-12081` |
|
||||||
|
| `MODULE` | PAISY module name | `eau`, `eubp`, `svmeldungen` |
|
||||||
|
| `SESSION_ID` | BigMind session to hand over (optional) | `d8a0f4fa-59ee-48c0-b863-a51bc6294331` |
|
||||||
|
|
||||||
|
## Output
|
||||||
|
|
||||||
|
Markdown file: `docs/<MODULE>/<TICKET_KEY>/<TICKET_KEY>-handover-<date>.md`
|
||||||
|
|
||||||
|
## Steps
|
||||||
|
|
||||||
|
### 1. Read BigMind session context
|
||||||
|
|
||||||
|
```python
|
||||||
|
# If SESSION_ID provided, get the full session detail
|
||||||
|
memory_get_session_detail(session_id=SESSION_ID)
|
||||||
|
|
||||||
|
# Also search for all facts related to this ticket
|
||||||
|
memory_search_facts("<TICKET_KEY>")
|
||||||
|
memory_search_chunks("<TICKET_KEY>")
|
||||||
|
```
|
||||||
|
|
||||||
|
### 2. Read git status
|
||||||
|
|
||||||
|
```bash
|
||||||
|
cd /Users/pplate/git/paisy-<TICKET_KEY>
|
||||||
|
git branch --show-current
|
||||||
|
git status
|
||||||
|
git log origin/current..HEAD --oneline
|
||||||
|
git diff origin/current --stat
|
||||||
|
```
|
||||||
|
|
||||||
|
### 3. Read Jira ticket status
|
||||||
|
|
||||||
|
```python
|
||||||
|
ticket = retrieve_ticket_details(TICKET_KEY)
|
||||||
|
# Extract: status, assignee, summary, checklist state
|
||||||
|
checklist = get_checklist(TICKET_KEY)
|
||||||
|
comments = retrieve_ticket_comments(TICKET_KEY)
|
||||||
|
```
|
||||||
|
|
||||||
|
### 4. Read existing documentation
|
||||||
|
|
||||||
|
```bash
|
||||||
|
ls docs/<MODULE>/<TICKET_KEY>/
|
||||||
|
```
|
||||||
|
|
||||||
|
Read all available docs:
|
||||||
|
- Assessment (`*-assessment.md`)
|
||||||
|
- Plan (`*-plan.md`)
|
||||||
|
- Test plan (`*-testplan.md`)
|
||||||
|
- Solution doc (`*-solution.md`)
|
||||||
|
- Review (`*-review.md`)
|
||||||
|
|
||||||
|
### 5. Analyze what's done vs. remaining
|
||||||
|
|
||||||
|
Cross-reference:
|
||||||
|
- Jira checklist items (done vs. open)
|
||||||
|
- Git commits (what's been implemented)
|
||||||
|
- Test plan status (which tests pass/fail/pending)
|
||||||
|
- Plan document (which steps are complete)
|
||||||
|
|
||||||
|
### 6. Generate handover document
|
||||||
|
|
||||||
|
Write `docs/<MODULE>/<TICKET_KEY>/<TICKET_KEY>-handover-<YYYY-MM-DD>.md`:
|
||||||
|
|
||||||
|
```markdown
|
||||||
|
# Handover: <TICKET_KEY> — <Summary>
|
||||||
|
|
||||||
|
**Datum:** <today>
|
||||||
|
**Modul:** <MODULE>
|
||||||
|
**Autor:** Roo (DocGen)
|
||||||
|
**BigMind Session:** `<SESSION_ID>`
|
||||||
|
**Branch:** <current branch>
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## 1. Aktueller Stand
|
||||||
|
|
||||||
|
**Jira-Status:** <status>
|
||||||
|
**Fortschritt:** <X>/<Y> Checklist-Punkte erledigt
|
||||||
|
|
||||||
|
<1-3 sentence summary of where things stand>
|
||||||
|
|
||||||
|
## 2. Erledigte Arbeiten
|
||||||
|
|
||||||
|
| # | Beschreibung | Dateien | Commit |
|
||||||
|
|---|-------------|---------|--------|
|
||||||
|
| 1 | <what was done> | `<file1>`, `<file2>` | `<short hash>` |
|
||||||
|
| 2 | <what was done> | `<file3>` | `<short hash>` |
|
||||||
|
|
||||||
|
## 3. Offene Arbeiten
|
||||||
|
|
||||||
|
| # | Beschreibung | Priorität | Geschätzter Aufwand |
|
||||||
|
|---|-------------|-----------|-------------------|
|
||||||
|
| 1 | <what remains> | Hoch/Mittel/Niedrig | <estimate> |
|
||||||
|
| 2 | <what remains> | Hoch/Mittel/Niedrig | <estimate> |
|
||||||
|
|
||||||
|
## 4. Offene Fragen / Blocker
|
||||||
|
|
||||||
|
| # | Frage/Blocker | Kontext | Ansprechpartner |
|
||||||
|
|---|-------------|---------|----------------|
|
||||||
|
| 1 | <question or blocker> | <context> | <who can help> |
|
||||||
|
|
||||||
|
## 5. Wichtige Entscheidungen
|
||||||
|
|
||||||
|
<Key decisions made during this work, extracted from BigMind chunks>
|
||||||
|
|
||||||
|
| Entscheidung | Begründung | Datum |
|
||||||
|
|-------------|-----------|-------|
|
||||||
|
| <decision> | <rationale> | <date> |
|
||||||
|
|
||||||
|
## 6. Technische Hinweise
|
||||||
|
|
||||||
|
<Important technical context the next person needs to know:>
|
||||||
|
- <Pattern used, gotcha, workaround, etc.>
|
||||||
|
- <Environment setup needed>
|
||||||
|
- <Test data requirements>
|
||||||
|
|
||||||
|
## 7. Kontext-Wiederherstellung
|
||||||
|
|
||||||
|
Für die Weiterarbeit:
|
||||||
|
- **Worktree:** `/Users/pplate/git/paisy-<TICKET_KEY>`
|
||||||
|
- **Branch:** `<branch name>`
|
||||||
|
- **BigMind Session:** `<SESSION_ID>` — `memory_get_session_detail("<SESSION_ID>")` für Details
|
||||||
|
- **Relevante BigMind Facts:** <list fact IDs if available>
|
||||||
|
- **Dokumentation:** `docs/<MODULE>/<TICKET_KEY>/`
|
||||||
|
```
|
||||||
|
|
||||||
|
### 7. Store in BigMind
|
||||||
|
|
||||||
|
```python
|
||||||
|
memory_store_fact(
|
||||||
|
category="codebase",
|
||||||
|
fact=f"{TICKET_KEY}: Handover doc created at docs/{MODULE}/{TICKET_KEY}/{TICKET_KEY}-handover-{date}.md. Status: {done}/{total} items done."
|
||||||
|
)
|
||||||
|
memory_append_chunk(
|
||||||
|
session_id=SESSION_ID,
|
||||||
|
content=f"Handover for {TICKET_KEY}: <summary of state and remaining work>",
|
||||||
|
flag_reason="handover documentation"
|
||||||
|
)
|
||||||
|
```
|
||||||
|
|
||||||
|
## Expected Output
|
||||||
|
|
||||||
|
- Handover document at `docs/<MODULE>/<TICKET_KEY>/<TICKET_KEY>-handover-<date>.md`
|
||||||
|
- Complete picture of done/remaining work
|
||||||
|
- Context recovery instructions for the next person/session
|
||||||
|
- BigMind fact stored for traceability
|
||||||
|
|
||||||
|
## Error Handling
|
||||||
|
|
||||||
|
| Error | Resolution |
|
||||||
|
|-------|------------|
|
||||||
|
| No BigMind session found | Generate handover from git + Jira only — note missing session context |
|
||||||
|
| No worktree found | Check if work was done in main repo with branch checkout |
|
||||||
|
| No plan/assessment docs | Generate handover from Jira ticket + git history only |
|
||||||
|
| Empty git history | Branch may not have diverged from `current` yet — note "no commits" |
|
||||||
|
|
||||||
|
## When to Use
|
||||||
|
|
||||||
|
| Scenario | Trigger |
|
||||||
|
|----------|---------|
|
||||||
|
| End of day | Capture progress before stopping work |
|
||||||
|
| Person transfer | Handing ticket to another developer |
|
||||||
|
| Session recovery | After IDE crash, use to restore context |
|
||||||
|
| Long pause | Before vacation or multi-day break |
|
||||||
|
| Mode switch | When Orchestrator hands off between modes |
|
||||||
|
|
||||||
|
## Language
|
||||||
|
|
||||||
|
- Document content: **German**
|
||||||
|
- Technical terms (class names, branch names, BigMind IDs): English as-is
|
||||||
|
- Section headers: German
|
||||||
@@ -0,0 +1,192 @@
|
|||||||
|
# Skill: generate-solution-doc
|
||||||
|
|
||||||
|
Solution documentation from implementation results.
|
||||||
|
|
||||||
|
## Invoked by
|
||||||
|
|
||||||
|
📝 DocGen mode
|
||||||
|
|
||||||
|
## Required Inputs
|
||||||
|
|
||||||
|
| Input | Source | Example |
|
||||||
|
|-------|--------|---------|
|
||||||
|
| `TICKET_KEY` | Jira issue key | `ESIDEPAISY-12081` |
|
||||||
|
| `MODULE` | PAISY module name | `eau` |
|
||||||
|
| `PLAN_PATH` | Path to plan.md | `docs/EAU/ESIDEPAISY-12081/ESIDEPAISY-12081-plan.md` |
|
||||||
|
| `TESTPLAN_PATH` | Path to testplan.md | `docs/EAU/ESIDEPAISY-12081/ESIDEPAISY-12081-testplan.md` |
|
||||||
|
| `REVIEW_PATH` | Path to review.md (optional) | `docs/EAU/ESIDEPAISY-12081/ESIDEPAISY-12081-review.md` |
|
||||||
|
|
||||||
|
## Output
|
||||||
|
|
||||||
|
- Markdown: `docs/<MODULE>/<TICKET_KEY>/<TICKET_KEY>-solution.md`
|
||||||
|
- PDF: `docs/<MODULE>/<TICKET_KEY>/<TICKET_KEY>-solution.pdf`
|
||||||
|
|
||||||
|
## Steps
|
||||||
|
|
||||||
|
### 1. Read input documents
|
||||||
|
|
||||||
|
Read all available docs in `docs/<MODULE>/<TICKET_KEY>/`:
|
||||||
|
- Plan document (required)
|
||||||
|
- Test plan (required)
|
||||||
|
- Assessment (if exists)
|
||||||
|
- Review findings (if exists)
|
||||||
|
|
||||||
|
### 2. Analyze actual changes
|
||||||
|
|
||||||
|
```bash
|
||||||
|
# If in worktree
|
||||||
|
cd /Users/pplate/git/paisy-<TICKET_KEY>
|
||||||
|
git diff origin/current --stat
|
||||||
|
git diff origin/current --name-only
|
||||||
|
|
||||||
|
# Or use git log for committed changes
|
||||||
|
git log origin/current..HEAD --oneline
|
||||||
|
```
|
||||||
|
|
||||||
|
Read the changed files to understand what was actually implemented vs. what was planned.
|
||||||
|
|
||||||
|
### 3. Gather test results
|
||||||
|
|
||||||
|
```bash
|
||||||
|
# Check if tests were run
|
||||||
|
# Look for surefire reports or test output
|
||||||
|
find . -name "TEST-*.xml" -path "*/surefire-reports/*" | head -20
|
||||||
|
```
|
||||||
|
|
||||||
|
Or reference the testplan status if already updated.
|
||||||
|
|
||||||
|
### 4. Generate solution document
|
||||||
|
|
||||||
|
Write `docs/<MODULE>/<TICKET_KEY>/<TICKET_KEY>-solution.md`:
|
||||||
|
|
||||||
|
```markdown
|
||||||
|
# Lösungsdokumentation: <TICKET_KEY>
|
||||||
|
|
||||||
|
**Datum:** <today>
|
||||||
|
**Modul:** <MODULE>
|
||||||
|
**Autor:** Patrick Plate / Roo (DocGen)
|
||||||
|
**Jira:** <TICKET_KEY>
|
||||||
|
**Branch:** current/<type>/<module>/<TICKET_KEY>-<desc>
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## 1. Problemstellung
|
||||||
|
|
||||||
|
<From assessment/plan: What was the problem? Why did it need solving?>
|
||||||
|
|
||||||
|
## 2. Lösungsansatz
|
||||||
|
|
||||||
|
<High-level approach chosen. Reference the plan document.>
|
||||||
|
|
||||||
|
## 3. Architektur-Entscheidungen
|
||||||
|
|
||||||
|
| Entscheidung | Begründung | Alternativen |
|
||||||
|
|-------------|-----------|--------------|
|
||||||
|
| <decision> | <why> | <what was considered> |
|
||||||
|
|
||||||
|
<Include Mermaid diagrams where helpful:>
|
||||||
|
|
||||||
|
```mermaid
|
||||||
|
graph TD
|
||||||
|
A[Component] --> B[Component]
|
||||||
|
```
|
||||||
|
|
||||||
|
## 4. Implementierte Änderungen
|
||||||
|
|
||||||
|
### 4.1 <Component/File group>
|
||||||
|
|
||||||
|
| Datei | Änderung | Beschreibung |
|
||||||
|
|-------|---------|-------------|
|
||||||
|
| `<path>` | Neu/Geändert | <what changed> |
|
||||||
|
|
||||||
|
<Explain key code changes. Reference patterns used.>
|
||||||
|
|
||||||
|
### 4.2 <Next component group>
|
||||||
|
...
|
||||||
|
|
||||||
|
### 4.n Datenbank-Migrationen
|
||||||
|
|
||||||
|
| Migration | Datenbank | Beschreibung |
|
||||||
|
|-----------|----------|-------------|
|
||||||
|
| `V{timestamp}__C_...` | H2/Oracle | <what it does> |
|
||||||
|
|
||||||
|
## 5. Testabdeckung
|
||||||
|
|
||||||
|
| ID | Beschreibung | Typ | Ergebnis |
|
||||||
|
|----|-------------|-----|----------|
|
||||||
|
| T-01 | <desc> | Unit | ✅ |
|
||||||
|
| T-02 | <desc> | Integration | ✅ |
|
||||||
|
|
||||||
|
**Zusammenfassung:** <N> Tests, alle bestanden.
|
||||||
|
|
||||||
|
## 6. Offene Punkte
|
||||||
|
|
||||||
|
| # | Beschreibung | Priorität | Ticket |
|
||||||
|
|---|-------------|-----------|--------|
|
||||||
|
| 1 | <open item> | Hoch/Mittel/Niedrig | <linked ticket or "—"> |
|
||||||
|
|
||||||
|
<If no open items: "Keine offenen Punkte.">
|
||||||
|
```
|
||||||
|
|
||||||
|
### 5. Ask for PDF color scheme
|
||||||
|
|
||||||
|
Before generating the PDF, ask Patrick:
|
||||||
|
|
||||||
|
> "Welches Farbschema für das PDF? Verfügbar: adp (rot), royal_purple, ocean, forest, sunset, slate, rose"
|
||||||
|
|
||||||
|
Default to `adp` if Patrick says "standard" or doesn't have a preference.
|
||||||
|
|
||||||
|
### 6. Generate PDF
|
||||||
|
|
||||||
|
```python
|
||||||
|
generate_pdf(
|
||||||
|
content=<markdown content>,
|
||||||
|
title=f"Lösungsdokumentation {TICKET_KEY}",
|
||||||
|
author="Patrick Plate",
|
||||||
|
classification="ADP Internal",
|
||||||
|
output_path=f"docs/<MODULE>/<TICKET_KEY>/<TICKET_KEY>-solution.pdf",
|
||||||
|
color_scheme=<chosen scheme>
|
||||||
|
)
|
||||||
|
```
|
||||||
|
|
||||||
|
### 7. Store in BigMind
|
||||||
|
|
||||||
|
```python
|
||||||
|
memory_store_fact(
|
||||||
|
category="codebase",
|
||||||
|
fact=f"{TICKET_KEY}: Solution doc at docs/<MODULE>/<TICKET_KEY>/<TICKET_KEY>-solution.md, PDF generated"
|
||||||
|
)
|
||||||
|
memory_append_chunk(
|
||||||
|
session_id=SESSION_ID,
|
||||||
|
content=f"Solution doc for {TICKET_KEY}: <summary of changes and decisions>",
|
||||||
|
flag_reason="solution documentation"
|
||||||
|
)
|
||||||
|
```
|
||||||
|
|
||||||
|
## Language
|
||||||
|
|
||||||
|
- Document content: **German**
|
||||||
|
- Section headers: German (Problemstellung, Lösungsansatz, etc.)
|
||||||
|
- Code references, class names, patterns: English as-is
|
||||||
|
- Mermaid diagram labels: German or English depending on audience
|
||||||
|
|
||||||
|
## Template Variants
|
||||||
|
|
||||||
|
### Minimal (for small bugfixes)
|
||||||
|
|
||||||
|
Skip sections 3 (Architektur-Entscheidungen) and 6 (Offene Punkte) if not applicable. Keep sections 1, 2, 4, 5.
|
||||||
|
|
||||||
|
### Extended (for large features)
|
||||||
|
|
||||||
|
Add additional sections:
|
||||||
|
- **Konfigurationsänderungen** — environment variables, properties
|
||||||
|
- **Deployment-Hinweise** — special deployment steps needed
|
||||||
|
- **Rückwärtskompatibilität** — backward compatibility considerations
|
||||||
|
- **Performance-Auswirkungen** — performance impact analysis
|
||||||
|
|
||||||
|
## PDF Conventions
|
||||||
|
|
||||||
|
- Always use `generate_pdf` MCP tool (never write PDF bytes directly)
|
||||||
|
- Color scheme must be confirmed by Patrick before generation
|
||||||
|
- Author field: "Patrick Plate" (not "Roo")
|
||||||
|
- Classification: "ADP Internal" unless told otherwise
|
||||||
@@ -0,0 +1,166 @@
|
|||||||
|
# Skill: generate-testplan
|
||||||
|
|
||||||
|
Structured test plan from implementation plan / assessment.
|
||||||
|
|
||||||
|
## Invoked by
|
||||||
|
|
||||||
|
📋 Planner mode
|
||||||
|
|
||||||
|
## Required Inputs
|
||||||
|
|
||||||
|
| Input | Source | Example |
|
||||||
|
|-------|--------|---------|
|
||||||
|
| `TICKET_KEY` | Jira issue key | `ESIDEPAISY-12081` |
|
||||||
|
| `MODULE` | PAISY module name | `eau`, `eubp`, `svmeldungen` |
|
||||||
|
| `PLAN_PATH` | Path to plan.md | `docs/EAU/ESIDEPAISY-12081/ESIDEPAISY-12081-plan.md` |
|
||||||
|
|
||||||
|
## Output
|
||||||
|
|
||||||
|
Markdown file: `docs/<MODULE>/<TICKET_KEY>/<TICKET_KEY>-testplan.md`
|
||||||
|
|
||||||
|
## Steps
|
||||||
|
|
||||||
|
### 1. Read the implementation plan
|
||||||
|
|
||||||
|
Read `PLAN_PATH` to understand:
|
||||||
|
- Which classes/methods are being added or modified
|
||||||
|
- Which data flows are affected
|
||||||
|
- Which database changes are involved (Flyway migrations, new tables/columns)
|
||||||
|
- Which integration points exist (ServiceCenter, NATS, external APIs)
|
||||||
|
|
||||||
|
### 2. Read the assessment (if exists)
|
||||||
|
|
||||||
|
Check for `docs/<MODULE>/<TICKET_KEY>/<TICKET_KEY>-assessment.md` — extract risk areas that need extra test coverage.
|
||||||
|
|
||||||
|
### 3. Identify testable units
|
||||||
|
|
||||||
|
For each component in the plan:
|
||||||
|
|
||||||
|
| Category | What to test | Test type |
|
||||||
|
|----------|-------------|-----------|
|
||||||
|
| New methods | Input/output, edge cases, null handling | Unit |
|
||||||
|
| Modified methods | Regression + new behavior | Unit |
|
||||||
|
| Database changes | Migration up/down, data integrity | Integration |
|
||||||
|
| Data flows | End-to-end processing | Integration |
|
||||||
|
| PAISY interaction | ServiceCenter calls, pgm responses | SSH (manual) |
|
||||||
|
| Error paths | Invalid input, missing data, PAISY "F;" responses | Unit |
|
||||||
|
|
||||||
|
### 4. Generate test plan document
|
||||||
|
|
||||||
|
Write `docs/<MODULE>/<TICKET_KEY>/<TICKET_KEY>-testplan.md` with this structure:
|
||||||
|
|
||||||
|
```markdown
|
||||||
|
# Testplan: <TICKET_KEY> — <Summary>
|
||||||
|
|
||||||
|
**Datum:** <today>
|
||||||
|
**Modul:** <MODULE>
|
||||||
|
**Autor:** Patrick Plate / Roo (Planner)
|
||||||
|
**Status:** Entwurf v1
|
||||||
|
**Basis:** <TICKET_KEY>-plan.md
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## Testübersicht
|
||||||
|
|
||||||
|
| ID | Beschreibung | Typ | Klasse | Status |
|
||||||
|
|----|-------------|-----|--------|--------|
|
||||||
|
| T-01 | <short desc> | Unit | <TestClass> | ⬜ |
|
||||||
|
| T-02 | <short desc> | Unit | <TestClass> | ⬜ |
|
||||||
|
| T-03 | <short desc> | Integration | <TestClass> | ⬜ |
|
||||||
|
| T-nn | <short desc> | SSH | manuell | ⬜ |
|
||||||
|
|
||||||
|
Status: ⬜ Offen | ✅ Bestanden | ❌ Fehlgeschlagen | ⏭️ Übersprungen
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## Testfälle
|
||||||
|
|
||||||
|
### T-01: <Descriptive name>
|
||||||
|
|
||||||
|
**Typ:** Unit
|
||||||
|
**Klasse:** `<package>.<TestClassName>`
|
||||||
|
**Methode:** `test<MethodName>()`
|
||||||
|
|
||||||
|
**Vorbedingungen:**
|
||||||
|
- <setup requirements>
|
||||||
|
|
||||||
|
**Szenarien:**
|
||||||
|
|
||||||
|
| # | Eingabe | Erwartetes Ergebnis |
|
||||||
|
|---|---------|-------------------|
|
||||||
|
| a | <input> | <expected> |
|
||||||
|
| b | <input> | <expected> |
|
||||||
|
| c | <edge case> | <expected> |
|
||||||
|
|
||||||
|
**Nachbedingungen:**
|
||||||
|
- <what to verify after test>
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
### T-02: <Descriptive name>
|
||||||
|
...
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## Testdaten
|
||||||
|
|
||||||
|
<Describe any test data requirements, fixtures, or database setup needed.>
|
||||||
|
|
||||||
|
## Manuelle Tests (SSH)
|
||||||
|
|
||||||
|
| ID | Instanz | Programm | Eingabe | Erwartetes Ergebnis |
|
||||||
|
|----|---------|----------|---------|-------------------|
|
||||||
|
| T-nn | <instance> | <PAI program> | <input> | <expected> |
|
||||||
|
|
||||||
|
## Testabdeckung
|
||||||
|
|
||||||
|
| Komponente | Unit | Integration | SSH | Gesamt |
|
||||||
|
|-----------|------|-------------|-----|--------|
|
||||||
|
| <Class1> | 3 | 1 | 0 | 4 |
|
||||||
|
| <Class2> | 2 | 0 | 1 | 3 |
|
||||||
|
| **Summe** | **5** | **1** | **1** | **7** |
|
||||||
|
```
|
||||||
|
|
||||||
|
### 5. Cross-reference with plan
|
||||||
|
|
||||||
|
Verify every implementation step in the plan has at least one test case:
|
||||||
|
- New method → unit test
|
||||||
|
- Modified method → regression test
|
||||||
|
- Database migration → migration test
|
||||||
|
- Integration point → integration test or SSH test
|
||||||
|
|
||||||
|
Flag any gaps as warnings in the testplan.
|
||||||
|
|
||||||
|
### 6. Present to user
|
||||||
|
|
||||||
|
- Show the test overview table
|
||||||
|
- Explicitly ask: **"Testplan v1 erstellt mit <N> Testfällen. GO / Feedback?"**
|
||||||
|
- On feedback: revise and increment version
|
||||||
|
|
||||||
|
### 7. Store in BigMind
|
||||||
|
|
||||||
|
```python
|
||||||
|
memory_store_fact(
|
||||||
|
category="codebase",
|
||||||
|
fact=f"{TICKET_KEY}: Testplan with {N} test cases (Unit: {u}, Integration: {i}, SSH: {s})"
|
||||||
|
)
|
||||||
|
```
|
||||||
|
|
||||||
|
## Test Naming Conventions
|
||||||
|
|
||||||
|
- Test class: `<OriginalClass>Test.java` or `<Feature>Test.java`
|
||||||
|
- Test method: `test<What>_<Scenario>_<Expected>()` or `test<What>()` for simple cases
|
||||||
|
- Location: mirror source structure under `src/test/java/`
|
||||||
|
- Base classes: extend existing test bases where available (e.g., `EAUFlywayMigrationTestBase`)
|
||||||
|
|
||||||
|
## Test ID Format
|
||||||
|
|
||||||
|
- Sequential: T-01, T-02, ..., T-nn
|
||||||
|
- Prefix by type if needed: UT-01 (unit), IT-01 (integration), MT-01 (manual/SSH)
|
||||||
|
- IDs are stable — don't renumber on revision, append new tests at the end
|
||||||
|
|
||||||
|
## Language
|
||||||
|
|
||||||
|
- Document content: **German**
|
||||||
|
- Test method names and code: **English** (Java convention)
|
||||||
|
- Scenario descriptions in the table: German
|
||||||
@@ -0,0 +1,174 @@
|
|||||||
|
# Skill: impact-analysis
|
||||||
|
|
||||||
|
Analyze impact of changes to shared modules across the PAISY monorepo.
|
||||||
|
|
||||||
|
## Invoked by
|
||||||
|
|
||||||
|
📋 Planner mode (or 🔍 Reviewer mode)
|
||||||
|
|
||||||
|
## Required Inputs
|
||||||
|
|
||||||
|
| Input | Source | Example |
|
||||||
|
|-------|--------|---------|
|
||||||
|
| `TICKET_KEY` | Jira issue key | `ESIDEPAISY-12081` |
|
||||||
|
| `CHANGED_MODULE` | Module being changed | `persistence`, `sv-common`, `flatfile-parser`, `paisy-common` |
|
||||||
|
| `CHANGED_API` | Changed class/method (optional) | `EMFactory.getLeftoverSchemas()`, `AbstractMeldung.initBaustein()` |
|
||||||
|
|
||||||
|
## Output
|
||||||
|
|
||||||
|
- Impact summary with affected modules, files, and risk level
|
||||||
|
- Stored in BigMind for future reference
|
||||||
|
|
||||||
|
## Steps
|
||||||
|
|
||||||
|
### 1. Identify the changed module's artifact
|
||||||
|
|
||||||
|
```bash
|
||||||
|
grep -A2 '<artifactId>' java/modules/cs-modules/<CHANGED_MODULE>/pom.xml | head -3
|
||||||
|
# Or for shared modules:
|
||||||
|
grep -A2 '<artifactId>' java/modules/<CHANGED_MODULE>/pom.xml | head -3
|
||||||
|
```
|
||||||
|
|
||||||
|
Extract the `groupId` and `artifactId` for dependency searching.
|
||||||
|
|
||||||
|
### 2. Find dependent modules (reverse dependency lookup)
|
||||||
|
|
||||||
|
```bash
|
||||||
|
# Search all module POMs for the changed artifact
|
||||||
|
grep -rn "<artifactId><CHANGED_MODULE></artifactId>" java/modules/cs-modules/*/pom.xml
|
||||||
|
grep -rn "<artifactId><CHANGED_MODULE></artifactId>" java/modules/*/pom.xml
|
||||||
|
```
|
||||||
|
|
||||||
|
Or use Maven dependency tree for a specific consumer:
|
||||||
|
```bash
|
||||||
|
cd /Users/pplate/git/paisy-<TICKET_KEY>
|
||||||
|
mvn dependency:tree -pl java/modules/cs-modules/<consumer_module> -DoutputType=text -f java/pom.xml | grep <CHANGED_MODULE>
|
||||||
|
```
|
||||||
|
|
||||||
|
### 3. For each dependent module, check API usage
|
||||||
|
|
||||||
|
```bash
|
||||||
|
# Search for usage of the changed class/method
|
||||||
|
grep -rn "ChangedClass\|changedMethod" java/modules/cs-modules/<dependent_module>/src/
|
||||||
|
|
||||||
|
# For import-level analysis
|
||||||
|
grep -rn "import.*<package>.<ChangedClass>" java/modules/cs-modules/*/src/main/java/
|
||||||
|
```
|
||||||
|
|
||||||
|
### 4. Classify impact per module
|
||||||
|
|
||||||
|
For each dependent module, determine:
|
||||||
|
|
||||||
|
| Impact Level | Criteria | Action |
|
||||||
|
|-------------|----------|--------|
|
||||||
|
| 🔴 High | Direct API consumer, method signature changed | Must update + test |
|
||||||
|
| 🟡 Medium | Uses the module but not the changed API directly | Verify compilation, run tests |
|
||||||
|
| 🟢 Low | Transitive dependency only, no direct usage | Monitor, no action needed |
|
||||||
|
| ⚪ None | Not a dependency | Skip |
|
||||||
|
|
||||||
|
### 5. Check for test coverage in dependent modules
|
||||||
|
|
||||||
|
```bash
|
||||||
|
# For each high/medium impact module, check if tests exist
|
||||||
|
find java/modules/cs-modules/<dependent_module>/src/test -name "*Test.java" | wc -l
|
||||||
|
|
||||||
|
# Check if the dependent module's tests use the changed API
|
||||||
|
grep -rn "ChangedClass\|changedMethod" java/modules/cs-modules/<dependent_module>/src/test/
|
||||||
|
```
|
||||||
|
|
||||||
|
### 6. Verify compilation across affected modules
|
||||||
|
|
||||||
|
```bash
|
||||||
|
cd /Users/pplate/git/paisy-<TICKET_KEY>
|
||||||
|
# Compile all affected modules without running tests
|
||||||
|
mvn compile -pl java/modules/cs-modules/<module1>,java/modules/cs-modules/<module2> -am -f java/pom.xml
|
||||||
|
```
|
||||||
|
|
||||||
|
### 7. Generate impact report
|
||||||
|
|
||||||
|
Present the findings as a structured summary:
|
||||||
|
|
||||||
|
```markdown
|
||||||
|
# Impact Analysis: <TICKET_KEY> — <Changed Module>
|
||||||
|
|
||||||
|
**Datum:** <today>
|
||||||
|
**Geändertes Modul:** <CHANGED_MODULE>
|
||||||
|
**Geänderte API:** <CHANGED_API>
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## Abhängige Module
|
||||||
|
|
||||||
|
| Modul | Impact | Direkte Nutzung | Dateien | Aktion |
|
||||||
|
|-------|--------|----------------|---------|--------|
|
||||||
|
| `eau` | 🔴 Hoch | `EMFactory.getLeftoverSchemas()` in `Center.java` | 2 | Update + Test |
|
||||||
|
| `eubp` | 🟡 Mittel | Nutzt EMFactory, aber nicht geänderte Methode | 1 | Kompilierung prüfen |
|
||||||
|
| `svmeldungen` | 🟢 Niedrig | Transitive Abhängigkeit | 0 | Monitoring |
|
||||||
|
|
||||||
|
## Betroffene Dateien (Detail)
|
||||||
|
|
||||||
|
### 🔴 eau
|
||||||
|
- `java/modules/cs-modules/eau/src/main/java/main/Center.java:142` — calls `EMFactory.getLeftoverSchemas()`
|
||||||
|
- `java/modules/cs-modules/eau/src/test/java/main/CenterTest.java:55` — tests the call
|
||||||
|
|
||||||
|
### 🟡 eubp
|
||||||
|
- `java/modules/cs-modules/eubp/src/main/java/main/EuBPCenter.java:88` — imports EMFactory
|
||||||
|
|
||||||
|
## Risikobewertung
|
||||||
|
|
||||||
|
| Risiko | Wahrscheinlichkeit | Auswirkung | Mitigation |
|
||||||
|
|--------|-------------------|------------|------------|
|
||||||
|
| Kompilierungsfehler in eau | Hoch | Hoch | Sofort anpassen |
|
||||||
|
| Laufzeitfehler in eubp | Niedrig | Mittel | Tests ausführen |
|
||||||
|
|
||||||
|
## Empfehlung
|
||||||
|
|
||||||
|
<Summary of recommended actions>
|
||||||
|
```
|
||||||
|
|
||||||
|
### 8. Store in BigMind
|
||||||
|
|
||||||
|
```python
|
||||||
|
memory_store_fact(
|
||||||
|
category="codebase",
|
||||||
|
fact=f"{TICKET_KEY}: Impact analysis for {CHANGED_MODULE} — {high} high, {medium} medium, {low} low impact modules."
|
||||||
|
)
|
||||||
|
memory_append_chunk(
|
||||||
|
session_id=SESSION_ID,
|
||||||
|
content=f"Impact analysis for {CHANGED_MODULE} change in {TICKET_KEY}:\n<detailed findings>",
|
||||||
|
flag_reason="impact analysis"
|
||||||
|
)
|
||||||
|
```
|
||||||
|
|
||||||
|
## Expected Output
|
||||||
|
|
||||||
|
- Clear list of affected modules with impact levels
|
||||||
|
- Specific file:line references for high-impact usages
|
||||||
|
- Compilation verification results
|
||||||
|
- Risk assessment with mitigation recommendations
|
||||||
|
- BigMind fact stored
|
||||||
|
|
||||||
|
## Error Handling
|
||||||
|
|
||||||
|
| Error | Resolution |
|
||||||
|
|-------|------------|
|
||||||
|
| Module not found in POM | Check if it's a parent module or uses a different artifactId |
|
||||||
|
| Too many dependents (>10) | Focus on high-impact only, list others as "low" without detail |
|
||||||
|
| Compilation fails | Document the failure as part of the impact — it confirms the impact is real |
|
||||||
|
| No tests in dependent module | Flag as risk — untested dependency on changed API |
|
||||||
|
|
||||||
|
## Common Shared Modules
|
||||||
|
|
||||||
|
| Module | Typical Dependents | Risk Profile |
|
||||||
|
|--------|-------------------|-------------|
|
||||||
|
| `persistence` | All modules with DB access | High — EMFactory, FlywayController |
|
||||||
|
| `sv-common` | All SV-Meldeverfahren modules | High — shared SV logic |
|
||||||
|
| `flatfile-parser` | Modules reading DSRV/ITSG files | Medium — parsing infrastructure |
|
||||||
|
| `paisy-common` | Nearly all modules | Very High — core utilities |
|
||||||
|
| `message-broker` | Modules using NATS | Medium — async messaging |
|
||||||
|
|
||||||
|
## Language
|
||||||
|
|
||||||
|
- Impact report: **German**
|
||||||
|
- Code references (class names, methods, file paths): English as-is
|
||||||
|
- BigMind facts: English
|
||||||
@@ -0,0 +1,204 @@
|
|||||||
|
# Skill: jira-lifecycle
|
||||||
|
|
||||||
|
Full Jira ticket lifecycle management for ESIDEPAISY.
|
||||||
|
|
||||||
|
## Invoked by
|
||||||
|
|
||||||
|
🎫 JiraOps mode
|
||||||
|
|
||||||
|
## Required Inputs
|
||||||
|
|
||||||
|
| Input | Source | Example |
|
||||||
|
|-------|--------|---------|
|
||||||
|
| `TICKET_KEY` | Jira issue key | `ESIDEPAISY-12081` |
|
||||||
|
|
||||||
|
## Overview
|
||||||
|
|
||||||
|
This skill manages a Jira ticket through its full lifecycle, from initial setup through to final acceptance. It handles field validation, Smart Checklist management, status transitions, attachments, and structured comments.
|
||||||
|
|
||||||
|
## Steps
|
||||||
|
|
||||||
|
### 1. Validate mandatory fields
|
||||||
|
|
||||||
|
```python
|
||||||
|
ticket = retrieve_ticket_details(TICKET_KEY)
|
||||||
|
```
|
||||||
|
|
||||||
|
Check and fix:
|
||||||
|
|
||||||
|
| Field | ID | Required | How to resolve |
|
||||||
|
|-------|----|----------|---------------|
|
||||||
|
| Feature Link | `customfield_10001` | ✅ Mandatory | Look up parent Epic via JQL: `project = ESIDEPAISY AND issuetype = Epic AND summary ~ "<module>"` |
|
||||||
|
| Sprint | `customfield_10000` | ✅ Mandatory | Derive from active sprint: `get_agile_boards("ESIDEPAISY")` → `get_sprints_from_board(board_id, states="active")` |
|
||||||
|
| Assignee | `assignee` | Recommended | `ticket_assignment(TICKET_KEY, assignee="currentUser()")` |
|
||||||
|
|
||||||
|
If Feature Link is missing:
|
||||||
|
```python
|
||||||
|
# Find the parent Epic
|
||||||
|
epics = list_tickets(jql_search='project = ESIDEPAISY AND issuetype = Epic AND summary ~ "<module keyword>"')
|
||||||
|
# Update the ticket
|
||||||
|
update_ticket_fields(TICKET_KEY, fields={"customfield_10001": epics[0]["key"]})
|
||||||
|
```
|
||||||
|
|
||||||
|
### 2. Create Smart Checklist
|
||||||
|
|
||||||
|
Set up the standard PAISY pipeline checklist:
|
||||||
|
|
||||||
|
```python
|
||||||
|
update_checklist(TICKET_KEY, items=[
|
||||||
|
{"name": "## Analyse & Planung"},
|
||||||
|
{"name": "Assessment erstellt", "status": "-"},
|
||||||
|
{"name": "Plan erstellt", "status": "-"},
|
||||||
|
{"name": "Testplan erstellt", "status": "-"},
|
||||||
|
{"name": "Plan Review bestanden", "status": "-!"}, # mandatory
|
||||||
|
{"name": "GO erhalten", "status": "-!"}, # mandatory
|
||||||
|
{"name": "---"},
|
||||||
|
{"name": "## Implementierung"},
|
||||||
|
{"name": "Code-Änderungen", "status": "-"},
|
||||||
|
{"name": "Tests implementiert", "status": "-"},
|
||||||
|
{"name": "Build grün", "status": "-!"}, # mandatory
|
||||||
|
{"name": "---"},
|
||||||
|
{"name": "## Security & Review"},
|
||||||
|
{"name": "Security Review bestanden", "status": "-!"}, # mandatory
|
||||||
|
{"name": "Code Review bestanden", "status": "-"},
|
||||||
|
{"name": "---"},
|
||||||
|
{"name": "## Dokumentation & Abschluss"},
|
||||||
|
{"name": "Lösungsdokumentation", "status": "-"},
|
||||||
|
{"name": "PDF generiert", "status": "-"},
|
||||||
|
{"name": "Jira aktualisiert", "status": "-"},
|
||||||
|
])
|
||||||
|
```
|
||||||
|
|
||||||
|
### 3. Status transitions
|
||||||
|
|
||||||
|
Manage the ticket through the ESIDEPAISY workflow:
|
||||||
|
|
||||||
|
| Phase | Status | When |
|
||||||
|
|-------|--------|------|
|
||||||
|
| Start | `In Progress` | After worktree creation, before implementation |
|
||||||
|
| Review | `In Review` | After implementation + tests, before code review |
|
||||||
|
| Done | `Accepted` | After all checklist items complete |
|
||||||
|
|
||||||
|
```python
|
||||||
|
update_status(TICKET_KEY, status="In Progress")
|
||||||
|
```
|
||||||
|
|
||||||
|
### 4. Update checklist as work progresses
|
||||||
|
|
||||||
|
Update individual items as phases complete:
|
||||||
|
|
||||||
|
```python
|
||||||
|
# After assessment is done
|
||||||
|
update_checklist(TICKET_KEY, items=[
|
||||||
|
{"name": "## Analyse"},
|
||||||
|
{"name": "Assessment erstellt", "checked": True},
|
||||||
|
{"name": "Plan erstellt", "status": "~"}, # in progress
|
||||||
|
# ... rest unchanged
|
||||||
|
])
|
||||||
|
```
|
||||||
|
|
||||||
|
**Important:** `update_checklist` replaces ALL items. Always send the full checklist with updated statuses.
|
||||||
|
|
||||||
|
### 5. Add structured comments at phase boundaries
|
||||||
|
|
||||||
|
At each major phase transition, add a German comment:
|
||||||
|
|
||||||
|
```python
|
||||||
|
# After planning + plan review
|
||||||
|
add_comment_to_ticket(TICKET_KEY, comment="""
|
||||||
|
*Phase 1-1.5 abgeschlossen: Analyse & Planung*
|
||||||
|
|
||||||
|
Assessment, Plan und Testplan erstellt:
|
||||||
|
- Assessment: [TICKET_KEY-assessment.md]
|
||||||
|
- Plan: [TICKET_KEY-plan.md]
|
||||||
|
- Testplan: [TICKET_KEY-testplan.md] ({N} Testfälle)
|
||||||
|
- Plan Review: [TICKET_KEY-plan-review.md] — ✅ APPROVED
|
||||||
|
|
||||||
|
GO erhalten am {date}.
|
||||||
|
""")
|
||||||
|
|
||||||
|
# After implementation + security review
|
||||||
|
add_comment_to_ticket(TICKET_KEY, comment="""
|
||||||
|
*Phase 3-5.5 abgeschlossen: Implementierung, Tests & Security*
|
||||||
|
|
||||||
|
Branch: current/{type}/{module}/{TICKET_KEY}-{desc}
|
||||||
|
Änderungen: {N} Dateien geändert, {M} neu
|
||||||
|
Tests: {T} Tests, alle bestanden
|
||||||
|
Security Review: ✅ PASS — [TICKET_KEY-security-review.md]
|
||||||
|
""")
|
||||||
|
|
||||||
|
# After documentation
|
||||||
|
add_comment_to_ticket(TICKET_KEY, comment="""
|
||||||
|
*Phase 7-8 abgeschlossen: Dokumentation & Finalisierung*
|
||||||
|
|
||||||
|
Lösungsdokumentation als PDF angehängt.
|
||||||
|
Alle Checklist-Punkte erledigt.
|
||||||
|
""")
|
||||||
|
```
|
||||||
|
|
||||||
|
### 6. Upload attachments
|
||||||
|
|
||||||
|
```python
|
||||||
|
# Upload solution PDF
|
||||||
|
add_attachment_to_ticket(TICKET_KEY, file_path="/absolute/path/to/<TICKET_KEY>-solution.pdf")
|
||||||
|
```
|
||||||
|
|
||||||
|
### 7. Final checklist update
|
||||||
|
|
||||||
|
Mark all items as done:
|
||||||
|
|
||||||
|
```python
|
||||||
|
update_checklist(TICKET_KEY, items=[
|
||||||
|
{"name": "## Analyse & Planung"},
|
||||||
|
{"name": "Assessment erstellt", "checked": True},
|
||||||
|
{"name": "Plan erstellt", "checked": True},
|
||||||
|
{"name": "Testplan erstellt", "checked": True},
|
||||||
|
{"name": "Plan Review bestanden", "status": "+!"},
|
||||||
|
{"name": "GO erhalten", "status": "+!"},
|
||||||
|
{"name": "---"},
|
||||||
|
{"name": "## Implementierung"},
|
||||||
|
{"name": "Code-Änderungen", "checked": True},
|
||||||
|
{"name": "Tests implementiert", "checked": True},
|
||||||
|
{"name": "Build grün", "status": "+!"},
|
||||||
|
{"name": "---"},
|
||||||
|
{"name": "## Security & Review"},
|
||||||
|
{"name": "Security Review bestanden", "status": "+!"},
|
||||||
|
{"name": "Code Review bestanden", "checked": True},
|
||||||
|
{"name": "---"},
|
||||||
|
{"name": "## Dokumentation & Abschluss"},
|
||||||
|
{"name": "Lösungsdokumentation", "checked": True},
|
||||||
|
{"name": "PDF generiert", "checked": True},
|
||||||
|
{"name": "Jira aktualisiert", "checked": True},
|
||||||
|
])
|
||||||
|
```
|
||||||
|
|
||||||
|
### 8. Final status transition
|
||||||
|
|
||||||
|
```python
|
||||||
|
update_status(TICKET_KEY, status="Accepted")
|
||||||
|
```
|
||||||
|
|
||||||
|
## Language
|
||||||
|
|
||||||
|
- All Jira content (summary, description, comments, checklist items): **German**
|
||||||
|
- Technical terms (branch names, file paths, tool names): English as-is
|
||||||
|
|
||||||
|
## Conventions
|
||||||
|
|
||||||
|
- Feature Link (`customfield_10001`): always look up dynamically, never hardcode Epic keys
|
||||||
|
- Sprint: always derive from active sprint, never hardcode sprint IDs
|
||||||
|
- Comments: use Jira wiki markup (`*bold*`, `{code}`, etc.)
|
||||||
|
- Attachments: use absolute file paths
|
||||||
|
- Checklist: always send the FULL list (Railsware replaces all items on update)
|
||||||
|
|
||||||
|
## Partial Lifecycle
|
||||||
|
|
||||||
|
Not every ticket needs the full lifecycle. For quick fixes:
|
||||||
|
|
||||||
|
| Scenario | Skip |
|
||||||
|
|----------|------|
|
||||||
|
| Trivial bugfix (< 1 hour) | Skip assessment, testplan, review. Keep checklist minimal. |
|
||||||
|
| Documentation-only change | Skip implementation, tests, review phases. |
|
||||||
|
| Hotfix | Skip planning loop. Minimal checklist: Code → Test → Deploy. |
|
||||||
|
|
||||||
|
Adjust the checklist template accordingly when creating it.
|
||||||
@@ -0,0 +1,253 @@
|
|||||||
|
# Skill: plan-review
|
||||||
|
|
||||||
|
Plan and testplan quality review before implementation.
|
||||||
|
|
||||||
|
## Description
|
||||||
|
|
||||||
|
Reviews assessment documents, implementation plans, and test plans for completeness, correctness, and feasibility. Produces a structured review with APPROVED/REVISE verdict. This creates a quality gate between planning and implementation — ensuring plans are solid before code is written.
|
||||||
|
|
||||||
|
## Invoked by
|
||||||
|
|
||||||
|
📋✅ Plan Reviewer mode
|
||||||
|
|
||||||
|
## Required Inputs
|
||||||
|
|
||||||
|
| Input | Source | Example |
|
||||||
|
|-------|--------|---------|
|
||||||
|
| `TICKET_KEY` | Jira issue key | `ESIDEPAISY-12081` |
|
||||||
|
| `MODULE` | PAISY module name | `eau`, `eubp`, `svmeldungen` |
|
||||||
|
|
||||||
|
## Output
|
||||||
|
|
||||||
|
Markdown file: `docs/<MODULE>/<TICKET_KEY>/<TICKET_KEY>-plan-review.md`
|
||||||
|
|
||||||
|
## Steps
|
||||||
|
|
||||||
|
### 1. Read the planning documents
|
||||||
|
|
||||||
|
Read all available docs in `docs/<MODULE>/<TICKET_KEY>/`:
|
||||||
|
- Assessment (`*-assessment.md`) — required
|
||||||
|
- Implementation plan (`*-plan.md`) — required
|
||||||
|
- Test plan (`*-testplan.md`) — required
|
||||||
|
|
||||||
|
If any required document is missing, flag as REVISE immediately.
|
||||||
|
|
||||||
|
### 2. Read the Jira ticket
|
||||||
|
|
||||||
|
```python
|
||||||
|
retrieve_ticket_details(TICKET_KEY)
|
||||||
|
# Extract: summary, description, acceptance criteria (customfield_10510)
|
||||||
|
```
|
||||||
|
|
||||||
|
Cross-reference: do the plan documents address ALL requirements from the ticket?
|
||||||
|
|
||||||
|
### 3. Read affected source code
|
||||||
|
|
||||||
|
For each file/class mentioned in the plan:
|
||||||
|
- Verify the file exists at the stated path
|
||||||
|
- Verify the class/method names are correct
|
||||||
|
- Verify the patterns described match the actual code
|
||||||
|
- Check if the plan missed any related files that should also be changed
|
||||||
|
|
||||||
|
### 4. Run the plan review checklist
|
||||||
|
|
||||||
|
#### Assessment Review
|
||||||
|
|
||||||
|
| # | Check | What to verify |
|
||||||
|
|---|-------|---------------|
|
||||||
|
| 1 | Problem statement complete | Is the problem clearly described? Does it match the Jira ticket? |
|
||||||
|
| 2 | Affected components identified | Are all affected files/classes listed? Any missing? |
|
||||||
|
| 3 | Current state accurate | Does the Ist-Zustand description match the actual code? |
|
||||||
|
| 4 | Risk assessment realistic | Are risks properly categorized? Any missing risks? |
|
||||||
|
| 5 | Solution options evaluated | Were alternatives considered? Is the recommendation justified? |
|
||||||
|
|
||||||
|
#### Implementation Plan Review
|
||||||
|
|
||||||
|
| # | Check | What to verify |
|
||||||
|
|---|-------|---------------|
|
||||||
|
| 6 | All requirements covered | Every Jira requirement maps to at least one implementation step |
|
||||||
|
| 7 | Correct PAISY patterns | Plan references correct patterns (AbstractMeldung, Datenbaustein, ServiceCenter, EMFactory, JAXB) |
|
||||||
|
| 8 | File paths correct | All referenced file paths exist and are accurate |
|
||||||
|
| 9 | Implementation order logical | Steps are ordered correctly — dependencies before dependents |
|
||||||
|
| 10 | No gaps in steps | No missing steps between plan items (e.g., missing Flyway migration, missing test) |
|
||||||
|
| 11 | Flyway migrations planned | If DB changes needed: both H2 and Oracle variants mentioned? |
|
||||||
|
| 12 | Error handling planned | Plan addresses error cases, not just happy path |
|
||||||
|
| 13 | No scope creep | Plan doesn't include changes beyond what the ticket requires |
|
||||||
|
|
||||||
|
#### Test Plan Review
|
||||||
|
|
||||||
|
| # | Check | What to verify |
|
||||||
|
|---|-------|---------------|
|
||||||
|
| 14 | Coverage complete | Every implementation step has at least one test case |
|
||||||
|
| 15 | Test types appropriate | Unit tests for logic, integration for DB/ServiceCenter, SSH for batch |
|
||||||
|
| 16 | Edge cases covered | Null handling, empty dates, F; responses, boundary values |
|
||||||
|
| 17 | Test class naming correct | Follows `<OriginalClass>Test.java` convention |
|
||||||
|
| 18 | Test method naming correct | Follows `test<What>_<Scenario>_<Expected>()` pattern |
|
||||||
|
| 19 | Test data defined | Required test fixtures and data are specified |
|
||||||
|
| 20 | SSH tests identified | If batch/ServiceCenter changes: SSH test cases included? |
|
||||||
|
|
||||||
|
### 5. Verify cross-references
|
||||||
|
|
||||||
|
- Every class mentioned in the plan exists in the codebase
|
||||||
|
- Every test case in the testplan maps to a plan step
|
||||||
|
- Every plan step maps to a Jira requirement
|
||||||
|
- Assessment risks are addressed by plan mitigations
|
||||||
|
|
||||||
|
### 5.5 Expert Panel Review (mandatory)
|
||||||
|
|
||||||
|
Before generating the verdict, run the `expert-panel-review` skill to get a multi-perspective analysis:
|
||||||
|
|
||||||
|
1. Load the `expert-panel-review` skill
|
||||||
|
2. Execute with:
|
||||||
|
- `ARTIFACT_TYPE`: `plan`
|
||||||
|
- `ARTIFACT_PATH`: the plan document path (`docs/<MODULE>/<TICKET_KEY>/<TICKET_KEY>-plan.md`)
|
||||||
|
3. Incorporate the panel's findings into the review:
|
||||||
|
- Panel blockers (❌) → add to "Muss überarbeitet werden" section
|
||||||
|
- Panel warnings (⚠️) → add to "Hinweise" section
|
||||||
|
- Panel confidence level → include in Verdict section
|
||||||
|
4. If panel confidence < 70%: verdict MUST be 🔄 REVISE regardless of checklist results
|
||||||
|
|
||||||
|
The expert panel provides Domain Expert (🏛️), Architecture Expert (🔧), and Risk/Compliance Expert (🛡️) perspectives. This catches domain-level errors that the mechanical checklist alone cannot detect.
|
||||||
|
|
||||||
|
### 6. Generate plan review document
|
||||||
|
|
||||||
|
Write `docs/<MODULE>/<TICKET_KEY>/<TICKET_KEY>-plan-review.md`:
|
||||||
|
|
||||||
|
```markdown
|
||||||
|
# Plan Review: <TICKET_KEY> — <Summary>
|
||||||
|
|
||||||
|
**Datum:** <today>
|
||||||
|
**Modul:** <MODULE>
|
||||||
|
**Reviewer:** Roo (Plan Reviewer)
|
||||||
|
**Dokumente:** assessment.md v<N>, plan.md v<N>, testplan.md v<N>
|
||||||
|
**Verdict:** ✅ APPROVED / 🔄 REVISE
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## Zusammenfassung
|
||||||
|
|
||||||
|
<1-2 sentence summary of the review outcome>
|
||||||
|
|
||||||
|
## Geprüfte Dokumente
|
||||||
|
|
||||||
|
| Dokument | Version | Bewertung |
|
||||||
|
|----------|---------|-----------|
|
||||||
|
| Assessment | v<N> | ✅ / ⚠️ / ❌ |
|
||||||
|
| Plan | v<N> | ✅ / ⚠️ / ❌ |
|
||||||
|
| Testplan | v<N> | ✅ / ⚠️ / ❌ |
|
||||||
|
|
||||||
|
## Checkliste
|
||||||
|
|
||||||
|
### Assessment
|
||||||
|
|
||||||
|
| # | Prüfpunkt | Ergebnis | Anmerkung |
|
||||||
|
|---|-----------|----------|-----------|
|
||||||
|
| 1 | Problemstellung vollständig | ✅/❌ | |
|
||||||
|
| 2 | Betroffene Komponenten identifiziert | ✅/❌ | |
|
||||||
|
| 3 | Ist-Zustand korrekt | ✅/❌ | |
|
||||||
|
| 4 | Risikobewertung realistisch | ✅/❌ | |
|
||||||
|
| 5 | Lösungsoptionen bewertet | ✅/❌ | |
|
||||||
|
|
||||||
|
### Implementierungsplan
|
||||||
|
|
||||||
|
| # | Prüfpunkt | Ergebnis | Anmerkung |
|
||||||
|
|---|-----------|----------|-----------|
|
||||||
|
| 6 | Alle Anforderungen abgedeckt | ✅/❌ | |
|
||||||
|
| 7 | Korrekte PAISY-Patterns | ✅/❌ | |
|
||||||
|
| 8 | Dateipfade korrekt | ✅/❌ | |
|
||||||
|
| 9 | Implementierungsreihenfolge logisch | ✅/❌ | |
|
||||||
|
| 10 | Keine Lücken in Schritten | ✅/❌ | |
|
||||||
|
| 11 | Flyway-Migrationen geplant | ✅/N/A | |
|
||||||
|
| 12 | Fehlerbehandlung geplant | ✅/❌ | |
|
||||||
|
| 13 | Kein Scope Creep | ✅/❌ | |
|
||||||
|
|
||||||
|
### Testplan
|
||||||
|
|
||||||
|
| # | Prüfpunkt | Ergebnis | Anmerkung |
|
||||||
|
|---|-----------|----------|-----------|
|
||||||
|
| 14 | Abdeckung vollständig | ✅/❌ | |
|
||||||
|
| 15 | Testtypen angemessen | ✅/❌ | |
|
||||||
|
| 16 | Randfälle abgedeckt | ✅/❌ | |
|
||||||
|
| 17 | Testklassen-Benennung korrekt | ✅/❌ | |
|
||||||
|
| 18 | Testmethoden-Benennung korrekt | ✅/❌ | |
|
||||||
|
| 19 | Testdaten definiert | ✅/❌ | |
|
||||||
|
| 20 | SSH-Tests identifiziert | ✅/N/A | |
|
||||||
|
|
||||||
|
## Befunde
|
||||||
|
|
||||||
|
### ❌ Muss überarbeitet werden (blocking)
|
||||||
|
|
||||||
|
1. **<document>** — <description of issue>
|
||||||
|
- Empfehlung: <what needs to change>
|
||||||
|
|
||||||
|
### ⚠️ Hinweise (non-blocking)
|
||||||
|
|
||||||
|
1. **<document>** — <description of suggestion>
|
||||||
|
- Empfehlung: <improvement suggestion>
|
||||||
|
|
||||||
|
## Traceability Matrix
|
||||||
|
|
||||||
|
| Jira-Anforderung | Plan-Schritt | Testfall | Status |
|
||||||
|
|-----------------|-------------|----------|--------|
|
||||||
|
| <requirement 1> | Step <N> | T-<NN> | ✅ Abgedeckt |
|
||||||
|
| <requirement 2> | Step <N> | T-<NN> | ❌ Fehlt |
|
||||||
|
|
||||||
|
## Verdict
|
||||||
|
|
||||||
|
**✅ APPROVED** — Plan ist vollständig, korrekt und umsetzungsbereit. Empfehlung: GO erteilen.
|
||||||
|
— oder —
|
||||||
|
**🔄 REVISE** — <N> Punkte müssen überarbeitet werden. Zurück an Planner für v<N+1>.
|
||||||
|
**Panel-Confidence:** <X>% (<Domain: Y%, Architecture: Z%, Risk: W%>)
|
||||||
|
```
|
||||||
|
|
||||||
|
### 7. Store in BigMind
|
||||||
|
|
||||||
|
```python
|
||||||
|
memory_store_fact(
|
||||||
|
category="codebase",
|
||||||
|
fact=f"{TICKET_KEY}: Plan review completed — {verdict}. {findings_count} findings ({blockers} blocking)."
|
||||||
|
)
|
||||||
|
```
|
||||||
|
|
||||||
|
## Expected Output
|
||||||
|
|
||||||
|
- Plan review document at `docs/<MODULE>/<TICKET_KEY>/<TICKET_KEY>-plan-review.md`
|
||||||
|
- Clear verdict: APPROVED or REVISE
|
||||||
|
- Traceability matrix linking requirements → plan steps → test cases
|
||||||
|
- BigMind fact stored
|
||||||
|
|
||||||
|
## Error Handling
|
||||||
|
|
||||||
|
| Error | Resolution |
|
||||||
|
|-------|------------|
|
||||||
|
| Assessment missing | Flag as REVISE — assessment is required before plan review |
|
||||||
|
| Plan missing | Flag as REVISE — cannot review without a plan |
|
||||||
|
| Testplan missing | Flag as REVISE — testplan is required |
|
||||||
|
| Referenced file not found | Flag specific file path as incorrect in findings |
|
||||||
|
| Worktree not found | Use main repo to verify file paths |
|
||||||
|
|
||||||
|
## Verdict Criteria
|
||||||
|
|
||||||
|
| Verdict | Criteria |
|
||||||
|
|---------|---------|
|
||||||
|
| ✅ APPROVED | All 20 checklist items pass (✅ or N/A). No blocking findings. |
|
||||||
|
| 🔄 REVISE | Any checklist item fails (❌). One or more blocking findings. |
|
||||||
|
|
||||||
|
## Review Loop
|
||||||
|
|
||||||
|
The Plan Reviewer creates a feedback loop with the Planner:
|
||||||
|
|
||||||
|
1. Planner produces assessment v1, plan v1, testplan v1
|
||||||
|
2. Plan Reviewer reviews → REVISE with specific findings
|
||||||
|
3. Planner revises → assessment v2, plan v2, testplan v2
|
||||||
|
4. Plan Reviewer reviews → APPROVED
|
||||||
|
5. Patrick gives GO
|
||||||
|
6. Pipeline proceeds to Phase 3 (JiraOps)
|
||||||
|
|
||||||
|
This loop continues until APPROVED. Maximum 3 iterations recommended — if still not approved after v3, escalate to Patrick for manual review.
|
||||||
|
|
||||||
|
## Language
|
||||||
|
|
||||||
|
- Document content: **German**
|
||||||
|
- Code references (class names, methods, patterns): English as-is
|
||||||
|
- Checklist items: German
|
||||||
@@ -0,0 +1,452 @@
|
|||||||
|
# Skill: security-review
|
||||||
|
|
||||||
|
Security-focused code review against ADP security policies and PAISY patterns.
|
||||||
|
|
||||||
|
## Description
|
||||||
|
|
||||||
|
Analyzes code changes against ADP's 67 SEC-* security rules, OWASP guidelines, and 10 PAISY-specific security patterns. Integrates automated scan results (SonarQube via MCP, DataRake secrets detection) with a 16-item manual checklist. Produces a structured security review report with a clear PASS/FAIL verdict. PASS is required before code review can proceed.
|
||||||
|
|
||||||
|
## Invoked by
|
||||||
|
|
||||||
|
🔒 Security Reviewer mode
|
||||||
|
|
||||||
|
## Required Inputs
|
||||||
|
|
||||||
|
| Input | Source | Example |
|
||||||
|
|-------|--------|---------|
|
||||||
|
| `TICKET_KEY` | Jira issue key | `ESIDEPAISY-12081` |
|
||||||
|
| `MODULE` | PAISY module name | `eau`, `eubp`, `svmeldungen` |
|
||||||
|
|
||||||
|
## Output
|
||||||
|
|
||||||
|
Markdown file: `docs/<MODULE>/<TICKET_KEY>/<TICKET_KEY>-security-review.md`
|
||||||
|
|
||||||
|
## Steps
|
||||||
|
|
||||||
|
### 1. Get the diff
|
||||||
|
|
||||||
|
```bash
|
||||||
|
cd /Users/pplate/git/paisy-<TICKET_KEY>
|
||||||
|
git diff origin/current --name-only
|
||||||
|
git diff origin/current --stat
|
||||||
|
git diff origin/current
|
||||||
|
```
|
||||||
|
|
||||||
|
Identify all changed files. Separate Java source files from test files, resources, and documentation.
|
||||||
|
|
||||||
|
### 2. Read changed files fully for context
|
||||||
|
|
||||||
|
For each changed Java file, read the full file — not just the diff hunks. Security issues often depend on surrounding context (e.g., a method that looks safe in isolation but is called with untrusted input).
|
||||||
|
|
||||||
|
```bash
|
||||||
|
cd /Users/pplate/git/paisy-<TICKET_KEY>
|
||||||
|
git diff origin/current --name-only | grep "\.java$"
|
||||||
|
```
|
||||||
|
|
||||||
|
### 3. Run SonarQube analyze_code_snippet on changed files
|
||||||
|
|
||||||
|
For each changed Java file, use the SonarQube MCP tool:
|
||||||
|
|
||||||
|
```python
|
||||||
|
# Read the full file content
|
||||||
|
file_content = read_file("<path_to_changed_file>")
|
||||||
|
|
||||||
|
# Analyze with SonarQube
|
||||||
|
analyze_code_snippet(
|
||||||
|
fileContent=file_content,
|
||||||
|
language=["java"],
|
||||||
|
scope=["MAIN"] # or ["TEST"] for test files
|
||||||
|
)
|
||||||
|
```
|
||||||
|
|
||||||
|
Collect all SonarQube findings. Filter for security-relevant rules (SECURITY impact software quality).
|
||||||
|
|
||||||
|
#### 3.1 DataRake Secrets Scan (Pipeline-Äquivalent)
|
||||||
|
|
||||||
|
ADP's Jenkins-Pipeline ruft `secretsScan()` über das **DataRake**-Widget auf (regex-basierter Secrets-Detector). Der Reviewer simuliert dieses Verhalten manuell, da DataRake nicht als MCP-Tool verfügbar ist.
|
||||||
|
|
||||||
|
**Was DataRake erkennt:**
|
||||||
|
- Passwörter (Literalwerte in sicherheitsrelevanten Kontexten)
|
||||||
|
- Tokens (Basic Auth, Bearer, JWT)
|
||||||
|
- Unverschlüsselte Private Keys
|
||||||
|
- Gefährliche Dateien (`.netrc`, Java Keystores `.jks`/`.p12`, SSH Private Keys)
|
||||||
|
- Gefährliche Kommandos, die Credentials offenlegen
|
||||||
|
- Hartkodierte Secrets in JDBC-Connection-Strings (Oracle, MySQL, PostgreSQL, Informix)
|
||||||
|
|
||||||
|
**Detection-Regeln (wichtig für die Beurteilung):**
|
||||||
|
- Passwort-Werte müssen **6–70 Zeichen** lang sein, um zu triggern (kürzere Werte werden als Placeholder gefiltert)
|
||||||
|
- JDBC-Rakes erkennen `user/password` direkt in URL-Connection-Strings
|
||||||
|
- Dateiendung entscheidet, welche Rakes greifen (`.java` → Java-spezifische Rakes)
|
||||||
|
- **Nur Single-Line-Matching** — über mehrere Zeilen verteilte Secrets werden nicht erkannt
|
||||||
|
|
||||||
|
**Schweregrade laut DataRake:**
|
||||||
|
|
||||||
|
| Schweregrad | Kontext | Begründung |
|
||||||
|
|-------------|---------|-----------|
|
||||||
|
| CRITICAL | Passwort/Token in HTML oder JavaScript | Kann ADP-Netzwerk verlassen (Browser-deliverable) |
|
||||||
|
| HIGH | Secrets in anderem Source-Code (`.java`, `.yml`, `.properties`, `.sh`) | Im Repository sichtbar |
|
||||||
|
| MEDIUM / LOW | Review-würdige Items (Keystores, verdächtige Muster) | Manuelle Bewertung nötig |
|
||||||
|
|
||||||
|
**Manuelles Scan-Vorgehen:**
|
||||||
|
|
||||||
|
```bash
|
||||||
|
# 1. Verdächtige Dateien identifizieren
|
||||||
|
cd /Users/pplate/git/paisy-<TICKET_KEY>
|
||||||
|
git diff origin/current --name-only | grep -E '\.(java|yml|yaml|properties|xml|sh|js|html|jsp)$'
|
||||||
|
|
||||||
|
# 2. Auf typische Secret-Patterns prüfen (6–70 Zeichen)
|
||||||
|
git diff origin/current | grep -iE '(password|passwd|pwd|token|api[_-]?key|secret)\s*[:=]\s*["\x27][^"\x27]{6,70}["\x27]'
|
||||||
|
|
||||||
|
# 3. JDBC-Connection-Strings auf Inline-Credentials prüfen
|
||||||
|
git diff origin/current | grep -iE 'jdbc:[^"\x27\s]*(user|password)='
|
||||||
|
|
||||||
|
# 4. Gefährliche Dateien finden
|
||||||
|
git diff origin/current --name-only | grep -iE '(\.netrc|\.jks|\.p12|id_rsa|id_dsa|id_ecdsa)$'
|
||||||
|
```
|
||||||
|
|
||||||
|
Quelle: Confluence EIT-Space, Seiten `3270157258` (DataRake), `3270157260` (FAQ), `3270157263` (JDBC Rakes).
|
||||||
|
|
||||||
|
### 4. Apply SEC-* rules — manual checklist (16 items)
|
||||||
|
|
||||||
|
For each changed file, systematically check:
|
||||||
|
|
||||||
|
| # | Rules | Check | What to look for |
|
||||||
|
|---|-------|-------|-----------------|
|
||||||
|
| 1 | SEC-001..004 | No hardcoded credentials | Passwords, API keys, tokens, JDBC credentials in string literals. Exclude test files. |
|
||||||
|
| 2 | SEC-005 | Credentials via `@Value`/env | All credentials must come from `@Value("${...}")`, `System.getProperty()`, or `System.getenv()`. No `private static final String PASSWORD = "..."`. |
|
||||||
|
| 3 | SEC-011 | No SQL injection | All SQL must use parameterized queries (`?` placeholders, `@Query` with `:param`, JPA Criteria API). No string concatenation in SQL. |
|
||||||
|
| 4 | SEC-012 | No path traversal | File paths from external input must be sanitized. Check for `new File(userInput)`, `Paths.get(userInput)` without validation. |
|
||||||
|
| 5 | SEC-016 | Input validation | All external data entry points (REST endpoints, file parsers, PAISY responses) must validate input before processing. |
|
||||||
|
| 6 | SEC-018 | No info disclosure in errors | Error messages must not expose stack traces, internal paths, SQL queries, or system details to callers. |
|
||||||
|
| 7 | SEC-033 | PII encryption | Payroll data, HR data, personal data must be encrypted at rest. Check for PII stored in plain text in new DB columns. |
|
||||||
|
| 8 | SEC-035 | No PII in LLM processing | No personal data (names, BBNR, Versicherungsnummer) sent to AI/LLM services. |
|
||||||
|
| 9 | SEC-040 | No sensitive data in logs | Log statements must not contain passwords, tokens, PII, or full payroll records. Check `log.debug/info/warn/error` calls. |
|
||||||
|
| 10 | SEC-055 | No `src.gen/` modifications | Files under `src.gen/` are JAXB-generated. Any modification is silently overwritten and creates false security. |
|
||||||
|
| 11 | SEC-057 | ServiceCenter `F;` response validation | Every `ServiceCenter.INSTANCE()` call must check if the response starts with `F;` before parsing. Unchecked `F;` responses can lead to corrupted payroll data sent to government agencies. |
|
||||||
|
| 12 | SEC-058 | Date sentinel handling | Before parsing dates from PAISY, check for sentinel values: `00.00.0000`, `0000000`, `9999999`. Parsing these causes `DateTimeParseException` or silently wrong date calculations. |
|
||||||
|
| 13 | SEC-059 | Batch EntityManager flush/clear | Batch processing loops must call `em.flush()` and `em.clear()` every 100 items. Without this, the JPA persistence context grows unbounded → `OutOfMemoryError` in production. |
|
||||||
|
| 14 | SEC-060 | Dual Flyway migrations | Every new migration must exist in BOTH `db/migration/H2/` AND `db/migration/ORACLE/`. Missing one breaks either dev/test (H2) or production (Oracle). |
|
||||||
|
| 15 | SEC-061 | No hardcoded BBNR/IDs | No hardcoded Betriebsnummern, sprint IDs, Epic keys, or instance names. These must come from configuration or runtime lookup. |
|
||||||
|
| 16 | SEC-064 | DataRake compliance — no secrets in source | No literal passwords/tokens (6–70 chars), no inline credentials in JDBC URLs, no committed keystores/SSH keys, no dangerous credential-exposing commands. H2 test DBs must use random UUID passwords, not default `sa`/empty. |
|
||||||
|
|
||||||
|
### 5. Check PAISY-specific patterns (SEC-055 through SEC-063) with code examples
|
||||||
|
|
||||||
|
For each PAISY-specific rule, verify against the actual code:
|
||||||
|
|
||||||
|
#### SEC-055: src.gen/ protection
|
||||||
|
```bash
|
||||||
|
# Check if any changed files are under src.gen/
|
||||||
|
git diff origin/current --name-only | grep "src\.gen/"
|
||||||
|
# If any match → CRITICAL finding
|
||||||
|
```
|
||||||
|
|
||||||
|
#### SEC-056: JAXB namespace
|
||||||
|
```java
|
||||||
|
// ❌ FAIL — javax namespace (legacy)
|
||||||
|
import javax.xml.bind.annotation.*;
|
||||||
|
|
||||||
|
// ✅ PASS — jakarta namespace
|
||||||
|
import jakarta.xml.bind.annotation.*;
|
||||||
|
```
|
||||||
|
|
||||||
|
#### SEC-057: ServiceCenter F; validation
|
||||||
|
```java
|
||||||
|
// ❌ UNSAFE — no error check
|
||||||
|
String response = ServiceCenter.INSTANCE().getPaisy().pgmReadLine();
|
||||||
|
String[] parts = response.split(";");
|
||||||
|
String bbnr = parts[1]; // ArrayIndexOutOfBoundsException or wrong data if F; response
|
||||||
|
|
||||||
|
// ✅ SAFE — error check first
|
||||||
|
String response = ServiceCenter.INSTANCE().getPaisy().pgmReadLine();
|
||||||
|
if (response.startsWith("F;")) {
|
||||||
|
log.error("PAISY error: {}", response);
|
||||||
|
throw new PaisyRuntimeException("ServiceCenter error: " + response);
|
||||||
|
}
|
||||||
|
String[] parts = response.split(";");
|
||||||
|
```
|
||||||
|
|
||||||
|
#### SEC-058: Date sentinel handling
|
||||||
|
```java
|
||||||
|
// ❌ UNSAFE — no sentinel check
|
||||||
|
LocalDate date = LocalDate.parse(paiDate, formatter);
|
||||||
|
|
||||||
|
// ✅ SAFE — sentinel check first
|
||||||
|
if (paiDate.equals("00.00.0000") || paiDate.equals("0000000") || paiDate.equals("9999999")) {
|
||||||
|
return null; // or LocalDate.MAX / LocalDate.MIN as appropriate
|
||||||
|
}
|
||||||
|
LocalDate date = LocalDate.parse(paiDate, formatter);
|
||||||
|
```
|
||||||
|
|
||||||
|
#### SEC-059: Batch EM flush/clear
|
||||||
|
```java
|
||||||
|
// ❌ UNSAFE — no flush/clear in batch loop
|
||||||
|
for (Record record : records) {
|
||||||
|
em.persist(record);
|
||||||
|
}
|
||||||
|
|
||||||
|
// ✅ SAFE — flush/clear every 100 items
|
||||||
|
for (int i = 0; i < records.size(); i++) {
|
||||||
|
em.persist(records.get(i));
|
||||||
|
if (i % 100 == 0) {
|
||||||
|
em.flush();
|
||||||
|
em.clear();
|
||||||
|
}
|
||||||
|
}
|
||||||
|
```
|
||||||
|
|
||||||
|
#### SEC-060: Dual Flyway migrations
|
||||||
|
```bash
|
||||||
|
# Check for new migration files
|
||||||
|
git diff origin/current --name-only | grep "db/migration"
|
||||||
|
# For each H2 migration, verify a matching ORACLE migration exists (and vice versa)
|
||||||
|
```
|
||||||
|
|
||||||
|
#### SEC-061: No hardcoded identifiers
|
||||||
|
```java
|
||||||
|
// ❌ FAIL — hardcoded BBNR
|
||||||
|
String bbnr = "12345678";
|
||||||
|
|
||||||
|
// ❌ FAIL — hardcoded sprint ID
|
||||||
|
int sprintId = 1234;
|
||||||
|
|
||||||
|
// ✅ PASS — from configuration
|
||||||
|
@Value("${paisy.bbnr}")
|
||||||
|
private String bbnr;
|
||||||
|
```
|
||||||
|
|
||||||
|
#### SEC-062: CSV encoding
|
||||||
|
```java
|
||||||
|
// ❌ FAIL — wrong encoding
|
||||||
|
new FileReader(csvFile, StandardCharsets.UTF_8);
|
||||||
|
|
||||||
|
// ✅ PASS — correct German government standard
|
||||||
|
new FileReader(csvFile, Charset.forName("ISO-8859-1"));
|
||||||
|
```
|
||||||
|
|
||||||
|
#### SEC-063: Parameterized logging
|
||||||
|
```java
|
||||||
|
// ❌ FAIL — string concatenation
|
||||||
|
log.debug("Processing BBNR: " + bbnr + " with status: " + status);
|
||||||
|
|
||||||
|
// ✅ PASS — parameterized
|
||||||
|
log.debug("Processing BBNR: {} with status: {}", bbnr, status);
|
||||||
|
```
|
||||||
|
|
||||||
|
#### SEC-064: DataRake compliance — H2 test database pattern
|
||||||
|
|
||||||
|
H2 in-memory Test-Datenbanken sind ein häufiger Auslöser für DataRake-Findings. Der **default user `sa` mit leerem Passwort** triggert die JDBC-Rakes nicht zuverlässig (`sa` < 6 Zeichen), aber jeder kurze hartkodierte Wert in `JDBC_PASSWORD` kann als Secret erkannt werden, sobald er die 6-Zeichen-Schwelle überschreitet.
|
||||||
|
|
||||||
|
```java
|
||||||
|
// ✅ SAFE — kein User gesetzt, zufälliges UUID-Passwort (wird nicht als Secret erkannt,
|
||||||
|
// da UUID-Format als Test-Pattern gefiltert wird und kein User → kein JDBC-Rake-Match)
|
||||||
|
props.put(JDBC_DRIVER, "org.h2.Driver");
|
||||||
|
props.put(JDBC_URL, "jdbc:h2:mem:test_db;DB_CLOSE_DELAY=-1;MODE=Oracle");
|
||||||
|
props.put(JDBC_PASSWORD, UUID.randomUUID().toString());
|
||||||
|
|
||||||
|
// ❌ TRIGGERS — default user "sa" + festes kurzes Passwort
|
||||||
|
props.put(JDBC_USER, "sa");
|
||||||
|
props.put(JDBC_PASSWORD, "testpassword123");
|
||||||
|
|
||||||
|
// ❌ TRIGGERS — Inline-Credentials im JDBC-URL
|
||||||
|
props.put(JDBC_URL, "jdbc:oracle:thin:scott/tiger123@//host:1521/SID");
|
||||||
|
|
||||||
|
// ✅ SAFE — Credentials separat, via @Value oder env
|
||||||
|
@Value("${db.user}")
|
||||||
|
private String dbUser;
|
||||||
|
@Value("${db.password}")
|
||||||
|
private String dbPassword;
|
||||||
|
```
|
||||||
|
|
||||||
|
**Generelle Regeln zur Vermeidung von DataRake-Findings:**
|
||||||
|
- Keine literalen Passwörter (6–70 Zeichen) in `.java`, `.yml`, `.properties`, `.xml`, `.sh`
|
||||||
|
- Keine Inline-Credentials in JDBC-URLs (`user=`/`password=` im URL-String)
|
||||||
|
- Keine Java Keystores (`.jks`, `.p12`), SSH Private Keys oder `.netrc`-Dateien im Repository
|
||||||
|
- Template-Variablen verwenden: `${ENV_VAR}`, `{placeholder}`, `((concourse-var))` — DataRake filtert diese als StandardPatterns
|
||||||
|
- Für Tests: `UUID.randomUUID().toString()` oder `ENC[AES256,...]` für verschlüsselte Werte
|
||||||
|
|
||||||
|
Präzedenzfall: `ESIDEPAISY-12154` dokumentiert das Pattern `user=password=<short_value>` als bewusst akzeptierten lokalen Dev-Pattern.
|
||||||
|
|
||||||
|
### 6. Identify false positives
|
||||||
|
|
||||||
|
Before flagging a finding, check against known false positive patterns:
|
||||||
|
|
||||||
|
| Pattern | Tool | Why It's Safe | Action |
|
||||||
|
|---------|------|--------------|--------|
|
||||||
|
| Variable self-assignment | DataRake | Variable assignment, not a password literal | Skip |
|
||||||
|
| Credential parsing from connection string | DataRake | Extracting, not hardcoding | Skip |
|
||||||
|
| Environment variable retrieval | DataRake | Runtime injection, not hardcoded | Skip |
|
||||||
|
| Test data in `src/test/` | Both | Test-only scope, never deployed | Skip (unless test exposes real credentials) |
|
||||||
|
| Application-specific passwords by design | DataRake | Business logic requirement (e.g., PDF encryption) | Document as exception |
|
||||||
|
| Log file matches | DataRake | Build artifacts, not source code | Skip |
|
||||||
|
| Snyk result files | DataRake | Scan output, not source | Skip |
|
||||||
|
| Username=password pattern for local dev | DataRake | Intentional dev-only pattern (ESIDEPAISY-12154 precedent) | Document as accepted risk |
|
||||||
|
|
||||||
|
#### DataRake StandardPatternFilters (built-in false positives)
|
||||||
|
|
||||||
|
DataRake filtert die folgenden Werte automatisch — sie lösen **kein** Finding aus und müssen nicht als False Positive dokumentiert werden:
|
||||||
|
|
||||||
|
| Pattern-Beispiel | Typ | Begründung |
|
||||||
|
|------------------|-----|-----------|
|
||||||
|
| `${variable_name}` | Spring/Shell Template | Wird zur Laufzeit ersetzt |
|
||||||
|
| `{variable}` | Bare Braces | Template-Platzhalter |
|
||||||
|
| `{{variable}}` | Handlebars / Helm Template | Template-Engine-Syntax |
|
||||||
|
| `$(variable)` | Shell Substitution | Wird zur Laufzeit ersetzt |
|
||||||
|
| `$VARIABLE` | Bare Dollar Sign | Shell-/Env-Variable |
|
||||||
|
| `%variable%` | Windows Env Style | Wird zur Laufzeit ersetzt |
|
||||||
|
| `#variable#` | Hash-Delimited | Template-Platzhalter |
|
||||||
|
| `??variable??` | Null-Coalescing Style | Template-Platzhalter |
|
||||||
|
| `((concourse-placeholder))` | Concourse/Pipeline | Pipeline-Variable |
|
||||||
|
| `XXXXXXXXXX` / `xxxxxxxxxx` | Repeated Single Char | Regex `^([0-9A-ZxX+#*-])(\1)+$` |
|
||||||
|
| `test-test`, `foo_foo`, `aaaaaa` | Repeated Word | 3–10 gleiche Zeichen/Wortgruppen |
|
||||||
|
| `ENC[AES256,...]` | AES256-verschlüsselt | Bereits sicher verschlüsselt |
|
||||||
|
| Werte unter 6 Zeichen | Zu kurz | Alle Regexes verlangen `{6,70}` |
|
||||||
|
| `example.com`, `test.de` | Domain/URL | Beispiel-Domains |
|
||||||
|
|
||||||
|
**Konsequenz für den Reviewer:** Tritt einer dieser Patterns im Diff auf, ist es **kein Finding** — auch wenn der Kontext "password" oder "secret" enthält. Nicht in den False-Positive-Report aufnehmen, sondern still überspringen.
|
||||||
|
|
||||||
|
Also search BigMind for known false positive patterns:
|
||||||
|
```python
|
||||||
|
memory_search_facts("false positive security")
|
||||||
|
memory_search_facts("SecBench accepted")
|
||||||
|
```
|
||||||
|
|
||||||
|
### 7. Generate security review document
|
||||||
|
|
||||||
|
Write `docs/<MODULE>/<TICKET_KEY>/<TICKET_KEY>-security-review.md`:
|
||||||
|
|
||||||
|
```markdown
|
||||||
|
# Security Review: <TICKET_KEY> — <Summary>
|
||||||
|
|
||||||
|
**Datum:** <today>
|
||||||
|
**Modul:** <MODULE>
|
||||||
|
**Reviewer:** Roo (Security Reviewer)
|
||||||
|
**Branch:** <branch name>
|
||||||
|
**Verdict:** ✅ PASS / ❌ FAIL
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## Scan-Ergebnisse
|
||||||
|
|
||||||
|
| Tool | Status | Befunde |
|
||||||
|
|------|--------|---------|
|
||||||
|
| SonarQube (SAST) | ✅ Sauber / ⚠️ N Befunde | <details> |
|
||||||
|
| Datarake (Secrets) | ✅ Sauber / ⚠️ N Befunde / ⏭️ Nicht verfügbar | <details> |
|
||||||
|
| Snyk Code | ✅ Sauber / ⚠️ N Befunde / ⏭️ Nicht verfügbar | <details> |
|
||||||
|
|
||||||
|
## Manuelle Sicherheits-Checkliste
|
||||||
|
|
||||||
|
| # | Regel | Prüfpunkt | Ergebnis | Anmerkung |
|
||||||
|
|---|-------|-----------|----------|-----------|
|
||||||
|
| 1 | SEC-001..004 | Keine hartkodierten Credentials | ✅/❌ | |
|
||||||
|
| 2 | SEC-005 | Credentials via @Value/env | ✅/❌ | |
|
||||||
|
| 3 | SEC-011 | Keine SQL-Injection | ✅/❌ | |
|
||||||
|
| 4 | SEC-012 | Kein Path Traversal | ✅/❌ | |
|
||||||
|
| 5 | SEC-016 | Input-Validierung | ✅/❌ | |
|
||||||
|
| 6 | SEC-018 | Keine Info-Disclosure in Fehlern | ✅/❌ | |
|
||||||
|
| 7 | SEC-033 | PII-Verschlüsselung | ✅/N/A | |
|
||||||
|
| 8 | SEC-035 | Kein PII in LLM-Verarbeitung | ✅/N/A | |
|
||||||
|
| 9 | SEC-040 | Keine sensiblen Daten in Logs | ✅/❌ | |
|
||||||
|
| 10 | SEC-055 | Keine src.gen/ Änderungen | ✅/❌ | |
|
||||||
|
| 11 | SEC-057 | F;-Response-Validierung | ✅/N/A | |
|
||||||
|
| 12 | SEC-058 | Datums-Sentinel-Behandlung | ✅/N/A | |
|
||||||
|
| 13 | SEC-059 | Batch-EM-Flush/Clear | ✅/N/A | |
|
||||||
|
| 14 | SEC-060 | Duale Flyway-Migrationen | ✅/N/A | |
|
||||||
|
| 15 | SEC-061 | Keine hartkodierten BBNR/IDs | ✅/❌ | |
|
||||||
|
| 16 | SEC-064 | DataRake-Compliance (keine Secrets im Source) | ✅/❌ | |
|
||||||
|
|
||||||
|
## Befunde
|
||||||
|
|
||||||
|
### ❌ Kritisch / Hoch (muss behoben werden)
|
||||||
|
|
||||||
|
1. **<file>:<line>** — [SEC-XXX] <Beschreibung>
|
||||||
|
- Schweregrad: Critical/High
|
||||||
|
- Empfehlung: <Behebungsvorschlag>
|
||||||
|
|
||||||
|
### ⚠️ Mittel (sollte behoben werden)
|
||||||
|
|
||||||
|
1. **<file>:<line>** — [SEC-XXX] <Beschreibung>
|
||||||
|
- Empfehlung: <Behebungsvorschlag>
|
||||||
|
|
||||||
|
### ℹ️ Niedrig / Info
|
||||||
|
|
||||||
|
1. **<file>:<line>** — [SEC-XXX] <Beschreibung>
|
||||||
|
|
||||||
|
## Identifizierte False Positives
|
||||||
|
|
||||||
|
| Tool | Datei | Befund | Begründung |
|
||||||
|
|------|-------|--------|-----------|
|
||||||
|
| <tool> | <file> | <finding> | <why it's safe> |
|
||||||
|
|
||||||
|
## Verdict
|
||||||
|
|
||||||
|
**✅ PASS** — Keine kritischen oder hohen Sicherheitsbefunde. Weiter zum Code Review.
|
||||||
|
— oder —
|
||||||
|
**❌ FAIL** — N kritische/hohe Befunde müssen vor dem Code Review behoben werden.
|
||||||
|
```
|
||||||
|
|
||||||
|
### 8. Determine verdict
|
||||||
|
|
||||||
|
| Verdict | Criteria | Pipeline Action |
|
||||||
|
|---------|---------|----------------|
|
||||||
|
| ✅ PASS | No Critical or High findings after false positive filtering | Proceed to Phase 6 (Code Review) |
|
||||||
|
| ❌ FAIL | Any Critical or High finding remains | Loop back to Phase 4 (Code mode) for fixes, then re-review |
|
||||||
|
|
||||||
|
### 9. Store findings in BigMind
|
||||||
|
|
||||||
|
```python
|
||||||
|
memory_store_fact(
|
||||||
|
category="codebase",
|
||||||
|
fact=f"{TICKET_KEY}: Security review {verdict}. {total_findings} findings ({critical} Critical, {high} High, {medium} Medium, {low} Low). {false_positives} false positives identified."
|
||||||
|
)
|
||||||
|
|
||||||
|
# For significant findings, store details
|
||||||
|
memory_append_chunk(
|
||||||
|
session_id=SESSION_ID,
|
||||||
|
content=f"Security review for {TICKET_KEY}:\nVerdict: {verdict}\nFindings: {details}\nFalse positives: {fp_details}",
|
||||||
|
flag_reason="security review findings"
|
||||||
|
)
|
||||||
|
```
|
||||||
|
|
||||||
|
## Expected Output
|
||||||
|
|
||||||
|
- Security review document at `docs/<MODULE>/<TICKET_KEY>/<TICKET_KEY>-security-review.md`
|
||||||
|
- SonarQube scan results integrated (where available)
|
||||||
|
- All 16 manual checklist items evaluated (incl. DataRake secrets compliance)
|
||||||
|
- False positives identified and documented with rationale
|
||||||
|
- Clear PASS/FAIL verdict
|
||||||
|
- BigMind fact stored
|
||||||
|
|
||||||
|
## Error Handling
|
||||||
|
|
||||||
|
| Error | Resolution |
|
||||||
|
|-------|------------|
|
||||||
|
| Worktree not found | Check if `/Users/pplate/git/paisy-<TICKET_KEY>` exists, or use main repo with branch checkout |
|
||||||
|
| SonarQube MCP unavailable | Skip automated scan, note in report as "⏭️ Nicht verfügbar", rely on manual checklist |
|
||||||
|
| DataRake not available as MCP | Expected — always perform manual DataRake simulation via Step 3.1 grep commands |
|
||||||
|
| No Java files changed | Skip SonarQube scan and SAST checks, focus on configuration/resource security |
|
||||||
|
| Empty diff | Branch identical to `current` — report "no changes to review" |
|
||||||
|
| Large diff (>50 files) | Focus on high-risk files first: files with `ServiceCenter`, `EntityManager`, `@Value`, SQL, file I/O |
|
||||||
|
|
||||||
|
## Severity Levels
|
||||||
|
|
||||||
|
| Severity | Symbol | Definition | SLA | Pipeline Impact |
|
||||||
|
|----------|--------|-----------|-----|----------------|
|
||||||
|
| Critical | ❌ | Exploitable vulnerability, hardcoded production credentials, data corruption risk | Fix immediately | Blocks pipeline — FAIL |
|
||||||
|
| High | ❌ | Security weakness that could be exploited with effort, missing input validation on external data | Fix before merge | Blocks pipeline — FAIL |
|
||||||
|
| Medium | ⚠️ | Security improvement needed but not immediately exploitable | Fix in sprint | Advisory — PASS with warnings |
|
||||||
|
| Low | ℹ️ | Best practice suggestion, defense-in-depth improvement | Fix when convenient | Advisory — PASS |
|
||||||
|
|
||||||
|
## Language
|
||||||
|
|
||||||
|
- Document content: **German**
|
||||||
|
- Code references (class names, methods, file paths): English as-is
|
||||||
|
- Checklist items: German
|
||||||
|
- BigMind facts: English
|
||||||
|
|
||||||
|
## Conventions
|
||||||
|
|
||||||
|
- One security review per ticket — don't split across multiple documents
|
||||||
|
- Always run SonarQube `analyze_code_snippet` when MCP tool is available
|
||||||
|
- Document ALL false positives with rationale — this builds the knowledge base
|
||||||
|
- Reference SEC-* rule IDs in all findings for traceability
|
||||||
|
- If a finding was previously accepted as risk (check BigMind), note it but don't re-flag
|
||||||
@@ -0,0 +1,238 @@
|
|||||||
|
# Skill: sprint-report
|
||||||
|
|
||||||
|
Generate sprint status report from Jira data.
|
||||||
|
|
||||||
|
## Invoked by
|
||||||
|
|
||||||
|
🎫 JiraOps mode (or 🪃 Orchestrator delegating to JiraOps)
|
||||||
|
|
||||||
|
## Required Inputs
|
||||||
|
|
||||||
|
| Input | Source | Example |
|
||||||
|
|-------|--------|---------|
|
||||||
|
| `PROJECT_KEY` | Jira project key | `ESIDEPAISY` |
|
||||||
|
| `SPRINT_ID` | Sprint ID (optional — auto-detected if omitted) | `1234` |
|
||||||
|
| `OUTPUT_FORMAT` | Report format (optional) | `markdown`, `confluence`, `teams` |
|
||||||
|
|
||||||
|
## Output
|
||||||
|
|
||||||
|
- Markdown report: `docs/sprint-reports/sprint-<sprint_name>-<date>.md`
|
||||||
|
- Optionally: Confluence page or Teams message
|
||||||
|
|
||||||
|
## Steps
|
||||||
|
|
||||||
|
### 1. Get active sprint
|
||||||
|
|
||||||
|
If `SPRINT_ID` is not provided, auto-detect:
|
||||||
|
|
||||||
|
```python
|
||||||
|
# Get the board
|
||||||
|
boards = get_agile_boards(project_key="ESIDEPAISY")
|
||||||
|
board_id = boards[0]["id"]
|
||||||
|
|
||||||
|
# Get active sprint
|
||||||
|
sprints = get_sprints_from_board(board_id=board_id, states="active")
|
||||||
|
sprint = sprints[0]
|
||||||
|
sprint_id = sprint["id"]
|
||||||
|
sprint_name = sprint["name"]
|
||||||
|
```
|
||||||
|
|
||||||
|
### 2. Get sprint tickets
|
||||||
|
|
||||||
|
```python
|
||||||
|
tickets = get_tickets_from_sprint(
|
||||||
|
sprint_id=sprint_id,
|
||||||
|
fields="project,summary,status,issuetype,assignee,customfield_10001,customfield_10106"
|
||||||
|
)
|
||||||
|
```
|
||||||
|
|
||||||
|
Key fields:
|
||||||
|
- `status` — current ticket status
|
||||||
|
- `assignee` — who's working on it
|
||||||
|
- `issuetype` — Story, Bug, Task
|
||||||
|
- `customfield_10106` — Story Points (if configured)
|
||||||
|
- `customfield_10001` — Feature Link (Epic)
|
||||||
|
|
||||||
|
### 3. Categorize tickets by status
|
||||||
|
|
||||||
|
Group tickets into workflow buckets:
|
||||||
|
|
||||||
|
| Category | Statuses |
|
||||||
|
|----------|----------|
|
||||||
|
| To Do | `Open`, `Backlog`, `To Do` |
|
||||||
|
| In Progress | `In Progress`, `In Development` |
|
||||||
|
| In Review | `In Review`, `Code Review` |
|
||||||
|
| Done | `Done`, `Accepted`, `Closed` |
|
||||||
|
| Blocked | Any ticket with `Blocked` flag or label |
|
||||||
|
|
||||||
|
### 4. Calculate metrics
|
||||||
|
|
||||||
|
```python
|
||||||
|
total = len(tickets)
|
||||||
|
done = len([t for t in tickets if t["status"] in DONE_STATUSES])
|
||||||
|
in_progress = len([t for t in tickets if t["status"] in PROGRESS_STATUSES])
|
||||||
|
todo = len([t for t in tickets if t["status"] in TODO_STATUSES])
|
||||||
|
completion_pct = round(done / total * 100) if total > 0 else 0
|
||||||
|
```
|
||||||
|
|
||||||
|
### 5. Group by assignee
|
||||||
|
|
||||||
|
```python
|
||||||
|
by_assignee = {}
|
||||||
|
for ticket in tickets:
|
||||||
|
assignee = ticket.get("assignee", "Unassigned")
|
||||||
|
by_assignee.setdefault(assignee, []).append(ticket)
|
||||||
|
```
|
||||||
|
|
||||||
|
### 6. Group by Epic/Feature
|
||||||
|
|
||||||
|
```python
|
||||||
|
by_epic = {}
|
||||||
|
for ticket in tickets:
|
||||||
|
epic = ticket.get("customfield_10001", "Kein Epic")
|
||||||
|
by_epic.setdefault(epic, []).append(ticket)
|
||||||
|
```
|
||||||
|
|
||||||
|
### 7. Generate report
|
||||||
|
|
||||||
|
Write `docs/sprint-reports/sprint-<sprint_name>-<date>.md`:
|
||||||
|
|
||||||
|
```markdown
|
||||||
|
# Sprint Report: <sprint_name>
|
||||||
|
|
||||||
|
**Datum:** <today>
|
||||||
|
**Sprint:** <sprint_name>
|
||||||
|
**Zeitraum:** <start_date> — <end_date>
|
||||||
|
**Projekt:** ESIDEPAISY
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## Übersicht
|
||||||
|
|
||||||
|
| Metrik | Wert |
|
||||||
|
|--------|------|
|
||||||
|
| Tickets gesamt | <total> |
|
||||||
|
| Erledigt | <done> (<completion_pct>%) |
|
||||||
|
| In Bearbeitung | <in_progress> |
|
||||||
|
| Offen | <todo> |
|
||||||
|
| In Review | <in_review> |
|
||||||
|
|
||||||
|
## Fortschritt
|
||||||
|
|
||||||
|
```
|
||||||
|
[████████████░░░░░░░░] 60% (<done>/<total>)
|
||||||
|
```
|
||||||
|
|
||||||
|
## Nach Status
|
||||||
|
|
||||||
|
### ✅ Erledigt (<done>)
|
||||||
|
|
||||||
|
| Ticket | Typ | Zusammenfassung | Bearbeiter |
|
||||||
|
|--------|-----|----------------|------------|
|
||||||
|
| <key> | Story | <summary> | <assignee> |
|
||||||
|
|
||||||
|
### 🔄 In Bearbeitung (<in_progress>)
|
||||||
|
|
||||||
|
| Ticket | Typ | Zusammenfassung | Bearbeiter |
|
||||||
|
|--------|-----|----------------|------------|
|
||||||
|
| <key> | Bug | <summary> | <assignee> |
|
||||||
|
|
||||||
|
### ⏳ Offen (<todo>)
|
||||||
|
|
||||||
|
| Ticket | Typ | Zusammenfassung | Bearbeiter |
|
||||||
|
|--------|-----|----------------|------------|
|
||||||
|
| <key> | Task | <summary> | <assignee> |
|
||||||
|
|
||||||
|
## Nach Bearbeiter
|
||||||
|
|
||||||
|
| Bearbeiter | Gesamt | Erledigt | In Bearbeitung | Offen |
|
||||||
|
|-----------|--------|----------|---------------|-------|
|
||||||
|
| <name> | <n> | <done> | <wip> | <todo> |
|
||||||
|
|
||||||
|
## Nach Feature/Epic
|
||||||
|
|
||||||
|
| Epic | Tickets | Erledigt | Fortschritt |
|
||||||
|
|------|---------|----------|-------------|
|
||||||
|
| <epic_name> | <n> | <done> | <pct>% |
|
||||||
|
|
||||||
|
## Blocker / Risiken
|
||||||
|
|
||||||
|
| Ticket | Beschreibung | Seit | Auswirkung |
|
||||||
|
|--------|-------------|------|-----------|
|
||||||
|
| <key> | <blocker description> | <date> | <impact> |
|
||||||
|
|
||||||
|
<If no blockers: "Keine Blocker im aktuellen Sprint.">
|
||||||
|
```
|
||||||
|
|
||||||
|
### 8. Publish to Confluence (optional)
|
||||||
|
|
||||||
|
If `OUTPUT_FORMAT` includes `confluence`:
|
||||||
|
|
||||||
|
```python
|
||||||
|
create_page(
|
||||||
|
space_key="ESIDEPAISY",
|
||||||
|
title=f"Sprint Report: {sprint_name} — {date}",
|
||||||
|
content=<html_converted_content>,
|
||||||
|
parent_id="<sprint-reports-parent-page-id>"
|
||||||
|
)
|
||||||
|
```
|
||||||
|
|
||||||
|
### 9. Send Teams summary (optional)
|
||||||
|
|
||||||
|
If `OUTPUT_FORMAT` includes `teams`:
|
||||||
|
|
||||||
|
```python
|
||||||
|
teams_send_channel_message(
|
||||||
|
team_id="<team_id>",
|
||||||
|
channel_id="<channel_id>",
|
||||||
|
content=f"📊 *Sprint Report: {sprint_name}*\n\n"
|
||||||
|
f"Fortschritt: {done}/{total} ({completion_pct}%)\n"
|
||||||
|
f"In Bearbeitung: {in_progress}\n"
|
||||||
|
f"Offen: {todo}\n"
|
||||||
|
f"Blocker: {blocked}\n\n"
|
||||||
|
f"Vollständiger Bericht: <confluence_link or file path>"
|
||||||
|
)
|
||||||
|
```
|
||||||
|
|
||||||
|
### 10. Store in BigMind
|
||||||
|
|
||||||
|
```python
|
||||||
|
memory_store_fact(
|
||||||
|
category="codebase",
|
||||||
|
fact=f"Sprint report for {sprint_name}: {done}/{total} done ({completion_pct}%), {in_progress} in progress, {blocked} blocked."
|
||||||
|
)
|
||||||
|
```
|
||||||
|
|
||||||
|
## Expected Output
|
||||||
|
|
||||||
|
- Markdown sprint report with ticket breakdown
|
||||||
|
- Metrics: completion %, by-status, by-assignee, by-epic
|
||||||
|
- Blocker/risk section
|
||||||
|
- Optionally published to Confluence and/or Teams
|
||||||
|
|
||||||
|
## Error Handling
|
||||||
|
|
||||||
|
| Error | Resolution |
|
||||||
|
|-------|------------|
|
||||||
|
| No active sprint found | Check `states="active"` — may need `states="active,future"` |
|
||||||
|
| No tickets in sprint | Sprint may be empty or newly created — report "0 tickets" |
|
||||||
|
| Board not found | Verify project key, try `get_agile_boards` with different key |
|
||||||
|
| Story points not configured | Skip story point metrics, use ticket count only |
|
||||||
|
| Confluence publish fails | Save markdown locally, report Confluence error |
|
||||||
|
|
||||||
|
## Report Variants
|
||||||
|
|
||||||
|
| Variant | When | Content |
|
||||||
|
|---------|------|---------|
|
||||||
|
| Daily standup | Mid-sprint | Focus on in-progress + blockers only |
|
||||||
|
| Sprint review | End of sprint | Full report with all sections |
|
||||||
|
| Management summary | On request | Metrics + epic progress only, no ticket details |
|
||||||
|
|
||||||
|
Adjust the template based on the variant requested.
|
||||||
|
|
||||||
|
## Language
|
||||||
|
|
||||||
|
- Report content: **German**
|
||||||
|
- Ticket keys, branch names: English as-is
|
||||||
|
- Teams messages: **German**
|
||||||
|
- Confluence page: **German**
|
||||||
@@ -0,0 +1,154 @@
|
|||||||
|
# Skill: ssh-test-deploy
|
||||||
|
|
||||||
|
Deploy and test a module JAR on a PAISY SSH test instance.
|
||||||
|
|
||||||
|
## Invoked by
|
||||||
|
|
||||||
|
💻 Code mode (or 🪃 Orchestrator delegating to Code)
|
||||||
|
|
||||||
|
## Required Inputs
|
||||||
|
|
||||||
|
| Input | Source | Example |
|
||||||
|
|-------|--------|---------|
|
||||||
|
| `TICKET_KEY` | Jira issue key | `ESIDEPAISY-12081` |
|
||||||
|
| `MODULE` | PAISY module name | `eau`, `eubp`, `svmeldungen`, `dabpv` |
|
||||||
|
| `PROGRAM` | PAI program to run | `PAI022`, `PAIBATCH`, `PAI030` |
|
||||||
|
| `PROGRAM_ARGS` | Program arguments (optional) | `"-eau"`, `"-svmeldungen DSAK"` |
|
||||||
|
|
||||||
|
## Steps
|
||||||
|
|
||||||
|
### 1. List available test instances
|
||||||
|
|
||||||
|
```python
|
||||||
|
list-instances()
|
||||||
|
```
|
||||||
|
|
||||||
|
Pick an appropriate instance based on module and availability. If the user has a preferred instance, use that.
|
||||||
|
|
||||||
|
### 2. Select the instance
|
||||||
|
|
||||||
|
```python
|
||||||
|
set-instance(instance="<chosen instance>")
|
||||||
|
```
|
||||||
|
|
||||||
|
### 3. Build the module JAR locally
|
||||||
|
|
||||||
|
```bash
|
||||||
|
cd /Users/pplate/git/paisy-<TICKET_KEY>
|
||||||
|
mvn package -pl java/modules/cs-modules/<MODULE> -am -DskipTests -f java/pom.xml
|
||||||
|
```
|
||||||
|
|
||||||
|
Locate the built JAR:
|
||||||
|
```bash
|
||||||
|
find java/modules/cs-modules/<MODULE>/target -name "*.jar" -not -name "*-sources.jar" | head -1
|
||||||
|
```
|
||||||
|
|
||||||
|
### 4. Upload JAR to instance
|
||||||
|
|
||||||
|
```python
|
||||||
|
upload-file(
|
||||||
|
localPath="/Users/pplate/git/paisy-<TICKET_KEY>/java/modules/cs-modules/<MODULE>/target/<MODULE>-<version>.jar",
|
||||||
|
remoteFilename="<MODULE>-<version>.jar"
|
||||||
|
)
|
||||||
|
```
|
||||||
|
|
||||||
|
### 5. Run the program
|
||||||
|
|
||||||
|
```python
|
||||||
|
run-program(
|
||||||
|
program="<PROGRAM>",
|
||||||
|
args="<PROGRAM_ARGS>"
|
||||||
|
)
|
||||||
|
```
|
||||||
|
|
||||||
|
For common programs:
|
||||||
|
|
||||||
|
| Program | Purpose | Typical args |
|
||||||
|
|---------|---------|-------------|
|
||||||
|
| `PAI022` | SV-Meldeverfahren batch | `"-svmeldungen DSAK"`, `"-svmeldungen DSBD"` |
|
||||||
|
| `PAIBATCH` | General batch runner | module-specific |
|
||||||
|
| `PAI030` | Lohnsteuer | `"-lstb"` |
|
||||||
|
| `PAI028` | SVD import | (no args, reads SVD.XML) |
|
||||||
|
|
||||||
|
### 6. Parse output
|
||||||
|
|
||||||
|
Check the program output for errors:
|
||||||
|
|
||||||
|
```python
|
||||||
|
# PAISY error responses start with "F;"
|
||||||
|
# Success responses typically start with "0;" or contain "RC=0"
|
||||||
|
```
|
||||||
|
|
||||||
|
| Pattern | Meaning | Action |
|
||||||
|
|---------|---------|--------|
|
||||||
|
| `F;` prefix | PAISY error | Log error, report to user |
|
||||||
|
| `RC=0` | Success | Continue |
|
||||||
|
| `RC=4` | Warning | Log warning, review output |
|
||||||
|
| `RC=8` or higher | Error | Log error, investigate |
|
||||||
|
|
||||||
|
### 7. Verify with shell command (optional)
|
||||||
|
|
||||||
|
```python
|
||||||
|
exec-command(command="ls -la /path/to/output/")
|
||||||
|
exec-command(command="cat /path/to/logfile.log | tail -50")
|
||||||
|
```
|
||||||
|
|
||||||
|
### 8. Log results to BigMind
|
||||||
|
|
||||||
|
```python
|
||||||
|
memory_store_fact(
|
||||||
|
category="codebase",
|
||||||
|
fact=f"{TICKET_KEY}: SSH test on <instance> — {PROGRAM} {PROGRAM_ARGS} → RC={rc}. <summary>"
|
||||||
|
)
|
||||||
|
memory_append_chunk(
|
||||||
|
session_id=SESSION_ID,
|
||||||
|
content=f"SSH test deploy for {TICKET_KEY}:\nInstance: <instance>\nProgram: {PROGRAM}\nResult: <output summary>",
|
||||||
|
flag_reason="SSH test result"
|
||||||
|
)
|
||||||
|
```
|
||||||
|
|
||||||
|
## Expected Output
|
||||||
|
|
||||||
|
- Module JAR built and uploaded to test instance
|
||||||
|
- Program executed with output captured
|
||||||
|
- Results logged to BigMind
|
||||||
|
- Error/success status reported to user
|
||||||
|
|
||||||
|
## Error Handling
|
||||||
|
|
||||||
|
| Error | Resolution |
|
||||||
|
|-------|------------|
|
||||||
|
| No instances available | `list-instances()` returns empty — ask user to check VPN/SSH access |
|
||||||
|
| Build failure | Check Maven output for compilation errors, fix before retrying |
|
||||||
|
| Upload failure | Verify instance is reachable, check disk space with `exec-command("df -h")` |
|
||||||
|
| `F;` response | Parse error code, check ADP Docs Wiki for error meaning |
|
||||||
|
| `RC=15` | Often means SVD.XML is outdated — run PAI028 first to import fresh SVD data |
|
||||||
|
| Connection timeout | Instance may be down — try another instance from `list-instances()` |
|
||||||
|
|
||||||
|
## Common Workflows
|
||||||
|
|
||||||
|
### EAU test
|
||||||
|
```python
|
||||||
|
set-instance(instance="Nadine.123")
|
||||||
|
run-program(program="PAI022", args="-eau")
|
||||||
|
```
|
||||||
|
|
||||||
|
### SVMeldungen DSAK test
|
||||||
|
```python
|
||||||
|
set-instance(instance="Tanja.122")
|
||||||
|
run-program(program="PAI022", args="-svmeldungen DSAK")
|
||||||
|
```
|
||||||
|
|
||||||
|
### Full batch test
|
||||||
|
```python
|
||||||
|
# First update SVD data
|
||||||
|
run-program(program="PAI028")
|
||||||
|
# Then run the batch
|
||||||
|
run-program(program="PAIBATCH", args="<module-specific>")
|
||||||
|
```
|
||||||
|
|
||||||
|
## Language
|
||||||
|
|
||||||
|
- Log entries and BigMind facts: English
|
||||||
|
- Error descriptions from PAISY: German (preserve as-is)
|
||||||
|
- User-facing summaries: match user's language
|
||||||
@@ -0,0 +1,135 @@
|
|||||||
|
---
|
||||||
|
name: cobol-index
|
||||||
|
description: Bulk-index PAISY COBOL analysis docs into BigMind. Pulls latest paisy-ai repo, scans all .md files in analysis/, extracts summaries, and stores them as BigMind facts (category paisy-cobol). Use when asked to index, refresh, or rebuild the COBOL knowledge base.
|
||||||
|
---
|
||||||
|
|
||||||
|
# Skill: cobol-index
|
||||||
|
|
||||||
|
Bulk-index PAISY COBOL analysis docs from paisy-ai into BigMind.
|
||||||
|
|
||||||
|
## When to use
|
||||||
|
|
||||||
|
- User asks to "index COBOL docs", "refresh COBOL knowledge", or "rebuild COBOL index"
|
||||||
|
- After new analysis docs are added to paisy-ai
|
||||||
|
- When `cobol-lookup` reports missing or stale BigMind facts
|
||||||
|
- Periodic maintenance to keep BigMind up to date
|
||||||
|
|
||||||
|
## When NOT to use
|
||||||
|
|
||||||
|
- For looking up a single program or file → use `cobol-lookup` instead
|
||||||
|
- For Java domain questions → use `domain-lookup`
|
||||||
|
- For non-COBOL documentation tasks → use other skills
|
||||||
|
|
||||||
|
## Required Inputs
|
||||||
|
|
||||||
|
| Input | Source | Example |
|
||||||
|
|-------|--------|---------|
|
||||||
|
| `SCOPE` | What to index (optional, default: all) | `"all"`, `"programs"`, `"datamodel"`, `"api"`, `"batch"`, `"isam-tools"` |
|
||||||
|
|
||||||
|
## Output
|
||||||
|
|
||||||
|
- BigMind facts created/updated (`category: "paisy-cobol"`)
|
||||||
|
- Summary report: total files scanned, new facts stored, skipped (already indexed)
|
||||||
|
|
||||||
|
## Steps
|
||||||
|
|
||||||
|
### 1. Pull latest paisy-ai
|
||||||
|
|
||||||
|
```bash
|
||||||
|
git -C /Users/pplate/git/paisy-ai pull
|
||||||
|
```
|
||||||
|
|
||||||
|
If the repo doesn't exist, inform the user it needs to be cloned first.
|
||||||
|
|
||||||
|
### 2. List target files based on scope
|
||||||
|
|
||||||
|
| Scope | Path pattern |
|
||||||
|
|-------|-------------|
|
||||||
|
| `all` | `analysis/**/*.md` |
|
||||||
|
| `programs` | `analysis/PAI*.md` |
|
||||||
|
| `datamodel` | `analysis/datamodel/DAI*.md` |
|
||||||
|
| `api` | `analysis/api/api-PAI*.md` |
|
||||||
|
| `batch` | `analysis/batch-client/*.md` |
|
||||||
|
| `isam-tools` | `analysis/isam-tools/*.md` |
|
||||||
|
| `architecture` | `analysis/cobol-architecture.md`, `analysis/cokz-system.md`, `analysis/codebase-size.md` |
|
||||||
|
| `wiki-crosscheck` | `analysis/wiki-crosscheck-*.md` |
|
||||||
|
|
||||||
|
```bash
|
||||||
|
# Example for all:
|
||||||
|
find /Users/pplate/git/paisy-ai/analysis -name "*.md" -type f | sort
|
||||||
|
```
|
||||||
|
|
||||||
|
### 3. Check existing BigMind index
|
||||||
|
|
||||||
|
```python
|
||||||
|
memory_search_facts("paisy-cobol")
|
||||||
|
```
|
||||||
|
|
||||||
|
Note which files are already indexed to avoid duplicate storage.
|
||||||
|
|
||||||
|
### 4. For each file, extract summary
|
||||||
|
|
||||||
|
Read the first ~30 lines of each file to extract:
|
||||||
|
- The title/heading (first `#` line)
|
||||||
|
- A one-line purpose summary
|
||||||
|
- Key identifiers (program name, file name, Sachgebiet codes)
|
||||||
|
|
||||||
|
```bash
|
||||||
|
head -30 /Users/pplate/git/paisy-ai/analysis/<file>.md
|
||||||
|
```
|
||||||
|
|
||||||
|
### 5. Store as BigMind fact
|
||||||
|
|
||||||
|
```python
|
||||||
|
memory_store_fact(
|
||||||
|
category="paisy-cobol",
|
||||||
|
fact="<filename> (<type>): <summary>. Path: analysis/<path>.md"
|
||||||
|
)
|
||||||
|
```
|
||||||
|
|
||||||
|
Fact format by type:
|
||||||
|
|
||||||
|
| Type | Fact format |
|
||||||
|
|------|------------|
|
||||||
|
| PAI program | `"PAI<nnn> (program): <purpose>. Sachgebiete: <list>. Path: analysis/PAI<nnn>.md"` |
|
||||||
|
| DAI file | `"DAI<nn> (datamodel): <description>. Key fields: <list>. Path: analysis/datamodel/DAI<nn>.md"` |
|
||||||
|
| API interface | `"api-PAI<nnn> (api): <Java↔COBOL interface for ...>. Path: analysis/api/api-PAI<nnn>.md"` |
|
||||||
|
| Batch doc | `"<name> (batch): <description>. Path: analysis/batch-client/<name>.md"` |
|
||||||
|
| ISAM tool | `"<name> (isam-tool): <description>. Path: analysis/isam-tools/<name>.md"` |
|
||||||
|
| Architecture | `"<name> (architecture): <description>. Path: analysis/<name>.md"` |
|
||||||
|
| Wiki cross-check | `"<name> (wiki-crosscheck): <Sachgebiete covered>. Path: analysis/<name>.md"` |
|
||||||
|
|
||||||
|
### 6. Report results
|
||||||
|
|
||||||
|
Present a summary:
|
||||||
|
|
||||||
|
```
|
||||||
|
## COBOL Index Results
|
||||||
|
|
||||||
|
| Category | Files scanned | New facts | Skipped (existing) |
|
||||||
|
|----------|--------------|-----------|-------------------|
|
||||||
|
| PAI programs | <n> | <n> | <n> |
|
||||||
|
| DAI datamodel | <n> | <n> | <n> |
|
||||||
|
| API interfaces | <n> | <n> | <n> |
|
||||||
|
| Batch framework | <n> | <n> | <n> |
|
||||||
|
| ISAM tools | <n> | <n> | <n> |
|
||||||
|
| Architecture | <n> | <n> | <n> |
|
||||||
|
| Wiki cross-checks | <n> | <n> | <n> |
|
||||||
|
| **Total** | **<N>** | **<N>** | **<N>** |
|
||||||
|
```
|
||||||
|
|
||||||
|
## Error Handling
|
||||||
|
|
||||||
|
| Error | Resolution |
|
||||||
|
|-------|------------|
|
||||||
|
| paisy-ai repo not found | Inform user: `git clone <url> /Users/pplate/git/paisy-ai` needed |
|
||||||
|
| `git pull` fails | Warn user, proceed with existing local files |
|
||||||
|
| Empty/stub .md file | Skip, note in report as "empty" |
|
||||||
|
| BigMind store fails | Retry once, then skip and note in report |
|
||||||
|
| Too many files (>200) | Process in batches of 50, report progress between batches |
|
||||||
|
|
||||||
|
## Language
|
||||||
|
|
||||||
|
- BigMind facts: English (BigMind convention)
|
||||||
|
- Report: match user's language
|
||||||
|
- Program names, field names: preserve as-is
|
||||||
@@ -0,0 +1,141 @@
|
|||||||
|
---
|
||||||
|
name: cobol-lookup
|
||||||
|
description: Look up PAISY COBOL domain knowledge — PAI programs, DAI ISAM files, API interfaces, batch framework, ISAM tools (PDDI/Quidam), COKZ system, and COBOL architecture. Use when asked about a PAI program, DAI file, COBOL data flow, batch processing, or PAISY backend internals.
|
||||||
|
---
|
||||||
|
|
||||||
|
# Skill: cobol-lookup
|
||||||
|
|
||||||
|
Look up PAISY COBOL domain knowledge from the paisy-ai analysis repository.
|
||||||
|
|
||||||
|
## When to use
|
||||||
|
|
||||||
|
- User asks about a specific PAI program (e.g., "What does PAI022 do?")
|
||||||
|
- User asks about a DAI ISAM data file (e.g., "What fields are in DAI28?")
|
||||||
|
- User asks about a PAI API interface (e.g., "How does Java call PAI022?")
|
||||||
|
- User asks about COBOL architecture, COKZ system, batch framework, or ISAM tools
|
||||||
|
- User needs to understand data flow between COBOL programs
|
||||||
|
- User asks about wiki cross-check findings for specific Sachgebiete
|
||||||
|
|
||||||
|
## When NOT to use
|
||||||
|
|
||||||
|
- For Java module questions → use `domain-lookup` skill instead
|
||||||
|
- For Jira/Git operations → use `jira-lifecycle` or `create-worktree`
|
||||||
|
- For code changes → switch to Code mode
|
||||||
|
- For bulk indexing of all COBOL docs → use `cobol-index` skill instead
|
||||||
|
|
||||||
|
## Required Inputs
|
||||||
|
|
||||||
|
| Input | Source | Example |
|
||||||
|
|-------|--------|---------|
|
||||||
|
| `QUERY` | User question or topic | `"PAI022"`, `"DAI28 fields"`, `"batch framework"`, `"COKZ system"` |
|
||||||
|
| `CONTEXT` | Additional context (optional) | `"for ESIDEPAISY-12081"`, `"related to EAU"` |
|
||||||
|
|
||||||
|
## Output
|
||||||
|
|
||||||
|
- Structured answer with source file paths cited
|
||||||
|
- Key findings stored in BigMind (`category: "paisy-cobol"`)
|
||||||
|
|
||||||
|
## Steps
|
||||||
|
|
||||||
|
### 1. Parse query → determine lookup type
|
||||||
|
|
||||||
|
| Query pattern | Lookup type | Target path |
|
||||||
|
|--------------|-------------|-------------|
|
||||||
|
| `PAI<nnn>` or program name | PAI program | `analysis/PAI<nnn>.md` |
|
||||||
|
| `DAI<nn>` or ISAM file | DAI datamodel | `analysis/datamodel/DAI<nn>.md` |
|
||||||
|
| `api-PAI<nnn>` or "API for PAI..." | API interface | `analysis/api/api-PAI<nnn>.md` |
|
||||||
|
| Architecture, COKZ, structure | Architecture | `analysis/cobol-architecture.md`, `analysis/cokz-system.md` |
|
||||||
|
| Batch, payroll scripts, AWK | Batch framework | `analysis/batch-client/*.md` |
|
||||||
|
| PDDI, Quidam, ISAM tools | ISAM tools | `analysis/isam-tools/*.md` |
|
||||||
|
| Sachgebiet, wiki cross-check | Wiki cross-check | `analysis/wiki-crosscheck-*.md` |
|
||||||
|
| General overview | Overview | `CLAUDE.md` (repo root) |
|
||||||
|
|
||||||
|
### 2. Search BigMind first
|
||||||
|
|
||||||
|
```python
|
||||||
|
memory_search_facts("<program or topic name>")
|
||||||
|
memory_search_facts("<program or topic name> paisy-cobol")
|
||||||
|
```
|
||||||
|
|
||||||
|
If BigMind has a recent, complete answer → present it directly and skip to step 6.
|
||||||
|
|
||||||
|
### 3. Read the target doc from paisy-ai
|
||||||
|
|
||||||
|
```bash
|
||||||
|
cat /Users/pplate/git/paisy-ai/analysis/<target-file>.md
|
||||||
|
```
|
||||||
|
|
||||||
|
If the exact file doesn't exist, search for related content:
|
||||||
|
|
||||||
|
```bash
|
||||||
|
ls /Users/pplate/git/paisy-ai/analysis/ | grep -i "<keyword>"
|
||||||
|
grep -rl "<keyword>" /Users/pplate/git/paisy-ai/analysis/ --include="*.md" | head -10
|
||||||
|
```
|
||||||
|
|
||||||
|
### 4. Cross-reference related docs
|
||||||
|
|
||||||
|
After reading the primary doc:
|
||||||
|
- If it's a PAI program → check if an API doc exists: `analysis/api/api-PAI<nnn>.md`
|
||||||
|
- If it's a PAI program → check which DAI files it references (mentioned in the doc)
|
||||||
|
- If it's a DAI file → check which PAI programs use it (grep across program docs)
|
||||||
|
- If it's an API → read the corresponding PAI program doc for full context
|
||||||
|
|
||||||
|
### 5. Present findings structured
|
||||||
|
|
||||||
|
Format the response as:
|
||||||
|
|
||||||
|
```
|
||||||
|
**<Program/File Name>** — <one-line summary>
|
||||||
|
|
||||||
|
<Detailed explanation from the doc>
|
||||||
|
|
||||||
|
**Source:** `analysis/<path>.md`
|
||||||
|
**Related:** <list of related PAI/DAI/API docs if any>
|
||||||
|
**See also:** <ADP Wiki page if relevant>
|
||||||
|
```
|
||||||
|
|
||||||
|
### 6. Store key findings in BigMind
|
||||||
|
|
||||||
|
```python
|
||||||
|
memory_store_fact(
|
||||||
|
category="paisy-cobol",
|
||||||
|
fact="<program/file>: <concise summary of purpose, key fields, or behavior>"
|
||||||
|
)
|
||||||
|
```
|
||||||
|
|
||||||
|
Only store if the fact is new or significantly more detailed than what BigMind already has.
|
||||||
|
|
||||||
|
### 7. Fall back to ADP Docs Wiki
|
||||||
|
|
||||||
|
If paisy-ai docs don't cover the topic:
|
||||||
|
|
||||||
|
```python
|
||||||
|
# Check BigMind index for known Wiki pages
|
||||||
|
memory_search_facts("<topic> adpdocs")
|
||||||
|
|
||||||
|
# Search Wiki directly
|
||||||
|
set-wiki(uri="mcp://wikis/adpdocs.de.adp.com")
|
||||||
|
search-page(query="<COBOL topic keywords>")
|
||||||
|
```
|
||||||
|
|
||||||
|
Relevant Wiki pages for COBOL topics:
|
||||||
|
- Programmabläufe → Page ID 15201
|
||||||
|
- Einzelaufrufe BATCH → Page ID 15250
|
||||||
|
- Fehlermeldungen → Page ID 15196
|
||||||
|
- Umgebungsvariablen → Page ID 22767
|
||||||
|
|
||||||
|
## Error Handling
|
||||||
|
|
||||||
|
| Error | Resolution |
|
||||||
|
|-------|------------|
|
||||||
|
| Doc file not found | Search with `grep -rl` across analysis/; the program may have a variant name |
|
||||||
|
| BigMind returns nothing | Proceed to read from paisy-ai docs directly |
|
||||||
|
| paisy-ai repo not cloned | Run `git clone` or inform user the repo is needed at `/Users/pplate/git/paisy-ai` |
|
||||||
|
| Multiple matches | Present all matches, let user pick the most relevant |
|
||||||
|
| Doc is empty or stub | Note the gap, fall back to ADP Wiki, suggest running `cobol-index` to refresh |
|
||||||
|
|
||||||
|
## Language
|
||||||
|
|
||||||
|
- Answers: match the user's language (German or English)
|
||||||
|
- COBOL program names, field names, Sachgebiet codes: preserve as-is
|
||||||
|
- German payroll terms: use as-is (Lohnkonto, Fehlzeiten, Sachgebiet, etc.)
|
||||||
@@ -0,0 +1,295 @@
|
|||||||
|
---
|
||||||
|
name: code-review
|
||||||
|
description: Structured code review against implementation plan.
|
||||||
|
---
|
||||||
|
|
||||||
|
# Skill: code-review
|
||||||
|
|
||||||
|
Structured code review against implementation plan, with mandatory SonarQube static analysis.
|
||||||
|
|
||||||
|
## Invoked by
|
||||||
|
|
||||||
|
🔍 Reviewer mode
|
||||||
|
|
||||||
|
## Required Inputs
|
||||||
|
|
||||||
|
| Input | Source | Example |
|
||||||
|
|-------|--------|---------|
|
||||||
|
| `TICKET_KEY` | Jira issue key | `ESIDEPAISY-12081` |
|
||||||
|
| `MODULE` | PAISY module name | `eau`, `eubp`, `svmeldungen` |
|
||||||
|
|
||||||
|
## Output
|
||||||
|
|
||||||
|
Markdown file: `docs/<MODULE>/<TICKET_KEY>/<TICKET_KEY>-review.md`
|
||||||
|
|
||||||
|
## Steps
|
||||||
|
|
||||||
|
### 1. Read the plan document
|
||||||
|
|
||||||
|
```bash
|
||||||
|
cat docs/<MODULE>/<TICKET_KEY>/<TICKET_KEY>-plan.md
|
||||||
|
```
|
||||||
|
|
||||||
|
Extract: planned changes, affected files, expected patterns, acceptance criteria.
|
||||||
|
|
||||||
|
### 2. Read the test plan (if exists)
|
||||||
|
|
||||||
|
```bash
|
||||||
|
cat docs/<MODULE>/<TICKET_KEY>/<TICKET_KEY>-testplan.md
|
||||||
|
```
|
||||||
|
|
||||||
|
Cross-reference: are all planned test cases implemented?
|
||||||
|
|
||||||
|
### 3. Get the diff
|
||||||
|
|
||||||
|
```bash
|
||||||
|
cd /Users/pplate/git/paisy-<TICKET_KEY>
|
||||||
|
git diff origin/current --name-only
|
||||||
|
git diff origin/current --stat
|
||||||
|
git diff origin/current
|
||||||
|
```
|
||||||
|
|
||||||
|
### 4. Read changed files
|
||||||
|
|
||||||
|
For each changed file, read the full file to understand context — not just the diff hunks.
|
||||||
|
|
||||||
|
```bash
|
||||||
|
cd /Users/pplate/git/paisy-<TICKET_KEY>
|
||||||
|
git diff origin/current --name-only | while read f; do echo "=== $f ==="; done
|
||||||
|
```
|
||||||
|
|
||||||
|
### 5. Run SonarQube static analysis (MANDATORY)
|
||||||
|
|
||||||
|
For every changed Java file, run the SonarQube SAST analyzer:
|
||||||
|
|
||||||
|
```python
|
||||||
|
# Get list of changed Java source files (exclude tests for MAIN scope)
|
||||||
|
changed_java = [f for f in changed_files if f.endswith(".java") and "/test/" not in f]
|
||||||
|
changed_tests = [f for f in changed_files if f.endswith(".java") and "/test/" in f]
|
||||||
|
|
||||||
|
# Analyze each source file
|
||||||
|
for java_file in changed_java:
|
||||||
|
file_content = read_file(java_file)
|
||||||
|
analyze_code_snippet(
|
||||||
|
fileContent=file_content,
|
||||||
|
language=["java"],
|
||||||
|
scope=["MAIN"]
|
||||||
|
)
|
||||||
|
|
||||||
|
# Analyze test files separately
|
||||||
|
for test_file in changed_tests:
|
||||||
|
file_content = read_file(test_file)
|
||||||
|
analyze_code_snippet(
|
||||||
|
fileContent=file_content,
|
||||||
|
language=["java"],
|
||||||
|
scope=["TEST"]
|
||||||
|
)
|
||||||
|
```
|
||||||
|
|
||||||
|
Additionally, check for PR-level Sonar analysis if a PR exists:
|
||||||
|
|
||||||
|
```python
|
||||||
|
# Check if a Sonar PR analysis exists for this branch
|
||||||
|
# Project key is always "com.adp.de:paisy"
|
||||||
|
list_pull_requests() # Get PR ID for this branch
|
||||||
|
search_sonar_issues_in_projects(
|
||||||
|
projects=["com.adp.de:paisy"],
|
||||||
|
pullRequestId="<PR_ID>",
|
||||||
|
issueStatuses=["OPEN"]
|
||||||
|
)
|
||||||
|
```
|
||||||
|
|
||||||
|
**SonarQube findings are categorized:**
|
||||||
|
| Severity | Impact on Review |
|
||||||
|
|----------|-----------------|
|
||||||
|
| BLOCKER | ❌ Blocks approval |
|
||||||
|
| HIGH | ❌ Blocks approval |
|
||||||
|
| MEDIUM | ⚠️ Warning, should fix |
|
||||||
|
| LOW/INFO | ℹ️ Informational |
|
||||||
|
|
||||||
|
### 6. Run the review checklist
|
||||||
|
|
||||||
|
For each changed file, verify:
|
||||||
|
|
||||||
|
| # | Check | What to look for |
|
||||||
|
|---|-------|-----------------|
|
||||||
|
| 1 | Plan compliance | All plan items implemented? Nothing missing, nothing extra? |
|
||||||
|
| 2 | Pattern correctness | Correct PAISY patterns used? (AbstractMeldung, Datenbaustein, ServiceCenter, EMFactory, JAXB) |
|
||||||
|
| 3 | No `src.gen/` changes | Generated sources must never be modified manually |
|
||||||
|
| 4 | Logging | `@Slf4j` or `@Log4j2` with parameterized messages (`log.debug("x: {}", v)`) — no string concatenation |
|
||||||
|
| 5 | German domain terms | Domain terms preserved: `Fehlzeiten`, `Lohnkonto`, `Vorlaufsatz`, `Nachlaufsatz` |
|
||||||
|
| 6 | Error handling | PAISY `F;` responses checked before parsing? Null-safe patterns? |
|
||||||
|
| 7 | Date handling | Correct formatters? Empty date checks (`00.00.0000`, `0000000`, `9999999`)? |
|
||||||
|
| 8 | Test coverage | Every new/modified public method has a test? Edge cases covered? |
|
||||||
|
| 9 | Flyway migrations | Correct naming convention? Dual H2/Oracle? Type mapping correct? |
|
||||||
|
| 10 | No hardcoded values | No hardcoded BBNR, sprint IDs, Epic keys, instance names? |
|
||||||
|
| 11 | Field visibility | `protected` for shared fields, `private` with Lombok for DTOs? |
|
||||||
|
| 12 | Annotations | Correct use of `@Service`/`@Lazy`, `@Transactional`, `@XmlElement`? |
|
||||||
|
| 13 | SonarQube clean | No new BLOCKER/HIGH issues? MEDIUM issues documented? |
|
||||||
|
|
||||||
|
### 7. Check test quality
|
||||||
|
|
||||||
|
```bash
|
||||||
|
cd /Users/pplate/git/paisy-<TICKET_KEY>
|
||||||
|
# Find new/modified test files
|
||||||
|
git diff origin/current --name-only | grep -E "Test\.java$"
|
||||||
|
```
|
||||||
|
|
||||||
|
For each test file:
|
||||||
|
- Meaningful assertions (not just `assertNotNull`)?
|
||||||
|
- Edge cases covered?
|
||||||
|
- Mocking done correctly (Mockito patterns)?
|
||||||
|
- Test naming convention: `test<What>_<Scenario>_<Expected>()`?
|
||||||
|
|
||||||
|
### 8. Run tests
|
||||||
|
|
||||||
|
```bash
|
||||||
|
cd /Users/pplate/git/paisy-<TICKET_KEY>
|
||||||
|
mvn test -pl java/modules/cs-modules/<MODULE> -f java/pom.xml
|
||||||
|
```
|
||||||
|
|
||||||
|
### 9. Expert Panel (for complex changes — optional)
|
||||||
|
|
||||||
|
For changes that span multiple modules, touch shared infrastructure, or involve GKV domain logic, invoke the `expert-panel-review` skill:
|
||||||
|
|
||||||
|
```
|
||||||
|
Trigger conditions (invoke if ANY apply):
|
||||||
|
- Changed files span 3+ packages
|
||||||
|
- Changes touch AbstractMeldung or shared base classes
|
||||||
|
- New/modified Datenbaustein field mappings
|
||||||
|
- JAXB schema changes (new XSD bindings)
|
||||||
|
- Flyway migrations that alter existing tables (not just add)
|
||||||
|
- ServiceCenter protocol changes
|
||||||
|
```
|
||||||
|
|
||||||
|
When triggered, invoke with `ARTIFACT_TYPE=code`.
|
||||||
|
|
||||||
|
### 10. Generate review document
|
||||||
|
|
||||||
|
Write `docs/<MODULE>/<TICKET_KEY>/<TICKET_KEY>-review.md`:
|
||||||
|
|
||||||
|
```markdown
|
||||||
|
# Code Review: <TICKET_KEY> — <Summary>
|
||||||
|
|
||||||
|
**Datum:** <today>
|
||||||
|
**Modul:** <MODULE>
|
||||||
|
**Reviewer:** Roo (Reviewer)
|
||||||
|
**Branch:** <branch name>
|
||||||
|
**Status:** ✅ Approved / ⚠️ Approved with comments / ❌ Changes requested
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## Zusammenfassung
|
||||||
|
|
||||||
|
<1-2 sentence summary of the review outcome>
|
||||||
|
|
||||||
|
## SonarQube-Analyse
|
||||||
|
|
||||||
|
| Schweregrad | Anzahl | Status |
|
||||||
|
|-------------|--------|--------|
|
||||||
|
| Blocker | <N> | ✅ 0 / ❌ N Befunde |
|
||||||
|
| High | <N> | ✅ 0 / ❌ N Befunde |
|
||||||
|
| Medium | <N> | ⚠️ N Befunde |
|
||||||
|
| Low/Info | <N> | ℹ️ |
|
||||||
|
|
||||||
|
<If PR-level Sonar analysis available:>
|
||||||
|
**Sonar Quality Gate:** ✅ Passed / ❌ Failed
|
||||||
|
|
||||||
|
## Geprüfte Dateien
|
||||||
|
|
||||||
|
| Datei | Änderung | Bewertung |
|
||||||
|
|-------|---------|-----------|
|
||||||
|
| `<path>` | Neu/Geändert | ✅ / ⚠️ / ❌ |
|
||||||
|
|
||||||
|
## Checkliste
|
||||||
|
|
||||||
|
| # | Prüfpunkt | Ergebnis | Anmerkung |
|
||||||
|
|---|-----------|----------|-----------|
|
||||||
|
| 1 | Plan-Konformität | ✅ | Alle geplanten Änderungen umgesetzt |
|
||||||
|
| 2 | Pattern-Korrektheit | ✅ | AbstractMeldung korrekt erweitert |
|
||||||
|
| 3 | Keine src.gen/ Änderungen | ✅ | — |
|
||||||
|
| 4 | Logging | ⚠️ | Zeile 42: String-Konkatenation → parameterized |
|
||||||
|
| 5 | Deutsche Domänenbegriffe | ✅ | — |
|
||||||
|
| 6 | Fehlerbehandlung | ✅ | F;-Prüfung vorhanden |
|
||||||
|
| 7 | Datumsbehandlung | ✅ | — |
|
||||||
|
| 8 | Testabdeckung | ✅ | 7 Tests, alle bestanden |
|
||||||
|
| 9 | Flyway-Migrationen | ✅ | H2 + Oracle korrekt |
|
||||||
|
| 10 | Keine Hardcoded-Werte | ✅ | — |
|
||||||
|
| 11 | Feld-Sichtbarkeit | ✅ | — |
|
||||||
|
| 12 | Annotationen | ✅ | — |
|
||||||
|
| 13 | SonarQube sauber | ✅ | Keine neuen Blocker/High Issues |
|
||||||
|
|
||||||
|
## Befunde
|
||||||
|
|
||||||
|
### ❌ Blocker (must fix)
|
||||||
|
|
||||||
|
1. **<file>:<line>** — <description of critical finding>
|
||||||
|
- Begründung: <why this must be fixed>
|
||||||
|
|
||||||
|
### ⚠️ Hinweise (non-blocking)
|
||||||
|
|
||||||
|
1. **<file>:<line>** — <description of finding>
|
||||||
|
- Empfehlung: <suggested fix>
|
||||||
|
|
||||||
|
### ℹ️ SonarQube-Befunde
|
||||||
|
|
||||||
|
<List any SonarQube findings with rule keys and descriptions>
|
||||||
|
|
||||||
|
## Expert Panel (falls durchgeführt)
|
||||||
|
|
||||||
|
<Include panel verdict if expert-panel-review was invoked>
|
||||||
|
|
||||||
|
## Tests
|
||||||
|
|
||||||
|
- **Ausgeführt:** <N> Tests
|
||||||
|
- **Bestanden:** <N> ✅
|
||||||
|
- **Fehlgeschlagen:** <N> ❌
|
||||||
|
- **Build:** ✅ Grün / ❌ Rot
|
||||||
|
|
||||||
|
## Empfehlung
|
||||||
|
|
||||||
|
<Final recommendation: merge / fix and re-review / reject>
|
||||||
|
```
|
||||||
|
|
||||||
|
### 11. Store in BigMind
|
||||||
|
|
||||||
|
```python
|
||||||
|
memory_store_fact(
|
||||||
|
category="codebase",
|
||||||
|
fact=f"{TICKET_KEY}: Code review completed — {status}. {findings_count} findings ({blockers} blockers). SonarQube: {sonar_issues} issues ({sonar_blockers} blocking)."
|
||||||
|
)
|
||||||
|
```
|
||||||
|
|
||||||
|
## Expected Output
|
||||||
|
|
||||||
|
- Review document at `docs/<MODULE>/<TICKET_KEY>/<TICKET_KEY>-review.md`
|
||||||
|
- SonarQube analysis results integrated
|
||||||
|
- All tests executed and results documented
|
||||||
|
- Expert panel verdict (if triggered)
|
||||||
|
- Clear recommendation: merge / fix / reject
|
||||||
|
|
||||||
|
## Error Handling
|
||||||
|
|
||||||
|
| Error | Resolution |
|
||||||
|
|-------|------------|
|
||||||
|
| No plan document found | Review without plan — note in review that plan was missing |
|
||||||
|
| Build fails | Document build failure as blocker, don't proceed with detailed review |
|
||||||
|
| No tests found | Flag as blocker — every change needs tests |
|
||||||
|
| Worktree not found | Check if `/Users/pplate/git/paisy-<TICKET_KEY>` exists, or use main repo with branch checkout |
|
||||||
|
| SonarQube MCP unavailable | Note in review as "⏭️ SonarQube nicht verfügbar", proceed with manual checklist only |
|
||||||
|
| Sonar project key wrong | Always use `com.adp.de:paisy` for the PAISY monorepo |
|
||||||
|
|
||||||
|
## Severity Levels
|
||||||
|
|
||||||
|
| Level | Symbol | Meaning | Action |
|
||||||
|
|-------|--------|---------|--------|
|
||||||
|
| Blocker | ❌ | Must fix before merge | Changes requested |
|
||||||
|
| Warning | ⚠️ | Should fix, not blocking | Approved with comments |
|
||||||
|
| Info | ℹ️ | Suggestion for improvement | Approved |
|
||||||
|
| OK | ✅ | No issues | — |
|
||||||
|
|
||||||
|
## Language
|
||||||
|
|
||||||
|
- Review document: **German**
|
||||||
|
- Code references (class names, methods, patterns): English as-is
|
||||||
|
- Checklist items: German
|
||||||
@@ -0,0 +1,207 @@
|
|||||||
|
---
|
||||||
|
name: create-flyway-migration
|
||||||
|
description: Generate Flyway migration SQL files for H2 and Oracle.
|
||||||
|
---
|
||||||
|
|
||||||
|
# Skill: create-flyway-migration
|
||||||
|
|
||||||
|
Generate Flyway migration SQL files for H2 and Oracle.
|
||||||
|
|
||||||
|
## Invoked by
|
||||||
|
|
||||||
|
💻 Code mode
|
||||||
|
|
||||||
|
## Required Inputs
|
||||||
|
|
||||||
|
| Input | Source | Example |
|
||||||
|
|-------|--------|---------|
|
||||||
|
| `TICKET_KEY` | Jira issue key | `ESIDEPAISY-12081` |
|
||||||
|
| `MODULE` | PAISY module name | `eau`, `eubp`, `svmeldungen`, `dabpv` |
|
||||||
|
| `ENTITY_NAME` | Table or entity being changed | `eau_rueckmeldung`, `eubp_archiv` |
|
||||||
|
| `CHANGE_TYPE` | Type of DDL change | `CREATE TABLE`, `ALTER TABLE`, `CREATE INDEX` |
|
||||||
|
|
||||||
|
## Output
|
||||||
|
|
||||||
|
- H2 migration: `java/modules/cs-modules/<MODULE>/src/main/resources/db/migration/H2/V{timestamp}__C_{revision}_{entity}.sql`
|
||||||
|
- Oracle migration: `java/modules/cs-modules/<MODULE>/src/main/resources/db/migration/ORACLE/V{timestamp}__C_{revision}_{entity}.sql`
|
||||||
|
|
||||||
|
## Steps
|
||||||
|
|
||||||
|
### 1. Determine timestamp
|
||||||
|
|
||||||
|
Generate the Flyway version timestamp in the required format:
|
||||||
|
|
||||||
|
```bash
|
||||||
|
date -u +"%Y_%m_%d_%H_%M_%S"
|
||||||
|
```
|
||||||
|
|
||||||
|
Result format: `2026_04_23_10_06_07`
|
||||||
|
|
||||||
|
### 2. Get app revision
|
||||||
|
|
||||||
|
Read the current app revision from `version.json` in the repo root:
|
||||||
|
|
||||||
|
```bash
|
||||||
|
cat version.json
|
||||||
|
```
|
||||||
|
|
||||||
|
Or extract from the parent POM:
|
||||||
|
|
||||||
|
```bash
|
||||||
|
grep -A1 '<revision>' java/pom.xml | head -2
|
||||||
|
```
|
||||||
|
|
||||||
|
The revision is the major version number (e.g., `123` from `123.4.2`).
|
||||||
|
|
||||||
|
### 3. Construct filename
|
||||||
|
|
||||||
|
```
|
||||||
|
V{timestamp}__C_{revision}_{entity_name}.sql
|
||||||
|
```
|
||||||
|
|
||||||
|
Example: `V2026_04_23_10_06_07__C_123_eau_rueckmeldung.sql`
|
||||||
|
|
||||||
|
**Note:** Double underscore `__` between version and description is mandatory Flyway convention.
|
||||||
|
|
||||||
|
### 4. Determine migration directories
|
||||||
|
|
||||||
|
Locate the module's migration directories:
|
||||||
|
|
||||||
|
```bash
|
||||||
|
ls java/modules/cs-modules/<MODULE>/src/main/resources/db/migration/
|
||||||
|
```
|
||||||
|
|
||||||
|
Expected structure:
|
||||||
|
- `db/migration/H2/` — H2-specific migrations
|
||||||
|
- `db/migration/ORACLE/` — Oracle-specific migrations
|
||||||
|
|
||||||
|
If only one directory exists, the module may use a shared migration path. Check the module's `application.properties` for `spring.flyway.locations`.
|
||||||
|
|
||||||
|
### 5. Create H2 migration
|
||||||
|
|
||||||
|
H2 supports `IF NOT EXISTS` / `IF EXISTS` clauses:
|
||||||
|
|
||||||
|
```sql
|
||||||
|
-- CREATE TABLE
|
||||||
|
CREATE TABLE IF NOT EXISTS <ENTITY_NAME> (
|
||||||
|
id BIGINT AUTO_INCREMENT PRIMARY KEY,
|
||||||
|
-- columns...
|
||||||
|
created_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP,
|
||||||
|
updated_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP
|
||||||
|
);
|
||||||
|
|
||||||
|
-- ALTER TABLE (add column)
|
||||||
|
ALTER TABLE <ENTITY_NAME> ADD COLUMN IF NOT EXISTS <column_name> <type>;
|
||||||
|
|
||||||
|
-- CREATE INDEX
|
||||||
|
CREATE INDEX IF NOT EXISTS idx_<entity>_<column> ON <ENTITY_NAME>(<column>);
|
||||||
|
|
||||||
|
-- DROP COLUMN
|
||||||
|
ALTER TABLE <ENTITY_NAME> DROP COLUMN IF EXISTS <column_name>;
|
||||||
|
```
|
||||||
|
|
||||||
|
### 6. Create Oracle migration
|
||||||
|
|
||||||
|
Oracle does NOT support `IF NOT EXISTS` — use PL/SQL blocks for idempotency when needed:
|
||||||
|
|
||||||
|
```sql
|
||||||
|
-- CREATE TABLE (simple — fails if exists, which is expected for versioned migrations)
|
||||||
|
CREATE TABLE <ENTITY_NAME> (
|
||||||
|
id NUMBER GENERATED ALWAYS AS IDENTITY PRIMARY KEY,
|
||||||
|
-- columns...
|
||||||
|
created_at TIMESTAMP DEFAULT SYSTIMESTAMP,
|
||||||
|
updated_at TIMESTAMP DEFAULT SYSTIMESTAMP
|
||||||
|
);
|
||||||
|
|
||||||
|
-- ALTER TABLE (add column — idempotent wrapper)
|
||||||
|
BEGIN
|
||||||
|
EXECUTE IMMEDIATE 'ALTER TABLE <ENTITY_NAME> ADD <column_name> <type>';
|
||||||
|
EXCEPTION
|
||||||
|
WHEN OTHERS THEN
|
||||||
|
IF SQLCODE = -1430 THEN NULL; -- column already exists
|
||||||
|
ELSE RAISE;
|
||||||
|
END IF;
|
||||||
|
END;
|
||||||
|
/
|
||||||
|
|
||||||
|
-- CREATE INDEX
|
||||||
|
CREATE INDEX idx_<entity>_<column> ON <ENTITY_NAME>(<column>);
|
||||||
|
```
|
||||||
|
|
||||||
|
### 7. Type mapping reference
|
||||||
|
|
||||||
|
| Java/H2 Type | Oracle Type | Notes |
|
||||||
|
|--------------|-------------|-------|
|
||||||
|
| `BIGINT` | `NUMBER(19)` | Primary keys |
|
||||||
|
| `INTEGER` | `NUMBER(10)` | Standard integers |
|
||||||
|
| `VARCHAR(n)` | `VARCHAR2(n)` | Strings |
|
||||||
|
| `BOOLEAN` | `NUMBER(1)` | Oracle has no native boolean |
|
||||||
|
| `TIMESTAMP` | `TIMESTAMP` | Same |
|
||||||
|
| `CLOB` | `CLOB` | Same |
|
||||||
|
| `BLOB` | `BLOB` | Same |
|
||||||
|
| `AUTO_INCREMENT` | `GENERATED ALWAYS AS IDENTITY` | Identity columns |
|
||||||
|
| `CURRENT_TIMESTAMP` | `SYSTIMESTAMP` | Default timestamp |
|
||||||
|
|
||||||
|
### 8. Register migration location (if new module)
|
||||||
|
|
||||||
|
If this is the first migration for the module, ensure the Flyway location is configured in the module's properties or EMFactory:
|
||||||
|
|
||||||
|
```java
|
||||||
|
// In EMFactory or FlywayController setup
|
||||||
|
flyway.migrate("<MODULE>", "<timestamp>");
|
||||||
|
```
|
||||||
|
|
||||||
|
Check existing modules for the pattern:
|
||||||
|
```bash
|
||||||
|
grep -rn "flyway.migrate" java/modules/cs-modules/<MODULE>/src/
|
||||||
|
```
|
||||||
|
|
||||||
|
### 9. Verify migration
|
||||||
|
|
||||||
|
Run the module's Flyway migration test to ensure the SQL is valid:
|
||||||
|
|
||||||
|
```bash
|
||||||
|
cd /Users/pplate/git/paisy-<TICKET_KEY>
|
||||||
|
mvn test -pl java/modules/cs-modules/<MODULE> -Dtest="*FlywayMigrationTest*" -f java/pom.xml
|
||||||
|
```
|
||||||
|
|
||||||
|
### 10. Store in BigMind
|
||||||
|
|
||||||
|
```python
|
||||||
|
memory_store_fact(
|
||||||
|
category="codebase",
|
||||||
|
fact=f"{TICKET_KEY}: Flyway migration V{timestamp}__C_{revision}_{entity} created for H2 + Oracle in {MODULE}"
|
||||||
|
)
|
||||||
|
```
|
||||||
|
|
||||||
|
## Expected Output
|
||||||
|
|
||||||
|
- H2 migration SQL file created in `db/migration/H2/`
|
||||||
|
- Oracle migration SQL file created in `db/migration/ORACLE/`
|
||||||
|
- Both files use correct Flyway naming convention
|
||||||
|
- Migration test passes
|
||||||
|
|
||||||
|
## Error Handling
|
||||||
|
|
||||||
|
| Error | Resolution |
|
||||||
|
|-------|------------|
|
||||||
|
| Duplicate version timestamp | Increment the seconds portion by 1 |
|
||||||
|
| H2 syntax error in test | Check H2-specific syntax (e.g., `IDENTITY` vs `AUTO_INCREMENT`) |
|
||||||
|
| Oracle PL/SQL block error | Ensure `/` terminator after PL/SQL blocks |
|
||||||
|
| Migration already applied | Flyway won't re-run versioned migrations — create a new version |
|
||||||
|
| Missing migration directory | Create `db/migration/H2/` and/or `db/migration/ORACLE/` directories |
|
||||||
|
|
||||||
|
## Conventions
|
||||||
|
|
||||||
|
- One migration file per logical change (don't combine unrelated DDL)
|
||||||
|
- H2 and Oracle files must produce equivalent schema
|
||||||
|
- Use `IF NOT EXISTS` / `IF EXISTS` in H2 for idempotency
|
||||||
|
- Oracle versioned migrations don't need idempotency (Flyway tracks them)
|
||||||
|
- Repeatable migrations use `R__` prefix instead of `V{timestamp}__`
|
||||||
|
- Comments in SQL: `-- <description>` at the top of each file
|
||||||
|
|
||||||
|
## Language
|
||||||
|
|
||||||
|
- SQL comments: English
|
||||||
|
- Column names: English (snake_case)
|
||||||
|
- Table names: English (snake_case), prefixed with module abbreviation where applicable
|
||||||
@@ -0,0 +1,173 @@
|
|||||||
|
---
|
||||||
|
name: create-pr
|
||||||
|
description: Create a Bitbucket pull request from a PAISY worktree branch.
|
||||||
|
---
|
||||||
|
|
||||||
|
# Skill: create-pr
|
||||||
|
|
||||||
|
Create a Bitbucket pull request from a PAISY worktree branch.
|
||||||
|
|
||||||
|
## Invoked by
|
||||||
|
|
||||||
|
🎫 JiraOps mode (or 🪃 Orchestrator delegating to JiraOps)
|
||||||
|
|
||||||
|
## Required Inputs
|
||||||
|
|
||||||
|
| Input | Source | Example |
|
||||||
|
|-------|--------|---------|
|
||||||
|
| `TICKET_KEY` | Jira issue key | `ESIDEPAISY-12081` |
|
||||||
|
| `MODULE` | PAISY module name | `eau`, `eubp`, `svmeldungen` |
|
||||||
|
|
||||||
|
## Output
|
||||||
|
|
||||||
|
- Bitbucket PR created targeting `current` branch
|
||||||
|
- Jira comment with PR link added
|
||||||
|
- BigMind fact stored
|
||||||
|
|
||||||
|
## Steps
|
||||||
|
|
||||||
|
### 1. Get current branch
|
||||||
|
|
||||||
|
```bash
|
||||||
|
cd /Users/pplate/git/paisy-<TICKET_KEY>
|
||||||
|
git branch --show-current
|
||||||
|
```
|
||||||
|
|
||||||
|
Expected format: `current/feature/<module>/<TICKET_KEY>-<desc>` or `current/bugfix/<module>/<TICKET_KEY>-<desc>`
|
||||||
|
|
||||||
|
### 2. Ensure all changes are committed
|
||||||
|
|
||||||
|
```bash
|
||||||
|
cd /Users/pplate/git/paisy-<TICKET_KEY>
|
||||||
|
git status
|
||||||
|
```
|
||||||
|
|
||||||
|
If uncommitted changes exist, warn the user before proceeding.
|
||||||
|
|
||||||
|
### 3. Push branch to origin
|
||||||
|
|
||||||
|
```bash
|
||||||
|
cd /Users/pplate/git/paisy-<TICKET_KEY>
|
||||||
|
git push -u origin <BRANCH>
|
||||||
|
```
|
||||||
|
|
||||||
|
### 4. Gather diff statistics
|
||||||
|
|
||||||
|
```bash
|
||||||
|
cd /Users/pplate/git/paisy-<TICKET_KEY>
|
||||||
|
git diff origin/current --stat
|
||||||
|
git diff origin/current --name-only
|
||||||
|
```
|
||||||
|
|
||||||
|
Use the stats to build the PR description.
|
||||||
|
|
||||||
|
### 5. Read Jira ticket for context
|
||||||
|
|
||||||
|
```python
|
||||||
|
ticket = retrieve_ticket_details(TICKET_KEY)
|
||||||
|
# Extract: summary, description for PR title/description
|
||||||
|
```
|
||||||
|
|
||||||
|
### 6. Compose PR title and description
|
||||||
|
|
||||||
|
PR title format (German):
|
||||||
|
```
|
||||||
|
<TICKET_KEY>: <Jira summary>
|
||||||
|
```
|
||||||
|
|
||||||
|
PR description template (German):
|
||||||
|
```markdown
|
||||||
|
## Jira
|
||||||
|
|
||||||
|
<TICKET_KEY>: <summary>
|
||||||
|
|
||||||
|
## Beschreibung
|
||||||
|
|
||||||
|
<Brief description of what was changed and why, derived from Jira ticket and plan doc>
|
||||||
|
|
||||||
|
## Änderungen
|
||||||
|
|
||||||
|
<List of changed files grouped by component, from git diff --stat>
|
||||||
|
|
||||||
|
### <Component 1>
|
||||||
|
- `<file1>` — <what changed>
|
||||||
|
- `<file2>` — <what changed>
|
||||||
|
|
||||||
|
### <Component 2>
|
||||||
|
- `<file3>` — <what changed>
|
||||||
|
|
||||||
|
## Tests
|
||||||
|
|
||||||
|
- <N> Unit-Tests
|
||||||
|
- <M> Integrationstests
|
||||||
|
- Alle Tests bestanden ✅
|
||||||
|
|
||||||
|
## Checkliste
|
||||||
|
|
||||||
|
- [ ] Code Review durchgeführt
|
||||||
|
- [ ] Tests bestanden
|
||||||
|
- [ ] Flyway-Migrationen geprüft (H2 + Oracle)
|
||||||
|
- [ ] Keine `src.gen/` Änderungen
|
||||||
|
```
|
||||||
|
|
||||||
|
### 7. Create the pull request
|
||||||
|
|
||||||
|
```python
|
||||||
|
create_pull_request(
|
||||||
|
project_key="ESIDEPAISY",
|
||||||
|
repo_slug="paisy",
|
||||||
|
title=f"{TICKET_KEY}: {summary}",
|
||||||
|
description=<composed description>,
|
||||||
|
from_branch=<BRANCH>,
|
||||||
|
to_branch="current"
|
||||||
|
)
|
||||||
|
```
|
||||||
|
|
||||||
|
### 8. Add Jira comment with PR link
|
||||||
|
|
||||||
|
```python
|
||||||
|
add_comment_to_ticket(
|
||||||
|
issue_key=TICKET_KEY,
|
||||||
|
comment=f"*Pull Request erstellt*\n\nBranch: {BRANCH}\nPR: [PR #{pr_id}|<pr_url>]\n\nÄnderungen: {N} Dateien geändert, {M} neu"
|
||||||
|
)
|
||||||
|
```
|
||||||
|
|
||||||
|
### 9. Store in BigMind
|
||||||
|
|
||||||
|
```python
|
||||||
|
memory_store_fact(
|
||||||
|
category="codebase",
|
||||||
|
fact=f"{TICKET_KEY}: PR #{pr_id} created — {BRANCH} → current. {N} files changed."
|
||||||
|
)
|
||||||
|
```
|
||||||
|
|
||||||
|
## Expected Output
|
||||||
|
|
||||||
|
- Branch pushed to origin
|
||||||
|
- Bitbucket PR created with German title/description
|
||||||
|
- Jira comment added with PR link
|
||||||
|
- BigMind fact stored
|
||||||
|
|
||||||
|
## Error Handling
|
||||||
|
|
||||||
|
| Error | Resolution |
|
||||||
|
|-------|------------|
|
||||||
|
| Branch not pushed | Run `git push -u origin <BRANCH>` first |
|
||||||
|
| Uncommitted changes | Warn user, suggest `git add` + `git commit` |
|
||||||
|
| PR already exists | Check `list_prs_for_repository` for existing PR from same branch |
|
||||||
|
| Merge conflicts | Run `git fetch origin current && git merge origin/current` in worktree, resolve conflicts |
|
||||||
|
| No diff (empty PR) | Branch is identical to `current` — nothing to merge |
|
||||||
|
|
||||||
|
## Conventions
|
||||||
|
|
||||||
|
- PR title: always starts with `TICKET_KEY:` for Jira auto-linking
|
||||||
|
- PR description: German (matches Jira language)
|
||||||
|
- Target branch: always `current` (never `master` or `main`)
|
||||||
|
- Repo: `project_key="ESIDEPAISY"`, `repo_slug="paisy"`
|
||||||
|
- One PR per ticket — don't create multiple PRs for the same branch
|
||||||
|
|
||||||
|
## Language
|
||||||
|
|
||||||
|
- PR title and description: **German**
|
||||||
|
- Branch names, file paths: English as-is
|
||||||
|
- Jira comment: **German**
|
||||||
@@ -0,0 +1,178 @@
|
|||||||
|
---
|
||||||
|
name: create-worktree
|
||||||
|
description: Git worktree setup for a PAISY Jira ticket. Supports multi-branch strategy (current/main, current/release, future/release) with automatic base branch selection. Use when asked to create a worktree, start work on a ticket, or set up a branch for a Jira issue.
|
||||||
|
---
|
||||||
|
|
||||||
|
# Skill: create-worktree
|
||||||
|
|
||||||
|
Git worktree setup for a PAISY Jira ticket with correct base branch selection.
|
||||||
|
|
||||||
|
## When to use
|
||||||
|
|
||||||
|
- User asks to create a worktree for a Jira ticket
|
||||||
|
- User asks to "start work on" or "set up" a ticket
|
||||||
|
- Orchestrator delegates worktree creation for a new ticket
|
||||||
|
|
||||||
|
## When NOT to use
|
||||||
|
|
||||||
|
- Switching to an existing worktree → use `switch-worktree` skill
|
||||||
|
- Removing a worktree after merge → see Cleanup section below
|
||||||
|
|
||||||
|
## Invoked by
|
||||||
|
|
||||||
|
🎫 JiraOps mode (or 🪃 Orchestrator delegating to JiraOps)
|
||||||
|
|
||||||
|
## Required Inputs
|
||||||
|
|
||||||
|
| Input | Source | Example |
|
||||||
|
|-------|--------|---------|
|
||||||
|
| `TICKET_ID` | Jira issue key | `ESIDEPAISY-12081` |
|
||||||
|
| `MODULE` | Ticket context or user input | `eau`, `eubp`, `svmeldungen`, `dabpv`, `rvbea` |
|
||||||
|
| `TYPE` | Ticket issue type (Story → feature, Bug → bugfix) | `feature` or `bugfix` |
|
||||||
|
| `SHORT_DESC` | Kebab-case summary (2-4 words) | `leftover-rueckmeldungen` |
|
||||||
|
| `BASE_BRANCH` | (Optional) Long-lived branch to base work on | `current/main` (default) |
|
||||||
|
|
||||||
|
## PAISY Branch Strategy
|
||||||
|
|
||||||
|
PAISY uses a multi-branch maintenance rotation (Wartungswechsel). These are the long-lived branches:
|
||||||
|
|
||||||
|
| Branch | Purpose | Use as base when... |
|
||||||
|
|--------|---------|-------------------|
|
||||||
|
| `current/main` | Current development — **DEFAULT** | Standard features, bugs, tasks |
|
||||||
|
| `current/release` | Current production release (hotfixes) | Urgent hotfixes that must reach production immediately |
|
||||||
|
| `future/release` | Next maintenance version | Changes targeting the next Wartungswechsel |
|
||||||
|
| `past/release` | Previous version (read-only) | **Never** — only receives cherry-picks |
|
||||||
|
|
||||||
|
### Base branch → worktree branch prefix mapping
|
||||||
|
|
||||||
|
| BASE_BRANCH | Allowed TYPE | Branch prefix |
|
||||||
|
|-------------|-------------|---------------|
|
||||||
|
| `current/main` | `feature` or `bugfix` | `current/<TYPE>/...` |
|
||||||
|
| `current/release` | `bugfix` only | `current/bugfix/...` |
|
||||||
|
| `future/release` | `feature` or `bugfix` | `future/<TYPE>/...` |
|
||||||
|
|
||||||
|
## Steps
|
||||||
|
|
||||||
|
### 1. Parse ticket metadata
|
||||||
|
|
||||||
|
```
|
||||||
|
TICKET_KEY = e.g. "ESIDEPAISY-12081"
|
||||||
|
TICKET_NUM = e.g. "12081" (numeric part only)
|
||||||
|
```
|
||||||
|
|
||||||
|
If MODULE or TYPE are not provided, retrieve them from Jira:
|
||||||
|
- `retrieve_ticket_details(TICKET_KEY)` → read `issuetype` and `summary`
|
||||||
|
- Map issue type: `Story` / `Task` → `feature`, `Bug` → `bugfix`
|
||||||
|
- Infer module from summary keywords or ask the user
|
||||||
|
|
||||||
|
### 2. Determine base branch
|
||||||
|
|
||||||
|
If `BASE_BRANCH` is not explicitly provided, apply this decision logic:
|
||||||
|
|
||||||
|
1. **Default:** `current/main`
|
||||||
|
2. **If user says "hotfix" or ticket priority is Critical/Blocker:** suggest `current/release`
|
||||||
|
3. **If user says "future", "next Wartung", or "nächste Wartung":** suggest `future/release`
|
||||||
|
|
||||||
|
When suggesting a non-default base, confirm with the user before proceeding.
|
||||||
|
|
||||||
|
### 3. Determine branch name
|
||||||
|
|
||||||
|
Derive the branch prefix from the base branch:
|
||||||
|
|
||||||
|
| BASE_BRANCH | Branch name pattern |
|
||||||
|
|-------------|-------------------|
|
||||||
|
| `current/main` | `current/<TYPE>/<MODULE>/<TICKET_KEY>-<SHORT_DESC>` |
|
||||||
|
| `current/release` | `current/bugfix/<MODULE>/<TICKET_KEY>-<SHORT_DESC>` |
|
||||||
|
| `future/release` | `future/<TYPE>/<MODULE>/<TICKET_KEY>-<SHORT_DESC>` |
|
||||||
|
|
||||||
|
```
|
||||||
|
BRANCH = <prefix>/<TYPE>/<MODULE>/<TICKET_KEY>-<SHORT_DESC>
|
||||||
|
```
|
||||||
|
|
||||||
|
Examples:
|
||||||
|
- `current/feature/eau/ESIDEPAISY-12081-leftover-rueckmeldungen` (base: `current/main`)
|
||||||
|
- `current/bugfix/eau/ESIDEPAISY-12261-azvu-package-placeholder` (base: `current/main`)
|
||||||
|
- `current/bugfix/eau/ESIDEPAISY-12836-pai280-insufficient-fields` (base: `current/release` — hotfix)
|
||||||
|
- `future/feature/eubp/ESIDEPAISY-13000-next-wartung-prep` (base: `future/release`)
|
||||||
|
|
||||||
|
**Validation:** If `BASE_BRANCH` is `current/release` and `TYPE` is `feature`, warn the user — release branches only accept bugfixes.
|
||||||
|
|
||||||
|
### 4. Ensure base branch is up to date
|
||||||
|
|
||||||
|
```bash
|
||||||
|
cd /Users/pplate/git/paisy
|
||||||
|
git fetch origin <BASE_BRANCH>
|
||||||
|
```
|
||||||
|
|
||||||
|
### 5. Create worktree
|
||||||
|
|
||||||
|
```bash
|
||||||
|
git worktree add /Users/pplate/git/paisy-<TICKET_KEY> -b <BRANCH> origin/<BASE_BRANCH>
|
||||||
|
```
|
||||||
|
|
||||||
|
This creates:
|
||||||
|
- Worktree directory: `/Users/pplate/git/paisy-<TICKET_KEY>`
|
||||||
|
- New branch: `<BRANCH>` tracking `origin/<BASE_BRANCH>`
|
||||||
|
|
||||||
|
### 6. Verify
|
||||||
|
|
||||||
|
```bash
|
||||||
|
cd /Users/pplate/git/paisy-<TICKET_KEY> && git branch --show-current
|
||||||
|
```
|
||||||
|
|
||||||
|
Expected output: the branch name from step 3.
|
||||||
|
|
||||||
|
### 7. Switch VS Code workspace to worktree
|
||||||
|
|
||||||
|
```bash
|
||||||
|
code --reuse-window /Users/pplate/git/paisy-<TICKET_KEY>
|
||||||
|
```
|
||||||
|
|
||||||
|
This opens the worktree folder in the current VS Code window, making it the active workspace.
|
||||||
|
|
||||||
|
### 8. Store in BigMind
|
||||||
|
|
||||||
|
```python
|
||||||
|
memory_store_fact(
|
||||||
|
category="codebase",
|
||||||
|
fact=f"{TICKET_KEY}: Worktree at /Users/pplate/git/paisy-{TICKET_KEY}, branch {BRANCH}, based on {BASE_BRANCH}"
|
||||||
|
)
|
||||||
|
```
|
||||||
|
|
||||||
|
### 9. Announce focus
|
||||||
|
|
||||||
|
```python
|
||||||
|
memory_announce_focus(
|
||||||
|
session_id=SESSION_ID,
|
||||||
|
description=f"Working on {TICKET_KEY} in worktree",
|
||||||
|
files=[f"/Users/pplate/git/paisy-{TICKET_KEY}"],
|
||||||
|
ide_hint="Roo"
|
||||||
|
)
|
||||||
|
```
|
||||||
|
|
||||||
|
## Expected Output
|
||||||
|
|
||||||
|
- Worktree directory exists at `/Users/pplate/git/paisy-<TICKET_KEY>`
|
||||||
|
- Branch `<BRANCH>` is checked out, based on `origin/<BASE_BRANCH>`
|
||||||
|
- VS Code workspace switched to worktree directory
|
||||||
|
- BigMind fact stored with worktree path and base branch
|
||||||
|
- Focus announced
|
||||||
|
|
||||||
|
## Error Handling
|
||||||
|
|
||||||
|
| Error | Resolution |
|
||||||
|
|-------|------------|
|
||||||
|
| Worktree already exists | Check if branch matches. If yes, reuse. If no, ask user. |
|
||||||
|
| Branch already exists | `git worktree add /Users/pplate/git/paisy-<TICKET_KEY> <BRANCH>` (without `-b`) |
|
||||||
|
| `origin/<BASE_BRANCH>` not found | Try `git fetch origin` first, then retry. Verify branch name spelling. |
|
||||||
|
| Directory already exists (not a worktree) | Ask user to remove or choose different path |
|
||||||
|
| VS Code `code` command not found | Ensure VS Code is in PATH. On macOS: Cmd+Shift+P → "Shell Command: Install 'code' command in PATH" |
|
||||||
|
| Feature on release branch | Warn user: release branches only accept bugfixes. Suggest `current/main` instead. |
|
||||||
|
|
||||||
|
## Cleanup (when ticket is done)
|
||||||
|
|
||||||
|
```bash
|
||||||
|
cd /Users/pplate/git/paisy
|
||||||
|
git worktree remove /Users/pplate/git/paisy-<TICKET_KEY>
|
||||||
|
git branch -d <BRANCH> # only after merge
|
||||||
|
```
|
||||||
@@ -0,0 +1,166 @@
|
|||||||
|
---
|
||||||
|
name: domain-lookup
|
||||||
|
description: Structured domain knowledge search across all PAISY knowledge sources.
|
||||||
|
---
|
||||||
|
|
||||||
|
# Skill: domain-lookup
|
||||||
|
|
||||||
|
Structured domain knowledge search across all PAISY knowledge sources.
|
||||||
|
|
||||||
|
## Invoked by
|
||||||
|
|
||||||
|
Any mode (📋 Planner, ❓ Ask, 🔍 Reviewer, 💻 Code)
|
||||||
|
|
||||||
|
## Required Inputs
|
||||||
|
|
||||||
|
| Input | Source | Example |
|
||||||
|
|-------|--------|---------|
|
||||||
|
| `TOPIC` | Domain topic or question | `"EuBP Archivierung"`, `"DSAK Änderungserkennung"`, `"Fehlzeiten DBFZ"` |
|
||||||
|
| `CONTEXT` | Additional context (optional) | `"for ESIDEPAISY-12081"`, `"Oracle migration syntax"` |
|
||||||
|
|
||||||
|
## Output
|
||||||
|
|
||||||
|
- Structured summary with sources cited
|
||||||
|
- New findings stored in BigMind for future reuse
|
||||||
|
|
||||||
|
## Steps
|
||||||
|
|
||||||
|
### 1. Search BigMind facts
|
||||||
|
|
||||||
|
```python
|
||||||
|
memory_search_facts("<2-3 keywords from TOPIC>")
|
||||||
|
```
|
||||||
|
|
||||||
|
FTS5 rule: AND-matches every token. Max 3 short keywords. Long queries return 0 results.
|
||||||
|
|
||||||
|
### 2. Search BigMind chunks
|
||||||
|
|
||||||
|
```python
|
||||||
|
memory_search_chunks("<2-3 keywords from TOPIC>")
|
||||||
|
```
|
||||||
|
|
||||||
|
Check for past decisions, code snippets, or session notes related to the topic.
|
||||||
|
|
||||||
|
### 3. Semantic search (if 1+2 return nothing)
|
||||||
|
|
||||||
|
```python
|
||||||
|
memory_search_semantic("<natural language description of what you're looking for>")
|
||||||
|
```
|
||||||
|
|
||||||
|
Use this when keyword search fails — it matches by meaning, not exact words.
|
||||||
|
|
||||||
|
### 4. Check ADP Docs Wiki index
|
||||||
|
|
||||||
|
```python
|
||||||
|
memory_search_facts("<topic> adpdocs")
|
||||||
|
```
|
||||||
|
|
||||||
|
Known page IDs (from BigMind `adpdocs-index` facts):
|
||||||
|
- EAU → 25123 | EuBP → 26666 | DaBPV → 27242 | DSBD → 26747 | DSAK → 26748
|
||||||
|
- DSVV → 18714 | RvBEA → 21174 | EEL → 2724 | ELStAM → 2737 | DEÜV → 5876
|
||||||
|
- Programmabläufe → 15201 | Einzelaufrufe BATCH → 15250 | Umgebungsvariablen → 22767
|
||||||
|
- PAISY verwalten → 15180 | Datenbanken verwalten → 15184 | Fehlermeldungen → 15196
|
||||||
|
|
||||||
|
### 5. Fetch Wiki page (if page ID known)
|
||||||
|
|
||||||
|
```python
|
||||||
|
set-wiki(uri="mcp://wikis/adpdocs.de.adp.com")
|
||||||
|
get-page(title="<page title>")
|
||||||
|
```
|
||||||
|
|
||||||
|
### 6. Search Wiki (if page ID not known)
|
||||||
|
|
||||||
|
```python
|
||||||
|
set-wiki(uri="mcp://wikis/adpdocs.de.adp.com")
|
||||||
|
search-page(query="<domain keywords>")
|
||||||
|
```
|
||||||
|
|
||||||
|
Or browse by category:
|
||||||
|
```python
|
||||||
|
get-category-members(category="Meldeverfahren")
|
||||||
|
```
|
||||||
|
|
||||||
|
Key categories: `Meldeverfahren`, `Verwalterhandbuch`, `Batchabläufe`, `Client Server (CS)`, `PAISYadvanced`, `Installationshandbuch für Windows und UNIX`
|
||||||
|
|
||||||
|
### 7. Search Confluence
|
||||||
|
|
||||||
|
```python
|
||||||
|
search_confluence_by_cql("text ~ '<topic keywords>' AND space = 'ESIDEPAISY'")
|
||||||
|
```
|
||||||
|
|
||||||
|
Or broader:
|
||||||
|
```python
|
||||||
|
search_confluence_by_cql("text ~ '<topic keywords>'")
|
||||||
|
```
|
||||||
|
|
||||||
|
### 8. Search Bitbucket (for code-level context)
|
||||||
|
|
||||||
|
```python
|
||||||
|
# Check recent PRs for related changes
|
||||||
|
list_prs_for_repository(project_key="ESIDEPAISY", repo_slug="paisy", status="MERGED")
|
||||||
|
|
||||||
|
# Or find a specific file
|
||||||
|
find_file(project_key="ESIDEPAISY", repo_slug="paisy", file_path="<path>", branch="current")
|
||||||
|
```
|
||||||
|
|
||||||
|
### 9. Web scraper (last resort only)
|
||||||
|
|
||||||
|
```python
|
||||||
|
webscraper_fetch(url="<relevant URL>")
|
||||||
|
```
|
||||||
|
|
||||||
|
**Only use if all previous sources returned nothing.** Never skip to webscraper if BigMind or Wiki MCP can answer.
|
||||||
|
|
||||||
|
### 10. Store new findings
|
||||||
|
|
||||||
|
After finding useful information, immediately store it:
|
||||||
|
|
||||||
|
```python
|
||||||
|
# For Wiki page discoveries
|
||||||
|
memory_store_fact(
|
||||||
|
category="adpdocs-index",
|
||||||
|
fact=f"ADP Docs Wiki: '<page title>' (Page ID: {page_id}) — <brief description of content>"
|
||||||
|
)
|
||||||
|
|
||||||
|
# For domain knowledge
|
||||||
|
memory_store_fact(
|
||||||
|
category="codebase",
|
||||||
|
fact=f"<domain topic>: <key finding>. Source: <where it came from>"
|
||||||
|
)
|
||||||
|
|
||||||
|
# For detailed findings
|
||||||
|
memory_append_chunk(
|
||||||
|
session_id=SESSION_ID,
|
||||||
|
content=f"Domain lookup for '{TOPIC}':\n<detailed findings with sources>",
|
||||||
|
flag_reason="domain knowledge"
|
||||||
|
)
|
||||||
|
```
|
||||||
|
|
||||||
|
## Expected Output
|
||||||
|
|
||||||
|
- Structured answer with cited sources
|
||||||
|
- Priority: BigMind facts → BigMind chunks → ADP Docs Wiki → Confluence → Bitbucket → webscraper
|
||||||
|
- New findings stored in BigMind for future lookups
|
||||||
|
|
||||||
|
## Error Handling
|
||||||
|
|
||||||
|
| Error | Resolution |
|
||||||
|
|-------|------------|
|
||||||
|
| BigMind FTS returns 0 | Reduce to 2 keywords, try synonyms, then use semantic search |
|
||||||
|
| Wiki page not found | Try `search-page` with different keywords, or browse category members |
|
||||||
|
| Confluence returns nothing | Broaden CQL query, remove space filter |
|
||||||
|
| All sources empty | Report "no information found" honestly — don't fabricate answers |
|
||||||
|
| Wiki connection error | Ensure `set-wiki` was called first with correct URI |
|
||||||
|
|
||||||
|
## Search Strategy Tips
|
||||||
|
|
||||||
|
- **German domain terms** often work better than English: `Fehlzeiten` not `absences`, `Lohnkonto` not `payroll account`
|
||||||
|
- **Abbreviations** are common: `DSAK`, `DSBD`, `DSVV`, `EuBP`, `DaBPV`, `RvBEA`, `EEL`
|
||||||
|
- **PAISY program names** are searchable: `PAI022`, `PAI028`, `PAI030`, `PAIBATCH`
|
||||||
|
- **Error codes** from PAISY start with `F;` — search for the specific code in Wiki Fehlermeldungen page (15196)
|
||||||
|
|
||||||
|
## Language
|
||||||
|
|
||||||
|
- Search queries: match the source language (German for Wiki/Confluence, English for code)
|
||||||
|
- Output summary: match the user's language
|
||||||
|
- Stored facts: English (BigMind convention)
|
||||||
Some files were not shown because too many files have changed in this diff Show More
Reference in New Issue
Block a user