Skip to content

Commit 89c516a

Browse files
thieungthieung
authored
feat(skill): make goclaw source path configurable for contributors (#22)
Support GOCLAW_SOURCE_PATH env var with fallback to ../goclaw/ so contributors can clone goclaw anywhere. Remove hardcoded relative paths from SKILL.md, README.md, and mapping.json.
1 parent 5567e84 commit 89c516a

3 files changed

Lines changed: 343 additions & 0 deletions

File tree

‎.claude/skills/goclaw-docs-audit/README.md‎

Lines changed: 124 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,124 @@
1+
# GoClaw Docs Audit Skill
2+
3+
Detect which GoClaw documentation pages need updating when the GoClaw source code changes. Cross-checks accuracy against GoClaw source docs (source of truth).
4+
5+
## Quick Start
6+
7+
```
8+
/goclaw-docs-audit
9+
```
10+
11+
## Usage
12+
13+
| Command | Description |
14+
|---------|-------------|
15+
| `/goclaw-docs-audit` | Audit all changes since last audit (or last commit if first run) |
16+
| `/goclaw-docs-audit HEAD~5..HEAD` | Audit a specific commit range |
17+
| `/goclaw-docs-audit HEAD~10..HEAD` | Audit last 10 commits |
18+
| `/goclaw-docs-audit internal/agent/loop.go` | Audit specific file(s) |
19+
| `/goclaw-docs-audit internal/agent/loop.go internal/tools/registry.go` | Audit multiple files |
20+
21+
## What It Does
22+
23+
1. **Identifies changed files** in the GoClaw source repo (resolved via `GOCLAW_SOURCE_PATH` env var, fallback `../goclaw/`)
24+
2. **Maps changes to docs pages** using `mapping.json` (40 glob rules covering all `internal/` packages)
25+
3. **Accuracy check** — compares goclaw-docs content against GoClaw source docs (source of truth) for factual correctness
26+
4. **EN-VI sync check** — detects outdated Vietnamese translations
27+
5. **Generates report** with affected pages, accuracy status, and recommended actions
28+
29+
## Report Output
30+
31+
Reports are saved to `plans/reports/docs-audit-YYYY-MM-DD.md` with three sections:
32+
33+
- **Affected Docs Pages** — which docs need review, grouped by priority (High/Medium/Low)
34+
- **Accuracy Check** — discrepancies between goclaw-docs and `../goclaw/docs/` source of truth
35+
- **EN-VI Sync Status** — which Vietnamese translations are outdated
36+
37+
## Last Audit Tracking
38+
39+
The skill automatically tracks when you last ran an audit via `.last-audit` file (gitignored). When you run `/goclaw-docs-audit` without arguments:
40+
- **First run**: audits the last commit only (`HEAD~1..HEAD`)
41+
- **Subsequent runs**: audits all changes since the previous audit's commit hash
42+
43+
This means you can just run `/goclaw-docs-audit` periodically and it will only show new changes.
44+
45+
## File Structure
46+
47+
```
48+
.claude/skills/goclaw-docs-audit/
49+
├── SKILL.md # Skill definition and step-by-step instructions
50+
├── mapping.json # 40 glob rules mapping Go source paths → doc pages
51+
├── .last-audit # Last audit commit hash (gitignored, auto-generated)
52+
└── README.md # This file
53+
```
54+
55+
## Mapping Rules
56+
57+
`mapping.json` maps GoClaw source code paths to documentation pages with priority levels:
58+
59+
| Priority | Source Packages | Example Docs |
60+
|----------|----------------|--------------|
61+
| **High** | `agent`, `tools`, `gateway`, `memory`, `tasks`, `migrations` | `agents/*`, `core-concepts/*`, `reference/websocket-protocol.md` |
62+
| **Medium** | `providers`, `channels/*`, `bootstrap`, `config`, `sessions`, `tracing`, `http`, `knowledgegraph` | `providers/*.md`, `channels/*.md`, `deployment/observability.md` |
63+
| **Low** | `scheduler`, `cron`, `sandbox`, `tts`, `skills`, `cache`, `media`, `i18n`, `crypto` | `advanced/scheduling-cron.md`, `advanced/sandbox.md` |
64+
65+
## Source of Truth
66+
67+
The GoClaw source repo's `docs/` directory contains authoritative technical documents. During accuracy checks, the skill compares goclaw-docs user-facing pages against these internal docs:
68+
69+
| GoClaw Internal Doc | Topic |
70+
|---------------------|-------|
71+
| `00-architecture-overview.md` | Overall architecture |
72+
| `01-agent-loop.md` | Agent loop, reasoning |
73+
| `02-providers.md` | LLM providers |
74+
| `03-tools-system.md` | Tools registration & execution |
75+
| `04-gateway-protocol.md` | WebSocket/RPC protocol |
76+
| `05-channels-messaging.md` | Channel integrations |
77+
| `06-store-data-model.md` | Database schema |
78+
| `07-bootstrap-skills-memory.md` | Bootstrap, skills, memory |
79+
| `08-scheduling-cron.md` | Cron & scheduling |
80+
| `09-security.md` | Security & permissions |
81+
| `10-tracing-observability.md` | OpenTelemetry |
82+
| `11-agent-teams.md` | Agent teams |
83+
| `12-extended-thinking.md` | Extended thinking |
84+
| `13-ws-team-events.md` | WebSocket team events |
85+
| `14-skills-runtime.md` | Skills runtime |
86+
| `15-core-skills-system.md` | Core skills |
87+
| `16-skill-publishing.md` | Skill publishing |
88+
| `17-changelog.md` | Changelog |
89+
| `18-http-api.md` | HTTP/REST API |
90+
| `19-websocket-rpc.md` | WebSocket RPC methods |
91+
| `20-api-keys-auth.md` | API keys & auth |
92+
93+
## Prerequisites
94+
95+
- GoClaw source repo must be accessible. The skill resolves the path in this order:
96+
1. `GOCLAW_SOURCE_PATH` environment variable (set in shell or `.claude/settings.local.json`)
97+
2. Fallback: `../goclaw/` (assumes `goclaw/` and `goclaw-docs/` share the same parent folder)
98+
- Both repos should have git history available
99+
100+
**Contributor setup** (if goclaw is not at `../goclaw/`):
101+
```bash
102+
export GOCLAW_SOURCE_PATH=/path/to/my/goclaw
103+
```
104+
Or in `.claude/settings.local.json`:
105+
```json
106+
{ "env": { "GOCLAW_SOURCE_PATH": "/path/to/my/goclaw" } }
107+
```
108+
109+
## Examples
110+
111+
### After merging a PR that changes agent logic
112+
```
113+
/goclaw-docs-audit HEAD~1..HEAD
114+
```
115+
116+
### Before a docs release — check all recent changes
117+
```
118+
/goclaw-docs-audit HEAD~20..HEAD
119+
```
120+
121+
### Spot-check specific files you're about to modify
122+
```
123+
/goclaw-docs-audit internal/gateway/handler.go internal/agent/loop.go
124+
```

‎.claude/skills/goclaw-docs-audit/SKILL.md‎

Lines changed: 173 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,173 @@
1+
---
2+
name: goclaw-docs-audit
3+
description: "Detect which GoClaw docs pages need updating when source code changes."
4+
argument-hint: "[commit-range|file1 file2 ...]"
5+
metadata:
6+
author: goclaw
7+
version: "2.0.0"
8+
---
9+
10+
# GoClaw Docs Audit
11+
12+
> Detect which GoClaw docs need updating when GoClaw source code changes.
13+
> Cross-check accuracy against GoClaw source docs (source of truth).
14+
15+
## Trigger
16+
17+
`/goclaw-docs-audit` or `/goclaw-docs-audit <commit-range>` or `/goclaw-docs-audit <file1> <file2>`
18+
19+
## Usage
20+
21+
- `/goclaw-docs-audit` — audit all changes since last audit (or last commit if first run)
22+
- `/goclaw-docs-audit HEAD~5..HEAD` — audit specific commit range
23+
- `/goclaw-docs-audit internal/agent/loop.go internal/channels/telegram/bot.go` — audit specific files
24+
25+
## GoClaw Source Path
26+
27+
The skill needs access to the GoClaw source repository. Resolution order:
28+
29+
1. **`GOCLAW_SOURCE_PATH`** environment variable (set in shell or `.claude/settings.local.json`)
30+
2. **Fallback:** `../goclaw/` (assumes `goclaw/` and `goclaw-docs/` share the same parent folder)
31+
32+
If neither resolves to a valid git repo, ask the user for the path.
33+
34+
**Contributor setup example:**
35+
```bash
36+
export GOCLAW_SOURCE_PATH=/path/to/my/goclaw
37+
```
38+
Or in `.claude/settings.local.json`:
39+
```json
40+
{ "env": { "GOCLAW_SOURCE_PATH": "/path/to/my/goclaw" } }
41+
```
42+
43+
## Instructions
44+
45+
When this skill is triggered, follow these steps exactly:
46+
47+
### Step 0: Resolve GoClaw Source Path
48+
49+
Determine `$GOCLAW_SOURCE` using the resolution order above:
50+
1. Check if `GOCLAW_SOURCE_PATH` env var is set and points to a valid git repo
51+
2. Otherwise check if `../goclaw/` exists and is a valid git repo
52+
3. If neither works, ask the user to set `GOCLAW_SOURCE_PATH`
53+
54+
Use `$GOCLAW_SOURCE` for all subsequent steps where `../goclaw/` was referenced.
55+
56+
### Step 1: Identify Changed Files
57+
58+
- If argument is a commit range (contains `..` or `HEAD`): run `git diff --name-only <range>` in `$GOCLAW_SOURCE`
59+
- If argument is file paths: use those directly
60+
- If no argument:
61+
1. Read `.claude/skills/goclaw-docs-audit/.last-audit` for the last audit commit hash
62+
2. If file exists: run `git diff --name-only <last-audit-hash>..HEAD` in `$GOCLAW_SOURCE`
63+
3. If file doesn't exist (first run): run `git diff --name-only HEAD~1..HEAD` in `$GOCLAW_SOURCE`
64+
65+
### Step 2: Load Mapping Rules
66+
67+
Read `mapping.json` from the same directory as this SKILL.md file.
68+
69+
The mapping also includes `source_of_truth` pointing to `docs/` (relative to `$GOCLAW_SOURCE`) — use those authoritative docs to verify accuracy of goclaw-docs pages.
70+
71+
### Step 3: Match Changed Files to Docs
72+
73+
For each changed file, check if its path matches any `pattern` in the mapping rules (use glob matching). Collect all matched `docs` pages and their `priority`.
74+
75+
### Step 4: Accuracy Check Against Source of Truth
76+
77+
For each matched docs page, cross-reference with the corresponding `$GOCLAW_SOURCE/docs/*.md` file:
78+
- Read the relevant goclaw internal doc (e.g., `01-agent-loop.md` for agent changes)
79+
- Compare key facts (config fields, API signatures, behavior descriptions) against what the goclaw-docs page says
80+
- Flag any discrepancies as "Needs accuracy update"
81+
82+
Source of truth mapping (`$GOCLAW_SOURCE/docs/`):
83+
| GoClaw Doc | Covers |
84+
|---|---|
85+
| `00-architecture-overview.md` | Overall architecture, component relationships |
86+
| `01-agent-loop.md` | Agent loop, reasoning, tool execution |
87+
| `02-providers.md` | LLM provider integrations |
88+
| `03-tools-system.md` | Tool registration, execution, built-in tools |
89+
| `04-gateway-protocol.md` | WebSocket/RPC protocol |
90+
| `05-channels-messaging.md` | Channel integrations |
91+
| `06-store-data-model.md` | Database schema, data model |
92+
| `07-bootstrap-skills-memory.md` | Bootstrap, skills, memory systems |
93+
| `08-scheduling-cron.md` | Cron jobs, scheduling |
94+
| `09-security.md` | Security, auth, permissions |
95+
| `10-tracing-observability.md` | OpenTelemetry, tracing |
96+
| `11-agent-teams.md` | Agent teams, delegation |
97+
| `12-extended-thinking.md` | Extended thinking feature |
98+
| `13-ws-team-events.md` | WebSocket team events |
99+
| `14-skills-runtime.md` | Skills runtime |
100+
| `15-core-skills-system.md` | Core skills system |
101+
| `16-skill-publishing.md` | Skill publishing |
102+
| `17-changelog.md` | Changelog |
103+
| `18-http-api.md` | HTTP/REST API |
104+
| `19-websocket-rpc.md` | WebSocket RPC methods |
105+
| `20-api-keys-auth.md` | API keys, authentication |
106+
107+
### Step 5: Check EN-VI Sync Status
108+
109+
For each matched docs page in the goclaw-docs repo:
110+
- Get last modification date of the EN file (e.g., `getting-started/quick-start.md`)
111+
- Get last modification date of the VI file (e.g., `vi/getting-started/quick-start.md`)
112+
- If VI is older than EN, or VI doesn't exist: mark as "Outdated"
113+
- If VI is same date or newer: mark as "Synced"
114+
115+
Use `git log -1 --format=%cd --date=short -- <file>` to get last modification dates.
116+
117+
### Step 6: Generate Report
118+
119+
Create a markdown report with this format:
120+
121+
```markdown
122+
# GoClaw Docs Audit Report
123+
124+
**GoClaw changes:** `<commit-range or file list>`
125+
**Date:** YYYY-MM-DD
126+
127+
## Affected Docs Pages
128+
129+
| Changed File | Affected Docs | Priority |
130+
|---|---|---|
131+
| internal/agent/loop.go | agents/*, core-concepts/agents-explained.md | High |
132+
133+
## Accuracy Check (vs $GOCLAW_SOURCE/docs/)
134+
135+
| Docs Page | Source of Truth | Status | Notes |
136+
|---|---|---|---|
137+
| agents/creating-agents.md | 01-agent-loop.md | Accurate | — |
138+
| core-concepts/tools-overview.md | 03-tools-system.md | Discrepancy | Missing new tool type "x" |
139+
140+
## EN-VI Sync Status
141+
142+
| EN Page | Last EN Update | Last VI Update | Status |
143+
|---|---|---|---|
144+
| getting-started/quick-start.md | 2026-03-07 | 2026-03-01 | Outdated |
145+
146+
## Recommended Actions
147+
1. Review `agents/creating-agents.md` — agent creation flow changed
148+
2. Fix accuracy: `core-concepts/tools-overview.md` missing new tool type
149+
3. Sync VI translation for `getting-started/quick-start.md`
150+
```
151+
152+
### Step 7: Save Report
153+
154+
Save to `{goclaw-docs-root}/plans/reports/docs-audit-{YYYY-MM-DD}.md` or to the reports path provided by session context.
155+
156+
### Step 8: Update Last Audit Marker
157+
158+
After saving the report, record the current HEAD commit hash of `$GOCLAW_SOURCE` so the next no-argument run starts from here:
159+
160+
```bash
161+
cd $GOCLAW_SOURCE && git rev-parse HEAD > <goclaw-docs-root>/.claude/skills/goclaw-docs-audit/.last-audit
162+
```
163+
164+
The `.last-audit` file contains a single line: the commit hash. This file is gitignored.
165+
166+
## Key Rules
167+
168+
- GoClaw source path is resolved via `GOCLAW_SOURCE_PATH` env var, fallback to `../goclaw/` (assumes same parent folder)
169+
- `$GOCLAW_SOURCE/docs/` is the **source of truth** for feature accuracy
170+
- Docs live in `goclaw-docs/` (EN at root, VI under `vi/`)
171+
- If no GoClaw repo found, ask user for the path
172+
- Always show: affected docs, accuracy check, AND EN-VI sync status
173+
- Group results by priority (High → Medium → Low)

‎.claude/skills/goclaw-docs-audit/mapping.json‎

Lines changed: 46 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,46 @@
1+
{
2+
"rules": [
3+
{"pattern": "internal/agent/*", "docs": ["agents/*", "core-concepts/agents-explained.md", "core-concepts/how-goclaw-works.md"], "priority": "high"},
4+
{"pattern": "internal/providers/*", "docs": ["providers/*.md"], "priority": "medium"},
5+
{"pattern": "internal/channels/telegram/*", "docs": ["channels/telegram.md"], "priority": "medium"},
6+
{"pattern": "internal/channels/discord/*", "docs": ["channels/discord.md"], "priority": "medium"},
7+
{"pattern": "internal/channels/feishu/*", "docs": ["channels/feishu.md", "channels/larksuite.md"], "priority": "medium"},
8+
{"pattern": "internal/channels/zalo/*", "docs": ["channels/zalo-oa.md", "channels/zalo-personal.md"], "priority": "medium"},
9+
{"pattern": "internal/channels/whatsapp/*", "docs": ["channels/whatsapp.md"], "priority": "medium"},
10+
{"pattern": "internal/channels/slack/*", "docs": ["channels/slack.md"], "priority": "medium"},
11+
{"pattern": "internal/channels/media/*", "docs": ["advanced/media-generation.md"], "priority": "low"},
12+
{"pattern": "internal/channels/typing/*", "docs": ["channels/overview.md"], "priority": "low"},
13+
{"pattern": "internal/channels/*", "docs": ["channels/overview.md", "channels/INDEX.md", "advanced/channel-instances.md"], "priority": "medium"},
14+
{"pattern": "internal/tools/*", "docs": ["core-concepts/tools-overview.md", "advanced/custom-tools.md"], "priority": "high"},
15+
{"pattern": "internal/gateway/*", "docs": ["reference/websocket-protocol.md", "reference/rest-api.md", "core-concepts/how-goclaw-works.md"], "priority": "high"},
16+
{"pattern": "internal/store/pg/*", "docs": ["reference/database-schema.md", "troubleshooting/database.md"], "priority": "medium"},
17+
{"pattern": "migrations/*", "docs": ["deployment/database-setup.md", "reference/database-schema.md", "deployment/upgrading.md"], "priority": "high"},
18+
{"pattern": "internal/mcp/*", "docs": ["advanced/mcp-integration.md"], "priority": "medium"},
19+
{"pattern": "internal/scheduler/*", "docs": ["advanced/scheduling-cron.md"], "priority": "low"},
20+
{"pattern": "internal/cron/*", "docs": ["advanced/scheduling-cron.md"], "priority": "low"},
21+
{"pattern": "internal/bootstrap/*", "docs": ["agents/context-files.md", "agents/system-prompt-anatomy.md", "agents/summoning-bootstrap.md"], "priority": "medium"},
22+
{"pattern": "internal/hooks/*", "docs": ["advanced/hooks-quality-gates.md"], "priority": "medium"},
23+
{"pattern": "internal/memory/*", "docs": ["core-concepts/memory-system.md"], "priority": "high"},
24+
{"pattern": "internal/skills/*", "docs": ["advanced/skills.md"], "priority": "low"},
25+
{"pattern": "internal/sandbox/*", "docs": ["advanced/sandbox.md", "advanced/exec-approval.md"], "priority": "low"},
26+
{"pattern": "internal/tts/*", "docs": ["advanced/tts-voice.md"], "priority": "low"},
27+
{"pattern": "internal/permissions/*", "docs": ["agents/sharing-and-access.md", "advanced/api-keys-rbac.md"], "priority": "medium"},
28+
{"pattern": "internal/config/*", "docs": ["reference/config-reference.md", "reference/environment-variables.md", "getting-started/configuration.md"], "priority": "medium"},
29+
{"pattern": "cmd/*", "docs": ["reference/cli-commands.md"], "priority": "medium"},
30+
{"pattern": "ui/web/*", "docs": ["getting-started/web-dashboard-tour.md"], "priority": "low"},
31+
{"pattern": "internal/tasks/*", "docs": ["agent-teams/*"], "priority": "high"},
32+
{"pattern": "internal/bus/*", "docs": ["agent-teams/team-messaging.md", "core-concepts/how-goclaw-works.md"], "priority": "medium"},
33+
{"pattern": "internal/sessions/*", "docs": ["core-concepts/sessions-and-history.md", "advanced/context-pruning.md"], "priority": "medium"},
34+
{"pattern": "internal/tracing/*", "docs": ["deployment/observability.md"], "priority": "medium"},
35+
{"pattern": "internal/oauth/*", "docs": ["advanced/authentication.md"], "priority": "medium"},
36+
{"pattern": "internal/crypto/*", "docs": ["deployment/security-hardening.md", "advanced/cli-credentials.md"], "priority": "low"},
37+
{"pattern": "internal/cache/*", "docs": ["advanced/caching.md"], "priority": "low"},
38+
{"pattern": "internal/media/*", "docs": ["advanced/media-generation.md"], "priority": "low"},
39+
{"pattern": "internal/knowledgegraph/*", "docs": ["advanced/knowledge-graph.md"], "priority": "medium"},
40+
{"pattern": "internal/i18n/*", "docs": ["core-concepts/multi-tenancy.md"], "priority": "low"},
41+
{"pattern": "internal/upgrade/*", "docs": ["deployment/upgrading.md"], "priority": "medium"},
42+
{"pattern": "internal/http/*", "docs": ["reference/rest-api.md", "advanced/api-keys-rbac.md"], "priority": "medium"}
43+
],
44+
"source_of_truth": "docs/",
45+
"_source_of_truth_note": "Relative to $GOCLAW_SOURCE (resolved from GOCLAW_SOURCE_PATH env var or ../goclaw/ fallback)"
46+
}

0 commit comments

Comments
 (0)