agentleFS
fortunto2fortunto2/solo-factory/CLAUDE.md

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

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
  1. Very specific:

    Run python3 scripts/add-openclaw-meta.py — idempotently adds openclaw: block to all SKILL.md files.

    line 117
  2. Very specific:

    All skills MUST use solo- prefix in SKILL.md frontmatter:

    line 151
  3. Very specific:

    Skill names: always solo-{skillname} in SKILL.md name: field

    line 164
  4. Very specific:

    No hardcoded paths: use ${CLAUDE_PLUGIN_ROOT} or relative paths for references

    line 167
  5. Distinctive:

    No dependencies — stdlib only (Python 3.10+).

    line 227
  6. Very specific:

    Don't forget to bump version before make plugin-publish

    line 231
  7. Very specific:

    Don't use bare skill names without solo- prefix

    line 232
  8. Distinctive:

    Don't hardcode absolute paths in skills

    line 233
  9. Very specific:

    Don't modify solo symlink (it maps .claude-plugin/ for cache compatibility)

    line 234

≈ “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.

Keep what fits and drop the rest. Your version, ready for your agents.
Files
CLAUDE.md

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 compatibility

Orchestrator Commands (commands/)

Commands are entry-point orchestrators following Command → Agent → Skill pattern:

CommandFlowPurpose
/devresearcher → /plan → /build → /reviewEnd-to-end feature development
/investigatecode-analyst → reproduce → fix → /reviewBug investigation and fix

Commands coordinate agents and skills — they don't do work themselves.

Rules (.claude/rules/)

RuleScopePurpose
ai-comments.mdAll filesAI-NOTE/TODO/ASK/PATTERN comment conventions
debugging.mdAll filesBackground task debugging, browser MCP for logs
routing.mdAll filesDirectory markers → next pipeline stage. Prompt-shape routing is the profile hook, not this file
harness-sensors.mdAll filesThe 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 commands

Publishing (3 Registries)

Skills are dual-compatible: Claude Code plugin + OpenClaw ClawHub. Each SKILL.md has metadata.openclaw block.

Registries

RegistryCommandAudience
Claude Code pluginmake plugin-publishClaude Code users (plugin marketplace)
ClawHubmake clawhub-publish S=nameOpenClaw users (clawhub.com)
npx skillsautomatic (from GitHub)Any AI agent (Cursor, Copilot, Gemini CLI, Codex)
All at oncemake publish-allPush 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 once

Always bump version before publishing. Claude Code compares version strings. ClawHub rejects duplicate versions.

How Claude Code plugin works

  1. git push → GitHub (fortunto2/solo-factory)
  2. Marketplace clone (~/.claude/plugins/marketplaces/solo/) synced via git fetch + reset
  3. claude plugin install solo@solo --scope user → copies to cache
  4. New session picks up updated skills

How ClawHub works

  1. clawhub login (one-time, GitHub OAuth)
  2. clawhub publish skills/<name> --slug solo-<name> --version <ver> → published to clawhub.com
  3. Users install via clawhub install solo-<name> or clawhub sync
  4. 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 instant

Adding 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.md name: field
  • Version: bump in .claude-plugin/plugin.json before every publish; marketplace.json and pyproject.toml follow via scripts/check-version --fix; CHANGELOG.md gets 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.sh passes --mcp-config ~/.mcp.json so solograph tools work in --print sessions
  • Codex optional: solo-codex.sh runs OpenAI Codex CLI for review/test/fix — reads AGENTS.md in project root
  • Factory Critic / Evolution Loop: /retro Phase 10 runs factory critique (opus evaluates skills/scripts/pipeline), solo-codex.sh --factory adds independent Codex critique. Both append structured defects to ~/.solo/evolution.md. Use make evolve to view, make evolve-apply to fix interactively, make factory-critique P=project to 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.

PlacementRunsBlocks?
PostToolUse on Edit|Write (hooks/sensor-edit.sh)Syntax of the one file just written, <1sno, injects context
Stop (hooks/sensor-stop.sh)solo-verify --fullyes, 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 at
  • HARNESS TOUCHED — test files and lint configs in the change, with sha256
  • Exit 0 pass · 0 partial (something ran, something could not — the word carries it, not the code) · 1 fail · 2 unknown (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 output

Algorithm: 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 solo symlink (it maps .claude-plugin/ for cache compatibility)

Download now (ZIP)

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
What did you use it for? e.g. Reviewing pull requests in a Rails app

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.