Skip to content

Commit 2ec4753

Browse files
andreadellacorteclaude
andreadellacorte
and
claude
committed
feat(0.10.1): groove-admin-* and groove-utilities-prime/check skills; recent_memory_days
- Add groove-admin-help, groove-admin-config, groove-admin-install, groove-admin-update, groove-admin-doctor as individual skills (admin namespace) - Add groove-utilities-prime, groove-utilities-check as individual skills (utilities namespace) - Add recent_memory_days: 5 config key; groove-daily-start now reviews last N days of memory - Add migration 0.10.0 -> 0.10.1: writes recent_memory_days to .groove/index.md, updates AGENTS.md prime stub to /groove-utilities-prime - Rename groove-work-work -> groove-work-exec in installed skill dirs Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
1 parent 6574c24 commit 2ec4753

39 files changed

Lines changed: 1647 additions & 23 deletions

File tree

‎.agents/skills/daily/SKILL.md‎

Lines changed: 0 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -5,7 +5,6 @@ license: MIT
55
allowed-tools: Bash(git:*) Read Write Edit AskUserQuestion
66
metadata:
77
author: andreadellacorte
8-
version: "0.1.0"
98
---
109

1110
<!-- groove:managed — do not edit; changes will be overwritten by groove update -->

‎.agents/skills/groove-admin-config/SKILL.md‎

Lines changed: 76 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,76 @@
1+
---
2+
name: groove-admin-config
3+
description: "Create or update .groove/index.md config interactively. Run before groove install."
4+
license: MIT
5+
allowed-tools: Read Write Edit Glob Grep Bash(git:*) Bash(beans:*) Bash(gh:*) Bash(linear:*) Bash(npx:*) Bash(mkdir:*) AskUserQuestion
6+
metadata:
7+
author: andreadellacorte
8+
---
9+
10+
<!-- groove:managed — do not edit; changes will be overwritten by groove update -->
11+
12+
# groove-admin-config
13+
14+
## Outcome
15+
16+
`.groove/index.md` is created or updated with values confirmed by the user. The git strategy is applied immediately. User is ready to run `/groove-admin-install`.
17+
18+
## Acceptance Criteria
19+
20+
- `.groove/index.md` exists with all config keys populated
21+
- Each key was either confirmed by the user or accepted as default
22+
- Git strategy is applied (`.groove/.gitignore` written) before exiting
23+
- User is shown a summary of the final config and told to run `/groove-admin-install`
24+
25+
## Steps
26+
27+
Walk the user through each config key in order. For each key: show the current value (or default if new), explain what it does, and ask to confirm or change.
28+
29+
### Keys and defaults
30+
31+
| Key | Default | Options | Question to ask |
32+
|---|---|---|---|
33+
| `tasks` | `beans` | `beans \| linear \| github \| none` | "Which task backend? beans tracks tasks as markdown files in your repo." |
34+
| `memory` | `.groove/memory/` | any path | "Where should groove store memory logs? (default: .groove/memory/)" |
35+
| `git.memory` | `ignore-all` | `ignore-all \| hybrid \| commit-all` | "Git strategy for memory logs? ignore-all keeps them local, hybrid commits logs but ignores sessions, commit-all commits everything." |
36+
| `git.tasks` | `ignore-all` | `ignore-all \| commit-all` | "Git strategy for task files (.groove/tasks/)? ignore-all keeps them local, commit-all tracks them in git." |
37+
| `git.hooks` | `commit-all` | `ignore-all \| commit-all` | "Git strategy for hooks (.groove/hooks/)? commit-all shares hooks with the team, ignore-all keeps them local." |
38+
39+
After all keys are confirmed:
40+
41+
1. Write `.groove/index.md` with confirmed values and `groove-version: <installed version>`
42+
2. Apply git strategy — write `.groove/.gitignore` (see constraints)
43+
3. Show summary of written config
44+
4. Tell user: "Run `/groove-admin-install` to install backends."
45+
46+
## Constraints
47+
48+
- If `.groove/index.md` already exists, pre-fill each question with the current value
49+
- If run non-interactively (arguments provided), apply them without prompting: e.g. `groove-admin-config tasks=linear git.memory=hybrid`
50+
- Always write `groove-version:` matching the installed version from `skills/groove/SKILL.md`
51+
52+
### Git strategy → `.groove/.gitignore`
53+
54+
After writing `.groove/index.md`, generate `.groove/.gitignore` from the `git.*` sub-keys:
55+
56+
| Component | Strategy | Entry added to `.groove/.gitignore` |
57+
|---|---|---|
58+
| `git.memory` | `ignore-all` | `memory/` |
59+
| `git.memory` | `hybrid` | `memory/sessions/` |
60+
| `git.memory` | `commit-all` | _(none)_ |
61+
| `git.tasks` | `ignore-all` | `tasks/` |
62+
| `git.tasks` | `commit-all` | _(none)_ |
63+
| `git.hooks` | `ignore-all` | `hooks/` |
64+
| `git.hooks` | `commit-all` | _(none)_ |
65+
66+
Write the generated entries to `.groove/.gitignore`, replacing the file entirely. If no entries are generated (all `commit-all`), write an empty file with a comment: `# groove git strategy: commit-all`.
67+
68+
Always append these lines at the end of `.groove/.gitignore`, regardless of strategy:
69+
```
70+
# cache — always local
71+
.cache/*
72+
!.cache/.gitkeep
73+
```
74+
75+
- If `.groove/` is listed in the root `.gitignore`, warn the user: "Note: `.groove/` is in your root .gitignore — any commit-all strategies require removing it."
76+
- Do not modify the root `.gitignore` automatically — flag it for the user to resolve

‎.agents/skills/groove-admin-doctor/SKILL.md‎

Lines changed: 80 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,80 @@
1+
---
2+
name: groove-admin-doctor
3+
description: "Run all groove health checks: config, backends, companions, AGENTS.md."
4+
license: MIT
5+
allowed-tools: Read Write Edit Glob Grep Bash(git:*) Bash(beans:*) Bash(gh:*) Bash(linear:*) Bash(npx:*) Bash(mkdir:*) AskUserQuestion
6+
metadata:
7+
author: andreadellacorte
8+
---
9+
10+
<!-- groove:managed — do not edit; changes will be overwritten by groove update -->
11+
12+
# groove-admin-doctor
13+
14+
## Outcome
15+
16+
All groove sub-skill health checks are run and a consolidated summary is reported. User knows exactly what is working, what is misconfigured, and what action to take for any failure.
17+
18+
## Acceptance Criteria
19+
20+
- `/groove-utilities-task-doctor` and `/groove-utilities-memory-doctor` are run
21+
- Companion skill presence is checked directly
22+
- Results are shown per sub-skill with pass/fail per check
23+
- Overall status is shown: all healthy, or N issues found
24+
- Each failure includes a specific remediation action
25+
26+
## Output format
27+
28+
```
29+
groove doctor
30+
─────────────────────────────────────
31+
groove
32+
✓ git repo: detected
33+
✓ groove-version: 0.1.0
34+
✓ installed version: 0.1.0
35+
✓ up to date
36+
37+
task
38+
✓ .groove/index.md present
39+
✓ tasks: beans
40+
✓ beans installed (v0.x.x)
41+
✓ .beans.yml present
42+
✓ beans reachable
43+
44+
memory
45+
✓ memory path exists (.groove/memory/)
46+
✓ memory dirs exist (.groove/memory/daily/, weekly/, monthly/, git/)
47+
48+
companions
49+
✓ find-skills installed
50+
✓ agent-browser installed
51+
✓ pdf-to-markdown installed
52+
53+
AGENTS.md
54+
✓ groove:prime section present
55+
✗ groove:task section missing — run: /groove-admin-install
56+
57+
─────────────────────────────────────
58+
1 issue found. Run the suggested commands above to fix.
59+
```
60+
61+
## Constraints
62+
63+
- Run git repo check first, then version check, then `/groove-utilities-task-doctor`, `/groove-utilities-memory-doctor`, companions check in sequence
64+
- Git repo check:
65+
- Run `git rev-parse --is-inside-work-tree` in the current directory
66+
- If it succeeds: `✓ git repo: detected`
67+
- If it fails: `✗ git repo: not a git repository — groove requires a git repo`
68+
- Version check:
69+
- Read `groove-version:` from `.groove/index.md` (if absent, treat as `0.1.0`)
70+
- Read `version:` from `skills/groove/SKILL.md`
71+
- If they differ: `✗ groove-version (<local>) behind installed (<installed>) — run: /groove-admin-update`
72+
- Companions check:
73+
- Check `ls .agents/skills/find-skills/SKILL.md` — if absent: `✗ find-skills not installed — run: /groove-admin-install`
74+
- Check `ls .agents/skills/agent-browser/SKILL.md` — if absent: `✗ agent-browser not installed — run: /groove-admin-install`
75+
- Check `ls .agents/skills/pdf-to-markdown/SKILL.md` — if absent: `✗ pdf-to-markdown not installed — run: /groove-admin-install`
76+
- Also check `AGENTS.md` for presence of `<!-- groove:prime:start -->` and `<!-- groove:task:start -->` sections
77+
- Collect all results before printing — do not interleave output with check progress
78+
- Each `✗` item must include a concrete remediation command on the same line
79+
- Exit with a clear "all healthy" message if no issues found
80+
- Do not attempt to auto-fix issues — report only

‎.agents/skills/groove-admin-help/SKILL.md‎

Lines changed: 104 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,104 @@
1+
---
2+
name: groove-admin-help
3+
description: "Display all groove skills and commands with live config values."
4+
license: MIT
5+
allowed-tools: Read Write Edit Glob Grep Bash(git:*) Bash(beans:*) Bash(gh:*) Bash(linear:*) Bash(npx:*) Bash(mkdir:*) AskUserQuestion
6+
metadata:
7+
author: andreadellacorte
8+
---
9+
10+
<!-- groove:managed — do not edit; changes will be overwritten by groove update -->
11+
12+
# groove-admin-help
13+
14+
Display a structured overview of all groove skills and their commands.
15+
16+
## Output
17+
18+
Print the following, substituting live config values from `.groove/index.md` where shown:
19+
20+
---
21+
22+
**groove** — compound engineering workflow
23+
24+
```
25+
/groove /groove-admin-help /groove-utilities-prime /groove-admin-install /groove-admin-config /groove-admin-update /groove-utilities-check /groove-admin-doctor
26+
```
27+
28+
**Daily**
29+
30+
| Skill | Purpose |
31+
|---|---|
32+
| `/groove-daily-start` | Start the workday |
33+
| `/groove-daily-end` | End the workday |
34+
35+
**Work**
36+
37+
| Skill | Purpose |
38+
|---|---|
39+
| `/groove-work-brainstorm` | Clarify scope through dialogue |
40+
| `/groove-work-plan` | Write implementation plan |
41+
| `/groove-work-exec` | Execute the plan |
42+
| `/groove-work-review` | Evaluate output |
43+
| `/groove-work-compound` | Capture lessons |
44+
| `/groove-work-spec [topic]` | Create outcome spec |
45+
| `/groove-work-audit` | Review branch for blindspots |
46+
47+
**Utilities — Tasks**
48+
49+
| Skill | Purpose |
50+
|---|---|
51+
| `/groove-utilities-task-list` | List active tasks |
52+
| `/groove-utilities-task-create` | Create a task |
53+
| `/groove-utilities-task-update` | Update a task |
54+
| `/groove-utilities-task-archive` | Archive a task |
55+
| `/groove-utilities-task-analyse` | Analyse task status |
56+
| `/groove-utilities-task-install` | Set up task backend |
57+
| `/groove-utilities-task-config` | Configure task backend |
58+
| `/groove-utilities-task-doctor` | Check task backend health |
59+
60+
**Utilities — Memory**
61+
62+
| Skill | Purpose |
63+
|---|---|
64+
| `/groove-utilities-memory-log-daily` | Write daily log entry |
65+
| `/groove-utilities-memory-log-weekly` | Roll up weekly log |
66+
| `/groove-utilities-memory-log-monthly` | Roll up monthly log |
67+
| `/groove-utilities-memory-log-git` | Record git activity |
68+
| `/groove-utilities-memory-init-daily` | Initialise today's memory file |
69+
| `/groove-utilities-memory-install` | Set up memory backend |
70+
| `/groove-utilities-memory-doctor` | Check memory backend health |
71+
72+
**Utilities — Session**
73+
74+
| Skill | Purpose |
75+
|---|---|
76+
| `/groove-utilities-prime` | Load workflow context into conversation |
77+
| `/groove-utilities-check` | Check if a newer version is available |
78+
79+
**Admin**
80+
81+
| Skill | Purpose |
82+
|---|---|
83+
| `/groove-admin-install` | Install backends and bootstrap AGENTS.md |
84+
| `/groove-admin-config` | Create or update `.groove/index.md` |
85+
| `/groove-admin-update` | Pull latest and apply migrations |
86+
| `/groove-admin-doctor` | Run all health checks |
87+
88+
**Config** (`.groove/index.md`)
89+
90+
```
91+
tasks: <value> — task backend (beans | linear | github | none)
92+
memory: <value> — log file path
93+
git.memory: <value> — memory commit strategy (ignore-all | hybrid | commit-all)
94+
git.tasks: <value> — tasks commit strategy (ignore-all | commit-all)
95+
git.hooks: <value> — hooks commit strategy (ignore-all | commit-all)
96+
```
97+
98+
---
99+
100+
## Constraints
101+
102+
- Read `.groove/index.md` and substitute actual configured values into the config block
103+
- If `.groove/index.md` does not exist, show defaults and note that config has not been created yet
104+
- Keep output concise — this is a quick-reference, not a manual

‎.agents/skills/groove-admin-install/SKILL.md‎

Lines changed: 72 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,72 @@
1+
---
2+
name: groove-admin-install
3+
description: "Install groove backends, companions, and AGENTS.md bootstrap. Run once per repo."
4+
license: MIT
5+
allowed-tools: Read Write Edit Glob Grep Bash(git:*) Bash(beans:*) Bash(gh:*) Bash(linear:*) Bash(npx:*) Bash(mkdir:*) AskUserQuestion
6+
metadata:
7+
author: andreadellacorte
8+
---
9+
10+
<!-- groove:managed — do not edit; changes will be overwritten by groove update -->
11+
12+
# groove-admin-install
13+
14+
## Outcome
15+
16+
All groove backends are installed in dependency order, groove-wide companion skills are installed, AGENTS.md contains the session bootstrap, and the repo is ready for use.
17+
18+
## Acceptance Criteria
19+
20+
- Task and memory backends installed
21+
- Companion skills installed (find-skills, agent-browser, pdf-to-markdown)
22+
- `AGENTS.md` contains the `<!-- groove:prime:start -->` session bootstrap
23+
- `AGENTS.md` contains a `<!-- groove:task:start -->` stub (if `tasks: beans`)
24+
- User sees a summary of what was installed and what was written
25+
26+
## Steps
27+
28+
Run in order:
29+
30+
1. If `.groove/index.md` does not exist, run `/groove-admin-config` to create it
31+
2. Run `/groove-utilities-task-install` — installs the configured task backend (e.g. beans)
32+
3. Run `/groove-utilities-memory-install` — creates memory directories
33+
4. Install companion skills:
34+
- **find-skills** (downloaded): check `ls .agents/skills/find-skills/SKILL.md`; if absent: `npx skills add https://github.com/vercel-labs/skills --skill find-skills`
35+
- **agent-browser** (downloaded): check `ls .agents/skills/agent-browser/SKILL.md`; if absent: `npx skills add https://github.com/vercel-labs/agent-browser --skill agent-browser`
36+
- **pdf-to-markdown** (embedded): check `ls .agents/skills/pdf-to-markdown/SKILL.md`; if absent: `npx skills add andreadellacorte/groove --skill pdf-to-markdown`
37+
- Report each as installed / already-present / failed
38+
5. Scaffold hooks and cache directories:
39+
- Create `.groove/hooks/` if it does not exist (with a `.gitkeep`)
40+
- Create `.groove/.cache/` if it does not exist (with a `.gitkeep`)
41+
- Report each as created / already-present
42+
6. Apply git strategy — write `.groove/.gitignore` from `git.*` sub-keys in `.groove/index.md` (see `/groove-admin-config` for rules)
43+
7. Write the session bootstrap to `AGENTS.md`:
44+
- Replace any existing `<!-- groove:prime:start -->` / `<!-- groove:prime:end -->` section with:
45+
```
46+
<!-- groove:prime:start -->
47+
**Run at the start of every session:**
48+
`/groove-utilities-prime` — loads groove workflow context into the conversation
49+
<!-- groove:prime:end -->
50+
```
51+
- If section absent, append to end of `AGENTS.md`; preserve all other content
52+
8. `/groove-utilities-task-install` already wrote the `<!-- groove:task:start -->` stub in step 2 — no additional AGENTS.md write needed here
53+
54+
## Constraints
55+
56+
- Read `.groove/index.md` for `tasks:` and `git.*` config before running
57+
- If `.groove/index.md` does not exist, `/groove-admin-config` is run first (step 1) to create it
58+
- Dependency order for backends must be respected: task → memory → companions
59+
- Each step reports installed / already-present / failed
60+
- `AGENTS.md` update is additive per section — preserve all other content
61+
- If any step fails, report it clearly but continue with remaining steps
62+
- Companion skills (find-skills, agent-browser, pdf-to-markdown) are hardcoded here, not read from any config file
63+
- Report a final summary:
64+
```
65+
✓ task backend (beans)
66+
✓ memory backend — memory dirs ready
67+
✓ companion: find-skills
68+
✓ companion: agent-browser
69+
✓ companion: pdf-to-markdown
70+
✓ hooks: .groove/hooks/ ready
71+
✓ AGENTS.md updated (groove:prime, groove:task)
72+
```

‎.agents/skills/groove-admin-update/SKILL.md‎

Lines changed: 52 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,52 @@
1+
---
2+
name: groove-admin-update
3+
description: "Pull latest groove skills and apply pending migrations to local groove state."
4+
license: MIT
5+
allowed-tools: Read Write Edit Glob Grep Bash(git:*) Bash(beans:*) Bash(gh:*) Bash(linear:*) Bash(npx:*) Bash(mkdir:*) AskUserQuestion
6+
metadata:
7+
author: andreadellacorte
8+
---
9+
10+
<!-- groove:managed — do not edit; changes will be overwritten by groove update -->
11+
12+
# groove-admin-update
13+
14+
## Outcome
15+
16+
All pending migrations are applied to the user's local groove state in version order. `.groove/index.md` reflects the current installed groove version.
17+
18+
## Acceptance Criteria
19+
20+
- `groove-version:` in `.groove/index.md` matches `version:` in `skills/groove/SKILL.md` after update
21+
- Each pending migration was applied in order
22+
- `groove-version:` updated after each successful migration (partial progress is recoverable)
23+
- If already up to date, reports clearly and exits
24+
- **Source-of-truth check**: "up to date" is only reported when the installed skill version equals the latest GitHub release; if the add step left an older version on disk (e.g. cached or default branch), the user is warned and told how to fix it
25+
26+
## Steps
27+
28+
1. Run `npx skills add andreadellacorte/groove --yes` — pulls latest groove skill files and refreshes the lock entry (more reliable than `npx skills update` which requires a pre-populated folder hash). Note: the CLI may install a cached or default-branch copy rather than the latest release tag; step 4 verifies against GitHub.
29+
- After this step, **re-read this SKILL.md (`skills/groove-admin-update/SKILL.md`) from disk** before continuing — the skill refresh may have updated the update command itself, and the remainder of these steps must reflect the latest version
30+
2. Read `groove-version:` from `.groove/index.md` — if key absent, assume `0.1.0` and write it
31+
3. Read installed version from `version:` in `skills/groove/SKILL.md`
32+
4. **Verify against latest release**: Fetch `https://api.github.com/repos/andreadellacorte/groove/releases/latest` (tag_name, strip leading `v`). If the request succeeds, compare installed with latest using semver. If installed is less than latest: do **not** report "up to date" even if local and installed match; instead report: "Installed skill is v<installed> but latest release is v<latest>. The add step may have used a cached or default-branch copy. Run: `npx skills add andreadellacorte/groove@v<latest> --yes` then run `/groove-admin-update` again." and exit. If the API call fails (network, rate limit), continue without this check.
33+
5. If local and installed versions match: report "groove is up to date (v<version>)" and exit
34+
6. Read `skills/groove/migrations/index.md` — parse the migration table
35+
7. Filter rows where `To` > local version AND `To` <= installed version, in table order — the `From` field is informational only and does not gate execution
36+
8. If no migrations found but versions differ: update `groove-version:` in `.groove/index.md` directly to the installed version and report "no state migrations needed — version bumped to v<version>"
37+
9. For each pending migration:
38+
a. Report "Applying <from> → <to>: <description>"
39+
b. Read and execute the migration file
40+
c. Update `groove-version:` in `.groove/index.md` to the `To` version
41+
d. Report "✓ <from> → <to> applied"
42+
10. Report summary: N migrations applied, now at v<version>
43+
44+
## Constraints
45+
46+
- **Source of truth for "latest" is GitHub releases** — `npx skills add` can leave an older version on disk (cached clone, default branch). Comparing only `.groove/index.md` with installed `SKILL.md` can falsely report "up to date". Step 4 must verify installed vs `releases/latest` and warn when they differ.
47+
- Never skip a migration — apply every matching migration in table order even if `From` does not match local version exactly
48+
- Update `groove-version:` after each individual migration, not only at the end
49+
- If a migration fails: stop, report the failure and current version, do not continue
50+
- Do not modify skill files — `npx skills update` handles that; this command only migrates local state
51+
- Local state includes: `.groove/index.md` config keys, memory directory structure, AGENTS.md sections
52+
- Each migration file is idempotent — if re-run after partial failure, it should be safe

0 commit comments

Comments
 (0)