AGENT SKILL

records-code-map

The code map for this project — where a file's sections and definitions are by line number, which files and lines mention a topic, and which checks, fixtures and cases cover a file. Use before searching or reading code to find something, before changing a file, and when deciding which test to run after an edit. The map is generated from the files on every call and never stored.

License 许可
MIT
最近更新
2026-11-14
Stars
★ 2
Forks
0

01 前言 Front Matter

lane
coding
name
records-code-map
strictness
standard
description
The code map for this project — where a file's sections and definitions are by line number, which files and lines mention a topic, and which checks, fixtures and cases cover a file. Use before searching or reading code to find something, before changing a file, and when deciding which test to run after an edit. The map is generated from the files on every call and never stored.
allowed-tools
Bash, Read

03 SKILL.md 正文

Records — Code Map

Holds one dataset: the map of this project's own code, produced by wf-map and addressed by file, by topic, or by what covers a file.

It is generated on every call and never stored. That is the dataset's defining property, not an optimisation. A hand-kept index drifts from the code in silence: the lab workspace carried a roster of about 30 subprojects in which 12 no longer existed on disk and 10 that did exist were missing, and nothing reported it for months. Regenerating costs one pass over the text — measured at 0.08 s on a 19,841-line file — so there is nothing a stored copy would buy.

Schema

Three views, each a stream of text rows on stdout. No file on disk, in any of them.

View Command One row is
outline wf-map <file> [<file>…] <line:int> <kind> <name> <first doc or comment line>, where kind is § (section), def, class or fn. Preceded by a header: path, language (python | shell | markdown | generic), line count, def count, section count
topic wf-map --topic <words…> a per-file block: <path> · <hits:int> hit(s) · <words matched:int>/<words asked:int>, then up to 3 <line:int> <text> rows. Ranked by words matched, then hits, then path
coverage wf-map --tests <file> three groups — the coverage COMMANDS present in this tree ($ <command> # <what it answers>, for the caller to run; nothing is executed), the conformance cases naming the file read out of expectations.json, and the handbook rows <handbook>:<line> Check|Regression|Negative: <command>

Options: --root DIR (default $CLAUDE_PROJECT_DIR, else the working directory), --limit N (outline rows, default 200; files shown per topic, max 12).

Exit codes: 0 mapped · 2 nothing readable, or the target resolved outside the root.

Invariants

Degraded state may cause more work. It may never authorize a write.

A map that is empty, truncated or refused sends its reader back to reading files. It never licenses an edit to a file nobody located, and it is never cited as evidence that something does not exist — wf-map --topic reporting nothing is a search that found nothing, which is the state ## Degradation answers.

Invariant Class
No row is ever written to disk — the map exists only on stdout mechanical
Every target resolves inside --root; a symlink leaving the tree is refused by name, before it is opened mechanical
Nothing in the mapped tree is executed, imported or loaded — not the file being mapped, and not a suite living there. A docstring match is not identity, so coverage commands are printed rather than run mechanical
Every vcs call overrides core.fsmonitor and core.hooksPath on the command line, because repository-local config can name an executable mechanical
At most 4 MiB is read per file, and a truncated outline says TRUNCATED in its header mechanical
--tests reuses the project's own selectors and keeps no coverage list of its own mechanical
A line number is the line in the file as it is on disk right now contextual — true only of an unedited file; re-run after an edit
An outline names what a file declares, never what it means advisory

Degradation

State Behaviour
absent the normal state. Nothing is stored, so every call starts here and generates the map
empty a file with no sections and no definitions prints its header with zero counts; a topic with no match says nothing matched. wf-map exits 2 when it mapped no file at all, because an empty map and a map of an empty file read alike on stdout
stale impossible to carry between calls, and that is the point. Within one call the map is as fresh as the file; after your own edit, re-run it
corrupt a binary or unreadable file is reported not readable as text and skipped; a path escaping the root is refused with its name and exit 2. Neither is repaired, and neither is reported as a map

Owner

engineering-coder — the employee that changes this repository's code is the one whose procedure reads this map. Its Lead is the second key.

The skill is the mechanism; the org chart is the policy. Nothing here prevents another employee from calling wf-map, and nothing needs to: the dataset is read-only by construction, since there is no stored copy for a second writer to race.

Git policy

Nothing to ignore, in any project. The map is never written, so no ignore rule exists or is needed; there is no path to name in .gitignore.

The script that produces it is tracked in the distribution at workforce/bin/wf-map and declared exec in manifest.txt. In an installed project it lands at <skills-root>/workforce/bin/wf-map.

Seed

An empty instance is the only instance:

(no file; the map is produced on each call)

Maintainers

Script Implements Load-bearing Negative test
workforce/bin/wf-map the three views above, the root containment rule, the read cap, and the refusal to execute anything in the mapped tree yes — an employee with no map searches by hand, which is the 21-42% of tool calls this exists to remove map-escape-symlink: a symlink out of the tree is handed to it → exits 2, names the path, reads nothing. Run 2026-10-12
bin/script-conformance --list (maintainer-only) answers which fixtures a change to a file can reach, transitively no — its absence costs the transitive fixture list, not correctness map-tests-handbook-check: a project with neither suite falls through to handbook Check: lines rather than reporting no coverage. Run 2026-10-12

A maintainer reports; it never repairs. wf-map writes nothing anywhere, which is the strongest form of that rule available to a script.

How it is reached

An employee calls it from Bash, by path:

WF="${CLAUDE_CONFIG_DIR:-$HOME/.claude}/skills/workforce"; [ -d "$WF" ] || WF="${CLAUDE_PROJECT_DIR}/.claude/skills/workforce"
"$WF/bin/wf-map" --topic session id            # which files and lines mention it
"$WF/bin/wf-map" src/widget.py                 # that file's sections and defs
"$WF/bin/wf-map" --tests src/widget.py         # what covers it, and the command to run

In this distribution's own repository the script is at workforce/bin/wf-map.

04 同仓库更多 Skills

odysseyalive
odysseyalive/claude-workforce

ui-design

Set a RENDERED interface's design direction before it is built, then evaluate what shipped. `direct` reads the project's CSS stack, asks about the case, researches real references for the job each screen does, hands the pick to the user, and writes the project's design record; `review` and `sweep` grade declared-vs-rendered slots (no missing or placeholder art), applied theme vs framework default, visual hierarchy, typography, colour roles, CTA, WCAG 2.2 AA contrast and focus, reflow at 320 CSS pixels, situation ergonomics, and AI-slop/templated-default tells. Use `direct` before the first UI build on a surface or for a new component pattern; use `review` after a UI-shipping change is written, when asked to design-review a page, or to decide whether a surface looks right to ship. Grades against a cited catalog with stable rule IDs and BLOCKS on hard-fail red flags. `review` and `sweep` are report-only.

★ 2
odysseyalive
odysseyalive/claude-workforce

timezone

Set the time zone Claude Code shows times in — the "done 7:55 PM" at the end of a turn, and the clock every command Claude runs sees. Use when the user asks to change, pick, set, fix or clear their time zone, or says the times shown are wrong (a remote server on UTC is the usual cause). Writes one key, env.TZ, into the user's own settings file.

★ 2
odysseyalive
odysseyalive/claude-workforce

text-eval

Evaluate written prose for AI-generation tells and register drift — mechanical character and punctuation defects, clustered judgment-class signals, citation integrity, and conversational register. Use after writing or editing any prose a person will read, when asked to check whether text reads as AI-generated, or before publishing copy. Grades against a cited catalog with clustering thresholds and hard rows that fire on first occurrence. Report-only.

★ 2
odysseyalive
odysseyalive/claude-workforce

shared-artifact

The house style for any shareable online artifact — a claude.ai Artifact, a published HTML page, a report or brief someone will be sent a link to. Use before writing or republishing any artifact page, when asked to create, share, publish or clean up an online artifact, and when deciding between an HTML page and a Claude Docs document. Carries the token set, the dark-mode contract, the briefing-binder layout, a starter template, and the sharing hygiene rules.

★ 2
odysseyalive
odysseyalive/claude-workforce

security-evaluator

Evaluate a code change for web-security flaws — OWASP Top 10:2025 classes as source-review classes, taint signals from source to sink, and a per-language sink appendix. Use after writing or editing code that handles input, auth, data access, templating, deserialization, or external requests; when asked to security-review a change, check for injection/XSS/SSRF/authz flaws, or evaluate the security of what was just written. Report-only, candidate-tier by construction.

★ 2
odysseyalive
odysseyalive/claude-workforce

code-evaluator

Evaluate code to prevent common AI coding mistakes — dead code, duplication, complexity hotspots, reinvented helpers, leftover scaffolding. Two functions plus a pre-write advisor. Use after writing or editing code, when asked to review code quality, clean up the codebase, find unused code, find duplicates, check complexity, or evaluate what an AI just wrote. Commands: review (post-write), sweep (full codebase).

★ 2