CtrlK
BlogDocsLog inGet started
Tessl Logo

shep-workstreams

Use when a large body of work (a version milestone, an epic, a roadmap, a set of PRDs/design docs) needs to be broken into parallel workstreams and executed with the shep CLI. Triggers include "break this down", "split into workstreams", "plan V6", "what should we build first", "run these in parallel", "dependency graph", "merge order", "worktree split", or any request to turn planning docs into running shep features. Produces a workstream plan first, then drives `shep feat new` / `shep feat start` wave by wave. Part of the Shep autonomous SDLC platform — https://shep.bot

75

Quality

92%

Does it follow best practices?

Run evals on this skill

Adds up to 20 points to the overall score

View guide

SecuritybySnyk

Passed

No findings from the security scan

SKILL.md
Quality
Evals
Security

Quality

Content

88%Weight 40%Scale 1-5

Reviews the quality of instructions and guidance provided to agents. Good implementation is clear, handles edge cases, and produces reliable results.

A well-structured orchestration skill: the two-phase workflow with an explicit approval gate, executable shep command examples covering the common wave patterns, and appropriately pushed-out reference files. The main issues are a missing referenced file (`templates/workstream-plan.md` does not exist in the bundle), some repetition between the mechanics section and the anti-patterns list, and inline CLI semantics that duplicate the cli-reference.

Suggestions

Add the referenced `templates/workstream-plan.md` to the bundle (or drop the reference) — Phase 1 Step 4 tells the agent to use it, but the file does not exist, so the agent cannot follow the instruction.

Consolidate the redundancy between the '--parent' mechanics paragraph and the anti-patterns list ('Everything parented to everything' / 'Hand-rolled git worktree add' restate points already made in 'The mechanics that matter'), trimming roughly a paragraph of tokens.

Consider moving the detailed '--parent' auto-rebase/unblocking semantics to `references/cli-reference.md` and keeping only the decision table inline, since the body already directs the reader there before composing commands.

DimensionReasoningScore

Conciseness

The body is dense with non-obvious, shep-specific guidance (parent/auto-rebase semantics, file-ownership partitioning rule, staged waves) and avoids explaining concepts Claude already knows, but there is noticeable redundancy: '--parent is not a substitute for good partitioning' reappears as the 'Everything parented to everything' and 'Hand-rolled git worktree add' anti-patterns, and the two-phase separation is stated three times. It sits between the level-3 'could be tightened' and level-5 'every token earns its place' anchors — efficient with minor trims available, i.e. level 4.

4 / 5

Actionability

The bash examples are copy-paste ready apart from unavoidable placeholder ids: full 'shep feat new ... --repo ... --attach ... --push --pr' invocations for the foundation, dependent, independent, and capacity-staged cases, plus a complete monitoring command block ('shep feat ls / show / logs / approve / reject / resume') and a decision table mapping each dependency situation to a mechanism. The examples cover the common cases exactly as the level-5 anchor requires.

5 / 5

Workflow Clarity

The two phases are hard-separated with an explicit validation gate ('Do not create a single feature until Phase 1 is written down and the user has approved it'), Phase 1 is a numbered five-step sequence ending in 'Stop and get approval', and Phase 2 includes a feedback loop ('After each merge, re-check `shep feat ls`', plus reject/resume handling for failed features) and a decision table for choosing the dependency mechanism. This matches the level-5 anchor of a clear sequence with explicit validation steps and feedback loops; level 4 would have missing checkpoints, which is not the case here.

5 / 5

Progressive Disclosure

Structure is good: the deep material (full partitioning rubric, full CLI flag reference, PM/work-item commands) is pushed to `references/partitioning.md` and `references/cli-reference.md`, both real bundle files, clearly signaled with when to read them ('Read it before composing commands'), and one level deep. However, the body instructs 'Use `templates/workstream-plan.md`' and no such file exists in the bundle — a broken reference — and the long '--parent' auto-rebase mechanics paragraph duplicates cli-reference material. Good structure with a concrete organization gap places it at level 4 rather than 5.

4 / 5

Total

18

/

20

Passed

Description

96%Weight 40%Scale 1-5

Based on the skill's description, can an agent find and select it at the right time? Clear, specific descriptions lead to better discovery.

A strong frontmatter description: it explicitly states what the skill does and when to use it, includes a rich set of natural trigger phrases, and specifies the exact shep commands involved. The only weakness is that a few trigger phrases are generic enough that the skill might fire for plain planning requests that don't involve shep.

DimensionReasoningScore

Specificity

The description names multiple concrete, specific actions with the exact commands involved: 'needs to be broken into parallel workstreams and executed with the shep CLI', 'Produces a workstream plan first, then drives `shep feat new` / `shep feat start` wave by wave'. These cover the skill's full capability surface comprehensively, matching the anchor for multiple specific concrete actions rather than the level-4 anchor's 'minor gaps in coverage'.

5 / 5

Completeness

It opens with an explicit 'Use when a large body of work (a version milestone, an epic, a roadmap, a set of PRDs/design docs) needs to be broken into parallel workstreams' trigger and states what it does ('Produces a workstream plan first, then drives `shep feat new` / `shep feat start` wave by wave'). Both what and when are explicit and concrete, exactly the level-5 anchor; level 4 would mean the 'when' was only adequate rather than fully specified.

5 / 5

Trigger Term Quality

It lists a broad set of natural phrases a user would actually say — 'break this down', 'split into workstreams', 'plan V6', 'what should we build first', 'run these in parallel', 'dependency graph', 'merge order', 'worktree split' — plus a catch-all ('any request to turn planning docs into running shep features'). This comprehensively covers natural terms and their variations, matching the level-5 anchor; level 4 would require noticeable missing natural terms.

5 / 5

Distinctiveness Conflict Risk

The niche is clear — shep-CLI workstream execution with distinctive triggers like 'worktree split' and 'merge order' — but several trigger phrases ('break this down', 'what should we build first', 'run these in parallel') are generic planning/prioritization language that a user could say without wanting the shep platform, creating minor overlap risk with general planning or task-breakdown skills. It is mostly distinct with minor overlap risk (level 4), not a fully clean niche (level 5).

4 / 5

Total

19

/

20

Passed

Validation

100%

Checks the skill against the spec for correct structure and formatting. All validation checks must pass before discovery and implementation can be scored.

Validation — 16 / 16 Passed

Validation for skill structure

No warnings or errors.

Repository
shep-ai/shep
Reviewed

Table of Contents

Is this your skill?

If you maintain this skill, you can claim it as your own. Once claimed, you can manage eval scenarios, bundle related skills, attach documentation or rules, and ensure cross-agent compatibility.