gsd-to-autoforge-spec

GSD to AutoForge Spec Converter

Converts .planning/codebase/*.md (GSD mapping output) to .autoforge/prompts/app_spec.txt (AutoForge format).

When to Use

• After running /gsd:map-codebase on an existing project
• When onboarding an existing codebase to AutoForge
• User wants AutoForge to continue development on existing code

Prerequisites

The project must have .planning/codebase/ with these files:

• STACK.md - Technology stack (required)
• ARCHITECTURE.md - Code architecture (required)
• STRUCTURE.md - Directory layout (required)
• CONVENTIONS.md - Code conventions (optional)
• INTEGRATIONS.md - External services (optional)

Process

<step name="verify_input"> ### Step 1: Verify GSD Mapping Exists

ls -la .planning/codebase/

Required files: STACK.md, ARCHITECTURE.md, STRUCTURE.md

If .planning/codebase/ doesn't exist:

GSD codebase mapping not found.

Run /gsd:map-codebase first to analyze the existing codebase.

Stop workflow. </step>

<step name="read_codebase_docs"> ### Step 2: Read Codebase Documentation

Read all available GSD documents:

cat .planning/codebase/STACK.md
cat .planning/codebase/ARCHITECTURE.md
cat .planning/codebase/STRUCTURE.md
cat .planning/codebase/CONVENTIONS.md 2>/dev/null || true
cat .planning/codebase/INTEGRATIONS.md 2>/dev/null || true

Extract key information:

• From STACK.md: Languages, frameworks, dependencies, runtime, ports
• From ARCHITECTURE.md: Patterns, layers, data flow, entry points
• From STRUCTURE.md: Directory layout, key file locations, naming conventions
• From INTEGRATIONS.md: External APIs, services, databases </step>

<step name="read_package_json"> ### Step 3: Extract Project Metadata

cat package.json 2>/dev/null | head -20 || echo "No package.json"

Extract:

• Project name
• Version
• Main dependencies </step>

<step name="generate_spec"> ### Step 4: Generate app_spec.txt

Create prompts/ directory:

mkdir -p .autoforge/prompts

Mapping GSD Documents to AutoForge Spec:

GSD Source	AutoForge Target
STACK.md Languages	<technology_stack>
STACK.md Frameworks	<frontend>, <backend>
STACK.md Dependencies	<prerequisites>
ARCHITECTURE.md Layers	<core_features> categories
ARCHITECTURE.md Data Flow	<key_interactions>
ARCHITECTURE.md Entry Points	<implementation_steps>
STRUCTURE.md Layout	<ui_layout> (if frontend)
INTEGRATIONS.md APIs	<api_endpoints_summary>
INTEGRATIONS.md Services	<prerequisites>

Feature Generation Guidelines:

1. Analyze existing code structure to infer implemented features
2. Each feature must be testable: "User can...", "System displays...", "API returns..."
3. Group features by category matching architecture layers
4. Target feature counts by complexity:
   • Simple CLI/utility: ~100-150 features
   • Medium web app: ~200-250 features
   • Complex full-stack: ~300-400 features

Write the spec file using the XML format from references/app-spec-format.md:

cat > .autoforge/prompts/app_spec.txt << 'EOF'
<project_specification>
  <project_name>{from package.json or directory}</project_name>

  <overview>
    {Synthesized from ARCHITECTURE.md overview}
  </overview>

  <technology_stack>
    <frontend>
      <framework>{from STACK.md}</framework>
      <styling>{from STACK.md}</styling>
      <port>{from STACK.md or default 3000}</port>
    </frontend>
    <backend>
      <runtime>{from STACK.md}</runtime>
      <database>{from STACK.md or INTEGRATIONS.md}</database>
      <port>{from STACK.md or default 3001}</port>
    </backend>
  </technology_stack>

  <prerequisites>
    <environment_setup>
      {from STACK.md Runtime + INTEGRATIONS.md requirements}
    </environment_setup>
  </prerequisites>

  <core_features>
    <!-- Group by ARCHITECTURE.md layers -->
    <{layer_name}>
      - {Feature derived from code analysis}
      - {Feature derived from code analysis}
    </{layer_name}>
  </core_features>

  <api_endpoints_summary>
    {from INTEGRATIONS.md or inferred from STRUCTURE.md routes/}
  </api_endpoints_summary>

  <key_interactions>
    {from ARCHITECTURE.md Data Flow}
  </key_interactions>

  <success_criteria>
    <functionality>
      - All existing features continue working
      - New features integrate seamlessly
      - No regression in core functionality
    </functionality>
  </success_criteria>
</project_specification>
EOF

</step> <step name="verify_output"> ### Step 5: Verify Generated Spec

head -100 .autoforge/prompts/app_spec.txt
echo "---"
grep -c "User can\|System\|API\|Feature" .autoforge/prompts/app_spec.txt || echo "0"

Validation checklist:

• <project_specification> root tag present
• <project_name> matches actual project
• <technology_stack> reflects STACK.md
• <core_features> has categorized features
• Features are specific and testable </step>

<step name="completion"> ### Step 6: Report Completion

Output:

app_spec.txt generated from GSD codebase mapping.

Source: .planning/codebase/*.md
Output: .autoforge/prompts/app_spec.txt

Next: Start AutoForge

  cd {project_dir}
  python ~/projects/autoforge/start.py

Or via UI:
  ~/projects/autoforge/start_ui.sh

The Initializer will create features.db from this spec.

</step>

XML Format Reference

See references/app-spec-format.md for complete XML structure with all sections.

Error Handling

Error	Resolution
No .planning/codebase/	Run /gsd:map-codebase first
Missing required files	Re-run GSD mapping
Cannot infer features	Ask user for clarification