sherpa-skill 2.0.6 → 2.0.7

package/.agents/skills/sherpa/docs/commands/README.md

@@ -0,0 +1,96 @@
+# Sherpa Native Commands
+
+[`commands/manifest.json`](https://github.com/Anshkaliya18/Sherpa/blob/main/commands/manifest.json) is the single authoritative registry. It lists only commands mapped to an existing workflow as implemented. Planned commands are not registered in host adapters or advertised as usable.
+
+## Preferred syntax
+
+Use `/sherpa-<action>` for direct invocation. The master `/sherpa` command and its existing nested forms remain available for backward compatibility. Both forms resolve through `core/commands/router.py` to the same workflow; adapters contain no business logic.
+
+## Implemented commands
+
+### Core
+
+- `/sherpa-status` — Show evidence-backed project status. Maps to `STATUS` → `workflows/status.md`.
+- `/sherpa-next` — Identify the single highest-priority next action. Maps to `NEXT` → `workflows/next.md`.
+- `/sherpa-help` — List implemented sherpa commands and limitations. Maps to `HELP` → `SKILL.md#help`.
+- `/sherpa-init` — Initialize project-local sherpa state safely. Maps to `INIT` → `workflows/init.md`.
+- `/sherpa-phase` — Show current lifecycle phase and evidence. Maps to `PHASE` → `SKILL.md#phase`.
+
+### Configuration
+
+- `/sherpa-config` — Show a redacted project configuration overview. Maps to `CONFIG` → `workflows/configuration.md`.
+- `/sherpa-config-check` — Validate project configuration and secret protections. Maps to `CONFIG CHECK` → `workflows/configuration.md`.
+
+### Intelligence
+
+- `/sherpa-suggest` — Discover, evaluate, and red-team idea candidates; human selection required. Maps to `SUGGEST` → `workflows/idea-intelligence.md`.
+- `/sherpa-evaluate` — Evaluate and compare candidate ideas with evidence. Maps to `IDEA-EVALUATE` → `workflows/idea-evaluation.md`.
+- `/sherpa-compare` — Compare candidate ideas using the existing idea-evaluation workflow. Maps to `IDEA-EVALUATE` → `workflows/idea-evaluation.md`.
+- `/sherpa-research` — Investigate a research question with source and evidence constraints. Maps to `RESEARCH` → `workflows/research.md`.
+- `/sherpa-redteam` — Challenge project assumptions and readiness using the red-team workflow. Maps to `RED-TEAM` → `workflows/red-team.md`.
+- `/sherpa-optimize` — Prioritize score-improving work against evidence and criteria. Maps to `SCORE-OPTIMIZE` → `workflows/score-optimization.md`.
+- `/sherpa-judge-me` — Simulate judge perception using the judge-simulation workflow. Maps to `JUDGE-SIM` → `workflows/judge-simulation.md`.
+
+### Engineering
+
+- `/sherpa-repo` — Inspect repository evidence as part of project planning. Maps to `PROJECT-PLAN` → `workflows/project-planning.md`.
+- `/sherpa-architecture` — Plan architecture from the selected idea and repository evidence. Maps to `PROJECT-PLAN` → `workflows/project-planning.md`.
+- `/sherpa-techstack` — Assess technology choices within the project plan. Maps to `PROJECT-PLAN` → `workflows/project-planning.md`.
+- `/sherpa-plan` — Create an implementation-ready project plan. Maps to `PROJECT-PLAN` → `workflows/project-planning.md`.
+- `/sherpa-build` — Execute an approved implementation task using the existing implementation workflow. Maps to `IMPLEMENT` → `workflows/implementation.md`.
+- `/sherpa-verify` — Verify implementation through the existing testing and security workflow. Maps to `TESTING-SECURITY` → `workflows/testing-security.md`.
+- `/sherpa-test` — Test implemented scope using the testing and security workflow. Maps to `TESTING-SECURITY` → `workflows/testing-security.md`.
+- `/sherpa-security` — Review security using the testing and security workflow. Maps to `TESTING-SECURITY` → `workflows/testing-security.md`.
+- `/sherpa-ux` — Review product usability and accessibility readiness. Maps to `UX-REVIEW` → `workflows/ux-review.md`.
+
+### Product Quality
+
+- `/sherpa-accessibility` — Review accessibility within the existing UX-review scope. Maps to `UX-REVIEW` → `workflows/ux-review.md`.
+
+### Finalization
+
+- `/sherpa-demo` — Prepare an evidence-backed judge-oriented demo plan. Maps to `DEMO-PREPARE` → `workflows/demo-preparation.md`.
+- `/sherpa-audit` — Run the existing final-audit workflow after its prerequisites are met. Maps to `FINAL-AUDIT` → `workflows/final-audit.md`.
+- `/sherpa-submission` — Prepare and verify submission materials without submitting. Maps to `SUBMISSION-PREPARE` → `workflows/submission.md`.
+- `/sherpa-postmortem` — Run the final-phase evidence-based retrospective. Maps to `POSTMORTEM` → `workflows/postmortem.md`.
+
+### Emergency
+
+No implemented command currently belongs to this group.
+
+## Planned, not available
+
+These names are intentionally absent from native adapters and command help until a corresponding workflow exists:
+
+- `/sherpa-improve` — PLANNED. No general improvement workflow exists; score optimization is narrower.
+- `/sherpa-polish` — PLANNED. No standalone polish workflow exists.
+- `/sherpa-performance` — PLANNED. No performance-review workflow exists.
+- `/sherpa-experience` — PLANNED. No standalone experience workflow exists.
+- `/sherpa-video` — PLANNED. No video workflow exists.
+- `/sherpa-emergency` — PLANNED. No emergency workflow exists.
+- `/sherpa-freeze` — PLANNED. No freeze workflow exists.
+- `/sherpa-reality-check` — PLANNED. No dedicated reality-check workflow exists.
+- `/sherpa-health` — PLANNED. No standalone health workflow exists.
+
+## Host registration and argument behavior
+
+| Host | Registration | Argument handling | Hyphenated runtime |
+|---|---|---|---|
+| Claude Code | `.claude/skills/<command>/SKILL.md`; the skill name is slash-invocable. | `$ARGUMENTS` is passed into each thin adapter. | NOT VERIFIED — global invocation stopped before dispatch because the configured model was unrecognized. |
+| OpenCode | `.opencode/commands/<command>.md`; filename defines the slash command. | `$ARGUMENTS` is supported by the command template. | NOT VERIFIED — global invocation produced no output after 15 seconds and was interrupted. |
+| Kilo | `.kilo/commands/<command>.md`; filename defines the workflow command. | No argument substitution is assumed; adapters do not depend on trailing input. | NOT VERIFIED — global status command loaded its workflow, then a read-only tool call was auto-rejected by the permission gate. |
+
+Runtime attempt evidence recorded in the manifest:
+
+- Claude Code: `NOT VERIFIED` — `claude --print --permission-mode plan /sherpa-status` from an isolated temporary project stopped before dispatch because Claude Code rejected the configured model as unrecognized.
+- OpenCode: `NOT VERIFIED` — `opencode run --pure --log-level DEBUG --command sherpa-status` from an isolated temporary project produced no output after 15 seconds and was interrupted; the earlier project-root attempt also waited without workflow output.
+- Kilo: `NOT VERIFIED` — `kilo run --pure --command sherpa-status` from an isolated temporary project resolved the global adapter and read the global SKILL.md, manifest, router, and status workflow; the permission gate auto-rejected a read-only Test-Path call before a report was produced.
+
+Runtime status is also recorded in `commands/manifest.json`. A file or static test proves registration structure, not that a host discovers or executes it. The existing master router has historical host-specific verification recorded in [`commands/README.md`](https://github.com/Anshkaliya18/Sherpa/blob/main/commands/README.md); those results do not verify the newly added hyphenated commands.
+
+Official host references: [Claude Code skills](https://code.claude.com/docs/en/skills), [OpenCode commands](https://opencode.ai/docs/commands), and [Kilo workflows](https://kilo.ai/docs/customize/workflows).
+
+## Compatibility and safety
+
+Existing `/sherpa`, `/sherpa status`, `/sherpa next`, `/sherpa config`, `/sherpa config check`, `/sherpa suggest`, and `/sherpa verify` are retained in the shared resolver. Native aliases share the same router and workflow. Config output remains redacted; the consuming project state is read in place and is not synchronized from this framework repository. Human approval, prerequisites, evidence labels, and lifecycle boundaries remain owned by the existing workflows. Stage 3 remains BLOCKED / NOT LOCKED until `/sherpa-suggest` has been run in a supported host against the actual consuming project. No Stage 4 action is invoked by registering `/sherpa-build`.
+

package/.agents/skills/sherpa/docs/configuration/runtime-verification.md

@@ -0,0 +1,64 @@
+# Stage 2 Runtime Verification Record
+
+**Result: STAGE 2 — COMPLETE & LOCKED.** On 2026-10-31, after synchronizing the current repository skill into the active Claude Code installation, the user manually executed `/sherpa config`, `/sherpa config check`, `/sherpa phase`, and `/sherpa next` and confirmed successful runtime output for all four. The specific output transcript was not included in this audit; the runtime result is recorded as user-confirmed manual evidence. Repository regression, routing, security, syntax, and lifecycle checks were also executed during this audit. Historical Kilo and OpenCode results remain separately recorded and are not recharacterized as successful.
+
+## Blocker resolution log
+
+**Latest audit timestamp:** 2026-10-31 (Claude Code manual verification reported by user; repository checks rerun in this audit).
+
+This record preserves historical failures and follow-up attempts. At the time of those attempts, no sherpa code fix was made because the observed blockers were in host model/provider availability, host command permissions, and OpenCode's own startup behavior. The later repository routing change has not been validated in a live host invocation.
+
+| Host | Cause classification | Diagnosis and follow-up |
+|---|---|---|
+| Claude Code | MANUAL RUNTIME VERIFIED | Earlier CLI attempts failed under stale host model configuration. After synchronizing the current repository skill into the active Claude Code installation, the user manually executed `/sherpa config`, `/sherpa config check`, `/sherpa phase`, and `/sherpa next`; successful runtime output was confirmed for each. This user-confirmed runtime evidence supersedes the earlier stale-installation failures. |
+| Kilo Code | PERMISSION / HOST MODEL | Historical separate-alias calls are described below. After the shared-router change, current root calls `kilo run --pure --command sherpa --format json config` and the same command with `config check` read the root skill/router and selected the corresponding CONFIG / CONFIG CHECK path. CONFIG then stopped at a denied directory-inspection command; CONFIG CHECK stopped at a denied `python core/configuration/manager.py check` command. No report was returned and broad `--auto` was not used. Both current host operations therefore failed at the Kilo permission gate; dispatch recognition is observed, operation completion is not. |
+| OpenCode | HOST STARTUP SIDE EFFECT | Before the historical OpenCode attempt, the disposable project had the command manifest but no package manifest or dependency directory. After `opencode run --command sherpa --format json config`, OpenCode had created `.opencode/.gitignore`, `.opencode/package.json`, `package-lock.json`, and `node_modules/`; the generated manifest pins `@opencode-ai/plugin` to the OpenCode host version 1.19.4. The manager and workflow contain no package-manager invocation. OpenCode documents automatic plugin-package installation at startup, and upstream reports describe generated project-local plugin SDK files ([plugin docs](https://opencode.ai/docs/plugins/), [upstream issue #27676](https://github.com/anomalyco/opencode/issues/27676)). The generated files establish that OpenCode's host bootstrap installed its runtime package; the exact installer subprocess was not captured (the lockfile is npm-format). This is not an application dependency, but it still fails the requested no-install condition. The check variant was not attempted after this was observed. This invocation predates the current shared router and does not establish current dispatch behavior. |
+
+### Resolution outcome
+
+- Claude Code: **PASS** for `/sherpa config`, `/sherpa config check`, `/sherpa phase`, and `/sherpa next` after synchronizing the current repository skill. Earlier model errors came from the prior unsynchronized host setup.
+- Kilo: **ROOT ROUTING OBSERVED; COMMANDS FAIL AT PERMISSION GATE**; both root arguments selected the intended operation, then the necessary manager/workspace command was auto-rejected. Broad auto-approval was intentionally not enabled.
+- OpenCode: **CURRENT ROOT ARGUMENTS UNKNOWN**; the historical invocation stalled and host startup generated its plugin SDK dependency in the disposable project. No repeat was run because it would risk repeating that dependency installation.
+- Regression after the attempts: Stage 1 **10/10 PASS**; Stage 2 **12/12 PASS**; `git diff --check` **PASS**.
+- Documentation now records the blocked outcomes; no successful runtime execution is claimed.
+- An ignored `.opencode/package.json`, lockfile, and `node_modules/` were also observed in the framework repository with filesystem creation time 2026-10-31 09:58 UTC, earlier than the current host attempts. No start-of-turn baseline was captured, so this audit does not attribute those files to this verification run.
+
+## Host results
+
+| Host | `config` | `config check` | Secret safety | Non-destructive |
+|---|---|---|---|---|
+| Claude Code | PASS | PASS | PASS (covered by redaction checks and confirmed output) | PASS (configuration operations completed) |
+| Kilo Code | FAIL | FAIL | UNKNOWN | UNKNOWN |
+| OpenCode | UNKNOWN | UNKNOWN | UNKNOWN | UNKNOWN |
+
+### Claude Code
+
+After synchronizing the current repository skill into the active Claude Code installation, the user manually ran `/sherpa config`, `/sherpa config check`, `/sherpa phase`, and `/sherpa next` and confirmed successful runtime output for all four. This confirms the root arguments reach their intended operations in the active installation and that the Stage 1 phase/next routes still work. The specific transcript was not attached; no configuration values are inferred here. Earlier print-mode failures under the stale installation are retained as history and superseded by this manual verification.
+
+### Kilo Code
+
+Historical CLI invocations recognized and routed the then-existing `sherpa-config` and `sherpa-config-check` aliases, but the Python manager permission was rejected. Those aliases were later removed from the Stage 2 interface.
+
+Current root-argument invocations were then made with `kilo run --pure --command sherpa --format json config` and `... config check`. Both read `SKILL.md` and `core/commands/router.py`; Kilo's model explicitly identified CONFIG and CONFIG CHECK respectively. CONFIG attempted to inspect `.sherpa/` but the host auto-rejected the shell permission. CONFIG CHECK read the workflow and manager, then the host auto-rejected `python core/configuration/manager.py check`. Neither returned the expected report. No broad `--auto` approval was enabled. Root argument routing is observed; command completion fails on the host permission gate. No sherpa config or application file was changed by these attempts. The host added its own `.kilo/.gitignore` during historical testing; no new repository application changes were observed.
+
+### OpenCode
+
+The canonical command was invoked with `config` arguments before the current shared router was added, but the process returned no report and was stopped. The attempt created `.opencode/package.json`, a lockfile, and `node_modules/` in the disposable project. This violates the expected no-install behavior for that verification run; no second command was attempted. This historical failure does not establish current routing behavior. The framework repository was not modified by this attempt.
+
+## Regression and scope
+
+- Stage 1 static regression: **10/10 PASS**.
+- Stage 2 configuration suite: **12/12 PASS**.
+- Command routing suite: **PASS** for seven routes, unknown-operation handling, full-command/trailing-argument normalization, adapter contracts, and Stage 3 route exclusion.
+- Secret-safety scan: **PASS**, no findings; fixture tests confirm redaction and preservation of `UNKNOWN` values.
+- Python compile checks: **PASS** for five files.
+- `git diff --check`: **PASS**.
+- Lifecycle table: **20 phases**, unchanged.
+- The suites use temporary fixtures and do not establish host slash-command runtime behavior.
+- No application source or lifecycle file was modified; no Stage 3 work was performed.
+- External provider connectivity remains **UNKNOWN**.
+
+## Lock decision
+
+Stage 2 is **COMPLETE & LOCKED** based on the current Claude Code manual verification, passing repository acceptance suites, and unchanged 20-phase lifecycle. Kilo's current root-argument calls were observed routing to the intended operations but did not complete because the host rejected required tool permissions. OpenCode remains UNKNOWN for the current router and was not rerun because its prior startup installed host dependencies. These platform-specific limits remain disclosed; they do not invalidate the successful Claude Code lock evidence.
+