Config

supermodo config

> Requires: the sibling protocols skill (shared protocol masters). Missing → tell the user to install the full supermodo package.

Keeper of the project's supermodo configuration. Its steady-state job is maintaining skills.config.json; bootstrap is just what it does when there is nothing to keep yet. Invasive by approved plan only — never by silent overwrite. Read ../protocols/references/config.md and ../protocols/references/docs-convention.md (the masters, in the sibling protocols skill — resolve relative to this SKILL.md's folder; if absent, tell the user to install the full supermodo package) before acting.

> Cross-tool note (Claude Code ↔ Codex). Written in Claude Code idioms. > Under Codex: ask the interview questions in chat, use your native task > tracking, and run scripts with node. The question format is plain chat on > every host.

Modes

| Invocation | Mode | | ----------------- | ------------------------------------------------------------------- | | config | Show the current config + validation result; offer edits. No config yet → run the bootstrap below automatically. | | config --edit [field] | Change one or more fields (interview just those, re-validate, show a before/after diff) | | config --upgrade | Migrate an existing skills.config.json to the current version |

Never re-scaffold over a configured project: with a valid config present, default invocation reports and offers edits — the bootstrap runs only when skills.config.json is absent (or the user explicitly asks to re-bootstrap, which follows the same conflict rules below).

---

Bootstrap (first run — no config exists)

1. Interview (plain chat, per the questions protocol)

Ask in concept-groups, one explanation + a recommended default per field. Keep it short — most fields have defaults. Discover candidates BEFORE asking.

• Project name — default: the working-directory basename.
• Docs entry — the router path. Default docs/README.md.
• Commands (argv arrays, never shell strings). First read

package.json scripts, deno.json/deno.jsonc tasks, and Makefile targets; propose concrete candidates, then confirm each. Map to tiers as available: test, testUnit, testAll, lint, coverage, mutation. Omit any tier the project lacks — do not invent commands. Example proposal: "Found deno task test → test: ["deno","task","test"]. Use it?"

• Coverage target — integer 1–100. Default 80.
• Agents dir — only if the project has an agent roster (.claude/agents,

.codex/agents). Absent → skills use their single-agent fallback; don't ask twice.

• GitLab — only if the user wants sync-gitlab. Then collect url

(must be https://), project (group/name), and the PAT env-var NAME (must match SUPERMODO_*); never a token value. Optional Cloudflare Access client id/secret env NAMES. Skip the whole section otherwise.

• Question transport — default chat; offer tool only on Claude Code

(global and per-skill overrides apply uniformly to every skill).

• Verbosity — default concise; standard for fuller chat reporting.

Class-(c) preference fields (name, coverage target, verbosity, transport) always come from the user even when a default is obvious.

2. Dry-run (mandatory) — enumerate before writing

Present the COMPLETE list of files that will be created or modified, then get explicit confirmation. Nothing is written before approval.

Docs scaffold (per ../protocols/references/docs-convention.md):

docs/README.md          # THE ROUTER, with generated nav markers:
                        #    … 
docs/CONVENTIONS.md     # prose conventions stub
docs/work/BACKLOG.md    # dated backlog, empty
docs/work/              # active task triads live here
docs/decisions/         # ADR-NNNN-.md
docs/reference/         # verified contracts
docs/archive/           # cold, completed work
skills.config.json      # the config (schema below)
.gitignore              # append one line: .skills/

Mark every generated doc that carries navigation with ` so librarian's scripts own it. Show the exact skills.config.json` you will write.

3. Handle conflicts as an explicit migration plan

If any target path already exists with non-generated content:

• Do NOT overwrite. Build a file-by-file migration plan: for each conflict,

propose move / merge / leave, and get approval per file.

• If the user declines the plan, HALT leaving the project unchanged.
• NEVER overwrite a file this skill did not itself mark

``. Invasiveness comes only from the approved plan.

4. Write + record a recoverable manifest

On approval, write files with write-temp-then-rename. Record every action (create/move/merge/append, with source→dest and a note) to .skills/supermodo/config-manifest.json so the change is reversible. Resolve that real path first and refuse to write outside the project's .skills/supermodo/ (containment rule, per the reports protocol). Append .skills/ to .gitignore (create it if missing; don't duplicate the line).

5. Validate

Run the bundled checker, resolving it relative to this installed SKILL folder (never a config path):

node /scripts/config-check.ts skills.config.json

Exit 0 = valid; on exit 1 print the field errors and fix them before reporting success. Then confirm the docs scaffold matches the convention.

---

config --edit [field]

Load + validate the current config first. Interview only the named field(s) — or ask which to change when none named — using the questions-protocol format. Show a before/after diff of the JSON, confirm, write (temp-then-rename), record the change in the manifest, re-validate. Class-(c) preference fields always confirm with the user even when the new value seems obvious.

config --upgrade

Current schema is configVersion: 1 — the only version. Semantics:

• Read the file's configVersion. Equal to the supported version →

nothing to migrate; report and stop.

• Lower than supported → run a migration: dry-run the field changes first,

same safety rules as bootstrap (enumerate, confirm, manifest, recoverable), then rewrite and re-validate. (No lower version exists yet; this path is reserved.)

• Higher than supported → HALT. The installed skills are older than the

config; tell the user to update the supermodo skills. An older config skill never rewrites a newer config.

Always dry-run and back up (manifest) before touching an existing config.

---

v1 config schema (standalone reference)

{
  "configVersion": 1,                       // required, literal 1
  "project": { "name": "string" },          // optional
  "docs": {                                 // required for librarian/work/flow/sync-gitlab
    "entry": "docs/README.md",              // default
    "conventions": "docs/CONVENTIONS.md"    // optional prose pointer
  },
  "commands": {                             // each optional; argv arrays only
    "test": ["deno","task","test"],
    "testUnit": ["..."], "testAll": ["..."],
    "lint": ["..."], "coverage": ["..."], "mutation": ["..."],
    "docsCheck": ["..."], "docsGenerate": ["..."]  // override bundled scripts
  },
  "coverage": { "target": 80 },             // integer 1-100
  "agents": { "dir": ".claude/agents" },    // absent → single-agent fallback
  "gitlab": {                               // only for sync-gitlab
    "url": "https://gitlab.example.com",    // must be https://
    "project": "group/name",
    "tokenEnv": "SUPERMODO_GITLAB_TOKEN",   // SUPERMODO_* env var NAME
    "cloudflareAccess": {                   // optional
      "clientIdEnv": "SUPERMODO_CF_CLIENT_ID",
      "clientSecretEnv": "SUPERMODO_CF_CLIENT_SECRET"
    }
  },
  "questions": {                            // optional
    "transport": "chat",                    // "chat" (default) | "tool"
    "perSkill": { "hunt": "tool" }          // per-skill override (uniform, grill included)
  },
  "output": { "verbosity": "concise" }      // "concise" (default) | "standard"
}

Rules that bite: unknown fields are errors; paths are root-relative POSIX with no ..; commands are argv arrays executed without a shell; *Env fields name SUPERMODO_* env vars, never secret values. Full spec in ../protocols/references/config.md.

Guardrails

• No git operations. The user runs git init/add/commit themselves; this

skill only edits .gitignore as a normal file.

• Never write outside the project except the docs scaffold, skills.config.json,

.gitignore, and .skills/supermodo/.

• Halt-and-report on any conflict the user hasn't approved a resolution for.

Report

State: config path + validation result, files created/moved/merged, the manifest path, and any conflicts left for the user. Concise per verbosity; safety and conflict details are never compressed.

Source & license

This open-source skill is cataloged on AgentStack and links to its original source — we do not rehost the code.

• Author: supermodo
• Source: supermodo/skills
• License: MIT

Install and usage instructions live in the source repository linked above.