[codex] add config setup skill routing#61
Conversation
There was a problem hiding this comment.
Pull request overview
Adds a “config-first” setup path so Codemap can detect when .codemap/config.json is missing/boilerplate/malformed and surface config-setup guidance early via hooks, skill routing, and plugin docs.
Changes:
- Introduces config assessment helpers (
AssessSetup,SetupState,IsZero,LooksBoilerplate) and uses them to drive setup hints and skill injection. - Updates hooks (
session-start,prompt-submit) to emit acodemap:configmarker + human hint and to injectconfig-setupinto matched skills when config needs attention. - Adds/updates
config-setupand Codemap skill documentation across builtin skills, plugin bundles, and.claudeskill files; updates plugin metadata andcodemap config showmessaging.
Reviewed changes
Copilot reviewed 12 out of 12 changed files in this pull request and generated 2 comments.
Show a summary per file
| File | Description |
|---|---|
| skills/builtin/config-setup.md | Adds builtin config-setup skill content + metadata used for matching. |
| plugins/codemap/skills/config-setup/SKILL.md | Adds config-setup skill to Codemap plugin bundle. |
| plugins/codemap/skills/codemap/SKILL.md | Updates Codemap skill docs to recommend config tuning as a first-use workflow. |
| plugins/codemap/.codex-plugin/plugin.json | Updates plugin descriptions and default prompts to emphasize config tuning. |
| config/config.go | Adds setup assessment types/helpers and AssessSetup implementation. |
| config/config_test.go | Adds unit tests for IsZero, LooksBoilerplate, and AssessSetup. |
| cmd/hooks.go | Emits setup hint on session start and injects config-setup into matched skills when needed. |
| cmd/hooks_more_test.go | Adds tests for skill injection and the new codemap:config hint output. |
| cmd/config.go | Uses IsZero and surfaces boilerplate note in codemap config show. |
| cmd/config_more_test.go | Adds test ensuring config show suggests tuning for boilerplate configs. |
| .claude/skills/codemap/SKILL.md | Mirrors updated “config-first” guidance in Claude skill docs. |
| .claude/skills/codemap-setup/SKILL.md | Adds Claude skill bundle entry for config-setup. |
Comments suppressed due to low confidence (1)
cmd/config.go:172
configShowusesconfig.Load()(which returns a zero-value config on read/unmarshal errors) and then prints "Config is empty" when the file exists. This means a malformed or unreadable.codemap/config.jsonwill be reported as empty instead of malformed/unreadable. Consider switching this early-return branch to useconfig.AssessSetup(root)so you can distinguishmissingvsemptyvsmalformedand print the correct guidance.
func configShow(root string) {
cfg := config.Load(root)
if cfg.IsZero() {
cfgPath := config.ConfigPath(root)
if _, err := os.Stat(cfgPath); os.IsNotExist(err) {
fmt.Println("No config file found.")
fmt.Printf("Run 'codemap config init' to create %s\n", cfgPath)
} else {
fmt.Println("Config is empty (no filters active).")
}
return
💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.
| @@ -0,0 +1,52 @@ | |||
| --- | |||
| name: config-setup | |||
There was a problem hiding this comment.
This skill lives under .claude/skills/codemap-setup/ but its frontmatter name is config-setup. If the Claude skill loader keys off the directory name (as it does for the existing codemap skill), this mismatch can make the skill undiscoverable or confusing to reference. Consider renaming the directory to .claude/skills/config-setup/ (and keeping name: config-setup) so the path and skill name align.
| name: config-setup | |
| name: codemap-setup |
| var cfg ProjectConfig | ||
| if err := json.Unmarshal(data, &cfg); err != nil { | ||
| return SetupAssessment{ | ||
| State: SetupStateMalformed, | ||
| Reasons: []string{"The existing .codemap/config.json is malformed JSON."}, | ||
| } | ||
| } |
There was a problem hiding this comment.
AssessSetup treats a zero-length / whitespace-only .codemap/config.json as malformed because json.Unmarshal fails. If you want the reported states to match the intent of having a distinct empty state, consider special-casing len(strings.TrimSpace(string(data)))==0 (or similar) to return SetupStateEmpty with an appropriate reason before attempting to unmarshal.
![chatgpt-codex-connector[bot]](https://avatars.githubusercontent.com/in/1144995?s=60&v=4){kind=small}
There was a problem hiding this comment.
💡 Codex Review
Here are some automated review suggestions for this pull request.
Reviewed commit: f192932ed9
ℹ️ About Codex in GitHub
Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you
- Open a pull request for review
- Mark a draft as ready
- Comment "@codex review".
If Codex has suggestions, it will comment; otherwise it will react with 👍.
Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".
| structureBudget := projCfg.SessionStartOutputBytes() | ||
| maxHubs := projCfg.HubDisplayLimit() | ||
|
|
||
| showConfigSetupHint(root) |
There was a problem hiding this comment.
The new setup hint is only called at this point in hookSessionStart, but the function already returns early for meta-repos (len(childRepos) > 1) via hookSessionStartMultiRepo. In that common monorepo path, users with missing/boilerplate config never get the new codemap:config marker or human guidance, so the feature added in this commit is effectively skipped for multi-repo sessions.
Useful? React with 👍 / 👎.
Summary
This adds a model-first config setup path so Codemap can guide repo tuning before deeper analysis instead of waiting for users to discover it manually.
What changed
.codemap/config.jsonasmissing,empty,boilerplate,malformed, orreadysession-startvia acodemap:configmarker and human-readable hint when config needs attentionconfig-setupskill into prompt-submit matches when the repo is clearly unconfiguredcodemap config showto call out bootstrap configs and point users tocodemap skill show config-setupconfig-setupskill and mirrored it into the Claude and Codex plugin skill bundlesWhy
Codemap works much better once per-project config reflects the actual stack and ignores noisy non-code trees. Today that setup is mostly manual and easy to skip, which makes first-run output noisy in repos with assets, fixtures, PDFs, training data, or generated files.
This change makes setup discoverable through the same model-facing surfaces users already touch: hooks, skills, and the plugin.
Impact
config-setupfirst when the repo is unconfiguredValidation
go test ./...