Generate Feature Specification

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

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)