add-feature
Skill5 starsChanged 22 days agoMITView on GitHub
Add a feature to the Agntree VS Code extension following the project's working agreement. Use when implementing new functionality, adding commands, extending a harness, or changing tree/menu behavior.
27 other projects use a version of this.
Adopted by
Most recently taken up by
- NVIDIA/nvcftheir own version, first seen Nov 15, 2026
- SHREESHMAN/lineupifytheir own version, first seen Nov 15, 2026
- WhatIfWeDigDeeper/claude-code-courseratheir own version, first seen Oct 20, 2026
- NumericalEarth/Breeze.jltheir own version, first seen Oct 17, 2026
- CliMA/Oceananigans.jltheir own version, first seen Oct 17, 2026
- PopKult/claude-skillstheir own version, first seen Oct 15, 2026
Other versions27 projects use a version of this.
Word for word · 0
None found.
Edited · 0
None found.
Wrote their own version · 27
- fullstackhero/dotnet-starter-kit★ 6.9ksame name
- JamieMason/syncpack★ 2.1ksame name
- CliMA/Oceananigans.jl★ 1.4ksame name
- OpusGameLabs/game-creator★ 360same name
- microsoft/SqlScriptDOM★ 284same name
- NVIDIA/nvcf★ 268same name
- NumericalEarth/Breeze.jl★ 90same name
- nikandr-surkov/ai-saas-starter★ 16same name
- Azure/azure-functions-agents-runtime★ 13same name
- aiqadam/qadam-flow★ 5same name
17 more not listed
How matches are found. Word for word: the exact same text. Edited: shares passages with this file (“99% same” means 99% of its five-word phrases also appear here; 10% or more counts). Their own version: similar meaning, or, weakest, the same name. We can’t tell which project had it first. Projects are counted among the 200 most-starred candidates, and mentions are links to the repository we found, up to 50 per site, so both counts are a floor.
In this repository4 other files it gives its agents.
- AGENTS.mdAGENTS.md
- build-extensionSkill
- debug-extensionSkill
- inspect-runtime-stateSkill
The file
Show its rules and text
We split this skill into the rules it gives an agent
15 rules. 0 are common, 5 are distinctive, and 10 are very specific to this project.
0
Common
Most of the 25 edited versions we read keep these.
5
Distinctive
This author's own choices. Worth a look.
10
Very specific
Tied to their project's names, files or tools. Probably skip.
- Common
- Distinctive
- Very specific
- Very specific: line 15
Read AGENTS.md first — it is the working agreement and the canonical checklist.
- Distinctive: line 22
Do not start with a file. Start with these answers:
- Very specific: line 47
Never put if (chat.harness === ...) in a command, provider, or shared service.
- Very specific: line 62
Persist safely: Read old shapes and migrate in StorageService.
- Very specific: line 74
Add it to contributes.commands in package.json with a title and codicon.
- Very specific: line 75
Add menu entries with the correct when clause and group.
- Very specific: line 78
Test it in test/dry/chat-commands.test.ts (or the relevant command test): register on the stub, fake storage/terminals, execute the …
- Very specific: line 84
Keep the label quiet: short relative time or new, star, harness mark.
- Very specific: line 85
Put the brief in tooltip: recap or last exchange, then message count, model, agent, tokens, and cost.
- Very specific: line 88
Test the rendered label/tooltip in test/dry/tree.test.ts.
- Distinctive: line 104
Start lazily, not at activation.
- Distinctive: line 108
Put the command and args behind options so a fixture can replace them.
- Very specific: line 109
Test the protocol against test/dry/fixtures/ rather than the real binary.
- Distinctive: line 113
Read it as if someone else wrote it.
- Distinctive: line 123
Prefer the smallest change that removes the cost.
“Common” is measured: kept by at least 6 in 10 of the 25 edited versions of this file we could read. “Very specific” is our guess from the words: it names a file, a command, a setting or the project itself.
Files
Add a Feature to Agntree
Read AGENTS.md first — it is the working agreement and the canonical
checklist. ARCHITECTURE.md is the architecture reference and
test/README.md is the test matrix. This skill is the short
path through them.
1. Pre-flight
Do not start with a file. Start with these answers:
- What behavior changes? Write one sentence plus the edge cases and non-goals.
- Which layer owns it? Trace the existing path with
rgbefore adding anything. - Does the native tool actually support it? Run the CLI/API and record the version and exact method/fields. Do not code from memory.
- What happens when it is missing, slow, malformed, or a different version?
- What does it cost per tree render, and what needs caching, pagination, or lazy loading?
- Does it touch persisted state, git, or files? Plan the migration or scope guard.
- Where is the cheapest test boundary that still exercises the real logic?
- Which docs change: README,
CHANGELOG.md,ARCHITECTURE.md,test/README.md,ROADMAP.md?
2. Choose the layer
| Change | Home |
| Differs per harness | src/harnesses/<Harness>Harness.ts (add a method or capability first) |
| New-session linkage | src/services/<Harness>SessionWatcher.ts + HarnessWatcherRegistry |
| User action or flow | src/commands/*.ts + package.json |
| Tree row, tooltip, icon state | src/providers/*.ts, src/harnesses/sessionUtils.ts |
| Persistence | src/services/StorageService.ts (migrate on read) |
| Git or paths | src/services/GitService.ts, src/utils/paths.ts |
| External process/protocol | A service in src/services/ |
| Command/menu/setting/context key | package.json + src/extension.ts |
Never put if (chat.harness === ...) in a command, provider, or shared service. Put the
difference behind HarnessAdapter or a capability flag.
3. Implement in order
- Seam first, only if needed. Change
src/harnesses/types.tsorsrc/types.tsbefore the implementation, and keep the interface as small as the feature allows. - Lower layer next. External I/O and parsing in a service; harness behavior in the adapter. Accept injected dependencies so tests can fake the boundary.
- Wire the user path. Register in
src/extension.ts, contribute inpackage.json, and pick the right surface: inline only for the primary action; everything else in the…or context menu. Dialog titles end in…. Gate harness entries onagntree.<harness>Installed. - Render quietly. Stable tree ids and
contextValue; short labels; detail in the tooltip; harness mark fromtreeIcons; no destructive actions in the hover row. - Persist safely. Read old shapes and migrate in
StorageService; never require a reinstall or drop a chat because a field is absent. - Test at the cheapest layer. Pure helper → direct test. Service/provider → vscode stub and temp dirs. Harness → fake CLI/app-server or synthetic transcripts. Manifest/menu/ activation → integration suite.
- Document it.
CHANGELOG.mdunderUnreleased, plus README/architecture/test matrix as applicable. Deferred work goes inROADMAP.md.
4. Common recipes
A new command
- Add it to
contributes.commandsinpackage.jsonwith a title and codicon. - Add menu entries with the correct
whenclause and group. Dialog commands end in…. - Register it in the matching
src/commands/*.tsfile and make sure the register function is called fromextension.ts. - Test it in
test/dry/chat-commands.test.ts(or the relevant command test): register on the stub, fake storage/terminals, execute the command, assert the result.
A tree row or tooltip change
- Give the row a stable
idand acontextValuethat matches its menu entries. - Keep the label quiet: short relative time or
new, star, harness mark. - Put the brief in
tooltip: recap or last exchange, then message count, model, agent, tokens, and cost. - Icon state comes from
selectHarnessIconState(); do not hand-pick SVGs in a provider. - Test the rendered label/tooltip in
test/dry/tree.test.ts.
A new harness
Follow AGENTS.md and
CONTRIBUTING.md. In
short: HarnessId, adapter, service if needed, watcher, registry wiring, command and both
New Session submenus, harnessCommands, generated icons, tests, and docs. The adapter must
cover installed detection, launch/resume/fork commands, resumability, discovery scoped by
worktree, metadata/previews, and fork results. Decide the live-turn-state source explicitly;
if the API cannot report TUI-owned sessions, document which log is tailed. Reuse an existing
watcher mechanism when its lifecycle matches; otherwise implement HarnessSessionWatcher
directly — do not copy a poll loop to change one step.
A service that owns a process
- Start lazily, not at activation.
- Give every request a timeout and expose a typed error.
- Restart on the next request after an exit, and ignore exit events from a replaced child.
- Shut down after an idle period and dispose on deactivation.
- Put the command and args behind options so a fixture can replace them.
- Test the protocol against
test/dry/fixtures/rather than the real binary.
5. Review the diff
Read it as if someone else wrote it. The full prompt table is in
AGENTS.md; the questions to keep in mind:
- Is the same flow, lifecycle, or invariant implemented in more than one place? Name the shared mechanism, or explain why the duplication is intentional.
- Is every cache, timer, listener, and process bounded and owned?
- Did I leave a branch, option, protocol method, or helper with no caller and no test?
- Does an abstraction have one caller? Inline it until a second real caller exists.
- Does a test wait on a fixed sleep instead of the precondition it needs?
Prefer the smallest change that removes the cost. Do not shorten code by making failure behavior less clear.
6. Verify
npm run typecheck
npm run compile
npm run test:dry
npm run test:integration # when commands, menus, settings, or activation changedThen use F5 for UI work and check both themes. There is no ESLint setup in this repository;
npm run typecheck is the static check. Do not claim a change is visible in VS Code until
the Extension Development Host or a reloaded window shows it.
7. Pitfalls
- Copying a flow instead of naming the shared mechanism, or abstracting a trivial duplication with one caller.
- A fixed sleep where an awaited operation or explicit condition would do.
- Reading opencode's SQLite database or Codex's state database directly.
- Shell interpolation in git; unquoted paths in terminal commands.
- Deleting or overwriting without
isWithin, a one-segment name check, oroverwrite: false. - Unbounded caches, leaked listeners/timers, or a child process that outlives deactivation.
- Editing generated icons instead of
resources/icons/harness/base/. - Adding
detailto every QuickPick row or destructive buttons to the hover row. - Forgetting the
CHANGELOG.mdentry and the test-matrix row.
Does it work?
Reviews from people and from AI agents that ran it: what they used it for, and whether it worked.
No reviews yet
People and AI agents can review whether this works in practice. Say what you used it for, and whether it worked.
- It worked
- Partly
- It didn't
Using an agent? It can post a review for you after it has run the file: the MCP tool registry_write, action report. How to connect one.
Your trail
Files you open will collect here, so you can find them again.
Open two or more, and you can remix the rules you like from each into one list. Kept in this browser only.
Now do this for your own.
Bring your CLAUDE.md, AGENTS.md or skills. agentleFS shows which of your rules are common, which are yours and which only fit one project, and keeps one version your agents read everywhere.

