Skip to content
Open
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension


Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
324 changes: 0 additions & 324 deletions .claude/skills/cron-wrapup/SKILL.md

This file was deleted.

This file was deleted.

92 changes: 7 additions & 85 deletions .claude/skills/knowledgebase-initialize/SKILL.md
Original file line number Diff line number Diff line change
@@ -1,6 +1,6 @@
---
name: knowledgebase-initialize
description: Use on a fresh clone, new machine, or new profile to create or repair the local data repository — verifying CLI tooling, choosing usage report mode, proposing cron jobs, and writing initialization handoff/log output.
description: Use on a fresh clone, new machine, or new profile to create or repair the local data repository — verifying CLI tooling and writing initialization handoff/log output.
---

# KnowledgeBase Initialize
Expand All @@ -15,10 +15,8 @@ Use this skill as the runtime contract for repository setup. Do not load `docs/`
- `data/` is a generated export directory. Postgres (reached via `DATABASE_URL`) is the canonical store. Never add `data/` to the outer repo.
- Never modify existing files under `data/raw/`.
- Preserve existing `data/` contents; create only missing directories/files.
- Do not install or edit crontab until the user approves the exact entries.
- Memory cron jobs run lint and leave changes uncommitted for manual review.
- Wiki promotion writes through the kb-mcp tools; it does not commit or push from the AI session.
- Prefer relative paths from repo root. Do not hard-code machine-specific absolute paths except when showing final crontab examples.
- Wiki writes go through the kb-mcp tools; the skill does not commit or push from the AI session.
- Prefer relative paths from repo root. Do not hard-code machine-specific absolute paths.

## Required Data Layout

Expand All @@ -33,7 +31,6 @@ data/
web/
manual/
ops/
cron/YYYY/MM/
runs/YYYY/MM/
decisions/YYYY/MM/
traces/YYYY/MM/
Expand All @@ -47,14 +44,9 @@ data/
improvements/YYYY-MM/
checklists/
summaries/YYYY/MM/
rejected/
ops/
reports/YYYY/MM/
log.md
```

`data/rejected/` may be empty on a fresh install. It is populated by wiki rejection.

## Phase 1: Inspect

Check:
Expand All @@ -65,8 +57,6 @@ psql "${DATABASE_URL/+psycopg/}" -tAc "SELECT 1" >/dev/null && echo "DB reachabl
test -f data/log.md
uv --version
uv run kb-lint --help
uv run kb-db-ttl-sweep --help
find scripts/cron -maxdepth 1 -type f -name 'kb-*.sh' | sort
```

If a command fails because dependencies are missing, run:
Expand Down Expand Up @@ -150,61 +140,7 @@ bash .claude/skills/knowledgebase-initialize/scripts/install-global-skills.sh
- Set `CLAUDE_SKILLS_DIR` to override the destination. Edit the `GLOBAL_SKILLS`
array in the script to expose more skills (currently: `handoff-document` and `wiki-note`).

## Phase 4: Usage Report Mode

Use the `usage-report-setup` skill if the user asks for detailed setup. For initialization, ask which source-specific reports to enable:

| Mode | Cron wrapper |
|---|---|
| none | no usage report job |
| OpenCode | `scripts/cron/kb-opencode-daily-report.sh` |
| Hermes | `scripts/cron/kb-hermes-daily-report.sh` |
| Claude Code | `scripts/cron/kb-claude-code-daily-report.sh` |
| multiple separate | selected wrappers only |

Default recommendation: enable only sources the user actually runs. Do not create combined usage reports.

## Phase 5: Propose Cron Jobs

KnowledgeBase owns the expected job contract and portable wrapper scripts under `scripts/cron/`; it does not require a specific scheduler backend.

Scheduler backend guidance:

- **Tested scheduler**: Hermes cron, using scheduler-local dispatcher scripts that call the repo wrappers.
- **Compatible but not yet tested here**: OpenClaw cron, native Unix crontab, systemd timers, or any equivalent scheduler that can run the wrapper scripts on the documented schedule.
- Actual job registration state belongs to the chosen scheduler backend. Run evidence belongs in DB tables (`cron_runs`, `handoffs`, `operation_logs`, and summary `pages`); `data/raw/ops/cron/{YYYY}/{MM}/`, `data/handoffs/`, `data/log.md`, and wrap-up markdown are generated export/debug copies.

Show the exact list before making cron changes:

```text
KnowledgeBase jobs:
- daily memory build: 03:30 every day
- wiki promote: 04:00 every day
- weekly memory build: 04:15 every Monday
- monthly memory maintenance:04:45 on day 1 of each month
- wiki TTL sweep: 00:30 every day
- cron wrap-up: 05:00 every day

Optional usage report jobs:
- OpenCode daily usage: 03:10 every day
- Hermes daily usage: 03:15 every day
- Claude Code daily usage: 03:20 every day

Optional global digest job:
- morning Slack digest: 09:00 every day (optional, recommended)
```

If the user wants the optional global digest, read `reference/optional-global-digest.md` and show the setup separately from the required KB cron jobs.

Wrapper prompt policy:

- Memory wrappers import `.claude/skills/memory-report/SKILL.md`.
- Wiki promotion wrapper imports `.claude/skills/wiki-approval/SKILL.md`.
- Cron wrap-up wrapper imports `.claude/skills/cron-wrapup/SKILL.md` and writes a Slack-digest-stable `wiki/summaries/.../{date}-cron-wrapup.md` plus run handoff.
- Usage setup/import prompts use `.claude/skills/usage-report-setup/SKILL.md`.
- TTL sweep runs `uv run kb-db-ttl-sweep --days 7`, applying status changes in-process through the `kb.service` layer.

### Register kb-mcp in agent runtimes (ask first)
## Phase 4: Register kb-mcp in Agent Runtimes

LLM/agent runtimes reach the write surface by connecting to the `kb-mcp` daemon over http. Before registering anything, **ask the user two things**:

Expand All @@ -225,17 +161,9 @@ Recipes (use the confirmed `<KB_MCP_URL>`):
- **Claude Code** — `claude mcp add --transport http --scope user kb-mcp <KB_MCP_URL>`
- **Other runtimes (e.g. Hermes)** — ask the user where their MCP config lives; add an http entry pointing at `<KB_MCP_URL>`.

Deterministic jobs (`kb-db-ttl-sweep`, daily reports, ingest) need no registration — they call `kb.service` in-process. The daemon has no auth: if it must be reachable from other hosts, publish it on the appropriate interface (compose default `0.0.0.0:8765`); on a single host, host-loopback (`127.0.0.1:8765:8765`) is safer (see #41).

Only after approval:

1. Create or update wrapper scripts under `scripts/cron/`.
2. Make wrappers executable.
3. Each wrapper writes its run log to `data/raw/ops/cron/{YYYY}/{MM}/{TARGET}_kb-<job>.log` (where YYYY/MM derives from TARGET_DATE). The `kb-cron-wrapup` wrapper writes to `.cron/logs/cron-wrapup.log` during the session, then commits it to `data/raw/ops/cron/` in a follow-up commit after the session exits.
4. Keep locks in `.cron/locks/`.
5. Show scheduler entries for the selected backend, or install/register them only if the user explicitly asks.
The daemon has no auth: if it must be reachable from other hosts, publish it on the appropriate interface (compose default `0.0.0.0:8765`); on a single host, host-loopback (`127.0.0.1:8765:8765`) is safer (see #41).

## Phase 6: Initialization Handoff
## Phase 5: Initialization Handoff

Write:

Expand Down Expand Up @@ -285,7 +213,7 @@ Run:
# Handoff validation runs inside the kb-mcp create_handoff tool (returns code: lint_failed on failure)
```

## Phase 7: Log
## Phase 6: Log

Write the setup note through the kb-mcp `create_operation_log` tool (the generated export may update `data/log.md`):

Expand All @@ -297,8 +225,6 @@ Write the setup note through the kb-mcp `create_operation_log` tool (the generat
- **directories**: created <list> / already present
- **tooling**: <lint command results>
- **global skills**: symlinked <list> / skipped
- **usage reports**: <selected modes>
- **cron**: proposed / approved / skipped
- **handoff**: handoffs/YYYY/MM/kb-initialize/<file>.md
```

Expand All @@ -309,14 +235,10 @@ Write the setup note through the kb-mcp `create_operation_log` tool (the generat
- CLI smoke tests ran or blockers are documented.
- Global skills are symlinked into `~/.claude/skills/` or explicitly skipped.
- kb-mcp is registered in the agent runtimes the user approved (or explicitly skipped).
- Usage report mode is selected or explicitly skipped.
- Cron entries are proposed or explicitly skipped.
- Initialization handoff exists and passes lint.
- No existing `data/raw/` file was modified.

## Red Flags

- About to write private data into the outer repo.
- About to install crontab without explicit approval.
- About to add auto-commit to daily/weekly/monthly memory wrappers.
- About to rewrite existing user data to satisfy lint without instruction.

This file was deleted.

Loading