@aragon-agent/cli 0.6.17 → 0.6.19

package/dist/team/types.d.ts

@@ -148,6 +148,57 @@ export interface SubagentRun {
         attempt: number;
         maxRetries: number;
     };
+    /**
+     * Supervisor inspections this child received (team-overseer). Optional so
+     * every existing fixture compiles; absent and `0` read the same.
+     */
+    interventions?: number;
+    /**
+     * Supervisor-driven rebuilds this child went through (team-overseer). The
+     * run object survives a rebuild with the same label, so this is where the
+     * report reads "this row is the Nth body of the same brief".
+     */
+    replacements?: number;
+}
+/** What the supervisor may do with one inspected child. */
+export type OverseerAction = 'wait' | 'nudge' | 'replace' | 'abandon';
+/**
+ * One supervisor decision, already normalized and clamped.
+ *
+ * Produced ONLY by `normalizeOverseerDecision` (repair, never reject): an
+ * unparseable or out-of-budget model answer becomes `wait` with the default
+ * interval, because supervision must not kill a healthy child.
+ */
+export interface OverseerDecision {
+    action: OverseerAction;
+    /** <= TEAM_LIMITS.overseerReasonChars. Why, for the report and the log. */
+    reason: string;
+    /** `nudge` only: <= TEAM_LIMITS.overseerGuidanceChars. Steered into the child. */
+    guidance?: string;
+    /** Model-chosen next check, clamped to the structural range. */
+    nextCheckMs?: number;
+}
+/** One supervisor intervention, as recorded on the outcome and rendered. */
+export interface OverseerIntervention {
+    label: string;
+    at: number;
+    action: OverseerAction;
+    reason: string;
+    /** What the trigger was: event stall, wall-clock check, or post-mortem. */
+    trigger: 'silence' | 'clock' | 'postmortem';
+}
+/**
+ * A terminal supervisor decision handed to the WORKER LOOP, which is the only
+ * place a child's `prompt()` is awaited and therefore the only place a
+ * lifecycle change can be applied without orphaning the replacement (I-OV1).
+ *
+ * Set by `TeamRuntime` on the handle, then `handle.abort()`; consumed and
+ * left in place (never cleared) by `runOne` after the await resolves.
+ */
+export interface OverseerVerdict {
+    action: 'replace' | 'abandon';
+    reason: string;
+    guidance?: string;
 }
 /** One message on the team bus. */
 export interface TeamMessage {
@@ -168,6 +219,12 @@ export interface DispatchOutcome {
     aborted: boolean;
     /** Messages addressed to `lead`; surfaced in their own report section. */
     leadMail: TeamMessage[];
+    /**
+     * Every supervisor decision that was applied (team-overseer), in order.
+     * Bounded by the per-child inspection budget; rendered as the report's
+     * Overseer section so the lead can see WHO was nudged or replaced and why.
+     */
+    interventions?: OverseerIntervention[];
     /**
      * Summed across all children. Real spend; it must reach the status bar
      * (§3.9). Every child runs the LEAD's model (main-agent parity), so one
@@ -212,6 +269,12 @@ export type TeamEvent = {
     type: 'message';
     dispatchId: string;
     message: TeamMessage;
+} | {
+    type: 'overseer';
+    dispatchId: string;
+    label: string;
+    decision: OverseerDecision;
+    trigger: OverseerIntervention['trigger'];
 } | {
     type: 'dispatch_end';
     dispatchId: string;

package/dist/ui/App.d.ts

@@ -11,7 +11,7 @@ import type { ConfirmRequest } from '../tools/index.js';
 import { type Overlay, type ToastLevel } from '../agent/reducer.js';
 import type { UpdateBridge } from '../update/types.js';
 import type { MouseSource } from '../input/stdin-filter.js';
-import type { PasteBridge } from '../input/limits.js';
+import { type PasteBridge } from '../input/limits.js';
 import type { SelectionBridge } from './selection/selection-controller.js';
 import type { HumanInputBridge } from '../tools/human-input.js';
 export interface ConfirmBridge {

package/dist/ui/App.js

@@ -48,6 +48,8 @@ import { useRenderGovernor } from './use-render-governor.js';
 import { readScrollbarPerf, setPerfResetHook, setPerfSnapshotProvider, } from '../commands/perf.js';
 import { buildFrameBudget } from './layout/budget.js';
 import { OVERLAY_PAGE, useWheelRouting } from './use-wheel-routing.js';
+import { INDEX_KEY_FRAME } from '../input/limits.js';
+import { INDEX_SKILL_NAME, buildIndexConfirmSummary, hasProjectIndex, indexBuildInvocationArgs, } from '../commands/index-build.js';
 import { installConsoleBridge } from './console-bridge.js';
 import { publishExitSnapshot } from './exit-snapshot.js';
 import { OverlayFrame } from './layout/OverlayFrame.js';
@@ -648,6 +650,15 @@ export function App({ controller, version, initialOverlay, initialPrompt, confir
                         dispatch({ type: 'teamUpdate', snapshot });
                     break;
                 }
+                case 'overseer': {
+                    // A supervisor decision was applied (team-overseer). The roster
+                    // already refreshed through the agent_update the runtime publishes
+                    // with it; re-read the snapshot so the panel cannot miss the row.
+                    const snap = controller.getTeamSnapshot();
+                    if (snap)
+                        dispatch({ type: 'teamUpdate', snapshot: snap });
+                    break;
+                }
                 case 'usage': {
                     // Child spend is REAL SPEND and must reach the status bar, or the
                     // session cost readout under-reports by however much the team consumed
@@ -1553,6 +1564,46 @@ export function App({ controller, version, initialOverlay, initialPrompt, confir
         setConfirmState(null);
         dispatch({ type: 'setOverlay', overlay: null });
     };
+    // --- Ctrl+I: run the bundled project-indexer skill. -------------------
+    //
+    // SAME PATH AS A TYPED COMMAND, ON PURPOSE. After the Yes/No gate (the
+    // second confirmation the user asked for) this dispatches
+    // `/skill:project-indexer <args>` through `executeSlashInput`, so the
+    // load/activate/queue-frame/submit lifecycle and the streaming tool cards
+    // in the transcript are the ones every skill command already has. The
+    // busy guard refuses rather than queueing: a queued skill body would
+    // arrive as steering mid-run, which is not what "build the index" means.
+    const requestIndexBuild = () => {
+        if (controller.isRunning() || interactionPhase.current !== 'idle') {
+            // A notice entry, not a toast: the running status row's feedback slot is
+            // owned by the activity phrase, and a busy warning nobody can read is
+            // the same as no warning.
+            notify('warn', 'The agent is busy. Let it finish before building the index (Ctrl+I).');
+            return;
+        }
+        if (cfg.skills.enabled) {
+            const record = controller.getSkillService().get(INDEX_SKILL_NAME);
+            if (!record || record.disabled || record.invalid) {
+                notify('warn', `Skill "${INDEX_SKILL_NAME}" is not available. Check /skills list.`);
+                return;
+            }
+        }
+        else {
+            notify('warn', 'Skills are disabled; the project index needs the bundled skill.');
+            return;
+        }
+        const cwd = controller.getCwd();
+        const existing = hasProjectIndex(cwd);
+        void (async () => {
+            const approved = await new Promise((resolve) => {
+                setConfirmState({ summary: buildIndexConfirmSummary({ cwd, hasExistingIndex: existing }), resolve });
+                dispatch({ type: 'setOverlay', overlay: 'confirm' });
+            });
+            if (approved) {
+                await executeSlashInput(`/skill:${INDEX_SKILL_NAME} ${indexBuildInvocationArgs(existing)}`);
+            }
+        })();
+    };
     /** Answer every outstanding request with the same response and close up. */
     const resolveHuman = (response) => {
         for (const entry of [...pendingHuman.current])
@@ -1714,6 +1765,16 @@ export function App({ controller, version, initialOverlay, initialPrompt, confir
             setStatusExpanded(value => !value);
             return;
         }
+        // Ctrl+I arrives as INDEX_KEY_FRAME, never as key.ctrl + 'i': legacy
+        // terminals encode it as the Tab byte and the stdin filter's translators
+        // are the only layer that can tell them apart (see input/limits.ts).
+        // Guarded exactly like Ctrl+G above it.
+        if (input.includes(INDEX_KEY_FRAME)) {
+            if (tooSmall || stateRef.current.overlay)
+                return;
+            requestIndexBuild();
+            return;
+        }
         if (tooSmall)
             return;
         // R-P1-7: the overlay branch MUST come before the transcript scroll branch

package/dist/ui/Header.js

@@ -5,7 +5,18 @@ import { Logo } from './Logo.js';
 export function Header({ cwd, provider, model, hasKey, variant, theme, caps, columns = 80, statusExpanded = false, scrolledLines = 0, overlayOpen = false }) {
     const scroll = Number.isFinite(scrolledLines) && scrolledLines > 0
         ? (scrolledLines > 9999 ? '^9999+' : '^' + Math.floor(scrolledLines)) + (overlayOpen ? ' ' : '  ') : '';
+    // The Ctrl+I project-index affordance sits LEFT of the ^G detail toggle:
+    // collapsed it names the key and the noun ('^I Index'); expanded - the
+    // same Ctrl+G state that adds the status detail row - it spells the action
+    // ('^I build index'). Hidden while an overlay owns the header and below the
+    // 72-column cutoff the composer hints also use: on a narrow terminal the
+    // scroll chip and the ^G toggle are the two affordances that must survive.
+    const indexHint = overlayOpen || columns < 72
+        ? ''
+        : (statusExpanded ? '^I build index  ' : '^I Index  ');
     const detail = overlayOpen ? (statusExpanded ? 'Details on' : 'Details off')
-        : '^G ' + (statusExpanded ? 'less' : 'more');
-    return _jsxs(Box, { flexDirection: "row", height: 1, width: columns, flexShrink: 0, overflow: "hidden", children: [_jsx(Box, { width: Math.max(0, columns - 18), flexShrink: 0, overflow: "hidden", children: _jsxs(Text, { wrap: "truncate", children: [_jsx(Logo, { variant: variant === 'mini' ? 'mini' : 'bar', theme: theme, caps: caps }), variant !== 'mini' && _jsxs(_Fragment, { children: [_jsxs(Text, { color: theme.accent, children: ['  ', provider, ":", model] }), _jsxs(Text, { color: theme.muted, children: ['  ', basename(cwd) || cwd] }), _jsxs(Text, { color: hasKey ? theme.toolDone : theme.toolRunning, children: ['  ', hasKey ? theme.symbols.keyOn : theme.symbols.keyOff] })] })] }) }), _jsx(Box, { width: 18, flexShrink: 0, justifyContent: "flex-end", children: _jsx(Text, { color: theme.muted, wrap: "truncate", children: scroll + detail }) })] });
+        : indexHint + '^G ' + (statusExpanded ? 'less' : 'more');
+    // Widest content: '^9999+  ' (8) + '^I build index  ^G less' (23) = 31.
+    const detailCells = indexHint ? 32 : 18;
+    return _jsxs(Box, { flexDirection: "row", height: 1, width: columns, flexShrink: 0, overflow: "hidden", children: [_jsx(Box, { width: Math.max(0, columns - detailCells), flexShrink: 0, overflow: "hidden", children: _jsxs(Text, { wrap: "truncate", children: [_jsx(Logo, { variant: variant === 'mini' ? 'mini' : 'bar', theme: theme, caps: caps }), variant !== 'mini' && _jsxs(_Fragment, { children: [_jsxs(Text, { color: theme.accent, children: ['  ', provider, ":", model] }), _jsxs(Text, { color: theme.muted, children: ['  ', basename(cwd) || cwd] }), _jsxs(Text, { color: hasKey ? theme.toolDone : theme.toolRunning, children: ['  ', hasKey ? theme.symbols.keyOn : theme.symbols.keyOff] })] })] }) }), _jsx(Box, { width: detailCells, flexShrink: 0, justifyContent: "flex-end", children: _jsx(Text, { color: theme.muted, wrap: "truncate", children: scroll + detail }) })] });
 }

package/dist/ui/PromptInput.js

@@ -37,7 +37,7 @@ import { draftMaxRows } from './composer-limits.js';
 import { layoutComposer, splitRowAtColumn } from './composer-rows.js';
 import { moveVisualCursor, snapGrapheme, stepGrapheme } from './editor-navigation.js';
 import { interactionCopy } from './interaction-copy.js';
-import { PASTE_DRAFT_MAX_BYTES, PASTE_MAX_BLOCKS, formatPasteSize, } from '../input/limits.js';
+import { INDEX_KEY_FRAME, PASTE_DRAFT_MAX_BYTES, PASTE_MAX_BLOCKS, formatPasteSize, } from '../input/limits.js';
 // ---------------------------------------------------------------------------
 // The scroll chip (§4.2)
 // ---------------------------------------------------------------------------
@@ -488,6 +488,16 @@ export function PromptInput({ cols: colsProp, terminalRows: terminalRowsProp, st
             insert('\n');
             return;
         }
+        // App owns the Ctrl+I index frame (see input/limits.ts). Standalone it
+        // never reaches here - isControlSeq drops it at the printable-insert
+        // branch below - but a frame glued to typed text in one chunk must
+        // insert ONLY the text, so strip it before any other interpretation.
+        if (input.includes(INDEX_KEY_FRAME)) {
+            const rest = input.split(INDEX_KEY_FRAME).join('');
+            if (rest.length > 0)
+                insert(rest);
+            return;
+        }
         if (hasPasteFrame(input) || hasEnterFrame(input) || /[\r\n]/.test(input)) {
             const intents = splitEnterFrames(input).map((frame) => frame.kind === 'paste' ? { ...frame, id: allocatePasteId() } : frame);
             if (intents.length > 0)

package/dist/ui/overlays/HelpOverlay.js

@@ -20,6 +20,7 @@ function keyRows(times) {
         [`Ctrl+C ${times}2`, 'Exit'],
         ['Ctrl+L', 'Redraw the frame'],
         ['Ctrl+T', 'Show/hide thinking (off by default)'],
+        ['Ctrl+I', 'Build the project index (bundled skill; asks first; needs keyboard enhancement)'],
         ['Ctrl+G', 'Expand/collapse status details; disabled while an overlay is open'],
         ['PgUp / PgDn', 'Scroll a page (transcript, or this overlay)'],
         ['Shift+Up / Shift+Down', 'Scroll the transcript a line (full-screen mode)'],

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@aragon-agent/cli",
-  "version": "0.6.17",
+  "version": "0.6.19",
   "description": "AragonAgent CLI — a Claude-Code / Codex-style interactive terminal UI (TUI) on top of the @aragon-agent/core engine. Installable and runnable via npm / npx.",
   "license": "MIT",
   "author": "AragonAgent contributors",
@@ -56,7 +56,7 @@
     "prepublishOnly": "npm run build"
   },
   "dependencies": {
-    "@aragon-agent/core": "^0.2.29",
+    "@aragon-agent/core": "^0.2.31",
     "chalk": "^5.6.2",
     "cli-highlight": "^2.0.0",
     "commander": "^12.1.0",

package/skills/project-indexer/SKILL.md

@@ -0,0 +1,163 @@
+---
+name: project-indexer
+description: Generate and use a project index for quick codebase understanding in new sessions. Scans the workspace, extracts exported symbols, writes .claude-index/index.md plus config, and injects a Google-style Clean Code Guidelines section into CLAUDE.md. Use when the user says "explore the project", "generate index", "regenerate index", "更新索引", "生成索引", or presses Ctrl+I.
+version: 1.1.0
+license: MIT
+keywords: [productivity, codebase, indexing, navigation, cleancode]
+# The read-only tools (read_file, list_dir, glob, grep, ask_user, todo_write)
+# are always available inside a skill frame via the tool floor; this ceiling
+# adds exactly the two writers the generated files need.
+allowed-tools:
+  - write_file
+  - edit_file
+---
+
+# Project Indexer
+
+Generate a structured index of any codebase so a new session understands the
+project with minimal context usage. The index is a **navigation map**, not a
+code copy: enough to see the project globally (type, stack, architecture),
+navigate on demand (feature map, file index), and know which symbols exist
+without reading every file.
+
+## Current request
+
+$ARGUMENTS
+
+## Step 1: Check for an existing index
+
+- If `.claude-index/index.md` exists and has the key sections (Project
+  Overview, Feature Map, File Index), go to "Using an existing index".
+- If it exists but is empty or malformed, tell the user and regenerate
+  (first-time flow), preserving `config.md` if intact.
+- Otherwise run the first-time flow.
+
+## Using an existing index
+
+1. Read `.claude-index/index.md` and `CLAUDE.md` (if present).
+2. Summarize in 3-5 bullets: structure, stack, feature areas, key entry
+   points. Offer to help.
+3. For later questions, navigate via the Feature Map / File Index and read
+   real source only when detail is needed.
+
+## First-time flow
+
+### Step 2: Gather configuration (ask_user)
+
+Ask with `ask_user`, defaults offered in every question:
+
+1. **Exclusions** - A) defaults (node_modules, .git, dist, build,
+   __pycache__, .venv, vendor, coverage, .next, .nuxt, .cache, target, bin,
+   obj, .idea, .vscode) B) add more C) custom list.
+2. **Priority directories** - A) auto-detect (recommended) B) specify C) all
+   equally.
+3. **Tech stack** - auto-detect unless the user names one.
+4. **Clean Code Guidelines** (injected into CLAUDE.md) - A) Google strict
+   (method 60, file 1000 - recommended) B) Google relaxed (method 600)
+   C) custom D) skip.
+
+If C: ask **one `ask_user` call per limit** showing default and range -
+MAX_FILE_LINES 1000 (200-5000), MAX_METHOD_LINES 60 (20-600),
+MAX_FUNCTION_PARAMS 5 (2-10), MAX_CYCLOMATIC 10 (5-25); fall back to the
+default on an out-of-range answer and say so in the summary.
+MAX_LINE_LENGTH (default 100, Python 80) and MAX_NESTING_DEPTH (4) are never
+asked. If the user skips every question, use all defaults.
+
+Treat the answer as `CleanCodeConfig.preset`: strict | relaxed | custom |
+disabled. D (`disabled`) skips the Clean Code composition below, never adds
+markers, and persists `Enabled: No`.
+
+### Step 3: Scan and analyze
+
+1. Traverse the tree with the exclusion rules (`glob`, never one giant read).
+2. Detect project type (frontend/backend/fullstack/library/CLI/monorepo),
+   languages with percentages, frameworks, entry points.
+3. Group files by feature/domain and extract exported symbols - full support
+   for JS/TS (.js/.jsx/.ts/.tsx/.mjs) and Python; best-effort for Java,
+   Kotlin, Go, Rust, C/C++, C#, Ruby, PHP; unknown types are listed without
+   symbols.
+4. Analyze module-level dependencies (import graph).
+
+Adaptive sizing: <50 files -> full detail; 50-200 -> full coverage with
+concise descriptions; 200+ -> detail the priority directories, summarize the
+rest, group similar utilities. Over 1000 files after exclusions: warn and
+suggest more exclusions before continuing; sample representative files with
+glob/grep rather than reading everything. Keep language/framework findings in
+working memory - do NOT write an intermediate JSON file.
+
+### Step 4: Write `.claude-index/`
+
+1. `config.md` - exclusions, priorities, tech stack, plus an Index Settings
+   block (Generated date, Project Root, Index Version) and a Clean Code
+   Settings block (Enabled / Preset / the six limits; when the user picked
+   skip, write `Enabled: No`, `Preset: disabled` and the strict numbers so a
+   later "enable cleancode" can flip it back).
+2. `index.md` - follow `templates/index-template.md` in this skill's
+   directory: Project Overview, Feature Map (per area: entry file, one-line
+   description, key exports with signatures), Module Dependencies, File Index
+   (per-directory tables, one line per file).
+
+### Step 5: Compose the Clean Code Guidelines (skip when disabled)
+
+Read `templates/cleancode-template.md` and `templates/cleancode-overrides.md`
+from this skill's directory, then:
+
+1. Primary languages = every language with >= 10% of post-exclusion source
+   files; if none clears 10%, use the `Other` row.
+2. Take the **minimum** across all matching rows for each numeric column.
+3. Apply the user preset: strict/relaxed values intersect with the language
+   minimum (never looser than the baseline); custom numbers are honoured
+   verbatim with divergence noted.
+4. Substitute every placeholder: `{{MAX_FILE_LINES}}`, `{{MAX_METHOD_LINES}}`,
+   `{{MAX_FUNCTION_PARAMS}}`, `{{MAX_CYCLOMATIC}}`, `{{MAX_LINE_LENGTH}}`,
+   `{{MAX_NESTING_DEPTH}}`, `{{PRIMARY_LANGUAGES}}` (comma-joined languages)
+   and `{{LANGUAGE_HINTS}}` (one `- Language: note` bullet per matching row,
+   deduped by exact string).
+5. Verify no `{{...}}` placeholder remains. Do not count characters at
+   runtime.
+
+### Step 6: Update CLAUDE.md
+
+- `## Project Index` section: upsert (replace when present, else append at
+  end; create the file when missing). Contents: Location
+  `.claude-index/index.md`, Last Updated (YYYY-MM-DD), Contents line, a
+  Usage line, and "Regenerate: say 'regenerate index' / '更新索引'".
+- `## Clean Code Guidelines` section (unless disabled): wrap the rendered
+  body in `<!-- project-indexer:cleancode:begin v1.1.0 -->` and
+  `<!-- project-indexer:cleancode:end -->`. Locate an existing block with
+  the version-agnostic regex `<!-- project-indexer:cleancode:begin
+  v\d+\.\d+\.\d+ -->` (NEVER a literal-version match) plus the literal end
+  marker; fallback: the region from a `## Clean Code Guidelines` heading to
+  the next `## ` heading or EOF. Replace the found block; if none, insert
+  after the Project Index section (first-insert only; when both sections
+  already exist preserve the user's ordering and everything between them).
+  Write UTF-8; add a trailing newline when missing.
+
+### Step 7: Report
+
+List what was created/updated, the feature-area count, files indexed and
+symbols extracted. Offer to start work.
+
+## Regeneration ("regenerate index" / "更新索引")
+
+1. Read `config.md` and preserve exclusions, priorities, stack.
+2. Clean Code handling: if CLAUDE.md has markers or the heading, ask
+   A) refresh B) keep C) remove; honour `Enabled: No` from config.md by
+   skipping silently with one reminder line. When no block exists and
+   Enabled is Yes/absent, compose and inject (announce before writing).
+3. Confirm the plan (exclusions, priorities, cleancode decision) with the
+   user, then re-run Steps 3-7.
+
+Special triggers: "disable cleancode" removes the block and sets
+`Enabled: No`; "enable cleancode" re-composes it and sets `Enabled: Yes` -
+both without a full rescan.
+
+## Edge cases
+
+- Inaccessible directories: list them under a "Skipped Directories" note and
+  continue; never fail the whole run for one unreadable path.
+- No recognizable source files: generate a minimal index (overview + file
+  listing) and say so.
+- The user pressed Ctrl+I: they already confirmed once - do not re-ask the
+  global "proceed?" question, but still ask the configuration questions
+  above (or reuse `.claude-index/config.md` when it exists).

package/skills/project-indexer/templates/cleancode-overrides.md

@@ -0,0 +1,46 @@
+# Clean Code — Language Override Table
+
+> Read by `project-indexer` at Step 5. The skill intersects the rows below
+> with the **primary languages** detected during the scan (any language whose
+> source files account for >= 10% of the post-exclusion total).
+>
+> When two or more rows apply, the skill **takes the minimum** for every
+> numeric column. Notes from each matching row are concatenated and rendered
+> as bullets in the `{{LANGUAGE_HINTS}}` placeholder of
+> `cleancode-template.md`.
+>
+> Defaults (used when no row matches, i.e. the `Other` row) live in the last
+> row. Numeric units: `MAX_FILE_LINES` and `MAX_METHOD_LINES` are physical
+> lines of source. `MAX_LINE_LENGTH` is columns. `MAX_FUNCTION_PARAMS` is the
+> count of positional + keyword parameters in a single signature.
+
+| Language    | MAX_FILE_LINES | MAX_METHOD_LINES | MAX_LINE_LENGTH | MAX_FUNCTION_PARAMS | Notes |
+|-------------|----------------|------------------|-----------------|---------------------|-------|
+| TypeScript  | 1000           | 60               | 100             | 5                   | Prefer `interface` over `type` for public APIs. |
+| JavaScript  | 1000           | 60               | 100             | 5                   | Avoid `any`; use JSDoc when no TS. |
+| Python      | 800            | 50               | 80              | 5                   | PEP 8 + Google docstrings. |
+| Go          | 800            | 60               | 120             | 4                   | Errors as values; no panic in library code. |
+| Java        | 1500           | 40               | 100             | 5                   | Google Java Style. |
+| Kotlin      | 1500           | 40               | 100             | 5                   | KtLint defaults. |
+| Rust        | 1000           | 60               | 100             | 5                   | `clippy::pedantic` recommended. |
+| C / C++     | 1000           | 50               | 100             | 5                   | Google C++ Style. |
+| Other       | 1000           | 60               | 100             | 5                   | Generic fallback. |
+
+## Merge Rules
+
+1. **Detection threshold** — only languages with >= 10% of source files (after
+   exclusions) contribute. If no language clears 10%, use the `Other` row.
+2. **Numeric merge** — `min()` across every matching row, per column.
+3. **Note merge** — collect each matching row's `Notes` cell, dedupe by exact
+   string match, render as a bullet list. Example for TypeScript + Python:
+   - `- TypeScript: Prefer interface over type for public APIs.`
+   - `- Python: PEP 8 + Google docstrings.`
+4. **Fixed defaults (not in the table, applied unconditionally)** —
+   `MAX_CYCLOMATIC = 10`, `MAX_NESTING_DEPTH = 4`. These can still be
+   overridden by the user via the Custom preset.
+
+## Adding a Language
+
+When extending this table, keep the column order identical and use the
+strictest reasonable value for each cell so the `min()` merge stays
+meaningful for polyglot repos.

package/skills/project-indexer/templates/cleancode-template.md

@@ -0,0 +1,94 @@
+<!--
+  cleancode-template.md — rendered into CLAUDE.md by project-indexer (Step 5).
+  Authoring rules:
+    - Chinese character body must measure 1,400–1,700 characters
+      (matched by regex `[一-鿿]`).
+    - Verify after editing by counting matches of `[一-鿿]` in this file.
+    - Placeholders: {{MAX_FILE_LINES}} {{MAX_METHOD_LINES}}
+      {{MAX_FUNCTION_PARAMS}} {{MAX_CYCLOMATIC}} {{MAX_LINE_LENGTH}}
+      {{MAX_NESTING_DEPTH}} {{PRIMARY_LANGUAGES}} {{LANGUAGE_HINTS}}
+    - At runtime the skill must ensure no `{{...}}` placeholder leaks into
+      the rendered output. Numeric character counting at runtime is NOT
+      required.
+-->
+
+> 本节由 `project-indexer` 自动维护，灵感取自谷歌风格，并按本项目主要语言收敛阈值。请勿手工编辑 markers 之间的内容，需要刷新时请运行「regenerate index」。
+
+### 一、概述
+
+本节是本项目在使用 AI 辅助开发时必须遵守的代码规范。在写或改动任何代码之前，先把下列条目读完一遍，再动键盘。规则的目的不是束缚发挥，而是让人类与 agent 写出的代码在阈值上保持可比的下限，避免出现千行文件与几百行方法，避免命名混乱、错误吞咽、测试缺失这些会在后续维护中迅速发酵的问题。所有阈值都允许根据项目实际情况调整，但调整必须在 `.claude-index/config.md` 中显式记录，并在评审中说明理由，不要靠默认值偷偷放宽。
+
+### 二、文件与函数尺寸
+
+- 单文件不超过 **{{MAX_FILE_LINES}}** 行，超过即按职责拆分到新模块。
+- 单方法不超过 **{{MAX_METHOD_LINES}}** 行，写到一半感觉膨胀就先抽函数。
+- 函数形参不超过 **{{MAX_FUNCTION_PARAMS}}** 个，多了请改用配置对象、命名参数或聚合结构体，禁止靠位置堆参数。
+- 圈复杂度不超过 **{{MAX_CYCLOMATIC}}**，分支累积过多必须拆函数或引入查找表。
+- 单行长度不超过 **{{MAX_LINE_LENGTH}}** 列，超长就换行或抽变量名。判定标准很简单：阈值超了就是技术债，提交前自查并修正。
+
+### 三、命名
+
+- 函数以动词开头表达动作，例如 `loadConfig`、`parseToken`；查询类用名词或 `get` / `find`。
+- 返回布尔值的函数与变量以 `is`、`has`、`should`、`can` 起头，便于阅读条件表达式。
+- 常量使用大写蛇形，模块名短小且语义化，避免堆叠首字母缩写。
+- 不缩写领域词，宁可名字长五个字母也要让读者一眼看懂含义。
+- 类与接口使用大驼峰命名，方法与变量使用小驼峰或语言推荐的蛇形写法，保持整个仓库风格一致。
+- 避免使用 `data`、`info`、`temp`、`obj` 这类无信息量的名字；给出具体的领域名词。
+
+### 四、注释与文档
+
+- 注释只解释「为什么」，不复述「做什么」，代码本身就是「做什么」的真相。
+- 所有公开 API 必须写 docstring，标注参数、返回值与可能抛出的异常。
+- 删除一切僵尸注释与被注释掉的旧代码；保留 `TODO` 必须带责任人与日期。
+- 行级注释稀缺即珍贵，不要在每行上方堆一句无信息量的话。
+- 复杂业务规则、踩坑记录、临时性 workaround 必须在注释中写清楚原因与可回退条件。
+
+### 五、错误处理
+
+- 错误显式传播，不要默默吞异常或返回 `null` 假装一切正常。
+- 外部输入在边界处一次性校验，进入内部后信任内部数据，禁止层层重复校验。
+- 不要为「理论上不会发生」的分支写防御性 `try/except`，那只是噪音。
+- 错误信息必须包含定位线索：发生在哪、关键参数是什么、下游应如何处理。
+- 在 IO、网络、子进程等不可控边界，使用带超时与重试的结构化封装，而非裸调用。
+- 捕获异常时尽量缩小作用域，只处理你确实有办法应对的错误类型，其他原样向上抛出。
+- 对外暴露的错误码或异常类必须稳定，更名等同于破坏性变更，需要在变更日志中显式标注。
+
+### 六、复杂度与嵌套
+
+- 嵌套深度不超过 **{{MAX_NESTING_DEPTH}}** 层，深嵌套是函数过长的前兆。
+- 优先使用早返回（guard clause）取代 `else` 阶梯。
+- 单个表达式里出现超过三个布尔条件，立刻抽成命名清晰的辅助函数。
+- 循环里若出现复杂条件分支，改写为查找表或策略对象往往更易读。
+- 一个函数只做一件事；当解释函数职责时需要用「并」「同时」「再」这类连词，就是应该拆分的信号。
+
+### 七、测试
+
+- 修 bug 必须先写一个能稳定复现该 bug 的测试用例，再动业务代码。
+- 公开行为都要有单元测试覆盖正常路径与至少一条异常路径。
+- 测试名描述被验证的行为而非实现细节，例如 `rejects_expired_token`。
+- 不允许 mock 数据库迁移、鉴权签名等高风险路径，必须使用真实集成测试。
+- 单测应快速且可重复运行；外部依赖通过桩或本地容器隔离，禁止依赖共享环境状态。
+- 任何被发现的回归 bug 都要补上对应的测试，把过去的坑变成未来的护栏。
+
+### 八、代码评审清单
+
+提交前对照以下 8 条自查，任何一条不满足即视为未完成：
+
+1. 命名是否自解释，是否避免无意义缩写。
+2. 文件、方法、参数、嵌套、圈复杂度是否都在阈值内。
+3. 错误是否显式传播，边界校验是否到位。
+4. 注释是否只解释「为什么」，是否还有僵尸代码或孤儿 TODO。
+5. 测试是否覆盖正常路径与异常路径，是否能稳定复现已修复的 bug。
+6. 是否引入新依赖，依赖是否必要、是否有安全或许可证风险。
+7. 是否泄露密钥、个人数据、内部链接等敏感信息。
+8. 是否与现有架构与命名风格一致，是否制造新的孤岛。
+
+### 九、语言特有提示
+
+当前项目主要语言：**{{PRIMARY_LANGUAGES}}**。
+
+{{LANGUAGE_HINTS}}
+
+### 十、元信息
+
+模板版本与上方 markers 中的版本一致。说「regenerate index」或「更新索引」可重新生成本节内容；说「disable cleancode」可移除本节。

package/skills/project-indexer/templates/config-template.md

@@ -0,0 +1,69 @@
+# Index Configuration
+
+> Configuration for project-indexer. Edit this file to customize index generation.
+
+## Excluded Directories
+
+Directories to skip during indexing:
+
+- node_modules
+- .git
+- dist
+- build
+- __pycache__
+- .venv
+- venv
+- vendor
+- coverage
+- .next
+- .nuxt
+- .cache
+- target
+- bin
+- obj
+- .idea
+- .vscode
+
+## Priority Directories
+
+Directories to index in detail (leave empty for auto-detection):
+
+- src/
+- lib/
+- app/
+- core/
+
+## Tech Stack
+
+Detected or specified technology stack:
+
+- **Frontend:** {React | Vue | Angular | Svelte | Next.js | Nuxt | etc.}
+- **Backend:** {Express | FastAPI | Django | Rails | Spring | etc.}
+- **Language:** {TypeScript | JavaScript | Python | Go | etc.}
+
+## Index Settings
+
+- **Generated:** {YYYY-MM-DD HH:MM:SS}
+- **Project Root:** {/path/to/project}
+- **Index Version:** 1.0
+- **Total Files Indexed:** {N}
+- **Total Symbols Extracted:** {N}
+
+## Clean Code Settings
+
+- Enabled: {Yes | No}
+- Preset: {strict | relaxed | custom | disabled}
+- MAX_FILE_LINES: 1000
+- MAX_METHOD_LINES: 60
+- MAX_FUNCTION_PARAMS: 5
+- MAX_CYCLOMATIC: 10
+- MAX_LINE_LENGTH: 100
+- MAX_NESTING_DEPTH: 4
+
+## Regeneration Notes
+
+Notes for future regeneration:
+
+- {Any special considerations}
+- {Files that need manual review}
+- {Known limitations}