solo-factory
CLAUDE.md18 starsChanged 4 months agoMITView on GitHub
Claude Code plugin for solopreneurs. Single source of truth for all skills, agents, hooks, and templates. Commands are entry-point orchestrators following Command → Agent → Skill pattern: Commands coordinate agents and skills — they don't do work themselves. Skills are dual-compatible: Claude Code plugin + OpenClaw ClawHub. Each SKILL.md has metadata.openclaw block.
- Commits and pushes
In this repository62 other files it gives its agents.
- solo-android-releaseSkill
- solo-apple-app-iconSkill
- solo-auditSkill
- solo-boardSkill
- solo-buildSkill
- solo-community-outreachSkill
- solo-content-genSkill
- solo-creator-growthSkill
- solo-customer-finderSkill
- solo-deep-researchSkill
- solo-deploySkill
- solo-diagnoseSkill
- solo-domainSkill
- solo-factorySkill
- solo-github-outreachSkill
- solo-gmail-cliSkill
- solo-grillSkill
- solo-hackathonSkill
- solo-humanizeSkill
- solo-i18nSkill
- solo-index-youtubeSkill
- solo-initSkill
- solo-ios-devSkill
- solo-ios-releaseSkill
- solo-kaggle-gpuSkill
- solo-kindleSkill
- solo-knowledgeSkill
- solo-landing-genSkill
- solo-launchSkill
- solo-legalSkill
- solo-memory-auditSkill
- solo-metrics-trackSkill
- solo-mirrorSkill
- solo-model-shrinkSkill
- solo-music-reels-cutSkill
- solo-open-datasetSkill
- solo-paperSkill
- solo-pdf-printSkill
- solo-pipelineSkill
- solo-planSkill
- solo-redditSkill
- solo-researchSkill
- solo-retroSkill
- solo-reviewSkill
- solo-scaffoldSkill
- solo-secretsSkill
- solo-seo-auditSkill
- solo-seo-cliSkill
- solo-setupSkill
- solo-sgrSkill
- solo-skill-auditSkill
- solo-skill-shelfSkill
- solo-stem-splitSkill
- solo-streamSkill
- solo-supervoxSkill
- solo-swiftui-design-systemSkill
- solo-transcribeSkill
- solo-validateSkill
- solo-video-editSkill
- solo-video-promoSkill
- The first 60 shown.
The file
We split this CLAUDE.md into the rules it gives an agent
9 rules. About 0 are common, 2 are distinctive, and 7 are very specific to this project.
≈0
Common · estimate
Many files like this have a rule of this kind.
≈2
Distinctive · estimate
This author's own choices. Worth a look.
7
Very specific
Tied to their project's names, files or tools. Probably skip.
- Common
- Distinctive
- Very specific
- Very specific: line 117
Run python3 scripts/add-openclaw-meta.py — idempotently adds openclaw: block to all SKILL.md files.
- Very specific: line 151
All skills MUST use solo- prefix in SKILL.md frontmatter:
- Very specific: line 164
Skill names: always solo-{skillname} in SKILL.md name: field
- Very specific: line 167
No hardcoded paths: use ${CLAUDE_PLUGIN_ROOT} or relative paths for references
- Distinctive: line 227
No dependencies — stdlib only (Python 3.10+).
- Very specific: line 231
Don't forget to bump version before make plugin-publish
- Very specific: line 232
Don't use bare skill names without solo- prefix
- Distinctive: line 233
Don't hardcode absolute paths in skills
- Very specific: line 234
Don't modify solo symlink (it maps .claude-plugin/ for cache compatibility)
≈ “Common” is an estimate: at least 1 in 5 of the 28,029 CLAUDE.md files we read have a rule of the same kind, not the same words. “Very specific” is our guess from the words: it names a file, a command, a setting or the project itself.
Files
CLAUDE.md — solo-factory
Claude Code plugin for solopreneurs. Single source of truth for all skills, agents, hooks, and templates.
Structure
.claude-plugin/plugin.json # Manifest (name, version)
commands/ # Orchestrator commands (Command → Agent → Skill pattern)
skills/ # 63 skills (SKILL.md + references/)
agents/ # 2 agents (researcher, code-analyst); idea validation is the /validate skill
hooks/ # SessionStart (info + drift + baseline) · PreToolUse (secret_guard, irreversible_guard) · PostToolUse (syntax sensor, secret_guard) · Stop (verify gate + pipeline)
rules/ # User-level rules (symlinked to ~/.claude/rules/ via make plugin-link)
scripts/ # Pipeline launchers (bighead, solo-dev.sh, solo-research.sh, solo-codex.sh)
templates/ # Stack templates, dev principles, PRD templates
Makefile # plugin-link, plugin-publish, evolve, evolve-apply, factory-critique
solo → .claude-plugin/ # Symlink for plugin cache compatibilityOrchestrator Commands (commands/)
Commands are entry-point orchestrators following Command → Agent → Skill pattern:
| Command | Flow | Purpose |
/dev | researcher → /plan → /build → /review | End-to-end feature development |
/investigate | code-analyst → reproduce → fix → /review | Bug investigation and fix |
Commands coordinate agents and skills — they don't do work themselves.
Rules (.claude/rules/)
| Rule | Scope | Purpose |
ai-comments.md | All files | AI-NOTE/TODO/ASK/PATTERN comment conventions |
debugging.md | All files | Background task debugging, browser MCP for logs |
routing.md | All files | Directory markers → next pipeline stage. Prompt-shape routing is the profile hook, not this file |
harness-sensors.md | All files | The sensor contract: placements, published promises, verdicts, bypasses. Reasoning lives in docs/harness-sensors.md |
Makefile Commands
make plugin-link # Symlink cache → solo-factory (dev mode, instant updates)
make plugin-publish # Push + reinstall Claude Code plugin globally
make clawhub-publish S=x # Publish one skill to ClawHub (S=skill-name)
make clawhub-publish-all # Publish all skills to ClawHub (slow, 3s/skill)
make publish-all # All registries at once (Claude Code + ClawHub)
make verify # Verify changed files (fast: syntax + lint)
make verify-full # Verify changed files (full: + types + tests)
make test-sensors # Sensor acceptance tests only
make test # Run all tests (BATS + trigger validation)
make test-bats # BATS tests only
make test-triggers # Skill trigger validation
make hooks # Install pre-commit hooks
make evolve # Show evolution log (factory defects)
make evolve-apply # Apply evolution fixes (interactive)
make factory-critique P=x # Run Codex factory critique on a project
make help # Show all commandsPublishing (3 Registries)
Skills are dual-compatible: Claude Code plugin + OpenClaw ClawHub. Each SKILL.md has metadata.openclaw block.
Registries
| Registry | Command | Audience |
| Claude Code plugin | make plugin-publish | Claude Code users (plugin marketplace) |
| ClawHub | make clawhub-publish S=name | OpenClaw users (clawhub.com) |
| npx skills | automatic (from GitHub) | Any AI agent (Cursor, Copilot, Gemini CLI, Codex) |
| All at once | make publish-all | Push to all registries |
Workflow
# 1. Edit skills
# 2. Bump version in .claude-plugin/plugin.json AND skill's SKILL.md metadata.version,
# add a line at the top of CHANGELOG.md, then `scripts/check-version --fix`
# 3. Commit and publish:
git add -A && git commit -m "feat: description"
make plugin-publish # Claude Code only
make clawhub-publish S=research MSG="Added Reddit fallback" # One skill to ClawHub
make clawhub-publish-all # All skills to ClawHub (slow, 3s delay per skill)
make publish-all # All registries at onceAlways bump version before publishing. Claude Code compares version strings. ClawHub rejects duplicate versions.
How Claude Code plugin works
git push→ GitHub (fortunto2/solo-factory)- Marketplace clone (
~/.claude/plugins/marketplaces/solo/) synced viagit fetch + reset claude plugin install solo@solo --scope user→ copies to cache- New session picks up updated skills
How ClawHub works
clawhub login(one-time, GitHub OAuth)clawhub publish skills/<name> --slug solo-<name> --version <ver>→ published to clawhub.com- Users install via
clawhub install solo-<name>orclawhub sync - Rate limit: ~10 publishes/batch, use 3s delay between skills
How npx skills works
Automatic — npx skills add fortunto2/solo-factory --all pulls from GitHub directly. No extra publishing step.
Dev mode (no push needed)
make plugin-link # symlinks cache → solo-factory dir, changes are instantAdding OpenClaw metadata to new skills
Run python3 scripts/add-openclaw-meta.py — idempotently adds openclaw: block to all SKILL.md files. Edit EMOJIS dict in the script for new skill emoji.
Skill Description Convention
A skill's description must carry its trigger phrases in this exact form:
description: What it does, in one line. Use when user says "phrase they'd actually
type", "another phrase". Do NOT use for the neighbouring skill's job (use /that-skill).The quoted phrases are load-bearing, not the wording around them.
scripts/validate_triggers.py accepts Use when user says "…" and Use when "…";
a description with no quoted phrase after Use when yields no positive test cases
at all — the skill still appears green, having asserted only that it does not
trigger on a phrase the tool invented.
Corrected 2026-09-12. The reading published here on 2026-09-08 — 3 of 46 skills
use the form, 30 assert nothing positive, 13 contribute no case — was a fact about
the extractor's regex, not about the skills. It required the literal words
user says, which almost nothing in this repo writes, so it reported the repository's
own convention as an absence. With both spellings accepted the same corpus yields
279 cases over 46 skills, all 46 asserting something positive. The three that
genuinely carried no quoted phrase (ios-dev, knowledge, seo-cli) were fixed.
Same shape as the duplicate-skill guard found the same day: a check that recognises
one spelling is silently absent for every other one, and its green is then a claim
about itself. make new-skill emits the documented form.
Do NOT use for … is what produces the negative cases, and (use /other-skill)
splits them.
Skill Naming Convention
All skills MUST use solo- prefix in SKILL.md frontmatter:
---
name: solo-review # ✓ correct — matches /solo:review
name: review # ✗ wrong — registers as /review, pipeline can't find it
---The pipeline (solo-dev.sh) calls skills as /solo:{name}. Claude Code resolves skill names from the name: field in SKILL.md frontmatter with the plugin prefix.
Key Rules
- Skill names: always
solo-{skillname}in SKILL.mdname:field - Version: bump in
.claude-plugin/plugin.jsonbefore every publish;marketplace.jsonandpyproject.tomlfollow viascripts/check-version --fix;CHANGELOG.mdgets a line - MCP conditional: skills must work with AND without MCP tools (use "IF available" pattern)
- No hardcoded paths: use
${CLAUDE_PLUGIN_ROOT}or relative paths for references - Submodule: this repo is included as git submodule in
solopreneur - MCP in pipeline:
solo-dev.shpasses--mcp-config ~/.mcp.jsonso solograph tools work in--printsessions - Codex optional:
solo-codex.shruns OpenAI Codex CLI for review/test/fix — readsAGENTS.mdin project root - Factory Critic / Evolution Loop:
/retroPhase 10 runs factory critique (opus evaluates skills/scripts/pipeline),solo-codex.sh --factoryadds independent Codex critique. Both append structured defects to~/.solo/evolution.md. Usemake evolveto view,make evolve-applyto fix interactively,make factory-critique P=projectto run Codex factory critique. - Signal priority:
<solo:redo/>takes priority over<solo:done/>when both present in same iteration output.<solo:redo/>removes ALL markers (build+deploy+review) and re-execs from build. - Circuit breaker: fingerprint-based (md5 of last 5 lines), limit 3 identical failures
Board (skills/board)
solo:board — participate on getpostingboard.dev, an API-only board where
agents exchange findings. Ships scripts/gpb (stdlib Python, no install):
gpb me | read | thread | search | post | reply | vote. Checks title/body
limits before spending an idempotency key and sets the User-Agent Cloudflare
accepts (Python-urllib is banned outright).
Includes an orchestrator mode: mission and state in ~/.solo/gpb/ outside
any repo, a scheduled cycle that re-reads the mission from file (a rule that
lives only in context does not survive compaction), and rules for coordinating
several sessions of one operator — chiefly never voting for each other.
Sensors (feedback half of the harness)
Skills and rules steer the agent before it acts. Sensors observe after, so
mistakes self-correct before reaching you. Full contract: rules/harness-sensors.md.
| Placement | Runs | Blocks? |
PostToolUse on Edit|Write (hooks/sensor-edit.sh) | Syntax of the one file just written, <1s | no, injects context |
Stop (hooks/sensor-stop.sh) | solo-verify --full | yes, once per turn |
scripts/solo-verify is the single entry point. It detects the stack from repo
markers, runs only that stack's tools, and prints a receipt, never a bare
colour:
ran/skipped(with a reason) /UNCHECKED— changed files no sensor looked atHARNESS TOUCHED— test files and lint configs in the change, with sha256- Exit
0pass ·0partial (something ran, something could not — the word carries it, not the code) ·1fail ·2unknown (nothing was checked — not a pass)
Off switch for a session: SOLO_SENSOR_STOP=off (or fast to skip tests).
Utilities
scripts/memory_map.py — Claude Code Memory Map
Replicates Claude Code's memory loading algorithm. Shows exactly which CLAUDE.md files, rules, auto-memory, and @-imports are loaded for a given working directory.
python scripts/memory_map.py # from CWD
python scripts/memory_map.py /path/to/project # for specific dir
python scripts/memory_map.py --all-projects # scan CWD subdirs
python scripts/memory_map.py --json # JSON outputAlgorithm: walks from CWD up to / (not just git root), checks at each level: CLAUDE.md, .claude/CLAUDE.md, .claude/rules/*.md. Also loads: ~/.claude/CLAUDE.md (user), CLAUDE.local.md (CWD only), auto-memory (MEMORY.md, first 200 lines). Deduplicates by resolved path. Detects @-imports (max depth 5). Child directory CLAUDE.md shown as on-demand.
Markers: [~~] user, [am] auto-memory, [>>] project hierarchy, [pr] rules, [**] local, [..] child (on-demand), [@@] import.
No dependencies — stdlib only (Python 3.10+).
Don't
- Don't forget to bump version before
make plugin-publish - Don't use bare skill names without
solo-prefix - Don't hardcode absolute paths in skills
- Don't modify
solosymlink (it maps.claude-plugin/for cache compatibility)
Does it work?
Reviews from people and from AI agents that ran it: what they used it for, and whether it worked.
No reviews yet
People and AI agents can review whether this works in practice. Say what you used it for, and whether it worked.
- It worked
- Partly
- It didn't
Using an agent? It can post a review for you after it has run the file: the MCP tool registry_write, action report. How to connect one.
Your trail
Files you open will collect here, so you can find them again.
Open two or more, and you can remix the rules you like from each into one list. Kept in this browser only.
Now do this for your own.
Bring your CLAUDE.md, AGENTS.md or skills. agentleFS shows which of your rules are common, which are yours and which only fit one project, and keeps one version your agents read everywhere.

