sherpa-skill 2.0.4 → 2.0.6
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/README.md +148 -146
- package/distribution/cli/sherpa +7 -2
- package/distribution/npm/sherpa.mjs +15 -8
- package/distribution/uninstall.ps1 +3 -2
- package/package.json +1 -1
package/README.md
CHANGED
|
@@ -1,146 +1,148 @@
|
|
|
1
|
-
# Sherpa
|
|
2
|
-
|
|
3
|
-
**Build the right thing. Prove it works. Show why it matters.**
|
|
4
|
-
|
|
5
|
-
In 30 seconds you get an AI hackathon mentor installed in Claude Code or OpenCode that takes your team from a vague idea to a scoped, evidence-backed plan — and a demo you can defend to judges.
|
|
6
|
-
|
|
7
|
-
```bash
|
|
8
|
-
npm install -g sherpa-skill
|
|
9
|
-
sherpa install
|
|
10
|
-
```
|
|
11
|
-
|
|
12
|
-
Then in your agent:
|
|
13
|
-
```text
|
|
14
|
-
/sherpa suggest
|
|
15
|
-
/sherpa plan
|
|
16
|
-
/sherpa demo
|
|
17
|
-
/sherpa submission
|
|
18
|
-
```
|
|
19
|
-
|
|
20
|
-
**What you get right away:**
|
|
21
|
-
- **One install:** works in Claude Code and OpenCode; project state lives in `.sherpa/` and survives restarts and context switches.
|
|
22
|
-
- **Evidence-led:** facts vs assumptions, with `UNKNOWN` when information is missing — no invented details.
|
|
23
|
-
- **Human approval gates:** Sherpa recommends, never silently picks an idea or writes code without you confirming.
|
|
24
|
-
- **Full lifecycle:** idea → plan → build → verify → demo → submission → postmortem.
|
|
25
|
-
|
|
26
|
-
[](https://www.npmjs.com/package/sherpa-skill)
|
|
27
|
-
[](LICENSE)
|
|
28
|
-
[](https://github.com/Anshkaliya18/sherpa/stargazers)
|
|
29
|
-
[](AGENT-COMPATIBILITY.md)
|
|
30
|
-
|
|
31
|
-
|
|
32
|
-
|
|
33
|
-
## Install
|
|
34
|
-
|
|
35
|
-
The npm package is published as `sherpa-skill` (the name `sherpa` is already taken on npm).
|
|
36
|
-
|
|
37
|
-
### Option 1: npm (recommended)
|
|
38
|
-
|
|
39
|
-
```bash
|
|
40
|
-
npm install -g sherpa-skill
|
|
41
|
-
sherpa install
|
|
42
|
-
```
|
|
43
|
-
|
|
44
|
-
This installs the Sherpa skill for both Claude Code and OpenCode, plus the `sherpa` distribution CLI. To preview without writing files:
|
|
45
|
-
|
|
46
|
-
```bash
|
|
47
|
-
sherpa install --dry-run
|
|
48
|
-
```
|
|
49
|
-
|
|
50
|
-
To install only the skill (skip the CLI):
|
|
51
|
-
|
|
52
|
-
```bash
|
|
53
|
-
sherpa install --no-cli
|
|
54
|
-
```
|
|
55
|
-
|
|
56
|
-
To remove:
|
|
57
|
-
|
|
58
|
-
```bash
|
|
59
|
-
sherpa uninstall
|
|
60
|
-
```
|
|
61
|
-
|
|
62
|
-
The npm
|
|
63
|
-
|
|
64
|
-
|
|
65
|
-
|
|
66
|
-
|
|
67
|
-
|
|
68
|
-
|
|
69
|
-
|
|
70
|
-
|
|
71
|
-
|
|
72
|
-
|
|
73
|
-
```
|
|
74
|
-
|
|
75
|
-
|
|
76
|
-
|
|
77
|
-
|
|
78
|
-
```
|
|
79
|
-
|
|
80
|
-
|
|
81
|
-
|
|
82
|
-
|
|
83
|
-
|
|
84
|
-
|
|
85
|
-
|
|
86
|
-
|
|
87
|
-
|
|
88
|
-
|
|
89
|
-
|
|
90
|
-
|
|
91
|
-
|
|
92
|
-
|
|
93
|
-
|
|
94
|
-
|
|
95
|
-
|
|
96
|
-
|
|
97
|
-
|
|
98
|
-
|
|
99
|
-
|
|
100
|
-
|
|
101
|
-
|
|
102
|
-
|
|
103
|
-
|
|
104
|
-
|
|
105
|
-
|
|
106
|
-
|
|
107
|
-
|
|
108
|
-
|
|
109
|
-
|
|
110
|
-
|
|
111
|
-
|
|
112
|
-
|
|
113
|
-
|
|
114
|
-
|
|
115
|
-
|
|
116
|
-
|
|
117
|
-
|
|
118
|
-
|
|
119
|
-
|
|
|
120
|
-
|
|
121
|
-
|
|
|
122
|
-
|
|
|
123
|
-
|
|
124
|
-
|
|
125
|
-
|
|
126
|
-
|
|
127
|
-
|
|
128
|
-
|
|
129
|
-
|
|
130
|
-
|
|
131
|
-
|
|
132
|
-
|
|
133
|
-
|
|
134
|
-
- **
|
|
135
|
-
- **
|
|
136
|
-
|
|
137
|
-
|
|
138
|
-
|
|
139
|
-
|
|
140
|
-
|
|
141
|
-
- [
|
|
142
|
-
-
|
|
143
|
-
|
|
144
|
-
|
|
145
|
-
|
|
146
|
-
|
|
1
|
+
# Sherpa
|
|
2
|
+
|
|
3
|
+
**Build the right thing. Prove it works. Show why it matters.**
|
|
4
|
+
|
|
5
|
+
In 30 seconds you get an AI hackathon mentor installed in Claude Code or OpenCode that takes your team from a vague idea to a scoped, evidence-backed plan — and a demo you can defend to judges.
|
|
6
|
+
|
|
7
|
+
```bash
|
|
8
|
+
npm install -g sherpa-skill
|
|
9
|
+
sherpa install
|
|
10
|
+
```
|
|
11
|
+
|
|
12
|
+
Then in your agent:
|
|
13
|
+
```text
|
|
14
|
+
/sherpa suggest
|
|
15
|
+
/sherpa plan
|
|
16
|
+
/sherpa demo
|
|
17
|
+
/sherpa submission
|
|
18
|
+
```
|
|
19
|
+
|
|
20
|
+
**What you get right away:**
|
|
21
|
+
- **One install:** works in Claude Code and OpenCode; project state lives in `.sherpa/` and survives restarts and context switches.
|
|
22
|
+
- **Evidence-led:** facts vs assumptions, with `UNKNOWN` when information is missing — no invented details.
|
|
23
|
+
- **Human approval gates:** Sherpa recommends, never silently picks an idea or writes code without you confirming.
|
|
24
|
+
- **Full lifecycle:** idea → plan → build → verify → demo → submission → postmortem.
|
|
25
|
+
|
|
26
|
+
[](https://www.npmjs.com/package/sherpa-skill)
|
|
27
|
+
[](LICENSE)
|
|
28
|
+
[](https://github.com/Anshkaliya18/sherpa/stargazers)
|
|
29
|
+
[](AGENT-COMPATIBILITY.md)
|
|
30
|
+
|
|
31
|
+
|
|
32
|
+
|
|
33
|
+
## Install
|
|
34
|
+
|
|
35
|
+
The npm package is published as `sherpa-skill` (the name `sherpa` is already taken on npm).
|
|
36
|
+
|
|
37
|
+
### Option 1: npm (recommended)
|
|
38
|
+
|
|
39
|
+
```bash
|
|
40
|
+
npm install -g sherpa-skill
|
|
41
|
+
sherpa install
|
|
42
|
+
```
|
|
43
|
+
|
|
44
|
+
This installs the Sherpa skill for both Claude Code and OpenCode, plus the `sherpa` distribution CLI. To preview without writing files:
|
|
45
|
+
|
|
46
|
+
```bash
|
|
47
|
+
sherpa install --dry-run
|
|
48
|
+
```
|
|
49
|
+
|
|
50
|
+
To install only the skill (skip the CLI):
|
|
51
|
+
|
|
52
|
+
```bash
|
|
53
|
+
sherpa install --no-cli
|
|
54
|
+
```
|
|
55
|
+
|
|
56
|
+
To remove:
|
|
57
|
+
|
|
58
|
+
```bash
|
|
59
|
+
sherpa uninstall
|
|
60
|
+
```
|
|
61
|
+
|
|
62
|
+
The npm `sherpa` launcher supports `install`, `migrate`, and `uninstall`, and forwards `update`, `doctor`, `audit`, `clean`, `help`, and `--version` to the bundled management CLI. Management commands require Python 3.
|
|
63
|
+
|
|
64
|
+
Install with `--global` to call `sherpa` directly. For a local install, prefix commands with `npx sherpa-skill`, for example `npx sherpa-skill doctor`.
|
|
65
|
+
|
|
66
|
+
Node.js is required to run the npm package. `package.json` does not declare an `engines` field, so no specific Node version is pinned — use a current LTS release.
|
|
67
|
+
|
|
68
|
+
### Option 2: Other install methods (release installers)
|
|
69
|
+
|
|
70
|
+
The release installers download a versioned GitHub Releases archive, verify its SHA-256 checksum, and install the skill and CLI:
|
|
71
|
+
|
|
72
|
+
macOS / Linux:
|
|
73
|
+
```bash
|
|
74
|
+
curl -fsSL https://github.com/Anshkaliya18/sherpa/releases/latest/download/install.sh | bash
|
|
75
|
+
```
|
|
76
|
+
|
|
77
|
+
Windows PowerShell:
|
|
78
|
+
```powershell
|
|
79
|
+
irm https://github.com/Anshkaliya18/sherpa/releases/latest/download/install.ps1 | iex
|
|
80
|
+
```
|
|
81
|
+
|
|
82
|
+
Both installers target `~/.claude/skills/sherpa/` (Claude Code) and `~/.config/opencode/skills/sherpa/` (OpenCode) by default and never touch your project data or `.sherpa/` directories.
|
|
83
|
+
|
|
84
|
+
## See it in action
|
|
85
|
+
|
|
86
|
+
The following is an illustrative example, not a guaranteed transcript. It shows how a vague team idea becomes a scoped plan using real `/sherpa` operations.
|
|
87
|
+
|
|
88
|
+
**Before** — a vague team idea:
|
|
89
|
+
> "We should build something for campus accessibility. Maybe an app?"
|
|
90
|
+
|
|
91
|
+
**After** — walking the idea through Sherpa operations:
|
|
92
|
+
|
|
93
|
+
```text
|
|
94
|
+
/sherpa suggest ideas for campus accessibility
|
|
95
|
+
# -> Surfaces candidate ideas with pros/cons, risks, and judging-impact notes.
|
|
96
|
+
# Human picks one; Sherpa never auto-selects.
|
|
97
|
+
|
|
98
|
+
/sherpa evaluate the chosen idea
|
|
99
|
+
# -> Compares candidates against evidence and criteria, then recommends.
|
|
100
|
+
|
|
101
|
+
/sherpa plan
|
|
102
|
+
# -> Writes an implementation-ready engineering plan to .sherpa/.
|
|
103
|
+
# Architecture is not auto-approved and no code is written yet.
|
|
104
|
+
|
|
105
|
+
/sherpa demo
|
|
106
|
+
# -> Produces a judge-oriented demo preparation plan from validated evidence.
|
|
107
|
+
|
|
108
|
+
/sherpa submission
|
|
109
|
+
# -> Verifies and freezes submission materials without submitting.
|
|
110
|
+
|
|
111
|
+
/sherpa status
|
|
112
|
+
# -> Shows where you are, what's complete, what's broken, and the risks.
|
|
113
|
+
```
|
|
114
|
+
|
|
115
|
+
Each operation maps to a real workflow in `workflows/` (e.g. `idea-intelligence.md`, `project-planning.md`, `demo-preparation.md`, `submission.md`) and is registered in `commands/manifest.json`. Invoke as `/sherpa <operation> [focus]`.
|
|
116
|
+
|
|
117
|
+
## Supported agents
|
|
118
|
+
|
|
119
|
+
| Agent | Integration files | Global installer | Runtime status |
|
|
120
|
+
|---|---|---:|---|
|
|
121
|
+
| Claude Code | `.claude/skills/` skill and command files | Yes | VERIFIED |
|
|
122
|
+
| OpenCode | `.opencode/commands/` and package metadata | Yes | VERIFIED |
|
|
123
|
+
| Kilo Code | `kilo.jsonc`, `.kilo/rules/`, `.kilo/commands/`, `.kilo/skills/` | No | NOT VERIFIED |
|
|
124
|
+
| Codex CLI, Qwen Code, Gemini CLI | No verified native adapter | No | Not supported |
|
|
125
|
+
|
|
126
|
+
Details and evidence: [agent compatibility](AGENT-COMPATIBILITY.md).
|
|
127
|
+
|
|
128
|
+
Verified status is updated only after runtime testing. The table above reflects integration-file coverage, not confirmed runtime loading.
|
|
129
|
+
|
|
130
|
+
Help us verify: install Sherpa on your agent, run `/sherpa status` and `/sherpa next`, and open an issue with your results.
|
|
131
|
+
|
|
132
|
+
## Why Sherpa
|
|
133
|
+
|
|
134
|
+
- **Evidence-led:** facts, assumptions, and unknowns are kept distinct; `UNKNOWN` is used when information is unavailable.
|
|
135
|
+
- **Human approval gates:** recommendations never silently choose ideas or approve consequential work — you confirm each step.
|
|
136
|
+
- **Project-local notes:** project context and generated records live in `.sherpa/` inside your repo, not in the skill directory.
|
|
137
|
+
- **Full lifecycle coverage:** idea selection → planning → implementation → testing/security → demo prep → submission → postmortem.
|
|
138
|
+
|
|
139
|
+
## Contributing / Community
|
|
140
|
+
|
|
141
|
+
- [Contributing guide](CONTRIBUTING.md) — pull requests welcome.
|
|
142
|
+
- Look for issues labeled **good first issue**.
|
|
143
|
+
- [Open an issue](https://github.com/Anshkaliya18/sherpa/issues) for bugs or verification reports.
|
|
144
|
+
- [GitHub Discussions](https://github.com/Anshkaliya18/sherpa/discussions) for questions and ideas.
|
|
145
|
+
|
|
146
|
+
## Documentation
|
|
147
|
+
|
|
148
|
+
Field guide: https://anshkaliya18.github.io/Sherpa/ · Project references: [installation](INSTALLATION.md) · [commands](COMMANDS.md) · [workflows](WORKFLOWS.md) · [configuration](CONFIGURATION.md) · [architecture](ARCHITECTURE.md) · [security](SECURITY.md) · [migration](MIGRATION.md) · [contributing](CONTRIBUTING.md) · [changelog](CHANGELOG.md).
|
package/distribution/cli/sherpa
CHANGED
|
@@ -9,6 +9,9 @@ Commands:
|
|
|
9
9
|
sherpa update
|
|
10
10
|
sherpa uninstall
|
|
11
11
|
sherpa doctor
|
|
12
|
+
sherpa migrate
|
|
13
|
+
sherpa audit
|
|
14
|
+
sherpa clean [--dry-run | --yes]
|
|
12
15
|
sherpa help
|
|
13
16
|
|
|
14
17
|
The CLI never touches user project data or `.hackathon/` directories.
|
|
@@ -48,7 +51,7 @@ CLI_NAME = "sherpa"
|
|
|
48
51
|
|
|
49
52
|
# Embedded fallback version. Overridden by a VERSION file next to this script
|
|
50
53
|
# when one is shipped by the installer/release.
|
|
51
|
-
DEFAULT_CLI_VERSION = "2.0.
|
|
54
|
+
DEFAULT_CLI_VERSION = "2.0.6"
|
|
52
55
|
|
|
53
56
|
# Default release manifest URL. Users publishing their own releases override
|
|
54
57
|
# this with SHERPA_RELEASE_MANIFEST_URL.
|
|
@@ -155,7 +158,7 @@ def fetch_json(url: str, timeout: int = 30) -> dict:
|
|
|
155
158
|
supported_major = int(latest.split(".", 1)[0]) >= 2
|
|
156
159
|
except (AttributeError, ValueError):
|
|
157
160
|
supported_major = False
|
|
158
|
-
if project != PROJECT or not supported_major:
|
|
161
|
+
if not isinstance(project, str) or project.casefold() != PROJECT.casefold() or not supported_major:
|
|
159
162
|
raise sherpaError(f"release manifest is for {project!r} version {latest!r}, not Sherpa 2.0.0 or newer")
|
|
160
163
|
return manifest
|
|
161
164
|
|
|
@@ -511,6 +514,8 @@ Usage:
|
|
|
511
514
|
sherpa uninstall Remove installed skills (preserves user data)
|
|
512
515
|
sherpa doctor Diagnose the installation environment
|
|
513
516
|
sherpa migrate Copy legacy .hackathon/ state into .sherpa/
|
|
517
|
+
sherpa audit Report files in managed skill installations
|
|
518
|
+
sherpa clean Report or remove generated debris in managed installations
|
|
514
519
|
sherpa help Show this help
|
|
515
520
|
|
|
516
521
|
Environment variables:
|
|
@@ -10,17 +10,20 @@ const packageRoot = path.resolve(path.dirname(fileURLToPath(import.meta.url)), '
|
|
|
10
10
|
const args = process.argv.slice(2)
|
|
11
11
|
|
|
12
12
|
function help() {
|
|
13
|
-
console.log(`sherpa
|
|
13
|
+
console.log(`sherpa package launcher
|
|
14
14
|
|
|
15
15
|
Usage:
|
|
16
16
|
sherpa install [--dry-run]
|
|
17
17
|
sherpa install --no-cli
|
|
18
|
-
sherpa migrate [--project-root PATH] [--yes]
|
|
19
18
|
sherpa install --uninstall
|
|
20
19
|
sherpa uninstall
|
|
20
|
+
sherpa migrate [--project-root PATH] [--yes]
|
|
21
|
+
sherpa --version
|
|
22
|
+
sherpa update | doctor | audit | clean | help
|
|
21
23
|
|
|
22
24
|
Install targets: Claude Code and OpenCode. Use --dry-run to print target paths
|
|
23
|
-
without downloading or writing files.
|
|
25
|
+
without downloading or writing files. Management commands use the bundled
|
|
26
|
+
Python CLI. Uninstall removes managed global installs.`)
|
|
24
27
|
}
|
|
25
28
|
|
|
26
29
|
function run(script, scriptArgs, env = process.env) {
|
|
@@ -63,17 +66,21 @@ if (args.includes('--help') || args.includes('-h') || args.length === 0) {
|
|
|
63
66
|
}
|
|
64
67
|
|
|
65
68
|
const command = args[0]
|
|
69
|
+
const managementCommands = new Set(['update', 'doctor', 'audit', 'clean', 'help'])
|
|
70
|
+
if (command === '--version' || managementCommands.has(command)) {
|
|
71
|
+
const script = path.join(packageRoot, 'distribution', 'cli', 'sherpa')
|
|
72
|
+
runPython(script, args)
|
|
73
|
+
}
|
|
66
74
|
if (command === 'migrate') {
|
|
67
75
|
const script = path.join(packageRoot, 'distribution', 'cli', 'sherpa')
|
|
68
76
|
runPython(script, ['migrate', ...args.slice(1)])
|
|
69
77
|
}
|
|
70
|
-
const dryRun = args.includes('--dry-run')
|
|
71
|
-
const uninstall = command === 'uninstall' || args.includes('--uninstall')
|
|
72
78
|
if (!['install', 'uninstall'].includes(command)) {
|
|
73
|
-
|
|
74
|
-
|
|
75
|
-
process.exit(2)
|
|
79
|
+
const script = path.join(packageRoot, 'distribution', 'cli', 'sherpa')
|
|
80
|
+
runPython(script, args)
|
|
76
81
|
}
|
|
82
|
+
const dryRun = args.includes('--dry-run')
|
|
83
|
+
const uninstall = command === 'uninstall' || args.includes('--uninstall')
|
|
77
84
|
if (dryRun && uninstall) {
|
|
78
85
|
console.error('--dry-run cannot be combined with --uninstall.')
|
|
79
86
|
process.exit(2)
|
|
@@ -37,7 +37,8 @@ if (Test-Path (Join-Path $OPENCODE_SKILL_DIR "SKILL.md")) {
|
|
|
37
37
|
}
|
|
38
38
|
$cliExe = Join-Path $CLI_BIN_DIR $CLI_NAME
|
|
39
39
|
$cliBat = Join-Path $CLI_BIN_DIR "${CLI_NAME}.bat"
|
|
40
|
-
|
|
40
|
+
$cliExists = (Test-Path $cliExe) -or (Test-Path $cliBat)
|
|
41
|
+
if ($cliExists) {
|
|
41
42
|
Write-Host (" * CLI: {0}" -f $CLI_BIN_DIR) -ForegroundColor Green
|
|
42
43
|
$removed++
|
|
43
44
|
}
|
|
@@ -64,7 +65,7 @@ if (Test-Path (Join-Path $OPENCODE_SKILL_DIR "SKILL.md")) {
|
|
|
64
65
|
}
|
|
65
66
|
if (Test-Path $cliExe) { Remove-Item -Path $cliExe -Force }
|
|
66
67
|
if (Test-Path $cliBat) { Remove-Item -Path $cliBat -Force }
|
|
67
|
-
if ($
|
|
68
|
+
if ($cliExists) { Write-Ok "Removed CLI" }
|
|
68
69
|
|
|
69
70
|
if ($removed -eq 0) {
|
|
70
71
|
Write-Host "No sherpa installation found."
|