Skip to content

Commit dab4e17

Browse files
LemonNekoGHLemonNekoGH
committed
fix(coding-agents): try to use neat-freak
1 parent 7e52e3d commit dab4e17

7 files changed

Lines changed: 312 additions & 38 deletions

File tree

‎.codex/skills/neat-freak/SKILL.md‎

Lines changed: 140 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,140 @@
1+
---
2+
name: neat-freak
3+
description: >
4+
End-of-session knowledge cleanup with strict documentation hygiene. Reconcile
5+
project docs, agent instructions, and durable memory against the current code
6+
so the project stays accurate for future agents and human maintainers. Trigger
7+
when the user asks to sync, tidy, clean up docs, update memory, prepare a
8+
handoff, finish a milestone, or make the project easy for a new maintainer to
9+
pick up.
10+
---
11+
12+
# Knowledge Base Neat-Freak
13+
14+
You are a knowledge-base editor, not a changelog recorder. Your job is to keep
15+
project knowledge clean, accurate, consolidated, and useful to someone arriving
16+
with no context.
17+
18+
Use English only in responses, project documentation, and agent-facing notes
19+
unless the user explicitly requests a non-English artifact.
20+
21+
## Upstream Attribution
22+
23+
This repo-local skill is adapted from the upstream `neat-freak` skill in
24+
KKKKhazix's `khazix-skills` repository:
25+
26+
- https://github.com/KKKKhazix/khazix-skills/blob/main/neat-freak/SKILL.md
27+
28+
The local version has been rewritten for this repository's constraints:
29+
30+
- English-only project communication and documentation.
31+
- Codex-oriented project and global instruction paths.
32+
- A self-check for citing an official document, upstream GitHub repository, or
33+
relevant community discussion when project instructions require source-backed
34+
technical approach guidance.
35+
36+
## Knowledge Layers
37+
38+
Keep the audience boundaries clear:
39+
40+
- Durable agent memory or global instructions: cross-project user preferences,
41+
non-obvious long-lived facts, and reusable references.
42+
- Project `AGENTS.md`, `CLAUDE.md`, or equivalent: project-specific agent
43+
constraints, structure, commands, tooling, and red lines.
44+
- Project `README.md` and `docs/`: human-facing onboarding, integration,
45+
architecture, operations, and handoff material.
46+
47+
Do not paste the same content everywhere. Update each layer for its audience.
48+
49+
## Workflow
50+
51+
### 1. Inventory
52+
53+
Perform a mechanical inventory before deciding what to edit:
54+
55+
1. List agent memory or global instruction files if the platform has them.
56+
For Codex, check `~/.codex/AGENTS.md`, project `AGENTS.md`, and repo-local
57+
`.codex/skills/`.
58+
2. For each project touched in the conversation:
59+
- `ls <project-root>/`
60+
- `ls <project-root>/docs/ 2>/dev/null`
61+
- `find <project-root> -maxdepth 2 -name "*.md" -not -path "*/node_modules/*" -not -path "*/.git/*"`
62+
- Read `README.md`, `AGENTS.md` or `CLAUDE.md`, and every `docs/*.md`.
63+
3. Search for additional Markdown files deeper in the repo when relevant.
64+
4. Review the conversation for facts that changed.
65+
66+
Maintain an internal list marking every discovered file as reviewed, changed, or
67+
intentionally unchanged.
68+
69+
### 2. Identify Impact
70+
71+
Think in terms of impact, not just the latest diff:
72+
73+
- New API, route, or protocol: update project agent notes, integration docs, and
74+
architecture docs.
75+
- New or renamed environment variable: update project agent notes, runbooks, and
76+
downstream setup docs.
77+
- New user flow or major feature: update README commands or usage, architecture,
78+
and handoff notes if present.
79+
- Cross-project protocol or SDK changes: update both the producer and consumer
80+
project documentation.
81+
- Stale memory: update or delete it rather than appending a competing note.
82+
83+
Use `references/sync-matrix.md` when uncertain.
84+
85+
### 3. Edit
86+
87+
Actually modify files. A plan is not enough.
88+
89+
Editing principles:
90+
91+
- Merge updates into existing sections instead of appending duplicate notes.
92+
- Delete stale temporary plans and superseded decisions.
93+
- Prefer precise, compact wording over broad narrative.
94+
- Use absolute dates such as `2026-04-29`; do not use relative time phrases
95+
like "today" or "recently".
96+
- Keep project docs useful to a first-time reader with limited time.
97+
- Be very conservative with global instructions; project facts belong in the
98+
project.
99+
100+
### 4. Self-Check
101+
102+
Before the final response, verify:
103+
104+
- Every file from the inventory was reviewed or intentionally skipped.
105+
- Project instructions mention only paths, commands, and tools that exist.
106+
- README run/build commands match the repository tooling.
107+
- New APIs or protocols appear in both usage-facing and architecture-facing
108+
docs when those docs exist.
109+
- Technical approach guidance cites at least one relevant source when required
110+
by project instructions.
111+
- Cross-project effects were checked.
112+
- No relative time phrases remain.
113+
- No unintended local absolute paths remain in docs.
114+
- No non-English text remains unless explicitly requested by the user.
115+
116+
Useful checks:
117+
118+
```sh
119+
rg -n 'today|yesterday|recently|last week' -g '*.md' -g '!node_modules/**' -g '!.git/**'
120+
rg -n '/Users|/private|/var/folders|/tmp/' -g '*.md' -g '!node_modules/**' -g '!.git/**'
121+
rg -n '[\p{Han}]' -g '*.md' -g '!node_modules/**' -g '!.git/**'
122+
git diff --check
123+
```
124+
125+
### 5. Summarize
126+
127+
After editing, summarize only actual changes:
128+
129+
- Memory or global instruction changes, if any.
130+
- Project documentation changes, grouped by project.
131+
- Unhandled items, with the reason they were not handled.
132+
133+
Keep the final response concise and in English.
134+
135+
## References
136+
137+
- `references/sync-matrix.md`: mapping from change types to documentation
138+
surfaces.
139+
- `references/agent-paths.md`: common agent memory, instruction, and skill
140+
paths.

‎.codex/skills/neat-freak/references/agent-paths.md‎

Lines changed: 57 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,57 @@
1+
# Agent Paths Reference
2+
3+
Use this file during the inventory step to locate durable instructions, memory,
4+
and skills for common coding-agent environments.
5+
6+
## OpenAI Codex
7+
8+
| Purpose | Path |
9+
|---|---|
10+
| Global instructions | `~/.codex/AGENTS.md` or `$CODEX_HOME/AGENTS.md` |
11+
| Project instructions | Project-root `AGENTS.md` |
12+
| Project override | `AGENTS.override.md`, when present |
13+
| Global skills | `~/.codex/skills/<name>/SKILL.md` |
14+
| Project skills | `.codex/skills/<name>/SKILL.md` |
15+
16+
Codex does not have a separate memory-index system. Durable project facts should
17+
live in project `AGENTS.md`; cross-project preferences may belong in global
18+
`AGENTS.md` only when the user clearly wants them to apply everywhere.
19+
20+
## Claude Code
21+
22+
| Purpose | Path |
23+
|---|---|
24+
| Global memory | `~/.claude/projects/<encoded-project-path>/memory/` |
25+
| Memory index | `~/.claude/projects/<encoded-project-path>/memory/MEMORY.md` |
26+
| Global instructions | `~/.claude/CLAUDE.md` |
27+
| Project instructions | Project-root `CLAUDE.md` |
28+
| Skills | `~/.claude/skills/<name>/SKILL.md` |
29+
30+
Memory files commonly use YAML frontmatter such as `name`, `description`, and
31+
`type`.
32+
33+
## OpenCode
34+
35+
| Purpose | Path |
36+
|---|---|
37+
| Global config | `~/.config/opencode/` |
38+
| Project config | `.opencode/` |
39+
| Project skills | `.opencode/skills/`, `.claude/skills/`, `.codex/skills/` |
40+
| Global skills | `~/.config/opencode/skills/`, `~/.claude/skills/`, `~/.codex/skills/` |
41+
42+
OpenCode may read both Claude-style and Codex-style skill directories.
43+
44+
## OpenClaw
45+
46+
| Purpose | Path |
47+
|---|---|
48+
| User skills | `~/.openclaw/skills/<name>/SKILL.md` |
49+
| Project skills | `.openclaw/skills/<name>/SKILL.md` |
50+
| Workspace skills | Workspace `skills/` directory |
51+
52+
## Cross-Agent Projects
53+
54+
For projects used by multiple agent platforms, prefer one canonical project
55+
instruction file plus small pointers from platform-specific files, or keep the
56+
platform files deliberately synchronized. `README.md` and `docs/` should remain
57+
platform-neutral.

‎.codex/skills/neat-freak/references/sync-matrix.md‎

Lines changed: 53 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,53 @@
1+
# Documentation Sync Matrix
2+
3+
Use this matrix when it is unclear which documentation surfaces should change.
4+
5+
## Code Changes to Documentation Changes
6+
7+
| Change | Documentation surfaces |
8+
|---|---|
9+
| New API, route, or protocol | Project agent instructions, integration guide or usage docs, architecture docs |
10+
| Renamed API, route, or protocol | Same as new API, plus search and replace stale names |
11+
| New or renamed environment variable | Project agent instructions, operator runbook, downstream setup docs |
12+
| New database table or schema | Project agent instructions, architecture data model |
13+
| New user flow | README usage, architecture flow notes, handoff or changelog if present |
14+
| Major feature across multiple files | README, architecture, integration or usage docs, runbook, handoff or changelog |
15+
| Terminology change | Glossary or integration docs if present, plus global stale-term search |
16+
| Deployment or infrastructure change | Operator runbook, project agent instructions, README setup when relevant |
17+
| SDK or downstream integration change | Producer integration docs and consumer project docs |
18+
19+
## Memory and Instruction Changes
20+
21+
| Situation | Action |
22+
|---|---|
23+
| Stale fact | Replace or delete the old fact |
24+
| Relative time phrase | Convert to an absolute date |
25+
| Duplicate memories | Merge into one clear note |
26+
| Completed temporary task | Delete it |
27+
| Reversed decision | Remove the old decision and keep the current one |
28+
| One-off context | Delete it unless it still affects future work |
29+
30+
## Cross-Project Checks
31+
32+
Search dependent projects whenever the change involves:
33+
34+
- shared protocols
35+
- SDKs
36+
- public routes or subdomains
37+
- environment variables
38+
- authentication or authorization flows
39+
- shared infrastructure
40+
41+
The producer and consumer documentation must agree.
42+
43+
## Standard Documentation Shape
44+
45+
For a new capability, update these surfaces when they exist:
46+
47+
1. Usage or integration docs: how to use it.
48+
2. Architecture docs: how it works.
49+
3. Runbook docs: how to operate or debug it.
50+
4. Handoff or changelog docs: what changed.
51+
52+
Keep high-frequency references such as API tables, environment-variable tables,
53+
and terminology lists current.

‎AGENTS.md‎

Lines changed: 36 additions & 18 deletions
Original file line numberDiff line numberDiff line change
@@ -9,14 +9,14 @@ The current milestone is limited to:
99

1010
1. create a platform WebView
1111
2. establish bidirectional IPC between Godot and the WebView
12-
3. stabilize the Kirie plugin shape before adding larger tooling layers
12+
3. support packaged `res://` web content loading enough for bridge tests
13+
4. stabilize the Kirie plugin shape before adding larger tooling layers
1314

1415
Do not introduce extra packages, adapters, or CLI workflows unless they are
15-
required to make the current IPC milestone work.
16-
17-
A future browser-facing `KirieIpcBridge` SDK is allowed as a follow-up layer,
18-
but it is not part of the current milestone unless the user explicitly asks for
19-
it.
16+
required to make the current IPC milestone work. The existing `@kirie/ipc`
17+
package is a thin browser-side transport wrapper; do not expand it into an
18+
application event or invocation layer unless the user explicitly asks for that
19+
higher-level work.
2020

2121
## Repository Layout
2222

@@ -27,8 +27,16 @@ it.
2727
Kotlin Android implementation
2828
- `packages/kirie/native/ios`
2929
Swift iOS implementation
30+
- `packages/ipc`
31+
thin browser-side IPC transport wrapper for WebView pages
3032
- `examples/basic-ipc`
31-
the first integration and regression target
33+
the first runnable manual integration target
34+
- `tests/integration`
35+
exported-app platform bridge regression target
36+
- `scripts`
37+
local build and run helpers for Android and iOS validation
38+
- `.codex/skills`
39+
repo-local Codex skills for project maintenance workflows
3240
- `docs`
3341
lightweight architecture notes
3442

@@ -37,6 +45,12 @@ it.
3745
Prefer the official references collected in `docs/references.md` before relying
3846
on memory for Godot plugin APIs or platform WebView behavior.
3947

48+
When proposing or adopting a technical approach, cite at least one relevant
49+
source: official documentation, the upstream GitHub repository, or a relevant
50+
community discussion. Prefer official documentation or upstream repositories for
51+
API and compatibility decisions. Treat community comments as supplemental and
52+
label them as anecdotal when they influence a decision.
53+
4054
## Design Constraints
4155

4256
- Treat `Kirie` as the service layer API.
@@ -47,14 +61,16 @@ on memory for Godot plugin APIs or platform WebView behavior.
4761
application event layer.
4862
- Defer higher-level semantics such as invocation APIs and richer event models
4963
to layers above `kirie`, such as future adapters.
50-
- Defer browser-side convenience wrappers such as `KirieIpcBridge` until after
51-
the native IPC path is working end to end.
64+
- Keep `@kirie/ipc` as a thin browser-side transport wrapper around the raw
65+
native bridge. Defer richer browser SDKs until there is a real app-level use
66+
case.
5267
- For the current milestone, assume a single active WebView unless the user
5368
explicitly asks to reintroduce multi-WebView behavior.
5469
- Keep the Godot-facing wrapper thin; prefer forwarding to the platform
5570
singleton over reimplementing platform lifecycle logic in GDScript.
56-
- Keep in mind that Kirie is expected to support offline web content sourced
57-
from project resources, including future `res://`-based loading flows.
71+
- Kirie supports packaged web content sourced from project resources through
72+
`res://web` loading on the current native paths. Runtime-mounted Godot packs
73+
remain out of scope for that loading path.
5874
- If an API is needed by both GDScript and C#, define the shape once and keep
5975
C# as a thin wrapper.
6076

@@ -89,8 +105,11 @@ that is deferred work and should not complicate the current IPC milestone.
89105
## Working Style
90106

91107
- Keep changes aligned with the current milestone.
108+
- Use English only for agent-facing communication, project-maintenance notes,
109+
AGENTS updates, and project documentation unless the user explicitly requests
110+
a non-English artifact.
92111
- Favor small, testable steps that can be exercised through
93-
`examples/basic-ipc`.
112+
`examples/basic-ipc` or `tests/integration`.
94113
- When touching native code, keep the Godot-facing API stable unless there is a
95114
strong reason to change it.
96115
- When adding agent-facing guidance, prefer `AGENTS.md` and repo-local skills
@@ -160,7 +179,8 @@ configured yet.
160179

161180
### Validation
162181

163-
- Prefer validating through `examples/basic-ipc`.
182+
- Use `examples/basic-ipc` for manual smoke validation and `tests/integration`
183+
for exported-app platform bridge regressions.
164184
- Run the relevant lint target through mise after changing a covered language:
165185
- GDScript: `mise x -- corepack pnpm run lint:gdscript`
166186
- TypeScript, JSON, CSS, and HTML: `mise x -- corepack pnpm run lint:biome`
@@ -181,7 +201,7 @@ configured yet.
181201
`scripts/build_kirie_ios.sh` so `examples/basic-ipc/ios/plugins/kirie/Kirie.xcframework`
182202
is refreshed before any device testing.
183203
- When changing the IPC shape, make sure at least one real request/response
184-
round-trip remains covered by the example.
204+
round-trip remains covered by the example or integration tests.
185205

186206
### Dependencies
187207

@@ -233,11 +253,9 @@ infrastructure.
233253
checks.
234254
- Code generation pipelines for future C# wrappers or shared API declarations do
235255
not exist yet.
236-
- A browser-facing `KirieIpcBridge` SDK shape is being considered for future
237-
cross-platform web usage, but it is not implemented yet.
256+
- Richer app-level adapters or invocation APIs above `@kirie/ipc` are not
257+
implemented yet.
238258
- Binary distribution policy is not finalized yet for Android Maven artifacts,
239259
local `.aar` files, or iOS plugin packaging outputs.
240260
- An editor-driven generated `gdip` shim flow is being considered for future
241261
iOS packaging, but it is not implemented yet.
242-
- The example project is planned as the main integration target, but the actual
243-
runnable Godot example has not been created yet.

0 commit comments

Comments
 (0)