Generate App Specification

Create comprehensive app specification files that document codebase structure, architecture, features, and implementation details in a standardized XML format.

When to Use

• Documenting an existing project
• Creating specs for handoff or onboarding
• Generating architecture documentation
• Analyzing unfamiliar codebases

Output Format

Generate XML following this structure (standard depth by default):

<project_specification>
  <project_name>Name</project_name>
  <overview>2-3 sentence description</overview>
  <technology_stack>
    <runtime>...</runtime>
    <language>...</language>
    <framework>...</framework>
    <key_dependencies>...</key_dependencies>
  </technology_stack>
  <core_features>
    <feature>
      <name>...</name>
      <description>...</description>
      <location>...</location>
    </feature>
  </core_features>
  <file_structure>
    <directory name="...">
      <key_files>...</key_files>
    </directory>
  </file_structure>
  <configuration>...</configuration>
  <running_the_project>...</running_the_project>
</project_specification>

Exploration Strategy

Step 1: Discover Project Type

Check for manifest files to identify the project:

Read the manifest to identify:

• Project name and description
• Dependencies and dev dependencies
• Scripts/commands available
• Entry points

Step 2: Map Structure

1. Use tree or find to get directory layout (exclude node_modules, .git, etc.)
2. Identify key directories:
   • src/, lib/, app/ - source code
   • test/, tests/, __tests__/ - tests
   • config/, .config/ - configuration
   • public/, static/, assets/ - static files
   • docs/ - documentation
3. Count files by type to understand composition

Step 3: Analyze Architecture

1. Find and read entry points:

   • main.ts, index.ts, app.ts (TypeScript)
   • main.js, index.js, app.js (JavaScript)
   • main.py, app.py, __main__.py (Python)
   • main.go, cmd/*/main.go (Go)
   • src/main.rs, src/lib.rs (Rust)

2. Trace imports to understand module structure

3. Look for:

   • Route definitions (API endpoints)
   • Database models/schemas
   • Configuration patterns
   • Authentication/authorization
   • Middleware

Step 4: Extract Features

1. Read README.md for stated features and usage
2. Analyze route handlers for actual features
3. Check for integrations (OAuth, external APIs, etc.)
4. Document UI components if frontend exists
5. Note CLI commands if applicable

Step 5: Generate Spec

1. Create app_spec.txt in project root
2. Use XML format from TEMPLATES.md
3. Include all discovered information
4. Add file paths for key components
5. Document how to run the project

Quality Guidelines

• Be specific: Include actual file paths, not generic descriptions
• Be accurate: Only document what exists, never invent features
• Be complete: Cover all major components and entry points
• Be concise: Standard depth covers essentials without exhaustive detail
• Be actionable: Include commands to install, build, run, and test

Depth Levels

When user requests different depths:

• Quick: project_name, overview, technology_stack (basics only), core_features (names only)
• Standard (default): All sections with moderate detail
• Comprehensive: Add database_schema, api_endpoints_summary, ui_layout, implementation_steps, success_criteria

Integration with auto-code

After generating app_spec.txt, the user can run:

auto-code build ./app_spec.txt

Completion Message

When you finish generating the app_spec.txt file, show the user:

Done! I've generated app_spec.txt at the project root.

The spec is ready to use:

  auto-code build ./app_spec.txt

IMPORTANT: The correct command is auto-code build (the package binary is auto-code, not autonomous-coding, and it uses subcommands like build and extend)

See Also

• TEMPLATES.md - XML templates by project type and depth
• EXAMPLES.md - Complete example specifications