Repository navigation
Releases
v0.1.5
Lower cost for each session, and a debugger that finds every cause of a defect. Each change comes from a benchmark against plain Claude Code on Opus 5.5.
Upgrade
/plugin marketplace update shark-skills
No project change is necessary.
What's new in 0.1.5
Less cost for each task. A benchmark of 3 tasks put shark at 3.6× the cost of plain Claude Code in 0.1.4. Now it is 2.0× plain on the same 3 tasks, and 1.66× on the multi-module task that cost 4.1× before. All hidden tests still pass.
- Direct path. The operator does small and medium work itself: a question, a review, or a change in 3 modules or fewer and about 10 files or fewer, with no migration. Agents and lanes start only for larger work, or when you ask for them.
- Less context. The skill and agent descriptions, the operator skill, the output style and the Working rules block are about half their earlier size. The orchestration details load only on the orchestrated path.
- Model routing.
doc-writerandcookbook-writerrun on Sonnet.invariant-guardruns on Sonnet at medium effort, only on the orchestrated path.architectruns on Opus at medium effort. The operator asks for a stronger model or a higher effort for each call that needs it.
Fixes keep their scope. A fix keeps each public interface. Other defects go in the report. An interface change is a question for you, never a default.
A debugger that finds every cause. A real defect often has more than one cause, and the obvious fix often breaks a rule next to it. shark:debug-rca now has a completeness gate:
- a symptom map before any hypothesis;
- a variant matrix: twin paths, operations, value shapes, the "all" scope and the denied actor, each tested with the defect's state in place;
- a search for twin code paths;
- guard tests for the rules that the fix must not break.
The operator sends a bug report with more than one symptom, or with a twin path, to shark:code-debugger first, word for word. shark:code-writer implements each part of the Fix spec.
Measured on a real Payload CMS defect (localized drafts and per-locale status), graded by the 9 upstream regression tests:
| Run | Tests fixed | Regressions |
|---|---|---|
| Plain Claude Code | 2 of 9 | 2 |
| Plain Claude Code with the debugger tools | 3 of 9 | 4 |
| shark 0.1.5 (best run) | 4 of 9 | 0 |
This is one defect and a small number of runs. The results change from run to run, and 5 of the 9 tests still fail. Work on these continues.
Launch recipes for each language are now references of shark:debug-rca. The JavaScript recipe records what we observed with Vitest: attach mode reaches the test worker, and a probe test replaces a breakpoint that stays unbound.
What's fixed in 0.1.5
- Lane branches stay after a merge. A lane that lands by cherry-pick is not merged for git. The lead now deletes it with
git branch -Donly whengit cherryshows that each commit is on the target. - The secrets hook blocked a debugger call. A test-name pattern such as
.*in debugger arguments looked like a file glob for.env. Debugger arguments do not go through a shell, so the hook no longer reads them as globs.
All 9 evals pass (attested in evals/attestation.json).
shark v0.1.4
A fix for /shark:init: it now always adds the Working rules block to your project file.
Upgrade
/plugin marketplace update shark-skills
If you ran /shark:init with 0.1.3 or earlier, check your project file: it must have the block between the shark:working-rules markers. Run /shark:init again to add it. A second run keeps your text and changes nothing else that is set up.
What's fixed in 0.1.4
init sometimes left out the Working rules block. The eval suite found it: some runs made an AGENTS.md with the project sections but with no Working rules. There were two causes:
- The skill told the model to add the block before it wrote the file. A run could add the block, then replace the whole file with the sections, and the block was gone.
- When the shell could not write the file, for example in a sandbox, nothing told the model what to do instead.
Now a script adds the block. working-rules.sh apply adds it at the end of the file only when it is missing, keeps the file permissions, and checks the result. init runs it as the last write to the file. When the shell cannot write, init adds the exact block with the Edit tool. The script has its own tests, and CI runs them.
Fewer "would" and "could" in replies. The shark:asd-ste100 word table now shows two rewrites: "would not show" becomes "does not show", and "could not read" becomes "did not read" or "cannot read". In the eval that found the problem, replies used these words in 4 of 13 runs before the change and in 0 of 9 runs after it.
Eval results
All nine cases pass on this release (the style cases run 3 times and need 2 passed runs). The Docker runner now keeps the eval workspaces on the mounted folder, where the shell can write, as in a real session.
License
MIT. The AGENTS.md template and the logo are CC0.
shark v0.1.3
shark now blocks agents from reading your secret files, gives each agent only the tools it needs, and comes with an eval suite that checks the kit before each release.
Upgrade
/plugin marketplace update shark-skills
Start a new session after the update. The secrets hook is on by default.
What's new in 0.1.3
A hook that keeps agents out of your secret files. Before each Read, Edit, Write, Grep, Bash or mcp-debugger call, the deny-secrets hook checks the paths against the ## Secrets section of your CLAUDE.md or AGENTS.md. With no section, it uses a default list: .env, .env.*, secrets/**, *.pem, *.key. A match stops the call and tells the agent why.
- Example files (
*.example,*.sample,*.template) always stay readable, so agents still learn the setting names. - Bash commands are checked too:
cat .env,grep KEY .env*andhead < .envare all stopped. - Debugger expressions are checked too:
open('.env').read()in a debug session is stopped. - Write
nonein your## Secretslist to turn the hook off.
The hook guards against mistakes. It is not a sandbox: a script that opens .env by itself is not stopped. Keep real production secrets out of the working tree.
Agents get only the tools they need.
shark:code-debuggerhad every tool. It now gets the read tools, Bash, Edit and Write for its regression test, and the debugger.- Every agent can now ask the operator for more time with
SendMessage. Before, the tool was missing and the request never arrived.
Consistent rules. One rule for git worktree remove --force: only on a temporary worktree that the agent made, or with known leftovers. The goal-loop lane timebox now matches the template: 20 minutes.
An eval suite. Nine cases check the output style, the comment rules, /shark:init, the secrets hook and the debugger agent on a small fixture project. Contributors run it in Docker (evals/docker/run.sh) and commit an attestation: a SHA-256 fingerprint of the files that the evals tested. CI checks that the attestation matches the code and that every case passed. All nine cases pass for this release (the style cases run 3 times and need 2 passed runs).
For contributors
See evals/README.md for how to run the suite, attest the result and add a case. CI runs node evals/attest.mjs verify and the hook unit tests on each push and pull request.
License
MIT. The AGENTS.md template and the logo are CC0.
shark v0.1.2
The /shark:init now sets asd-ste100 as default output-style for your project, and the code agents no longer write explanation comments on almost each line of your code. The final code is well readable.
Upgrade
/plugin marketplace update shark-skills
Then run /shark:init again in each project. It adds the output style and changes nothing else that is already set up.
What's new in 0.1.2
The output style has real rules. In 0.1.1 the style told Claude only "write in ASD-STE100". Now it gives the rules:
- Sentences of 20 words or fewer for an instruction and 25 for a description, in the active voice, with a table of words to avoid.
- Each claim labelled observed (seen in this session) or inferred. General knowledge is never "observed".
- The answer first, one recommendation, and no extra review that you did not ask for.
- Every reply ends with a Summary and Action items, each with an owner, so the end of the reply in your terminal tells you what to do next.
We tuned the rules over three rounds of 10 test prompts.
/shark:init sets the output style. It writes "outputStyle": "shark:asd-ste100" to .claude/settings.json, and keeps every other key. If your team already uses a different style, init asks before it changes it. It never changes your personal .claude/settings.local.json.
No explanation comments in code. shark:code-writer, shark:lead-engineer and shark:code-debugger no longer add comments that say what a line does or why. Names, small functions and types carry the meaning, and the reason goes in the report or the commit message. You can still ask for an explanation comment.
Documentation comments follow one format. Doc comments (docstrings, TSDoc, Go and Rust doc comments) tell a caller how to use the API, not how it works:
| Part | Rule |
|---|---|
| Description | One sentence of 20 words or fewer |
| Parameters | One sentence each, with the unit |
| Return value | One sentence |
| Errors | Only the errors that a caller must handle |
| Example | One usage example. An edge case is one more example line. |
The format comes from the Rust API guidelines, rustdoc, the NumPy docstring standard, the Google Python style guide, Go doc comments and PEP 257. shark:code-writer has reference samples for Python, TypeScript, Go and Rust.
License
MIT. The AGENTS.md template and the logo are CC0.
shark v0.1.1
shark is my Claude Code setup for building real features with a team of agents. This is the first public release.
The main session becomes the operator: it briefs subagents, checks what they hand back, and talks to you. Lanes build in parallel against one shared contract, every merge gets audited, and every bug gets a root cause before it gets a fix.
Install
/plugin marketplace add tusharsrivastava/shark-skills
/plugin install shark@shark-skills
Then run /shark:init once per project. It brings your AGENTS.md or CLAUDE.md in line with the template, so every new session loads the operator by itself. If you already have your own orchestrator, it asks which one leads.
You'll need git, and Node.js with npx for the debugger MCP server.
What's in 0.1.1
Session
/shark:init: set up a project once. It adds the missing sections, keeps the text you already have, and never removes a line./shark:operator: the harness. It sets the mode (feature, review, debug) and keeps long work in background agents./shark:handoff: carry state between sessions.
Build and merge
/shark:lead-merge,/shark:merge-audit: merge parallel lanes, then check each merge independently./shark:goal-loop: fix rounds on N failing scenarios./shark:port-audit,/shark:patch-fanout: find the rules a rewrite lost, and put them back./shark:commit-blocks: one reason per commit, and each commit passes the gate on its own.
Debug and design
/shark:debug-rca: a root cause, a failing regression test and a fix spec, before any fix./shark:system-design: design checks, SOLID, patterns, contracts.
Docs and upkeep
/shark:cookbook-writing,/shark:gitignore.
Agents: architect, code-writer, code-debugger, lead-engineer, invariant-guard, doc-writer, cookbook-writer.
Also in the box
- The
AGENTS.mdtemplate with the working rules. - The
asd-ste100output style, for reports in simplified technical English. - The mcp-debugger MCP server (pinned to 0.24.2) for real step-through debugging.
License
MIT. The AGENTS.md template and the logo are CC0.
Found a security issue? Report it privately through the Security tab. See SECURITY.md.
v0.1.0
First Version Release
Full Changelog: https://github.com/tusharsrivastava/shark-skills/commits/v0.1.0
