Skip to content

Commit e61726d

Browse files
author
supernormxl
committed
Add README, SECURITY, CI, hero GIF, and GitHub infrastructure
Rewrote README to match current plugin (12 skills, capsule architecture, hook pipeline). Added animated hero GIF, SECURITY.md, CONTRIBUTING.md, CHANGELOG.md, GitHub Actions validation workflow, issue/PR templates, and FUNDING.yml. Removed PII from map skill.
1 parent 821c3fd commit e61726d

13 files changed

Lines changed: 587 additions & 58 deletions

File tree

‎.github/FUNDING.yml‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1 @@
1+
custom: ["https://alivecomputer.com"]

‎.github/ISSUE_TEMPLATE/bug_report.md‎

Lines changed: 40 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,40 @@
1+
---
2+
name: Bug Report
3+
about: Something isn't working as expected
4+
title: '[bug] '
5+
labels: bug
6+
assignees: ''
7+
---
8+
9+
**Plugin version:** <!-- e.g. 1.0.1-beta -->
10+
**Claude Code version:** <!-- claude --version -->
11+
**OS:** <!-- e.g. macOS 15.3 -->
12+
**Model:** <!-- e.g. claude-opus-4-6 -->
13+
**Runtime:** <!-- e.g. squirrel.core@1.0 -->
14+
15+
## Behavior
16+
17+
**Expected:**
18+
19+
**Actual:**
20+
21+
## Reproduction
22+
23+
<!-- Skill invoked, walnut state, or sequence of actions. -->
24+
25+
```
26+
```
27+
28+
## System State
29+
30+
<!-- Paste relevant: squirrel YAML entry, hook output, or _core/now.md frontmatter. -->
31+
32+
```yaml
33+
```
34+
35+
## Logs
36+
37+
<!-- Any error output from hooks or Claude Code stderr. -->
38+
39+
```
40+
```

‎.github/ISSUE_TEMPLATE/config.yml‎

Lines changed: 8 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,8 @@
1+
blank_issues_enabled: true
2+
contact_links:
3+
- name: Community Discussion
4+
url: https://github.com/alivecomputer/claude-plugins/discussions
5+
about: Questions, ideas, and show & tell
6+
- name: Worldbuilders on Skool
7+
url: https://skool.com/worldbuilders
8+
about: Community hub for worldbuilders using ALIVE

‎.github/ISSUE_TEMPLATE/feature_request.md‎

Lines changed: 26 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,26 @@
1+
---
2+
name: Feature Request
3+
about: Propose a new skill, hook, rule, or capability
4+
title: '[feature] '
5+
labels: enhancement
6+
assignees: ''
7+
---
8+
9+
**Component:** <!-- skill | rule | hook | template | runtime | other -->
10+
**Affects:** <!-- e.g. alive:save, session lifecycle, capsule routing -->
11+
12+
## Problem
13+
14+
<!-- What's missing, broken, or slow? One paragraph max. -->
15+
16+
## Proposal
17+
18+
<!-- What should exist? Be specific about behavior, not implementation. -->
19+
20+
## Workflow Impact
21+
22+
<!-- Which part of the session flow does this touch? open → work → save → resume -->
23+
24+
## Prior Art
25+
26+
<!-- Links, references, or other tools that solve this well. -->

‎.github/PULL_REQUEST_TEMPLATE.md‎

Lines changed: 27 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,27 @@
1+
**Component:** <!-- skill | rule | hook | template | runtime | other -->
2+
**Breaking:** <!-- yes/no — does this change walnut structure, hook behavior, or skill interface? -->
3+
4+
## What changed
5+
6+
<!-- One sentence per change. Link to issue if applicable. -->
7+
8+
-
9+
10+
## Why
11+
12+
<!-- The problem this solves. Not what you did — why you did it. -->
13+
14+
## Verification
15+
16+
- [ ] Tested against a real walnut (not just a scaffold)
17+
- [ ] Backward compatible — existing walnuts still load correctly
18+
- [ ] Templates match any schema changes
19+
- [ ] Hooks fire correctly on session start, resume, and compact
20+
- [ ] No PII, credentials, or hardcoded paths in committed files
21+
22+
## Session context
23+
24+
<!-- Optional: paste your squirrel YAML entry if this was built inside an ALIVE session. -->
25+
26+
```yaml
27+
```

‎.github/workflows/validate-plugin.yml‎

Lines changed: 124 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,124 @@
1+
name: Validate Plugin Structure
2+
3+
on:
4+
push:
5+
branches: [main]
6+
paths: ['plugins/**']
7+
pull_request:
8+
branches: [main]
9+
paths: ['plugins/**']
10+
11+
jobs:
12+
validate:
13+
runs-on: ubuntu-latest
14+
steps:
15+
- uses: actions/checkout@v4
16+
17+
- name: Validate plugin structure
18+
run: |
19+
PLUGIN_DIR="plugins/alive"
20+
ERRORS=0
21+
22+
echo "=== Validating ALIVE plugin structure ==="
23+
24+
# Check required top-level files
25+
for file in CLAUDE.md; do
26+
if [ ! -f "$PLUGIN_DIR/$file" ]; then
27+
echo "❌ Missing required file: $PLUGIN_DIR/$file"
28+
ERRORS=$((ERRORS + 1))
29+
else
30+
echo "✅ $PLUGIN_DIR/$file"
31+
fi
32+
done
33+
34+
# Check skills have SKILL.md
35+
echo ""
36+
echo "=== Skills ==="
37+
for skill_dir in "$PLUGIN_DIR"/skills/*/; do
38+
skill_name=$(basename "$skill_dir")
39+
if [ ! -f "$skill_dir/SKILL.md" ]; then
40+
echo "❌ Skill '$skill_name' missing SKILL.md"
41+
ERRORS=$((ERRORS + 1))
42+
else
43+
# Check SKILL.md has frontmatter
44+
if ! head -1 "$skill_dir/SKILL.md" | grep -q "^---"; then
45+
echo "❌ Skill '$skill_name' SKILL.md missing frontmatter"
46+
ERRORS=$((ERRORS + 1))
47+
else
48+
echo "✅ $skill_name"
49+
fi
50+
fi
51+
done
52+
53+
# Check rules have frontmatter
54+
echo ""
55+
echo "=== Rules ==="
56+
for rule_file in "$PLUGIN_DIR"/rules/*.md; do
57+
rule_name=$(basename "$rule_file")
58+
if ! head -1 "$rule_file" | grep -q "^---"; then
59+
echo "❌ Rule '$rule_name' missing frontmatter"
60+
ERRORS=$((ERRORS + 1))
61+
else
62+
echo "✅ $rule_name"
63+
fi
64+
done
65+
66+
# Check hooks.json exists and references valid scripts
67+
echo ""
68+
echo "=== Hooks ==="
69+
HOOKS_JSON="$PLUGIN_DIR/hooks/hooks.json"
70+
if [ ! -f "$HOOKS_JSON" ]; then
71+
echo "❌ Missing hooks.json"
72+
ERRORS=$((ERRORS + 1))
73+
else
74+
echo "✅ hooks.json exists"
75+
# Extract script paths from hooks.json and verify they exist
76+
SCRIPTS=$(grep -o '"command":\s*"[^"]*"' "$HOOKS_JSON" | sed 's/"command":\s*"//;s/"//' | grep -o '[^ ]*\.sh')
77+
for script in $SCRIPTS; do
78+
script_path="$PLUGIN_DIR/hooks/scripts/$(basename "$script")"
79+
if [ ! -f "$script_path" ]; then
80+
echo "❌ Hook references missing script: $script"
81+
ERRORS=$((ERRORS + 1))
82+
else
83+
echo "✅ $(basename "$script")"
84+
fi
85+
done
86+
fi
87+
88+
# Check templates exist
89+
echo ""
90+
echo "=== Templates ==="
91+
for template_dir in alive walnut capsule squirrel; do
92+
if [ ! -d "$PLUGIN_DIR/templates/$template_dir" ]; then
93+
echo "⚠️ Template directory '$template_dir' not found (optional)"
94+
else
95+
file_count=$(find "$PLUGIN_DIR/templates/$template_dir" -type f | wc -l)
96+
echo "✅ $template_dir ($file_count files)"
97+
fi
98+
done
99+
100+
# Check no secrets
101+
echo ""
102+
echo "=== Security ==="
103+
if grep -rn "sk-[a-zA-Z0-9]\{20,\}\|ghp_[a-zA-Z0-9]\{36\}\|gho_[a-zA-Z0-9]\{36\}\|AKIA[A-Z0-9]\{16\}" "$PLUGIN_DIR"/ 2>/dev/null; then
104+
echo "❌ Possible API key or secret detected"
105+
ERRORS=$((ERRORS + 1))
106+
else
107+
echo "✅ No secrets detected"
108+
fi
109+
110+
echo ""
111+
echo "=== Summary ==="
112+
SKILL_COUNT=$(find "$PLUGIN_DIR/skills" -name "SKILL.md" | wc -l)
113+
RULE_COUNT=$(find "$PLUGIN_DIR/rules" -name "*.md" | wc -l)
114+
HOOK_COUNT=$(find "$PLUGIN_DIR/hooks/scripts" -name "*.sh" 2>/dev/null | wc -l)
115+
echo "Skills: $SKILL_COUNT | Rules: $RULE_COUNT | Hooks: $HOOK_COUNT"
116+
117+
if [ $ERRORS -gt 0 ]; then
118+
echo ""
119+
echo "❌ Validation failed with $ERRORS error(s)"
120+
exit 1
121+
else
122+
echo ""
123+
echo "✅ All checks passed"
124+
fi

‎.gitignore‎

Lines changed: 3 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,3 @@
1+
og-option-*.html
2+
og-hero-animated.html
3+
og-social-preview.png

‎CHANGELOG.md‎

Lines changed: 42 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,42 @@
1+
# Changelog
2+
3+
All notable changes to the ALIVE plugin are documented here.
4+
5+
## [1.0.1-beta] — 2026-03-12
6+
7+
### Added
8+
- **Capsule architecture** — self-contained units of work replace `_working/` and `_references/`. Capsules have companions, versioned drafts, and raw source material. Full lifecycle: `draft → prototype → published → done`. Graduation to walnut root on v1 ship.
9+
- **3 new skills:** `alive:mine` (deep context extraction), `alive:extend` (create custom skills/rules/hooks), `alive:map` (interactive world graph)
10+
- **Inbox scan mode** — `alive:capture` with no content falls back to scanning `03_Inputs/` for unrouted files
11+
- **Context graph** — D3.js force-directed visualization of your entire world
12+
- **World index generator** — `_index.yaml` built from all walnut and capsule frontmatter
13+
- **Capsule routing heuristic** — automatic routing of content to capsules by goal alignment
14+
- **Multi-agent capsule collaboration** — active session claims, capsule-scoped tasks, append-only work logs
15+
- **Cross-capsule shared references** — raw files live where first captured, other capsules link via `sources:` path
16+
17+
### Changed
18+
- **Walnut anatomy** — system files live in `_core/`. `_capsules/` and `_squirrels/` are the only system folders. Everything else is live context.
19+
- **Skill renames:** `housekeeping` → `tidy`, `config` → `tune`, `recall` → `history`
20+
- **Rules restructured** — 6 rule files: capsules, human, squirrels, standards, voice, world
21+
- **Templates updated** for capsule structure
22+
- **All hooks** updated with backward compatibility for flat walnut structures
23+
24+
### Removed
25+
- `_working/` and `_references/` folders (migrated to capsules, legacy still supported)
26+
27+
## [1.0.0-beta] — 2026-03-10
28+
29+
### Added
30+
- **12 skills:** world, open, save, capture, find, create, tidy, tune, history, mine, extend, map
31+
- **6 foundational rules:** capsules, human, squirrels, standards, voice, world
32+
- **13 hooks:** session lifecycle, log guardian, rules guardian, archive enforcer, external guard, context watch, inbox check, pre-compact, post-write
33+
- **Squirrel caretaker runtime** — stash mechanic, session signing, zero-context handoff
34+
- **ALIVE framework** — 5-domain folder structure (Archive, Life, Inputs, Ventures, Experiments)
35+
- **Walnut system** — 5 core files (key.md, now.md, log.md, insights.md, tasks.md)
36+
- **Onboarding** — first-run world builder experience
37+
- **Statusline** — terminal status bar with session info, context warnings, and stash count
38+
- **Templates** for all system file types
39+
40+
## [0.1.0-beta] — 2026-02-23
41+
42+
Initial release. 9 skills, flat walnut structure, basic session management.

‎CONTRIBUTING.md‎

Lines changed: 67 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,67 @@
1+
# Contributing to ALIVE
2+
3+
Thanks for your interest in contributing. ALIVE is open source and we welcome contributions — whether it's a bug fix, new skill, or documentation improvement.
4+
5+
## Getting Started
6+
7+
1. Fork the repository
8+
2. Clone your fork locally
9+
3. Install the plugin from your local copy for testing:
10+
```bash
11+
claude plugin install /path/to/your/clone
12+
```
13+
14+
## Project Structure
15+
16+
```
17+
plugins/alive/
18+
skills/ 12 skill folders, each with a SKILL.md
19+
rules/ 6 rule files defining caretaker behavior
20+
hooks/ hooks.json + scripts/ for session lifecycle
21+
templates/ file templates for walnuts, capsules, companions
22+
onboarding/ first-run experience
23+
statusline/ terminal status bar integration
24+
scripts/ utility scripts (world index, context graph)
25+
CLAUDE.md the core runtime definition
26+
```
27+
28+
## Making Changes
29+
30+
### Skills
31+
Each skill lives in `plugins/alive/skills/{name}/SKILL.md`. Skills define what the squirrel can do — they're invoked by the user via `/alive:{name}`.
32+
33+
### Rules
34+
Rules live in `plugins/alive/rules/`. They define how the squirrel behaves — these are always loaded and always followed.
35+
36+
### Hooks
37+
Hook scripts live in `plugins/alive/hooks/scripts/`. They fire on session lifecycle events (start, resume, compact) and tool use events (pre/post). The hook registry is `plugins/alive/hooks/hooks.json`.
38+
39+
### Templates
40+
Templates in `plugins/alive/templates/` define the schema for system files. The squirrel reads these before writing any system file.
41+
42+
## Guidelines
43+
44+
- **Read before writing.** Understand the existing code before modifying it.
45+
- **Frontmatter on everything.** Every `.md` file has YAML frontmatter. No exceptions.
46+
- **Don't break backward compatibility.** Existing walnuts must keep working.
47+
- **Test with a real world.** Create a test walnut and exercise your changes.
48+
- **Keep skills focused.** One skill, one purpose.
49+
- **Respect the stash.** Mid-session writes are limited to capture and capsule work only.
50+
51+
## Pull Requests
52+
53+
- Keep PRs focused on a single change
54+
- Describe what changed and why
55+
- Reference any related issues
56+
57+
## Reporting Issues
58+
59+
Use [GitHub Issues](https://github.com/alivecomputer/claude-plugins/issues) for bugs and feature requests. Use the provided templates.
60+
61+
## Community
62+
63+
Join [Worldbuilders on Skool](https://skool.com/worldbuilders) for discussion, feedback, and show & tell.
64+
65+
## License
66+
67+
By contributing, you agree that your contributions will be licensed under the MIT License.

0 commit comments

Comments
 (0)