shifu

KO | EN

gitlite — search

#typescript #ai-agents #ai #dsh-plugin #deepseek-harness #open-source #cli #claude-code #codex #developer-tools #react #windows

★ 37 Open GitHub ↗

No description available.

// repository documentation

Was this content helpful?

★ 0 (0 ratings)

# shifu

[![skills.sh](https://skills.sh/b/vikingmute/shifu)](https://skills.sh/vikingmute/shifu)

An agent skill that decomposes complex tasks into self-contained specs for cheaper models to execute.

The idea: use your most capable model for the part where intelligence compounds — understanding the full task, judging decomposition boundaries, writing unambiguous specs — and hand execution to cheaper models. The skill never implements anything itself. The spec is the product.

```
you          →  /shifu                      (expensive model, plans)
plans/       →  001-add-auth-middleware.md   (self-contained specs)
other agent  →  implements, tests, ships    (cheap model, executes)
```

## Install

```bash
npx skills add vikingmute/shifu
```

Works in any agent that supports [Agent Skills](https://skills.sh) format. The specs it writes are plain markdown, so any agent (or human) can pick them up.

## Usage

```
/shifu <description>                        analyze → decompose → spec
/shifu quick <description>                  lightweight: fewer sub-tasks, less analysis
/shifu deep <description>                   exhaustive: fine-grained decomposition
/shifu execute <plan-id>                    dispatch a worker, review its output
/shifu execute <plan-id> --model <model>    use a specific model for the worker
/shifu execute all                          dispatch all ready specs in dependency order
/shifu execute all --model <model>          all specs, specific model
/shifu review <plan-id>                     critique and tighten an existing spec
/shifu status                               show state of all plans
/shifu reconcile                            verify done, unblock stuck, retire completed
```

## How to use

### Automated (Cursor, Codex, Claude Code, ...)

Most modern agents can spawn subagents. Shifu uses this to run the full plan-dispatch-review loop without leaving your session:

1. `/shifu add JWT authentication to this Express app`
2. Shifu reads the repo and presents a decomposition table. You confirm which sub-tasks to spec.
3. `/shifu execute all --model gpt-5.4-mini` — shifu dispatches a cheap worker for each spec, reviews every diff against the plan, and reports a verdict per sub-task. Merging stays up to you.
4. Next session: `/shifu reconcile` refreshes the backlog.

You stay in one session. Shifu handles the planner-worker coordination automatically — picking the right subagent type for each strategy, passing the self-contained spec, and reviewing the output.

### Manual (any agent, any environment)

No subagent support? The specs are plain markdown — they work anywhere:

1. `/shifu add JWT authentication to this Express app`
2. Shifu reads the repo, presents the decomposition. You confirm.
3. Specs land in `plans/` — one file each, plus an index with dependency order and status.
4. Open a separate session with a cheaper model, paste or point it at `plans/001-*.md`. It has everything it needs: context, steps, verification commands, boundaries.
5. Come back and run `/shifu reconcile` to verify what landed and retire completed work.

The specs are designed to be copy-pasteable — all context inlined, no reference to the planner session.

## How it works

**Understand.** Maps just enough context for the specific task — repo structure, conventions, build/test/lint commands (these become verification gates in every spec). No unnecessary full-codebase audit.

**Decompose.** Breaks the task into ordered, dependency-aware sub-tasks. Each one gets an execution strategy:

| Strategy | When | How |
|----------|------|-----|
| **direct** | Sequential deps, low-risk changes, most tasks | Worker runs in current directory |
| **worktree** | High-risk refactors, parallel exploration | Worker runs in isolated git worktree |
| **explore** | Research, code analysis, information gathering | Read-only worker |

**Spec.** One file per sub-task, written for the weakest plausible executor:

- **Self-contained.** All context inlined: file paths, current-state code excerpts, repo conventions with exemplar snippets. No "as discussed above."
- **Verification gates.** Every step ends with a command and expected output. Done criteria are machine-checkable.
- **Hard boundaries.** Explicit in-scope and out-of-scope lists. STOP conditions instead of letting a small model improvise.

Each spec stamps the git commit it was written against for drift detection.

**Review.** After execution, shifu reviews the worker's output like a tech lead — re-runs done criteria, checks scope compliance, reads the diff. Verdict: approve, revise (max 2 rounds), or block and refine the spec.

## Works across agent environments

Shifu's execution strategies (direct / worktree / explore) are semantic — they automatically map to the right subagent API in each host:

| Strategy | Cursor | Codex | Claude Code |
|----------|--------|-------|-------------|
| direct | `generalPurpose` | `worker` | subagent |
| worktree | `best-of-n-runner` | `worker` (isolated) | subagent (worktree) |
| explore | `explore` (readonly) | `explorer` | read-only subagent |

You don't need to know the underlying API. To control cost, use `--model`:

```
/shifu execute 001 --model gpt-5.4-mini
/shifu execute all --model composer-2.5-fast
```

No subagent support? Shifu outputs specs as plain markdown files — copy-paste them into any agent session.

## What makes it different from [improve](https://github.com/shadcn/improve)

| | shifu | improve |
|---|---|---|
| **Scope** | Any complex task | Codebase auditing |
| **Starting point** | User's intent | Problem discovery |
| **Execution** | Adaptive (direct / worktree / explore) | Always isolated worktree |
| **Granularity** | Adapts to task complexity | 9 fixed audit categories |
| **Direction** | Bidirectional (build + fix) | Find problems → plan fixes |

Shifu is task-agnostic: building features, refactoring, migrations, research, documentation, debugging, or any complex work. It starts from what you want to do, not from what's wrong.

## Hard rules

- Never modifies source code itself. The only writes go to `plans/`.
- Never runs commands that mutate the working tree — read, search, and read-only analysis only.
- Never reproduces secret values. Locations and credential types only.
- Asked to implement? It declines and points at the spec.

## License

MIT

shifu

Explore Similar Repositories

Was this content helpful?

Recent Feedback

Download README