tdk-config-index

/tdk-config-index - Generate Document Manager Index

Purpose

Generate or update document-manager.md - an index file that helps AI understand the docs structure and read priority.

---

Output

Creates/updates {docs.path}/document-manager.md

• With --sub-workspace: Sub-workspace-specific path (e.g., apps/frontend/{docs.path}/document-manager.md)
• Without --sub-workspace: Workspace path (e.g., {docs.path}/document-manager.md)

---

Flags

• --sub-workspace NAME: Target specific sub-workspace
• --full: Full rebuild (regenerate all descriptions)
• Default (no flag): Incremental update (preserve existing descriptions)

---

Execution

Step 0: Parse Arguments & Run Script

Parse user input for sub-workspace targeting:

1. Check if --sub-workspace NAME in command args
2. Check if user mentions sub-workspace name in natural language
3. Check if --full flag is specified

Run bash script:

# If sub-workspace specified:
cd $CLAUDE_PROJECT_DIR/.specify/scripts/ts && bun src/commands/config/index.ts --sub-workspace {SUB_WORKSPACE_NAME} [--full]

# Otherwise (workspace level):
cd $CLAUDE_PROJECT_DIR/.specify/scripts/ts && bun src/commands/config/index.ts [--full]

CRITICAL: Handle script errors:

• If exit code != 0: STOP IMMEDIATELY. Do NOT continue or try workarounds.
• If "Required tools not installed": Show error message to user and STOP. User must install prerequisites first.
• If other errors: Show error message and STOP.

On success only: Parse JSON output into variables:

• DOCS_DIR - Docs directory path
• MANAGER_FILE - Path to document-manager.md
• HAS_MANAGER - Whether document-manager.md exists
• MODE - "create" | "incremental" | "full_rebuild"
• FILES - Array of file objects with path, size, modified

---

Step 1: Handle Mode

If MODE = "create" or "full_rebuild":

• Generate descriptions for ALL files in FILES array
• Skip to Step 3

If MODE = "incremental":

1. Read existing document-manager.md
2. Parse existing file entries (path + description)
3. Compare with FILES array:
   • New files: Files in FILES but not in existing (need description)
   • Deleted files: Files in existing but not in FILES (remove)
   • Unchanged files: Keep existing descriptions
4. Only generate descriptions for NEW files

---

Step 2: Generate Descriptions (AI)

For each file needing description:

1. Read file content (first 100 lines)
2. Generate concise description (1-2 sentences)
3. Identify if it's a "System Document" (generated by commands) or "Custom Document"

System documents (auto-generated):

• Files in rules/ folder typically auto-generated

Custom documents (user-managed):

• Everything else

---

Step 3: Build Document Manager Content

Use this template:

# Document Manager
> Auto-generated by /tdk-config-index
> Last updated: {YYYY-MM-DD HH:MM}

## Read Priority

When working in a sub-workspace, AI reads documents in this order:
1. **Sub-workspace local** (`{sub-workspace}/{docs.path}/`)
2. **Workspace base** (`{workspace}/{docs.path}/`)

If same file exists in both -> Sub-workspace wins (override).

## System Documents

| File | Purpose | Generated By |
|------|---------|--------------|
{FOR EACH system document}
| `{path}` | {description} | {generator command} |
{END FOR}

## Custom Documents

| File | Purpose |
|------|---------|
{FOR EACH custom document}
| `{path}` | {description} |
{END FOR}

---
*Run `/tdk-config-index` to refresh this index.*
*Run `/tdk-config-index --full` to rebuild from scratch.*

---

Step 4: Write & Confirm

1. Preview first 30 lines
2. Write to {MANAGER_FILE}

Output:

Document Manager updated: {MANAGER_FILE}
Mode: {MODE}
Files indexed: {count}
  - System documents: {count}
  - Custom documents: {count}
Changes: {new_count} added, {deleted_count} removed

---

Related

• docs:diff - Compare workspace vs sub-workspace docs
• docs:sync - Sync docs between workspace and sub-workspace