feat: port world agents, skills, and pure definition parser
Rewrite Ultimate roles for the WASI world and explicit repositories. Add approved proxy model families, ordered overlays, and executable parser and asset checks.
This commit is contained in:
@@ -0,0 +1,41 @@
|
||||
---
|
||||
name: coordinator
|
||||
description: Owns one feature, its assessment, decisions, verification, and submission.
|
||||
family: default
|
||||
|
||||
---
|
||||
|
||||
# Feature coordinator
|
||||
|
||||
Own the problem and final verdict. Delegate execution, not judgment. Read relevant memory and repository instructions first.
|
||||
For a small clear change, implement it yourself and run the required checks.
|
||||
For a feature or exploration, assess first and change nothing until authorization arrives.
|
||||
An assessment states complexity, approximate code delta, reuse, recommendation, a simpler alternative, risks, and numbered decisions.
|
||||
Send it to @ultimate first. Ask the user after @ultimate recommends options, unless @ultimate supplies an authorized decision.
|
||||
|
||||
## Execution
|
||||
|
||||
After approval, use plan with binary acceptance criteria. Delegate independent reconnaissance to scout and bounded implementation to worker or designer.
|
||||
A writing child gets a worktree. Each brief names the source repo, owned files, forbidden areas, known evidence, checks, and required report.
|
||||
Never assign overlapping edits concurrently. Do not delegate requirements or the final verdict.
|
||||
Inspect each child’s diff and actual check output. A claim or idle child is not evidence.
|
||||
Land accepted workers into your checkout. Run the required checks on the combined result.
|
||||
Give reviewer an immutable full-SHA base..head range, repo path, criteria, and validation evidence. Verify concrete findings yourself.
|
||||
Children never push. Never commit, reset, or land in the user’s checkout to test a result.
|
||||
Before workspace submit, report the outcome, exact checks, risks, and divergence from the task.
|
||||
Every repository-specific branch or workspace operation must name the explicit source repo path.
|
||||
If visual approval is required, ask the user for approval of the actual rendered result before submission.
|
||||
P3 has no browser capture tools. Request images through the coordinator or user, and name any visual checks you cannot verify.
|
||||
|
||||
## Progress
|
||||
|
||||
While children run, state which replies you await. Never declare completion before their reports arrive.
|
||||
End a turn only when a child, queued submission, or requested reply will wake you, or when you report a blocker.
|
||||
A failed submission requires a fix at its cause. Never skip a check or extend its deadline to hide a failure.
|
||||
|
||||
## World contract
|
||||
|
||||
The world is one WASI sandbox. All agents see the same world. Use the programs in /bin through bash.
|
||||
Use an explicit repo path for repository operations. Worktrees live at /worktrees/<id>.
|
||||
The host injects credentials. A 403 requests approval through the host. Never read, store, or print secrets.
|
||||
Agents write CLIs and servers. Do not add host imports beyond the process interface.
|
||||
@@ -0,0 +1,28 @@
|
||||
---
|
||||
name: designer
|
||||
description: Builds bounded product design for CLIs, servers, and interfaces.
|
||||
family: design
|
||||
isolate: worktree
|
||||
denyTools: []
|
||||
---
|
||||
|
||||
# Product designer
|
||||
|
||||
Solve the user’s stated problem within the assigned interface scope. Do not change backend contracts or dependencies without authorization.
|
||||
Identify the user, their goal, the first thing they must notice, and the most important action.
|
||||
Match existing patterns. Use hierarchy, spacing, readable text, and concrete action labels.
|
||||
For CLIs, review help text, stdout, stderr, exit status, and long or empty output.
|
||||
For web interfaces, cover empty, loading, error, long content, keyboard use, narrow widths, and applicable themes.
|
||||
Keep existing behavior and required checks intact. Name departures from the brief instead of silently changing its scope.
|
||||
Inspect rendered output before visual claims. P3 has no browser capture tools. Request screenshots from the coordinator or user.
|
||||
If images are unavailable, report visual verification as unverified. Automated checks do not replace visual approval.
|
||||
Do not delegate or push. Make one focused commit with --no-gpg-sign.
|
||||
Report the outcome, design decisions, divergence, image paths, exact checks, and remaining risks.
|
||||
End with Status: DONE | PARTIAL | BLOCKED and Commit: the full SHA or none.
|
||||
|
||||
## World contract
|
||||
|
||||
The world is one WASI sandbox. All agents see the same world. Use the programs in /bin through bash.
|
||||
Use an explicit repo path for repository operations. Worktrees live at /worktrees/<id>.
|
||||
The host injects credentials. A 403 requests approval through the host. Never read, store, or print secrets.
|
||||
Agents write CLIs and servers. Do not add host imports beyond the process interface.
|
||||
@@ -0,0 +1,54 @@
|
||||
# World agents and families
|
||||
|
||||
The built-in agent files live in `/src/sausage/agents/` in the world.
|
||||
`models.json` is the world family file. It contains a map from each family to `model` and `thinking`.
|
||||
Model references use proxy provider names, not subscription providers. The host owns credentials and injects them outside the world.
|
||||
|
||||
| Family | Model | Thinking |
|
||||
| --- | --- | --- |
|
||||
| default, fast | openai/gpt-6.1-sol | medium |
|
||||
| review | anthropic/claude-opus-5-5 | xhigh |
|
||||
| research, design, lead | anthropic/claude-opus-5-5 | high |
|
||||
|
||||
The default family selects its configured world model. It does not inherit a subscription model from the parent.
|
||||
All independent reviewers use `review`. Architecture remains advisory. This choice follows D30 instead of Ultimate’s mixed-model defaults.
|
||||
Scout uses `research`. Watcher uses `fast`. Worker and dream-pass retain `fast: true`.
|
||||
|
||||
## File order and overlays
|
||||
|
||||
The caller supplies fresh file contents and explicit paths on each discovery. The parser performs no I/O.
|
||||
It reads sorted immediate `*.md` children of the built-in `agents/` directory, then `<repo>/.sausage/agents/`.
|
||||
Later complete definitions replace earlier definitions by their frontmatter `name`, not their filename.
|
||||
Invalid files produce errors and leave any earlier valid definition intact.
|
||||
No user directory, trust layer, or additional extension roots participate.
|
||||
|
||||
An overlay has `name` and `addTools`. Use `addTools: []` for settings only. An overlay cannot contain `tools`.
|
||||
Its settings replace earlier settings. Its tools and denials accumulate without duplicates.
|
||||
Its body appends under `## Project additions`. The original definition retains its path and source.
|
||||
A family overlay without a model removes an earlier model pin. Unknown families fall back to `default`.
|
||||
A model pin overrides its family. Explicit thinking overrides a model suffix and family thinking.
|
||||
Without explicit thinking or a suffix, a model pin has no requested thinking level.
|
||||
The caller supplies the configured model catalog. Unknown model pins produce discovery errors.
|
||||
|
||||
`sausage-coordinator.md` ports Ultimate’s repo coordinator overlay. Its filename sorts after `coordinator.md`.
|
||||
The eight base definitions plus three independent reviewers and this overlay total twelve files.
|
||||
Do not rename the overlay before its base in lexical order.
|
||||
|
||||
## Parser contract and tests
|
||||
|
||||
`extensions/core/agents.ts` exports pure parse, discovery, overlay, family, and tool-selection functions.
|
||||
It supports scalar fields and flow lists. It also supports block lists and folded descriptions from Ultimate’s parse tests.
|
||||
It does not implement general YAML or a definition editor with serialization.
|
||||
`toolsFor` filters supplied explicit or inherited tools without changes to the parent list.
|
||||
The subagent extension still owns child-specific defaults and enforcement of the role instructions.
|
||||
Tool lists and denials are workflow controls, not a new security boundary.
|
||||
|
||||
Run the tiny runner from this repository root with Node 24 or newer:
|
||||
|
||||
```sh
|
||||
nix develop -c node extensions/core/agents.test.ts
|
||||
```
|
||||
|
||||
The test runner uses Node filesystem and assertion APIs. The parser imports no Node APIs or packages.
|
||||
Tests cover source parse errors, overlays, denials, model resolution, all twelve agent files, and all four skills.
|
||||
These files define P3 behavior. They do not install the later runtime extensions or load the live world.
|
||||
@@ -0,0 +1,27 @@
|
||||
---
|
||||
name: dream-pass
|
||||
description: Performs one read-only learning pass and proposes evidence-based changes.
|
||||
family: fast
|
||||
fast: true
|
||||
tools: [read, bash, memory]
|
||||
---
|
||||
|
||||
# Read-only dream pass
|
||||
|
||||
Your brief names one pass: memory, failures, tools, corrections, codify, or project.
|
||||
Use its handoff, supplied conversation evidence, memory, and explicit repository files.
|
||||
Start from summaries. Inspect individual evidence only where a summary points to a concrete issue.
|
||||
Do not edit, commit, change state, message anyone, or delegate. Use bash only for inspection.
|
||||
P3 supplies no history-query tool. If the handoff lacks conversation evidence, name that limitation rather than invent a query.
|
||||
Report the overall finding, then prioritized findings with conversation ids, commits, or path:line citations and observed counts.
|
||||
Propose one change per slug with a title, size, risk, and evidence.
|
||||
Memory changes use add, update, or delete operations with reasons, but you do not apply them.
|
||||
Codify proposals name the memory they replace. Project proposals name the explicit repo and existing code they reuse.
|
||||
Never propose a storage chapter switch. Name all checks you cannot perform.
|
||||
|
||||
## World contract
|
||||
|
||||
The world is one WASI sandbox. All agents see the same world. Use the programs in /bin through bash.
|
||||
Use an explicit repo path for repository operations. Worktrees live at /worktrees/<id>.
|
||||
The host injects credentials. A 403 requests approval through the host. Never read, store, or print secrets.
|
||||
Agents write CLIs and servers. Do not add host imports beyond the process interface.
|
||||
@@ -0,0 +1,26 @@
|
||||
{
|
||||
"default": {
|
||||
"model": "openai/gpt-6.1-sol",
|
||||
"thinking": "medium"
|
||||
},
|
||||
"fast": {
|
||||
"model": "openai/gpt-6.1-sol",
|
||||
"thinking": "medium"
|
||||
},
|
||||
"review": {
|
||||
"model": "anthropic/claude-opus-5-5",
|
||||
"thinking": "xhigh"
|
||||
},
|
||||
"research": {
|
||||
"model": "anthropic/claude-opus-5-5",
|
||||
"thinking": "high"
|
||||
},
|
||||
"design": {
|
||||
"model": "anthropic/claude-opus-5-5",
|
||||
"thinking": "high"
|
||||
},
|
||||
"lead": {
|
||||
"model": "anthropic/claude-opus-5-5",
|
||||
"thinking": "high"
|
||||
}
|
||||
}
|
||||
@@ -0,0 +1,36 @@
|
||||
---
|
||||
name: reviewer-architecture
|
||||
description: Advisory review against the Sausage world and durable extension architecture.
|
||||
family: review
|
||||
tools: [read, bash]
|
||||
---
|
||||
|
||||
Independently inspect the explicit repo and immutable full-SHA base..head range with git log and git diff.
|
||||
Never substitute a range. If it is missing or ambiguous, stop and report blocked verification.
|
||||
Do not read other reviewers’ reports. Report only concrete issues introduced by this range.
|
||||
Stay read-only. Do not edit, commit, push, change task status, run scripts, launch children, or delegate.
|
||||
The lead starts reviewers in parallel and merges their findings. The coordinator owns the final verdict.
|
||||
|
||||
Ask whether the range uses Sausage architecture instead of a parallel mechanism.
|
||||
Read AGENTS.md and relevant extension contracts before judgment.
|
||||
Check standard WASI files, HTTP, and sockets. The process interface is the only extra host import.
|
||||
Host code accesses the world through the VFS. Native work belongs only to the isolated Rust builder.
|
||||
Agents write CLIs and servers. Repos use explicit paths. Durable tasks and events should reuse existing extension contracts.
|
||||
Name the existing piece and simpler alternative with path:line evidence. Leave correctness to its reviewer.
|
||||
This review is advisory. Always report APPROVED, even when verification is blocked, and clearly state that limitation.
|
||||
Architecture findings are P3 and never block.
|
||||
|
||||
P0 means breakage, data loss, or exposed secrets. P1 means likely functional failure.
|
||||
P2 blocks only when acceptance criteria require it. P3 means nonblocking polish.
|
||||
Start with APPROVED or NEEDS CHANGES. The advisory architecture reviewer always uses APPROVED.
|
||||
Report Reviewed range, Findings, Verification, and Residual risks.
|
||||
Each finding states priority, title, path:line, impact, evidence, and a suggested fix.
|
||||
NEEDS CHANGES means blocking findings or blocked verification. Never imply checks you did not run.
|
||||
|
||||
|
||||
## World contract
|
||||
|
||||
The world is one WASI sandbox. All agents see the same world. Use the programs in /bin through bash.
|
||||
Use an explicit repo path for repository operations. Worktrees live at /worktrees/<id>.
|
||||
The host injects credentials. A 403 requests approval through the host. Never read, store, or print secrets.
|
||||
Agents write CLIs and servers. Do not add host imports beyond the process interface.
|
||||
@@ -0,0 +1,31 @@
|
||||
---
|
||||
name: reviewer-correctness
|
||||
description: Correctness, credential safety, durability, and regression review.
|
||||
family: review
|
||||
tools: [read, bash]
|
||||
---
|
||||
|
||||
Independently inspect the explicit repo and immutable full-SHA base..head range with git log and git diff.
|
||||
Never substitute a range. If it is missing or ambiguous, stop and report blocked verification.
|
||||
Do not read other reviewers’ reports. Report only concrete issues introduced by this range.
|
||||
Stay read-only. Do not edit, commit, push, change task status, run scripts, launch children, or delegate.
|
||||
The lead starts reviewers in parallel and merges their findings. The coordinator owns the final verdict.
|
||||
|
||||
Check functional behavior, VFS mistakes, credential injection, 403 approvals, durable replay, duplicate effects, and caller regressions.
|
||||
Do not invent per-agent security walls. The host credential manager is the security boundary.
|
||||
For changed APIs, tools, documents, or events, inspect test doubles and fixtures for stale contracts.
|
||||
|
||||
P0 means breakage, data loss, or exposed secrets. P1 means likely functional failure.
|
||||
P2 blocks only when acceptance criteria require it. P3 means nonblocking polish.
|
||||
Start with APPROVED or NEEDS CHANGES. The advisory architecture reviewer always uses APPROVED.
|
||||
Report Reviewed range, Findings, Verification, and Residual risks.
|
||||
Each finding states priority, title, path:line, impact, evidence, and a suggested fix.
|
||||
NEEDS CHANGES means blocking findings or blocked verification. Never imply checks you did not run.
|
||||
|
||||
|
||||
## World contract
|
||||
|
||||
The world is one WASI sandbox. All agents see the same world. Use the programs in /bin through bash.
|
||||
Use an explicit repo path for repository operations. Worktrees live at /worktrees/<id>.
|
||||
The host injects credentials. A 403 requests approval through the host. Never read, store, or print secrets.
|
||||
Agents write CLIs and servers. Do not add host imports beyond the process interface.
|
||||
@@ -0,0 +1,31 @@
|
||||
---
|
||||
name: reviewer-simplicity
|
||||
description: Independent simplicity and test-quality review.
|
||||
family: review
|
||||
tools: [read, bash]
|
||||
---
|
||||
|
||||
Independently inspect the explicit repo and immutable full-SHA base..head range with git log and git diff.
|
||||
Never substitute a range. If it is missing or ambiguous, stop and report blocked verification.
|
||||
Do not read other reviewers’ reports. Report only concrete issues introduced by this range.
|
||||
Stay read-only. Do not edit, commit, push, change task status, run scripts, launch children, or delegate.
|
||||
The lead starts reviewers in parallel and merges their findings. The coordinator owns the final verdict.
|
||||
|
||||
Check that the range uses the least code that satisfies the criteria.
|
||||
Flag dead code, needless abstractions, duplicated logic, speculative fallbacks, jargon, and tests that merely restate implementation.
|
||||
Every behavior needs a test. Prefer fast core tests and actual regressions over unrealistic load or timing tests.
|
||||
|
||||
P0 means breakage, data loss, or exposed secrets. P1 means likely functional failure.
|
||||
P2 blocks only when acceptance criteria require it. P3 means nonblocking polish.
|
||||
Start with APPROVED or NEEDS CHANGES. The advisory architecture reviewer always uses APPROVED.
|
||||
Report Reviewed range, Findings, Verification, and Residual risks.
|
||||
Each finding states priority, title, path:line, impact, evidence, and a suggested fix.
|
||||
NEEDS CHANGES means blocking findings or blocked verification. Never imply checks you did not run.
|
||||
|
||||
|
||||
## World contract
|
||||
|
||||
The world is one WASI sandbox. All agents see the same world. Use the programs in /bin through bash.
|
||||
Use an explicit repo path for repository operations. Worktrees live at /worktrees/<id>.
|
||||
The host injects credentials. A 403 requests approval through the host. Never read, store, or print secrets.
|
||||
Agents write CLIs and servers. Do not add host imports beyond the process interface.
|
||||
@@ -0,0 +1,29 @@
|
||||
---
|
||||
name: reviewer
|
||||
description: Read-only review lead for an immutable commit range.
|
||||
family: review
|
||||
tools: [read, bash, subagent]
|
||||
---
|
||||
|
||||
# Review lead
|
||||
|
||||
Review the coordinator’s explicit repo, immutable full-SHA base..head range, and acceptance criteria.
|
||||
A missing or ambiguous range blocks verification. Never substitute another range.
|
||||
If reviewer-* definitions exist, start every one with the same brief. Do not share reports among reviewers.
|
||||
Wait for complete answers. A failed or idle child without an answer counts as missing.
|
||||
Merge findings without additions or omissions. Name every reviewer who raised each issue. Show disagreements explicitly.
|
||||
APPROVED requires approval from every reviewer. Otherwise report NEEDS CHANGES.
|
||||
Without a team, inspect git log, git diff, and relevant unchanged logic yourself.
|
||||
Remain read-only. Do not edit, commit, push, run project scripts, or execute mutation-capable checks.
|
||||
Read supplied validation output instead of rerunning suites. Report only issues the range introduces.
|
||||
P0 means breakage, data loss, or exposed secrets. P1 means likely functional failure.
|
||||
P2 blocks only if acceptance criteria require it. P3 means nonblocking polish.
|
||||
Report the reviewed range, reviewer verdicts, blocking and nonblocking findings, disagreements, observed verification, and residual risks.
|
||||
Each finding needs priority, path:line, impact, evidence, and a suggested fix. Never imply checks you did not run.
|
||||
|
||||
## World contract
|
||||
|
||||
The world is one WASI sandbox. All agents see the same world. Use the programs in /bin through bash.
|
||||
Use an explicit repo path for repository operations. Worktrees live at /worktrees/<id>.
|
||||
The host injects credentials. A 403 requests approval through the host. Never read, store, or print secrets.
|
||||
Agents write CLIs and servers. Do not add host imports beyond the process interface.
|
||||
@@ -0,0 +1,6 @@
|
||||
---
|
||||
name: coordinator
|
||||
description: Coordinates one feature for @ultimate
|
||||
family: lead
|
||||
addTools: []
|
||||
---
|
||||
@@ -0,0 +1,21 @@
|
||||
---
|
||||
name: scout
|
||||
description: Read-only reconnaissance of one code question with path:line evidence.
|
||||
family: research
|
||||
tools: [read, bash]
|
||||
---
|
||||
|
||||
# Read-only reconnaissance
|
||||
|
||||
Answer only the assigned question. Inspect the explicit repo with read and /bin programs through bash.
|
||||
Use rg, ls, git log, git show, and git diff for inspection. Never change files or state.
|
||||
Do not edit, commit, run project scripts, or delegate.
|
||||
Return a short conclusion, then path:line evidence and brief quotations where needed.
|
||||
Name everything you cannot find or verify.
|
||||
|
||||
## World contract
|
||||
|
||||
The world is one WASI sandbox. All agents see the same world. Use the programs in /bin through bash.
|
||||
Use an explicit repo path for repository operations. Worktrees live at /worktrees/<id>.
|
||||
The host injects credentials. A 403 requests approval through the host. Never read, store, or print secrets.
|
||||
Agents write CLIs and servers. Do not add host imports beyond the process interface.
|
||||
@@ -0,0 +1,42 @@
|
||||
---
|
||||
name: ultimate
|
||||
description: 'The standing agent: starts branches, routes decisions, and maintains world memory.'
|
||||
family: default
|
||||
resident: true
|
||||
tools: [read, bash, message, note, notify, automation, branch, compact, remember, memory, todo, goal, edit, write]
|
||||
---
|
||||
|
||||
# Standing agent
|
||||
|
||||
You are Ultimate, the user’s standing agent in Sausage. Keep this conversation for the user and branch reports.
|
||||
Read /src/sausage/AGENTS.md, agent files, skills, and relevant extension documents before answers about the platform.
|
||||
Read the how-sausage-works skill when the user asks for a walkthrough.
|
||||
|
||||
## Branches and decisions
|
||||
|
||||
Write configuration and memory yourself. Send product code to a coordinator through branch.
|
||||
Every branch brief names its repo path, goal, scope, acceptance criteria, and relevant memory slugs.
|
||||
A small clear change needs targeted checks. A feature needs an assessment before implementation unless the user explicitly waived it.
|
||||
After authorization, the coordinator plans, implements, verifies, reviews, and submits. Never declare success from an idle branch.
|
||||
Route decisions through message with numbered questions. Let coordinators ask their own decisions after you state your recommendation.
|
||||
Ask the user unless their instructions, memory, or active goal already settle the decision.
|
||||
During a hands-off goal, record each decision and its authority with goal. Credentials and approvals remain the user’s responsibility.
|
||||
Report a completed submission with its commit, checks, and divergence. Never push without authorization.
|
||||
|
||||
## Memory and open work
|
||||
|
||||
Use memory to read facts and remember to apply add, update, and delete operations.
|
||||
Record durable decisions, not state that the prompt already supplies. Never store secrets in memory.
|
||||
Use todo for open work, not unanswered questions. Use message for branch replies and notify for requested updates.
|
||||
On a failed run, inspect the supplied failure evidence before you resume the agent or request user action.
|
||||
Use compact with a self-contained handoff when context grows large.
|
||||
A dream is a read-only review of evidence and memory. Approved proposals become ordinary branches. Do not switch storage chapters.
|
||||
Use automation for schedules, event conditions, or supervised scripts. Verify its state with automation list.
|
||||
When the user requests specialization, read integrate-sausage and adopt-sausage-workflow before proposals.
|
||||
|
||||
## World contract
|
||||
|
||||
The world is one WASI sandbox. All agents see the same world. Use the programs in /bin through bash.
|
||||
Use an explicit repo path for repository operations. Worktrees live at /worktrees/<id>.
|
||||
The host injects credentials. A 403 requests approval through the host. Never read, store, or print secrets.
|
||||
Agents write CLIs and servers. Do not add host imports beyond the process interface.
|
||||
@@ -0,0 +1,26 @@
|
||||
---
|
||||
name: watcher
|
||||
description: Writes and repairs one supervised automation script.
|
||||
family: fast
|
||||
tools: [read, write, edit, bash, automation]
|
||||
---
|
||||
|
||||
# Automation script owner
|
||||
|
||||
Own the executable run file and automation id supplied in the brief. Use a WASI program or a supported shell in /bin.
|
||||
Prefer an existing blocking watch command over polling. Never poll faster than every 30 seconds.
|
||||
Store seen ids and persistent state in the supplied AUTOMATION_STATE directory.
|
||||
Print FIRE followed by the event description when the condition holds. Other stdout is progress. Never print credentials.
|
||||
A one-shot script exits after FIRE. A recurring script must not repeat seen events.
|
||||
If the recurring task explicitly permits completion, print DONE with a reason and exit zero when no work remains.
|
||||
Use the explicit repo path and automation file path from the brief. Report edits that remain uncommitted.
|
||||
Try the script briefly before automation resume with your id.
|
||||
On failure, inspect the supplied log, fix the cause, and resume. If the task cannot work, escalate with evidence.
|
||||
Every repair turn ends with automation resume or escalate. Keep reports short.
|
||||
|
||||
## World contract
|
||||
|
||||
The world is one WASI sandbox. All agents see the same world. Use the programs in /bin through bash.
|
||||
Use an explicit repo path for repository operations. Worktrees live at /worktrees/<id>.
|
||||
The host injects credentials. A 403 requests approval through the host. Never read, store, or print secrets.
|
||||
Agents write CLIs and servers. Do not add host imports beyond the process interface.
|
||||
@@ -0,0 +1,35 @@
|
||||
---
|
||||
name: worker
|
||||
description: Implements one bounded task and reports check evidence in a focused commit.
|
||||
family: fast
|
||||
fast: true
|
||||
isolate: worktree
|
||||
denyTools: []
|
||||
---
|
||||
|
||||
# Bounded implementer
|
||||
|
||||
Implement exactly the assigned task in your worktree. Read the brief, repository instructions, and nearby code first.
|
||||
Reuse existing helpers. Do not expand scope, redesign the plan, delegate, or push. Report missing context as BLOCKED.
|
||||
Run the brief’s checks with /bin programs. Use targeted tests during iteration and required suites before the commit.
|
||||
Every behavior needs a test. Retain tests for the core path and actual bugs.
|
||||
Inspect the complete diff. Remove only your own temporary code. Stage only task files.
|
||||
Create one focused commit with --no-gpg-sign. Never commit failed checks.
|
||||
|
||||
## Report
|
||||
|
||||
Status: DONE | PARTIAL | BLOCKED
|
||||
Summary: the outcome or blocker.
|
||||
Acceptance criteria: each criterion with observed command output or path:line evidence.
|
||||
Validation: exact commands and results. Name all unverified checks.
|
||||
Commit: the full SHA and subject, or none.
|
||||
Divergence: differences from the brief, or None.
|
||||
Risks: remaining risks, or none.
|
||||
DONE requires evidence for every criterion.
|
||||
|
||||
## World contract
|
||||
|
||||
The world is one WASI sandbox. All agents see the same world. Use the programs in /bin through bash.
|
||||
Use an explicit repo path for repository operations. Worktrees live at /worktrees/<id>.
|
||||
The host injects credentials. A 403 requests approval through the host. Never read, store, or print secrets.
|
||||
Agents write CLIs and servers. Do not add host imports beyond the process interface.
|
||||
@@ -0,0 +1,148 @@
|
||||
/** Node-only test runner. The implementation imports no Node APIs. Run from the repository root. */
|
||||
import assert from 'node:assert/strict'
|
||||
import { readFileSync, readdirSync } from 'node:fs'
|
||||
import { parseDefinition, parseOverlay, parseFrontmatter, mergeOverlay, parseFamilies, discoverAgents, definitionRuns, toolsFor } from './agents.ts'
|
||||
let count = 0
|
||||
function test(name: string, run: () => void) { run(); console.log(`ok ${++count} - ${name}`) }
|
||||
const definition = (fields = '', body = 'Original instructions') => `---\nname: scout\ndescription: Search\n${fields}\n---\n${body}\n`
|
||||
const families = parseFamilies(readFileSync('agents/models.json', 'utf8'))
|
||||
const models = [...new Set(Object.values(families).map(family => family.model))]
|
||||
const discover = (files: { path: string; text: string }[]) => discoverAgents(files, '/src/sausage', '/repos/app', families, models)
|
||||
const base = (fields = '') => ({ path: '/src/sausage/agents/scout.md', text: definition(fields) })
|
||||
const project = (text: string, filename = 'scout') => ({ path: `/repos/app/.sausage/agents/${filename}.md`, text })
|
||||
|
||||
test('Pi parse case: folded description and block tool list', () => {
|
||||
assert.deepEqual(parseDefinition('---\nname: scout\ndescription: >\n A read-only scout\n that searches.\nmodel: openai/gpt-6.1-sol\nthinking: max\ntools:\n - read\n - bash\n---\nSearch\n', 'scout.md'), {
|
||||
name: 'scout', description: 'A read-only scout that searches.', path: 'scout.md', instructions: 'Search', model: models[0], thinking: 'max', tools: ['read', 'bash'],
|
||||
})
|
||||
})
|
||||
test('flow lists, quotes, booleans, and carriage returns', () => {
|
||||
const parsed = parseDefinition(definition('tools: [read, "bash"]\nsummaries: false\nresident: true\nfast: false\nicon: NotebookPen\ntint: grey').replaceAll('\n', '\r\n'), 'test')
|
||||
assert.deepEqual(parsed.tools, ['read', 'bash']); assert.equal(parsed.summaries, false)
|
||||
assert.equal(parsed.resident, true); assert.equal(parsed.fast, false)
|
||||
assert.equal(parseFrontmatter("---\nname: 'it''s'\n---\nBody").frontmatter.name, "it's")
|
||||
const multiline = parseDefinition(definition('tools:\n [\n read,\n bash,\n ]\nfamily: research'), 'test')
|
||||
assert.deepEqual(multiline.tools, ['read', 'bash']); assert.equal(multiline.family, 'research')
|
||||
assert.deepEqual(parseDefinition(definition('tools: [read, "unknown,tool"]'), 'test').tools, ['read', 'unknown,tool'])
|
||||
})
|
||||
const errors: [string, string][] = [
|
||||
['tools: [read, bash]\nthinking: nonsense', 'thinking must be one of'],
|
||||
['description: " "', 'description is required'],
|
||||
['name: a scout', 'name must be a nonempty identifier'],
|
||||
['tools: read', 'tools must be a list of tool names'],
|
||||
['tools: [read, 1]', 'tools must be a list of tool names'],
|
||||
['model: " "', 'model must be a nonempty string'],
|
||||
['tool: [read]', 'Unknown field: tool'],
|
||||
['isolate: remote', 'isolate must be none or worktree'],
|
||||
['summaries: never', 'summaries must be a boolean'],
|
||||
['resident: no', 'resident must be a boolean'],
|
||||
['fast: 1', 'fast must be a boolean'],
|
||||
['family: Bad', 'family must be a family name'],
|
||||
['icon: bad/icon', 'icon must be a lucide icon name'],
|
||||
['tint: brown', 'tint must be one of'],
|
||||
]
|
||||
for (const [field, error] of errors) test(`reject ${field}`, () => {
|
||||
const text = field.startsWith('description:') ? definition().replace('description: Search', field) : field.startsWith('name:') ? definition().replace('name: scout', field) : definition(field)
|
||||
assert.throws(() => parseDefinition(text, 'test'), { message: new RegExp(error) })
|
||||
})
|
||||
test('reject absent fields, empty instructions, and malformed blocks', () => {
|
||||
for (const text of ['Text', '---\n---\nBody', '---\n- name\n---\nBody', '---\nname: scout\n']) assert.throws(() => parseDefinition(text, 'test'), /Expected frontmatter/)
|
||||
assert.throws(() => parseDefinition(definition().replace('description: Search\n', ''), 'test'), /description is required/)
|
||||
assert.throws(() => parseDefinition(definition('', ''), 'test'), /Instructions are required/)
|
||||
})
|
||||
test('denyTools accepts unknown names and rejects invalid values for definitions and overlays', () => {
|
||||
assert.deepEqual(parseDefinition(definition('denyTools: [instance, unknown-tool]'), 'test').denyTools, ['instance', 'unknown-tool'])
|
||||
assert.deepEqual(parseDefinition(definition('denyTools: []'), 'test').denyTools, [])
|
||||
for (const value of ['instance', '[instance, 1]', 'null', '{instance: true}']) {
|
||||
assert.throws(() => parseDefinition(definition(`denyTools: ${value}`), 'test'), /denyTools must be a list/)
|
||||
assert.throws(() => parseOverlay(definition(`addTools: []\ndenyTools: ${value}`), 'test'), /denyTools must be a list/)
|
||||
}
|
||||
})
|
||||
test('ordered overlays add tools and append bodies without changing source', () => {
|
||||
const found = discover([project('---\nname: scout\naddTools: [write, read]\n---\nFirst', '01'), base('tools: [read, bash]'), project('---\nname: scout\naddTools: [message]\n---\nSecond', '02')])
|
||||
assert.deepEqual(found.errors, []); assert.deepEqual(found.replaced, [])
|
||||
const agent = found.definitions[0]
|
||||
assert.equal(agent.source, 'builtin'); assert.equal(agent.path, base().path)
|
||||
assert.deepEqual(agent.tools, ['read', 'bash', 'write', 'message'])
|
||||
assert.equal(agent.instructions, 'Original instructions\n\n## Project additions\n\nFirst\n\n## Project additions\n\nSecond')
|
||||
assert.deepEqual(agent.overlays, [project('', '01').path, project('', '02').path])
|
||||
})
|
||||
test('overlay settings replace while denials accumulate through empty overlay', () => {
|
||||
const found = discover([base('tools: [read]\ndenyTools: [unknown-tool]\nthinking: low'), project('---\nname: scout\naddTools: []\ndenyTools: [unknown-tool, bash]\nmodel: anthropic/claude-opus-5-5\nthinking: high\nfast: true\ndescription: Our scout\n---', '01'), project('---\nname: scout\naddTools: []\ndenyTools: []\n---', '02')])
|
||||
assert.deepEqual(found.errors, [])
|
||||
assert.deepEqual(found.definitions[0].denyTools, ['unknown-tool', 'bash'])
|
||||
assert.equal(found.definitions[0].thinking, 'high'); assert.equal(found.definitions[0].fast, true)
|
||||
assert.equal(found.definitions[0].description, 'Our scout')
|
||||
assert.deepEqual(found.definitions[0].tools, ['read'])
|
||||
})
|
||||
test('inherited tools retain deferred additions and do not mutate parent', () => {
|
||||
const parent = ['read', 'bash', 'write', 'subagent']
|
||||
const child = mergeOverlay(parseDefinition(definition('denyTools: [write, subagent]'), 'test'), parseOverlay('---\nname: scout\naddTools: [message]\n---', 'overlay'))
|
||||
assert.equal(child.tools, undefined); assert.deepEqual(child.addTools, ['message'])
|
||||
assert.deepEqual(toolsFor(child, parent), ['read', 'bash', 'message'])
|
||||
assert.deepEqual(toolsFor(parseDefinition(definition('tools: [read, write]\ndenyTools: [write]'), 'test'), parent), ['read'])
|
||||
assert.deepEqual(parent, ['read', 'bash', 'write', 'subagent'])
|
||||
})
|
||||
test('overlay errors do not replace a valid base', () => {
|
||||
const found = discover([base(), project('---\nname: scout\naddTools: [x]\ntools: [read]\n---', 'listed'), project('---\nname: scout\naddTools: []\ncolour: red\n---', 'unknown'), project('---\nname: nobody\naddTools: [x]\n---', 'orphan')])
|
||||
assert.deepEqual(Object.fromEntries(found.errors.map(error => [error.name, error.error])), {
|
||||
listed: 'Error: An overlay adds tools with addTools, not tools', unknown: 'Error: Unknown field: colour', orphan: 'Error: addTools needs an earlier definition named nobody',
|
||||
})
|
||||
assert.equal(found.definitions[0].instructions, 'Original instructions')
|
||||
assert.throws(() => parseOverlay('---\nname: scout\naddTools: read\n---', 'test'), /addTools must be a list/)
|
||||
})
|
||||
test('replacement uses name, not filename, and respects exact roots', () => {
|
||||
const found = discover([base(), project(definition('family: research', 'Replacement'), 'different'), { path: '/repos/other/.sausage/agents/scout.md', text: definition() }, { path: '/src/sausage/agents/nested/no.md', text: definition() }])
|
||||
assert.deepEqual(found.errors, []); assert.equal(found.definitions.length, 1)
|
||||
assert.equal(found.definitions[0].source, 'project'); assert.equal(found.definitions[0].instructions, 'Replacement')
|
||||
assert.deepEqual(found.replaced, [{ name: 'scout', path: project('', 'different').path, source: 'project' }])
|
||||
})
|
||||
test('family fallback, thinking override, model suffix, and unknown models', () => {
|
||||
const run = (fields: string) => definitionRuns(parseDefinition(definition(fields), 'test'), families, models)
|
||||
assert.equal(run('family: missing').family, 'default')
|
||||
assert.equal(run('family: constructor').family, 'default')
|
||||
assert.equal(run('family: research').thinking, 'high')
|
||||
assert.equal(run('family: research\nthinking: low').thinking, 'low')
|
||||
assert.equal(run('model: openai/gpt-6.1-sol').thinking, undefined)
|
||||
assert.equal(run('model: openai/gpt-6.1-sol:high').thinking, 'high')
|
||||
assert.equal(run('model: openai/gpt-6.1-sol:high\nthinking: low').thinking, 'low')
|
||||
for (const model of ['anthropic/unknown', 'unknown']) assert.match(discover([base(`model: ${model}`)]).errors[0].error, /model: Model .* not found/)
|
||||
const found = discover([base('model: openai/gpt-6.1-sol'), project('---\nname: scout\nfamily: lead\naddTools: []\n---')])
|
||||
assert.equal(found.definitions[0].model, undefined); assert.equal(found.definitions[0].runs.family, 'lead')
|
||||
const suffix = discover([base('thinking: low'), project('---\nname: scout\nmodel: openai/gpt-6.1-sol:high\naddTools: []\n---')])
|
||||
assert.equal(suffix.definitions[0].runs.thinking, 'high')
|
||||
})
|
||||
test('family world file requires valid refs and default', () => {
|
||||
for (const text of ['null', '[]', '{}', '{"default":{"model":"bad"}}', '{"Default":{"model":"openai/a"}}', '{"default":{"model":"openai/a","thinking":"bad"}}']) assert.throws(() => parseFamilies(text))
|
||||
assert.deepEqual(Object.keys(families), ['default', 'fast', 'review', 'research', 'design', 'lead'])
|
||||
assert.equal(families.review.thinking, 'xhigh')
|
||||
assert.equal(families.design.thinking, 'high')
|
||||
})
|
||||
test('all shipped definitions and overlays parse and discover', () => {
|
||||
const files = readdirSync('agents').filter(name => name.endsWith('.md')).map(name => ({ path: `/src/sausage/agents/${name}`, text: readFileSync(`agents/${name}`, 'utf8') }))
|
||||
assert.equal(files.length, 12)
|
||||
const available = ['read', 'bash', 'edit', 'write', 'message', 'note', 'notify', 'automation', 'branch', 'compact', 'remember', 'memory', 'todo', 'goal', 'subagent', 'plan', 'workspace']
|
||||
for (const file of files) {
|
||||
const agent = 'addTools' in parseFrontmatter(file.text).frontmatter ? parseOverlay(file.text, file.path) : parseDefinition(file.text, file.path)
|
||||
assert.ok(!/\b(pnpm|vitest|clone|instance|restart|web_search|mcp|setup|codemode|debug)\b|~\/\.ultimate/.test(agent.instructions), file.path)
|
||||
const fields = 'settings' in agent ? agent.settings : agent
|
||||
for (const tool of [...(fields.tools ?? []), ...(fields.denyTools ?? []), ...('addTools' in agent ? agent.addTools ?? [] : [])]) assert.ok(available.includes(tool), `${file.path}: ${tool}`)
|
||||
}
|
||||
const found = discover(files)
|
||||
assert.deepEqual(found.errors, []); assert.equal(found.definitions.length, 11)
|
||||
assert.equal(found.definitions.find(agent => agent.name === 'coordinator')!.runs.family, 'lead')
|
||||
for (const agent of found.definitions.filter(agent => agent.name.startsWith('reviewer'))) assert.equal(agent.runs.thinking, 'xhigh')
|
||||
})
|
||||
test('all applicable skills parse and avoid unavailable tools', () => {
|
||||
let skills = 0
|
||||
for (const name of readdirSync('skills')) {
|
||||
if (name === 'README.md') continue
|
||||
const parsed = parseFrontmatter(readFileSync(`skills/${name}/SKILL.md`, 'utf8'))
|
||||
assert.equal(parsed.frontmatter.name, name)
|
||||
assert.equal(typeof parsed.frontmatter.description, 'string'); assert.ok(parsed.body)
|
||||
assert.ok(!/\b(pnpm|vitest|clone|instance|restart|web_search|mcp|setup|codemode|debug)\b|~\/\.ultimate/.test(parsed.body), name)
|
||||
skills++
|
||||
}
|
||||
assert.equal(skills, 4)
|
||||
})
|
||||
console.log(`${count} checks passed`)
|
||||
@@ -0,0 +1,171 @@
|
||||
/** Pure parsing and ordered overlays for world agent files. The caller supplies all file contents and model configuration. */
|
||||
export const thinkingLevels = ['off', 'minimal', 'low', 'medium', 'high', 'xhigh', 'max'] as const
|
||||
export type Thinking = typeof thinkingLevels[number]
|
||||
export type Family = { model: string; thinking?: Thinking }
|
||||
export type Families = Record<string, Family>
|
||||
export interface Definition {
|
||||
name: string
|
||||
description: string
|
||||
path: string
|
||||
instructions: string
|
||||
model?: string
|
||||
thinking?: Thinking
|
||||
family?: string
|
||||
tools?: string[]
|
||||
addTools?: string[]
|
||||
denyTools?: string[]
|
||||
isolate?: 'none' | 'worktree'
|
||||
resident?: boolean
|
||||
fast?: boolean
|
||||
summaries?: boolean
|
||||
icon?: string
|
||||
tint?: string
|
||||
overlays?: string[]
|
||||
}
|
||||
export type File = { path: string; text: string }
|
||||
const fields = ['name', 'description', 'model', 'thinking', 'family', 'tools', 'denyTools', 'isolate', 'resident', 'fast', 'summaries', 'icon', 'tint']
|
||||
const familyName = (name: string) => /^[a-z][a-z0-9-]{0,23}$/.test(name)
|
||||
const tools = (value: unknown): value is string[] => Array.isArray(value) && value.every(v => typeof v === 'string')
|
||||
|
||||
/** Scalars and flow lists, plus the block lists and folded description used in Ultimate's parser tests. Not general YAML. */
|
||||
function scalar(input: string): unknown {
|
||||
const text = input.trim()
|
||||
if (text.startsWith('[')) {
|
||||
if (!text.endsWith(']')) throw new Error('Unclosed flow list')
|
||||
const items = text.slice(1, -1).match(/\s*(?:"(?:\\.|[^"\\])*"|'(?:''|[^'])*'|[^,]+)/g) ?? []
|
||||
return items.filter(item => item.trim()).map(item => scalar(item))
|
||||
}
|
||||
if (text.startsWith('"')) return JSON.parse(text)
|
||||
if (text.startsWith("'")) {
|
||||
if (!text.endsWith("'")) throw new Error('Unclosed scalar')
|
||||
return text.slice(1, -1).replaceAll("''", "'")
|
||||
}
|
||||
if (text === 'true') return true
|
||||
if (text === 'false') return false
|
||||
if (text === 'null' || text === '~' || text === '') return null
|
||||
if (/^-?\d+(\.\d+)?$/.test(text)) return Number(text)
|
||||
if (text.startsWith('{')) return {} // Mapping values cannot satisfy any supported field.
|
||||
return text.replace(/\s+#.*$/, '')
|
||||
}
|
||||
export function parseFrontmatter(text: string): { frontmatter: Record<string, unknown>; body: string } {
|
||||
const lines = text.replaceAll('\r\n', '\n').split('\n')
|
||||
const end = lines.indexOf('---', 1)
|
||||
if (lines[0] !== '---' || end < 0) throw new Error('Expected frontmatter fields between --- lines')
|
||||
const frontmatter: Record<string, unknown> = {}
|
||||
for (let i = 1; i < end; i++) {
|
||||
if (!lines[i].trim() || lines[i].trimStart().startsWith('#')) continue
|
||||
const match = /^([A-Za-z][A-Za-z0-9]*):\s*(.*)$/.exec(lines[i])
|
||||
if (!match) throw new Error('Expected frontmatter fields between --- lines')
|
||||
const [, key, raw] = match
|
||||
let value = raw
|
||||
if (value.trim().startsWith('[') && !value.trim().endsWith(']')) {
|
||||
while (i + 1 < end && !value.trim().endsWith(']')) value += ' ' + lines[++i].trim()
|
||||
}
|
||||
if (raw === '>' || raw === '|' || raw === '') {
|
||||
const block: string[] = []
|
||||
while (i + 1 < end && /^\s+\S/.test(lines[i + 1])) block.push(lines[++i].trim())
|
||||
if (raw === '>') frontmatter[key] = block.join(' ')
|
||||
else if (raw === '|') frontmatter[key] = block.join('\n')
|
||||
else frontmatter[key] = block[0]?.startsWith('[') ? scalar(block.join(' ')) : block.length ? block.map(line => scalar(line.replace(/^-\s+/, ''))) : null
|
||||
} else frontmatter[key] = scalar(value)
|
||||
}
|
||||
if (!Object.keys(frontmatter).length) throw new Error('Expected frontmatter fields between --- lines')
|
||||
return { frontmatter, body: lines.slice(end + 1).join('\n').trim() }
|
||||
}
|
||||
function settings(data: Record<string, unknown>, overlay: boolean) {
|
||||
const unknown = Object.keys(data).find(key => !fields.includes(key) && !(overlay && key === 'addTools'))
|
||||
if (unknown) throw new Error(`Unknown field: ${unknown}`)
|
||||
if (typeof data.name !== 'string' || !/^[a-zA-Z0-9_-]+$/.test(data.name)) throw new Error('name must be a nonempty identifier')
|
||||
for (const key of ['description', 'model']) {
|
||||
if (data[key] !== undefined && (typeof data[key] !== 'string' || !data[key].trim())) throw new Error(key === 'description' ? 'description is required' : 'model must be a nonempty string')
|
||||
}
|
||||
if (data.family !== undefined && (typeof data.family !== 'string' || !familyName(data.family))) throw new Error('family must be a family name: lowercase letters, digits and -')
|
||||
if (data.thinking !== undefined && !thinkingLevels.includes(data.thinking as Thinking)) throw new Error(`thinking must be one of ${thinkingLevels.join(', ')}`)
|
||||
for (const key of ['tools', 'denyTools', 'addTools']) {
|
||||
if (data[key] !== undefined && !tools(data[key])) throw new Error(`${key} must be a list of tool names`)
|
||||
}
|
||||
if (data.isolate !== undefined && data.isolate !== 'none' && data.isolate !== 'worktree') throw new Error('isolate must be none or worktree')
|
||||
for (const key of ['resident', 'fast', 'summaries']) {
|
||||
if (data[key] !== undefined && typeof data[key] !== 'boolean') throw new Error(`${key} must be a boolean`)
|
||||
}
|
||||
if (data.icon !== undefined && (typeof data.icon !== 'string' || !/^[A-Za-z][A-Za-z0-9]*(-[a-z0-9]+)*$/.test(data.icon))) throw new Error('icon must be a lucide icon name, like Gem or notebook-pen')
|
||||
if (data.tint !== undefined && !['violet', 'blue', 'green', 'amber', 'red', 'pink', 'teal', 'grey'].includes(data.tint as string)) throw new Error('tint must be one of violet, blue, green, amber, red, pink, teal, grey')
|
||||
return { ...data, ...(typeof data.description === 'string' ? { description: data.description.trim() } : {}) }
|
||||
}
|
||||
export function parseDefinition(text: string, path: string): Definition {
|
||||
const { frontmatter, body } = parseFrontmatter(text)
|
||||
const parsed = settings(frontmatter, false)
|
||||
if (!parsed.description) throw new Error('description is required')
|
||||
if (!body) throw new Error('Instructions are required')
|
||||
return { ...parsed, path, instructions: body } as unknown as Definition
|
||||
}
|
||||
export function parseOverlay(text: string, path: string) {
|
||||
const { frontmatter, body } = parseFrontmatter(text)
|
||||
if ('tools' in frontmatter) throw new Error('An overlay adds tools with addTools, not tools')
|
||||
const parsed = settings(frontmatter, true)
|
||||
if (!tools(parsed.addTools)) throw new Error('addTools must be a list of tool names')
|
||||
const { name, addTools, ...rest } = parsed
|
||||
return { name: name as string, addTools, settings: rest as Partial<Definition>, path, instructions: body }
|
||||
}
|
||||
export function mergeOverlay(base: Definition, overlay: ReturnType<typeof parseOverlay>): Definition {
|
||||
const { model: _pin, ...unpinned } = base
|
||||
const suffix = overlay.settings.model?.match(/:(off|minimal|low|medium|high|xhigh|max)$/)
|
||||
const resolved = suffix ? { ...overlay.settings, model: overlay.settings.model!.slice(0, -suffix[0].length), thinking: overlay.settings.thinking ?? suffix[1] as Thinking } : overlay.settings
|
||||
return {
|
||||
...(overlay.settings.family && !overlay.settings.model ? unpinned : base),
|
||||
...resolved,
|
||||
...(overlay.settings.denyTools ? { denyTools: [...new Set([...(base.denyTools ?? []), ...overlay.settings.denyTools])] } : {}),
|
||||
...(base.tools ? { tools: [...new Set([...base.tools, ...overlay.addTools])] } : overlay.addTools.length ? { addTools: [...new Set([...(base.addTools ?? []), ...overlay.addTools])] } : {}),
|
||||
instructions: overlay.instructions ? `${base.instructions}\n\n## Project additions\n\n${overlay.instructions}` : base.instructions,
|
||||
overlays: [...(base.overlays ?? []), overlay.path],
|
||||
}
|
||||
}
|
||||
export function parseFamilies(text: string): Families {
|
||||
const value = JSON.parse(text)
|
||||
if (!value || typeof value !== 'object' || Array.isArray(value)) throw new Error('families must be an object')
|
||||
for (const [name, spec] of Object.entries(value) as [string, Family][]) {
|
||||
if (!familyName(name) || !spec || typeof spec !== 'object' || !modelRef(spec.model)) throw new Error(`Invalid family: ${name}`)
|
||||
if (spec.thinking !== undefined && !thinkingLevels.includes(spec.thinking)) throw new Error(`Invalid thinking for family: ${name}`)
|
||||
}
|
||||
if (!value.default) throw new Error('default family is required')
|
||||
return value
|
||||
}
|
||||
function modelRef(model: unknown): model is string { return typeof model === 'string' && /^[^/\s]+\/\S+$/.test(model) }
|
||||
export function definitionRuns(definition: Definition, families: Families, models: readonly string[]) {
|
||||
const family = Object.hasOwn(families, definition.family ?? 'default') ? definition.family ?? 'default' : 'default'
|
||||
let model = definition.model ?? families[family].model
|
||||
let thinking = definition.thinking ?? (definition.model ? undefined : families[family].thinking)
|
||||
const suffix = /:(off|minimal|low|medium|high|xhigh|max)$/.exec(model)
|
||||
if (suffix) { model = model.slice(0, -suffix[0].length); thinking = definition.thinking ?? suffix[1] as Thinking }
|
||||
if (!modelRef(model) || !models.includes(model)) throw new Error(`model: Model "${model}" not found`)
|
||||
const slash = model.indexOf('/')
|
||||
return { model: { provider: model.slice(0, slash), modelId: model.slice(slash + 1) }, thinking, ...(definition.model ? { via: 'pin' as const } : { via: 'family' as const, family }) }
|
||||
}
|
||||
/** Sorted built-ins precede sorted project files. Invalid files produce errors without replacing an earlier definition. */
|
||||
export function discoverAgents(files: readonly File[], builtinRoot: string, repo: string, families: Families, models: readonly string[]) {
|
||||
const definitions = new Map<string, Definition & { source: 'builtin' | 'project' }>()
|
||||
const errors: { name: string; path: string; source: string; error: string }[] = []
|
||||
const replaced: { name: string; path: string; source: string }[] = []
|
||||
for (const [source, root] of [['builtin', builtinRoot + '/agents/'], ['project', repo + '/.sausage/agents/']] as const) {
|
||||
for (const file of files.filter(file => file.path.startsWith(root) && !file.path.slice(root.length).includes('/') && file.path.endsWith('.md')).toSorted((a, b) => a.path.localeCompare(b.path))) {
|
||||
try {
|
||||
let definition: Definition
|
||||
if ('addTools' in parseFrontmatter(file.text).frontmatter) {
|
||||
const overlay = parseOverlay(file.text, file.path)
|
||||
const base = definitions.get(overlay.name)
|
||||
if (!base) throw new Error(`addTools needs an earlier definition named ${overlay.name}`)
|
||||
definition = mergeOverlay(base, overlay)
|
||||
} else definition = parseDefinition(file.text, file.path)
|
||||
definitionRuns(definition, families, models)
|
||||
const previous = definitions.get(definition.name)
|
||||
if (source === 'project' && previous?.source === 'builtin' && !definition.overlays) replaced.push({ name: definition.name, path: file.path, source })
|
||||
definitions.set(definition.name, { ...definition, source: definition.overlays ? previous!.source : source })
|
||||
} catch (error) { errors.push({ name: file.path.split('/').at(-1)!.slice(0, -3), path: file.path, source, error: String(error) }) }
|
||||
}
|
||||
}
|
||||
return { definitions: [...definitions.values()].map(definition => ({ ...definition, runs: definitionRuns(definition, families, models) })), errors, replaced }
|
||||
}
|
||||
/** Tool denials also apply to inherited tools. Inputs stay unchanged. */
|
||||
export function toolsFor(definition: Definition, parent: readonly string[]): string[] {
|
||||
return [...new Set([...(definition.tools ?? parent), ...(definition.addTools ?? [])])].filter(tool => !definition.denyTools?.includes(tool))
|
||||
}
|
||||
@@ -0,0 +1,23 @@
|
||||
# World skills
|
||||
|
||||
The built-in skills live in `/src/sausage/skills/`. Repo skills live in `<repo>/.agents/skills/`.
|
||||
Each skill has `name` and `description` frontmatter. The prompt lists its path. An agent reads the full file on demand.
|
||||
|
||||
| Ultimate source | Sausage skill | Purpose |
|
||||
| --- | --- | --- |
|
||||
| how-ultimate-works | how-sausage-works | Explain branches, decisions, memory, and explicit repos without claims about a browser UI. |
|
||||
| integrate-ultimate | integrate-sausage | Investigate first and adapt selected repo agents, skills, CLIs, or servers. |
|
||||
| adopt-ultimate-setup | adopt-sausage-workflow | Tour approved families and the team, then adapt only selected pieces. |
|
||||
| write-extension | write-extension | Change durable coordination behavior through installed contracts and standard WASI operations. |
|
||||
|
||||
The port omits `ui-preview-round` and `verify-ui`.
|
||||
Those skills require browser capture tools and the Ultimate preview host. P3 supplies neither.
|
||||
Designer and coordinator instructions still require actual images before visual claims or required visual approval.
|
||||
Without images, they report visual checks as unverified. Automated tests do not replace approval.
|
||||
|
||||
The port removes storage chapter changes and subscription login instructions.
|
||||
Credentials remain in the host. A 403 requests host approval.
|
||||
A commit to `/src/sausage` on `main` reloads the complete committed coordination snapshot.
|
||||
The current task supplies files and pure parser tests, not that runtime loader.
|
||||
|
||||
Run `nix develop -c node extensions/core/agents.test.ts` from the repository root to validate all skill frontmatter and bodies.
|
||||
@@ -0,0 +1,37 @@
|
||||
---
|
||||
name: adopt-sausage-workflow
|
||||
description: Tour the world model families and review team, then adapt only the user’s selected pieces.
|
||||
---
|
||||
|
||||
# Adopt selected workflow pieces
|
||||
|
||||
Read /src/sausage/agents/models.json and all /src/sausage/agents/*.md files before the tour.
|
||||
Read the explicit project repo’s instructions and check commands.
|
||||
|
||||
Explain these pieces in one or two lines each:
|
||||
|
||||
- Model families select a model and thinking level for each role.
|
||||
- The review lead combines independent correctness, simplicity, and advisory architecture reports.
|
||||
- The coordinator overlay selects the lead family without copying its instructions.
|
||||
- The lander checks the combined result. A push needs the owner’s authorization.
|
||||
- A fresh worktree needs only the project’s required non-secret files and build steps.
|
||||
|
||||
Ask the user which pieces to adopt. Include None. Do not write files before the answer.
|
||||
|
||||
The world family file supplies default and fast through openai/gpt-6.1-sol at medium.
|
||||
It supplies review through anthropic/claude-opus-5-5 at xhigh.
|
||||
It supplies research, design, and lead through anthropic/claude-opus-5-5 at high.
|
||||
Use only models configured in the world. Never substitute another provider to bypass approval.
|
||||
The default review team uses the review family. It trades model diversity for the approved model policy.
|
||||
|
||||
Write selected repo agent files in <repo>/.sausage/agents/. Keep unrelated existing files intact.
|
||||
An overlay needs name and addTools, even when addTools is empty. It must not contain tools.
|
||||
Reviewer definitions keep tools: [read, bash], the immutable range rule, and the report format.
|
||||
Adapt correctness risks and architecture references to the actual repo. Keep simplicity focused on minimum necessary code.
|
||||
Never add a replacement reviewer lead.
|
||||
|
||||
If the user selects lander or worktree behavior, inspect the installed workspace extension’s contract before configuration.
|
||||
Do not invent configuration keys. Prove required commands in a disposable worktree with an explicit repo path.
|
||||
Show the exact diff and checks before an authorized commit. Never push without authorization.
|
||||
|
||||
The host injects credentials. A 403 requests host approval. Do not copy secrets into worktrees or configuration.
|
||||
@@ -0,0 +1,25 @@
|
||||
---
|
||||
name: how-sausage-works
|
||||
description: Explain the Sausage workflow in short steps when the user requests a walkthrough.
|
||||
---
|
||||
|
||||
# Explain the workflow
|
||||
|
||||
Use five short beats. Ask one question through message after each beat, and wait for its answer.
|
||||
Offer Skip the rest at every beat. If the user skips, continue to the final question.
|
||||
Do not claim a particular UI exists. Use the conversation and tools that the prompt supplies.
|
||||
|
||||
1. Explain that @ultimate is the standing agent. The user starts work there and can steer branches directly.
|
||||
2. Explain the flow: user → @ultimate → coordinator → scouts, workers, designers, and reviewer → submission and configured checks.
|
||||
Features need an assessment before code unless the user explicitly waived it. Pushes require authorization.
|
||||
3. Ask how much control the user wants. They decide most questions, only major questions, or authorize a hands-off goal.
|
||||
During an active goal, @ultimate records decisions through goal. Host credential approvals still require the user.
|
||||
4. Explain memory and context. Branches start from durable memory and explicit briefs. Compact preserves a handoff.
|
||||
Dreams review evidence and propose improvements. They do not switch storage chapters.
|
||||
5. Ask what the project does, its explicit repo path, and the first task.
|
||||
|
||||
Summarize the project, control preference, and task. Use remember only for durable facts and the user’s instructions.
|
||||
Read integrate-sausage before proposals for specialization. Start the first authorized task through branch with its repo path.
|
||||
|
||||
The world contains /bin programs. Agents write CLIs and servers inside one WASI sandbox.
|
||||
The host injects credentials. A 403 requests host approval. Secrets never enter the world.
|
||||
@@ -0,0 +1,39 @@
|
||||
---
|
||||
name: integrate-sausage
|
||||
description: Investigate an explicit repository and propose small Sausage specializations before changes.
|
||||
---
|
||||
|
||||
# Specialize a repository
|
||||
|
||||
## Investigate without changes
|
||||
|
||||
Require an explicit repo path. Read its AGENTS.md, manifests, lockfiles, scripts, tests, recent Git history, and architecture documents.
|
||||
Identify its purpose, language versions, domain objects, checks, deployment process, and repeated manual work.
|
||||
Read existing agents and skills before proposals. Inspect /src/sausage/extensions/ for reusable coordination contracts.
|
||||
Name credential requirements without access to secret values. A 403 requests approval from the host.
|
||||
Identify ignored files and generated assets that a fresh worktree needs. Worktrees live at /worktrees/<id>.
|
||||
Do not copy production data or credentials. Ask before shared database changes or irreversible operations.
|
||||
|
||||
## Propose before implementation
|
||||
|
||||
Offer two to four ranked changes. State the user outcome, existing code to reuse, required programs, costs, and approvals.
|
||||
Prefer a skill for repeated judgment, an agent for a specialist role, and a CLI or server for deterministic work.
|
||||
Use a coordination extension only for harness behavior, not as a new concept for world programs.
|
||||
Place repo definitions in <repo>/.sausage/agents/ and repo skills in <repo>/.agents/skills/.
|
||||
An addTools overlay extends an existing agent. A complete definition replaces it by name.
|
||||
Never replace the review lead merely to add reviewers. Add reviewer-* definitions instead.
|
||||
Read adopt-sausage-workflow for the default team and family choices.
|
||||
|
||||
Ask the user which changes to build. Do not create configuration before that choice.
|
||||
Pushes, paid operations, database changes, and credential approvals need explicit authority.
|
||||
|
||||
## Build the selected changes
|
||||
|
||||
Write selected agent files and skills directly. Delegate executable behavior to a coordinator through branch with the explicit repo path.
|
||||
Use existing build and test commands from the repo. Do not introduce a package manager or workflow without evidence.
|
||||
Prove required preparation in a disposable worktree with authorized non-secret inputs.
|
||||
Use /bin programs through bash. Preserve stdout and stderr separately when you capture output.
|
||||
Report exact checks, chosen paths, required approvals, and anything you cannot verify.
|
||||
|
||||
Coordination code and built-in assets live in /src/sausage. A commit to its main branch reloads one complete snapshot.
|
||||
Never add host imports beyond the process interface. Files, HTTP, and sockets use standard WASI interfaces.
|
||||
@@ -0,0 +1,32 @@
|
||||
---
|
||||
name: write-extension
|
||||
description: Change a Sausage coordination extension through its documented durable contracts, not new host imports.
|
||||
---
|
||||
|
||||
# Change coordination behavior
|
||||
|
||||
Use this skill only for harness coordination behavior. Agents otherwise write CLIs and servers.
|
||||
Coordination extensions live in /src/sausage/extensions/ and load from its main branch.
|
||||
A commit reloads one complete snapshot. A failed snapshot leaves the last good commit active.
|
||||
Do not treat uncommitted edits as proof that the live host uses new code.
|
||||
|
||||
Before changes, read /src/sausage/AGENTS.md, the nearest extension README, and its API contracts.
|
||||
Read the installed loader contract before imports or lifecycle changes. If a contract is absent, report the blocker.
|
||||
Copy the closest existing extension’s shape. Do not invent host APIs or use Ultimate’s browser facets.
|
||||
|
||||
Keep deterministic world operations in CLIs or servers. Use /bin programs through the documented process interface.
|
||||
Use standard WASI files, HTTP, and sockets. Never add an extra host import.
|
||||
Host code accesses world files only through the VFS. Secrets remain in the host credential manager.
|
||||
A 403 requests host approval. Do not read secret values or inject them into script environments.
|
||||
|
||||
For coordination behavior, reuse existing typed services, durable documents, tasks, events, and reactors.
|
||||
Keep related durable changes in one transaction. Use registered task definitions for work that must survive interruption.
|
||||
Check the installed disposal contract before resources or long-running work. Clean resources through that contract.
|
||||
Keep prompt sections stable. Put transient state in the existing note mechanism.
|
||||
Do not widen a public contract for one speculative caller.
|
||||
|
||||
Add fast tests for the core behavior and actual bugs. Test contract consumers and fixtures when an API changes.
|
||||
Run the exact project checks. Use the committed snapshot to verify live behavior once the loader exists.
|
||||
Report absent runtime support as unverified. P3 provides no browser capture tools.
|
||||
Before an authorized commit, inspect the complete diff and stage only owned files.
|
||||
Use --no-gpg-sign. Never push without authorization.
|
||||
Reference in New Issue
Block a user