Skip to content

Commit 2e6b708

Browse files
Maik Roland Dammclaude
andcommitted
feat(agent): BetterHarness — core skills + slim system prompt
Extract all per-tool documentation from the system prompt into 6 embedded Core Skill files (file-access, memory, plans, tasks, rules-skills, harness). System prompt shrinks from ~470 to ~240 lines; tool docs are now served lazily via `skills_read`. - Add `SkillSourceKind::Core` variant (backend + frontend wire types) - `list_skills` prepends 6 always-present core skills; `read_skill` serves embedded content; `remove_skill` rejects core names - Skills tab: Core/User sub-tabs; "Install" button hidden in Core view - SkillCard: "core" badge + remove button suppressed for core skills - All 13 locale files updated with SrSkillsTabCore/User/SrSourceCore Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
1 parent 72e44aa commit 2e6b708

30 files changed

Lines changed: 644 additions & 343 deletions

.agents/plans/PLANS.md

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -13,3 +13,4 @@ Persistent plans for multi-step work on **blxcode**. Individual plans live as Ma
1313
| done | [terminal-agent-context-handoff.md](terminal-agent-context-handoff.md) | BLXCode Agent kann aktuellen Kontext gezielt per Toolcall an Terminal-Agent-Sessions uebergeben; Bilder werden als Metadaten plus lokale Pfade exportiert |
1414
| planned | [plan-manager.md](plan-manager.md) | Plan Manager fuer `.agents/plans`: Manage-Tab wie Memory Files, plan-linked Tasks gruppiert, Agent-Toolcalls, System-Prompt-Update und shared Context fuer BLXCode Agent plus Terminal-Handoff |
1515
| planned | [kanban-board-view.md](kanban-board-view.md) | Kanban-View im Plans-Panel fuer alle Plan-Tasks eines Workspaces: Status-Spalten, Drag-and-Drop fuer Karten und Spalten, Spalten ein-/ausblenden und Markdown-Writeback |
16+
| in-progress | [better-harness.md](better-harness.md) | BetterHarness: Shrink system prompt by extracting tool docs into 6 embedded Core Skills; Skills tab gets Core/User sub-tabs |

.agents/plans/better-harness.md

Lines changed: 89 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,89 @@
1+
# BetterHarness: Core Harness Skills + Slim System Prompt
2+
3+
## Context
4+
5+
The current system prompt (`system_prompt.rs`) is ~470 lines and embeds full documentation for 50+ tools inline. This bloats every API request, consuming tokens and making prompt maintenance fragile. The goal is to extract tool documentation into **Core Skills** — built-in Markdown skill files shipped with the app — and reduce the system prompt to a minimal checklist + compact tool-name index. The Skills panel UI is extended to separate Core (built-in) from User (installed) skills.
6+
7+
---
8+
9+
## Overview of Changes
10+
11+
### 1. Core Harness Skill Files (new embedded assets)
12+
Create `src-tauri/src/agent/harness_skills/` with 6 Markdown skill files (embedded via `include_str!`):
13+
14+
| File | Covers |
15+
|---|---|
16+
| `memory.md` | `memory_*`, `memory_context_*`, `image_context_*` |
17+
| `plans.md` | `plan_*`, `plan_context_*` |
18+
| `tasks.md` | `task_*` |
19+
| `rules-skills.md` | `rules_*`, `skills_*` |
20+
| `file-access.md` | `list_workspace_files`, `read_workspace_file`, `list_tools` |
21+
| `harness.md` | `harness.*` client tools |
22+
23+
Each file contains usage guidance, parameter notes, and patterns — exactly as a user-authored `SKILL.md` would.
24+
25+
### 2. Backend: Add `Core` skill source + load harness skills
26+
27+
**`src-tauri/src/skills_rules/types.rs`**
28+
- Add `Core` variant to `SkillSourceKind` enum
29+
30+
**`src-tauri/src/skills_rules/store.rs`**
31+
- Add `CORE_SKILLS: &[(&str, &str)]` array — pairs of `(name, content)` using `include_str!`
32+
- `list_skills()` prepends core skills into the result (enabled state from workspace index, default `true`)
33+
- `read_skill()` serves core skill content from the embedded array
34+
- Core skills cannot be removed (error on `remove_skill` for core names)
35+
- `set_skill_enabled` works for both core and user skills (persisted in workspace index)
36+
37+
**`src-tauri/src/agent/system_prompt.rs`** — major reduction (~470 → ~240 lines):
38+
- Remove all per-tool documentation sections
39+
- Keep: workspace scope, security policy, turn checklist
40+
- Replace tool catalog with compact grouped name list (~25 lines)
41+
- Add: *"Call `skills_read` with a core skill name to get full usage guidance"*
42+
43+
**`src/skills_rules_wire.rs`**
44+
- Add `Core` variant to `SkillSourceKind` (mirrors backend type)
45+
46+
### 3. Frontend: Skills Tab — Core / User tabs
47+
48+
**`src/workbench/skills_rules_panel/skills_tab.rs`**
49+
- Add `SkillsView` signal: `Core | User` (default: `Core`)
50+
- Render a two-button sub-tab strip below the header
51+
- Filter displayed skills by view; "Install skill" button only visible in User view
52+
53+
**`src/workbench/skills_rules_panel/skill_card.rs`**
54+
- Add `"core"` badge with `blx-sr-card__badge--core` CSS class
55+
- Remove button suppressed for core skills (`is_core` flag)
56+
57+
**I18n strings added** (all 13 locale files):
58+
- `SrSkillsTabCore` — "Core" / locale equivalents
59+
- `SrSkillsTabUser` — "User" / locale equivalents
60+
- `SrSourceCore` — "core"
61+
62+
---
63+
64+
## Critical Files
65+
66+
| File | Change |
67+
|---|---|
68+
| `src-tauri/src/skills_rules/types.rs` | Add `Core` to `SkillSourceKind` |
69+
| `src-tauri/src/skills_rules/store.rs` | Embed + serve core skills, merge with index |
70+
| `src-tauri/src/skills_rules/install.rs` | Add `Core` arm to install match |
71+
| `src-tauri/src/agent/system_prompt.rs` | Reduce to ~240 lines; add core skill reference |
72+
| `src-tauri/src/agent/harness_skills/*.md` | 6 new embedded skill files |
73+
| `src/skills_rules_wire.rs` | Add `Core` to `SkillSourceKind` |
74+
| `src/workbench/skills_rules_panel/skills_tab.rs` | Core/User sub-tab strip + filtering |
75+
| `src/workbench/skills_rules_panel/skill_card.rs` | Core badge + no-remove guard |
76+
| `src/workbench/skills_rules_panel/install_dialog.rs` | `Core` arm in source kind matches |
77+
| `src/i18n/locales/*.rs` (all 13 locales) | 3 new I18n keys |
78+
79+
## Tasks
80+
81+
- [x] `create-skill-files` - Create 6 harness skill .md files in src-tauri/src/agent/harness_skills/
82+
- [x] `extend-source-kind` - Add Core variant to SkillSourceKind (backend + frontend wire)
83+
- [x] `update-store` - Embed + serve core skills, guard remove, enable/disable
84+
- [x] `slim-system-prompt` - Replace inline tool docs with compact list + core skill reference
85+
- [x] `i18n-keys` - Add SrSkillsTabCore, SrSkillsTabUser, SrSourceCore to all locales
86+
- [x] `skill-card-ui` - Core badge + remove button suppression
87+
- [x] `skills-tab-ui` - Core/User sub-tab strip with filtering
88+
- [x] `fix-match-exhaustive` - Add Core arms to install.rs and install_dialog.rs
89+
- [x] `update-tests` - Fix store tests to account for core skills always being present
Lines changed: 25 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,25 @@
1+
# File Access
2+
3+
Explore and read files inside the active workspace sandbox.
4+
5+
## Tools
6+
7+
### `list_tools`
8+
Returns the full catalog of every available tool (name, site, description, parameters schema). Call this when you are unsure what tools exist.
9+
10+
### `list_workspace_files { path?, recursive?, maxEntries? }`
11+
Lists files and directories under the workspace root or a relative subdirectory.
12+
- `path` — relative subdirectory (omit to list the root)
13+
- `recursive` — default `false`; set `true` for a deep scan
14+
- `maxEntries` — cap on returned entries
15+
16+
**Pattern:** Always call `list_workspace_files` before reading files when you do not know the exact path. Do not guess directory names.
17+
18+
### `read_workspace_file { path }`
19+
Reads a UTF-8 text file under the workspace root. Output is truncated at 4 000 characters. Path is relative to the workspace root.
20+
21+
**Pattern:** After exploring the tree with `list_workspace_files`, read only the files you actually need. Cite the path you read in your reply.
22+
23+
## Sandbox rules
24+
- All paths are relative to the workspace root. Never use `..` or absolute paths.
25+
- The tools enforce the boundary; path-escape attempts are rejected.
Lines changed: 46 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,46 @@
1+
# Harness Actions
2+
3+
Client-side tools that mutate the BLXCode workbench window. After each call you receive a `role:"tool"` reply describing the result.
4+
5+
## Workspace & terminal management
6+
7+
### `harness.create_workspace { title?, cwd?, terminalCount?, agentSlugs? }`
8+
Creates and selects a new workspace in the UI.
9+
- `terminalCount` — 1–16 terminal slots
10+
- `agentSlugs` — optional per-slot array like `["claude", "claude"]`
11+
- `cwd` — omit to use the active workspace cwd or the configured harness root
12+
13+
### `harness.open_terminal { count?, agentSlug?, agentSlugs? }`
14+
Opens one or more terminal slots in the **active** workspace.
15+
- **Default:** call with no arguments `{}` for a single plain shell.
16+
- `count` — open multiple at once (max 16). Do NOT call in a loop.
17+
- `agentSlug` — apply the same CLI agent to every new slot
18+
- `agentSlugs` — per-slot array (length must equal `count`)
19+
- Only pass agent slugs when the user explicitly names one of: `claude`, `codex`, `gemini`, `opencode`, `cursor`
20+
21+
Example — open 3 Codex terminals: `{ "count": 3, "agentSlug": "codex" }`
22+
23+
## Inspecting & driving other CLI agents
24+
25+
### `harness.list_terminals`
26+
Returns `[{ slotId, agentSlug, running }]` for the active workspace. **Always call this first** when you intend to interact with another agent.
27+
28+
### `harness.send_terminal_keys { slotId? | agentSlug?, text, submit? }`
29+
Types `text` into a slot's PTY.
30+
- `submit: true` — appends a newline so the command/prompt is executed
31+
- Address by `slotId` when possible (unique); `agentSlug` picks the first matching slot
32+
- Use to ask a running CLI agent for status, delegate work, or drive plain shells
33+
34+
### `harness.send_agent_context { slotId? | agentSlug?, instruction?, includeKinds?, submit? }`
35+
Hands off BLXCode-attached context to a terminal CLI agent. Prefer this over raw `send_terminal_keys` when the other agent needs workspace context (memory/learnings, plans, tasks, images).
36+
- Image bytes are exported to `<workspace>/.blxcode/agent-context/images/`; base64 is never written into the prompt
37+
- `includeKinds` defaults to all four: `["memory", "plans", "tasks", "images"]`
38+
- Call `harness.list_terminals` first when multiple slots could match
39+
40+
### `harness.read_terminal_output { slotId? | agentSlug?, maxBytes? }`
41+
Non-destructively reads the last bytes from a slot's rolling tail buffer (cap 64 KiB). Use after `send_terminal_keys` to observe the response. Output contains ANSI escapes — focus on the readable text.
42+
43+
## Delegation pattern
44+
1. `harness.list_terminals` — find the target slot
45+
2. `harness.send_agent_context` or `harness.send_terminal_keys` — send the prompt
46+
3. Wait briefly, then `harness.read_terminal_output` — capture the reply (repeat for long-running tasks)
Lines changed: 76 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,76 @@
1+
# Workspace Memory
2+
3+
Persist and retrieve notes and learnings scoped to the active workspace.
4+
5+
## Storage roots
6+
- `.agents/memory/` — general notes (category `memory` + user-created subcategories)
7+
- `.agents/learnings/` — durable repo learnings (category `learnings`, API path `learnings/<file>.md`)
8+
- Subdirectories of `.agents/memory/` become their own categories (e.g. `projects/setup.md` → category `projects`).
9+
10+
## Note CRUD (server-side)
11+
12+
### `memory_list`
13+
Lists every note (up to 200) with size and modified time. Cheap overview call.
14+
15+
### `memory_read { path }`
16+
Reads one note. `path` is the API path ending in `.md` (e.g. `projects/setup.md` or `learnings/api-notes.md`).
17+
18+
### `memory_search { query }`
19+
Full-text search; returns up to 50 hits with paths and snippets. Use this before `memory_list` for targeted lookups.
20+
21+
### `memory_create { path, content? }`
22+
Creates a **new** note (32 KiB max). Path must end in `.md` and must not already exist.
23+
24+
### `memory_write { path, content }`
25+
Overwrites an existing note. Prefer this over `memory_create` to avoid near-duplicates.
26+
27+
### `memory_delete { path }`
28+
Deletes one note permanently.
29+
30+
### `memory_rename { oldPath, newPath, rewriteLinks? }`
31+
Renames or moves a note. Cross-root (`memory``learnings`) is rejected. `rewriteLinks` defaults to `true` (updates `[[wikilinks]]` in other notes).
32+
33+
### `memory_graph`
34+
Returns graph nodes/edges/tags clustered by category. Use for a high-level overview of the knowledge base.
35+
36+
### `memory_backlinks { path }`
37+
Returns notes that link to the given path via `[[wikilinks]]`.
38+
39+
### `memory_list_categories`
40+
Lists every category present in the workspace (built-in + user-created folders).
41+
42+
### `memory_create_category { name }`
43+
Creates an empty category (subfolder under `.agents/memory/`). Use sparingly — prefer creating the first note with a `<category>/<note>.md` path instead.
44+
45+
## Category UI & agent context (client-side)
46+
47+
### `memory_category_list`
48+
Returns label/color/sidebar/graph flags for every visible category.
49+
50+
### `memory_category_update { category, label?, color?, showInSidebar?, showInGraph? }`
51+
Updates display settings for a category. `color` as `#rrggbb`.
52+
53+
### `memory_context_list`
54+
Lists items currently attached to BLXCode Agent context.
55+
56+
### `memory_context_attach { kind, path?, label? }`
57+
Attaches a memory item. `kind` values: `memory_category`, `learning_category`, `memory_note`, `learning_note` (notes require `path`).
58+
59+
### `memory_context_detach { id }`
60+
Removes an attached context item by id.
61+
62+
### `image_context_list`
63+
Lists images attached to the active Agent context.
64+
65+
### `image_context_detach { id }`
66+
Removes an attached image by id.
67+
68+
## When to read / write
69+
70+
**Read when:** the question is about this repo's conventions, architecture, prior decisions, or pitfalls. Start with `memory_search` (focused query), then `memory_read` on the 1–3 best paths.
71+
72+
**Write when:** a durable convention, decision, API contract, migration step, or non-obvious pitfall emerged from the work.
73+
74+
**Skip when:** trivial questions, single-line fixes, or topics answered entirely from the current message and one file read.
75+
76+
Use `[[wikilinks]]` when linking related notes. Keep notes concise and free of secrets.
Lines changed: 60 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,60 @@
1+
# Workspace Plans
2+
3+
Durable Markdown files that capture a multi-step implementation strategy. Lives at `<workspace>/.agents/plans/`. Plans are the long-lived counterpart to the task list and are checked into git.
4+
5+
`PLANS.md` is the protected index — never delete or rename it.
6+
7+
## Tools (server-side)
8+
9+
### `plan_list`
10+
Overview of every plan with task summary counts. Call before guessing about existing plans.
11+
12+
### `plan_read { path }`
13+
Reads one plan's Markdown body. `path` is relative to `<workspace>/.agents/plans/` (e.g. `my-plan.md`).
14+
15+
### `plan_create { path, content? }`
16+
Creates a new plan. Path must end in `.md` and must not exist. Optionally seed with initial content.
17+
18+
### `plan_write { path, content }`
19+
Overwrites an existing plan. Use `plan_sync_from_tasks` instead when you only need to update the `## Tasks` section.
20+
21+
### `plan_delete { path }`
22+
Deletes a plan (cannot delete `PLANS.md`).
23+
24+
### `plan_rename { oldPath, newPath }`
25+
Renames within `.agents/plans/`. Task records pointing at the old path are rewritten automatically.
26+
27+
### `plan_load { path }`
28+
Syncs the plan's `## Tasks` (or `## Todos`) section into the task manager. Also attaches the plan to BLXCode Agent shared context (`PlanFile`) and sets `activePlanPath` on the snapshot.
29+
30+
**Call `plan_load` whenever you open or start working from a plan** — including plans you just created. Without it, plan tasks are not in the task manager.
31+
32+
### `plan_sync_from_tasks { path }`
33+
Writes the current plan-linked task state back into the plan Markdown. Use after reordering or batch-status-changing plan tasks via `task_*` tools.
34+
35+
## Agent context (client-side)
36+
37+
### `plan_context_list`
38+
Lists plans attached to BLXCode Agent shared context.
39+
40+
### `plan_context_attach { path }`
41+
Attaches a plan (makes it visible to terminal CLI agents via `harness.send_agent_context`).
42+
43+
### `plan_context_detach { id }`
44+
Detaches a plan from context by id.
45+
46+
## Task line syntax in `## Tasks`
47+
48+
```
49+
- [ ] `task-id` - Pending task title
50+
- [>] `task-id` - In-progress task title
51+
- [!] `task-id` - Blocked task title
52+
- [x] `task-id` - Completed task title
53+
- [-] `task-id` - Cancelled task title
54+
```
55+
56+
## Key semantics
57+
- `plan_*` manage durable plan files; `task_*` manage live execution state. Both coexist for one plan.
58+
- `task_update` on plan-linked tasks writes status back into the plan Markdown automatically.
59+
- Plan files and the task store survive workspace reload, harness restart, and OS exit.
60+
- Reference plans from `PLANS.md` with Markdown links.
Lines changed: 61 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,61 @@
1+
# Rules & Skills
2+
3+
Two customisation layers stored under `<workspace>/.agents/`, each with an `index.json` manifest.
4+
5+
## Rules vs Skills
6+
7+
| | Rules | Skills |
8+
|---|---|---|
9+
| Storage | `.agents/rules/rule-*.md` | `.agents/skills/<name>/SKILL.md` |
10+
| Authority | **Binding** — override your defaults | **Advisory** — apply when relevant |
11+
| Conflict | Rules win over skills ||
12+
| Naming | `rule-<stem>.md` | `[a-z0-9][a-z0-9-_]{0,40}` |
13+
14+
Only entries with `enabled: true` count. Disabled entries do not exist — never apply, cite, or lobby the user to re-enable them.
15+
16+
## Rules tools (server-side)
17+
18+
### `rules_list`
19+
Returns JSON of every rule with `enabled`, `title`, `summary`, `updatedAt`. Filter by `enabled == true` before applying.
20+
21+
### `rules_read { name }`
22+
Reads the Markdown body of one rule. Read every active rule whose title/summary is plausibly relevant before starting work.
23+
24+
### `rules_write { name, content }`
25+
Creates or overwrites a rule. Name must start with `rule-` and end with `.md`. Only on explicit user request.
26+
27+
### `rules_set_enabled { name, enabled }`
28+
Toggles the manifest flag. Only on explicit user request.
29+
30+
### `rules_remove { name }`
31+
Deletes a rule and cleans its index entry. Confirm with the user before removing.
32+
33+
## Skills tools (server-side)
34+
35+
### `skills_list`
36+
Returns JSON of every skill (core and user) with `enabled`, `title`, `summary`, `source`, `updatedAt`.
37+
38+
### `skills_read { name }`
39+
Reads `SKILL.md` for a user-installed skill, or the embedded content for a core harness skill. Use this to get full guidance for a tool group.
40+
41+
**Core skill names:** `memory`, `plans`, `tasks`, `rules-skills`, `file-access`, `harness`
42+
43+
### `skills_write { name, content }`
44+
Creates or overwrites a skill's `SKILL.md`. Source is set to `agent-created`. Only on explicit user request.
45+
46+
### `skills_set_enabled { name, enabled }`
47+
Toggles the enabled flag. Works for both core and user skills.
48+
49+
### `skills_remove { name }`
50+
Removes a user-installed skill directory and its index entry. Core skills cannot be removed.
51+
52+
### `skills_install { name, source }`
53+
Installs a new skill. `source.kind` is one of:
54+
- `git``url` (required) + `ref` (optional branch/tag)
55+
- `npm``package` (required) + `version` (optional)
56+
- `local``path` (workspace-relative)
57+
58+
The source must contain `SKILL.md` at the top level; otherwise the install is rejected and rolled back. Only call when the user explicitly asks to install something.
59+
60+
## Index files
61+
`.agents/rules/index.json` and `.agents/skills/index.json` are managed by the harness. Do not hand-edit them — use the `*_set_enabled` / `*_remove` / `skills_install` tools instead.

0 commit comments

Comments
 (0)