Config Generator Skill

Purpose

Generates master configuration files that define the structure, components, relationships, and interdependencies for web application features. These configs serve as single sources of truth that enable:

Human rapid discovery - Quickly understand what's touched or impacted by a given set of documents or events
AI systematic propagation - Enable AI agents to propagate changes across all affected parts of the system
Bidirectional sync - Keep documentation and implementation synchronized

When to Use

Invoke this skill when you need to create a configuration document for:

A new feature or use case in a web application
A set of code components that work together
User interaction flows that span multiple parts of the system
Any complex operation that involves multiple files, APIs, or components

Tier

Tier 1 - Core Foundation (used during planning and implementation phases)

Input Parameters

The skill expects one or more of the following:

1. Use Case Input

use_case:
  name: "user-authentication-flow"
  description: "Complete user authentication including registration, login, password reset"
  user_role: "end-user"
  entry_points: ["registration page", "login page", "forgot password link"]
  success_criteria: "User can register, login, and reset password securely"

2. Code Components Input

code_components:
  - type: "api-endpoint"
    path: "backend/api/auth/register.py"
    purpose: "Handle user registration"
    dependencies: ["database/models/user.py", "utils/email_validator.py"]

  - type: "component"
    path: "frontend/components/LoginForm.tsx"
    purpose: "User login UI"
    dependencies: ["api/auth.ts", "hooks/useAuth.ts"]

  - type: "database-model"
    path: "backend/models/user.py"
    purpose: "User data schema"
    dependencies: []

3. User Interaction Input

user_interaction:
  user_type: "authenticated-user"
  interaction_name: "task-management-workflow"
  steps:
    - action: "Create new task"
      triggers: ["POST /api/tasks"]
      ui_components: ["TaskForm.tsx", "TaskList.tsx"]

    - action: "Update task status"
      triggers: ["PATCH /api/tasks/:id"]
      ui_components: ["TaskCard.tsx"]

    - action: "Delete task"
      triggers: ["DELETE /api/tasks/:id"]
      ui_components: ["TaskCard.tsx", "DeleteConfirmModal.tsx"]

Process

Step 1: Analyze Input

Parse and understand what's being configured:

For use cases:

Identify all user roles involved
Map user journeys and interaction points
Determine success/failure paths
List affected systems (frontend, backend, database, external services)

For code components:

Build dependency graph
Identify circular dependencies
Map data flow (request → response)
Categorize by context (backend, frontend, test, deployment)

For user interactions:

Map UI to API to data layer
Identify state changes
List side effects (emails, notifications, logs)
Determine rollback/error handling needs

Step 2: Discover Related Files

Systematically search the codebase:

# Find related backend files
find . -path "./backend/*" -name "*{keyword}*"

# Find related frontend files
find . -path "./frontend/*" -name "*{keyword}*"

# Find related tests
find . -path "./tests/*" -name "*{keyword}*" -o -path "*/regressions/*" -name "*{keyword}*"

# Search for API endpoints
grep -r "api/{endpoint}" --include="*.py" --include="*.ts" --include="*.js"

# Search for component usage
grep -r "import.*{ComponentName}" --include="*.tsx" --include="*.ts" --include="*.jsx"

Build complete inventory of:

All files that must be created
All files that must be modified
All tests that must be written
All documentation that must be updated

Step 3: Map Relationships

Create relationship matrix showing:

File-to-File Dependencies:

Component A → imports → Component B
API Endpoint → calls → Database Model
Frontend Hook → fetches from → API Route

Event-to-Impact Mapping:

When: User clicks "Create Task"
Then:
  - Frontend: TaskForm.tsx validates input
  - API: POST /api/tasks endpoint called
  - Backend: TaskController.create() invoked
  - Database: tasks table INSERT
  - State: Redux store updated
  - UI: TaskList.tsx re-renders
  - Side Effects: Notification sent

Change-Propagation Paths:

If: tasks table schema changes
Then propagate to:
  - backend/models/task.py (update model)
  - backend/migrations/ (create migration)
  - backend/api/tasks.py (update serialization)
  - frontend/types/task.ts (update TypeScript types)
  - frontend/components/TaskForm.tsx (update form fields)
  - tests/backend/test_tasks.py (update test fixtures)
  - tests/frontend/TaskForm.test.tsx (update component tests)
  - ai-state/regressions/backend/test_tasks_regression.py

Step 4: Define Configuration Structure

Create hierarchical structure matching the pattern:

# {Feature/UseCase} Configuration Reference

**Version:** 1.0 | **Updated:** {date} | **System:** Khujta Sphere Framework

> **Purpose:** Master configuration for {feature} that defines structure, components, and relationships. Enables rapid discovery for humans and systematic propagation for AI.

---

## Quick Reference

| Aspect | Value | Code Location |
|--------|-------|---------------|
| **Feature Entry Point** | {main UI component or API} | {file path} |
| **Backend Handler** | {controller/service} | {file path} |
| **Database Models** | {model names} | {file paths} |
| **Frontend Components** | {component names} | {file paths} |
| **Test Coverage** | {test locations} | {file paths} |
| **Related Docs** | {documentation} | {doc paths} |

---

## Components Involved

### Component 1: {Name}

**Location:** `{file path}`

**Purpose:** {What this component does}

**Type:** {API endpoint | UI component | Database model | Service | Utility}

**Dependencies:**
- {dependency 1} - {file path} - {why needed}
- {dependency 2} - {file path} - {why needed}

**Used By:**
- {dependent 1} - {file path} - {how it's used}
- {dependent 2} - {file path} - {how it's used}

**Key Exports:**
```typescript
// For TS/JS components
export function functionName(params): ReturnType
export interface TypeName { ... }

# For Python components
def function_name(params) -> ReturnType:
class ClassName:

Propagation: | Change Type | Files to Update | What to Change | |-------------|-----------------|----------------| | Add field | {list of files} | {specific changes needed} | | Modify validation | {list of files} | {specific changes needed} | | Change API contract | {list of files} | {specific changes needed} |

Code Reference:

Main implementation: {file}:{line_start}-{line_end}
Tests: {test_file}:{line_start}-{line_end}

Use Case Flow

Flow 1: {User Action Name}

Trigger: {What initiates this flow - user action, API call, scheduled job}

Actor: {User type or system component}

Steps:

{Step Name} - {Description}
- Files involved: {list}
- Data transformations: {input → output}
- Validation rules: {list}
- Error conditions: {list}
{Step Name} - {Description}
- Files involved: {list}
- Data transformations: {input → output}
- Side effects: {emails, logs, notifications}
- Success criteria: {what success looks like}

Sequence Diagram:

sequenceDiagram
    participant User
    participant Frontend as {Component}
    participant API as {Endpoint}
    participant Service as {Service}
    participant DB as {Database}

    User->>Frontend: {action}
    Frontend->>API: {HTTP method} {endpoint}
    API->>Service: {method call}
    Service->>DB: {query}
    DB-->>Service: {result}
    Service-->>API: {response data}
    API-->>Frontend: {HTTP response}
    Frontend-->>User: {UI update}

Error Handling: | Error Condition | Where Caught | User Message | Logged As | |-----------------|--------------|--------------|-----------| | {error 1} | {file:line} | {message} | {log level + details} | | {error 2} | {file:line} | {message} | {log level + details} |

Rollback Strategy:

{What happens on failure}
{How to undo partial changes}
{Transaction boundaries}

Data Flow

Data Model: {Entity Name}

Database Schema:

CREATE TABLE {table_name} (
  {field}: {type} {constraints},
  ...
);

Backend Model:

class {ModelName}:
    {field}: {type}  # {description}

Frontend Type:

interface {TypeName} {
  {field}: {type};  // {description}
}

Transformations:

| Layer | Format | Location | Notes | |-------|--------|----------|-------| | Database | SQL row | {table} | {constraints} | | Backend Model | Python object | {model file} | {ORM details} | | API Response | JSON | {endpoint} | {serialization} | | Frontend Type | TypeScript | {type file} | {validation} |

Propagation - Schema Change: | Change | Impact Files | Required Updates | |--------|--------------|------------------| | Add field | {list all files} | {specific changes per file} | | Rename field | {list all files} | {specific changes per file} | | Change type | {list all files} | {specific changes per file} | | Add constraint | {list all files} | {specific changes per file} |

Testing Requirements

Test Coverage Map

Backend Tests: | Test Type | File Location | What's Tested | Required Tests | |-----------|---------------|---------------|----------------| | Unit | {path} | {component} | {list} | | Integration | {path} | {flow} | {list} | | Regression | ai-state/regressions/backend/ | {critical paths} | {list} |

Frontend Tests: | Test Type | File Location | What's Tested | Required Tests | |-----------|---------------|---------------|----------------| | Component | {path} | {component} | {list} | | Integration | {path} | {user flow} | {list} | | E2E | {path} | {full workflow} | {list} | | Regression | ai-state/regressions/frontend/ | {critical paths} | {list} |

Test Data:

fixtures:
  - name: {fixture_name}
    location: {path}
    purpose: {what it's for}
    data: {sample data structure}

Configuration & Environment

Environment Variables:

# Required for this feature
{VAR_NAME}={description}
{VAR_NAME}={description}

Feature Flags:

feature_flags:
  - name: {flag_name}
    default: {true|false}
    purpose: {what it controls}
    files_affected: [{list}]

External Dependencies: | Dependency | Version | Purpose | Fallback Strategy | |------------|---------|---------|-------------------| | {library} | {version} | {why needed} | {what if unavailable} |

Event Impact Analysis

Event: {Event Name}

What triggers it: {description}

Immediate impacts:

{File 1}: {what changes}
{File 2}: {what changes}
{File 3}: {what changes}

Cascading impacts:

File A change
  → triggers File B update (because: {dependency})
    → triggers File C update (because: {dependency})
      → requires File D update (because: {dependency})

Validation checklist after this event:

[ ] {Check 1 - what to verify}
[ ] {Check 2 - what to verify}
[ ] {Check 3 - what to verify}
[ ] {Check 4 - what to verify}

Modification Workflows

Workflow 1: Adding {Capability}

Use Case: {When you'd do this}

Steps:

Backend Changes
- [ ] Update {file} - {specific change}
- [ ] Update {file} - {specific change}
- [ ] Create migration: {migration description}
- [ ] Add tests: {test file}
Frontend Changes
- [ ] Update {file} - {specific change}
- [ ] Update {file} - {specific change}
- [ ] Add tests: {test file}
Integration
- [ ] Update API contract: {file}
- [ ] Update TypeScript types: {file}
- [ ] Test integration: {how to verify}
Validation
- [ ] Run backend tests: {command}
- [ ] Run frontend tests: {command}
- [ ] Manual verification: {steps}

Propagation Checklist:

backend:
  - file: {path}
    change: {description}
    lines: {line range or function name}

frontend:
  - file: {path}
    change: {description}
    lines: {line range or function name}

tests:
  - file: {path}
    change: {description}
    type: {unit|integration|e2e}

docs:
  - file: {path}
    change: {description}

Version History

| Version | Date | Changes | |---------|------|---------| | 1.0 | {date} | Initial configuration for {feature} |

Summary

This configuration defines all components, relationships, and workflows for {feature}. Use this document to:

Understand structure - See all components and how they connect
Track impacts - Know what changes when a file is modified
Propagate changes - Follow checklists to update all affected files
Ensure completeness - Verify all related tests and docs are updated

Remember: Update this config first when making architectural changes, then propagate to implementation files using the provided workflows.


### Step 5: Generate Visual Diagrams

**Include Mermaid diagrams for:**

**Architecture Overview:**
```mermaid
graph TB
    subgraph Frontend
        UI[User Interface]
        State[State Management]
        API_Client[API Client]
    end

    subgraph Backend
        Routes[API Routes]
        Controllers[Controllers]
        Services[Services]
        Models[Models]
    end

    subgraph Data
        DB[(Database)]
        Cache[(Cache)]
    end

    UI --> State
    State --> API_Client
    API_Client --> Routes
    Routes --> Controllers
    Controllers --> Services
    Services --> Models
    Models --> DB
    Services --> Cache

Data Flow Diagram:

flowchart LR
    Input[User Input] --> Validate[Validation]
    Validate --> |Valid| Process[Process Request]
    Validate --> |Invalid| Error1[Return Error]
    Process --> DB[Database Write]
    DB --> |Success| Response[Success Response]
    DB --> |Failure| Error2[Return Error]
    Response --> Update[Update UI]

Dependency Graph:

graph LR
    A[Component A] --> B[Component B]
    A --> C[Component C]
    B --> D[Shared Util]
    C --> D
    D --> E[External Lib]

Step 6: Write Configuration File

Save to: ai-state/config/{feature-name}-config.md

Naming conventions:

Use kebab-case: user-authentication-config.md
Be specific: task-crud-operations-config.md not tasks-config.md
Include scope: backend-api-setup-config.md vs frontend-routing-config.md

File structure requirements:

Must include "Quick Reference" table
Must include "Propagation" tables for each component
Must include at least one Mermaid diagram
Must include "Modification Workflows" section
Must include "Version History" table

Step 7: Validate Configuration

Completeness checks:

[ ] All referenced files exist or are marked as "to be created"
[ ] All dependencies are documented
[ ] All propagation paths are traced
[ ] All modification workflows have checklists
[ ] All diagrams render correctly

Accuracy checks:

[ ] File paths are correct relative to project root
[ ] Line number references are accurate (use code scanning)
[ ] Component relationships match actual code
[ ] Data flow matches implementation

Utility checks:

[ ] A human can understand what's impacted by a change
[ ] An AI can follow propagation tables to make changes
[ ] Modification workflows are actionable
[ ] Quick reference table provides fast lookup

Output Format

The skill generates a single markdown file at ai-state/config/{feature-name}-config.md following the structure defined in Step 4.

Success criteria:

Configuration file is comprehensive (all components documented)
Configuration file is accurate (matches actual codebase)
Configuration file is actionable (provides clear modification workflows)
Configuration file is maintainable (easy to update when code changes)

Integration Points

Input from:

User specifications
Existing codebase analysis
ai-state/active/tasks.yaml - task context
ai-state/standards/*.md - coding standards
.claude/docs/config/*.md - configuration patterns

Output to:

ai-state/config/{feature}-config.md - generated configuration
Used by human developers for understanding
Used by AI agents for propagation
Referenced in modification workflows

Examples

Example 1: User Authentication Config

Input:

use_case:
  name: "user-authentication"
  description: "User registration, login, JWT tokens"
  entry_points: ["POST /api/auth/register", "POST /api/auth/login"]

Output: ai-state/config/user-authentication-config.md

Key sections:

Backend: auth routes, user model, JWT service
Frontend: LoginForm, RegisterForm, useAuth hook
Database: users table schema
Flow diagrams: registration flow, login flow
Propagation: what changes when adding OAuth

Example 2: Task CRUD Config

Input:

code_components:
  - path: "backend/api/tasks.py"
    type: "api-endpoint"
  - path: "frontend/components/TaskList.tsx"
    type: "component"

Output: ai-state/config/task-crud-operations-config.md

Key sections:

CRUD endpoints: GET, POST, PATCH, DELETE /api/tasks
Frontend components: TaskList, TaskForm, TaskCard
Data flow: UI → API → Database
Propagation: adding new task field

Example 3: Multi-Step User Workflow

Input:

user_interaction:
  interaction_name: "order-checkout-flow"
  steps:
    - action: "Add items to cart"
    - action: "Enter shipping info"
    - action: "Enter payment info"
    - action: "Confirm order"

Output: ai-state/config/order-checkout-flow-config.md

Key sections:

Multi-step sequence diagram
State management across steps
Error handling at each step
Rollback strategy for failures

Best Practices

Start broad, then narrow:
- Map entire feature first
- Then detail each component
- Finally add propagation tables
Use code scanning, not assumptions:
- Use Grep/Glob tools to find actual files
- Verify line numbers before documenting
- Check dependencies with import analysis
Think bidirectionally:
- Document "uses" and "used by"
- Map both forward and backward dependencies
- Consider circular dependencies
Make it actionable:
- Every propagation table should have specific file:line references
- Every workflow should have checkboxes
- Every change should have validation steps
Keep it fresh:
- Add version history entries
- Update when code structure changes
- Reference from commit messages

Phase-Specific Behavior

Prototype Phase:

Focus on happy path flows
Minimal error handling documentation
Basic component relationships

MVP Phase:

Add error handling paths
Document validation rules
Include rollback strategies

Growth Phase:

Add performance considerations
Document caching strategies
Include monitoring/observability

Scale Phase:

Add security hardening notes
Document disaster recovery
Include multi-region considerations

Quality Standards

Completeness: All components documented, no orphaned files
Accuracy: File paths and line numbers verified
Clarity: Non-technical stakeholders can understand flows
Actionability: AI agents can execute propagation tables
Maintainability: Easy to update as code evolves

Troubleshooting

Issue: Configuration is too large (>2000 lines) Solution: Split into multiple configs by feature area or layer (backend-config.md, frontend-config.md)

Issue: Hard to keep file paths accurate Solution: Use relative paths from project root, add validation script

Issue: Propagation tables are incomplete Solution: Use dependency graph tools, trace all imports

Issue: Modification workflows are too generic Solution: Base workflows on actual past changes, be specific

Related Skills

standards-creator - Creates implementation standards (this creates structural configs)
write-plan - Creates tasks.yaml (this creates feature configs)
execute-tasks - Executes tasks (uses configs for propagation)
brainstorm - Refines requirements (input to this skill)

Version

1.0 - Initial config-generator skill for creating master configuration files

config-generator

Config Generator Skill

Purpose

When to Use

Tier

Input Parameters

1. Use Case Input

2. Code Components Input

3. User Interaction Input

Process

Step 1: Analyze Input

Step 2: Discover Related Files

Step 3: Map Relationships

Step 4: Define Configuration Structure

Use Case Flow

Flow 1: {User Action Name}

Data Flow

Data Model: {Entity Name}

Testing Requirements

Test Coverage Map

Configuration & Environment

Event Impact Analysis

Event: {Event Name}

Modification Workflows

Workflow 1: Adding {Capability}

Related Documentation

Version History

Summary

Step 6: Write Configuration File

Step 7: Validate Configuration

Output Format

Integration Points

Examples

Example 1: User Authentication Config

Example 2: Task CRUD Config

Example 3: Multi-Step User Workflow

Best Practices

Phase-Specific Behavior

Quality Standards

Troubleshooting

Related Skills

Version