configure-docs-index

name	configure-docs-index
description	Analyzes the codebase, creates project documentation, generates a rebuildable codebase index, and updates AGENTS.md. Used during /5:implement CONFIGURE.
allowed-tools	Read, Write, Bash, Glob, Grep
model	sonnet
user-invocable	false

Configure Docs And Index Skill

Overview

This skill handles the documentation and indexing work during implementation for the CONFIGURE feature. It is called by step-executor to create the project docs, codebase index, and AGENTS.md.

It handles one task:

• Analyze Codebase and Create/Update Documentation + Index - Maps codebase, writes .5/*.md, generates .5/index/*, and updates AGENTS.md

Note: config.json is written directly by /5:configure during the Q&A phase.

---

Modes

This skill supports two modes. The analysis (A1), template filling (A2-A3), index generation (A3.5), and AGENTS.md update (A4-A5) logic is the same in both modes — only the input source changes.

Full Mode (default)

Used by /5:configure → /5:implement CONFIGURE flow.

• Input: Pattern/command selections from unified plan (.5/features/CONFIGURE/plan.md)
• Behavior: Creates documentation, index files, and AGENTS.md from scratch based on unified plan requirements

Refresh Mode

Used by /5:reconfigure for lightweight refresh.

• Input: The Task prompt tells it to refresh documentation and the codebase index
• Behavior: Re-analyzes codebase and overwrites docs, index files, and AGENTS.md
• Trigger: Task prompt includes "REFRESH MODE"

In both modes, the analysis and generation logic is identical.

---

A. Analyze Codebase and Create/Update AGENTS.md

Process:

A1. Codebase Analysis

Perform focused analysis to gather data for documentation templates. Only capture information that cannot be derived by reading project files directly — skip version numbers, dependency lists, directory layouts, linter configs, and other facts that Claude Code can look up on demand.

Architecture Analysis (for ARCHITECTURE.md):

• Identify architectural pattern (MVC, layered, modular, microservices) from directory structure
• Map layers by directory structure (controllers/, services/, models/, routes/, etc.)
• Trace data flow patterns (read 2-3 example files from different layers)
• Identify key abstractions (interfaces, base classes, common patterns)
• Identify non-obvious conventions: implicit rules not enforced by tooling (e.g., "all services extend BaseService", "barrel exports required per module"). Skip anything in .eslintrc, .prettierrc, tsconfig, etc.
• Determine where new code should go (new features, tests, utilities)

Testing Analysis (for TESTING.md):

• Determine test organization (co-located vs separate test/ or spec/)
• Identify mocking framework and project-specific mocking conventions
• Find fixture/factory patterns
• Note gotchas: setup/teardown quirks, env requirements, flaky areas

Concerns Analysis (for CONCERNS.md — conditional):

• Grep for TODO/FIXME/HACK/XXX/DEPRECATED comments across all code
• Check for common security issues (SQL injection patterns, XSS vulnerabilities)
• Identify non-obvious integration details: auth flows, required env vars not documented elsewhere, webhook contracts, gotchas with external services
• Look for performance bottlenecks or scaling limits mentioned in comments/docs

Conventions Analysis (for CONVENTIONS.md — when conventions.generate is true in config.json):

• Identify the primary language(s) and runtime (TypeScript, Java, Python, Go, etc.) for the summary line
• Typing patterns: Check tsconfig.json for strict mode (TypeScript); check mypy.ini or pyproject.toml [tool.mypy] for strict settings (Python); scan source files for any type usage count, non-null assertion (!) patterns, and missing return types
• Error handling patterns: Scan for try/catch structures, custom error classes/types, and patterns of silent catches (empty catch blocks)
• Test assertion patterns: Read 3-5 test files to identify assertion library (Jest expect, Chai, JUnit assertEquals, etc.), mocking approach, and whether factories/builders exist
• Naming patterns: Observe the dominant casing and naming conventions already established in the codebase
• Code structure patterns: Note average file lengths and any consistent structural patterns across modules

A2. Fill Templates

For each template in .claude/templates/:

1. Read template content with Read tool
2. Replace placeholders with analyzed data from A1
3. Omit sections entirely if no data was found — do not write "Not detected" or "None found"
4. For CONCERNS.md: if ALL sections would be empty, do not create the file at all

Placeholder mapping examples:

ARCHITECTURE.md:

• {Pattern name} → "Layered Architecture" or "MVC" or "Modular Monolith"
• {Layer} → "Controllers", "Services", "Repositories"
• {path} → "src/controllers/", "src/services/"
• {skill links} → slash-command links to project-specific skills installed in .claude/skills/ that correspond to this layer (e.g., /controller, /service). Check which create-* skills exist for this layer's pattern. If none exist, use "—".

TESTING.md:

• Describe actual patterns observed, not framework names/versions (those are in config files)

CONCERNS.md:

• {file paths} → Actual file paths from grep results

A3. Write Documentation Files

Write filled templates to .5/ folder:

1. Ensure .5/ directory exists: mkdir -p .5
2. Write filled templates:
   • .5/ARCHITECTURE.md — always created
   • .5/TESTING.md — always created
   • .5/CONCERNS.md — only if concerns were found (skip if all sections empty)
   • .5/CONVENTIONS.md — only when conventions.generate is true in config.json (see A3.1)

A3.1. Generate CONVENTIONS.md

Skip this section entirely if conventions.generate is false in .5/config.json.

Read .claude/templates/CONVENTIONS.md as the source template.

Placeholder mapping:

• {PROJECT_CONVENTIONS_SUMMARY} → 1 sentence naming the primary language/runtime and any detected strict-mode tooling (e.g., "TypeScript project with strict: true in tsconfig." or "Python 3.11 service with mypy strict mode enabled."). Remove the placeholder if nothing useful can be stated.
• {PROJECT_TYPING} → Project-specific findings from Conventions Analysis: detected tsconfig settings, any any usage count, non-null assertion patterns, absence of return types. Frame as imperative directives ("Enable strict: true in tsconfig — currently disabled." or "49 usages of any detected; prioritize removal in new code."). Remove placeholder if nothing project-specific to add.
• {PROJECT_STRUCTURE} → Observed structural patterns or deviations from defaults (e.g., "Files in src/controllers/ average 380 lines — respect the 300-line default; split controllers that exceed it."). Remove placeholder if no notable findings.
• {PROJECT_NAMING} → Casing or naming patterns specific to this codebase beyond the defaults (e.g., "This project uses kebab-case for file names and PascalCase for classes — match existing files."). Remove placeholder if defaults already cover it.
• {PROJECT_ERROR_HANDLING} → Detected error-handling patterns or gaps (e.g., "Custom AppError class in src/errors/ — use it for all domain errors." or "3 empty catch blocks found in src/services/ — always log or rethrow."). Remove placeholder if no notable findings.
• {PROJECT_TESTING} → Project-specific testing directives beyond the defaults: assertion library in use, factory/builder location, any detected weak assertions or disabled tests (e.g., "Use src/test/factories/ helpers for test data — do not inline objects." or "12 uses of toBeDefined() as sole assertion detected — always assert the actual value."). Remove placeholder if defaults already cover it.
• {PROJECT_COMMENTS} → Any documentation patterns or gaps observed (e.g., "Public controllers lack JSDoc — add docblocks to all new public methods."). Remove placeholder if defaults already cover it.

Rules for filling placeholders:

• Write project-specific sections as imperative directives, not observations.
• Remove (do not leave) any placeholder whose section has nothing project-specific to add.
• Do not duplicate the default convention text — project sections supplement, not restate, the defaults.
• Keep each project-specific addition under 5 bullet points.

A3.5. Generate Codebase Index Script and Index Files

Generate a repository-local codebase index that stays generic and works for any language or framework detected in the project.

Requirements:

• Create .5/index/ if it does not exist
• Generate a script that rebuilds the index at .5/index/rebuild-index.sh
• Make the script self-contained and dependency-light:
  • Prefer portable shell plus standard tools already expected in a dev environment
  • If the project clearly has a better built-in runtime already available (for example Node.js or Python), it is acceptable to generate a small script in that runtime instead, but keep it local to the repo and avoid adding new dependencies
• The script must inspect the current codebase and write multiple focused Markdown index files into .5/index/
• Include .5/index/README.md as a manifest describing what each generated index file contains and how to rebuild the index
• Group content by concern and adapt to the actual project. Each file should be compact, easy to scan, and optimized for AI/context loading rather than prose documentation.
• Each generated index file should follow this style:
  • Short title and 1-line purpose statement
  • Bulleted or table-like entries only
  • One entry per route/component/module/model/command as applicable
  • Each entry should include the path and a short descriptor
  • Prefer signatures, exported names, HTTP methods, key fields, and relationships over long explanations
  • Keep entries factual and compact; avoid narrative paragraphs
• Suggested file shapes:
  • commands.md — runnable commands, entrypoints, scripts, key developer workflows
  • routes.md — routes, handlers, API endpoints, HTTP methods, notable middleware
  • modules.md — modules/packages/components/services and what they own
  • models.md — schemas, entities, tables, migrations, key relationships
  • libraries.md — shared utilities, helpers, exported functions/classes
• Suggested categories to create when applicable:
  • Entrypoints / runnable commands
  • Routes / handlers / API surface
  • Components / modules / packages
  • Data models / schemas / migrations
  • Libraries / utilities / shared code
• Skip categories that do not apply. Do not generate empty placeholder files.
• The script should overwrite previously generated index files on each run so rebuild is idempotent.

A4. Create AGENTS.md

Generate AGENTS.md — the provider-agnostic instructions file that works with any AI coding tool:

Use .claude/templates/AGENTS.md as the source template.

Placeholder mapping:

• {PROJECT_OVERVIEW} → 1-2 sentences from README/package.json
• {BUILD_RUN_COMMANDS} → build, test, and other detected commands
• {PROJECT_DOCUMENTATION_LINKS} → links to whichever .5/ files were created (only list files that exist — includes CONVENTIONS.md when generated)
• {CODEBASE_INDEX_LINKS} → links to .5/index/README.md, generated index files, and .5/index/rebuild-index.sh
• {CONVENTIONS_REFERENCE} → when .5/CONVENTIONS.md was generated: "Read \.5/CONVENTIONS.md` before writing any code. It defines the full convention set for this project: typing rules, code structure limits, naming, error handling, and testing standards."` — when not generated: remove the placeholder entirely
• {CUSTOM_DOCUMENTATION} → preserved user-authored sections under ## Custom Documentation; remove the placeholder entirely if there is no custom content

Preserve the static template sections exactly as written, including skill usage, commit messages, workflow rules, coding guidelines, simplicity, testing, surgical changes, goal-driven execution, and index freshness.

A5. Migrate and Preserve Existing Content

Run this step BEFORE writing the CLAUDE.md shim to avoid data loss.

If AGENTS.md already exists:

• Read current content
• Identify user-written custom sections (not matching template structure)
• Preserve under "Custom Documentation" section in new AGENTS.md
• Ensure the generated guidance sections are retained

If CLAUDE.md already exists with real content (not just @AGENTS.md):

• Read current CLAUDE.md content
• Identify user-written custom sections (not matching template structure)
• Migrate all content into the new AGENTS.md (preserve under "Custom Documentation" section)

A6. Create CLAUDE.md shim (Claude Code only)

After migration is complete (A5), create or overwrite CLAUDE.md with only:

@AGENTS.md

This single line uses Claude Code's include syntax to pull in the full AGENTS.md content. This way Claude Code users get the instructions automatically, while other AI tools (Codex, etc.) read AGENTS.md directly.

---

Output Contract

Returns structured results for each component:

Component A (Documentation + Index): SUCCESS - Created documentation files, codebase index, and AGENTS.md
  - .5/ARCHITECTURE.md (Pattern: Layered, 4 layers identified)
  - .5/TESTING.md (mocking patterns, gotchas documented)
  - .5/CONCERNS.md (3 TODO items, 1 security note) [or "skipped — no concerns found"]
  - .5/CONVENTIONS.md (defaults + project-specific typing/testing findings) [or "skipped — conventions.generate is false"]
  - .5/index/rebuild-index.sh (generated index rebuild script)
  - .5/index/*.md (focused codebase index files)
  - AGENTS.md (updated with references)
  - CLAUDE.md (shim: @AGENTS.md)

Or on failure:

Component A (Documentation + Index): FAILED - Unable to read template files

DO NOT

• DO NOT overwrite existing user-written AGENTS.md sections
• DO NOT include steps in config.json
• DO NOT hardcode conventions - always derive from actual project analysis
• DO NOT generate empty or placeholder index files