Generate Feature Specification

Create features_spec.txt files for use with the auto-code package in extension mode. This skill analyzes an existing codebase and generates a structured XML specification of features to implement.

When to Use

• Before running auto-code extend ./features_spec.txt
• When you want precise control over which features to add
• When extending an existing TypeScript/JavaScript project
• When you have specific requirements and don't want agent-generated recommendations

Output Format

Generate XML with a <feature> element for each feature:

<?xml version="1.0" encoding="UTF-8"?>
<features_spec version="1.0">
  <metadata>
    <project>Project Name</project>
    <generated_date>2026-01-05</generated_date>
    <source>Manual specification</source>
    <base_branch>development</base_branch>
  </metadata>

  <feature id="feature-1">
    <title>Feature Name</title>
    <type>new-feature</type>
    <priority>normal</priority>

    <description>
      Description of what this feature should do.
      Any additional context, requirements, or acceptance criteria.
    </description>

    <affected_files>
      <file path="src/components/Example.tsx">
        <issues>- Add new component logic here</issues>
      </file>
    </affected_files>

    <implementation_steps>
      <step order="1">First implementation step</step>
      <step order="2">Second implementation step</step>
    </implementation_steps>

    <acceptance_criteria>
      <criterion>Feature works as expected</criterion>
    </acceptance_criteria>

    <testing>
      <test type="manual">Verify feature works in browser</test>
    </testing>
  </feature>
</features_spec>

Workflow

Step 1: Analyze Existing Codebase

First, understand the current project:

# Check project type and dependencies
cat package.json 2>/dev/null || cat pyproject.toml 2>/dev/null

# Get directory structure
find . -type f -name "*.ts" -o -name "*.tsx" | head -30

# Check for existing app_spec.txt
cat app_spec.txt 2>/dev/null

Document:

• Technology stack (React, Next.js, Express, etc.)
• Existing features and components
• Code patterns and conventions
• Database schema if applicable

Step 2: Gather Requirements

Ask the user what features they want to add:

1. If app_spec.txt exists: Reference it and ask which features from the spec should be implemented
2. If no app_spec.txt: Ask the user to describe the features they want

Use AskUserQuestion to clarify:

• Feature priorities
• Specific requirements or constraints
• Integration points with existing code
• Any technical preferences

Step 3: Generate features_spec.txt

Create the file with:

• One <feature> element per feature
• Clear, actionable descriptions
• Relevant technical context
• Affected files with specific issues/changes needed
• Implementation steps
• Acceptance criteria

Step 4: Review with User

Present the generated spec and ask if any adjustments are needed before finalizing.

XML Schema Reference

Root Element

<features_spec version="1.0">

Metadata Section

<metadata>
  <project>Project Name</project>
  <generated_date>YYYY-MM-DD</generated_date>
  <source>Where features came from (Linear, manual, etc.)</source>
  <base_branch>development</base_branch>
</metadata>

Feature Element

Element	Required	Description
id	Yes	Unique identifier (e.g., "PROJ-123", "feature-1")
title	Yes	Human-readable title
type	Yes	bug-fix, ui-enhancement, improvement, new-feature
priority	No	low, normal, high, urgent (default: normal)
labels	No	Comma-separated labels
linear_url	No	Link to issue tracker
branch	No	Pre-created branch name
description	Yes	Detailed description
affected_files	No	Files to modify with issues
implementation_steps	No	Ordered steps
acceptance_criteria	No	What "done" looks like
testing	No	How to verify the feature

Feature Types

• bug-fix: Fixing broken functionality
• ui-enhancement: Visual/UX improvements
• improvement: Enhancing existing features
• new-feature: Adding new functionality

Quality Guidelines

• Be specific: Include file paths, line numbers where possible
• Be realistic: Each feature should be implementable in 1-3 sessions
• Be ordered: Put foundational features first, dependent features after
• Reference existing code: Use <affected_files> to point to specific locations
• Include acceptance criteria: What does "done" look like for each feature?
• Add testing steps: How should the agent verify the implementation?

Example Output

<?xml version="1.0" encoding="UTF-8"?>
<features_spec version="1.0">
  <metadata>
    <project>My Portal App</project>
    <generated_date>2026-01-05</generated_date>
    <source>Manual specification</source>
    <base_branch>development</base_branch>
  </metadata>

  <feature id="auth-001">
    <title>User Authentication</title>
    <type>new-feature</type>
    <priority>high</priority>

    <description>
      Add login and logout functionality using NextAuth.js.
      Support email/password authentication with secure session handling.
    </description>

    <affected_files>
      <file path="src/pages/api/auth/[...nextauth].ts">
        <issues>- Create NextAuth configuration</issues>
      </file>
      <file path="src/pages/login.tsx">
        <issues>- Create login page matching existing UI style</issues>
      </file>
      <file path="src/middleware.ts">
        <issues>- Add protected route middleware</issues>
      </file>
    </affected_files>

    <implementation_steps>
      <step order="1">Install next-auth and configure providers</step>
      <step order="2">Create login and signup pages</step>
      <step order="3">Add session provider to _app.tsx</step>
      <step order="4">Implement protected route middleware</step>
      <step order="5">Add user context to navigation</step>
    </implementation_steps>

    <acceptance_criteria>
      <criterion>Users can sign up with email/password</criterion>
      <criterion>Users can log in and log out</criterion>
      <criterion>Protected routes redirect to login</criterion>
      <criterion>Session persists across page refreshes</criterion>
    </acceptance_criteria>

    <testing>
      <test type="manual">Complete signup and login flow</test>
      <test type="manual">Verify protected routes redirect</test>
      <test type="manual">Verify logout clears session</test>
    </testing>
  </feature>

  <feature id="dashboard-001">
    <title>Dashboard Analytics Widget</title>
    <type>new-feature</type>
    <priority>normal</priority>

    <description>
      Add a new widget to the dashboard showing user activity metrics.
      Follow existing widget pattern and use recharts for visualization.
    </description>

    <affected_files>
      <file path="src/components/widgets/AnalyticsWidget.tsx">
        <issues>- Create new widget component</issues>
      </file>
      <file path="src/pages/api/analytics.ts">
        <issues>- Create API endpoint for metrics</issues>
      </file>
      <file path="src/pages/dashboard.tsx">
        <issues>- Add widget to dashboard grid</issues>
      </file>
    </affected_files>

    <implementation_steps>
      <step order="1">Create /api/analytics endpoint</step>
      <step order="2">Create AnalyticsWidget following existing pattern</step>
      <step order="3">Add recharts line/bar chart</step>
      <step order="4">Add loading and error states</step>
      <step order="5">Integrate into dashboard</step>
    </implementation_steps>

    <acceptance_criteria>
      <criterion>Widget displays activity metrics</criterion>
      <criterion>Chart renders correctly with data</criterion>
      <criterion>Loading state shows skeleton</criterion>
      <criterion>Error state shows retry button</criterion>
    </acceptance_criteria>

    <testing>
      <test type="manual">View dashboard with analytics widget</test>
      <test type="manual">Verify chart updates with new data</test>
    </testing>
  </feature>

  <feature id="export-001">
    <title>Export to CSV</title>
    <type>improvement</type>
    <priority>low</priority>

    <description>
      Allow users to export their data to CSV format.
      Support filtering before export and handle large datasets with streaming.
    </description>

    <affected_files>
      <file path="src/components/DataTable.tsx">
        <issues>- Add export button to table header</issues>
      </file>
      <file path="src/lib/export.ts">
        <issues>- Create CSV generation utility</issues>
      </file>
    </affected_files>

    <implementation_steps>
      <step order="1">Create CSV generation utility</step>
      <step order="2">Add export button to DataTable component</step>
      <step order="3">Implement streaming for large datasets</step>
      <step order="4">Add progress indicator</step>
    </implementation_steps>

    <acceptance_criteria>
      <criterion>Export button visible in data table</criterion>
      <criterion>CSV file downloads with current filter applied</criterion>
      <criterion>Large exports show progress</criterion>
    </acceptance_criteria>

    <testing>
      <test type="manual">Export small dataset</test>
      <test type="manual">Export with filters applied</test>
      <test type="integration">Test export with 10k+ rows</test>
    </testing>
  </feature>
</features_spec>

Integration with auto-code

After generating features_spec.txt, the user can run:

auto-code extend ./features_spec.txt

Or if working from an app spec instead:

auto-code extend --app-spec ./app_spec.txt

The autonomous agent will:

1. Read features_spec.txt
2. Create one feature_list.json entry per <feature> element
3. Implement ONLY the features listed (no additional recommendations)
4. Use the provided context (affected_files, steps, criteria) to guide implementation

Completion Message

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

Done! I've generated features_spec.txt with [N] features.

The spec is ready to use:

  auto-code extend ./features_spec.txt

IMPORTANT: Do NOT use the old command format autonomous-coding --mode extend --features-spec. The correct command is auto-code extend (the package binary is auto-code, not autonomous-coding, and it uses subcommands, not --mode flags)