swamp-club/swamp-plugin
Watch
6
0
Fork
You've already forked swamp-plugin
 0
Code Pull requests Activity Actions

Add CLAUDE.md, repo consistency checks, and CI #1

Merged
stack72 merged 1 commit from add-claude-md-and-repo-checks into main 2026-07-30 20:19:29 +00:00
Conversation 0 Commits 1 Files changed 4 +317 -1
stack72 commented 2026-07-30 20:18:39 +00:00
Owner
Copy link

What

  • CLAUDE.md — guidance for Claude Code agents working in this repo: what the plugin is (executed markdown, not docs), the progressive-disclosure architecture (SKILL.md routing table → guide.md → reference.md → deep dives), the eval JSON files as behavioral contracts, recipes for adding commands/skill domains, and repo conventions (server-first model, fgj for PRs, conventional commits).
  • scripts/check.sh — dependency-free consistency checks (bash + python3 stdlib), exit code = failure count:
    1. relative markdown links resolve
    2. command/skill frontmatter valid, name: matches filename/directory
    3. ${CLAUDE_PLUGIN_ROOT} paths exist
    4. eval JSON parses, matches per-file schema, referenced guides exist
    5. SKILL.md routing table ↔ references/*/guide.md agree both ways
    6. plugin.json / marketplace.json names and versions match
    7. shell scripts pass bash -n
  • .forgejo/workflows/check.yml — runs the checks on push to main and on PRs.
  • README.md — structure tree lists the new script.

Why

The repo is almost entirely markdown that Claude Code executes at runtime — broken routing links, malformed frontmatter, or eval/guide drift fail silently. These checks make those invariants explicit and enforced.

Verification

  • ./scripts/check.sh passes on the branch.
  • Fault-injection tested: a broken routing link, a frontmatter name mismatch, an eval pointing at a nonexistent guide, and manifest version drift were each caught, then reverted.

🤖 Generated with Claude Code

## What - **CLAUDE.md** — guidance for Claude Code agents working in this repo: what the plugin is (executed markdown, not docs), the progressive-disclosure architecture (SKILL.md routing table → guide.md → reference.md → deep dives), the eval JSON files as behavioral contracts, recipes for adding commands/skill domains, and repo conventions (server-first model, fgj for PRs, conventional commits). - **scripts/check.sh** — dependency-free consistency checks (bash + python3 stdlib), exit code = failure count: 1. relative markdown links resolve 2. command/skill frontmatter valid, `name:` matches filename/directory 3. `${CLAUDE_PLUGIN_ROOT}` paths exist 4. eval JSON parses, matches per-file schema, referenced guides exist 5. SKILL.md routing table ↔ `references/*/guide.md` agree both ways 6. plugin.json / marketplace.json names and versions match 7. shell scripts pass `bash -n` - **.forgejo/workflows/check.yml** — runs the checks on push to main and on PRs. - **README.md** — structure tree lists the new script. ## Why The repo is almost entirely markdown that Claude Code executes at runtime — broken routing links, malformed frontmatter, or eval/guide drift fail silently. These checks make those invariants explicit and enforced. ## Verification - `./scripts/check.sh` passes on the branch. - Fault-injection tested: a broken routing link, a frontmatter name mismatch, an eval pointing at a nonexistent guide, and manifest version drift were each caught, then reverted. 🤖 Generated with [Claude Code](https://claude.com/claude-code)
- CLAUDE.md documenting the plugin architecture (progressive disclosure,
  eval contracts, Forgejo/fgj PR flow) for Claude Code agents
- scripts/check.sh: dependency-free consistency checks (links, frontmatter,
  eval schemas, routing table, manifest versions, shell syntax)
- .forgejo/workflows/check.yml: run checks on push and PR
- README.md: list check.sh in the structure tree

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
Sign in to join this conversation.
Reviewers
No reviewers
Labels
Clear labels
No items
No labels
Milestone
Clear milestone
No items
No milestone
Assignees
Clear assignees
No assignees
1 participant
Notifications
Due date
The due date is invalid or out of range. Please use the format "yyyy-mm-dd".

No due date set.

Dependencies

No dependencies set

Reference
swamp-club/swamp-plugin!1
No description provided.