A solo-dev framework for Claude Code

kss — Keep Shit Simple

Session-driven workflow with reduced ceremony. 13 skills, 6 layers, one rule: never auto-commit.

v0.4.0 · fnneves/kss-plugins · MIT
Why another framework?

Most agent frameworks have ceremony you don't need.

Solo dev. One brain. The collaboration tax doesn't apply.

×

Multi-agent orchestrators expect a team. You're not a team.

×

Heavy state machines expect a PM. You're the PM and the IC.

×

Generated docs expect compliance. The only auditor is future-you, in three weeks.

I wanted shit, just simpler.

Three commitments

File-based state. Markdown skills. Detect & offer.

01File-based state

Everything lives under .kss/ as plain markdown. Grep it. Diff it. Commit it. State survives the framework.

02Markdown skills

Every skill is one SKILL.md. Open it. Edit it. Fork the marketplace. No compiled code, no hidden rules.

03Detect & offer

Skills detect a condition and offer the next move behind a one-keystroke confirm — never auto-fire, never auto-commit. Less ceremony, still your call.

What's in the box

13 skills across 6 layers.

You only invoke what the situation demands. There's no orchestrator running them in sequence.

Setup

2
scaffold-project
map-codebase
Bootstrap once per project; refresh after major refactors.

Lifecycle

3
new-topic
plan-milestone
complete-milestone
Topics isolate work tracks; milestones scope finite chunks inside.

Session

3
start-session
spike
wrap-up
Bookend each work session; spike when an idea needs testing first.

Knowledge

2
capture
distill
Park ideas with triggers; promote durable insights to the canonical KB.

Meta

1
skill-autopsy
The self-improvement loop — fix skills that misfire. See next slide.

Utilities

2
explore-html
explore-notebook
On-demand HTML artifacts (this deck included); explore-notebook is the served, live-reload sibling with a LAN URL and two-way feedback.

No skill ever runs git commit. Every artifact is a file you review before any commit happens.

The distinctive part

When a skill misfires, you fix it.

Most agent frameworks ship rigid skills. When one consistently misfires, the friction recurs forever. kss treats your frustration as the input to the next iteration of the skill.

1
A skill underperforms → /kss:skill-autopsy <name>. It interviews you and appends a short report at ~/kss-skill-reports/<skill>.md.
2
Reports accumulate as you use the skill. Past 4 reports, autopsy offers to consolidate.
3
Consolidate mode reads all reports, looks for recurring root causes, and proposes a concrete diff against the skill's SKILL.md. If reports share no pattern, it says so honestly instead of inventing fixes.
4
If ~/.kss-source points to your fork → diff is applied + reports cleared. Otherwise → diff is printed for you to handle manually. You commit and push on your own time.

The framework is the friction you remember to fix.

If this looks useful

Install + first commands.

Inside Claude Code. Three lines to install, five to scaffold your first project.

# add the marketplace + install
/plugin marketplace add fnneves/kss-plugins
/plugin install kss@kss-plugins

# your first project
/kss:scaffold-project     # once per project
/kss:map-codebase         # once per major refactor
/kss:new-topic            # when starting unrelated work
/kss:plan-milestone       # when scoping a chunk
/kss:start-session        # at session start
→ github.com/fnneves/kss-plugins
1 / 6
← → · space