Skip to content

plan.md

Latest commit

 

History

History
148 lines (122 loc) · 6.18 KB

plan.md

File metadata and controls

148 lines (122 loc) · 6.18 KB

Works On My Machine Skills — Plan

Repo Structure

Each skill is a directory with a SKILL.md file containing YAML frontmatter and markdown instructions.

worksonmymachine-skills/
├── .claude-plugin/
│   └── marketplace.json              # Plugin manifest — lists all skills
│
├── skills/
│   ├── design-doc/
│   │   ├── SKILL.md
│   │   └── references/
│   │       └── design-doc-template.md
│   ├── epic-breakdown/
│   │   ├── SKILL.md
│   │   └── references/
│   │       ├── epic-template.md
│   │       ├── epics-hub-template.md
│   │       └── story-sizing.md
│   ├── implementation-plan/
│   │   ├── SKILL.md
│   │   └── references/
│   │       └── plan-template.md
│   ├── implement/
│   │   ├── SKILL.md
│   │   └── references/
│   │       └── implementation-workflow.md
│   ├── golden-spec-create/
│   │   ├── SKILL.md
│   │   └── references/
│   │       └── golden-spec-template.md
│   ├── about/
│   │   └── SKILL.md
│   ├── upstream-sync/
│   │   ├── SKILL.md
│   │   └── references/
│   │       └── sync-workflow.md
│   └── fork-share/
│       ├── SKILL.md
│       └── references/
│           └── manifest-format.md
│
├── golden-specs/                     # Knowledge base — read directly from ~/.womm-skills/golden-specs/
│   ├── RAILS_AWS_TERRAFORM.md        # Starter content (ships with repo)
│   ├── RAILS_STRIPE_INTEGRATION.md   # User adds their own over time
│   └── README.md
│
├── docs/                             # Project documentation
│   ├── motivation-and-design.md
│   ├── plan.md
│   ├── epics.md
│   ├── website-plan.md
│   └── epics/                        # Individual epic specs
│
├── website/                          # skills.worksonmymachine.ai
│
├── CLAUDE.md
├── README.md
├── LICENSE
└── CONTRIBUTING.md

Skills (8 total)

Process Skills (5) — The build → capture → learn loop

Skill What It Does Reference Files
design-doc Deep interview → structured design document design-doc-template.md
epic-breakdown Design doc → epics with stories, dependencies, and risk ordering epic-template.md, epics-hub-template.md, story-sizing.md
implementation-plan Epic or phase → detailed technical plan (patterns, files, decisions) plan-template.md
implement Epic → story-by-story execution with tests and commits implementation-workflow.md
golden-spec-create Solved problem → golden spec document golden-spec-template.md

Fork Lifecycle Skills (3) — Stay in sync, share what you build

Skill What It Does Reference Files
about Version, links, community, installed skills, fork status —
upstream-sync Selectively pull upstream changes without losing customizations sync-workflow.md
fork-share Generate structured summary of what your fork changed and why manifest-format.md

Skills vs Golden Specs: Two Different Mechanisms

  • Skills = installed via plugin system, cached, available everywhere. Reinstall when upstream adds new skills.
  • Golden specs = flat markdown files at ~/.womm-skills/golden-specs/, referenced by ~/.claude/CLAUDE.md. Read directly — no reinstall needed. Write a new one and it's available in every project immediately.

This separation exists because the plugin system copies files to cache (designed for static suites), but golden specs need to grow over time. Skills change rarely; golden specs change constantly.

Convention Over Configuration

  • Repo location: ~/.womm-skills/ (clone destination)
  • Golden specs: ~/.womm-skills/golden-specs/ (read directly, not cached)
  • Global reference: ~/.claude/CLAUDE.md points at the golden specs directory
  • Upstream remote: upstream (standard git convention)
  • Sync marker: .womm-upstream-sync in repo root
  • Fork metadata: womm-manifest.json (generated by fork-share)

Golden Specs Access Check

All skills should check that ~/.womm-skills/golden-specs/ is accessible. If not, instruct the user to:

  1. Add the path to ~/.claude/settings.json (file access permissions)
  2. Add a reference in ~/.claude/CLAUDE.md pointing to the golden specs directory

Installation

Claude Code only. Fork-first.

# 1. Fork the repo on GitHub
# 2. Clone your fork to ~/.womm-skills/
git clone https://github.com/YOU/womm-skills ~/.womm-skills
cd ~/.womm-skills
# 3. Install skills as Claude Code plugin
claude /plugin install .
# 4. Add golden specs access to your global Claude config
#    Add to ~/.claude/settings.json allowedTools or permissions:
#    Allow read/write access to ~/.womm-skills/
#
#    Add to ~/.claude/CLAUDE.md:
#    "Reference golden specs at ~/.womm-skills/golden-specs/ for battle-tested
#    patterns and gotchas. When you solve a problem worth documenting, use
#    /golden-spec-create to write a new spec to this directory."
# 5. Done. Skills are available everywhere. Golden specs accumulate over time.

How It Works

  • Skills (stable) are installed via the plugin system. They're cached and available in every project.
  • Golden specs (growing) live at ~/.womm-skills/golden-specs/ and are read directly via the ~/.claude/CLAUDE.md reference. No reinstall needed when you add new ones.
  • Plugin reinstall is only needed when upstream adds new skills (not for golden specs).

Alternative: copy skills/ into your project's .claude/skills/ directory.

Phased Build Plan

Phase 0 — Infrastructure

Repo scaffolding, plugin manifest, CLAUDE.md, README, LICENSE, about skill.

Phase 1 — Core Process & Fork Lifecycle Skills

design-doc, epic-breakdown, implementation-plan, implement, golden-spec-create, upstream-sync, fork-share

Phase 2 — Starter Content

Starter golden specs (Rails+AWS+Terraform, Stripe Subscriptions)