Skip to content

CLAUDE.md

Latest commit

 

History

History
95 lines (70 loc) · 3.91 KB

CLAUDE.md

File metadata and controls

95 lines (70 loc) · 3.91 KB
Raw

CLAUDE.md

Spec-driven development CLI plus a Claude Code plugin. Specs are the source of truth; code serves specs.

What spexl Is

Two parts shipped from this one repo:

  1. CLI – plumbing for spec management: init, new, changes, info, archive, validate, refs, link, unlink. No skill installation, no priming -- those moved to the plugin.
  2. Claude Code plugin – skills/, agents/, plugins/claude/hooks/ at the repo root, plus .claude-plugin/plugin.json. Users install it via Claude Code's plugin mechanism. The SessionStart hook cats plugins/claude/hooks/prime.md to prime the agent at session start.

The plugin tree is generated by shablon from .shablon/templates/. Edit templates, run just plugins (= shablon generate), commit both the templates and the rendered output.

Project Structure

.shablon/                         # Source of truth for plugin content
├── vars.py                       # Render context (version, spexl --help)
├── config.toml
└── templates/
    ├── _includes/prime.md        # Shared partial for SessionStart hook body
    ├── skills/<skill>/SKILL.md
    ├── agents/<agent>.md
    └── plugins/claude/hooks/{hooks.json,prime.md}

skills/, agents/, plugins/        # Rendered plugin tree (committed)
.claude-plugin/plugin.json        # Plugin manifest (hand-written)

src/spexl/
├── __init__.py                   # main() entry point, argparse routing
├── __main__.py                   # `python -m spexl`
├── config.py                     # .spexl.toml discovery/loading
├── errors.py                     # SpexlError + exit-code conventions
├── specroot.py                   # locate specs/ from CWD
└── cli/
    ├── changes.py                # new, changes, info, archive
    ├── init.py                   # init (project scaffold)
    ├── refs.py
    ├── links.py                  # link, unlink
    └── validate.py               # validate (+ --fix)

specs/                            # spexl's own specs (dogfooding)
tests/                            # pytest
.spexl.toml                       # Project config

plugin_src is a symlink to .shablon/ for editor discoverability -- one source tree, two names.

Running

  • uv run spexl – run the CLI locally
  • uv run pytest – run tests
  • just plugins – re-render the plugin tree from .shablon/templates/
  • uv tool install -e . – install the CLI locally for end-to-end testing

CLI Design

spexl is intended for use by AI agents. All errors exit 1 with a clear explanation so the agent can reason about what went wrong. Prefer crashing over silent failures.

Whenever plumbing commands are updated, check whether validate (+ --fix) logic needs updating to cover new fields or invariants.

Spec-Driven Workflow

explore [topic]       → Think before proposing
propose [description] → Create change + all artifacts (proposal, deltas, design, tasks)
refine [instruction]  → Update any artifact
apply [spec slug]     → Implement and verify
archive [spec slug]   → Sync deltas to reference + archive

Editing plugin content

  1. Edit the template under .shablon/templates/.
  2. Run just plugins (or shablon generate).
  3. Commit both the template change and the rendered output. Tests assert the rendered tree exists; CI catches stale renders.

Changelog

Update CHANGELOG.md when committing notable changes.

Items should start with verbs like 'added', 'removed', 'fixed', 'improved', 'changed', etc.

Versioning and release

  1. Increment version number. Stick to 'zero-ver', as breaking changes are still possible.
  2. Update CHANGELOG.md: change ## [Unreleased] to version + date
  3. Update project.version= in pyproject.toml.
  4. Commit and tag: 
    git add <relevant files>
git commit -m "release: v0.4.0"
git tag v0.4.0
git push && git push origin v0.4.0