From f1b62c65f970a991015e219604691225344edce8 Mon Sep 17 00:00:00 2001 From: Georg Bauer Date: Sun, 30 Aug 2026 13:19:51 +0200 Subject: [PATCH] Update agent feature documentation --- README.md | 24 ++++++++++++++--- docs/USER_GUIDE.md | 65 +++++++++++++++++++++++++++++++++++++++++++++- 2 files changed, 85 insertions(+), 4 deletions(-) diff --git a/README.md b/README.md index 706aa04..8fc6432 100644 --- a/README.md +++ b/README.md @@ -15,7 +15,19 @@ the Metal kernels and small native integration layers are adapted from - **Local coding tools.** The agent can read, search, list, write, and edit project files; run and monitor asynchronous shell commands; search Google; and visit rendered web pages. File access is confined to the project, output - is bounded, and risky shell or visible-browser actions require approval. + is bounded, risky shell or visible-browser actions require approval, and + tool calls are validated against the same typed schemas shown to the model. +- **Fresh-agent Ralph loops.** For a bounded coding objective, the agent can + run foreground rounds in fresh model contexts while preserving workspace + changes between rounds. A validated structured report is the only + conversational handoff to the next worker; the loop stops on reported + completion, a blocker, failure, cancellation, or its configurable round + limit. +- **Workspace instructions and reusable skills.** A global `AGENTS.md` plus + project and nested `AGENTS.md`/`AGENTS.local.md` files provide hierarchical + guidance that is reconciled as the agent enters or changes a workspace area. + Standard `~/.agents/skills//SKILL.md` packages are advertised by + metadata and loaded in full only when a task matches. - **Project-backed Dev Brain.** An optional managed Obsidian vault provides source-verified wiki pages, ranked search, and on-demand skills. Each session receives the verified skill names, descriptions, and paths, then loads full @@ -93,18 +105,24 @@ make bundle open target/release/DS4Server.app ``` +Tagged versions are also published as Apple Silicon DMG files on the +[repository releases page](https://git.rfc1437.de/hugo/DS4Server/releases). + ## Application data ```text ~/Library/Application Support/de.rfc1437.ds4server/data.sqlite3 ~/Library/Application Support/de.rfc1437.ds4server/config.yaml +~/Library/Application Support/de.rfc1437.ds4server/AGENTS.md ~/Library/Application Support/de.rfc1437.ds4server/models/ ~/Library/Application Support/de.rfc1437.ds4server/kv-cache/ ``` Deleting a project or session removes DS4Server metadata and its associated -checkpoint; it never deletes the referenced project directory. See -[PLAN.md](PLAN.md) for the remaining implementation work. +checkpoint; it never deletes the referenced project directory. Standard agent +skills live separately under `~/.agents/skills/`. See the +[issue tracker](https://git.rfc1437.de/hugo/DS4Server/issues) for remaining +implementation work. The adapted Metal and browser sources retain their upstream notices in [`native/metal/LICENSE`](native/metal/LICENSE) and diff --git a/docs/USER_GUIDE.md b/docs/USER_GUIDE.md index 3dcf71a..d82cb28 100644 --- a/docs/USER_GUIDE.md +++ b/docs/USER_GUIDE.md @@ -92,7 +92,70 @@ application-control, and credential risks still require approval. Tool calls and results appear in the transcript. Use their copy actions for the complete, untruncated text; large outputs can also be opened from their saved -file. +file. Calls are checked against typed schemas before execution, so unknown +tools, missing or extra fields, invalid values, and malformed tool syntax are +returned to the agent as structured errors instead of being executed. + +## Ralph loops + +For a bounded task that benefits from repeated autonomous passes, ask the agent +to use a Ralph loop, for example: “Use a Ralph loop with at most 12 rounds to +fix and verify this parser.” This is an agent tool, not a slash command or a +separate view. The normal default is 8 rounds and the allowed range is 1–64. + +Ralph runs in the foreground. Each round receives the same immutable objective +in a fresh model context, inspects the current project as its source of truth, +and ends with one structured report. File changes remain on disk between +rounds, but earlier conversation does not: only the previous validated report, +applicable workspace instructions, and available skills are handed to the next +worker. This limits accumulated context while allowing the next round to +continue, verify, or repair the work. + +The current chat's model settings and permission mode still apply. Risky shell +commands and visible browser actions can therefore pause for the usual +approval. **Stop** cancels the loop and its active work. Ralph also stops when a +worker reports completion or a blocker, a child round fails, or the round limit +is reached. Completion is a worker report rather than independent +certification; review its evidence or ask the parent agent to verify it when +that distinction matters. Ralph workers cannot start nested Ralph loops. + +## Workspace instructions and standard skills + +DS4Server applies workspace guidance from these locations: + +- `~/Library/Application Support/de.rfc1437.ds4server/AGENTS.md` applies to all + projects. +- `AGENTS.md` in the project root applies to that project. +- `AGENTS.md` and `AGENTS.local.md` in nested directories apply after the agent + successfully reads, writes, or edits a file in that part of the project. + +Instructions are ordered from broad to specific. A deeper file takes +precedence over broader guidance, and `AGENTS.local.md` is the final overlay for +its directory. DS4Server records additions, changes, and removals during an +ongoing chat and restores the applicable instruction set after context +compaction. Files that cannot be read safely produce a context notice; if the +file was already tracked, its last readable version remains in effect. +Workspace instructions cannot override system, developer, or direct user +instructions. + +Reusable standard skills are discovered from +`~/.agents/skills//SKILL.md`. Each `SKILL.md` starts with YAML frontmatter: + +```yaml +--- +name: review-release +description: Review a release against this project's checklist. +--- +``` + +The directory name must match `name`; names use lowercase letters, digits, and +single hyphens. DS4Server initially gives the agent only each valid skill's +name, description, and path. When a task matches, the agent reads the complete +file and any needed resources from that skill directory. Standard skill files +are readable but not writable through agent tools. Install only skills you +trust, place them manually before starting a chat, and start a new chat after +changing the installed set. There is currently no built-in skill installer or +extension marketplace. ## Dev Brain